@harness-engineering/cli 1.3.0 → 1.6.0

package/dist/agents/personas/architecture-enforcer.yaml

@@ -5,6 +5,7 @@ role: Enforce layer boundaries, detect circular dependencies, block forbidden im
 skills:
   - enforce-architecture
   - check-mechanical-constraints
+  - harness-dependency-health
 commands:
   - check-deps
   - validate

package/dist/agents/personas/code-reviewer.yaml

@@ -0,0 +1,41 @@
+version: 2
+name: Code Reviewer
+description: Full-lifecycle code review with harness methodology
+role: >
+  Perform AI-powered code review incorporating harness validation,
+  architectural analysis, and project-specific calibration.
+  Produces structured Strengths/Issues/Assessment output.
+skills:
+  - harness-code-review
+steps:
+  - command: validate
+    when: always
+  - command: check-deps
+    when: always
+  - command: check-docs
+    when: on_pr
+  - skill: harness-code-review
+    when: on_pr
+    output: auto
+  - skill: harness-code-review
+    when: manual
+    output: auto
+triggers:
+  - event: on_pr
+    conditions:
+      paths:
+        - "src/**"
+        - "packages/**"
+  - event: on_commit
+    conditions:
+      branches:
+        - main
+        - develop
+config:
+  severity: error
+  autoFix: false
+  timeout: 600000
+outputs:
+  agents-md: true
+  ci-workflow: true
+  runtime-config: true

package/dist/agents/personas/codebase-health-analyst.yaml

@@ -0,0 +1,27 @@
+version: 1
+name: Codebase Health Analyst
+description: Proactively identifies structural problems, coupling risks, and architectural drift
+role: Run health checks, detect hotspots, analyze impact, surface risks before they become incidents
+skills:
+  - harness-hotspot-detector
+  - harness-dependency-health
+  - harness-impact-analysis
+  - cleanup-dead-code
+commands:
+  - graph status
+  - check-deps
+triggers:
+  - event: scheduled
+    cron: "0 6 * * 1"
+  - event: on_pr
+    conditions:
+      min_files: 10
+  - event: manual
+config:
+  severity: warning
+  autoFix: false
+  timeout: 600000
+outputs:
+  agents-md: false
+  ci-workflow: true
+  runtime-config: true

package/dist/agents/personas/documentation-maintainer.yaml

@@ -5,9 +5,11 @@ role: Detect documentation drift, validate doc coverage, align docs with code ch
 skills:
   - detect-doc-drift
   - align-documentation
+  - harness-knowledge-mapper
 commands:
   - check-docs
   - validate
+  - scan
 triggers:
   - event: on_pr
     conditions:

package/dist/agents/personas/entropy-cleaner.yaml

@@ -5,9 +5,12 @@ role: Run scheduled cleanup, detect documentation drift, fix pattern violations
 skills:
   - cleanup-dead-code
   - detect-doc-drift
+  - harness-hotspot-detector
+  - harness-impact-analysis
 commands:
   - cleanup
   - fix-drift
+  - scan
 triggers:
   - event: scheduled
     cron: "0 6 * * 1"

package/dist/agents/personas/graph-maintainer.yaml

@@ -0,0 +1,27 @@
+version: 1
+name: Graph Maintainer
+description: Keeps the knowledge graph fresh, monitors connector health, and ensures data quality
+role: Re-scan codebase, sync external connectors, detect graph anomalies, maintain graph freshness
+skills:
+  - harness-dependency-health
+  - harness-knowledge-mapper
+  - validate-context-engineering
+commands:
+  - scan
+  - ingest
+  - graph status
+triggers:
+  - event: scheduled
+    cron: "0 4 * * *"
+  - event: on_commit
+    conditions:
+      branches: ["main"]
+  - event: manual
+config:
+  severity: warning
+  autoFix: false
+  timeout: 600000
+outputs:
+  agents-md: false
+  ci-workflow: true
+  runtime-config: true

package/dist/agents/personas/parallel-coordinator.yaml

@@ -0,0 +1,29 @@
+version: 2
+name: Parallel Coordinator
+description: Dispatches independent work across isolated Task Executor instances
+role: >
+  Verify task independence, create focused agent briefs, dispatch
+  Task Executor instances in isolated worktrees, integrate results,
+  and run full validation after all agents complete.
+skills:
+  - harness-parallel-agents
+steps:
+  - command: validate
+    when: always
+  - skill: harness-parallel-agents
+    when: manual
+    output: inline
+triggers:
+  - event: on_pr
+    conditions:
+      paths:
+        - "src/**"
+        - "packages/**"
+config:
+  severity: error
+  autoFix: false
+  timeout: 1800000
+outputs:
+  agents-md: true
+  ci-workflow: true
+  runtime-config: true

package/dist/agents/personas/task-executor.yaml

@@ -0,0 +1,41 @@
+version: 2
+name: Task Executor
+description: Executes approved plans with state tracking, TDD, and verification
+role: >
+  Execute implementation plans task-by-task using harness methodology.
+  Maintains persistent state, follows TDD rhythm, runs verification
+  after each task, and respects checkpoint protocol.
+skills:
+  - harness-execution
+steps:
+  - command: validate
+    when: always
+  - command: check-deps
+    when: always
+  - command: scan
+    when: manual
+  - skill: harness-execution
+    when: on_plan_approved
+    output: auto
+  - skill: harness-execution
+    when: manual
+    output: auto
+triggers:
+  - event: on_pr
+    conditions:
+      paths:
+        - "src/**"
+        - "packages/**"
+  - event: on_commit
+    conditions:
+      branches:
+        - main
+        - develop
+config:
+  severity: error
+  autoFix: false
+  timeout: 900000
+outputs:
+  agents-md: true
+  ci-workflow: true
+  runtime-config: true

package/dist/agents/skills/README.md

@@ -37,6 +37,14 @@ agents/skills/
 - `initialize-harness-project` - Scaffold new project
 - `add-harness-component` - Add components
 
+### Graph Integration Levels
+
+**Graph-Transformed** (7 skills): harness-code-review, validate-context-engineering, detect-doc-drift, cleanup-dead-code, harness-parallel-agents, enforce-architecture, harness-onboarding
+
+**Graph-Enhanced** (5 skills): harness-execution, harness-planning, harness-architecture-advisor, harness-refactoring, align-documentation
+
+**Graph-Enabled** (5 new skills): harness-impact-analysis, harness-dependency-health, harness-hotspot-detector, harness-test-advisor, harness-knowledge-mapper
+
 ## Usage
 
 ### Claude Code

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

@@ -73,6 +73,16 @@
 
 2. **Run `harness check-deps`** to verify no dependency violations were introduced. The new component's imports must respect layer boundaries.
 
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
+
 3. **If validation fails,** fix the issues before committing. Common causes:
    - New layer not properly registered in `harness.yaml`
    - Component placed in wrong directory for its declared layer

package/dist/agents/skills/claude-code/align-documentation/SKILL.md

@@ -31,6 +31,15 @@
 
 3. **Run `harness check-docs`** to identify any documentation that already has broken references due to the changes.
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context:
+
+- `query_graph` — find `documents` edges pointing to nodes changed in this diff
+- `get_impact` — auto-suggest which docs need updating after code changes
+
+Replaces manual doc-to-code correlation. Fall back to file-based commands if no graph is available.
+
 ### Phase 2: Map — Connect Code Changes to Documentation
 
 For each changed file, identify all documentation that references it:
@@ -84,6 +93,16 @@ For each affected documentation location:
 
 4. **Run `harness fix-drift`** to catch any remaining simple drift issues that manual review missed.
 
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
+
 5. **Commit the documentation update.** Use a commit message that references the original change: "docs: update AGENTS.md for notification service refactoring" or "docs: sync API docs after auth module rename."
 
 ## What to Update

package/dist/agents/skills/claude-code/cleanup-dead-code/SKILL.md

@@ -28,6 +28,15 @@
 
 3. **Review the report summary.** Note the total count and distribution. A few dead exports are normal; dozens suggest accumulated entropy from incomplete refactorings.
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate dead code detection:
+
+- `query_graph` — perform graph reachability analysis from entry point nodes to identify truly unreachable code
+- `get_relationships` — distinguish dynamic imports from genuinely unused code by checking edge types
+
+Graph reachability reduces false positives compared to static analysis alone, since it traces the full transitive import graph including re-exports. Fall back to file-based commands if no graph is available.
+
 ### Phase 2: Categorize — Safe vs. Needs Review
 
 **Safe to auto-fix (remove without further analysis):**
@@ -63,6 +72,16 @@ For each item categorized as safe:
 
 ### Phase 4: Report Remaining Items
 
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+Dead code removal changes graph topology — skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
+
 For items that need human review, report:
 
 1. **What it is** — file path, export name, what it does

package/dist/agents/skills/claude-code/detect-doc-drift/SKILL.md

@@ -22,6 +22,14 @@
 
 3. **Optionally, run `git diff` against a baseline** (last release, last sprint, etc.) to identify which code files changed. This helps prioritize — docs for recently changed files are most likely to be drifted.
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate drift detection:
+
+- `query_graph` — find `documents` edges where the target code node has changed since the doc node was last updated
+
+When a graph is available, drift is simply stale edges: doc-to-code edges where the code side has been modified more recently than the doc side. This replaces regex pattern matching and catches semantic drift that text search misses. Fall back to file-based commands if no graph is available.
+
 ### Phase 2: Identify — Classify Drift Types
 
 Categorize each finding into one of these drift types:

package/dist/agents/skills/claude-code/enforce-architecture/SKILL.md

@@ -28,6 +28,15 @@
    - Same-layer imports may or may not be allowed depending on project config
    - Cross-cutting concerns (logging, config) have their own rules
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate violation detection:
+
+- `query_graph` — traverse `imports` edges against layer constraint nodes to find all violations in a single query
+- `get_relationships` — find all code dependent on a violation target to show the full scope of impact
+
+Graph queries show the complete violation scope (not just the first occurrence per file) and reveal transitive violations that single-file analysis misses. Fall back to file-based commands if no graph is available.
+
 ### Phase 2: Run Dependency Checks
 
 1. **Run `harness check-deps`** to analyze all import statements against the constraint model. Capture the full JSON output.

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

