@harness-engineering/cli 1.7.0 → 1.8.1

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

@@ -0,0 +1,171 @@
+# 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.
+
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate independence verification:
+
+- `query_graph` — get the dependency subgraph per candidate task and check for node overlap between tasks
+- `get_impact` — verify tasks do not write to overlapping files or share transitive dependencies
+
+Automated graph-based independence verification replaces manual import grep and catches transitive overlaps that file-level checks miss. Fall back to file-based commands if no graph is available.
+
+### 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/skills/gemini-cli/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: []

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

@@ -45,34 +45,62 @@ Tier 1 violations are non-negotiable blockers. If a Tier 1 violation is detected
 
 ---
 
+### Graph Availability
+
+Hotspot scoring and coupling analysis benefit from the knowledge graph but work without it.
+
+**Staleness sensitivity:** Medium -- auto-refresh if >10 commits stale. Hotspot scoring uses churn data which does not change rapidly.
+
+| Feature                              | With Graph                                                   | Without Graph                                                                                                                    |
+| ------------------------------------ | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
+| Hotspot scoring (churn x complexity) | `GraphComplexityAdapter` computes from graph nodes           | `git log --format="%H" -- <file>` for per-file commit count; complexity from `check-perf --structural` output; multiply manually |
+| Coupling ratio                       | `GraphCouplingAdapter` computes from graph edges             | Parse import statements, count fan-out/fan-in per file                                                                           |
+| Critical path resolution             | Graph inference (high fan-in) + `@perf-critical` annotations | `@perf-critical` annotations only; grep for decorator/comment                                                                    |
+| Transitive dep depth                 | Graph BFS depth                                              | Import chain follow, 2 levels deep                                                                                               |
+
+**Notice when running without graph:** "Running without graph (run `harness scan` to enable hotspot scoring and coupling analysis)"
+
+**Impact on tiers:** Without graph, Tier 1 hotspot detection is degraded. Hotspot scoring falls back to churn-only (no complexity multiplication). This limitation is documented in the performance report output.
+
+---
+
 ### Phase 2: BENCHMARK — Runtime Performance
 
 This phase runs only when `.bench.ts` files exist in the project. If none are found, skip to Phase 3.
 
-1. **Check for benchmark files.** Scan the project for `*.bench.ts` files. If none exist, skip this phase entirely.
+1. **Check baseline lock-in.** Before running benchmarks, verify baselines are kept in sync:
+   - List all `.bench.ts` files changed in this PR: `git diff --name-only | grep '.bench.ts'`
+   - If any `.bench.ts` files are new or modified:
+     - Check if `.harness/perf/baselines.json` is also modified in this PR
+     - If NOT modified: flag as Tier 2 warning: "Benchmark files changed but baselines not updated. Run `harness perf baselines update` and commit the result."
+     - If modified: verify the updated baselines include entries for all changed benchmarks
+   - If no `.bench.ts` files changed: skip this check
+   - This check also runs standalone via `--check-baselines` flag
+
+2. **Check for benchmark files.** Scan the project for `*.bench.ts` files. If none exist, skip this phase entirely.
 
-2. **Verify clean working tree.** Run `git status --porcelain`. If there are uncommitted changes, STOP. Benchmarks on dirty trees produce unreliable results.
+3. **Verify clean working tree.** Run `git status --porcelain`. If there are uncommitted changes, STOP. Benchmarks on dirty trees produce unreliable results.
 
-3. **Run benchmarks.** Execute `harness perf bench` to run all benchmark suites.
+4. **Run benchmarks.** Execute `harness perf bench` to run all benchmark suites.
 
-4. **Load baselines.** Read `.harness/perf/baselines.json` for previous benchmark results. If no baselines exist, treat this as a baseline-capture run.
+5. **Load baselines.** Read `.harness/perf/baselines.json` for previous benchmark results. If no baselines exist, treat this as a baseline-capture run.
 
-5. **Compare results against baselines** using the `RegressionDetector`:
+6. **Compare results against baselines** using the `RegressionDetector`:
    - Calculate percentage change for each benchmark
    - Apply noise margin (default: 3%) before flagging regressions
    - Distinguish between critical-path and non-critical-path benchmarks
 
-6. **Resolve critical paths** via `CriticalPathResolver`:
+7. **Resolve critical paths** via `CriticalPathResolver`:
    - Check `@perf-critical` annotations in source files
    - Check graph fan-in data (functions called by many consumers)
    - Functions in the critical path set have stricter thresholds
 
-7. **Flag regressions by tier:**
+8. **Flag regressions by tier:**
    - **Tier 1:** >5% regression on a critical path benchmark
    - **Tier 2:** >10% regression on a non-critical-path benchmark
    - **Tier 3:** >5% regression on a non-critical-path benchmark (within noise margin consideration)
 
-8. **If this is a baseline-capture run,** report results without regression comparison. Recommend running `harness perf baselines update` to persist.
+9. **If this is a baseline-capture run,** report results without regression comparison. Recommend running `harness perf baselines update` to persist.
 
 ---
 
@@ -138,6 +166,7 @@ This phase runs only when `.bench.ts` files exist in the project. If none are fo
 - **`harness perf bench`** — Run benchmarks only. Requires clean working tree.
 - **`harness perf baselines show`** — View current benchmark baselines.
 - **`harness perf baselines update`** — Persist current benchmark results as new baselines.
+- **`harness perf --check-baselines`** -- Verify baseline file is updated when benchmarks change. Runs the baseline lock-in check standalone.
 - **`harness perf critical-paths`** — View the current critical path set and how it was determined.
 - **`harness validate`** — Run after enforcement to verify overall project health.
 - **`harness graph scan`** — Refresh knowledge graph for accurate hotspot scoring.

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

@@ -21,6 +21,9 @@ cli:
     - name: path
       description: Project root path
       required: false
+    - name: check-baselines
+      description: Verify baseline file is updated when benchmarks change
+      required: false
 mcp:
   tool: run_skill
   input:

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

@@ -60,10 +60,23 @@ If you find yourself writing production code before both the test and the benchm
 
 2. **Run the test** — observe pass. If it fails, fix the implementation until it passes.
 
-3. **Run the benchmark** — capture initial results. This is the first measurement. Note:
-   - If a performance assertion exists in the spec, verify it passes
-   - If no assertion exists, record the result as a baseline reference
-   - Do not optimize at this stage unless the assertion fails
+3. **Run the benchmark** -- capture initial results and apply thresholds:
+
+   **When the spec defines a performance requirement** (e.g., "< 50ms"):
+   - Use the spec requirement as the benchmark assertion threshold
+   - Verify it passes; if not, see step 4
+
+   **When the spec is vague or silent on performance:**
+   - Fall back to harness-perf tier thresholds:
+     - Critical path functions (annotated `@perf-critical` or high fan-in): must not regress >5% from baseline (Tier 1)
+     - Non-critical functions: must not regress >10% from baseline (Tier 2)
+     - Structural complexity: must stay under Tier 2 thresholds (cyclomatic <=15, nesting <=4, function length <=50 lines, params <=5)
+   - These thresholds give developers concrete targets even when the spec does not specify performance requirements
+
+   **When no baseline exists (new code):**
+   - This run captures the initial baseline
+   - No regression comparison on first run
+   - VALIDATE phase (Phase 4) ensures the captured baseline is committed via `harness perf baselines update`
 
 4. **If the performance assertion fails,** you have two options:
    - The implementation approach is fundamentally wrong (e.g., O(n^2) when O(n) is needed) — revise the algorithm