feature-workflow

name	feature-workflow
description	TDD-based feature workflow with 9 phases - loads directly into session (no installation)

Feature Workflow

9-phase TDD feature implementation workflow (from worktree setup through deployed-and-smoked closeout). Loads directly into session - no file installation required.

🔴 4 CORE PRINCIPLES (ALWAYS ENFORCED)

These 4 principles are MANDATORY throughout the entire workflow. Violations are BLOCKED.

1️⃣ USE SUBAGENT (Task Tool)

❌ BLOCKED: Direct Edit/Write without subagent
✅ REQUIRED: Task(subagent_type="...") for ALL implementation

Task Type	Subagent
Backend/API	backend-architect
Frontend/UI	frontend-architect
Tests	quality-engineer
Types	typescript-pro
Exploration	Explore

2️⃣ USE LSP (Not grep/glob)

❌ BLOCKED: grep, glob, Grep, Glob for symbol search
✅ REQUIRED: LSP tool for code navigation

Task	LSP Operation
Find definition	goToDefinition
File symbols	documentSymbol
Project search	workspaceSymbol
Find references	findReferences
Find implementations	goToImplementation

3️⃣ USE TDD (Tests First)

❌ BLOCKED: Implementation before tests
✅ REQUIRED: Write tests → Run (RED) → Implement → Run (GREEN)

• Phase 2 (Tests) MUST complete before Phase 3 (Implementation)
• Tests should FAIL initially (red phase)
• Implementation makes tests PASS (green phase)

4️⃣ USE PARALLEL (Concurrent Execution)

❌ INEFFICIENT: Sequential subagent calls
✅ REQUIRED: Parallel Task calls when no dependencies

# GOOD: Single message with multiple Task calls
Task(types) + Task(query-keys)  ← Parallel (no dependency)

# GOOD: Sequential only when dependent
Task(api) → Task(hooks)  ← Sequential (hooks needs api)

Self-Check (BEFORE EVERY ACTION)

□ Am I using Task tool with subagent? → If NO, STOP
□ Am I using LSP for code navigation? → If grep/glob, STOP
□ Did I write tests first? → If NO, go back to Phase 2
□ Can these tasks run in parallel? → If YES, single message with multiple Task calls

---

Usage

/feature-workflow:feature-workflow "feature description"

⚡ MANDATORY: DELEGATE TO feature-dev

When this skill is invoked, IMMEDIATELY delegate to feature-dev:feature-dev

/feature-workflow:feature-workflow "Implement user settings page"
     │
     ▼
Skill(feature-dev:feature-dev, args="Implement user settings page")
     │
     ▼
feature-dev orchestrates → feature-workflow phases 1-7

Delegation Rule

# ALWAYS delegate - no exceptions
if skill_invoked == "feature-workflow":
    Skill("feature-dev:feature-dev", args=user_request)

How It Works

1. Delegate to feature-dev:feature-dev (MANDATORY)
2. Auto-detect project type (vite.config, go.mod, pubspec.yaml, etc.)
3. Apply 4 core principles + 9-phase workflow
4. Enforce throughout the session

7-Phase Workflow (STRICT ORDER)

Phase 1: Git Worktree Setup

• Create isolated feature branch
• Setup worktree in .worktrees/
• Verify dependencies

Gate: Worktree exists, correct branch

Phase 2: TDD - Write Tests First

• Write E2E/integration tests BEFORE implementation
• Tests should initially fail (red phase)

Gate: Test files created

Phase 3: Implementation (SUBAGENT MANDATORY!)

🚨 SUBAGENT DELEGATION IS REQUIRED - NOT OPTIONAL

ALWAYS use Task tool with subagents for implementation. Direct implementation without subagents is BLOCKED.

❌ BLOCKED: Direct file editing without subagent
✅ REQUIRED: Task(subagent_type="backend-architect" | "frontend-architect" | ...)

Subagent Selection by Task

Task Type	Subagent	When to Use
API/Backend	backend-architect	Handlers, services, repositories
UI/Frontend	frontend-architect	Components, pages, hooks
Tests	quality-engineer	Test files, test utilities
Types/Schemas	typescript-pro	Type definitions, schemas
Performance	performance-engineer	Optimization tasks
Security	security-engineer	Auth, validation

