@harness-engineering/cli 1.0.1 → 1.1.0

package/dist/agents/agents/skills/gemini-cli/harness-verification/SKILL.md

@@ -0,0 +1,262 @@
+# Harness Verification
+
+> 3-level evidence-based verification. No completion claims without fresh evidence. "Should work" is not evidence.
+
+## When to Use
+
+- After completing any implementation task (before claiming "done")
+- After executing a plan or spec (verify all deliverables)
+- When validating work done by another agent or in a previous session
+- When resuming work after a context reset (re-verify before continuing)
+- When `on_commit` or `on_pr` triggers fire and verification is needed
+- NOT as a replacement for tests (verification checks that tests exist and pass, not that logic is correct)
+- NOT for in-progress work (verify at completion boundaries, not mid-stream)
+
+### Verification Tiers
+
+Harness uses a two-tier verification model:
+
+| Tier           | Skill                             | When                       | What                                               |
+| -------------- | --------------------------------- | -------------------------- | -------------------------------------------------- |
+| **Quick gate** | harness-execution (built-in)      | After every task           | test + lint + typecheck + build + harness validate |
+| **Deep audit** | harness-verification (this skill) | Milestones, PRs, on-demand | EXISTS → SUBSTANTIVE → WIRED                       |
+
+Use this skill (deep audit) for milestone boundaries, before creating PRs, or when the quick gate passes but something feels wrong. Do NOT invoke this skill after every individual task — that is what the quick gate handles.
+
+## Process
+
+### Iron Law
+
+**No completion claim may be made without fresh verification evidence collected in THIS session.**
+
+Cached results, remembered outcomes, and "it worked last time" are not evidence. Run the checks. Read the output. Report what you observed.
+
+The words "should", "probably", "seems to", and "I believe" are forbidden in verification reports. Replace with "verified: [evidence]" or "not verified: [what is missing]."
+
+---
+
+### Level 1: EXISTS — The Artifact Is Present
+
+For every artifact that was supposed to be created or modified:
+
+1. **Check that the file exists on disk.** Use `ls`, `stat`, or read the file. Do not assume it exists because you wrote it — file writes can fail silently.
+
+2. **Check that the file has content.** An empty file is not an artifact. Read the file and confirm it has non-trivial content.
+
+3. **Check the file is in the right location.** Compare the actual path against the spec or plan. A file in the wrong directory is not "present."
+
+4. **Record the result.** For each expected artifact:
+   ```
+   [EXISTS: PASS] path/to/file.ts (247 lines)
+   [EXISTS: FAIL] path/to/missing-file.ts — file not found
+   ```
+
+Do not proceed to Level 2 until all Level 1 checks pass. Missing files must be created first.
+
+---
+
+### Level 2: SUBSTANTIVE — Not a Stub
+
+For every artifact that passed Level 1:
+
+1. **Read the file content.** Do not skim — read it thoroughly.
+
+2. **Scan for anti-patterns** that indicate stub or placeholder implementations:
+   - `TODO` or `FIXME` comments (especially `TODO: implement`)
+   - `throw new Error('not implemented')`
+   - `() => {}` (empty arrow functions)
+   - `return null`, `return undefined`, `return {}` as the only logic
+   - `pass` (Python placeholder)
+   - `placeholder`, `stub`, `mock` in non-test code
+   - Functions with only a comment describing what they should do
+   - Interfaces or types defined but never implemented
+
+3. **Verify real implementation exists.** The file must contain actual logic that performs the described behavior. A function that only returns a hardcoded value is a stub unless that is the correct behavior.
+
+4. **Check for completeness against the spec.** If the spec says "handles errors X, Y, Z," verify all three are handled, not just X.
+
+5. **Record the result.** For each artifact:
+   ```
+   [SUBSTANTIVE: PASS] path/to/file.ts — real implementation, no stubs
+   [SUBSTANTIVE: FAIL] path/to/file.ts — contains TODO on line 34, empty handler on line 67
+   ```
+
+Do not proceed to Level 3 until all Level 2 checks pass. Stubs must be replaced with real implementations first.
+
+---
+
+### Level 3: WIRED — Connected to the System
+
+For every artifact that passed Level 2:
+
+1. **Verify the artifact is imported/required** by at least one other file in the system (unless it is an entry point).
+
+2. **Verify the artifact is called/used.** An import that is never called is dead code. Trace the usage:
+   - Functions: called from at least one other function or test
+   - Components: rendered in at least one parent or route
+   - Types: used in at least one function signature or variable declaration
+   - Configuration: loaded and applied by the system
+   - Tests: executed by the test runner
+
+3. **Verify the artifact is tested.** There must be at least one test that exercises the artifact's behavior. Check:
+   - Test file exists
+   - Test imports or references the artifact
+   - Test makes assertions about the artifact's behavior
+   - Test actually runs (not skipped with `.skip` or `xit`)
+
+4. **Run the tests.** Execute the test suite and verify tests pass. Do not trust "they passed earlier" — run them now.
+
+5. **Run harness checks.** Execute `harness validate` and verify the artifact integrates correctly with the project's constraints.
+
+6. **Record the result.** For each artifact:
+   ```
+   [WIRED: PASS] path/to/file.ts — imported by 3 files, tested in file.test.ts (4 tests, all pass)
+   [WIRED: FAIL] path/to/file.ts — exported but not imported by any other file
+   ```
+
+---
+
+### Anti-Pattern Scan
+
+Run this scan across all changed files as a final check:
+
+```
+Scan targets: TODO, FIXME, XXX, HACK, PLACEHOLDER, NOT_IMPLEMENTED
+Code patterns: () => {}, return null (as sole body), pass, raise NotImplementedError
+Test patterns: .skip, xit, xdescribe, @pytest.mark.skip, pending
+```
+
+Any match is a verification failure. Either fix it or explicitly document why it is acceptable (e.g., "TODO is tracked in issue #123 and out of scope for this task").
+
+---
+
+### Gap Identification
+
+After running all three levels, produce a structured gap report:
+
+```
+## Verification Report
+
+### Level 1: EXISTS
+- [PASS] path/to/file-a.ts (120 lines)
+- [PASS] path/to/file-b.ts (85 lines)
+- [FAIL] path/to/file-c.ts — not found
+
+### Level 2: SUBSTANTIVE
+- [PASS] path/to/file-a.ts — real implementation
+- [FAIL] path/to/file-b.ts — TODO on line 22
+
+### Level 3: WIRED
+- [PASS] path/to/file-a.ts — imported, tested, harness passes
+- [NOT CHECKED] path/to/file-b.ts — blocked by Level 2 failure
+
+### Anti-Pattern Scan
+- path/to/file-b.ts:22 — TODO: implement validation
+
+### Gaps
+1. path/to/file-c.ts must be created
+2. path/to/file-b.ts:22 must be implemented (not stub)
+
+### Verdict: INCOMPLETE — 2 gaps must be resolved
+```
+
+---
+
+### Regression Test Verification
+
+When verifying a bug fix, apply this extended protocol:
+
+1. **Write** the regression test that reproduces the bug
+2. **Run** the test — it must PASS (proving the fix works)
+3. **Revert** the fix (temporarily): `git stash` or comment out the fix
+4. **Run** the test — it must FAIL (proving the test actually catches the bug)
+5. **Restore** the fix: `git stash pop` or uncomment
+6. **Run** the test — it must PASS again (proving the fix is the reason)
+
+If step 4 passes (test does not fail without the fix), the test is not a valid regression test. It does not catch the bug. Rewrite it.
+
+## Harness Integration
+
+- **`harness validate`** — Run in Level 3 WIRED check. Verifies project-wide health and constraint compliance.
+- **`harness check-deps`** — Run in Level 3 to verify new artifacts respect dependency boundaries.
+- **`harness check-docs`** — Run to verify documentation is updated for new artifacts. Missing docs for new public APIs is a gap.
+- **Test runner** — Must be run fresh (not cached) during Level 3. Read actual output, check exit codes.
+
+All commands must be run fresh in the current session. Do not rely on results from a previous session or a previous run in the same session if code has changed since.
+
+## Success Criteria
+
+- Every claimed deliverable has been verified at all 3 levels
+- No anti-patterns remain in delivered code
+- Verification report uses the structured format with PASS/FAIL per artifact per level
+- All verification evidence was collected fresh in the current session
+- No forbidden language ("should", "probably", "seems to") appears in the report
+- All gaps are explicitly identified with specific remediation steps
+- Regression tests (for bug fixes) pass the 5-step revert check
+
+## Non-Determinism Tolerance
+
+For mechanical checks (tests pass, lint clean, types check), results are binary — pass or fail. No tolerance.
+
+For behavioral verification (did the agent follow a convention, did the output match a style guide), accept threshold-based results:
+
+- Run the check multiple times if needed
+- "Agent followed the constraint in 4/5 runs" = pass
+- "Agent followed the constraint in 2/5 runs" = fail — the convention is poorly written, not the agent
+
+If a behavioral convention fails more than 40% of the time, the convention needs rewriting. Blame the instruction, not the executor.
+
+## Examples
+
+### Example: Verifying a New Service Module
+
+Task: "Create UserService with create, read, update, delete operations."
+
+```
+## Verification Report
+
+### Level 1: EXISTS
+- [PASS] src/services/user-service.ts (189 lines)
+- [PASS] src/services/user-service.test.ts (245 lines)
+- [PASS] src/services/index.ts (updated — exports UserService)
+
+### Level 2: SUBSTANTIVE
+- [PASS] src/services/user-service.ts — all 4 CRUD methods implemented with
+         validation, error handling, and database calls
+- [PASS] src/services/user-service.test.ts — 12 tests covering happy paths,
+         error cases, and edge cases (no skipped tests)
+
+### Level 3: WIRED
+- [PASS] src/services/user-service.ts — imported by src/api/routes/users.ts,
+         tested in user-service.test.ts (12 tests, all pass)
+- [PASS] harness validate — passes
+- [PASS] harness check-deps — no boundary violations
+
+### Anti-Pattern Scan
+- No matches found
+
+### Gaps
+(none)
+
+### Verdict: COMPLETE — all artifacts verified at all levels
+```
+
+## 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.
+- **No stale evidence.** Evidence must be from the current session. "I checked earlier" is not evidence. Run it again.
+- **No forbidden language.** "Should work," "probably fine," "seems correct," and "I believe it works" are not verification statements. Replace with observed evidence or state "not verified."
+- **No skipping levels.** Level 1 before Level 2. Level 2 before Level 3. Each level depends on the previous.
+- **No satisfaction before evidence.** The natural inclination after writing code is to feel done. Resist it. Feeling done is not being done. Evidence is being done.
+
+## Escalation
+
+- **When an artifact cannot pass Level 3 (WIRED) because the system it connects to does not exist yet:** Document the gap explicitly. State what integration is missing and what must be built. Do not mark it as PASS.
+- **When anti-pattern scan finds TODOs that are intentional:** Each must be justified with a tracked issue number. "TODO: implement" with no issue reference is not acceptable. "TODO(#123): add rate limiting after infrastructure is ready" is acceptable.
+- **When tests pass but you suspect they are not testing real behavior:** Read the test assertions carefully. If tests only check "does not throw" or assert on mock return values without verifying real behavior, flag them as SUBSTANTIVE failures.
+- **When verification reveals the spec itself is incomplete:** Do not fill in the gaps yourself. Escalate to the human: "Verification found that the spec does not define behavior for [scenario]. How should this be handled?"
+- **When you cannot run harness checks:** If `harness validate` or `harness check-deps` cannot be run (missing configuration, broken tooling), this is a blocking issue. Do not skip verification — fix the tooling or escalate.
+
+After verification completes, append a tagged learning:
+
+- **YYYY-MM-DD [skill:harness-verification] [outcome:pass/fail]:** Verified [feature]. [Brief note on what was found or confirmed.]

