@harness-engineering/cli 1.7.0 → 1.8.1

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

@@ -0,0 +1,48 @@
+name: harness-soundness-review
+version: "1.0.0"
+description: Deep soundness analysis of specs and plans with auto-fix and convergence loop
+cognitive_mode: meticulous-verifier
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+cli:
+  command: harness skill run harness-soundness-review
+  args:
+    - name: path
+      description: Project root path
+      required: false
+    - name: mode
+      description: Review mode — "spec" for spec soundness or "plan" for plan soundness
+      required: true
+mcp:
+  tool: run_skill
+  input:
+    skill: harness-soundness-review
+    path: string
+type: rigid
+phases:
+  - name: check
+    description: Run all checks for the current mode and classify findings
+    required: true
+  - name: fix
+    description: Auto-fix inferrable issues and log changes
+    required: true
+  - name: converge
+    description: Re-run checks, compare issue counts, loop or stop
+    required: true
+  - name: surface
+    description: Present remaining issues to user for resolution
+    required: true
+state:
+  persistent: false
+  files: []
+depends_on: []

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

@@ -13,8 +13,23 @@
 
 ## 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.
+A knowledge graph at `.harness/graph/` enables full analysis. If no graph exists,
+the skill uses static analysis fallbacks (see Graph Availability section).
+Run `harness scan` to enable graph-enhanced analysis.
+
+### Graph Availability
+
+Before starting, check if `.harness/graph/graph.json` exists.
+
+**If graph exists:** Check staleness — compare `.harness/graph/metadata.json`
+scanTimestamp against `git log -1 --format=%ct` (latest commit timestamp).
+If graph is more than 10 commits behind (`git log --oneline <scanTimestamp>..HEAD | wc -l`),
+run `harness scan` to refresh before proceeding. (Staleness sensitivity: **Medium**)
+
+**If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.
+
+**If no graph exists:** Output "Running without graph (run `harness scan` to
+enable full analysis)" and use fallback strategies for all subsequent steps.
 
 ## Process
 
@@ -43,6 +58,20 @@ For each changed file, use graph traversal to find test files:
 
 3. **Co-change tests**: Check `co_changes_with` edges for test files that historically change alongside the modified files.
 
+#### Fallback (without graph)
+
+When no graph is available, use naming conventions, import parsing, and git history:
+
+1. **Tier 1 — Filename convention matching**: For each changed file `foo.ts`, search for:
+   - `foo.test.ts`, `foo.spec.ts` (same directory)
+   - `__tests__/foo.ts`, `__tests__/foo.test.ts`
+   - Test files in a parallel `tests/` directory mirroring the source path
+2. **Tier 2 — Import-linked tests**: Parse test files' import statements (grep for `import.*from` in `*.test.*` and `*.spec.*` files). If a test file imports the changed file, it belongs in Tier 2 (if not already in Tier 1).
+3. **Tier 3 — Co-change correlated tests**: Use `git log --format="%H" --name-only` to find test files that frequently change in the same commit as the target file. Files that co-change in >2 commits are co-change correlated.
+4. **Rank**: Tier 1 = direct filename match, Tier 2 = import-linked tests, Tier 3 = co-change correlated tests. Output the same tiered format as the graph version.
+
+> Fallback completeness: ~80% — naming conventions and imports catch most mappings; misses dynamic imports and indirect coverage.
+
 ### Phase 3: PRIORITIZE — Rank and Generate Commands
 
 Organize tests into three tiers:
@@ -85,7 +114,7 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 
 ## Harness Integration
 
-- **`harness scan`** — Must run before this skill to ensure graph is current.
+- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses naming convention and import parsing fallbacks.
 - **`harness validate`** — Run after acting on findings to verify project health.
 - **Graph tools** — This skill uses `query_graph`, `get_impact`, and `get_relationships` MCP tools.
 
@@ -95,7 +124,7 @@ npx vitest run tests/services/auth.test.ts tests/types/user.test.ts tests/routes
 - Executable run commands generated for quick and full test runs
 - Coverage gaps flagged for changed files with no test coverage
 - Report follows the structured output format
-- All findings are backed by graph query evidence, not heuristics
+- All findings are backed by graph query evidence (with graph) or systematic static analysis (without graph)
 
 ## Examples
 
@@ -122,8 +151,8 @@ Output:
 
 ## Gates
 
