Dev Workflow

Feature Development Skill

Enforce configurable 9-phase feature development workflow with phase validation, state management, and approval gates.

Configuration

Read from project's CLAUDE.md:

## Feature Development Workflow

**Phases:** 0,1,2,3,4,7
**TDD:** required
**FeatureDocsPath:** Documentation/Requirements/Feature

Note: Phases 0, 1, 2, 3, 4, 5, 8 are mandatory (auto-added if missing). Phases 6-7 require explicit approval.

9-Phase Workflow

Schema Source: schema/phases.txt (single source of truth for phase names, emojis, statuses)

*Phases 6-7 require explicit user approval before execution.

Phase 1 Sub-Phases (OpenSpec Artifacts)

Phase 1 delegates to OpenSpec skills (openspec-continue-change or openspec-ff-change).

How to Use

1. Load config from CLAUDE.md 2. Detect mode: context.md exists → resume, otherwise → start Phase 0 3. Phase 0 sequence (mandatory, in order): a. Create worktree — feature branch + worktree is ALWAYS the first step b. All subsequent work happens in the worktree — context.md, OpenSpec, code, everything c. Create context.md + OpenSpec init in the worktree d. Run `/openspec-explore` — design thinking before artifact generation e. Run `/brainstorm` (optional — only if available in current context) — structured brainstorming after explore 4. Execute phases 1-8 in configured sequence (all within worktree) 5. Validate completion before transitions 6. Get approvals at gates 7. Update context.md after every step

State Management

• Single file: {FeatureDocsPath}/doing/{feature-name}/context.md
• Skill updates: Status, Current Phase, Last Updated
• Hook updates: What's Been Completed, Next Todo
• After completion: Move to done/ directory

Schema

The schema file defines:

• Main phases (0-8) with names, emojis, descriptions
• Sub-phases for Phase 1 (1.1-1.4) with OpenSpec output files
• Valid status values (in_progress, complete, blocked, paused)

Both the skill templates and stop hook read from this schema.

References (6 files)

Templates

Note: Phase 1 uses OpenSpec's own artifact templates (via openspec instructions).

Critical Rules

1. Load configuration from CLAUDE.md first 2. Phases 0, 1, 2, 3, 4, 5, 8 are mandatory 3. Worktree is ALWAYS the first step — create feature branch + worktree before anything else 4. All work happens in the worktree — context.md, OpenSpec, implementation, everything 5. `/openspec-explore` before Phase 1 — design thinking is mandatory before artifact generation 6. Use ONLY context.md for state 7. Validate phase completion before transitions 8. Phase 1: Delegate to OpenSpec — openspec-continue-change per artifact → Get approval → Next (4 gates) 9. Update context.md header (Status, Current Phase, Last Updated) after every step 10. Never commit without explicit user approval 11. MANDATORY AGENT INVOCATION - See below

MANDATORY: Agent Invocation Protocol

YOU MUST FOLLOW THIS PROTOCOL FOR EVERY PHASE TRANSITION:

Step 1: Announce (REQUIRED)

Before starting any phase, announce which agents are required:

Phase {N} ({Name}) requires these agents:
- {agent-name}: {specific purpose for this feature}

Step 2: Confirm (REQUIRED)

Use AskUserQuestion to get explicit confirmation:

Options:
- "Invoke all agents" (Recommended)
- "Skip agents" (Must provide reason)

Step 3: Invoke (REQUIRED unless user skips)

Use Task tool with appropriate subagent_type for each approved agent.

Step 4: Report (REQUIRED)

After each agent completes, summarize key findings before proceeding.

Required Agents by Phase

Phase 4 domain detection (run git diff --name-only main...HEAD before announcing): Wave 0 runs first; Wave 1 agents run in parallel after Wave 0 completes. Announce only applicable agents based on changed directories.

NEVER Skip Silently

If you proceed without invoking required agents: 1. You are violating the workflow 2. User may miss important analysis 3. Quality may suffer

Always announce → confirm → invoke → report

Integration

Schema: Both skill and stop hook read from schema/phases.txt.

Stop hook: Updates "What's Been Completed" and "Next Todo" (supports OpenSpec artifacts with fallback).

Superpowers skills (Phase 0): using-git-worktrees (mandatory — always create worktree first) OpenSpec skills (Phase 0): opsx:explore (mandatory — design thinking before artifacts) OpenSpec skills (Phase 1): openspec-new-change, openspec-continue-change, openspec-ff-change OpenSpec skills (Phase 8): openspec-verify-change, openspec-archive-change, openspec-sync-specs Superpowers skills (Phase 3): test-driven-development, subagent-driven-development, executing-plans, dispatching-parallel-agents Superpowers skills (Phase 4-5): requesting-code-review, receiving-code-review CLAUDE.md management (Phase 7): claude-md-management:revise-claude-md, claude-code-setup:claude-automation-recommender Superpowers skills (Phase 8): verification-before-completion, finishing-a-development-branch

Related skills: mssql-dev for database work. Workflow docs: project workflow directory (e.g. .ai/workflows/implementation.md if present)

Code Review - {Feature Name}

Review Date: {YYYY-MM-DD} Phase: Phase 4 - Code Review (Multi-Agent) Overall Assessment: {READY/NOT READY to close Phase 4} (Grade: {Letter}, {Score}/100)

Domain Detection: git diff --name-only main...HEAD

---

Executive Summary

{Brief summary of findings across all agents, test results, and overall quality assessment}

Test Results: {X}/{Total} tests passing ({Percentage}%)

