@harness-engineering/cli 1.26.0 → 1.27.0

package/dist/agents/skills/cursor/harness-perf/SKILL.md

@@ -22,26 +22,28 @@ Tier 1 violations are non-negotiable blockers. If a Tier 1 violation is detected
 
 ### Phase 1: ANALYZE — Structural and Coupling Checks
 
-1. **Run structural checks.** Execute `harness check-perf --structural` to compute complexity metrics for all changed files:
+1. **Assess current performance posture.** Run `check_performance` to evaluate current performance metrics against defined budgets. Run `get_critical_paths` to identify performance-critical functions and hot paths.
+
+2. **Run structural checks.** Execute `harness check-perf --structural` to compute complexity metrics for all changed files:
    - Cyclomatic complexity per function
    - Nesting depth per function
    - File length (lines of code)
    - Parameter count per function
 
-2. **Run coupling checks.** Execute `harness check-perf --coupling` to compute coupling metrics:
+3. **Run coupling checks.** Execute `harness check-perf --coupling` to compute coupling metrics:
    - Fan-in and fan-out per module
    - Afferent and efferent coupling
    - Transitive dependency depth
    - Circular dependency detection
 
-3. **Classify violations by tier:**
+4. **Classify violations by tier:**
    - **Tier 1 (error, block commit):** Cyclomatic complexity > 15, circular dependencies, hotspot in top 5%
    - **Tier 2 (warning, block merge):** Complexity > 10, nesting > 4, fan-out > 10, size budget exceeded
    - **Tier 3 (info, no gate):** File length > 300, fan-in > 20, transitive depth > 30
 
-4. **If Tier 1 violations found,** report them immediately and STOP. Do not proceed to benchmarks. The violations must be fixed first.
+5. **If Tier 1 violations found,** report them immediately and STOP. Do not proceed to benchmarks. The violations must be fixed first.
 
-5. **If no violations found,** proceed to Phase 2.
+6. **If no violations found,** proceed to Phase 2.
 
 ---
 
@@ -83,7 +85,7 @@ This phase runs only when `.bench.ts` files exist in the project. If none are fo
 
 4. **Run benchmarks.** Execute `harness perf bench` to run all benchmark suites.
 
-5. **Load baselines.** Read `.harness/perf/baselines.json` for previous benchmark results. If no baselines exist, treat this as a baseline-capture run.
+5. **Load baselines.** Load existing baselines via `get_perf_baselines` before running new benchmarks. Read `.harness/perf/baselines.json` for previous benchmark results. If no baselines exist, treat this as a baseline-capture run.
 
 6. **Compare results against baselines** using the `RegressionDetector`:
    - Calculate percentage change for each benchmark
@@ -100,7 +102,7 @@ This phase runs only when `.bench.ts` files exist in the project. If none are fo
    - **Tier 2:** >10% regression on a non-critical-path benchmark
    - **Tier 3:** >5% regression on a non-critical-path benchmark (within noise margin consideration)
 
-9. **If this is a baseline-capture run,** report results without regression comparison. Recommend running `harness perf baselines update` to persist.
+9. **If this is a baseline-capture run,** report results without regression comparison. Recommend running `harness perf baselines update` to persist. After benchmarks pass, update baselines via `update_perf_baselines` to record new performance targets.
 
 ---
 

package/dist/agents/skills/cursor/harness-planning/SKILL.md

@@ -29,6 +29,7 @@ The `rigorLevel` is passed by autopilot (or set via `--fast`/`--thorough` flags)
 | Phase     | `fast`                                             | `standard` (default)                       | `thorough`                                          |
 | --------- | -------------------------------------------------- | ------------------------------------------ | --------------------------------------------------- |
 | SCOPE     | No change.                                         | No change.                                 | No change.                                          |
+| KNOWLEDGE | Skip entirely.                                     | Run detect; fix if gaps found.             | Run detect; fix if gaps found.                      |
 | DECOMPOSE | Skip skeleton. Full tasks directly after file map. | Skeleton if tasks >= 8; full tasks if < 8. | Always skeleton. Require approval before expanding. |
 | SEQUENCE  | No change.                                         | No change.                                 | No change.                                          |
 | VALIDATE  | No change.                                         | No change.                                 | No change.                                          |