-- **No advice without graph.** If no graph exists, fall back to: "Run all tests in the same directory as changed files."
-- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these.
+- **Graph preferred, fallback available.** If no graph exists, use naming conventions, import parsing, and git co-change analysis to identify relevant tests. Do not stop — produce the best test selection possible.
+- **Always include Tier 1.** Direct test coverage is non-negotiable — always recommend running these (whether found via graph or naming conventions).
 
 ## Escalation
 

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

@@ -160,6 +160,70 @@ After running all three levels, produce a structured gap report:
 ### Verdict: INCOMPLETE — 2 gaps must be resolved
 ```
 
+The verification report uses conventional markdown patterns for structured output:
+
+```
+**[CRITICAL]** path/to/file.ts:22 — TODO: implement validation (anti-pattern)
+**[IMPORTANT]** path/to/file.ts — exported but not imported by any other file
+```
+
+### Verification Sign-Off
+
+After producing the verification report, request acceptance:
+
+```json
+emit_interaction({
+  path: "<project-root>",
+  type: "confirmation",
+  confirmation: {
+    text: "Verification report: <VERDICT>. Accept and proceed?",
+    context: "<summary: N artifacts checked, N gaps found>"
+  }
+})
+```
+
+### Handoff and Transition
+
+After producing the verification report, write the handoff and conditionally transition:
+
+Write `.harness/handoff.json`:
+
+```json
+{
+  "fromSkill": "harness-verification",
+  "phase": "COMPLETE",
+  "summary": "<verdict summary>",
+  "artifacts": ["<verified file paths>"],
+  "verdict": "pass | fail",
+  "gaps": ["<gap descriptions if any>"]
+}
+```
+
+**If verdict is PASS (all levels passed, no gaps):**
+
+Call `emit_interaction`:
+
+```json
+{
+  "type": "transition",
+  "transition": {
+    "completedPhase": "verification",
+    "suggestedNext": "review",
+    "reason": "Verification passed at all 3 levels",
+    "artifacts": ["<verified file paths>"],
+    "requiresConfirmation": false,
+    "summary": "Verification passed: <N> artifacts checked. EXISTS, SUBSTANTIVE, WIRED all passed."
+  }
+}
+```
+
+The response will include `nextAction: "Invoke harness-code-review skill now"`.
+Immediately invoke harness-code-review without waiting for user input.
+
+**If verdict is FAIL or INCOMPLETE:**
+
+Do NOT emit a transition. Surface gaps to the user for resolution. The handoff is written with the gaps recorded for future reference.
+
 ---
 
 ### Regression Test Verification
@@ -184,6 +248,8 @@ If step 4 passes (test does not fail without the fix), the test is not a valid r
 
 All commands must be run fresh in the current session. Do not rely on results from a previous session or a previous run in the same session if code has changed since.
 
+- **`emit_interaction`** -- Call after verification passes to auto-transition to harness-code-review. Only emitted on PASS verdict. Uses auto-transition (proceeds immediately).
+
 ## Success Criteria
 
 - Every claimed deliverable has been verified at all 3 levels

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

@@ -13,6 +13,7 @@ tools:
   - Bash
   - Read
   - Glob
+  - emit_interaction
 cli:
   command: harness skill run harness-verification
   args:

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

@@ -89,6 +89,16 @@ Rules:
 - If all checks are SKIPPED, overall result is `PASS` (nothing to fail).
 - On FAIL, include a brief summary of what failed (e.g., "3 type errors", "2 lint errors", "5 tests failed") below the structured block.
 
+### Roadmap Sync (conditional)
+
+When all non-skipped checks pass (overall `Verification: PASS`) and `docs/roadmap.md` exists:
+
+1. Trigger a roadmap sync to update feature statuses based on the verified state.
+2. Use the `manage_roadmap` MCP tool with `sync` action if available, or note to the caller that a roadmap sync is recommended.
+3. Features linked to plans whose tasks are all complete and verified may be marked as `done`.
+
+If `docs/roadmap.md` does not exist, skip this step silently. If verification failed, do not sync — the roadmap should only reflect verified completions.
+
 ## Deterministic Checks
 
 This skill is entirely deterministic. There are no LLM judgment calls anywhere in the process.
@@ -106,6 +116,7 @@ This skill is entirely deterministic. There are no LLM judgment calls anywhere i
 - Output format is consumed by harness-integrity for the unified pipeline
 - Invokes `harness-accessibility` for design constraint checking when `design` config exists
 - Design violations respect `design.strictness` from `harness.config.json`
+- **Roadmap sync** — When verification passes and `docs/roadmap.md` exists, triggers `manage_roadmap sync` to mark verified features as `done`. Only fires on overall PASS.
 
 ## Success Criteria
 

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

@@ -59,6 +59,11 @@
 
 4. **For advanced:** Configure state management (`.harness/state.json` schema), learnings capture (`.harness/learnings.md` conventions), and CI integration hooks.
 
+5. **Configure i18n (all levels).** Ask: "Will this project support multiple languages?" Based on the answer:
+   - **Yes:** Invoke `harness-i18n-workflow` configure phase to set up i18n config in `harness.config.json` (source locale, target locales, framework, strictness). Then invoke `harness-i18n-workflow` scaffold phase to create translation file structure and extraction config. Set `i18n.enabled: true`.
+   - **No:** Set `i18n.enabled: false` in `harness.config.json`. The `harness-i18n-process` skill will still fire gentle prompts for unconfigured projects when features touch user-facing strings.
+   - **Not sure yet:** Skip i18n configuration entirely. Do not set `i18n.enabled`. The project can enable i18n later by running `harness-i18n-workflow` directly.
+
 ### Phase 4: VALIDATE — Confirm Everything Works
 
 1. **Run `harness validate`** to verify the full configuration. This checks:
@@ -82,7 +87,9 @@ harness scan [path]
 
 This creates the `.harness/graph/` directory and populates it with the project's dependency and relationship data. Subsequent graph queries (impact analysis, dependency health, test advisor) depend on this initial scan.
 
-4. **Commit the initialization.** All generated and configured files in a single commit.
+4. **Mention roadmap.** After validation passes, inform the user: "When you are ready to set up a project roadmap, run `/harness:roadmap --create`. This creates a unified `docs/roadmap.md` that tracks features, milestones, and status across your specs and plans." This is informational only — do not create the roadmap automatically.
+
+5. **Commit the initialization.** All generated and configured files in a single commit.
 
 ## Harness Integration
 
@@ -91,6 +98,8 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - **`harness persona generate`** — Generate persona definitions based on project stack and team structure.
 - **`harness validate`** — Verify the full project configuration is valid and complete.
 - **`harness check-deps`** — Verify dependency constraints match the actual codebase (intermediate and above).
+- **`harness-i18n-workflow configure` + `harness-i18n-workflow scaffold`** — Invoked during Phase 3 if the project will support multiple languages. Sets up i18n configuration and translation file structure.
+- **Roadmap nudge** — After successful initialization, inform the user about `/harness:roadmap --create` for setting up project-level feature tracking. Informational only; does not create the roadmap.
 
 ## Success Criteria
 
@@ -102,6 +111,7 @@ This creates the `.harness/graph/` directory and populates it with the project's
 - Personas are configured if the project uses them
 - The adoption level matches what was agreed upon with the human
 - All generated files are committed in a single atomic commit
+- i18n configuration is set if the human chose to enable it during init
 
 ## Examples
 
@@ -131,6 +141,10 @@ Edit AGENTS.md:
   - Add stack: TypeScript, Express, Vitest, PostgreSQL
   - Add conventions: "Use zod for validation, repository pattern for data access"
   - Add constraints: "No direct SQL queries outside repository layer"
+  - Ask: "Will this project support multiple languages?"
+  - Human: "Yes, Spanish and French."
+  - Run harness-i18n-workflow configure (source: en, targets: es, fr)
+  - Run harness-i18n-workflow scaffold (creates locales/ directory structure)
 ```
 
 **VALIDATE:**

