dev-harness-cli 1.0.0

package/templates/AGENTS.md

@@ -0,0 +1,63 @@
+# {{stackLabel}} — Harness
+
+## Quick Start
+
+```bash
+harness-dev status        # Where are we?
+harness-dev phase <name>  # Invoke a phase
+harness-dev validate      # Check gate criteria
+```
+
+## Project
+
+- **Stack:** {{stack}}
+- **Mode:** copilot / autopilot
+- **Phase:** not started
+
+## Phase Pipeline
+
+INIT → DEFINE → PLAN → BUILD → VERIFY → [SIMPLIFY] → REVIEW → SHIP
+
+See `docs/phases/` for phase-specific instructions.
+
+## Agent Roles
+
+| Role | File | Tone |
+|------|------|------|
+| Planner | `docs/agents/planner.md` | Analytical, precise. Define clear boundaries |
+| Generator | `docs/agents/generator.md` | Focused, practical. Build what's specified |
+| Evaluator | `docs/agents/evaluator.md` | Skeptical, thorough. Accept only compelling evidence |
+| Simplifier | `docs/agents/simplifier.md` | Relentless about clarity. Delete more than you add |
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `harness-config.json` | Config + state |
+| `feature_list.json` | Feature list with passes |
+| `progress.md` | Session state + lessons |
+| `sprint-contract.md` | Pre-build agreement |
+| `init.sh` | Install → verify → start |
+| `evaluator-rubric.md` | Quality scorecard (6 dimensions, 0-2) |
+|
+## Rules (non-negotiable)
+
+1. No agent evaluates its own work — Evaluator always judges
+2. Read `progress.md` + this file before each operation
+3. Commit frequently — each iteration is a checkpoint
+4. If unsure → read the role guide in `docs/agents/`
+5. Never skip gates — run `harness-dev validate` after each phase
+6. Fresh context per retry — pass `--git-ops` to `harness-dev phase <name>` to auto-reset the working tree on retry (off by default; agent-agnostic)
+7. **No files in project root** unless they are harness-managed files (listed in Key Files above) or standard project files (README.md, LICENSE, CHANGELOG.md, CONTRIBUTING.md, .gitignore, and the stack config file like package.json/pyproject.toml/Cargo.toml). All source code, tests, scripts, and docs go in subdirectories.
+8. **Structure from the start** — create folders for your work on day one and stick to them. Suggested layout: `src/` (source), `tests/` (tests), `docs/` (documentation), `scripts/` (automation). Do not dump files at root "temporarily" — there is no temporary.
+9. **No orphaned files** — every file you create must have a clear purpose and be referenced by imports, configs, docs, or the build system. If you create a file, wire it in immediately. Delete files you stop using.
+
+## Development Commands
+
+| Task | Command |
+|------|---------|
+| Install deps | `{{installCmd}}` |
+| Build | `{{buildCmd}}` |
+| Test | `{{testCmd}}` |
+| Lint | `{{lintCmd}}` |
+| Type check | `{{typeCheckCmd}}` |

package/templates/ci/github-actions.yml

