dev-harness-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,299 @@
+# Dev Harness
+
+**Agent-agnostic development pipeline CLI.** Scaffold, phase orchestrate, gate validate, and iterate any software project — works with any coding agent (Claude Code, Codex, OpenCode, Cursor, etc.).
+
+```bash
+npx github:bakr-bagaber/dev-harness init --stack python --target my-project
+cd my-project
+npx github:bakr-bagaber/dev-harness phase define
+```
+
+## Install
+
+```bash
+# Quick start (no install)
+npx github:bakr-bagaber/dev-harness --help
+
+# Global install from GitHub
+npm install -g https://github.com/bakr-bagaber/dev-harness.git
+harness-dev --help
+
+# Or clone and install
+git clone https://github.com/bakr-bagaber/dev-harness.git
+cd dev-harness && npm install -g .
+```
+
+Requires **Node.js >= 18**.
+
+## Quick Start
+
+```bash
+# Scaffold a new project
+harness-dev init --stack python --target my-app
+
+# Check status
+cd my-app
+harness-dev status
+
+# Start the DEFINE phase
+harness-dev phase define
+```
+
+## Supported Stacks
+
+| Stack | Detection | Config File |
+|-------|-----------|-------------|
+| Python | `pyproject.toml`, `setup.py`, `*.py` | `pyproject.toml` |
+| Java | `pom.xml`, `build.gradle`, `*.java` | `pom.xml` |
+| Kotlin | `build.gradle.kts`, `*.kt` | `build.gradle.kts` |
+| Node.js | `package.json`, `*.js`, `*.ts` | `package.json` |
+| Go | `go.mod`, `*.go` | `go.mod` |
+| Rust | `Cargo.toml`, `*.rs` | `Cargo.toml` |
+| C | `*.c` | `CMakeLists.txt` |
+| C++ | `*.cpp`, `*.hpp` | `CMakeLists.txt` |
+| .NET | `*.cs`, `*.fs` | `global.json` |
+| MATLAB | `*.m` | (none) |
+| VHDL | `*.vhdl`, `*.vhd` | (none) |
+| Verilog | `*.v`, `*.sv` | (none) |
+| Generic | fallback | (none) |
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Scaffold project (21 files) |
+| `status` | Show current state |
+| `phase <name>` | Invoke a phase |
+| `validate` | Run gate checks |
+| `config get/set` | Read/write config |
+| `learn <msg>` | Save a lesson |
+| `set-mode` | copilot / autopilot |
+| `pause` / `resume` | Control autopilot |
+| `contract propose/review/status/escalate` | Sprint contract negotiation |
+| `worktree create/list/prune/remove` | Git worktree management |
+| `checkpoint create <label>` | Git tag checkpoint |
+| `rollback list/to/branch` | Rollback to checkpoint |
+
+## Phase Pipeline
+
+```
+INIT → DEFINE → PLAN → BUILD → VERIFY → [SIMPLIFY] → REVIEW → SHIP
+```
+
+Two loop modes:
+- **Copilot** (default): one phase at a time, human decides when to advance
+- **Autopilot**: auto-advances through pipeline after each gate passes
+
+## Output Contracts
+
+All commands produce machine-parseable JSON with `--json`:
+
+```json
+{"command":"status","status":"ok","message":"Phase: define, Stack: Node.js",
+ "currentPhase":"define","mode":"copilot","recentLessons":[]}
+```
+
+Errors go to stderr: `{"error":"CliError","message":"...","exitCode":N}`
+
+Exit codes: `0` success, `1` validation failure, `2` usage error, `3` internal error
+
+## Architecture
+
+```
+cli/
+├── harness-dev.mjs        — Entry point + command router
+├── lib/
+│   ├── args.mjs           — Argument parser
+│   ├── errors.mjs         — Error handling + exit codes
+│   ├── help.mjs           — Help text + per-command help
+│   ├── detect-stack.mjs   — 13-stack detection engine
+│   ├── vars.mjs           — Stack variable resolution
+│   ├── templates.mjs      — Template engine ({{VAR}} substitution)
+│   ├── state.mjs          — Config I/O + phase transitions
+│   ├── phases.mjs         — Pure phase pipeline logic
+│   ├── progress.mjs       — progress.md reader/writer
+│   ├── gates.mjs          — Phase gate validation
+│   ├── ralph-inner.mjs    — Inner loop engine
+│   ├── ralph-outer.mjs    — Outer loop engine
+│   ├── ralph-output.mjs   — Phase instruction text builders
+│   ├── modes.mjs          — Copilot/autopilot modes
+│   ├── contract.mjs       — Sprint contract negotiation
+│   ├── git.mjs            — Centralized git operations
+│   ├── paths.mjs          — Centralized path resolution
+│   ├── file-io.mjs        — JSON/text I/O helpers
+│   ├── output.mjs         — JSON/human output helpers
+│   ├── command-helpers.mjs— Shared arg parsing + phaseLabel
+│   ├── constants.mjs      — Centralized magic numbers
+│   ├── scaffold.mjs       — Stack-specific scaffolding assets
+│   ├── validate-schema.mjs— Minimal JSON-schema validator
+│   └── schemas/
+│       └── stacks.json    — 13-stack metadata (CLI-internal)
+├── commands/              — 13 command handlers
+│   ├── init.mjs, status.mjs, phase.mjs, validate.mjs, config.mjs
+│   ├── learn.mjs, set-mode.mjs, pause.mjs, resume.mjs
+│   └── contract.mjs, worktree.mjs, rollback.mjs, checkpoint.mjs
+templates/                  — Scaffold templates (AGENTS.md, init.sh, ci/, docs/, etc.)
+schema/                     — Published JSON schemas (harness-config, feature-list)
+test/                       — Test suites (test-t*.mjs + run-all.mjs)
+dist/install.sh             — One-liner installation script (curl-pipe-bash)
+adapters/                  — Tool adapters (claude-code, cursor, codex, hermes, generic)
+docs/                      — TOOL_INTEGRATION.md (per-tool setup guides)
+references/                 — Historical audit reports
+history/                    — Project audit log, changelog, decisions, issues
+docs-site-templates/        — Docusaurus/Sphinx scaffolds (experimental)
+```
+
+## Agent Integration
+
+harness-dev works with any coding agent via stdout JSON contracts and AGENTS.md project conventions. Use `--agent-tool` at scaffold time to generate tool-specific files, or `detect-tool` to discover which tools are configured.
+
+```bash
+# Scaffold with a specific tool
+harness-dev init --stack node --agent-tool claude-code --target my-project
+
+# Or scaffold generically (AGENTS.md only — works with most tools)
+harness-dev init --stack node --target my-project
+
+# Detect which tools are configured
+harness-dev detect-tool --target my-project
+```
+
+**Supported tools:** `claude-code` (CLAUDE.md), `cursor` (.cursorrules), `codex`, `aider`, `continue`, `opencode` (all read AGENTS.md), `hermes` (SKILL.md), `generic` (default).
+
+See [docs/TOOL_INTEGRATION.md](docs/TOOL_INTEGRATION.md) for per-tool setup guides and the adapter architecture.
+
+### Claude Code
+
+```bash
+harness-dev init --stack node --agent-tool claude-code --target my-project
+cd my-project
+# Claude reads CLAUDE.md automatically
+harness-dev phase build
+# Claude follows the phase instructions, runs:
+harness-dev validate
+```
+
+### Codex CLI
+
+```bash
+harness-dev init --stack go --agent-tool codex --target my-project
+cd my-project
+# Codex reads AGENTS.md from project root
+harness-dev status --json
+# → Machine-readable state for agent decision-making
+```
+
+### Cursor
+
+```bash
+harness-dev init --stack rust --agent-tool cursor --target my-project
+cd my-project
+# .cursorrules generated with harness conventions
+harness-dev phase build
+```
+
+### Generic Agent Workflow
+
+```bash
+harness-dev phase build
+# → Prints task instructions for agent
+# → Agent reads AGENTS.md + progress.md + sprint-contract.md
+# → Agent implements → calls `harness-dev validate`
+# → Gate passes → `harness-dev phase verify`
+```
+
+## API Reference
+
+### JSON Output Contract (all commands)
+
+```json
+{
+  "command": "<command_name>",
+  "status": "ok" | "not_implemented" | "error",
+  "message": "Human-readable status or error detail"
+}
+```
+
+Additional command-specific fields are included (e.g. `currentPhase`, `stack`, `mode`).
+
+### Error Contract
+
+```json
+{
+  "error": "CliError",
+  "message": "Description of the problem",
+  "exitCode": 1
+}
+```
+
+Errors always go to **stderr** so stdout stays parseable.
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | Validation failure |
+| 2 | Usage error |
+| 3 | Internal error |
+
+### All Commands
+
+| Command | JSON Fields | Description |
+|---------|-------------|-------------|
+| `init` | `project`, `stack`, `filesCreated` | Scaffold harness project |
+| `status` | `currentPhase`, `mode`, `stack`, `gateStatus`, `checksPassing`, `checksTotal`, `recentLessons`, `nextAction` | Show current state |
+| `phase <name>` | `phase`, `previousPhase`, `gateResult`, `iteration` | Invoke a phase |
+| `validate` | `phase`, `checks[]`, `overall`, `failures[]` | Run gate checks |
+| `config get <key>` | `key`, `value` | Read config value |
+| `config set <key> <value>` | `key`, `previous`, `current` | Write config value |
+| `learn <msg>` | `lesson` | Append a lesson |
+| `set-mode copilot\|autopilot` | `previous`, `current` | Switch mode |
+| `pause` / `resume` | `paused` | Control autopilot |
+| `contract propose\|review\|status\|escalate` | `status`, `agreed`, `round`, `pinned` | Sprint contract |
+| `worktree create\|list\|prune\|remove` | `worktrees[]`, `action`, `name` | Git worktree |
+| `checkpoint create <label>` | `tag`, `commit` | Git checkpoint |
+| `rollback list\|to\|branch` | `checkpoints[]`, `restored` | Rollback |
+
+## Project Structure
+
+```
+cli/                        — CLI source
+├── harness-dev.mjs         — Entry point + command router
+├── lib/                    — Core libraries
+│   ├── git.mjs             — Centralized git operations
+│   ├── state.mjs           — Config I/O + phase transitions (re-exports phases.mjs)
+│   ├── phases.mjs          — Pure phase pipeline logic
+│   ├── ralph-inner.mjs     — Inner loop (work → validate → retry)
+│   ├── ralph-outer.mjs     — Outer loop (phase auto-advance)
+│   ├── ralph-output.mjs    — Phase instruction text builders
+│   ├── gates.mjs           — Phase gate validation
+│   ├── contract.mjs        — Sprint contract negotiation
+│   ├── paths.mjs           — Centralized path resolution
+│   ├── file-io.mjs         — JSON/text I/O helpers
+│   ├── output.mjs          — JSON/human output helpers
+│   ├── command-helpers.mjs — Shared arg parsing + phaseLabel
+│   ├── constants.mjs       — Centralized magic numbers
+│   ├── scaffold.mjs        — Stack-specific scaffolding assets
+│   ├── templates.mjs       — Template engine
+│   ├── detect-stack.mjs    — Stack detection
+│   ├── validate-schema.mjs — Minimal JSON-schema validator
+│   └── schemas/stacks.json — Stack metadata (CLI-internal)
+├── commands/               — Command handlers (13 commands)
+templates/                  — Scaffold templates (AGENTS.md, init.sh, ci/, docs/, etc.)
+schema/                     — Published JSON schemas (harness-config, feature-list)
+test/                       — Test suites (test-t*.mjs + run-all.mjs)
+dist/install.sh             — One-liner install script
+adapters/                  — Tool adapters (claude-code, cursor, codex, hermes, generic)
+docs/                      — TOOL_INTEGRATION.md (per-tool setup guides)
+references/                 — Historical audit reports (T5-T14)
+history/                    — Project audit log, changelog, decisions, issues
+docs-site-templates/        — Docusaurus/Sphinx scaffolds (experimental, T25)
+PROJECT_PLAN.md             — Full task breakdown (T1-T20)
+SPEC.md                     — Original architecture specification
+dev-harness.md              — Internal project note (Obsidian)
+```
+
+## License
+
+MIT

