@harness-engineering/cli 1.24.0 → 1.24.1

package/dist/agents/skills/codex/harness-autopilot/skill.yaml

@@ -1,6 +1,7 @@
 name: harness-autopilot
 version: "1.0.0"
 description: Autonomous phase execution loop — chains planning, execution, verification, and review, pausing only at human decision points
+stability: static
 cognitive_mode: constructive-architect
 triggers:
   - manual

package/dist/agents/skills/codex/harness-brainstorming/SKILL.md

@@ -4,13 +4,13 @@
 
 ## When to Use
 
-- Starting a new feature or project that requires design decisions
-- When the problem space is ambiguous and needs exploration before planning
-- When multiple implementation approaches exist and tradeoffs must be weighed
-- When `on_new_feature` trigger fires and the scope is non-trivial
+- Starting a new feature requiring design decisions
+- When the problem space is ambiguous and needs exploration
+- When multiple approaches exist and tradeoffs must be weighed
+- When `on_new_feature` trigger fires and scope is non-trivial
 - NOT when the implementation path is already clear (go straight to harness-planning)
 - NOT when fixing a bug with an obvious root cause (use harness-debugging or harness-tdd)
-- NOT when the task is a simple refactor with no design decisions (use harness-refactoring)
+- NOT for simple refactors with no design decisions (use harness-refactoring)
 
 ## Process
 
@@ -18,27 +18,33 @@
 
 **No implementation may begin before the design is approved by the human.**
 
-If you find yourself writing production code, tests, or scaffolding before the human has signed off on the design, STOP. You are in the wrong skill. Brainstorming produces a spec document, not code.
+If you find yourself writing production code, tests, or scaffolding before sign-off, STOP. Brainstorming produces a spec document, not code.
 
 ---
 
-### Phase 1: EXPLORE — Gather Context
+### Argument Resolution
 
-1. **Read the existing codebase.** Understand the current architecture, constraints, and conventions. Check AGENTS.md, existing specs in `docs/`, and relevant source files.
+When invoked by autopilot (or with explicit arguments), resolve paths before starting:
 
-2. **Identify the problem boundary.** What exactly needs to be solved? What is explicitly out of scope? Write down both.
+1. **Session slug:** If `session-slug` argument provided, use it for all session-scoped reads/writes (`{sessionDir} = .harness/sessions/<session-slug>/`). Otherwise, session-scoped paths are unavailable — fall back to global `.harness/` paths.
+2. **Handoff output:** When session slug is known, write handoff to `{sessionDir}/handoff.json`. Otherwise write to `.harness/handoff.json` (deprecated fallback).
 
-3. **Check for prior art.** Has this problem been partially solved elsewhere in the codebase? Are there existing patterns that should be followed or deliberately broken?
-
-4. **Assess scope.** If the problem spans more than 3 major subsystems or would take more than 2 weeks to implement, it is too large. Decompose into sub-projects first, then brainstorm each one separately.
+When no arguments are provided (standalone invocation), the skill operates exactly as before — no session scoping, global paths only.
 
 ---
 
-### Phase 2: EVALUATE — Ask Questions and Narrow
+### Phase 1: EXPLORE -- Gather Context
+
+1. **Read the existing codebase.** Understand architecture, constraints, and conventions. Check AGENTS.md, existing specs in `docs/`, and relevant source files.
+2. **Identify the problem boundary.** What exactly needs solving? What is out of scope? Write both down.
+3. **Check for prior art.** Has this been partially solved elsewhere? Are there patterns to follow or deliberately break?
+4. **Assess scope.** If the problem spans >3 major subsystems or >2 weeks to implement, decompose into sub-projects first.
+
+---
 
-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.
+### Phase 2: EVALUATE -- Ask Questions and Narrow
 
