# Corvus Phase 2

> Planning (Phase 2), User Approval (Phase 3), and optional High Accuracy Plan Review (Phase 3.5) Use when this capability is needed.

- Skill: `tomevault-io/corvus-phase-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/corvus-phase-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/corvus-phase-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/corvus-phase-2

---


## Phase 2: PLANNING (MANDATORY)

**Goal**: Create comprehensive master plan with task files.

### Step 1: Ask Test Preference (MANDATORY)

<critical_rule priority="9999">
BEFORE invoking task-planner, you MUST call the `question()` tool to ask the user
about test preference. Do NOT skip this step. Do NOT assume a default.
This is the FIRST thing you do when this skill is loaded.
</critical_rule>

Invoke the `question()` tool with these exact parameters:

- question: "Should I generate and run tests for this feature?"
- options:
  1. label: "Yes (recommended)", description: "Generate test tasks and run tests at every quality gate"
  2. label: "Yes — at end only", description: "Generate test tasks but defer testing to Phase 5 final validation. Phase 4 quality gates use acceptance-only mode"
  3. label: "No — skip tests", description: "Skip test generation entirely, quality gates always use acceptance-only mode"

Store the result as two flags:
- "Yes (recommended)": `tests_enabled: true, tests_deferred: false`
- "Yes — at end only": `tests_enabled: true, tests_deferred: true`
- "No — skip tests": `tests_enabled: false, tests_deferred: false`

Pass both flags to task-planner via the `**TEST PREFERENCE**` field in the delegation template below.

### Step 2: Create Master Plan

<mandatory>
This phase is NOT optional. You MUST invoke the task-planner subagent to create:
1. `.corvus/tasks/[feature-name]/MASTER_PLAN.md` - The execution tracking document
2. Individual task files with detailed implementation steps

DO NOT:
- Summarize findings and ask "should I proceed?"
- Ask the user to approve a verbal/informal plan
- Skip to implementation discussions
- Present your own plan without invoking task-planner

INSTEAD:
- Immediately invoke task-planner after Phase 1 completes
- Wait for task-planner to create the actual files
- Only then proceed to Phase 3 to present the created plan for approval
</mandatory>

Invoke **task-planner** with combined context from Phase 1:

```markdown
**TASK**: Create master plan for [feature description]

**PLAN_TYPE**: [LIGHTWEIGHT / STANDARD / SPEC_DRIVEN]
(Selected by user in Plan-Type Selection step)

**EXPECTED OUTCOME**:
- Master plan document at `.corvus/tasks/[feature-name]/MASTER_PLAN.md`
- Individual task files at `.corvus/tasks/[feature-name]/NN-task-name.md`
[If SPEC_DRIVEN: - Spec files at `.corvus/tasks/[feature-name]/specs/*.md`]

**USER REQUIREMENTS (IMMUTABLE)**:
[Paste the "User Requirements (Immutable)" section from requirements-analyst output]
⚠️ These MUST be incorporated into MASTER_PLAN.md and all relevant task files.
⚠️ Do NOT substitute with alternatives unless user explicitly approves.

**PLAN-TYPE CONTEXT**:
- If LIGHTWEIGHT: Generate simplified plan — 1 phase, 3-6 tasks, simplified templates
- If STANDARD: Generate full plan — current behavior, no changes
- If SPEC_DRIVEN: Generate full plan with mandatory specs layer — formal specs before task files, SHALL/MUST language, Given/When/Then acceptance criteria

**TEST PREFERENCE**: `tests_enabled: [true/false], tests_deferred: [true/false]` (from Corvus question() tool — see "Test Preference" step)
- When `tests_enabled: true, tests_deferred: false`: Generate test tasks, include test sections in task files (default behavior)
- When `tests_enabled: true, tests_deferred: true`: Generate test tasks and include test sections, but Phase 4 quality gates run in acceptance-only mode. Tests are deferred to Phase 5 final validation.
- When `tests_enabled: false`: Do NOT generate test tasks, omit test sections from task files

**CONTEXT FROM RESEARCH**:
[Paste summary of researcher findings, or "N/A - no external research needed"]

**CONTEXT FROM CODE EXPLORATION**:
[Paste summary of code-explorer findings]
- Files to modify: [list]
- Patterns to follow: [list]
- Risks identified: [list]

