dev-harness-cli 1.2.0 โ 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +501 -121
- package/cli/lib/constants.mjs +19 -2
- package/package.json +10 -1
package/README.md
CHANGED
|
@@ -1,62 +1,241 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
# Dev Harness
|
|
3
|
+
# ๐ฏ Dev Harness
|
|
4
4
|
|
|
5
|
-
### Agent-
|
|
5
|
+
### *Agent-Agnostic Development Pipeline CLI*
|
|
6
6
|
|
|
7
|
-
Scaffold ยท Phase
|
|
7
|
+
**Scaffold ยท Phase Orchestration ยท Gate Validation ยท Iterative Refinement**
|
|
8
8
|
|
|
9
|
-
[](https://www.npmjs.com/package/dev-harness-cli)
|
|
10
|
-
[](https://opensource.org/licenses/MIT)
|
|
11
|
-
[](https://www.npmjs.com/package/dev-harness-cli)
|
|
10
|
+
[](https://opensource.org/licenses/MIT)
|
|
11
|
+
[](https://nodejs.org)
|
|
12
|
+
[](#-dependencies)
|
|
13
|
+
[](#)
|
|
14
|
+
[](#)
|
|
13
15
|
|
|
14
|
-
**Works with any coding agent
|
|
16
|
+
๐งฐ **Works with any coding agent โ IDE or TUI**
|
|
17
|
+
|
|
18
|
+
`Claude Code` ยท `Cursor` ยท `Windsurf` ยท `GitHub Copilot` ยท `Gemini CLI` ยท `Codex CLI` ยท `Cline` ยท `Roo Code` ยท `Kilo Code` ยท `Amazon Q Developer` ยท `OpenCode` ยท `Continue` ยท `Aider` ยท `Hermes` ยท `OpenClaw` ยท `Antigravity` ยท `Pi` ยท and more
|
|
15
19
|
|
|
16
20
|
</div>
|
|
17
21
|
|
|
18
22
|
---
|
|
19
23
|
|
|
20
|
-
##
|
|
24
|
+
## ๐ Table of Contents
|
|
25
|
+
|
|
26
|
+
- [๐ค What Is This?](#-what-is-this)
|
|
27
|
+
- [๐ Quick Start](#-quick-start)
|
|
28
|
+
- [๐ User Guide](#-user-guide)
|
|
29
|
+
- [๐ฅ๏ธ IDE-Based Agentic Tools](#๏ธ-ide-based-agentic-tools)
|
|
30
|
+
- [๐ป TUI-Based Agentic Tools](#-tui-based-agentic-tools)
|
|
31
|
+
- [๐ง How It Works](#-how-it-works)
|
|
32
|
+
- [Pipeline Phases](#pipeline-phases)
|
|
33
|
+
- [Gate Validation](#gate-validation)
|
|
34
|
+
- [Ralph Inner / Outer Loops](#ralph-inner--outer-loops)
|
|
35
|
+
- [Multi-Agent Committee Review](#multi-agent-committee-review)
|
|
36
|
+
- [๐ Project Structure](#-project-structure)
|
|
37
|
+
- [โ๏ธ CLI Reference](#๏ธ-cli-reference)
|
|
38
|
+
- [๐ง Configuration](#-configuration)
|
|
39
|
+
- [๐ค JSON Output](#-json-output)
|
|
40
|
+
- [๐ Acknowledgements & Influences](#-acknowledgements--influences)
|
|
41
|
+
- [๐ License](#-license)
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## ๐ค What Is This?
|
|
46
|
+
|
|
47
|
+
**Dev Harness** is a CLI tool that brings **deterministic structure** to AI-assisted software development. Instead of ad-hoc prompting โ where agents hallucinate scope, skip steps, or rubber-stamp their own work โ Dev Harness enforces a **phase pipeline** with **gate validation**.
|
|
48
|
+
|
|
49
|
+
> ๐ฏ **Specs before code. Review before shipping. Nothing skipped.**
|
|
50
|
+
|
|
51
|
+
```mermaid
|
|
52
|
+
flowchart LR
|
|
53
|
+
DEFINE[๐ DEFINE] --> PLAN[๐ PLAN]
|
|
54
|
+
PLAN --> BUILD[๐ ๏ธ BUILD]
|
|
55
|
+
BUILD --> VERIFY[โ
VERIFY]
|
|
56
|
+
VERIFY -.-> SIMPLIFY[๐งน SIMPLIFY]
|
|
57
|
+
VERIFY --> REVIEW[๐ REVIEW]
|
|
58
|
+
SIMPLIFY --> REVIEW
|
|
59
|
+
REVIEW --> SHIP[๐ SHIP]
|
|
60
|
+
|
|
61
|
+
style DEFINE fill:#4A90D9,color:#fff,stroke:none
|
|
62
|
+
style PLAN fill:#50C878,color:#fff,stroke:none
|
|
63
|
+
style BUILD fill:#FF8C42,color:#fff,stroke:none
|
|
64
|
+
style VERIFY fill:#9B59B6,color:#fff,stroke:none
|
|
65
|
+
style SIMPLIFY fill:#F1C40F,color:#333,stroke:none
|
|
66
|
+
style REVIEW fill:#E74C3C,color:#fff,stroke:none
|
|
67
|
+
style SHIP fill:#2ECC71,color:#fff,stroke:none
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Each phase has **deterministic gates** โ automated checks that must pass before the pipeline can advance. The agent does the work; the harness validates the result. No more wondering if the agent actually finished what it said it did.
|
|
71
|
+
|
|
72
|
+
### โจ Key Features
|
|
73
|
+
|
|
74
|
+
| | Feature | Description |
|
|
75
|
+
|---|---------|-------------|
|
|
76
|
+
| ๐งฉ | **Agent-Agnostic** | Works with 18+ agentic coding tools โ IDE extensions and TUI agents alike |
|
|
77
|
+
| ๐ฆ | **Phase Pipeline** | 7-phase workflow: Define โ Plan โ Build โ Verify โ Simplify โ Review โ Ship |
|
|
78
|
+
| ๐ง | **Gate Validation** | Every phase has deterministic pass/fail checks โ no skipping steps |
|
|
79
|
+
| ๐ | **Ralph Loops** | Inner/outer iterative loops with fresh-context retry (inspired by [ghuntley.com/ralph](https://ghuntley.com/ralph)) |
|
|
80
|
+
| ๐งโโ๏ธ | **Multi-Agent Review** | Committee of agent personas (Planner, Generator, Evaluator, Simplifier) prevents self-evaluation leniency |
|
|
81
|
+
| ๐ | **Sprint Contracts** | Pre-build negotiation between agent personas for spec/code agreement |
|
|
82
|
+
| ๐๏ธ | **31+ Stack Templates** | Python, Node.js, Go, Rust, C, C++, Java, Kotlin, .NET, Ruby, PHP, Swift, Elixir, and many more |
|
|
83
|
+
| ๐ญ | **Custom Stacks** | Unlimited custom language/platform support via `config.stackMeta` |
|
|
84
|
+
| ๐ฆ | **Minimal Dependencies** | Curated runtime deps (ajv, simple-git, ink, p-retry, picocolors, string-width) โ each chosen for a concrete robustness win |
|
|
21
85
|
|
|
22
|
-
|
|
86
|
+
---
|
|
87
|
+
|
|
88
|
+
## ๐๏ธ Architecture
|
|
89
|
+
|
|
90
|
+
Dev Harness is a layered CLI: argument parsing โ command routing โ library modules โ file/state I/O. The diagrams below show how the pieces fit together.
|
|
91
|
+
|
|
92
|
+
### System Architecture
|
|
93
|
+
|
|
94
|
+
```mermaid
|
|
95
|
+
flowchart TD
|
|
96
|
+
User([User / Agent]) -->|dev-harness <cmd>| CLI[cli/dev-harness.mjs<br/>Entry + routing]
|
|
97
|
+
CLI -->|parse| Args[lib/args.mjs<br/>Argument parser]
|
|
98
|
+
CLI -->|dispatch| Cmds[cli/commands/*.mjs<br/>17 command handlers]
|
|
99
|
+
Cmds -->|use| Lib[cli/lib/*.mjs<br/>30+ library modules]
|
|
100
|
+
Lib -->|read/write| State[(harness/config.json<br/>+ feature-list.json<br/>+ progress.md)]
|
|
101
|
+
Lib -->|git ops| Git[lib/git.mjs<br/>simple-git async]
|
|
102
|
+
Lib -->|validate| Gates[lib/gates.mjs<br/>Phase gate checks]
|
|
103
|
+
Lib -->|iterate| Ralph[lib/ralph-inner.mjs<br/>lib/ralph-outer.mjs]
|
|
104
|
+
Lib -->|spawn| Supervisor[lib/supervisor.mjs<br/>Orchestrator + p-retry]
|
|
105
|
+
Supervisor -->|render| TUI[tui/dashboard.mjs<br/>Ink live dashboard]
|
|
106
|
+
Cmds -->|scaffold| Templates[templates/<br/>31 stack templates]
|
|
107
|
+
Cmds -->|detect| Stacks[lib/detect-stack.mjs<br/>Stack detection]
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
### 7-Phase Pipeline
|
|
111
|
+
|
|
112
|
+
```mermaid
|
|
113
|
+
flowchart LR
|
|
114
|
+
INIT[INIT<br/>Scaffold] --> DEFINE[DEFINE<br/>Specs + contract]
|
|
115
|
+
DEFINE --> PLAN[PLAN<br/>Architecture]
|
|
116
|
+
PLAN --> BUILD[BUILD<br/>Implement features]
|
|
117
|
+
BUILD --> VERIFY[VERIFY<br/>Tests + coverage]
|
|
118
|
+
VERIFY --> SIMPLIFY[SIMPLIFY<br/>Refactor]
|
|
119
|
+
SIMPLIFY --> REVIEW[REVIEW<br/>Multi-agent committee]
|
|
120
|
+
REVIEW --> SHIP[SHIP<br/>Tag + release]
|
|
121
|
+
style SIMPLIFY fill:#fef3c7,stroke:#d97706,stroke-dasharray: 5 5
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
> `SIMPLIFY` is opt-in (excluded from default phase order). Each phase has deterministic gate checks โ no skipping.
|
|
125
|
+
|
|
126
|
+
### Ralph Inner/Outer Loop
|
|
127
|
+
|
|
128
|
+
The Ralph pattern drives iterative refinement. The **outer loop** advances phases; the **inner loop** iterates features/tasks within a phase, retrying with fresh git context on failure.
|
|
129
|
+
|
|
130
|
+
```mermaid
|
|
131
|
+
stateDiagram-v2
|
|
132
|
+
[*] --> Idle
|
|
133
|
+
Idle --> Running: phase <name>
|
|
134
|
+
state Running {
|
|
135
|
+
[*] --> LoadConfig
|
|
136
|
+
LoadConfig --> CheckRetries
|
|
137
|
+
CheckRetries --> Escalated: retries >= max
|
|
138
|
+
CheckRetries --> GitReset: retry & --git-ops
|
|
139
|
+
GitReset --> PickTask
|
|
140
|
+
CheckRetries --> PickTask: fresh run
|
|
141
|
+
PickTask --> FeatureIterate: build/verify/simplify
|
|
142
|
+
PickTask --> DeliverableRetry: init/define/plan/review/ship
|
|
143
|
+
FeatureIterate --> Instruction: next task
|
|
144
|
+
DeliverableRetry --> Instruction: produce deliverable
|
|
145
|
+
Instruction --> [*]: agent validates
|
|
146
|
+
}
|
|
147
|
+
Running --> Complete: all features pass
|
|
148
|
+
Running --> Escalated: retries exhausted
|
|
149
|
+
Complete --> [*]
|
|
150
|
+
Escalated --> [*]
|
|
151
|
+
```
|
|
23
152
|
|
|
153
|
+
### Orchestrator (Supervisor) Data Flow
|
|
154
|
+
|
|
155
|
+
`dev-harness run` spawns an agent per task, monitors it, retries on API downtime, and renders a live dashboard.
|
|
156
|
+
|
|
157
|
+
```mermaid
|
|
158
|
+
flowchart TD
|
|
159
|
+
Start([dev-harness run]) --> Loop{Pipeline<br/>complete?}
|
|
160
|
+
Loop -->|no| Heartbeat[Record heartbeat]
|
|
161
|
+
Heartbeat --> BuildPrompt[Build task prompt]
|
|
162
|
+
BuildPrompt --> HasTask{Task<br/>available?}
|
|
163
|
+
HasTask -->|no| Advance[continuePipeline]
|
|
164
|
+
Advance --> Loop
|
|
165
|
+
HasTask -->|yes| Spawn[spawnAgent<br/>fresh session]
|
|
166
|
+
Spawn --> Wait[waitForCompletion]
|
|
167
|
+
Wait --> ExitCode{exit code}
|
|
168
|
+
ExitCode -->|0| Validate[runChecks]
|
|
169
|
+
Validate --> Pass{gates pass?}
|
|
170
|
+
Pass -->|yes| MarkDone[Mark task complete]
|
|
171
|
+
MarkDone --> Loop
|
|
172
|
+
Pass -->|no| RetryTask[Increment taskRetry]
|
|
173
|
+
RetryTask --> Loop
|
|
174
|
+
ExitCode -->|non-zero| ApiError{API error?}
|
|
175
|
+
ApiError -->|yes| Backoff[p-retry<br/>exponential backoff]
|
|
176
|
+
Backoff -->|recovered| Validate
|
|
177
|
+
Backoff -->|exhausted| Pause[Pause pipeline]
|
|
178
|
+
ApiError -->|no| RetryTask
|
|
179
|
+
Pause --> End([Paused โ resume on recovery])
|
|
180
|
+
Loop -->|yes| End2([Pipeline complete])
|
|
24
181
|
```
|
|
25
|
-
|
|
182
|
+
|
|
183
|
+
### Tier-1 vs Tier-2 Agent Integration
|
|
184
|
+
|
|
185
|
+
```mermaid
|
|
186
|
+
flowchart TB
|
|
187
|
+
subgraph Tier1[Tier 1 โ Orchestrator Mode]
|
|
188
|
+
direction LR
|
|
189
|
+
CLI1[dev-harness run] --> Spawn1[spawnAgent per task]
|
|
190
|
+
Spawn1 --> Hermes[Hermes]
|
|
191
|
+
Spawn1 --> OpenClaw[OpenClaw]
|
|
192
|
+
Spawn1 --> ClaudeCode[Claude Code]
|
|
193
|
+
end
|
|
194
|
+
subgraph Tier2[Tier 2 โ Instruction Mode]
|
|
195
|
+
direction LR
|
|
196
|
+
CLI2[dev-harness phase <name>] --> Write[Write AGENTS.md<br/>+ task instructions]
|
|
197
|
+
Write --> Cursor[Cursor]
|
|
198
|
+
Write --> Copilot[Copilot]
|
|
199
|
+
Write --> Windsurf[Windsurf]
|
|
200
|
+
Write --> Gemini[Gemini]
|
|
201
|
+
Write --> OtherIDE[...14 more IDE tools]
|
|
202
|
+
end
|
|
26
203
|
```
|
|
27
204
|
|
|
28
|
-
|
|
205
|
+
> **Tier 1** tools are spawnable TUI agents โ dev-harness runs them per task with fresh sessions and API retry. **Tier 2** tools are IDE extensions โ dev-harness writes instructions and the agent reads them natively.
|
|
206
|
+
|
|
207
|
+
---
|
|
29
208
|
|
|
30
|
-
##
|
|
209
|
+
## ๐ Quick Start
|
|
31
210
|
|
|
32
211
|
```bash
|
|
33
|
-
#
|
|
212
|
+
# ๐ One-liner โ no install needed
|
|
34
213
|
npx dev-harness-cli init --stack python --target my-project
|
|
35
214
|
|
|
36
|
-
# Global install
|
|
215
|
+
# ๐ฆ Global install
|
|
37
216
|
npm install -g dev-harness-cli
|
|
38
217
|
dev-harness --help
|
|
39
218
|
```
|
|
40
219
|
|
|
41
|
-
Requires
|
|
220
|
+
> **Requires Node.js >= 18.** Minimal, audited runtime dependencies.
|
|
42
221
|
|
|
43
|
-
|
|
222
|
+
### Your First Pipeline
|
|
44
223
|
|
|
45
224
|
```bash
|
|
46
|
-
# 1
|
|
225
|
+
# 1๏ธโฃ Scaffold a new project
|
|
47
226
|
dev-harness init --stack node --target my-app
|
|
48
227
|
cd my-app
|
|
49
228
|
|
|
50
|
-
# 2
|
|
229
|
+
# 2๏ธโฃ Check your status
|
|
51
230
|
dev-harness status
|
|
52
231
|
|
|
53
|
-
# 3
|
|
232
|
+
# 3๏ธโฃ Run the DEFINE phase (agent writes specs)
|
|
54
233
|
dev-harness phase define
|
|
55
234
|
|
|
56
|
-
# 4
|
|
235
|
+
# 4๏ธโฃ Validate โ run gate checks
|
|
57
236
|
dev-harness validate
|
|
58
237
|
|
|
59
|
-
# 5
|
|
238
|
+
# 5๏ธโฃ Advance through the pipeline
|
|
60
239
|
dev-harness phase plan
|
|
61
240
|
dev-harness phase build
|
|
62
241
|
dev-harness phase verify
|
|
@@ -64,38 +243,225 @@ dev-harness phase review
|
|
|
64
243
|
dev-harness phase ship
|
|
65
244
|
```
|
|
66
245
|
|
|
67
|
-
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## ๐ User Guide
|
|
249
|
+
|
|
250
|
+
Dev Harness works with two families of agentic coding tools. Which one are you using?
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
### ๐ฅ๏ธ IDE-Based Agentic Tools
|
|
255
|
+
|
|
256
|
+
These tools run as **extensions or built-in features inside an editor/IDE** (VS Code, JetBrains, etc.). They read a project-level config file to understand how to behave.
|
|
257
|
+
|
|
258
|
+
#### How It Works
|
|
259
|
+
|
|
260
|
+
1. **Scaffold** with the `--agent-tool` flag for your tool
|
|
261
|
+
2. Dev Harness generates the **tool-specific config file** that the agent reads automatically
|
|
262
|
+
3. The agent follows the **phase instructions** emitted by `dev-harness phase <name>`
|
|
263
|
+
4. After each phase, run `dev-harness validate` to **check gates** before advancing
|
|
264
|
+
|
|
265
|
+
#### Supported IDE Tools
|
|
266
|
+
|
|
267
|
+
| Tool | Config File | Init Command |
|
|
268
|
+
|------|-------------|-------------|
|
|
269
|
+
| **Claude Code** | `CLAUDE.md` | `dev-harness init --agent-tool claude-code` |
|
|
270
|
+
| **Cursor** | `.cursorrules` | `dev-harness init --agent-tool cursor` |
|
|
271
|
+
| **Windsurf** | `.windsurfrules` | `dev-harness init --agent-tool windsurf` |
|
|
272
|
+
| **GitHub Copilot** | `.github/copilot-instructions.md` | `dev-harness init --agent-tool copilot` |
|
|
273
|
+
| **Gemini CLI** | `GEMINI.md` | `dev-harness init --agent-tool gemini` |
|
|
274
|
+
| **Codex CLI** | `AGENTS.md` | `dev-harness init --agent-tool codex` |
|
|
275
|
+
| **Cline** | `.clinerules` | `dev-harness init --agent-tool cline` |
|
|
276
|
+
| **Roo Code** | `.roorules` | `dev-harness init --agent-tool roo` |
|
|
277
|
+
| **Kilo Code** | `.kilocoderules` | `dev-harness init --agent-tool kilo-code` |
|
|
278
|
+
| **Amazon Q Developer** | `.amazonq/rules.md` | `dev-harness init --agent-tool amazon-q` |
|
|
279
|
+
| **OpenCode** | `AGENTS.md` | `dev-harness init --agent-tool opencode` |
|
|
280
|
+
| **Continue** | `AGENTS.md` | `dev-harness init --agent-tool continue` |
|
|
281
|
+
| **Aider** | `AGENTS.md` | `dev-harness init --agent-tool aider` |
|
|
282
|
+
|
|
283
|
+
#### IDE Setup Example โ Claude Code
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
# Scaffold with Claude Code adapter
|
|
287
|
+
dev-harness init --stack python --agent-tool claude-code --target my-project
|
|
288
|
+
cd my-project
|
|
289
|
+
|
|
290
|
+
# CLAUDE.md is now in the project root โ Claude reads it automatically
|
|
291
|
+
claude
|
|
292
|
+
|
|
293
|
+
# Inside Claude: follow the phase instructions
|
|
294
|
+
# "Run: dev-harness phase define"
|
|
295
|
+
# "Run: dev-harness validate"
|
|
296
|
+
# "Run: dev-harness phase plan"
|
|
297
|
+
# ...and so on through the pipeline
|
|
298
|
+
```
|
|
299
|
+
|
|
300
|
+
> **Pattern:** All IDE tools follow the same workflow โ scaffold with the tool flag, then let the agent read its config and follow phase instructions. The only difference is which filename the agent expects.
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
### ๐ป TUI-Based Agentic Tools
|
|
305
|
+
|
|
306
|
+
These tools run as **standalone terminal applications** (TUI = Terminal User Interface). They typically read `AGENTS.md` from the project root natively, or use a custom manifest format.
|
|
307
|
+
|
|
308
|
+
#### How It Works
|
|
309
|
+
|
|
310
|
+
1. **Scaffold** with `--agent-tool` for your TUI tool (or use `generic`)
|
|
311
|
+
2. The harness generates `AGENTS.md` โ the canonical conventions file
|
|
312
|
+
3. The TUI agent reads `AGENTS.md` on startup and follows the pipeline
|
|
313
|
+
4. Full adapter directories may include **wrapper scripts** that delegate to the CLI
|
|
314
|
+
|
|
315
|
+
#### Supported TUI Tools
|
|
316
|
+
|
|
317
|
+
| Tool | Entry Point | Init Command | Notes |
|
|
318
|
+
|------|------------|-------------|-------|
|
|
319
|
+
| **Hermes** | `adapters/hermes/SKILL.md` | `dev-harness init --agent-tool hermes` | Full adapter with SKILL.md manifest + wrapper scripts |
|
|
320
|
+
| **OpenClaw** | `AGENTS.md` | `dev-harness init --agent-tool openclaw` | Reads AGENTS.md natively |
|
|
321
|
+
| **Antigravity** | `AGENTS.md` | `dev-harness init --agent-tool antigravity` | Reads AGENTS.md natively |
|
|
322
|
+
| **Pi** | `AGENTS.md` | `dev-harness init --agent-tool pi` | Reads AGENTS.md natively |
|
|
323
|
+
| **Generic** | `AGENTS.md` | `dev-harness init --agent-tool generic` | Fallback โ works with any tool |
|
|
324
|
+
|
|
325
|
+
#### TUI Setup Example โ Hermes
|
|
326
|
+
|
|
327
|
+
```bash
|
|
328
|
+
# Scaffold with Hermes adapter
|
|
329
|
+
dev-harness init --stack go --agent-tool hermes --target my-service
|
|
330
|
+
cd my-service
|
|
331
|
+
|
|
332
|
+
# Hermes loads the skill via adapters/hermes/SKILL.md
|
|
333
|
+
# The SKILL.md references wrapper scripts that call the CLI
|
|
334
|
+
# adapters/hermes/
|
|
335
|
+
# โโโ SKILL.md โ Hermes skill manifest
|
|
336
|
+
# โโโ scripts/
|
|
337
|
+
# โ โโโ init.mjs โ Wraps dev-harness init
|
|
338
|
+
# โ โโโ phase.mjs โ Wraps dev-harness phase
|
|
339
|
+
# โ โโโ validate.mjs โ Wraps dev-harness validate
|
|
340
|
+
# โโโ templates/ โ Shared templates
|
|
341
|
+
|
|
342
|
+
# Follow the phase pipeline inside Hermes
|
|
343
|
+
```
|
|
344
|
+
|
|
345
|
+
> **Pattern:** TUI tools that natively read `AGENTS.md` need no extra config โ just scaffold and go. Tools with custom manifest formats (like Hermes with `SKILL.md`) get a full adapter directory with wrapper scripts.
|
|
346
|
+
|
|
347
|
+
---
|
|
348
|
+
|
|
349
|
+
## ๐ง How It Works
|
|
350
|
+
|
|
351
|
+
### Pipeline Phases
|
|
352
|
+
|
|
353
|
+
| Phase | ๐ฏ Goal | ๐ฆ Key Artifact | ๐ง Gate(s) |
|
|
354
|
+
|-------|---------|-----------------|------------|
|
|
355
|
+
| ๐ต **DEFINE** | Write specs before any code | `SPEC.md`, `PROJECT_PLAN.md` | `feature-branch`, `contract-agreed` |
|
|
356
|
+
| ๐ข **PLAN** | Break specs into actionable tasks | Task breakdown | `git-clean` |
|
|
357
|
+
| ๐ **BUILD** | Implement features one at a time | Working code | `coverage` _(if enabled)_ |
|
|
358
|
+
| ๐ฃ **VERIFY** | Validate and test everything | Passing test suite | `coverage` _(if enabled)_ |
|
|
359
|
+
| ๐ก **SIMPLIFY** | Refactor, reduce complexity | Cleaner codebase | `git-clean`, `no-empty-dirs` |
|
|
360
|
+
| ๐ด **REVIEW** | Multi-agent committee review | Review report | `branch-up-to-date`, `rubric-exists`, `readme-exists`, `architecture-doc`, `decisions-logged` |
|
|
361
|
+
| ๐ข **SHIP** | Tag, changelog, publish | Release | `git-clean`, `tagged`, `changelog`, `readme-exists`, `license-exists`, `changelog-content`, `contributing-exists`, `no-empty-dirs` |
|
|
362
|
+
|
|
363
|
+
> ๐งน **SIMPLIFY** is optional โ it runs after VERIFY only if `simplify` is in your phase list.
|
|
364
|
+
|
|
365
|
+
### Gate Validation
|
|
366
|
+
|
|
367
|
+
Every phase has **deterministic gates** โ automated checks that return a clear **pass/fail**. Gates prevent the most common failure modes in AI-assisted development:
|
|
368
|
+
|
|
369
|
+
- ๐ซ **No skipping** โ can't ship without reviewing
|
|
370
|
+
- ๐ **No coding without specs** โ DEFINE gates must pass before BUILD
|
|
371
|
+
- ๐ **No self-review leniency** โ REVIEW uses multi-agent committee
|
|
372
|
+
- ๐งน **No dead code or empty dirs** โ SIMPLIFY gates keep the codebase clean
|
|
373
|
+
|
|
374
|
+
Enable gates:
|
|
375
|
+
|
|
376
|
+
```bash
|
|
377
|
+
dev-harness config set gates.enabled true
|
|
378
|
+
```
|
|
379
|
+
|
|
380
|
+
### Ralph Inner / Outer Loops
|
|
381
|
+
|
|
382
|
+
The architecture is built on the **Ralph pattern** โ an iterative loop architecture that gives the agent fresh context on each retry.
|
|
383
|
+
|
|
384
|
+
```
|
|
385
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
386
|
+
โ ๐ OUTER LOOP โ
|
|
387
|
+
โ define โ plan โ build โ verify โ review โ ship โ
|
|
388
|
+
โ (phase transitions, gate validation, human escalation) โ
|
|
389
|
+
โโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
390
|
+
โ
|
|
391
|
+
โผ
|
|
392
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
393
|
+
โ ๐ INNER LOOP โ
|
|
394
|
+
โ โ
|
|
395
|
+
โ feature-iterate mode: โ
|
|
396
|
+
โ pick next feature โ agent works โ validate โ pass? โ
|
|
397
|
+
โ โ
โ next feature โ
|
|
398
|
+
โ โ โ git reset --hard โ retry (fresh context) โ
|
|
399
|
+
โ โ
|
|
400
|
+
โ deliverable-retry mode: โ
|
|
401
|
+
โ agent works on deliverable โ validate โ pass? โ
|
|
402
|
+
โ โ
โ advance phase โ
|
|
403
|
+
โ โ โ rewrite + retry (up to N attempts) โ
|
|
404
|
+
โ โ
|
|
405
|
+
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
#### ๐ Outer Loop
|
|
409
|
+
|
|
410
|
+
The CLI **emits structured instructions** for the current phase. The agent executes the phase, then runs `dev-harness validate` โ which checks phase-specific gates. If gates pass, the agent advances to the next phase.
|
|
411
|
+
|
|
412
|
+
#### ๐ Inner Loop (Ralph)
|
|
413
|
+
|
|
414
|
+
When building or verifying, the harness enters an **inner loop** that iterates over individual features (`feature-iterate`) or retries failed deliverables (`deliverable-retry`). The critical insight: **on retry, the harness resets to a clean git state** (`git reset --hard` + clean). This forces the agent to re-approach the problem with fresh context โ avoiding the common failure mode of compounding its own mistakes.
|
|
415
|
+
|
|
416
|
+
> ๐ก *"The single most important implementation detail is the hard reset on retry โ it forces the agent to re-approach the problem rather than patch around its own bugs."*
|
|
417
|
+
|
|
418
|
+
### Multi-Agent Committee Review
|
|
419
|
+
|
|
420
|
+
During REVIEW, Dev Harness can orchestrate a **committee of agent personas** โ each reviewing from a different perspective:
|
|
421
|
+
|
|
422
|
+
| Persona | Role |
|
|
423
|
+
|---------|------|
|
|
424
|
+
| ๐งญ **Planner** | Does this meet the spec? Is the architecture sound? |
|
|
425
|
+
| โ๏ธ **Generator** | Does the code work? Is it idiomatic? |
|
|
426
|
+
| ๐ **Evaluator** | What's wrong? Where are the gaps? _(tuned to be skeptical)_ |
|
|
427
|
+
| ๐งน **Simplifier** | Is this over-engineered? Can it be simpler? |
|
|
428
|
+
|
|
429
|
+
This directly addresses the **self-evaluation leniency problem** โ an agent asked to review its own work will almost always rubber-stamp it. A separate Evaluator persona, tuned to be skeptical, catches what the Generator misses.
|
|
430
|
+
|
|
431
|
+
---
|
|
432
|
+
|
|
433
|
+
## ๐ Project Structure
|
|
68
434
|
|
|
69
435
|
When you run `dev-harness init`, all harness-managed files go into a `harness/` subfolder โ keeping your project root clean:
|
|
70
436
|
|
|
71
437
|
```
|
|
72
438
|
my-project/
|
|
73
|
-
โโโ AGENTS.md
|
|
74
|
-
โโโ .gitignore
|
|
75
|
-
โโโ package.json
|
|
76
|
-
โโโ src/
|
|
77
|
-
โโโ tests/
|
|
78
|
-
โโโ harness/
|
|
79
|
-
โโโ config.json
|
|
80
|
-
โโโ progress.md
|
|
81
|
-
โโโ sprint-contract.md
|
|
82
|
-
โโโ evaluator-rubric.md
|
|
83
|
-
โโโ session-handoff.md
|
|
84
|
-
โโโ clean-state-checklist.md
|
|
439
|
+
โโโ AGENTS.md # Agent conventions (root โ tools expect it here)
|
|
440
|
+
โโโ .gitignore # Git ignore rules
|
|
441
|
+
โโโ package.json # Your project's package file
|
|
442
|
+
โโโ src/ # Your source code
|
|
443
|
+
โโโ tests/ # Your tests
|
|
444
|
+
โโโ harness/ # All harness-managed files
|
|
445
|
+
โโโ config.json # Harness configuration + state
|
|
446
|
+
โโโ progress.md # Session state + lessons learned
|
|
447
|
+
โโโ sprint-contract.md # Pre-build agreement
|
|
448
|
+
โโโ evaluator-rubric.md # Quality scorecard
|
|
449
|
+
โโโ session-handoff.md # Context for session transitions
|
|
450
|
+
โโโ clean-state-checklist.md # Clean state checklist
|
|
85
451
|
โโโ features/
|
|
86
|
-
โ โโโ feature-list.json
|
|
87
|
-
โ โโโ feature-list.schema.json
|
|
452
|
+
โ โโโ feature-list.json # Feature tracking
|
|
453
|
+
โ โโโ feature-list.schema.json # Feature list schema
|
|
88
454
|
โโโ docs/
|
|
89
|
-
โ โโโ ARCHITECTURE.md
|
|
90
|
-
โ โโโ CONSTRAINTS.md
|
|
91
|
-
โ โโโ DECISIONS.md
|
|
92
|
-
โ โโโ api-patterns.md
|
|
93
|
-
โ โโโ agents/
|
|
455
|
+
โ โโโ ARCHITECTURE.md # Architecture decisions
|
|
456
|
+
โ โโโ CONSTRAINTS.md # Technical constraints
|
|
457
|
+
โ โโโ DECISIONS.md # Decision log
|
|
458
|
+
โ โโโ api-patterns.md # API conventions
|
|
459
|
+
โ โโโ agents/ # Agent role guides
|
|
94
460
|
โ โ โโโ planner.md
|
|
95
461
|
โ โ โโโ generator.md
|
|
96
462
|
โ โ โโโ evaluator.md
|
|
97
463
|
โ โ โโโ simplifier.md
|
|
98
|
-
โ โโโ phases/
|
|
464
|
+
โ โโโ phases/ # Phase instructions
|
|
99
465
|
โ โโโ define.md
|
|
100
466
|
โ โโโ plan.md
|
|
101
467
|
โ โโโ build.md
|
|
@@ -111,98 +477,63 @@ my-project/
|
|
|
111
477
|
โโโ init.ps1
|
|
112
478
|
```
|
|
113
479
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
31 built-in stacks + custom stack support:
|
|
117
|
-
|
|
118
|
-
| Stack | Detection Files | Config File |
|
|
119
|
-
|-------|----------------|-------------|
|
|
120
|
-
| Node.js | `package.json`, `*.js`, `*.ts` | `package.json` |
|
|
121
|
-
| Python | `pyproject.toml`, `setup.py`, `*.py` | `pyproject.toml` |
|
|
122
|
-
| Rust | `Cargo.toml`, `*.rs` | `Cargo.toml` |
|
|
123
|
-
| Go | `go.mod`, `*.go` | `go.mod` |
|
|
124
|
-
| Java | `pom.xml`, `build.gradle`, `*.java` | `pom.xml` |
|
|
125
|
-
| C/C++ | `*.c`, `*.cpp`, `*.hpp` | `CMakeLists.txt` |
|
|
126
|
-
| .NET | `*.cs`, `*.fs` | `global.json` |
|
|
127
|
-
| Ruby | `Gemfile`, `*.rb` | `Gemfile` |
|
|
128
|
-
| PHP | `composer.json`, `*.php` | `composer.json` |
|
|
129
|
-
| Swift | `Package.swift`, `*.swift` | `Package.swift` |
|
|
130
|
-
| + 21 more | | |
|
|
131
|
-
|
|
132
|
-
**Custom stacks:** Pass any name to `--stack` and fill `stackMeta` in `harness/config.json` during DEFINE phase.
|
|
480
|
+
---
|
|
133
481
|
|
|
134
|
-
##
|
|
482
|
+
## โ๏ธ CLI Reference
|
|
135
483
|
|
|
136
484
|
| Command | Description |
|
|
137
485
|
|---------|-------------|
|
|
138
|
-
| `init` | Scaffold a new project
|
|
139
|
-
| `status` | Show current phase, stack,
|
|
140
|
-
| `phase <name>` |
|
|
141
|
-
| `validate` | Run gate checks for current phase |
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `config set
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
152
|
-
| `
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
Harness works with any coding agent. Use `--agent-tool` during init to generate tool-specific files:
|
|
157
|
-
|
|
158
|
-
```bash
|
|
159
|
-
# Claude Code โ generates CLAUDE.md
|
|
160
|
-
dev-harness init --stack node --agent-tool claude-code --target my-app
|
|
161
|
-
|
|
162
|
-
# Cursor โ generates .cursorrules
|
|
163
|
-
dev-harness init --stack node --agent-tool cursor --target my-app
|
|
164
|
-
|
|
165
|
-
# GitHub Copilot โ generates .github/copilot-instructions.md
|
|
166
|
-
dev-harness init --stack node --agent-tool copilot --target my-app
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
**18 supported tools:** claude-code, cursor, windsurf, gemini, copilot, cline, roo, kilo-code, amazon-q, codex, opencode, continue, aider, antigravity, openclaw, pi, hermes, generic.
|
|
486
|
+
| `dev-harness init` | ๐๏ธ Scaffold a new harness project (stack + agent tool + target) |
|
|
487
|
+
| `dev-harness status` | ๐ Show current phase, stack, mode, and pipeline state |
|
|
488
|
+
| `dev-harness phase <name>` | ๐ฆ Run a pipeline phase (define, plan, build, verify, simplify, review, ship) |
|
|
489
|
+
| `dev-harness validate` | โ
Run gate checks for the current phase |
|
|
490
|
+
| `dev-harness run` | ๐ Start orchestrator โ spawn agent per task, API retry, live dashboard |
|
|
491
|
+
| `dev-harness select-tool` | ๐งฐ Choose backend agentic tool (interactive wizard) |
|
|
492
|
+
| `dev-harness config [get|set|list]` | โ๏ธ View or update configuration parameters |
|
|
493
|
+
| `dev-harness contract` | ๐ Negotiate a sprint contract between agent personas |
|
|
494
|
+
| `dev-harness checkpoint` | ๐พ Create a manual git checkpoint |
|
|
495
|
+
| `dev-harness rollback` | โช Roll back to a previous checkpoint |
|
|
496
|
+
| `dev-harness worktree` | ๐ฟ Manage git worktrees for parallel feature work |
|
|
497
|
+
| `dev-harness pause` | โธ๏ธ Pause the pipeline (save state) |
|
|
498
|
+
| `dev-harness resume` | โถ๏ธ Resume a paused pipeline |
|
|
499
|
+
| `dev-harness set-mode <mode>` | ๐ Switch between `copilot` (instruction) and `autopilot` (auto-advance) |
|
|
500
|
+
| `dev-harness learn` | ๐ Mark a phase as learned (skip in future runs) |
|
|
501
|
+
| `dev-harness detect-tool` | ๐ Auto-detect which agent tool is in use |
|
|
502
|
+
| `dev-harness --help` | โ Show full help |
|
|
170
503
|
|
|
171
|
-
|
|
504
|
+
---
|
|
172
505
|
|
|
173
|
-
##
|
|
506
|
+
## ๐ง Configuration
|
|
174
507
|
|
|
175
|
-
|
|
508
|
+
All configuration lives in `harness/config.json`. View with:
|
|
176
509
|
|
|
177
510
|
```bash
|
|
178
|
-
dev-harness config
|
|
511
|
+
dev-harness config list
|
|
179
512
|
```
|
|
180
513
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
| DEFINE | feature-branch, contract-agreed |
|
|
184
|
-
| PLAN | git-clean |
|
|
185
|
-
| BUILD | (coverage if enabled) |
|
|
186
|
-
| VERIFY | (coverage if enabled) |
|
|
187
|
-
| SIMPLIFY | git-clean, no-empty-dirs |
|
|
188
|
-
| REVIEW | branch-up-to-date, rubric-exists, readme-exists, architecture-doc, decisions-logged |
|
|
189
|
-
| SHIP | git-clean, tagged, changelog, readme-exists, license-exists, changelog-content, contributing-exists, no-empty-dirs |
|
|
514
|
+
<details>
|
|
515
|
+
<summary>๐ Click to see configuration groups</summary>
|
|
190
516
|
|
|
191
|
-
|
|
517
|
+
| Group | Parameters | Description |
|
|
518
|
+
|-------|-----------|-------------|
|
|
519
|
+
| โก **Execution** | `maxRetries`, `commandTimeout`, `coverageTimeout`, `maxNegotiationRounds`, `escalationTimeout` | Runtime behavior tuning |
|
|
520
|
+
| ๐๏ธ **Stack** | `stack`, `stackMeta` | Language/platform configuration |
|
|
521
|
+
| ๐งฐ **Agent Tool** | `agentTool` | Current agent tool selection |
|
|
522
|
+
| ๐ง **Gates** | `gates.enabled`, `gates.required`, `gates.coverageThreshold` | Gate validation settings |
|
|
523
|
+
| ๐ฟ **Git** | `git.autoCommit`, `git.autoPush`, `git.mainBranch`, `git.tagPrefix` | Git integration behavior |
|
|
524
|
+
| ๐ฆ **Phases** | `phases.order`, `phases.skip`, `phases.simplifyAfter` | Pipeline phase configuration |
|
|
525
|
+
| ๐ญ **Agent Tones** | `tones.planner`, `tones.generator`, `tones.evaluator`, `tones.simplifier` | Persona instruction customization |
|
|
526
|
+
| ๐พ **Runtime State** | `currentPhase`, `retryCount`, `mode`, `paused` | Live pipeline state |
|
|
192
527
|
|
|
193
|
-
|
|
528
|
+
</details>
|
|
194
529
|
|
|
195
|
-
|
|
196
|
-
dev-harness config list
|
|
197
|
-
```
|
|
530
|
+
**29 parameters** across 8 groups. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the full reference.
|
|
198
531
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for full reference.
|
|
532
|
+
---
|
|
202
533
|
|
|
203
|
-
## JSON Output
|
|
534
|
+
## ๐ค JSON Output
|
|
204
535
|
|
|
205
|
-
All commands support `--json` for machine-parseable output
|
|
536
|
+
All commands support `--json` for machine-parseable output โ perfect for CI/CD pipelines, wrapper scripts, and tool integration.
|
|
206
537
|
|
|
207
538
|
```bash
|
|
208
539
|
dev-harness status --json
|
|
@@ -220,8 +551,57 @@ dev-harness validate --json
|
|
|
220
551
|
}
|
|
221
552
|
```
|
|
222
553
|
|
|
223
|
-
|
|
554
|
+
| Convention | Rule |
|
|
555
|
+
|------------|------|
|
|
556
|
+
| โ
**stdout** | Always valid JSON โ machine-parseable, no exceptions |
|
|
557
|
+
| โ **stderr** | All errors, warnings, human-readable messages |
|
|
558
|
+
| **Exit codes** | `0` success, `1` validation failure, `2` usage error, `3` internal error |
|
|
559
|
+
| **JSON contract** | Every response includes `command`, `status`, `message` |
|
|
560
|
+
|
|
561
|
+
---
|
|
562
|
+
|
|
563
|
+
## ๏ฟฝ Dependencies
|
|
564
|
+
|
|
565
|
+
Dev Harness v2.1.0 moved from zero-runtime-deps to a **minimal, audited** dependency set. Each dependency was chosen for a concrete robustness, performance, or correctness win that the hand-rolled equivalent could not match. All dependencies are ubiquitous, well-maintained, and support Node 18+.
|
|
566
|
+
|
|
567
|
+
| Dependency | Version | Replaces | Why |
|
|
568
|
+
|------------|---------|----------|-----|
|
|
569
|
+
| [`ajv`](https://github.com/ajv-validator/ajv) | ^8 | hand-rolled `validate-schema.mjs` | Full JSON Schema draft-07 support (`$ref`, `format`, `oneOf`, `if/then/else`, `pattern`) โ the previous validator silently passed configs using unsupported keywords |
|
|
570
|
+
| [`simple-git`](https://github.com/steveukx/git-js) | ^3 | `execSync`-based `git.mjs` | **Async** git ops โ unblocks the orchestrator event loop during `dev-harness run`; typed results; eliminates string-concat command injection risk |
|
|
571
|
+
| [`ink`](https://github.com/vadimdemedes/ink) + [`react`](https://react.dev) | ^5 / ^18 | manual ANSI `tui/dashboard.mjs` | Real layout engine, proper Unicode width, focus management, scrollable regions that work across terminals |
|
|
572
|
+
| [`p-retry`](https://github.com/sindresorhus/p-retry) | ^6 | hand-rolled backoff in `supervisor.mjs` | Battle-tested exponential backoff with `shouldRetry` predicate |
|
|
573
|
+
| [`picocolors`](https://github.com/alexeyraspopov/picocolors) | ^1 | hand-rolled ANSI color codes | TTY detection, `NO_COLOR`/`FORCE_COLOR` conformance, Windows support, 256/truecolor downgrading |
|
|
574
|
+
| [`string-width`](https://github.com/sindresorhus/string-width) | ^7 | emoji-width heuristic in `ansi.mjs` | Correctly measures emoji, combining marks, ZWJ sequences, and East Asian wide chars โ the previous heuristic mis-measured many code points |
|
|
224
575
|
|
|
225
|
-
|
|
576
|
+
> **Supply-chain posture:** 6 direct deps, all from established maintainers (Sindre Sorhus, Ajv org, Vadim Demedes, Steve King). `npm audit` reports 0 vulnerabilities. Versions pinned with caret ranges for patch updates.
|
|
226
577
|
|
|
227
|
-
|
|
578
|
+
---
|
|
579
|
+
|
|
580
|
+
## ๏ฟฝ๐ Acknowledgements & Influences
|
|
581
|
+
|
|
582
|
+
Dev Harness was built on the shoulders of foundational work in the **harness engineering** space. We are deeply grateful to these projects, papers, and people whose ideas shaped this tool:
|
|
583
|
+
|
|
584
|
+
| Influence | Links | Impact on Dev Harness |
|
|
585
|
+
|-----------|-------|----------------------|
|
|
586
|
+
| **Ralph Pattern**<br>by Dean Huntley | [`ghuntley.com/ralph`](https://ghuntley.com/ralph) ยท [`snarktank/ralph`](https://github.com/snarktank/ralph) | ๐ง **Core architecture.** The entire inner/outer loop design, fresh-context retry via `git reset --hard`, and `progress.md` session tracking are direct implementations of the Ralph pattern. The `ralph-inner.mjs`, `ralph-outer.mjs`, and `ralph-output.mjs` modules are named in its honor. |
|
|
587
|
+
| **Agent Skills**<br>by Addy Osmani | [`github.com/addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) | ๐ฆ **Pipeline & review design.** The 6-phase pipeline structure, committee-based multi-agent review with 4 personas (Planner, Generator, Evaluator, Simplifier), and anti-rationalization patterns come directly from this work. |
|
|
588
|
+
| **Anthropic**<br>Harness Research | ["Effective Harnesses" (Nov 2025)](https://anthropic.com/engineering/effective-harnesses) ยท ["Harness Design" (Mar 2026)](https://anthropic.com/engineering/harness-design) | ๐ **Generator/Evaluator split, sprint contracts, and rollback.** The finding that *"tuning a standalone evaluator to be skeptical is far more tractable than making a generator critical of its own work"* directly motivated our multi-agent committee. Sprint contract negotiation, feature lists, and middle-iteration recovery are all Anthropic-inspired. |
|
|
589
|
+
| **OpenAI**<br>Harness Engineering | ["Harness Engineering" (Feb 2026)](https://openai.com/index/harness-engineering/) | ๐ฟ **Worktree isolation & progressive disclosure.** The worktree CLI commands for isolated parallel feature development, and the progressive disclosure pattern in `AGENTS.md` (a concise map to detailed docs/) are direct applications of OpenAI's principles. |
|
|
590
|
+
|
|
591
|
+
> ๐ก *These works collectively define the **harness engineering** discipline โ the practice of building structured execution environments that make AI coding agents reliable at scale. Dev Harness is our synthesis and implementation of these ideas in a single, tool-agnostic CLI.*
|
|
592
|
+
|
|
593
|
+
---
|
|
594
|
+
|
|
595
|
+
## ๐ License
|
|
596
|
+
|
|
597
|
+
[MIT](LICENSE) ยฉ 2026 Bakr Bagaber
|
|
598
|
+
|
|
599
|
+
---
|
|
600
|
+
|
|
601
|
+
<div align="center">
|
|
602
|
+
<sub>Built with โ and ๐ค ยท Questions? Open an issue ยท Contributions welcome!</sub>
|
|
603
|
+
<br>
|
|
604
|
+
<sub>
|
|
605
|
+
<a href="#-dev-harness">โ Back to top</a>
|
|
606
|
+
</sub>
|
|
607
|
+
</div>
|
package/cli/lib/constants.mjs
CHANGED
|
@@ -8,8 +8,11 @@
|
|
|
8
8
|
* import { GATE_TIMEOUT, COVERAGE_TIMEOUT, MAX_NEGOTIATION_ROUNDS } from './constants.mjs';
|
|
9
9
|
*/
|
|
10
10
|
|
|
11
|
-
/** Default max retries per
|
|
12
|
-
|
|
11
|
+
/** Default max retries per task before escalating to human.
|
|
12
|
+
* Retry scope is per-task (not per-phase) โ each task gets its own retry budget.
|
|
13
|
+
* Configurable via: dev-harness config set maxRetries <N>
|
|
14
|
+
*/
|
|
15
|
+
export const DEFAULT_MAX_RETRIES = 10;
|
|
13
16
|
|
|
14
17
|
/** Timeout (ms) for standard git/shell commands. */
|
|
15
18
|
export const COMMAND_TIMEOUT = 30000;
|
|
@@ -28,3 +31,17 @@ export const STACK_SCAN_DEPTH = 2;
|
|
|
28
31
|
|
|
29
32
|
/** File mode for executable scripts (init.sh). */
|
|
30
33
|
export const EXECUTABLE_MODE = 0o755;
|
|
34
|
+
|
|
35
|
+
// โโ Supervisor / Orchestrator constants โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
|
|
36
|
+
|
|
37
|
+
/** Default max API retry attempts before pausing pipeline. */
|
|
38
|
+
export const API_MAX_RETRIES = 5;
|
|
39
|
+
|
|
40
|
+
/** Base backoff delay in ms for API retries (exponential: 60s, 120s, 240s, ...). */
|
|
41
|
+
export const API_BACKOFF_MS = 60000;
|
|
42
|
+
|
|
43
|
+
/** Supervisor heartbeat interval in ms. */
|
|
44
|
+
export const SUPERVISOR_INTERVAL_MS = 60000;
|
|
45
|
+
|
|
46
|
+
/** Max heartbeat staleness before stall detection (5 min). */
|
|
47
|
+
export const SUPERVISOR_MAX_STALLS = 3;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dev-harness-cli",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "2.1.0",
|
|
4
4
|
"description": "Agent-agnostic software development harness CLI โ scaffold, phase orchestration, gate validation for any coding agent",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|
|
@@ -44,6 +44,15 @@
|
|
|
44
44
|
"test:verbose": "node test/run-all.mjs --verbose",
|
|
45
45
|
"postinstall": "node -e \"try{process.stdout.write('dev-harness installed. Run: npx dev-harness --help\\n')}catch(e){}\""
|
|
46
46
|
},
|
|
47
|
+
"dependencies": {
|
|
48
|
+
"ajv": "^8.17.1",
|
|
49
|
+
"ink": "^5.1.0",
|
|
50
|
+
"p-retry": "^6.2.1",
|
|
51
|
+
"picocolors": "^1.1.1",
|
|
52
|
+
"react": "^18.3.1",
|
|
53
|
+
"simple-git": "^3.27.0",
|
|
54
|
+
"string-width": "^7.1.0"
|
|
55
|
+
},
|
|
47
56
|
"devDependencies": {
|
|
48
57
|
"@eslint/js": "^10.0.1",
|
|
49
58
|
"eslint": "^10.5.0"
|