Harness Onboarding

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 harness-initialize-project)
• NOT when the project has no harness configuration (onboard to harness first with harness-initialize-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.config.json. 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.

5. Detect the roadmap layout. If docs/roadmap.d/ exists the project uses the sharded roadmap: per-row shards docs/roadmap.d/<slug>.md (plus _meta.md) are canonical and docs/roadmap.md is a generated merge=ours aggregate (do not hand-edit it). New contributors must run the one-time per-clone setup so generated-file merges behave: git config merge.ours.driver true (the .gitattributes merge=ours entry is inert without it — harness validate warns clones that have not run it). Surface this in "Getting Started". If only docs/roadmap.md exists, the project is monolith; if neither, it is file-less or uninitialized. See the adoption guide docs/guides/roadmap-sharding.md.

Phase 2: MAP — Understand the Codebase Structure

Use code_outline to get structural overviews of key modules (functions, classes, exports) without reading full source files. Use code_search to locate patterns, symbols, or conventions across the codebase.

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.config.json 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.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

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.

When deep-diving into specific modules to explain architecture, use code_unfold to expand specific symbols to their full implementation with dependency context.

Phase 3: ORIENT — Identify Adoption Level and Maturity

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

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:

# 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.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.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.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
• harness validate was run and results are reported

Rationalizations to Reject

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.config.json:
  - 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/changes/notifications/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.config.json — 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 harness-initialize-project to upgrade)

Adoption Maturity

A mental model for where a team sits on the harness adoption curve. Not prescriptive — just orientation.

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.