Generate Architecture Artifacts From Codebase

Generate Architecture Artifacts From Codebase

What This Skill Produces

• A primary Architecture and Design Document as the main output.
• Architecture options analysis with pros and cons when no established baseline architecture is found.
• Mermaid and PlantUML diagram source artifacts for architecture views.
• A business workflows document that captures workflow steps and business logic.
• A data models document covering entities, relationships, constraints, and flows.
• An open questions document for unresolved/ambiguous areas.
• Architecture image prompt pack.
• Architect Generic Playbook application document (requirements + codebase assessment).
• Supporting evidence, traceability, timeline, and state snapshots.

Use When

• You need architecture artifacts from an existing codebase with or without formal BRD/API requirement docs.
• You want the same output structure every run for auditability.
• You want incremental updates when the codebase changes.

Required Input

• Exactly one path: codebaseRootFolder.

The skill must auto-discover requirement signals from codebaseRootFolder, including:

• BRD-style docs, API specs, ADRs, wiki exports, and markdown notes.
• If requirement docs are missing, infer requirements from code and mark inferred items explicitly.

Detail-First Generation Mechanism (Default)

Use detailed-sequential generation by default.

Process rules:

1. Generate one major document at a time, complete it, run quality checks, then move to the next document.
2. Do not create all documents in a shallow single pass.
3. Keep an internal generation queue and process in this order:
4. architecture/Architecture_and_Design_Document.md
5. workflows/Business_Workflows_and_Logic.md
6. data-models/Data_Models_Document.md
7. playbook/Architect_Generic_Playbook_Applied.md
8. architecture/Architecture_Options_Pros_Cons.md (conditional)
9. diagrams (.mmd, .puml)
10. image-prompts/architecture-image-prompts.md
11. After each file, run a file-level quality gate before continuing.

Minimum depth gate per narrative document:

1. Every section must include concrete details, not placeholders.
2. Each major section must cite at least one source/evidence reference.
3. Include explicit assumptions, risks, and unresolved questions where applicable.
4. Include examples/tables for key logic (scoring, flows, entity mappings) when available.
5. If details are missing, add focused TBD questions instead of generic text.

Document-family depth gates:

1. architecture/Architecture_and_Design_Document.md

• Must contain a complete end-to-end architecture narrative, not just headings.
• Must include explicit component boundaries, interfaces, data flow, deployment, NFRs, and decision rationale.
• Must include source links per major section.

2. workflows/Business_Workflows_and_Logic.md

• Must describe workflow steps, decision points, branching, and business rules in detail.
• Must include exceptions, alternate paths, and trigger conditions.

3. data-models/Data_Models_Document.md

• Must include entity definitions, relationships, cardinality, lifecycle, and ownership.
• Must include examples or tables for key entities and attributes.

4. image-prompts/architecture-image-prompts.md

• Must include one detailed prompt per required view, with scope, style, labels, and relationship constraints.
• Must reference the exact architecture artifact or section it visualizes.

5. traceability/open-questions.md

• Must group questions by artifact/decision area.
• Each question must include why it matters, source reference, and owner/follow-up hint.

6. playbook/Architect_Generic_Playbook_Applied.md

• Must map playbook sections to requirements and evidence with gap/remediation notes.

7. architecture/Architecture_Options_Pros_Cons.md (conditional)

• Must include at least three options with tradeoffs, risks, and recommendation.

Output Contract

Create or update these artifacts under generated-architecture-output/ inside codebaseRootFolder:

1. architecture/Architecture_and_Design_Document.md
2. diagrams/mermaid/component-diagram.mmd
3. diagrams/mermaid/data-flow.mmd
4. diagrams/mermaid/deployment-diagram.mmd
5. diagrams/mermaid/er-database-schema.mmd
6. diagrams/plantuml/component-diagram.puml
7. diagrams/plantuml/data-flow.puml
8. diagrams/plantuml/deployment-diagram.puml
9. diagrams/plantuml/er-database-schema.puml
10. workflows/Business_Workflows_and_Logic.md
11. data-models/Data_Models_Document.md
12. traceability/open-questions.md
13. image-prompts/architecture-image-prompts.md
14. playbook/Architect_Generic_Playbook_Applied.md
15. evidence/evidence-index.md
16. evidence/source-facts.md
17. traceability/requirements-to-evidence-map.md
18. timeline/architecture-timeline.md
19. timeline/source-change-log.md
20. timeline/document-revision-log.md
21. .state/last-run-source-snapshot.json
22. .state/last-run-doc-checksums.json

Conditional output (required when architecture baseline is not established):

1. architecture/Architecture_Options_Pros_Cons.md

Non-negotiable rule:

• These outputs are mandatory on every run. If evidence is incomplete, still generate each file with explicit TBD sections and questions.

Structure compatibility rule:

• Keep old output-structure files when they already exist.
• Update equivalent old-structure files alongside canonical outputs when deltas are detected.
• If an old-structure file has no equivalent in the current run, keep it unchanged and mark it legacy-unmapped in revision log.

Procedure

1. Validate and prepare paths.

• Confirm codebaseRootFolder exists.
• Create generated-architecture-output/ and required subfolders if missing.

2. Discover requirements and codebase shape.

• Discover requirement documents first (BRD, API spec, ADR, wiki/md docs), then code/config evidence.
• Enumerate source files, build files, runtime configs, infra files, and docs.
• Detect languages, frameworks, package managers, and deployment model.
• Identify module boundaries by directory structure and import/reference patterns.

3. Discover architecture signals.

