@harness-engineering/cli 1.23.1 → 1.24.0

package/dist/agents/commands/codex/harness/harness-security-scan/SKILL.md

@@ -96,21 +96,11 @@ These apply to ALL skills. If you catch yourself doing any of these, STOP.
 
 ## Rationalizations to Reject
 
-### Universal
-
-These reasoning patterns sound plausible but lead to bad outcomes. Reject them.
-
-- **"It's probably fine"** — "Probably" is not evidence. Verify before asserting.
-- **"This is best practice"** — Best practice in what context? Cite the source and
-  confirm it applies to this codebase.
-- **"We can fix it later"** — If it is worth flagging, it is worth documenting now
-  with a concrete follow-up plan.
-
-### Domain-Specific
-
-- **"No attacker would find this"** — Security by obscurity. If the code is wrong, flag it regardless of discoverability.
-- **"We're behind a firewall"** — Network boundaries change. Code should be secure at every layer regardless of deployment topology.
-- **"The framework handles this for us"** — Verify the framework's actual behavior. Misuse of a secure framework is still insecure.
+| Rationalization | Reality |
+| --- | --- |
+| "No attacker would find this" | Security by obscurity. If the code is wrong, flag it regardless of discoverability. |
+| "We're behind a firewall" | Network boundaries change. Code should be secure at every layer regardless of deployment topology. |
+| "The framework handles this for us" | Verify the framework's actual behavior. Misuse of a secure framework is still insecure. |
 
 ## Escalation
 

package/dist/agents/commands/codex/harness/harness-skill-authoring/SKILL.md

@@ -123,11 +123,30 @@ depends_on:
 
 8. **For rigid skills, write `## Escalation`.** Define when to stop and ask for help. Each escalation condition should describe the symptom, the likely cause, and what to report.
 
+9. **Write `## Rationalizations to Reject`.** Every user-facing skill must include this section. It contains domain-specific rationalizations that prevent agents from skipping steps with plausible-sounding excuses. Format requirements:
+
+   - **Table format:** `| Rationalization | Reality |` with a header separator row
+   - **3-8 entries** per skill, each specific to the skill's domain
+   - **No generic filler.** Every entry must address a rationalization that is plausible in the context of this specific skill
+   - **Do not repeat universal rationalizations.** The following three are always in effect for all skills and must NOT appear in individual skill tables:
+
+   | Rationalization | Reality |
+   | --- | --- |
+   | "It's probably fine" | "Probably" is not evidence. Verify before asserting. |
+   | "This is best practice" | Best practice in what context? Cite the source and confirm it applies here. |
+   | "We can fix it later" | If worth flagging, document now with a concrete follow-up plan. |
+
+   Example of a good domain-specific entry (for a code review skill):
+
+   | Rationalization | Reality |
+   | --- | --- |
+   | "The tests pass so the logic must be correct" | Passing tests prove the tested paths work. They say nothing about untested paths, edge cases, or whether the tests themselves are correct. |
+
 ### Phase 5: VALIDATE — Verify the Skill
 
 1. **Run `harness skill validate`** to check:
    - `skill.yaml` has all required fields and valid values
-   - `SKILL.md` has all required sections (`## When to Use`, `## Process`, `## Harness Integration`, `## Success Criteria`, `## Examples`)
+   - `SKILL.md` has all required sections (`## When to Use`, `## Process`, `## Harness Integration`, `## Success Criteria`, `## Examples`, `## Rationalizations to Reject`)
    - Rigid skills have `## Gates` and `## Escalation` sections
    - The `name` in `skill.yaml` matches the directory name
    - Referenced tools exist

package/dist/agents/commands/codex/harness/harness-soundness-review/SKILL.md

