| name | pipeline |
| description | Unified development pipeline for all implementation tasks.
Clean Architecture is the default — file placement follows CA layer templates.
Auto-detects execution mode (Sequential or Team) based on task scope.
Covers single-file fixes through cross-cutting multi-agent parallel work.
Do NOT use for research, documentation-only, or planning-only tasks.
|
Harness Pipeline
🚫 CRITICAL — PLAN APPROVAL CANNOT BE BYPASSED
When invoked, this pipeline MUST run Phase 1 (Plan) and receive ExitPlanMode
approval from the user BEFORE any source-code edit. The phase-guard
hook hard-blocks Edit/Write on source files until pipeline-state.json
records plan_approved: true. Do NOT attempt to set plan_approved: true
without actually presenting a plan to the user via ExitPlanMode. Do NOT
skip the pipeline skill just because a task seems small.
When merging a PR to the integration branch at Phase 4, the flow MUST split
into two scripts — git-pr-create.sh then a user-confirmed git-pr-merge.sh.
Auto-merging without explicit user sign-off is forbidden.
Unified development pipeline. Follow these steps sequentially. Each step MUST complete before proceeding.
Architecture: Clean Architecture (4-layer) is the default for all projects. Dependency rules, layer responsibilities, and TDD scope per layer live in the shared reference skill — see skills/ca-rules/SKILL.md.
Framework & monorepo detection: Delegated to shared reference skills — see skills/framework-detection/SKILL.md and skills/monorepo-detection/SKILL.md.
Mode Detection (Auto-Detect)
After Phase 1 planning, auto-detect execution mode based on task scope. The user can override explicitly ("use sequential mode" / "use team mode").
| Criteria | Mode | Description |
|---|
| 1-5 files, 1-2 features | Sequential | Main agent handles all phases directly |
| 6+ files, 3+ features | Team | Lead + teammate agents via TeamCreate |
Pipeline State Management
The harness enforces Access Control via two state files.
.claude/runtime/pipeline-state.json
Updated at each Phase transition. The phase-guard hook reads this to block source code modifications during plan phase + block the review → validate transition while review issues remain unresolved.
Format:
{
"current_phase": "plan",
"mode": "sequential",
"branch": "feature/xxx",
"plan_approved": false,
"issue_number": null,
"ui_involved": false,
"updated_at": "2026-04-08T10:00:00Z"
}
issue_number: GitHub Issue number. Set during Phase 1 Issue creation. Used for PR Closes #N linking. The harness is GitHub-only — gh auth status is the prerequisite, enforced by gh-auth-check.sh.ui_involved: true if the plan's file list includes Presentation layer files or task description contains UI keywords. Set during Phase 1 Step 4-ui. Read by Phase 2 and Phase 3 to conditionally invoke ux-design-lead.
Phase order: none → discovery → plan → tdd → review → validate → complete
discovery phase: set when Phase 0 (interview) starts. Shares the
phase-guard semantics of plan — source code edits remain hard-blocked. Cleared
only when Phase 0's user-confirmation gate passes and the agent advances
to plan.
plan_approved: Flipped to true automatically by the post-plan-approval.sh PostToolUse:ExitPlanMode hook once the user approves a plan via ExitPlanMode. The phase-guard hook still blocks source-code edits while plan_approved is false.
Do NOT attempt to manually write plan_approved: true from the agent. A system-level safety filter blocks that pattern to prevent agents from skipping plan mode. The hook is the only sanctioned path — it runs in the Claude Code runtime, not the agent context, and cannot fire without a real ExitPlanMode approval event.
Update command (run at each Phase transition — plan_approved is excluded, its hook owns it):
cat > .claude/runtime/pipeline-state.json << EOF
{
"current_phase": "PHASE",
"mode": "MODE",
"branch": "$(git branch --show-current)",
"plan_approved": PLAN_APPROVED,
"issue_number": ISSUE_NUMBER,
"ui_involved": UI_INVOLVED,
"updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
}
EOF
For phase transitions other than plan approval, PLAN_APPROVED should carry forward the current value (read with jq -r '.plan_approved' .claude/runtime/pipeline-state.json).
Phase Execution
Each phase has detailed steps in its reference file. Read the reference for the current phase before starting.
Phase 0 entry point: when /harness:pipeline is first invoked, the main
agent MUST call the Skill tool with skill name interview-protocol before
issuing any AskUserQuestion. Reading references/phase-0-discovery.md is
not a substitute — the 12 Core Rules that govern the entire discovery loop
(Lenses Pool, hedge detection, false-pass guard, etc.) live inside the
skill itself. Skipping this invocation degrades Phase 0 to ad-hoc
questioning and breaks Rule #2 (Ambiguity Count = 0 + coverage confirmed).
| Phase | Reference | Key Actions |
|---|
| 0. Discovery | references/phase-0-discovery.md | Invoke Skill(interview-protocol) first → enumerate ambiguities → AskUserQuestion loop until ambiguity = 0 → write Korean intent summary → user confirmation gate |
| 1. Plan | references/phase-1-plan.md | Load docs, gh auth check, create Issue, create plan, detect mode, create branch + tasks |
| 2. TDD | references/phase-2-tdd.md | Red (unit-test-writer) → Green (implement) → Design apply (ux-design-lead, if UI) → commit |
| 3. Review | references/phase-3-review.md | code-reviewer (2 passes: pass=quality then pass=security) + design-reviewer (ux-design-lead, if UI) → fix issues → commit |
| 4. Validate | references/phase-4-validate.md | E2E test → docs update → PR create + merge (GitHub) or direct merge (Local) → cleanup |
Team Protocol: references/team-protocol.md — teammate execution steps, working rules, communication, merge strategy
TDD-First Reminder (Enforced by tdd-guard Stop Hook)
The tdd-guard Stop hook emits a single cooldown-gated reminder when implementation files are modified without any matching test files in the same TDD window. The reminder fires once per phase and cools down for 30 seconds. There is no retry / Green-completion enforcement — agents are expected to honor the TDD discipline once notified.
Hook Observability — HARNESS_DEBUG=1
Hooks silently exit 0 on many early paths (wrong tool, phase mismatch, missing state file). Set HARNESS_DEBUG=1 to turn every early exit into a [hook] skip: <reason> stderr line — useful when diagnosing "why didn't this hook fire?". No-op when unset.
Wired today: phase-guard.sh. Other hooks opt in by sourcing lib/harness-debug.sh and calling harness_debug <tag> <reason> before each early exit.
Mode Comparison
| Aspect | Sequential | Team |
|---|
| Context usage | All in main | Per teammate |
| Parallelization | None | Full parallel |
| Recovery | Manual | Autonomous + lead |
| Scenario | Recommended Mode |
|---|
| Quick bug fix (1-2 files) | Sequential |
| New component (3-5 files) | Sequential |
| Feature with multiple components (6+) | Team |
| Cross-cutting refactor (10+ files) | Team |
| Exploration / research | Sequential (no workers) |
