pm-architect-brownfield

Analyze architecture gaps and risks in the existing codebase

Run the full brownfield architecture review pipeline on an existing codebase

Design target architecture that addresses identified gaps and risks

Discover and model the existing codebase architecture with evidence-backed analysis

Generate refactor task backlog, roadmap, and RFC list from migration plan

Create a phased migration plan with rollback strategy and validation gates

Extract actual features and capabilities from an existing codebase into a reverse PRD

Create a review brief and alignment matrix for an architecture review

Use this agent when the user asks to "run a full architecture review", "conduct a brownfield assessment", "analyze this legacy codebase end-to-end", or needs a complete orchestrated review pipeline that produces a unified handoff bundle from an existing codebase. <example> User: Run a full architecture review on this codebase Use: Yes — this is a complete brownfield review requiring orchestration of all specialist agents <commentary>The lead orchestrates the full pipeline: discovery, reverse-PRD, gap analysis, target architecture, migration planning, and backlog generation. It delegates each phase to the appropriate specialist agent and collects artifacts into handoff_bundle.json.</commentary> </example> <example> User: Just discover the codebase components and build the system model Use: No — this is a single-phase discovery task, route to codebase-cartographer <commentary>The lead orchestrates multi-phase pipelines. Single-phase work belongs to the specialist who owns that phase. Discovery is owned by codebase-cartographer.</commentary> </example>

Use this agent when the user asks to "generate the refactor backlog", "create the task list", "build the project roadmap", "produce the RFC list", "break down the migration into tasks", or needs actionable refactor tasks, a prioritized roadmap, and RFC documents derived from the target architecture and migration plan. <example> User: Generate the refactor backlog and roadmap from the migration plan Use: Yes — this is a backlog generation task requiring task breakdown, roadmap, and RFC production <commentary>The backlog-planner takes the target architecture and migration plan as input and produces three artifacts: REFACTOR_TASKS.md with individual tasks, ROADMAP.md with a prioritized timeline, and RFC_LIST.md with request-for-comment documents for major changes.</commentary> </example> <example> User: Plan the migration phases and rollback strategy Use: No — migration phase planning is owned by migration-planner <commentary>The backlog-planner breaks phases into tasks. Defining the phases themselves, their sequencing, validation gates, and rollback strategies belongs to migration-planner.</commentary> </example>

Use this agent when the user asks to "map out the existing codebase", "discover the system architecture", "build the AS-IS model", "explore the codebase structure", or needs a comprehensive inventory of components, dependencies, and patterns in an existing codebase. <example> User: Map out the existing codebase architecture Use: Yes — this is a codebase discovery and system model construction task <commentary>The cartographer explores the codebase systematically, identifying components, dependencies, data flows, and architectural patterns to produce the AS_IS_SYSTEM_MODEL.md with file:line evidence for every claim.</commentary> </example> <example> User: Identify the architecture gaps in this codebase Use: No — gap identification requires an existing system model and is owned by gap-and-risk-analyst <commentary>The cartographer discovers what IS. Analyzing what is MISSING or WRONG is gap analysis, which belongs to gap-and-risk-analyst. The cartographer's system model is a prerequisite for gap analysis.</commentary> </example>

Use this agent when the user asks to "identify architecture gaps", "find risks in the codebase", "assess technical debt", "analyze what's missing or broken", or needs a structured gap analysis with prioritized risk assessment (P0/P1/P2) for an existing brownfield codebase. <example> User: Identify the architecture gaps and risks in this codebase Use: Yes — this is a gap identification and risk assessment task requiring structured GAP-NNNN and RISK-NNNN output <commentary>The gap-and-risk-analyst compares the AS-IS system model and reverse PRD against architectural best practices, identifying deficiencies (GAP-NNNN) and assessing their risks (RISK-NNNN) with P0/P1/P2 priority levels.</commentary> </example> <example> User: Design the target architecture to fix these problems Use: No — designing solutions is owned by target-architect <commentary>The gap-and-risk-analyst identifies WHAT is wrong and HOW risky it is. Designing the solution is target-architect's responsibility. The analyst's gap report is a prerequisite for target architecture design.</commentary> </example>