@@ -1250,6 +1250,16 @@ Phase 4: SURFACE
 CLEAN EXIT — returning control to harness-planning for sign-off.
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "The spec looks coherent to me, so I can skip running the S1 internal coherence check" | Every check in the mode must run. S1 detects contradictions between decisions, technical design, and success criteria that human review frequently misses. |
+| "This unstated assumption is obvious, so documenting it would be pedantic" | S3 exists because "obvious" assumptions cause the most damage when they turn out to be wrong. Obvious assumptions are the cheapest to document and the most expensive to miss. |
+| "The success criterion is somewhat vague but the team will know what it means" | S7 flags vague criteria like "should be fast" because they are untestable. Vague criteria survive brainstorming and planning only to fail at verification. |
+| "This auto-fixable finding is minor, so I will just note it rather than applying the fix" | Auto-fixable findings should be applied silently -- that is the design intent. Skipping them means the spec ships with known inferrable gaps. |
+| "The feasibility check found a signature mismatch but the code can probably be adapted during execution" | S5 feasibility red flags are always severity "error" and always surface to the user. A spec that references nonexistent modules will produce a broken plan. |
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.

package/dist/agents/commands/codex/harness/harness-supply-chain-audit/SKILL.md

@@ -182,6 +182,14 @@ Combine factor scores into an overall risk level:
 
 ---
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "This package has high risk signals but it is widely used, so it must be safe" | The Iron Law: present findings as flags for human review, never as verdicts. Popularity does not eliminate bus-factor risk or maintenance abandonment. |
+| "The npm API returned an error for this package, so I will skip it and move on" | API failures produce "unknown" scores with a note, not skips. Partial results with noted gaps are always better than incomplete audits. |
+| "The install script is probably just native addon compilation, so I do not need to flag it" | Every install script must be flagged in the report. "Probably legitimate" is exactly the assumption that supply chain attacks exploit. |
+
 ## Gates
 
 - **Stop if no lockfile.** Do not evaluate without a lockfile — results will be unreliable.

package/dist/agents/commands/codex/harness/harness-tdd/SKILL.md

@@ -159,6 +159,15 @@ git commit -m "feat(cart): calculate total from item price and quantity"
 
 **Next cycle (RED):** Write a test for empty array input. Watch it fail (or pass — if it passes, the behavior is already handled). Continue.
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "I know exactly what the implementation should be, so I will write it first and add the test after" | Code before test equals delete it. The gate is explicit: if production code is written before a failing test exists, delete the production code and start correctly. |
+| "The test passed on the first run, so TDD is working" | If the test passed without implementing the production code, either the behavior already exists or the test is wrong. You must watch the test FAIL for the right reason before proceeding to GREEN. |
+| "I will test multiple behaviors in this one test to be efficient" | One test, one assertion, one behavior. Multi-behavior tests make it impossible to pinpoint which behavior broke when the test fails. |
+| "Harness validate can wait until the end of the feature since it slows down the cycle" | No skipping VALIDATE. Every cycle must end with harness check-deps and harness validate. A passing test with a failing validation means the implementation violated a project constraint. |
+
 ## Gates
 
 These are hard stops. Violating any gate means the process has broken down.

package/dist/agents/commands/codex/harness/harness-test-advisor/SKILL.md

@@ -151,6 +151,14 @@ Output:
   Coverage gaps: none
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "Only the Tier 1 direct tests matter -- Tier 2 and Tier 3 are probably unnecessary" | Tier 2 tests catch indirect breakage one hop away. A change to auth.ts breaks login.ts which breaks login.test.ts. Skipping Tier 2 misses exactly the regressions hardest to debug. |
+| "The changed file has no tests, but that is not my concern -- I just advise on which tests to run" | Coverage gaps must be flagged. When a changed file has no test coverage, the advisor reports it. Silently producing an empty test list gives false confidence. |
+| "The graph is stale but I will use it anyway since some data is better than no data" | If the graph is more than 10 commits behind, refresh before proceeding. Staleness sensitivity is Medium for test advisor. |
+
 ## Gates
 
 - **Graph preferred, fallback available.** If no graph exists, use naming conventions, import parsing, and git co-change analysis to identify relevant tests. Do not stop — produce the best test selection possible.

package/dist/agents/commands/codex/harness/harness-verification/SKILL.md

