@harness-engineering/cli 1.6.2 → 1.8.0

package/dist/agents/skills/claude-code/harness-accessibility/skill.yaml

@@ -0,0 +1,51 @@
+name: harness-accessibility
+version: "1.0.0"
+description: WCAG accessibility scanning, contrast checking, ARIA validation, and remediation
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_new_feature
+  - on_project_init
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-accessibility
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: scope
+      description: Scope of scan (full, component, page)
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-accessibility
+    path: string
+type: rigid
+phases:
+  - name: scan
+    description: Scan codebase for accessibility issues (WCAG AA baseline)
+    required: true
+  - name: evaluate
+    description: Evaluate severity and categorize findings
+    required: true
+  - name: report
+    description: Generate structured accessibility report
+    required: true
+  - name: fix
+    description: Apply automated fixes for mechanical issues
+    required: false
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-design-system

package/dist/agents/skills/claude-code/harness-autopilot/SKILL.md

@@ -13,18 +13,23 @@
 
 ## Relationship to Other Skills
 
-| Skill                | Role in Autopilot                            |
-| -------------------- | -------------------------------------------- |
-| harness-planning     | Delegated to for phase plan creation         |
-| harness-execution    | Delegated to for task-by-task implementation |
-| harness-verification | Delegated to for post-execution validation   |
-| harness-code-review  | Delegated to for post-verification review    |
+| Skill                | Persona Agent (`subagent_type`) | Role in Autopilot                            |
+| -------------------- | ------------------------------- | -------------------------------------------- |
+| harness-planning     | `harness-planner`               | Delegated to for phase plan creation         |
+| harness-execution    | `harness-task-executor`         | Delegated to for task-by-task implementation |
+| harness-verification | `harness-verifier`              | Delegated to for post-execution validation   |
+| harness-code-review  | `harness-code-reviewer`         | Delegated to for post-verification review    |
 
-Autopilot orchestrates these skills — it never reimplements their logic.
+Autopilot orchestrates these persona agents — it never reimplements their logic. Each agent is dispatched via the Agent tool with the corresponding `subagent_type`, which isolates it to the harness methodology and prevents it from using unrelated skills.
 
 ## Iron Law
 
-**Autopilot delegates, never reimplements.** If you find yourself writing planning logic, execution logic, or review logic inside the autopilot loop, STOP. Delegate to the appropriate skill via subagent.
+**Autopilot delegates, never reimplements.** If you find yourself writing planning logic, execution logic, or review logic inside the autopilot loop, STOP. Delegate to the dedicated persona agent.
+
+**Always use dedicated persona agents, never general-purpose agents.** Every dispatch MUST target the specific harness persona (`harness-planner`, `harness-task-executor`, `harness-verifier`, `harness-code-reviewer`). General-purpose agents see all globally registered skills and may use unrelated workflows instead of the harness methodology.
+
+- **Claude Code:** Use the Agent tool with `subagent_type` set to the persona name.
+- **Gemini CLI:** Use the `run_agent` tool targeting the persona by name, or dispatch via `harness persona run <name>`.
 
 **Human always approves plans.** No plan executes without explicit human sign-off, regardless of complexity level. The difference is whether autopilot generates the plan automatically or asks the human to drive planning interactively.
 
@@ -44,20 +49,32 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### Phase 1: INIT — Load Spec and Restore State
 
-1. **Check for existing state.** Read `.harness/autopilot-state.json`. If it exists and `currentState` is not `DONE`:
+1. **Resolve spec path.** The spec file is provided as an argument, or ask the user for the spec path.
+
+2. **Derive session slug and directory:**
+   - Derive the session slug from the spec path:
+     1. If the path starts with `docs/`, strip the `docs/` prefix. Otherwise, use the full relative path.
+     2. Drop the trailing `.md` extension
+     3. Replace all `/` and `.` characters with `--`
+     4. Lowercase the result
+   - Set `sessionDir = .harness/sessions/<slug>/`
+   - Create the session directory if it does not exist
+
+3. **Check for existing state.** Read `{sessionDir}/autopilot-state.json`. If it exists and `currentState` is not `DONE`:
    - Report: "Resuming autopilot from state `{currentState}`, phase {currentPhase}: {phaseName}."
    - Skip to the recorded `currentState` and continue from there.
 
