@harness-engineering/cli 1.27.1 → 1.28.0

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

@@ -23,6 +23,18 @@ If you find yourself writing implementation code, STOP. You have left advisory m
 
 ## Process
 
+### Storage Location
+
+Architecture artifacts (discovery, analysis, proposals, ADRs) are human-facing documentation and live under the project's docs directory — NOT under `.harness/` (which is reserved for tool state like debug sessions, graph data, and baselines).
+
+Resolve the storage root as follows:
+
+1. Read `docsDir` from `harness.config.json` at the project root. If present, use `<docsDir>/architecture/` (e.g. `docsDir: "./docs"` → `docs/architecture/`).
+2. If `harness.config.json` is absent or has no `docsDir`, default to `docs/architecture/`.
+3. If a legacy `.harness/architecture/` directory exists from a prior version of this skill, surface this to the human and offer to migrate it via `git mv .harness/architecture <docsDir>/architecture` before proceeding.
+
+All path references below use `<docs>/architecture/` as shorthand for the resolved location.
+
 ### Phase 1: DISCOVER — Understand the Problem Space
 
 **Gate: This phase requires human answers. Do not proceed to Phase 2 until the human has responded.**
@@ -42,7 +54,7 @@ Ask these 5 questions. Wait for answers before proceeding.
 Record the answers verbatim. Do not paraphrase or interpret at this stage.
 
 ```
-Store answers in: .harness/architecture/<topic>/discovery.md
+Store answers in: <docs>/architecture/<topic>/discovery.md
 ```
 
 ---
@@ -107,7 +119,7 @@ Look for existing issues that may affect the decision:
 ```
 
 ```
-Store analysis in: .harness/architecture/<topic>/analysis.md
+Store analysis in: <docs>/architecture/<topic>/analysis.md
 ```
 
 ### Graph-Enhanced Context (when available)
@@ -185,7 +197,7 @@ However, if <condition>, Option <Y> would be stronger.
 Present the options to the human and wait for their choice.
 
 ```
-Store proposal in: .harness/architecture/<topic>/proposal.md
+Store proposal in: <docs>/architecture/<topic>/proposal.md
 ```
 
 ---
@@ -251,7 +263,7 @@ discussion.>
 Save the ADR:
 
 ```
-.harness/architecture/<topic>/ADR-<number>.md
+<docs>/architecture/<topic>/ADR-<number>.md
 ```
 
 Also link from the project's ADR index if one exists.
@@ -261,7 +273,7 @@ Also link from the project's ADR index if one exists.
 - Extends the human-architect model — the skill is a thinking partner, not a decision maker
 - Respects architectural constraints defined in harness.config.json
 - Outputs structured ADR that other skills can reference
-- Reads prior ADRs from `.harness/architecture/` for consistency
+- Reads prior ADRs from `<docs>/architecture/` (resolved from `harness.config.json` `docsDir`, default `docs/architecture/`) for consistency
 
 ## Success Criteria
 

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

@@ -48,5 +48,5 @@ phases:
 state:
   persistent: true
   files:
-    - .harness/architecture/
+    - docs/architecture/
 depends_on: []

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

@@ -80,12 +80,12 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → INTEGRATE
 
 ```
 subagent_type: "harness-planner"
