architecture-docs-export

name

architecture-docs-export

description

On-demand export of architecture documents to professional Word (.docx) files. Exports are never automatic — invoke explicitly when ready to produce deliverables. Solution Architecture mode synthesizes an Executive Summary from docs/01-system-overview.md, the component index, and the compliance manifest (if present), then exports individual ADR docs. Handoff mode exports selected component development handoffs from handoffs/. Compliance mode exports selected compliance contracts from compliance-docs/. Security Posture mode exports the consolidated security validation checklist (analysis/SECURITY-POSTURE-<date>.md, from architecture-analysis) as a reviewer-fillable worksheet. IMPORTANT — this skill ONLY produces Word .docx files. It does NOT handle releasing, publishing, tagging, freezing, bumping, or finalizing an architecture version. For the Draft → Released lifecycle (git tag architecture-v{version}, archive snapshot, semver bump), use the `architecture-docs` skill (Workflow 10) instead. Do NOT invoke this skill when the user says "release my architecture", "release architecture", "publish architecture", "ship architecture", "tag architecture version", "freeze architecture", "bump architecture version", or "finalize architecture" — those route to `architecture-docs`.

Architecture Doc Export Skill — Orchestrator

Exports architecture documents to professional Word files on demand.

On-demand only — this skill never runs automatically after document generation. Invoke it explicitly when you are ready to produce deliverable Word files.

---

Architecture — Orchestrator + Sub-Agent (v3.8.0)

As of v3.8.0, this skill is an orchestrator. The actual export work (file reads, markdown composition, bun run tools/docgen/generate-doc.js invocations) runs inside the docs-export-generator sub-agent, pinned to model: sonnet. It now covers four export modes: Solution Architecture, Component Handoff, Compliance Contract, and Security Posture.

Why: Export is a high-frequency, zero-synthesis task — pure verbatim extraction + docgen orchestration. Running it on Opus (the default for most Claude Code sessions) wastes token budget. The sub-agent pins Sonnet deterministically, so cost per run does not depend on whoever invokes it. Teams that batch-export ADRs, handoffs, and compliance contracts weekly/monthly see immediate savings.

Orchestrator responsibilities (main context):

• User interaction: listing ADRs / handoffs / compliance contracts, parsing selection ("all", numbers, ranges)
• Plugin directory resolution
• Compliance contract metadata extraction (score + status from Document Control table) for user-facing display
• Spawning the sub-agent with the full job spec

Sub-agent responsibilities (agents/generators/docs-export-generator.md):

• Read source files verbatim
• Compose the executive summary markdown (SA mode)
• Call docgen per output
• Clean up temp files
• Report a structured EXPORT_RESULT: block back

---

Runtime: Bun only — never Node. All generator calls inside the sub-agent use bun run $plugin_dir/tools/docgen/generate-doc.js (absolute path). If bun run hangs:

1. Ensure the docx package is installed: cd $plugin_dir/tools/docgen && bun install
2. Confirm plugin_dir was resolved correctly in Step 0 — re-run the Glob if unsure
3. Never fall back to node — it is not an authorized runtime

Documentation Fidelity: All executive summary content is extracted verbatim from source files. No paraphrasing, no embellishment. If a required section exists in the source but is empty, the sub-agent writes [NOT DOCUMENTED — add content to <source-file>]. Compliance statistics are computed strictly from manifest table values.

---

What Gets Exported

Export Mode	Input Sources	Output
Solution Architecture	docs/01-system-overview.md + docs/02-architecture-principles.md + docs/components/README.md + compliance-docs/COMPLIANCE_MANIFEST.md (optional)	exports/SA-<name>.docx (executive summary) + exports/ADR-NNN-<title>.docx per ADR
Component Handoff	Selected handoff(s) from handoffs/	exports/HANDOFF-<component>.docx per component
Compliance Contract	Selected contract(s) from compliance-docs/	exports/CC-<domain>-<project>.docx per contract; Questions & Gaps Register cells are highlighted for stakeholder editing
Security Posture	Selected Security Posture report(s) from analysis/ (SECURITY-POSTURE-<date>.md)	exports/SECURITY-POSTURE-<name>.docx; Status / Owner / Evidence checklist cells are highlighted for reviewer completion

---

Step 0 — Resolve Plugin Directory (orchestrator)

Before spawning the sub-agent, the orchestrator MUST resolve the absolute path to the plugin installation and pass it in the spawn prompt.

Step 0a — Glob (dev/local mode):

Glob for: **/{sa-skills,solutions-architect-skills}/tools/docgen/generate-doc.js

The brace expansion matches both marketplace installs (sa-skills/ in ~/.claude/plugins/cache/...) and local dev clones (historical repo folder solutions-architect-skills/). If found, strip /tools/docgen/generate-doc.js from the result to get plugin_dir.

Step 0b — Marketplace fallback:

If Glob returns nothing, run:

