codeharness 0.13.2 → 0.16.1
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
ADDED
|
@@ -0,0 +1,118 @@
|
|
|
1
|
+
# codeharness
|
|
2
|
+
|
|
3
|
+
Makes autonomous coding agents produce software that actually works — not software that passes tests.
|
|
4
|
+
|
|
5
|
+
codeharness is an **npm CLI** + **Claude Code plugin** that packages verification-driven development as an installable tool: black-box verification via Docker, agent-first observability via VictoriaMetrics, and mechanical enforcement via hooks that make skipping verification architecturally impossible.
|
|
6
|
+
|
|
7
|
+
## What it does
|
|
8
|
+
|
|
9
|
+
1. **Verifies features work** — not just that tests pass. Black-box verification runs the built CLI inside a Docker container with no source code access. If the feature doesn't work from a user's perspective, verification fails.
|
|
10
|
+
2. **Fixes what it finds** — verification failures with code bugs automatically return to development with specific findings. The dev agent gets told exactly what's broken and why.
|
|
11
|
+
3. **Runs sprints autonomously** — reads your sprint plan, picks the highest-priority story, implements it, reviews it, verifies it, and moves to the next one. Cross-epic prioritization, retry management, and session handoff built in.
|
|
12
|
+
4. **Makes agents see runtime** — ephemeral VictoriaMetrics stack (logs, metrics, traces) that agents query programmatically during development. No guessing at what the code does at runtime.
|
|
13
|
+
|
|
14
|
+
## Installation
|
|
15
|
+
|
|
16
|
+
Two components — install both:
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
# CLI (npm package)
|
|
20
|
+
npm install -g codeharness
|
|
21
|
+
|
|
22
|
+
# Claude Code plugin (slash commands, hooks, skills)
|
|
23
|
+
claude plugin install github:iVintik/codeharness
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Quick Start
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
# Initialize in your project
|
|
30
|
+
codeharness init
|
|
31
|
+
|
|
32
|
+
# Start autonomous sprint execution (inside Claude Code)
|
|
33
|
+
/harness-run
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
## How it works
|
|
37
|
+
|
|
38
|
+
### As a CLI (`codeharness`)
|
|
39
|
+
|
|
40
|
+
The CLI handles all mechanical work — stack detection, Docker management, verification, coverage, retry state.
|
|
41
|
+
|
|
42
|
+
| Command | Purpose |
|
|
43
|
+
|---------|---------|
|
|
44
|
+
| `codeharness init` | Detect stack, install dependencies, start observability, scaffold docs |
|
|
45
|
+
| `codeharness run` | Execute the autonomous coding loop (Ralph) |
|
|
46
|
+
| `codeharness verify --story <key>` | Run verification pipeline for a story |
|
|
47
|
+
| `codeharness status` | Show harness health, sprint progress, Docker stack |
|
|
48
|
+
| `codeharness coverage` | Run tests with coverage and evaluate against targets |
|
|
49
|
+
| `codeharness onboard epic` | Scan codebase for gaps, generate onboarding stories |
|
|
50
|
+
| `codeharness retry --status` | Show retry counts and flagged stories |
|
|
51
|
+
| `codeharness retry --reset` | Clear retry state for re-verification |
|
|
52
|
+
| `codeharness verify-env build` | Build Docker image for black-box verification |
|
|
53
|
+
| `codeharness stack start` | Start the shared observability stack |
|
|
54
|
+
| `codeharness teardown` | Remove harness from project |
|
|
55
|
+
|
|
56
|
+
All commands support `--json` for machine-readable output.
|
|
57
|
+
|
|
58
|
+
### As a Claude Code plugin (`/harness-*`)
|
|
59
|
+
|
|
60
|
+
The plugin provides slash commands that orchestrate the CLI within Claude Code sessions:
|
|
61
|
+
|
|
62
|
+
| Command | Purpose |
|
|
63
|
+
|---------|---------|
|
|
64
|
+
| `/harness-run` | Autonomous sprint execution — picks stories by priority, runs create → dev → review → verify loop |
|
|
65
|
+
| `/harness-init` | Interactive project initialization |
|
|
66
|
+
| `/harness-status` | Quick overview of sprint progress and harness health |
|
|
67
|
+
| `/harness-onboard` | Scan project and generate onboarding plan |
|
|
68
|
+
| `/harness-verify` | Verify a story with real-world evidence |
|
|
69
|
+
|
|
70
|
+
### BMAD Method integration
|
|
71
|
+
|
|
72
|
+
codeharness integrates with [BMAD Method](https://github.com/bmadcode/BMAD-METHOD) for structured sprint planning:
|
|
73
|
+
|
|
74
|
+
| Phase | Commands |
|
|
75
|
+
|-------|----------|
|
|
76
|
+
| Analysis | `/create-brief`, `/brainstorm-project`, `/market-research` |
|
|
77
|
+
| Planning | `/create-prd`, `/create-ux` |
|
|
78
|
+
| Solutioning | `/create-architecture`, `/create-epics-stories` |
|
|
79
|
+
| Implementation | `/sprint-planning`, `/create-story`, then `/harness-run` |
|
|
80
|
+
|
|
81
|
+
## Verification architecture
|
|
82
|
+
|
|
83
|
+
```
|
|
84
|
+
┌─────────────────────────────────────────┐
|
|
85
|
+
│ Claude Code Session │
|
|
86
|
+
│ /harness-run picks next story │
|
|
87
|
+
│ → create-story → dev → review → verify │
|
|
88
|
+
└────────────────────┬────────────────────┘
|
|
89
|
+
│ verify
|
|
90
|
+
▼
|
|
91
|
+
┌─────────────────────────────────────────┐
|
|
92
|
+
│ Docker Container (no source code) │
|
|
93
|
+
│ - codeharness CLI installed from tarball│
|
|
94
|
+
│ - claude CLI for nested verification │
|
|
95
|
+
│ - curl/jq for observability queries │
|
|
96
|
+
│ Exercises CLI as a real user would │
|
|
97
|
+
└────────────────────┬────────────────────┘
|
|
98
|
+
│ queries
|
|
99
|
+
▼
|
|
100
|
+
┌─────────────────────────────────────────┐
|
|
101
|
+
│ Observability Stack (VictoriaMetrics) │
|
|
102
|
+
│ - VictoriaLogs :9428 (LogQL) │
|
|
103
|
+
│ - VictoriaMetrics :8428 (PromQL) │
|
|
104
|
+
│ - OTEL Collector :4318 │
|
|
105
|
+
└─────────────────────────────────────────┘
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
When verification finds code bugs → story returns to dev with findings → dev fixes → re-verify. This loop runs up to 10 times per story. Infrastructure failures (timeouts, Docker errors) retry 3 times then skip.
|
|
109
|
+
|
|
110
|
+
## Requirements
|
|
111
|
+
|
|
112
|
+
- Node.js >= 18
|
|
113
|
+
- Docker (for observability and verification)
|
|
114
|
+
- Claude Code (for plugin features)
|
|
115
|
+
|
|
116
|
+
## License
|
|
117
|
+
|
|
118
|
+
MIT
|