package/adapters/amazon-q/README.md

@@ -0,0 +1,23 @@
+# Amazon Q Developer Adapter
+
+Amazon Q Developer reads .amazonq/rules.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool amazon-q --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `.amazonq/rules.md` — Amazon Q Developer-specific rules file (generated from AGENTS.md content)
+- `harness-config.json` — with `agentTool: "amazon-q"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. .amazonq/rules.md) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/adapters/antigravity/README.md

@@ -0,0 +1,22 @@
+# Antigravity 2 Adapter
+
+Antigravity 2 (IDE/CLI/SDK) — assumed to read AGENTS.md.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool antigravity --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `harness-config.json` — with `agentTool: "antigravity"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. AGENTS.md) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/adapters/claude-code/README.md

@@ -0,0 +1,30 @@
+# Claude Code Adapter
+
+Claude Code reads `AGENTS.md` from the project root automatically. When you
+scaffold with `harness-dev init --agent-tool claude-code`, the harness generates
+a `CLAUDE.md` that points Claude at the harness conventions.
+
+## Usage
+
+```bash
+# Scaffold with Claude Code adapter
+harness-dev init --stack node --agent-tool claude-code --target my-project
+cd my-project
+
+# Claude Code picks up CLAUDE.md automatically
+claude
+```
+
+## Files Generated
+
+- `CLAUDE.md` — Claude-specific entry point (references AGENTS.md)
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `harness-config.json` — with `agentTool: "claude-code"`
+
+## How It Works
+
+Claude Code reads `CLAUDE.md` on startup. The generated `CLAUDE.md` includes
+the harness quick-start, phase pipeline, and commands — same content as
+`AGENTS.md` but in the file Claude looks for. Claude then follows the phase
+instructions emitted by `harness-dev phase <name>` and runs
+`harness-dev validate` after each phase.