-2. **If no existing state (fresh start):**
-   - Read the spec file (provided as argument or found via `.harness/handoff.json`). If neither is available, ask the user for the spec path.
+4. **If no existing state (fresh start):**
+   - Read the spec file.
    - Parse the `## Implementation Order` section to extract phases.
    - For each phase heading (`### Phase N: Name`), extract:
      - Phase name
      - Complexity annotation (`<!-- complexity: low|medium|high -->`, default: `medium`)
-   - Create `.harness/autopilot-state.json`:
+   - Create `{sessionDir}/autopilot-state.json`:
      ```json
      {
-       "schemaVersion": 1,
+       "schemaVersion": 2,
+       "sessionDir": ".harness/sessions/<slug>",
        "specPath": "<path to spec>",
        "currentState": "ASSESS",
        "currentPhase": 0,
@@ -78,15 +95,22 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
      }
      ```
 
-3. **Load context.** Read `.harness/learnings.md` and `.harness/failures.md` if they exist. Note any relevant learnings or known dead ends for the current phase.
+5. **Load context.** Read `.harness/learnings.md` and `.harness/failures.md` (global, at `.harness/` root) if they exist. Note any relevant learnings or known dead ends for the current phase.
+
+6. **Load roadmap context.** If `docs/roadmap.md` exists, read it to understand:
+   - Current project priorities (which features are `in-progress`)
+   - Blockers that may affect the upcoming phases
+   - Overall project status and milestone progress
+
+   This provides the autopilot with project-level context beyond the individual spec being executed. If the roadmap does not exist, skip this step — the autopilot operates normally without it.
 
-4. **Transition to ASSESS.**
+7. **Transition to ASSESS.**
 
 ---
 
 ### ASSESS — Determine Phase Approach
 
-1. **Read the current phase** from `autopilot-state.json` at index `currentPhase`.
+1. **Read the current phase** from `{sessionDir}/autopilot-state.json` at index `currentPhase`.
 
 2. **Check if plan already exists.** If `planPath` is set and the file exists, skip to `APPROVE_PLAN`.
 
@@ -97,8 +121,8 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
      | Effective Complexity | Action                                                                                                                                                                                                                               |
      | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-     | `low`                | Auto-plan via subagent. Proceed to PLAN.                                                                                                                                                                                             |
-     | `medium`             | Auto-plan via subagent. Proceed to PLAN. Present with extra scrutiny note.                                                                                                                                                           |
+     | `low`                | Auto-plan via `harness-planner` agent. Proceed to PLAN.                                                                                                                                                                              |
+     | `medium`             | Auto-plan via `harness-planner` agent. Proceed to PLAN. Present with extra scrutiny note.                                                                                                                                            |
      | `high`               | Pause. Tell the user: "Phase {N}: {name} is marked high-complexity. Run `/harness:planning` interactively for this phase, then re-invoke `/harness:autopilot` to continue." Transition to PLAN with `awaitingInteractivePlan: true`. |
 
 4. **Update state** with `currentState: "PLAN"` and save.
@@ -109,22 +133,27 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 **If auto-planning (low/medium complexity):**
 
-1. Dispatch a subagent with the following prompt:
+1. Dispatch a planning agent using the Agent tool:
 
    ```
-   You are running harness-planning for phase {N}: {name}.
-
-   Spec: {specPath}
-   Phase description: {phase description from spec}
-   Previous phase learnings: {relevant learnings from .harness/learnings.md}
-   Known failures to avoid: {relevant entries from .harness/failures.md}
-
-   Follow the harness-planning skill process exactly. Write the plan to
-   docs/plans/{date}-{phase-name}-plan.md. Write .harness/handoff.json when done.
+   Agent tool parameters:
+     subagent_type: "harness-planner"
+     description: "Plan phase {N}: {name}"
+     prompt: |
+       You are running harness-planning for phase {N}: {name}.
+
+       Spec: {specPath}
+       Session directory: {sessionDir}
+       Phase description: {phase description from spec}
+       Previous phase learnings (global): {relevant learnings from .harness/learnings.md}
+       Known failures to avoid (global): {relevant entries from .harness/failures.md}
+
+       Follow the harness-planning skill process exactly. Write the plan to
+       docs/plans/{date}-{phase-name}-plan.md. Write {sessionDir}/handoff.json when done.
    ```
 
-2. When the subagent returns:
-   - Read the generated plan path from `.harness/handoff.json`.
+2. When the agent returns:
+   - Read the generated plan path from `{sessionDir}/handoff.json`.
    - **Apply complexity override check:**
      - Count tasks in the plan.
      - Count `[checkpoint:*]` markers.
