Project Docs Generator

Step 0) Clarify the goal and audience (ask first)

Ask the user the minimum questions from:

• references/questionnaire.md

Do not start writing “final” docs until you can answer at least:

• What are the critical user/business workflows?
• Is this a monolith or a distributed system (microservices/events)?
• What are the integration surfaces (APIs, events, files)?
• What are the non-functional targets (SLOs, throughput, RTO/RPO)?
• Is there any compliance/regulatory/audit requirement? If yes, which frameworks/sources are authoritative?
• What tech stack choices are locked (backend, frontend, mobile, data, IaC)?
• Do we need UI/UX planning artifacts (journeys, screen inventory, wireframes)?
• Do we need an AI agent implementation plan (AGENT.md + sprint execution plan)?

If details are missing, keep explicit TODO markers and add an “Open questions” section with owners.

Step 1) Pick a documentation blueprint (structure)

Use the default blueprint described in:

• references/docs-blueprint.md

Then scaffold with scripts/scaffold_project_docs.py.

Step 2) Research the right standards (don’t invent requirements)

When writing docs that cite standards, use authoritative sources and record them explicitly.

Use:

• references/research-sources.md

Rules:

• Prefer official specs (OpenAPI/AsyncAPI), RFCs, and established frameworks (C4, ADRs, OWASP, NIST/ISO).
• If compliance is in scope, create/maintain a sources register and traceability matrix (templates under assets/templates/standard/docs/06-compliance/).
• If unsure about an obligation, write it as a question with an owner; do not guess.

Step 3) Write docs in the right order (so it stays consistent)

Recommended sequence:

1. docs/DOCS_GOVERNANCE.md + docs/STYLE_GUIDE.md (sets the quality bar).
2. docs/00-project-charter.md + docs/00-vision-roadmap.md (why/what/when).
3. docs/02-architecture/* (system map, responsibilities, integrations, security, observability).
4. docs/03-modules/* (module/service specs that link to contracts).
5. specs/* (OpenAPI/AsyncAPI/file specs) and link them from the relevant module docs.
6. docs/01-discovery/* (journeys, screen inventory, UI/UX stories, wireframe checklist, design backlog).
7. epics/* (delivery backlog; stories with acceptance criteria + outputs).
8. epics/sprints/* (sprint plan, per-sprint backlogs, refinement).
9. docs/00-ai-agent-implementation-plan.md + AGENT.md (AI agent execution guidance).
10. docs/07-operations/* (runbooks, DR, incident response).
11. Optional: docs/06-compliance/* (requirements register, traceability, retention/legal hold).

Use the “quality bar” checklist in:

• references/quality-bar.md

Step 4) Validate and iterate (docs-as-code)

• Link hygiene:
  • python3 <SKILL_DIR>/scripts/check_md_links.py --root .
• Contract hygiene (if applicable):
  • follow the repo’s specs/QUALITY_GATES.md (or generate one via templates)
• Coverage checks (if UX/sprints are in scope):
  • Every UX story appears in the sprint mapping.
  • Every sprint backlog references its story files and acceptance criteria.

Bundled resources

• Templates: assets/templates/standard/ (docs/ + specs/ + epics/ + prototypes/)
• References:
  • references/questionnaire.md (what to ask)
  • references/docs-blueprint.md (what to generate)
  • references/research-sources.md (what to cite)
  • references/quality-bar.md (definition of done)
• Scripts:
  • scripts/scaffold_project_docs.py (scaffold the docs set)
  • scripts/check_md_links.py (validate repo-local Markdown links)