@dtlabs/ai-toolkit 0.13.0 → 0.14.0

package/src/claude/skills/implement-feature/SKILL.md

@@ -5,12 +5,9 @@ argument-hint: <path-to-feature.md> [--force]
 
 # Implement Feature
 
-Orchestrates the full feature delivery pipeline by invoking three sequential workflow phases
-(`pm-phase1`, `pm-phase2`, `pm-phase3`), handling approval gates in the main loop between
-each phase, and recording the real token consumption at the end.
+Runs documentation and work breakdown through the deterministic Node workflow host, then implementation through the FTR-018 task executor. Approval gates remain in the main loop.
 
-Each workflow phase runs as a real subagent boundary, ensuring worker agents are dispatched
-with their declared `model:` frontmatter honoured and producing accurate per-agent `usage` data.
+Workflows are JavaScript assets, never agent types. Do not pass pm-phase1/2/3 or am-phase1/2 to agentType, subagent_type, or --agent. Use the workflow CLI below. Resolve the absolute Claude executable path as described in docs/task-executor-bootstrap.md.
 
 ---
 
@@ -58,53 +55,13 @@ Before starting the pipeline, verify that every pipeline agent is installed and
 
 ## Step 1 — Invoke pm-phase1 (Documentation Phase)
 
-### Step 1a — Tier 1 dispatch guard (AC-06, AC-07, AC-20)
-
-Before dispatching, resolve and verify the pm-phase1 orchestrator:
-
-```bash
-ai-toolkit agents resolve \
-  --project . \
-  --id gaia.orchestrator.feature.phase1 \
-  --require-verified
-```
-
-If exit non-zero → **HARD STOP**: report the error, do not dispatch pm-phase1.
-
-Store the resolution record fields: `nativeName`, `sha256` (definitionHash), `scope` (resolutionScope), `toolkitVersion`.
-
-Open the dispatch ledger entry (fail-closed):
-
-```bash
-ai-toolkit ledger open \
-  --prefix {PREFIX} \
-  --agent pm-phase1:dispatch \
-  --phase phase3 \
-  --dir {LEDGER_DIR} \
-  --metadata-json '{"agentId":"gaia.orchestrator.feature.phase1","nativeAgentName":"{nativeName}","platform":"claude","toolkitVersion":"{toolkitVersion}","resolutionScope":"{scope}","definitionHash":"{sha256}"}'
-```
-
-If exit non-zero → **HARD STOP** (fail-closed): do not dispatch.
-
-### Step 1b — Invoke pm-phase1 using verified nativeName
-
-Invoke the workflow using ONLY the resolved `nativeName` (never a hardcoded name):
-
-```
-subagent_type: {nativeName}
-prompt: <path-to-feature.md>
-```
-
-Wait for the workflow to complete. Do NOT proceed until it returns.
-
-After the workflow returns, close the dispatch ledger entry:
+Run directly via the shell tool:
 
 ```bash
-ai-toolkit ledger close \
-  --prefix {PREFIX} --agent pm-phase1:dispatch --dir {LEDGER_DIR}
+ai-toolkit workflow run pm-phase1 --project . --claude-path "{ABSOLUTE_CLAUDE_EXE}" -- "<path-to-feature.md>" [--force]
 ```
 
-If ledger close fails → **HARD STOP**: report the error and do not continue.
+The host verifies the installed workflow and each worker and owns all ledger transitions. Do not manually open/close its entries. Nonzero exit is a HARD STOP: do not present the next gate or report successful completion. Parse stdout as JSON only on exit 0. Never dispatch the workflow as a subagent.
 
 Extract from the result:
 - `prefix` — feature prefix (e.g. `FTR-009`)
@@ -174,40 +131,15 @@ If the file is missing or incomplete, write it again before proceeding.
 
 ## Step 3 — Invoke pm-phase2 (Work Breakdown Phase)
 
-### Step 3a — Tier 1 dispatch guard
-
-Resolve and verify pm-phase2:
+Run directly via the shell tool:
 
 ```bash
-ai-toolkit agents resolve \
-  --project . \
-  --id gaia.orchestrator.feature.phase2 \
-  --require-verified
+ai-toolkit workflow run pm-phase2 --project . --claude-path "{ABSOLUTE_CLAUDE_EXE}" -- "<path-to-feature.md>"
 ```
 
