dev-harness-cli 1.0.4 → 1.1.0

package/README.md

@@ -1,298 +1,226 @@
+<div align="center">
+
 # 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.).
+### Agent-agnostic development pipeline CLI
 
-```bash
-npx dev-harness-cli init --stack python --target my-project
-cd my-project
-npx dev-harness-cli phase define
+Scaffold · Phase orchestration · Gate validation · Iteration
+
+[![npm version](https://img.shields.io/npm/v/dev-harness-cli.svg)](https://www.npmjs.com/package/dev-harness-cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js >=18](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org)
+[![Zero Dependencies](https://img.shields.io/badge/dependencies-zero-blue.svg)](#)
+
+**Works with any coding agent:** Claude Code · Codex · Cursor · Aider · Continue · OpenCode · Windsurf · Gemini · GitHub Copilot · Cline · Roo · Kilo Code · Amazon Q · and more
+
+</div>
+
+---
+
+## What is this?
+
+**Dev Harness** is a CLI tool that brings structure to AI-assisted software development. Instead of ad-hoc prompting, it enforces a **phase pipeline** with **gate validation** — ensuring specs are written before code, code is reviewed before shipping, and nothing gets skipped.
+
+```
+define → plan → build → verify → [simplify] → review → ship
 ```
 
+Each phase has **deterministic gates** (checks) that must pass before advancing. The agent does the work; harness validates the result.
+
 ## Install
 
 ```bash
 # Quick start (no install)
-npx dev-harness-cli --help
+npx dev-harness-cli init --stack python --target my-project
 
 # Global install
 npm install -g dev-harness-cli
 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**.
+Requires **Node.js >= 18**. Zero runtime dependencies.
 
 ## Quick Start
 
 ```bash
-# Scaffold a new project
-harness-dev init --stack python --target my-app
-
-# Check status
+# 1. Scaffold a new project
+harness-dev init --stack node --target my-app
 cd my-app
+
+# 2. Check status
 harness-dev status
 
-# Start the DEFINE phase
+# 3. Run the DEFINE phase (agent writes specs)
 harness-dev phase define
+
+# 4. Validate (run gate checks)
+harness-dev validate
+
+# 5. Continue through pipeline
+harness-dev phase plan
+harness-dev phase build
+harness-dev phase verify
+harness-dev phase review
+harness-dev phase ship
+```
+
+## Project Structure
+
+When you run `harness-dev init`, all harness-managed files go into a `harness/` subfolder — keeping your project root clean:
+
+```
+my-project/
+├── AGENTS.md                 # Agent instructions (root — tools expect it here)
+├── .gitignore                # Git ignore rules
+├── package.json              # Your project's package file
+├── src/                      # Your source code
+├── tests/                    # Your tests
+└── harness/                  # All harness-managed files
+    ├── config.json           # Harness configuration + state
+    ├── progress.md           # Session state + lessons learned
+    ├── sprint-contract.md    # Pre-build agreement
+    ├── evaluator-rubric.md   # Quality scorecard
+    ├── session-handoff.md    # Context for session transitions
+    ├── clean-state-checklist.md
+    ├── features/
+    │   ├── feature-list.json       # Feature tracking
+    │   └── feature-list.schema.json
+    ├── docs/
+    │   ├── ARCHITECTURE.md         # Architecture decisions
+    │   ├── CONSTRAINTS.md          # Technical constraints
+    │   ├── DECISIONS.md            # Decision log
+    │   ├── api-patterns.md         # API conventions
+    │   ├── agents/                 # Agent role guides
+    │   │   ├── planner.md
+    │   │   ├── generator.md
+    │   │   ├── evaluator.md
+    │   │   └── simplifier.md
+    │   └── phases/                 # Phase instructions
+    │       ├── define.md
+    │       ├── plan.md
+    │       ├── build.md
+    │       ├── verify.md
+    │       ├── simplify.md
+    │       ├── review.md
+    │       └── ship.md
+    ├── ci/
+    │   ├── github-actions.yml
+    │   └── gitlab-ci.yml
+    └── scripts/
+        ├── init.sh
+        └── init.ps1
 ```
 
 ## 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` |
+31 built-in stacks + custom stack support:
+
+| Stack | Detection Files | Config File |
+|-------|----------------|-------------|
 | Node.js | `package.json`, `*.js`, `*.ts` | `package.json` |
-| Go | `go.mod`, `*.go` | `go.mod` |
+| Python | `pyproject.toml`, `setup.py`, `*.py` | `pyproject.toml` |
 | Rust | `Cargo.toml`, `*.rs` | `Cargo.toml` |