Parallel Execution Pattern

Phase 3 Implementation:
├─ [Parallel] Task(types) + Task(query-keys)
├─ [Sequential] Task(api) → Task(hooks) (dependency)
└─ [Parallel] Task(page) + Task(components)

LSP-First Within Subagents

Task	Use This	❌ NOT This
Find definition	LSP goToDefinition	grep/glob
File symbols	LSP documentSymbol	cat/read
Project search	LSP workspaceSymbol	grep
Find references	LSP findReferences	grep

Gate: Implementation complete via subagents, no direct edits

Phase 4: Build & Verification

• TypeScript/Go/Dart compilation
• Lint checks
• Unit tests

Gate: Build passes, lint clean

Phase 5: Local Testing

• Test with real backend
• E2E scenarios pass

Gate: E2E tests pass

Phase 6: Code Review (Local Review Loop — MANDATORY)

🔴 Local code review loop is REQUIRED. Do NOT skip to Phase 7 without a clean PASS verdict.

Loop until verdict = PASS (zero BLOCKING and zero HIGH findings).

Loop steps

1. Review: dispatch code-reviewer (Opus) per worktree/PR. Run in parallel when multiple PRs/features are in flight.

   • Each reviewer must compare against the base branch (e.g. git diff origin/develop...HEAD).
   • Reviewer prompt MUST constrain output to BLOCKING / HIGH severities only. Style nits, naming preferences, "could be more elegant" refactors, and test-coverage suggestions are noise and must be excluded.
   • Output format: severity-bucketed fix-list with file:line references and concrete proposed fix per item, plus a final BLOCK | PASS verdict.

2. Triage:

   • BLOCKING = correctness bug / security vuln / spec violation / will break prod → must fix
   • HIGH = clear logic defect → must fix
   • Anything below → ignore for this loop
   • If verdict = PASS (0 BLOCKING + 0 HIGH) → exit loop, proceed to Phase 7

3. Fix: dispatch executor (Opus, run in worktree). One executor per PR, batching all findings for that PR in a single prompt.

   • Prompt must enumerate each defect with file:line + reviewer's proposed fix
   • Executor must add a follow-up commit on the existing branch (NOT amend), push, and post a PR comment summarizing the fix
   • Verification gate before push: ktlintCheck + relevant unit tests + relevant integration tests all green

4. Re-review: dispatch fresh code-reviewer (Opus) on the same worktree against the new HEAD. Go to step 2.

5. Stop conditions:

   • PASS verdict → exit and proceed to Phase 7
   • 3 consecutive review rounds with no convergence → STOP and escalate to user with the unresolved findings (do NOT silently merge)
   • Reviewer keeps surfacing the same issue after fix → executor likely misunderstood; clarify the fix in the next executor prompt with a more specific example

Severity rubric (orchestrator must enforce in reviewer prompts)

Severity	Examples
BLOCKING	unverified webhook signature, missing @PreAuthorize on admin endpoint, TOCTOU race that double-sends/double-pays, log leak of secrets, wrong state transition, payment amount mutation, schema migration with no rollback
HIGH	silent failure path that loses data, missing null-safety on field the spec requires, off-by-one in cohort filter, idempotency that only works on the happy path, IT that passes even when the bug is reintroduced
❌ Not reported	style/ktlint/formatting, naming, "could be more elegant", missing comments, perf micro-opts, test coverage gaps unless a critical path is uncovered

Parallel execution

When multiple PRs/worktrees are in this phase, fire all reviewers in a single message (one Agent call per PR with run_in_background: true). Same for executors. Do NOT serialize independent PRs.

Gate: All worktrees return verdict PASS (0 BLOCKING + 0 HIGH).

Phase 7: Commit & Push

• Stage all changes
• Descriptive commit message
• Push to remote

Gate: Clean commit, pushed

Phase 8: Merge & Deploy

Once Phase 6 returns PASS, merge each PR and confirm the deploy reaches the dev environment.

