@open-agent-toolkit/cli 0.0.66 → 0.0.69

package/assets/docs/contributing/skills.md

@@ -21,6 +21,7 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - Keep prerequisites and expected artifacts concrete.
 - Spell out blocked vs allowed activities for state-advancing skills.
 - Define user-facing progress indicators for longer workflows.
+- Define a pre-work capability and authorization gate for skills that delegate to subagents, workers, or reviewers.
 - Keep output obligations explicit so downstream skills and users know what changed.
 
 ## Contract components
@@ -28,6 +29,7 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - Mode assertion (purpose, blocked/allowed activities)
 - Preconditions and required artifacts
 - User-facing progress indicator expectations
+- Delegation capability detection and fallback behavior, when the skill dispatches helper agents
 - Output obligations
 - Escalation/guardrail behavior
 
@@ -59,6 +61,21 @@ Skill behavior is defined by frontmatter plus the process contract in each `SKIL
 - Use `create-agnostic-skill` when you want a reusable workflow skill that is not OAT-specific.
 - Use existing lifecycle skills as examples for progress banners, prerequisites, and artifact updates.
 
+## Delegation-Capable Skills
+
+Skills that dispatch subagents, workers, reviewers, or fresh-context helper sessions need a capability model before work starts. Do not assume delegation is available, and do not silently downgrade just because the runtime needs user authorization.
+
+At minimum, the skill contract should:
+
+- Probe whether the host can dispatch the required helper role(s).
+- Distinguish `available`, `authorization required`, and `not resolved`.
+- Ask once at skill start when authorization is required, with the approval scope stated clearly.
+- Lock the selected tier for the run unless the user explicitly changes execution mode.
+- Stop before side effects if delegation is required for correctness and authorization remains unresolved.
+- Document the fallback path and any quality or independence tradeoff.
+
+Use `create-agnostic-skill` or `create-oat-skill` as the starting point; both include the current delegation guidance and optional capability-detection template.
+
 ## Reading project state
 
 Skills that need fields from the active project's `state.md` (e.g. `phase`, `phaseStatus`, `workflowMode`, `docsUpdated`, `lastCommit`) MUST query the CLI instead of hand-parsing YAML with `grep`/`awk`.

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.66",
-  "docs-config": "0.0.66",
-  "docs-theme": "0.0.66",
-  "docs-transforms": "0.0.66"
+  "cli": "0.0.69",
+  "docs-config": "0.0.69",
+  "docs-theme": "0.0.69",
+  "docs-transforms": "0.0.69"
 }

package/assets/skills/create-agnostic-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-agnostic-skill
-version: 1.2.1
+version: 1.3.0
 description: Use when adding a reusable workflow skill for AI coding agents. Scaffolds a new .agents/skills skill using the Agent Skills open standard.
 argument-hint: '[skill-name]'
 disable-model-invocation: true
@@ -60,6 +60,7 @@ If not provided in arguments, ask for:
 - **Model invocation**: Should the agent be able to invoke this automatically? (default: no)
 - **User invocable**: (Claude Code only) Should this appear in the `/` menu? (default: yes)
 - **Tool restrictions**: (Claude Code only) Which tools should the skill be allowed to use?
+- **Delegation**: Will the skill dispatch subagents or require a fresh-context worker/reviewer? If yes, define the capability probe, authorization gate, fallback tier, and approval scope.
 - **Supporting files**: Does the skill need templates, scripts, or reference files?
 
 ### Step 2: Apply Progressive Disclosure
@@ -295,9 +296,62 @@ Do **not** hard-code a specific Codex question tool name in skill prose unless t
 
 **When NOT to:**
 
-- Autonomous/subagent skills — use argument defaults or flags to drive decisions instead of prompting mid-execution
+- Long-running autonomous skills after work has started — resolve required decisions in a pre-work gate, then lock the choice for the run
 - Questions with open-ended answers — just ask conversationally in the skill prose
 
+### Delegation and Subagent Capability
+
+Skills that dispatch subagents, reviewers, workers, or fresh-context helper sessions must define a pre-work capability model. Do not let generated skills assume delegation is available, silently downgrade because authorization is required, or ask repeated approval questions mid-run.
+
+**When to include this section:**
+
+- The skill uses provider subagents, task workers, reviewers, or multi-agent execution
+- The skill's quality depends on fresh context or isolated review/implementation
+- The skill has a fallback mode when delegation is unavailable
+
+**Required guidance for delegation-capable skills:**
+
+1. **Probe before work starts.** Check whether the host can dispatch the needed worker/reviewer and whether dispatch requires user authorization.
+2. **Separate capability states.** Report `available`, `authorization required`, or `not resolved`; do not treat authorization-required as unavailable.
+3. **Ask once when authorization is required.** Use a concise question that names the delegation scope for the run. Approval should cover the stated worker roles and phases; a decline should select the documented fallback.
+4. **Lock the tier.** Once selected, keep the execution mode for the run unless the user explicitly changes it.
+5. **Fail closed before side effects.** If delegation is required for correctness and authorization is unresolved, stop before edits, writes, external side effects, or long-running work.
+6. **Document fallback behavior.** If inline or single-agent execution is acceptable, explain when it applies. If it changes quality, artifact freshness, or review independence, say so.
+
+**Portable provider wording:**
+
+- Claude Code: use Task/subagent dispatch when available; if the skill benefits from structured prompts, include `AskUserQuestion` in `allowed-tools`.
+- Cursor: use the provider's explicit agent invocation or natural-language agent handoff when supported.
+- Codex: use multi-agent spawning when available; if the host requires explicit user authorization before spawning, ask before falling back.
+- Fallback: use inline/single-agent execution only when the user declines delegation or the runtime truly cannot dispatch the required agent.
+
+**Good pre-work pattern:**
+
+```markdown
+### Step 0.5: Capability Detection
+
+Before edits, writes, external side effects, or long-running work, detect whether the required helper agents are available.
+
+- Available without authorization → Tier 1: delegated execution.
+- Authorization required → ask once: "Authorize `{worker/reviewer}` delegation for this run?"
+  - Approved → Tier 1.
+  - Declined → Tier 2: documented fallback.
+- Not resolved / unsupported → Tier 2: documented fallback.
+
+Report:
+
+`Selected: Tier {1|2} — {Delegated|Fallback}; Reason: {available|authorized|user declined delegation|dispatch unavailable|required role unresolved}`
+
+Lock the selected tier for the run.
+```
+
+**Anti-patterns:**
+
+- Selecting inline fallback just because the user did not pre-mention subagents, when the skill itself requires delegation and authorization can be requested
+- Asking for authorization after implementation or review has already started
+- Re-asking for each phase when the first approval explicitly covered the run
+- Hiding fallback quality differences from the user
+
 ### Progress Feedback
 
 For multi-step skills, print brief progress updates so the user knows what's happening:

package/assets/skills/create-agnostic-skill/references/skill-template.md

@@ -13,11 +13,12 @@ Adjust based on complexity—not all sections are required:
 5. **Arguments** - Parameters parsed from `$ARGUMENTS`
 6. **Prerequisites** - Required setup or context (if applicable)
 7. **Workflow/Steps** - Numbered steps using "Step 1, 2, 3..." naming
-8. **Quality Standards** - Checklist format for docs skills (if applicable)
-9. **Examples** - Both "Basic Usage" and "Conversational" styles
-10. **Reference** - Links to relevant documentation
-11. **Troubleshooting** - Common issues and solutions
-12. **Success Criteria** - Checklist of completion conditions
+8. **Capability Detection** - Required before work starts if the skill dispatches subagents/workers/reviewers
+9. **Quality Standards** - Checklist format for docs skills (if applicable)
+10. **Examples** - Both "Basic Usage" and "Conversational" styles
+11. **Reference** - Links to relevant documentation
+12. **Troubleshooting** - Common issues and solutions
+13. **Success Criteria** - Checklist of completion conditions
 
 ## Annotated Template
 
@@ -87,6 +88,24 @@ Parse from `$ARGUMENTS`:
 
 ## Workflow
 
+<!-- Include this Step 0.5 only if the skill dispatches subagents, workers, reviewers, or fresh-context helpers. -->
+
+### Step 0.5: Capability Detection
+
+Before edits, writes, external side effects, or long-running work, detect whether required helper agents are available.
+
+- Available without authorization → Tier 1: delegated execution.
+- Authorization required → ask once: "Authorize `{worker/reviewer}` delegation for this run?"
+  - Approved → Tier 1.
+  - Declined → Tier 2: documented fallback.
+- Not resolved / unsupported → Tier 2: documented fallback.
+
+Report the selected tier and reason before starting work:
+
+`Selected: Tier {1|2} — {Delegated|Fallback}; Reason: {available|authorized|user declined delegation|dispatch unavailable|required role unresolved}`
+
+Lock the selected tier for the run unless the user explicitly changes it.
+
 ### Step 1: First Step Title
 
 Clear instructions in imperative form. Tell the agent what to do.

package/assets/skills/oat-project-complete/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-complete
-version: 1.4.5
+version: 1.4.7
 description: Use when all implementation work is finished and the project is ready to close. Marks the OAT project lifecycle as complete.
 disable-model-invocation: true
 user-invocable: true
@@ -27,7 +27,7 @@ When executing this skill, provide lightweight progress feedback so the user can
   - `[3/6] Completing lifecycle…`
   - `[4/6] Generating PR description + archiving…`
   - `[5/6] Refreshing dashboard + committing…`
-  - `[6/6] Opening PR…`
+  - `[6/6] Opening PR or syncing description…`
 
 ## Process
 
@@ -64,6 +64,17 @@ Ask all user questions at once so the user can answer them in a single interacti
 
 Before asking the batched questions, read `oat_pr_status` and `oat_pr_url` from `state.md` frontmatter.
 
+**Capture pre-mutation PR state for later steps.** The skill mutates `state.md` (Step 5) and the project tree (Step 8) before Step 11.5 needs to know whether the PR was already open at the start. Persist that decision in a shell variable now:
+
+```bash
+WAS_PR_OPEN_AT_START="false"
+if [[ "${oat_pr_status:-}" == "open" ]]; then
+  WAS_PR_OPEN_AT_START="true"
+fi
+```
+
+Use the same `state.md` read you already perform for `oat_pr_status`/`oat_pr_url` — do not re-read after Step 5. Step 11.5 (Sync Open-PR Description on GitHub) consumes this value.
+
 **Workflow preference checks (before asking questions):**
 
 Some questions can be answered automatically from workflow preferences. Read each preference before deciding whether to include its question in the batched prompt:
@@ -299,7 +310,29 @@ fi
 
 5. **Write PR description artifact** — write to `{PROJECT_PATH}/pr/project-pr-YYYY-MM-DD.md` following the template and policies from `oat-project-pr-final` Step 4 (frontmatter policy, reference links policy, local path exclusion).
 
-If a PR description artifact already exists at `{PROJECT_PATH}/pr/project-pr-*.md`, skip generation and use the existing one instead.
+If a PR description artifact already exists at `{PROJECT_PATH}/pr/project-pr-*.md`:
+
+- When `SHOULD_ARCHIVE` is `true`, regenerate it (overwrite). The existing artifact was authored by `oat-project-pr-final` before any archive intent existed and links to artifact paths that will be local-only after Step 8. Regenerating ensures Step 11 / Step 11.5 push a body whose links still resolve on the remote.
+- When `SHOULD_ARCHIVE` is `false`, skip generation and use the existing artifact as-is. No archive means the existing blob links remain valid.
+
+**Archive-aware References (required when `SHOULD_ARCHIVE` is `true`):**
+
+When archiving, the project artifacts at `{PROJECT_PATH}/{plan,implementation,discovery,spec,design,summary}.md` will move to a gitignored archive location in Step 8. After commit + push (Step 10), those paths no longer exist on the branch and any blob link to them returns 404 on GitHub. The PR description must anticipate this:
+
+- **Drop References bullets** that point to artifacts about to become local-only:
+  - `plan.md`, `implementation.md`, `discovery.md`, `spec.md`, `design.md`, `summary.md`, `references/imported-plan.md`
+  - Active `reviews/` (the active project tree, including `reviews/`, moves with the archive)
+- **Add a canonical project-record bullet** when `archive.summaryExportPath` is configured and `summary.md` exists:
+  - Resolve the export filename: `${SUMMARY_EXPORT_PATH}/$(date +%Y%m%d)-${PROJECT_NAME}.md` (matches `archive-utils.ts` naming).
+  - Reference it as a tracked, post-archive blob link, e.g.:
+    `- Project record: [${SUMMARY_EXPORT_PATH}/${YYYYMMDD}-${PROJECT_NAME}.md]({REPO_WEB}/blob/{BRANCH}/${SUMMARY_EXPORT_PATH}/${YYYYMMDD}-${PROJECT_NAME}.md)`
+  - Use the **current/head branch** for the blob link (the same `{BRANCH}` value used by `oat-project-pr-final` Step 4 for every other reference). Step 8 creates the export on the current checkout and Step 10 commits + pushes it on the feature branch, so the link resolves immediately while the PR is open and continues to resolve after merge once the file lands on the base branch.
+  - Anti-pattern: do **not** point this link at the base branch (`main` / resolved default branch). The export does not exist on the base branch until the PR merges, so a `blob/main/...` link 404s for the entire window the PR is open — the same class of broken link this whole step exists to prevent.
+  - When `archive.summaryExportPath` is unset or `summary.md` is missing, omit this bullet rather than emit a broken link.
+- **Keep References bullets** that resolve independently of the archive: backlog item links under `.oat/repo/reference/backlog/`, decision-record links under `.oat/repo/reference/decisions/`, repo-reference docs, ticket URLs, and anything else under tracked paths outside the project directory.
+- Apply the existing `localPaths`-based exclusion rule from `oat-project-pr-final` Step 4 on top of these rules — it already covers `.oat/**/pr` and `.oat/**/reviews/archived` and may catch additional patterns configured per repo.
+
+Anti-pattern: do not "rescue" a dropped artifact by linking to its archived path under `.oat/projects/archived/<name>/...`. That path is gitignored on every checkout and never reaches the remote.
 
 ### Step 8: Archive Project (Conditional)
 
@@ -528,6 +561,46 @@ gh pr create --base main --title "{title}" --body-file "$TMP_BODY"
 
 Do not assume `gh` is installed; if missing, instruct manual PR creation using the file contents.
 
+### Step 11.5: Sync Open-PR Description on GitHub (Conditional)
+
+**Run only when `WAS_PR_OPEN_AT_START="true"` AND `SHOULD_ARCHIVE="true"`.**
+
+When the PR was already open at the start of this skill (typically because `oat-project-pr-final` ran earlier in the lifecycle) AND we just archived, the GitHub PR description authored by `oat-project-pr-final` still points to the active artifact paths. Step 8 moved those artifacts to a gitignored archive location and Step 10 pushed the move, so any blob link in the open PR body now 404s. Push the regenerated archive-aware body to the existing PR.
+
+Skip this step when:
+
+- The PR was not yet open at the start (`WAS_PR_OPEN_AT_START="false"`) — Step 11 already created the PR with the archive-aware body.
+- No archive happened (`SHOULD_ARCHIVE="false"`) — the original blob links still resolve.
+- `IS_SHARED_PROJECT="false"` — non-shared projects are not archived in this skill, so no link breakage.
+
+Steps:
+
+1. Locate the PR description artifact at `{PROJECT_PATH}/pr/project-pr-*.md`. After Step 8, `PROJECT_PATH` points at the archived location, so the artifact lives at `{ARCHIVE_PATH}/pr/project-pr-*.md`.
+2. Strip YAML frontmatter (everything from the opening `---` through and including the closing `---`) and write the result to a temporary file. Verify the temp file does not start with YAML frontmatter keys.
+3. Resolve the open PR. Prefer the tracked URL captured in Step 2:
+
+   ```bash
+   PR_REF="${oat_pr_url:-}"
+   if [[ -z "$PR_REF" ]]; then
+     # Fall back to the head branch — gh auto-resolves to the open PR for the current branch.
+     PR_REF=$(git rev-parse --abbrev-ref HEAD)
+   fi
+   ```
+
+4. Push the updated body:
+
+   ```bash
+   gh pr edit "$PR_REF" --body-file "$TMP_BODY"
+   ```
+
+5. Clean up the temp file.
+
+Failure handling:
+
+- If `gh` is missing, warn and print the path to the regenerated artifact body so the user can paste it into the PR manually. Do not fail the skill.
+- If `gh pr edit` fails (e.g. PR was merged between Step 2 and now, or the auth token lacks edit permission), warn and continue. Step 12's completion summary should call out that the PR body was not updated and surface the artifact path so the user can update it manually.
+- Never re-archive or re-commit on failure here — the lifecycle bookkeeping in Step 10 already shipped.
+
 ### Step 12: Confirm to User
 
 Show user:
@@ -538,3 +611,4 @@ Show user:
 - Include commit hash and push result for the bookkeeping changes.
 - If PR was opened: include the PR URL.
 - If `oat_pr_url` is present, show it in the completion summary even when PR creation was skipped because the project already tracked an open PR.
+- If Step 11.5 ran, report whether the PR description was synced (e.g. `PR description synced: <PR URL>`) or warn that the sync failed and surface the artifact path so the user can update it manually.

package/assets/skills/oat-project-next/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-next
-version: 1.0.3
+version: 1.0.4
 description: Use when continuing work on the active OAT project. Reads project state, determines the next lifecycle action, and invokes the appropriate skill automatically.
 disable-model-invocation: true
 user-invocable: true
@@ -178,10 +178,12 @@ Phase-to-skill mapping for HiLL override:
 | Phase     | Skill                  |
 | --------- | ---------------------- |
 | discovery | `oat-project-discover` |
-| spec      | `oat-project-spec`     |
+| spec      | `oat-project-design`   |
 | design    | `oat-project-design`   |
 | plan      | `oat-project-plan`     |
 
+Note: a `spec` HiLL phase only appears in legacy projects scaffolded before requirements confirmation was folded into `oat-project-design`. New projects scaffold with `['discovery', 'design']` HiLL checkpoints, so `spec` falls through to `oat-project-design` here as a graceful migration. The standalone `oat-project-spec` skill remains available as an opt-in for users who want to formalize requirements separately.
+
 Note: `implement` is intentionally omitted. Implementation-phase checkpoints are handled by `oat_plan_hill_phases` in plan.md (plan-phase-level gates), not by the workflow-level `oat_hill_checkpoints` in state.md.
 
 #### Step 3b: Phase Routing Tables
@@ -196,9 +198,9 @@ Otherwise, look up the target skill from the routing table for the current `oat_
 | Current Phase | Phase Status | Boundary Tier        | Target Skill               |
 | ------------- | ------------ | -------------------- | -------------------------- |
 | discovery     | in_progress  | tier 3 (template)    | `oat-project-discover`     |
