harnessed 3.3.0 → 3.4.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 +211 -194
- package/dist/cli.mjs +417 -138
- package/dist/cli.mjs.map +1 -1
- package/dist/index.mjs +1 -1
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
- package/workflows/disciplines/language.yaml +33 -13
package/README.md
CHANGED
|
@@ -1,103 +1,121 @@
|
|
|
1
1
|
# harnessed
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
**English** | [中文](./README-cn.md)
|
|
4
|
+
|
|
5
|
+
> AI coding harness package manager + composition orchestrator
|
|
6
|
+
> Machine-executes the three-layer-stack collaboration methodology (gstack governance + GSD project manager + superpowers senior engineer + karpathy principles + mattpocock moves) as a runnable engine
|
|
5
7
|
|
|
6
8
|
[](https://npmjs.com/package/harnessed)
|
|
7
9
|
[](./LICENSE)
|
|
8
10
|
[](https://github.com/sponsors/easyinplay)
|
|
9
11
|
|
|
10
|
-
> Not affiliated with, endorsed by, or sponsored by Harness Inc. (
|
|
12
|
+
> Not affiliated with, endorsed by, or sponsored by Harness Inc. (see [NOTICE](./NOTICE))
|
|
11
13
|
|
|
12
14
|
---
|
|
13
15
|
|
|
14
|
-
## ✨
|
|
16
|
+
## ✨ TL;DR
|
|
17
|
+
|
|
18
|
+
Assembles the best open-source Claude Code ecosystem components, weaving them into a unified workflow via opinionated composition skills; does not vendor upstream code — manifests describe install/check, and composition skills orchestrate multi-upstream collaboration.
|
|
19
|
+
|
|
20
|
+
---
|
|
15
21
|
|
|
16
|
-
|
|
22
|
+
> Wait — can harnessed really go toe-to-toe with upstream giants like superpowers / gstack / GSD?
|
|
23
|
+
> Of course — we **stand on the shoulders of giants**. See further, Newton said. 🧐
|
|
24
|
+
> ... *(whispers)* Though on closer look, more like the parrot perched on said shoulder.
|
|
25
|
+
> Eh — parrots mimic; we **orchestrate**. 🦜
|
|
17
26
|
|
|
18
27
|
---
|
|
19
28
|
|
|
20
|
-
## 🎯
|
|
29
|
+
## 🎯 Key Differentiators
|
|
21
30
|
|
|
22
|
-
-
|
|
23
|
-
-
|
|
24
|
-
- **Composition Skill** —
|
|
25
|
-
- **L0 Discipline Substrate** —
|
|
26
|
-
-
|
|
27
|
-
-
|
|
31
|
+
- **Three-layer stack machine-executed** — `gstack governance` + `GSD project manager` + `superpowers senior engineer` + `karpathy 4 principles` + `mattpocock 23 moves`, 5 pillars at 100% capture
|
|
32
|
+
- **No vendoring of upstream** — manifests describe install/check; on upstream upgrade users just re-install to get the latest version
|
|
33
|
+
- **Composition Skill** — in-house workflow skills act as the conductor's baton, orchestrating multiple upstreams in concert. **1 super-master `/auto` + 4 stage masters + 18 sub-workflows + 2 standalones = 25 namespace-layered workflows**, full 4-stage machine-execution (`/auto` one-shot across stages / `/discuss /plan /task /verify` single stage / 18 three-layer-stack subs / `/research /retro` 2 standalones)
|
|
34
|
+
- **L0 Discipline Substrate** — global cross-stage behavior baseline (karpathy principles + output-style + language + operational + priority + protocols), applied universally
|
|
35
|
+
- **Package manager mindset** — install dependency graph auto-resolves, doctor health check, install-base one-shot full install
|
|
36
|
+
- **Unified entry point** — users face `/discuss /plan /task /verify` master slash commands without learning each upstream's terminology; sub commands explicitly invoke a single stage (e.g. `/discuss-strategic` runs only the strategic-layer clarification)
|
|
28
37
|
|
|
29
38
|
---
|
|
30
39
|
|
|
31
|
-
## 📦
|
|
40
|
+
## 📦 Quick Install
|
|
32
41
|
|
|
33
42
|
```bash
|
|
34
43
|
npm install -g harnessed && harnessed setup
|
|
35
44
|
```
|
|
36
45
|
|
|
37
|
-
> Windows PowerShell 5.x
|
|
46
|
+
> Windows PowerShell 5.x does not support `&&` chaining — use `;` or two lines (`npm install -g harnessed; harnessed setup`). bash / zsh / PowerShell 7+ / cmd.exe all work normally.
|
|
47
|
+
|
|
48
|
+
🤖 **Or have an AI install it for you** — paste this sentence to Claude Code (or any AI assistant):
|
|
49
|
+
|
|
50
|
+
> Install harnessed for me following the guide at `https://github.com/easyinplay/harnessed/blob/main/INSTALL-WITH-AI.md`
|
|
51
|
+
|
|
52
|
+
The AI will auto-fetch the doc + run the install, handling OS / permissions / PATH / corepack edge cases — no need to copy large chunks of text.
|
|
38
53
|
|
|
39
|
-
|
|
54
|
+
> [!TIP]
|
|
55
|
+
> 🚀 **The much-loved Agent Teams and Subagent features are auto-enabled in harnessed based on the task!**
|
|
56
|
+
> No need to manually configure `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` — `harnessed setup` writes it to `~/.claude/settings.json` automatically. Pattern A full-stack three-way / Pattern C 4-specialist and other multi-agent workflows work out of the box.
|
|
40
57
|
|
|
41
58
|
---
|
|
42
59
|
|
|
43
|
-
## 🚀
|
|
60
|
+
## 🚀 Quick Start — 3 Options
|
|
44
61
|
|
|
45
|
-
|
|
62
|
+
In order of increasing user intervention:
|
|
46
63
|
|
|
47
|
-
### 🎯
|
|
64
|
+
### 🎯 Auto Mode (Recommended for newcomers / don't want to think hard)
|
|
48
65
|
|
|
49
66
|
```
|
|
50
|
-
/auto "
|
|
67
|
+
/auto "requirement X"
|
|
51
68
|
|
|
52
|
-
#
|
|
53
|
-
|
|
69
|
+
# For large requirements you can explicitly stage (usually not needed — AI auto-judges and routes in;
|
|
70
|
+
# force it if you believe it's a large requirement):
|
|
71
|
+
/auto "requirement X" --staged
|
|
54
72
|
```
|
|
55
73
|
|
|
56
|
-
>
|
|
74
|
+
> Don't want to think hard, or just getting started — let harnessed handle everything. Runs the full 6 stages (research conditional → discuss → plan → task → verify → retro mandatory) without stopping. AI 1-shot auto-judges requirement complexity, suggests switching to `--staged` mode for large requirements (stops after each stage for review); before starting prompts "Do you have a clear understanding of the requirement?" — if no → auto-runs `/research` multi-source investigation; ends with mandatory `/retro` summary. Fail-fast on failure, resume via `harnessed resume`.
|
|
57
75
|
|
|
58
|
-
### 📂
|
|
76
|
+
### 📂 Stage Mode (Recommended for power users / want to review intermediate results)
|
|
59
77
|
|
|
60
78
|
```
|
|
61
|
-
/discuss "
|
|
62
|
-
/plan "
|
|
63
|
-
/task "subtask-1"
|
|
64
|
-
/verify "phase-1"
|
|
79
|
+
/discuss "requirement X" # Strategic + Phase + Subtask 3-layer clarification
|
|
80
|
+
/plan "requirement X" # Architecture (conditional) + plan persistence
|
|
81
|
+
/task "subtask-1" # 4 subs serial (clarify → code → test → deliver)
|
|
82
|
+
/verify "phase-1" # 7 subs conditional verification
|
|
65
83
|
```
|
|
66
84
|
|
|
67
|
-
>
|
|
85
|
+
> Want to decide which stage to start from / review intermediate outputs — 4 masters callable independently, and each master still auto-fans-out all of that stage's subs internally.
|
|
68
86
|
|
|
69
|
-
### 🔬
|
|
87
|
+
### 🔬 Surgical Mode (Expert mode / you know what you want)
|
|
70
88
|
|
|
71
89
|
```
|
|
72
|
-
/discuss-phase "..." #
|
|
73
|
-
/plan-architecture "..." #
|
|
74
|
-
/verify-paranoid "..." #
|
|
75
|
-
# ...
|
|
90
|
+
/discuss-phase "..." # Run only Phase-layer clarification
|
|
91
|
+
/plan-architecture "..." # Run only architecture review
|
|
92
|
+
/verify-paranoid "..." # Run only the Paranoid Staff Engineer review
|
|
93
|
+
# ... pick any of the other 18 sub-workflows
|
|
76
94
|
```
|
|
77
95
|
|
|
78
|
-
> "
|
|
96
|
+
> "I'm an expert, I'll decide myself" — skip the master, invoke a sub-workflow directly. Suits advanced users who know exactly which sub they need, or reuse of a single step.
|
|
79
97
|
|
|
80
98
|
---
|
|
81
99
|
|
|
82
|
-
## 📐 4-
|
|
100
|
+
## 📐 4-Stage Flow Diagram
|
|
83
101
|
|
|
84
102
|
```mermaid
|
|
85
103
|
graph TD
|
|
86
|
-
RS([⓪ /research —
|
|
87
|
-
subgraph Discuss[① Discuss
|
|
104
|
+
RS([⓪ /research — pre-stage multi-source investigation, optional]):::optional
|
|
105
|
+
subgraph Discuss[① Discuss — Strategic Clarification]
|
|
88
106
|
DM[/discuss master/]
|
|
89
107
|
DS[discuss-strategic]
|
|
90
108
|
DP[discuss-phase]
|
|
91
109
|
DT[discuss-subtask]
|
|
92
110
|
DM --> DS & DP & DT
|
|
93
111
|
end
|
|
94
|
-
subgraph Plan[② Plan
|
|
112
|
+
subgraph Plan[② Plan — Task Planning]
|
|
95
113
|
PM[/plan master/]
|
|
96
114
|
PA[plan-architecture]
|
|
97
115
|
PP[plan-phase]
|
|
98
116
|
PM --> PA & PP
|
|
99
117
|
end
|
|
100
|
-
subgraph Task[③ Task
|
|
118
|
+
subgraph Task[③ Task — Execution]
|
|
101
119
|
TM[/task master/]
|
|
102
120
|
TC[task-clarify]
|
|
103
121
|
TCo[task-code]
|
|
@@ -105,7 +123,7 @@ graph TD
|
|
|
105
123
|
TD[task-deliver]
|
|
106
124
|
TM --> TC --> TCo --> TT --> TD
|
|
107
125
|
end
|
|
108
|
-
subgraph Verify[④ Verify
|
|
126
|
+
subgraph Verify[④ Verify — Verification]
|
|
109
127
|
VMs[/verify master/]
|
|
110
128
|
VP[verify-progress]
|
|
111
129
|
VC[verify-code-review]
|
|
@@ -117,151 +135,151 @@ graph TD
|
|
|
117
135
|
VM[verify-multispec]
|
|
118
136
|
VMs --> VP & VC & VPa & VQ & VS & VD & VSi & VM
|
|
119
137
|
end
|
|
120
|
-
RT([⑤ /retro —
|
|
138
|
+
RT([⑤ /retro — milestone summary, optional]):::optional
|
|
121
139
|
RS --> Discuss
|
|
122
140
|
Discuss --> Plan --> Task --> Verify
|
|
123
141
|
Verify --> RT
|
|
124
142
|
classDef optional stroke-dasharray:5 5,fill:#f5f5f5,color:#666
|
|
125
143
|
```
|
|
126
144
|
|
|
127
|
-
>
|
|
145
|
+
> Dashed boxes = optional standalones (`/research` pre-strategic investigation / `/retro` post-milestone summary); solid boxes = main 4-stage cadence.
|
|
128
146
|
|
|
129
|
-
### 25
|
|
147
|
+
### 25-Workflow Overview Table
|
|
130
148
|
|
|
131
149
|
| Slash cmd | Stage | Type | Capability / Upstream | Brief |
|
|
132
150
|
|-----------|-------|------|----------------------|-------|
|
|
133
|
-
| `/auto` | All | **Super-master** | masterOrchestrator (
|
|
134
|
-
| `/discuss` | ① Discuss | Master | masterOrchestrator | 3
|
|
135
|
-
| `/discuss-strategic` | ① Discuss | Sub | gstack `/office-hours` + `/plan-ceo-review` + planning-with-files |
|
|
136
|
-
| `/discuss-phase` | ① Discuss | Sub | GSD `/gsd-discuss-phase` + planning-with-files | Phase
|
|
137
|
-
| `/discuss-subtask` | ① Discuss | Sub | superpowers brainstorming + `/grill-with-docs` |
|
|
138
|
-
| `/plan` | ② Plan | Master | masterOrchestrator |
|
|
139
|
-
| `/plan-architecture` | ② Plan | Sub | gstack `/plan-eng-review` |
|
|
140
|
-
| `/plan-phase` | ② Plan | Sub | GSD `/gsd-plan-phase` + planning-with-files `/plan` |
|
|
141
|
-
| `/task` | ③ Task | Master | masterOrchestrator |
|
|
142
|
-
| `/task-clarify` | ③ Task | Sub | superpowers brainstorming + `/grill-with-docs` conditional |
|
|
143
|
-
| `/task-code` | ③ Task | Sub | karpathy 4
|
|
144
|
-
| `/task-test` | ③ Task | Sub | superpowers TDD red-green-refactor + `/diagnose` conditional |
|
|
145
|
-
| `/task-deliver` | ③ Task | Sub | `ralph-loop` SDK wrapper + Agent Teams conditional |
|
|
146
|
-
| `/verify` | ④ Verify | Master | masterOrchestrator | 7
|
|
147
|
-
| `/verify-progress` | ④ Verify | Sub | GSD `/gsd-verify-work` + `/gsd-progress` |
|
|
148
|
-
| `/verify-code-review` | ④ Verify | Sub | `code-review`
|
|
149
|
-
| `/verify-paranoid` | ④ Verify | Sub | gstack `/review` (Paranoid Staff Engineer) |
|
|
150
|
-
| `/verify-qa` | ④ Verify | Sub | gstack `/qa` + playwright-cli / `@playwright/test` / webapp-testing |
|
|
151
|
+
| `/auto` | All | **Super-master** | masterOrchestrator (across 6 stages) | One-shot full 6-stage run (research conditional → discuss → plan → task → verify → retro mandatory); AI 1-shot complexity judge + understanding check + mandatory retro; `--staged` opt-in stage gate |
|
|
152
|
+
| `/discuss` | ① Discuss | Master | masterOrchestrator | 3 subs parallel gate-eval (chain-isolation rule) |
|
|
153
|
+
| `/discuss-strategic` | ① Discuss | Sub | gstack `/office-hours` + `/plan-ceo-review` + planning-with-files | Strategic layer — mandatory governance for new features / new milestones / product direction (findings.md persisted) |
|
|
154
|
+
| `/discuss-phase` | ① Discuss | Sub | GSD `/gsd-discuss-phase` + planning-with-files | Phase layer — ≥2 open decisions / gray-area clarification (findings.md + knowledge.md persisted) |
|
|
155
|
+
| `/discuss-subtask` | ① Discuss | Sub | superpowers brainstorming + `/grill-with-docs` | Subtask layer — ≥2 approaches / core algorithm / API contract (ephemeral short discussion, not persisted) |
|
|
156
|
+
| `/plan` | ② Plan | Master | masterOrchestrator | Serial invoke of 2 subs (architecture conditional → phase always) |
|
|
157
|
+
| `/plan-architecture` | ② Plan | Sub | gstack `/plan-eng-review` | Architecture layer — mandatory governance gate for complex architecture |
|
|
158
|
+
| `/plan-phase` | ② Plan | Sub | GSD `/gsd-plan-phase` + planning-with-files `/plan` | Plan layer — persists `task_plan.md` + `progress.md` |
|
|
159
|
+
| `/task` | ③ Task | Master | masterOrchestrator | Serial invoke of 4 subs per subtask (clarify → code → test → deliver) |
|
|
160
|
+
| `/task-clarify` | ③ Task | Sub | superpowers brainstorming + `/grill-with-docs` conditional | Subtask startup clarification gate |
|
|
161
|
+
| `/task-code` | ③ Task | Sub | karpathy 4 principles + `/zoom-out` / `/improve-codebase-architecture` / `/diagnose` conditional | Subtask coding + cross-session progress.md sync |
|
|
162
|
+
| `/task-test` | ③ Task | Sub | superpowers TDD red-green-refactor + `/diagnose` conditional | TDD mandatory for core logic (alias mattpocock `/tdd`) |
|
|
163
|
+
| `/task-deliver` | ③ Task | Sub | `ralph-loop` SDK wrapper + Agent Teams conditional | Until verbatim `COMPLETE` + R20.10 max_iter fallback |
|
|
164
|
+
| `/verify` | ④ Verify | Master | masterOrchestrator | 7 subs conditional dispatch by scenario |
|
|
165
|
+
| `/verify-progress` | ④ Verify | Sub | GSD `/gsd-verify-work` + `/gsd-progress` | Mandatory serial starting point — UAT acceptance + state sync |
|
|
166
|
+
| `/verify-code-review` | ④ Verify | Sub | `code-review` multi-subagent fan-out | High-confidence findings in parallel |
|
|
167
|
+
| `/verify-paranoid` | ④ Verify | Sub | gstack `/review` (Paranoid Staff Engineer) | Mandatory for critical-module pre-PR |
|
|
168
|
+
| `/verify-qa` | ④ Verify | Sub | gstack `/qa` + playwright-cli / `@playwright/test` / webapp-testing | End-to-end QA (has_ui_changes conditional) |
|
|
151
169
|
| `/verify-security` | ④ Verify | Sub | gstack `/cso` | OWASP / auth / secrets (has_auth_or_secrets conditional) |
|
|
152
|
-
| `/verify-design` | ④ Verify | Sub | gstack `/design-review` + ui-ux-pro-max + frontend-design |
|
|
153
|
-
| `/verify-simplify` | ④ Verify | Sub | `code-simplifier` |
|
|
154
|
-
| `/verify-multispec` | ④ Verify | Sub | 4-specialist Agent Team Pattern C |
|
|
155
|
-
| `/research` | Standalone | Standalone | Tavily / Exa MCP + ctx7 + GSD `/gsd-discuss-phase` |
|
|
156
|
-
| `/retro` | Standalone | Standalone | gstack `/retro` + planning-with-files RETROSPECTIVE.md |
|
|
170
|
+
| `/verify-design` | ④ Verify | Sub | gstack `/design-review` + ui-ux-pro-max + frontend-design | Design system consistency (has_design_changes conditional) |
|
|
171
|
+
| `/verify-simplify` | ④ Verify | Sub | `code-simplifier` | Final serial simplification |
|
|
172
|
+
| `/verify-multispec` | ④ Verify | Sub | 4-specialist Agent Team Pattern C | Critical release / large refactor PR escalation (mutual SendMessage cross-examination) |
|
|
173
|
+
| `/research` | Standalone | Standalone | Tavily / Exa MCP + ctx7 + GSD `/gsd-discuss-phase` | Multi-source investigation (Stage ① alternate) |
|
|
174
|
+
| `/retro` | Standalone | Standalone | gstack `/retro` + planning-with-files RETROSPECTIVE.md | Project / milestone close-out summary |
|
|
157
175
|
|
|
158
|
-
> Master orchestrator
|
|
159
|
-
>
|
|
176
|
+
> Master orchestrator auto gate-routes to the right sub (chain-isolation rule — non-firing subs are transparently declared skipped).
|
|
177
|
+
> Direct sub invocation also bypasses the master to run a single stage, e.g. `/discuss-strategic "new feature X"`.
|
|
160
178
|
|
|
161
179
|
---
|
|
162
180
|
|
|
163
|
-
## ⚡
|
|
181
|
+
## ⚡ Usage Flow
|
|
164
182
|
|
|
165
|
-
4-stage
|
|
183
|
+
4-stage three-layer-stack methodology — recommended driving via the 4 master orchestrators in series:
|
|
166
184
|
|
|
167
185
|
```
|
|
168
186
|
/discuss → /plan → /task → /verify
|
|
169
187
|
① ② ③ ④
|
|
170
188
|
```
|
|
171
189
|
|
|
172
|
-
| Stage | Master |
|
|
190
|
+
| Stage | Master | Main sub-workflows | Upstream collaboration |
|
|
173
191
|
| ---- | ---- | ---- | ---- |
|
|
174
|
-
| ① **Discuss** | `/discuss` | strategic / phase / subtask (3
|
|
192
|
+
| ① **Discuss** | `/discuss` | strategic / phase / subtask (3 in parallel) | gstack `/office-hours` + GSD `/gsd-discuss-phase` + superpowers brainstorming |
|
|
175
193
|
| ② **Plan** | `/plan` | architecture (conditional) → phase | gstack `/plan-eng-review` + GSD `/gsd-plan-phase` + planning-with-files |
|
|
176
|
-
| ③ **Task** | `/task` | clarify → code → test → deliver (4
|
|
194
|
+
| ③ **Task** | `/task` | clarify → code → test → deliver (4 serial per subtask) | karpathy principles + mattpocock moves + superpowers TDD + `ralph-loop` |
|
|
177
195
|
| ④ **Verify** | `/verify` | progress → 5 parallel conditional → simplify (+ multispec critical) | GSD `/gsd-verify-work` + code-review + gstack `/review` / `/qa` / `/cso` / `/design-review` + code-simplifier |
|
|
178
196
|
|
|
179
|
-
|
|
197
|
+
Practical example:
|
|
180
198
|
|
|
181
199
|
```bash
|
|
182
|
-
# 1.
|
|
200
|
+
# 1. Install workflow upstreams (one line installs gstack + GSD + superpowers + planning-with-files)
|
|
183
201
|
harnessed setup
|
|
184
202
|
|
|
185
|
-
# 2.
|
|
186
|
-
/discuss "
|
|
187
|
-
/plan "
|
|
188
|
-
/task "subtask-1: API contract"
|
|
189
|
-
/verify "phase-1"
|
|
203
|
+
# 2. Run the 4-stage cadence inside Claude Code
|
|
204
|
+
/discuss "new feature X" # Strategic + Phase + Subtask 3-layer clarification
|
|
205
|
+
/plan "new feature X" # Architecture (conditional) + plan (task graph persisted)
|
|
206
|
+
/task "subtask-1: API contract" # 4 subs serial per subtask
|
|
207
|
+
/verify "phase-1" # 7 subs conditional
|
|
190
208
|
|
|
191
|
-
# 3.
|
|
209
|
+
# 3. Resume after interruption (any time)
|
|
192
210
|
harnessed resume
|
|
193
211
|
```
|
|
194
212
|
|
|
195
|
-
>
|
|
213
|
+
> You can also invoke subs directly to bypass the master and run just one layer, e.g. `/verify-paranoid` runs only the Paranoid Staff Engineer review.
|
|
196
214
|
|
|
197
|
-
📊
|
|
215
|
+
📊 Detailed mermaid + full stage walkthroughs: [docs/WORKFLOW.md](./docs/WORKFLOW.md)
|
|
198
216
|
|
|
199
217
|
---
|
|
200
218
|
|
|
201
|
-
## 🗂️
|
|
219
|
+
## 🗂️ Architecture (4-stage namespace-layered)
|
|
202
220
|
|
|
203
|
-
### 1.
|
|
221
|
+
### 1. Directory Structure
|
|
204
222
|
|
|
205
223
|
```
|
|
206
224
|
harnessed/
|
|
207
|
-
├── manifests/ # L1:
|
|
208
|
-
├── workflows/ # L6: composition
|
|
209
|
-
│ ├── discuss/ # Stage ① 3
|
|
225
|
+
├── manifests/ # L1: upstream description layer (NOT vendored)
|
|
226
|
+
├── workflows/ # L6: composition skills (4-stage conductor's baton)
|
|
227
|
+
│ ├── discuss/ # Stage ① 3 layers (strategic + phase + subtask)
|
|
210
228
|
│ │ ├── auto/ # /discuss master gate-route
|
|
211
229
|
│ │ ├── strategic/ # /discuss-strategic (gstack /office-hours + /plan-ceo-review)
|
|
212
230
|
│ │ ├── phase/ # /discuss-phase (GSD /gsd-discuss-phase)
|
|
213
231
|
│ │ └── subtask/ # /discuss-subtask (superpowers brainstorming)
|
|
214
|
-
│ ├── plan/ # Stage ② (architecture + phase
|
|
232
|
+
│ ├── plan/ # Stage ② (architecture + phase task graph)
|
|
215
233
|
│ ├── task/ # Stage ③ (clarify + code + test + deliver)
|
|
216
234
|
│ ├── verify/ # Stage ④ (progress + code-review + paranoid + qa + cso + design + simplify + multispec)
|
|
217
235
|
│ ├── research/ # standalone Stage ① alternate
|
|
218
236
|
│ ├── retro/ # standalone post-④ milestone close
|
|
219
|
-
│ ├── capabilities.yaml # L5a: ~70
|
|
237
|
+
│ ├── capabilities.yaml # L5a: ~70 entries, 7 categories SoT
|
|
220
238
|
│ ├── defaults.yaml # ralph_max_iterations per workflow phase
|
|
221
|
-
│ ├── judgments/ # L5a:
|
|
239
|
+
│ ├── judgments/ # L5a: three-layer-stack criteria + parallelism + tdd + fallback + rules-routing
|
|
222
240
|
│ │ ├── strategic-gate.yaml
|
|
223
241
|
│ │ ├── phase-gate.yaml
|
|
224
242
|
│ │ ├── subtask-gate.yaml
|
|
225
243
|
│ │ ├── parallelism-gate.yaml # L5b execution mechanism routing
|
|
226
244
|
│ │ ├── tdd-gate.yaml
|
|
227
|
-
│ │ ├── fallback.yaml # 3
|
|
228
|
-
│ │ ├── web-design-routing.yaml # UI
|
|
229
|
-
│ │ ├── web-testing-routing.yaml # E2E /
|
|
230
|
-
│ │ ├── web-search-routing.yaml #
|
|
231
|
-
│ │ └── stage-routing.yaml # master orchestrator sub-stage
|
|
232
|
-
│ └── disciplines/ # L0:
|
|
233
|
-
│ ├── karpathy.yaml # 4
|
|
245
|
+
│ │ ├── fallback.yaml # 3 rules: skip_with_transparency + override + chain_isolation
|
|
246
|
+
│ │ ├── web-design-routing.yaml # UI design tool routing
|
|
247
|
+
│ │ ├── web-testing-routing.yaml # E2E / browser testing tool routing
|
|
248
|
+
│ │ ├── web-search-routing.yaml # Web search / doc fetch routing
|
|
249
|
+
│ │ └── stage-routing.yaml # master orchestrator sub-stage routing
|
|
250
|
+
│ └── disciplines/ # L0: global cross-stage behavior baseline
|
|
251
|
+
│ ├── karpathy.yaml # 4 principles + ≤200L
|
|
234
252
|
│ ├── output-style.yaml # BLUF + no-emoji + no-em-dash
|
|
235
253
|
│ ├── language.yaml # zh-Hans default + English preserve
|
|
236
254
|
│ ├── operational.yaml # biome preempt + A7 + commit safety
|
|
237
|
-
│ ├── priority.yaml # skill conflict
|
|
238
|
-
│ └── protocols.yaml # cc-handoff design doc
|
|
255
|
+
│ ├── priority.yaml # skill conflict arbitration
|
|
256
|
+
│ └── protocols.yaml # cc-handoff design doc self-contained
|
|
239
257
|
├── routing/ # L4: routing engine SSOT (decision_rules.yaml)
|
|
240
258
|
├── schemas/ # L3: JSON Schema (IDE / CI consume)
|
|
241
259
|
├── src/ # L4: TS engine (workflow + routing + cli + installers + checkpoint + audit + state)
|
|
242
260
|
├── tests/ # vitest unit + integration + dogfood (R8.1 dogfood-first)
|
|
243
261
|
├── scripts/ # CI gate (check-workflow-schema, transparency-verdict, state-archive)
|
|
244
262
|
├── .planning/ # project memory (STATE + ROADMAP + REQUIREMENTS + per-phase + milestones)
|
|
245
|
-
└── docs/adr/ #
|
|
263
|
+
└── docs/adr/ # architecture decision records
|
|
246
264
|
```
|
|
247
265
|
|
|
248
|
-
### 2.
|
|
266
|
+
### 2. Logical Layering (8 layers)
|
|
249
267
|
|
|
250
268
|
```
|
|
251
269
|
┌────────────────────────────────────────────────────────────┐
|
|
252
270
|
│ L7 User-facing slash cmd + harnessed CLI │
|
|
253
|
-
│ /discuss /plan /task /verify (master) +
|
|
271
|
+
│ /discuss /plan /task /verify (master) + 18 sub + /research /retro + /auto super-master
|
|
254
272
|
│ + direct gstack invoke (30+ optional): /office-hours /review /qa /...
|
|
255
273
|
├────────────────────────────────────────────────────────────┤
|
|
256
274
|
│ L6 Workflow orchestration (workflows/<stage>/<sub>/) │
|
|
257
275
|
├────────────────────────────────────────────────────────────┤
|
|
258
276
|
│ L5b Execution Mechanism (orthogonal): subagent / Agent Teams │
|
|
259
|
-
│ /
|
|
260
|
-
│ parallelism-gate.yaml:
|
|
261
|
-
│ Pattern A
|
|
277
|
+
│ / main session + ralph-loop wrapper │
|
|
278
|
+
│ parallelism-gate.yaml: default subagent → escalate 5 triggers │
|
|
279
|
+
│ Pattern A full-stack three-way / B opposing hypotheses / C multi-dim review │
|
|
262
280
|
├────────────────────────────────────────────────────────────┤
|
|
263
281
|
│ L5a Capability + Judgment + Defaults SoT │
|
|
264
|
-
│ capabilities.yaml (7
|
|
282
|
+
│ capabilities.yaml (7 categories) + judgments/ (10 files) + │
|
|
265
283
|
│ defaults.yaml │
|
|
266
284
|
├────────────────────────────────────────────────────────────┤
|
|
267
285
|
│ L4 Runtime engine (workflow / routing / handlers) │
|
|
@@ -272,17 +290,17 @@ harnessed/
|
|
|
272
290
|
├────────────────────────────────────────────────────────────┤
|
|
273
291
|
│ L1 Upstream components (NOT vendored) │
|
|
274
292
|
├────────────────────────────────────────────────────────────┤
|
|
275
|
-
│ L0 Discipline Substrate (
|
|
276
|
-
│ karpathy
|
|
293
|
+
│ L0 Discipline Substrate (applies globally) │
|
|
294
|
+
│ karpathy principles + output-style + language + operational + │
|
|
277
295
|
│ priority + protocols (applied universally to L1-L7) │
|
|
278
296
|
└────────────────────────────────────────────────────────────┘
|
|
279
297
|
```
|
|
280
298
|
|
|
281
|
-
### 3. Cross-cutting Capabilities (capabilities.yaml 7
|
|
299
|
+
### 3. Cross-cutting Capabilities (capabilities.yaml — 7 categories, ~83 entries)
|
|
282
300
|
|
|
283
301
|
```
|
|
284
302
|
behavioral (6): karpathy-guidelines + output-style + language + operational + priority + protocols
|
|
285
|
-
tool-slash-cmd (~60): gstack 30+ optional + gsd 10+ + mattpocock 12
|
|
303
|
+
tool-slash-cmd (~60): gstack 30+ optional + gsd 10+ + mattpocock 12 high-frequency + etc.
|
|
286
304
|
tool-mcp (3): chrome-devtools-mcp / tavily-mcp / exa-mcp
|
|
287
305
|
tool-cli (2): ctx7 / gws
|
|
288
306
|
tool-plugin (2): planning-with-files / @playwright/test
|
|
@@ -290,18 +308,18 @@ tool-bundled (3): ralph-loop / webapp-testing / playwright-cli
|
|
|
290
308
|
agent-platform (3): agent-teams-create / send-message / shutdown
|
|
291
309
|
```
|
|
292
310
|
|
|
293
|
-
### 4.
|
|
311
|
+
### 4. Data Flow Example (user invokes `/discuss "new feature X"`)
|
|
294
312
|
|
|
295
313
|
```
|
|
296
|
-
[L7] User invokes /discuss "
|
|
314
|
+
[L7] User invokes /discuss "new feature X"
|
|
297
315
|
↓
|
|
298
316
|
[L6] workflows/discuss/auto/workflow.yaml master orchestrator
|
|
299
317
|
↓
|
|
300
|
-
[L5a] judgments.strategic-gate.fires + phase-gate.fires + subtask-gate.fires (3-way
|
|
318
|
+
[L5a] judgments.strategic-gate.fires + phase-gate.fires + subtask-gate.fires (3-way parallel eval)
|
|
301
319
|
↓
|
|
302
320
|
[L4] judgmentResolver.ts (4-level ref split) + exprBuilder.ts (expr-eval evaluate)
|
|
303
321
|
↓
|
|
304
|
-
[L0] discipline.priority-hierarchy
|
|
322
|
+
[L0] discipline.priority-hierarchy arbitrates tool conflicts / output-style formats output
|
|
305
323
|
↓
|
|
306
324
|
[fires=true sub] → invoke sub-workflow (/discuss-strategic / /discuss-phase / /discuss-subtask)
|
|
307
325
|
↓ for each sub:
|
|
@@ -310,150 +328,149 @@ agent-platform (3): agent-teams-create / send-message / shutdown
|
|
|
310
328
|
├─ parallelism: judgments.parallelism-gate.<route>.fires (L5b mechanism)
|
|
311
329
|
└─ phase invocations execute via capability template interpolation
|
|
312
330
|
↓
|
|
313
|
-
[fallback.yaml chain-isolation]
|
|
314
|
-
[Skip
|
|
331
|
+
[fallback.yaml chain-isolation] 3 layers judged independently, not serially dependent
|
|
332
|
+
[Skip transparency declaration] non-firing subs → "⚠️ Skipped <sub> because <reason>"
|
|
315
333
|
↓
|
|
316
334
|
planning-with-files /plan (cross-cutting tool) → write artifacts to .planning/<phase-id>/
|
|
317
335
|
↓
|
|
318
336
|
[L4] state.ts writeCurrentWorkflow (proper-lockfile) + audit.append (12-field JSONL)
|
|
319
337
|
```
|
|
320
338
|
|
|
321
|
-
### 5.
|
|
339
|
+
### 5. Decision Routing Matrix (rules-based, codified in judgments + capabilities)
|
|
322
340
|
|
|
323
|
-
|
|
|
341
|
+
| Scenario | Default → Escalate |
|
|
324
342
|
|------|---------------------|
|
|
325
|
-
|
|
|
326
|
-
| UI
|
|
327
|
-
| E2E
|
|
328
|
-
| E2E commit-able TS | @playwright/test
|
|
329
|
-
| E2E Python
|
|
330
|
-
|
|
|
331
|
-
| Web
|
|
332
|
-
| Web
|
|
333
|
-
|
|
|
343
|
+
| Parallelism mechanism | subagent → Agent Teams Pattern A/B/C (5 triggers) |
|
|
344
|
+
| UI design primary plan | ui-ux-pro-max → frontend-design (user explicitly asks for style) |
|
|
345
|
+
| E2E browser exploration | playwright-cli (one-line Bash, token-efficient) |
|
|
346
|
+
| E2E commit-able TS | @playwright/test default |
|
|
347
|
+
| E2E Python backend linkage | webapp-testing |
|
|
348
|
+
| Performance / a11y / memory diagnostics | chrome-devtools-mcp |
|
|
349
|
+
| Web search (keyword) | Tavily MCP default |
|
|
350
|
+
| Web search (descriptive / academic) | Exa MCP |
|
|
351
|
+
| Library API docs | ctx7 CLI |
|
|
334
352
|
| GitHub URL | gh CLI |
|
|
335
|
-
|
|
|
353
|
+
| Single URL fetch | WebFetch built-in |
|
|
336
354
|
| Gmail / Drive / Calendar | gws CLI |
|
|
337
|
-
|
|
|
338
|
-
| TDD
|
|
339
|
-
|
|
|
340
|
-
|
|
|
341
|
-
|
|
|
342
|
-
| `/auto`
|
|
343
|
-
| `/auto`
|
|
355
|
+
| Architecture review (complex) | gstack /plan-eng-review |
|
|
356
|
+
| TDD mandatory (core algorithm) | superpowers TDD OR mattpocock /tdd |
|
|
357
|
+
| Critical module PR | gstack /review |
|
|
358
|
+
| Large refactor PR multi-dim review | 4-specialist Agent Team Pattern C |
|
|
359
|
+
| Cross-session hand-off | discipline.protocols self-contained design doc |
|
|
360
|
+
| `/auto` complexity for large requirements | AI 1-shot judge → auto-suggest `--staged` (n abort suggests manual `/discuss`) |
|
|
361
|
+
| `/auto` requirement understanding | prompt before start → n auto-adds `/research` multi-source investigation |
|
|
344
362
|
|
|
345
363
|
---
|
|
346
364
|
|
|
347
|
-
## 🛠️
|
|
365
|
+
## 🛠️ Operational Commands
|
|
348
366
|
|
|
349
|
-
>
|
|
367
|
+
> These are harnessed's own maintenance commands (setup / health check / backup-rollback / state recovery, etc.). For day-to-day feature development just use the slash commands above — you usually don't need these.
|
|
350
368
|
|
|
351
|
-
### CLI
|
|
369
|
+
### CLI Commands
|
|
352
370
|
|
|
353
|
-
|
|
|
371
|
+
| Command | Description |
|
|
354
372
|
| ---- | ---- |
|
|
355
|
-
| `harnessed setup` |
|
|
356
|
-
| `harnessed resume` |
|
|
357
|
-
| `harnessed status` |
|
|
358
|
-
| `harnessed doctor` | 8-check
|
|
359
|
-
| `harnessed install <name>` |
|
|
360
|
-
| `harnessed uninstall <name>` |
|
|
361
|
-
| `harnessed backup` |
|
|
362
|
-
| `harnessed rollback <timestamp>` |
|
|
363
|
-
| `harnessed gc` |
|
|
364
|
-
| `harnessed audit-log` |
|
|
365
|
-
|
|
366
|
-
###
|
|
367
|
-
|
|
368
|
-
>
|
|
369
|
-
|
|
370
|
-
| Flag |
|
|
373
|
+
| `harnessed setup` | One-time setup; installs workflow skills to `~/.claude/skills/` + MCP to `~/.claude.json` |
|
|
374
|
+
| `harnessed resume` | Resume from the most recent checkpoint after a session interruption |
|
|
375
|
+
| `harnessed status` | Current phase + lock holder |
|
|
376
|
+
| `harnessed doctor` | 8-check health check (Node / MCP / jq / Win bash / routing / token budget, etc.) |
|
|
377
|
+
| `harnessed install <name>` | Install an upstream manifest |
|
|
378
|
+
| `harnessed uninstall <name>` | Reverse uninstall |
|
|
379
|
+
| `harnessed backup` | Snapshot backup management |
|
|
380
|
+
| `harnessed rollback <timestamp>` | One-line rollback (EOL preserve + sha1 verify) |
|
|
381
|
+
| `harnessed gc` | Clean up expired backups |
|
|
382
|
+
| `harnessed audit-log` | Routing transparency log query (supports `--filter` jq expression) |
|
|
383
|
+
|
|
384
|
+
### Flags
|
|
385
|
+
|
|
386
|
+
> All commands **apply (immediate write)** by default — no flag needed. Advanced users can add `--dry-run` to preview.
|
|
387
|
+
|
|
388
|
+
| Flag | Description |
|
|
371
389
|
| ---- | ---- |
|
|
372
|
-
| `--dry-run` |
|
|
373
|
-
| `--non-interactive` | CI /
|
|
374
|
-
| `--system` | L4
|
|
375
|
-
| `--yes` |
|
|
376
|
-
| `--full-diff` |
|
|
377
|
-
| `--no-color` |
|
|
390
|
+
| `--dry-run` | Preview without writing to disk (advanced opt-in) |
|
|
391
|
+
| `--non-interactive` | CI / scripted scenarios |
|
|
392
|
+
| `--system` | Allow L4 global install (otherwise downgrade to L1 npx ephemeral) |
|
|
393
|
+
| `--yes` | Skip interactive confirm on uninstall |
|
|
394
|
+
| `--full-diff` | Expand diffs folded above 200 lines |
|
|
395
|
+
| `--no-color` | Force nocolor (even on TTY) |
|
|
378
396
|
|
|
379
|
-
> `--apply` flag 仍保留为向后兼容 alias (no-op, 旧脚本不破)。
|
|
380
397
|
|
|
381
398
|
---
|
|
382
399
|
|
|
383
400
|
## ❓ FAQ
|
|
384
401
|
|
|
385
402
|
<details>
|
|
386
|
-
<summary><b>Q1.
|
|
403
|
+
<summary><b>Q1. Do I still need to install superpowers / gstack / GSD upstreams after installing harnessed?</b></summary>
|
|
387
404
|
|
|
388
405
|
<br>
|
|
389
406
|
|
|
390
|
-
|
|
407
|
+
Yes, but **the user experience = one command**:
|
|
391
408
|
|
|
392
409
|
```bash
|
|
393
|
-
harnessed setup
|
|
410
|
+
harnessed setup # Auto-installs gstack + GSD + superpowers + planning-with-files; 25 workflow skills land in ~/.claude/skills/ + Agent Teams env var auto-written to ~/.claude.json
|
|
394
411
|
```
|
|
395
412
|
|
|
396
|
-
|
|
413
|
+
Think `brew install <formula>` pulling the full dependency set — you don't need to `brew install` each dependency separately.
|
|
397
414
|
|
|
398
415
|
</details>
|
|
399
416
|
|
|
400
417
|
<details>
|
|
401
|
-
<summary><b>Q2.
|
|
418
|
+
<summary><b>Q2. Why not just vendor superpowers / gstack into the harnessed repo?</b></summary>
|
|
402
419
|
|
|
403
420
|
<br>
|
|
404
421
|
|
|
405
|
-
4
|
|
422
|
+
4 reasons:
|
|
406
423
|
|
|
407
|
-
1.
|
|
408
|
-
2. **License + attribution
|
|
409
|
-
3.
|
|
410
|
-
4. **Bus factor 1** —
|
|
424
|
+
1. **Differentiation philosophy** — harnessed is the "assembly-ist package manager" counterposed to the "all-in-one self-built" camp. Vendoring = losing the wedge → becoming yet another plugin pack
|
|
425
|
+
2. **License + attribution nightmare** — vendoring 4-5 actively maintained upstreams = a complex license patchwork
|
|
426
|
+
3. **Upstream upgrades flip direction** — current manifest description lets users re-install for the latest version on upstream upgrade; vendoring forces manual code sync and falls perpetually behind
|
|
427
|
+
4. **Bus factor 1** — a single maintainer keeping 4-5 vendored upstreams in sync = accelerated burnout
|
|
411
428
|
|
|
412
429
|
</details>
|
|
413
430
|
|
|
414
431
|
<details>
|
|
415
|
-
<summary><b>Q3. gstack / GSD / superpowers
|
|
432
|
+
<summary><b>Q3. gstack / GSD / superpowers all look like plan/discuss tools — aren't they overlapping?</b></summary>
|
|
416
433
|
|
|
417
434
|
<br>
|
|
418
435
|
|
|
419
|
-
|
|
436
|
+
**No**. They are different stages of the three-layer stack:
|
|
420
437
|
|
|
421
|
-
|
|
|
438
|
+
| Stage | Upstream | Responsibility |
|
|
422
439
|
| ---- | ---- | ---- |
|
|
423
|
-
| Governance | gstack |
|
|
424
|
-
| Brainstorming | superpowers |
|
|
425
|
-
| Orchestration | GSD |
|
|
426
|
-
| Persistence | planning-with-files |
|
|
440
|
+
| Governance | gstack | Multi-role decision gates (CEO / EM / Designer / Paranoid Engineer) |
|
|
441
|
+
| Brainstorming | superpowers | Subtask design clarification, alternative comparison |
|
|
442
|
+
| Orchestration | GSD | High-level phase task graph + dependency analysis |
|
|
443
|
+
| Persistence | planning-with-files | Persists `task_plan.md` / `progress.md` / `findings.md` |
|
|
427
444
|
|
|
428
|
-
`/discuss /plan /task /verify` 4
|
|
445
|
+
`/discuss /plan /task /verify` — the 4 masters string the 4 stages together; each master internally delegates to its sub. Each stage does a different thing and feeds the next. **No merging**.
|
|
429
446
|
|
|
430
447
|
</details>
|
|
431
448
|
|
|
432
449
|
<details>
|
|
433
|
-
<summary><b>Q4. workflow
|
|
450
|
+
<summary><b>Q4. Do workflow phases run automatically or wait for the user?</b></summary>
|
|
434
451
|
|
|
435
452
|
<br>
|
|
436
453
|
|
|
437
|
-
|
|
454
|
+
Depends on the `pause` field in `workflows/<name>/SKILL.md` frontmatter:
|
|
438
455
|
|
|
439
|
-
- `pause: human_review` →
|
|
440
|
-
-
|
|
456
|
+
- `pause: human_review` → blocks waiting for user approval (governance gate / final lock, e.g. `/discuss-strategic` gstack `/office-hours` + `/plan-architecture` `/plan-eng-review` lock-in gate)
|
|
457
|
+
- No `pause` → auto-chains to the next phase
|
|
441
458
|
|
|
442
|
-
|
|
459
|
+
Each phase output is written to `.harnessed/checkpoints/`; after a session interruption `harnessed resume` continues from the latest checkpoint.
|
|
443
460
|
|
|
444
461
|
</details>
|
|
445
462
|
|
|
446
463
|
<details>
|
|
447
|
-
<summary><b>Q5. harnessed
|
|
464
|
+
<summary><b>Q5. Is harnessed itself a CC plugin?</b></summary>
|
|
448
465
|
|
|
449
466
|
<br>
|
|
450
467
|
|
|
451
|
-
|
|
468
|
+
A hybrid:
|
|
452
469
|
|
|
453
|
-
- `npx harnessed@latest setup`
|
|
454
|
-
- setup
|
|
455
|
-
- `/discuss` / `/plan` / `/task` / `/verify`
|
|
456
|
-
- CLI
|
|
470
|
+
- `npx harnessed@latest setup` runs the **Node.js CLI** (`bin/harnessed`)
|
|
471
|
+
- setup installs **workflow skills** (markdown) into `~/.claude/skills/`, loaded by the Claude Code runtime
|
|
472
|
+
- `/discuss` / `/plan` / `/task` / `/verify` etc. are slash commands inside CC that trigger skill execution
|
|
473
|
+
- The CLI and the CC skills share the `.harnessed/checkpoints/` state directory
|
|
457
474
|
|
|
458
475
|
</details>
|
|
459
476
|
|
|
@@ -462,6 +479,6 @@ harnessed setup --apply # 自动装齐 gstack + GSD + superpowers + planning-wi
|
|
|
462
479
|
|
|
463
480
|
## License
|
|
464
481
|
|
|
465
|
-
[Apache-2.0](./LICENSE) —
|
|
482
|
+
[Apache-2.0](./LICENSE) — see [NOTICE](./NOTICE) (includes Harness Inc. trademark disclaimer)
|
|
466
483
|
|
|
467
|
-
|
|
484
|
+
Support development: [](https://github.com/sponsors/easyinplay)
|