-   When asking a clarifying question, use `emit_interaction` with `type: 'question'`:
+1. **Ask ONE question at a time.** Ask the most important question first. Wait for the answer. Let it inform the next question. Use `emit_interaction` with `type: 'question'`:
 
    ```json
    emit_interaction({
@@ -47,97 +53,68 @@ If you find yourself writing production code, tests, or scaffolding before the h
      question: {
        text: "For auth, which approach should we use?",
        options: [
-         {
-           label: "A) Existing JWT middleware",
-           pros: ["Already in codebase", "Team has experience"],
-           cons: ["No refresh token support", "Session-only"],
-           risk: "low",
-           effort: "low"
-         },
-         {
-           label: "B) OAuth2 via provider X",
-           pros: ["Industry standard", "Refresh tokens built-in"],
-           cons: ["New dependency", "Learning curve"],
-           risk: "medium",
-           effort: "medium"
-         },
-         {
-           label: "C) External auth service",
-           pros: ["Zero maintenance", "Enterprise features included"],
-           cons: ["Vendor lock-in", "Monthly cost", "Latency"],
-           risk: "medium",
-           effort: "low"
-         }
+         { "label": "A) Existing JWT middleware", "pros": ["Already in codebase"], "cons": ["No refresh tokens"], "risk": "low", "effort": "low" },
+         { "label": "B) OAuth2 via provider X", "pros": ["Industry standard"], "cons": ["New dependency"], "risk": "medium", "effort": "medium" },
+         { "label": "C) External auth service", "pros": ["Zero maintenance"], "cons": ["Vendor lock-in", "Cost"], "risk": "medium", "effort": "low" }
        ],
-       recommendation: {
-         optionIndex: 0,
-         reason: "Sufficient for current requirements. OAuth2 adds complexity we don't need yet.",
-         confidence: "high"
-       }
+       recommendation: { "optionIndex": 0, "reason": "Sufficient for current requirements.", "confidence": "high" }
      }
    })
    ```
 
-   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.
-
-4. **Apply YAGNI ruthlessly.** For every proposed capability, ask: "Do we need this for the stated goal, or is this speculative?" If speculative, cut it. If the human insists, note it as a future consideration, not a requirement.
-
-5. **Continue until you have enough clarity** to propose concrete approaches. Typically 3-7 questions are sufficient. If you need more than 10, the scope is too large — decompose.
+2. **Prefer multiple choice over open-ended questions.** Give 2-4 concrete options with brief tradeoff notes.
+3. **Acknowledge answers and build on them.** Do not re-ask clarified points. Track decisions as they accumulate.
+4. **Apply YAGNI ruthlessly.** For every proposed capability, ask: "Do we need this for the stated goal, or is this speculative?" If speculative, cut it. If the human insists, note it as a future consideration.
+5. **Continue until you have enough clarity** to propose concrete approaches. Typically 3-7 questions suffice. If you need >10, the scope is too large -- decompose.
 
 ### Context Keywords
 
-During Phase 2, extract 5-10 domain keywords that capture the problem space. Include them in the spec frontmatter:
+During Phase 2, extract 5-10 domain keywords for the spec frontmatter:
 
 ```
 **Keywords:** auth, middleware, session-tokens, refresh-flow, OAuth2
 ```
 
-These keywords flow into the `handoff.json` `contextKeywords` field when the spec is handed off to planning. Select keywords that would help a fresh agent — one that has never seen this conversation — understand the domain area quickly.
+These flow into `handoff.json` `contextKeywords` field. Select keywords that help a fresh agent understand the domain quickly.
 
 ---
 
-### Phase 3: PRIORITIZE — Propose Approaches
+### Phase 3: PRIORITIZE -- Propose Approaches
 
-1. **Propose 2-3 concrete approaches.** Not 1 (no choice), not 5 (decision paralysis). Each approach must include:
-   - **Summary:** One sentence describing the approach
-   - **How it works:** Key technical decisions (what data structures, what APIs, what patterns)
-   - **Tradeoffs:** What you gain, what you lose, what gets harder later
-   - **Estimated complexity:** Low / Medium / High, with a brief justification
+1. **Propose 2-3 concrete approaches.** Each must include:
+   - **Summary:** One sentence
+   - **How it works:** Key technical decisions (data structures, APIs, patterns)
+   - **Tradeoffs:** What you gain, lose, what gets harder later
+   - **Complexity:** Low/Medium/High with brief justification
    - **Risk:** What could go wrong, what assumptions might be wrong
 