-| C | `*.c` | `CMakeLists.txt` |
-| C++ | `*.cpp`, `*.hpp` | `CMakeLists.txt` |
+| Go | `go.mod`, `*.go` | `go.mod` |
+| Java | `pom.xml`, `build.gradle`, `*.java` | `pom.xml` |
+| C/C++ | `*.c`, `*.cpp`, `*.hpp` | `CMakeLists.txt` |
 | .NET | `*.cs`, `*.fs` | `global.json` |
-| MATLAB | `*.m` | (none) |
-| VHDL | `*.vhdl`, `*.vhd` | (none) |
-| Verilog | `*.v`, `*.sv` | (none) |
-| Generic | fallback | (none) |
+| Ruby | `Gemfile`, `*.rb` | `Gemfile` |
+| PHP | `composer.json`, `*.php` | `composer.json` |
+| Swift | `Package.swift`, `*.swift` | `Package.swift` |
+| + 21 more | | |
+
+**Custom stacks:** Pass any name to `--stack` and fill `stackMeta` in `harness/config.json` during DEFINE phase.
 
 ## 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 |
+| `init` | Scaffold a new project with harness structure |
+| `status` | Show current phase, stack, features, gates |
+| `phase <name>` | Invoke a pipeline phase |
+| `validate` | Run gate checks for current phase |
+| `config list` | List all 29 configurable parameters |
+| `config get <key>` | Get a config value |
+| `config set <key> <value>` | Set a config value |
+| `set-mode <copilot\|autopilot>` | Switch execution mode |
+| `pause` / `resume` | Pause/resume 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 |
+| `learn <message>` | Save a lesson to progress.md |
+| `checkpoint create <label>` | Create a manual checkpoint |
+| `rollback list/to/branch` | Restore to checkpoint |
+| `worktree create/list/remove` | Git worktree management |
+| `detect-tool` | Detect available agent tools |
 
-## Phase Pipeline
-
-```
-INIT → DEFINE → PLAN → BUILD → VERIFY → [SIMPLIFY] → REVIEW → SHIP
-```
+## Agent Tool Integration
 
-Two loop modes:
-- **Copilot** (default): one phase at a time, human decides when to advance
-- **Autopilot**: auto-advances through pipeline after each gate passes
+Harness works with any coding agent. Use `--agent-tool` during init to generate tool-specific files:
 
-## Output Contracts
+```bash
+# Claude Code → generates CLAUDE.md
+harness-dev init --stack node --agent-tool claude-code --target my-app
 
-All commands produce machine-parseable JSON with `--json`:
+# Cursor → generates .cursorrules
+harness-dev init --stack node --agent-tool cursor --target my-app
 
-```json
-{"command":"status","status":"ok","message":"Phase: define, Stack: Node.js",
- "currentPhase":"define","mode":"copilot","recentLessons":[]}
+# GitHub Copilot → generates .github/copilot-instructions.md
+harness-dev init --stack node --agent-tool copilot --target my-app
 ```
 
-Errors go to stderr: `{"error":"CliError","message":"...","exitCode":N}`
+**18 supported tools:** claude-code, cursor, windsurf, gemini, copilot, cline, roo, kilo-code, amazon-q, codex, opencode, continue, aider, antigravity, openclaw, pi, hermes, generic.
 
-Exit codes: `0` success, `1` validation failure, `2` usage error, `3` internal error
+See [docs/TOOL_INTEGRATION.md](docs/TOOL_INTEGRATION.md) for per-tool setup guides.
 
-## Architecture
+## Gates
 
-```
-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.
+Gates are deterministic checks that must pass before advancing to the next phase. Enable with:
 
 ```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
+harness-dev config set gates.enabled true
 ```
 
-**Supported tools:** `claude-code` (CLAUDE.md), `cursor` (.cursorrules), `codex`, `aider`, `continue`, `opencode` (all read AGENTS.md), `hermes` (SKILL.md), `generic` (default).
+| Phase | Gates |
+|-------|-------|
+| DEFINE | feature-branch, contract-agreed |
+| PLAN | git-clean |
+| BUILD | (coverage if enabled) |
+| VERIFY | (coverage if enabled) |
+| SIMPLIFY | git-clean, no-empty-dirs |
+| REVIEW | branch-up-to-date, rubric-exists, readme-exists, architecture-doc, decisions-logged |
+| SHIP | git-clean, tagged, changelog, readme-exists, license-exists, changelog-content, contributing-exists, no-empty-dirs |
 