@@ -396,6 +396,15 @@ Task: "Create UserService with create, read, update, delete operations."
 ### Verdict: COMPLETE — all artifacts verified at all levels
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "The tests passed when I ran them earlier, so I do not need to re-run them now" | The Iron Law forbids cached results. All verification evidence must be collected fresh in THIS session. |
+| "The file exists and has code in it, so I can skip reading it thoroughly for Level 2" | Level 2 (SUBSTANTIVE) requires reading the file content thoroughly. Scanning for TODO, throw new Error, empty functions, and hardcoded return values catches stubs that look like real implementations. |
+| "This artifact is tested by a file that imports it, so it passes Level 3 WIRED" | Being imported is necessary but not sufficient for WIRED. The test must actually make assertions about the artifact's behavior and not be skipped. |
+| "The verification report probably looks fine based on what I remember" | The words "should", "probably", "seems to", and "I believe" are forbidden in verification reports. Replace with "verified: [evidence]" or "not verified: [what is missing]." |
+
 ## Gates
 
 - **No completion without evidence.** You may not say "done," "complete," "finished," or "implemented" without a verification report showing PASS at all 3 levels for all deliverables.

package/dist/agents/commands/codex/harness/harness-verify/SKILL.md

@@ -147,6 +147,14 @@ Verification: FAIL
 - Tests: NOT RUN
 ```
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+| --- | --- |
+| "The lint command is slow and the code looks clean, so I will skip it" | No skipping. If a command is detected, it runs. Period. There is no "looks clean" judgment call. |
+| "The typecheck failed but it is just a missing type declaration, so I will interpret it as a pass" | The exit code is the only signal. No judgment calls. Exit code non-zero equals FAIL, always. |
+| "I will fix the lint error I found and re-run, since it is a quick fix" | No file modifications. This skill is read-only plus command execution. Fixing errors is the responsibility of the skill that produced the code. |
+
 ## Gates
 
 - **No judgment calls.** The exit code is the only signal.

package/dist/agents/commands/codex/harness/initialize-harness-project/SKILL.md

@@ -18,14 +18,14 @@
 
 ### Phase 1: ASSESS — Determine Current State
 
-1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.yaml`, and any skill definitions. Their presence determines whether this is a new project or a migration.
+1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.config.json`, and any skill definitions. Their presence determines whether this is a new project or a migration.
 
 2. **For new projects:** Gather project context — language, framework, test runner, build tool. Ask the human if any of these are undecided. Do not assume defaults.
 
 2b. **For existing projects with detectable frameworks:** Run `harness init` without flags first. The command auto-detects frameworks (FastAPI, Django, Gin, Axum, Spring Boot, Next.js, React+Vite, Vue, Express, NestJS) by scanning project files. Present the detection result to the human and ask for confirmation before proceeding. If detection fails, ask the human to specify `--framework` manually.
 
 3. **For existing projects:** Run `harness validate` to see what is already configured and what is missing. Read `AGENTS.md` if it exists. Identify the current adoption level:
-   - **Basic:** Has `AGENTS.md` and `harness.yaml` with project metadata. No layers, no skills, no dependency constraints.
+   - **Basic:** Has `AGENTS.md` and `harness.config.json` with project metadata. No layers, no skills, no dependency constraints.
    - **Intermediate:** Has layers defined, dependency constraints between layers, at least one custom skill. `harness check-deps` runs and passes.
    - **Advanced:** Has full persona configuration, custom skills for the team's workflows, state management, learnings capture, and CI integration for `harness validate`.
 
@@ -46,13 +46,13 @@
    **Supported languages:** typescript, python, go, rust, java
 
 2. **Review generated files.** `harness init` creates:
-   - `harness.yaml` — Project configuration (name, stack, adoption level)
+   - `harness.config.json` — Project configuration (name, stack, adoption level)
    - `.harness/` directory — State and learnings storage
    - `AGENTS.md` — Agent instructions (template, needs customization)
    - Layer definitions (intermediate and above)
    - Dependency constraints (intermediate and above)
 
-3. **Do not blindly accept generated content.** Read the generated `AGENTS.md` and `harness.yaml`. Flag anything that looks wrong or incomplete. The scaffolded output is a starting point, not a finished product.
+3. **Do not blindly accept generated content.** Read the generated `AGENTS.md` and `harness.config.json`. Flag anything that looks wrong or incomplete. The scaffolded output is a starting point, not a finished product.
 
 ### Phase 3: CONFIGURE — Customize for the Project
 
@@ -65,7 +65,7 @@
    - Known constraints and forbidden patterns
    - Links to relevant documentation
 
-3. **For intermediate and above:** Define layer boundaries. Which modules belong to which layers? What are the allowed import directions? Document these in `harness.yaml` and ensure they match the actual codebase structure.
+3. **For intermediate and above:** Define layer boundaries. Which modules belong to which layers? What are the allowed import directions? Document these in `harness.config.json` and ensure they match the actual codebase structure.
 
 4. **For advanced:** Configure state management (`.harness/state.json` schema), learnings capture (`.harness/learnings.md` conventions), and CI integration hooks.
 
@@ -77,7 +77,7 @@
 ### Phase 4: VALIDATE — Confirm Everything Works
 
 1. **Run `harness validate`** to verify the full configuration. This checks:
-   - `harness.yaml` schema validity
+   - `harness.config.json` schema validity
    - `AGENTS.md` presence and required sections
    - Layer definitions (if intermediate+)
    - Dependency constraints (if intermediate+)
@@ -113,7 +113,7 @@ This creates the `.harness/graph/` directory and populates it with the project's
 
 ## Success Criteria
 
-- `harness.yaml` exists and passes schema validation
+- `harness.config.json` exists and passes schema validation
 - `AGENTS.md` exists with project-specific content (not just the template)
 - `.harness/` directory exists with appropriate state files
 - `harness validate` passes with zero errors
@@ -123,6 +123,15 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - All generated files are committed in a single atomic commit
 - i18n configuration is set if the human chose to enable it during init
 
+## Rationalizations to Reject
+
+| Rationalization | Reality |
+|---|---|
+| "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. |
+
 ## Examples
 
 ### Example: New TypeScript Project (Basic Level)
@@ -140,7 +149,7 @@ Human confirms: "Basic is fine for now."
 
 ```bash
 harness init --level basic --framework express