plugin_dir=$(bun ~/.claude/plugins/marketplaces/shadowx4fox-solution-architect-marketplace/skills/architecture-compliance/utils/resolve-plugin-dir.ts)

If both fail:

❌ Cannot locate plugin directory. Ensure the plugin is installed correctly.

plugin_dir is passed to the sub-agent in the spawn prompt — the sub-agent does NOT re-resolve it.

---

Workflow A — Export Solution Architecture

Trigger phrases: "export architecture", "export to Word", "export solution architecture"

Step A.1 — Validate prerequisites (orchestrator)

Confirm docs/01-system-overview.md exists. If not:

❌ docs/01-system-overview.md not found.
   Generate architecture documentation first with /skill architecture-docs.

Step A.2 — Discover ADRs (orchestrator)

Scan for ADR files in these locations, in order:

• adr/ADR-*.md
• docs/adr/ADR-*.md
• docs/decisions/ADR-*.md
• ADR-*.md in project root

Collect absolute paths. If zero ADRs found, still proceed — the executive summary will have an empty ADR table.

Step A.3 — Determine solution slug (orchestrator)

Read docs/01-system-overview.md's H1; kebab-case it for the output filename. Pass as solution_name_slug.

Step A.4 — Spawn the sub-agent

Invoke sa-skills:generators:docs-export-generator with a prompt providing:

• job_type: solution-architecture
• plugin_dir: <absolute path from Step 0>
• project_dir: <CWD>
• solution_name_slug: <from Step A.3>
• items: <JSON array of absolute ADR file paths from Step A.2>

Wait for the sub-agent's EXPORT_RESULT: block, then report to user.

Step A.5 — Report (orchestrator)

Parse the sub-agent's EXPORT_RESULT: block and display:

✅ Solution Architecture Export Complete

   exports/SA-<solution-name>.docx          (Executive Summary)
   exports/ADR-001-<title>.docx             (Architecture Decision 001)
   exports/ADR-002-<title>.docx             (Architecture Decision 002)
   ...

If status: PARTIAL or FAILED, list the failures from the result block.

---

Workflow B — Export Component Handoff

Trigger phrases: "export handoff", "export dev handoff", "export to Word"

Step B.1 — List available handoffs (orchestrator)