-prompt: "Phase {N}: {name}. Spec: {specPath}. Session: {sessionSlug}. Rigor: {rigorLevel}. Follow harness-planning. Write plan to docs/plans/. Write {sessionDir}/handoff.json when done."
+prompt: "Phase {N}: {name}. Spec: {specPath}. Session: {sessionSlug}. Rigor: {rigorLevel}. Follow harness-planning. Write plan to docs/changes/<topic>/plans/ (topic from specPath; legacy docs/plans/ if spec is outside docs/changes/). Write {sessionDir}/handoff.json when done."
 ```
 
 On return: read `planPath` from `{sessionDir}/handoff.json`. Complexity override check: `low` + tasks>10 or checkpoints>3 → `"medium"`; tasks>20 or checkpoints>6 → `"high"`. Update state `planPath`. → APPROVE_PLAN.
 
-**Interactive plan (high):** Check for plan file at `docs/plans/*{phase-name}*` or `planPath` in handoff. If found: update `planPath` → APPROVE_PLAN. If not: remind and wait.
+**Interactive plan (high):** Check for plan file at `docs/changes/<topic>/plans/*{phase-name}*` (or legacy `docs/plans/*{phase-name}*`) or `planPath` in handoff. If found: update `planPath` → APPROVE_PLAN. If not: remind and wait.
 
 ---
 
@@ -275,7 +275,7 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 
 **INIT:** 3 phases found: Phase 1: Core Scanner (low), Phase 2: Rule Engine (high), Phase 3: CLI Integration (low).
 
-**Phase 1 — ASSESS → PLAN:** harness-planner dispatched. Returns plan: `docs/plans/2026-03-19-core-scanner-plan.md` (8 tasks).
+**Phase 1 — ASSESS → PLAN:** harness-planner dispatched. Returns plan: `docs/changes/security-scanner/plans/2026-03-19-core-scanner-plan.md` (8 tasks).
 
 **Phase 1 — APPROVE_PLAN (auto):** All signals false. "Auto-approved Phase 1: Core Scanner | auto | low | no concerns | 8 tasks."
 
@@ -287,7 +287,7 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 
 **Phase 2 — ASSESS:** High complexity. "Run `/harness:planning` interactively, then re-invoke." [User plans interactively. Re-invokes.]
 
-**INIT (resume):** "Resuming from PLAN, phase 2: Rule Engine. Found plan: docs/plans/2026-03-19-rule-engine-plan.md"
+**INIT (resume):** "Resuming from PLAN, phase 2: Rule Engine. Found plan: docs/changes/security-scanner/plans/2026-03-19-rule-engine-plan.md"
 
 **Phase 2 — APPROVE_PLAN (paused):** Complexity: high triggered. "Approve? → yes" **EXECUTE → VERIFY → REVIEW → PHASE_COMPLETE.** 14 tasks, 1 retry.
 

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

@@ -242,7 +242,7 @@ git diff --stat HEAD~1                    # measure diff size
 git diff HEAD~1 -- <file>                 # per-file diff
 grep -n "import\|require\|from " <file>   # find imports
 find . -name "*<module>*test*" -o -name "*<module>*spec*"
-grep -rl "<component>" docs/changes/ docs/design-docs/ docs/plans/
+grep -rl "<component>" docs/changes/ docs/design-docs/ docs/plans/   # docs/changes/*/plans/ covered by docs/changes/; docs/plans/ kept for legacy
 grep -rn "interface\|type\|schema" <changed-file> | head -20
 ```
 

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

@@ -25,7 +25,12 @@
    - CSS files with custom properties (`--color-*`, `--font-*`, `--space-*`)
    - `theme.ts`, `theme.js`, `styles/variables.*` -- CSS-in-JS or preprocessor variables
 
-2. **Check harness configuration.** Read `harness.config.json` for:
+2. **Check harness configuration.** Read `harness.config.json` and apply the `design.enabled` short-circuit _before_ doing anything else in Phase 1:
+   - If `design.enabled` is `false`: the project explicitly declined a design system during init. Log `"design.enabled is false in harness.config.json — project explicitly declined the design system. Skipping."` and stop. Do not run the rest of Phase 1 or any subsequent phase.
+   - If `design.enabled` is `true`: proceed normally with the rest of Phase 1.
+   - If `design.enabled` is absent (the field does not appear under `design`): the project has not decided yet. Surface a gentle prompt: "This project has not configured a design system. Would you like to enable one now? (yes / no / not sure)". On `yes`, proceed with Phase 1 — note that this answer is not persisted to `harness.config.json` (the init skill is the canonical writer of that field), so this prompt will fire again on the next `on_new_feature` invocation; run `harness init --migrate` to make the choice permanent. On `no` or `not sure`, stop without writing anything to `harness.config.json`.
+
+   After the gate, read the remaining design configuration fields:
    - `design.strictness` -- enforcement level (`strict`, `standard`, `permissive`)
    - `design.platforms` -- which platforms are enabled (web, mobile)
    - `design.tokenPath` -- path to tokens file (default: `design-system/tokens.json`)

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

@@ -27,15 +27,15 @@ Deviating mid-execution introduces untested assumptions, breaks atomicity, and m
 When invoked by autopilot (or with explicit arguments), resolve paths before starting:
 
 1. **Session slug:** If `session-slug` argument provided, set `{sessionDir} = .harness/sessions/<session-slug>/`. Pass to `gather_context({ session: "<session-slug>" })`. All state/handoff writes go to `{sessionDir}/`.
-2. **Plan path:** If `plan-path` argument provided, read plan from that path. Otherwise, discover from `{sessionDir}/handoff.json` (read upstream planning output) or search `docs/plans/`.
+2. **Plan path:** If `plan-path` argument provided, read plan from that path. Otherwise, discover from `{sessionDir}/handoff.json` (read upstream planning output) or search `docs/changes/<topic>/plans/` (preferred) and `docs/plans/` (legacy fallback).
 
-When no arguments are provided (standalone invocation), discover plan from `docs/plans/` or prompt. Global `.harness/` paths used as fallback.
+When no arguments are provided (standalone invocation), discover plan from `docs/changes/<topic>/plans/` (or legacy `docs/plans/`) or prompt. Global `.harness/` paths used as fallback.
 
 ---
 
 ### Phase 1: PREPARE — Load State and Verify Prerequisites
 
-1. **Load the plan.** If `plan-path` argument was resolved, read from that path. Otherwise read from `docs/plans/`. Identify total task count and checkpoints.
+1. **Load the plan.** If `plan-path` argument was resolved, read from that path. Otherwise read from the resolved discovery location (`docs/changes/<topic>/plans/` preferred, `docs/plans/` legacy fallback). Identify total task count and checkpoints.
 
 2. **Gather context in one call.** Use `gather_context` to load all working context:
 
@@ -384,7 +384,7 @@ Claims about task completion, test results, or code behavior MUST cite evidence:
 **Session Start (fresh):**
 
 ```