-# Creates: harness.yaml, .harness/, AGENTS.md (template)
+# Creates: harness.config.json, .harness/, AGENTS.md (template)
 ```
 
 **CONFIGURE:**
@@ -161,7 +170,7 @@ Edit AGENTS.md:
 
 ```bash
 harness validate  # Pass — basic level checks satisfied
-git add harness.yaml .harness/ AGENTS.md
+git add harness.config.json .harness/ AGENTS.md
 git commit -m "feat: initialize harness project at basic level"
 ```
 
@@ -170,7 +179,7 @@ git commit -m "feat: initialize harness project at basic level"
 **ASSESS:**
 
 ```
-Read harness.yaml — level: basic
+Read harness.config.json — level: basic
 Read AGENTS.md — exists, has project-specific content
 Run: harness validate — passes at basic level
 Recommend: intermediate (add layers and dependency constraints)
@@ -181,14 +190,14 @@ Human confirms: "Yes, we're ready for layers."
 
 ```bash
 harness init --level intermediate --migrate
-# Preserves existing harness.yaml and AGENTS.md
+# Preserves existing harness.config.json and AGENTS.md
 # Adds: layer definitions template, dependency constraints template
 ```
 
 **CONFIGURE:**
 
 ```
-Define layers in harness.yaml:
+Define layers in harness.config.json:
   - presentation: src/routes/, src/middleware/
   - business: src/services/, src/models/
   - data: src/repositories/, src/db/
@@ -216,7 +225,7 @@ git commit -m "feat: migrate harness project to intermediate level with layers"
 **Basic (start here):**
 
 - `AGENTS.md` with project context
-- `harness.yaml` with metadata
+- `harness.config.json` with metadata
 - `harness validate` runs in development
 
 **Intermediate (add structure):**

package/dist/agents/commands/cursor/harness/add-harness-component.mdc

@@ -36,11 +36,11 @@ alwaysApply: false
    - **Component:** Name, which layer it belongs to, what it depends on, what will depend on it
    - **Skill:** Name, purpose, type (rigid or flexible), triggers
 
-3. **Check prerequisites.** The project must already be initialized with harness. If `harness.yaml` does not exist, stop and run initialize-harness-project first.
+3. **Check prerequisites.** The project must already be initialized with harness. If `harness.config.json` does not exist, stop and run initialize-harness-project first.
 
 ### Phase 2: VALIDATE — Check Against Existing Constraints
 
-1. **Read the current configuration.** Load `harness.yaml` and `AGENTS.md` to understand existing layers, constraints, and architecture.
+1. **Read the current configuration.** Load `harness.config.json` and `AGENTS.md` to understand existing layers, constraints, and architecture.
 
 2. **Verify the new component does not conflict:**
    - Does the layer name already exist?
@@ -60,7 +60,7 @@ alwaysApply: false
    - Component: `harness add component <name> --layer <layer-name>`
    - Skill: `harness add skill <name> --type <rigid|flexible>`
 
-2. **Review generated files and configuration changes.** `harness add` modifies `harness.yaml` and may generate template files. Check that the changes look correct.
+2. **Review generated files and configuration changes.** `harness add` modifies `harness.config.json` and may generate template files. Check that the changes look correct.
 
 3. **Create the actual code or content.** `harness add` creates the configuration entry but not necessarily the implementation. Create the directories, files, and initial code as needed.
 
@@ -70,7 +70,7 @@ alwaysApply: false
 
 2. **Update `AGENTS.md`.** Add the new component to the architecture section. Document its purpose, boundaries, and relationships to other components. This keeps agent instructions accurate.
 
-3. **Update layer configuration** if the new component changes dependency relationships. Ensure `harness.yaml` reflects the actual import graph.
+3. **Update layer configuration** if the new component changes dependency relationships. Ensure `harness.config.json` reflects the actual import graph.
 
 4. **For new skills:** Write the `skill.yaml` and `SKILL.md` files following the harness skill format. Use harness-skill-authoring for guidance on writing good skill content.
 
@@ -91,7 +91,7 @@ harness scan [path]
 Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
 
 3. **If validation fails,** fix the issues before committing. Common causes:
-   - New layer not properly registered in `harness.yaml`
+   - New layer not properly registered in `harness.config.json`
    - Component placed in wrong directory for its declared layer
    - Imports from forbidden layers
    - `AGENTS.md` references outdated architecture
@@ -109,7 +109,7 @@ Skipping this step means subsequent graph queries (impact analysis, dependency h
 
 ## Success Criteria
 
-- The new component is properly registered in `harness.yaml`
+- The new component is properly registered in `harness.config.json`
 - The component's files exist in the correct directories for its declared layer
 - `AGENTS.md` is updated to reflect the new component
 - `harness validate` passes after the addition
@@ -129,7 +129,7 @@ DETERMINE: Adding a layer. Name: infrastructure. Dirs: src/infrastructure/.
   Imported by: business layer (services call external APIs through infrastructure).
 
 VALIDATE:
-  Read harness.yaml — existing layers: presentation, business, data.
+  Read harness.config.json — existing layers: presentation, business, data.
   No conflict with "infrastructure" name.
   Run: harness check-deps — passes (clean baseline).
 
@@ -138,13 +138,13 @@ ADD:
   mkdir -p src/infrastructure
 
 WIRE:
-  Update harness.yaml: allow business → infrastructure imports.
+  Update harness.config.json: allow business → infrastructure imports.
   Update AGENTS.md: document infrastructure layer purpose and boundaries.
 
 VERIFY:
   harness validate    # Pass
   harness check-deps  # Pass
-  git add harness.yaml AGENTS.md src/infrastructure/
+  git add harness.config.json AGENTS.md src/infrastructure/
   git commit -m "feat: add infrastructure layer for external API clients"
 ```
 