@@ -0,0 +1,78 @@
+# CI/CD pipeline for {{stackLabel}} projects scaffolded by Dev Harness
+# Trigger: push + PR to main
+# Stack: {{stack}} — toolchain setup is conditional on the rendered stack value.
+name: harness
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        if: {{stack}} == 'node'
+        with: { node-version: lts/* }
+      - uses: actions/setup-python@v5
+        if: {{stack}} == 'python'
+        with: { python-version: '3.x' }
+      - uses: actions/setup-go@v5
+        if: {{stack}} == 'go'
+        with: { go-version: 'stable' }
+      - uses: dtolnay/rust-toolchain@stable
+        if: {{stack}} == 'rust'
+      - run: {{installCmd}}
+      - run: {{lintCmd}}
+
+  test:
+    needs: lint
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        if: {{stack}} == 'node'
+        with: { node-version: ${{ matrix.node-version }} }
+      - uses: actions/setup-python@v5
+        if: {{stack}} == 'python'
+        with: { python-version: '3.x' }
+      - uses: actions/setup-go@v5
+        if: {{stack}} == 'go'
+        with: { go-version: 'stable' }
+      - uses: dtolnay/rust-toolchain@stable
+        if: {{stack}} == 'rust'
+      - run: {{installCmd}}
+      - run: {{testCmd}}
+
+  coverage:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        if: {{stack}} == 'node'
+        with: { node-version: lts/* }
+      - uses: actions/setup-python@v5
+        if: {{stack}} == 'python'
+        with: { python-version: '3.x' }
+      - uses: actions/setup-go@v5
+        if: {{stack}} == 'go'
+        with: { go-version: 'stable' }
+      - uses: dtolnay/rust-toolchain@stable
+        if: {{stack}} == 'rust'
+      - run: {{installCmd}}
+      - run: {{testCmd}}
+
+  gate:
+    needs: coverage
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: npm install -g @dev-harness/cli
+      - run: harness-dev validate --json

package/templates/ci/gitlab-ci.yml

@@ -0,0 +1,59 @@
+# CI/CD pipeline for {{stackLabel}} projects scaffolded by Dev Harness
+# Stack: {{stack}} — CI image selected via workflow rules.
+stages:
+  - lint
+  - test
+  - coverage
+  - gate
+
+# Select the container image based on the rendered stack value.
+# {{stack}} is substituted at scaffold time, so exactly one rule matches.
+workflow:
+  rules:
+    - if: {{stack}} == 'python'
+      variables:
+        CI_IMAGE: python:3.12
+    - if: {{stack}} == 'go'
+      variables:
+        CI_IMAGE: golang:latest
+    - if: {{stack}} == 'rust'
+      variables:
+        CI_IMAGE: rust:latest
+    - if: {{stack}} == 'java'
+      variables:
+        CI_IMAGE: maven:latest
+    - if: {{stack}} == 'dotnet'
+      variables:
+        CI_IMAGE: mcr.microsoft.com/dotnet/sdk:latest
+    - when: always
+      variables:
+        CI_IMAGE: node:lts
+
+lint:
+  stage: lint
+  image: $CI_IMAGE
+  script:
+    - {{installCmd}}
+    - {{lintCmd}}
+
+test:
+  stage: test
+  image: $CI_IMAGE
+  script:
+    - {{installCmd}}
+    - {{testCmd}}
+
+coverage:
+  stage: coverage
+  image: $CI_IMAGE
+  script:
+    - {{installCmd}}
+    - {{testCmd}}
+
+gate:
+  stage: gate
+  image: node:lts
+  script:
+    - npm install -g @dev-harness/cli
+    - harness-dev validate --json
+  needs: [coverage]

package/templates/docs/agents/evaluator.md

@@ -0,0 +1,14 @@
+# Evaluator Role
+
+Tone: Skeptical and thorough. Accept only compelling evidence.
+
+You verify. You gate. You are the final authority.
+
+- Do NOT trust "seems right" — require proof
+- Run the verification commands yourself
+- If criteria are ambiguous, reject with specific reason
+- "Pass" means all checks pass; "Fail" means at least one check is insufficient
+- In DEFINE: review sprint-contract.md for clarity and testability
+- In REVIEW: check all phase gates, branch alignment, changelog
+- Use `evaluator-rubric.md` to score quality across 6 dimensions
+- Gate failures escalate to human after max retries

package/templates/docs/agents/generator.md

@@ -0,0 +1,13 @@
+# Generator Role
+
+Tone: Focused and practical. Build what's specified.
+
+You implement. You produce artifacts. You self-check.
+
+- Build exactly what the Planner specified
+- Do not add scope or "future-proof"
+- Run lint + tests before handoff
+- In BUILD: implement ONE task at a time, then validate
+- In VERIFY: run the full test suite
+- In SIMPLIFY: adopt the Simplifier persona (see simplifier.md)
+- When done: call `harness-dev validate`

package/templates/docs/agents/planner.md

@@ -0,0 +1,13 @@
+# Planner Role
+
+Tone: Analytical and precise. Define clear boundaries.
+
+You design the approach. You write criteria. You set scope.
+
+- Propose what to build in sprint-contract.md
+- Define unambiguous acceptance criteria
+- Set exclusions explicitly ("We will NOT build X")
+- Hand off to Generator when criteria are clear
+- In DEFINE: interview the user, write PRD in specs/*.md
+- In PLAN: decompose features into tasks in feature_list.json
+- Review gate criteria with Evaluator before proceeding

package/templates/docs/agents/simplifier.md

@@ -0,0 +1,13 @@
+# Simplifier (Generator Persona for SIMPLIFY Phase)
+
+Tone: Relentless about clarity. Delete more than you add.
+
+You refactor. You clean. You never change behavior.
+
+- Flatten nesting — max 4 levels
+- Remove dead code and commented-out blocks
+- Extract repeated logic into shared functions
+- Break long functions (~40 line threshold)
+- Rename unclear variables
+- ⚠ All tests must still pass after your changes
+- Run `harness-dev validate` after each feature to confirm gate

package/templates/docs/phases/build.md

@@ -0,0 +1,41 @@
+# BUILD Phase
+
+**Loop mode:** Feature-iterate
+**Unit of work:** One incomplete feature from `feature_list.json`
+**Primary agent:** Generator
+
+## Purpose
+
+Implement features one at a time. Each iteration: pick the next incomplete
+feature → work → validate that task → pass = next feature / fail = retry with
+fresh context. Only when all features pass does the phase gate run.
+
+## Entry
+
+- PLAN gate passed
+- `sprint-contract.md` status is `Agreed`
+- `feature_list.json` non-empty
+
+## Work
+
+1. Read `progress.md`, `AGENTS.md`, `sprint-contract.md`.
+2. Pick next feature where `passes === false`.
+3. Implement the feature's tasks.
+4. Run `harness-dev validate --feature <name> --task <id>` per task.
+5. On pass: mark feature `passes: true`, commit, append lesson to `progress.md`.
+6. On fail (≤ `maxRetries`): retry with fresh context (git reset if `--git-ops`).
+7. On fail (> `maxRetries`): escalate to human.
+
+## Exit Gate
+
+Run `harness-dev validate` — checks:
+
+- `config-exists`
+- `git-repo`
+- `feature-branch` (not on main/master)
+- `git-clean`
+- All features in `feature_list.json` have `passes: true`
+
+## Handoff
+
+On gate pass: `harness-dev phase verify` (Generator → Evaluator).

package/templates/docs/phases/define.md

@@ -0,0 +1,51 @@
+# DEFINE Phase
+
+**Loop mode:** Deliverable-retry
+**Deliverable:** Product Requirements Document (`specs/*.md`)
+**Primary agent:** Planner
+
+## Purpose
+
+Interview the user, capture intent, and write a bounded PRD. The output is a
+short, unambiguous specification that the PLAN phase can decompose into a
+feature list.
+
+## Entry
+
+- `harness-config.json` exists (created by `harness-dev init`)
+- `AGENTS.md` present in project root
+
+## Work
+
+1. Read `progress.md` and `AGENTS.md` for context.
+2. Interview the user to surface objectives, constraints, and exclusions.
+3. **If stack is custom/unknown**, fill `stackMeta` in `harness-config.json`:
+   - `testCmd` — command to run tests (e.g. `mix test`)
+   - `lintCmd` — command to lint (e.g. `mix credo`)
+   - `buildCmd` — command to build (e.g. `mix compile`)
+   - `installCmd` — command to install deps (e.g. `mix deps.get`)
+   - `coverageCmd` — command for coverage (e.g. `mix test --cover`)
+   - `configFile` — project config file (e.g. `mix.exs`)
+   - `extensions` — source file extensions (e.g. `[".ex", ".exs"]`)
+   - These override the built-in stack metadata and make gate validation work.
+4. **Define project folder structure** — agree on directory layout with user:
+   - `src/` for source code
+   - `tests/` for test files
+   - `docs/` for documentation
+   - `scripts/` for automation scripts
+   - No source files in project root (only harness + standard project files)
+   - Document the agreed structure in `specs/prd.md`
+5. Write `specs/prd.md` — scope, success criteria, non-goals.
+6. Keep the PRD bounded: no vague verbs ("improve", "enhance").
+
+## Exit Gate
+
+Run `harness-dev validate` — checks:
+
+- `config-exists`
+- `git-repo`
+- `specs/prd.md` present
+
+## Handoff
+
+On gate pass: `harness-dev phase plan` (Planner → continues as Planner for decomposition).

package/templates/docs/phases/plan.md

@@ -0,0 +1,36 @@
+# PLAN Phase
+
+**Loop mode:** Deliverable-retry
+**Deliverable:** `feature_list.json` with decomposed tasks
+**Primary agent:** Planner
+
+## Purpose
+
+Decompose the PRD into a feature list. Each feature has one or more tasks with
+verifiable acceptance criteria. The Sprint Contract is negotiated here.
+
+## Entry
+
+- DEFINE gate passed
+- `specs/prd.md` present
+
+## Work
+
+1. Read `specs/prd.md`.
+2. Decompose into features → tasks in `feature_list.json`.
+3. Planner proposes `sprint-contract.md` (scope, criteria, exclusions).
+4. Evaluator reviews; iterate until `**Status:** Agreed`.
+5. Use `harness-dev contract propose` / `contract review --decision <agreed|needs-revision>`.
+
+## Exit Gate
+
+Run `harness-dev validate` — checks:
+
+- `config-exists`
+- `git-repo`
+- `feature_list.json` present and non-empty
+- `contract-agreed` (sprint contract status is `Agreed`)
+
+## Handoff
+
+On gate pass: `harness-dev phase build` (Planner → Generator).

package/templates/docs/phases/review.md

@@ -0,0 +1,42 @@
+# REVIEW Phase
+
+**Loop mode:** Deliverable-retry
+**Deliverable:** Review report (`review-report.md`)
+**Primary agents:** Multi-agent committee (Planner, Generator, Evaluator, Simplifier)
+
+## Purpose
+
+Whole-project review by the committee. Each persona reviews from its angle and
+records findings. The Evaluator aggregates into `review-report.md` with an
+overall verdict: Accept / Revise / Block.
+
+## Entry
+
+- SIMPLIFY gate passed (or SIMPLIFY disabled)
+
+## Work
+
+1. Each persona reviews the full diff since last review:
+   - Planner: scope adherence vs `sprint-contract.md`
+   - Generator: implementation correctness
+   - Evaluator: rubric scores, gate evidence
+   - Simplifier: residual complexity / dead code
+2. Evaluator aggregates findings into `review-report.md`.
+3. Verdict `Revise` → return to BUILD with specific feedback.
+4. Verdict `Accept` → proceed to SHIP.
+
+## Exit Gate
+
+Run `harness-dev validate` — checks:
+
+- `config-exists`
+- `git-repo`
+- `git-clean`
+- `review-report.md` present with verdict `Accept`
+- `readme-exists` — README.md present with meaningful content
+- `architecture-doc` — ARCHITECTURE.md filled in (if file exists)
+- `decisions-logged` — DECISIONS.md has at least one recorded decision
+
+## Handoff
+
+On gate pass: `harness-dev phase ship` (committee → release).

package/templates/docs/phases/ship.md

@@ -0,0 +1,43 @@
+# SHIP Phase
+
+**Loop mode:** Deliverable-retry
+**Deliverable:** Release artifact (tag, changelog entry, PR)
+**Primary agent:** Generator (release mechanics), Evaluator (final sign-off)
+
+## Purpose
+
+Produce the release. Cut a tag, update `CHANGELOG.md`, open or merge the PR.
+The release must be reproducible from a clean checkout.
+
+## Entry
+
+- REVIEW gate passed with verdict `Accept`
+
+## Work
+
+1. Update `CHANGELOG.md` with version, date, summary.
+2. Bump version in `package.json` / equivalent manifest.
+3. Run full `harness-dev validate` — all gates must pass.
+4. Tag the release: `git tag -a v<x.y.z> -m "Release x.y.z"`.
+5. Open or merge the PR per project workflow.
+
+## Exit Gate
+
+Run `harness-dev validate` — checks:
+
+- `config-exists`
+- `git-repo`
+- `git-clean`
+- Release tag exists
+- `CHANGELOG.md` updated
+- `readme-exists` — README.md present with meaningful content
+- `license-exists` — LICENSE file present
+- `changelog-content` — CHANGELOG.md has actual version entries
+- `contributing-exists` — CONTRIBUTING.md present (recommended)
+- `no-empty-dirs` — no empty directories in shipped project
+
+## Handoff
+
+On gate pass: pipeline complete. `harness-dev status` reports
+`Pipeline complete after "ship"`. Increment `pipelineIteration` and loop back
+to DEFINE for the next sprint, or stop if the project is done.

package/templates/docs/phases/simplify.md

@@ -0,0 +1,40 @@
+# SIMPLIFY Phase
+
+**Loop mode:** Feature-iterate
+**Unit of work:** One feature simplified
+**Primary agent:** Simplifier
+
+## Purpose
+
+Relentless clarity. Delete more than you add. Each feature gets a simplification
+pass: remove dead code, collapse duplication, tighten names. Simplifications
+must not break the feature's acceptance criteria.
+
+## Entry
+
+- VERIFY gate passed
+- `simplify` enabled in `harness-config.json` (`phases.enabled` includes `simplify`)
+
+## Work
+
+1. Read `progress.md` and `AGENTS.md`.
+2. For each feature: review the implementation, propose deletions/renames.
+3. Apply simplifications.
+4. Re-run `harness-dev validate --feature <name>` — criteria must still pass.
+5. On pass: commit, append lesson.
+6. On fail (≤ `maxRetries`): revert and retry.
+7. On fail (> `maxRetries`): escalate.
+
+## Exit Gate
+
+Run `harness-dev validate` — checks:
+
+- `config-exists`
+- `git-repo`
+- `git-clean`
+- `no-empty-dirs` — no empty directories (cleanup dead structure)
+- All features still pass their criteria
+
+## Handoff
+
+On gate pass: `harness-dev phase review` (Simplifier → multi-agent committee).

package/templates/docs/phases/verify.md

@@ -0,0 +1,38 @@
+# VERIFY Phase
+
+**Loop mode:** Feature-iterate
+**Unit of work:** One feature re-checked by an independent agent
+**Primary agent:** Evaluator
+
+## Purpose
+
+No agent evaluates its own work. The Evaluator independently re-runs each
+feature's acceptance criteria from the sprint contract and scores it against
+`evaluator-rubric.md`. Failures go back to BUILD with feedback.
+
+## Entry
+
+- BUILD gate passed
+- All features marked `passes: true` by Generator
+
+## Work
+
+1. Read `sprint-contract.md` criteria and `evaluator-rubric.md`.
+2. For each feature: re-run its verification command independently.
+3. Score each rubric dimension (0–2): Correctness, Coverage, Code Quality,
+   Security, Performance, Handoff Readiness.
+4. On pass: keep `passes: true`, record score in `progress.md`.
+5. On fail: mark `passes: false`, write feedback, return to BUILD.
+
+## Exit Gate
+
+Run `harness-dev validate` — checks:
+
+- `config-exists`
+- `git-repo`
+- `git-clean`
+- All features re-confirmed `passes: true` by Evaluator
+
+## Handoff
+
+On gate pass: `harness-dev phase simplify` (Evaluator → Simplifier).

package/templates/evaluator-rubric.md

@@ -0,0 +1,28 @@
+# Evaluator Rubric
+
+Score each dimension 0-2:
+
+| Score | Meaning |
+|-------|---------|
+| 0 | Unacceptable (blocker — must fix) |
+| 1 | Acceptable with minor issues |
+| 2 | Excellent (no issues) |
+
+## Scorecard
+
+| Dimension | Score | Evidence | Notes |
+|-----------|-------|----------|-------|
+| **Correctness** | 0-2 | [test results] | Does it work? |
+| **Test Coverage** | 0-2 | [coverage report] | ≥80%? |
+| **Code Quality** | 0-2 | [lint output] | Clean? Idiomatic? |
+| **Security** | 0-2 | [scan results] | Vulnerabilities? |
+| **Performance** | 0-2 | [benchmarks] | Regressions? |
+| **Handoff Readiness** | 0-2 | [docs updated] | Next agent can continue? |
+
+## Thresholds
+
+| Total Score | Outcome |
+|-------------|---------|
+| 10-12 | Accept (pass gate) |
+| 5-9 | Revise (fix issues, re-check) |
+| 0-4 | Block (escalate to human) |

package/templates/init.ps1

@@ -0,0 +1,97 @@
+<#
+.SYNOPSIS
+    Dev Harness — cross-platform init script (PowerShell).
+.DESCRIPTION
+    Installs dependencies, verifies the setup, and starts the dev server
+    for the detected project stack.
+.NOTES
+    Generated by Dev Harness v{{harnessVersion}} for {{stack}}.
+#>
+
+$ErrorActionPreference = "Stop"
+$HarnessVersion = "{{harnessVersion}}"
+$Stack = "{{stack}}"
+$StackLabel = "{{stackLabel}}"
+
+Write-Host "=== $StackLabel — Dev Harness ===" -ForegroundColor Cyan
+Write-Host ""
+
+# ── Install ──────────────────────────────────────────────────────────────────
+Write-Host "Installing dependencies..." -ForegroundColor Yellow
+
+switch ($Stack) {
+  "python" {
+    python -m pip install -e ".[dev]" 2>$null
+    if ($LASTEXITCODE -ne 0) { pip install -e ".[dev]" }
+  }
+  "node" {
+    npm install
+  }
+  "go" {
+    go mod download
+  }
+  "rust" {
+    cargo build
+  }
+  "java" {
+    mvn install -DskipTests
+  }
+  "kotlin" {
+    ./gradlew build
+  }
+  "dotnet" {
+    dotnet restore
+  }
+  "c" {
+    # C toolchain — requires gcc/cmake (install via system package manager)
+    cmake --version 2>$null
+    if ($LASTEXITCODE -ne 0) { Write-Host "cmake not found — install CMake + a C compiler" -ForegroundColor Yellow }
+  }
+  "cpp" {
+    # C++ toolchain — requires g++/cmake
+    cmake --version 2>$null
+    if ($LASTEXITCODE -ne 0) { Write-Host "cmake not found — install CMake + a C++ compiler" -ForegroundColor Yellow }
+  }
+  "matlab" {
+    # MATLAB — no install step; verify matlab is on PATH at verify stage
+  }
+  "vhdl" {
+    # VHDL — GHDL is the common open-source simulator
+    ghdl --version 2>$null
+    if ($LASTEXITCODE -ne 0) { Write-Host "ghdl not found — install GHDL for VHDL simulation" -ForegroundColor Yellow }
+  }
+  "verilog" {
+    # Verilog/SystemVerilog — Icarus Verilog is the common open-source simulator
+    iverilog -V 2>$null
+    if ($LASTEXITCODE -ne 0) { Write-Host "iverilog not found — install Icarus Verilog" -ForegroundColor Yellow }
+  }
+  Default {
+    Write-Host "No install command configured for $Stack" -ForegroundColor Yellow
+  }
+}
+
+Write-Host "  ✓ Dependencies installed" -ForegroundColor Green
+
+# ── Verify ───────────────────────────────────────────────────────────────────
+Write-Host "`nVerifying setup..." -ForegroundColor Yellow
+
+switch ($Stack) {
+  "python" { python -m pytest --version }
+  "node"   { npm test }
+  "go"     { go test ./... }
+  "rust"   { cargo test }
+  "java"   { mvn test }
+  "kotlin" { ./gradlew test }
+  "dotnet" { dotnet build }
+  "c"      { cmake --version }
+  "cpp"    { cmake --version }
+  "matlab" { matlab -batch "disp('matlab ok')" }
+  "vhdl"   { ghdl --version }
+  "verilog"{ iverilog -V }
+  Default { Write-Host "No verify command configured for $Stack" -ForegroundColor Yellow }
+}
+
+Write-Host "  ✓ Setup verified" -ForegroundColor Green
+
+# ── Start ────────────────────────────────────────────────────────────────────
+Write-Host "`nSetup complete. Run: harness-dev phase define" -ForegroundColor Cyan