-See [docs/TOOL_INTEGRATION.md](docs/TOOL_INTEGRATION.md) for per-tool setup guides and the adapter architecture.
+## Configuration
 
-### Claude Code
+All configuration lives in `harness/config.json`. View with:
 
 ```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
+harness-dev config list
 ```
 
-### 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
-```
+29 parameters across 8 groups: Execution, Stack, Agent Tool, Gates, Git, Phases, Agent Tones, Runtime State.
 
-### Cursor
+See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for full reference.
 
-```bash
-harness-dev init --stack rust --agent-tool cursor --target my-project
-cd my-project
-# .cursorrules generated with harness conventions
-harness-dev phase build
-```
+## JSON Output
 
-### Generic Agent Workflow
+All commands support `--json` for machine-parseable output:
 
 ```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"
-}
+harness-dev status --json
+harness-dev phase define --json
+harness-dev validate --json
 ```
 
-Additional command-specific fields are included (e.g. `currentPhase`, `stack`, `mode`).
-
-### Error Contract
-
 ```json
 {
-  "error": "CliError",
-  "message": "Description of the problem",
-  "exitCode": 1
+  "command": "status",
+  "status": "ok",
+  "currentPhase": "define",
+  "stack": "node",
+  "mode": "copilot"
 }
 ```
 
-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)
-```
+Errors go to stderr. Exit codes: `0` success, `1` validation, `2` usage, `3` internal.
 
 ## License
 

package/cli/commands/config.mjs