-If exit non-zero → **HARD STOP**: do not dispatch pm-phase2.
-
-Open the dispatch ledger entry (fail-closed):
-
-```bash
-ai-toolkit ledger open \
-  --prefix {PREFIX} \
-  --agent pm-phase2:dispatch \
-  --phase phase3 \
-  --dir {LEDGER_DIR} \
-  --metadata-json '{"agentId":"gaia.orchestrator.feature.phase2","nativeAgentName":"{nativeName}","platform":"claude","toolkitVersion":"{toolkitVersion}","resolutionScope":"{scope}","definitionHash":"{sha256}"}'
-```
-
-If exit non-zero → **HARD STOP** (fail-closed).
-
-### Step 3b — Invoke pm-phase2 using verified nativeName
-
-```
-subagent_type: {nativeName}
-prompt: <path-to-feature.md>
-```
+The host verifies the installed workflow and each worker and owns all ledger transitions. Do not manually open/close its entries. Nonzero exit is a HARD STOP: do not present the next gate or report successful completion. Parse stdout as JSON only on exit 0. Never dispatch the workflow as a subagent.
 
-Wait for the workflow to complete. Extract from the result:
+Extract from the result:
 - `user_stories` — number of User Stories
 - `total_tasks` — total task count
 - `domain_breakdown` — tasks per domain
@@ -216,15 +148,6 @@ Wait for the workflow to complete. Extract from the result:
 - `agent_estimate` — agent parallel estimate
 - `token_ledger` — per-agent token data from phase 2
 
-Close the dispatch ledger entry after the workflow returns:
-
-```bash
-ai-toolkit ledger close \
-  --prefix {PREFIX} --agent pm-phase2:dispatch --dir {LEDGER_DIR}
-```
-
-If ledger close fails → **HARD STOP**: report the error. Do not continue to Gate 2. The error is not swallowed (AC-22).
-
 ---
 
 ## Step 4 — Present Gate 2 (HARD STOP — present in main loop)
@@ -276,7 +199,7 @@ Read back `{PREFIX}-Approvals.md` and verify Gate 2 ✅ is present before contin
 
 ## Step 5 — Create feature branch
 
-Before invoking pm-phase3, create the feature branch:
+Before launching the task executor, create the feature branch:
 
 ```bash
 git checkout -b feature/{PREFIX}-{short-slug}
@@ -290,102 +213,88 @@ git checkout feature/{PREFIX}-{short-slug}
 
 ---
 
-## Step 6 — Invoke pm-phase3 (Implementation Phase)
+## Step 6 — Launch the task executor (Implementation Phase)
 
 Pre-condition check: read `{PREFIX}-Approvals.md` and verify BOTH Gate 1 ✅ and Gate 2 ✅.
 If either is missing, return to the missing gate.
 
-### Step 6a — Tier 1 dispatch guard (Gate 2 post-approval, AC-06, AC-07, AC-08)
+Implementation is no longer dispatched as a subagent from this skill. There is no
+pm-phase3 workflow, no Tier-1 dispatch guard, and no `pm-phase3:dispatch` ledger entry for
+this step — none of that applies once implementation runs as an external process instead of
+an in-chat subagent. Once Gate 2 is approved, this skill's job is limited to presenting or
+launching **one explicit `task-executor` start command**; the executor process itself then
+owns the repo, plans, executes, checkpoints and resumes tasks deterministically, independent
+of this chat.
+
+**No subagent orchestrates the run, and no assistant or agent involvement is required for
+each task transition once the run has started.** This is a deliberate behavioral change from
+the retired pm-phase3 grouping model: previously an assistant-driven subagent had to be
+present for the whole implementation phase; now a single durable command launch is enough,
+and the run may keep going, checkpointing and resuming, even after this conversation ends.
+
+### Step 6a — Present or launch the executor start command
 
-After Gate 2 approval, resolve and verify pm-phase3 with `--require-verified`. Only a `verified` status permits dispatch:
+Build the start command:
 
 ```bash
-ai-toolkit agents resolve \
+ai-toolkit executor start \
   --project . \
