@harness-engineering/cli 1.7.0 → 1.8.1

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

@@ -0,0 +1,167 @@
+# Harness Integrity
+
+> Unified integrity gate — single invocation chains mechanical verification with AI-powered code review and produces a consolidated pass/fail report.
+
+## When to Use
+
+- Before opening or merging a pull request
+- At project milestones as a comprehensive quality check
+- When you need a single authoritative answer: "is this code ready to ship?"
+- NOT after every task (use `harness-verify` for quick post-task checks)
+- NOT for deep architectural audits (use `harness-verification` for that)
+
+## Relationship to Other Skills
+
+| Skill                        | What It Does                                   | Scope                  | Time  |
+| ---------------------------- | ---------------------------------------------- | ---------------------- | ----- |
+| **harness-verify**           | Mechanical only: typecheck, lint, test         | Exit codes             | ~30s  |
+| **harness-code-review**      | AI only: change-type-aware review              | LLM analysis           | ~2min |
+| **harness-integrity** (this) | Both: verify + code-review unified             | Full pipeline          | ~3min |
+| **harness-verification**     | Deep audit: architecture, patterns, edge cases | Thorough investigation | ~5min |
+
+`harness-integrity` is the standard pre-PR gate. It runs the fast mechanical checks first, then layers on AI review, and produces a single consolidated report.
+
+## Process
+
+### Phase 1: VERIFY
+
+Invoke `harness-verify` to run the mechanical quick gate.
+
+1. Delegate entirely to `harness-verify` — typecheck, lint, test.
+2. Capture the structured result (PASS/FAIL per check).
+3. **If ALL three checks FAIL**, stop here. Do not proceed to Phase 2. The code is not in a reviewable state.
+4. If at least one check passes (or some are skipped), proceed to Phase 2.
+
+### Phase 1.5: SECURITY SCAN
+
+Run the built-in security scanner as a mechanical check between verification and AI review.
+
+1. Use `run_security_scan` MCP tool against the project root (or changed files if available).
+2. Capture findings by severity: errors, warnings, info.
+3. **Error-severity security findings are blocking** — they cause the overall integrity check to FAIL, same as a test failure.
+4. Warning/info findings are included in the report but do not block.
+
+### Phase 1.7: DESIGN HEALTH (conditional)
+
+When the project has `design` configured in `harness.config.json`:
+
+1. Run `harness-design` in review mode to check existing components against design intent and anti-patterns.
+2. Run `harness-accessibility` in scan+evaluate mode to check WCAG compliance.
+3. Combine findings into a design health summary:
+   - Error count (blocking, based on strictness)
+   - Warning count (non-blocking)
+   - Info count (advisory)
+4. **Error-severity design findings are blocking** in `strict` mode only. In `standard` and `permissive` modes, design findings do not block.
+5. If no `design` block exists, skip this phase entirely.
+
+### Phase 1.8: I18N SCAN (conditional)
+
+When the project has `i18n.enabled: true` in `harness.config.json`:
+
+1. Run `harness-i18n` in scan mode to detect hardcoded strings, missing translations, locale-sensitive formatting issues, and RTL violations.
+2. Combine findings into an i18n health summary:
+   - Error count (blocking, based on `i18n.strictness`)
+   - Warning count (non-blocking)
+   - Info count (advisory)
+3. **Error-severity i18n findings are blocking** in `strict` mode only. In `standard` and `permissive` modes, i18n findings do not block.
+4. If no `i18n` block exists or `i18n.enabled` is false, skip this phase entirely.
+
+### Phase 2: REVIEW
+
+Run change-type-aware AI review using `harness-code-review`.
+
+1. Detect the change type if not provided: `feature`, `bugfix`, `refactor`, or `docs`.
+2. Invoke `harness-code-review` with the detected change type.
+3. Capture the review findings: suggestions, blocking issues, and notes.
+4. A review finding is "blocking" only if it would cause a runtime error, data loss, or security vulnerability.
+5. The AI review includes a security-focused pass that complements the mechanical scanner — checking for semantic issues like user input flowing to dangerous sinks across function boundaries.
+
+### Phase 3: REPORT
+
+Produce a unified integrity report in this exact format:
+
+```
+Integrity Check: [PASS/FAIL]
+- Tests:    [PASS/FAIL/SKIPPED]
+- Lint:     [PASS/FAIL/SKIPPED]
+- Types:    [PASS/FAIL/SKIPPED]
+- Security: [PASS/WARN/FAIL] ([count] errors, [count] warnings)
+- Design:   [PASS/WARN/FAIL/SKIPPED] ([count] errors, [count] warnings)
+- i18n:     [PASS/WARN/FAIL/SKIPPED] ([count] errors, [count] warnings)
+- Review:   [PASS/FAIL] ([count] suggestions, [count] blocking)
+
+Overall: [PASS/FAIL]
+```
+
+Rules:
+
+- Overall `PASS` requires: all non-skipped mechanical checks pass AND zero blocking review findings AND zero blocking design findings (strict mode only) AND zero blocking i18n findings (strict mode only).
+- Any mechanical failure OR any blocking review finding means `FAIL`.
+- On FAIL, include a summary section listing each failure reason.
+- Non-blocking review suggestions are noted but do not cause FAIL.
+
+## Deterministic Checks
+
+- **Phase 1 is fully deterministic.** Exit codes determine pass/fail with no interpretation.
+- **Phase 2 involves LLM judgment.** The AI review may produce different results on repeated runs. Only "blocking" findings (runtime errors, data loss, security) affect the overall result.
+
+## Harness Integration
+
+- Chains harness-verify (mechanical) and harness-code-review (AI) into a unified pipeline
+- Follows Principle 7 — deterministic checks always run first
+- Consumes change-type detection from harness-code-review for per-type checklists
+- Output can be written to `.harness/integrity-report.md` for CI integration
+- Invokes `harness-design` and `harness-accessibility` for design health when `design` config exists
+- Design strictness from config controls whether design findings block the overall result
+- Invokes `harness-i18n` for i18n compliance when `i18n.enabled` is true in config. i18n strictness controls whether findings block the overall result.
+
+## Success Criteria
+
+- [ ] Mechanical verification ran and produced structured results
+- [ ] AI review ran with change-type awareness
+- [ ] Unified report follows the exact format
+- [ ] Overall verdict correctly reflects both mechanical and review results
+
+## Examples
+
+### Example: All Clear
+
+```
+Integrity Check: PASS
+- Tests: PASS (42/42)
+- Lint: PASS (0 warnings)
+- Types: PASS
+- Security: PASS (0 errors, 0 warnings)
+- Design: PASS (0 errors, 0 warnings)
+- i18n: PASS (0 errors, 0 warnings)
+- Review: 1 suggestion (0 blocking)
+```
+
+### Example: Security Blocking Issue
+
+```
+Integrity Check: FAIL
+- Tests: PASS (42/42)
+- Lint: PASS
+- Types: PASS
+- Security: FAIL (1 error, 0 warnings)
+  - [SEC-INJ-002] src/auth/login.ts:42 — SQL query built with string concatenation
+- Design: WARN (0 errors, 2 warnings)
+- i18n: SKIPPED
+- Review: 3 findings (1 blocking)
+
+Blocking: [SEC-INJ-002] SQL injection — user input passed directly to query without parameterization.
+```
+
+## Gates
+
+- **Mechanical first.** Always run Phase 1 before Phase 2. If the code does not compile or pass basic checks, AI review is wasted effort (unless partial results exist).
+- **No partial reports.** The report must include results from all phases that were executed. Do not output Phase 1 results without attempting Phase 2 (unless the all-fail early stop triggers).
+- **Fresh execution only.** Do not reuse cached results. Run everything from scratch each time.
+
+## Escalation
+
+- **All checks fail:** If typecheck, lint, and test all fail in Phase 1, stop immediately. Report the failures and skip Phase 2. The code needs basic fixes before review is worthwhile.
+- **Architectural concerns:** If the AI review identifies architectural concerns, note them in the report but do not mark them as blocking. Architectural decisions require human judgment.
+- **Timeout:** Phase 1 inherits the 120-second per-command timeout from `harness-verify`. Phase 2 has a 180-second timeout for the AI review.
+- **Missing dependencies:** If `harness-verify` or `harness-code-review` skills are unavailable, report the missing dependency and mark the corresponding phase as `ERROR`.

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