package/adapters/cline/README.md

@@ -0,0 +1,23 @@
+# Cline Adapter
+
+Cline (VS Code extension) reads .clinerules.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool cline --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `.clinerules` — Cline-specific rules file (generated from AGENTS.md content)
+- `harness-config.json` — with `agentTool: "cline"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. .clinerules) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/adapters/codex/README.md

@@ -0,0 +1,31 @@
+# Codex CLI Adapter
+
+Codex CLI reads `AGENTS.md` from the project root natively — no tool-specific
+file is needed. When you scaffold with `harness-dev init --agent-tool codex`,
+the harness sets `agentTool: "codex"` in config but does not generate any
+extra files (AGENTS.md is already the canonical entry point).
+
+## Usage
+
+```bash
+# Scaffold with Codex adapter
+harness-dev init --stack node --agent-tool codex --target my-project
+cd my-project
+
+# Codex reads AGENTS.md automatically
+codex
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated; Codex reads this)
+- `harness-config.json` — with `agentTool: "codex"`
+
+## How It Works
+
+Codex CLI reads `AGENTS.md` on startup. The generated `AGENTS.md` includes
+the harness quick-start, phase pipeline, agent roles, and commands. Codex
+then follows the phase instructions emitted by `harness-dev phase <name>`
+and runs `harness-dev validate` after each phase.
+
+No `.codexrules` or similar file is needed — AGENTS.md is the standard.