@@ -164,7 +164,7 @@ WIRE:
 
 VERIFY:
   harness validate  # Pass
-  git add harness.yaml AGENTS.md
+  git add harness.config.json AGENTS.md
   git commit -m "feat: track API spec for documentation drift detection"
 ```
 
@@ -177,7 +177,7 @@ DETERMINE: Adding a component. Name: notification-service. Layer: business.
   Depends on: data layer (notification repository). Depended on by: presentation layer (routes).
 
 VALIDATE:
-  Read harness.yaml — business layer exists, maps to src/services/.
+  Read harness.config.json — business layer exists, maps to src/services/.
   No existing notification-service directory.
   business → data is an allowed import. Presentation → business is allowed.
   Run: harness check-deps — passes.
@@ -194,7 +194,7 @@ WIRE:
 VERIFY:
   harness validate    # Pass
   harness check-deps  # Pass
-  git add harness.yaml AGENTS.md src/services/notification-service.*
+  git add harness.config.json AGENTS.md src/services/notification-service.*
   git commit -m "feat: add notification service to business layer"
 ```
 

package/dist/agents/commands/cursor/harness/harness-onboarding.mdc

@@ -30,7 +30,7 @@ alwaysApply: false
    - Constraints and forbidden patterns
    - Any special instructions or warnings
 