@@ -0,0 +1,47 @@
+name: harness-integrity
+version: "1.0.0"
+description: Unified integrity gate — chains verify (quick gate) with AI review into a single report
+triggers:
+  - manual
+  - on_pr
+  - on_milestone
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-integrity
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: change-type
+      description: "Type of change: feature, bugfix, refactor, docs"
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-integrity
+    path: string
+type: rigid
+cognitive_mode: meticulous-verifier
+phases:
+  - name: verify
+    description: Run harness-verify quick gate (test, lint, typecheck)
+    required: true
+  - name: review
+    description: Run change-type-aware AI review
+    required: true
+  - name: report
+    description: Produce unified integrity report
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on:
+  - harness-verify
+  - harness-code-review

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

@@ -13,8 +13,35 @@
 
 ## Prerequisites
 
-A knowledge graph must exist at `.harness/graph/`. Run `harness scan` if no graph is available.
-If the graph exists but code has changed since the last scan, re-run `harness scan` first — stale graph data leads to inaccurate results.
+A knowledge graph at `.harness/graph/` enables full analysis. If no graph exists,
+the skill uses static analysis fallbacks (see Graph Availability section).
+Run `harness scan` to enable graph-enhanced analysis.
+
+### Graph Availability
+
+Before starting, check if `.harness/graph/graph.json` exists.
+
+**If graph exists:** Check staleness — compare `.harness/graph/metadata.json`
+scanTimestamp against `git log -1 --format=%ct` (latest commit timestamp).
+If graph is more than 10 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **Medium**)
+
+**If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.
+
+**If no graph exists:** Output "Running without graph (run `harness scan` to
+enable full analysis)" and use fallback strategies for all subsequent steps.
+
+### Pipeline Context (when orchestrated)
+
+When invoked by `harness-docs-pipeline`, check for a `pipeline` field in `.harness/handoff.json`:
+
+- If `pipeline` field exists: read `DocPipelineContext` from it
+  - If `pipeline.bootstrapped === true`, this is a bootstrap invocation — generate full AGENTS.md without confirmation prompt
+  - Write any generated documentation back as `DocFix[]` to `pipeline.fillsApplied`
+  - This enables the orchestrator to track what was generated and verify it
+- If `pipeline` field does not exist: behave exactly as today (standalone mode)
+
+No changes to the skill's interface or output format — the pipeline field is purely additive.
 
 ## Process
 