• Backend (NUnit): {X} tests — {Coverage}% coverage
• Frontend (Vitest): {X} tests — {Coverage}% coverage
• E2E (Playwright): {X}/{Total} scenarios

Build Status: {✓ Successful / ✗ Failed} ({Warnings} warnings, {Errors} errors)

---

Wave 0: Plan Compliance — code-reviewer

Scope: proposal.md / specs/\.spec.md / design.md vs actual implementation*

Deviations from plan:

• {List deviations, or "None — implementation matches spec ✓"}

Verdict: {PASS/FAIL} — {brief rationale}

---

Wave 1: Architecture — architect-reviewer

Scope: SOLID principles, layering, ADR-001–ADR-012, dependency injection

ADR Compliance:

SOLID / Layering:

• {✓/✗} Controller → Service → Repository pattern respected
• {✓/✗} No business logic in controllers
• {✓/✗} No direct DB access outside repository layer
• {✓/✗} Dependency injection via constructor (no service locator)

Issues: {List or "None"}

---

Wave 1: Security — backend-development:security-auditor

Scope: OWASP Top 10, auth flaws, injection, JWT/cookie security, input validation

Issues: {List blocking/non-blocking security issues, or "None"}

---

Wave 1: Performance — performance-engineer

Scope: N+1 queries, slow query patterns (e.g. missing query hints per project conventions), blocking async calls, expensive re-renders, index gaps (read-only analysis)

Database Performance:

• {✓/✗} All SELECTs use WITH(NOLOCK) where required
• {✓/✗} No N+1 query patterns (single query per logical operation)
• {✓/✗} Index coverage for new query predicates

Application Performance:

• {✓/✗} No blocking .Result / .Wait() calls on async code
• {✓/✗} No unnecessary re-renders on the frontend
• {✓/✗} Expensive operations not in hot paths

Issues: {List or "None — no performance concerns identified"}

Performance fixes are applied in Phase 5 (profiling + optimization). This section is analysis only.

---

Wave 1: Backend .NET — csharp-developer

Scope: .NET 8 patterns, Dapper, typed exceptions, async/await, nullable

Skip this section if no `{backend-dir}/` or `{backend-dir}.Tests/` changes.

Conventions:

• {✓/✗} Typed exceptions used (not generic Exception or ApplicationException)
• {✓/✗} Dapper query patterns correct (parameterized, no string interpolation)
• {✓/✗} Async/await properly propagated throughout call chain
• {✓/✗} Nullable reference types handled correctly

Issues: {List or "None"}

---

Wave 1: Database — database-optimizer

Scope: SP naming, WITH(NOLOCK), GUID validation, audit columns, @@ROWCOUNT

Skip this section if no `{database-dir}/` changes.

Issues: {List or "None"}

---

Wave 1: Frontend Vue/Nuxt — vue-expert

Scope: SSR safety, useFetch, composables, data-testid attributes, CSS custom props

Skip this section if no `{frontend-dir}/` changes.

SSR Safety:

• {✓/✗} No window/document access outside onMounted or <ClientOnly>
• {✓/✗} useFetch used for data fetching (not raw fetch)

Component Quality:

• {✓/✗} data-testid attributes on interactive elements
• {✓/✗} CSS custom properties used (no hardcoded hex colors in components)
• {✓/✗} ARIA landmarks and skip-to-content pattern followed (layouts/default.vue)

Issues: {List or "None"}

---

Wave 1: TypeScript Safety — typescript-pro

Scope: Strict mode, no implicit any, props/emits typing, composable return types

Skip this section if no `{frontend-dir}/` changes.

• {✓/✗} No any types (implicit or explicit)
• {✓/✗} Props defined with defineProps<T>() generic pattern
• {✓/✗} Emits defined with defineEmits<T>()
• {✓/✗} Composable return types explicitly typed (not inferred from ref)
• {✓/✗} TypeScript strict mode compliance (noImplicitAny, strictNullChecks)

Issues: {List or "None"}

---

Wave 1: Test Quality — test-automator

Scope: NUnit+Moq coverage (≥80%), Vitest (≥95%), Playwright fixtures, AAA pattern

Coverage:

• Backend (NUnit+Moq): {X}% — {✓ ≥80% / ✗ Below threshold}
• Frontend (Vitest): {X}% — {✓ ≥95% / ✗ Below threshold}
• E2E (Playwright): {X}/{Total} scenarios covered

Test Quality:

• {✓/✗} AAA pattern (Arrange/Act/Assert) consistently applied
• {✓/✗} Moq mocks properly scoped and verified
• {✓/✗} Playwright fixtures used (not bare page.goto() navigation)
• {✓/✗} No flaky waits (networkidle preferred over arbitrary timeouts)

Issues: {List or "None"}

---

Issues Summary

Taxonomy key:

• [BLOCKER] — correctness bug, security flaw, or convention violation → must be fixed (no skip)
• [SHOULD] — best practice gap, not a hard violation → fixed OR user explicitly approves skip
• [NIT] — style preference → fixed OR user explicitly approves skip
• [QUESTION] — clarification needed → must be answered before Phase 4 closes

Blockers ([BLOCKER])

{List all blockers that must be fixed before Phase 4 can close, or "None identified. ✓"}

Should-Fix ([SHOULD])

Nits ([NIT])

Questions ([QUESTION])

---

Key Files Reviewed

• {File path} — {Description}

---

Final Assessment

Grade: {Letter} ({Score}/100)

Verdict: {READY/NOT READY} to close Phase 4

{Detailed assessment paragraph}

Strengths:

• ✓ {Strength}