@@ -41,7 +42,7 @@ The skeleton pass is the primary rigor lever. Fast mode goes straight to full de
 
 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 handoff writes go to `{sessionDir}/handoff.json`.
+1. **Session slug:** If `session-slug` argument provided, set `{sessionDir} = .harness/sessions/<session-slug>/`. Pass to `gather_context({ session: "<session-slug>", include: ["state", "learnings", "handoff", "graph", "businessKnowledge", "sessions", "validation"] })`. All handoff writes go to `{sessionDir}/handoff.json`.
 2. **Spec path:** If `spec-path` argument provided, read spec from that path. Otherwise, discover from `{sessionDir}/handoff.json` (read upstream brainstorming output) or prompt the user.
 3. **Rigor level:** If `fast`/`thorough` argument provided, use it. Otherwise default to `standard`.
 
@@ -54,14 +55,31 @@ When no arguments are provided (standalone invocation), discover spec from conte
 Work backward from the goal. Start with "what must be true when we are done?"
 
 1. **State the goal.** One sentence. What does the system do when this plan is complete?
-2. **Derive observable truths.** What can be observed (running a command, opening a browser, reading a file) that proves the goal is met? Be specific:
+
+1b. **Load skill recommendations.** After loading the spec, check for skill recommendations:
+
+- If `docs/changes/<feature>/SKILLS.md` exists alongside the spec: parse the Apply and Reference tiers. These inform task annotation in Phase 2.
+- If SKILLS.md is missing but a spec exists: run the advisor inline using `advise_skills` MCP tool to generate SKILLS.md.
+- If neither SKILLS.md nor a spec exists: emit a one-line note:
+
+  ```
+  Note: No skill recommendations found. Run the advisor to discover
+  relevant design, framework, and knowledge skills:
+    harness advise-skills --spec-path <path>
+  ```
+
+Store the parsed skill list for use in Phase 2 task annotation.
+
+2. **Review prior decisions.** Check `decisions` from the prior brainstorming session (loaded via `sessions` in gather_context). Do not re-decide what was already decided — build on those choices.
+
+3. **Derive observable truths.** What can be observed (running a command, opening a browser, reading a file) that proves the goal is met? Be specific:
    - BAD: "The API handles errors"
    - GOOD: "GET /api/users/nonexistent returns 404 with `{ error: 'User not found' }` body"
-3. **Derive required artifacts.** For each truth, what files must exist? What functions? What tests pass? List exact file paths.
-4. **Identify key links.** How do artifacts connect? What imports what? What calls what?
-5. **Apply YAGNI.** For every artifact: "Is this required for an observable truth?" If not, cut it.
+4. **Derive required artifacts.** For each truth, what files must exist? What functions? What tests pass? List exact file paths.
+5. **Identify key links.** How do artifacts connect? What imports what? What calls what?
+6. **Apply YAGNI.** For every artifact: "Is this required for an observable truth?" If not, cut it.
 
-6. **Surface uncertainties.** Before proceeding to Phase 2, explicitly list what you do NOT know. For each uncertainty, classify it:
+7. **Surface uncertainties.** Before proceeding to Phase 2, explicitly list what you do NOT know. For each uncertainty, classify it:
    - **Blocking:** Cannot decompose tasks without resolving this. Escalate to user.
    - **Assumption:** Can proceed with a stated assumption. Document it. If wrong, specific tasks will need revision.
    - **Deferrable:** Does not affect task decomposition. Note for execution phase.
