@harness-engineering/cli 2.7.1 → 2.8.0

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

@@ -0,0 +1,152 @@
+# Harness Strategy
+
+> Repo-root strategic anchor. **Phase 2 of the strategic-anchor spec ships the skill**: a first-run interview that writes a valid `STRATEGY.md`, plus an update flow that re-interviews one section at a time with pushback against fluff, goals-as-strategy, and feature-lists-as-strategy. Downstream wiring (init, brainstorming, roadmap-pilot, ideate, knowledge graph) ships in spec Phases 3-7.
+
+## When to Use
+
+- Manually, when a project wants a durable upstream product anchor that survives across milestones and phases
+- When `STRATEGY.md` is absent and the user invokes `/harness:strategy`
+- When `STRATEGY.md` exists and the user wants to update one section (the user picks which one; nothing is auto-rewritten)
+- NOT for tactical phase tracking — that's `docs/roadmap.md` (kept deliberately separate; see proposal Decision 1)
+- NOT for generating strategy from code or commit history — strategy is a human commitment, never a derived artifact (proposal Decision 8)
+- NOT for producing specs/plans/code — those are `harness-brainstorming`'s job; this skill only writes `STRATEGY.md`
+
+## Process
+
+### Iron Law
+
+**The skill never writes `STRATEGY.md` without explicit user confirmation of the assembled doc, and never silently accepts an answer that fails a pushback rule on the FIRST round.** The 2-round cap is the _capitulation_ point, not the _bypass_ point — round 1 must always fire when a rule matches.
+
+---
+
+### Phase 0: ROUTE BY FILE STATE
+
+1. **Locate `STRATEGY.md` at repo root.** Use `path.join(process.cwd(), 'STRATEGY.md')`.
+2. **Call `validate_strategy({ path: process.cwd() })` via the harness MCP server.** It returns `{ present, valid, error? }`. The MCP server already has `@harness-engineering/core` loaded, so the project does not need it installed.
+   - **`{ present: false }`** → proceed to Phase 1 (first-run interview).
+   - **`{ present: true, valid: true }`** → proceed to Phase 2 (update run).
+   - **`{ present: true, valid: false, error }`** → surface `error` verbatim, then offer three paths via `emit_interaction` (or numbered chat options when MCP is unavailable):
+     - **a)** Fix the offending section now via the update flow → proceed to Phase 2 with the broken section pre-selected.
+     - **b)** Move file to `STRATEGY.md.bak.<YYYY-MM-DD-HHmm>` and run Phase 1 fresh.
+     - **c)** Exit; user repairs manually. No further action.
+
+The skill MUST NOT auto-overwrite a present-but-invalid STRATEGY.md — that's the user's prior work, even if broken. The three-path offer is the contract.
+
+---
+
+### Phase 1: FIRST-RUN INTERVIEW
+
+Read `references/interview.md` for the three pushback rules and the 2-round cap. Both are mandatory.
+
+Walk sections in **template order** — never out of order, because each section informs the next:
+
+1. **Target problem.** Open with: _"In 2-4 sentences: what is specifically broken in the world that this product addresses? Not the goal — the diagnosis."_ Capture. Apply `Fluff detection` and `Goal-as-strategy` rules.
+2. **Our approach.** Open with: _"What is your distinctive bet on how to solve the target problem? The choice you're making about HOW, not WHAT you're building."_ Apply all three rules (`Fluff`, `Goal-as-strategy`, `Feature-list-as-strategy`) — this is where feature-list answers live.
+3. **Who it's for.** Open with: _"Specific persona — who is the person, what context are they in, what alternatives are they currently using? 'Developers' is not a specific persona."_ Apply `Fluff detection`.
+4. **Key metrics.** Open with: _"What 1-5 metrics, measured where, would tell you the bet is paying off? Each metric is a bullet line: `- <name>: <how measured, where it lives>`."_ Apply `Fluff detection` per bullet.
+5. **Tracks.** Open with: _"What 1-5 tracks of work are you currently investing in to advance the bet? Each track is a bullet line: `- <track name>: <one-sentence current investment>`."_ Apply `Feature-list-as-strategy` per bullet (a "track" should be an investment direction, not a feature name).
+6. **Optional sections.** Ask once whether to add `Milestones`, `Not working on`, and/or `Marketing`. If yes, walk each with the same rules. If no, skip — they remain absent (the schema allows omission).
+7. **Assemble.** Show the full proposed doc. Ask explicitly: _"Write this to STRATEGY.md?"_ Wait for yes/no.
+8. **Write.** Call `write_strategy({ path: process.cwd(), doc })` via the harness MCP server. The `doc` argument is the assembled `StrategyDoc` shape: `{ frontmatter: { name, last_updated, version }, sections: [{ name, body }, ...] }`. Set `last_updated` to today's ISO date; `version` to `1` for first run. The MCP tool validates against `StrategyDocSchema` and refuses to touch disk on schema failure. Passing the doc as a JSON parameter (not through a shell) means user-supplied prose never crosses the shell tokenizer — no quoting, backtick, or `$VAR` hazard. Fallback for environments without the MCP server: shell out to `node -e "import('@harness-engineering/core').then(m => m.writeStrategyDoc(JSON.parse(require('fs').readFileSync(0, 'utf-8')), { cwd: process.cwd() }))"` with the doc piped on stdin — but only when `@harness-engineering/core` is resolvable from the project's `node_modules`.
+
+9. **Validate.** Run `harness validate` to confirm the file passes `StrategyDocSchema`. On failure, surface the error and stop (do not retry).
+
+---
+
+### Phase 2: UPDATE RUN
+
+1. **Re-read the existing file** via `read_strategy({ path: process.cwd() })` on the harness MCP server. It returns `{ present: true, valid: true, doc }` with the parsed `StrategyDoc` shape; the server runs `validateStrategy` + `parseStrategyDoc` + `asStrategyDoc` internally so the project does not need `@harness-engineering/core` installed.
+2. **Summarize current state** in 3-5 lines: frontmatter (`name`, `last_updated`, `version`), then the first sentence of each present section. This is the "what's there now" view the user needs to choose what to revisit.
+3. **Ask which section to revisit.** Present the section names as numbered options. Allow `none` (exit) or `multiple` (sequential re-interviews).
+4. **Re-interview each selected section** with the same pushback rules and 2-round cap from Phase 1. Do not re-ask sections the user did not select.
+5. **Bump frontmatter.** Set `last_updated` to today's ISO date. Increment `version` by 1.
+6. **Confirm and write.** Show the diff between the parsed doc and the new doc (added/changed sections). Ask explicitly: _"Write the update?"_ Wait for yes/no. Call `write_strategy` (same pattern as Phase 1.8). The writer preserves the user's H1 line and writes a `.bak` only if no `.bak` exists yet (idempotent — the original pre-strategy file is the rollback target).
+7. **Validate.** Run `harness validate`.
+
+---
+
+### Phase 3: DOWNSTREAM HANDOFF
+
+After Phase 1 or Phase 2 completes successfully, print this short note (3-5 lines):
+
+```
+STRATEGY.md written. Downstream skills that pick this up as grounding:
+  - harness-brainstorming     (Phase 5 of strategic-anchor spec — reads STRATEGY.md in Phase 1 EXPLORE)
+  - harness-ideate            (Phase 4 of spec — generates ranked candidates grounded in STRATEGY.md)
+  - harness-roadmap-pilot     (Phase 6 of spec — strategy-alignment tiebreaker)
+  - BusinessKnowledgeIngestor (Phase 7 of spec — strategy domain → business_fact nodes)
+Soft-fail when absent; no downstream skill blocks on STRATEGY.md's presence.
+```
+
+The handoff exists to set the user's expectation about _why_ they just answered those questions. It is short by design — this is not a section to grow.
+
+## Harness Integration
+
+- **`harness validate`** — Run after `write_strategy`; the existing `validateStrategy` helper (Phase 1 of this spec) catches schema violations.
+- **Harness MCP tools consumed by this skill** (canonical execution path — works without `@harness-engineering/core` in the project's `node_modules`):
+  - `validate_strategy({ path })` — Phase 0's routing oracle. Returns `{ present, valid, error? }`.
+  - `read_strategy({ path })` — Phase 2's read path. Returns `{ present, valid, doc?, error? }`.
+  - `write_strategy({ path, doc, skipBackup? })` — atomic disk write with `.bak` on first overwrite. Validates against `StrategyDocSchema` before touching disk.
+- **`@harness-engineering/core`** primitives the MCP tools wrap (only directly relevant when developing inside the monorepo or when the MCP server is unavailable):
+  - `validateStrategy(cwd)`, `parseStrategyDoc(raw)` + `asStrategyDoc(parsed)`, `writeStrategyDoc(doc, { cwd, skipBackup? })`, `serializeStrategyDoc(doc, opts?)`, `StrategyDocSchema`.
+- **Boundary with `harness-pulse`** — Pulse reads `STRATEGY.md` to seed metric names; strategy writes it. Pulse NEVER writes to `STRATEGY.md` (Decision 6 of the feedback-loops spec). Strategy NEVER touches `harness.config.json`.
+- **Boundary with `harness-brainstorming`** — Brainstorming consumes `STRATEGY.md` as grounding context; this skill produces it. Phase 5 of the strategic-anchor spec wires the brainstorming read path.
+- **Decision 1 (separation from roadmap.md)** — `docs/roadmap.md` is tactical phase tracking; `STRATEGY.md` is the strategic anchor. They never merge. Documented in `references/interview.md`.
+- **Decision 2 (placeholder rejection)** — A STRATEGY.md with the template placeholder text (e.g., `<2-4 sentences. ...>`) still in it FAILS validation. The skill never writes placeholder text; the writer validates before touching disk.
+
+## Success Criteria
+
+- On a project with no `STRATEGY.md`, the first-run interview produces a valid `STRATEGY.md` ≤ 100 lines that passes `harness validate`.
+- Re-running the skill on a project with a valid `STRATEGY.md` enters Phase 2 (update), preserves sections the user did not touch verbatim, bumps `version`, and updates `last_updated`.
+- All three pushback rules (`Fluff detection`, `Goal-as-strategy`, `Feature-list-as-strategy`) fire on at least one canonical anti-pattern fixture in `references/interview.md`.
+- After Phase 1 or 2, `harness validate` passes.
+- A `STRATEGY.md.bak` is written on the _first_ overwrite of an existing file, but NOT clobbered on subsequent overwrites (idempotency).
+- A present-but-invalid STRATEGY.md surfaces the validation error and offers the three repair paths from Phase 0; the skill never auto-overwrites a present-but-invalid file.
+
+## Examples
+
+### Example: greenfield (no STRATEGY.md)
+
+- Phase 0: `validate_strategy` returns `{ present: false, valid: true }`; route to Phase 1.
+- Phase 1.1: ask Target problem. User answers `"engineering teams want to be the best at shipping"`. **Fluff detection** fires: "be the best at" is empty-modifier vocabulary. Repair suggestion: "Replace `be the best at shipping` with a concrete diagnosis." User revises: `"engineering teams ship without a strategic anchor; brainstorming starts mid-stream"`. Accepted.
+- Phase 1.2-5: walk Our approach, Who it's for, Key metrics, Tracks with the same pushback discipline.
+- Phase 1.6: user declines optional sections.
+- Phase 1.7: show full doc; user confirms.
+- Phase 1.8: `write_strategy` writes the file; no `.bak` written (fresh create).
+- Phase 1.9: `harness validate` passes.
+- Phase 3: handoff note printed.
+
+### Example: update existing STRATEGY.md (one section)
+
+- Phase 0: `validate_strategy` returns `{ present: true, valid: true }`; route to Phase 2.
+- Phase 2.1-2: parse and summarize. Current state shows `name: Acme, last_updated: 2026-05-01, version: 3` and 5 required sections.
+- Phase 2.3: user selects `Tracks` for revisit.
+- Phase 2.4: re-interview Tracks. User answers `"add features X, Y, Z to the dashboard"`. **Feature-list-as-strategy** fires: 3+ feature names. Repair suggestion: "What's the coherent action these features are instances of?" User revises: `"- Dashboard track: collapse 3 separate widgets into one explorable surface"`. Accepted.
+- Phase 2.5: frontmatter bumped to `last_updated: 2026-06-02, version: 4`.
+- Phase 2.6: show diff; user confirms. `write_strategy` writes the file; `.bak` already exists from a prior overwrite — NOT clobbered.
+- Phase 2.7: `harness validate` passes.
+
+### Example: present-but-invalid STRATEGY.md
+
+- Phase 0: `validate_strategy` returns an error like `section "Key metrics": unfilled template placeholder detected (- <metric 1>: <how it's measured, where it lives>)`. Surface verbatim.
+- User picks **a) Fix now**: skill enters Phase 2 with `Key metrics` pre-selected. User answers; skill writes the file.
+
+### Example: pushback gives up after the cap
+
+- Phase 1.1: ask Target problem. User answers `"deliver value"`. **Fluff detection** fires. Round 1: suggest repair. User answers `"deliver maximum value"`. Round 2: suggest repair again. User answers `"deliver excellent value"`. **Cap reached** — skill captures the answer verbatim AND emits a flag in the doc summary: `"⚠ Target problem: flagged for revisit — pushback cap reached without concrete diagnosis."` Continue to the next section.
+
+## Gates
+
+- **The 2-round pushback cap is non-negotiable.** No flag, no override, no "I know what I'm doing" path — the cap is the disable mechanism (proposal §Risks).
+- **The skill MUST NEVER write to `STRATEGY.md` without explicit user confirmation** of the assembled or updated doc.
+- **`write_strategy` (or `writeStrategyDoc` when invoked directly) is the only sanctioned write path.** Do not hand-edit `STRATEGY.md`. The writer is the layer that validates against the schema, preserves the H1, writes the `.bak`, and does the atomic rename.
+- **`harness validate` must pass before exit** of Phase 1 or Phase 2. A malformed STRATEGY.md silently breaks the downstream grounding reads (Phases 5/6/7 of the spec).
+- **Round 1 pushback MUST always fire when a rule matches.** The cap protects users from infinite loops, not from feedback. Skipping round 1 violates the Iron Law.
+
+## Escalation
+
+- **User insists pushback is wrong:** Capture the answer verbatim after round 1 (do not push back twice if the user explicitly disagrees with round 1). Surface a one-line flag in the doc summary. Continue.
+- **`write_strategy` returns `{ written: false, error }` (or `writeStrategyDoc` throws a schema error directly):** Report the error verbatim. Do not retry without user fix. The most common cause is a section body that's empty or still contains template placeholder text.
+- **STRATEGY.md frontmatter is malformed (Phase 2):** Treat as present-but-invalid; route through Phase 0's three-path offer.
+- **User wants to add a section name not in the documented schema:** Refuse and cite Decision 2 of the proposal ("schema validation rejects unknown sections; expansion requires a separate ADR"). Offer to file the proposal ADR as a follow-up.
+- **Atomic rename fails (e.g., permission denied):** Surface the filesystem error verbatim. The temp file is cleaned up by the writer; no partial STRATEGY.md is left behind.