-Read plan: docs/plans/2026-03-14-notifications-plan.md (5 tasks)
+Read plan: docs/changes/notifications/plans/2026-03-14-notifications-plan.md (5 tasks)
 Read state: .harness/state.json — not found (fresh start, Task 1)
 Read learnings: .harness/learnings.md — not found
 Run: harness validate — passes. Clean baseline.

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

@@ -207,7 +207,7 @@ i18n Process Validation
 =======================
 Mode:           gate (standard)
 Workflow:        planning
-Artifact:        docs/plans/2026-03-20-checkout-redesign-plan.md
+Artifact:        docs/changes/checkout-redesign/plans/2026-03-20-checkout-redesign-plan.md
 
 Checks:
 [PASS] Plan contains i18n-related task (Task 7: "Extract checkout strings")
@@ -319,7 +319,7 @@ i18n Process Validation
 =======================
 Mode:           gate (standard)
 Workflow:        planning
-Artifact:        docs/plans/2026-03-20-product-reviews-plan.md
+Artifact:        docs/changes/product-reviews/plans/2026-03-20-product-reviews-plan.md
 
 Checks:
 [FAIL] No i18n-related tasks found in plan

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

@@ -33,7 +33,7 @@ When invoked by autopilot (or with explicit arguments), resolve paths before sta
 2. **Plan path:** Discover from `{sessionDir}/handoff.json` (read upstream execution/verification output). The plan contains integration tasks tagged `category: "integration"` and the `integrationTier` field.
 3. **Rigor level:** If `fast`/`thorough` argument provided, use it. Otherwise default to `standard`.
 
-When no arguments are provided (standalone invocation), discover plan from `docs/plans/` or prompt. Global `.harness/` paths used as fallback.
+When no arguments are provided (standalone invocation), discover plan from `docs/changes/<topic>/plans/` (preferred) or `docs/plans/` (legacy fallback) or prompt. Global `.harness/` paths used as fallback.
 
 ---
 

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

@@ -70,6 +70,7 @@ Extract business knowledge from all available sources into a fresh snapshot.
 
 4. **Build Fresh Snapshot:** Collect all extraction results into a `KnowledgeSnapshot`.
    - Each entry has: `id`, `type`, `contentHash`, `source`, `name`
+   - Each entry's `domain` is resolved via path-based inference (`packages/<dir>`, `apps/<dir>`, etc.) unless an explicit `metadata.domain` is set; projects can extend or override via `knowledge.domainPatterns` and `knowledge.domainBlocklist` in `harness.config.json` — see [`docs/knowledge/graph/node-edge-taxonomy.md`](../../../../docs/knowledge/graph/node-edge-taxonomy.md#domain-inference) for full precedence.
 
 **Output:** `context.extractionSnapshot` populated.
 

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

@@ -259,7 +259,7 @@ State: Mid-execution on a 6-task notification feature plan
 
 ```
 Produce orientation with all sections. Getting Started for this context:
-1. Read the plan at docs/plans/2026-03-14-notifications-plan.md
+1. Read the plan at docs/changes/notifications/plans/2026-03-14-notifications-plan.md
 2. Resume execution at Task 4 (state shows Tasks 1-3 complete)
 3. Note the UTC normalization gotcha from learnings before working with dates
 ```

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

@@ -293,7 +293,7 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
 4. **Run `harness validate`** to verify project health before writing the plan.
 5. **Check failures log.** Read `.harness/failures.md`. If planned approaches match known failures, flag them.
 6. **Run soundness review.** Invoke `harness-soundness-review --mode plan` against the draft. Do not proceed until the review converges with no remaining issues.
