taskforge-execute

name	taskforge-execute
description	Executes the next available task. Use when the user says "/taskforge-execute", "next task", "run", "go ahead", or similar. v2 changes: contextManifest-based file loading, few-shot reference injection, CoT template injection, guardrail enforcement, telemetry logging, silent error detection.

Execute — Task Execution (v2)

Find the next executable task and run it.

v2 key changes:

1. contextManifest: Read files in priority order before execution (not ad-hoc).
2. Reference injection: Automatically include references/ files listed in task.
3. CoT template: Inject cotTemplate if specified — reasoning scaffold before action.
4. Guardrails: Enforce maxTurns / maxCostUSD / maxWallTimeMin. Stop and report if exceeded.
5. Silent error detection: Scan output for TODOs, stubs, placeholders before marking done.
6. Telemetry: Append events to telemetry.jsonl.

Core principle: Clean context, clear plan, right model, right references.

Prerequisites

• project-plan.json (status: approved) under _workspace/projects/{projectId}/
• execution-state.json exists
• Project selection: auto if one project, ask if multiple
• All paths relative to _workspace/projects/{projectId}/

Step 0: Task Size Gate (v2)

Before executing, check if the incoming request is actually a plan task or an ad-hoc request:

Signal	Route
Explicit task ID (e.g. "M1-S1-T2")	Execute that task
User says "next task" / "go"	Find next task from plan
User describes a tiny change ("just fix X")	Suggest /taskforge-quick
User describes multi-milestone feature	Suggest /taskforge-discover

This gate prevents execute from being used for work that belongs in a different route.

Execution Flow

1. Select Next Task

Find the next task to run:

• Earliest task in dependency order with all dependencies completed
• Exclude: completed / failed / skipped / locked tasks
• Lock check: Read locks/{task-id}.lock — skip if exists and < 30 min old

Task Locking:

{
  "sessionId": "{timestamp}-{random}",
  "acquiredAt": "2026-04-20T10:30:00Z",
  "taskId": "M1-S1-T3",
  "expiresAt": "2026-04-20T11:00:00Z"
}

Write lock → execute → release lock (always, even on failure).

Wave parallelism: If multiple tasks share same wave number and all deps satisfied:

• "Wave {n}에 병렬 실행 가능한 태스크가 {count}개 있어요. 동시에 실행할까요?"
• On yes: run in parallel via Agent tool (each acquires own lock)

2. Assemble Context (v2 contextManifest)

Read files in the order specified in the task's contextManifest, highest priority first:

Priority 0: vision.json          ← project why / constraints
Priority 1: concept.json         ← core loop / tech direction
Priority 2: conventions.md       ← naming, colors, patterns
Priority 3: references/*.html    ← few-shot examples
Priority 4: decisions/D*.md      ← relevant decisions
Priority 5: handoffs/{prev}.json ← what previous task did

What gets injected (in order):

1. contextManifest files (priority order)
2. Task plan (the plan field — specific how-to)
3. CoT template if cotTemplate is set (reasoning scaffold)
4. Domain skills if skills is non-empty
5. acceptanceCriteria (what done looks like)
6. Guardrail limits (what to stop at)

What does NOT get injected:

• Full conversation history
• Other tasks' details
• Logs from unrelated sessions

CoT template injection (hidden from user): If cotTemplate is set, prepend the scaffold to the execution prompt:

이 작업을 시작하기 전에 다음 순서로 생각해보세요:
1. {step 1}
2. {step 2}
3. {step 3}
그 다음 구현을 시작하세요.

User sees the AI thinking through steps — they don't need to know it's a CoT template.

3. Guardrail Check (v2)

Before starting, record guardrail limits from task:

{ "maxTurns": 20, "maxCostUSD": 2.0, "maxWallTimeMin": 35 }

During execution, monitor:

• If maxTurns exceeded: stop, save state, report:

  ⚠️ 이 작업이 예상보다 복잡해요. 지금까지 한 것을 저장하고 멈출게요.
  계속하려면 /taskforge-execute, 건너뛰거나 분할하려면 /taskforge-plan-edit.
  

• If maxCostUSD exceeded: same stop behavior.
• If maxWallTimeMin exceeded: same stop behavior.

Log to telemetry.jsonl:

{"t":"...","event":"guardrail_triggered","taskId":"M1-S1-T3","type":"maxTurns","value":22,"limit":20}

4. Model Routing

Use the task's model field for the code-writing model:

• haiku: simple, fast, cheap
• sonnet: general and complex (both medium and hard)

Opus is never used for code-writing. It is reserved for judgment work — planning, propagation, orchestration, cross-context analysis. The split is by work type, not by step name. If a step inside execution turns out to be a judgment step (see harness mode below), opus may run it; the worker that writes the actual code stays on haiku/sonnet.

5. Execute

single mode

Execute task plan directly with the task's model (haiku/sonnet). Write code, create/modify files.

single + skills mode

Same as single, but inject domain skills from skills field. Load from harnesses/*/skills/{skill-name}/skill.md.