-   When presenting approach tradeoffs, use conventional markdown patterns:
+   Use conventional markdown for callouts:
 
    ```
    **[IMPORTANT]** Approach 1 trades simplicity for extensibility
-   **[SUGGESTION]** Consider Approach 2 if real-time requirements emerge later
+   **[SUGGESTION]** Consider Approach 2 if real-time requirements emerge
    ```
 
-2. **Be honest about tradeoffs.** Do not soft-sell a preferred approach. If approach A is simpler but less extensible, say so plainly.
-
+2. **Be honest about tradeoffs.** Do not soft-sell a preferred approach.
 3. **State your recommendation** and why, but defer to the human's decision.
-
 4. **Wait for the human to choose.** Do not proceed until an approach is selected.
 
 ---
 
-### Phase 4: VALIDATE — Write the Spec
+### Phase 4: VALIDATE -- Write the Spec
 
-1. **Present the design section by section.** Do not dump the entire spec at once. Present each major section, get feedback, and incorporate it before moving to the next:
+1. **Present the design section by section** (not all at once). Get feedback on each section, incorporate it, then move to the next:
    - Overview and goals
-   - Decisions made (with rationale from the brainstorming conversation)
+   - Decisions made (with rationale from brainstorming)
    - Technical design (data structures, APIs, file layout)
    - Success criteria (observable, testable outcomes)
