@dtlabs/ai-toolkit 0.12.0 → 0.14.0

package/src/claude/commands/next-task.md

@@ -23,14 +23,14 @@ Steps:
 
    Suggested agent: <subagent_type>
    Suggested invocation:
-     subagent_type: <developer-backend | developer-frontend | developer-testing>
+     subagent_type: <gaia-developer-backend | gaia-developer-frontend | gaia-developer-testing>
      prompt: <feature-md-path> <task-id>
    ```
 
    Domain → agent mapping:
-   - `DB`, `BE`, `INFRA` → `developer-backend`
-   - `FE` → `developer-frontend`
-   - `TEST` → `developer-testing`
+   - `DB`, `BE`, `INFRA` → `gaia-developer-backend`
+   - `FE` → `gaia-developer-frontend`
+   - `TEST` → `gaia-developer-testing`
 
 5. If no unblocked task remains, output: `✅ All tasks are either done, in progress, or blocked. Check blockers.`
 

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} |
-...
-| assessment-manager/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/define-feature/SKILL.md

@@ -3,10 +3,10 @@ description: "Define Feature — reads existing repo context, then grills only o
 disable-model-invocation: true
 ---
 
-Spawn the `define-feature` agent, passing through whatever the user provided as a source reference (a backlog entry, ticket path, spec path, or free-text description). If the user gave nothing, pass an empty source.
+Spawn the `gaia-define-feature` agent, passing through whatever the user provided as a source reference (a backlog entry, ticket path, spec path, or free-text description). If the user gave nothing, pass an empty source.
 
 ```
-subagent_type: define-feature
+subagent_type: gaia-define-feature
 prompt: |
   Start the feature definition session.
   Source reference (may be empty): {{user arguments verbatim}}

package/src/claude/skills/hi-gaia/SKILL.md

@@ -37,7 +37,7 @@ Here's what I know and what's available for you:
 - `/feature-status`, `/check-docs`, `/next-task`, `/pr-description`
 - `/assessment-status`
 
-**Specialized agents** (spawnable): project-manager, developer-backend, developer-frontend, developer-testing, review-solution, assessment-manager, and more.
+**Specialized agents** (spawnable): developer-backend, developer-frontend, developer-testing, review-solution, and more.
 
 Let me take a look at your workspace to understand the context…
 

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

@@ -5,25 +5,63 @@ 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.
+
+---
+
+## Step 0 — Agent Preflight (fail-closed, AC-19)
+
+Before starting the pipeline, verify that every pipeline agent is installed and verified.
+
+1. **Derive the feature prefix** from the `<path-to-feature.md>` argument (e.g. path contains `FTR-017` → prefix = `FTR-017`). Derive the ledger directory as the directory containing the feature.md file.
+
+2. **Open the preflight ledger entry** (fail-closed — if this fails, do NOT proceed):
+   ```bash
+   ai-toolkit ledger open \
+     --prefix {PREFIX} \
+     --agent agent-preflight:implement-feature \
+     --phase phase3 \
+     --dir {LEDGER_DIR}
+   ```
+   If the command exits non-zero, **STOP IMMEDIATELY** — report the error and do not continue.
+
+3. **Run the preflight check:**
+   ```bash
+   ai-toolkit agents preflight --project . --pipeline implement-feature
+   ```
+
+4. **On success** (exit 0): close the ledger entry:
+   ```bash
+   ai-toolkit ledger close \
+     --prefix {PREFIX} \
+     --agent agent-preflight:implement-feature \
+     --dir {LEDGER_DIR}
+   ```
+   Then continue to Step 1.
+
+5. **On failure** (exit non-zero): mark the ledger entry failed and STOP:
+   ```bash
+   ai-toolkit ledger fail \
+     --prefix {PREFIX} \
+     --agent agent-preflight:implement-feature \
+     --error "agent preflight failed — one or more pipeline agents unverified" \
+     --dir {LEDGER_DIR}
+   ```
+   Report the preflight error to the user. Do NOT continue to Step 1.
 
 ---
 
 ## Step 1 — Invoke pm-phase1 (Documentation Phase)
 
-Invoke the `pm-phase1` workflow with the feature path:
+Run directly via the shell tool:
 
-```
-subagent_type: pm-phase1
-prompt: <path-to-feature.md>
+```bash
+ai-toolkit workflow run pm-phase1 --project . --claude-path "{ABSOLUTE_CLAUDE_EXE}" -- "<path-to-feature.md>" [--force]
 ```
 
-Wait for the workflow to complete. Do NOT proceed until it returns.
+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`)
@@ -93,14 +131,15 @@ If the file is missing or incomplete, write it again before proceeding.
 
 ## Step 3 — Invoke pm-phase2 (Work Breakdown Phase)
 
-Invoke the `pm-phase2` workflow:
+Run directly via the shell tool:
 
-```
-subagent_type: pm-phase2
-prompt: <path-to-feature.md>
+```bash
+ai-toolkit workflow run pm-phase2 --project . --claude-path "{ABSOLUTE_CLAUDE_EXE}" -- "<path-to-feature.md>"
 ```
 
-Wait for the workflow to complete. Extract from the result:
+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:
 - `user_stories` — number of User Stories
 - `total_tasks` — total task count
 - `domain_breakdown` — tasks per domain
@@ -160,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}
@@ -174,40 +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.
 
-Invoke the `pm-phase3` workflow:
+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
+
+Build the start command:
+
+```bash
+ai-toolkit executor start \
+  --project . \
+  --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>
 ```
-subagent_type: pm-phase3
-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
+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
+
+**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.
+
+**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.
+
+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.
 
-If `issues_summary.escalations > 0`, report the escalation details to the user.
+Tell the user that implementation has been launched and that progress and cost can be
+checked at any time with:
+
+```bash
+ai-toolkit executor status --run-id {run_id} --format json
+```
+
+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.
 
 ---
 
 ## 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
+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 executor status --run-id {run_id} --format json
+```
+
+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.
 
-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
-| project-manager/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} |
 
 ---
 
@@ -215,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}
-| project-manager/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
 
@@ -234,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.
 
 ---
@@ -246,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).

package/src/claude/skills/init-agents/SKILL.md

@@ -4,10 +4,10 @@ argument-hint: "[path-to-project-root]"
 disable-model-invocation: true
 ---
 
-Spawn the `init-agents-md` agent with the arguments provided by the user:
+Spawn the `gaia-init-agents-md` agent with the arguments provided by the user:
 
 ```
-subagent_type: init-agents-md
+subagent_type: gaia-init-agents-md
 prompt: [path-to-project-root]
 ```
 

package/src/claude/skills/install-toolkit/SKILL.md

@@ -4,10 +4,10 @@ argument-hint: "[path-to-destination] [--force]"
 disable-model-invocation: true
 ---
 
-Spawn the `install-toolkit` agent with the arguments provided by the user:
+Spawn the `gaia-install-toolkit` agent with the arguments provided by the user:
 
 ```
-subagent_type: install-toolkit
+subagent_type: gaia-install-toolkit
 prompt: <path-to-destination> [--force]
 ```