@@ -138,7 +167,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 **If awaiting interactive plan (high complexity):**
 
 1. Check if a plan file now exists for this phase (user ran planning separately).
-   - Look for files matching `docs/plans/*{phase-name}*` or check `.harness/handoff.json` for a planning handoff.
+   - Look for files matching `docs/plans/*{phase-name}*` or check `{sessionDir}/handoff.json` for a planning handoff.
 2. If found: update `planPath` in state, transition to `APPROVE_PLAN`.
 3. If not found: remind the user and wait.
 
@@ -170,27 +199,32 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### EXECUTE — Run the Plan
 
-1. **Dispatch execution subagent:**
+1. **Dispatch execution agent using the Agent tool:**
 
    ```
-   You are running harness-execution for phase {N}: {name}.
-
-   Plan: {planPath}
-   State: .harness/state.json
-   Learnings: .harness/learnings.md
-   Failures: .harness/failures.md
-
-   Follow the harness-execution skill process exactly.
-   Update .harness/state.json after each task.
-   Write .harness/handoff.json when done or when blocked.
+   Agent tool parameters:
+     subagent_type: "harness-task-executor"
+     description: "Execute phase {N}: {name}"
+     prompt: |
+       You are running harness-execution for phase {N}: {name}.
+
+       Plan: {planPath}
+       Session directory: {sessionDir}
+       State: {sessionDir}/state.json
+       Learnings (global): .harness/learnings.md
+       Failures (global): .harness/failures.md
+
+       Follow the harness-execution skill process exactly.
+       Update {sessionDir}/state.json after each task.
+       Write {sessionDir}/handoff.json when done or when blocked.
    ```
 
-2. **When the subagent returns, check the outcome:**
+2. **When the agent returns, check the outcome:**
    - **All tasks complete:** Transition to VERIFY.
    - **Checkpoint reached:** Surface the checkpoint to the user in the main conversation. Handle the checkpoint type:
-     - `[checkpoint:human-verify]` — Show output, ask for confirmation, then resume execution subagent.
-     - `[checkpoint:decision]` — Present options, record choice, resume execution subagent.
-     - `[checkpoint:human-action]` — Instruct user, wait for confirmation, resume execution subagent.
+     - `[checkpoint:human-verify]` — Show output, ask for confirmation, then resume execution agent.
+     - `[checkpoint:decision]` — Present options, record choice, resume execution agent.
+     - `[checkpoint:human-action]` — Instruct user, wait for confirmation, resume execution agent.
    - **Task failed:** Enter retry logic (see below).
 
 3. **Retry logic on failure:**
@@ -198,7 +232,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - If `attemptsUsed < maxAttempts`:
      - Increment `attemptsUsed`.
      - Record the attempt (timestamp, error, fix attempted, result).
-     - **Attempt 1:** Read error output, apply obvious fix, re-dispatch execution subagent for the failed task only.
+     - **Attempt 1:** Read error output, apply obvious fix, re-dispatch execution agent for the failed task only.
      - **Attempt 2:** Expand context — read related files, check `learnings.md` for similar failures, re-dispatch with additional context.
      - **Attempt 3:** Full context gather — read test output, imports, plan instructions for ambiguity. Re-dispatch with maximum context.
    - If budget exhausted:
@@ -213,16 +247,22 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### VERIFY — Post-Execution Validation
 
-1. **Dispatch verification subagent:**
+1. **Dispatch verification agent using the Agent tool:**
 
    ```
-   You are running harness-verification for phase {N}: {name}.
+   Agent tool parameters:
+     subagent_type: "harness-verifier"
+     description: "Verify phase {N}: {name}"
+     prompt: |
+       You are running harness-verification for phase {N}: {name}.
+
+       Session directory: {sessionDir}
 
-   Follow the harness-verification skill process exactly.
-   Report pass/fail with findings.
+       Follow the harness-verification skill process exactly.
+       Report pass/fail with findings.
    ```
 
-2. **When the subagent returns:**
+2. **When the agent returns:**
    - **All checks pass:** Transition to REVIEW.
    - **Failures found:** Surface findings to the user. Ask: "Fix these issues before review? (yes / skip verification / stop)"
      - **yes** — Re-enter EXECUTE with targeted fixes (retry budget resets for verification fixes).
@@ -235,16 +275,22 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
 
 ### REVIEW — Code Review
 