@@ -75,7 +93,7 @@ Work backward from the goal. Start with "what must be true when we are done?"
    - [DEFERRABLE] Exact error message wording. (Can be finalized during implementation.)
    ```
 
-   **Read-only constraint:** Steps 1-5 above are research and analysis. Do not propose task structure, file organization, or implementation approaches during SCOPE. Record what must be true (observable truths) and what you do not know (uncertainties). Solutions belong in DECOMPOSE.
+   **Read-only constraint:** Steps 1-6 above are research and analysis. Do not propose task structure, file organization, or implementation approaches during SCOPE. Record what must be true (observable truths) and what you do not know (uncertainties). Solutions belong in DECOMPOSE.
 
    When scope is ambiguous, use `emit_interaction`:
 
@@ -145,9 +163,39 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 - `query_graph` — discover module dependencies for realistic task decomposition
 - `get_impact` — estimate which modules a feature touches
+- `compute_blast_radius` — simulate failure propagation from target files to understand scope
+- `predict_failures` — forecast which architectural constraints are at risk from planned changes, informing where extra test coverage or smaller tasks are needed
+- `detect_anomalies` — identify structural irregularities in the affected area before planning tasks around them
 
 Fall back to file-based commands if no graph is available.
 
+### Intelligence Signals (when orchestrator is available)
+
+If the orchestrator is running, request intelligence analysis via `POST /api/analyze` with the feature title/description before decomposing. The pipeline returns:
+
+- **SEL** (Spec Enrichment) — affected systems and blast radius derived from the graph
+- **CML** (Complexity Modeling) — structural, semantic, and historical complexity scores. Use `structuralComplexity > 0.7` to flag areas needing smaller, more cautious tasks.
+- **PESL** (Pre-Execution Simulation) — simulated risk score. Use `riskScore > 0.6` to add extra checkpoints or split risky tasks further.
+
+If no orchestrator, `predict_failures` and `compute_blast_radius` MCP tools provide equivalent directional signals.
+
+---
+
+### Phase 1.5: KNOWLEDGE BASELINE — Materialize Domain Knowledge
+
+Before decomposing into tasks, ensure domain knowledge from PRDs and specs is documented. **Skip this phase** when no PRDs, specs, or business domain documents exist in the project, or when rigor level is `fast`.
+
+1. **Run knowledge pipeline in detect mode.** Execute `harness knowledge-pipeline --domain <feature-domain>` to produce a differential gap report comparing extracted business rules against documented knowledge in `docs/knowledge/`.
+
+2. **If gaps exist and `--fix` is appropriate,** run `harness knowledge-pipeline --fix --domain <feature-domain>` to materialize `docs/knowledge/{domain}/*.md` files from extracted findings. This creates the knowledge baseline from PRDs before any tasks are written.
+
+3. **Cross-check uncertainties against materialized knowledge** (from `businessKnowledge` loaded in gather_context and freshly materialized docs):
+   - Remove "assumptions" from the uncertainty list that are now documented facts in `docs/knowledge/`
+   - Escalate if contradictions exist between PRDs and existing knowledge docs
+   - Use `business_fact` nodes from the graph context to validate domain assumptions
+
+4. **Reference materialized knowledge in Phase 2 task decomposition.** Tasks should reference specific knowledge docs they implement. Observable truths should map back to documented business rules. Use the `businessKnowledge` context (domains, tags, documented facts) loaded in Phase 1 to ground task instructions in verified domain knowledge rather than assumptions.
+
 ---
 
 ### Phase 2: DECOMPOSE — Map File Structure and Create Tasks
@@ -190,16 +238,47 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
    - **Exact commit message**
    - **`harness validate`** as the final step
 
-5. **Include checkpoints.** Mark tasks requiring human input:
+5. **Skill annotations.** If skill recommendations were loaded in Phase 1, annotate each task with relevant skills from the Apply and Reference tiers:
+
+   ```
+   ### Task 3: Implement dark mode toggle
+   **Skills:** `design-dark-mode` (apply), `a11y-color-contrast` (reference)
+   ```
+
+   Match skills to tasks based on keyword and domain overlap between the task description and the skill's purpose/keywords. Only annotate when the match is relevant to the specific task.
+
+6. **Include checkpoints.** Mark tasks requiring human input:
    - `[checkpoint:human-verify]` — Pause, show result, wait for confirmation
    - `[checkpoint:decision]` — Pause, present options, wait for choice
    - `[checkpoint:human-action]` — Pause, instruct human on required action
 
+7. **Derive integration tasks from the spec's Integration Points section.** If the spec contains an Integration Points section, create tasks for each non-empty integration point. Skip subsections marked "None" — do not derive tasks from them. Integration tasks are normal plan tasks but tagged with `category: "integration"` in their description. They appear at the end of the task list, after all implementation tasks.
+
+   For each subsection of Integration Points, derive tasks:
+
+   | Integration Point                               | Example Derived Task                                                       |
+   | ----------------------------------------------- | -------------------------------------------------------------------------- |
+   | Entry Points: "New CLI command"                 | "Regenerate barrel exports. Verify new command appears in `_registry.ts`." |
+   | Registrations Required: "Skill at tier 2"       | "Add skill to tier list in `AGENTS.md`. Generate slash commands."          |
+   | Documentation Updates: "AGENTS.md capabilities" | "Update AGENTS.md to describe the feature."                                |
+   | Architectural Decisions: "ADR for approach X"   | "Write ADR `docs/knowledge/decisions/NNNN-<slug>.md`."                     |
+   | Knowledge Impact: "Domain concept Y"            | "Enrich knowledge graph with concept node."                                |
+
+   Integration tasks follow the same atomic task rules (2-5 minutes, exact file paths, exact code). Use the `**Category:** integration` tag in the task header, e.g.:
+
+   ```
+   ### Task N: Update AGENTS.md with new feature description
+
+   **Depends on:** Task N-1 | **Files:** `AGENTS.md` | **Category:** integration
+   ```
+
+   If the spec has no Integration Points section, skip this step.
+
 ---
 
 ### Phase 3: SEQUENCE — Order Tasks and Identify Dependencies
 
-1. **Order by dependency.** Types before implementations. Implementations before integrations. Tests alongside implementations (same task, TDD style).
+1. **Order by dependency.** Types before implementations. Implementations before integrations. Integration tasks (tagged `category: "integration"`) after all implementation tasks. Tests alongside implementations (same task, TDD style).
 2. **Identify parallel opportunities.** Tasks touching different subsystems with no shared state can be marked parallelizable.
 3. **Number tasks sequentially.** Use `Task 1`, `Task 2`, etc. Dependencies reference task numbers.
 4. **Estimate total time.** Sum 2-5 minutes per task. If total exceeds available time, identify a milestone boundary for pausing.
@@ -236,7 +315,7 @@ Report progress: `**[Phase 2/4]** DECOMPOSE — mapping file structure and creat
 ```markdown
 # Plan: <Feature Name>
 
-**Date:** YYYY-MM-DD | **Spec:** (if applicable) | **Tasks:** N | **Time:** N min
+**Date:** YYYY-MM-DD | **Spec:** (if applicable) | **Tasks:** N | **Time:** N min | **Integration Tier:** small | medium | large
 
 ## Goal
 
@@ -274,6 +353,18 @@ One sentence.
 [checkpoint:human-verify] ...
 ```
 
+### Integration Tier Heuristics
+
+When a spec contains an **Integration Points** section, set the plan's `integrationTier` field based on scope:
+
+| Tier       | Signal                                                               | Integration Requirements                                                 |
+| ---------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| **small**  | Bug fix, config change, < 3 files, no new exports                    | Wiring checks only (defaults always run)                                 |
+| **medium** | New feature within existing package, new exports, 3-15 files         | Wiring + project updates (roadmap, changelog, graph enrichment)          |
+| **large**  | New package, new skill, new public API surface, architectural change | Wiring + project updates + knowledge materialization (ADRs, doc updates) |
+
+If the spec has no Integration Points section, omit the `integrationTier` field from the plan header.
+
 ## Session State
 
 | Section       | Read | Write | Purpose                                                           |
@@ -287,7 +378,7 @@ One sentence.
 
 **When to write:** Phase 1 — constraints and risks. Phase 2 — decisions about task structure. Phase 4 — resolve questions.
 
-**When to read:** Start of Phase 1 via `gather_context` with `include: ["sessions"]` to inherit brainstorming context.
+**When to read:** Start of Phase 1 via `gather_context` with `include: ["state", "learnings", "handoff", "graph", "businessKnowledge", "sessions", "validation"]` to inherit brainstorming context and load documented business knowledge.
 
 ## Evidence Requirements
 

package/dist/agents/skills/cursor/harness-refactoring/SKILL.md

@@ -28,9 +28,11 @@ If tests are not green before you start, you are not refactoring — you are deb
 
 2. **Run `harness validate`** and **`harness check-deps`**. Both must pass. You are establishing a clean baseline. If either reports issues, fix those first (that is a separate task, not part of this refactoring).
 
-3. **Identify the refactoring target.** Be specific: which file, function, class, or module? What is wrong with the current structure? What will be better after refactoring?
+3. **Run `compute_blast_radius` on target files** to understand downstream impact before refactoring. This reveals which modules, tests, and consumers will be affected by structural changes.
 
-4. **Plan the steps.** Break the refactoring into the smallest possible individual changes. Each step should be independently committable and verifiable. If you cannot describe a step in one sentence, it is too large.
+4. **Identify the refactoring target.** Be specific: which file, function, class, or module? What is wrong with the current structure? What will be better after refactoring?
+
+5. **Plan the steps.** Break the refactoring into the smallest possible individual changes. Each step should be independently committable and verifiable. If you cannot describe a step in one sentence, it is too large.
 
 ### Graph-Enhanced Context (when available)
 
@@ -81,6 +83,10 @@ For EACH step in the plan:
 
 2. **Run `harness validate` and `harness check-deps` one final time.** Clean output.
 
+3. **Run `detect_stale_constraints`** to verify architectural constraints are still valid after structural changes. Refactoring can render existing constraints obsolete or misaligned.
+
+4. **Run `check_traceability`** to confirm refactoring didn't break requirement-to-implementation mappings. Moved or renamed code may orphan traceability links.
+
 ### Graph Refresh
 
 If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
@@ -91,9 +97,9 @@ harness scan [path]
 
 Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
 
-3. **Review the cumulative diff.** Does the final state match the intended improvement? Is the code genuinely better, or just different?
+5. **Review the cumulative diff.** Does the final state match the intended improvement? Is the code genuinely better, or just different?
 
-4. **If the refactoring introduced no improvement,** revert the entire sequence. Refactoring for its own sake is churn.
+6. **If the refactoring introduced no improvement,** revert the entire sequence. Refactoring for its own sake is churn.
 
 ## Common Refactoring Patterns
 
@@ -133,6 +139,9 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 - **`harness check-deps`** — Run after each step, especially when moving code between files or layers. Catches dependency violations introduced by structural changes.
 - **`harness check-docs`** — Run after renaming or moving public APIs. Catches documentation that references old names or locations.
 - **`harness cleanup`** — Run after completing a refactoring sequence. Detects dead code that the refactoring may have created (unused exports, orphaned files).
+- **`compute_blast_radius`** — Run in Phase 1 PREPARE before making changes. Reveals downstream impact of target files so you understand what the refactoring will affect.
+- **`detect_stale_constraints`** — Run in Phase 3 VERIFY after refactoring. Checks whether architectural constraints are still valid after structural changes.
+- **`check_traceability`** — Run in Phase 3 VERIFY after refactoring. Confirms requirement-to-implementation mappings were not broken by moved or renamed code.
 
 ## Success Criteria
 

package/dist/agents/skills/cursor/harness-security-scan/SKILL.md

@@ -34,7 +34,9 @@
    - `warning`: errors and warnings (default)
    - `info`: all findings
 
-6. **Output report.** Present findings grouped by severity:
+6. **Check security trends.** Check `get_security_trends` to compare current scan results against the project's security posture history and identify trajectory changes.
+
+7. **Output report.** Present findings grouped by severity:
 
    ```
    Security Scan: [PASS/FAIL]

package/dist/agents/skills/cursor/harness-soundness-review/SKILL.md

@@ -47,6 +47,10 @@ Every finding conforms to this structure:
 
 Execute all checks for the active mode. Classify each finding as `autoFixable: true` or `false`. Record total issue count.
 
+#### Traceability and Cross-Check Tools
+
+Run `check_traceability` to verify that all requirements in the spec/plan have corresponding implementation artifacts. Run `validate_cross_check` to verify plan-to-implementation alignment as part of the soundness assessment.
+
 #### Graph Detection and Fallback
 
 Before running checks, determine graph availability:

package/dist/agents/skills/cursor/harness-tdd/SKILL.md

@@ -71,9 +71,11 @@ If you find yourself writing production code first, STOP. Delete it. Write the t
 
 2. **Run `harness validate`** to verify the full project health. This catches architectural drift, documentation gaps, and constraint violations.
 
-3. **If either check fails,** fix the issue before committing. The fix may require another RED-GREEN-REFACTOR cycle if it involves behavioral changes.
+3. **Run `check_traceability`** to verify new tests map to specific requirements, ensuring test coverage aligns with spec expectations. This catches tests that exist in isolation without a traced requirement.
 
-4. **Commit the cycle.** Each RED-GREEN-REFACTOR-VALIDATE cycle produces one atomic commit. The commit message references what behavior was added (not "add test" — describe the behavior).
+4. **If any check fails,** fix the issue before committing. The fix may require another RED-GREEN-REFACTOR cycle if it involves behavioral changes.
+
+5. **Commit the cycle.** Each RED-GREEN-REFACTOR-VALIDATE cycle produces one atomic commit. The commit message references what behavior was added (not "add test" — describe the behavior).
 
 ### Graph Refresh
 
@@ -111,6 +113,7 @@ Repeat the 4 phases for each new behavior. A typical feature requires 3-10 cycle
 - **`harness check-deps`** — Run in VALIDATE phase after each cycle. Catches forbidden imports and layer boundary violations introduced by new code.
 - **`harness validate`** — Run in VALIDATE phase after each cycle. Full project health check including architecture, documentation, and constraints.
 - **`harness cleanup`** — Run periodically (every 3-5 cycles) to detect entropy accumulation. Address any issues before they compound.
+- **`check_traceability`** — Run in VALIDATE phase after tests are written. Verifies new tests map to specific requirements so test coverage aligns with spec expectations.
 - **Test runner** — Use the project's configured test runner. Harness does not prescribe a test framework but the test must actually execute and report results.
 
 ## Success Criteria

package/dist/agents/skills/cursor/harness-verification/SKILL.md

@@ -386,6 +386,10 @@ Task: "Create UserService with CRUD operations."
 - **`harness check-deps`** -- Run during Level 3 (WIRED) to verify dependency boundaries.
 - **`harness check-docs`** -- Verify documentation updated for new artifacts. Missing docs for public APIs is a gap.
 - **Test runner** -- Must be run fresh (not cached) during Level 3. Read actual output, check exit codes.
+- **`check_traceability`** -- Run during Level 3 (WIRED) to verify every requirement in the spec maps to at least one implemented artifact and test.
+- **`validate_cross_check`** -- Run after Level 3 against the plan to verify implementation matches planned file map and task descriptions.
+- **`check_phase_gate`** -- Run before producing the verification report to validate the current phase meets all gate criteria before marking complete.
+- **`detect_anomalies`** -- Run during the Anti-Pattern Scan to identify structural inconsistencies (orphaned files, missing tests, unusual coupling) introduced during execution.
 - **`emit_interaction`** -- Auto-transition to harness-code-review on PASS verdict only.
 - **Session directory** -- `.harness/sessions/<slug>/` contains `handoff.json`, `state.json`, `artifacts.json` (spec path, plan path, file lists from execution). Do not write to global `.harness/handoff.json` when session slug is known.
 

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

@@ -29,6 +29,17 @@
 
 4. **Recommend the target adoption level.** For new projects, start with basic unless the team has harness experience. For existing projects, recommend one level up from current. Present the recommendation and wait for confirmation.
 
+5. **Classify the project shape — product/service or test-suite?** Check these signals; if any match, the project is a test suite and the rest of this skill's flow changes:
+   - Repo or package name matches `*test*`, `*-e2e*`, `*-qa*`, `*-automation*`
+   - `package.json` has `@playwright/test`, `cypress`, `webdriverio`, `mocha`, or `testcafe` as a direct dep
+   - Top-level `tests/`, `e2e/`, `specs/`, or `playwright/` directories are the primary source tree
+   - 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 product/service:** continue with the rest of this skill as written.
+
 ### Phase 2: SCAFFOLD — Generate Project Structure
 
 1. **Run `harness init` with the appropriate flags:**
@@ -72,6 +83,8 @@
    - **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.
 
+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
 
 1. **Run `harness validate`** to verify the full configuration. This checks:
@@ -107,6 +120,7 @@ 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.
+- **`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.
 
 ## Success Criteria
@@ -120,15 +134,17 @@ 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 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. |
+| 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. |
 
 ## Examples
 

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

@@ -32,4 +32,5 @@ tier: 1
 state:
   persistent: false
   files: []
-depends_on: []
+depends_on:
+  - initialize-test-suite-project