Skip to content

chore: remove stale inception docs PLAN.md and IDEA.md#41

Merged
chaliy merged 1 commit into
mainfrom
claude/cleanup-plan-idea-t0rOv
May 17, 2026
Merged

chore: remove stale inception docs PLAN.md and IDEA.md#41
chaliy merged 1 commit into
mainfrom
claude/cleanup-plan-idea-t0rOv

Conversation

@chaliy
Copy link
Copy Markdown
Owner

@chaliy chaliy commented May 17, 2026

What

Delete PLAN.md and IDEA.md — both are stale inception documents that nothing in the repo references and that now actively mislead readers.

Why

I read both files end-to-end and grepped the repo for references. Findings:

IDEA.md (104 lines)

  • The architecture diagram shows Anthropic and Gemini as first-class provider endpoints; the server actually implements only OpenAI and OpenResponses. New readers would assume features that don't exist.
  • "Future Extensions" is half-done (WebSocket, stats endpoint — shipped) and half-aspirational (record/replay, Prometheus), same list as PLAN.md's Phase 6.
  • Problem statement + design principles are the same content as the README.

PLAN.md (342 lines)

  • Phase 7 "Set up GitHub releases" and "Publish to crates.io" are unchecked, but the project has shipped both (v0.2.x on crates.io with multi-platform release artifacts).
  • The Technical Decisions Log decision Create README, license, and contribution files #3 declares "YAML for config" — already obsoleted by PR chore(config)!: migrate config file format from YAML to TOML #37's TOML migration.
  • Unchecked phases (tool calling, Anthropic, Gemini) are roadmap items better tracked as GitHub issues than as a stale plan that the next agent has to re-evaluate from scratch.
  • The "completed" phases duplicate information that's already in specs/architecture.md and the source tree.

Cross-repo grep

$ grep -rn "PLAN.md\|IDEA.md" --include="*.md" --include="*.rs" \
    --include="*.toml" --include="*.sh" --include="*.yml" --include="*.yaml" .
(no output)

Nothing links to either file.

Active substitutes are already in place

Need File
Problem statement / "why" README.md
Project structure specs/architecture.md
API endpoints specs/api-endpoints.md, specs/responses-api.md
Roadmap / future work GitHub issues
Design decisions Code comments (per AGENTS.md: "Keep decisions as comments on top of the file")

How

git rm PLAN.md IDEA.md. No code changes.

Risk

  • Low. Nothing references either file. Anything still valuable in the Technical Decisions Log (e.g., "Axum over Actix-web", "tiktoken-rs", "atomic counters for stats") is already implicit in the code; if a specific decision needs preserving long-term, it belongs in the file it concerns per the AGENTS.md guideline.
  • If anyone discovers a reason to resurrect a specific paragraph, git show HEAD~1:PLAN.md recovers it.

Checklist

  • Verified no in-repo references with grep
  • Confirmed each file's "still valid" content is duplicated elsewhere
  • Listed the misleading entries that would harm a new reader

Both files were written at project inception and have not been kept
in sync with reality. Nothing in the repo references them
(verified with grep across .md/.rs/.toml/.sh/.yml/.yaml).

Why they're stale, not historical:

- IDEA.md's architecture diagram shows Anthropic and Gemini provider
  endpoints as first-class boxes, but the server only implements
  OpenAI and OpenResponses. Its "Future Extensions" list is partly
  already-done (WebSocket, stats endpoint), partly aspirational
  (record/replay, Prometheus) — same ideas as PLAN.md's Phase 6.

- PLAN.md's Phase 7 "Set up GitHub releases" and "Publish to
  crates.io" are unchecked, but the project has shipped both
  (v0.2.x releases, listed on crates.io). Its Technical Decisions
  Log claims "YAML for config" as decision #3 — already obsoleted
  by the TOML migration in #37. Several other "unchecked" phases
  (tool calling, Anthropic, Gemini) are aspirational future work
  better tracked as GitHub issues than as a stale plan document.

Active substitutes are already in place:

- Problem statement / "why this exists" -> README.md
- Project structure / module org      -> specs/architecture.md
- API endpoints + capabilities        -> specs/api-endpoints.md +
                                          specs/responses-api.md
- Roadmap / future work               -> GitHub issues
- Design decisions worth preserving   -> code comments per the
                                          AGENTS.md guideline
                                          "Keep decisions as
                                          comments on top of the
                                          file"

Future agents reading the repo should follow README -> AGENTS.md ->
specs/ instead of being pointed at an inception plan that no longer
matches the code.
@chaliy chaliy merged commit aa2ccaa into main May 17, 2026
11 checks passed
@chaliy chaliy deleted the claude/cleanup-plan-idea-t0rOv branch May 17, 2026 17:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant