docs: add special-case architecture review guidance

Author: rohans0509

.claude/agents/review.md

@@ -25,14 +25,23 @@ You are a code reviewer for codealmanac. Review like someone who has to maintain
 6. **Tests.** Tests should cover the behavior boundary that changed. Command tests can fake `runAgent`; provider adapter tests should assert args/parsing/status behavior when that surface changes.
 7. **CLAUDE.md violations.** Explicitly cite the rule or principle violated.
 
-## Codealmanac invariants to enforce
-
-- Only `bootstrap` and `capture` may touch AI or write wiki pages.
-- Other commands operate on `index.db`, frontmatter, and the filesystem only.
-- No propose/apply flow, no dry-run mode, no interactive prompt.
-- Prompts stay as files in `prompts/`, not embedded TypeScript strings.
-- Provider modules expose `metadata`, `checkStatus()`, `assertReady()`, and `run()`.
-- `prompts/reviewer.md` is the wiki reviewer. This file is the code reviewer.
+## Special-case architecture
+
+This project has been built with AI. Existing special conditions are not automatically legitimate just because they are already in the codebase; they may be residue from locally effective one-off fixes that were never consciously accepted as architecture.
+
+Actively question new and existing special paths: extra flags, copied or derived files, workflow-only storage, fallback branches, bespoke state, command-specific parsers, provider-specific conditionals outside provider modules, prompt-specific preprocessing, helper scripts, and parallel lifecycle paths. Ask whether the existing general abstraction should absorb the behavior instead.
+
+Do not reject every special case. Internally weight each one by cost and evidence:
+
+- What invariant does it protect?
+- What user-facing behavior would break if it were removed?
+- Is it compensating for a missing general abstraction?
+- Is it temporary glue with a removal condition, or permanent architecture?
+- Does it duplicate source-of-truth data or create a lifecycle future maintainers must remember?
+
+Assume the agents using this repo are capable: they can read files, inspect history, follow wiki pages, call tools, and reason over context. Flag rigid preprocessing, copied context bundles, artificial staging files, or orchestration that exists only to make an agent's input look simpler when a clear contract over the real source material would work.
+
+This is an open-source project. Treat new tracked files as public API surface and future maintenance burden. When a change adds a file, ask whether it belongs in an existing prompt, doc, module, or test helper instead, and what prevents it from becoming stale.
 
 ## On restructure
 

AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

CLAUDE.md

@@ -11,6 +11,11 @@ Intelligence lives in prompts, not pipelines. When judgment is needed — decidi
 There is no prize for preserving awkward code. Prefer the structure a new maintainer would understand immediately.
 
 - Prefer obvious architecture over local patching when a bug exposes mixed responsibilities.
+- Before accepting a solution, ask whether it creates a one-off mechanism where the existing general model could be extended instead. If it does, require an explicit architectural justification: why the general path is insufficient, whether the exception is temporary or permanent, how it is bounded, and what would make it safe to remove or generalize later.
+- Existing special conditions are not automatically legitimate just because they are already in the codebase. This project has been built with AI, and AI agents can leave behind locally effective one-off fixes that were never consciously accepted as architecture. Treat extra flags, copied files, fallback paths, bespoke state, provider-specific branches, and helper scripts as provisional until they earn their place.
+- Weight special cases by cost and evidence. Do not remove them reflexively; compatibility, migration, safety, platform, and provider constraints can be real. But a narrow exception with high maintenance cost needs stronger justification than a small localized shim.
+- Assume the agents using this repo are capable: they can read files, inspect history, follow wiki pages, call tools, and reason over context. Do not build rigid preprocessing, copied context bundles, artificial staging files, or elaborate orchestration solely because an agent might need help. Prefer giving the agent real source material and a clear contract unless there is evidence that the general agentic workflow fails.
+- This is an open-source project, so every new tracked file is public surface area and future maintenance burden. Before adding a file, ask who will own it, whether it belongs in an existing prompt/doc/module, and what keeps it from becoming stale.
 - Keep modules honest: a file named `auth.ts` should not secretly mean "Claude auth"; a central status file should not know provider-specific details.
 - Short files are good, but responsibility boundaries matter more than line count. Split when a file has multiple reasons to change.
 - Delete dead compatibility layers once callers have moved. Compatibility shims are temporary bridges, not architecture.