package/dist/agents/skills/claude-code/validate-context-engineering/SKILL.md

@@ -32,6 +32,18 @@ When a knowledge graph exists at `.harness/graph/`, use graph queries for faster
 
 When a graph is available, it IS the source of truth for documentation coverage. Drift = stale or missing edges between code and doc nodes. Fall back to file-based commands if no graph is available.
 
+### Pipeline Context (when orchestrated)
+
+When invoked by `harness-docs-pipeline`, check for a `pipeline` field in `.harness/handoff.json`:
+
+- If `pipeline` field exists: read `DocPipelineContext` from it
+  - Use `pipeline.exclusions` to skip findings that were already addressed in the FIX phase
+  - Write `GapFinding[]` results back to `pipeline.gapFindings` in handoff.json
+  - This enables dedup across FIX and AUDIT phases
+- If `pipeline` field does not exist: behave exactly as today (standalone mode)
+
+No changes to the skill's interface or output format — the pipeline field is purely additive.
+
 ### Phase 2: Detect Gaps
 
 Categorize findings into four types:

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

@@ -0,0 +1,192 @@
+# Add Harness Component
+
+> Add layers, documentation, components, or skills to an existing harness project with proper integration. Validate against existing constraints, wire into architecture, and verify the result.
+
+## When to Use
+
+- Adding a new layer to the project's architecture
+- Adding a new documentation file that harness should track
+- Adding a new component (module, service, package) that must be wired into existing layer boundaries
+- Adding a new skill to the project's skill library
+- When a plan calls for introducing a new architectural boundary or module
+- NOT when initializing a project from scratch (use initialize-harness-project)
+- NOT when modifying an existing component (use standard editing workflows)
+- NOT when removing components (manual process — removing requires careful dependency analysis)
+
+## Process
+
+### Phase 1: DETERMINE — Identify What to Add
+
+1. **Clarify the component type.** Ask if not obvious from context:
+   - **Layer:** A new architectural boundary (e.g., adding an "infrastructure" layer to a project that only has "business" and "data")
+   - **Document:** A documentation file that harness should track for drift detection (e.g., API docs, architecture decision records)
+   - **Component:** A code module, service, or package that lives within an existing layer
+   - **Skill:** A new harness skill definition for the project's workflow
+
+2. **Gather requirements.** For each type:
+   - **Layer:** Name, which directories belong to it, which layers it can import from, which layers can import from it
+   - **Document:** Path, what it documents, which code files it relates to
+   - **Component:** Name, which layer it belongs to, what it depends on, what will depend on it
+   - **Skill:** Name, purpose, type (rigid or flexible), triggers
+
+3. **Check prerequisites.** The project must already be initialized with harness. If `harness.yaml` does not exist, stop and run initialize-harness-project first.
+
+### Phase 2: VALIDATE — Check Against Existing Constraints
+
+1. **Read the current configuration.** Load `harness.yaml` and `AGENTS.md` to understand existing layers, constraints, and architecture.
+
+2. **Verify the new component does not conflict:**
+   - Does the layer name already exist?
+   - Does the component directory already exist?
+   - Would the new dependency relationships create circular imports?
+   - Does the component violate any existing forbidden-import rules?
+
+3. **If conflicts are found,** report them clearly: "Adding layer X would conflict with existing layer Y because [reason]. Options: [A] rename, [B] merge into existing layer, [C] restructure. Which do you prefer?"
+
+4. **Run `harness check-deps`** on the current state to establish a clean baseline. If it already fails, fix existing violations before adding new components.
+
+### Phase 3: ADD — Create the Component
+
+1. **Run `harness add` with appropriate arguments:**
+   - Layer: `harness add layer <name> --dirs <dir1,dir2> --imports <allowed-layers>`
+   - Document: `harness add doc <path> --tracks <related-code-paths>`
+   - Component: `harness add component <name> --layer <layer-name>`
+   - Skill: `harness add skill <name> --type <rigid|flexible>`
+
+2. **Review generated files and configuration changes.** `harness add` modifies `harness.yaml` and may generate template files. Check that the changes look correct.
+
+3. **Create the actual code or content.** `harness add` creates the configuration entry but not necessarily the implementation. Create the directories, files, and initial code as needed.
+
+### Phase 4: WIRE — Integrate into Architecture
+
+1. **Update imports and exports.** If the new component needs to be imported by existing code, add the imports. If existing code needs to be aware of the new layer, update barrel files or index modules.
+
+2. **Update `AGENTS.md`.** Add the new component to the architecture section. Document its purpose, boundaries, and relationships to other components. This keeps agent instructions accurate.
+
+3. **Update layer configuration** if the new component changes dependency relationships. Ensure `harness.yaml` reflects the actual import graph.
+
+4. **For new skills:** Write the `skill.yaml` and `SKILL.md` files following the harness skill format. Use harness-skill-authoring for guidance on writing good skill content.
+
+### Phase 5: VERIFY — Confirm Integration
+
+1. **Run `harness validate`** to verify the full project configuration is still valid after the addition.
+
+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
+   - Imports from forbidden layers
+   - `AGENTS.md` references outdated architecture
+
+4. **Commit the addition.** All new and modified files in a single atomic commit.
+
+## Harness Integration
+
+- **`harness add layer <name>`** — Register a new architectural layer with directory mappings and import rules.
+- **`harness add doc <path>`** — Register a documentation file for drift tracking.
+- **`harness add component <name> --layer <layer>`** — Register a new code component within an existing layer.
+- **`harness add skill <name> --type <type>`** — Scaffold a new skill definition.
+- **`harness validate`** — Verify project configuration after the addition.
+- **`harness check-deps`** — Verify dependency constraints are respected after the addition.
+
+## Success Criteria
+
+- The new component is properly registered in `harness.yaml`
+- The component's files exist in the correct directories for its declared layer
+- `AGENTS.md` is updated to reflect the new component
+- `harness validate` passes after the addition
+- `harness check-deps` passes after the addition (no new violations)
+- No circular dependencies were introduced
+- The addition is committed as a single atomic commit
+
+## Examples
+
+### Example: Adding a New Layer
+
+```
+Human: "We need an infrastructure layer for external API clients."
+
+DETERMINE: Adding a layer. Name: infrastructure. Dirs: src/infrastructure/.
+  Imports from: (none — infrastructure is a leaf layer, no internal dependencies).
+  Imported by: business layer (services call external APIs through infrastructure).
+
+VALIDATE:
+  Read harness.yaml — existing layers: presentation, business, data.
+  No conflict with "infrastructure" name.
+  Run: harness check-deps — passes (clean baseline).
+
+ADD:
+  harness add layer infrastructure --dirs src/infrastructure --imports none
+  mkdir -p src/infrastructure
+
+WIRE:
+  Update harness.yaml: allow business → infrastructure imports.
+  Update AGENTS.md: document infrastructure layer purpose and boundaries.
+
+VERIFY:
+  harness validate    # Pass
+  harness check-deps  # Pass
+  git add harness.yaml AGENTS.md src/infrastructure/
+  git commit -m "feat: add infrastructure layer for external API clients"
+```
+
+### Example: Adding a Document for Drift Tracking
+
+```
+Human: "Track our API specification for documentation drift."
+
+DETERMINE: Adding a document. Path: docs/api-spec.md.
+  Tracks: src/routes/, src/models/response.ts.
+
+ADD:
+  harness add doc docs/api-spec.md --tracks src/routes,src/models/response.ts
+
+WIRE:
+  Update AGENTS.md: note that docs/api-spec.md is tracked for drift.
+
+VERIFY:
+  harness validate  # Pass
+  git add harness.yaml AGENTS.md
+  git commit -m "feat: track API spec for documentation drift detection"
+```
+
+### Example: Adding a Component to an Existing Layer
+
+```
+Human: "Add a notification service to the business layer."
+
+DETERMINE: Adding a component. Name: notification-service. Layer: business.
+  Depends on: data layer (notification repository). Depended on by: presentation layer (routes).
+
+VALIDATE:
+  Read harness.yaml — business layer exists, maps to src/services/.
+  No existing notification-service directory.
+  business → data is an allowed import. Presentation → business is allowed.
+  Run: harness check-deps — passes.
+
+ADD:
+  harness add component notification-service --layer business
+  Create src/services/notification-service.ts
+  Create src/services/notification-service.test.ts
+
+WIRE:
+  Add export to src/services/index.ts (if barrel file exists).
+  Update AGENTS.md: add notification service to business layer component list.
+
+VERIFY:
+  harness validate    # Pass
+  harness check-deps  # Pass
+  git add harness.yaml AGENTS.md src/services/notification-service.*
+  git commit -m "feat: add notification service to business layer"
+```

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

@@ -0,0 +1,32 @@
+name: add-harness-component
+version: "1.0.0"
+description: Add a component to an existing harness project
+cognitive_mode: constructive-architect
+triggers:
+  - manual
+platforms:
+  - claude-code
+  - gemini-cli
+tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+cli:
+  command: harness skill run add-harness-component
+  args:
+    - name: path
+      description: Project root path
+      required: false
+mcp:
+  tool: run_skill
+  input:
+    skill: add-harness-component
+    path: string
+type: flexible
+state:
+  persistent: false
+  files: []
+depends_on:
+  - initialize-harness-project