Skip to main content
Overview Intent Plan Build Test Review Document Deploy Monitor
01
Software Architect

Plan

Research first, plan second. Read-only always.

Read Search Glob Git log/diff Execute Write Git commit

Why this phase exists

The most common challenge in agentic development is agents that begin building before fully understanding the codebase. Without research, they hallucinate file paths, miss existing patterns, and create solutions that conflict with the architecture.

Plan exists to enforce a research-then-decide discipline. By making this phase strictly read-only, we guarantee the agent cannot modify anything while it is still forming its understanding.

It goes first because every downstream phase depends on a well-scoped spec. A bad plan cascades: Build creates the wrong thing, Test validates the wrong behavior, Review flags fundamental issues, and the whole workflow loops back.

Methodology

1

Receive input

If an intent artifact is available ($intent_artifact), use it as the primary source; it contains a pre-validated problem statement, issue type, acceptance criteria, and scope. If no intent artifact, parse the raw task description. Identify the issue type: feature, bug, task, or patch. Each type follows a different planning approach.

2

Route to issue-type template

Features need EARS user stories and architecture analysis. Bugs need root cause analysis. Tasks need scope boundaries. Patches need minimal-change analysis.

3

Research phase (parallel subagents)

Spawn 3 subagents simultaneously: Locator finds all relevant files and maps the dependency graph. Analyzer reads identified files to understand patterns and conventions. Pattern Finder searches for similar implementations in the codebase.

4

Synthesize findings

Main agent pulls subagent results together into a clear picture of the codebase and the changes needed.

5

Generate specification

Produce the structured plan with file:line references, change list, anti-scope-creep section, and test strategy.

6

Self-validate

Review the spec against the original task. Check completeness. Verify all referenced files exist. Confirm the plan addresses the full issue and nothing more.

Inputs and outputs

Inputs

  • • Intent specification (from Intent phase, if run), or
  • • Task description (from user or ticket system)
  • • Issue type: feature | bug | task | patch
  • • Branch name
  • • Codebase context (agentic layer config, project docs)

Source: Intent phase ($intent_artifact), or external (user, ticket system, or Monitor phase feedback)

Outputs

  • • Structured specification (Markdown)
  • • Summary, files to modify with line refs
  • • Files to create, "What we are NOT doing"
  • • Test strategy, acceptance criteria

Consumed by: Build phase as $plan_artifact

Plan output template 
# Plan: ${issue_title}

## Summary
[1-2 paragraph description of what will be built and why]

## Issue Type
${issue_type}  # feature | bug | task | patch

## Files to Modify
- `src/auth/login.ts:42-67` -- Refactor token validation logic
- `src/auth/types.ts:12` -- Add new TokenConfig interface

## Files to Create
- `src/auth/__tests__/login.test.ts` -- Unit tests for new validation
- `src/auth/token-config.ts` -- Configuration module

## What We Are NOT Doing
- Not refactoring the entire auth module
- Not changing the session management layer
- Not updating API contracts

## Test Strategy
- Unit tests for token validation edge cases
- Integration test for login flow with new config

## Acceptance Criteria
- [ ] Token validation handles expired tokens gracefully
- [ ] Existing tests continue to pass
- [ ] New tests cover all edge cases listed above

Agent pattern

Multi-Agent: Parallel Research Fan-Out
Main Planner Locator Analyzer Pattern Finder Plan Spec

Small tasks (patches, tiny bugs): single agent is sufficient. Skip the parallel fan-out.

Medium tasks (features, larger bugs): full 3-subagent pattern for thorough research.

Large tasks (multi-system features): add domain-specific subagents (e.g., "API Analyzer", "Database Analyzer").

Tool permissions

Read Search Glob Git log/diff Execute Write Git commit

The Plan phase is deliberately read-only. Allowing write access tempts the agent to "just fix this quick thing" while planning, which breaks the separation between thinking and doing.

Execute is denied because running tests or scripts could have side effects. The Planner does not need to run anything; it needs to understand the structure.

What "limited git" means: git log, git diff, git status, git show are allowed. git add, git commit, git push, git checkout are denied.

Prompt template

# Plan Phase -- Software Architect

## Role
You are a Software Architect. Your job is to research the
codebase and produce a detailed implementation plan.