-7. **Write the plan to `docs/plans/`.** Naming: `YYYY-MM-DD-<feature-name>-plan.md`. Create directory if needed.
+7. **Write the plan to `docs/changes/<topic>/plans/`.** Naming: `YYYY-MM-DD-<feature-name>-plan.md`. Resolve `<topic>` from the spec path — if the spec lives at `docs/changes/<topic>/proposal.md`, the plan goes in the sibling `plans/` directory. If the spec is not under `docs/changes/`, fall back to `docs/plans/` and flag the spec location for human review. Create directories as needed.
 8. **Write handoff.** Write to the session-scoped path when session slug is known, otherwise fall back to global path:
    - Session-scoped (preferred): `.harness/sessions/<session-slug>/handoff.json`
    - Global (fallback, **deprecated**): `.harness/handoff.json`
@@ -392,7 +392,7 @@ When referencing existing code in task specs, cite evidence using `file:line` fo
 
 - **`harness validate`** — Run in Phase 4 (before writing plan) and included in every task.
 - **`harness check-deps`** — Referenced in tasks adding imports or creating modules.
-- **Plan location** — `docs/plans/YYYY-MM-DD-<feature-name>-plan.md`.
+- **Plan location** — `docs/changes/<topic>/plans/YYYY-MM-DD-<feature-name>-plan.md` when the spec lives under `docs/changes/<topic>/proposal.md`; otherwise `docs/plans/` as a fallback.
 - **Handoff** — Once approved, invoke harness-execution for task-by-task implementation.
 - **Session directory** — Session-scoped writes go to `.harness/sessions/<slug>/`. Structure: `handoff.json`, `state.json`, `artifacts.json` (registry of spec/plan paths and produced file lists). Global `.harness/handoff.json` is deprecated for session-aware invocations.
 - **`emit_interaction`** — Call at end of Phase 4 to suggest transitioning to execution (confirmed transition).
@@ -422,7 +422,7 @@ Only apply when modifying existing documented behavior. When `docs/changes/` exi
 
 ## Success Criteria
 
-- Plan document exists in `docs/plans/` with all required sections
+- Plan document exists at the resolved location (`docs/changes/<topic>/plans/` or `docs/plans/` fallback) with all required sections
 - Every task completable in 2-5 minutes (one context window)
 - Every task includes exact file paths, exact code, and exact commands
 - Every code-producing task follows TDD: test first, fail, implement, pass

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

@@ -32,7 +32,8 @@ If the human has not seen and approved the milestone groupings and feature list,
    - `docs/changes/*/proposal.md`
    - Record each spec's title, status (if detectable from frontmatter or content), and file path.
 3. Scan for plans:
-   - `docs/plans/*.md`
+   - `docs/changes/*/plans/*.md` (preferred — co-located with proposals)
+   - `docs/plans/*.md` (legacy fallback for plans not yet migrated)
    - Record each plan's title, estimated tasks, and file path.
 4. Match plans to specs:
    - Plans often reference their spec in frontmatter (`spec:`) or body text. Link them when a match is found.
@@ -112,7 +113,7 @@ Unmatched plans: N (flag for review)
    - **Spec:** docs/changes/feature-a/proposal.md
    - **Summary:** One-line description of the feature
    - **Blockers:** none