-| discovery     | in_progress  | tier 2 (substantive) | `oat-project-spec`         |
-| discovery     | complete     | tier 1               | `oat-project-spec`         |
-| spec          | in_progress  | tier 3               | `oat-project-spec`         |
+| discovery     | in_progress  | tier 2 (substantive) | `oat-project-design`       |
+| discovery     | complete     | tier 1               | `oat-project-design`       |
+| spec          | in_progress  | tier 3               | `oat-project-design`       |
 | spec          | in_progress  | tier 2               | `oat-project-design`       |
 | spec          | complete     | tier 1               | `oat-project-design`       |
 | design        | in_progress  | tier 3               | `oat-project-design`       |

package/assets/skills/oat-project-progress/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-progress
-version: 1.2.3
+version: 1.2.4
 description: Use when resuming work, checking status, or unsure which OAT skill to run next. Evaluates project progress and routes to the appropriate next step.
 disable-model-invocation: true
 user-invocable: true
@@ -186,7 +186,7 @@ Read `oat_workflow_mode` from `state.md` frontmatter:
 - In that case, do **not** advance to the next phase even if `oat_phase_status: complete`.
 - Recommend continuing the current phase skill to capture explicit approval:
   - discovery gate pending -> `oat-project-discover`
-  - spec gate pending -> `oat-project-spec`
+  - spec gate pending (legacy projects only — newly scaffolded projects no longer use a spec HiLL gate) -> `oat-project-design`
   - design gate pending -> `oat-project-design`
 
 **Drift detection (apply before routing `implement | in_progress`):**