package/dist/agents/skills/claude-code/harness-strategy/references/interview.md

@@ -0,0 +1,122 @@
+# Strategy Interview Reference
+
+The first-run interview (and the per-section update flow) converts vague intent ("we want to be the best at X") into a small, concrete `STRATEGY.md`. This document is the rule book the skill quotes when pushing back on input.
+
+The interview is heuristic — the agent reading SKILL.md applies the rules. Nothing in `packages/core` parses the user's natural-language answers. The fixture-driven contract test in `agents/skills/tests/harness-strategy.test.ts` asserts the rule _names_ and the presence of repair-script keywords; rewording surrounding prose is free.
+
+## Pushback Rules
+
+Three rules, each cited verbatim in the skill output when it fires (so the user sees _why_ the answer was rejected, not just _that_ it was). **Each rule fires AT MOST TWICE per section. After the second pushback, capture what the user offered, flag the section, and move on.** The cap is the disable mechanism — there is no flag, no override, no "I know what I'm doing" path. The cap protects users from infinite loops, not from feedback. Round 1 MUST always fire when a rule matches.
+
+### Rule 1: Fluff detection
+
+**What it catches:** Empty modifiers and mission-statement vocabulary that look like answers but state nothing concrete.
+
+| Detection signal                                                              | Example trigger                                     |
+| ----------------------------------------------------------------------------- | --------------------------------------------------- |
+| Empty modifiers: "best", "leading", "world-class", "best-in-class", "premier" | _"We want to be the best at developer experience."_ |
+| Mission-statement verbs: "delight", "empower", "transform", "revolutionize"   | _"Empower engineers to build amazing things."_      |
+| Answers ≤ 5 words with no domain-specific noun                                | _"Deliver value."_ / _"Win the market."_            |
+| Adjective-only diagnoses: "broken", "bad", "slow" without an object           | _"It's slow."_ / _"It's hard."_                     |
+
+**Repair script:**
+
+> Replace `<phrase>` with a concrete diagnosis: _what is broken_, _for whom_, _that we can verify_. "We want to be the best at X" is not a diagnosis — it's an aspiration. Try the next layer down: which _specific_ failure mode are we trying to remove from the world?
+
+### Rule 2: Goal-as-strategy
+
+**What it catches:** Targets, KPIs, and fiscal-year aspirations dressed up as strategy. A goal is a destination; strategy is the bet you're making about how to get there.
+
+| Detection signal                                                         | Example trigger                                          |
+| ------------------------------------------------------------------------ | -------------------------------------------------------- |
+| Numeric targets without an underlying bet                                | _"Grow revenue by 20% this year."_ / _"Get to 10k DAU."_ |
+| Fiscal-year or quarter phrasing under `Target problem` or `Our approach` | _"By Q4 we'll have shipped the new platform."_           |
+| KPI-shape strings: "increase X by Y%", "reduce X to Z"                   | _"Reduce churn to under 5%."_                            |
+| Sentences that name a metric value but not a mechanism                   | _"Hit 99.9% uptime."_                                    |
+
+**Repair script:**
+
+> That's a goal. What is the **bet** — the choice you're making about _how_ to produce it — that goes underneath? Strategy is the coherent action that, if it works, produces the goal. "Grow revenue 20%" is the destination; _how_ you'll do it (which segment, which channel, which product wedge) is the strategy.
+
+### Rule 3: Feature-list-as-strategy
+
+**What it catches:** Roadmap-style enumerations of components dressed up as strategy. Feature lists don't survive contact with reality; the coherent action underneath does.
+
+| Detection signal                                                              | Example trigger                                       |
+| ----------------------------------------------------------------------------- | ----------------------------------------------------- |
+| Multi-item lists (≥3 bullets) of feature/component names under `Our approach` | _"- Dashboard, - Notifications, - Mobile app, - SSO"_ |
+| Noun-heavy lists with no verbs describing the coherent action                 | _"- AI agents - Knowledge graph - Skill registry"_    |
+| Track names that are feature names (e.g., `- Dashboard:`, `- Mobile:`)        | _"- Dashboard: ship the new dashboard"_               |
+| `Our approach` answered as a roadmap rather than a thesis                     | _"First we'll do X, then Y, then Z."_                 |
+
+**Repair script:**
+
+> Feature lists don't survive contact with reality. What's the **coherent action** these features are instances of? The features are downstream of the bet. State the bet, then the features become consequences ("we're betting on agent-orchestrated workflows, so dashboard/SSO/mobile fall out of that"), not the strategy itself.
+
+## The 2-Round Cap
+
+For every section, each rule fires at most twice:
+
+1. **Round 1** — Rule matches → cite the rule, quote the failing answer, offer the repair script. Wait for revised answer.
+2. **Round 2** — Rule matches the revised answer → cite the rule a second time, quote the repair script. Wait for the user's third attempt.
+3. **Cap reached** — Capture whatever the user offered on attempt 3. Emit a section flag in the doc summary:
+
+   > ⚠ <section name>: flagged for revisit — pushback cap reached without <concrete diagnosis | underlying bet | coherent action>.
+
+The flag is informational. It does NOT block the write — STRATEGY.md is the user's commitment, not the skill's gate. The flag lives in the _summary_ shown to the user, not in the on-disk file (the schema rejects unknown content).
+
+If the user explicitly says round 1's pushback is wrong (e.g., _"no, that IS the diagnosis — we really mean it this way"_), capture the answer verbatim after round 1. Do NOT push back twice if the user explicitly disagrees with round 1. This is not a third path around the cap; it's recognition that pushback is an offer, not a gate.
+
+## Separation from `docs/roadmap.md`
+
+The interview MUST refuse to capture tactical phase tracking (phase numbers, blockers, assignees, external IDs) under any section. That belongs in `docs/roadmap.md`. The two artifacts have different lifecycles:
+
+| Artifact          | Cadence            | Owner            | Content                                            |
+| ----------------- | ------------------ | ---------------- | -------------------------------------------------- |
+| `STRATEGY.md`     | Quarterly-ish      | Product / lead   | Target problem, approach, persona, metrics, tracks |
+| `docs/roadmap.md` | Per-phase / weekly | Eng orchestrator | Phase status, blockers, assignees, external-IDs    |
+
+If the user asks "where do I track that we're blocked on X" or "where do I record the assignee for phase 4" → answer: `docs/roadmap.md`, not `STRATEGY.md`. The separation is Decision 1 of the strategic-anchor proposal.
+
+## Section-by-section interview prompts
+
+Phase 1 walks the sections in template order. Each prompt is a single focused question; the rules above govern the response loop.
+
+| Section              | Opening prompt                                                                                                                                                   | Rules to apply                                                                                                                                   |
+| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Target problem       | _"In 2-4 sentences: what is specifically broken in the world that this product addresses? Not the goal — the diagnosis."_                                        | Fluff, Goal-as-strategy                                                                                                                          |
+| Our approach         | _"What is your distinctive bet on how to solve the target problem? The choice you're making about HOW, not WHAT you're building."_                               | Fluff, Goal-as-strategy, Feature-list                                                                                                            |
+| Who it's for         | _"Specific persona — who is the person, what context are they in, what alternatives are they currently using? 'Developers' is not a specific persona."_          | Fluff                                                                                                                                            |
+| Key metrics          | _"What 1-5 metrics, measured where, would tell you the bet is paying off? Each metric is a bullet line: `- <name>: <how measured, where it lives>`."_            | Fluff (per bullet)                                                                                                                               |
+| Tracks               | _"What 1-5 tracks of work are you currently investing in to advance the bet? Each track is a bullet line: `- <track name>: <one-sentence current investment>`."_ | Feature-list (per bullet)                                                                                                                        |
+| Milestones (opt)     | _"What 2-3 dated milestones would mark visible progress on the tracks? Skip if none yet."_                                                                       | Goal-as-strategy (milestones SHOULD be dated targets — accept them here even though Rule 2 rejects them under `Target problem` / `Our approach`) |
+| Not working on (opt) | _"What did you deliberately decide NOT to invest in this cycle? Explicit non-goals reduce future drift."_                                                        | Fluff                                                                                                                                            |
+| Marketing (opt)      | _"What 1-3 sentences describe how you'd pitch this to the persona? Often this is downstream of `Target problem` + `Our approach`."_                              | Fluff                                                                                                                                            |
+
+## Anti-pattern fixtures (referenced by the contract test)
+
+The skill's contract test (`agents/skills/tests/harness-strategy.test.ts`) asserts the rule names and key repair-script phrases appear in this file. The fixtures below are the canonical anti-patterns each rule must catch.
+
+### Fluff detection fixture
+
+> **User answer (Target problem):** _"We want to be the best at developer experience."_
+>
+> **Skill response:** "**Fluff detection** fired. `be the best at` is empty-modifier vocabulary — it states an aspiration, not a diagnosis. Try the next layer down: which _specific_ failure mode in developer experience are we trying to remove from the world?"
+
+### Goal-as-strategy fixture
+
+> **User answer (Our approach):** _"Grow revenue 20% this year and reduce churn to under 5%."_
+>
+> **Skill response:** "**Goal-as-strategy** fired. Those are goals, not approach. What is the **bet** — the choice you're making about _how_ to produce them — that goes underneath?"
+
+### Feature-list-as-strategy fixture
+
+> **User answer (Our approach):** _"- Ship the new dashboard. - Add notifications. - Build the mobile app. - Wire up SSO."_
+>
+> **Skill response:** "**Feature-list-as-strategy** fired. Feature lists don't survive contact with reality. What's the **coherent action** these features are instances of? The features are downstream of the bet."
+
+## Update-flow guidance
+
+Phase 2 of the skill re-interviews ONE user-selected section at a time. The same three rules apply. **Re-running a section does not exempt it from pushback** — "no rubber-stamping" is the proposal Decision 4 phrasing.
+
+When the user revisits a section and the new answer also triggers a rule, the 2-round cap still applies — counted _within that revisit_, not cumulatively across all-time runs.

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