-2. **Read `harness.yaml`.** Extract:
+2. **Read `harness.config.json`.** Extract:
    - Project name and stack
    - Adoption level (basic, intermediate, advanced)
    - Layer definitions and their directory mappings
@@ -55,7 +55,7 @@ alwaysApply: false
 2. **Map the architecture.** Walk the directory structure and identify:
    - Top-level organization pattern (monorepo, single package, workspace)
    - Source code location and entry points
-   - Layer boundaries (from `harness.yaml` and actual directory structure)
+   - Layer boundaries (from `harness.config.json` and actual directory structure)
    - Shared utilities or common modules
    - Configuration files and their purposes
 
@@ -68,7 +68,7 @@ alwaysApply: false
    - Code formatting (detect from config files: `.prettierrc`, `.eslintrc`, `biome.json`)
 
 4. **Map the constraints.** Identify what is restricted:
-   - Forbidden imports (from `harness.yaml` dependency constraints)
+   - Forbidden imports (from `harness.config.json` dependency constraints)
    - Layer boundary rules (which layers can import from which)
    - Linting rules that encode architectural decisions
    - Any constraints documented in `AGENTS.md` that are not yet automated
@@ -102,8 +102,8 @@ Graph queries produce a complete architecture map in seconds, including transiti
 
 ### Phase 3: ORIENT — Identify Adoption Level and Maturity
 
-1. **Confirm the adoption level** matches what `harness.yaml` declares:
-   - Basic: `AGENTS.md` and `harness.yaml` exist but no layers or constraints
+1. **Confirm the adoption level** matches what `harness.config.json` declares:
+   - Basic: `AGENTS.md` and `harness.config.json` exist but no layers or constraints
    - Intermediate: Layers defined, dependency constraints enforced, at least one custom skill
    - Advanced: Personas, state management, learnings, CI integration
 
@@ -191,16 +191,16 @@ Graph queries produce a complete architecture map in seconds, including transiti
 - **`harness check-deps`** — Run to verify dependency constraints are passing, which confirms layer boundaries are respected.
 - **`harness state show`** — View current state to understand where the last session left off.
 - **`AGENTS.md`** — Primary source of project context and agent instructions.
-- **`harness.yaml`** — Source of structural configuration (layers, constraints, skills).
+- **`harness.config.json`** — Source of structural configuration (layers, constraints, skills).
 - **`.harness/learnings.md`** — Historical context and institutional knowledge.
 
 ## Success Criteria
 