@@ -40,6 +67,20 @@ If the graph exists but code has changed since the last scan, re-run `harness sc
    get_relationships(nodeId=<module>, direction="outbound", depth=1)
    ```
 
+#### Fallback (without graph)
+
+When no graph is available, use directory structure and file analysis:
+
+1. **Module hierarchy from directories**: Use the directory structure as the module hierarchy — each directory represents a module. Glob for all source files to build the tree.
+2. **Entry points**: Check `package.json` for `main` and `exports` fields. Glob for `src/index.*` and `index.*` patterns. These are the entry points.
+3. **Source file inventory**: Glob for all source files (`**/*.ts`, `**/*.tsx`, `**/*.js`, `**/*.jsx`, etc.).
+4. **Documentation inventory**: Glob for all doc files (`**/*.md`, `docs/**/*`).
+5. **Undocumented module detection**: Diff the source directory set against the doc directory set. Source directories with no corresponding docs (no README.md, no matching doc file) are undocumented.
+6. **Existing knowledge map**: Read existing AGENTS.md if present for current knowledge map state.
+7. **Dependency flow (approximate)**: Parse import statements in each module's files to determine which modules depend on which others.
+
+> Fallback completeness: ~50% — no semantic grouping; modules grouped by directory only; no cross-cutting concern detection.
+
 ### Phase 2: GENERATE — Build Knowledge Map
 
 Generate markdown sections following AGENTS.md conventions:
