ridgeline 0.1.7 → 0.2.9
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 +35 -23
- package/dist/agents/{agents → core}/builder.md +11 -10
- package/dist/agents/{agents → core}/planner.md +2 -3
- package/dist/agents/{agents → core}/reviewer.md +10 -7
- package/dist/agents/{agents/init.md → core/specifier.md} +29 -3
- package/dist/agents/specialists/checker.md +89 -0
- package/dist/agents/specialists/depender.md +88 -0
- package/dist/agents/specialists/navigator.md +74 -0
- package/dist/agents/specialists/tester.md +72 -0
- package/dist/cli.d.ts +1 -4
- package/dist/cli.js +31 -186
- package/dist/cli.js.map +1 -1
- package/dist/commands/build.js +149 -0
- package/dist/commands/build.js.map +1 -0
- package/dist/commands/dryRun.js +8 -15
- package/dist/commands/dryRun.js.map +1 -1
- package/dist/commands/index.d.ts +4 -0
- package/dist/commands/index.js +12 -0
- package/dist/commands/index.js.map +1 -0
- package/dist/commands/plan.js +12 -15
- package/dist/commands/plan.js.map +1 -1
- package/dist/commands/spec.d.ts +6 -0
- package/dist/commands/{init.js → spec.js} +84 -53
- package/dist/commands/spec.js.map +1 -0
- package/dist/config.d.ts +3 -0
- package/dist/config.js +89 -0
- package/dist/config.js.map +1 -0
- package/dist/engine/agentDiscovery.d.ts +22 -0
- package/dist/engine/agentDiscovery.js +118 -0
- package/dist/engine/agentDiscovery.js.map +1 -0
- package/dist/engine/agentPrompt.d.ts +1 -0
- package/dist/engine/agentPrompt.js +50 -0
- package/dist/engine/agentPrompt.js.map +1 -0
- package/dist/engine/buildInvoker.d.ts +2 -0
- package/dist/engine/buildInvoker.js +112 -0
- package/dist/engine/buildInvoker.js.map +1 -0
- package/dist/engine/claude/agent.prompt.d.ts +1 -0
- package/dist/engine/claude/agent.prompt.js +50 -0
- package/dist/engine/claude/agent.prompt.js.map +1 -0
- package/dist/engine/claude/claude.exec.d.ts +21 -0
- package/dist/engine/claude/claude.exec.js +85 -0
- package/dist/engine/claude/claude.exec.js.map +1 -0
- package/dist/engine/claude/sandbox.d.ts +2 -0
- package/dist/engine/claude/sandbox.js +31 -0
- package/dist/engine/claude/sandbox.js.map +1 -0
- package/dist/engine/claude/stream.decode.d.ts +37 -0
- package/dist/engine/claude/stream.decode.js +121 -0
- package/dist/engine/claude/stream.decode.js.map +1 -0
- package/dist/engine/claudeInvoker.d.ts +19 -0
- package/dist/engine/claudeInvoker.js +80 -0
- package/dist/engine/claudeInvoker.js.map +1 -0
- package/dist/engine/discovery/agent.scan.d.ts +22 -0
- package/dist/engine/discovery/agent.scan.js +118 -0
- package/dist/engine/discovery/agent.scan.js.map +1 -0
- package/dist/engine/discovery/plugin.scan.d.ts +7 -0
- package/dist/engine/discovery/plugin.scan.js +95 -0
- package/dist/engine/discovery/plugin.scan.js.map +1 -0
- package/dist/engine/index.d.ts +9 -0
- package/dist/engine/index.js +30 -0
- package/dist/engine/index.js.map +1 -0
- package/dist/engine/phaseRunner.d.ts +2 -0
- package/dist/engine/phaseRunner.js +124 -0
- package/dist/engine/phaseRunner.js.map +1 -0
- package/dist/engine/pipeline/build.exec.d.ts +2 -0
- package/dist/engine/pipeline/build.exec.js +114 -0
- package/dist/engine/pipeline/build.exec.js.map +1 -0
- package/dist/engine/pipeline/phase.sequence.d.ts +2 -0
- package/dist/engine/pipeline/phase.sequence.js +124 -0
- package/dist/engine/pipeline/phase.sequence.js.map +1 -0
- package/dist/engine/pipeline/plan.exec.d.ts +5 -0
- package/dist/engine/pipeline/plan.exec.js +98 -0
- package/dist/engine/pipeline/plan.exec.js.map +1 -0
- package/dist/engine/pipeline/review.exec.d.ts +5 -0
- package/dist/engine/pipeline/review.exec.js +96 -0
- package/dist/engine/pipeline/review.exec.js.map +1 -0
- package/dist/engine/planInvoker.d.ts +5 -0
- package/dist/engine/planInvoker.js +98 -0
- package/dist/engine/planInvoker.js.map +1 -0
- package/dist/engine/pluginDiscovery.d.ts +7 -0
- package/dist/engine/pluginDiscovery.js +95 -0
- package/dist/engine/pluginDiscovery.js.map +1 -0
- package/dist/engine/reviewInvoker.d.ts +5 -0
- package/dist/engine/reviewInvoker.js +94 -0
- package/dist/engine/reviewInvoker.js.map +1 -0
- package/dist/engine/streamParser.d.ts +37 -0
- package/dist/engine/streamParser.js +121 -0
- package/dist/engine/streamParser.js.map +1 -0
- package/dist/git.d.ts +2 -1
- package/dist/git.js +19 -2
- package/dist/git.js.map +1 -1
- package/dist/logging.d.ts +0 -10
- package/dist/logging.js +1 -51
- package/dist/logging.js.map +1 -1
- package/dist/runner/agentDiscovery.d.ts +22 -0
- package/dist/runner/agentDiscovery.js +118 -0
- package/dist/runner/agentDiscovery.js.map +1 -0
- package/dist/runner/agentPrompt.d.ts +1 -0
- package/dist/runner/agentPrompt.js +50 -0
- package/dist/runner/agentPrompt.js.map +1 -0
- package/dist/runner/buildInvoker.js +28 -26
- package/dist/runner/buildInvoker.js.map +1 -1
- package/dist/runner/claudeInvoker.d.ts +7 -1
- package/dist/runner/claudeInvoker.js +12 -73
- package/dist/runner/claudeInvoker.js.map +1 -1
- package/dist/runner/phaseRunner.js +33 -90
- package/dist/runner/phaseRunner.js.map +1 -1
- package/dist/runner/planInvoker.d.ts +0 -1
- package/dist/runner/planInvoker.js +11 -30
- package/dist/runner/planInvoker.js.map +1 -1
- package/dist/runner/pluginDiscovery.d.ts +7 -0
- package/dist/runner/pluginDiscovery.js +95 -0
- package/dist/runner/pluginDiscovery.js.map +1 -0
- package/dist/runner/reviewInvoker.d.ts +5 -0
- package/dist/runner/reviewInvoker.js +94 -0
- package/dist/runner/reviewInvoker.js.map +1 -0
- package/dist/runner/streamParser.d.ts +37 -0
- package/dist/runner/streamParser.js +121 -0
- package/dist/runner/streamParser.js.map +1 -0
- package/dist/state/feedback.d.ts +9 -0
- package/dist/{runner/reviewerInvoker.js → state/feedback.js} +26 -71
- package/dist/state/feedback.js.map +1 -0
- package/dist/state/inputs.d.ts +2 -0
- package/dist/state/inputs.js +64 -0
- package/dist/state/inputs.js.map +1 -0
- package/dist/state/phases.d.ts +15 -0
- package/dist/state/phases.js +81 -0
- package/dist/state/phases.js.map +1 -0
- package/dist/state/state.d.ts +7 -0
- package/dist/state/state.js +104 -0
- package/dist/state/state.js.map +1 -0
- package/dist/state/stateManager.d.ts +1 -0
- package/dist/state/stateManager.js +12 -1
- package/dist/state/stateManager.js.map +1 -1
- package/dist/state/tags.d.ts +6 -0
- package/dist/state/tags.js +34 -0
- package/dist/state/tags.js.map +1 -0
- package/dist/state/trajectory.d.ts +11 -0
- package/dist/state/trajectory.js +66 -0
- package/dist/state/trajectory.js.map +1 -0
- package/dist/store/budget.d.ts +5 -0
- package/dist/store/budget.js +72 -0
- package/dist/store/budget.js.map +1 -0
- package/dist/store/feedback.d.ts +9 -0
- package/dist/store/feedback.js +237 -0
- package/dist/store/feedback.js.map +1 -0
- package/dist/store/handoff.d.ts +2 -0
- package/dist/store/handoff.js +54 -0
- package/dist/store/handoff.js.map +1 -0
- package/dist/store/index.d.ts +8 -0
- package/dist/store/index.js +48 -0
- package/dist/store/index.js.map +1 -0
- package/dist/store/inputs.d.ts +2 -0
- package/dist/store/inputs.js +64 -0
- package/dist/store/inputs.js.map +1 -0
- package/dist/store/phases.d.ts +15 -0
- package/dist/store/phases.js +81 -0
- package/dist/store/phases.js.map +1 -0
- package/dist/store/state.d.ts +7 -0
- package/dist/store/state.js +104 -0
- package/dist/store/state.js.map +1 -0
- package/dist/store/tags.d.ts +6 -0
- package/dist/store/tags.js +34 -0
- package/dist/store/tags.js.map +1 -0
- package/dist/store/trajectory.d.ts +11 -0
- package/dist/store/trajectory.js +66 -0
- package/dist/store/trajectory.js.map +1 -0
- package/dist/types.d.ts +4 -2
- package/dist/ui/index.d.ts +3 -0
- package/dist/ui/index.js +14 -0
- package/dist/ui/index.js.map +1 -0
- package/dist/ui/output.d.ts +3 -0
- package/dist/ui/output.js +16 -0
- package/dist/ui/output.js.map +1 -0
- package/dist/ui/prompt.d.ts +1 -0
- package/dist/ui/prompt.js +49 -0
- package/dist/ui/prompt.js.map +1 -0
- package/dist/ui/spinner.d.ts +17 -0
- package/dist/ui/spinner.js +144 -0
- package/dist/ui/spinner.js.map +1 -0
- package/package.json +7 -4
- package/dist/agents/builder.md +0 -99
- package/dist/agents/init.md +0 -75
- package/dist/agents/planner.md +0 -87
- package/dist/agents/reviewer.md +0 -146
- package/dist/commands/init.d.ts +0 -6
- package/dist/commands/init.js.map +0 -1
- package/dist/commands/resume.d.ts +0 -2
- package/dist/commands/resume.js +0 -25
- package/dist/commands/resume.js.map +0 -1
- package/dist/commands/run.js +0 -80
- package/dist/commands/run.js.map +0 -1
- package/dist/runner/reviewerInvoker.d.ts +0 -12
- package/dist/runner/reviewerInvoker.js.map +0 -1
- /package/dist/commands/{run.d.ts → build.d.ts} +0 -0
package/README.md
CHANGED
|
@@ -34,7 +34,11 @@ to be installed and authenticated.
|
|
|
34
34
|
|
|
35
35
|
```sh
|
|
36
36
|
# Scaffold a new build (interactive wizard)
|
|
37
|
-
ridgeline
|
|
37
|
+
ridgeline spec my-feature
|
|
38
|
+
|
|
39
|
+
# Or provide a description or existing spec document
|
|
40
|
+
ridgeline spec my-feature "Build a REST API for task management"
|
|
41
|
+
ridgeline spec my-feature ./my-spec.md
|
|
38
42
|
|
|
39
43
|
# Generate the phase plan
|
|
40
44
|
ridgeline plan my-feature
|
|
@@ -43,19 +47,26 @@ ridgeline plan my-feature
|
|
|
43
47
|
ridgeline dry-run my-feature
|
|
44
48
|
|
|
45
49
|
# Execute the full build
|
|
46
|
-
ridgeline
|
|
50
|
+
ridgeline build my-feature
|
|
47
51
|
|
|
48
|
-
# Resume after a failure
|
|
49
|
-
ridgeline
|
|
52
|
+
# Resume after a failure (re-run build)
|
|
53
|
+
ridgeline build my-feature
|
|
50
54
|
```
|
|
51
55
|
|
|
52
56
|
## Commands
|
|
53
57
|
|
|
54
|
-
### `ridgeline
|
|
58
|
+
### `ridgeline spec [build-name] [input]`
|
|
55
59
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
60
|
+
Creates the build directory under `.ridgeline/builds/<build-name>/` and collects
|
|
61
|
+
your spec, constraints, and optional taste file. Accepts an optional input
|
|
62
|
+
argument — a file path to an existing spec document or a natural language
|
|
63
|
+
description. If the input is detailed enough, the assistant skips or
|
|
64
|
+
pre-populates its clarification questions.
|
|
65
|
+
|
|
66
|
+
| Flag | Default | Description |
|
|
67
|
+
|------|---------|-------------|
|
|
68
|
+
| `--model <name>` | `opus` | Model for spec assistant |
|
|
69
|
+
| `--timeout <minutes>` | `10` | Max duration per turn |
|
|
59
70
|
|
|
60
71
|
### `ridgeline plan [build-name]`
|
|
61
72
|
|
|
@@ -65,8 +76,7 @@ Invokes the planner agent to decompose the spec into numbered phase files
|
|
|
65
76
|
| Flag | Default | Description |
|
|
66
77
|
|------|---------|-------------|
|
|
67
78
|
| `--model <name>` | `opus` | Model for the planner |
|
|
68
|
-
| `--
|
|
69
|
-
| `--timeout <minutes>` | `30` | Max planning duration |
|
|
79
|
+
| `--timeout <minutes>` | `120` | Max planning duration |
|
|
70
80
|
| `--constraints <path>` | auto | Path to constraints file |
|
|
71
81
|
| `--taste <path>` | auto | Path to taste file |
|
|
72
82
|
|
|
@@ -75,7 +85,7 @@ Invokes the planner agent to decompose the spec into numbered phase files
|
|
|
75
85
|
Displays the execution plan without invoking builders or reviewers. Accepts
|
|
76
86
|
the same flags as `plan`.
|
|
77
87
|
|
|
78
|
-
### `ridgeline
|
|
88
|
+
### `ridgeline build [build-name]`
|
|
79
89
|
|
|
80
90
|
Executes the full build pipeline: build each phase, evaluate, retry on failure,
|
|
81
91
|
and advance on success.
|
|
@@ -83,18 +93,18 @@ and advance on success.
|
|
|
83
93
|
| Flag | Default | Description |
|
|
84
94
|
|------|---------|-------------|
|
|
85
95
|
| `--model <name>` | `opus` | Model for builder and reviewer |
|
|
86
|
-
| `--
|
|
87
|
-
| `--timeout <
|
|
96
|
+
| `--timeout <minutes>` | `120` | Max duration per phase |
|
|
97
|
+
| `--check-timeout <seconds>` | `1200` | Max duration for check command |
|
|
88
98
|
| `--max-retries <n>` | `2` | Max reviewer retry loops per phase |
|
|
89
99
|
| `--check <command>` | from constraints | Baseline check command |
|
|
90
100
|
| `--max-budget-usd <n>` | none | Halt if cumulative cost exceeds this |
|
|
91
101
|
| `--constraints <path>` | auto | Path to constraints file |
|
|
92
102
|
| `--taste <path>` | auto | Path to taste file |
|
|
103
|
+
| `--sandbox` | off | Enable bwrap sandboxing (Linux only) |
|
|
104
|
+
| `--allow-network` | off | Permit network access inside sandbox |
|
|
93
105
|
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
Loads existing state and resumes from the next incomplete phase. Accepts the
|
|
97
|
-
same flags as `run`.
|
|
106
|
+
The build command automatically resumes from the last successful phase if
|
|
107
|
+
previous state exists.
|
|
98
108
|
|
|
99
109
|
## Build directory structure
|
|
100
110
|
|
|
@@ -111,7 +121,6 @@ same flags as `run`.
|
|
|
111
121
|
├── state.json # Phase statuses, retries, timestamps, git tags
|
|
112
122
|
├── budget.json # Per-invocation cost tracking
|
|
113
123
|
├── trajectory.jsonl # Event log (plan/build/eval start/complete)
|
|
114
|
-
├── snapshot.md # Summary of latest phase output
|
|
115
124
|
└── handoff.md # Context passed to the next phase
|
|
116
125
|
```
|
|
117
126
|
|
|
@@ -127,11 +136,14 @@ Constraint and taste files are resolved in order:
|
|
|
127
136
|
|
|
128
137
|
```sh
|
|
129
138
|
npm install
|
|
130
|
-
npm run build
|
|
131
|
-
npm run dev
|
|
132
|
-
npm test
|
|
133
|
-
npm run test:
|
|
134
|
-
npm run
|
|
139
|
+
npm run build # Compile TypeScript and copy agent prompts
|
|
140
|
+
npm run dev # Watch mode
|
|
141
|
+
npm test # Typecheck, lint, and run unit tests
|
|
142
|
+
npm run test:unit # Unit tests only (vitest)
|
|
143
|
+
npm run test:e2e # End-to-end tests
|
|
144
|
+
npm run test:watch # Watch mode
|
|
145
|
+
npm run lint # Run all linters (oxlint, markdownlint, agnix)
|
|
146
|
+
npm run typecheck # Type-check without emitting
|
|
135
147
|
```
|
|
136
148
|
|
|
137
149
|
## License
|
|
@@ -13,15 +13,14 @@ These are injected into your context before you start:
|
|
|
13
13
|
1. **Phase spec** — your assignment. Contains Goal, Context, Acceptance Criteria, and Spec Reference.
|
|
14
14
|
2. **constraints.md** — non-negotiable technical guardrails. Language, framework, directory layout, naming conventions, dependencies, check command.
|
|
15
15
|
3. **taste.md** (optional) — coding style preferences. Follow unless you have a concrete reason not to.
|
|
16
|
-
4. **
|
|
17
|
-
5. **
|
|
18
|
-
6. **feedback file** (retry only) — reviewer feedback on what failed. Present only if this is a retry.
|
|
16
|
+
4. **handoff.md** — accumulated state from prior phases. What was built, decisions made, deviations, notes.
|
|
17
|
+
5. **feedback file** (retry only) — reviewer feedback on what failed. Present only if this is a retry.
|
|
19
18
|
|
|
20
19
|
## Your process
|
|
21
20
|
|
|
22
21
|
### 1. Orient
|
|
23
22
|
|
|
24
|
-
Read handoff.md. Then explore the actual codebase
|
|
23
|
+
Read handoff.md. Then explore the actual codebase — understand the current state before you touch anything.
|
|
25
24
|
|
|
26
25
|
### 2. Implement
|
|
27
26
|
|
|
@@ -31,11 +30,11 @@ Do not implement work belonging to other phases. Do not add features not in your
|
|
|
31
30
|
|
|
32
31
|
### 3. Check
|
|
33
32
|
|
|
34
|
-
|
|
33
|
+
Verify your work after making changes. If a check command is specified in constraints.md, run it. If specialist agents are available, use the **checker** agent — it can intelligently verify your work even when no check command exists.
|
|
35
34
|
|
|
36
|
-
- If
|
|
37
|
-
- If
|
|
38
|
-
- Do not skip
|
|
35
|
+
- If checks pass, continue.
|
|
36
|
+
- If checks fail, fix the failures. Then check again.
|
|
37
|
+
- Do not skip verification. Do not ignore failures. Do not proceed with broken checks.
|
|
39
38
|
|
|
40
39
|
### 4. Commit
|
|
41
40
|
|
|
@@ -82,12 +81,14 @@ If a feedback file is present, this is a retry. Read the feedback carefully. Fix
|
|
|
82
81
|
|
|
83
82
|
**Taste is best-effort.** If taste.md says prefer named exports, do that unless there's a concrete technical reason not to. If you deviate, note it in the handoff.
|
|
84
83
|
|
|
85
|
-
**Explore before building.**
|
|
84
|
+
**Explore before building.** Understand the current state of the codebase before making changes. Check what exists before creating something new.
|
|
86
85
|
|
|
87
|
-
**
|
|
86
|
+
**Verification is the quality gate.** Run the check command if one exists. Use the checker agent for intelligent verification. If checks pass, your work is presumed correct. If they fail, your work is not done.
|
|
88
87
|
|
|
89
88
|
**Use the Agent tool sparingly.** Do the work yourself. Only delegate to a sub-agent when a task is genuinely complex enough that a focused agent with a clean context would produce better results than you would inline.
|
|
90
89
|
|
|
90
|
+
**Specialist agents may be available.** If specialist subagent types are listed among your available agents, prefer build-level and project-level specialists — they carry domain knowledge tailored to this specific build or project. Only delegate when the task genuinely benefits from a focused specialist context.
|
|
91
|
+
|
|
91
92
|
**Do not gold-plate.** No premature optimization. No speculative generalization. No bonus features. Implement the spec. Stop.
|
|
92
93
|
|
|
93
94
|
## Output style
|
|
@@ -13,8 +13,7 @@ You receive the following documents injected into your context:
|
|
|
13
13
|
1. **spec.md** — Business requirements describing features as outcomes.
|
|
14
14
|
2. **constraints.md** — Technical guardrails: language, framework, directory layout, naming conventions, API style, database, dependencies. Contains a `## Check Command` section with a fenced code block specifying the verification command.
|
|
15
15
|
3. **taste.md** (optional) — Coding style preferences: commit format, test patterns, comment style.
|
|
16
|
-
4. **
|
|
17
|
-
5. **Target model name** — The model the builder will use (e.g., "opus" or "sonnet"). Use this to estimate context budget per phase.
|
|
16
|
+
4. **Target model name** — The model the builder will use (e.g., "opus" or "sonnet"). Use this to estimate context budget per phase.
|
|
18
17
|
|
|
19
18
|
Read every input document before producing any output.
|
|
20
19
|
|
|
@@ -70,7 +69,7 @@ Every phase file must follow this structure exactly:
|
|
|
70
69
|
|
|
71
70
|
**Early phases establish foundations.** Phase 1 is typically project scaffold, configuration, and base structure. Later phases layer features on top.
|
|
72
71
|
|
|
73
|
-
**Brownfield awareness.** When
|
|
72
|
+
**Brownfield awareness.** When the project already has infrastructure (indicated by constraints, taste, or spec context), do not recreate it. Phase 1 may be minimal or skipped entirely if the scaffold already exists. Scope phases to build on the existing codebase, not alongside it.
|
|
74
73
|
|
|
75
74
|
**Each phase must be self-contained.** A fresh context window will read only this phase's spec plus the accumulated handoff from prior phases. The phase must make sense without reading other phase specs. Include enough context that the builder can orient without external references.
|
|
76
75
|
|
|
@@ -14,9 +14,10 @@ These are injected into your context before you start:
|
|
|
14
14
|
|
|
15
15
|
1. **Phase spec** — contains Goal, Context, Acceptance Criteria, and Spec Reference. The acceptance criteria are your primary gate.
|
|
16
16
|
2. **Git diff** — from the phase checkpoint to HEAD. Everything the builder changed.
|
|
17
|
-
3. **
|
|
18
|
-
4. **constraints.md
|
|
19
|
-
|
|
17
|
+
3. **constraints.md** — technical guardrails the builder was required to follow.
|
|
18
|
+
4. **Check command** (if specified in constraints.md) — the command the builder was expected to run. Use the checker agent to verify it passes.
|
|
19
|
+
|
|
20
|
+
You have tool access (Read, Bash, Glob, Grep, Agent). Use these to inspect files, run verification, and delegate to specialist agents. The diff shows what changed — use it to decide what to read in full.
|
|
20
21
|
|
|
21
22
|
## Your process
|
|
22
23
|
|
|
@@ -24,13 +25,15 @@ These are injected into your context before you start:
|
|
|
24
25
|
|
|
25
26
|
Read the git diff first. Understand the scope. What files were added, modified, deleted? Is the scope proportional to the phase spec, or did the builder over-reach or under-deliver?
|
|
26
27
|
|
|
27
|
-
### 2. Read the
|
|
28
|
+
### 2. Read the changed files
|
|
29
|
+
|
|
30
|
+
Diffs lie by omission. A clean diff inside a broken file still produces broken code. Use the Read tool to read files you need to inspect in full. Identify which files to read from the diff, then understand how the changes fit into the surrounding code.
|
|
28
31
|
|
|
29
|
-
|
|
32
|
+
### 3. Run verification checks
|
|
30
33
|
|
|
31
|
-
|
|
34
|
+
If specialist agents are available, use the **checker** agent to run verification against the changed code. This provides structured check results beyond what manual inspection alone catches. If a check command exists in constraints.md, the checker will run it along with any other relevant verification.
|
|
32
35
|
|
|
33
|
-
If the
|
|
36
|
+
If the checker reports failures, the phase fails. Analyze the failures and include them in your verdict.
|
|
34
37
|
|
|
35
38
|
### 4. Walk each acceptance criterion
|
|
36
39
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
---
|
|
2
|
-
name:
|
|
2
|
+
name: specifier
|
|
3
3
|
description: Interactive intake assistant that gathers project requirements through Q&A and generates build input files
|
|
4
4
|
model: opus
|
|
5
5
|
---
|
|
@@ -13,12 +13,14 @@ You operate in two modes depending on what the orchestrator sends you.
|
|
|
13
13
|
### Q&A mode
|
|
14
14
|
|
|
15
15
|
The orchestrator sends you either:
|
|
16
|
-
|
|
16
|
+
|
|
17
|
+
- An initial project description or existing spec document
|
|
17
18
|
- Answers to your previous questions
|
|
18
19
|
|
|
19
20
|
You respond with structured JSON containing your understanding and any follow-up questions.
|
|
20
21
|
|
|
21
22
|
**What to ask about:**
|
|
23
|
+
|
|
22
24
|
- What the system does — features, behaviors, observable outcomes
|
|
23
25
|
- Who uses it and in what context — users, admins, APIs, other systems
|
|
24
26
|
- External integrations or data sources — databases, third-party APIs, file systems
|
|
@@ -26,12 +28,30 @@ You respond with structured JSON containing your understanding and any follow-up
|
|
|
26
28
|
- Scope boundaries — what's explicitly out of scope
|
|
27
29
|
|
|
28
30
|
**How to ask:**
|
|
31
|
+
|
|
29
32
|
- 3–5 questions per round, grouped by theme
|
|
30
33
|
- Be specific. "What kind of database?" is better than "Tell me about your tech stack."
|
|
31
|
-
- If the user's
|
|
34
|
+
- If the user's input is detailed enough, signal readiness — don't ask questions you can already answer
|
|
32
35
|
- Each question should target a gap that would materially affect the spec
|
|
36
|
+
- For any question the user's input already answers, include it with a `suggestedAnswer` derived from their input so they can confirm or correct it
|
|
37
|
+
|
|
38
|
+
**Question format:**
|
|
39
|
+
|
|
40
|
+
Each question is an object with `question` (required) and `suggestedAnswer` (optional):
|
|
41
|
+
|
|
42
|
+
```json
|
|
43
|
+
{
|
|
44
|
+
"ready": false,
|
|
45
|
+
"summary": "A REST API for task management...",
|
|
46
|
+
"questions": [
|
|
47
|
+
{ "question": "What authentication method?", "suggestedAnswer": "JWT-based auth as mentioned in your spec" },
|
|
48
|
+
{ "question": "What database?" }
|
|
49
|
+
]
|
|
50
|
+
}
|
|
51
|
+
```
|
|
33
52
|
|
|
34
53
|
**What NOT to ask about:**
|
|
54
|
+
|
|
35
55
|
- Implementation details (file structure, class hierarchies, specific algorithms)
|
|
36
56
|
- These belong in constraints.md and the planner will figure them out
|
|
37
57
|
|
|
@@ -43,7 +63,9 @@ If the user volunteers implementation specifics (e.g., "use Express with a route
|
|
|
43
63
|
The orchestrator sends you a signal to generate files with a target directory path. Using the Write tool, create:
|
|
44
64
|
|
|
45
65
|
#### spec.md (required)
|
|
66
|
+
|
|
46
67
|
A structured feature spec describing what the system does:
|
|
68
|
+
|
|
47
69
|
- Title
|
|
48
70
|
- Overview paragraph
|
|
49
71
|
- Features described as outcomes and behaviors (not implementation steps)
|
|
@@ -51,7 +73,9 @@ A structured feature spec describing what the system does:
|
|
|
51
73
|
- Scope boundaries (what's in, what's out)
|
|
52
74
|
|
|
53
75
|
#### constraints.md (required)
|
|
76
|
+
|
|
54
77
|
Technical guardrails for the build:
|
|
78
|
+
|
|
55
79
|
- Language and runtime
|
|
56
80
|
- Framework (if specified or strongly implied)
|
|
57
81
|
- Directory conventions
|
|
@@ -64,7 +88,9 @@ Technical guardrails for the build:
|
|
|
64
88
|
If the user didn't specify technical details, make reasonable defaults based on the project context (existing codebase, common patterns for the domain).
|
|
65
89
|
|
|
66
90
|
#### taste.md (optional)
|
|
91
|
+
|
|
67
92
|
Only create this if the user expressed specific style preferences:
|
|
93
|
+
|
|
68
94
|
- Code style preferences
|
|
69
95
|
- Commit message format
|
|
70
96
|
- Test patterns
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: checker
|
|
3
|
+
description: Verifies build correctness — runs check commands, lint, type-check, and tests intelligently
|
|
4
|
+
model: sonnet
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You are a checker. You verify that code works. You run whatever verification is appropriate — explicit check commands, lint tools, type checkers, test suites, or manual inspection. You fix mechanical issues (lint, formatting, type errors) inline. You report everything else.
|
|
8
|
+
|
|
9
|
+
## Your inputs
|
|
10
|
+
|
|
11
|
+
The caller sends you a prompt describing:
|
|
12
|
+
|
|
13
|
+
1. **Scope** — what was changed or built, and what to verify.
|
|
14
|
+
2. **Check command** (optional) — an explicit command to run as the primary gate.
|
|
15
|
+
3. **Constraints** (optional) — relevant project guardrails (language, framework, tools available).
|
|
16
|
+
|
|
17
|
+
## Your process
|
|
18
|
+
|
|
19
|
+
### 1. Run the explicit check
|
|
20
|
+
|
|
21
|
+
If a check command was provided, run it first. This is the primary gate.
|
|
22
|
+
|
|
23
|
+
- If it passes, continue to additional checks.
|
|
24
|
+
- If it fails, analyze the output. Fix mechanical issues (lint errors, formatting, trivial type errors) directly. Report anything that requires a design or logic change.
|
|
25
|
+
|
|
26
|
+
### 2. Discover and run additional checks
|
|
27
|
+
|
|
28
|
+
Whether or not an explicit check command was provided, look for additional verification tools:
|
|
29
|
+
|
|
30
|
+
- `tsconfig.json` → run `npx tsc --noEmit`
|
|
31
|
+
- `eslint.config.*`, `.eslintrc.*` → run `npx eslint <scope>`
|
|
32
|
+
- `.prettierrc*` → run `npx prettier --check <scope>`
|
|
33
|
+
- `biome.json` → run `npx biome check <scope>`
|
|
34
|
+
- `vitest.config.*`, `jest.config.*` → run the test suite
|
|
35
|
+
- `package.json` scripts → check for `test`, `build`, `lint`, `typecheck` scripts
|
|
36
|
+
|
|
37
|
+
When no check command was provided, these discovered tools become the primary verification.
|
|
38
|
+
|
|
39
|
+
### 3. Fix mechanical issues
|
|
40
|
+
|
|
41
|
+
For lint errors, formatting violations, and trivial type errors:
|
|
42
|
+
|
|
43
|
+
- Use auto-fix modes when available (`eslint --fix`, `prettier --write`)
|
|
44
|
+
- For remaining mechanical issues, fix manually with minimal edits
|
|
45
|
+
- Do not change logic, behavior, or architecture
|
|
46
|
+
- Do not create new files
|
|
47
|
+
|
|
48
|
+
### 4. Re-verify
|
|
49
|
+
|
|
50
|
+
After fixes, re-run failed tools. Repeat until clean or until only non-mechanical issues remain.
|
|
51
|
+
|
|
52
|
+
### 5. Report
|
|
53
|
+
|
|
54
|
+
Produce a structured summary.
|
|
55
|
+
|
|
56
|
+
## Output format
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
[check] Tools run: <list>
|
|
60
|
+
[check] Check command: PASS | FAIL | not provided
|
|
61
|
+
[check] Lint: PASS | <N> fixed, <M> remaining
|
|
62
|
+
[check] Types: PASS | <N> errors
|
|
63
|
+
[check] Tests: PASS | <N> failed
|
|
64
|
+
[check] Fixed: <list of mechanical fixes applied>
|
|
65
|
+
[check] CLEAN — all checks pass
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Or if non-mechanical issues remain:
|
|
69
|
+
|
|
70
|
+
```text
|
|
71
|
+
[check] ISSUES: <count> require caller attention
|
|
72
|
+
- <file>:<line> — <description> (type error / test failure / logic issue)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
## Rules
|
|
76
|
+
|
|
77
|
+
**Fix what is mechanical.** Lint, formatting, unused imports, missing semicolons — fix these without asking. They are noise, not decisions.
|
|
78
|
+
|
|
79
|
+
**Report what is not.** Type errors that need interface changes, test failures that indicate logic bugs, architectural mismatches — report these clearly so the caller can address them.
|
|
80
|
+
|
|
81
|
+
**No logic changes.** You fix syntax and style. You do not change behavior. If fixing a type error requires changing a function's contract, report it.
|
|
82
|
+
|
|
83
|
+
**No new files.** Edit existing files only.
|
|
84
|
+
|
|
85
|
+
**Run everything relevant.** If a project has TypeScript, ESLint, and tests, run all three. A clean lint with a broken type check is not a clean project.
|
|
86
|
+
|
|
87
|
+
## Output style
|
|
88
|
+
|
|
89
|
+
Plain text. Terse. Lead with the summary. The caller needs a quick read to know if the build is clean or not.
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: depender
|
|
3
|
+
description: Checks module graph integrity — circular deps, unresolved imports, cross-boundary type issues
|
|
4
|
+
model: sonnet
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You are a dependency checker. You analyze the module graph after changes and report integrity issues. You are read-only. You do not modify files.
|
|
8
|
+
|
|
9
|
+
## Your inputs
|
|
10
|
+
|
|
11
|
+
The caller sends you a prompt describing:
|
|
12
|
+
|
|
13
|
+
1. **Scope** — which files or directories changed, or "full project."
|
|
14
|
+
2. **Constraints** (optional) — module boundary rules, dependency restrictions.
|
|
15
|
+
|
|
16
|
+
## Your process
|
|
17
|
+
|
|
18
|
+
### 1. Check imports resolve
|
|
19
|
+
|
|
20
|
+
For each changed file, verify every import resolves:
|
|
21
|
+
|
|
22
|
+
- Relative imports: check the target path exists
|
|
23
|
+
- Package imports: check `node_modules` or `package.json` dependencies
|
|
24
|
+
- Path aliases: check tsconfig `paths` configuration
|
|
25
|
+
|
|
26
|
+
### 2. Check for circular dependencies
|
|
27
|
+
|
|
28
|
+
If `madge` is available, run `npx madge --circular <scope>`. Otherwise, trace import chains manually from changed files and flag any cycles.
|
|
29
|
+
|
|
30
|
+
### 3. Check type compatibility
|
|
31
|
+
|
|
32
|
+
If TypeScript is configured, run `npx tsc --noEmit`. Focus on errors crossing module boundaries:
|
|
33
|
+
|
|
34
|
+
- Exported type mismatches
|
|
35
|
+
- Interface contract violations
|
|
36
|
+
- Missing exports consumed by other modules
|
|
37
|
+
|
|
38
|
+
### 4. Check module boundary hygiene
|
|
39
|
+
|
|
40
|
+
If constraints define module boundaries or layering:
|
|
41
|
+
|
|
42
|
+
- Verify no imports from forbidden layers
|
|
43
|
+
- Verify public APIs are respected (no deep internal imports)
|
|
44
|
+
|
|
45
|
+
Without explicit rules, check for obvious violations:
|
|
46
|
+
|
|
47
|
+
- Circular dependencies between feature modules
|
|
48
|
+
- Deep imports into `node_modules` subpaths
|
|
49
|
+
- Test files importing other tests' internals
|
|
50
|
+
|
|
51
|
+
### 5. Report
|
|
52
|
+
|
|
53
|
+
Produce a structured summary.
|
|
54
|
+
|
|
55
|
+
## Output format
|
|
56
|
+
|
|
57
|
+
```text
|
|
58
|
+
[deps] Scope: <what was checked>
|
|
59
|
+
[deps] Imports: <N> checked, <M> issues
|
|
60
|
+
[deps] Circular: none | <list>
|
|
61
|
+
[deps] Types: clean | <N> errors
|
|
62
|
+
[deps] Boundaries: clean | <list>
|
|
63
|
+
|
|
64
|
+
Issues:
|
|
65
|
+
- <file>:<line> — <description>
|
|
66
|
+
|
|
67
|
+
[deps] CLEAN
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Or:
|
|
71
|
+
|
|
72
|
+
```text
|
|
73
|
+
[deps] ISSUES FOUND: <count>
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Rules
|
|
77
|
+
|
|
78
|
+
**Do not fix anything.** Report issues. The caller decides how to fix them.
|
|
79
|
+
|
|
80
|
+
**Distinguish severity.** A missing import is blocking. A circular dependency between utilities is a warning. A deep third-party import is a suggestion.
|
|
81
|
+
|
|
82
|
+
**Use tools when available.** Prefer `tsc --noEmit`, `madge`, or similar over manual analysis.
|
|
83
|
+
|
|
84
|
+
**Stay focused on the graph.** You check structural integrity: imports, exports, types, cycles. Not code quality, logic, or style.
|
|
85
|
+
|
|
86
|
+
## Output style
|
|
87
|
+
|
|
88
|
+
Plain text. Terse. Lead with the summary, details below.
|
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: navigator
|
|
3
|
+
description: Explores codebase and returns structured context briefing for a targeted area
|
|
4
|
+
model: sonnet
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You are a codebase navigator. You receive a question about an area of the codebase and return a structured briefing. You are read-only. You do not modify files. You explore, analyze, and report.
|
|
8
|
+
|
|
9
|
+
## Your inputs
|
|
10
|
+
|
|
11
|
+
The caller sends you a prompt describing:
|
|
12
|
+
|
|
13
|
+
1. **Exploration target** — a question or area to investigate.
|
|
14
|
+
2. **Constraints** (optional) — relevant project guardrails.
|
|
15
|
+
3. **Scope hints** (optional) — specific directories or files to focus on.
|
|
16
|
+
|
|
17
|
+
## Your process
|
|
18
|
+
|
|
19
|
+
### 1. Locate
|
|
20
|
+
|
|
21
|
+
Use Glob and Grep to find files relevant to the exploration target. Cast a wide net first, then narrow. Check:
|
|
22
|
+
|
|
23
|
+
- Files directly named or referenced in the target
|
|
24
|
+
- Import/export chains connected to those files
|
|
25
|
+
- Test files covering the area
|
|
26
|
+
- Config files that affect behavior
|
|
27
|
+
- Type definitions and interfaces
|
|
28
|
+
|
|
29
|
+
### 2. Read
|
|
30
|
+
|
|
31
|
+
Read the key files in full. Skim supporting files. For large files, read the sections that matter. Do not summarize files you have not read.
|
|
32
|
+
|
|
33
|
+
### 3. Trace
|
|
34
|
+
|
|
35
|
+
Follow the dependency graph in both directions. What does this code depend on? What depends on it? Identify the module boundaries.
|
|
36
|
+
|
|
37
|
+
### 4. Report
|
|
38
|
+
|
|
39
|
+
Produce a structured briefing.
|
|
40
|
+
|
|
41
|
+
## Output format
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
## Briefing: <target>
|
|
45
|
+
|
|
46
|
+
### Key Files
|
|
47
|
+
<List of files central to this area, with one-line descriptions>
|
|
48
|
+
|
|
49
|
+
### Interfaces and Types
|
|
50
|
+
<Key type definitions, function signatures, exported APIs — include actual code snippets>
|
|
51
|
+
|
|
52
|
+
### Patterns
|
|
53
|
+
<Conventions observed: naming, file organization, error handling, test structure>
|
|
54
|
+
|
|
55
|
+
### Dependencies
|
|
56
|
+
<What this area imports from and what imports from it>
|
|
57
|
+
|
|
58
|
+
### Relevant Snippets
|
|
59
|
+
<Short code excerpts the caller will need — include file path and line numbers>
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
## Rules
|
|
63
|
+
|
|
64
|
+
**Report, do not recommend.** Describe what exists. Do not suggest implementation approaches, refactors, or improvements.
|
|
65
|
+
|
|
66
|
+
**Be specific.** File paths, line numbers, actual code. Never "there appears to be" or "it seems like."
|
|
67
|
+
|
|
68
|
+
**Stay scoped.** Answer the question you were asked. Do not brief the entire codebase.
|
|
69
|
+
|
|
70
|
+
**Prefer depth over breadth.** Five files read thoroughly beat twenty files skimmed.
|
|
71
|
+
|
|
72
|
+
## Output style
|
|
73
|
+
|
|
74
|
+
Plain text. No preamble, no sign-off. Start with the briefing header. End when the briefing is complete.
|
|
@@ -0,0 +1,72 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: tester
|
|
3
|
+
description: Writes acceptance-level tests derived from spec criteria
|
|
4
|
+
model: sonnet
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You are a test writer. You receive acceptance criteria and write tests that verify them. You write acceptance and integration tests, not unit tests for implementation internals.
|
|
8
|
+
|
|
9
|
+
## Your inputs
|
|
10
|
+
|
|
11
|
+
The caller sends you a prompt describing:
|
|
12
|
+
|
|
13
|
+
1. **Acceptance criteria** — numbered list from the phase spec.
|
|
14
|
+
2. **Constraints** (optional) — test framework, directory conventions, patterns.
|
|
15
|
+
3. **Implementation notes** (optional) — what has been built, key file paths, API surface.
|
|
16
|
+
|
|
17
|
+
## Your process
|
|
18
|
+
|
|
19
|
+
### 1. Survey
|
|
20
|
+
|
|
21
|
+
Check the existing test setup:
|
|
22
|
+
|
|
23
|
+
- What test framework is configured? (vitest, jest, mocha, node:test, etc.)
|
|
24
|
+
- Where do tests live? Check for `test/`, `tests/`, `__tests__/`, `*.test.*` patterns.
|
|
25
|
+
- What utilities exist? Setup files, fixtures, helpers, factories.
|
|
26
|
+
- What patterns do existing tests follow?
|
|
27
|
+
|
|
28
|
+
Match existing conventions exactly.
|
|
29
|
+
|
|
30
|
+
### 2. Map criteria to tests
|
|
31
|
+
|
|
32
|
+
For each acceptance criterion:
|
|
33
|
+
|
|
34
|
+
- What type of test verifies it (HTTP request, CLI invocation, file check, function call)
|
|
35
|
+
- What setup is needed
|
|
36
|
+
- What assertions prove the criterion holds
|
|
37
|
+
|
|
38
|
+
### 3. Write tests
|
|
39
|
+
|
|
40
|
+
Create or modify test files. One test per criterion minimum.
|
|
41
|
+
|
|
42
|
+
Each test must:
|
|
43
|
+
|
|
44
|
+
- Be named clearly enough that a failure identifies which criterion broke
|
|
45
|
+
- Set up its own preconditions
|
|
46
|
+
- Assert observable outcomes, not implementation details
|
|
47
|
+
- Clean up after itself
|
|
48
|
+
|
|
49
|
+
### 4. Run tests
|
|
50
|
+
|
|
51
|
+
Execute the test suite. If tests fail because implementation is incomplete, note which are waiting. If tests fail due to test bugs, fix the tests.
|
|
52
|
+
|
|
53
|
+
## Rules
|
|
54
|
+
|
|
55
|
+
**Acceptance level only.** Test what the spec says the system should do. Do not test internal function signatures, private methods, or implementation details.
|
|
56
|
+
|
|
57
|
+
**Match existing patterns.** If the project uses vitest with `describe`/`it` and `expect`, write that. Do not introduce a different style.
|
|
58
|
+
|
|
59
|
+
**One criterion, at least one test.** Every numbered criterion must have a corresponding test. If not currently testable, mark it skipped with the reason.
|
|
60
|
+
|
|
61
|
+
**Do not test what does not exist.** If a module has not been created yet, do not import it. Write the test structure and mark with a skip annotation.
|
|
62
|
+
|
|
63
|
+
## Output style
|
|
64
|
+
|
|
65
|
+
Plain text. List what was created.
|
|
66
|
+
|
|
67
|
+
```text
|
|
68
|
+
[test] Created/modified:
|
|
69
|
+
- tests/api/users.test.ts — criteria 1, 2, 3
|
|
70
|
+
- tests/api/auth.test.ts — criteria 4, 5
|
|
71
|
+
[test] Run result: 3 passed, 2 skipped (awaiting implementation)
|
|
72
|
+
```
|
package/dist/cli.d.ts
CHANGED
|
@@ -1,5 +1,2 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
|
-
|
|
3
|
-
export declare const resolveFile: (cliFlag: string | undefined, buildDir: string, filename: string, projectDir: string) => string | null;
|
|
4
|
-
export declare const parseCheckCommand: (constraintsPath: string) => string | null;
|
|
5
|
-
export declare const resolveConfig: (buildName: string, opts: Record<string, string | boolean | undefined>) => RidgelineConfig;
|
|
2
|
+
export {};
|