• Extract API surface from OpenAPI specs, route definitions, controllers, handlers, and RPC contracts.
• Extract data model signals from schema files, ORM models, migrations, SQL, and repository code.
• Extract integration signals from HTTP clients, SDK usage, queues, events, and secrets/config references.
• Extract runtime and NFR signals from config (timeouts, retries, security headers, auth, scaling hints, logging, telemetry).

4. Build normalized evidence inventory.

• Record each discovered source with path, type, purpose, and confidence.
• Group evidence by architecture domain: context, component, data, integration, deployment, security, reliability.

5. Initialize update mode.

• If .state/last-run-source-snapshot.json exists, run incremental mode.
• Classify file changes as added, updated, removed, unchanged.
• Record change summary in timeline/source-change-log.md.
• Use .state/last-run-doc-checksums.json to detect changed documents (requirements/docs) and changed generated artifacts.
• Trigger targeted regeneration from document changes first, then code/config changes.

6. Generate architecture facts.

• Produce explicit fact cards with source references.
• Mark inferred facts clearly as assumptions.
• Flag conflicts or ambiguity when multiple code paths imply different behavior.

7. Generate architecture options when baseline is missing.

• If requirements and code evidence do not indicate a stable existing architecture baseline, create architecture/Architecture_Options_Pros_Cons.md.
• Include at least three architecture options.
• For each option include:

1. Option summary
2. Pros
3. Cons
4. Risks
5. Operational impact
6. Migration complexity

• Add recommended option and decision rationale.

8. Generate primary architecture and design document.

• Build architecture/Architecture_and_Design_Document.md first and treat it as the primary output.
• Minimum required sections:

1. system context
2. component architecture
3. data architecture and flow
4. integration architecture
5. deployment and operations
6. security and compliance
7. risks, assumptions, and decisions

• For unknown sections, add TBD and track questions in traceability/open-questions.md.

9. Generate workflows document.

• Create workflows/Business_Workflows_and_Logic.md.
• Include end-to-end workflow steps, decision points, business rules, exceptions, and dependency calls.

10. Generate data models document.

• Create data-models/Data_Models_Document.md.
• Include entities, attributes, keys, relationships, cardinality, lifecycle, and data lineage/flows.

11. Generate image prompts.

• Create image-prompts/architecture-image-prompts.md.
• Cover at least: context, component, deployment, data flow, and workflow views.
• Include style constraints, scope, labels, and relationships.

12. Generate diagram source artifacts.

• Generate Mermaid and PlantUML files for: component, data flow, deployment, and ER/database schema.
• Ensure diagram labels and node names match architecture docs.
• If a view cannot be fully derived, emit partial diagram plus explicit TODO notes in comments.

13. Apply Architect Generic Playbook.

• Create playbook/Architect_Generic_Playbook_Applied.md.
• Document how each playbook section is satisfied by requirements and by code evidence.
• Record gaps, deviations, and recommended remediations.

14. Generate traceability.

• Map major architecture claims to concrete code/config evidence in traceability/requirements-to-evidence-map.md.
• Capture unresolved questions and conflict notes in traceability/open-questions.md.

15. Maintain timeline artifacts.

• Append run summary and key architecture changes to timeline/architecture-timeline.md.
• Append per-document change entries to timeline/document-revision-log.md.
• Never delete prior timeline entries.
• Include preserved existing docs count and updated docs count in each run summary.

16. Persist state snapshots.

• Save current source snapshot to .state/last-run-source-snapshot.json.
• Save generated document checksums to .state/last-run-doc-checksums.json.

17. Quality checks.

• Completeness: all output artifacts exist.
• Traceability: all major claims include source references.
• Consistency: names and interfaces are consistent across outputs.
• Explainability: assumptions and unknowns are explicit.
• Diagram validity: Mermaid and PlantUML files must be syntactically valid and aligned with generated docs.
• Priority check: architecture/Architecture_and_Design_Document.md is generated first and references the other generated artifacts.
• Sequencing check: each major file passed file-level quality gate before the next file was generated.
• Depth check: generated narrative docs are detailed enough for design review (not outline-only text).

Decision Points

• If architecture signals are weak: produce minimum baseline docs and raise targeted open questions.
• If no established architecture baseline exists: produce architecture/Architecture_Options_Pros_Cons.md before final architecture selection.
• If conflicting patterns exist: prefer executable runtime path over dead/legacy code and log rationale.
• If monorepo is large: prioritize active apps/services first, then shared libraries.
• If generated outputs already exist: update impacted sections only and preserve unchanged content.
• If requirement documents change but code does not: still update architecture, workflows, data model, and playbook outputs based on document deltas.

Completion Criteria

• All required artifacts are present under generated-architecture-output/.
• If no established architecture exists, architecture/Architecture_Options_Pros_Cons.md contains at least three options and a recommended path.
• Primary document architecture/Architecture_and_Design_Document.md exists and is complete.
• Workflows and data-model docs exist with business logic and model relationships.
• Open questions document exists even if empty (with No open questions marker).
• Playbook application document exists and references both requirements and code evidence.
• Every major section has sourced content or explicit TBD plus question.
• Diagram source files exist for each mandatory view (component, data flow, deployment, ER/schema).
• Timeline and state files are updated for the run.
• Old structure files remain available and are synchronized where equivalent outputs exist.
• A reviewer can trace architecture conclusions back to concrete code/config evidence.

Invocation Pattern

When invoked, ask only for:

1. codebaseRootFolder

Then:

1. Analyze the codebase.
2. Generate/update artifacts in detailed-sequential mode (one file at a time with file-level gates).
3. Report output paths, change summary, open questions, and per-file gate outcomes.