@@ -226,8 +226,8 @@ Routing matrix by mode:
 | oat_phase | oat_phase_status | Next Skill                                                                                                                                                                                                           |
 | --------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | discovery | in_progress      | Continue `oat-project-discover`                                                                                                                                                                                      |
-| discovery | complete         | `oat-project-spec`                                                                                                                                                                                                   |
-| spec      | in_progress      | Continue `oat-project-spec`                                                                                                                                                                                          |
+| discovery | complete         | `oat-project-design` (folds requirements confirmation in; standalone `oat-project-spec` remains an opt-in alternative)                                                                                               |
+| spec      | in_progress      | `oat-project-design` (legacy phase — design reuses any existing `spec.md`)                                                                                                                                           |
 | spec      | complete         | `oat-project-design`                                                                                                                                                                                                 |
 | design    | in_progress      | Continue `oat-project-design`                                                                                                                                                                                        |
 | design    | complete         | `oat-project-plan`                                                                                                                                                                                                   |
@@ -282,8 +282,8 @@ Workflow:
   oat-project-import-plan       - Import an external markdown plan and normalize plan.md
   oat-project-promote-spec-driven - Promote quick/import project to spec-driven lifecycle
   oat-project-discover          - Start discovery phase (requirements gathering)
-  oat-project-spec              - Create specification from discovery
-  oat-project-design            - Create technical design from spec
+  oat-project-design            - Confirm requirements + create technical design (folds spec authoring inline)
+  oat-project-spec              - Optional standalone specification (most projects skip this — design handles it)
   oat-project-plan              - Create implementation plan from design (spec-driven mode)
   oat-project-implement         - Execute implementation plan (sequential or parallel)
   oat-project-reconcile         - Reconcile manual/human commits with plan tasks