Use this agent when the user asks to "plan the migration strategy", "create migration phases", "design the rollback strategy", "build the migration plan", or needs a phased migration plan with validation gates and rollback procedures to move from AS-IS to TO-BE architecture. <example> User: Plan the migration strategy with phases and rollback gates Use: Yes — this is a migration planning task requiring phased execution strategy with validation gates <commentary>The migration-planner takes the gap analysis and target architecture as input and produces a phased MIGRATION_PLAN.md with execution order, rollback strategies, validation gates, and risk mitigation for each phase.</commentary> </example> <example> User: Generate the refactor task list and project roadmap Use: No — task generation and roadmap production are owned by backlog-planner <commentary>The migration-planner designs the phase structure and sequencing. Breaking phases into individual tasks, estimating effort, and producing a roadmap is backlog-planner's responsibility.</commentary> </example>

Use this agent when the user asks to "extract what this system actually does", "reverse-engineer the PRD", "document the actual features", "build a feature inventory from code", or needs a comprehensive product requirements document derived from existing code behavior rather than original specifications. <example> User: Extract what this system actually does and document its features Use: Yes — this is a reverse PRD extraction task requiring feature discovery from code evidence <commentary>The reverse-prd-analyst reads the codebase (informed by the cartographer's system model) and extracts actual implemented features, user-facing behaviors, business rules, and integration points into a structured REVERSE_PRD.md.</commentary> </example> <example> User: Build the system model first so we understand the architecture Use: No — system model construction is owned by codebase-cartographer <commentary>The reverse-prd-analyst depends on the cartographer's system model as input. It extracts features from code, not architectural structure. Route to codebase-cartographer for system model construction.</commentary> </example>

Use this agent when the user asks to "design the target architecture", "propose the TO-BE state", "architect the solution", "create the target state design", or needs a comprehensive target architecture document that addresses all identified gaps and risks from a brownfield assessment. <example> User: Design the target architecture for this codebase Use: Yes — this is a target architecture design task requiring gap resolution mappings and architectural decisions <commentary>The target-architect takes the gap analysis as input and designs a TO_BE_ARCHITECTURE.md that addresses every GAP-NNNN with specific architectural decisions, component redesigns, and technology selections.</commentary> </example> <example> User: Plan the migration phases to get from current to target state Use: No — migration planning is owned by migration-planner <commentary>The target-architect designs WHERE we want to go. The migration-planner designs HOW we get there. Planning phases, rollback strategies, and validation gates belong to migration-planner.</commentary> </example>

This skill should be used when the user asks to "find architecture gaps", "assess technical debt", "identify risks in the codebase", "evaluate code quality", "audit the architecture", or needs to produce a prioritized inventory of gaps, risks, and technical debt in a brownfield codebase based on evidence from prior discovery artifacts.

This skill should be used when the user asks to "discover the current architecture", "map the existing system", "document the as-is state", "inventory the codebase", "trace dependencies", or needs to produce a comprehensive model of an existing brownfield codebase from actual code evidence rather than documentation claims.

This skill should be used when the user asks to "plan the migration", "create a migration strategy", "design the transition plan", "define migration phases", "plan rollback strategy", or needs to produce a phased migration plan with validation gates and rollback triggers for transitioning a brownfield codebase from its current state to the target architecture.

This skill should be used when the user asks to "generate refactor tasks", "create a migration backlog", "build a roadmap", "create architecture decision records", "generate RFCs", "plan the refactoring work", or needs to produce actionable task lists, milestone-based roadmaps, and architecture decision records from a migration plan.

This skill should be used when the user asks to "reverse engineer requirements", "extract what the system actually does", "build a PRD from code", "document existing features", "trace user flows from code", or needs to understand the actual behavior of a brownfield codebase by analyzing code rather than trusting documentation.

This skill should be used when the user asks to "scope an architecture review", "define review goals", "create a review brief", "align review goals with codebase", or needs to establish the scope and goals of a brownfield codebase review before analysis begins.

This skill should be used when the user asks to "design the target architecture", "propose the to-be state", "create an architecture proposal", "plan the future architecture", "define the end-state system", or needs to produce a target architecture that addresses identified gaps and risks from a brownfield codebase analysis.

1 hook across 1 event