package/adapters/copilot/README.md

@@ -0,0 +1,23 @@
+# GitHub Copilot Adapter
+
+GitHub Copilot reads .github/copilot-instructions.md.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool copilot --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `.github/copilot-instructions.md` — GitHub Copilot-specific rules file (generated from AGENTS.md content)
+- `harness-config.json` — with `agentTool: "copilot"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. .github/copilot-instructions.md) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/adapters/cursor/README.md

@@ -0,0 +1,29 @@
+# Cursor Adapter
+
+Cursor reads `.cursorrules` from the project root. When you scaffold with
+`harness-dev init --agent-tool cursor`, the harness generates a `.cursorrules`
+file that embeds the harness conventions.
+
+## Usage
+
+```bash
+# Scaffold with Cursor adapter
+harness-dev init --stack node --agent-tool cursor --target my-project
+cd my-project
+
+# Open in Cursor — .cursorrules is loaded automatically
+cursor .
+```
+
+## Files Generated
+
+- `.cursorrules` — Cursor-specific rules (embeds harness conventions)
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `harness-config.json` — with `agentTool: "cursor"`
+
+## How It Works
+
+Cursor loads `.cursorrules` as system context for every chat. The generated
+file includes the phase pipeline, agent roles, and the rule that the agent
+must run `harness-dev validate` after each phase. Cursor then follows the
+instructions emitted by `harness-dev phase <name>`.

package/adapters/gemini/README.md

@@ -0,0 +1,23 @@
+# Gemini CLI Adapter
+
+Google Gemini CLI reads GEMINI.md on startup.
+
+## Usage
+
+```bash
+harness-dev init --stack node --agent-tool gemini --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (always generated)
+- `GEMINI.md` — Gemini CLI-specific rules file (generated from AGENTS.md content)
+- `harness-config.json` — with `agentTool: "gemini"`
+
+## How It Works
+
+The harness generates AGENTS.md as the canonical conventions file. For tools
+with a specific rules file, the harness copies AGENTS.md content to the
+tool-specific filename (e.g. GEMINI.md) with an optional header. The tool then
+reads its native file and follows the harness phase instructions.