-1. **Dispatch review subagent:**
+1. **Dispatch review agent using the Agent tool:**
 
    ```
-   You are running harness-code-review for phase {N}: {name}.
+   Agent tool parameters:
+     subagent_type: "harness-code-reviewer"
+     description: "Review phase {N}: {name}"
+     prompt: |
+       You are running harness-code-review for phase {N}: {name}.
+
+       Session directory: {sessionDir}
 
-   Follow the harness-code-review skill process exactly.
-   Report findings with severity (blocking / warning / note).
+       Follow the harness-code-review skill process exactly.
+       Report findings with severity (blocking / warning / note).
    ```
 
-2. **When the subagent returns:**
+2. **When the agent returns:**
    - **No blocking findings:** Report summary, transition to PHASE_COMPLETE.
    - **Blocking findings:** Surface to user. Ask: "Address blocking findings before completing this phase? (yes / override / stop)"
      - **yes** — Re-enter EXECUTE with review fixes.
@@ -303,7 +349,7 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - "Create a PR? (yes / no)"
    - If yes: assemble commit history, suggest PR title and description.
 
-3. **Write final handoff:**
+3. **Write final handoff** to `{sessionDir}/handoff.json`:
 
    ```json
    {
@@ -326,20 +372,21 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → REVIEW →
    - [skill:harness-autopilot] [outcome:observation] {any notable patterns from the run}
    ```
 
-5. **Clean up state:** Set `currentState: "DONE"` in `autopilot-state.json`. Do not delete the file — it serves as a record.
+5. **Clean up state:** Set `currentState: "DONE"` in `{sessionDir}/autopilot-state.json`. Do not delete the file — it serves as a record.
 
 ## Harness Integration
 
 - **`harness validate`** — Run during INIT to verify project health. Included in every execution task via harness-execution delegation.
 - **`harness check-deps`** — Delegated to harness-execution (included in task steps).
-- **State file** — `.harness/autopilot-state.json` tracks the orchestration state machine. `.harness/state.json` tracks task-level execution state (managed by harness-execution).
-- **Handoff** — `.harness/handoff.json` is written by each delegated skill and read by the next. Autopilot writes a final handoff on DONE.
-- **Learnings** — `.harness/learnings.md` is appended by both delegated skills and autopilot itself.
+- **State file** — `.harness/sessions/<slug>/autopilot-state.json` tracks the orchestration state machine. `.harness/sessions/<slug>/state.json` tracks task-level execution state (managed by harness-execution). The slug is derived from the spec path during INIT.
+- **Handoff** — `.harness/sessions/<slug>/handoff.json` is written by each delegated skill and read by the next. Autopilot writes a final handoff on DONE.
+- **Learnings** — `.harness/learnings.md` (global) is appended by both delegated skills and autopilot itself.
+- **Roadmap context** — During INIT, reads `docs/roadmap.md` (if present) for project-level priorities, blockers, and milestone status. Provides broader context for phase execution decisions.
 
 ## Success Criteria
 
 - Single `/harness:autopilot` invocation executes all phases through to completion
-- Resume from any state after context reset via `.harness/autopilot-state.json`
+- Resume from any state after context reset via session-scoped `autopilot-state.json`
 - Low-complexity phases auto-plan; high-complexity phases pause for interactive planning
 - Planning override bumps complexity upward when task signals disagree
 - Retry budget (3 attempts) with escalating context before surfacing failures
@@ -360,7 +407,7 @@ Read spec — found 3 phases:
   Phase 1: Core Scanner (complexity: low)
   Phase 2: Rule Engine (complexity: high)
   Phase 3: CLI Integration (complexity: low)
-Created .harness/autopilot-state.json. Starting Phase 1.
+Created .harness/sessions/specs--2026-03-19-security-scanner/autopilot-state.json. Starting Phase 1.
 ```
 
 **Phase 1 — ASSESS:**
@@ -372,7 +419,7 @@ Phase 1: Core Scanner — complexity: low. Auto-planning.
 **Phase 1 — PLAN:**
 
 ```
-[Subagent runs harness-planning]
+[harness-planner agent runs harness-planning]
 Plan generated: docs/plans/2026-03-19-core-scanner-plan.md (8 tasks, ~24 min)
 ```
 
@@ -388,9 +435,9 @@ Approve this plan and begin execution? (yes / revise / skip / stop)
 **Phase 1 — EXECUTE → VERIFY → REVIEW:**
 
 ```