-   - Implementation order (high-level phases, not detailed tasks — that is harness-planning's job)
+   - Implementation order (high-level phases, not detailed tasks)
 
-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.
+2. **Run soundness review.** Invoke `harness-soundness-review --mode spec` against the draft. Do not write to `docs/` until the review converges with no remaining issues.
 
-3. **Write the spec to `docs/`.** Write proposals to `docs/changes/<feature>/proposal.md`. This keeps change proposals organized by feature in a consistent location.
+3. **Write the spec** to `docs/changes/<feature>/proposal.md`.
 
-4. **Run `harness validate`** to verify the spec file is properly placed and the project remains healthy.
+4. **Run `harness validate`** to verify proper placement and project health.
 
 5. **Request sign-off via `emit_interaction`:**
 
@@ -147,7 +124,7 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
      type: "confirmation",
      confirmation: {
        text: "Approve spec at <file-path>?",
-       context: "<one-paragraph summary of the design>",
+       context: "<one-paragraph summary>",
        impact: "Spec approval unlocks implementation planning. No code changes yet.",
        risk: "low"
      }
@@ -157,25 +134,28 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    The human must explicitly approve before this skill is complete.
 
 6. **Add feature to roadmap.** If `docs/roadmap.md` exists:
-   - Derive the feature name from the spec title (the H1 heading of the proposal).
-   - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path. Include a one-line summary from the spec overview.
-   - If the feature already exists in the roadmap (duplicate name), skip silently — the feature was likely added manually or by a prior brainstorming session.
-   - Log: `"Added '<feature-name>' to roadmap as planned"` (informational, not a prompt).
-   - If `manage_roadmap` is unavailable, fall back to direct file manipulation using `parseRoadmap`/`serializeRoadmap` from core to read, modify, and write `docs/roadmap.md`. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored to push changes to GitHub."
-   - If no roadmap exists, skip this step silently.
+   - Derive feature name from the spec title (the H1 heading).
+   - Call `manage_roadmap` with action `add`, `status: "planned"`, `milestone: "Current Work"`, and the spec path.
+   - If the feature already exists, skip silently.
+   - If `manage_roadmap` is unavailable, fall back to `parseRoadmap`/`serializeRoadmap` from core. Warn: "External sync skipped (MCP unavailable). Run `manage_roadmap sync` when MCP is restored."
+   - If no roadmap exists, skip silently.
 
-7. **Write handoff and suggest transition.** After the human approves the spec:
+7. **Write handoff and suggest transition.** After approval:
 
-   Write `.harness/handoff.json`:
+   Write handoff to the session-scoped path when a session slug is known, otherwise fall back to the global path:
+   - Session-scoped (preferred): `.harness/sessions/<session-slug>/handoff.json`
+   - Global (fallback, deprecated): `.harness/handoff.json`
+
+   > **[DEPRECATED]** Writing to `.harness/handoff.json` is deprecated. When running within an autopilot session, always write to `.harness/sessions/<session-slug>/handoff.json`. Global writes cause cross-session contamination in parallel runs.
 
    ```json
    {
      "fromSkill": "harness-brainstorming",
      "phase": "VALIDATE",
-     "summary": "<1-sentence spec summary>",
-     "artifacts": ["<spec file path>"],
+     "summary": "<1-sentence summary>",
+     "artifacts": ["<spec path>"],
      "decisions": [{ "what": "<decision>", "why": "<rationale>" }],
-     "contextKeywords": ["<domain keywords from Phase 2>"]
+     "contextKeywords": ["<keywords from Phase 2>"]
    }
    ```
 
@@ -188,9 +168,9 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
        "completedPhase": "brainstorming",
        "suggestedNext": "planning",
        "reason": "Spec approved and written to docs/",
-       "artifacts": ["<spec file path>"],
+       "artifacts": ["<spec path>"],
        "requiresConfirmation": true,
-       "summary": "<Spec title> -- <key design choices>. <N> success criteria, <N> implementation phases.",
+       "summary": "<title> -- <key choices>. <N> success criteria, <N> phases.",
        "qualityGate": {
          "checks": [
            {
@@ -207,124 +187,106 @@ These keywords flow into the `handoff.json` `contextKeywords` field when the spe
    }
    ```
 
-   If the user confirms: invoke harness-planning with the spec path.
-   If the user declines: stop. The handoff is written for future invocation.
+   If confirmed: invoke harness-planning with the spec path.
+   If declined: stop. The handoff is written for future invocation.
 
 ---
 
 ### Scope Check
 
-At any point during brainstorming, if the design reveals that the project is larger than initially expected:
+If the design reveals larger-than-expected scope:
 
-1. **Identify natural decomposition boundaries.** Where can the project be split into independently deliverable pieces?
-2. **Propose sub-projects.** Each sub-project should be brainstormable and plannable on its own.
-3. **Get approval for the decomposition** before continuing to brainstorm any individual sub-project.
+1. **Identify natural decomposition boundaries** -- where can it split into independent pieces?
+2. **Propose sub-projects**, each brainstormable and plannable on its own.
+3. **Get approval for decomposition** before continuing.
 
 ## Party Mode
 
-When activated with `--party`, add a multi-perspective evaluation step after proposing approaches.
+When activated with `--party`, add multi-perspective evaluation after proposing approaches.
 
 ### Perspective Selection
 
-Select 2-3 perspectives based on design topic:
+Select 2-3 perspectives based on topic:
 
-| Topic          | Perspectives                                 |
-| -------------- | -------------------------------------------- |
-| API / backend  | Backend Developer, API Consumer, Operations  |
-| UI / frontend  | Developer, Designer, End User                |
-| Infrastructure | Architect, SRE, Developer                    |
-| Data model     | Backend Developer, Data Consumer, Migration  |
-| Library / SDK  | Library Author, Library Consumer, Maintainer |
-| Cross-cutting  | Architect, Security, Developer               |
-| Default        | Architect, Developer, User/Consumer          |
+| Topic         | Perspectives                                |
+| ------------- | ------------------------------------------- |
+| API/backend   | Backend Developer, API Consumer, Operations |
+| UI/frontend   | Developer, Designer, End User               |
+| Infra         | Architect, SRE, Developer                   |
+| Data model    | Backend Dev, Data Consumer, Migration       |
+| Library/SDK   | Library Author, Consumer, Maintainer        |
+| Cross-cutting | Architect, Security, Developer              |
+| Default       | Architect, Developer, User/Consumer         |
 
 ### Evaluation Process
 
-For each proposed approach, evaluate from each perspective:
+For each approach, evaluate from each perspective:
 
 ```
 ### Approach N: [name]
-
-**[Perspective 1] perspective:**
-[Assessment]. Concern: [specific concern or "None"].
-
-**[Perspective 2] perspective:**
-[Assessment]. Concern: [specific concern or "None"].
-
-**[Perspective 3] perspective:**
-[Assessment]. Concern: [specific concern or "None"].
-
-**Synthesis:** [Consensus summary. Address raised concerns. Recommend proceed/revise.]
+**[Perspective 1]:** [Assessment]. Concern: [specific or "None"].
+**[Perspective 2]:** [Assessment]. Concern: [specific or "None"].
+**[Perspective 3]:** [Assessment]. Concern: [specific or "None"].
+**Synthesis:** [Consensus. Address concerns. Recommend proceed/revise.]
 ```
 
 Converge on a recommendation that addresses all concerns before presenting the design.
 
 ## Session State
 
-This skill reads and writes to the following session sections via `manage_state`:
+| Section       | R   | W   | Purpose                                         |
+| ------------- | --- | --- | ----------------------------------------------- |
+| terminology   | Y   | Y   | Domain terms discovered during brainstorming    |
+| decisions     |     | Y   | Design decisions made during exploration        |
+| constraints   | Y   |     | Reads constraints to scope brainstorming        |
+| risks         |     | Y   | Risks identified during brainstorming           |
+| openQuestions | Y   | Y   | Adds new questions, resolves answered ones      |
+| evidence      |     | Y   | Cites sources for recommendations and prior art |
 
-| Section       | Read | Write | Purpose                                                           |
-| ------------- | ---- | ----- | ----------------------------------------------------------------- |
-| terminology   | yes  | yes   | Captures domain terms discovered during brainstorming             |
-| decisions     | no   | yes   | Records design decisions made during exploration                  |
-| constraints   | yes  | no    | Reads constraints to scope brainstorming                          |
-| risks         | no   | yes   | Captures risks identified during brainstorming                    |
-| openQuestions | yes  | yes   | Adds new questions, resolves answered ones                        |
-| evidence      | no   | yes   | Cites sources for design recommendations and prior art references |
-
-**When to write:** After each phase transition (EXPLORE -> EVALUATE -> PRIORITIZE -> VALIDATE), append relevant entries to the appropriate sections. This ensures downstream skills (planning, execution) inherit accumulated context without re-discovery.
-
-**When to read:** At the start of Phase 1 (EXPLORE), read `terminology` and `constraints` from the session to inherit context from prior skills or previous brainstorming sessions on the same feature.
+**Write** after each phase transition (EXPLORE->EVALUATE->PRIORITIZE->VALIDATE) so downstream skills inherit context.
+**Read** at Phase 1 start -- `terminology` and `constraints` from session for prior context.
 
 ## Evidence Requirements
 
-When this skill makes claims about existing code behavior, architecture patterns, or technical tradeoffs, it MUST cite evidence using one of:
+Technical claims about existing code, architecture, or tradeoffs MUST cite evidence:
 
-1. **File reference:** `file:line` format (e.g., `src/services/auth.ts:42` -- "existing JWT middleware handles token refresh")
-2. **Prior art reference:** `file` format with description (e.g., `src/utils/email.ts` -- "email utility already exists, can be reused for notifications")
-3. **Documentation reference:** `docs/path` format (e.g., `docs/changes/user-auth/proposal.md` -- "prior spec established OAuth2 as the auth standard")
-4. **Session evidence:** Write to the `evidence` session section:
-   ```json
-   manage_state({
-     action: "append_entry",
-     session: "<current-session>",
-     section: "evidence",
-     authorSkill: "harness-brainstorming",
-     content: "src/services/auth.ts:42 -- existing JWT middleware supports refresh tokens"
-   })
-   ```
+1. **File reference:** `file:line` (e.g., `src/services/auth.ts:42` -- "existing JWT middleware")
+2. **Prior art:** `file` with description (e.g., `src/utils/email.ts` -- "reusable for notifications")
+3. **Docs:** `docs/path` (e.g., `docs/changes/user-auth/proposal.md` -- "established OAuth2 standard")
+4. **Session evidence:** Write via `manage_state` `append_entry` to `evidence` section.
 
-**When to cite:** During Phase 1 (EXPLORE) when referencing existing code or patterns. During Phase 3 (PRIORITIZE) when justifying tradeoffs with concrete code references. During Phase 4 (VALIDATE) when spec references existing implementation details.
+**When to cite:** Phase 1 (existing code/patterns), Phase 3 (tradeoff justifications), Phase 4 (spec referencing existing implementation).
 
-**Uncited claims:** Technical assertions without citations MUST be prefixed with `[UNVERIFIED]`. Example: `[UNVERIFIED] The current auth middleware does not support refresh tokens`. Uncited claims are flagged during review (Wave 2.2).
+**Uncited claims** MUST be prefixed with `[UNVERIFIED]`. These are flagged during review.
 
 ## Harness Integration
 
-- **`harness validate`** — Run after writing the spec to `docs/`. Verifies project health and that the new spec file is properly placed.
-- **`harness check-docs`** — Run to verify the spec does not conflict with existing documentation.
-- **Spec location** — Specs go to `docs/changes/<feature>/proposal.md`. Follow existing naming patterns.
-- **Handoff to harness-planning** — Once the spec is approved, invoke harness-planning to create the implementation plan from the spec.
-- **Roadmap sync** — After spec approval, call `manage_roadmap` with action `add` to register the new feature as `planned` in `docs/roadmap.md`. Skip silently if no roadmap exists. Duplicates are silently ignored.
-- **`emit_interaction`** -- Call at the end of Phase 4 to suggest transitioning to harness-planning. Uses confirmed transition (waits for user approval).
+- **`harness validate`** -- Run after writing the spec. Verifies project health and spec placement.
+- **`harness check-docs`** -- Verify spec does not conflict with existing docs.
+- **Spec location** -- `docs/changes/<feature>/proposal.md`.
+- **Handoff** -- Once approved, invoke harness-planning to create the implementation plan.
+- **Session directory** — When session slug is known, handoff goes to `.harness/sessions/<slug>/handoff.json`. The session directory structure is: `handoff.json`, `state.json`, `artifacts.json` (registry of spec/plan paths and file lists). Do not write to `.harness/handoff.json` in session context.
+- **Roadmap sync** -- After approval, call `manage_roadmap` action `add` to register as `planned`. Skip silently if no roadmap. Duplicates ignored.
+- **`emit_interaction`** -- End of Phase 4 to suggest transition to harness-planning (confirmed transition).
 
 #### Requirement Phrasing
 
-When brainstorming produces requirements or acceptance criteria that will feed into planning, prefer EARS sentence patterns for behavioral requirements. See the EARS Requirement Patterns section in harness-planning for the full template reference. Key patterns:
+When brainstorming produces requirements for planning, prefer EARS sentence patterns (see harness-planning for full reference):
 
 - **Event-driven:** "When [trigger], the system shall [response]."
 - **Unwanted:** "If [condition], then the system shall not [behavior]."
 
-These patterns make requirements testable and unambiguous. Apply them when the output of brainstorming includes specific behavioral expectations.
+Apply when output includes specific behavioral expectations.
 
 ## Success Criteria
 
-- A spec document exists in `docs/` with all required sections (overview, decisions, technical design, success criteria, implementation order)
-- The human explicitly approved the design before any implementation
-- YAGNI was applied: no speculative features made it into the spec
-- 2-3 approaches were presented with honest tradeoffs before a decision was made
-- Questions were asked one at a time with multiple-choice options where possible
-- `harness validate` passes after the spec is written
-- If scope was too large, it was decomposed into sub-projects with the human's approval
+- Spec exists in `docs/` with all required sections (overview, decisions, technical design, success criteria, implementation order)
+- Human explicitly approved before any implementation
+- YAGNI applied: no speculative features in the spec
+- 2-3 approaches presented with honest tradeoffs before decision
+- Questions asked one at a time with multiple-choice options where possible
+- `harness validate` passes after spec is written
+- If scope was too large, it was decomposed with human approval
 
 ## Rationalizations to Reject
 
@@ -342,27 +304,20 @@ These patterns make requirements testable and unambiguous. Apply them when the o
 **EXPLORE:**
 
 ```
-Read AGENTS.md — project is a TypeScript monorepo with React frontend and Express backend.
-Read existing docs/ — no prior notification specs. Found docs/changes/user-auth/proposal.md as naming example.
-Checked src/services/ — no notification code exists. Found email utility in src/utils/email.ts.
-Scope assessment: single subsystem (notifications), estimated 1 week. Proceed.
+Read AGENTS.md -- TypeScript monorepo, React frontend, Express backend.
+No prior notification specs. Found docs/changes/user-auth/proposal.md as naming example.
+No notification code in src/services/. Found email utility in src/utils/email.ts.
+Scope: single subsystem, ~1 week. Proceed.
 ```
 
 **EVALUATE:**
 
 ```
-Q1: "For notifications, should we support:
-  (A) Email only (simplest, covers 90% of use cases)
-  (B) Email + in-app (covers real-time needs)
-  (C) Email + in-app + push (full coverage, most complex)?"
-Human: "B — email and in-app."
-
-Q2: "For in-app notifications, should we:
-  (A) Poll from client every 30s (simple, slight delay)
-  (B) WebSocket push (real-time, more infrastructure)?"
-Human: "A — polling is fine for now."
-
-Q3: "Should notifications be stored permanently or expire after 30 days?"
+Q1: "Notifications: (A) Email only, (B) Email + in-app, (C) Email + in-app + push?"
+Human: "B -- email and in-app."
+Q2: "In-app delivery: (A) Poll every 30s (simple), (B) WebSocket (real-time, more infra)?"
+Human: "A -- polling is fine."
+Q3: "Store permanently or expire after 30 days?"
 Human: "Expire after 30 days."
 ```
 
@@ -370,20 +325,17 @@ Human: "Expire after 30 days."
 
 ```
 Approach 1: Event-driven with queue
-- Services emit events, notification worker consumes and dispatches
-- Tradeoff: More infrastructure (needs queue), but decoupled and scalable
-- Complexity: Medium
-- Risk: Queue adds operational overhead
+- Services emit events, worker consumes and dispatches
+- Tradeoff: More infra (needs queue), but decoupled and scalable
+- Complexity: Medium. Risk: Queue adds operational overhead
 
 Approach 2: Direct service calls
 - Services call NotificationService directly
 - Tradeoff: Simpler, but couples services to notification logic
-- Complexity: Low
-- Risk: Harder to add channels later, synchronous blocking
+- Complexity: Low. Risk: Harder to add channels later, synchronous blocking
 
-Recommendation: Approach 2. YAGNI — direct calls are sufficient for email + polling.
-We can migrate to event-driven later if we add push notifications.
-Human: "Agreed, approach 2."
+Recommendation: Approach 2 (YAGNI). Direct calls suffice for email + polling.
+Human: "Agreed."
 ```
 
 **VALIDATE:**
@@ -391,25 +343,23 @@ Human: "Agreed, approach 2."
 ```
 Wrote docs/changes/notification-system/proposal.md
 Sections: Overview, Decisions, Technical Design, Success Criteria, Implementation Order
-harness validate — passes
-"Spec written to docs/changes/notification-system/proposal.md. Ready for sign-off?"
-Human: "Approved."
+harness validate -- passes. Human: "Approved."
 ```
 
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.
 
-- **No implementation before approval.** No production code, no test code, no scaffolding, no "let me just set up the directory structure." The spec must be approved first. If you wrote code, delete it.
-- **No skipping the question phase.** You must ask at least one clarifying question before proposing approaches. If you think you already know the answer, you are making assumptions — validate them.
-- **No single-approach proposals.** Always present at least 2 approaches with tradeoffs. A single approach is a recommendation disguised as a decision — the human has no real choice.
-- **No speculative features.** Every capability in the spec must trace to a stated requirement. "We might need this later" is not a requirement. Cut it.
-- **No section-dump specs.** Present the design section by section with feedback between each. Do not write the entire spec and ask "looks good?"
+- **No implementation before approval.** No production code, tests, or scaffolding. The spec must be approved first. If you wrote code, delete it.
+- **No skipping the question phase.** Ask at least one clarifying question before proposing approaches. If you think you know the answer, validate the assumption.
+- **No single-approach proposals.** Always present at least 2 approaches with tradeoffs. A single approach is a recommendation disguised as a decision.
+- **No speculative features.** Every capability must trace to a stated requirement. "We might need this later" is not a requirement.
+- **No section-dump specs.** Present section by section with feedback between each. Do not write the entire spec and ask "looks good?"
 
 ## Escalation
 
-- **When the human cannot decide between approaches:** Identify the key differentiator. Ask: "The main difference is X. Given your priorities, does X matter more than Y?" If still stuck, suggest building a small spike to compare (but the spike is NOT production code).
-- **When scope keeps growing during brainstorming:** Stop brainstorming. Explicitly say: "The scope has expanded beyond the original problem. Should we (A) decompose into sub-projects, or (B) revisit the original goal to narrow it?" Do not continue accumulating scope.
-- **When the problem domain is unfamiliar:** State what you do not know. Ask the human if they have domain expertise, documentation, or a reference implementation. Do not guess at domain-specific requirements.
-- **When requirements conflict with existing architecture:** Flag the conflict explicitly: "The spec calls for X, but the current architecture assumes Y. Should we (A) change the spec to work within current architecture, or (B) plan an architecture change as a prerequisite?"
-- **When you have asked more than 10 questions without converging:** The problem is too large or too ambiguous. Stop and propose a decomposition or a scoping exercise before continuing.
+- **Human cannot decide between approaches:** Identify the key differentiator. Ask: "The main difference is X. Given your priorities, does X matter more than Y?" If still stuck, suggest a small spike (not production code).
+- **Scope keeps growing:** Stop brainstorming. Say: "Scope has expanded beyond the original problem. Should we (A) decompose into sub-projects, or (B) narrow the original goal?"
+- **Unfamiliar problem domain:** State what you do not know. Ask if the human has domain expertise, docs, or a reference implementation. Do not guess at domain-specific requirements.
+- **Requirements conflict with architecture:** Flag explicitly: "The spec calls for X, but current architecture assumes Y. Should we (A) change the spec, or (B) plan an architecture change as prerequisite?"
+- **More than 10 questions without converging:** The problem is too large or ambiguous. Stop and propose decomposition or a scoping exercise.

package/dist/agents/skills/codex/harness-brainstorming/skill.yaml

@@ -1,6 +1,7 @@
 name: harness-brainstorming
 version: "1.0.0"
 description: Structured ideation and exploration with harness methodology
+stability: static
 cognitive_mode: constructive-architect
 triggers:
   - manual
@@ -24,6 +25,9 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: session-slug
+      description: Session slug for scoped state/handoff (passed by autopilot)
+      required: false
 mcp:
   tool: run_skill
   input:

package/dist/agents/skills/codex/harness-caching/skill.yaml

@@ -1,6 +1,7 @@
 name: harness-caching
 version: "1.0.0"
 description: Cache strategies, invalidation patterns, and distributed caching
+stability: static
 cognitive_mode: advisory-guide
 triggers:
   - manual

package/dist/agents/skills/codex/harness-chaos/skill.yaml

@@ -1,6 +1,7 @@
 name: harness-chaos
 version: "1.0.0"
 description: Chaos engineering, fault injection, and resilience validation
+stability: static
 cognitive_mode: adversarial-reviewer
 triggers:
   - manual