**PROJECT ENVIRONMENT**:
[Paste environment details from code-explorer]
- Virtual environment: [path, e.g., .venv/, venv/]
- Package manager: [npm/pnpm/yarn/pip/poetry]
- Available scripts: [list from package.json or Makefile]
- Command prefix: [e.g., ".venv/bin/python" or "pnpm"]

**MUST DO**:
- Create MASTER_PLAN.md with phases, dependencies, and progress tracking
- Create individual task files with detailed steps and acceptance criteria
- Include validation commands for each task using correct environment (venv, package manager)
- Estimate effort for each task and phase
- Group related tasks into logical phases
- Respect `tests_enabled` flag: generate test tasks only when `true` (regardless of `tests_deferred` — deferred mode still generates test tasks)

**MUST NOT DO**:
- Skip the master plan document
- Create tasks without acceptance criteria
- Create tasks without validation commands
- Use generic commands (python, pytest, npm) - always use project environment

**REPORT BACK**:
- Path to master plan document
- List of task files created
- Total estimated effort
- Recommended execution order
- Any concerns or risks
```

### Plan-Type-Specific Guidance

#### LIGHTWEIGHT Plans
- task-planner generates a simplified MASTER_PLAN.md (1 phase, no specs section)
- 3-6 tasks maximum
- Simplified task file templates
- Skip Phase 5 (Final Validation) — phase-level 4b is sufficient
- Skip Phase 3.5 (High Accuracy Review) — keep it fast

#### STANDARD Plans
- Current behavior — no changes to existing templates or workflow
- Full MASTER_PLAN.md with all sections
- Multi-phase structure with phase test tasks

#### SPEC_DRIVEN Plans
- task-planner creates `specs/` directory with formal specifications FIRST
- Specs use SHALL/MUST/SHOULD/MAY language (RFC 2119)
- Acceptance criteria in task files use Given/When/Then format
- Specs are presented alongside MASTER_PLAN.md in Phase 3 for approval
- Higher test coverage expectations

**Exit Criteria**: Master plan document exists with all task files created.

---

## Phase 3: USER APPROVAL

**Goal**: Get user approval for the MASTER_PLAN.md created in Phase 2.

**Prerequisites** (verify before proceeding):
- [ ] Phase 2 is complete
- [ ] `.corvus/tasks/[feature]/MASTER_PLAN.md` file exists
- [ ] Individual task files exist in `.corvus/tasks/[feature]/`

If prerequisites are NOT met, go back to Phase 2 and invoke task-planner.

Present the created plan to the user in this format:

```markdown
## Implementation Plan Ready

**Feature**: [Name]
**Total Tasks**: [N] tasks across [M] phases
**Estimated Effort**: [X hours/days]

### Phases

| Phase | Name | Tasks | Effort | Description |
|-------|------|-------|--------|-------------|
| 1 | [Name] | [N] | [effort] | [Brief description] |
| 2 | [Name] | [N] | [effort] | [Brief description] |

### Key Changes

**Files to Modify**:
- `[file1]` - [what changes]
- `[file2]` - [what changes]

**Files to Create**:
- `[file1]` - [purpose]

### Risks & Mitigations
- [Risk 1] - [Mitigation]
- [Risk 2] - [Mitigation]

### Master Plan Location
`.corvus/tasks/[feature-name]/MASTER_PLAN.md`

```

<critical_rule priority="9999">
AFTER presenting the plan summary above, you MUST call the question tool. 
Do NOT write the options as text. Do NOT ask the user to type a response.
You MUST invoke the question tool directly with these exact parameters:

- question: "Ready to proceed with this plan?"
- header: "Implementation Plan"
- options:
  1. label: "Start Implementation", description: "Approve the plan and begin Phase 4 immediately"
  2. label: "High Accuracy Review", description: "Approve the plan and run plan-reviewer to validate it first"
  3. label: "Request Changes", description: "Go back to planning with feedback"
</critical_rule>

**Decision Point** (based on user's selection):
- "Start Implementation" → Proceed to Phase 4
- "High Accuracy Review" → Proceed to Phase 3.5
- "Request Changes" → Return to Phase 2 with feedback

**Exit Criteria**: User selects an option via the question tool.

---

## Phase 3.5: HIGH ACCURACY PLAN REVIEW (Optional)

**Goal**: Validate plan quality before implementation begins.

**When**: User chose "High Accuracy Review" after Phase 3 approval.

**Prerequisites**: Phase 3 complete (user approved plan).

### Invoke plan-reviewer

**DELEGATE TO**: @plan-reviewer

```markdown
**TASK**: Review implementation plan for [feature name]