• Squash-merge each PR to the integration branch (develop / main) with --delete-branch so the worktree branch is cleaned up.
• Verify the post-merge CI run on the integration branch is green for each squash commit (gh run list --branch <integration-branch>).
• Verify the deploy reaches dev: image pushed to registry, ArgoCD (or equivalent) synced, target pod healthy.
• If multiple PRs merge in close succession, verify they each got their own CI run and that the final dev pod is running the squash commit of the last merge (or all squash commits together).

Gate: integration-branch CI green for every merged PR commit AND dev environment reports the new image healthy.

Phase 9: Smoke & Issue Close

Only after dev is confirmed healthy with the new code:

• Run a focused smoke against the deployed dev environment exercising each merged feature's happy path. Pick the lightest mechanism that actually hits the deployed code — repo-specific, in priority order:
  1. Public dev API endpoint via curl (if the dev environment exposes a routable URL).
  2. kubectl --context=<dev-context> exec into the running pod and run an in-pod request against localhost (when the dev environment is internal-only).
  3. Dedicated smoke harness in the repo (postman collection, *.http file, integration suite tagged @SmokeTest) when one exists.
• The smoke is FEATURE-LEVEL, not endpoint-level. Hit the user-visible contract added by the PR (e.g. for a webhook feature, post a sample payload and verify the side effect lands in the DB; for an admin endpoint, call it with admin auth and verify the response shape and an audit/log row).
• DO NOT close the upstream issue until smoke passes. The local review loop guarantees correctness against the spec but not against deployment regressions (config drift, missing secrets, IAM, etc.).
• After smoke passes:
  • Close each tracked issue with a closeout comment that links the squash-merge commit, the CI run, the dev image digest, and the smoke evidence (request → response → side-effect line).
  • If smoke fails, do NOT close. File a follow-up commit on a hotfix branch and re-enter Phase 6 for that fix.

Gate: smoke passes for every merged feature AND every tracked issue is closed with concrete deploy + smoke evidence in the closeout comment.

Phase Enforcement (MANDATORY)

❌ BLOCKED:
- Starting Phase 3 without completing Phase 2
- Skipping to Phase 6 from Phase 2
- Committing (Phase 7) before code review (Phase 6)
- Merging (Phase 8) before commit/push (Phase 7)
- Closing the issue (end of Phase 9) before smoke passes against the deployed dev env
- Direct file editing in Phase 3 (MUST use subagents)

✅ ALLOWED:
- Sequential progression: 1→2→3→4→5→6→7→8→9
- Fixing issues within current phase
- Parallel subagent execution in Phase 3

🚨 SUBAGENT ENFORCEMENT (CRITICAL)

Phase 3 REQUIRES subagent delegation. This is NOT optional.

Self-Check Before Implementation

Before ANY file edit in Phase 3, ask:
□ Am I using Task tool with a subagent? → If NO, STOP
□ Did I select the appropriate subagent_type? → Match task to agent
□ Can multiple tasks run in parallel? → Launch parallel Task calls

Enforcement Rule

if phase == 3 and action == "edit_file":
    if not using_subagent:
        BLOCK("Use Task tool with subagent_type for implementation")

Supported Project Types

Type	Stack	Key Features
react-vite	React + Vite + pnpm	Playwright E2E, TanStack Query
nextjs	Next.js + pnpm	App Router, Server Components
go-gin	Go + Gin + fx	Handler→Service→Repo, Swagger
flutter	Flutter + BLoC	Clean Architecture

Checkpoint Indicators

Symbol	Status
[P1:_]	Pending
[P1:*]	In Progress
[P1:V]	Verified
[P1:X]	Failed

Integration with Skills

• feature-dev:feature-dev - DELEGATED TO (orchestrates the 9 phases)
• superpowers:using-git-worktrees - Worktree setup (Phase 1)
• superpowers:test-driven-development - TDD approach (Phase 2)
• oh-my-claudecode:code-reviewer (Opus) - Local review agent invoked each round of the Phase 6 loop
• oh-my-claudecode:executor (Opus) - Fix agent invoked when Phase 6 reviewer returns BLOCKING/HIGH
• ralph-loop:ralph-loop - Optional alternative for fully-autonomous Phase 6 loop (use when the orchestrator is not Claude Code)
• code-patterns - LSP-first enforcement (Phase 3)