@@ -104,6 +104,15 @@ Look for existing issues that may affect the decision:
 Store analysis in: .harness/architecture/<topic>/analysis.md
 ```
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context:
+
+- `query_graph` — discover how similar features are structured in the codebase
+- `search_similar` — find analogous patterns and implementations
+
+Replaces manual Glob/Grep exploration with graph pattern discovery. Fall back to file-based commands if no graph is available.
+
 ---
 
 ### Phase 3: PROPOSE — Present Options with Trade-Offs

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

@@ -54,6 +54,16 @@ grep -rl "<component-name>" docs/specs/ docs/design-docs/ docs/plans/
 grep -rn "interface\|type\|schema" <changed-file> | head -20
 ```
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context gathering:
+
+- `query_graph` — traverse dependency chain from changed files to find all imports and transitive dependencies (replaces grep for import tracing)
+- `get_impact` — find all affected tests, docs, and downstream code that may break from the change
+- `find_context_for` — assemble review context for changed files within token budget, ranked by relevance
+
+Graph queries replace manual grep/find commands and discover transitive dependencies that file search misses. Fall back to file-based commands if no graph is available.
+
 ### Commit History Context
 
 As part of context assembly (priority item #5), retrieve recent commit history for every affected file:

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

@@ -233,6 +233,16 @@ Characteristics of a bad fix (revert immediately):
 4. Run `harness check-deps` — must PASS
 5. Manually verify the original failing scenario works
 
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
+
 #### Step 4: Verify the Test Catches the Bug
 
 Apply the regression test verification protocol:

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

@@ -0,0 +1,150 @@
+# Harness Dependency Health
+
+> Analyze structural health of the codebase and surface problems before they become incidents.
+
+## When to Use
+
+- Weekly scheduled health check on the codebase
+- Before major refactoring — understand current structural health
+- When onboarding to a new project — assess codebase quality
+- NOT for checking layer violations (use enforce-architecture)
+- NOT for finding dead code (use cleanup-dead-code)
+
+## Prerequisites
+
+A knowledge graph must exist at `.harness/graph/`. Run `harness scan` if no graph is available.
+If the graph exists but code has changed since the last scan, re-run `harness scan` first — stale graph data leads to inaccurate results.
+
+## Process
+
+### Phase 1: METRICS — Compute Graph Structural Metrics
+
+Query the graph for five key structural indicators:
+
+1. **Hub detection**: Find nodes with high fan-in (>10 inbound `imports` edges).
+
+   ```
+   query_graph(rootNodeIds=[all file nodes], includeEdges=["imports"])
+   ```
+
+   Hubs are single points of failure — changes to them have outsized blast radius.
+
+2. **Orphan detection**: Find file nodes with zero inbound `imports` edges that are not entry points.
+
+   ```
+   get_relationships(nodeId=<file>, direction="inbound")
+   ```
+
+   Orphans may be dead code or missing from the module system.
+
+3. **Cycle detection**: Use `check_dependencies` to find circular import chains.
+   Cycles create fragile coupling — any change in the cycle affects all members.
+
+4. **Deep chain detection**: Find import chains longer than N hops (default: 7).
+
+   ```
+   query_graph(rootNodeIds=[entry points], maxDepth=10, includeEdges=["imports"])
+   ```
+
+   Deep chains are fragile — a change at the bottom propagates unpredictably.
+
+5. **Module cohesion**: For each module (directory), count internal vs external edges. Low internal cohesion (many external edges, few internal) suggests misplaced code.
+
+### Phase 2: SCORE — Calculate Health Score
+
+Compute a weighted health score (0-100):
+
+| Metric            | Weight | Scoring                                   |
+| ----------------- | ------ | ----------------------------------------- |
+| Hubs (>10 fan-in) | 25%    | 0 hubs = 100, 1-3 = 70, 4-6 = 40, >6 = 10 |
+| Orphans           | 20%    | 0 = 100, 1-5 = 80, 6-15 = 50, >15 = 20    |
+| Cycles            | 25%    | 0 = 100, 1 = 60, 2-3 = 30, >3 = 0         |
+| Deep chains (>7)  | 15%    | 0 = 100, 1-3 = 70, >3 = 30                |
+| Cohesion (avg)    | 15%    | >0.7 = 100, 0.5-0.7 = 70, <0.5 = 30       |
+
+**Grades**: A (90-100), B (75-89), C (60-74), D (40-59), F (<40)
+
+### Phase 3: RECOMMEND — Generate Recommendations
+
+For each problem found, generate a specific, actionable recommendation:
+
+- **Hubs**: "Split `src/utils/helpers.ts` (14 importers) into domain-specific utilities"
+- **Orphans**: "Remove `src/legacy/old-parser.ts` (0 importers, not an entry point)"
+- **Cycles**: "Break cycle A→B→C→A by extracting shared types to `src/types/shared.ts`"
+- **Deep chains**: "Consider flattening chain: entry→A→B→C→D→E→F→G (8 hops)"
+- **Low cohesion**: "Module `src/services/` has 80% external edges — consider splitting"
+
+### Output
+
+```
+## Dependency Health Report
+
+### Score: B (78/100)
+
+### Metrics
+| Metric | Count | Score |
+|--------|-------|-------|
+| Hubs (>10 fan-in) | 2 | 70/100 |
+| Orphans | 3 | 80/100 |
+| Cycles | 0 | 100/100 |
+| Deep chains (>7) | 1 | 70/100 |
+| Module cohesion | 0.62 avg | 70/100 |
+
+### Top Issues
+1. **Hub**: src/utils/helpers.ts — 14 importers (split recommended)
+2. **Hub**: src/types/index.ts — 12 importers (acceptable for type barrel)
+3. **Orphan**: src/legacy/old-parser.ts — 0 importers
+4. **Deep chain**: entry→auth→user→db→pool→config→env→loader (8 hops)
+
+### Recommendations
+1. Split src/utils/helpers.ts into domain-specific modules
+2. Investigate src/legacy/old-parser.ts for removal
+3. Flatten auth chain by having auth import db directly
+```
+
+## Harness Integration
+
+- **`harness scan`** — Must run before this skill to ensure graph is current.
+- **`harness validate`** — Run after acting on findings to verify project health.
+- **Graph tools** — This skill uses `query_graph`, `get_relationships`, and `check_dependencies` MCP tools.
+
+## Success Criteria
+
+- Health score computed on 0-100 scale with letter grade (A-F)
+- All five structural metrics gathered (hubs, orphans, cycles, deep chains, cohesion)
+- Recommendations are specific and actionable (name files, suggest concrete fixes)
+- Report follows the structured output format
+- All findings are backed by graph query evidence, not heuristics
+
+## Examples
+
+### Example: Weekly Health Check on Monorepo
+
+```
+Input: Scheduled weekly run on project root
+
+1. METRICS    — query_graph for hubs: 2 found (helpers.ts, index.ts)
+                get_relationships for orphans: 3 found
+                check_dependencies for cycles: 0 found
+                query_graph for deep chains: 1 found (8 hops)
+                Module cohesion average: 0.62
+2. SCORE      — Weighted score: 78/100 (Grade: B)
+3. RECOMMEND  — "Split helpers.ts (14 importers) into domain modules"
+                "Investigate old-parser.ts for removal (0 importers)"
+                "Flatten auth chain — 8 hops exceeds threshold"
+
+Output:
+  Score: B (78/100)
+  Top issues: 2 hubs, 3 orphans, 1 deep chain
+  3 actionable recommendations generated
+```
+
+## Gates
+
+- **No analysis without graph.** If no graph exists, stop and instruct to run `harness scan`.
+- **No guessing.** All metrics must come from graph queries, not heuristics.
+
+## Escalation
+
+- **When score is F (<40)**: Flag as critical and recommend immediate architectural review.
+- **When graph is stale**: Warn and suggest re-scanning before trusting results.

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

@@ -0,0 +1,41 @@
+name: harness-dependency-health
+version: "1.0.0"
+description: Analyze structural health of the codebase using graph metrics
+cognitive_mode: analytical-reporter
+triggers:
+  - manual
+  - scheduled
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-dependency-health
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-dependency-health
+    path: string
+type: rigid
+phases:
+  - name: metrics
+    description: Compute graph structural metrics
+    required: true
+  - name: score
+    description: Calculate health score and identify problems
+    required: true
+  - name: recommend
+    description: Generate specific remediation recommendations
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -41,6 +41,15 @@ Deviating from the plan mid-execution introduces untested assumptions, breaks ta
 
 7. **If prerequisites fail,** do not proceed. Report what is missing and which task is blocked.
 
+### Graph-Enhanced Context (when available)
+
+When a knowledge graph exists at `.harness/graph/`, use graph queries for faster, more accurate context:
+
+- `query_graph` — check file overlap between current and next task for conflict detection
+- `get_impact` — understand blast radius before executing a task
+
+Enables smarter execution ordering and blockage detection. Fall back to file-based commands if no graph is available.
+
 ---
 
 ### Phase 2: EXECUTE — Implement Tasks Atomically
@@ -137,6 +146,16 @@ Between tasks (especially between sessions):
    }
    ```
 
+### Graph Refresh
+
+If a knowledge graph exists at `.harness/graph/`, refresh it after code changes to keep graph queries accurate:
+
+```
+harness scan [path]
+```
+
+Skipping this step means subsequent graph queries (impact analysis, dependency health, test advisor) may return stale results.
+
 2. **Append tagged learnings to `.harness/learnings.md`.** Tag every entry with skill and outcome:
 
    ```markdown