You do NOT write code. You do NOT modify files. You are
read-only. Your output is a specification that a Software
Engineer will execute.

## Context
Intent: ${intent_artifact}              # from Intent phase (if run)
Issue: ${issue_description}             # raw description (fallback if no intent)
Type: ${issue_type}                     # feature | bug | task | patch
Branch: ${branch_name}
Repository: ${repo_name}
Agentic Layer Config: ${agentic_layer_path}

## Issue-Type Routing

### If feature:
- Write EARS-format user stories: "When [stimulus], the system shall [response]"
- Analyze architectural impact across modules
- Identify integration points with existing systems
- Propose test strategy: unit, integration, E2E

### If bug:
- Perform root cause analysis
- Trace the bug from symptom to source
- Identify minimal fix surface (fewest files touched)
- Check for similar bugs elsewhere in the codebase

### If task:
- Define clear scope boundaries
- Identify dependencies and ordering constraints
- List files affected with specific line ranges

### If patch:
- Identify exact lines to change
- Verify no side effects in adjacent code
- Minimal change only -- no refactoring

## Research Protocol
Before planning, you MUST complete these research steps:

1. Use Glob to find all files related to the task area
2. Read each relevant file to understand current patterns
3. Search for similar implementations in the codebase
4. Check existing test patterns for the affected modules
5. Review recent git history for the affected files

## Constraints
- Read-only. Do not modify any files.
- Research before planning. Never plan and execute simultaneously.
- Reference specific file:line locations for every change.
- Every file you reference MUST exist. Verify with Read.
- Do not add scope. If the issue says "fix login timeout",
  do not also refactor the auth module.

## Output Format
Produce a structured specification with these exact sections:

1. Summary -- What will change and why (2-3 sentences)
2. Files to Modify -- Each with file:line range and description
3. Files to Create -- Each with purpose and location
4. What We Are NOT Doing -- Explicit anti-scope-creep
5. Test Strategy -- What tests to write, what they validate
6. Acceptance Criteria -- Checkboxes, verifiable conditions
7. Risk Assessment -- What could go wrong, mitigation steps

## Quality Checks (Self-Validation)
Before submitting your plan, verify:
- [ ] Every referenced file exists (you read it)
- [ ] Line numbers are accurate (you checked them)
- [ ] The plan addresses the full issue, nothing more
- [ ] Test strategy covers happy path and edge cases
- [ ] "What we are NOT doing" section is present and specific
Role Assignment Template Variables Issue-Type Routing Anti-Scope-Creep Self-Validation

Best practices

Do

  • Read every file you reference before citing it
  • Include line numbers for every modification target
  • Write an explicit anti-scope-creep section
  • Route different issue types to different planning approaches
  • Validate that your plan addresses the complete issue

Don't

  • Modify any files during planning
  • Plan and build in the same agent invocation
  • Reference files you have not read
  • Expand scope beyond the original issue
  • Skip the research phase for "simple" tasks

Nuances

EARS user stories for features

Use the Easy Approach to Requirements Syntax. Format: "When [stimulus], the system shall [response]." This gives Build agents testable, unambiguous acceptance criteria.

Root-cause analysis for bugs

Do not stop at the symptom. Trace the call chain from where the bug manifests to where the defect originates. The plan should target the root, not the symptom.

Plan validation by a second agent

In multi-agent setups, a second agent can review the plan before it goes to Build. This catches hallucinated file paths, unrealistic scope, and gaps in the test strategy.

Context-window management

For large codebases, the Planner should not try to read everything. The parallel subagent pattern (Locator, Analyzer, Pattern Finder) distributes the reading load across separate context windows.

Issue-type templates are extensible

The four types (feature, bug, task, patch) are defaults. Teams can add custom types (e.g., "refactor", "security-fix", "performance") with their own planning templates.

When Intent improves Plan output

When input quality varies (vague tickets, cross-team requests, monitor-generated issues), running the Intent phase before Plan dramatically reduces planning failures. Intent provides pre-validated acceptance criteria, explicit scope boundaries, and codebase context that Plan would otherwise have to discover on its own. When input is consistently well-defined, Intent can be skipped without loss. See Intent Phase.