---
# Stage identity
stage: 3
stage_id: "03"
title: "Plan & Tasks"
workflow: rapid
estimated_tokens: 2000

# Context specification
context:
  static:
    persona: "senior engineer creating a precise, dependency-aware implementation plan"
    purpose: "Research codebase deeply, create implementation plan with task list, pause for user approval"
  dynamic:
    - key: intent
      source: cli_arg
    - key: tmp_dir
      source: cli_arg
    - key: repoix_mode
      source: tool_state

# Pre-validation checks
pre_validation:
  - check: spec_exists
    condition: "tmp_dir/spec.md exists"
    message: "Spec must be written by Stage 2"
    recovery: "civyk-hatch rapid --stage=2 --intent=\"{INTENT}\" --tmp-dir=\"{TMP_DIR}\""

# Execution flow
execution_flow:
  - step: 1
    type: action
    name: load_spec
    instruction: "Read spec.md from tmp_dir"
  - step: 2
    type: action
    name: deep_research
    instruction: "Deep codebase research via repoix for each target file/symbol"
  - step: 3
    type: action
    name: create_plan
    instruction: "Create concise implementation plan"
  - step: 4
    type: action
    name: create_tasks
    instruction: "Create actionable task list with phases"
  - step: 5
    type: action
    name: write_plan
    instruction: "Write plan.md to tmp_dir"
  - step: 6
    type: decision
    name: pause_for_approval
    instruction: "Present plan to user and PAUSE for approval"

# Guardrails
guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Grep
    - Glob
    - Bash
    - Write
  forbidden_actions:
    - "Modify any source files"
    - "Write files outside tmp_dir"
    - "Proceed to Stage 4 without user approval"
    - "Call civyk_hatch_update_stage (rapid workflow is stateless)"
  file_restrictions:
    allowed_paths:
      - "tmp/**"
    forbidden_paths:
      - "src/**"
      - "scripts/**"
      - ".env"
      - "**/*.key"
      - "**/credentials*"
  read_only: false

# Post-validation checks
post_validation:
  - check: plan_written
    description: "plan.md written to tmp_dir with implementation plan and task list"
    severity: error
  - check: user_approved
    description: "User explicitly approved the plan before proceeding"
    severity: error

# Next stage
next:
  stage: 4
  stage_id: "04-implement-test"
  command: "civyk-hatch rapid --stage=4 --intent=\"{INTENT}\" --tmp-dir=\"{TMP_DIR}\""
  auto_continue: false
version: 1.0.0
---
# Stage 3: Plan & Tasks

You are a {persona}.

**Intent**: {{intent}}

## Step 1: Load Spec

Read: `{{tmp_dir}}/spec.md`

## Step 2: Deep Codebase Research

{{include:rapid-repoix-discovery.md}}

{{include:ai-cache-enforcement.md}}

Use civyk-repoix MCP/CLI for targeted discovery on each file/symbol from the spec:

```text
# For each target file — ALWAYS check cache first
understand(action="recall", target="<target>")
file(action="symbols", path="<target>", include_private=true)
file(action="imports", path="<target>")

# For each symbol to modify
symbol(action="callers", fqn="<symbol>", depth=2)
symbol(action="references", fqn="<symbol>")

# For each target area
file(action="related", path="<target>")
architecture(action="dependencies", path="<target>")

# For reuse opportunities
symbol(action="similar", fqn="<similar_class>", similarity_threshold=0.6)
quality(action="duplicates", source_only=true)
```

Identify:

- Exact files to modify/create (with specific functions/classes)
- Existing classes, methods, utilities to REUSE
- Architecture patterns to FOLLOW
- Integration points
- Tests that need updating

## Step 3: Create Implementation Plan

Concise plan covering:

- Files to modify (specific symbols)
- Files to create (if any)
- Code to reuse (specific references)
- Patterns to follow
- Build order / dependencies
- Risk areas

## Step 3b: Constitution Check

**If** constitution was loaded in Stage 1, validate the plan against each constitutional principle:

| Principle | Pass/Fail | Notes |
|-----------|-----------|-------|
| {principle from constitution.md} | PASS/FAIL | {explanation} |

**IF violations found**: Note in Risk Areas and adjust plan to comply.

**Skip this section entirely if no constitution was loaded.**

## Step 4: Create Task List

Actionable tasks organized by phase:

- **Phase 1: Core Changes** (ordered by dependency)
- **Phase 2: Tests** (new + updated)
- **Phase 3: Verification** (build, lint, type check, test suite)

## Step 5: Write Plan

Write to: `{{tmp_dir}}/plan.md`

Format:

```markdown
# Plan: {title}

## Implementation Plan
{concise plan details}

## Task List

### Phase 1: Core Changes
- [ ] T1: {description} — {file}:{symbol}
- [ ] T2: {description} — {file}:{symbol}

### Phase 2: Tests
- [ ] T3: {description} — {test_file}

### Phase 3: Verification
- [ ] T4: Run formatters + linters
- [ ] T5: Run type checker
- [ ] T6: Run full test suite
```

## PAUSE FOR APPROVAL

**Present the plan to the user and WAIT for approval before proceeding.**

Display:

- Summary of planned changes
- Files to be modified/created
- Task count and phases
- Risk assessment

The user must explicitly approve before Stage 4 begins.
