architecture-docs ยท diff
git:20261001.1ab73e9 to git:20261001.67d45f1
31 added, 23 removed. Audit A to A.
---
name: architecture-docs
- description: Write or synchronize architecture and agent guidance using verified repository evidence. Use when the user asks to write, update, audit, or consolidate architecture docs, README.md, AGENTS.md, SKILL.md, or .agents guidance, or when an authorized change requires documentation updates. Documentation only; do not edit runtime code.
- argument-hint: Documentation request, instruction-file revision, or accepted change with affected docs.
+ description: Write and update project guidance using verified code and accepted decisions. Use when the user asks to write, audit, or simplify architecture docs, README.md, AGENTS.md, SKILL.md, or .agents guidance, or when an approved change needs related docs. Documentation only; do not edit runtime code.
+ argument-hint: Document request, prompt rewrite, or approved change with affected docs.
---
# Architecture docs
- ## Outcome and boundary
+ Write guidance that is easy to follow and matches accepted decisions and verified facts.
- Produce concise, consistent guidance that describes accepted decisions and verified reality.
+ Edit only requested documents or docs directly affected by an approved implementation. Do not edit code, tests, configuration, or dependencies to make a document true. Do not change plan approvals or task status unless the request includes them or an approved implementation has verified progress to record.
- Edit only documents authorized by the request or directly affected by an authorized implementation. Shared agent rules and skill files are valid targets when explicitly requested. Do not edit runtime code, tests, configuration, dependencies, or unrelated documents to make the documentation true. Do not bootstrap a documentation tree merely because another skill is being used.
+ ## Step 1: Read and check the facts
- ## Ground and synchronize
+ 1. Read the request, project instructions, accepted decisions, and documents in scope.
+ 2. Follow relevant links in the existing project guides. Do not assume every project has the same documentation folders.
+ 3. Verify file paths, symbols, commands, and behavior against current source. Record the branch or commit when comparing projects.
+ 4. Separate current behavior, accepted work that is not implemented, and proposals. Report disagreements that affect the document.
- - Read applicable instruction entrypoints, the current request, accepted decisions, and documents in scope. Verify paths, symbols, commands, and behavior against current repository evidence.
- - Follow the existing project guide into context, rules, plans/decisions, and testing guidance. Record the source branch/ref for cross-repository audits; do not treat a project guide as auto-loaded or assume all repositories use the same documentation tree.
- - Distinguish current implementation, approved but unimplemented design, and proposals. Label these states rather than merging them into a claim that a feature works.
- - Choose the existing authoritative document or instruction file. Update the smallest set needed for consistency; link to a source of truth instead of duplicating it.
- - For instruction suites, check the entry conditions, permissions, outputs, and handoffs together. A downstream skill must not grant itself authority denied by the common rules or the current request.
- - When deriving shared guidance from projects, cite working source/contracts/tests and distinguish repeated conventions from project-specific decisions, scaffolds, and legacy defects. Generalize ownership and verification principles without copying domain constants, storage backends, runtime stages, or UI themes into every project.
- - Describe the outcome and constraints. Include exact procedures only where order matters for correctness, safety, or reproducibility; avoid prescribing tools and ceremony for ordinary work.
- - Keep durable conventions and non-obvious constraints. Remove stale paths, conflicting rules, redundant generic advice, arbitrary size limits, unsupported claims, and speculative scaffolding. Preserve security and data-loss warnings in full.
- - Match the language and structure requested for the artifact. Shared agent instructions and skills stay in English. Preserve exact identifiers and commands.
+ ## Step 2: Choose where to write
- ## Structure and verification
+ 1. Update the existing document that owns the guidance.
+ 2. Change only the files needed for consistency. Link to shared rules instead of repeating them.
+ 3. For a new requested document, use the project's layout or a simple path for its purpose. Do not create a whole documentation tree.
- Use the repository's current layout. When a new document is authorized and no convention exists, select a minimal path for its actual purpose; do not generate README, context, rules, testing, plans, or runbooks as a mandatory bundle.
+ Keep a root README focused on purpose, requirements, usage, checks, and important limits. Add a diagram only when it explains a verified design.
- A root README should contain only the supported material needed by its audience: purpose, prerequisites, usage, verification, and important boundaries. Use diagrams only when they clarify a verified architecture; do not fill a word quota.
+ ## Step 3: Write clear instructions
- Before finishing, check referenced files, links, commands, terminology, version labels, and contradictions across the affected documents. Run safe checks when needed to substantiate behavior; do not claim a proposed flow was tested. For a shared instruction rewrite, check representative task scenarios for consistent permissions and handoffs, and obtain independent review when warranted.
+ 1. Use plain English for shared instructions and skills. Use the requested language for other documents. Keep identifiers and commands exact.
+ 2. State the goal and scope first. Use short sentences with a clear action.
+ 3. Use numbered steps when order matters. Put optional or task-specific details under a clear condition.
+ 4. Keep project rules the agent cannot infer from the code. Remove repeated advice, stale paths, unsupported claims, and arbitrary size limits.
+ 5. Preserve security and data-loss warnings in full.
- Synchronize existing context/testing guides and module READMEs when authorized changes affect their paths, entrypoints, environment, contracts, or supported behavior. Do not infer plan approval, completion, acceptance, or release from a directory name or old test count. Report unresolved documentation drift separately from verified runtime defects.
+ For skills, check when each skill is selected, what it may change, what it returns, and where it stops. A handoff cannot grant extra permission.
- ## Handoff and output
+ When learning from other projects, use working code and tests as evidence. Reuse useful design principles; keep project-specific databases, agent stages, business rules, and themes out of shared requirements.
- Report documents changed, decisive consistency checks, and unresolved questions. Send a discovered runtime defect to `debug-investigator`, an unresolved architectural decision to `implementation-planner`, or an authorized implementation correction to `thoughtful-coder`; do not perform those changes as part of documentation-only work.
+ ## Step 4: Review and report
- A documentation request does not authorize changing plan approvals or implementation status. Update a plan only when the requested documentation scope includes it or when recording verified progress from the authorized implementation.
+ 1. Check links, paths, commands, names, versions, and contradictions across the changed documents.
+ 2. For a prompt rewrite, walk through representative requests and check permissions, steps, outputs, and handoffs. Use independent review when required and available.
+ 3. Run safe checks needed to support factual claims. Do not describe a proposed flow as tested.
+ 4. Update affected existing project guides or module READMEs when the approved work changes their instructions.
+
+ Report changed documents, check results, and unresolved questions. Keep document errors separate from confirmed runtime bugs.
+
+ Send a runtime bug to `debug-investigator`, a design question to `implementation-planner`, or an approved code correction to `thoughtful-coder`. Do not perform those code changes during documentation-only work.