-  --id gaia.orchestrator.feature.phase3 \
-  --require-verified
+  --feature <path-to-feature.md> \
+  --max-concurrency 1 \
+  --claude-path <resolved-claude-cli-path> \
+  --task-timeout-ms <task-timeout-ms, e.g. 900000> \
+  --agent-budget-usd <per-agent budget in USD, e.g. 5.00>
 ```
 
-If exit non-zero → **HARD STOP** (AC-08): pm-phase3 is absent or tampered. Report the error with remediation instructions:
+Placeholders:
+- `<path-to-feature.md>` — the feature.md path passed to this skill
+- `<resolved-claude-cli-path>` — the Claude CLI executable path on this host; ask the user if unknown
+- `<task-timeout-ms>` and `<agent-budget-usd>` — must be supplied explicitly; there is no hidden default timeout or spend
 
-```
-⛔ HARD STOP — pm-phase3 cannot be dispatched.
-
-Remediation:
-  1. Run: ai-toolkit agents resolve --project . --id gaia.orchestrator.feature.phase3
-  2. Check the status field in the output for the failure reason.
-  3. Re-install the toolkit if the status is not-installed or hash-mismatch.
-  4. Contact the toolkit team if the issue persists.
+**If the host's ordinary terminal capability can launch a durable external command**, launch
+it directly through that capability so the process persists independently of this chat.
 
-Do NOT use an alternative workflow name or any fallback. This pipeline requires verified agents.
-```
+**If the host cannot launch a durable external command, show the exact command above for the
+user to run themselves in a terminal.** Do not attempt to fake a durable launch by running it
+as a blocking in-chat command — the run must be able to outlive this conversation.
 
-Do NOT use any alternative workflow name or fallback.
+In both cases, capture (or ask the user to report back) the `run-id` printed by `start` — it
+is required for every subsequent `status`, `diagnose`, `stop`, `reconcile`, `resume`, and
+`replan` call; there is no implicit last-run selection.
 
-Open the dispatch ledger entry (fail-closed):
+Tell the user that implementation has been launched and that progress and cost can be
+checked at any time with:
 
 ```bash
-ai-toolkit ledger open \
-  --prefix {PREFIX} \
-  --agent pm-phase3:dispatch \
-  --phase phase3 \
-  --dir {LEDGER_DIR} \
-  --metadata-json '{"agentId":"gaia.orchestrator.feature.phase3","nativeAgentName":"{nativeName}","platform":"claude","toolkitVersion":"{toolkitVersion}","resolutionScope":"{scope}","definitionHash":"{sha256}"}'
+ai-toolkit executor status --run-id {run_id} --format json
 ```
 
-If exit non-zero → **HARD STOP** (fail-closed): do not dispatch.
-
-### Step 6b — Invoke pm-phase3 using verified nativeName
+Do not block this skill on the run reaching a terminal state — proceed to Step 7 with
+whatever the latest `status` reports at this point. No fallback to the retired pm-phase3
+grouping model is permitted.
 
-Invoke the workflow using ONLY the resolved `nativeName` (never a hardcoded name):
-
-```
-subagent_type: {nativeName}
-prompt: <path-to-feature.md> --branch feature/{PREFIX}-{short-slug}
-```
-
-Wait for the workflow to complete. Capture its full result, including the `<usage>` block
-(format: `subagent_tokens: N`). Extract from the result:
-- `pr_url` — the created pull request URL
-- `token_ledger` — all per-agent token data from phase 3
-- `issues_summary` — escalation and issues counts
-
-If `issues_summary.escalations > 0`, report the escalation details to the user.
-
-**If pm-phase3 returned an error or escalation:** mark the dispatch ledger entry failed before stopping:
-
-```bash
-ai-toolkit ledger fail \
-  --prefix {PREFIX} --agent pm-phase3:dispatch \
-  --error "pm-phase3 returned an error or escalation" \
-  --dir {LEDGER_DIR}
-```
+---
 
-If `ledger fail` itself exits non-zero → **HARD STOP** (AC-22): report both the original workflow error and the ledger failure. The error is NOT swallowed.
+## Step 7 — Complete Token Estimate file
 
-**On successful completion:** close the dispatch ledger entry:
+Phases 1 and 2 return JSON token_ledger entries from measured worker subprocess usage. They do not return a workflow subagent usage block. Missing measurements stay unavailable. For phase 3 use the executor:
 
 ```bash