package/adapters/generic/README.md

@@ -0,0 +1,40 @@
+# Generic Adapter (Default)
+
+The generic adapter is the default when no `--agent-tool` is specified at
+scaffold time. It generates only `AGENTS.md` — the canonical, tool-agnostic
+harness conventions file that any coding agent can read.
+
+## Usage
+
+```bash
+# Scaffold with generic adapter (default — no flag needed)
+harness-dev init --stack node --target my-project
+cd my-project
+```
+
+## Files Generated
+
+- `AGENTS.md` — canonical harness conventions (read by Claude Code, Codex,
+  Aider, Continue, OpenCode, and any tool that follows the AGENTS.md standard)
+- `harness-config.json` — with `agentTool: null` (unspecified)
+
+## How It Works
+
+Any agent tool that reads `AGENTS.md` from the project root will pick up the
+harness conventions automatically. The agent follows the phase instructions
+emitted by `harness-dev phase <name>` and runs `harness-dev validate` after
+each phase.
+
+## Supported Tools (no adapter needed)
+
+These tools read `AGENTS.md` natively and work with the generic adapter:
+
+- **Claude Code** — reads AGENTS.md (but also supports CLAUDE.md; use
+  `--agent-tool claude-code` for the dedicated adapter)
+- **Codex CLI** — reads AGENTS.md
+- **Aider** — reads AGENTS.md via `--read AGENTS.md`
+- **Continue** — reads AGENTS.md
+- **OpenCode** — reads AGENTS.md
+
+If your tool isn't listed, the generic adapter is the right choice —
+AGENTS.md is the emerging standard for agent-readable project conventions.

package/adapters/hermes/README.md

@@ -0,0 +1,31 @@
+# Hermes Adapter
+
+Hermes is an agentic coding platform. This adapter provides the Hermes skill
+manifest (`SKILL.md`) and thin wrapper scripts that delegate to the dev-harness
+CLI. When you scaffold with `harness-dev init --agent-tool hermes`, the harness
+generates the Hermes skill files alongside the standard `AGENTS.md`.
+
+## Usage
+
+```bash
+# Scaffold with Hermes adapter
+harness-dev init --stack node --agent-tool hermes --target my-project
+cd my-project
+
+# Hermes loads the skill via SKILL.md
+```
+
+## Files
+
+- `SKILL.md` — Hermes skill manifest (YAML frontmatter + command docs)
+- `scripts/init.mjs`, `scripts/phase.mjs`, `scripts/validate.mjs` — thin
+  `spawnSync` wrappers that delegate to the CLI
+- `templates` — symlink to the main `templates/` directory (shared, not duplicated)
+- `AGENTS.md` — canonical harness conventions (always generated)
+
+## How It Works
+
+The wrapper scripts resolve the CLI path relative to their own location and
+call `node cli/harness-dev.mjs <command>` with the forwarded arguments. No
+logic is duplicated — the scripts are pure delegation. The `templates`
+symlink ensures Hermes sees the same templates the CLI uses.