Glob handoffs/*-handoff.md. If none found:

❌ No handoff documents found in handoffs/.
   Generate them first with /skill architecture-dev-handoff.

Otherwise display numbered list:

Available component handoffs:

  1. 01-payment-api-handoff.md        Payment API
  2. 02-user-service-handoff.md       User Service
  3. 03-audit-db-handoff.md           Audit Database

Which component(s) to export?
  Enter numbers (e.g. 1, 3), ranges (e.g. 1-3), or "all"

Step B.2 — Parse selection (orchestrator)

Convert user input to the list of absolute paths.

Step B.3 — Spawn the sub-agent

Invoke sa-skills:generators:docs-export-generator with:

• job_type: handoff
• plugin_dir: <absolute path>
• project_dir: <CWD>
• items: <JSON array of absolute handoff file paths>

Step B.4 — Report (orchestrator)

✅ Handoff Export Complete
   exports/HANDOFF-payment-api.docx    (Payment API)
   exports/HANDOFF-user-service.docx   (User Service)

---

Workflow C — Export Compliance Contracts

Trigger phrases: "export compliance", "export compliance contract", "export compliance to Word"

Step C.1 — List available contracts (orchestrator)

Glob compliance-docs/*.md (excluding COMPLIANCE_MANIFEST.md). If none:

❌ No compliance contracts found in compliance-docs/.
   Generate them first with /skill architecture-compliance.

For each contract, read the Document Control table and extract:

• Score (from [VALIDATION_SCORE] or the populated score field)
• Document status (from | Status | row)
• Approval authority (from the Approval Authority field)
• Generation date (from **Generation Date**)

Display:

Available compliance contracts:

  1. SRE_ARCHITECTURE_Project_2026-03-25.md      SRE Architecture          7.69/10  In Review
  2. CLOUD_ARCHITECTURE_Project_2026-03-25.md    Cloud Architecture        8.50/10  Approved
  ...

Which contract(s) to export?
  Enter numbers (e.g. 1, 3), ranges (e.g. 1-3), or "all"

Step C.2 — Parse selection + derive slugs (orchestrator)

For each selected contract, derive domain_slug from the filename prefix (e.g., SRE_ARCHITECTURE → sre-architecture). Read the project name for project_slug.

Step C.3 — Spawn the sub-agent

Invoke sa-skills:generators:docs-export-generator with:

• job_type: compliance
• plugin_dir: <absolute path>
• project_dir: <CWD>
• project_slug: <kebab-case project name>
• items: <JSON array of {path, domain_slug, score, document_status, approval_authority} objects>

Step C.4 — Report (orchestrator)

✅ Compliance Export Complete

   exports/CC-sre-architecture-project.docx       (SRE Architecture — 7.69/10 In Review)
   exports/CC-cloud-architecture-project.docx     (Cloud Architecture — 8.50/10 Approved)

📝 The Questions & Gaps Register in each document has yellow-highlighted cells (Owner, Action Required, Priority)
   ready for stakeholder review and editing in Microsoft Word.

---

Workflow D — Export Security Posture

Trigger phrases: "export security posture", "export security posture validation", "export security checklist to Word"

The input is a Security Posture validation report (analysis/SECURITY-POSTURE-<date>.md) produced by /skill architecture-analysis (analysis 12 — the consolidation of STRIDE + Data Sensitivity). This export is a pure verbatim render: docgen renders the checklist with editable Status / Owner / Evidence cells for the validating reviewer.

Step D.1 — List available Security Posture reports (orchestrator)

Glob analysis/SECURITY-POSTURE-*.md. If none found:

❌ No Security Posture report found in analysis/.
   Generate one first: /skill architecture-analysis  →  select 12 (Security Posture).

If multiple dates exist, display them numbered (most recent first) and let the user choose; default to the most recent if the user just says "export security posture":

Available Security Posture reports:

  1. SECURITY-POSTURE-2026-06-03.md      (most recent)
  2. SECURITY-POSTURE-2026-05-01.md

Which to export? (number, or "latest")

Step D.2 — Determine solution slug (orchestrator)

If docs/01-system-overview.md exists, read its H1 and kebab-case it for solution_name_slug. Otherwise omit it (the sub-agent falls back to SECURITY-POSTURE.docx).

Step D.3 — Spawn the sub-agent

Invoke sa-skills:generators:docs-export-generator with:

• job_type: security-posture
• plugin_dir: <absolute path from Step 0>
• project_dir: <CWD>
• solution_name_slug: <from Step D.2, if available>
• items: <JSON array of absolute paths to the selected SECURITY-POSTURE-<date>.md file(s)>

Step D.4 — Report (orchestrator)

✅ Security Posture Export Complete

   exports/SECURITY-POSTURE-<solution-name>.docx

📝 The Status, Owner, and Evidence columns are yellow-highlighted, ready for the validating
   reviewer to mark each control Pass / Fail / N/A in Microsoft Word.

---

Document Styling

Document	Type Code	Color	Purpose
Executive Summary	SA	Corporate blue #1F4E79	Architecture overview deliverable
ADR-*.md	ADR	Amber/Gold #8B6914	Architecture decisions
Component handoffs	HANDOFF	Teal #0D7377	Dev team deliverables
Compliance contracts	CC	Purple #7B2D8E	Compliance adherence contracts with editable Questions & Gaps Register
Security Posture	SP	Crimson #9C1F2E	Consolidated security control checklist with editable Status / Owner / Evidence cells

Security Posture exports' checklist tables have:

• Yellow-highlighted cells for Status, Owner, and Evidence (editable in Word)
• Severity/Tier-conditional coloring on the Sev / Tier column (High/Critical/S1=red, Medium/S2=amber, Low=green)

Compliance exports' Questions & Gaps Register has:

• Yellow-highlighted cells for Owner, Action Required, and Priority (editable in Word)
• Status-conditional coloring in the Compliance Summary table: green=Compliant, red=Non-Compliant, gray=Not Applicable, yellow=Unknown

---

Output Location

All exports land in exports/ at the project root.

exports/
├── SA-payment-gateway.docx              ← Executive Summary
├── ADR-001-api-gateway-choice.docx      ← Individual ADR
├── ADR-002-database-selection.docx      ← Individual ADR
├── HANDOFF-payment-api.docx
├── HANDOFF-user-service.docx
├── CC-sre-architecture-project.docx     ← Compliance Contract (Questions & Gaps editable)
├── CC-cloud-architecture-project.docx
└── SECURITY-POSTURE-payment-gateway.docx ← Security Posture checklist (Status/Owner/Evidence editable)

---

Dependency Check

If you see a Cannot find module 'docx' error from the sub-agent's report:

cd tools/docgen && bun install

Only needed once per plugin install.

---

Prerequisites

• docs/01-system-overview.md and docs/components/README.md created by /skill architecture-docs
• ADR files created by /skill architecture-definition-record
• Compliance manifest created by /skill architecture-compliance (optional for Workflow A; required for Workflow C)
• Component handoffs created by /skill architecture-dev-handoff (required for Workflow B)
• Security Posture report created by /skill architecture-analysis (analysis 12) (required for Workflow D)

---

Permissions required

Add to project .claude/settings.json:

"Bash(bun *)",
"Bash(mkdir *)",
"Bash(rm *)",
"Write(exports/*)",
"Read(exports/*)",
"Read(analysis/*)",
"Agent(sa-skills:generators:docs-export-generator)"

Read(analysis/*) is used by Workflow D to read the Security Posture report before export.

Bash(rm *) is used by the sub-agent to clean up the temporary sa-executive-summary.md.