Documentation Scaffold

Process

1. Source Review: Inspect existing docs for accuracy and gaps.
2. Scope: Decide whether this is greenfield bootstrap or brownfield cleanup.
3. Authoring:
   • Create or update AGENTS.md as canonical context.
   • Add a compatible CLAUDE.md only if the repo needs it.
   • Ensure README contains setup and verification steps.
   • Add ADRs for material decisions.
   • If local secrets are used, include a safe .env.example and ensure real secrets are excluded from version control.
4. Verification: Run doc quality gates (documentation-as-code).
5. Review: Tech Lead and Software Engineer validate doc accuracy and scope.

Example Test / Validation

• Documentation checks pass and onboarding steps are reproducible.

Common Red Flags / Guardrail Violations

• Writing new docs that contradict the actual repo state.
• Using CLAUDE.md as the only context file when AGENTS.md is required.
• Skipping ADRs for structural decisions.

Recommended Review Personas

• Tech Lead - validates architectural intent and decision coverage.
• Software Engineer - validates onboarding clarity and accuracy.

Skill Priority

P2 - Consistency & Governance

Conflict Resolution Rules

• If documentation conflicts with implementation, implementation evidence wins and docs must be corrected before proceeding.

Conceptual Dependencies

• documentation-as-code

Classification

Governance Core

Notes

Use AGENTS.md as the default context file for this repo. Only add CLAUDE.md when compatibility is explicitly required.