package/dist/agents/agents/skills/gemini-cli/harness-verification/skill.yaml

@@ -0,0 +1,41 @@
+name: harness-verification
+version: "1.0.0"
+description: Comprehensive harness verification of project health and compliance
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+  - on_pr
+  - on_commit
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+cli:
+  command: harness skill run harness-verification
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-verification
+    path: string
+type: rigid
+phases:
+  - name: check
+    description: Run all harness validation commands
+    required: true
+  - name: report
+    description: Summarize findings and violations
+    required: true
+  - name: remediate
+    description: Fix any critical violations
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

package/dist/agents/agents/skills/gemini-cli/harness-verify/SKILL.md

@@ -0,0 +1,122 @@
+# Harness Verify
+
+> Binary pass/fail quick gate. Runs test, lint, typecheck — returns structured result. No judgment calls, no deep analysis. Pass or fail.
+
+## When to Use
+
+- After every task as a final sanity check
+- As the final step in any code-producing skill
+- When you need a fast mechanical answer: "does the code compile, lint, and pass tests?"
+- NOT for deep verification or architectural review (use `harness-verification` for that)
+- NOT for AI-powered code review (use `harness-code-review` for that)
+
+## Relationship to Other Skills
+
+| Skill                     | What It Does                                   | Time  |
+| ------------------------- | ---------------------------------------------- | ----- |
+| **harness-verify** (this) | Mechanical quick gate: typecheck, lint, test   | ~30s  |
+| **harness-verification**  | Deep audit: architecture, patterns, edge cases | ~5min |
+
+`harness-verify` is the fast, deterministic gate. `harness-verification` is the slow, thorough audit. They serve different purposes and should not be confused.
+
+## Process
+
+### Phase 1: DETECT
+
+Auto-detect project commands by inspecting the project root:
+
+1. **package.json** — Look for `scripts.test`, `scripts.lint`, `scripts.typecheck` (or `scripts.tsc`, `scripts.type-check`)
+2. **Makefile** — Look for `test`, `lint`, `typecheck` targets
+3. **Conventions** — Fall back to common commands:
+   - Typecheck: `npx tsc --noEmit`, `mypy .`, `go vet ./...`
+   - Lint: `npx eslint .`, `ruff check .`, `golangci-lint run`
+   - Test: `npm test`, `pytest`, `go test ./...`
+4. **Language detection** — Use file extensions to determine which convention set applies
+
+For each of the three checks (typecheck, lint, test), record either the detected command or `NONE` if no command can be determined.
+
+### Phase 2: EXECUTE
+
+Run all detected commands in this order: **typecheck -> lint -> test**.
+
+Rules:
+
+- Run ALL commands regardless of earlier failures. Do not short-circuit.
+- Capture exit code, stdout, and stderr for each command.
+- Exit code 0 = PASS. Any non-zero exit code = FAIL.
+- If a command was `NONE` (not detected), mark that check as `SKIPPED`.
+- Run each command from the project root directory.
+- Do not modify any files. Do not install dependencies. Do not fix errors.
+
+### Phase 3: REPORT
+
+Output a structured result in this exact format:
+
+```
+Verification: [PASS/FAIL]
+- Typecheck: [PASS/FAIL/SKIPPED]
+- Lint:      [PASS/FAIL/SKIPPED]
+- Test:      [PASS/FAIL/SKIPPED]
+```
+
+Rules:
+
+- Overall `Verification: PASS` only if all non-skipped checks passed.
+- If all checks are SKIPPED, overall result is `PASS` (nothing to fail).
+- On FAIL, include a brief summary of what failed (e.g., "3 type errors", "2 lint errors", "5 tests failed") below the structured block.
+
+## Deterministic Checks
+
+This skill is entirely deterministic. There are no LLM judgment calls anywhere in the process.
+
+- Exit code 0 = PASS. Always.
+- Exit code non-zero = FAIL. Always.
+- No "it looks like this might be okay" reasoning. No interpretation of output.
+- The same codebase with the same commands will always produce the same result.
+
+## Harness Integration
+
+- Follows Principle 7 (Deterministic-vs-LLM Split) — this skill is entirely deterministic
+- Invoked as the final step by code-producing skills (harness-execution, harness-tdd)
+- Complements harness-verification (deep audit) — use verify for quick checks, verification for milestones
+- Output format is consumed by harness-integrity for the unified pipeline
+
+## Success Criteria
+
+- [ ] All detected commands were executed
+- [ ] Report follows the structured format exactly
+- [ ] Overall verdict correctly reflects individual results
+- [ ] Failed checks include error output summary
+
+## Examples
+
+### Example: Node.js Project
+
+```
+Verification: PASS
+- Types: PASS (no errors)
+- Lint: PASS (0 warnings)
+- Tests: PASS (42/42)
+```
+
+### Example: Failing Project
+
+```
+Verification: FAIL
+- Types: FAIL (3 type errors in src/auth/login.ts)
+- Lint: PASS
+- Tests: NOT RUN
+```
+
+## Gates
+
+- **No judgment calls.** The exit code is the only signal.
+- **No skipping.** If a command is detected, it runs. Period.
+- **Fresh execution only.** Do not cache results. Do not reuse previous runs. Execute the commands right now.
+- **No file modifications.** This skill is read-only (plus command execution). It must not change the codebase.
+
+## Escalation
+
+- **Timeout:** Each command has a 120-second timeout. If a command exceeds this, mark it as FAIL with reason "TIMEOUT".
+- **No commands detected:** If no typecheck, lint, or test commands can be detected, all three checks are SKIPPED and the overall result is PASS. Log a note that no verification commands were found.
+- **Environment errors:** If a command fails due to missing tooling (e.g., `tsc` not installed), mark it as FAIL. Do not attempt to install the tooling.

