Plan Architecture
"Architecture is the art of making decisions you will not regret when the plugin grows."
Generate a complete architecture plan for a Claude Code plugin. Takes a plugin concept brief (from ideate-plugin) and produces a detailed technical plan covering agents, skills, hooks, commands, quality gates, and execution flows. [EXPLICIT]
Procedure
Step 1 -- Parse Plugin Brief
- Read the plugin brief document at the provided path.
- Extract: problem statement, movement structure, component estimates, feasibility notes.
- If no brief exists at the path, report the error and suggest running
/pqa:ideate first.
- Validate that the brief has the required sections. Tag findings:
[DOC].
Step 2 -- Determine Agent Roles
- For each movement, decide whether it needs a dedicated agent or shares the plugin's primary agent.
- Apply the heuristic: a movement gets its own agent if it has 5+ skills OR fundamentally different tool needs.
- For each agent, define:
- Name: kebab-case, role-descriptive (e.g.,
code-analyzer, report-generator). [EXPLICIT]
- Boundary: What it owns and what it delegates. [EXPLICIT]
- Tool allowlist: Minimum tools needed (least privilege). [EXPLICIT]
- maxTurns: Estimated based on skill count and complexity. [EXPLICIT]
- Record the plugin subagent constraint: no hooks, mcpServers, or permissionMode in agent frontmatter.
[CONFIG]
Step 3 -- Map Skills to Movements
- For each movement from the brief, list the skills with:
- Name: kebab-case verb-noun (e.g.,
validate-structure, generate-report). [EXPLICIT]
- Purpose: One sentence. [EXPLICIT]
- Inputs: What data/files it reads. [EXPLICIT]
- Outputs: What it produces (findings, artifacts, reports). [EXPLICIT]
- Agent: Which agent orchestrates it. [EXPLICIT]
- Sequence: Order within the movement (parallel or sequential). [EXPLICIT]
- Verify no skill appears in multiple movements.
[DOC]
Step 4 -- Select Hooks from Compatibility Matrix
- Review the 22 lifecycle events available in Claude Code.
- For each proposed hook from the brief, validate against the type-event compatibility matrix:
type:command -- compatible with all 22 events. [EXPLICIT]
type:http -- compatible with all 22 events. [EXPLICIT]
type:prompt -- compatible with PreToolUse, PostToolUse, and PermissionRequest ONLY (requires ToolUseContext). [EXPLICIT]
type:agent -- compatible with PreToolUse, PostToolUse, and PermissionRequest ONLY (requires ToolUseContext). [EXPLICIT]
- Flag any incompatible combinations as
CRITICAL (prompt/agent on non-ToolUseContext events) and propose alternatives.
- Document the hook strategy: which events, which types, what behavior.
[CONFIG]
Step 5 -- Define Command Routing
- For each user-facing operation, create a command entry:
- Canonical command: Full descriptive name (e.g.,
/prefix:validate). [EXPLICIT]
- Alias: Optional single-letter shortcut (e.g.,
/prefix:v). [EXPLICIT]
- Target: Which skill or agent the command invokes. [EXPLICIT]
- Arguments: What the command passes through. [EXPLICIT]
- Verify no command name conflicts with existing commands in the plugin ecosystem.
- Total commands = canonical + aliases. Document the count.
[DOC]
Step 6 -- Place Quality Gates
- Define quality gates between movements:
- Gate name: Descriptive (e.g.,
G1: Analysis Complete). [EXPLICIT]
- Trigger: What must be true to pass (e.g., "all validate-* skills pass with zero CRITICALs"). [EXPLICIT]
- Blocker behavior: What happens if the gate fails (pause, skip, abort). [EXPLICIT]
- Minimum: one gate between each movement boundary.
- Gate criteria must be testable and evidence-based.
[DOC]
Step 7 -- Generate Architecture Diagrams
- Produce Mermaid diagrams for:
- Component map: Agents, skills, commands, hooks and their relationships. [EXPLICIT]
- Execution flow: Sequential/parallel skill execution within each movement. [EXPLICIT]
- Delegation graph: Agent-to-skill ownership. [EXPLICIT]
- Diagrams must be valid Mermaid syntax.
[CODIGO]
Step 8 -- Write Architecture Plan
Quality Criteria
Assumptions & Limits
- This skill produces a plan document, not code. It does not create directories, files, or scaffolds -- that is
build-plugin-scaffold's job.
- The hook compatibility matrix is taken as authoritative. If the official Claude Code spec changes, this skill's Step 4 must be updated to match.
- Agent count heuristic (5+ skills = dedicated agent) is a guideline, not a rule. Simple plugins may work fine with a single agent regardless of skill count.
- Cannot validate that the proposed architecture is optimal -- only that it is internally consistent and spec-compliant.
- Mermaid diagram generation assumes the user's rendering environment supports Mermaid syntax. No fallback for environments that do not.
Good vs Bad
Bad architecture plan excerpt:
## Agents
- Agent 1: handles stuff
- Agent 2: handles other stuff
Missing: no tool allowlist, no boundaries, no maxTurns, no skill assignments. [EXPLICIT]
Good architecture plan excerpt:
## Agent Roles
| Agent | Boundary | Skills Owned | Tools | maxTurns |
|-------|----------|-------------|-------|----------|
| code-analyzer | Owns validation movement. Reads only. | validate-structure, validate-manifest, validate-components | Read, Glob, Grep | 25 |
| report-generator | Owns reporting movement. Writes report files. | generate-qa-report, generate-qa-scorecard | Read, Glob, Write | 15 |
Includes: agent name, boundary, skills owned, tool allowlist, maxTurns estimate. [EXPLICIT]
Anti-Patterns
- Creating one agent per skill -- agents should manage groups of related skills. [EXPLICIT]
- Using
type:prompt hooks on Stop or Compact events (runtime error). [EXPLICIT]
- Defining quality gates without measurable criteria ("it looks good" is not a gate). [EXPLICIT]
- Creating aliases for commands that are rarely used (aliases are for frequent operations). [EXPLICIT]
- Putting all skills in a single movement (defeats the purpose of movement-based organization). [EXPLICIT]
Edge Cases
- Plugin with a single movement -- valid for simple plugins. Skip quality gates between movements but add an exit gate. [EXPLICIT]
- Plugin with no hooks -- valid. Many plugins operate entirely on-demand. Document the decision. [EXPLICIT]
- Brief proposes more than 4 agents -- review whether some can be merged. More than 4 agents is a code smell for plugins. [EXPLICIT]
- A skill needs Write access but the movement is labeled "read-only" -- resolve the contradiction before proceeding. [EXPLICIT]
Usage
Example invocations:
- "/plan-architecture" — Run the full plan architecture workflow
- "plan architecture on this project" — Apply to current context