package/dist/commands/project/new/scaffold.js

@@ -18,13 +18,13 @@ const TEMPLATES_BY_MODE = {
 };
 const STATE_TEMPLATE_BY_MODE = {
     'spec-driven': {
-        hillCheckpoints: "['discovery', 'spec', 'design']",
+        hillCheckpoints: "['discovery', 'design']",
         phase: 'discovery',
         status: 'Discovery',
         currentPhase: 'Discovery - Gathering requirements and understanding the problem space',
         artifacts: [
             '- **Discovery:** `discovery.md` (in_progress)',
-            '- **Spec:** `spec.md` (scaffolded template — not started)',
+            '- **Spec:** `spec.md` (scaffolded template — authored inline by `oat-project-design`)',
             '- **Design:** `design.md` (scaffolded template — not started)',
             '- **Plan:** `plan.md` (scaffolded template — not started)',
             '- **Implementation:** `implementation.md` (scaffolded template — not started)',
@@ -34,7 +34,7 @@ const STATE_TEMPLATE_BY_MODE = {
             '- ✓ Downstream lifecycle files scaffolded',
             '- ⧗ Awaiting user input',
         ],
-        nextMilestone: 'Complete discovery and move to specification phase',
+        nextMilestone: 'Complete discovery and move to design phase',
     },
     quick: {
         hillCheckpoints: '[]',

package/dist/commands/state/generate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/state/generate.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AA4GD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvE;AAqaD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CA2C9B"}
+{"version":3,"file":"generate.d.ts","sourceRoot":"","sources":["../../../src/commands/state/generate.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACjC,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CAClD;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,aAAa,CAAC;CACrB;AAED,MAAM,WAAW,mBAAmB;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AA4GD,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAEvE;AA8aD,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC,CA2C9B"}

package/dist/commands/state/generate.js

@@ -207,9 +207,14 @@ function computeNextStep(project, hasProjects, state) {
     if (state.phaseStatus === 'complete' &&
         phaseInHillList(state.phase, state.hillCheckpoints) &&
         !phaseInHillList(state.phase, state.hillCompleted)) {
+        // Spec is no longer a discrete HiLL checkpoint in newly-scaffolded projects —
+        // requirements confirmation is folded into oat-project-design. Legacy
+        // projects whose state.md still lists `spec` in oat_hill_checkpoints route
+        // to oat-project-design here so they finish through the consolidated flow
+        // rather than being pushed back at the deprecated standalone skill.
         const phaseSkillMap = {
             discovery: 'oat-project-discover',
-            spec: 'oat-project-spec',
+            spec: 'oat-project-design',
             design: 'oat-project-design',
             plan: 'oat-project-plan',
             implement: 'oat-project-implement',
@@ -227,12 +232,14 @@ function computeNextStep(project, hasProjects, state) {
             reason: 'Continue discovery phase',
         },
         'spec-driven:discovery:complete': {
-            step: 'oat-project-spec',
-            reason: 'Create specification from discovery',
+            step: 'oat-project-design',
+            reason: 'Confirm requirements and produce design (spec is folded into design)',
         },
+        // Legacy projects whose phase still reads `spec` route to design — the
+        // consolidated oat-project-design skill handles existing spec.md gracefully.
         'spec-driven:spec:in_progress': {
-            step: 'oat-project-spec',
-            reason: 'Continue specification phase',
+            step: 'oat-project-design',
+            reason: 'Continue into design (spec is folded into design — legacy phase)',
         },
         'spec-driven:spec:complete': {
             step: 'oat-project-design',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.0.66",
+  "version": "0.0.69",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -33,7 +33,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.0.66"
+    "@open-agent-toolkit/control-plane": "0.0.69"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",