package/dist/agents/agents/skills/gemini-cli/harness-verify/skill.yaml

@@ -0,0 +1,40 @@
+name: harness-verify
+version: "1.0.0"
+description: Binary pass/fail quick gate — runs test, lint, typecheck commands and returns structured result
+triggers:
+  - manual
+  - on_task_complete
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+cli:
+  command: harness skill run harness-verify
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-verify
+    path: string
+type: rigid
+cognitive_mode: meticulous-verifier
+phases:
+  - name: detect
+    description: Auto-detect project commands from package.json, Makefile, or conventions
+    required: true
+  - name: execute
+    description: Run test, lint, typecheck commands
+    required: true
+  - name: report
+    description: Return structured pass/fail result
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -0,0 +1,200 @@
+# Initialize Harness Project
+
+> Scaffold a new harness-compliant project or migrate an existing project to the next adoption level. Assess current state, configure personas, generate AGENTS.md, and validate the result.
+
+## When to Use
+
+- Starting a brand new project that should be harness-managed from day one
+- Migrating an existing project to harness for the first time
+- Upgrading an existing harness project from one adoption level to the next (basic to intermediate, intermediate to advanced)
+- When `on_project_init` triggers fire
+- NOT when the project is already at the desired adoption level (use harness-onboarding to orient instead)
+- NOT when adding a single component to an existing harness project (use add-harness-component)
+- NOT when the project has no clear owner or maintainer — harness setup requires someone to own the constraints
+
+## Process
+
+### 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.
+
+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.
+
+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.
+   - **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`.
+
+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.
+
+### Phase 2: SCAFFOLD — Generate Project Structure
+
+1. **Run `harness init` with the appropriate flags:**
+   - New basic project: `harness init --level basic --framework <framework>`
+   - New intermediate project: `harness init --level intermediate --framework <framework>`
+   - Migration to intermediate: `harness init --level intermediate --migrate`
+   - Migration to advanced: `harness init --level advanced --migrate`
+
+2. **Review generated files.** `harness init` creates:
+   - `harness.yaml` — 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.
+
+### Phase 3: CONFIGURE — Customize for the Project
+
+1. **Configure personas.** Run `harness persona generate` to create persona definitions based on the project's stack and team structure. Personas define how agents should behave in this project — coding style, communication preferences, constraint strictness.
+
+2. **Customize AGENTS.md.** The generated template needs project-specific content:
+   - Project description and purpose
+   - Architecture overview (components, layers, data flow)
+   - Key conventions the team follows
+   - 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.
+
+4. **For advanced:** Configure state management (`.harness/state.json` schema), learnings capture (`.harness/learnings.md` conventions), and CI integration hooks.
+
+### Phase 4: VALIDATE — Confirm Everything Works
+
+1. **Run `harness validate`** to verify the full configuration. This checks:
+   - `harness.yaml` schema validity
+   - `AGENTS.md` presence and required sections
+   - Layer definitions (if intermediate+)
+   - Dependency constraints (if intermediate+)
+   - Persona configuration (if configured)
+
+2. **Fix any validation errors before finishing.** Do not leave the project in a half-configured state.
+
+3. **Run `harness check-deps`** (intermediate and above) to verify dependency constraints match the actual codebase. If there are violations, decide with the human: update the constraints or fix the code.
+
+4. **Commit the initialization.** All generated and configured files in a single commit.
+
+## Harness Integration
+
+- **`harness init --level <level> --framework <framework>`** — Scaffold a new project at the specified adoption level.
+- **`harness init --level <level> --migrate`** — Migrate an existing project to the next adoption level, preserving existing configuration.
+- **`harness persona generate`** — Generate persona definitions based on project stack and team structure.
+- **`harness validate`** — Verify the full project configuration is valid and complete.
+- **`harness check-deps`** — Verify dependency constraints match the actual codebase (intermediate and above).
+
+## Success Criteria
+
+- `harness.yaml` 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
+- `harness check-deps` passes (intermediate and above)
+- Personas are configured if the project uses them
+- The adoption level matches what was agreed upon with the human
+- All generated files are committed in a single atomic commit
+
+## Examples
+
+### Example: New TypeScript Project (Basic Level)
+
+**ASSESS:**
+
+```
+Human: "I'm starting a new TypeScript API project using Express and Vitest."
+Check for .harness/ — not found. This is a new project.
+Recommend: basic level (new project, start simple).
+Human confirms: "Basic is fine for now."
+```
+
+**SCAFFOLD:**
+
+```bash
+harness init --level basic --framework express
+# Creates: harness.yaml, .harness/, AGENTS.md (template)
+```
+
+**CONFIGURE:**
+
+```
+Edit AGENTS.md:
+  - Add project description: "REST API for widget management"
+  - Add stack: TypeScript, Express, Vitest, PostgreSQL
+  - Add conventions: "Use zod for validation, repository pattern for data access"
+  - Add constraints: "No direct SQL queries outside repository layer"
+```
+
+**VALIDATE:**
+
+```bash
+harness validate  # Pass — basic level checks satisfied
+git add harness.yaml .harness/ AGENTS.md
+git commit -m "feat: initialize harness project at basic level"
+```
+
+### Example: Migrating Existing Project from Basic to Intermediate
+
+**ASSESS:**
+
+```
+Read harness.yaml — level: basic
+Read AGENTS.md — exists, has project-specific content
+Run: harness validate — passes at basic level
+Recommend: intermediate (add layers and dependency constraints)
+Human confirms: "Yes, we're ready for layers."
+```
+
+**SCAFFOLD:**
+
+```bash
+harness init --level intermediate --migrate
+# Preserves existing harness.yaml and AGENTS.md
+# Adds: layer definitions template, dependency constraints template
+```
+
+**CONFIGURE:**
+
+```
+Define layers in harness.yaml:
+  - presentation: src/routes/, src/middleware/
+  - business: src/services/, src/models/
+  - data: src/repositories/, src/db/
+
+Define constraints:
+  - presentation → business (allowed)
+  - business → data (allowed)
+  - data → presentation (forbidden)
+  - presentation → data (forbidden — must go through business)
+
+Update AGENTS.md with layer documentation.
+```
+
+**VALIDATE:**
+
+```bash
+harness validate      # Pass — intermediate level checks satisfied
+harness check-deps    # Pass — no constraint violations in existing code
+git add -A
+git commit -m "feat: migrate harness project to intermediate level with layers"
+```
+
+### Example: Adoption Level Progression
+
+**Basic (start here):**
+
+- `AGENTS.md` with project context
+- `harness.yaml` with metadata
+- `harness validate` runs in development
+
+**Intermediate (add structure):**
+
+- Layer definitions and boundaries
+- Dependency constraints enforced by `harness check-deps`
+- At least one custom skill for team workflows
+
+**Advanced (full integration):**
+
+- Persona configuration for consistent agent behavior
+- State management across sessions
+- `.harness/learnings.md` capturing institutional knowledge
+- `harness validate` runs in CI pipeline
+- Custom skills for all common team workflows