@harness-engineering/cli 1.1.0 → 1.2.0

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

@@ -1,162 +0,0 @@
-# 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

@@ -1,33 +0,0 @@
-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: []

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

@@ -1,326 +0,0 @@
-# Harness Planning
-
-> Implementation planning with atomic tasks, goal-backward must-haves, and complete executable instructions. Every task fits in one context window.
-
-## When to Use
-
-- After a design spec is approved (output of harness-brainstorming) and implementation needs to be planned
-- When starting a new feature or project that needs structured task decomposition
-- When `on_new_feature` or `on_project_init` triggers fire and the work is non-trivial
-- When resuming a stalled project that needs a fresh plan
-- NOT when the task is small enough to implement directly (under 15 minutes, single file — just do it)
-- NOT when you need to explore the problem space first (use harness-brainstorming)
-- NOT when a plan already exists and needs execution (use harness-execution)
-
-## Process
-
-### Iron Law
-
-**Every task in the plan must be completable in one context window (2-5 minutes). If a task is larger, split it.**
-
-A plan with vague tasks like "add validation" or "implement the service" is not a plan — it is a wish list. Every task must contain exact file paths, exact commands, and complete code snippets.
-
----
-
-### Phase 1: SCOPE — Derive Must-Haves from Goals
-
-Work backward from the goal. Do not start with "what should we build?" Start with "what must be true when we are done?"
-
-1. **State the goal.** One sentence. What does the system do when this plan is complete?
-
-2. **Derive observable truths.** What can be observed (by running a command, opening a browser, reading a file) that proves the goal is met? These are your acceptance criteria. Be specific:
-   - BAD: "The API handles errors"
-   - GOOD: "GET /api/users/nonexistent returns 404 with `{ error: 'User not found' }` body"
-
-3. **Derive required artifacts.** For each observable truth, what files must exist? What functions must be implemented? What tests must pass? List exact file paths.
-
-4. **Identify key links.** How do the artifacts connect? What imports what? What calls what? What data flows where? Draw the dependency graph mentally.
-
-5. **Apply YAGNI.** For every artifact, ask: "Is this required for an observable truth?" If not, cut it.
-
-#### EARS Requirement Patterns
-
-When writing observable truths and acceptance criteria, use EARS (Easy Approach to Requirements Syntax) sentence patterns. These patterns eliminate ambiguity by forcing a consistent grammatical structure.
-
-| Pattern          | Template                                                 | Use When                                          |
-| ---------------- | -------------------------------------------------------- | ------------------------------------------------- |
-| **Ubiquitous**   | The system shall [behavior].                             | Behavior that always applies, unconditionally     |
-| **Event-driven** | When [trigger], the system shall [response].             | Behavior triggered by a specific event            |
-| **State-driven** | While [state], the system shall [behavior].              | Behavior that applies only during a certain state |
-| **Optional**     | Where [feature is enabled], the system shall [behavior]. | Behavior gated by a configuration or feature flag |
-| **Unwanted**     | If [condition], then the system shall not [behavior].    | Explicitly preventing undesirable behavior        |
-
-**Worked Examples:**
-
-1. **Ubiquitous:** "The system shall return JSON responses with `Content-Type: application/json` header."
-2. **Event-driven:** "When a user submits an invalid form, the system shall display field-level error messages within 200ms."
-3. **State-driven:** "While the database connection is unavailable, the system shall serve cached responses and log reconnection attempts."
-4. **Optional:** "Where rate limiting is enabled, the system shall reject requests exceeding 100/minute per API key with HTTP 429."
-5. **Unwanted:** "If the request body exceeds 10MB, then the system shall not attempt to parse it — return HTTP 413 immediately."
-
-**When to use EARS:** Apply these patterns when writing observable truths in Phase 1. Not every criterion needs an EARS pattern — use them when the requirement is behavioral (not structural). File existence checks ("src/types/user.ts exists with User interface") do not need EARS framing.
-
----
-
-### Phase 2: DECOMPOSE — Map File Structure and Create Tasks
-
-1. **Map the file structure first.** Before writing any tasks, list every file that will be created or modified. This is where decomposition decisions are locked. Example:
-
-   ```
-   CREATE src/services/notification-service.ts
-   CREATE src/services/notification-service.test.ts
-   MODIFY src/services/index.ts (add export)
-   CREATE src/types/notification.ts
-   MODIFY src/api/routes/users.ts (add notification trigger)
-   ```
-
-2. **Decompose into atomic tasks.** Each task must:
-   - Be completable in 2-5 minutes
-   - Fit in a single context window
-   - Have a clear, testable outcome
-   - Follow TDD: write test, fail, implement, pass, commit
-   - Produce one atomic commit
-
-3. **Write complete instructions for each task.** Not summaries — complete executable instructions:
-   - **Exact file paths** to create or modify
-   - **Exact code** to write (not "add validation logic" — write the actual validation code)
-   - **Exact test commands** to run (e.g., `npx vitest run src/services/notification-service.test.ts`)
-   - **Exact commit message** to use
-   - **`harness validate`** as the final step
-
-4. **Include checkpoints.** Mark tasks that require human verification, decisions, or actions:
-   - `[checkpoint:human-verify]` — Pause, show result, wait for confirmation
-   - `[checkpoint:decision]` — Pause, present options, wait for choice
-   - `[checkpoint:human-action]` — Pause, instruct human on what they need to do
-
----
-
-### Phase 3: SEQUENCE — Order Tasks and Identify Dependencies
-
-1. **Order by dependency.** Types before implementations. Implementations before integrations. Tests alongside their implementations (same task, TDD style).
-
-2. **Identify parallel opportunities.** Tasks that touch different subsystems with no shared state can be marked as parallelizable (for harness-parallel-agents).
-
-3. **Number tasks sequentially.** Use `Task 1`, `Task 2`, etc. Dependencies reference task numbers: "Depends on: Task 3."
-
-4. **Estimate total time.** Each task is 2-5 minutes. Sum them. If the total exceeds the available time, identify a milestone boundary where the plan can be paused with a working system.
-
----
-
-### Phase 4: VALIDATE — Review and Finalize the Plan
-
-1. **Verify completeness.** Every observable truth from Phase 1 must be achievable by completing the tasks. Trace each truth to the specific task(s) that deliver it.
-
-2. **Verify task sizing.** Read each task. Could an agent complete it in one context window without needing to explore or make decisions? If not, split it.
-
-3. **Verify TDD compliance.** Every task that produces code must include a test step. No task should say "write tests later."
-
-4. **Run `harness validate`** to verify project health before writing the plan.
-
-5. **Check failures log.** Read `.harness/failures.md` before finalizing. If planned approaches match known failures, flag them with warnings.
-
-6. **Write the plan to `docs/plans/`.** Use naming convention: `YYYY-MM-DD-<feature-name>-plan.md`. If the directory does not exist, create it.
-
-7. **Write handoff.** Save `.harness/handoff.json` with the following structure:
-
-   ```json
-   {
-     "fromSkill": "harness-planning",
-     "phase": "VALIDATE",
-     "summary": "<one-sentence description of what was planned>",
-     "completed": [],
-     "pending": ["<task 1>", "<task 2>", "..."],
-     "concerns": ["<any concerns or risks identified>"],
-     "decisions": ["<key decisions made during planning>"],
-     "contextKeywords": ["<domain-relevant keywords>"]
-   }
-   ```
-
-8. **Present the plan to the human for review.** Walk through the task list, the estimated timeline, and any checkpoints that require human input.
-
----
-
-### Plan Document Structure
-
-````markdown
-# Plan: <Feature Name>
-
-**Date:** YYYY-MM-DD
-**Spec:** docs/specs/<spec-file>.md (if applicable)
-**Estimated tasks:** N
-**Estimated time:** N minutes
-
-## Goal
-
-One sentence.
-
-## Observable Truths (Acceptance Criteria)
-
-1. [observable truth]
-2. [observable truth]
-
-## File Map
-
-- CREATE path/to/file.ts
-- MODIFY path/to/other-file.ts
-
-## Tasks
-
-### Task 1: <descriptive name>
-
-**Depends on:** none
-**Files:** path/to/file.ts, path/to/file.test.ts
-
-1. Create test file `path/to/file.test.ts`:
-   ```typescript
-   // exact test code
-   ```
-````
-
-2. Run test: `npx vitest run path/to/file.test.ts`
-3. Observe failure: [expected failure message]
-4. Create implementation `path/to/file.ts`:
-   ```typescript
-   // exact implementation code
-   ```
-5. Run test: `npx vitest run path/to/file.test.ts`
-6. Observe: all tests pass
-7. Run: `harness validate`
-8. Commit: `feat(scope): descriptive message`
-
-### Task 2: <descriptive name>
-
-[checkpoint:human-verify]
-...
-
-````
-
-## Harness Integration
-
-- **`harness validate`** — Run during Phase 4 (before writing the plan) and included as a step in every task.
-- **`harness check-deps`** — Referenced in tasks that add imports or create new modules. Ensures dependency boundaries are respected.
-- **Plan location** — Plans go to `docs/plans/`. Follow the naming convention: `YYYY-MM-DD-<feature-name>-plan.md`.
-- **Handoff to harness-execution** — Once the plan is approved, invoke harness-execution to begin task-by-task implementation.
-- **Task commands** — Every task includes exact harness CLI commands to run (e.g., `harness validate`, `harness check-deps`).
-
-## Change Specifications
-
-When planning changes to existing functionality (not greenfield), express requirements as deltas from the current documented behavior. Use these markers:
-
-- **[ADDED]** — New behavior that does not exist today
-- **[MODIFIED]** — Existing behavior that changes
-- **[REMOVED]** — Existing behavior that goes away
-
-**Example:**
-```markdown
-## Changes to User Authentication
-
-- [ADDED] Support OAuth2 refresh tokens with 7-day expiry
-- [MODIFIED] Login endpoint returns `refreshToken` field alongside existing `accessToken`
-- [MODIFIED] Token validation middleware accepts both JWT and OAuth2 tokens
-- [REMOVED] Legacy API key authentication (deprecated in v2.1)
-````
-
-This is not mandatory for greenfield features. Only apply when modifying existing documented behavior.
-
-When `docs/specs/` exists in the project, produce `docs/changes/<feature>/delta.md` alongside the task plan. This keeps the change intent separate from the full spec and makes review easier.
-
-## Success Criteria
-
-- A plan document exists in `docs/plans/` with all required sections
-- Every task is completable in 2-5 minutes (one context window)
-- Every task includes exact file paths, exact code, and exact commands
-- Every code-producing task follows TDD: test first, fail, implement, pass
-- Observable truths trace to specific tasks that deliver them
-- File map lists every file to be created or modified
-- Checkpoints are marked where human input is required
-- `harness validate` passes before the plan is written
-- `harness validate` is included as a step in every task
-- The human has reviewed and approved the plan
-
-## Examples
-
-### Example: Planning a User Notification Feature
-
-**Goal:** Users receive email and in-app notifications when their account is modified.
-
-**Observable Truths:**
-
-1. `POST /api/users/:id` with changed fields triggers a notification record in the database
-2. `GET /api/notifications?userId=:id` returns the notification with type, message, and timestamp
-3. Notification email is sent via the existing email utility (verified by mock in test)
-4. `npx vitest run src/services/notification-service.test.ts` passes with 8+ tests
-5. `harness validate` passes
-
-**File Map:**
-
-```
-CREATE src/types/notification.ts
-CREATE src/services/notification-service.ts
-CREATE src/services/notification-service.test.ts
-MODIFY src/services/index.ts
-MODIFY src/api/routes/users.ts
-MODIFY src/api/routes/users.test.ts
-```
-
-**Task 1: Define notification types**
-
-```
-Files: src/types/notification.ts
-1. Create src/types/notification.ts:
-   export interface Notification {
-     id: string;
-     userId: string;
-     type: 'account_modified';
-     message: string;
-     read: boolean;
-     createdAt: Date;
-     expiresAt: Date;
-   }
-2. Run: harness validate
-3. Commit: "feat(notifications): define Notification type"
-```
-
-**Task 2: Create notification service with create method (TDD)**
-
-```
-Files: src/services/notification-service.ts, src/services/notification-service.test.ts
-1. Write test: create notification returns Notification object with correct fields
-2. Run test — observe: NotificationService is not defined
-3. Implement: NotificationService.create() stores and returns notification
-4. Run test — observe: pass
-5. Run: harness validate
-6. Commit: "feat(notifications): add NotificationService.create"
-```
-
-**Task 3: Add list and expiry methods (TDD)**
-
-```
-[checkpoint:human-verify] — verify Task 2 output before continuing
-Files: src/services/notification-service.ts, src/services/notification-service.test.ts
-1. Write tests: list by userId, filter expired
-2. Run tests — observe failures
-3. Implement: list() and isExpired() methods
-4. Run tests — observe: pass
-5. Run: harness validate, harness check-deps
-6. Commit: "feat(notifications): add list and expiry to NotificationService"
-```
-
-## Gates
-
-These are hard stops. Violating any gate means the process has broken down.
-
-- **No vague tasks.** "Implement the service" is not a task. Every task must have exact file paths, exact code, and exact commands. If you cannot write the code in the plan, you do not understand the task well enough to plan it.
-- **No tasks larger than one context window.** If a task requires exploring the codebase, making design decisions, or touching more than 3 files, it is too large. Split it.
-- **No skipping TDD in tasks.** Every task that produces code must start with writing a test. "Add tests later" is not allowed in a plan. If tests cannot be written first, the design is unclear — go back to brainstorming.
-- **No plan without observable truths.** The plan must start with goal-backward acceptance criteria. If you cannot state what is observable when the plan is complete, you do not understand the goal.
-- **No implementation during planning.** The plan is a document, not code. Do not "just start Task 1 while we are here." Write the plan, get approval, then use harness-execution.
-- **File map must be complete.** Every file that will be created or modified must appear in the file map. Discovering new files during execution means the plan was incomplete.
-
-## Escalation
-
-- **When you cannot write exact code for a task:** The design is underspecified. Go back to the spec (or brainstorm if no spec exists). Do not write a vague task as a placeholder.
-- **When task count exceeds 20:** The project may be too large for a single plan. Consider splitting into multiple plans with clear milestone boundaries.
-- **When dependencies form a cycle:** The decomposition is wrong. Re-examine the file map and find a way to break the cycle (usually by extracting a shared type or interface).
-- **When you discover the spec is missing information during planning:** Do not fill in the gaps yourself. Escalate: "The spec does not define behavior for [scenario]. This blocks Task N. We need to update the spec before continuing the plan."
-- **When estimated time exceeds available time:** Identify a milestone boundary where the plan can be paused with a working system. Propose delivering the plan in phases, each phase producing a usable increment.

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

@@ -1,47 +0,0 @@
-name: harness-planning
-version: "1.0.0"
-description: Structured project planning with harness constraints and validation
-cognitive_mode: constructive-architect
-triggers:
-  - manual
-  - on_new_feature
-  - on_project_init
-platforms:
-  - claude-code
-  - gemini-cli
-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - Glob
-cli:
-  command: harness skill run harness-planning
-  args:
-    - name: path
-      description: Project root path
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: harness-planning
-    path: string
-type: rigid
-phases:
-  - name: scope
-    description: Define goals and constraints
-    required: true
-  - name: decompose
-    description: Break work into tasks
-    required: true
-  - name: sequence
-    description: Order tasks and identify dependencies
-    required: true
-  - name: validate
-    description: Run harness checks on the plan
-    required: true
-state:
-  persistent: false
-  files: []
-depends_on:
-  - harness-verification

package/dist/agents/agents/skills/claude-code/harness-pre-commit-review/skill.yaml

@@ -1,33 +0,0 @@
-name: harness-pre-commit-review
-version: "1.0.0"
-description: Lightweight pre-commit quality gate combining mechanical checks and AI review
-triggers: [manual, on_commit]
-platforms: [claude-code, gemini-cli]
-tools: [Bash, Read, Glob, Grep]
-cli:
-  command: harness skill run harness-pre-commit-review
-  args:
-    - name: path
-      description: Project root path
-      required: false
-mcp:
-  tool: run_skill
-  input:
-    skill: harness-pre-commit-review
-    path: string
-type: rigid
-phases:
-  - name: mechanical-checks
-    description: Run deterministic checks (lint, typecheck, tests)
-    required: true
-  - name: classify-changes
-    description: Determine if AI review is needed based on change type
-    required: true
-  - name: ai-review
-    description: Lightweight AI review of staged changes (skipped for docs/config-only)
-    required: false
-state:
-  persistent: false
-  files: []
-depends_on:
-  - harness-code-review