@@ -109,7 +150,7 @@ This ensures subsequent graph queries (impact analysis, drift detection) include
 
 ## Harness Integration
 
-- **`harness scan`** — Must run before this skill to ensure graph is current.
+- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses directory structure fallbacks.
 - **`harness validate`** — Run after acting on findings to verify project health.
 - **Graph tools** — This skill uses `query_graph`, `get_relationships`, and `check_docs` MCP tools.
 
@@ -119,7 +160,7 @@ This ensures subsequent graph queries (impact analysis, drift detection) include
 - Coverage gaps identified (undocumented modules, missing descriptions, stale references)
 - Output written to AGENTS.md (or specified path) in proper markdown format
 - Report follows the structured output format
-- All findings are backed by graph query evidence, not heuristics
+- All findings are backed by graph query evidence (with graph) or directory/file analysis (without graph)
 
 ## Examples
 
@@ -145,7 +186,7 @@ Output:
 
 ## Gates
 
-- **No generation without graph.** If no graph exists, stop and instruct to run `harness scan`.
+- **Graph preferred, fallback available.** If no graph exists, use directory structure and file analysis to build the knowledge map. Do not stop — produce the best map possible.
 - **Never overwrite without confirmation.** If AGENTS.md exists, show the diff and ask before replacing.
 
 ## Escalation

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

