harnessed 3.3.1 → 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 +207 -198
- package/dist/cli.mjs +335 -142
- 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,111 +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.
|
|
38
47
|
|
|
39
|
-
🤖
|
|
48
|
+
🤖 **Or have an AI install it for you** — paste this sentence to Claude Code (or any AI assistant):
|
|
40
49
|
|
|
41
|
-
>
|
|
50
|
+
> Install harnessed for me following the guide at `https://github.com/easyinplay/harnessed/blob/main/INSTALL-WITH-AI.md`
|
|
42
51
|
|
|
43
|
-
AI
|
|
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.
|
|
44
53
|
|
|
45
54
|
> [!TIP]
|
|
46
|
-
> 🚀
|
|
47
|
-
>
|
|
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.
|
|
48
57
|
|
|
49
58
|
---
|
|
50
59
|
|
|
51
|
-
## 🚀
|
|
60
|
+
## 🚀 Quick Start — 3 Options
|
|
52
61
|
|
|
53
|
-
|
|
62
|
+
In order of increasing user intervention:
|
|
54
63
|
|
|
55
|
-
### 🎯
|
|
64
|
+
### 🎯 Auto Mode (Recommended for newcomers / don't want to think hard)
|
|
56
65
|
|
|
57
66
|
```
|
|
58
|
-
/auto "
|
|
67
|
+
/auto "requirement X"
|
|
59
68
|
|
|
60
|
-
#
|
|
61
|
-
|
|
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
|
|
62
72
|
```
|
|
63
73
|
|
|
64
|
-
>
|
|
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`.
|
|
65
75
|
|
|
66
|
-
### 📂
|
|
76
|
+
### 📂 Stage Mode (Recommended for power users / want to review intermediate results)
|
|
67
77
|
|
|
68
78
|
```
|
|
69
|
-
/discuss "
|
|
70
|
-
/plan "
|
|
71
|
-
/task "subtask-1"
|
|
72
|
-
/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
|
|
73
83
|
```
|
|
74
84
|
|
|
75
|
-
>
|
|
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.
|
|
76
86
|
|
|
77
|
-
### 🔬
|
|
87
|
+
### 🔬 Surgical Mode (Expert mode / you know what you want)
|
|
78
88
|
|
|
79
89
|
```
|
|
80
|
-
/discuss-phase "..." #
|
|
81
|
-
/plan-architecture "..." #
|
|
82
|
-
/verify-paranoid "..." #
|
|
83
|
-
# ...
|
|
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
|
|
84
94
|
```
|
|
85
95
|
|
|
86
|
-
> "
|
|
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.
|
|
87
97
|
|
|
88
98
|
---
|
|
89
99
|
|
|
90
|
-
## 📐 4-
|
|
100
|
+
## 📐 4-Stage Flow Diagram
|
|
91
101
|
|
|
92
102
|
```mermaid
|
|
93
103
|
graph TD
|
|
94
|
-
RS([⓪ /research —
|
|
95
|
-
subgraph Discuss[① Discuss
|
|
104
|
+
RS([⓪ /research — pre-stage multi-source investigation, optional]):::optional
|
|
105
|
+
subgraph Discuss[① Discuss — Strategic Clarification]
|
|
96
106
|
DM[/discuss master/]
|
|
97
107
|
DS[discuss-strategic]
|
|
98
108
|
DP[discuss-phase]
|
|
99
109
|
DT[discuss-subtask]
|
|
100
110
|
DM --> DS & DP & DT
|
|
101
111
|
end
|
|
102
|
-
subgraph Plan[② Plan
|
|
112
|
+
subgraph Plan[② Plan — Task Planning]
|
|
103
113
|
PM[/plan master/]
|
|
104
114
|
PA[plan-architecture]
|
|
105
115
|
PP[plan-phase]
|
|
106
116
|
PM --> PA & PP
|
|
107
117
|
end
|
|
108
|
-
subgraph Task[③ Task
|
|
118
|
+
subgraph Task[③ Task — Execution]
|
|
109
119
|
TM[/task master/]
|
|
110
120
|
TC[task-clarify]
|
|
111
121
|
TCo[task-code]
|
|
@@ -113,7 +123,7 @@ graph TD
|
|
|
113
123
|
TD[task-deliver]
|
|
114
124
|
TM --> TC --> TCo --> TT --> TD
|
|
115
125
|
end
|
|
116
|
-
subgraph Verify[④ Verify
|
|
126
|
+
subgraph Verify[④ Verify — Verification]
|
|
117
127
|
VMs[/verify master/]
|
|
118
128
|
VP[verify-progress]
|
|
119
129
|
VC[verify-code-review]
|
|
@@ -125,151 +135,151 @@ graph TD
|
|
|
125
135
|
VM[verify-multispec]
|
|
126
136
|
VMs --> VP & VC & VPa & VQ & VS & VD & VSi & VM
|
|
127
137
|
end
|
|
128
|
-
RT([⑤ /retro —
|
|
138
|
+
RT([⑤ /retro — milestone summary, optional]):::optional
|
|
129
139
|
RS --> Discuss
|
|
130
140
|
Discuss --> Plan --> Task --> Verify
|
|
131
141
|
Verify --> RT
|
|
132
142
|
classDef optional stroke-dasharray:5 5,fill:#f5f5f5,color:#666
|
|
133
143
|
```
|
|
134
144
|
|
|
135
|
-
>
|
|
145
|
+
> Dashed boxes = optional standalones (`/research` pre-strategic investigation / `/retro` post-milestone summary); solid boxes = main 4-stage cadence.
|
|
136
146
|
|
|
137
|
-
### 25
|
|
147
|
+
### 25-Workflow Overview Table
|
|
138
148
|
|
|
139
149
|
| Slash cmd | Stage | Type | Capability / Upstream | Brief |
|
|
140
150
|
|-----------|-------|------|----------------------|-------|
|
|
141
|
-
| `/auto` | All | **Super-master** | masterOrchestrator (
|
|
142
|
-
| `/discuss` | ① Discuss | Master | masterOrchestrator | 3
|
|
143
|
-
| `/discuss-strategic` | ① Discuss | Sub | gstack `/office-hours` + `/plan-ceo-review` + planning-with-files |
|
|
144
|
-
| `/discuss-phase` | ① Discuss | Sub | GSD `/gsd-discuss-phase` + planning-with-files | Phase
|
|
145
|
-
| `/discuss-subtask` | ① Discuss | Sub | superpowers brainstorming + `/grill-with-docs` |
|
|
146
|
-
| `/plan` | ② Plan | Master | masterOrchestrator |
|
|
147
|
-
| `/plan-architecture` | ② Plan | Sub | gstack `/plan-eng-review` |
|
|
148
|
-
| `/plan-phase` | ② Plan | Sub | GSD `/gsd-plan-phase` + planning-with-files `/plan` |
|
|
149
|
-
| `/task` | ③ Task | Master | masterOrchestrator |
|
|
150
|
-
| `/task-clarify` | ③ Task | Sub | superpowers brainstorming + `/grill-with-docs` conditional |
|
|
151
|
-
| `/task-code` | ③ Task | Sub | karpathy 4
|
|
152
|
-
| `/task-test` | ③ Task | Sub | superpowers TDD red-green-refactor + `/diagnose` conditional |
|
|
153
|
-
| `/task-deliver` | ③ Task | Sub | `ralph-loop` SDK wrapper + Agent Teams conditional |
|
|
154
|
-
| `/verify` | ④ Verify | Master | masterOrchestrator | 7
|
|
155
|
-
| `/verify-progress` | ④ Verify | Sub | GSD `/gsd-verify-work` + `/gsd-progress` |
|
|
156
|
-
| `/verify-code-review` | ④ Verify | Sub | `code-review`
|
|
157
|
-
| `/verify-paranoid` | ④ Verify | Sub | gstack `/review` (Paranoid Staff Engineer) |
|
|
158
|
-
| `/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) |
|
|
159
169
|
| `/verify-security` | ④ Verify | Sub | gstack `/cso` | OWASP / auth / secrets (has_auth_or_secrets conditional) |
|
|
160
|
-
| `/verify-design` | ④ Verify | Sub | gstack `/design-review` + ui-ux-pro-max + frontend-design |
|
|
161
|
-
| `/verify-simplify` | ④ Verify | Sub | `code-simplifier` |
|
|
162
|
-
| `/verify-multispec` | ④ Verify | Sub | 4-specialist Agent Team Pattern C |
|
|
163
|
-
| `/research` | Standalone | Standalone | Tavily / Exa MCP + ctx7 + GSD `/gsd-discuss-phase` |
|
|
164
|
-
| `/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 |
|
|
165
175
|
|
|
166
|
-
> Master orchestrator
|
|
167
|
-
>
|
|
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"`.
|
|
168
178
|
|
|
169
179
|
---
|
|
170
180
|
|
|
171
|
-
## ⚡
|
|
181
|
+
## ⚡ Usage Flow
|
|
172
182
|
|
|
173
|
-
4-stage
|
|
183
|
+
4-stage three-layer-stack methodology — recommended driving via the 4 master orchestrators in series:
|
|
174
184
|
|
|
175
185
|
```
|
|
176
186
|
/discuss → /plan → /task → /verify
|
|
177
187
|
① ② ③ ④
|
|
178
188
|
```
|
|
179
189
|
|
|
180
|
-
| Stage | Master |
|
|
190
|
+
| Stage | Master | Main sub-workflows | Upstream collaboration |
|
|
181
191
|
| ---- | ---- | ---- | ---- |
|
|
182
|
-
| ① **Discuss** | `/discuss` | strategic / phase / subtask (3
|
|
192
|
+
| ① **Discuss** | `/discuss` | strategic / phase / subtask (3 in parallel) | gstack `/office-hours` + GSD `/gsd-discuss-phase` + superpowers brainstorming |
|
|
183
193
|
| ② **Plan** | `/plan` | architecture (conditional) → phase | gstack `/plan-eng-review` + GSD `/gsd-plan-phase` + planning-with-files |
|
|
184
|
-
| ③ **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` |
|
|
185
195
|
| ④ **Verify** | `/verify` | progress → 5 parallel conditional → simplify (+ multispec critical) | GSD `/gsd-verify-work` + code-review + gstack `/review` / `/qa` / `/cso` / `/design-review` + code-simplifier |
|
|
186
196
|
|
|
187
|
-
|
|
197
|
+
Practical example:
|
|
188
198
|
|
|
189
199
|
```bash
|
|
190
|
-
# 1.
|
|
200
|
+
# 1. Install workflow upstreams (one line installs gstack + GSD + superpowers + planning-with-files)
|
|
191
201
|
harnessed setup
|
|
192
202
|
|
|
193
|
-
# 2.
|
|
194
|
-
/discuss "
|
|
195
|
-
/plan "
|
|
196
|
-
/task "subtask-1: API contract"
|
|
197
|
-
/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
|
|
198
208
|
|
|
199
|
-
# 3.
|
|
209
|
+
# 3. Resume after interruption (any time)
|
|
200
210
|
harnessed resume
|
|
201
211
|
```
|
|
202
212
|
|
|
203
|
-
>
|
|
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.
|
|
204
214
|
|
|
205
|
-
📊
|
|
215
|
+
📊 Detailed mermaid + full stage walkthroughs: [docs/WORKFLOW.md](./docs/WORKFLOW.md)
|
|
206
216
|
|
|
207
217
|
---
|
|
208
218
|
|
|
209
|
-
## 🗂️
|
|
219
|
+
## 🗂️ Architecture (4-stage namespace-layered)
|
|
210
220
|
|
|
211
|
-
### 1.
|
|
221
|
+
### 1. Directory Structure
|
|
212
222
|
|
|
213
223
|
```
|
|
214
224
|
harnessed/
|
|
215
|
-
├── manifests/ # L1:
|
|
216
|
-
├── workflows/ # L6: composition
|
|
217
|
-
│ ├── 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)
|
|
218
228
|
│ │ ├── auto/ # /discuss master gate-route
|
|
219
229
|
│ │ ├── strategic/ # /discuss-strategic (gstack /office-hours + /plan-ceo-review)
|
|
220
230
|
│ │ ├── phase/ # /discuss-phase (GSD /gsd-discuss-phase)
|
|
221
231
|
│ │ └── subtask/ # /discuss-subtask (superpowers brainstorming)
|
|
222
|
-
│ ├── plan/ # Stage ② (architecture + phase
|
|
232
|
+
│ ├── plan/ # Stage ② (architecture + phase task graph)
|
|
223
233
|
│ ├── task/ # Stage ③ (clarify + code + test + deliver)
|
|
224
234
|
│ ├── verify/ # Stage ④ (progress + code-review + paranoid + qa + cso + design + simplify + multispec)
|
|
225
235
|
│ ├── research/ # standalone Stage ① alternate
|
|
226
236
|
│ ├── retro/ # standalone post-④ milestone close
|
|
227
|
-
│ ├── capabilities.yaml # L5a: ~70
|
|
237
|
+
│ ├── capabilities.yaml # L5a: ~70 entries, 7 categories SoT
|
|
228
238
|
│ ├── defaults.yaml # ralph_max_iterations per workflow phase
|
|
229
|
-
│ ├── judgments/ # L5a:
|
|
239
|
+
│ ├── judgments/ # L5a: three-layer-stack criteria + parallelism + tdd + fallback + rules-routing
|
|
230
240
|
│ │ ├── strategic-gate.yaml
|
|
231
241
|
│ │ ├── phase-gate.yaml
|
|
232
242
|
│ │ ├── subtask-gate.yaml
|
|
233
243
|
│ │ ├── parallelism-gate.yaml # L5b execution mechanism routing
|
|
234
244
|
│ │ ├── tdd-gate.yaml
|
|
235
|
-
│ │ ├── fallback.yaml # 3
|
|
236
|
-
│ │ ├── web-design-routing.yaml # UI
|
|
237
|
-
│ │ ├── web-testing-routing.yaml # E2E /
|
|
238
|
-
│ │ ├── web-search-routing.yaml #
|
|
239
|
-
│ │ └── stage-routing.yaml # master orchestrator sub-stage
|
|
240
|
-
│ └── disciplines/ # L0:
|
|
241
|
-
│ ├── 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
|
|
242
252
|
│ ├── output-style.yaml # BLUF + no-emoji + no-em-dash
|
|
243
253
|
│ ├── language.yaml # zh-Hans default + English preserve
|
|
244
254
|
│ ├── operational.yaml # biome preempt + A7 + commit safety
|
|
245
|
-
│ ├── priority.yaml # skill conflict
|
|
246
|
-
│ └── protocols.yaml # cc-handoff design doc
|
|
255
|
+
│ ├── priority.yaml # skill conflict arbitration
|
|
256
|
+
│ └── protocols.yaml # cc-handoff design doc self-contained
|
|
247
257
|
├── routing/ # L4: routing engine SSOT (decision_rules.yaml)
|
|
248
258
|
├── schemas/ # L3: JSON Schema (IDE / CI consume)
|
|
249
259
|
├── src/ # L4: TS engine (workflow + routing + cli + installers + checkpoint + audit + state)
|
|
250
260
|
├── tests/ # vitest unit + integration + dogfood (R8.1 dogfood-first)
|
|
251
261
|
├── scripts/ # CI gate (check-workflow-schema, transparency-verdict, state-archive)
|
|
252
262
|
├── .planning/ # project memory (STATE + ROADMAP + REQUIREMENTS + per-phase + milestones)
|
|
253
|
-
└── docs/adr/ #
|
|
263
|
+
└── docs/adr/ # architecture decision records
|
|
254
264
|
```
|
|
255
265
|
|
|
256
|
-
### 2.
|
|
266
|
+
### 2. Logical Layering (8 layers)
|
|
257
267
|
|
|
258
268
|
```
|
|
259
269
|
┌────────────────────────────────────────────────────────────┐
|
|
260
270
|
│ L7 User-facing slash cmd + harnessed CLI │
|
|
261
|
-
│ /discuss /plan /task /verify (master) +
|
|
271
|
+
│ /discuss /plan /task /verify (master) + 18 sub + /research /retro + /auto super-master
|
|
262
272
|
│ + direct gstack invoke (30+ optional): /office-hours /review /qa /...
|
|
263
273
|
├────────────────────────────────────────────────────────────┤
|
|
264
274
|
│ L6 Workflow orchestration (workflows/<stage>/<sub>/) │
|
|
265
275
|
├────────────────────────────────────────────────────────────┤
|
|
266
276
|
│ L5b Execution Mechanism (orthogonal): subagent / Agent Teams │
|
|
267
|
-
│ /
|
|
268
|
-
│ parallelism-gate.yaml:
|
|
269
|
-
│ 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 │
|
|
270
280
|
├────────────────────────────────────────────────────────────┤
|
|
271
281
|
│ L5a Capability + Judgment + Defaults SoT │
|
|
272
|
-
│ capabilities.yaml (7
|
|
282
|
+
│ capabilities.yaml (7 categories) + judgments/ (10 files) + │
|
|
273
283
|
│ defaults.yaml │
|
|
274
284
|
├────────────────────────────────────────────────────────────┤
|
|
275
285
|
│ L4 Runtime engine (workflow / routing / handlers) │
|
|
@@ -280,17 +290,17 @@ harnessed/
|
|
|
280
290
|
├────────────────────────────────────────────────────────────┤
|
|
281
291
|
│ L1 Upstream components (NOT vendored) │
|
|
282
292
|
├────────────────────────────────────────────────────────────┤
|
|
283
|
-
│ L0 Discipline Substrate (
|
|
284
|
-
│ karpathy
|
|
293
|
+
│ L0 Discipline Substrate (applies globally) │
|
|
294
|
+
│ karpathy principles + output-style + language + operational + │
|
|
285
295
|
│ priority + protocols (applied universally to L1-L7) │
|
|
286
296
|
└────────────────────────────────────────────────────────────┘
|
|
287
297
|
```
|
|
288
298
|
|
|
289
|
-
### 3. Cross-cutting Capabilities (capabilities.yaml 7
|
|
299
|
+
### 3. Cross-cutting Capabilities (capabilities.yaml — 7 categories, ~83 entries)
|
|
290
300
|
|
|
291
301
|
```
|
|
292
302
|
behavioral (6): karpathy-guidelines + output-style + language + operational + priority + protocols
|
|
293
|
-
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.
|
|
294
304
|
tool-mcp (3): chrome-devtools-mcp / tavily-mcp / exa-mcp
|
|
295
305
|
tool-cli (2): ctx7 / gws
|
|
296
306
|
tool-plugin (2): planning-with-files / @playwright/test
|
|
@@ -298,18 +308,18 @@ tool-bundled (3): ralph-loop / webapp-testing / playwright-cli
|
|
|
298
308
|
agent-platform (3): agent-teams-create / send-message / shutdown
|
|
299
309
|
```
|
|
300
310
|
|
|
301
|
-
### 4.
|
|
311
|
+
### 4. Data Flow Example (user invokes `/discuss "new feature X"`)
|
|
302
312
|
|
|
303
313
|
```
|
|
304
|
-
[L7] User invokes /discuss "
|
|
314
|
+
[L7] User invokes /discuss "new feature X"
|
|
305
315
|
↓
|
|
306
316
|
[L6] workflows/discuss/auto/workflow.yaml master orchestrator
|
|
307
317
|
↓
|
|
308
|
-
[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)
|
|
309
319
|
↓
|
|
310
320
|
[L4] judgmentResolver.ts (4-level ref split) + exprBuilder.ts (expr-eval evaluate)
|
|
311
321
|
↓
|
|
312
|
-
[L0] discipline.priority-hierarchy
|
|
322
|
+
[L0] discipline.priority-hierarchy arbitrates tool conflicts / output-style formats output
|
|
313
323
|
↓
|
|
314
324
|
[fires=true sub] → invoke sub-workflow (/discuss-strategic / /discuss-phase / /discuss-subtask)
|
|
315
325
|
↓ for each sub:
|
|
@@ -318,150 +328,149 @@ agent-platform (3): agent-teams-create / send-message / shutdown
|
|
|
318
328
|
├─ parallelism: judgments.parallelism-gate.<route>.fires (L5b mechanism)
|
|
319
329
|
└─ phase invocations execute via capability template interpolation
|
|
320
330
|
↓
|
|
321
|
-
[fallback.yaml chain-isolation]
|
|
322
|
-
[Skip
|
|
331
|
+
[fallback.yaml chain-isolation] 3 layers judged independently, not serially dependent
|
|
332
|
+
[Skip transparency declaration] non-firing subs → "⚠️ Skipped <sub> because <reason>"
|
|
323
333
|
↓
|
|
324
334
|
planning-with-files /plan (cross-cutting tool) → write artifacts to .planning/<phase-id>/
|
|
325
335
|
↓
|
|
326
336
|
[L4] state.ts writeCurrentWorkflow (proper-lockfile) + audit.append (12-field JSONL)
|
|
327
337
|
```
|
|
328
338
|
|
|
329
|
-
### 5.
|
|
339
|
+
### 5. Decision Routing Matrix (rules-based, codified in judgments + capabilities)
|
|
330
340
|
|
|
331
|
-
|
|
|
341
|
+
| Scenario | Default → Escalate |
|
|
332
342
|
|------|---------------------|
|
|
333
|
-
|
|
|
334
|
-
| UI
|
|
335
|
-
| E2E
|
|
336
|
-
| E2E commit-able TS | @playwright/test
|
|
337
|
-
| E2E Python
|
|
338
|
-
|
|
|
339
|
-
| Web
|
|
340
|
-
| Web
|
|
341
|
-
|
|
|
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 |
|
|
342
352
|
| GitHub URL | gh CLI |
|
|
343
|
-
|
|
|
353
|
+
| Single URL fetch | WebFetch built-in |
|
|
344
354
|
| Gmail / Drive / Calendar | gws CLI |
|
|
345
|
-
|
|
|
346
|
-
| TDD
|
|
347
|
-
|
|
|
348
|
-
|
|
|
349
|
-
|
|
|
350
|
-
| `/auto`
|
|
351
|
-
| `/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 |
|
|
352
362
|
|
|
353
363
|
---
|
|
354
364
|
|
|
355
|
-
## 🛠️
|
|
365
|
+
## 🛠️ Operational Commands
|
|
356
366
|
|
|
357
|
-
>
|
|
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.
|
|
358
368
|
|
|
359
|
-
### CLI
|
|
369
|
+
### CLI Commands
|
|
360
370
|
|
|
361
|
-
|
|
|
371
|
+
| Command | Description |
|
|
362
372
|
| ---- | ---- |
|
|
363
|
-
| `harnessed setup` |
|
|
364
|
-
| `harnessed resume` |
|
|
365
|
-
| `harnessed status` |
|
|
366
|
-
| `harnessed doctor` | 8-check
|
|
367
|
-
| `harnessed install <name>` |
|
|
368
|
-
| `harnessed uninstall <name>` |
|
|
369
|
-
| `harnessed backup` |
|
|
370
|
-
| `harnessed rollback <timestamp>` |
|
|
371
|
-
| `harnessed gc` |
|
|
372
|
-
| `harnessed audit-log` |
|
|
373
|
-
|
|
374
|
-
###
|
|
375
|
-
|
|
376
|
-
>
|
|
377
|
-
|
|
378
|
-
| 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 |
|
|
379
389
|
| ---- | ---- |
|
|
380
|
-
| `--dry-run` |
|
|
381
|
-
| `--non-interactive` | CI /
|
|
382
|
-
| `--system` | L4
|
|
383
|
-
| `--yes` |
|
|
384
|
-
| `--full-diff` |
|
|
385
|
-
| `--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) |
|
|
386
396
|
|
|
387
|
-
> `--apply` flag 仍保留为向后兼容 alias (no-op, 旧脚本不破)。
|
|
388
397
|
|
|
389
398
|
---
|
|
390
399
|
|
|
391
400
|
## ❓ FAQ
|
|
392
401
|
|
|
393
402
|
<details>
|
|
394
|
-
<summary><b>Q1.
|
|
403
|
+
<summary><b>Q1. Do I still need to install superpowers / gstack / GSD upstreams after installing harnessed?</b></summary>
|
|
395
404
|
|
|
396
405
|
<br>
|
|
397
406
|
|
|
398
|
-
|
|
407
|
+
Yes, but **the user experience = one command**:
|
|
399
408
|
|
|
400
409
|
```bash
|
|
401
|
-
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
|
|
402
411
|
```
|
|
403
412
|
|
|
404
|
-
|
|
413
|
+
Think `brew install <formula>` pulling the full dependency set — you don't need to `brew install` each dependency separately.
|
|
405
414
|
|
|
406
415
|
</details>
|
|
407
416
|
|
|
408
417
|
<details>
|
|
409
|
-
<summary><b>Q2.
|
|
418
|
+
<summary><b>Q2. Why not just vendor superpowers / gstack into the harnessed repo?</b></summary>
|
|
410
419
|
|
|
411
420
|
<br>
|
|
412
421
|
|
|
413
|
-
4
|
|
422
|
+
4 reasons:
|
|
414
423
|
|
|
415
|
-
1.
|
|
416
|
-
2. **License + attribution
|
|
417
|
-
3.
|
|
418
|
-
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
|
|
419
428
|
|
|
420
429
|
</details>
|
|
421
430
|
|
|
422
431
|
<details>
|
|
423
|
-
<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>
|
|
424
433
|
|
|
425
434
|
<br>
|
|
426
435
|
|
|
427
|
-
|
|
436
|
+
**No**. They are different stages of the three-layer stack:
|
|
428
437
|
|
|
429
|
-
|
|
|
438
|
+
| Stage | Upstream | Responsibility |
|
|
430
439
|
| ---- | ---- | ---- |
|
|
431
|
-
| Governance | gstack |
|
|
432
|
-
| Brainstorming | superpowers |
|
|
433
|
-
| Orchestration | GSD |
|
|
434
|
-
| 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` |
|
|
435
444
|
|
|
436
|
-
`/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**.
|
|
437
446
|
|
|
438
447
|
</details>
|
|
439
448
|
|
|
440
449
|
<details>
|
|
441
|
-
<summary><b>Q4. workflow
|
|
450
|
+
<summary><b>Q4. Do workflow phases run automatically or wait for the user?</b></summary>
|
|
442
451
|
|
|
443
452
|
<br>
|
|
444
453
|
|
|
445
|
-
|
|
454
|
+
Depends on the `pause` field in `workflows/<name>/SKILL.md` frontmatter:
|
|
446
455
|
|
|
447
|
-
- `pause: human_review` →
|
|
448
|
-
-
|
|
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
|
|
449
458
|
|
|
450
|
-
|
|
459
|
+
Each phase output is written to `.harnessed/checkpoints/`; after a session interruption `harnessed resume` continues from the latest checkpoint.
|
|
451
460
|
|
|
452
461
|
</details>
|
|
453
462
|
|
|
454
463
|
<details>
|
|
455
|
-
<summary><b>Q5. harnessed
|
|
464
|
+
<summary><b>Q5. Is harnessed itself a CC plugin?</b></summary>
|
|
456
465
|
|
|
457
466
|
<br>
|
|
458
467
|
|
|
459
|
-
|
|
468
|
+
A hybrid:
|
|
460
469
|
|
|
461
|
-
- `npx harnessed@latest setup`
|
|
462
|
-
- setup
|
|
463
|
-
- `/discuss` / `/plan` / `/task` / `/verify`
|
|
464
|
-
- 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
|
|
465
474
|
|
|
466
475
|
</details>
|
|
467
476
|
|
|
@@ -470,6 +479,6 @@ harnessed setup --apply # 自动装齐 gstack + GSD + superpowers + planning-wi
|
|
|
470
479
|
|
|
471
480
|
## License
|
|
472
481
|
|
|
473
|
-
[Apache-2.0](./LICENSE) —
|
|
482
|
+
[Apache-2.0](./LICENSE) — see [NOTICE](./NOTICE) (includes Harness Inc. trademark disclaimer)
|
|
474
483
|
|
|
475
|
-
|
|
484
|
+
Support development: [](https://github.com/sponsors/easyinplay)
|