-- All four configuration sources were read (`AGENTS.md`, `harness.yaml`, `.harness/learnings.md`, `.harness/state.json`)
+- All four configuration sources were read (`AGENTS.md`, `harness.config.json`, `.harness/learnings.md`, `.harness/state.json`)
 - Technology stack is accurately identified (language, framework, test runner, build tool)
 - Architecture is mapped with correct layer boundaries and dependency directions
 - Conventions are identified from actual code patterns, not assumed
-- Constraints are enumerated from both `harness.yaml` and `AGENTS.md`
+- Constraints are enumerated from both `harness.config.json` and `AGENTS.md`
 - Adoption level is confirmed (not just declared — validated)
 - A structured orientation summary is produced with all sections filled
 - The "Getting Started" section is actionable and tailored to the audience
@@ -218,7 +218,7 @@ Read AGENTS.md:
   - Stack: TypeScript, Express, Vitest, PostgreSQL
   - Conventions: zod validation, repository pattern, kebab-case files
 
-Read harness.yaml:
+Read harness.config.json:
   - Level: intermediate
   - Layers: presentation (src/routes/), business (src/services/), data (src/repositories/)
   - Constraints: presentation → business OK, business → data OK, data → presentation FORBIDDEN
@@ -265,7 +265,7 @@ Produce orientation with all sections. Getting Started for this context:
 
 ```
 Read AGENTS.md — exists, minimal content
-Read harness.yaml — level: basic, no layers defined
+Read harness.config.json — level: basic, no layers defined
 No .harness/learnings.md
 No .harness/state.json
 ```

package/dist/agents/commands/cursor/harness/harness-roadmap.mdc

@@ -49,7 +49,7 @@ If the human has not seen and approved the milestone groupings and feature list,
    - Has spec + plan but no implementation -> `planned`
    - Has spec but no plan -> `backlog`
    - Has plan but no spec -> `planned` (unusual, flag for human review)
-6. Detect project name from `harness.yaml` `project` field, or `package.json` `name` field, or directory name as fallback.
+6. Detect project name from `harness.config.json` `project` field, or `package.json` `name` field, or directory name as fallback.
 
 Present scan summary:
 

package/dist/agents/commands/cursor/harness/initialize-harness-project.mdc

@@ -23,14 +23,14 @@ alwaysApply: false
 
 ### Phase 1: ASSESS — Determine Current State
 