@@ -0,0 +1,54 @@
+name: harness-strategy
+version: "0.1.0"
+description: First-run interview and update flow for STRATEGY.md — the durable upstream product anchor read by harness-brainstorming, harness-ideate, and harness-roadmap-pilot. Enforces three pushback rules (fluff, goal-as-strategy, feature-list-as-strategy) with a 2-round-per-section cap. Phase 2 ships the skill; downstream wiring (init, brainstorming, roadmap-pilot, ideate, knowledge graph) ships in spec Phases 3-7.
+stability: static
+cognitive_mode: configuration-interviewer
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+  - cursor
+  - codex
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-strategy
+  args: []
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-strategy
+type: rigid
+tier: 2
+phases:
+  - name: route
+    description: Route by STRATEGY.md presence and validity (absent → first-run; valid → update; invalid → repair offer)
+    required: true
+  - name: first-run-interview
+    description: Walk sections in template order with pushback; cap at 2 rounds per section; write via writeStrategyDoc
+    required: true
+  - name: update
+    description: Re-interview a single user-selected section; bump version and last_updated; preserve untouched sections
+    required: false
+  - name: handoff
+    description: Note which downstream skills (harness-brainstorming, harness-ideate, harness-roadmap-pilot, BusinessKnowledgeIngestor) will pick up STRATEGY.md as grounding
+    required: true
+state:
+  persistent: true
+  files:
+    - STRATEGY.md
+    - STRATEGY.md.bak
+depends_on: []
+keywords:
+  - strategy
+  - strategic-anchor
+  - product-anchor
+  - upstream-grounding
+  - compound-engineering
+  - rumelt

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