@@ -0,0 +1,288 @@
+# Harness Onboarding
+
+> Navigate an existing harness-managed project and generate a structured orientation for new team members. Map the codebase, understand constraints, identify the adoption level, and produce a summary that gets someone productive fast.
+
+## When to Use
+
+- A new developer (human or agent) is joining a harness-managed project for the first time
+- Resuming work on a project after extended time away and needing to re-orient
+- When `on_project_init` triggers fire in an existing project (agent starting a new session)
+- When someone asks "how does this project work?" or "where do I start?"
+- NOT when initializing a new project (use initialize-harness-project)
+- NOT when the project has no harness configuration (onboard to harness first with initialize-harness-project)
+- NOT when deep-diving into a specific module (use standard code exploration — onboarding gives the big picture)
+
+## Process
+
+### Phase 1: READ — Load Project Configuration
+
+1. **Read `AGENTS.md`.** This is the primary source of truth for agent behavior in the project. Note:
+   - Project description and purpose
+   - Architecture overview
+   - Conventions and coding standards
+   - Constraints and forbidden patterns
+   - Any special instructions or warnings
+
+2. **Read `harness.yaml`.** Extract:
+   - Project name and stack
+   - Adoption level (basic, intermediate, advanced)
+   - Layer definitions and their directory mappings
+   - Dependency constraints between layers
+   - Registered skills and their triggers
+   - Persona configuration (if present)
+
+3. **Read `.harness/learnings.md`** if it exists. This contains hard-won insights from previous sessions — decisions made, gotchas discovered, patterns that worked or failed. Summarize the most recent and most important entries.
+
+4. **Read `.harness/state.json`** if it exists. This reveals what was happening in the last session — current phase, active task, any blockers that were recorded.
+
+### Phase 2: MAP — Understand the Codebase Structure
+
+1. **Map the technology stack.** Identify from package files, configuration, and code:
+   - Language(s) and version(s)
+   - Framework(s) and major libraries
+   - Test framework and test runner command
+   - Build tool and build command
+   - Package manager
+   - Database or data stores (if applicable)
+
+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)
+   - Shared utilities or common modules
+   - Configuration files and their purposes
+
+3. **Map the conventions.** Look for patterns in existing code:
+   - File naming conventions (kebab-case, camelCase, PascalCase)
+   - Test file location and naming (co-located, separate directory, `.test.ts` vs `.spec.ts`)
+   - Import style (relative, aliases, barrel files)
+   - Error handling patterns
+   - Logging patterns
+   - 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)
+   - 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
+
+5. **Map the design system** (when present). Look for:
+   - `design-system/tokens.json` — W3C DTCG design tokens (colors, typography, spacing)
+   - `design-system/DESIGN.md` — Aesthetic intent, anti-patterns, platform notes
+   - `harness.config.json` `design` block — strictness level, enabled platforms, token path
+   - Active design skills — check if `harness-design-system`, `harness-accessibility`, `harness-design`, `harness-design-web`, `harness-design-mobile` are available
+   - Design constraint violations — run a quick `harness-accessibility` scan to surface any existing issues
+   - Token coverage — how many components reference tokens vs. hardcoded values
+
+   If no design system exists, note this as a potential improvement area.
+
+6. **Map the concerns.** Identify areas that need attention:
+   - Are there TODOs or FIXMEs in the code?
+   - Does `harness validate` pass cleanly, or are there warnings?
+   - Are there known blockers in `.harness/state.json`?
+   - Is documentation up to date with the code?
+   - Are there tests? What is the approximate coverage?
+
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate codebase mapping:
+
+- `query_graph` — map architecture automatically from module and layer nodes, replacing manual directory walking
+- `search_similar` — find entry points and key files by querying for high-connectivity nodes
+- `get_relationships` — show layer dependencies and module structure as a traversable graph
+
+Graph queries produce a complete architecture map in seconds, including transitive relationships that directory inspection misses. Fall back to file-based commands if no graph is available.
+
+### 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
+   - Intermediate: Layers defined, dependency constraints enforced, at least one custom skill
+   - Advanced: Personas, state management, learnings, CI integration
+
+2. **Assess harness health.** Run `harness validate` and note any issues. A project that declares intermediate but fails validation is not truly intermediate.
+
+3. **Identify available skills.** List the skills configured for the project. Note which are custom (project-specific) vs. standard (harness-provided). Each skill represents a workflow the team has formalized.
+
+### Phase 4: SUMMARIZE — Generate Orientation Output
+
+1. **Produce a structured orientation summary.** This is the deliverable. Format:
+
+```markdown
+# Project Orientation: <project-name>
+
+## Overview
+
+<1-2 sentence project description from AGENTS.md>
+
+## Stack
+
+- Language: <language> <version>
+- Framework: <framework>
+- Tests: <test framework> (`<test command>`)
+- Build: <build tool> (`<build command>`)
+- Package manager: <pm>
+
+## Architecture
+
+<Brief description of top-level organization>
+
+### Layers
+
+| Layer   | Directories | Can Import From   |
+| ------- | ----------- | ----------------- |
+| <layer> | <dirs>      | <allowed imports> |
+
+### Key Components
+
+- <component>: <purpose> (<location>)
+
+## Constraints
+
+- <constraint 1>
+- <constraint 2>
+
+## Conventions
+
+- <convention 1>
+- <convention 2>
+
+## Design System
+
+- **Tokens:** [present/absent] ([token count] tokens in [group count] groups)
+- **Aesthetic Intent:** [present/absent] (style: [style], strictness: [level])
+- **Platforms:** [web, mobile, or none configured]
+- **Accessibility:** [baseline scan result — e.g., "3 warnings, 0 errors"]
+- **Design Skills:** [list of available design skills]
+
+## Harness Status
+
+- Adoption level: <level>
+- Validation: <pass/fail with summary>
+- Available skills: <list>
+- State: <current phase/task if applicable>
+
+## Recent Learnings
+
+- <most relevant learnings from .harness/learnings.md>
+
+## Getting Started
+
+1. <first thing to do>
+2. <second thing to do>
+3. <third thing to do>
+```
+
+2. **Tailor "Getting Started" to the audience.** For a new developer: how to set up the dev environment and run tests. For an agent resuming work: what the current task is and what to do next. For a reviewer: where to look and what constraints to check.
+
+3. **Present the summary to the human.** Do not write it to a file unless asked. The orientation is a conversation artifact, not a project artifact.
+
+## Harness Integration
+
+- **`harness validate`** — Run during onboarding to assess project health and identify any configuration issues.
+- **`harness skill list`** — List available skills to understand what workflows the team has formalized.
+- **`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/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`)
+- 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`
+- 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
+- `harness validate` was run and results are reported
+
+## Examples
+
+### Example: Onboarding to an Intermediate TypeScript Project
+
+**READ:**
+
+```
+Read AGENTS.md:
+  - Project: Widget API — REST service for widget lifecycle management
+  - Stack: TypeScript, Express, Vitest, PostgreSQL
+  - Conventions: zod validation, repository pattern, kebab-case files
+
+Read harness.yaml:
+  - Level: intermediate
+  - Layers: presentation (src/routes/), business (src/services/), data (src/repositories/)
+  - Constraints: presentation → business OK, business → data OK, data → presentation FORBIDDEN
+
+Read .harness/learnings.md:
+  - "Date comparison needs UTC normalization — use Date.now()"
+  - "The notifications table has a unique constraint on (userId, type) — upsert, don't insert"
+
+Read .harness/state.json:
+  - Position: Phase execute, Task 4 of 6
+  - Blocker: none
+```
+
+**MAP:**
+
+```
+Stack: TypeScript 5.3, Express 4, Vitest 1.2, pg (node-postgres)
+Architecture: Single package, 3 layers, entry point src/index.ts
+Conventions: kebab-case files, co-located tests (.test.ts), barrel exports
+Constraints: 3 layers with strict downward-only imports
+Concerns: harness validate passes, 47 tests all passing
+```
+
+**ORIENT:**
+
+```
+Adoption level: intermediate (confirmed — layers defined, constraints enforced)
+Skills: harness-tdd, harness-execution, harness-code-review
+State: Mid-execution on a 6-task notification feature plan
+```
+
+**SUMMARIZE:**
+
+```
+Produce orientation with all sections. Getting Started for this context:
+1. Read the plan at docs/plans/2026-03-14-notifications-plan.md
+2. Resume execution at Task 4 (state shows Tasks 1-3 complete)
+3. Note the UTC normalization gotcha from learnings before working with dates
+```
+
+### Example: Onboarding to a Basic Project
+
+**READ:**
+
+```
+Read AGENTS.md — exists, minimal content
+Read harness.yaml — level: basic, no layers defined
+No .harness/learnings.md
+No .harness/state.json
+```
+
+**MAP and SUMMARIZE:**
+
+```
+Adoption level: basic (confirmed — no layers or constraints)
+Getting Started:
+1. Run npm install && npm test to verify the project builds and tests pass
+2. Read AGENTS.md for project context and conventions
+3. Consider migrating to intermediate level to add layer boundaries
+   (use initialize-harness-project to upgrade)
+```
+
+## Adoption Maturity
+
+A mental model for where a team sits on the harness adoption curve. Not prescriptive — just orientation.
+
+| Level | Name               | Description                                                                                                                                                          |
+| ----- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 1     | **Manual**         | Write `CLAUDE.md` by hand, run commands manually. Harness is a reference, not a tool.                                                                                |
+| 2     | **Repeatable**     | Skills installed, agent follows conventions consistently. Workflows are codified but enforcement is human-driven.                                                    |
+| 3     | **Automated**      | Mechanical gates in CI. `harness validate` runs on PRs. Failures auto-log to `.harness/failures.md`. The system catches mistakes before humans do.                   |
+| 4     | **Self-improving** | Learnings accumulate in `.harness/learnings.md`. Agents reference past failures before planning. Institutional knowledge compounds across sessions and team members. |
+
+Most teams start at Level 1 and move up as they see the value. There is no pressure to reach Level 4 — each level delivers real benefits on its own.

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

@@ -0,0 +1,30 @@
+name: harness-onboarding
+version: "1.0.0"
+description: Onboard a new developer to a harness-managed project
+cognitive_mode: advisory-guide
+triggers:
+  - manual
+  - on_project_init
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+cli:
+  command: harness skill run harness-onboarding
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-onboarding
+    path: string
+type: flexible
+state:
+  persistent: false
+  files: []
+depends_on: []