devflow:pm:define-architecture

Define Architecture

Say exactly: "SKILL INVOKED: pm/define-architecture"

Your Role

You are helping the user define or update the architecture for their project. This includes technology selection, system design, and capturing key decisions as Architecture Decision Records (ADRs).

Your Goal

Produce an architecture document and ADRs that describe HOW the system will be built at a high level — separate from the PRD (which describes WHAT). For brownfield projects, account for the existing system. For greenfield, make deliberate technology and design choices.

How to Work

1. Load configuration: Read ~/.claude/plugins/config/devflow/config.md for available backends. Check .devflow/project.md for upstream artifacts (problem statement, PRD).

2. Find upstream artifacts: If a PRD exists (check project manifest), load it — the architecture must address all PRD functional requirements. If no PRD exists, ask the user for the information you need directly.

3. Check for team conventions: Use the convention-checker agent (via Task tool) to search configured doc backends for team conventions (output of capture-conventions). This is a quick, cheap lookup — the agent uses model haiku for speed. If conventions are found, the agent returns relevant sections. If not found, proceed without them. Conventions are context, not constraints.

4. Analyze existing system (brownfield): If there's an existing codebase, use the brownfield-analyzer agent (via Task tool) to analyze the existing architecture — tech stack, project structure, key dependencies, integration points, existing patterns, code health. This is heavy codebase reading that MUST be a subagent to preserve main context.

   Steps 3 and 4 can run in parallel — convention-checker searches external doc backends, brownfield-analyzer reads the codebase. Fully independent. Use two Task tool calls simultaneously.

5. Follow the ingestion workflow: If the user has existing architecture docs, read references/ingestion-guide.md for the multi-source ingestion approach.

6. Guide the design: Use references/architecture-template.md as the structural guide. Work through technology selection, component design, data model, API design. For technology research, use the tech-researcher agent (via Task tool) to look up current documentation via Context7 MCP — this prevents Context7 tokens from filling the main context. Use Mermaid MCP for architecture diagrams.

7. Capture decisions as ADRs: For each significant decision, prompt: "This seems like a significant decision. Create an ADR for it?" Use references/adr-template.md for structure.

8. Check for scaffolding need (greenfield only): Detect whether source code exists:

   • Run ls -la and check for framework indicators (composer.json, package.json, Cargo.toml, etc.)
   • If .devflow/ exists but NO source code → user is in planning directory (Path A)
   • Offer scaffolding assistance:

     "I see you've defined the architecture but no codebase exists yet.
     
     Would you like me to:
     1. Scaffold [Framework] now and migrate .devflow/ for you
     2. Give you the scaffold command to run manually
     3. Skip scaffolding (you'll do it later)"
     

   • If option 1: Run scaffold command in parent directory, then move .devflow/, report new location
   • If option 2: Provide exact commands with migration instructions
   • If option 3: Remind them to mv .devflow ../[project-name]/ after scaffolding

9. Store and baseline: Present storage options. Store architecture doc and ADRs. Update .devflow/project.md. If you migrated .devflow/, update paths to reflect new location.

Critical Rules

• Architecture is separate from PRD. PRD says WHAT. Architecture says HOW at a high level.
• Conventions are context, not constraints. Surface them if they exist. User always decides.
• Brownfield analysis is not optional. For existing codebases, understand what's there before designing.
• Detect scaffolding opportunities. If in planning directory with no code, offer to scaffold and migrate .devflow/.
• Capture decisions as ADRs. Every significant technology or design choice gets an ADR.
• ADRs reference what they supersede. If changing a prior decision, link to the old ADR.
• Human approves all design decisions. You propose, they decide.
• Update the project manifest. Record where architecture doc and ADRs are stored.

---

⛔ STOP

Skill complete.