[tunahorse]

Summary

• Refactors AGENTS.md into a compact repository map and moves detailed workflow guidance into markdown docs.
• Adds the markdown artifact/process/project control-plane docs and frontmatter-valid mdBook chapters referenced by docs/SUMMARY.md.
• Removes tracked .DS_Store, ignores future .DS_Store files, and updates CHANGELOG.md for merged PR feat: add changelog PR coverage test and backfill missing entries #17 plus this PR [codex] chore: refactor agent docs #18.

Validation

• cargo test --test changelog_test
• python3 scripts/check_markdown_frontmatter.py
• mdbook build
• git diff --cached --check
• just check (also passed through the pre-push hook)

Draft PR for review.

Summary by CodeRabbit

Release Notes

• Documentation

  • Enhanced repository documentation with comprehensive architecture guide, process workflows, and project context references.
  • Established artifact system for tracking decisions, executions, and evidence across development sessions.

• Chores

  • Updated .gitignore to exclude macOS .DS_Store files.
  • Introduced changelog coverage validation to ensure merged changes are documented.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: f6b39e55-74d5-4e30-a5be-e53d4a149edd

📥 Commits

Reviewing files that changed from the base of the PR and between 28d31dd and af766aa.

⛔ Files ignored due to path filters (1)

• .DS_Store is excluded by !**/.DS_Store

📒 Files selected for processing (37)

• .gitignore
• AGENTS.md
• CHANGELOG.md
• docs/artifacts/INDEX.md
• docs/artifacts/active/CHARTER-20260530-agents-doc-cleanup.md
• docs/artifacts/active/EXEC-20260530-agents-doc-cleanup.md
• docs/artifacts/active/README.md
• docs/artifacts/completed/README.md
• docs/artifacts/decisions/README.md
• docs/artifacts/evidence/EVID-20260530-agents-doc-cleanup.md
• docs/artifacts/evidence/README.md
• docs/artifacts/explorations/README.md
• docs/artifacts/memory/MEM-20260530-agents-doc-cleanup.md
• docs/artifacts/memory/README.md
• docs/artifacts/open-issues/README.md
• docs/artifacts/templates/TEMPLATE_BUG_FIX_CHARTER.md
• docs/artifacts/templates/TEMPLATE_DECISION_RECORD.md
• docs/artifacts/templates/TEMPLATE_EVIDENCE_PACK.md
• docs/artifacts/templates/TEMPLATE_EXECUTION_LOG.md
• docs/artifacts/templates/TEMPLATE_EXPLORATION_MEMORY.md
• docs/artifacts/templates/TEMPLATE_OPEN_ISSUE.md
• docs/artifacts/templates/TEMPLATE_REFACTOR_CHARTER.md
• docs/artifacts/templates/TEMPLATE_RELEASE_CHECKLIST.md
• docs/artifacts/templates/TEMPLATE_SESSION_CHARTER.md
• docs/artifacts/templates/TEMPLATE_SESSION_MEMORY.md
• docs/dependency-direction.md
• docs/ideal-dependency-architecture-map.md
• docs/import-organization.md
• docs/process/AGENT_HANDOFF.md
• docs/process/GARBAGE_COLLECTION.md
• docs/process/RULES.md
• docs/process/SESSION_PROMPTS.md
• docs/process/WORKFLOW.md
• docs/project/ARCHITECTURE.md
• docs/project/CONSTRAINTS.md
• docs/project/PROJECT_CONTEXT.md
• docs/project/TESTING.md

---

📝 Walkthrough

Walkthrough

This pull request establishes a comprehensive markdown-based control plane system for the sophon repository. It defines structured artifact types (charters, execution logs, evidence packs, memory, decisions), standardized templates, governance rules, process workflows, and project-specific constraints and architectural boundaries, demonstrating the system with a concrete AGENTS.md cleanup session.

Changes

Markdown Control Plane System