@@ -75,7 +75,7 @@ export default async function configCommand(args) {
     // Human output — grouped table
     process.stdout.write('═══ Harness Configuration ═══\n\n');
     if (!ok) {
-      process.stdout.write('  No harness-config.json found. Run: harness-dev init\n\n');
+      process.stdout.write('  No harness/config.json found. Run: harness-dev init\n\n');
       return;
     }
 

package/cli/commands/detect-tool.mjs

@@ -20,12 +20,13 @@ import { parseCommandArgs } from '../lib/command-helpers.mjs';
 import { emitJson, emitHuman } from '../lib/output.mjs';
 import { loadConfig } from '../lib/state.mjs';
 import { getAllDetectionSignatures, AGENTS_MD_TOOLS, TOOL_REGISTRY } from '../lib/tool-registry.mjs';
+import { AGENTS_PATH } from '../lib/paths.mjs';
 
 export default async function detectToolCommand(args) {
   const { json, targetDir } = parseCommandArgs(args);
 
   const detected = [];
-  const hasAgentsMd = existsSync(resolve(targetDir, 'AGENTS.md'));
+  const hasAgentsMd = existsSync(AGENTS_PATH(targetDir));
 
   // 1. Scan for tool-specific detection files (from registry)
   for (const { tool, file } of getAllDetectionSignatures()) {

package/cli/commands/init.mjs

@@ -144,16 +144,16 @@ export default async function initCommand(args) {
   const harnessPaths = [];
   const projectPaths = [];
 
-  // Template files — known template names
+  // Template files — known template names (mapped to harness/ paths by templates.mjs)
   const templateNames = [
-    'AGENTS.md', 'harness-config.json', 'init.sh',
-    'progress.md', 'sprint-contract.md', 'evaluator-rubric.md',
+    'AGENTS.md', 'harness/config.json', 'harness/scripts/init.sh',
+    'harness/progress.md', 'harness/sprint-contract.md', 'harness/evaluator-rubric.md',
   ];
   for (const name of templateNames) {
     harnessPaths.push(join(targetDir, name));
   }
 
-  // Extra scaffold files
+  // Extra scaffold files (already have harness/ prefix from getExtraFiles)
   for (const relPath of Object.keys(extraFiles)) {
     harnessPaths.push(join(targetDir, relPath));
   }
@@ -190,8 +190,8 @@ export default async function initCommand(args) {
   // Ensure target directory exists
   mkdirSync(targetDir, { recursive: true });
 
-  // Ensure docs/ directory exists
-  mkdirSync(join(targetDir, 'docs'), { recursive: true });
+  // Ensure harness/ directory exists (all harness files go here)
+  mkdirSync(join(targetDir, 'harness'), { recursive: true });
 
   const created = [];
   const errors = [];
@@ -289,15 +289,15 @@ export default async function initCommand(args) {
       }
     }
 
-    // Set agentTool in the generated harness-config.json
-    const configPath = join(targetDir, 'harness-config.json');
+    // Set agentTool in the generated harness/config.json
+    const configPath = join(targetDir, 'harness', 'config.json');
     if (existsSync(configPath)) {
       try {
         const cfg = JSON.parse(readFileSync(configPath, 'utf-8'));
         cfg.agentTool = agentTool;
         writeFileSync(configPath, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
       } catch (err) {
-        errors.push(`harness-config.json agentTool: ${err.message}`);
+        errors.push(`harness/config.json agentTool: ${err.message}`);
       }
     }
   }

package/cli/commands/rollback.mjs

@@ -161,9 +161,9 @@ export default async function rollbackCommand(args) {
 
     // Restore all files from the checkpoint
     const restoreFiles = [
-      'harness-config.json',
-      'progress.md',
-      'feature_list.json',
+      'harness/config.json',
+      'harness/progress.md',
+      'harness/features/feature-list.json',
     ];
 
     // First, restore the whole working tree from the tag

package/cli/commands/status.mjs

@@ -61,7 +61,7 @@ export default async function statusCommand(args) {
       status: 'ok',
       message: configOk
         ? `Phase: ${phase || 'not started'}, Stack: ${stack.label}`
-        : 'No harness-config.json found — run harness-dev init',
+        : 'No harness/config.json found — run harness-dev init',
       project: basename(targetDir),
       stack: stack.name,
       stackLabel: stack.label,
@@ -84,7 +84,7 @@ export default async function statusCommand(args) {
 
   // ── Human-readable output ─────────────────────────────────────────────
   let out = '';
-  out += '═══ dev-harness Status ═══\n';
+  out += '═══ harness Status ═══\n';
   out += line('Project:', basename(targetDir)) + '\n';
   out += line('Stack:', `${stack.label}${stack.name !== 'generic' ? '' : ' (not detected)'}`) + '\n';
   out += line('Mode:', modeLabel(mode)) + '\n';
@@ -104,7 +104,7 @@ export default async function statusCommand(args) {
     out += '  Phase: not started.\n';
     out += '\n';
   } else {
-    out += '  No harness-config.json found.\n';
+    out += '  No harness/config.json found.\n';
     out += '\n';
   }
 

package/cli/lib/gates.mjs

@@ -18,6 +18,7 @@ import { loadConfig } from './state.mjs';
 import { getStackMeta, detectStack } from './detect-stack.mjs';
 import { validateContract } from './contract.mjs';
 import { execGitCheck as execCheck } from './git.mjs';
+import { CONFIG_PATH, RUBRIC_PATH, ARCHITECTURE_PATH, DECISIONS_PATH, HARNESS_DIR } from './paths.mjs';
 import { COVERAGE_TIMEOUT, COVERAGE_THRESHOLD_DEFAULT } from './constants.mjs';
 
 function getStackLabel(targetDir) {
@@ -38,19 +39,20 @@ function checkGitRepo(targetDir) {
 }
 
 function checkConfigExists(targetDir) {
-  const cfgPath = resolve(targetDir, 'harness-config.json');
+  const cfgPath = CONFIG_PATH(targetDir);
   const exists = existsSync(cfgPath);
   return {
     name: 'config-exists',
     pass: exists,
-    detail: exists ? 'harness-config.json present' : 'Missing: harness-config.json',
+    detail: exists ? 'harness/config.json present' : 'Missing: harness/config.json',
   };
 }
 
 function checkInitExecutable(targetDir) {
+  // init.sh is now at harness/scripts/init.sh
+  const initSh = resolve(HARNESS_DIR(targetDir), 'scripts', 'init.sh');
   // Windows has no POSIX executable bit — skip the exec-bit check there.
   if (process.platform === 'win32') {
-    const initSh = resolve(targetDir, 'init.sh');
     return {
       name: 'init-executable',
       pass: existsSync(initSh),
@@ -58,7 +60,7 @@ function checkInitExecutable(targetDir) {
     };
   }
   try {
-    const { exitCode } = execCheck('test -x init.sh', targetDir);
+    const { exitCode } = execCheck(`test -x "${initSh}"`, targetDir);
     return {
       name: 'init-executable',
       pass: exitCode === 0,
@@ -177,11 +179,11 @@ function checkContractAgreed(targetDir) {
 
 /** Check that evaluator-rubric.md exists in the project. */
 function checkRubricExists(targetDir) {
-  const found = existsSync(resolve(targetDir, 'evaluator-rubric.md'));
+  const found = existsSync(RUBRIC_PATH(targetDir));
   return {
     name: 'rubric-exists',
     pass: found,
-    detail: found ? 'evaluator-rubric.md found' : 'evaluator-rubric.md missing — run init to scaffold',
+    detail: found ? 'harness/evaluator-rubric.md found' : 'harness/evaluator-rubric.md missing — run init to scaffold',
   };
 }
 
@@ -291,7 +293,7 @@ function checkChangelogContent(targetDir) {
 
 /** Check that ARCHITECTURE.md is filled in (if file exists, not just stub). */
 function checkArchitectureDoc(targetDir) {
-  const archPath = resolve(targetDir, 'ARCHITECTURE.md');
+  const archPath = ARCHITECTURE_PATH(targetDir);
   if (!existsSync(archPath)) {
     return { name: 'architecture-doc', pass: true, detail: 'ARCHITECTURE.md not present (optional)' };
   }
@@ -304,7 +306,7 @@ function checkArchitectureDoc(targetDir) {
 
 /** Check that DECISIONS.md has at least one recorded decision (if file exists). */
 function checkDecisionsLogged(targetDir) {
-  const decPath = resolve(targetDir, 'DECISIONS.md');
+  const decPath = DECISIONS_PATH(targetDir);
   if (!existsSync(decPath)) {
     return { name: 'decisions-logged', pass: true, detail: 'DECISIONS.md not present (optional)' };
   }

package/cli/lib/help.mjs

@@ -53,7 +53,7 @@ Exit codes:
   2  Usage error (bad arguments)
   3  Internal error`;
 
-const VERSION = '1.0.3';
+const VERSION = '1.1.0';
 
 // Help text for JSON output
 function buildJsonHelp() {

package/cli/lib/paths.mjs

@@ -37,39 +37,118 @@ export const FEATURE_LIST_SCHEMA_PATH = resolve(SCHEMA_DIR, 'feature-list.schema
 export const STACKS_SCHEMA_PATH = resolve(LIB_DIR, 'schemas', 'stacks.json');
 
 // ── Project-relative paths (target project, not this CLI) ────────────────────
+// All harness-managed files live under harness/ with subfolder grouping:
+//   harness/              — config, progress, contract, rubric, handoff, checklist
+//   harness/features/     — feature list + schema
+//   harness/docs/         — architecture, constraints, decisions, agent docs, phase docs
+//   harness/ci/           — CI/CD templates
+//   harness/scripts/      — init scripts
+// AGENTS.md stays in root (agent tools expect it there).
 
 /**
- * Path to a project's harness-config.json.
+ * Harness root directory within a target project.
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function HARNESS_DIR(targetDir) {
+  return resolve(targetDir, 'harness');
+}
+
+/**
+ * Path to a project's config.json (harness/config.json).
  * @param {string} targetDir
  * @returns {string}
  */
 export function CONFIG_PATH(targetDir) {
-  return resolve(targetDir, 'harness-config.json');
+  return resolve(HARNESS_DIR(targetDir), 'config.json');
 }
 
 /**
- * Path to a project's feature_list.json.
+ * Path to a project's feature-list.json (harness/features/feature-list.json).
  * @param {string} targetDir
  * @returns {string}
  */
 export function FEATURE_LIST_PATH(targetDir) {
-  return resolve(targetDir, 'feature_list.json');
+  return resolve(HARNESS_DIR(targetDir), 'features', 'feature-list.json');
 }
 
 /**
- * Path to a project's sprint-contract.md.
+ * Path to a project's sprint-contract.md (harness/sprint-contract.md).
  * @param {string} targetDir
  * @returns {string}
  */
 export function CONTRACT_PATH(targetDir) {
-  return resolve(targetDir, 'sprint-contract.md');
+  return resolve(HARNESS_DIR(targetDir), 'sprint-contract.md');
 }
 
 /**
- * Path to a project's progress.md.
+ * Path to a project's progress.md (harness/progress.md).
  * @param {string} targetDir
  * @returns {string}
  */
 export function PROGRESS_PATH(targetDir) {
-  return resolve(targetDir, 'progress.md');
+  return resolve(HARNESS_DIR(targetDir), 'progress.md');
+}
+
+/**
+ * Path to a project's evaluator-rubric.md (harness/evaluator-rubric.md).
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function RUBRIC_PATH(targetDir) {
+  return resolve(HARNESS_DIR(targetDir), 'evaluator-rubric.md');
+}
+
+/**
+ * Path to a project's session-handoff.md (harness/session-handoff.md).
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function HANDOFF_PATH(targetDir) {
+  return resolve(HARNESS_DIR(targetDir), 'session-handoff.md');
+}
+
+/**
+ * Path to a project's clean-state-checklist.md (harness/clean-state-checklist.md).
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function CHECKLIST_PATH(targetDir) {
+  return resolve(HARNESS_DIR(targetDir), 'clean-state-checklist.md');
+}
+
+/**
+ * Path to a project's ARCHITECTURE.md (harness/docs/ARCHITECTURE.md).
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function ARCHITECTURE_PATH(targetDir) {
+  return resolve(HARNESS_DIR(targetDir), 'docs', 'ARCHITECTURE.md');
+}
+
+/**
+ * Path to a project's CONSTRAINTS.md (harness/docs/CONSTRAINTS.md).
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function CONSTRAINTS_PATH(targetDir) {
+  return resolve(HARNESS_DIR(targetDir), 'docs', 'CONSTRAINTS.md');
+}
+
+/**
+ * Path to a project's DECISIONS.md (harness/docs/DECISIONS.md).
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function DECISIONS_PATH(targetDir) {
+  return resolve(HARNESS_DIR(targetDir), 'docs', 'DECISIONS.md');
+}
+
+/**
+ * Path to a project's AGENTS.md (stays in root — agent tools expect it there).
+ * @param {string} targetDir
+ * @returns {string}
+ */
+export function AGENTS_PATH(targetDir) {
+  return resolve(targetDir, 'AGENTS.md');
 }

package/cli/lib/scaffold.mjs

@@ -212,12 +212,13 @@ work/
 // ── Extra scaffolding files (not covered by templates) ───────────────────────
 
 /**
- * Inline content for files beyond the 5 template-based ones.
- * Key is relative output path, value is file content.
+ * Inline content for files beyond the template-based ones.
+ * Key is relative output path (under harness/), value is file content.
+ * All harness-managed files go under harness/ with subfolder grouping.
  */
 export function getExtraFiles(stack) {
   return {
-    'feature_list.json': JSON.stringify({
+    'harness/features/feature-list.json': JSON.stringify({
       version: '0.1',
       features: [
         {
@@ -232,7 +233,7 @@ export function getExtraFiles(stack) {
       ],
     }, null, 2) + '\n',
 
-    'feature-list.schema.json': JSON.stringify({
+    'harness/features/feature-list.schema.json': JSON.stringify({
       $schema: 'http://json-schema.org/draft-07/schema#',
       title: 'Feature List',
       type: 'object',
@@ -266,7 +267,7 @@ export function getExtraFiles(stack) {
       },
     }, null, 2) + '\n',
 
-    'session-handoff.md': `# Session Handoff
+    'harness/session-handoff.md': `# Session Handoff
 
 ## Context
 
@@ -296,7 +297,7 @@ export function getExtraFiles(stack) {
 | ... | ... |
 `,
 
-    'clean-state-checklist.md': `# Clean State Checklist
+    'harness/clean-state-checklist.md': `# Clean State Checklist
 
 Run this before starting any phase to ensure deterministic state.
 
@@ -308,10 +309,10 @@ Run this before starting any phase to ensure deterministic state.
 
 ## Harness
 
-- [ ] \`harness-config.json\` exists and valid
+- [ ] \`harness/config.json\` exists and valid
 - [ ] Current phase matches what we're about to run
-- [ ] \`progress.md\` has latest Session State
-- [ ] \`feature_list.json\` up-to-date
+- [ ] \`harness/progress.md\` has latest Session State
+- [ ] \`harness/features/feature-list.json\` up-to-date
 
 ## Environment
 
@@ -320,7 +321,7 @@ Run this before starting any phase to ensure deterministic state.
 - [ ] No stale background processes
 `,
 
-    'ARCHITECTURE.md': `# Architecture
+    'harness/docs/ARCHITECTURE.md': `# Architecture
 
 ## Module Structure
 
@@ -330,7 +331,7 @@ src/
 \`\`\`
 `,
 
-    'CONSTRAINTS.md': `# Constraints
+    'harness/docs/CONSTRAINTS.md': `# Constraints
 
 ## Technical
 
@@ -351,7 +352,7 @@ src/
 - Fail fast, fail loud
 `,
 
-    'DECISIONS.md': `# Decisions
+    'harness/docs/DECISIONS.md': `# Decisions
 
 <!-- Record architectural and design decisions here. Use the format below. -->
 
@@ -372,7 +373,7 @@ src/
 | | | |
 `,
 
-    'docs/api-patterns.md': `# API Patterns
+    'harness/docs/api-patterns.md': `# API Patterns
 
 ## Conventions
 
@@ -417,11 +418,10 @@ export function getVersionFileContent(stack) {
  * Return .gitignore content for the given stack.
  */
 export function getGitignoreContent(stack) {
-  return `# Harness scaffold
-harness-config.json
-feature_list.json
-feature-list.schema.json
-progress.md
+  return `# Harness runtime state (regenerated by harness-dev)
+harness/config.json
+harness/features/feature-list.json
+harness/progress.md
 
 ${GITIGNORE_PATTERNS[stack] || GITIGNORE_PATTERNS.generic}
 # OS

package/cli/lib/templates.mjs

@@ -111,6 +111,42 @@ export function discoverTemplates() {
   }
 }
 
+/**
+ * Map a template's relative path to its output path under harness/.
+ * Templates that are harness-managed go into harness/ subfolders.
+ * AGENTS.md stays in project root (agent tools expect it there).
+ *
+ * Mapping:
+ *   AGENTS.md                  → AGENTS.md (root)
+ *   harness-config.json        → harness/config.json
+ *   progress.md                → harness/progress.md
+ *   sprint-contract.md         → harness/sprint-contract.md
+ *   evaluator-rubric.md        → harness/evaluator-rubric.md
+ *   init.sh / init.ps1         → harness/scripts/init.sh
+ *   ci/*                       → harness/ci/*
+ *   docs/*                     → harness/docs/*
+ *
+ * @param {string} relPath — relative path within templates/
+ * @returns {string} — relative output path within target
+ */
+function mapTemplateOutput(relPath) {
+  // AGENTS.md stays in root
+  if (relPath === 'AGENTS.md') return relPath;
+  // harness-config.json → harness/config.json
+  if (relPath === 'harness-config.json') return 'harness/config.json';
+  // Top-level harness files → harness/
+  const harnessRootFiles = ['progress.md', 'sprint-contract.md', 'evaluator-rubric.md'];
+  if (harnessRootFiles.includes(relPath)) return `harness/${relPath}`;
+  // init scripts → harness/scripts/
+  if (relPath === 'init.sh' || relPath === 'init.ps1') return `harness/scripts/${relPath}`;
+  // ci/ → harness/ci/
+  if (relPath.startsWith('ci/')) return `harness/${relPath}`;
+  // docs/ → harness/docs/
+  if (relPath.startsWith('docs/')) return `harness/${relPath}`;
+  // Default: put under harness/
+  return `harness/${relPath}`;
+}
+
 /**
  * Run the template engine.
  *
@@ -147,7 +183,8 @@ export function generateTemplates(opts) {
     const relativePath = tmplPath.startsWith(TEMPLATES_DIR + '/')
       ? tmplPath.slice(TEMPLATES_DIR.length + 1)
       : basename(tmplPath);
-    const outPath = join(target, relativePath);
+    const outputRel = mapTemplateOutput(relativePath);
+    const outPath = join(target, outputRel);
     const outDir = dirname(outPath);
 
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dev-harness-cli",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "description": "Agent-agnostic software development harness CLI — scaffold, phase orchestration, gate validation for any coding agent",
   "type": "module",
   "bin": {
@@ -37,7 +37,11 @@
     "cli"
   ],
   "scripts": {
+    "lint": "eslint cli/",
+    "lint:fix": "eslint cli/ --fix",
     "check": "node --check cli/harness-dev.mjs && echo 'Syntax OK'",
+    "test": "node test/run-all.mjs",
+    "test:verbose": "node test/run-all.mjs --verbose",
     "postinstall": "node -e \"try{process.stdout.write('harness-dev installed. Run: npx harness-dev --help\\n')}catch(e){}\""
   },
   "devDependencies": {

package/schema/feature-list.schema.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Feature List",
+  "description": "Schema for feature_list.json — tracks features and their tasks through the pipeline",
+  "type": "object",
+  "required": ["version", "features"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "description": "Schema version",
+      "default": "0.1"
+    },
+    "features": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "passes", "tasks"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Unique feature identifier (e.g. feature-001)"
+          },
+          "name": {
+            "type": "string",
+            "description": "Human-readable feature name"
+          },
+          "description": {
+            "type": "string",
+            "description": "Optional feature description"
+          },
+          "passes": {
+            "type": "boolean",
+            "default": false,
+            "description": "All tasks completed and verified"
+          },
+          "tasks": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["id", "description", "status"],
+              "properties": {
+                "id": {
+                  "type": "string",
+                  "description": "Unique task identifier"
+                },
+                "description": {
+                  "type": "string",
+                  "description": "Task description"
+                },
+                "status": {
+                  "type": "string",
+                  "enum": ["pending", "in_progress", "complete", "blocked"],
+                  "default": "pending",
+                  "description": "Task status"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/templates/AGENTS.md

@@ -18,7 +18,7 @@ harness-dev validate      # Check gate criteria
 
 INIT → DEFINE → PLAN → BUILD → VERIFY → [SIMPLIFY] → REVIEW → SHIP
 
-See `docs/phases/` for phase-specific instructions.
+See `harness/docs/phases/` for phase-specific instructions.
 
 ## Agent Roles
 
@@ -31,21 +31,25 @@ See `docs/phases/` for phase-specific instructions.
 
 ## Key Files
 
+All harness-managed files live under `harness/` (except `AGENTS.md` which stays in root for agent tool compatibility).
+
 | 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) |
-|
+| `AGENTS.md` | This file — agent instructions (root) |
+| `harness/config.json` | Config + state |
+| `harness/features/feature-list.json` | Feature list with passes |
+| `harness/progress.md` | Session state + lessons |
+| `harness/sprint-contract.md` | Pre-build agreement |
+| `harness/scripts/init.sh` | Install → verify → start |
+| `harness/evaluator-rubric.md` | Quality scorecard (6 dimensions, 0-2) |
+| `harness/docs/` | Architecture, constraints, decisions, agent guides, phase guides |
+
 ## Rules (non-negotiable)
 
 1. No agent evaluates its own work — Evaluator always judges
-2. Read `progress.md` + this file before each operation
+2. Read `harness/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/`
+4. If unsure → read the role guide in `harness/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.

package/templates/ci/github-actions.yml

@@ -74,5 +74,5 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - run: npm install -g @dev-harness/cli
+      - run: npm install -g dev-harness-cli
       - run: harness-dev validate --json

package/templates/ci/gitlab-ci.yml

@@ -54,6 +54,6 @@ gate:
   stage: gate
   image: node:lts
   script:
-    - npm install -g @dev-harness/cli
+    - npm install -g dev-harness-cli
     - harness-dev validate --json
   needs: [coverage]

package/templates/docs/agents/planner.md

@@ -9,5 +9,5 @@ You design the approach. You write criteria. You set scope.
 - 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
+- In PLAN: decompose features into tasks in harness/features/feature-list.json
 - Review gate criteria with Evaluator before proceeding

package/templates/harness-config.json

@@ -0,0 +1,42 @@
+{
+  "version": "1.0",
+  "stack": "{{stack}}",
+  "stackMeta": null,
+  "agentTool": null,
+  "mode": "copilot",
+  "currentPhase": null,
+  "paused": false,
+  "features": {
+    "remaining": 0,
+    "passing": 0,
+    "total": 0
+  },
+  "gates": {
+    "enabled": false,
+    "checks": ["all"]
+  },
+  "git": {
+    "autoCommit": false,
+    "autoTag": false,
+    "resetOnRetry": false,
+    "branch": null,
+    "clean": true,
+    "hasUpstream": false,
+    "lastCommitMessage": null
+  },
+  "phases": {
+    "enabled": ["define", "plan", "build", "verify", "review", "ship"]
+  },
+  "agents": {
+    "tone": {
+      "planner": "Analytical and precise. Define clear boundaries.",
+      "generator": "Focused and practical. Build what's specified, nothing more.",
+      "evaluator": "Skeptical and thorough. Accept only compelling evidence.",
+      "simplifier": "Relentless about clarity. Delete more than you add."
+    }
+  },
+  "maxRetries": 3,
+  "retryCount": 0,
+  "pipelineIteration": 0,
+  "gateHistory": []
+}

package/templates/progress.md

@@ -0,0 +1,18 @@
+# Progress: {{stackLabel}}
+
+## Session State
+
+Current Phase: not started
+Current Feature: —
+Gate Status: pending
+Next Action: —
+Retry Count: 0/{{maxRetries}}
+
+## Lessons
+
+<!-- Use \`harness-dev learn "lesson here"\` to add lessons. -->
+
+## Checkpoints
+
+| Tag | Phase | Date | Notes |
+|-----|-------|------|-------|