-ai-toolkit ledger close \
-  --prefix {PREFIX} --agent pm-phase3:dispatch --dir {LEDGER_DIR}
+ai-toolkit executor status --run-id {run_id} --format json
 ```
 
-If ledger close fails → **HARD STOP** (AC-22): report the error. The pipeline does not silently swallow ledger failures after dispatch returns.
-
----
+Read the run's total actual tokens/cost and duration from that ledger-sourced summary. If the
+run has not yet reached a terminal state (it may still be executing or may outlive this
+chat), treat its actuals as **not yet available** for this pass — apply the same
+null-compatibility rule below, and note in the file that the run is still in progress and the
+row should be refreshed with a later `status` call.
 
-## Step 7 — Complete Token Estimate file
-
-From the `<usage>` block of the pm-phase3 result, read:
-- `subagent_tokens` — total tokens consumed by the pm-phase3 workflow
-- `duration_ms` — wall-clock duration of pm-phase3
-
-Read `{PREFIX}-Token-Estimate.md`. Append the orchestrator row and grand total:
+Read `{PREFIX}-Token-Estimate.md`. Append the executor run row and grand total:
 
 > **Null-compatibility — actuals reading and cost calculation:** Treat a token value of `null`, `0`, or `not_available` as **data unavailable** — never as a real, observable zero consumption. Render unavailable values as `—` in the Actual tokens and Actual cost columns; exclude them from sums, averages, and grand totals. Preventing resume clobber and legacy misinterpretation requires that no unavailable measurement is coerced into a real zero.
 
 ```markdown
-| pm-phase3 (orchestrator) | — | sonnet | 80,000 (estimated) | {subagent_tokens} (actual) | ±{delta} | {duration} |
+| task-executor (run {run_id}) | — | — | 80,000 (estimated) | {ledger_actual_tokens} (actual) | ±{delta} | {ledger_duration} |
 
 ---
 
@@ -393,8 +302,8 @@ Read `{PREFIX}-Token-Estimate.md`. Append the orchestrator row and grand total:
 
 | Agent | Task / Scope | Model | Est. tokens | Actual tokens | Delta | Est. cost ($) | Actual cost ($) | Duration |
 |-------|-------------|-------|------------|---------------|-------|--------------|----------------|----------|
-{one row per entry in token_ledger — from phase 1, 2, and 3; for any entry where actual tokens is null, 0, or not_available show — in Actual tokens and Actual cost and exclude that row from totals}
-| pm-phase3 (orchestrator) | — | sonnet | 80,000 | {subagent_tokens} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
+{one row per entry in token_ledger from phase 1 and 2, plus per-task ledger entries recorded by the executor run for phase 3; for any entry where actual tokens is null, 0, or not_available show — in Actual tokens and Actual cost and exclude that row from totals}
+| task-executor (run {run_id}) | — | — | 80,000 | {ledger_actual_tokens} | ±{delta} | $0.4320 | ${ledger_actual_cost} | {ledger_duration} |
 
 ## Estimation accuracy by agent type
 
@@ -412,9 +321,9 @@ Read `{PREFIX}-Token-Estimate.md`. Append the orchestrator row and grand total:
 ```
 
 > Per-agent values marked *(proportional)* are estimated distributions of the phase total.
-> Phase totals and grand total are exact measurements from workflow subagent_tokens.
+> Phase 1/2 actuals come from worker usage in token_ledger; implementation actuals come from the task executor ledger. Missing measurements remain unavailable.
 
-If the Token Estimate file does not exist (pm-phase3 failed before writing it), create it
+If the Token Estimate file does not exist (a prior phase failed before writing it), create it
 from scratch using the data available in the token_ledger.
 
 ---
@@ -424,8 +333,14 @@ from scratch using the data available in the token_ledger.
 After writing the token file, report:
 
 ```
-Feature pipeline complete.
+Feature pipeline complete through implementation launch.
    Token estimate + actuals → {PREFIX}-Token-Estimate.md
    Effort estimate + actuals → {PREFIX}-Effort-Estimate.md
-   Pull Request → {pr_url}
+   Implementation run       → run-id {run_id} (check with `ai-toolkit executor status --run-id {run_id}`)
 ```
+
+Unlike the retired pm-phase3 model, this skill does not itself produce a pull request: the
+executor's scope is task execution, checkpointing and branch integration, not PR creation.
+Once `executor status` reports the run has reached a terminal, fully-integrated state, open
+the pull request the same way you would for any other finished branch (e.g. `gh pr create`,
+or the toolkit's own `/pr-description` skill).