harness mode

Two-tier model split:

• Orchestrator: opus. Loads the harness, coordinates the team, dispatches sub-tasks, cross-validates outputs, handles errors. This is judgment work — model routing here is opus regardless of the task's model field.
• Worker agents: haiku/sonnet. Each worker that actually writes code/content runs on the task's model field (or the per-agent model defined in the harness). Opus never writes the worker output directly.

This mirrors the project-wide rule: judgment → opus, code-writing → haiku/sonnet.

6. Self-Review

After writing code, re-read changed files and check:

• Does code match the task plan?
• Are acceptance criteria actually met?
• Any obvious bugs, missing imports, broken references?

7. Silent Error Detection (v2)

Before marking done, scan all changed files for:

Pattern	Type
TODO / FIXME / HACK	Incomplete work
Empty function bodies {} / pass	Stub
"Lorem ipsum" / "placeholder" / "dummy"	Placeholder content
console.log / print( / debugger	Debug code
Hardcoded secrets (password=, api_key=)	Security risk

If found, show with this format (one line per finding):

⚠️ 완료 전 확인이 필요해요:
  - {file}:{line} — {issueType}: {description}
  - {file}:{line} — {issueType}: {description}

수정하고 다시 확인할까요?

Auto-fix if simple. Report to user if cannot auto-fix.

8. Acceptance Criteria Validation

Show each criterion's check result:

완성 기준 확인:
  ✅ {criterion as written in plan}
  ✅ {criterion as written in plan}
  ❌ {criterion as written in plan} → {what's missing}

If any fail: auto-fix once. If still failing after retry: report to user.

9. Platform Validation

Use validationStrategy from spec-card:

• Run build, typecheck, lint, run per spec-card config
• If manual validation needed: present checklist to user

10. Completion Processing

1. Telemetry: Append to telemetry.jsonl:

   {"t":"...","event":"task_end","taskId":"M1-S1-T3","outcome":"pass","retryCount":0,"tokens":12450,"costUSD":0.42,"wallMin":18,"referencesInjected":["ui-pattern.html"],"cotUsed":false}
   

2. Generate Handoff: Save handoffs/{task-id}.json with this schema:

   {
     "taskId": "{task-id}",
     "completedAt": "{ISO-8601 timestamp}",
     "whatChanged": ["{file path} {created|modified|deleted}", "..."],
     "decisionsMade": ["{decision id and summary}", "..."],
     "hintsForNext": "{any context the next task should know — or empty string}",
     "openItems": ["{known incomplete piece}", "..."],
     "silentErrors": [],
     "guardrailEvents": []
   }
   

   Fill all values from the actual task outcome — do not invent details. Handoff is always generated (not conditional). Only tiny quick-fix tasks skip handoff.
3. Platform validation: Run per spec-card strategy
4. Acceptance criteria check: All must pass
5. Update execution-state.json: ready → in_progress → completed
6. Release task lock: Delete locks/{task-id}.lock
7. Report with this template:

   ✅ 완료: "{taskName}" ({difficultyLabel}, {duration}, ${cost})
      변경 파일: {files joined by comma}
      검증: {check name} ✅ {check name} ✅
      완성 기준: {passed}/{total} ✅
      
      다음: "{nextTaskName}" [{difficultyLabel}/{model}]
      → /taskforge-execute로 계속, /taskforge-status로 전체 진행 확인
   

11. On Failure

Auto-retry (built-in):

1. Add failure reason to context: "이전 시도가 [이유]로 실패했어요. 이 방법은 피해보세요."
2. Re-execute in same session
3. After 2 failures: stop and ask:

   ⚠️ 이 작업이 2번 실패했어요.
   실패 이유: [요약]
   
   선택:
   - 다시 시도 (다른 방법으로)
   - 건너뛰기
   - 직접 수정 후 /taskforge-execute 계속
   

Log to telemetry:

{"t":"...","event":"task_end","taskId":"...","outcome":"failed","retryCount":2,"failureReason":"..."}

Sprint/Milestone Completion Detection

After task completes, if all sprint tasks done:

• "스프린트 [이름] 완료! /taskforge-validate로 통합 검증을 실행해보세요."

If all milestone tasks done:

• "마일스톤 [이름] 완료! /taskforge-validate milestone으로 최종 검증을 먼저 하고, /taskforge-playtest로 직접 확인해보세요."