@harness-engineering/cli 1.14.0 → 1.16.0

package/dist/agents/commands/codex/harness/harness-hotspot-detector/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Reserved for Phase B native integration
+name: harness-hotspot-detector
+version: "1.0.0"

package/dist/agents/commands/codex/harness/harness-impact-analysis/SKILL.md

@@ -0,0 +1,187 @@
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# Harness Impact Analysis
+
+> Graph-based impact analysis. Answers: "if I change X, what breaks?"
+
+## When to Use
+
+- Before merging a PR — understand the blast radius of changes
+- When planning a refactoring — know what will be affected
+- When a test fails — trace backwards to find what change caused it
+- When `on_pr` triggers fire
+- NOT for understanding code (use harness-onboarding or harness-code-review)
+- NOT for finding dead code (use cleanup-dead-code)
+
+## Prerequisites
+
+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 2 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **High**)
+
+**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.
+
+## Process
+
+### Phase 1: IDENTIFY — Determine Changed Files
+
+1. **From diff**: If a git diff is available, parse it to extract changed file paths.
+2. **From input**: If file paths are provided directly, use those.
+3. **From git**: If neither, use `git diff --name-only HEAD~1` to get recent changes.
+
+### Phase 2: ANALYZE — Query Graph for Impact
+
+For each changed file:
+
+1. **Direct dependents**: Use `get_impact` MCP tool to find all files that import or call the changed file.
+
+   ```
+   get_impact(filePath="src/services/auth.ts")
+   → tests: [auth.test.ts, integration.test.ts]
+   → docs: [auth-guide.md]
+   → code: [routes/login.ts, middleware/verify.ts, ...]
+   ```
+
+2. **Transitive dependents**: Use `query_graph` with depth 3 to find indirect consumers.
+
+   ```
+   query_graph(rootNodeIds=["file:src/services/auth.ts"], maxDepth=3, includeEdges=["imports", "calls"])
+   ```
+
+3. **Documentation impact**: Use `get_relationships` to find `documents` edges pointing to changed nodes.
+
+4. **Test coverage**: Identify test files connected via `imports` edges. Flag changed files with no test coverage.
+
+5. **Design token impact**: When the graph contains `DesignToken` nodes, use `query_graph` with `USES_TOKEN` edges to find components that consume changed tokens.
+
+   ```
+   query_graph(rootNodeIds=["designtoken:color.primary"], maxDepth=2, includeEdges=["uses_token"])
+   → components: [Button.tsx, Card.tsx, Header.tsx, ...]
+   ```
+
+   If a changed file is `design-system/tokens.json`, identify ALL tokens that changed and trace each to its consuming components. This reveals the full design blast radius of a token change.
+
+6. **Design constraint impact**: When the graph contains `DesignConstraint` nodes, check if changed code introduces new `VIOLATES_DESIGN` edges.
+
+#### Fallback (without graph)
+
+When no graph is available, use static analysis to approximate impact:
+
+1. **Parse imports**: For each changed file, grep all source files for `import.*from.*<changed-file>` and `require.*<changed-file>` patterns to find direct dependents.
+2. **Follow imports 2 levels deep**: For each direct dependent found, repeat the import grep to find second-level dependents. Stop at 2 levels (fallback cannot reliably trace deeper).
+3. **Find test files by naming convention**: For each changed file `foo.ts`, search for:
+   - `foo.test.ts`, `foo.spec.ts` (same directory and `__tests__/` directory)
+   - `*.test.*` and `*.spec.*` files that import the changed file (from step 1)
+4. **Find docs by path matching**: Grep `docs/` directory for references to the changed module name (filename without extension).
+5. **Group results** the same as the graph version: tests, docs, code, other. Note the count of files found.
+
+> Fallback completeness: ~70% — misses transitive deps beyond 2 levels.
+
+### Phase 3: ASSESS — Risk Assessment and Report
+
+1. **Impact score**: Calculate based on:
+   - Number of direct dependents (weight: 3x)
+   - Number of transitive dependents (weight: 1x)
+   - Whether affected code includes entry points (weight: 5x)
+   - Whether tests exist for the changed code (no tests = higher risk)
+   - Whether design tokens are affected (weight: 2x — token changes cascade to all consumers)
+
+2. **Risk tiers**:
+   - **Critical** (score > 50): Changes affect entry points or >20 downstream files
+   - **High** (score 20-50): Changes affect multiple modules or shared utilities
+   - **Medium** (score 5-20): Changes affect a few files within the same module
+   - **Low** (score < 5): Changes are isolated with minimal downstream impact
+
+3. **Output report**:
+
+   ```
+   ## Impact Analysis Report
+
+   ### Changed Files
+   - src/services/auth.ts (modified)
+   - src/types/user.ts (modified)
+
+   ### Impact Summary
+   - Direct dependents: 8 files
+   - Transitive dependents: 23 files
+   - Affected tests: 5 files
+   - Affected docs: 2 files
+   - Risk tier: HIGH
+
+   ### Affected Tests (must run)
+   1. tests/services/auth.test.ts (direct)
+   2. tests/routes/login.test.ts (transitive)
+   3. tests/integration/auth-flow.test.ts (transitive)
+
+   ### Affected Documentation (may need update)
+   1. docs/auth-guide.md → documents src/services/auth.ts
+   2. docs/api-reference.md → documents src/types/user.ts
+
+   ### Downstream Consumers
+   1. src/routes/login.ts — imports auth.ts
+   2. src/middleware/verify.ts — imports auth.ts
+   3. src/routes/signup.ts — imports user.ts (transitive via auth.ts)
+
+   ### Affected Design Tokens (when tokens change)
+   1. color.primary → used by 12 components
+   2. typography.body → used by 8 components
+   ```
+
+## Harness Integration
+
+- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses static analysis fallbacks.
+- **`harness validate`** — Run after acting on findings to verify project health.
+- **Graph tools** — This skill uses `query_graph`, `get_impact`, and `get_relationships` MCP tools.
+
+## Success Criteria
+
+- Impact report generated with a risk tier (Critical / High / Medium / Low)
+- All affected test files listed with direct vs transitive classification
+- All affected documentation files listed with relationship context
+- Report follows the structured output format
+- All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
+
+## Examples
+
+### Example: Analyzing a Change to auth.ts
+
+```
+Input: git diff shows src/services/auth.ts modified
+
+1. IDENTIFY — Extract changed file: src/services/auth.ts
+2. ANALYZE  — get_impact(filePath="src/services/auth.ts")
+              query_graph(rootNodeIds=["file:src/services/auth.ts"], maxDepth=3)
+              Results: 8 direct dependents, 23 transitive, 5 tests, 2 docs
+3. ASSESS   — Impact score: 34 (High tier)
+              - Entry points affected: no
+              - Tests exist: yes (5 files)
+
+Output:
+  Risk tier: HIGH
+  Must-run tests: auth.test.ts, login.test.ts, auth-flow.test.ts
+  Docs to update: auth-guide.md, api-reference.md
+  Downstream consumers: 8 files across 3 modules
+```
+
+## Gates
+
+- **Graph preferred, fallback available.** If no graph exists, use fallback strategies (import parsing, naming conventions, path matching). Do not stop — produce the best analysis possible with available tools.
+- **No risk assessment without data.** Use graph queries when available; use import parsing and naming conventions when not. If neither approach yields data, state what is missing.
+
+## Escalation
+
+- **When graph is stale**: If the graph's last scan timestamp is older than the most recent commit, warn that results may be incomplete and suggest re-scanning.
+- **When impact is critical**: If risk tier is Critical, recommend a thorough code review and full test suite run before merging.
+

package/dist/agents/commands/codex/harness/harness-impact-analysis/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Reserved for Phase B native integration
+name: harness-impact-analysis
+version: "1.0.0"

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

@@ -0,0 +1,170 @@
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# 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/commands/codex/harness/harness-integrity/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Reserved for Phase B native integration
+name: harness-integrity
+version: "1.0.0"

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

@@ -0,0 +1,291 @@
+<!-- Generated by harness generate-slash-commands. Do not edit. -->
+
+# 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/commands/codex/harness/harness-onboarding/agents/openai.yaml

@@ -0,0 +1,3 @@
+# Reserved for Phase B native integration
+name: harness-onboarding
+version: "1.0.0"