**MASTER PLAN**: `.corvus/tasks/[feature]/MASTER_PLAN.md`
**TASK FILES**: `.corvus/tasks/[feature]/*.md`

**TESTS_ENABLED**: [true/false] (from Phase 2 question() tool)
**TESTS_DEFERRED**: [true/false] (from Phase 2 question() tool)

**PROJECT ENVIRONMENT**:
[Paste environment details from code-explorer]
- Virtual environment: [path, e.g., .venv/, venv/, or "none"]
- Package manager: [npm/pnpm/yarn/pip/poetry or "none"]
- Available scripts: [list from package.json or Makefile, or "none"]
- Command prefix: [e.g., ".venv/bin/python" or "pnpm", or "none"]

**USER REQUIREMENTS**:
[Paste the "User Requirements (Immutable)" section from requirements-analyst output]

**MUST DO**:
- Run 3-pass review (Structural → Completeness & Reference → Adversarial)
- Verify ALL file paths via glob (not spot-check)
- Run weasel word detection via grep
- Check `tests_enabled` and `tests_deferred` compliance
- Verify user requirements traceability
- Detect cross-task file conflicts
- Provide evidence citations for every PASS sub-check
- Render binary OKAY/REJECT verdict

**MUST NOT DO**:
- Modify any files
- Suggest alternative approaches (unless current approach is broken)
- Reject for style preferences
- Cite more than 3 blocking issues
- Claim verification without showing glob/grep output

**REPORT BACK**:
- **PLAN REVIEW GATE STATUS**: OKAY / REJECT
- Sub-checklist results for all 4 criteria (with evidence)
- Weasel word scan results
- Cross-task file conflict table
- User requirements traceability table
- Blocking issues (if REJECT, max 3)
- Non-blocking notes (optional)
```

### Decision Point after Phase 3.5

**If OKAY**:
→ Present review results to user and ask for confirmation before proceeding.

Report the review summary to the user:
```markdown
## Plan Review: OKAY ✅

The plan passed high-accuracy review. All criteria met.

**Review Summary**:
[Paste plan-reviewer's summary of the 4 criteria here]

**Non-blocking Notes** (if any):
[Paste any non-blocking notes from plan-reviewer]
```

Then you MUST call the question tool (do NOT write the options as text):

- question: "Plan review passed. Ready to begin implementation?"
- header: "Review Complete"
- options:
  1. label: "Start Implementation", description: "Begin Phase 4 — the plan is validated"
  2. label: "Re-run Review", description: "Run the high accuracy review again"

**User chooses "Start Implementation"** → Proceed to Phase 4
**User chooses "Re-run Review"** → Phase 3.5 again

**If REJECT**:
1. Invoke task-planner with rejection feedback:
```markdown
**TASK**: Fix plan based on plan-reviewer feedback
**MODE**: LEARNING
**TRIGGER**: FAILURE_ANALYSIS

**REJECTION FEEDBACK**:
[Paste plan-reviewer's blocking issues here]

**MASTER PLAN**: `.corvus/tasks/[feature]/MASTER_PLAN.md`
**TASK FILES**: `.corvus/tasks/[feature]/*.md`

**MUST DO**:
- Address each blocking issue cited by plan-reviewer
- Update affected task files
- Update MASTER_PLAN.md if needed

**MUST NOT DO**:
- Change completed task statuses
- Rewrite the entire plan (targeted fixes only)
```

2. Present updated plan to user with choice using the `question()` tool:
```markdown
## Plan Updated After Review

The plan-reviewer found [N] blocking issue(s). Task-planner has addressed them:

### Issues Fixed
1. **[Issue title]**: [How it was fixed]
```

Then you MUST call the question tool (do NOT write the options as text):

- question: "Plan has been updated based on review feedback. How would you like to proceed?"
- header: "Next Step"
- options:
  1. label: "Re-run Review", description: "Run plan-reviewer again on the updated plan"
  2. label: "Start Implementation", description: "Begin Phase 4 with the current plan"

**User chooses "Re-run Review"** → Phase 3.5 again
**User chooses "Start Implementation"** → Phase 4

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/nachoflizaur) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->