@@ -140,6 +140,60 @@ Detect plugin-only state by checking whether `harness` resolves on PATH (`comman
 
     **Skip this step entirely if Phase 1 step 5 classified the project as a test suite.** Test-suite projects will be dispatched at step 6 below to `initialize-test-suite-project` and have no UI to govern.
 
+5c. **Capture strategic anchor (all levels).** Offer a three-way prompt for `STRATEGY.md` — the durable upstream product anchor read by `harness-brainstorming`, `harness-ideate`, and `harness-roadmap-pilot`. Use `emit_interaction`:
+
+    ```json
+    emit_interaction({
+      type: "question",
+      question: {
+        text: "Capture strategic anchor (STRATEGY.md) now?",
+        options: [
+          {
+            label: "Yes — run the strategy interview",
+            pros: [
+              "Grounds brainstorm/ideate/roadmap-pilot in product-level context",
+              "Durable across milestones and phases (peer of README.md)"
+            ],
+            cons: ["Adds an interview (10-20 minutes) to init"],
+            risk: "low",
+            effort: "medium"
+          },
+          {
+            label: "No — this project does not need a strategy doc",
+            pros: ["Permanent decline recorded; init does not re-ask on rerun"],
+            cons: ["Re-running init will not re-offer; user must run /harness:strategy manually"],
+            risk: "low",
+            effort: "low"
+          },
+          {
+            label: "Not sure yet",
+            pros: ["Decision deferred without commitment", "Can run /harness:strategy later"],
+            cons: ["No decline flag set; init may re-offer on rerun"],
+            risk: "low",
+            effort: "low"
+          }
+        ],
+        recommendation: { optionIndex: 0, reason: "Strategy grounds brainstorm/ideate/roadmap-pilot — value compounds as the project grows", confidence: "medium" }
+      }
+    })
+    ```
+
+    Before prompting, check whether `STRATEGY.md` already exists at repo root. Three cases:
+
+    - **Absent (most common on init).** Present the prompt above. Apply the answer:
+      - **Yes:** delegate to `harness-strategy` (which routes via its own Phase 0 to the first-run interview). When `harness-strategy` completes, continue with step 6.
+      - **No:** write `init.strategy.declined: true` to `.harness/state.json` (merge into existing JSON; do not clobber). This is the explicit decline location; re-running init detects the flag and skips the prompt.
+      - **Not sure yet:** no state write. `/harness:strategy` remains available standalone, and a future re-run of init will re-offer.
+
+    - **Present and valid.** Skip the prompt silently. Surface a one-line note: `STRATEGY.md detected — downstream skills will pick it up as grounding`. No `init.strategy.declined` write.
+
+    - **Present but invalid.** Surface the validation error verbatim (run a Node one-liner that imports `validateStrategy` from `@harness-engineering/core` and pipes the error). Offer three paths (mirror `harness-strategy` Phase 0):
+      - **a) Fix now via `/harness:strategy` update** → delegate to `harness-strategy` with the broken section pre-selected.
+      - **b) Move file to `STRATEGY.md.bak.<YYYY-MM-DD-HHmm>` and run a fresh interview** → rename, then delegate to `harness-strategy` Phase 1.
+      - **c) Ignore for this init and proceed** → record `init.strategy.declined: true` and continue. Init does NOT block on present-but-invalid STRATEGY.md.
+
+    Mirror the i18n / design-system pattern: ask once, record the answer, never silently skip.
+
 6. **Test-suite projects only — dispatch to `initialize-test-suite-project`.** If Phase 1 step 5 classified this as a test suite, invoke `initialize-test-suite-project` now and let it own archetype selection, shared-library decision, layer variants (A self-contained vs B consumer), ESLint flat-config fix, tag taxonomy, reporter stack, custom report, and the "prove the guards fire" verification. Return here for Phase 4 step 4+ (knowledge graph, roadmap, commit). Product and service projects skip this step entirely.
 
 ### Phase 4: VALIDATE — Confirm Everything Works
@@ -269,6 +323,8 @@ This phase closes the parity gap that the marketplace plugin install does not co
 - **`harness integrations list` / `harness integrations add <name>`** — Phase 5 step 6. Lists Tier-0 (zero-config) and Tier-1 (API-key) MCP integrations and adds them to project `.mcp.json`.
 - **`harness-i18n-workflow configure` + `harness-i18n-workflow scaffold`** — Invoked during Phase 3 if the project will support multiple languages. Sets up i18n configuration and translation file structure.
 - **`harness-design-system` (deferred via `on_new_feature`)** — Phase 3 step 5b records `design.enabled` + `design.platforms` in `harness.config.json` but does NOT run the full design-system skill. Token generation defers to the first design-touching feature, where `harness-design-system` fires via `on_new_feature` and reads `design.enabled` to decide whether to proceed.
+- **`harness-strategy`** — Phase 3 step 5c delegates to this skill on "Yes". The skill conducts a first-run interview (pushback rules with a 2-round cap per section) and writes a valid `STRATEGY.md` at repo root via `writeStrategyDoc`. On "No" init writes `init.strategy.declined: true` to `.harness/state.json`. On "Not sure yet" no state is written; the user can run `/harness:strategy` standalone. When `STRATEGY.md` already exists and is valid the prompt is skipped; when present-but-invalid the user gets the three-path repair offer.
+- **`validateStrategy`** — `@harness-engineering/core` helper used by Phase 3 step 5c to detect present-but-invalid `STRATEGY.md`. Invoked through a Node one-liner so init does not require importing core directly.
 - **`initialize-test-suite-project`** — Sub-skill. Invoked during Phase 3 step 6 when Phase 1 step 5 classified the project as a test suite. Owns archetype selection, shared-library vs in-repo decision, layer variants, tag taxonomy, reporter stack, custom report, and "prove the guards fire" verification.
 - **`harness-roadmap` skill** — Phase 6 step 1 invokes this skill (or `/harness:roadmap --create`) when the user opts in to creating `docs/roadmap.md`. The `manage_roadmap` MCP tool does not create roadmaps; it manages entries in an existing one.
 - **`manage_roadmap` MCP tool** — Phase 6 step 1, when `design.enabled === true`, calls `manage_roadmap` with `action: add` to insert a `planned` "Set up design system" item under milestone `Current Work` with a summary describing the deferred work.
@@ -285,6 +341,7 @@ This phase closes the parity gap that the marketplace plugin install does not co
 - All generated files are committed in a single atomic commit
 - i18n configuration is set if the human chose to enable it during init
 - For non-test-suite projects, the design-system question was asked and `harness.config.json` reflects the answer: `design.enabled: true` (with `design.platforms` populated) for yes, `design.enabled: false` for no, or absent for not-sure.
+- The strategy question (Phase 3 step 5c) was asked unless `STRATEGY.md` already existed and was valid (in which case the prompt was skipped silently with a one-line detection note). The answer was recorded according to the documented semantics: Yes → `STRATEGY.md` exists and `harness validate` passes against `StrategyDocSchema`; No → `.harness/state.json` contains `init.strategy.declined: true`; Not sure yet → no `STRATEGY.md` and no `init.strategy.declined` flag.
 - **Phase 5 (INSTRUMENT) outputs:** `.harness/graph/` is populated; `.harness/arch/baselines.json` exists; `harness check-perf` ran without errors (intermediate and above); `.harness/telemetry.json` exists if the human opted into identity tagging; legacy layout warnings were surfaced via `harness migrate --dry-run` and either resolved or explicitly deferred; Tier-0 MCP integrations (context7, sequential-thinking, playwright) are present in the project's `.mcp.json` (or the human declined and that decision is recorded).
 - The roadmap question was asked. If the user answered yes, `docs/roadmap.md` exists and was created via `harness-roadmap` (or the documented `/harness:roadmap --create` fallback).
 - When `design.enabled === true` AND the user answered yes to the roadmap question, `docs/roadmap.md` contains a `planned` entry titled "Set up design system" under milestone `Current Work` with a summary describing the deferred work. The entry is absent in all other answer combinations.
@@ -293,16 +350,19 @@ This phase closes the parity gap that the marketplace plugin install does not co
 
 ## Rationalizations to Reject
 
-| Rationalization                                                          | Why It Is Wrong                                                                                                                                                                                                                                                                 |
-| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| "The generated AGENTS.md template looks fine -- no need to customize it" | Phase 3 says do not blindly accept generated content. Without project-specific descriptions, agents receive generic instructions.                                                                                                                                               |
-| "We should start at the advanced level since we want full coverage"      | The skill recommends basic for new projects. Each level builds on the previous. Jumping to advanced creates misconfigured rules.                                                                                                                                                |
-| "I will skip the i18n question to keep setup fast"                       | Phase 3 requires asking about i18n and recording the decision. Skipping creates ambiguity about whether the omission was intentional.                                                                                                                                           |
-| "I will skip the design-system question to keep setup fast"              | Phase 3 step 5b requires asking about design and recording the answer in `design.enabled`. Skipping creates ambiguity about whether the omission was intentional and bypasses the linkage between init and the deferred `harness-design-system` invocation on `on_new_feature`. |
-| "Validation passed, so the project is ready"                             | Phase 5 captures baselines, configures telemetry identity, surfaces legacy warnings, and wires Tier-0 integrations. Validation alone is not sufficient.                                                                                                                         |
-| "Plugin install means setup is done"                                     | The marketplace plugin ships skills, slash commands, subagents, hooks, and MCP — but it cannot mutate the user's project state. `harness.config.json`, baselines, telemetry identity, and Tier-0 integrations require running this skill once per project.                      |
-| "Skip Phase 5 if we already ran `harness setup`"                         | Phase 5 is idempotent. It safely no-ops where setup already wired things and fills gaps where it didn't (common case: setup ran once, then a new Tier-0 integration was added or a layout was migrated). Re-running is the right behavior.                                      |
-| "This is a test suite, we'll configure layers in this skill"             | Phase 3 step 6 dispatches to `initialize-test-suite-project` for archetype selection, layer variants, and the rest. Do not inline test-suite-specific configuration here — the sub-skill owns it and carries the gotchas.                                                       |
+| Rationalization                                                              | Why It Is Wrong                                                                                                                                                                                                                                                                                                                                                       |
+| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "The generated AGENTS.md template looks fine -- no need to customize it"     | Phase 3 says do not blindly accept generated content. Without project-specific descriptions, agents receive generic instructions.                                                                                                                                                                                                                                     |
+| "We should start at the advanced level since we want full coverage"          | The skill recommends basic for new projects. Each level builds on the previous. Jumping to advanced creates misconfigured rules.                                                                                                                                                                                                                                      |
+| "I will skip the i18n question to keep setup fast"                           | Phase 3 requires asking about i18n and recording the decision. Skipping creates ambiguity about whether the omission was intentional.                                                                                                                                                                                                                                 |
+| "I will skip the design-system question to keep setup fast"                  | Phase 3 step 5b requires asking about design and recording the answer in `design.enabled`. Skipping creates ambiguity about whether the omission was intentional and bypasses the linkage between init and the deferred `harness-design-system` invocation on `on_new_feature`.                                                                                       |
+| "I will skip the strategy question — it's just paperwork"                    | Phase 3 step 5c is the only point in the workflow where init asks the user to capture the strategic anchor. Skipping bypasses the grounding signal that brainstorming, ideate, and roadmap-pilot read; downstream skill output degrades silently. Even a "No" or "Not sure yet" answer is better than no answer because it locks in the decision (or absence of one). |
+| "STRATEGY.md exists already, so I should re-run the interview to refresh it" | When `STRATEGY.md` is present and valid, Phase 3 step 5c skips the prompt silently. Refreshing strategy mid-init is out of scope — that is what the standalone `/harness:strategy` update flow is for. Surface a one-line detection note and continue.                                                                                                                |
+| "STRATEGY.md is present but invalid, so I should block init"                 | Phase 3 step 5c explicitly does NOT block. It surfaces the validation error, offers three repair paths (fix now / move-to-bak / ignore), and continues based on the user's choice. Init is the wrong place to gate on strategy correctness.                                                                                                                           |
+| "Validation passed, so the project is ready"                                 | Phase 5 captures baselines, configures telemetry identity, surfaces legacy warnings, and wires Tier-0 integrations. Validation alone is not sufficient.                                                                                                                                                                                                               |
+| "Plugin install means setup is done"                                         | The marketplace plugin ships skills, slash commands, subagents, hooks, and MCP — but it cannot mutate the user's project state. `harness.config.json`, baselines, telemetry identity, and Tier-0 integrations require running this skill once per project.                                                                                                            |
+| "Skip Phase 5 if we already ran `harness setup`"                             | Phase 5 is idempotent. It safely no-ops where setup already wired things and fills gaps where it didn't (common case: setup ran once, then a new Tier-0 integration was added or a layout was migrated). Re-running is the right behavior.                                                                                                                            |
+| "This is a test suite, we'll configure layers in this skill"                 | Phase 3 step 6 dispatches to `initialize-test-suite-project` for archetype selection, layer variants, and the rest. Do not inline test-suite-specific configuration here — the sub-skill owns it and carries the gotchas.                                                                                                                                             |
 
 ## Examples
 
@@ -377,6 +437,11 @@ Step 5b (design): "Will this project have a UI requiring a design system?"
   Inform: "Design tokens will be generated when you start your first design-touching
   feature — harness-design-system fires automatically via on_new_feature."
 
+Step 5c (strategy): "Capture strategic anchor (STRATEGY.md) now?"
+  Human: "Yes."
+  Delegate to harness-strategy → first-run interview → STRATEGY.md written.
+  Result: STRATEGY.md exists at repo root; harness validate passes against StrategyDocSchema.
+
 Step 6 (test-suite dispatch): skipped (not a test suite).
 ```
 
@@ -482,6 +547,7 @@ npx @harness-engineering/cli init  # auto-detects framework
 Customize AGENTS.md with project-specific content.
 Phase 3 step 5 (i18n): "No, English only." → i18n.enabled = false.
 Phase 3 step 5b (design): "No, this is a backend service." → design.enabled = false.
+Phase 3 step 5c (strategy): "Not sure yet." → no STRATEGY.md, no init.strategy.declined flag; user can run /harness:strategy later.
 Phase 3 step 6 (test-suite dispatch): not a test suite, skipped.
 ```
 

package/dist/agents/skills/codex/align-design-system/SKILL.md

@@ -65,6 +65,7 @@ For each finding classified as `suggestion`: emit a human-readable description p
 
 - **`harness align-design-system`** — the CLI entry point. `--dry-run` for preview; `--write` is the default. Standard `--json` / `--verbose` / `--quiet` flags.
 - **`harness align-design-system --mode pipeline`** — orchestrator-driven mode. Reads pre-classified findings from handoff.json; writes outcomes back.
+- **`harness align-design-system --revert`** — inverse-applies the most-recent batch recorded at `.harness/align/last-batch.json`. Skips files edited externally since the apply (content-hash check). Idempotent: a second revert on the same batch is a no-op because the file no longer matches the recorded post-apply text.
 - **`mcp__harness__align_design_system`** — MCP tool for agent consumption. Same input/output shape as the function call.
 - **`detect-design-drift`** — soft dependency. Standalone mode invokes detect internally; pipeline mode trusts the orchestrator to have done it.
 - **`harness check-design`** — composes detect (as 3rd verifier) into a single-pass design check. align is the matching FIX step; together they form the DETECT → FIX cycle that the (future) #5 orchestrator will loop.
@@ -82,6 +83,7 @@ See `docs/changes/design-pipeline/align-design-system/proposal.md` for the full
 - Pipeline mode writes `pipeline.fixesApplied` back to handoff.json
 - `--dry-run` produces identical `FixOutcome` shapes but never writes files
 - Re-running detect after align produces strictly fewer T001/T002/T003 findings
+- `--revert` re-applies the inverse of the most-recent `fixesApplied` batch; no-op when the file has been edited externally since the apply
 
 ## Examples
 
@@ -147,6 +149,21 @@ src/SaveButton.tsx
 
 v1 never auto-applies primitive adoption — prop translation across `<button>` ⇄ `<Button>` is the kind of judgment-call that benefits from a human or LLM review.
 
+### Example: Revert the last batch
+
+After a write run, the applied diffs (plus a SHA-256 of each post-apply file) are persisted to `.harness/align/last-batch.json`. Running `harness align-design-system --revert` reads that batch and inverse-applies each diff:
+
+```
+src/Card.tsx
+  ✓ DRIFT-T001:2 — Hex color "#0066cc" should use a token reference instead of a raw literal
+     before: const styles = { color: tokens.color.brand.primary };
+     after:  const styles = { color: "#0066cc" };
+
+Summary: 1 reverted, 0 suggestions, 0 skipped, 0 failed (1 files modified, 4ms)
+```
+
+If the file has been edited externally between apply and revert (the SHA-256 doesn't match), every entry for that file is skipped with `skipped-unsafe / reason: file changed externally since apply`. A second revert on the same batch is a no-op for the same reason — the file's post-revert content no longer matches the recorded post-apply text.
+
 ## Gates
 
 - **No autofix without classifier approval.** Every codemod application goes through `classifyFinding`. If the classifier returns `suggestion`, NO file write occurs — even for the same finding code in the same file.
@@ -162,6 +179,7 @@ v1 never auto-applies primitive adoption — prop translation across `<button>`
 - **When the codemod corrupts a file (rare):** every application includes a structured diff. Recover via `git checkout <file>`. If the same input repeatedly corrupts, report the case — pre-flight classifier rules are conservative by design.
 - **When pipeline-mode run finds no `pipeline.driftFindings` field:** align exits cleanly with empty outcomes. The orchestrator's contract is to write the field BEFORE invoking align.
 - **When `--dry-run` shows fixes you don't want applied:** scope with `--files <glob>` to apply only specific files, or invoke align in pipeline mode with a curated `pipeline.fixBatch` list.
+- **When you want to undo an apply:** run `harness align-design-system --revert`. It reads `.harness/align/last-batch.json`, content-hash-checks each file, and inverse-applies. Files edited since the apply are skipped (no silent corruption); recover via `git checkout <file>` if the content-hash check blocks revert and the prior commit is still in history.
 - **When you want primitive-adoption fixes today:** apply the suggestion manually. The v1.x sub-project will add prop-translation tables + import resolution + revert-on-test-fail.
 - **When align is invoked without detect having run first (standalone mode):** standalone mode runs detect internally — no manual ordering needed. Pipeline mode trusts the orchestrator to populate findings.
 

package/dist/agents/skills/codex/align-design-system/skill.yaml

@@ -31,6 +31,9 @@ cli:
     - name: mode
       description: standalone (default) or pipeline (read findings from handoff.json)
       required: false
+    - name: revert
+      description: Inverse-apply the most-recent batch persisted at .harness/align/last-batch.json
+      required: false
 mcp:
   tool: run_skill
   input: