Architecture Diagram

Generates an architecture SVG diagram by scanning the live project structure.

When to Use

• User asks to update / regenerate / sync the architecture diagram
• Skills, agents, or commands have changed
• First-time setup (diagram doesn't exist yet)

Execution

Step 1 — locate project root

Use the bash tool to find the project root (directory containing .agents/):

# From wherever the agent is currently working
pwd
ls .agents/ .opencode/ 2>/dev/null || echo "NOT_FOUND"

If .agents/ is not in the current directory, search upward or ask the user to confirm the project root before continuing.

Step 2 — run the generator script

Copy the script from the skill bundle into a temp location and run it from the project root:

python /path/to/skill/scripts/generate_diagram.py \
  --root . \
  --out docs/architecture.svg

The script auto-discovers:

• Skills → .agents/skills/*/SKILL.md (reads name: from frontmatter)
• Agents → */agents/*.md (uses filename stem)
• Commands → */commands/*.md (uses filename stem, strips leading /)

It writes a self-contained SVG to --out (default: docs/architecture.svg).

Step 3 — confirm and report

After the script exits:

1. Tell the user the output path
2. Report counts: N skills · M agents · K commands
3. If counts differ from the last known state, summarise what changed

Output

docs/architecture.svg — a standalone SVG output file, viewBox 680 × auto, compatible with GitHub README embedding (example: ![Architecture](docs/architecture.svg)).

Customisation

The script reads an optional docs/diagram-config.json if present:

{
  "title": "Project Architecture",
  "project_name": "My Project",
  "author": "maintainer",
  "pipeline_stages": [
    {"name": "build", "color": "teal"},
    {"name": "test", "color": "blue"},
    {"name": "deploy", "color": "green"}
  ]
}

All fields are optional — the script uses sensible defaults when the file is absent.

Bundled Scripts

• scripts/generate_diagram.py — Main generator script

See Also

• readme-best-practices — README and documentation best practices
• skill-creator — Create and improve skills

Rationalizations

Red Flags

• Committing architecture changes without regenerating the diagram
• Manually editing the SVG instead of using the generator script
• Ignoring diagram regeneration when adding/removing skills or agents

Voice & Context

• Default: professional + blog
• Reference: voice-profiles skill for definitions and auto-detection.