Areas for Improvement (Non-blocking):

• {Improvement area — labeled [SHOULD] or [NIT] in Issues Summary}

---

Phase 4 Exit Checklist

All items must be resolved before Phase 4 closes. User sign-off required.

Blockers:

• [ ] All [BLOCKER] items: Fixed and tests pass ✓ _(no skip allowed)_

Should-Fix:

• [ ] All [SHOULD] items: Fixed or User explicitly approved skipping ✓

Nits:

• [ ] All [NIT] items: Fixed or User explicitly approved skipping ✓

Questions:

• [ ] All [QUESTION] items: Answered ✓

Sign-off:

• [ ] User has reviewed this checklist and approves Phase 4 closure

Skipped [SHOULD] and [NIT] items must be recorded in context.md ## Key Decisions.

These items do NOT automatically become Phase 5 scope — Phase 5 is independently pre-scoped.

>

Two-Session Rule: If total findings ≥ 5 or blockers ≥ 3, split into Session A (blockers only, commit) and Session B (should/nits). See workflow-rules.md → "Two-Session Rule".

---

Review Completed: {YYYY-MM-DD} Approved By: (Pending user sign-off on exit checklist above)

Feature: {feature-name}

Worktree: {worktree-path} OpenSpec Change: openspec/changes/{feature-name}

<!-- CURRENT_PHASE: 0 --> <!-- PHASE_STATUS: in_progress -->

<!-- HOOK_STATUS_START -->

Status (Updated by Hook)

Last Updated: {timestamp} Current Phase: Phase 0 - Context Setup

What's Been Completed

<!-- Auto-generated -->

Next Todo

<!-- Auto-generated --> <!-- HOOK_STATUS_END -->

---

Key Decisions

{Record approvals and decisions here}

---

Blockers & Issues

{Record blockers here}

---

Learnings

{Record insights here}

Retrospective: {Feature Name} ({FEATURE-ID})

Feature ID: FEATURE-ID Completed: {date} Duration: {start-date} to {end-date} Team: {team-members}

---

<!-- GUIDANCE: Use this retrospective to capture learnings for future features

• Reflect honestly on what went well and what didn't
• Identify actionable process improvements
• Document patterns that can be reused
• Update team knowledge base and memories

-->

Executive Summary

Brief overview of the feature implementation journey and key outcomes.

Overall Success: Success / Partial Success / Needs Improvement

Key Achievement: 1-2 sentences on the most significant accomplishment

Key Challenge: 1-2 sentences on the biggest obstacle overcome

---

1. What Went Well

Planning & Requirements

• ✅ Item 1: What worked well in requirements gathering
• ✅ Item 2: What worked well in acceptance criteria definition
• ✅ Item 3: What worked well in task breakdown

Implementation

• ✅ Item 1: What worked well in coding/TDD process
• ✅ Item 2: What worked well in technology choices
• ✅ Item 3: What worked well in team collaboration

Testing & Quality

• ✅ Item 1: What worked well in test coverage
• ✅ Item 2: What worked well in code review
• ✅ Item 3: What worked well in quality assurance

Process & Workflow

• ✅ Item 1: What worked well in the 8-phase workflow
• ✅ Item 2: What worked well in using feature-dev skill
• ✅ Item 3: What worked well in approval gates

---

2. Challenges & Obstacles

Technical Challenges

Challenge 1: {Description}

• Problem: What went wrong or was difficult
• Impact: How it affected the project (time, quality, scope)
• Resolution: How it was resolved
• Lesson: What we learned

Challenge 2: {Description}

• Problem: What went wrong or was difficult
• Impact: How it affected the project
• Resolution: How it was resolved
• Lesson: What we learned

Process Challenges

Challenge 1: {Description}

• Problem: What didn't work in the workflow
• Impact: How it slowed us down
• Resolution: How it was addressed
• Lesson: What should change next time

---

3. Deviations from Plan

Planned vs Actual

Why Deviations Occurred

1. Deviation 1: Explanation of why plan changed

• Was it avoidable?: Yes/No, and why
• Should planning improve?: What to do differently

2. Deviation 2: Explanation of why plan changed

• Was it avoidable?: Yes/No, and why
• Should planning improve?: What to do differently

---

4. Key Learnings

Technical Learnings

Learning 1: {Topic}

What we learned: Detailed description Reusability: How this applies to future features Documentation: Where this is now documented (ADR, memory, wiki)

Learning 2: {Topic}

What we learned: Detailed description Reusability: How this applies to future features Documentation: Where this is now documented

Process Learnings

Learning 1: {Process Improvement}

What we learned: What didn't work as expected Impact: How it affected productivity/quality Recommendation: What should change

Learning 2: {Best Practice}

What we learned: What worked exceptionally well Impact: Positive outcomes Recommendation: Should be standard practice

---

5. Metrics & Statistics

Development Metrics

• Lines of Code Added: X
• Files Created/Modified: Y
• Test Coverage Achieved: Z%
• Bugs Found in Review: N
• Bugs Found Post-Release: M

Time Metrics

• Phase 0 (Context Setup): X hours
• Phase 1 (Planning): X hours
• Phase 2 (Convention & Readiness Review): X hours
• Phase 3 (Implementation): X hours
• Phase 4 (Code Review): X hours
• Phase 5 (Refactor): X hours
• Phase 8 (Approval & Commit): X hours
• Total: X hours

Quality Metrics

• Initial Test Pass Rate: X%
• Code Review Issues: X
• Refactoring Iterations: X
• Final Build Status: Pass/Fail

---

