@koreanhole/kandev 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +367 -2
- package/bin/codex-acp.js +16 -0
- package/bin/kandev-auto-sync.mjs +101 -0
- package/bin/kandev-config.js +53 -0
- package/bin/kandev.js +35 -0
- package/config/config.yaml +6 -0
- package/config/docker/projects/opencodex-cli.json +79 -0
- package/config/docker/projects/samsung-bus-tracker.json +91 -0
- package/config/gateways.json +14 -0
- package/config/pipeline.json +150 -0
- package/config/workflows/sdlc.yaml +1019 -0
- package/docker/Dockerfile +68 -0
- package/docker/Dockerfile.opencodex-cli +44 -0
- package/docker/Dockerfile.samsung-bus-tracker +75 -0
- package/package.json +61 -4
- package/scripts/agent-tools-docker.mjs +223 -0
- package/scripts/baseline.mjs +20 -0
- package/scripts/codex-medium +2 -0
- package/scripts/codex-stage +22 -0
- package/scripts/gate.mjs +909 -0
- package/scripts/gateways/docker.mjs +64 -0
- package/scripts/gateways/speckit.mjs +78 -0
- package/scripts/install-prerequisites.mjs +48 -0
- package/scripts/lib/artifacts.mjs +990 -0
- package/scripts/lib/bugfix.mjs +325 -0
- package/scripts/lib/checksum.mjs +166 -0
- package/scripts/lib/docker-workspace.mjs +1209 -0
- package/scripts/lib/gateways.mjs +79 -0
- package/scripts/lib/kandev.mjs +273 -0
- package/scripts/lib/mcp.mjs +111 -0
- package/scripts/lib/pipeline.mjs +548 -0
- package/scripts/lib/planning-replan.mjs +103 -0
- package/scripts/lib/resume.mjs +207 -0
- package/scripts/lib/review-history.mjs +260 -0
- package/scripts/lib/stage-boundary.mjs +146 -0
- package/scripts/lib/stage-model.mjs +23 -0
- package/scripts/lib/task-worktree.mjs +40 -0
- package/scripts/measure-tokens.mjs +121 -0
- package/scripts/planning-tools.mjs +166 -0
- package/scripts/replan-planning.mjs +82 -0
- package/scripts/review-digest.mjs +240 -0
- package/scripts/run-android-e2e.mjs +116 -0
- package/scripts/run-code-review.mjs +281 -0
- package/scripts/run-detached.mjs +163 -0
- package/scripts/run-doc-review.mjs +155 -0
- package/scripts/run-gateways.mjs +138 -0
- package/scripts/sync.mjs +588 -0
- package/scripts/verify-change.mjs +252 -0
- package/scripts/verify-node.mjs +288 -0
- package/scripts/verify.mjs +442 -0
- package/scripts/wait-status.mjs +88 -0
package/README.md
CHANGED
|
@@ -1,3 +1,368 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Kandev Workflow Config — Agentic SDLC
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Configuration-as-code for a five-stage agentic software lifecycle with a human approval lane on
|
|
4
|
+
[Kandev](https://kandev.ai). Agent gateways → Spec Kit planning and document review →
|
|
5
|
+
clean-context implementation → independent review → end-to-end verification, with a
|
|
6
|
+
hard fail-fast gate at every step.
|
|
7
|
+
|
|
8
|
+
- **Kandev core is untouched.** Only `config.yaml`, portable workflow YAML, agent
|
|
9
|
+
profiles, and the external MCP/HTTP surfaces are used.
|
|
10
|
+
- **npm-distributed agents only.** All stages run the `@openai/codex` runtime brought by `codex-acp`;
|
|
11
|
+
the gateway adapters and `$speckit-*` skills are deterministic setup/planning
|
|
12
|
+
surfaces, not local review agents. E2E adds `@playwright/mcp` and
|
|
13
|
+
`@playwright/test`.
|
|
14
|
+
- **Git is the source of truth.** `npm run sync` reconciles a live instance to the
|
|
15
|
+
committed definition and is idempotent; UI edits are drift.
|
|
16
|
+
|
|
17
|
+
## npm bundle
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install -g @koreanhole/kandev
|
|
21
|
+
kandev
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
On the first server start, the `kandev` wrapper waits for the loopback endpoint and runs
|
|
25
|
+
the bundled workflow sync automatically. Set `KANDEV_AUTO_SYNC=0` to disable it. If the
|
|
26
|
+
automatic sync fails because `codex-acp` is not ready yet, run `kandev-config sync`
|
|
27
|
+
manually after Kandev is up.
|
|
28
|
+
|
|
29
|
+
`@koreanhole/kandev` installs Kandev 0.98.0, this repository's runtime config, the
|
|
30
|
+
three sub-agent packages, and `@agentclientprotocol/codex-acp@2.5.0`. `codex-acp` brings
|
|
31
|
+
its compatible `@openai/codex` transitively. The bundle exposes `codex-acp`. The postinstall installs
|
|
32
|
+
`specify-cli==1.2.0` with `uv` or `pipx` when `specify` is missing. If it cannot install
|
|
33
|
+
or verify `specify`, the npm install fails. Set `KANDEV_SKIP_PREREQ_INSTALL=1` only when
|
|
34
|
+
you intentionally manage `specify` yourself. Codex authentication remains a manual
|
|
35
|
+
prerequisite. `kandev` forwards to the original CLI; `kandev-config` applies and verifies
|
|
36
|
+
the bundled config. Gate and baseline state live under the
|
|
37
|
+
installed package's `.cache`; after upgrading the package, rerun
|
|
38
|
+
`kandev-config baseline`.
|
|
39
|
+
|
|
40
|
+
## Requirements
|
|
41
|
+
|
|
42
|
+
- Kandev 0.98.x running on the same host, bound to loopback.
|
|
43
|
+
- Node.js 22+.
|
|
44
|
+
- Codex CLI authenticated as the Kandev service user (`codex exec "ok"` succeeds).
|
|
45
|
+
Authentication is not automated by the package.
|
|
46
|
+
- `specify` CLI on PATH for the Stage 1 gateway. The npm postinstall installs
|
|
47
|
+
`specify-cli==1.2.0` with `uv` or `pipx` when it is missing and fails the install if it
|
|
48
|
+
still cannot verify `specify`. Install `uv`, `pipx`, or `specify-cli==1.2.0` before the
|
|
49
|
+
npm install, or set `KANDEV_SKIP_PREREQ_INSTALL=1` if you manage it yourself.
|
|
50
|
+
- `@agentclientprotocol/codex-acp@2.5.0` is installed by the bundle and exposed as
|
|
51
|
+
`codex-acp`. Kandev's `codex-acp` agent must still be configured and ready;
|
|
52
|
+
`kandev-config sync` checks it.
|
|
53
|
+
- `gh` authenticated for the one-time repository setup.
|
|
54
|
+
|
|
55
|
+
## Source checkout
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
git clone git@github.com:koreanhole/kandev-workflow-config.git
|
|
59
|
+
cd kandev-workflow-config
|
|
60
|
+
npm ci
|
|
61
|
+
cp .env.example .env # optional overrides; no secret is required to sync
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Apply
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
npm run sync # create/update profiles + workflow, bind steps
|
|
68
|
+
npm run sync # must print only "unchanged"
|
|
69
|
+
npm run baseline # record the immutable Kandev install (once per install/upgrade)
|
|
70
|
+
npm run gate # keep running in another terminal (completion gate)
|
|
71
|
+
npm run verify # all checks must be OK
|
|
72
|
+
npm run measure # read-only token usage from the local Kandev database
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`kandev` already runs the sync automatically for `run`/`start` and no-subcommand
|
|
76
|
+
launches. Use `kandev-config sync` to reapply after config changes. The installed
|
|
77
|
+
equivalents are `kandev-config sync`, `kandev-config sync --dry-run`,
|
|
78
|
+
`kandev-config baseline`, `kandev-config gate`, `kandev-config verify`, and
|
|
79
|
+
`kandev-config measure`. Automatic sync does not run for `dev`, `service`, `--help`, or
|
|
80
|
+
`--version`.
|
|
81
|
+
|
|
82
|
+
`sync` never deletes profiles or a workflow. Extra steps are reported as a conflict and
|
|
83
|
+
left untouched; `--prune` is refused while any task exists and only removes extra steps
|
|
84
|
+
after the workflow is empty. Steps are updated in place so existing tasks keep their
|
|
85
|
+
position. `baseline` is required before `verify`; rerun it after every Kandev upgrade.
|
|
86
|
+
Exit codes: `0` converged, `1` live failure, `2` validation failure.
|
|
87
|
+
|
|
88
|
+
`npm run e2e:contract` runs a token-free agent-stage contract test: the real gate,
|
|
89
|
+
artifact validators, stage boundaries, and `verify-change.mjs` are exercised against a
|
|
90
|
+
temporary fixture with no model calls.
|
|
91
|
+
|
|
92
|
+
An existing four-stage workflow must be migrated once before the first five-stage sync:
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
npm run migrate:legacy
|
|
96
|
+
npm run sync
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
The migration reuses the legacy step IDs, inserts Agent Gateway, and refuses while any
|
|
100
|
+
task is active.
|
|
101
|
+
|
|
102
|
+
An existing five-stage workflow must then run the approval migration once:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npm run migrate:approval
|
|
106
|
+
npm run sync
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
It renames `6. Done` to `7. Done`, inserts `6. Human Approval`, and reorders the steps.
|
|
110
|
+
|
|
111
|
+
## npm release
|
|
112
|
+
|
|
113
|
+
The package is published from this repository. Publish the Android sub-agent first when
|
|
114
|
+
its pin changes, then refresh the lockfile and publish the bundle:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
npm login
|
|
118
|
+
(cd agents/android-testing-superpowers && npm run release)
|
|
119
|
+
npm install --package-lock-only
|
|
120
|
+
npm test
|
|
121
|
+
npm publish --access public
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The tarball contains only `bin/`, the runtime config, `scripts/`, and this README. It
|
|
125
|
+
excludes `agents/`, `specs/`, `test/`, and `.cache/`.
|
|
126
|
+
|
|
127
|
+
## Pipeline
|
|
128
|
+
|
|
129
|
+
| Step | Profile | Artifact |
|
|
130
|
+
| --- | --- | --- |
|
|
131
|
+
| 1. Agent Gateway | `SDLC 1 · Gateway` | `.agentic/gateway.json` |
|
|
132
|
+
| 2. Planning | `SDLC 2 · Planning` | `.agentic/spec.json`, `.agentic/spec-review.json`, `.agentic/speckit-analyze.md`, optional `.agentic/bugfix.json` |
|
|
133
|
+
| 3. Implementation | `SDLC 3 · Implement` | `.agentic/implementation.json`, `.agentic/bugfix-runs/` for bugfixes |
|
|
134
|
+
| 4. Code Review | `SDLC 4 · Review` | `.agentic/review.json` |
|
|
135
|
+
| 5. E2E | `SDLC 5 · E2E` | `.agentic/e2e.json` |
|
|
136
|
+
| 6. Human Approval | — | manual lane; a person reviews the verified worktree/PR |
|
|
137
|
+
| 7. Done | — | terminal lane; `complete_task_on_enter` |
|
|
138
|
+
|
|
139
|
+
Stages 1-5 set `auto_advance_requires_signal: true`, but the workflow itself has no
|
|
140
|
+
transition actions. `scripts/gate.mjs` watches tasks whose turn ended, validates the stage
|
|
141
|
+
artifact (`verdict: PASS`, AC coverage, scenario status, build/lint codes) and only then
|
|
142
|
+
moves the task. Missing or invalid artifacts leave it in place. A valid `review.json` or
|
|
143
|
+
`e2e.json` with `verdict: FAIL` is a rework signal: when `config/pipeline.json` sets
|
|
144
|
+
`rework.max_attempts` to a positive number, the gate moves the task back to Implementation
|
|
145
|
+
and logs the attempt. After the cap it blocks for human review. Omit the policy or set it
|
|
146
|
+
to `0` for fail-fast-only behavior. The gate keeps the Planning pins (`spec.json`,
|
|
147
|
+
`bugfix.json`, and reproduction files) across every later transition. Agent stages 1-5
|
|
148
|
+
disable manual moves; the gate owns those transitions. Human Approval is the only manual
|
|
149
|
+
lane: a person reviews the verified worktree and moves the task to Done. No agent can
|
|
150
|
+
signal directly into Done.
|
|
151
|
+
|
|
152
|
+
All five stages and the default workspace profile (`DeepSeek V4.1 Flash`) run on `combo/deepseek-v4.1-flash-auto`
|
|
153
|
+
with `reasoning_effort: "xhigh"`, including Stage 5 E2E. The same stage model is injected
|
|
154
|
+
into the child agents through each profile's `agent-tools` environment, so the requirement
|
|
155
|
+
agent, code review roles, and Android E2E agent do not fall back to their package
|
|
156
|
+
defaults. The resume policy below bounds stalled-turn recovery.
|
|
157
|
+
|
|
158
|
+
Live E2E runs (`docs/token-free-e2e.md` layer 4) lower that model's reasoning effort to
|
|
159
|
+
`low`, its lowest supported value. The token-free contract and no-agent probe never call
|
|
160
|
+
a model, so the setting does not apply there.
|
|
161
|
+
|
|
162
|
+
The gate also resumes a stage that ends without its artifact. It sends a self-contained
|
|
163
|
+
`[Kandev resume]` prompt to the same session through `message_task_kandev`, or creates a
|
|
164
|
+
replacement session with `spawn_session_kandev` when every session is terminal. It never
|
|
165
|
+
moves a task; the artifact validators remain the only transition authority. The policy in
|
|
166
|
+
`config/pipeline.json` allows three attempts per task and stage boundary, with a
|
|
167
|
+
two-minute cooldown. A `RUNNING`/`STARTING` session is left alone while its last message
|
|
168
|
+
is within the stage idle window (15 minutes; 30 minutes for Code Review and E2E). A truly
|
|
169
|
+
hung session is settled by Kandev's stall sweep, so `config/config.yaml` sets
|
|
170
|
+
`tasks.stallDetectionThreshold: "10m"`; apply the same value to the live service and
|
|
171
|
+
restart Kandev once when no task is mid-turn. The current headless launch does not inject
|
|
172
|
+
`config/config.yaml` into the backend automatically, so set
|
|
173
|
+
`KANDEV_TASK_STALL_DETECTION_THRESHOLD=10m` in the launch environment as well. After the
|
|
174
|
+
third failed attempt the gate blocks for human review. The gate discovers the advertised
|
|
175
|
+
MCP tools first; if the connected Kandev build does not expose the message/spawn tool,
|
|
176
|
+
resume is treated as unavailable and no resume failure is recorded.
|
|
177
|
+
|
|
178
|
+
`rework.max_attempts` lives in `config/pipeline.json` because rework is an external gate
|
|
179
|
+
policy, not a Kandev transition action. The gate counts `decision: "rework"` entries in
|
|
180
|
+
`.cache/gate-log.jsonl`; the cap is per task. A FAIL artifact older than the current stage
|
|
181
|
+
boundary is treated as stale and never starts a new rework. When the gate routes back, it
|
|
182
|
+
archives the prior `implementation.json` (and the prior `review.json` after an E2E failure)
|
|
183
|
+
under `.agentic/rework/` and removes the live copy, so a rework turn that stops without
|
|
184
|
+
writing fresh evidence cannot advance on the old PASS artifact.
|
|
185
|
+
|
|
186
|
+
The gateway stage is generic. `config/gateways.json` lists enabled adapters; the current
|
|
187
|
+
`speckit` adapter installs Codex Spec Kit skills when `.specify` or `.agents/skills` is
|
|
188
|
+
missing and preserves an existing default integration. Future gateways add a module and a
|
|
189
|
+
config entry without changing the workflow prompt.
|
|
190
|
+
|
|
191
|
+
Implementation starts in a new session with no task prompt. It reads `.agentic/spec.json`
|
|
192
|
+
only for the reviewed `documents` list, runs `$speckit-implement`, runs
|
|
193
|
+
`$speckit-converge` once, and runs one follow-up `$speckit-implement` only when
|
|
194
|
+
convergence appended unchecked tasks. The code review stage sees the application diff,
|
|
195
|
+
not `specs/` planning evidence.
|
|
196
|
+
|
|
197
|
+
Stage 3 follows `$speckit-implement`'s normal implementation and verification. A feature
|
|
198
|
+
that changes source files must add or update a permanent test file; the temporary
|
|
199
|
+
`.agentic/e2e-driver.mjs` is not a permanent test. After
|
|
200
|
+
that, `scripts/verify-change.mjs` writes the deterministic `implementation.json`
|
|
201
|
+
artifact and leaves the full output in `.agentic/verify.log`. The agent reads only the
|
|
202
|
+
last 60 lines of that log when the verifier fails.
|
|
203
|
+
|
|
204
|
+
### Bugfix path
|
|
205
|
+
|
|
206
|
+
Planning writes `change_type` (`feature` or `bugfix`) and a classification reason in
|
|
207
|
+
`spec.json`. A bugfix also writes `.agentic/bugfix.json` with the symptom, the canonical
|
|
208
|
+
E2E driver, pinned file hashes, a `path:line` root cause, and the permanent regression
|
|
209
|
+
test. It must run `.agentic/bugfix-repro.mjs` and record a failed `planning-before` run
|
|
210
|
+
before `$speckit-plan`. Stage 3 replays the same driver before any edit, adds the native
|
|
211
|
+
regression test, replays after the fix, and records both results. Stage 5 replays the
|
|
212
|
+
same driver and the permanent test. The gate pins `spec.json`, `bugfix.json`, and every
|
|
213
|
+
reproduction file at the Planning transition; a changed canonical file blocks the task.
|
|
214
|
+
|
|
215
|
+
Feature classification is checked twice. First, the gate rejects a `feature` task whose
|
|
216
|
+
text carries an explicit bug marker (`[bug]`, `bug:`, an issue reference, or a Korean
|
|
217
|
+
bug/error word). Second, Stage 4 independently classifies the change and the gate fails
|
|
218
|
+
the review when that classification differs from `spec.json`.
|
|
219
|
+
|
|
220
|
+
The bugfix path does not add a workflow stage or change the pinned npm agents. It uses
|
|
221
|
+
the existing execution profile, `$speckit-*` skills, code reviewer, and Android test
|
|
222
|
+
package.
|
|
223
|
+
|
|
224
|
+
Each stage is write-isolated by the external gate. Gateway may only create `.specify/`,
|
|
225
|
+
`.agents/`, and its own artifact. Planning may only create `specs/` and
|
|
226
|
+
`.specify/feature.json`. Implementation may change application files and `tasks.md`
|
|
227
|
+
checkboxes. Code Review and E2E are read-only for the application and planning documents;
|
|
228
|
+
their reports live under `.agentic/`. The gate snapshots the worktree after each successful
|
|
229
|
+
transition and rejects out-of-stage paths.
|
|
230
|
+
|
|
231
|
+
## Token controls
|
|
232
|
+
|
|
233
|
+
All five agent-stage prompts share one bounded-output rule: build/test logs end in
|
|
234
|
+
`2>&1 | tail -60`, file reads end in `| head -c 4000`, and any command that may
|
|
235
|
+
exceed 8 KB writes to `.agentic/logs/` first. A tool result larger than 8 KB is a
|
|
236
|
+
pipeline defect and must be rerun bounded.
|
|
237
|
+
|
|
238
|
+
Stage 2 uses `$speckit-specify`, `$speckit-clarify`, `$speckit-plan`, and
|
|
239
|
+
`$speckit-tasks`, then reviews the feature directory with the pinned requirement agent
|
|
240
|
+
(ambiguity, testability, consistency) and one `$speckit-analyze` pass. Three successful
|
|
241
|
+
rounds are the maximum. The planning gate verifies reviewed-document hashes, checklist
|
|
242
|
+
completion, `feature.json`, and the analyze report before implementation. Stage 2 and
|
|
243
|
+
Stage 4 wait with `scripts/wait-status.mjs` instead of polling every 20 seconds.
|
|
244
|
+
The requirement agent receives `--model` from `KANDEV_STAGE_MODEL`; a missing or invalid
|
|
245
|
+
model stops the wrapper before it spawns the package. After two completed review rounds,
|
|
246
|
+
the `FR-*`/`AC-*`/`SC-*` id set from the latest completed round is frozen and each reviewed
|
|
247
|
+
document has a bounded remediation growth budget. New behavior requires a replan instead
|
|
248
|
+
of expanding the documents inside the review loop. The finalizer records hashes from the
|
|
249
|
+
latest review run's immutable `snapshot.json`, not from the current files, and binds
|
|
250
|
+
`rounds`, `major_history`, counts, and major finding stable ids to the completed run artifacts.
|
|
251
|
+
The requirement agent merges cross-role findings at shared citation loci and emits a
|
|
252
|
+
`stableId`; the gate prefers it over the renumbered `F-*` display id. A major count may rise
|
|
253
|
+
between rounds when the reviewer reviews revised text; PASS requires zero blockers and a
|
|
254
|
+
reason for every remaining major, not a decreasing count. Every listed
|
|
255
|
+
document, including `analysis.md`, must be final before the final review run; any edit
|
|
256
|
+
after it invalidates the snapshot and requires another round.
|
|
257
|
+
|
|
258
|
+
Stage 3 runs `scripts/verify-change.mjs` once after the skill's normal verification. It
|
|
259
|
+
runs configured npm build/lint/test scripts for Node and Web, or `./gradlew assembleDebug` plus
|
|
260
|
+
`./gradlew testDebugUnitTest` for Android, and writes `implementation.json` plus
|
|
261
|
+
`.agentic/verify.log`. Stage 5's Node branch still uses
|
|
262
|
+
`scripts/verify-node.mjs --mode e2e` for its final acceptance run and writes
|
|
263
|
+
`node-result.json` plus `node-test.log`.
|
|
264
|
+
|
|
265
|
+
Stage 4 runs the code reviewer through the repository-owned `scripts/codex-medium`
|
|
266
|
+
shim. The shim injects `model_reasoning_effort="medium"` while preserving argv and
|
|
267
|
+
exit status. Every selected role is launched as `codex:<KANDEV_STAGE_MODEL>`, so the
|
|
268
|
+
reviewer package cannot use its own default model. The wrapper disables Codex ACP for
|
|
269
|
+
that invocation, logs the selected CLI transport, model, and effort before spawning, and
|
|
270
|
+
fails if the shim or stage model is missing. Before review,
|
|
271
|
+
it writes `.agentic/review-excludes.txt` and injects it through
|
|
272
|
+
`GIT_CONFIG_*` so logs and derived artifacts never enter the application diff;
|
|
273
|
+
`.agentic/spec.json` remains the authoritative contract. After review,
|
|
274
|
+
`scripts/review-digest.mjs` produces a compact JSON digest; the stage must not read
|
|
275
|
+
`aggregateMarkdown` or the full log. Package install failures are infrastructure
|
|
276
|
+
failures and must not be debugged through the npm registry.
|
|
277
|
+
|
|
278
|
+
The review wrapper selects roles from `spec.json`: a feature uses spec-compliance,
|
|
279
|
+
adversarial, and regression; a bugfix uses adversarial and regression; Android adds the
|
|
280
|
+
ANR/FC risk role. The selected roles are logged with the run.
|
|
281
|
+
|
|
282
|
+
Stage 5's Android branch runs through `scripts/run-android-e2e.mjs`, which sets the
|
|
283
|
+
stage model as `SUPERPOWER_LLM_MODEL` and points the package at `scripts/codex-stage`.
|
|
284
|
+
That shim translates the Android agent's `-p` prompt into `codex exec -m
|
|
285
|
+
<KANDEV_STAGE_MODEL>`, so the Android planner and evaluator use the Kandev model.
|
|
286
|
+
|
|
287
|
+
Stage 5's web branch runs `.agentic/e2e-driver.mjs` first: one real Playwright
|
|
288
|
+
scenario per acceptance criterion, bounded output, and `.agentic/e2e-result.json`
|
|
289
|
+
with per-AC evidence. Interactive Playwright MCP inspection is limited to five calls
|
|
290
|
+
after a driver start failure or an ambiguous assertion. Screenshots are failure-only.
|
|
291
|
+
|
|
292
|
+
## Layout
|
|
293
|
+
|
|
294
|
+
```text
|
|
295
|
+
config/config.yaml startup configuration (loopback, port, home)
|
|
296
|
+
config/pipeline.json stage -> profile/model/MCP mapping
|
|
297
|
+
config/workflows/sdlc.yaml portable kandev_workflow definition
|
|
298
|
+
config/gateways.json enabled gateway adapters in execution order
|
|
299
|
+
scripts/sync.mjs idempotent reconciler
|
|
300
|
+
scripts/gate.mjs external completion gate (validates artifacts, moves tasks)
|
|
301
|
+
scripts/verify.mjs live verification (health, bindings, immutability, secrets)
|
|
302
|
+
scripts/measure-tokens.mjs read-only task/profile token report
|
|
303
|
+
scripts/wait-status.mjs blocking stage-status wait
|
|
304
|
+
scripts/run-gateways.mjs gateway adapter runner and gateway.json writer
|
|
305
|
+
scripts/gateways/speckit.mjs Spec Kit Codex-skill adapter
|
|
306
|
+
scripts/planning-tools.mjs planning hashes and handoff validation
|
|
307
|
+
scripts/run-doc-review.mjs pinned requirement-agent wrapper
|
|
308
|
+
scripts/run-android-e2e.mjs pinned Android E2E wrapper with stage-model injection
|
|
309
|
+
scripts/verify-change.mjs deterministic Stage 3 build/test verifier
|
|
310
|
+
scripts/lib/bugfix.mjs bugfix contract, run evidence, and hash pins
|
|
311
|
+
scripts/verify-node.mjs deterministic Node build/lint/test verification
|
|
312
|
+
scripts/review-digest.mjs compact code-review summary
|
|
313
|
+
scripts/codex-medium code-review executor shim (medium reasoning effort)
|
|
314
|
+
scripts/codex-stage Android executor shim (stage model injection)
|
|
315
|
+
scripts/lib/stage-model.mjs KANDEV_STAGE_MODEL validation
|
|
316
|
+
scripts/lib/ MCP client, Kandev helpers, validation, checksum
|
|
317
|
+
test/ unit tests for pure logic
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
## Change workflow
|
|
321
|
+
|
|
322
|
+
1. Edit `config/workflows/sdlc.yaml` or `config/pipeline.json`.
|
|
323
|
+
2. `npm test && npm run sync && npm run verify`.
|
|
324
|
+
3. Commit and push. Kandev never owns the definition; the repository does.
|
|
325
|
+
|
|
326
|
+
Native Workflow Sync is intentionally not enabled in the MVP: portable descriptors match
|
|
327
|
+
profiles by agent display name + model, and every agent stage shares the Codex vendor. The
|
|
328
|
+
reconciler binds profiles by exact name instead, which is deterministic. See
|
|
329
|
+
`specs/001-agentic-sdlc-pipeline/` for the full design and verification evidence.
|
|
330
|
+
|
|
331
|
+
## Self-improvement loop
|
|
332
|
+
|
|
333
|
+
The read-only reviewer in `improver/` reviews completed and gate-blocked tasks,
|
|
334
|
+
writes task reports and agent scorecards under `.state/improver/`, and turns
|
|
335
|
+
repeated failures into candidate Kandev tasks. It never edits a worktree or the
|
|
336
|
+
Kandev database. See [docs/improver.md](docs/improver.md) for the report fields,
|
|
337
|
+
ticket rules, and guardrails.
|
|
338
|
+
|
|
339
|
+
```bash
|
|
340
|
+
npm run improve:status
|
|
341
|
+
npm run improve # one tick
|
|
342
|
+
npm run improve:review -- <task-id>
|
|
343
|
+
npm run improve:tickets
|
|
344
|
+
npm run improve:convert -- <ticket-id> [--start-agent] [--yes]
|
|
345
|
+
npm run measure # task and per-profile token totals
|
|
346
|
+
mkdir -p .state/improver && touch .state/improver/FREEZE # stop actions; remove to resume
|
|
347
|
+
```
|
|
348
|
+
|
|
349
|
+
A frozen tick, review, or conversion exits `2` and appends a `skipped` audit
|
|
350
|
+
record without writing a report or calling MCP. Conversion runs under the
|
|
351
|
+
controller lock. The lock is an atomic directory at `.state/improver/lock/`
|
|
352
|
+
with a heartbeat; only a changed hostname, dead PID, or heartbeat older than 24
|
|
353
|
+
hours makes it stale.
|
|
354
|
+
|
|
355
|
+
Planning also accepts `platform: "node"`. Stage 5's Node branch runs the
|
|
356
|
+
deterministic `verify-node.mjs --mode e2e` helper, which runs `npm test` and
|
|
357
|
+
a non-mutating `npm run sync:dry` when defined, otherwise records
|
|
358
|
+
`not-configured` at exit 127. Both results go in the required `commands` array,
|
|
359
|
+
and `report_path` plus scenario evidence must be non-empty `.log` files under
|
|
360
|
+
`.agentic/`. Improvement tasks are limited to a candidate commit plus rollback
|
|
361
|
+
notes; sync, publish, gate restart, and live `~/.kandev` edits are forbidden.
|
|
362
|
+
|
|
363
|
+
## Security
|
|
364
|
+
|
|
365
|
+
`.env`, artifacts, caches, and Playwright output are gitignored. `verify` scans every
|
|
366
|
+
tracked file for token patterns and refuses non-empty `.env.example` values. The External
|
|
367
|
+
MCP endpoint is loopback-only and unauthenticated, so never expose the Kandev port
|
|
368
|
+
publicly without an authenticated proxy.
|
package/bin/codex-acp.js
ADDED
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { spawn } from "node:child_process";
|
|
3
|
+
import { createRequire } from "node:module";
|
|
4
|
+
|
|
5
|
+
const require = createRequire(import.meta.url);
|
|
6
|
+
const entry = require.resolve("@agentclientprotocol/codex-acp/dist/index.js");
|
|
7
|
+
const child = spawn(process.execPath, [entry, ...process.argv.slice(2)], {
|
|
8
|
+
stdio: "inherit",
|
|
9
|
+
});
|
|
10
|
+
child.on("error", (error) => {
|
|
11
|
+
console.error(`[codex-acp] ${error.message}`);
|
|
12
|
+
process.exit(1);
|
|
13
|
+
});
|
|
14
|
+
child.on("exit", (code, signal) => {
|
|
15
|
+
process.exit(code ?? (signal ? 1 : 0));
|
|
16
|
+
});
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
import { spawnSync as nodeSpawnSync } from "node:child_process";
|
|
3
|
+
|
|
4
|
+
const SERVER_COMMANDS = new Set(["run", "start"]);
|
|
5
|
+
const VALUE_FLAGS = new Set(["--port", "--backend-port", "--web-internal-port"]);
|
|
6
|
+
const INFORMATIONAL_FLAGS = new Set(["--help", "-h", "--version", "-V", "--dev"]);
|
|
7
|
+
|
|
8
|
+
export function shouldAutoSync(argv, env = process.env) {
|
|
9
|
+
if (env.KANDEV_AUTO_SYNC === "0") return false;
|
|
10
|
+
if (argv.some((arg) => INFORMATIONAL_FLAGS.has(arg))) return false;
|
|
11
|
+
let command = null;
|
|
12
|
+
for (let index = 0; index < argv.length; index += 1) {
|
|
13
|
+
const arg = argv[index];
|
|
14
|
+
if (VALUE_FLAGS.has(arg)) {
|
|
15
|
+
index += 1;
|
|
16
|
+
continue;
|
|
17
|
+
}
|
|
18
|
+
if (arg.startsWith("-")) continue;
|
|
19
|
+
command = arg;
|
|
20
|
+
break;
|
|
21
|
+
}
|
|
22
|
+
return command === null || SERVER_COMMANDS.has(command);
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export function targetUrl(argv, env = process.env) {
|
|
26
|
+
if (env.KANDEV_URL) return env.KANDEV_URL.replace(/\/$/, "");
|
|
27
|
+
let port = "38429";
|
|
28
|
+
for (let index = 0; index < argv.length; index += 1) {
|
|
29
|
+
const arg = argv[index];
|
|
30
|
+
if (arg === "--port" || arg === "--backend-port") {
|
|
31
|
+
if (argv[index + 1]) {
|
|
32
|
+
port = argv[index + 1];
|
|
33
|
+
index += 1;
|
|
34
|
+
}
|
|
35
|
+
continue;
|
|
36
|
+
}
|
|
37
|
+
if (arg.startsWith("--port=")) port = arg.slice("--port=".length);
|
|
38
|
+
else if (arg.startsWith("--backend-port=")) port = arg.slice("--backend-port=".length);
|
|
39
|
+
}
|
|
40
|
+
return `http://127.0.0.1:${port}`;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function sleep(milliseconds, signal) {
|
|
44
|
+
return new Promise((resolve) => {
|
|
45
|
+
const timer = setTimeout(resolve, milliseconds);
|
|
46
|
+
signal?.addEventListener(
|
|
47
|
+
"abort",
|
|
48
|
+
() => {
|
|
49
|
+
clearTimeout(timer);
|
|
50
|
+
resolve();
|
|
51
|
+
},
|
|
52
|
+
{ once: true },
|
|
53
|
+
);
|
|
54
|
+
});
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export async function autoSync({
|
|
58
|
+
argv,
|
|
59
|
+
env = process.env,
|
|
60
|
+
root,
|
|
61
|
+
fetchImpl = fetch,
|
|
62
|
+
spawnSyncImpl = nodeSpawnSync,
|
|
63
|
+
log = console.log,
|
|
64
|
+
warn = console.warn,
|
|
65
|
+
timeoutMs = 120000,
|
|
66
|
+
intervalMs = 1000,
|
|
67
|
+
signal,
|
|
68
|
+
} = {}) {
|
|
69
|
+
if (!shouldAutoSync(argv, env)) return { synced: false, reason: "disabled" };
|
|
70
|
+
const url = targetUrl(argv, env);
|
|
71
|
+
const deadline = Date.now() + timeoutMs;
|
|
72
|
+
while (Date.now() < deadline) {
|
|
73
|
+
if (signal?.aborted) return { synced: false, reason: "aborted", url };
|
|
74
|
+
try {
|
|
75
|
+
const response = await fetchImpl(`${url}/api/v1/workspaces`, {
|
|
76
|
+
signal: AbortSignal.timeout(Math.max(100, Math.min(2000, intervalMs * 2))),
|
|
77
|
+
});
|
|
78
|
+
if (response.ok) {
|
|
79
|
+
log(`[kandev] workflow config: syncing ${url}`);
|
|
80
|
+
let result;
|
|
81
|
+
try {
|
|
82
|
+
result = spawnSyncImpl(process.execPath, [path.join(root, "scripts", "sync.mjs")], {
|
|
83
|
+
stdio: "inherit",
|
|
84
|
+
env: { ...env, KANDEV_URL: url },
|
|
85
|
+
});
|
|
86
|
+
} catch (error) {
|
|
87
|
+
warn(`[kandev] workflow config sync failed: ${error.message}`);
|
|
88
|
+
return { synced: false, reason: "sync-failed", url };
|
|
89
|
+
}
|
|
90
|
+
if (result?.status === 0) return { synced: true, url };
|
|
91
|
+
warn("[kandev] workflow config sync failed; run `kandev-config sync` after Kandev is ready");
|
|
92
|
+
return { synced: false, reason: "sync-failed", url };
|
|
93
|
+
}
|
|
94
|
+
} catch {
|
|
95
|
+
// The server is still starting.
|
|
96
|
+
}
|
|
97
|
+
await sleep(intervalMs, signal);
|
|
98
|
+
}
|
|
99
|
+
warn("[kandev] workflow config auto-sync skipped: server did not become ready");
|
|
100
|
+
return { synced: false, reason: "timeout", url };
|
|
101
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { spawnSync } from "node:child_process";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { fileURLToPath } from "node:url";
|
|
5
|
+
|
|
6
|
+
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
|
|
7
|
+
const COMMANDS = {
|
|
8
|
+
sync: "scripts/sync.mjs",
|
|
9
|
+
verify: "scripts/verify.mjs",
|
|
10
|
+
gate: "scripts/gate.mjs",
|
|
11
|
+
baseline: "scripts/baseline.mjs",
|
|
12
|
+
measure: "scripts/measure-tokens.mjs",
|
|
13
|
+
replan: "scripts/replan-planning.mjs",
|
|
14
|
+
};
|
|
15
|
+
|
|
16
|
+
function usage() {
|
|
17
|
+
console.log(`Usage: kandev-config <command> [options]
|
|
18
|
+
|
|
19
|
+
Commands:
|
|
20
|
+
sync Reconcile the bundled config with the running Kandev instance
|
|
21
|
+
verify Verify the live Kandev bindings, gate, and install
|
|
22
|
+
gate Run the completion gate daemon
|
|
23
|
+
baseline Record the Kandev install fingerprint
|
|
24
|
+
measure Measure token usage from the local Kandev database
|
|
25
|
+
replan Archive a blocked Planning attempt and re-enter the gateway
|
|
26
|
+
|
|
27
|
+
Examples:
|
|
28
|
+
kandev-config sync
|
|
29
|
+
kandev-config sync --dry-run
|
|
30
|
+
kandev-config gate
|
|
31
|
+
kandev-config verify`);
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
const [command, ...args] = process.argv.slice(2);
|
|
35
|
+
if (!command || command === "help" || command === "-h" || command === "--help") {
|
|
36
|
+
usage();
|
|
37
|
+
process.exit(0);
|
|
38
|
+
}
|
|
39
|
+
const script = COMMANDS[command];
|
|
40
|
+
if (!script) {
|
|
41
|
+
console.error(`kandev-config: unknown command "${command}"`);
|
|
42
|
+
usage();
|
|
43
|
+
process.exit(2);
|
|
44
|
+
}
|
|
45
|
+
const result = spawnSync(process.execPath, [path.join(ROOT, script), ...args], {
|
|
46
|
+
stdio: "inherit",
|
|
47
|
+
env: process.env,
|
|
48
|
+
});
|
|
49
|
+
if (result.error) {
|
|
50
|
+
console.error(`kandev-config: ${result.error.message}`);
|
|
51
|
+
process.exit(1);
|
|
52
|
+
}
|
|
53
|
+
process.exit(result.status ?? 1);
|
package/bin/kandev.js
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { spawn } from "node:child_process";
|
|
3
|
+
import { createRequire } from "node:module";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
import { fileURLToPath } from "node:url";
|
|
6
|
+
import { autoSync } from "./kandev-auto-sync.mjs";
|
|
7
|
+
|
|
8
|
+
const require = createRequire(import.meta.url);
|
|
9
|
+
const cli = require.resolve("kandev/bin/cli.js");
|
|
10
|
+
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
|
|
11
|
+
const argv = process.argv.slice(2);
|
|
12
|
+
const env = {
|
|
13
|
+
...process.env,
|
|
14
|
+
KANDEV_TASK_STALL_DETECTION_THRESHOLD:
|
|
15
|
+
process.env.KANDEV_TASK_STALL_DETECTION_THRESHOLD || "10m",
|
|
16
|
+
};
|
|
17
|
+
const controller = new AbortController();
|
|
18
|
+
const child = spawn(process.execPath, [cli, ...argv], {
|
|
19
|
+
stdio: "inherit",
|
|
20
|
+
env,
|
|
21
|
+
});
|
|
22
|
+
|
|
23
|
+
autoSync({ argv, env, root: ROOT, signal: controller.signal }).catch((error) => {
|
|
24
|
+
console.warn(`[kandev] workflow config auto-sync failed: ${error.message}`);
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
child.on("error", (error) => {
|
|
28
|
+
controller.abort();
|
|
29
|
+
console.error(`[kandev] ${error.message}`);
|
|
30
|
+
process.exit(1);
|
|
31
|
+
});
|
|
32
|
+
child.on("exit", (code, signal) => {
|
|
33
|
+
controller.abort();
|
|
34
|
+
process.exit(code ?? (signal ? 1 : 0));
|
|
35
|
+
});
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
{
|
|
2
|
+
"project": "opencodex-cli",
|
|
3
|
+
"match": {
|
|
4
|
+
"repo_names": ["opencodex-cli"],
|
|
5
|
+
"package_names": ["@koreanhole/opencodex"],
|
|
6
|
+
"files": ["package.json", "bun.lock", "bunfig.toml"]
|
|
7
|
+
},
|
|
8
|
+
"image": "kandev-task-opencodex-cli:bookworm",
|
|
9
|
+
"dockerfile": "docker/Dockerfile.opencodex-cli",
|
|
10
|
+
"platform": "linux/arm64",
|
|
11
|
+
"container_prefix": "kandev-task-ocx",
|
|
12
|
+
"env": {
|
|
13
|
+
"BUN_INSTALL_CACHE_DIR": "/root/.bun/install/cache",
|
|
14
|
+
"NPM_CONFIG_CACHE": "/opt/npm-cache"
|
|
15
|
+
},
|
|
16
|
+
"volumes": [
|
|
17
|
+
"kandev-bun-cache:/root/.bun/install/cache"
|
|
18
|
+
],
|
|
19
|
+
"dependencies": {
|
|
20
|
+
"apt": [
|
|
21
|
+
"bash",
|
|
22
|
+
"ca-certificates",
|
|
23
|
+
"curl",
|
|
24
|
+
"git",
|
|
25
|
+
"gnupg",
|
|
26
|
+
"jq",
|
|
27
|
+
"procps",
|
|
28
|
+
"python3",
|
|
29
|
+
"python3-pip",
|
|
30
|
+
"python3-venv",
|
|
31
|
+
"ripgrep",
|
|
32
|
+
"unzip",
|
|
33
|
+
"wget"
|
|
34
|
+
],
|
|
35
|
+
"cli_tools": [
|
|
36
|
+
{ "name": "node", "verify": ["node", "--version"] },
|
|
37
|
+
{ "name": "npm", "verify": ["npm", "--version"] },
|
|
38
|
+
{ "name": "bun", "verify": ["bun", "--version"] },
|
|
39
|
+
{ "name": "git", "verify": ["git", "--version"] },
|
|
40
|
+
{ "name": "rg", "verify": ["rg", "--version"] },
|
|
41
|
+
{ "name": "uv", "verify": ["uv", "--version"] },
|
|
42
|
+
{ "name": "specify", "verify": ["specify", "--help"] },
|
|
43
|
+
{ "name": "codex", "verify": ["codex", "--version"] }
|
|
44
|
+
],
|
|
45
|
+
"npm_global": [
|
|
46
|
+
"bun@1.4.4",
|
|
47
|
+
"@openai/codex@0.164.0"
|
|
48
|
+
],
|
|
49
|
+
"npm_cache": [
|
|
50
|
+
"mcp-server-commands@0.8.2",
|
|
51
|
+
"@koreanhole/requirement-agent@0.1.7",
|
|
52
|
+
"@koreanhole/code-review-agent@0.5.0",
|
|
53
|
+
"@playwright/mcp@0.0.84"
|
|
54
|
+
],
|
|
55
|
+
"uv_tools": [
|
|
56
|
+
"specify-cli==1.2.0"
|
|
57
|
+
],
|
|
58
|
+
"bun": {
|
|
59
|
+
"version": "1.4.4",
|
|
60
|
+
"lockfile": "bun.lock",
|
|
61
|
+
"packages": [
|
|
62
|
+
"@agentclientprotocol/sdk@1.9.0",
|
|
63
|
+
"@bitkyc08/opencodex@2.94.0",
|
|
64
|
+
"@modelcontextprotocol/sdk@^1.32.1",
|
|
65
|
+
"bun@1.4.4",
|
|
66
|
+
"@types/bun@1.4.4",
|
|
67
|
+
"typescript@7.0.2"
|
|
68
|
+
],
|
|
69
|
+
"provision_commands": [
|
|
70
|
+
["bun", "install", "--frozen-lockfile"]
|
|
71
|
+
],
|
|
72
|
+
"verify_commands": [
|
|
73
|
+
["bun", "run", "verify:upstream"],
|
|
74
|
+
["bun", "run", "typecheck"],
|
|
75
|
+
["bun", "test", "tests/repository-surface.test.ts"]
|
|
76
|
+
]
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
}
|