@dtlabs/ai-toolkit 0.13.0 → 0.14.1

package/src/claude/skills/assess-codebase/SKILL.md

@@ -9,8 +9,7 @@ Orchestrates the full codebase assessment pipeline by invoking two sequential wo
 (`am-phase1`, `am-phase2`), handling the Findings Gate in the main loop between the phases,
 and recording the real token consumption at the end.
 
-Each workflow phase runs as a real subagent boundary, ensuring assessment agents are dispatched
-with accurate per-agent `usage` data and their declared `model:` frontmatter honoured.
+Run workflows through the deterministic Node host. Workflows are not agent types. Resolve the absolute Claude executable path using docs/task-executor-bootstrap.md.
 
 ---
 
@@ -25,16 +24,14 @@ found, or start at `ASSESS-001`. This prefix is used for all output files in thi
 
 Invoke the `am-phase1` workflow:
 
-```
-subagent_type: am-phase1
-prompt: <path> [--scope=<areas>] --prefix ASSESS-NNN [--force]
+```bash
+ai-toolkit workflow run am-phase1 --project . --claude-path "{ABSOLUTE_CLAUDE_EXE}" -- "<path>" [--scope=<areas>] --prefix ASSESS-NNN
 ```
 
 If no path was provided by the user, use `.` (current working directory).
 Always pass `--prefix ASSESS-NNN` with the prefix determined in Step 1.
 
-Wait for the workflow to complete. Capture its full result, including the `<usage>` block
-(format: `subagent_tokens: N`). Extract from the result:
+Wait for exit 0, then parse stdout JSON. A nonzero exit is a HARD STOP; do not present a successful Findings Gate. The host owns ledger transitions. Extract from the result:
 - `prefix` — confirmed assessment prefix
 - `output_dir` — path to `docs/assessments/ASSESS-NNN/`
 - `assessment_summaries` — list of `{ agent, output_file }` for each completed assessment
@@ -46,8 +43,7 @@ Wait for the workflow to complete. Capture its full result, including the `<usag
 - `token_estimate_path` — path to `{PREFIX}-Token-Estimate.md`
 - `errors` — any agent failures during phase 1
 
-If `errors` is non-empty, report them to the user before presenting the Findings Gate.
-Partial assessments are acceptable — present the Findings Gate with available data.
+If any worker fails, stop. Partial assessments must not be represented as a completed workflow.
 
 ---
 
@@ -112,9 +108,8 @@ Capture the flagged identifiers (as a comma-separated string, or "none").
 
 Invoke the `am-phase2` workflow:
 
-```
-subagent_type: am-phase2
-prompt: --prefix {prefix} --output-dir {output_dir} --flagged {flagged_ids} --ack "{acknowledgement_text}"
+```bash
+ai-toolkit workflow run am-phase2 --project . -- "--prefix" "{prefix}" --output-dir "{output_dir}" --flagged "{flagged_ids}" --ack "{acknowledgement_text}"
 ```
 
 Where `{flagged_ids}` is the comma-separated list of INT-NNN identifiers (or "none").
@@ -126,95 +121,6 @@ Wait for the workflow to complete. Extract from the result:
 
 ---
 
-## Step 5 — Complete Token Estimate file
-
-From the `<usage>` block of the am-phase1 result, read:
-- `subagent_tokens` — total tokens consumed by the am-phase1 workflow
-- `duration_ms` — wall-clock duration of am-phase1
-
-If the `<usage>` block is missing: log warning
-`"am-phase1 produced no <usage> block; orchestrator token data unavailable"`
-and set `actual_tokens = "N/A"`.
-
-Read `{token_estimate_path}`. Append the following in order:
-
-### 5a — Orchestrator row (for use in 5b only)
-
-Compute values:
-- Estimated tokens: 80,000 (baseline from estimation model)
-- Estimated cost: $0.4320 — `80,000 × $0.005400 / 1,000` using sonnet blended rate
-- Actual tokens: `subagent_tokens` from `<usage>` block; `"N/A"` if missing
-- Actual cost: `(actual_tokens / 1,000) × 0.005400` at 4 decimal places; `"N/A"` if unavailable
-
-### 5b — Actuals vs Estimate section
-
-Append a horizontal rule (`---`) followed by:
-
-```markdown
-## Actuals vs Estimate
-
-| Agent | Task/Scope | Model | Est. tokens | Actual tokens | Delta | Est. cost ($) | Actual cost ($) | Duration |
-|-------|------------|-------|-------------|---------------|-------|---------------|-----------------|----------|
-| {agent} | {scope} | {model} | {est} | {actual} | {±delta} | {est_cost} | {actual_cost} | {Xmin Ys} |
-...
-| am-phase1 (orchestrator) | — | sonnet | 80,000 | {actual} | ±{delta} | $0.4320 | ${actual_cost} | {duration} |
-```
-
-Column rules:
-- **Delta**: `actual_tokens − est_tokens`; show as `+N` or `−N`. Show `"N/A"` if either missing.
-- **Duration**: convert `duration_ms` to `Xmin Ys` where available; use `"—"` where not.
-- Rows with `"N/A"` actual tokens are still shown but excluded from aggregate calculations.
-
-### 5c — Estimation accuracy by agent type (conditional)
-
-If 2+ distinct model tiers appear with non-N/A actuals, append:
-
-```markdown
-## Estimation accuracy by agent type
-
-| Model | Count | Avg est. tokens | Avg actual tokens | Avg delta | Trend |
-|-------|-------|-----------------|-------------------|-----------|-------|
-| {model} | {N} | {avg_est} | {avg_actual} | {avg_delta} | {trend} |
-```
-
-- One row per model tier (e.g., `haiku`, `sonnet`)
-- Exclude N/A rows from averages
-- **Trend**: `"over-target"` if avg delta > +20% of avg est; `"under-target"` if < −20%; else `"on-target"`
-
-### 5d — Grand Total section
-
-Update the Grand Total section: replace `"partial — updated at pipeline end"` with Final values:
-
-```markdown
-## Grand Total (Final)
-
-| Metric | Estimated | Actual | Delta | Delta % |
-|--------|-----------|--------|-------|---------|
-| Total tokens (all agents) | {sum_est} | {sum_actual} | ±{delta} | {delta_pct} |
-| Total cost ($) | ${sum_est_cost} | ${sum_actual_cost} | ±${delta_cost} | {delta_cost_pct} |
-| Total wall-clock | — | {Xmin Ys} | — | — |
-```
-
-- **Delta %**: `(delta / estimated) × 100` at 1 decimal place; `"N/A"` if estimated is 0
-- Sum all agents' tokens and costs; exclude `"N/A"` rows from sums
-- Cost: 2 decimal places for totals; 4 decimal places for per-row costs
-- The "Remediation" section contains a static note — leave it as-is
-- Wall-clock: convert `duration_ms` from am-phase1 `<usage>` to minutes/seconds
-
----
-
-## Step 6 — Report to user
-
-After writing to the Token Estimate file, report:
-
-```
-Assessment pipeline complete.
-   Token estimate + actuals → {token_estimate_path}
-   Approvals                → {approvals_path}
-   Process log              → {output_dir}/{prefix}-process-log.txt
-
-{summary from am-phase2}
-```
+## Step 5 — Report results
 
-If the Token Estimate file does not exist (am-phase1 failed before writing it):
-note this in the report but do not halt — the skill has completed its work.
+Use the deterministic Token-Estimate and Effort-Estimate files returned by am-phase1, and the summary returned by am-phase2. Worker usage is in token_ledger; missing usage remains unavailable. Do not invent an orchestrator usage block or overwrite the host-generated metrics.

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).