-[Subagent executes 8 tasks... all pass]
-[Subagent runs verification... pass]
-[Subagent runs code review... 0 blocking, 2 notes]
+[harness-task-executor agent executes 8 tasks... all pass]
+[harness-verifier agent runs verification... pass]
+[harness-code-reviewer agent runs code review... 0 blocking, 2 notes]
 ```
 
 **Phase 1 — PHASE_COMPLETE:**
@@ -479,16 +526,16 @@ How should we proceed? (fix manually and continue / revise plan / stop)
 
 ## Gates
 
-- **No reimplementing delegated skills.** Autopilot orchestrates. If you are writing planning logic, execution logic, verification logic, or review logic, STOP. Delegate to the appropriate skill.
+- **No reimplementing delegated skills.** Autopilot orchestrates. If you are writing planning logic, execution logic, verification logic, or review logic, STOP. Delegate to the appropriate persona agent via `subagent_type`.
 - **No executing without plan approval.** Every plan must be explicitly approved by the human before execution begins. No exceptions, regardless of complexity level.
 - **No skipping VERIFY or REVIEW.** Every phase goes through verification and review. The human can override findings, but the steps cannot be skipped.
 - **No infinite retries.** The retry budget is 3 attempts. If exhausted, STOP and surface to the human. Do not extend the budget without explicit human instruction.
-- **No modifying autopilot-state.json manually.** The state file is managed by the skill. If the state appears corrupted, start fresh rather than patching it.
+- **No modifying session state files manually.** The session state files are managed by the skill. If the state appears corrupted, start fresh rather than patching it.
 
 ## Escalation
 
 - **When the spec has no Implementation Order section:** Cannot identify phases. Ask the user to add phase annotations to the spec or provide a roadmap file.
-- **When a delegated skill fails to produce expected output:** Check that handoff.json was written correctly. If the subagent failed, report the failure and ask the user whether to retry the entire phase step or stop.
-- **When the user wants to reorder phases mid-run:** Update the phases array in autopilot-state.json (mark skipped phases, adjust currentPhase). Do not re-run completed phases.
+- **When a delegated skill fails to produce expected output:** Check that `{sessionDir}/handoff.json` was written correctly. If the agent failed, report the failure and ask the user whether to retry the entire phase step or stop.
+- **When the user wants to reorder phases mid-run:** Update the phases array in the session-scoped `autopilot-state.json` (mark skipped phases, adjust currentPhase). Do not re-run completed phases.
 - **When context limits are approaching:** Persist state immediately and inform the user: "Context limit approaching. State saved. Re-invoke /harness:autopilot to continue from this point."
 - **When multiple phases fail in sequence:** After 2 consecutive phase failures (retry budget exhausted in both), suggest the user review the spec for systemic issues rather than continuing.

package/dist/agents/skills/claude-code/harness-autopilot/skill.yaml

@@ -42,9 +42,11 @@ phases:
 state:
   persistent: true
   files:
-    - .harness/autopilot-state.json
-    - .harness/state.json
+    - .harness/sessions/*/autopilot-state.json
+    - .harness/sessions/*/state.json
+    - .harness/sessions/*/handoff.json
     - .harness/learnings.md
+    - .harness/failures.md
 depends_on:
   - harness-planning
   - harness-execution

package/dist/agents/skills/claude-code/harness-brainstorming/SKILL.md

@@ -38,6 +38,21 @@ If you find yourself writing production code, tests, or scaffolding before the h
 
 1. **Ask ONE question at a time.** Do not dump a list of 10 questions on the human. Ask the most important question first. Wait for the answer. Let the answer inform the next question.
 
+   When asking a clarifying question, use `emit_interaction` with `type: 'question'`:
+
+   ```json
+   emit_interaction({
+     path: "<project-root>",
+     type: "question",
+     question: {
+       text: "For auth, should we use:",
+       options: ["A) existing JWT middleware", "B) OAuth2 via provider X", "C) external service"]
+     }
+   })
+   ```
+
+   This records the question in state and returns a formatted prompt to present.
+
 2. **Prefer multiple choice.** Instead of "How should we handle auth?", ask "For auth, should we: (A) use existing JWT middleware, (B) add OAuth2 via provider X, or (C) delegate to an external service?" Give 2-4 concrete options with brief tradeoff notes.
 
 3. **When the human answers, acknowledge and build on it.** Do not re-ask clarified points. Track decisions as they accumulate.
@@ -67,6 +82,13 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    - **Estimated complexity:** Low / Medium / High, with a brief justification
    - **Risk:** What could go wrong, what assumptions might be wrong
 
+   When presenting approach tradeoffs, use conventional markdown patterns:
+
+   ```
+   **[IMPORTANT]** Approach 1 trades simplicity for extensibility
+   **[SUGGESTION]** Consider Approach 2 if real-time requirements emerge later
+   ```
+
 2. **Be honest about tradeoffs.** Do not soft-sell a preferred approach. If approach A is simpler but less extensible, say so plainly.
 
 3. **State your recommendation** and why, but defer to the human's decision.
@@ -84,13 +106,62 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    - Success criteria (observable, testable outcomes)
    - Implementation order (high-level phases, not detailed tasks — that is harness-planning's job)
 
-2. **After all sections are reviewed, write the spec to `docs/`.** Use the project's existing spec naming convention. If none exists, use `docs/specs/YYYY-MM-DD-<feature-name>.md`.
+2. **Run soundness review.** After all sections are reviewed and the spec is drafted, invoke `harness-soundness-review --mode spec` against the draft. Do not proceed to write the spec to `docs/` until the soundness review converges with no remaining issues.
 
-   When the project has `docs/specs/`, write proposals to `docs/changes/<feature>/proposal.md` instead. This keeps change proposals separate from established specs. Fall back to the existing behavior (`docs/specs/`) when no `docs/specs/` directory exists yet.
+3. **Write the spec to `docs/`.** Use the project's existing spec naming convention. If none exists, use `docs/specs/YYYY-MM-DD-<feature-name>.md`.
 
-3. **Run `harness validate`** to verify the spec file is properly placed and the project remains healthy.
+   When the project has `docs/specs/`, write proposals to `docs/changes/<feature>/proposal.md` instead. This keeps change proposals separate from established specs. Fall back to the existing behavior (`docs/specs/`) when no `docs/specs/` directory exists yet.
 
-4. **Ask for final sign-off.** Present the complete spec file path and a one-paragraph summary. The human must explicitly approve before this skill is complete.
+4. **Run `harness validate`** to verify the spec file is properly placed and the project remains healthy.
+
+5. **Request sign-off via `emit_interaction`:**
+
+   ```json
+   emit_interaction({
+     path: "<project-root>",
+     type: "confirmation",
+     confirmation: {
+       text: "Approve spec at <file-path>?",
+       context: "<one-paragraph summary of the design>"
+     }
+   })
+   ```
+
+   The human must explicitly approve before this skill is complete.
+
+6. **Write handoff and suggest transition.** After the human approves the spec:
+
+   Write `.harness/handoff.json`:
+
+   ```json
+   {
+     "fromSkill": "harness-brainstorming",
+     "phase": "VALIDATE",
+     "summary": "<1-sentence spec summary>",
+     "artifacts": ["<spec file path>"],
+     "decisions": [{ "what": "<decision>", "why": "<rationale>" }],
+     "contextKeywords": ["<domain keywords from Phase 2>"]
+   }
+   ```
+
+   Call `emit_interaction`:
+
+   ```json
+   {
+     "type": "transition",
+     "transition": {
+       "completedPhase": "brainstorming",
+       "suggestedNext": "planning",
+       "reason": "Spec approved and written to docs/",
+       "artifacts": ["<spec file path>"],
+       "requiresConfirmation": true,
+       "summary": "<Spec title> -- <key design choices>. <N> success criteria, <N> implementation phases."
+     }
+   }
+   ```
+
+   If the user confirms: invoke harness-planning with the spec path.
+   If the user declines: stop. The handoff is written for future invocation.
 
 ---
 
@@ -147,6 +218,7 @@ Converge on a recommendation that addresses all concerns before presenting the d
 - **`harness check-docs`** — Run to verify the spec does not conflict with existing documentation.
 - **Spec location** — Specs go to `docs/` (or `docs/specs/` if the project uses that convention). Follow existing naming patterns.
 - **Handoff to harness-planning** — Once the spec is approved, invoke harness-planning to create the implementation plan from the spec.
+- **`emit_interaction`** -- Call at the end of Phase 4 to suggest transitioning to harness-planning. Uses confirmed transition (waits for user approval).
 
 #### Requirement Phrasing
 

package/dist/agents/skills/claude-code/harness-brainstorming/skill.yaml

@@ -15,6 +15,7 @@ tools:
   - Edit
   - Glob
   - Grep
+  - emit_interaction
 cli:
   command: harness skill run harness-brainstorming
   args:
@@ -45,3 +46,4 @@ state:
   files: []
 depends_on:
   - harness-planning
+  - harness-soundness-review