@harness-engineering/cli 1.0.1 → 1.1.0

package/dist/agents/agents/skills/claude-code/harness-onboarding/SKILL.md

@@ -0,0 +1,260 @@
+# 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 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?
+
+### 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>
+
+## 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/agents/skills/claude-code/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: []

package/dist/agents/agents/skills/claude-code/harness-parallel-agents/SKILL.md

@@ -0,0 +1,162 @@
+# Harness Parallel Agents
+
+> Dispatch independent tasks to concurrent agents, integrate results, and verify no conflicts. Only for truly independent problems.
+
+## When to Use
+
+- When 3 or more tasks are truly independent (no shared state, no shared files, different subsystems)
+- When tasks involve investigation or implementation in separate parts of the codebase
+- When parallel execution would meaningfully reduce wall-clock time
+- When a plan has tasks explicitly marked as parallelizable
+- NOT when failures across tasks might be related (investigate serially to find the common cause)
+- NOT when tasks need full system understanding to complete correctly
+- NOT when agents would modify the same files or shared state
+- NOT when there are fewer than 3 independent tasks (overhead of coordination outweighs parallelism)
+- NOT when the tasks are sequential by nature (each depends on the previous)
+
+## Process
+
+### Step 1: Identify Independent Problem Domains
+
+Before dispatching anything in parallel, rigorously verify independence:
+
+1. **List the candidate tasks.** Pull from the plan, or identify from the current work.
+
+2. **Check file overlap.** For each pair of tasks, compare the files they will read and write. Any overlap in WRITE targets means they are NOT independent. Overlap in READ targets is acceptable only if neither task writes to those files.
+
+3. **Check state overlap.** Do any tasks share database tables, configuration files, environment variables, or in-memory state? If yes, they are NOT independent.
+
+4. **Check import graph overlap.** If Task A modifies module X and Task B imports module X, they are NOT independent — Task B's tests may be affected by Task A's changes.
+
+5. **When in doubt, run serially.** The cost of a false parallel dispatch (merge conflicts, subtle bugs, wasted work) far exceeds the cost of running serially.
+
+### Step 2: Create Focused Agent Tasks
+
+For each independent task, write a focused agent brief:
+
+1. **Scope.** Exactly what files and directories this agent may touch. Be explicit about boundaries — the agent should not explore outside its scope.
+
+2. **Goal.** One sentence: what is the observable outcome when this agent is done?
+
+3. **Constraints.** What the agent must NOT do:
+   - Do not modify files outside your scope
+   - Do not install new dependencies without approval
+   - Do not change shared configuration
+   - Run `harness validate` before your final commit
+
+4. **Expected output.** What the agent should produce:
+   - Commit(s) on the current branch
+   - Test results (all pass)
+   - Summary of what was done and any surprises
+
+5. **Context.** Give each agent the minimum context it needs. Include relevant file paths, type definitions it will use, and API contracts it must respect. Do not dump the entire codebase context — focused agents work better with focused context.
+
+### Step 3: Dispatch Concurrently
+
+1. **Launch agents in parallel.** Use subagent dispatch (TaskCreate or platform-specific parallel execution).
+
+2. **Do not intervene while agents are running** unless one reports a blocker. Let them complete independently.
+
+3. **Collect results.** Wait for all agents to finish. Gather their outputs: commits, test results, and summaries.
+
+### Step 4: Integrate Results
+
+1. **Check for conflicts.** Even with verified independence, unexpected conflicts can occur:
+   - Git merge conflicts in any file
+   - Two agents added the same import or export
+   - Test names collide
+   - Shared configuration was modified despite constraints
+
+2. **If conflicts exist, resolve them manually.** Do not ask an agent to fix conflicts it does not have full context for. You have the full picture; the agents did not.
+
+3. **Run the FULL test suite.** Not just each agent's tests — the complete project test suite. Parallel changes can cause integration failures that individual test runs miss.
+
+4. **Run `harness validate`.** Verify project-wide health after integration.
+
+5. **If integration fails,** identify which agent's changes caused the failure. Revert that agent's commits, fix the issue serially, and re-integrate.
+
+### Step 5: Verify and Commit
+
+1. **Verify all observable truths** from the plan are satisfied after integration.
+
+2. **If all tests pass and harness validates,** the parallel execution is complete.
+
+3. **Write a summary** of what was parallelized, what each agent produced, and any integration issues that were resolved.
+
+## Harness Integration
+
+- **`harness validate`** — Each agent runs this before its final commit. Run again after integration.
+- **`harness check-deps`** — Run after integration to verify no cross-boundary violations were introduced by the combined changes.
+- **Agent dispatch** — Use platform-specific parallel execution (e.g., Claude Code subagents via TaskCreate, or separate terminal sessions).
+- **Test runner** — Full suite must run after integration, not just individual agent tests.
+
+## Success Criteria
+
+- Independence was verified before dispatch (file overlap, state overlap, import graph)
+- Each agent had a focused brief with explicit scope, goal, constraints, and expected output
+- All agents completed successfully (or blockers were reported)
+- Integration produced no merge conflicts (or conflicts were resolved)
+- Full test suite passes after integration
+- `harness validate` passes after integration
+- No agent modified files outside its declared scope
+
+## Examples
+
+### Example: Parallel Implementation of Three Independent Services
+
+**Context:** Plan has Tasks 4, 5, and 6 which implement UserService, ProductService, and NotificationService. Each service is in its own directory, has its own types, and has no cross-service dependencies.
+
+**Step 1: Verify independence**
+
+```
+Task 4 (UserService):      writes src/services/user/*, reads src/types/user.ts
+Task 5 (ProductService):   writes src/services/product/*, reads src/types/product.ts
+Task 6 (NotificationService): writes src/services/notification/*, reads src/types/notification.ts
+
+File overlap: NONE (different directories, different type files)
+State overlap: NONE (different DB tables, no shared config)
+Import graph: NONE (no cross-service imports)
+Verdict: INDEPENDENT — safe to parallelize
+```
+
+**Step 2: Create agent briefs**
+
+```
+Agent A — UserService:
+  Scope: src/services/user/, src/services/user.test.ts
+  Goal: UserService with CRUD operations, all tests passing
+  Constraints: Do not modify files outside src/services/user/. Run harness validate.
+  Context: User type definition in src/types/user.ts, DB helper in src/utils/db.ts
+
+Agent B — ProductService:
+  Scope: src/services/product/, src/services/product.test.ts
+  Goal: ProductService with CRUD operations, all tests passing
+  Constraints: Do not modify files outside src/services/product/. Run harness validate.
+  Context: Product type definition in src/types/product.ts, DB helper in src/utils/db.ts
+
+Agent C — NotificationService:
+  Scope: src/services/notification/, src/services/notification.test.ts
+  Goal: NotificationService with create and list, all tests passing
+  Constraints: Do not modify files outside src/services/notification/. Run harness validate.
+  Context: Notification type in src/types/notification.ts, email utility in src/utils/email.ts
+```
+
+**Step 3-4: Dispatch, integrate**
+
+```
+All 3 agents complete. No merge conflicts.
+Run full test suite: 34 tests, all pass.
+Run harness validate: passes.
+```
+
+### Example: When NOT to Parallelize
+
+**Situation:** Tasks 7 and 8 both modify `src/api/routes/index.ts` to add new route handlers.
+
+```
+Task 7: writes src/api/routes/users.ts, MODIFIES src/api/routes/index.ts
+Task 8: writes src/api/routes/products.ts, MODIFIES src/api/routes/index.ts
+
+File overlap: BOTH WRITE to src/api/routes/index.ts
+Verdict: NOT INDEPENDENT — run serially
+```

package/dist/agents/agents/skills/claude-code/harness-parallel-agents/skill.yaml

@@ -0,0 +1,33 @@
+name: harness-parallel-agents
+version: "1.0.0"
+description: Coordinate multiple agents working in parallel on a harness project
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+  - on_new_feature
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-parallel-agents
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-parallel-agents
+    path: string
+type: flexible
+state:
+  persistent: false
+  files: []
+depends_on: []