Layer / File(s)	Summary
Artifact System Foundation & Folder Structure docs/artifacts/INDEX.md, docs/artifacts/active/README.md, docs/artifacts/completed/README.md, docs/artifacts/decisions/README.md, docs/artifacts/evidence/README.md, docs/artifacts/explorations/README.md, docs/artifacts/memory/README.md, docs/artifacts/open-issues/README.md	System index document defines lifecycle, artifact types, naming conventions, and required markdown header contract. Each folder README specifies its purpose, content rules, and where artifacts move after completion.
Artifact Templates docs/artifacts/templates/TEMPLATE_*.md (11 templates)	Standardized templates for session charters, bug fix and refactor charters, execution logs, evidence packs, session memory, exploration memory, decision records, release checklists, and open issues with structured sections and placeholder metadata.
Process Rules & Workflow Governance docs/process/RULES.md, docs/process/WORKFLOW.md	Non-negotiable governance rules (charter-before-code, evidence-before-done, decision record requirements), markdown-only control plane model, context/constraint tracking rules, evidence standards with concrete examples, and explicit workflow flows for exploration, execution, and decision cycles with stop conditions.
Agent Handoff & Documentation Maintenance docs/process/AGENT_HANDOFF.md, docs/process/GARBAGE_COLLECTION.md	Handoff protocol specifies onboarding read order, session classification, required first output per session type, and good vs. bad handoff examples. Garbage collection process removes stale content, maintains artifact index currency, and defines when artifacts are superseded versus deleted.
Session Type Prompts docs/process/SESSION_PROMPTS.md	Standardized prompts for Exploration, Execution, Bug Fix, Refactor, Session End, and Evidence Pack workflows, guiding agents on required artifacts and information capture per session type.
Project Context & Architecture docs/project/PROJECT_CONTEXT.md, docs/project/ARCHITECTURE.md	PROJECT_CONTEXT describes sophon-cli's purpose, user groups, current goal, key workflows, high-level architecture, testing approach, and known risks. ARCHITECTURE details system structure (provider-agnostic domain, bootstrapped services, adapters, HTTP transport), boundaries by source path, dependency direction, data flow, external integrations, invariants, common mistakes, and guidance on preferred/prohibited change locations.
Project Constraints & Testing docs/project/CONSTRAINTS.md, docs/project/TESTING.md	CONSTRAINTS enumerates hard rules (charter/evidence/decision requirements), architecture layer import rules, dependency hygiene, platform/CLI output conventions, documentation style (mandatory YAML frontmatter), and protected areas (secrets, generated files). TESTING defines standard just check command set, smoke test procedures (no-network vs. live-provider), regression checks, and evidence requirements for bug fixes, refactors, and releases.
Dependency Architecture & Import Organization docs/dependency-direction.md, docs/ideal-dependency-architecture-map.md, docs/import-organization.md	Dependency direction flowchart maps intended flow from main.rs → cli → bootstrap → app → {domain, providers} → transport → reqwest. Ideal architecture map and import organization table define per-layer responsibilities and forbidden reverse imports enforced by architecture_test.rs.
Example Session: AGENTS.md Cleanup docs/artifacts/active/CHARTER-20260530-agents-doc-cleanup.md, docs/artifacts/active/EXEC-20260530-agents-doc-cleanup.md, docs/artifacts/memory/MEM-20260530-agents-doc-cleanup.md, docs/artifacts/evidence/EVID-20260530-agents-doc-cleanup.md	Concrete May 30, 2026 session demonstrates the system: charter defines scope (AGENTS.md rewrite, docs staging, .DS_Store cleanup) and exit criteria; execution log records chronological steps and fixes; session memory captures decisions and affected files; evidence pack proves claims with commands run, test results, and validation checklist.
Root Entry Point Updates .gitignore, AGENTS.md, CHANGELOG.md	.gitignore adds .DS_Store. AGENTS.md completely rewritten as process-focused repository map with "Read First" artifact/project docs locations, updated commands (provider selection), architecture boundaries tied to tests, artifact workflow guidance, and validation checklist. CHANGELOG.md adds entries for changelog coverage test, control-plane documentation, compact AGENTS.md map, and .DS_Store cleanup.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

📚 A markdown warren has been built,
With charters, memory, and evidence gilt—
No more guesswork in the burrow's halls,
Just structured truth on digital walls! 🐰✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/refactor-agent-docs

---

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.}