-1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.yaml`, and any skill definitions. Their presence determines whether this is a new project or a migration.
+1. **Check for existing harness configuration.** Look for `.harness/` directory, `AGENTS.md`, `harness.config.json`, and any skill definitions. Their presence determines whether this is a new project or a migration.
 
 2. **For new projects:** Gather project context — language, framework, test runner, build tool. Ask the human if any of these are undecided. Do not assume defaults.
 
 2b. **For existing projects with detectable frameworks:** Run `harness init` without flags first. The command auto-detects frameworks (FastAPI, Django, Gin, Axum, Spring Boot, Next.js, React+Vite, Vue, Express, NestJS) by scanning project files. Present the detection result to the human and ask for confirmation before proceeding. If detection fails, ask the human to specify `--framework` manually.
 
 3. **For existing projects:** Run `harness validate` to see what is already configured and what is missing. Read `AGENTS.md` if it exists. Identify the current adoption level:
-   - **Basic:** Has `AGENTS.md` and `harness.yaml` with project metadata. No layers, no skills, no dependency constraints.
+   - **Basic:** Has `AGENTS.md` and `harness.config.json` with project metadata. No layers, no skills, no dependency constraints.
    - **Intermediate:** Has layers defined, dependency constraints between layers, at least one custom skill. `harness check-deps` runs and passes.
    - **Advanced:** Has full persona configuration, custom skills for the team's workflows, state management, learnings capture, and CI integration for `harness validate`.
 
@@ -51,13 +51,13 @@ alwaysApply: false
    **Supported languages:** typescript, python, go, rust, java
 
 2. **Review generated files.** `harness init` creates:
-   - `harness.yaml` — Project configuration (name, stack, adoption level)
+   - `harness.config.json` — Project configuration (name, stack, adoption level)
    - `.harness/` directory — State and learnings storage
    - `AGENTS.md` — Agent instructions (template, needs customization)
    - Layer definitions (intermediate and above)
    - Dependency constraints (intermediate and above)
 
-3. **Do not blindly accept generated content.** Read the generated `AGENTS.md` and `harness.yaml`. Flag anything that looks wrong or incomplete. The scaffolded output is a starting point, not a finished product.
+3. **Do not blindly accept generated content.** Read the generated `AGENTS.md` and `harness.config.json`. Flag anything that looks wrong or incomplete. The scaffolded output is a starting point, not a finished product.
 
 ### Phase 3: CONFIGURE — Customize for the Project
 
@@ -70,7 +70,7 @@ alwaysApply: false
    - Known constraints and forbidden patterns
    - Links to relevant documentation
 
-3. **For intermediate and above:** Define layer boundaries. Which modules belong to which layers? What are the allowed import directions? Document these in `harness.yaml` and ensure they match the actual codebase structure.
+3. **For intermediate and above:** Define layer boundaries. Which modules belong to which layers? What are the allowed import directions? Document these in `harness.config.json` and ensure they match the actual codebase structure.
 
 4. **For advanced:** Configure state management (`.harness/state.json` schema), learnings capture (`.harness/learnings.md` conventions), and CI integration hooks.
 
@@ -82,7 +82,7 @@ alwaysApply: false
 ### Phase 4: VALIDATE — Confirm Everything Works
 
 1. **Run `harness validate`** to verify the full configuration. This checks:
-   - `harness.yaml` schema validity
+   - `harness.config.json` schema validity
    - `AGENTS.md` presence and required sections
    - Layer definitions (if intermediate+)
    - Dependency constraints (if intermediate+)
@@ -118,7 +118,7 @@ This creates the `.harness/graph/` directory and populates it with the project's
 
 ## Success Criteria
 
-- `harness.yaml` exists and passes schema validation
+- `harness.config.json` exists and passes schema validation
 - `AGENTS.md` exists with project-specific content (not just the template)
 - `.harness/` directory exists with appropriate state files
 - `harness validate` passes with zero errors
@@ -145,7 +145,7 @@ Human confirms: "Basic is fine for now."
 
 ```bash
 harness init --level basic --framework express
-# Creates: harness.yaml, .harness/, AGENTS.md (template)
+# Creates: harness.config.json, .harness/, AGENTS.md (template)
 ```
 
 **CONFIGURE:**
@@ -166,7 +166,7 @@ Edit AGENTS.md:
 
 ```bash
 harness validate  # Pass — basic level checks satisfied
-git add harness.yaml .harness/ AGENTS.md
+git add harness.config.json .harness/ AGENTS.md
 git commit -m "feat: initialize harness project at basic level"
 ```
 
@@ -175,7 +175,7 @@ git commit -m "feat: initialize harness project at basic level"
 **ASSESS:**
 
 ```
-Read harness.yaml — level: basic
+Read harness.config.json — level: basic
 Read AGENTS.md — exists, has project-specific content
 Run: harness validate — passes at basic level
 Recommend: intermediate (add layers and dependency constraints)
@@ -186,14 +186,14 @@ Human confirms: "Yes, we're ready for layers."
 
 ```bash
 harness init --level intermediate --migrate
-# Preserves existing harness.yaml and AGENTS.md
+# Preserves existing harness.config.json and AGENTS.md
 # Adds: layer definitions template, dependency constraints template
 ```
 
 **CONFIGURE:**
 
 ```
-Define layers in harness.yaml:
+Define layers in harness.config.json:
   - presentation: src/routes/, src/middleware/
   - business: src/services/, src/models/
   - data: src/repositories/, src/db/
@@ -221,7 +221,7 @@ git commit -m "feat: migrate harness project to intermediate level with layers"
 **Basic (start here):**
 
 - `AGENTS.md` with project context
-- `harness.yaml` with metadata
+- `harness.config.json` with metadata
 - `harness validate` runs in development
 
 **Intermediate (add structure):**