docs: consolidate Claude guidance into CLAUDE.md

[Wirasm]

Summary

Describe this PR in 2-5 bullets:

• Problem: .claude/rules/*.md had drifted from the actual code and conflicted with the maintained root CLAUDE.md.
• Why it matters: stale Claude memory increases instruction conflicts and makes agent behavior less reliable.
• What changed: removed the individual .claude/rules/* files and updated CLAUDE.md to reflect the current codebase in the areas that were stale.
• What did not change (scope boundary): no runtime code, product behavior, config semantics, database schema, or tests were changed.

UX Journey

Before

Maintainer              Claude project memory
──────────              ─────────────────────
updates CLAUDE.md ───▶  root guidance is current
                        per-file rules remain present
                        some rules contradict code / CLAUDE.md
agent reads both ────▶  conflicting instructions during work

After

Maintainer              Claude project memory
──────────              ─────────────────────
updates CLAUDE.md ───▶  single maintained source of project guidance
                        [-] per-file rules removed
agent reads memory ───▶  lower instruction drift and fewer conflicts

Architecture Diagram

Before

CLAUDE.md
  |
  +--> Claude project memory
  |
.claude/rules/*.md
  |
  +--> Claude project memory

After

[~] CLAUDE.md
  |
  +==> Claude project memory

[-] .claude/rules/*.md

Connection inventory (list every module-to-module edge, mark changes):

From	To	Status	Notes
CLAUDE.md	Claude project memory	modified	Updated stale command/testing/API guidance
.claude/rules/*.md	Claude project memory	removed	Deleted stale per-area rule files

Label Snapshot

• Risk: risk: low
• Size: size: M
• Scope: docs
• Module: docs:claude-memory

Change Metadata

• Change type: docs
• Primary scope: multi

Linked Issue

• Closes #
• Related #
• Depends on # (if stacked)
• Supersedes # (if replacing older PR)

Validation Evidence (required)

Commands and result summary:

bun run type-check
bun run lint
bun run format:check
bun run test
# Or all at once:
bun run validate

• Evidence provided (test/log/trace/screenshot): verified the changed guidance against the source code and migration files before editing.
• If any command is intentionally skipped, explain why: skipped all runtime validation commands because this PR only changes Claude memory/docs files and removes stale .claude/rules markdown.

Security Impact (required)

• New permissions/capabilities? (No)
• New external network calls? (No)
• Secrets/tokens handling changed? (No)
• File system access scope changed? (No)
• If any Yes, describe risk and mitigation:

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Database migration needed? (No)
• If yes, exact upgrade steps:

Human Verification (required)

What was personally validated beyond CI:

• Verified scenarios: checked current source for orchestrator deterministic commands, workflow output format behavior, test batching counts, and current server API endpoints; confirmed CLAUDE.md now reflects those realities.
• Edge cases checked: ensured .claude/rules is fully removed and branch only contains memory/docs cleanup.
• What was not verified: no runtime behavior was exercised.

Side Effects / Blast Radius (required)

• Affected subsystems/workflows: Claude Code project memory only.
• Potential unintended effects: if any deleted rule file contained useful context not preserved elsewhere, future agent sessions may lose that nuance.
• Guardrails/monitoring for early detection: root CLAUDE.md is now the single maintained source; future drift is easier to inspect in one place.

Rollback Plan (required)

• Fast rollback command/path: revert commit 39c6f05b or restore the deleted .claude/rules/* files from dev.
• Feature flags or config toggles (if any): none.
• Observable failure symptoms: Claude sessions stop following a project convention that was previously only documented in a deleted rule file.

Risks and Mitigations

List real risks in this PR (or write None).

• Risk: some removed rule text may have contained still-useful guidance not copied into CLAUDE.md.
  • Mitigation: only corrected obviously stale sections in CLAUDE.md; the cleanup is isolated to docs/memory and is easy to revert.

Summary by CodeRabbit

• Documentation

  • Removed internal development rules documentation (adapters, CLI, database, testing, workflows, etc.).
  • Updated primary documentation with refined command routing and archon directory guidance.

• New Features

  • Added new API endpoints: environment management (GET/PUT/DELETE /api/codebases/:id/env), environment list endpoint, and system health check (GET /api/health).

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: c22ee3f2-ebe9-4c5e-91ef-7608cf9cfc0a

📥 Commits

Reviewing files that changed from the base of the PR and between a4242e6 and 39c6f05.

📒 Files selected for processing (12)

• .claude/rules/adapters.md
• .claude/rules/cli.md
• .claude/rules/database.md
• .claude/rules/dx-quirks.md
• .claude/rules/isolation-patterns.md
• .claude/rules/isolation.md
• .claude/rules/orchestrator.md
• .claude/rules/server-api.md
• .claude/rules/testing.md
• .claude/rules/web-frontend.md
• .claude/rules/workflows.md
• CLAUDE.md

💤 Files with no reviewable changes (11)

• .claude/rules/dx-quirks.md
• .claude/rules/cli.md
• .claude/rules/isolation.md
• .claude/rules/workflows.md
• .claude/rules/orchestrator.md
• .claude/rules/testing.md
• .claude/rules/isolation-patterns.md
• .claude/rules/web-frontend.md
• .claude/rules/adapters.md
• .claude/rules/server-api.md
• .claude/rules/database.md

---

📝 Walkthrough

Walkthrough

This PR removes 11 documentation files from the .claude/rules/ directory containing architectural conventions for adapters, CLI, database, isolation, testing, workflows, and server APIs, while updating CLAUDE.md with refinements to command routing, API endpoints, and workspace documentation.

Changes

Cohort / File(s)	Summary
Rules Documentation Cleanup .claude/rules/adapters.md, .claude/rules/cli.md, .claude/rules/database.md, .claude/rules/dx-quirks.md, .claude/rules/isolation.md, .claude/rules/isolation-patterns.md, .claude/rules/orchestrator.md, .claude/rules/server-api.md, .claude/rules/testing.md, .claude/rules/web-frontend.md, .claude/rules/workflows.md	Deleted 11 comprehensive rules documentation files covering adapter patterns, CLI conventions, database schema/queries, isolation architecture, testing strategies, orchestrator determinism, server API design, and frontend stack guidance.
Main Documentation Update CLAUDE.md	Refined test batch guidance for @archon/adapters, updated deterministic command routing (removed slash command variants, added project management commands), adjusted workspace directory documentation, changed command discovery to direct filesystem resolution via .archon/commands/ and API endpoint GET /api/commands, and added new environment and health endpoints.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• fix: remove CWD env stripping, load ~/.archon/.env with override for binary support #1045: Updates .claude/rules/cli.md while this PR deletes the same file, indicating overlapping documentation changes.

Poem

📚✂️ Files deleted, conventions shed,
Rules archived, wisdom spread,
Clean slate for tomorrow's thread,
Documentation lightened instead! 🐰

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly and specifically describes the main change: consolidating Claude guidance from multiple per-area rule files into a single CLAUDE.md file.
Description check	✅ Passed	The description comprehensively follows the template with all required sections completed: Summary (4 bullets), UX Journey (before/after), Architecture Diagram, Label Snapshot, Change Metadata, Validation Evidence, Security Impact, Compatibility, Human Verification, Side Effects/Blast Radius, and Rollback Plan.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rules-cleanup

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}