@harness-engineering/cli 1.6.1 → 1.7.0

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

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

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

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

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

@@ -4,7 +4,7 @@ description: Analyze structural health of the codebase using graph metrics
 cognitive_mode: analytical-reporter
 triggers:
   - manual
-  - scheduled
+  - on_milestone
 platforms:
   - claude-code
   - gemini-cli

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

@@ -0,0 +1,265 @@
+# Harness Design
+
+> Aesthetic direction workflow. Capture design intent, generate DESIGN.md with anti-patterns and platform notes, review components against aesthetic guidelines, and enforce design constraints at configurable strictness levels.
+
+## When to Use
+
+- Establishing aesthetic direction for a new or existing project (style, tone, differentiator)
+- When `on_new_feature` triggers fire and the feature has design scope requiring aesthetic guidance
+- Reviewing existing components against declared design intent and anti-patterns
+- Enforcing design constraints via the knowledge graph with configurable strictness
+- Generating or updating `design-system/DESIGN.md` with aesthetic direction, anti-patterns, and platform notes
+- NOT for design token generation or palette selection (use harness-design-system)
+- NOT for accessibility auditing or WCAG compliance (use harness-accessibility)
+- NOT for platform-specific token implementation into CSS/Tailwind/etc. (use harness-design-web/mobile, Phase 5)
+
+## Process
+
+### Phase 1: INTENT -- Capture Aesthetic Intent
+
+1. **Read existing design artifacts.** Search for:
+   - `design-system/DESIGN.md` -- existing aesthetic direction documentation (from harness-design-system output)
+   - `design-system/tokens.json` -- existing W3C DTCG tokens (palette, typography, spacing defined by harness-design-system)
+   - `harness.config.json` -- project configuration for design settings
+
+2. **Check harness configuration.** Read `harness.config.json` for:
+   - `design.strictness` -- enforcement level (`strict`, `standard`, `permissive`). If not set, default to `standard`.
+   - `design.platforms` -- which platforms are enabled (web, mobile)
+   - `design.aestheticIntent` -- path to design intent doc (default: `design-system/DESIGN.md`)
+
+3. **Load industry profile.** If an industry is specified (via CLI `--industry` arg or config), read the industry profile from `agents/skills/shared/design-knowledge/industries/{industry}.yaml`. Available industries include: `saas`, `fintech`, `healthcare`, `ecommerce`, `creative`, `emerging-tech`, `lifestyle`, `services`. The profile provides sector-specific guidance on:
+   - Recommended visual style and tone
+   - Industry conventions and user expectations
+   - Regulatory or cultural considerations
+   - Common anti-patterns for the sector
+
+4. **Capture user intent.** Ask the user to define:
+   - **Style:** minimal, expressive, corporate, playful, editorial, or custom
+   - **Tone:** warm, cool, neutral, bold, muted, or custom
+   - **Key differentiator:** what makes this product's visual identity unique
+   - **Anti-patterns:** specific design choices to explicitly avoid (e.g., "no gradients on data elements," "no decorative borders on cards")
+
+5. **Load shared design knowledge.** Read anti-pattern awareness from `agents/skills/shared/design-knowledge/`:
+   - `palettes/curated.yaml` -- curated palettes to understand which aesthetic families are available
+   - `typography/pairings.yaml` -- typography pairings to understand which font combinations are recommended
+   - Industry-specific anti-pattern guidance from the loaded industry profile
+
+6. **Confirm intent before proceeding.** Present a summary of the captured aesthetic intent to the user. This is a hard gate -- no DESIGN.md generation without the user confirming their aesthetic intent.
+
+### Phase 2: DIRECTION -- Generate DESIGN.md
+
+1. **Generate or update `design-system/DESIGN.md`.** The document must contain the following sections:
+
+   **Aesthetic Direction:**
+   - Style declaration (the chosen style and what it means for this project)
+   - Tone description (how the tone manifests in color usage, typography weight, spacing density)
+   - Key differentiator (the unique visual identity aspect and how it is expressed)
+
+   **Anti-Patterns:**
+   - Project-specific anti-patterns (from user input in Phase 1)
+   - Industry-informed anti-patterns (from the loaded industry profile)
+   - Each anti-pattern includes: name, description, example of what NOT to do, and why it conflicts with the declared intent
+
+   **Platform Notes:**
+   - Web-specific guidance (CSS strategy, responsive behavior, animation preferences)
+   - Mobile-specific guidance (touch targets, native component usage, platform conventions)
+   - Cross-platform consistency rules (which elements must be identical vs. platform-adapted)
+
+   **Strictness Override:**
+   - Current `designStrictness` level and what it means
+   - Instructions for changing strictness in `harness.config.json`
+   - Behavior differences per level:
+     - `permissive` -- all design violations reported as `info` (nothing blocks)
+     - `standard` -- anti-pattern and accessibility violations are `warn`, critical violations are `error` (default)
+     - `strict` -- accessibility violations are `error` (blocks CI/PR merge), anti-pattern violations are `warn`
+
+2. **Populate the knowledge graph.** If a graph exists at `.harness/graph/`:
+   - Create an `AestheticIntent` node with properties: style, tone, differentiator, strictness level. Use `DesignIngestor` from `packages/graph/src/ingest/DesignIngestor.ts` for graph ingestion.
+   - Create a `DECLARES_INTENT` edge from the project node to the `AestheticIntent` node.
+   - This enables downstream skills (harness-accessibility, harness-impact-analysis) to query the declared design intent.
+
+3. **Run harness validate.** After generating DESIGN.md, verify the project still passes all constraints. The new file must not break existing validations.
+
+### Phase 3: REVIEW -- Review Components Against Design Intent
+
+1. **Scan for anti-pattern violations.** Use Grep to search the codebase for patterns that match declared anti-patterns:
+   - Hardcoded color values not present in `design-system/tokens.json` (suggests off-brand color usage)
+   - Font families flagged as anti-patterns in the design intent (e.g., decorative fonts in a minimal project)
+   - Layout patterns on the forbidden list (e.g., excessive drop shadows in a flat design, gradients on data elements)
+   - CSS properties or values that contradict the declared style (e.g., rounded corners in a sharp-edge design)
+
+2. **Load detection rules from shared design knowledge.** Read from `agents/skills/shared/design-knowledge/`:
+   - `anti-patterns/typography.yaml` — font combinations, size, weight, and line-height issues that clash with the declared style
+   - `anti-patterns/color.yaml` — hardcoded colors, insufficient contrast, color-only indicators that undermine the declared tone
+   - `anti-patterns/layout.yaml` — spacing inconsistencies, missing touch targets, fixed-width containers
+   - `anti-patterns/motion.yaml` — missing prefers-reduced-motion, long animations, scroll-jacking
+   - `industries/{industry}.yaml` — industry-specific rules from the loaded industry profile
+
+3. **Cross-reference with graph constraints.** If a graph exists at `.harness/graph/`:
+   - Query for existing `VIOLATES_DESIGN` edges using `DesignConstraintAdapter` from `packages/graph/src/constraints/DesignConstraintAdapter.ts`
+   - Compare current findings against previously recorded violations
+   - Identify new violations and resolved violations
+
+4. **Assign severity based on `designStrictness`:**
+   - `permissive` -- all findings are `info` severity
+   - `standard` -- anti-pattern violations and accessibility-related findings are `warn`, critical design constraint violations are `error`
+   - `strict` -- accessibility violations are `error` (blocks), anti-pattern violations are `warn`
+
+5. **Report findings.** Present each finding with:
+   - File path and line number
+   - Violation description and which anti-pattern or design constraint it violates
+   - Severity level (based on current strictness)
+   - Suggested remediation
+
+### Phase 4: ENFORCE -- Surface and Record Violations
+
+1. **Create constraint nodes in the graph.** For each violated design rule, if a graph exists at `.harness/graph/`:
+   - Create a `DesignConstraint` node for the rule being violated (if one does not already exist)
+   - Create a `VIOLATES_DESIGN` edge from the violating component to the `DesignConstraint` node
+   - Use `DesignConstraintAdapter` from `packages/graph/src/constraints/DesignConstraintAdapter.ts` to manage constraint creation and violation recording
+
+2. **Format violation output.** Each violation follows a numbered format:
+
+   ```
+   DESIGN-001 [warn] Anti-pattern: gradient used on data visualization element
+     File:       src/components/Chart.tsx
+     Line:       42
+     Constraint: No gradients on data elements
+     Intent:     Style "minimal" prohibits decorative effects on informational components
+     Fix:        Replace linear-gradient with solid color from token "neutral.100"
+
+   DESIGN-002 [error] Off-brand color: hardcoded #ff6b35 not in token set
+     File:       src/components/Alert.tsx
+     Line:       18
+     Constraint: All colors must reference design tokens
+     Intent:     Tone "cool" conflicts with warm orange accent
+     Fix:        Use token "semantic.warning" (#f59e0b) or add color to tokens.json via harness-design-system
+
+   DESIGN-003 [info] Typography: decorative font "Playfair Display" used in component
+     File:       src/components/Hero.tsx
+     Line:       8
+     Constraint: Heading font must match declared typography pairing
+     Intent:     Style "minimal" uses Inter for all headings
+     Fix:        Replace with token "typography.heading.fontFamily"
+   ```
+
+3. **Control severity by `designStrictness`:**
+   - `permissive` -- all violations output as `info` (DESIGN-001 [info], DESIGN-002 [info], etc.)
+   - `standard` -- anti-patterns and a11y = `warn`, off-brand tokens = `error` (default)
+   - `strict` -- a11y violations = `error` (blocks CI), anti-patterns = `warn`, off-brand tokens = `error`
+
+4. **Run harness validate.** After recording violations in the graph, run validation to ensure the enforcement pass is consistent with the project state.
+
+## Harness Integration
+
+- **`harness validate`** -- Run after generating DESIGN.md and after enforcement passes. Design violations surface as constraint violations at the configured strictness level.
+- **`harness scan`** -- Run after changes to refresh the knowledge graph. Updated graph enables accurate violation detection and impact analysis.
+- **`DesignIngestor`** (`packages/graph/src/ingest/DesignIngestor.ts`) -- Parses `tokens.json` and `DESIGN.md` to create graph nodes representing the design system. Creates `AestheticIntent` nodes and `DECLARES_INTENT` edges during the DIRECTION phase.
+- **`DesignConstraintAdapter`** (`packages/graph/src/constraints/DesignConstraintAdapter.ts`) -- Manages `DesignConstraint` nodes and `VIOLATES_DESIGN` edges in the graph. Reads `design.strictness` to control violation severity. Used during REVIEW and ENFORCE phases.
+
+**Graph naming convention:** This skill uses PascalCase for node types (`AestheticIntent`, `DesignToken`, `DesignConstraint`) and UPPER_SNAKE for edge types (`DECLARES_INTENT`, `VIOLATES_DESIGN`, `USES_TOKEN`, `PLATFORM_BINDING`) as conceptual labels. The graph schema registers these as snake_case identifiers (`aesthetic_intent`, `design_token`, `design_constraint`, `declares_intent`, `violates_design`, `uses_token`, `platform_binding`). The adapter classes (`DesignIngestor`, `DesignConstraintAdapter`) handle the mapping — always use the adapters rather than constructing graph queries with raw type names.
+
+- **`harness-design-system`** -- Dependency. This skill reads tokens and design intent generated by harness-design-system. Token-level issues (palette changes, new colors) are resolved by running harness-design-system, not this skill.
+- **`harness-impact-analysis`** -- When design tokens change, impact analysis traces which components consume affected tokens. Use this to determine which components need re-review after token updates.
+
+## Success Criteria
+
+- `design-system/DESIGN.md` exists with all required sections: Aesthetic Direction, Anti-Patterns, Platform Notes, Strictness Override
+- Anti-patterns are detected in the codebase and reported with file paths, line numbers, and severity
+- `designStrictness` configuration is read from `harness.config.json` and respected in all severity assignments
+- `AestheticIntent` node created in the knowledge graph with style, tone, differentiator, and strictness properties
+- `DECLARES_INTENT` edge connects the project to the aesthetic intent node
+- `DesignConstraint` nodes created for each violated design rule
+- `VIOLATES_DESIGN` edges connect violating components to their constraint nodes
+- Violations output in numbered format (DESIGN-001, DESIGN-002, etc.) with severity matching strictness level
+- `harness validate` passes after DESIGN.md generation and enforcement
+- User confirmed aesthetic intent before DESIGN.md generation (hard gate)
+
+## Examples
+
+### Example: SaaS Analytics Dashboard Aesthetic Direction
+
+**Context:** A SaaS analytics dashboard project. Industry: `saas`. Design tokens already generated by harness-design-system. No existing DESIGN.md aesthetic direction.
+
+**INTENT capture:**
+
+```
+Industry profile:     Loaded (saas) -- recommends professional, data-focused aesthetic
+Style:                Minimal
+Tone:                 Cool, professional
+Differentiator:       Dense information display with generous whitespace between sections
+Anti-patterns:        No gradients on data elements, no decorative borders on cards,
+                      no more than 2 font weights per component
+Strictness:           standard (from harness.config.json)
+```
+
+**DIRECTION output (DESIGN.md excerpt):**
+
+```markdown
+## Aesthetic Direction
+
+**Style:** Minimal -- clean lines, flat surfaces, no decorative elements that do not serve
+an informational purpose. Every visual element must earn its place by conveying data or
+guiding the user's eye.
+
+**Tone:** Cool, professional -- slate and blue palette dominates. Warm colors reserved
+exclusively for semantic states (warning, error). No warm accents in neutral UI.
+
+**Differentiator:** Dense information display with generous whitespace between sections.
+Components are compact internally but breathe externally. Card padding is tight (12px),
+but gaps between cards are generous (24px+).
+
+## Anti-Patterns
+
+| Pattern                    | Description                                  | Why It Conflicts                           |
+| -------------------------- | -------------------------------------------- | ------------------------------------------ |
+| Gradients on data elements | linear-gradient on charts, tables, cards     | Minimal style: flat surfaces only          |
+| Decorative card borders    | border with color on .card elements          | Minimal style: borders are structural only |
+| Excess font weights        | More than 2 font-weight values per component | Minimal style: typographic restraint       |
+
+## Strictness Override
+
+Current level: **standard**
+
+To change, update `harness.config.json`:
+"design": { "strictness": "strict" | "standard" | "permissive" }
+```
+
+**REVIEW findings:**
+
+```
+Found 3 anti-pattern violations in 2 files:
+
+DESIGN-001 [warn] Gradient on data element
+  File:       src/components/RevenueChart.tsx:42
+  Constraint: No gradients on data elements
+  Fix:        Replace linear-gradient(#3b82f6, #1d4ed8) with solid token "primary.500"
+
+DESIGN-002 [warn] Decorative border on card
+  File:       src/components/MetricCard.tsx:15
+  Constraint: No decorative borders on cards
+  Fix:        Remove border-color: #3b82f6, use border-color: transparent or remove border
+
+DESIGN-003 [info] Three font weights in one component
+  File:       src/components/MetricCard.tsx:8
+  Constraint: Max 2 font weights per component
+  Fix:        Consolidate font-weight values to 400 (body) and 600 (heading) only
+```
+
+## Gates
+
+These are hard stops. Violating any gate means the process has broken down.
+
+- **No DESIGN.md generated without the user confirming aesthetic intent.** The INTENT phase must end with explicit user confirmation of style, tone, differentiator, and anti-patterns. Do not generate based on assumptions.
+- **No enforcement without reading tokens from harness-design-system.** The REVIEW and ENFORCE phases require `design-system/tokens.json` to exist. If tokens have not been generated, instruct the user to run harness-design-system first.
+- **Strictness must be read from configuration, not assumed.** Read `design.strictness` from `harness.config.json`. If the key does not exist, default to `standard` and report the default to the user. Never hardcode a strictness level.
+- **No anti-pattern detection without a declared intent.** The REVIEW phase requires an existing DESIGN.md with declared anti-patterns. If no intent has been captured, run the INTENT and DIRECTION phases first.
+- **No graph mutations without validating node types.** When creating `AestheticIntent`, `DesignConstraint`, or `VIOLATES_DESIGN` edges, verify the node and edge types are registered in the graph schema before writing.
+
+## Escalation
+
+- **When the user cannot articulate a style or tone:** Suggest industry-based defaults from the loaded industry profile. Present 2-3 options with examples: "Based on the saas industry profile, common styles are: (1) Minimal -- clean, data-focused, (2) Corporate -- structured, trustworthy, (3) Expressive -- colorful, engaging. Which resonates most?"
+- **When declared anti-patterns conflict with existing code:** Present a migration path rather than flagging every instance as a violation. Report: "Found 47 instances of gradients on data elements. Recommend a phased migration: (1) Update new components immediately, (2) Schedule legacy component updates over 3 sprints. Set strictness to 'permissive' during migration to avoid blocking CI."
+- **When tokens do not exist yet:** Do not attempt to infer a token set. Instruct the user: "Design tokens have not been generated. Run harness-design-system first to create `design-system/tokens.json`, then re-run harness-design for aesthetic direction."
+- **When strictness level conflicts with team velocity:** Explain the tradeoffs: "Strict mode blocks PRs on any design violation. If this is slowing the team, consider 'standard' mode which blocks only on critical violations (off-brand colors, accessibility) and warns on anti-patterns."
+- **When the knowledge graph is unavailable:** Skip graph operations in DIRECTION and ENFORCE phases. Log: "Graph not available at `.harness/graph/` -- skipping AestheticIntent node creation and violation recording. Run `harness scan` later to populate." Continue with file-based operations.