-   - **Plan:** docs/plans/2026-03-20-feature-a-plan.md
+   - **Plan:** docs/changes/feature-a/plans/2026-03-20-feature-a-plan.md
    ```
 
 3. Write to `docs/roadmap.md`.
@@ -436,7 +437,7 @@ Choice?
 
 ## Success Criteria
 
-1. `--create` discovers all specs (`docs/changes/*/proposal.md`) and plans (`docs/plans/*.md`)
+1. `--create` discovers all specs (`docs/changes/*/proposal.md`) and plans (`docs/changes/*/plans/*.md` and legacy `docs/plans/*.md`)
 2. `--create` proposes groupings and waits for human confirmation before writing
 3. `--create` produces a valid `docs/roadmap.md` that round-trips through `parseRoadmap`/`serializeRoadmap`
 4. `--add` collects all fields interactively (milestone, status, spec, summary, blockers, plan)

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

@@ -36,7 +36,7 @@
    - Config files like `playwright.config.*`, `cypress.config.*`, `wdio.conf.*`
    - No production runtime — build output consumed only by other test repos (shared library)
 
-   **If a test suite:** complete Phase 2 (scaffolding) here, then dispatch to `initialize-test-suite-project` for Phase 3 configuration and Phase 4 verification, then return here for Phase 4 step 4+ (knowledge graph, roadmap nudge, final commit). The test-suite skill owns archetype selection, layer variants, tags, reporters, and the custom report.
+   **If a test suite:** complete Phase 2 (scaffolding) here, then dispatch to `initialize-test-suite-project` for Phase 3 configuration and Phase 4 verification, then return here for Phase 4 step 4+ (knowledge graph, roadmap question, final commit). The test-suite skill owns archetype selection, layer variants, tags, reporters, and the custom report.
 
    **If a product/service:** continue with the rest of this skill as written.
 
@@ -83,6 +83,48 @@
    - **No:** Set `i18n.enabled: false` in `harness.config.json`. The `harness-i18n-process` skill will still fire gentle prompts for unconfigured projects when features touch user-facing strings.
    - **Not sure yet:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.
 
+5b. **Configure design system (non-test-suite projects).** Ask: "Will this project have a UI requiring a design system?" Mirror the i18n step's three-way response shape. Use `emit_interaction`:
+
+    ```json
+    emit_interaction({
+      type: "question",
+      question: {
+        text: "Will this project have a UI requiring a design system?",
+        options: [
+          {
+            label: "Yes — capture design intent now",
+            pros: ["Records platforms in harness.config.json", "harness-design-system fires automatically on first design-touching feature"],
+            cons: ["One extra follow-up question (which platforms)"],
+            risk: "low",
+            effort: "low"
+          },
+          {
+            label: "No — this project has no UI",
+            pros: ["No future design nudges", "Permanent decline recorded"],
+            cons: ["Re-running init is required if a UI is added later"],
+            risk: "low",
+            effort: "low"
+          },
+          {
+            label: "Not sure yet",
+            pros: ["Decision deferred without commitment", "Can run harness-design-system later"],
+            cons: ["No design.enabled flag set; on_new_feature will prompt later"],
+            risk: "low",
+            effort: "low"
+          }
+        ],
+        recommendation: { optionIndex: 0, reason: "Most product/service projects benefit from a centralized design system", confidence: "medium" }
+      }
+    })
+    ```
+
+    Based on the answer:
+    - **Yes:** Ask a follow-up: "Which platforms? `web`, `mobile`, or both?" Write `design.enabled: true` and `design.platforms: [...]` (a non-empty array of `web` and/or `mobile`) to `harness.config.json`. Inform the user: "Design tokens will be generated when you start your first design-touching feature — `harness-design-system` fires automatically via `on_new_feature`."
+    - **No:** Write `design.enabled: false` to `harness.config.json`. Do not write `design.platforms`. The `on_new_feature` trigger respects this flag and will not fire `harness-design-system`.
+    - **Not sure yet:** Do not write `design.enabled` or `design.platforms`. The project can enable design later by running `harness-design-system` directly; `on_new_feature` will prompt gently when a feature touches user-facing UI.
+
+    **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.
+
 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
@@ -108,7 +150,38 @@ harness scan [path]
 
 This creates the `.harness/graph/` directory and populates it with the project's dependency and relationship data. Subsequent graph queries (impact analysis, dependency health, test advisor) depend on this initial scan.
 
-4. **Mention roadmap.** After validation passes, inform the user: "When you are ready to set up a project roadmap, run `/harness:roadmap --create`. This creates a unified `docs/roadmap.md` that tracks features, milestones, and status across your specs and plans." This is informational only — do not create the roadmap automatically.
+4. **Set up project roadmap.** Ask: "Set up a project roadmap now? `docs/roadmap.md` tracks features, milestones, and status across your specs and plans." Use `emit_interaction`:
+
+   ```json
+   emit_interaction({
+     type: "question",
+     question: {
+       text: "Set up a project roadmap now?",
+       options: [
+         {
+           label: "Yes — create docs/roadmap.md now",
+           pros: ["Roadmap visible from day one", "Future specs auto-discovered on next sync"],
+           cons: ["Adds one file to the initial commit"],
+           risk: "low",
+           effort: "low"
+         },
+         {
+           label: "No — skip for now",
+           pros: ["Smaller initial footprint"],
+           cons: ["Run `/harness:roadmap --create` later when ready"],
+           risk: "low",
+           effort: "low"
+         }
+       ],
+       recommendation: { optionIndex: 0, reason: "Validation has just passed — a tangible 'project works' signal is the right moment to introduce planning artifacts", confidence: "medium" }
+     }
+   })
+   ```
+
+   Based on the answer:
+   - **Yes:** Invoke `harness-roadmap` (skill) or run `/harness:roadmap --create` to create `docs/roadmap.md`. Verify the file exists. The `manage_roadmap` MCP tool is for managing entries in an existing roadmap, not for creating one.
+     - **If `design.enabled === true` in `harness.config.json`** (set by Phase 3 step 5b), call `manage_roadmap` with `action: add`, `feature: "Set up design system"`, `status: "planned"`, `milestone: "Current Work"`, `summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens. Deferred from project init — fires on first design-touching feature via on_new_feature."`. Skip silently if `manage_roadmap show` reports a duplicate `(feature, milestone)` pair. This closes the loop between deferred design intent and visible planning work.
+   - **No:** Skip silently. The user can still run `/harness:roadmap --create` later — that informational fallback remains valid.
 
 5. **Commit the initialization.** All generated and configured files in a single commit.
 
@@ -120,8 +193,10 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - **`harness validate`** — Verify the full project configuration is valid and complete.
 - **`harness check-deps`** — Verify dependency constraints match the actual codebase (intermediate and above).
 - **`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.
 - **`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.
-- **Roadmap nudge** — After successful initialization, inform the user about `/harness:roadmap --create` for setting up project-level feature tracking. Informational only; does not create the roadmap.
+- **`harness-roadmap` skill** — Phase 4 step 4 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 4 step 4, 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.
 
 ## Success Criteria
 
@@ -134,17 +209,21 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - The adoption level matches what was agreed upon with the human
 - 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 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.
 - For test suites: `initialize-test-suite-project` ran to completion and its Success Criteria are also met
 
 ## 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.                                                                                     |
-| "Validation passed, so the project is ready"                             | Phase 4 includes harness check-deps for intermediate+ projects and knowledge graph initialization. Validation alone is not sufficient.                                                                                    |
-| "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`. |
+| "Validation passed, so the project is ready"                             | Phase 4 includes harness check-deps for intermediate+ projects and knowledge graph initialization. Validation alone is not sufficient.                                                                                                                                          |
+| "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
 
@@ -188,6 +267,67 @@ git add harness.config.json .harness/ AGENTS.md
 git commit -m "feat: initialize harness project at basic level"
 ```
 
+### Example: New TypeScript Web App with Design and Roadmap
+
+**ASSESS:**
+
+```
+Human: "I'm starting a new Next.js web app. Single-language, but it definitely needs a design system."
+Check for .harness/ — not found. Recommend: basic level.
+Phase 1 step 5 classification: not a test suite (Next.js app with src/, no playwright/cypress).
+```
+
+**SCAFFOLD:**
+
+```bash
+harness init --level basic --framework nextjs
+```
+
+**CONFIGURE (Phase 3):**
+
+```
+Step 5 (i18n): "Will this project support multiple languages?"
+  Human: "No, English only."
+  Result: i18n.enabled = false in harness.config.json.
+
+Step 5b (design): "Will this project have a UI requiring a design system?"
+  Human: "Yes."
+  Follow-up: "Which platforms? web, mobile, or both?"
+  Human: "Web."
+  Result: design.enabled = true, design.platforms = ["web"] in harness.config.json.
+  Inform: "Design tokens will be generated when you start your first design-touching
+  feature — harness-design-system fires automatically via on_new_feature."
+
+Step 6 (test-suite dispatch): skipped (not a test suite).
+```
+
+**VALIDATE (Phase 4):**
+
+```
+Step 1: harness validate — pass.
+Step 3: harness check-deps — pass (basic level, no constraints yet).
+Build initial knowledge graph: harness scan — graph populated.
+
+Step 4 (roadmap): "Set up a project roadmap now?"
+  Human: "Yes."
+  Invoke harness-roadmap (or /harness:roadmap --create) — docs/roadmap.md created.
+  design.enabled === true detected → manage_roadmap action: add
+    feature: "Set up design system"
+    status: planned
+    milestone: Current Work
+    summary: "Run harness-design-system to define palette, typography, and generate W3C DTCG tokens..."
+  Result: docs/roadmap.md contains the planned design item.
+
+Step 5: commit.
+```
+
+```bash
+git add harness.config.json .harness/ AGENTS.md docs/roadmap.md
+git commit -m "feat: initialize harness project with design and roadmap"
+```
+
+**Final state:** `harness.config.json` has `design.enabled: true` + `design.platforms: ["web"]`; `docs/roadmap.md` lists "Set up design system" as a `planned` item under `Current Work`; on the first feature touching UI, `on_new_feature` fires `harness-design-system` which reads `design.enabled` and runs the full discover/define/generate/validate flow.
+
 ### Example: Migrating Existing Project from Basic to Intermediate
 
 **ASSESS:**

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

@@ -1,6 +1,6 @@
 name: initialize-harness-project
 version: "1.0.0"
-description: Scaffold a new harness-compliant project
+description: Scaffold a new harness-compliant project, including design system and roadmap configuration
 stability: static
 cognitive_mode: constructive-architect
 triggers:
@@ -34,3 +34,4 @@ state:
   files: []
 depends_on:
   - initialize-test-suite-project
+  - harness-design-system

package/dist/agents/skills/codex/harness-architecture-advisor/SKILL.md

@@ -23,6 +23,18 @@ If you find yourself writing implementation code, STOP. You have left advisory m
 
 ## Process
 
+### Storage Location
+
+Architecture artifacts (discovery, analysis, proposals, ADRs) are human-facing documentation and live under the project's docs directory — NOT under `.harness/` (which is reserved for tool state like debug sessions, graph data, and baselines).
+
+Resolve the storage root as follows:
+
+1. Read `docsDir` from `harness.config.json` at the project root. If present, use `<docsDir>/architecture/` (e.g. `docsDir: "./docs"` → `docs/architecture/`).
+2. If `harness.config.json` is absent or has no `docsDir`, default to `docs/architecture/`.
+3. If a legacy `.harness/architecture/` directory exists from a prior version of this skill, surface this to the human and offer to migrate it via `git mv .harness/architecture <docsDir>/architecture` before proceeding.
+
+All path references below use `<docs>/architecture/` as shorthand for the resolved location.
+
 ### Phase 1: DISCOVER — Understand the Problem Space
 
 **Gate: This phase requires human answers. Do not proceed to Phase 2 until the human has responded.**
@@ -42,7 +54,7 @@ Ask these 5 questions. Wait for answers before proceeding.
 Record the answers verbatim. Do not paraphrase or interpret at this stage.
 
 ```
-Store answers in: .harness/architecture/<topic>/discovery.md
+Store answers in: <docs>/architecture/<topic>/discovery.md
 ```
 
 ---
@@ -107,7 +119,7 @@ Look for existing issues that may affect the decision:
 ```
 
 ```
-Store analysis in: .harness/architecture/<topic>/analysis.md
+Store analysis in: <docs>/architecture/<topic>/analysis.md
 ```
 
 ### Graph-Enhanced Context (when available)
@@ -185,7 +197,7 @@ However, if <condition>, Option <Y> would be stronger.
 Present the options to the human and wait for their choice.
 
 ```
-Store proposal in: .harness/architecture/<topic>/proposal.md
+Store proposal in: <docs>/architecture/<topic>/proposal.md
 ```
 
 ---
@@ -251,7 +263,7 @@ discussion.>
 Save the ADR:
 
 ```
-.harness/architecture/<topic>/ADR-<number>.md
+<docs>/architecture/<topic>/ADR-<number>.md
 ```
 
 Also link from the project's ADR index if one exists.
@@ -261,7 +273,7 @@ Also link from the project's ADR index if one exists.
 - Extends the human-architect model — the skill is a thinking partner, not a decision maker
 - Respects architectural constraints defined in harness.config.json
 - Outputs structured ADR that other skills can reference
-- Reads prior ADRs from `.harness/architecture/` for consistency
+- Reads prior ADRs from `<docs>/architecture/` (resolved from `harness.config.json` `docsDir`, default `docs/architecture/`) for consistency
 
 ## Success Criteria
 

package/dist/agents/skills/codex/harness-architecture-advisor/skill.yaml

@@ -48,5 +48,5 @@ phases:
 state:
   persistent: true
   files:
-    - .harness/architecture/
+    - docs/architecture/
 depends_on: []

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

@@ -80,12 +80,12 @@ INIT → ASSESS → PLAN → APPROVE_PLAN → EXECUTE → VERIFY → INTEGRATE
 
 ```
 subagent_type: "harness-planner"
-prompt: "Phase {N}: {name}. Spec: {specPath}. Session: {sessionSlug}. Rigor: {rigorLevel}. Follow harness-planning. Write plan to docs/plans/. Write {sessionDir}/handoff.json when done."
+prompt: "Phase {N}: {name}. Spec: {specPath}. Session: {sessionSlug}. Rigor: {rigorLevel}. Follow harness-planning. Write plan to docs/changes/<topic>/plans/ (topic from specPath; legacy docs/plans/ if spec is outside docs/changes/). Write {sessionDir}/handoff.json when done."
 ```
 
 On return: read `planPath` from `{sessionDir}/handoff.json`. Complexity override check: `low` + tasks>10 or checkpoints>3 → `"medium"`; tasks>20 or checkpoints>6 → `"high"`. Update state `planPath`. → APPROVE_PLAN.
 
-**Interactive plan (high):** Check for plan file at `docs/plans/*{phase-name}*` or `planPath` in handoff. If found: update `planPath` → APPROVE_PLAN. If not: remind and wait.
+**Interactive plan (high):** Check for plan file at `docs/changes/<topic>/plans/*{phase-name}*` (or legacy `docs/plans/*{phase-name}*`) or `planPath` in handoff. If found: update `planPath` → APPROVE_PLAN. If not: remind and wait.
 
 ---
 
@@ -275,7 +275,7 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 
 **INIT:** 3 phases found: Phase 1: Core Scanner (low), Phase 2: Rule Engine (high), Phase 3: CLI Integration (low).
 
-**Phase 1 — ASSESS → PLAN:** harness-planner dispatched. Returns plan: `docs/plans/2026-03-19-core-scanner-plan.md` (8 tasks).
+**Phase 1 — ASSESS → PLAN:** harness-planner dispatched. Returns plan: `docs/changes/security-scanner/plans/2026-03-19-core-scanner-plan.md` (8 tasks).
 
 **Phase 1 — APPROVE_PLAN (auto):** All signals false. "Auto-approved Phase 1: Core Scanner | auto | low | no concerns | 8 tasks."
 
@@ -287,7 +287,7 @@ Persist findings to `{sessionDir}/phase-{N}-review.json`. No blocking → PHASE_
 
 **Phase 2 — ASSESS:** High complexity. "Run `/harness:planning` interactively, then re-invoke." [User plans interactively. Re-invokes.]
 
-**INIT (resume):** "Resuming from PLAN, phase 2: Rule Engine. Found plan: docs/plans/2026-03-19-rule-engine-plan.md"
+**INIT (resume):** "Resuming from PLAN, phase 2: Rule Engine. Found plan: docs/changes/security-scanner/plans/2026-03-19-rule-engine-plan.md"
 
 **Phase 2 — APPROVE_PLAN (paused):** Complexity: high triggered. "Approve? → yes" **EXECUTE → VERIFY → REVIEW → PHASE_COMPLETE.** 14 tasks, 1 retry.
 

package/dist/agents/skills/codex/harness-code-review/SKILL.md

@@ -242,7 +242,7 @@ git diff --stat HEAD~1                    # measure diff size
 git diff HEAD~1 -- <file>                 # per-file diff
 grep -n "import\|require\|from " <file>   # find imports
 find . -name "*<module>*test*" -o -name "*<module>*spec*"
-grep -rl "<component>" docs/changes/ docs/design-docs/ docs/plans/
+grep -rl "<component>" docs/changes/ docs/design-docs/ docs/plans/   # docs/changes/*/plans/ covered by docs/changes/; docs/plans/ kept for legacy
 grep -rn "interface\|type\|schema" <changed-file> | head -20
 ```
 

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

@@ -25,7 +25,12 @@
    - CSS files with custom properties (`--color-*`, `--font-*`, `--space-*`)
    - `theme.ts`, `theme.js`, `styles/variables.*` -- CSS-in-JS or preprocessor variables
 
-2. **Check harness configuration.** Read `harness.config.json` for:
+2. **Check harness configuration.** Read `harness.config.json` and apply the `design.enabled` short-circuit _before_ doing anything else in Phase 1:
+   - If `design.enabled` is `false`: the project explicitly declined a design system during init. Log `"design.enabled is false in harness.config.json — project explicitly declined the design system. Skipping."` and stop. Do not run the rest of Phase 1 or any subsequent phase.
+   - If `design.enabled` is `true`: proceed normally with the rest of Phase 1.
+   - If `design.enabled` is absent (the field does not appear under `design`): the project has not decided yet. Surface a gentle prompt: "This project has not configured a design system. Would you like to enable one now? (yes / no / not sure)". On `yes`, proceed with Phase 1 — note that this answer is not persisted to `harness.config.json` (the init skill is the canonical writer of that field), so this prompt will fire again on the next `on_new_feature` invocation; run `harness init --migrate` to make the choice permanent. On `no` or `not sure`, stop without writing anything to `harness.config.json`.
+
+   After the gate, read the remaining design configuration fields:
    - `design.strictness` -- enforcement level (`strict`, `standard`, `permissive`)
    - `design.platforms` -- which platforms are enabled (web, mobile)
    - `design.tokenPath` -- path to tokens file (default: `design-system/tokens.json`)