6. Patterns & Anti-Patterns

Patterns to Reuse

Pattern 1: {Name}

• Context: When to use this pattern
• Implementation: How we implemented it
• Benefits: Why it worked well
• Code Location: Where to find examples (file:line)

Pattern 2: {Name}

• Context: When to use this pattern
• Implementation: How we implemented it
• Benefits: Why it worked well
• Code Location: Where to find examples

Anti-Patterns to Avoid

Anti-Pattern 1: {Name}

• What we did: Description of the mistake
• Why it was wrong: Problems it caused
• Correct approach: What should have been done
• How to detect: Warning signs to watch for

Anti-Pattern 2: {Name}

• What we did: Description of the mistake
• Why it was wrong: Problems it caused
• Correct approach: What should have been done
• How to detect: Warning signs to watch for

---

7. Process Improvements

Immediate Actions (Apply to Next Feature)

1. Improvement 1: {Description}

• Problem Solved: What this addresses
• How to Implement: Concrete steps
• Responsible: Who will ensure this happens

2. Improvement 2: {Description}

• Problem Solved: What this addresses
• How to Implement: Concrete steps
• Responsible: Who will ensure this happens

Long-Term Improvements (Update Standards)

1. Improvement 1: {Description}

• Document to Update: Which workflow/standard doc
• Proposed Change: What should be added/changed
• Justification: Why this should be standard

2. Improvement 2: {Description}

• Document to Update: Which workflow/standard doc
• Proposed Change: What should be added/changed
• Justification: Why this should be standard

---

8. Knowledge Base Updates

Serena Memory Updates

Memories Updated:

• [ ] project_overview - Added information about {topic}
• [ ] tech_stack_details - Documented {pattern/approach}
• [ ] code_style_{lang} - Added guideline about {topic}
• [ ] database_conventions - Updated with {learning}

New Patterns Documented:

• Pattern in project tech-stack directory or ADR

ADR Updates

New ADRs Created:

• ADR-XXX: {Decision Title} - {Brief description}

Existing ADRs Updated:

• ADR-YYY: Updated with {new information}

---

9. Tool & Workflow Assessment

feature-dev Skill

• Effectiveness: How well did the skill enforce workflow?
• Pain Points: What didn't work smoothly?
• Suggestions: What should be improved in the skill?

8-Phase Workflow

• Phase Effectiveness: Which phases were most/least valuable?
• Pain Points: Where did the workflow slow us down?
• Suggestions: Should any phases be modified?

Tools & Technologies

• What Worked: Tools that increased productivity
• What Didn't: Tools that caused friction
• Suggestions: New tools to consider

---

10. Team Feedback

Individual Reflections

Team Member 1: {name}

• What went well from your perspective
• What was challenging
• What you learned
• What you'd do differently

Team Member 2: {name}

• What went well from your perspective
• What was challenging
• What you learned
• What you'd do differently

---

11. Action Items

Immediate (Before Next Feature)

• [ ] Action 1: {Description} - Assigned to: {name} - Due: {date}
• [ ] Action 2: {Description} - Assigned to: {name} - Due: {date}
• [ ] Action 3: {Description} - Assigned to: {name} - Due: {date}

Short-Term (Within Sprint)

• [ ] Action 1: {Description} - Assigned to: {name} - Due: {date}
• [ ] Action 2: {Description} - Assigned to: {name} - Due: {date}

Long-Term (Within Quarter)

• [ ] Action 1: {Description} - Assigned to: {name} - Due: {date}
• [ ] Action 2: {Description} - Assigned to: {name} - Due: {date}

---

12. Conclusion

Overall Assessment

1-2 paragraphs summarizing the feature implementation experience, key takeaways, and confidence in future features based on lessons learned.

Confidence for Next Feature

Rating: 1-10 (where 10 = very confident) Reasoning: Why this rating and what would increase confidence

---

Related Documents

• Proposal: openspec/changes/{change-name}/proposal.md
• Design: openspec/changes/{change-name}/design.md
• Tasks: openspec/changes/{change-name}/tasks.md
• Context File: context.md
• Implementation Workflow: project workflow directory (e.g. .ai/workflows/implementation.md if present)

---

Retrospective Completed By: {facilitator-name} Date: {date} Participants: {all-participants}

Agent Orchestration (MANDATORY)

CRITICAL: Agent invocation is MANDATORY, not optional. You MUST announce, confirm, and invoke agents at each phase transition.

Mandatory Invocation Protocol

Step 1: ANNOUNCE (Required)

Before starting any phase, list required agents:

Phase {N} ({Name}) requires these agents:
- {agent-name}: {specific purpose for this feature}
- {agent-name}: {specific purpose for this feature}

Step 2: CONFIRM (Required)

Use AskUserQuestion with options:

• "Invoke all agents" (Recommended)
• "Skip agents" (User must provide reason)

Step 3: INVOKE (Required unless user explicitly skips)

Use Task tool with subagent_type for each approved agent.

Step 4: REPORT (Required)

Summarize key findings from each agent before proceeding.

Agent Selection by Phase

Phase 4 Execution Protocol

Step 0: Domain Detection

git diff --name-only main...HEAD

Derive domain boundaries in priority order: 1. Read CLAUDE.md Subdirectory Instructions for explicit subdirectory → domain mappings 2. Fallback — file extension patterns from git diff --name-only main...HEAD:

• hasBackendChanges → .cs or .csproj files
• hasFrontendChanges → .vue or .ts files
• hasDatabaseChanges → .sql files

Wave 0 (Sequential Anchor)

Invoke code-reviewer first. Scope: plan compliance only (proposal/specs/design.md vs implementation). Pass Wave 0 summary to all Wave 1 agents as context.

Wave 1 (Parallel — after Wave 0 completes)

Invoke all applicable agents simultaneously:

performance-engineer in Phase 4 is read-only (identify issues). Phase 5 scope is profiling + fixing.

Technology-Specific Agents

Skip Conditions (User MUST Explicitly Approve)

Agents may ONLY be skipped if:

• User explicitly says "skip agents" in AskUserQuestion response
• Feature is explicitly marked as "trivial" complexity
• Same agent already ran in current session with same scope

NEVER silently skip agent invocation.

User Communication

Before invoking (REQUIRED):

Phase {N} requires the following agents:
- {agent-name}: {purpose}

[AskUserQuestion: Invoke agents?]

After completion (REQUIRED):

{Agent-name} complete. Key findings:
- {finding 1}
- {finding 2}

Agent Failure

If agent fails or times out: 1. Inform user of issue 2. Offer to retry or continue manually 3. Log failure in context.md 4. Don't block workflow

CRITICAL RULES

1. ANNOUNCE → CONFIRM → INVOKE → REPORT (mandatory sequence) 2. NEVER skip without explicit user approval 3. Agents assist decisions, don't replace them 4. User can override any agent suggestion 5. Never auto-invoke for commit approval

Violation Consequences

If you proceed without following the protocol:

• User misses important analysis
• Quality may suffer
• Workflow is incomplete
• This is a workflow violation

Superpowers Skill Integration

Superpowers skills enhance execution at specific phases.

Phase-to-Skill Mapping

Phase 3: Execution Model Choice

At the start of Phase 3, present the user with:

How should implementation be executed?

A) Subagent-Driven (superpowers:subagent-driven-development)
   → Fresh subagent per task, 2-stage review (spec + code quality)

B) Team Mode (spawn parallel agent team)
   → Requires team mode enabled in Claude Code settings
   → Spawns specialized agents per task stream (DB, backend, frontend, E2E)

C) Batch Execution (superpowers:executing-plans)
   → Execute tasks in batches of 3, review checkpoints between

D) Direct Implementation
   → Manual task-by-task, no delegation

[AskUserQuestion]

OpenSpec's tasks.md serves as the plan for all execution models.

Phase 3: Team Mode (When Enabled)

If user chooses Team Mode and Claude Code team features are available:

1. Parse OpenSpec tasks.md for independent task streams/batches 2. Create team via TeamCreate with feature name 3. Create tasks via TaskCreate from OpenSpec tasks.md items 4. Spawn teammates via Task tool with team_name parameter:

• Assign subagent_type based on task domain (e.g., csharp-developer, vue-expert, database-optimizer)
• Each teammate gets: task description, relevant OpenSpec artifacts (design.md, specs/), file scope

5. Coordinate: Mark tasks in TaskList as teammates complete them 6. Sync back: When all teammates done, update OpenSpec tasks.md checkboxes (- [x]) 7. Shutdown team via SendMessage shutdown_request to each teammate

Team mode follows the same file ownership boundaries:

• DB agent: database domain (.sql files / database subdirectory per CLAUDE.md)
• Backend agent: backend domain (.cs/.csproj files / backend subdirectory)
• Frontend agent: frontend domain (.vue/.ts files / frontend subdirectory)
• E2E agent: e2e domain (playwright config / e2e subdirectory)

Phase 8: Verification + Finalization

1. superpowers:verification-before-completion — run tests, provide evidence 2. openspec-verify-change — validate implementation matches specs/tasks 3. superpowers:finishing-a-development-branch — present 4 options (merge/PR/keep/discard) 4. openspec-archive-change + optional openspec-sync-specs — finalize artifacts

Context File Management

Single source of truth for context.md format, updates, and parsing.

Location

{FeatureDocsPath}/doing/{feature-name}/context.md   # During development
{FeatureDocsPath}/done/{feature-name}/context.md    # After completion (Phase 8)

Canonical Format

# Feature: {feature-name}

**OpenSpec Change:** openspec/changes/{change-name}

**Status:** In Progress | Blocked | Complete
**Current Phase:** Phase {N} - {Name}
**Last Updated:** YYYY-MM-DD HH:MM:SS AM/PM TZ

---

## Current Progress

### What's Been Completed
- [x] Phase 0: Context Setup
- [x] Phase 1: Planning
- [ ] Phase 2: Convention & Readiness Review
- [ ] Phase 3: Implementation

### Next Todo
- {Next action to take}

---

## Key Decisions
- {Approval or decision with date}

---

## Blockers & Issues
- {Current blockers if any}

---

## Learnings
- {Insights discovered}

Update Responsibilities

Update Protocol

Update header after every step:

**Status:** In Progress
**Current Phase:** Phase 3 - Implementation
**Last Updated:** 2025-12-25 03:00:00 PM CST

Update triggers:

• Starting new activity
• Completing activity
• Receiving approval
• Phase transition
• Encountering blocker

Always update: Last Updated timestamp after every activity

Parsing (Resume Mode)

Extract Current Phase

Parse: **Current Phase:** Phase {N}
Extract: N (integer 0-8)

Extract Status

Parse: **Status:** {value}
Values: "In Progress" | "Blocked" | "Complete"

Extract Completed Phases

Parse: ## Current Progress → ### What's Been Completed
Look for: - [x] Phase {N}:
Extract: List of completed phase numbers

Extract Approvals

Parse: ## Key Decisions
Look for: "approved" keyword
Extract: Which documents were approved

Extract OpenSpec Change Path

Parse: **OpenSpec Change:** {path}
Extract: path (relative to project root, e.g., openspec/changes/add-user-auth)

Extract Blockers

Parse: ## Blockers & Issues
If non-empty and not placeholder text → hasBlockers = true

Hook Integration

The stop hook (.claude/hooks/update-context-on-stop.sh) updates:

• "What's Been Completed" section
• "Next Todo" section

Skill should NOT update these sections to avoid conflicts.

Resume Flow

1. Read context.md 2. Parse current phase and status 3. Present summary to user:

   Resuming: {feature-name}
   Current Phase: Phase {N} - {Name}
   Last Updated: {timestamp}

   Continue?

4. Proceed from current phase

Error Handling

Error scenarios and recovery strategies.

Context.md Not Found

Scenario: Resume mode but context.md doesn't exist

Response:

context.md not found for feature: {feature-name}
Expected: {FeatureDocsPath}/doing/{feature-name}/context.md

Options:
A) Start fresh with Phase 0
B) Check done/ directory
C) Try different feature name

Phase Validation Failed

Scenario: Transition attempted but phase incomplete

Response:

Phase {X} not complete. Missing:

Files:
- {missing files}

Approvals:
- {missing approvals}

Complete these before proceeding.

Invalid Phase Skip

Scenario: User tries to skip phases

Response:

Cannot skip from Phase {X} to Phase {Y}.
Configured phases: {list}
Next allowed phase: {next}

Configuration Missing

Scenario: No workflow config in CLAUDE.md

Response:

No configuration found. Using defaults:
- Phases: 0,1,2,3,8
- TDD: optional
- FeatureDocsPath: Documentation/Requirements/Feature

Context.md Parse Error

Scenario: context.md corrupted or malformed

Response:

Failed to parse context.md.

Options:
A) View current content
B) Start fresh (backup existing)
C) Manually fix

OpenSpec Change Not Found

Scenario: Phase 1 but no OpenSpec change exists

Response:

No OpenSpec change found for feature: {feature-name}

Options:
A) Create new change: openspec-new-change "{feature-name}"
B) Link existing change (update context.md)
C) Use fast-forward: openspec-ff-change "{feature-name}"

OpenSpec Artifacts Incomplete

Scenario: Phase 1→2 transition but artifacts missing

Response:

OpenSpec artifacts incomplete. Missing:
- {missing artifacts}

Run openspec-continue-change to create remaining artifacts.

Best Practices

1. Be specific - Explain exactly what's wrong 2. Offer options - Multiple paths forward 3. Preserve state - Don't lose user work 4. Allow retry - Let user try again

Phase 1: Planning (OpenSpec Delegation)

Phase 1 delegates planning to OpenSpec's artifact workflow. Instead of 5 separate documents, invoke OpenSpec to produce 4 artifacts: proposal, specs, design, tasks.

Critical First Step

Use AskUserQuestion BEFORE starting artifact creation to clarify:

• Unclear functional requirements
• Missing non-functional requirements
• Implementation preferences
• Priority and scope boundaries

Artifact Sequence

Rule: Create ONE artifact at a time via openspec-continue-change. User approves each before proceeding to next.

How It Works

Step 1: Clarify Requirements

Use AskUserQuestion to gather context before creating any artifacts.

Step 2: Create Artifacts via OpenSpec

Invoke openspec-continue-change skill repeatedly:

• Each invocation creates ONE artifact
• OpenSpec reads dependency artifacts for continuity
• User reviews and approves after each
• Continue until all 4 artifacts are complete

Alternative: Fast-Forward

If user wants all artifacts created at once:

• Invoke openspec-ff-change skill
• Creates all artifacts in dependency order without stepping through
• Still requires user review of final result

WHAT vs HOW (Natural Separation)

OpenSpec artifacts naturally separate concerns:

• proposal.md + specs/ = WHAT (requirements, acceptance criteria, scenarios)
• design.md + tasks.md = HOW (technical decisions, implementation steps)

Completion Validation

Phase 1 is complete when:

• All 4 artifacts exist in openspec/changes/<name>/
• All approvals recorded in context.md Key Decisions

Phase 2: Convention & Readiness Review

Hard gate between planning and implementation. Loads ADRs and tech-stack gotchas relevant to the feature's domains, re-reads all 4 OpenSpec artifacts, cross-checks for convention violations, and resolves any violations in the spec before implementation begins.

No subagents required — this phase is performed by the main agent.

Entry Condition (Phase 1 → Phase 2)

• All 4 OpenSpec artifacts exist in openspec/changes/<name>/
• All 4 approvals recorded in context.md Key Decisions

Step 1: Domain Detection

Check CLAUDE.md Subdirectory Instructions section first. If subdirectory → domain mappings are declared there, use them directly (most precise). Otherwise fall back to file extension patterns from tasks.md content:

Step 2: Filtered Convention Load

Tech-stack discovery: Scan the project tech-stack directory (read TechStackPath: from CLAUDE.md; defaults to .ai/tech-stack/) subdirectories by domain flag. Load convention files from matched subdirectories. Do NOT hardcode filenames — the project's tech-stack directory structure is authoritative.

⚠️ If the project tech-stack directory does not exist: warn the user —

"No project tech-stack found. Applying generic conventions only.

Create tech-stack convention files to get project-specific guidance."

Gotchas files are never loaded by default. Load gotchas.md from the relevant

subdirectory only when debugging a specific edge case or when Phase 4 review identifies

a gotcha-class issue.

Step 3: Comprehension Re-Read

Read all 4 OpenSpec artifacts in order:

1. proposal.md 2. specs/*/spec.md (all spec files) 3. design.md 4. tasks.md

Step 4: Cross-Check & Produce Checklist

For each loaded ADR and tech-stack file, verify the design and tasks comply. Output a checklist in chat:

Convention & Readiness Review Checklist
Domains: Backend, Database

ADRs Reviewed: adr/architecture/ (all), adr/database/ (all)
Tech-stack: <discovered files>

Violations Found:
⚠ design.md proposes raw Exception — MUST use typed exceptions (backend/exceptions.md)
  → Resolution required: Update design.md

Clean Items:
✓ GUIDs used as PKs (ADR-012)
✓ SP naming follows {Project}_Entity_Op pattern (per project database conventions)
✓ WITH(NOLOCK) noted on all SELECT queries (database/sp-conventions.md)
...

Comprehension:
✓ All 4 OpenSpec artifacts re-read
✓ No blocking ambiguities in tasks.md

Step 5: Resolve Violations (HARD GATE)

NO BYPASSING. For each ⚠ violation:

1. Update the relevant OpenSpec artifact (design.md or tasks.md) 2. Re-record the resolution in the checklist: ⚠ → ✓ RESOLVED: [what was changed] 3. All violations must be resolved before Phase 3 begins

If a "violation" is determined to be a false positive (convention does not actually apply), document the reasoning as a clean item with a note.

Step 6: Record in context.md

Under ## Key Decisions:

- Convention & Readiness Review complete (YYYY-MM-DD)
  Domains: Backend, Database
  ADRs: architecture/ (all), database/ (all) | Tech-stack: backend/exceptions.md, database/sp-conventions.md
  Violations found: 1 (resolved — design.md updated for typed exceptions)

If no violations:

- Convention & Readiness Review complete (YYYY-MM-DD)
  Domains: Backend, Database
  ADRs: architecture/ (all), database/ (all) | Tech-stack: backend/exceptions.md, database/sp-conventions.md
  Violations found: 0

Step 7: Implementer Reference Checklist

Emit the following checklist in chat at Phase 2 exit. The implementer carries it into Phase 3 as a quick-reference guard against the most frequently rediscovered conventions.

Only include sections whose domain flag is true:

Implementation Quick-Reference (carry into Phase 3)

[hasDatabase]
□ SP filename: {Project}_Entity_Op.sql — proc name: {Project}_Entity_Op_YYYY.MM.DD
□ WITH(NOLOCK) on every SELECT where required (SQL Server-specific hint; check project conventions); forbidden on writes
□ Audit columns: CreatedBy/ModifiedBy (NVARCHAR email), CreatedOn/ModifiedOn (GETUTCDATE)
□ GUID validation: = '00000000-0000-0000-0000-000000000000' (not <= 0)
□ @@ROWCOUNT captured BEFORE COMMIT

[hasBackend]
□ Typed exceptions only (NotFoundException, ValidationException, ConflictException)
□ Constructor injection; register in Program.cs
□ Async/await fully propagated — no .Result or .Wait()

[hasFrontend]
□ CSS custom properties only — no hardcoded hex
□ data-testid on interactive elements
□ SSR guard: import.meta.server before browser APIs
□ Project-specific API composable for authenticated calls (check project frontend conventions)

Exit Condition (Phase 2 → Phase 3)

• Convention compliance checklist complete (all items are ✓ or ✓ RESOLVED)
• No open ⚠ violations remain
• Convention & Readiness Review recorded in context.md Key Decisions
• Implementer Reference Checklist emitted in chat
• User approves transition to Phase 3 (Implementation)

Workflow Rules

Single source of truth for phase sequence, validation, approvals, and execution rules.

Startup Flow

On Invocation

1. Load config from project's CLAUDE.md:

• Phases: Which phases to execute (default: 0,1,2,3,8)
• TDD: required | optional | none (default: optional)
• FeatureDocsPath: Where context.md lives (default: Documentation/Requirements/Feature)

2. Get feature name from user input or ask if not provided

3. Detect mode:

• If {FeatureDocsPath}/doing/{feature-name}/context.md exists → RESUME
• Otherwise → START (begin Phase 0)

4. Phase 0 sequence (mandatory, in order): a. Create worktree — git worktree add with feature branch (ALWAYS first) b. Switch to worktree — all subsequent work happens there c. Create context.md + OpenSpec init in the worktree d. Run `/openspec-explore` — design thinking before artifact generation e. Run `/brainstorm` (optional — skill may not be available inside worktree context) — structured brainstorming after explore f. Run `Explore` agent — codebase investigation

5. Execute phases 1-8 in configured sequence with validation at each transition (all within worktree)

Phase Sequence

Schema Source: schema/phases.txt (single source of truth for phase names, emojis, descriptions)

*Phases 6-7 require explicit user approval even if configured.

Mandatory phases: 0, 1, 2, 3, 4, 5, 8 (auto-added if missing from config)

Phase 1 Sub-Activities (OpenSpec Artifacts)

Planning delegates to OpenSpec (defined in schema/phases.txt):

Rule: Invoke openspec-continue-change per artifact. One at a time. User approves each. Alternative: openspec-ff-change for batch creation.

Phase Validation Rules

Phase 0 → Phase 1

Required:

• Git worktree exists for feature branch
• Feature directory exists: {FeatureDocsPath}/doing/{feature-name}/
• context.md exists with required sections (including **Worktree:** path)
• OpenSpec change exists: openspec/changes/{feature-name}/
• context.md has **OpenSpec Change:** field populated
• /openspec-explore has been run (design thinking completed)
• Explore agent has been invoked

Phase 1 → Phase 2

Required (OpenSpec artifacts in openspec/changes/<name>/):

• proposal.md exists
• specs/ directory non-empty (at least one spec)
• design.md exists
• tasks.md exists

Required Approvals (in context.md Key Decisions):

• Proposal approved
• Specifications approved
• Design approved
• Tasks approved

Phase 2 → Phase 3

Required:

• Convention compliance checklist completed (all items are ✓ or ✓ RESOLVED)
• No open ⚠ violations remain — all resolved in OpenSpec artifacts
• Convention & Readiness Review recorded in context.md Key Decisions
• User approves transition to Phase 3 (Implementation)

Phase 3 → Phase 4

Required:

• All tasks in OpenSpec tasks.md completed (- [x])
• All tests passing
• Build succeeds

Phase 4 → Phase 5

Required:

• Code review checklist completed
• ALL [BLOCKER] findings fixed and tests pass
• ALL [SHOULD] findings: Fixed or user-approved skip (recorded in context.md ## Key Decisions)
• ALL [NIT] findings: Fixed or user-approved skip (recorded in context.md ## Key Decisions)
• ALL [QUESTION] findings answered
• Phase 4 Exit Checklist signed off by user in code-review document

Phase 5 → Phase 6/7/8

Required:

• Tests still passing after refactoring
• Build succeeds

Phase 8 Complete

Required:

• All tests passing
• Build succeeds
• User explicitly approved commit

Approval Gates

Phase 1 Approvals (4 mandatory, via OpenSpec)

Phase Transition Approvals

Recording Approvals

Record all approvals in context.md ## Key Decisions section:

## Key Decisions
- Proposal approved (YYYY-MM-DD)
- Specifications approved (YYYY-MM-DD)
- Design approved (YYYY-MM-DD)
- Tasks approved (YYYY-MM-DD)

TDD Enforcement (Phase 3)

TDD Cycle: RED (failing test) → GREEN (make pass) → REFACTOR (improve)

Code Review (Phase 4)

Checklist categories:

• Functionality: Requirements met, edge cases handled
• Code Quality: Conventions, no duplication, naming
• Testing: 80%+ coverage, meaningful tests
• Security: Input validation, no injection vulnerabilities
• Performance: Optimized queries, no N+1

Process: Skill presents checklist → User performs review → User marks complete

Review Comment Taxonomy

Every finding from any sub-agent MUST be labeled before Phase 4 can close:

Reviewer Authority — what CAN carry [BLOCKER]:

• Correctness: code produces wrong output for defined inputs
• Security: OWASP vulnerability, missing auth check, injection risk
• Test failure: any test that does not pass
• Convention violation: rule explicitly defined in project tech-stack docs

What CANNOT be a blocker:

• Style preferences not codified in conventions
• "I would have done it differently"
• Refactoring requests that change structure without fixing a defect

Phase 4 Disposition Requirement

Before Phase 4 closes, ALL sub-agent findings must have a recorded disposition:

1. [BLOCKER] — Fixed and tests pass (no skip allowed under any circumstances) 2. [SHOULD] — Fixed OR user explicitly approves skipping 3. [NIT] — Fixed OR user explicitly approves skipping 4. [QUESTION] — Answered before Phase 4 closes

Nothing disappears silently. Every finding needs a recorded disposition. User approval of skipped items must be recorded in context.md ## Key Decisions.

Two-Session Rule (Phase 4)

If Phase 4 produces ≥ 5 total findings or ≥ 3 blockers, split into two sessions:

• Session A — Fix all [BLOCKER] findings only. Commit: [BEHAVIORAL]: fix Phase 4 blockers
• Session B — Address remaining [SHOULD] / [NIT] / [QUESTION] items

Record the split in context.md:

- Phase 4 split: Session A (blockers, YYYY-MM-DD) | Session B (should/nits, YYYY-MM-DD)

This ensures blockers are always committed before context runs out. If findings are below the threshold, complete everything in one session as normal.

Refactor (Phase 5)

Definition: Restructuring existing, correct code to improve internal design WITHOUT changing observable behavior.

Proof of preservation: The full test suite passes before and after, with zero test file changes. If any test had to change, it was not a refactor — it was a behavior change.

Pre-scoping rule: Phase 5 scope MUST be declared in Phase 1 tasks.md or at Phase 3 start. Phase 5 is NEVER triggered by Phase 4 findings.

Skipping: If nothing was pre-scoped, Phase 5 is simply skipped. No obligation.

What IS a refactor:

• Extract an 80-line service method into smaller, focused methods
• Rename an unclear SP parameter to match the project's SP naming convention
• Simplify deeply nested if chains in a controller action
• Move duplicated validation logic into a shared helper

What is NOT a refactor:

• Adding a missing query hint required by project conventions — that's a bug fix ([BLOCKER])
• Changing SP parameter types — that's a behavior change
• Adding a new field to a DTO — that's a feature
• Rewriting a composable's API shape — that changes callers

Validation steps: 1. Run full test suite — confirm all pass (baseline) 2. Make structural changes 3. Run full test suite again — confirm still all pass 4. git diff --name-only — confirm zero test files changed

Commit Approval (Phase 8)

Pre-commit validation:

• All tests passing
• Build succeeds
• All tasks completed

CRITICAL: Never commit without explicit user approval.

Post-commit:

• Move feature directory from doing/ to done/
• Update context.md status to Complete