@haaaiawd/skeinn 0.0.0-stage → 2.5.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/CHANGELOG.md +102 -0
- package/CONTRIBUTING.md +37 -0
- package/EVIL_EVAL.md +84 -0
- package/LICENSE +21 -0
- package/README.md +196 -2
- package/README.zh-CN.md +262 -0
- package/SECURITY.md +11 -0
- package/cli/bin/skeinn.js +512 -0
- package/cli/src/protocol.js +862 -0
- package/cli/src/store.js +1992 -0
- package/design.md +257 -0
- package/docs/PROMPT_CATALOG.md +139 -0
- package/docs/RELEASE_CHECKLIST.md +53 -0
- package/docs/UX_FLOW.md +200 -0
- package/docs/ai-development-landscape-2026-10.md +163 -0
- package/docs/brand/skeinn-mark-dark.svg +14 -0
- package/docs/brand/skeinn-mark.svg +14 -0
- package/docs/brand/skeinn-wordmark-dark.svg +11 -0
- package/docs/brand/skeinn-wordmark-light.svg +11 -0
- package/docs/eval/RELAY-001.md +115 -0
- package/docs/loom-eval-loop.drawio +21 -0
- package/docs/loom-eval-loop.svg +56 -0
- package/docs/loom-journey-audit.md +107 -0
- package/docs/loom-production-loop.drawio +41 -0
- package/docs/loom-production-loop.svg +92 -0
- package/package.json +54 -4
|
@@ -0,0 +1,512 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import { readFileSync } from 'node:fs';
|
|
4
|
+
import { dirname, resolve } from 'node:path';
|
|
5
|
+
import { fileURLToPath } from 'node:url';
|
|
6
|
+
import {
|
|
7
|
+
addDeliverable,
|
|
8
|
+
blockTask,
|
|
9
|
+
checkProject,
|
|
10
|
+
checkDeliverableCoverage,
|
|
11
|
+
clarifyStatus,
|
|
12
|
+
closeClarify,
|
|
13
|
+
compileContext,
|
|
14
|
+
completeTask,
|
|
15
|
+
confirmCapability,
|
|
16
|
+
configureRuntime,
|
|
17
|
+
createCapability,
|
|
18
|
+
createDesign,
|
|
19
|
+
exemptCapabilities,
|
|
20
|
+
recordCheckpoint,
|
|
21
|
+
recordDecision,
|
|
22
|
+
resetKeeper,
|
|
23
|
+
resolveFinding,
|
|
24
|
+
getCapability,
|
|
25
|
+
getCapabilityStatus,
|
|
26
|
+
getDesign,
|
|
27
|
+
getCheckpointPrompt,
|
|
28
|
+
getKeeperPrompt,
|
|
29
|
+
getTask,
|
|
30
|
+
importTasks,
|
|
31
|
+
initProject,
|
|
32
|
+
listCapabilities,
|
|
33
|
+
listDeliverables,
|
|
34
|
+
listDesigns,
|
|
35
|
+
loadProject,
|
|
36
|
+
markReady,
|
|
37
|
+
recordKeeper,
|
|
38
|
+
recordUnderstanding,
|
|
39
|
+
reopenTask,
|
|
40
|
+
researchCapability,
|
|
41
|
+
resolveClarify,
|
|
42
|
+
scaffoldEval,
|
|
43
|
+
synthesizeCapability,
|
|
44
|
+
skipKeeper,
|
|
45
|
+
startClarify,
|
|
46
|
+
startTask,
|
|
47
|
+
taskSummary,
|
|
48
|
+
updateTask,
|
|
49
|
+
} from '../src/store.js';
|
|
50
|
+
import { promptCatalog } from '../src/protocol.js';
|
|
51
|
+
|
|
52
|
+
const argv = process.argv.slice(2);
|
|
53
|
+
const [command, subcommand, ...rest] = argv;
|
|
54
|
+
|
|
55
|
+
function output(value) {
|
|
56
|
+
console.log(typeof value === 'string' ? value : JSON.stringify(value, null, 2));
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function fail(message) {
|
|
60
|
+
console.error(`Error: ${message}`);
|
|
61
|
+
process.exitCode = 1;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function option(name) {
|
|
65
|
+
const index = argv.indexOf(name);
|
|
66
|
+
return index === -1 ? undefined : argv[index + 1];
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
function jsonFile() {
|
|
70
|
+
const path = option('--json-file');
|
|
71
|
+
if (!path) throw new Error('This command requires --json-file <path>');
|
|
72
|
+
try {
|
|
73
|
+
return JSON.parse(readFileSync(resolve(path), 'utf8'));
|
|
74
|
+
} catch (error) {
|
|
75
|
+
throw new Error(`Cannot read JSON file ${path}: ${error.message}`);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
function help() {
|
|
80
|
+
return `skeinn — continuity infrastructure for Agents
|
|
81
|
+
|
|
82
|
+
The human talks naturally to the Agent. The Agent uses these commands silently.
|
|
83
|
+
|
|
84
|
+
Typical flow (first pass):
|
|
85
|
+
1. skeinn init — create .skeinn/ skeleton
|
|
86
|
+
2. skeinn record — confirm facts, assumptions, open questions
|
|
87
|
+
3. skeinn design add — one document per consequential decision surface,
|
|
88
|
+
comparing at least two viable alternatives; skipping
|
|
89
|
+
this makes PROJECT.md an unresumable monolith
|
|
90
|
+
4. skeinn capability add — 1–3 single-file bottleneck domain specs (real
|
|
91
|
+
practitioner research + project reflection + Design
|
|
92
|
+
delta); skipping without skeinn capability exempt fails
|
|
93
|
+
ready and produces generic output
|
|
94
|
+
5. skeinn deliverable add — decompose the delivery surface
|
|
95
|
+
6. skeinn task plan — write Tasks with guardrails and acceptance criteria
|
|
96
|
+
7. skeinn project ready — freeze a digest for Keeper review
|
|
97
|
+
8. skeinn keeper prompt → record — fresh Agent runs integrity & anti-laziness audit
|
|
98
|
+
9. skeinn task start → done — execute one Task at a time, fill acceptance evidence
|
|
99
|
+
10. skeinn check — verify health, coverage, stale dependents, and drift
|
|
100
|
+
|
|
101
|
+
Steps 3–6 iterate together: Design surfaces hard decisions; Capability researches how real
|
|
102
|
+
practitioners solve them and feeds operational rules + Design delta back into Design. Run
|
|
103
|
+
\`skeinn help <concept>\` for purpose and quality bar: shaping, design, capability, task, deliverable.
|
|
104
|
+
|
|
105
|
+
When a new idea changes an existing decision:
|
|
106
|
+
skeinn decision --json-file <decision.json> — record what changed and affected tasks
|
|
107
|
+
then update the design document directly; skeinn check warns which done tasks need reopening.
|
|
108
|
+
|
|
109
|
+
When the human changes direction, requests a redesign, or contradicts project truth:
|
|
110
|
+
skeinn clarify start --reason <what changed> — pause work, open an inquiry round
|
|
111
|
+
ask ONE batch of material questions in conversation, then:
|
|
112
|
+
skeinn clarify resolve --json-file <round.json> — record answers/decisions/new questions
|
|
113
|
+
skeinn clarify close — close once every round question is resolved
|
|
114
|
+
or skipped, then cascade the answers into design documents and Tasks.
|
|
115
|
+
|
|
116
|
+
Start and resume
|
|
117
|
+
skeinn init
|
|
118
|
+
skeinn context [--task TASK-001] [--keeper] [--full] [--human-channel available|unavailable]
|
|
119
|
+
(default returns state + Task context; --full restores the complete protocol)
|
|
120
|
+
skeinn check
|
|
121
|
+
skeinn prompts
|
|
122
|
+
|
|
123
|
+
Preserve understanding
|
|
124
|
+
skeinn record --json-file <update.json>
|
|
125
|
+
skeinn decision --json-file <decision.json>
|
|
126
|
+
skeinn project ready
|
|
127
|
+
skeinn design add <slug> --title <text> --kind <product|experience|system|contract|verification|operations|research>
|
|
128
|
+
skeinn design list|get <slug>
|
|
129
|
+
skeinn capability add <slug> --title <professional-field> [--mode external_researched|codebase_grounded|offline_reflection]
|
|
130
|
+
skeinn capability list|get|status <slug>
|
|
131
|
+
skeinn capability confirm <slug> --scenario <text> --source human|agent
|
|
132
|
+
— optional authority upgrade (human_confirmed vs agent_provisional)
|
|
133
|
+
skeinn capability exempt --reason <text>
|
|
134
|
+
— explicit exemption when standard engineering suffices (audited by Keeper)
|
|
135
|
+
|
|
136
|
+
Map the delivery surface
|
|
137
|
+
skeinn deliverable add <slug> --title <text> --kind <module|feature|behavior|interface|artifact|operational|verification|other>
|
|
138
|
+
skeinn deliverable list
|
|
139
|
+
skeinn deliverable coverage
|
|
140
|
+
|
|
141
|
+
Maintain the work map
|
|
142
|
+
skeinn task plan --json-file <tasks.json>
|
|
143
|
+
skeinn task status|next|get <id>
|
|
144
|
+
skeinn task start <id>
|
|
145
|
+
skeinn task update <id> --json-file <patch.json>
|
|
146
|
+
skeinn task block <id> --json-file <block.json>
|
|
147
|
+
skeinn task reopen <id> [--reason <reason>]
|
|
148
|
+
skeinn task done <id> --json-file <evidence.json>
|
|
149
|
+
|
|
150
|
+
Each Task should produce one verifiable unit of real work. Use acceptance[] with criterion,
|
|
151
|
+
verify_by, and evidence fields, plus guardrails[] for key specialist red lines. Task completion
|
|
152
|
+
fills in each acceptance condition's evidence with the actual result (for acceptance tasks) or
|
|
153
|
+
quotes each done_when criterion (for legacy tasks).
|
|
154
|
+
|
|
155
|
+
One-time independent handoff
|
|
156
|
+
skeinn review [--help] — Keeper handoff and stage-review guide
|
|
157
|
+
skeinn keeper --help — read-only guide in any project state
|
|
158
|
+
skeinn keeper prompt
|
|
159
|
+
skeinn keeper record --json-file <result.json>
|
|
160
|
+
skeinn keeper skip --reason <reason>
|
|
161
|
+
|
|
162
|
+
Evaluate Skeinn itself
|
|
163
|
+
skeinn eval scaffold --json-file <scenario.json>
|
|
164
|
+
|
|
165
|
+
Use \`--state-dir <outside-workspace-dir>\` on every command to keep Skeinn state in an isolated sidecar
|
|
166
|
+
(for example, a benchmark runner's per-run state directory). Sidecar initialization never edits AGENTS.md.
|
|
167
|
+
|
|
168
|
+
Use \`skeinn <command> --help\` or \`skeinn help <topic>\` for canonical JSON payloads. Topics:
|
|
169
|
+
record, decision, task-plan, task-update, task-block, task-done, keeper-record, eval-scaffold
|
|
170
|
+
Conceptual guidance topics: shaping, design, capability, task, deliverable, clarify
|
|
171
|
+
|
|
172
|
+
Use JSON files for structured writes so long content and shell quoting remain auditable.
|
|
173
|
+
Task completion JSON includes evidence plus either acceptance_results[] (one per acceptance criterion,
|
|
174
|
+
each with concrete evidence) or checks[] (one per done_when criterion, for legacy tasks).`;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
const STRUCTURED_HELP = {
|
|
178
|
+
record: {
|
|
179
|
+
usage: 'skeinn record --json-file <update.json>',
|
|
180
|
+
example: {
|
|
181
|
+
confirmed: ['A fact confirmed by the human or workspace.'],
|
|
182
|
+
assumptions: [{ text: 'A bounded, reversible Agent assumption.', source: 'agent' }],
|
|
183
|
+
unresolved: [{ question: 'A consequential question still open?', impact: 'high' }],
|
|
184
|
+
resolved: [{ id: 'Q-001', status: 'resolved' }],
|
|
185
|
+
retire_assumptions: ['A-001'],
|
|
186
|
+
decisions: [{ title: 'Decision title', decision: 'Current decision.', rationale: 'Why it follows.', supersedes: [], affects: ['.skeinn/PROJECT.md'] }],
|
|
187
|
+
},
|
|
188
|
+
},
|
|
189
|
+
decision: {
|
|
190
|
+
usage: 'skeinn decision --json-file <decision.json>',
|
|
191
|
+
example: { summary: 'What changed and why.', changes: ['.skeinn/design/system.md', 'src/system.js'], affected_tasks: ['TASK-001'] },
|
|
192
|
+
},
|
|
193
|
+
'task-plan': {
|
|
194
|
+
usage: 'skeinn task plan --json-file <tasks.json>',
|
|
195
|
+
example: { tasks: [{ title: 'Create one verifiable result', outcome: 'A concrete artifact behaves as specified.', acceptance: [{ criterion: 'Observable condition', verify_by: 'Exact command or review method', evidence: '' }], boundaries: ['Does not change unrelated behavior'], guardrails: ['Concrete specialist red line inherited from capability/design'], depends_on: [], reads: ['.skeinn/PROJECT.md', '.skeinn/design/system.md'], touches: ['src/result.js'], implements: '.skeinn/design/system.md#Responsibility', covers: ['DLV-001'] }] },
|
|
196
|
+
},
|
|
197
|
+
'task-update': {
|
|
198
|
+
usage: 'skeinn task update <id> --json-file <patch.json>',
|
|
199
|
+
example: { progress: { completed: ['Finished checkpoint'], current: 'Verifying behavior', next: 'Run the named acceptance check' } },
|
|
200
|
+
},
|
|
201
|
+
'task-block': {
|
|
202
|
+
usage: 'skeinn task block <id> --json-file <block.json>',
|
|
203
|
+
example: { reason: 'A concrete dependency or authority is unavailable.', recovery_conditions: ['Observable condition that permits resuming'], evidence: ['Inspection or command output showing the block'] },
|
|
204
|
+
},
|
|
205
|
+
'task-done': {
|
|
206
|
+
usage: 'skeinn task done <id> --json-file <evidence.json>',
|
|
207
|
+
example: { evidence: ['Overall reproducible verification result'], acceptance_results: [{ criterion: 'Exact acceptance criterion from the Task', evidence: 'Concrete command, artifact, or observation' }] },
|
|
208
|
+
},
|
|
209
|
+
'keeper-record': {
|
|
210
|
+
usage: 'skeinn keeper record --json-file <result.json>',
|
|
211
|
+
example: { run_id: 'fresh-agent-run-001', prepared_digest: '<digest from skeinn project ready>', verdict: 'passed', review: { mode: 'independent', reviewer_id: 'fresh-agent-001', evidence: 'Host opened a separate Agent without the shaping conversation.' }, summary: 'Build-readiness judgment.', gaps: [], evidence: ['Files and observations supporting the verdict'] },
|
|
212
|
+
},
|
|
213
|
+
'eval-scaffold': {
|
|
214
|
+
usage: 'skeinn eval scaffold --json-file <scenario.json>',
|
|
215
|
+
example: { id: 'EVAL-001', title: 'Offline tool 3-baton relay', mode: 'relay', budget_cny: 20, brief: 'Identical brief for both conditions.', pivot: 'Mid-flight requirement change injected at Baton 2.', hidden_user_facts: ['Fact revealed by the same answer script'], hidden_checks: ['Zero external network calls', 'Reload restores state'], human_channel: 'unavailable', success_criteria: ['Fresh Agent finishes Baton 2 and Baton 3 without regressions'], repetitions: 1 },
|
|
216
|
+
},
|
|
217
|
+
'clarify-resolve': {
|
|
218
|
+
usage: 'skeinn clarify resolve --json-file <round.json>',
|
|
219
|
+
example: { answers: [{ id: 'Q-001', resolution: 'User confirmed the new direction' }, { question: 'Inline question', resolution: 'Answer recorded as a confirmed fact' }], confirmed: ['New confirmed fact'], retire_assumptions: ['A-001'], decisions: [{ title: 'Decision title', decision: 'Current decision.', rationale: 'Why it follows.', supersedes: [], affects: ['.skeinn/design/x.md'] }], new_questions: [{ question: 'Still open?', recommendation: 'Your recommended answer', impact: 'high' }] },
|
|
220
|
+
},
|
|
221
|
+
};
|
|
222
|
+
|
|
223
|
+
const CONCEPT_HELP = {
|
|
224
|
+
shaping: `skeinn shaping — the iterative loop that makes a project resumable and strong
|
|
225
|
+
|
|
226
|
+
record → iterate Design & 1–3 bottleneck Capabilities → deliverable → task plan → project ready.
|
|
227
|
+
Design surfaces the hard decisions; Capabilities research how real practitioners solve them and feed
|
|
228
|
+
operational rules + Before -> After Design delta back into Design. No silent Capability skips: add
|
|
229
|
+
1–3 bottleneck domains or explicitly record skeinn capability exempt --reason.
|
|
230
|
+
Per-layer details: skeinn help capability | design | deliverable | task`,
|
|
231
|
+
|
|
232
|
+
design: `skeinn design — one document per consequential decision surface
|
|
233
|
+
|
|
234
|
+
Owns the decisions a fresh Agent must verify independently; skipping it makes PROJECT.md an
|
|
235
|
+
unresumable monolith, and template text fails skeinn project ready. Core design docs (product,
|
|
236
|
+
experience, system, contract) compare at least two genuinely viable alternatives (no strawmen),
|
|
237
|
+
compile applied capability rules into mechanisms, and name how the work could look done yet fail.
|
|
238
|
+
skeinn design add <slug> --title <text> --kind <product|experience|system|contract|verification|operations|research>
|
|
239
|
+
Tasks link to it via implements or a concrete design_exemption.`,
|
|
240
|
+
|
|
241
|
+
capability: `skeinn capability — real practitioner research + project reflection, in one file
|
|
242
|
+
|
|
243
|
+
One single .md file per recognizable field (focus on the 1–3 bottleneck domains that truly raise the
|
|
244
|
+
project's ceiling). Three sections:
|
|
245
|
+
1. How real practitioners operate (verifiable external sources; never agent-authored filler)
|
|
246
|
+
2. Reflection for this project (what fits, what to adapt/refuse, where ordinary AI feels amateur)
|
|
247
|
+
3. Operational rules and Design delta (quality bar, tradeoffs & flip conditions, anti-patterns,
|
|
248
|
+
verification probes, and Before -> After Design delta)
|
|
249
|
+
Commands: skeinn capability add <slug> --title <field> [--mode external_researched|codebase_grounded|offline_reflection]
|
|
250
|
+
Optional authority upgrade: skeinn capability confirm <slug> --scenario <text> --source human|agent
|
|
251
|
+
Explicit skip when standard engineering suffices: skeinn capability exempt --reason <text>`,
|
|
252
|
+
|
|
253
|
+
task: `skeinn task — one verifiable unit of real work
|
|
254
|
+
|
|
255
|
+
Required: outcome + acceptance[criterion/verify_by/evidence] + boundaries + exact reads/touches +
|
|
256
|
+
implements|design_exemption + covers + depends_on. Recommended: guardrails[] (1–3 specialist red
|
|
257
|
+
lines carried forward from capability/design). Canonical payload: skeinn task plan --help.
|
|
258
|
+
Completion needs one acceptance_results entry per criterion; start/done refuse unclassified Tasks
|
|
259
|
+
and missing declared outputs. Use kind: "spike" for pre-Launch empirical prototypes (delivery Tasks
|
|
260
|
+
cannot depend_on a spike; distill findings back into Design/Capability).`,
|
|
261
|
+
|
|
262
|
+
deliverable: `skeinn deliverable — the delivery surface, decomposed
|
|
263
|
+
|
|
264
|
+
One deliverable is one observable thing the project must produce. Tasks claim coverage
|
|
265
|
+
via covers; skeinn deliverable coverage separates planned from delivered.
|
|
266
|
+
Commands: skeinn deliverable add|list|coverage.`,
|
|
267
|
+
|
|
268
|
+
clarify: `skeinn clarify — frontier inquiry for direction changes
|
|
269
|
+
|
|
270
|
+
Open when the human changes direction, requests a redesign, or contradicts project
|
|
271
|
+
truth. Pause material work, ask the current frontier in one batch (each question with
|
|
272
|
+
a recommended answer; look facts up, don't ask them), then skeinn clarify resolve
|
|
273
|
+
records it and skeinn clarify close refuses while any round question stays open.
|
|
274
|
+
Payload: skeinn clarify resolve --help. Small feedback needs no round — fix directly.`,
|
|
275
|
+
};
|
|
276
|
+
|
|
277
|
+
function conceptHelp(topic) {
|
|
278
|
+
const entry = CONCEPT_HELP[topic];
|
|
279
|
+
if (!entry) return null;
|
|
280
|
+
return entry;
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
function structuredHelp(topic) {
|
|
284
|
+
if (['keeper', 'review', 'keeper-prompt'].includes(topic)) return reviewHelp();
|
|
285
|
+
if (topic === 'keeper-record') return `${STRUCTURED_HELP[topic].usage}\n\nCanonical JSON payload:\n${JSON.stringify(STRUCTURED_HELP[topic].example, null, 2)}\n\nFor a revised pass, add closure_results: [{"gap":"<exact prior gap text>","evidence":"<observed closure proof>"}] for every prior gap. Minor gaps require fresh verification too.`;
|
|
286
|
+
const entry = STRUCTURED_HELP[topic];
|
|
287
|
+
if (!entry) {
|
|
288
|
+
const concept = conceptHelp(topic);
|
|
289
|
+
if (concept) return concept;
|
|
290
|
+
throw new Error(`Unknown help topic: ${topic}. Payload topics: ${Object.keys(STRUCTURED_HELP).join(', ')}. Concept topics: ${Object.keys(CONCEPT_HELP).join(', ')}`);
|
|
291
|
+
}
|
|
292
|
+
return `${entry.usage}\n\nCanonical JSON payload:\n${JSON.stringify(entry.example, null, 2)}`;
|
|
293
|
+
}
|
|
294
|
+
|
|
295
|
+
function reviewHelp() {
|
|
296
|
+
return `Skeinn review guide
|
|
297
|
+
|
|
298
|
+
Keeper is the first build-readiness handoff. Stage reviews use ordinary Tasks.
|
|
299
|
+
This guide is read-only and available before initialization or project readiness.
|
|
300
|
+
|
|
301
|
+
Keeper handoff:
|
|
302
|
+
1. The shaping Agent runs skeinn project ready after preparing project truth.
|
|
303
|
+
2. The host opens a fresh Agent without inherited conversation. Give it the workspace
|
|
304
|
+
path, the CLI location (absolute path in source checkouts), and this instruction:
|
|
305
|
+
Run skeinn keeper prompt, then skeinn context --keeper, and inspect the referenced files.
|
|
306
|
+
3. The fresh Agent records its verdict with skeinn keeper record --json-file <result.json>.
|
|
307
|
+
See skeinn keeper record --help for the payload and independent review provenance.
|
|
308
|
+
4. The parent waits for the result, then runs skeinn context. On needs_revision or blocked,
|
|
309
|
+
repair the named sources, prepare again, and obtain a fresh review, including minor gaps.
|
|
310
|
+
5. On passed, resume with skeinn task next and skeinn task start <id>.
|
|
311
|
+
If isolation is unavailable, explicitly record skeinn keeper skip --reason <limitation>.
|
|
312
|
+
The CLI prints instructions and records state; it does not launch Agents itself.
|
|
313
|
+
|
|
314
|
+
Stage review:
|
|
315
|
+
Use skeinn task plan --help to create a review Task naming the implementation, design,
|
|
316
|
+
and verification artifacts in reads. Record each finding as a repair Task with concrete
|
|
317
|
+
acceptance criteria and evidence. Block the review Task with skeinn task block until repairs
|
|
318
|
+
are ready; reopen it and re-run verification before skeinn task done. A completed repair
|
|
319
|
+
alone is not a completed review. No findings: close the review Task with inspection evidence.
|
|
320
|
+
Do not rerun first-time Keeper just to review every implementation Task.`;
|
|
321
|
+
}
|
|
322
|
+
|
|
323
|
+
function activeStructuredHelpTopic() {
|
|
324
|
+
if (command === 'record' || command === 'decision') return command;
|
|
325
|
+
if (command === 'clarify' && subcommand === 'resolve') return 'clarify-resolve';
|
|
326
|
+
if (command === 'task' && ['plan', 'update', 'block', 'done'].includes(subcommand)) return `task-${subcommand}`;
|
|
327
|
+
if (command === 'keeper' && subcommand === 'record') return 'keeper-record';
|
|
328
|
+
if (command === 'eval' && subcommand === 'scaffold') return 'eval-scaffold';
|
|
329
|
+
return '';
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
try {
|
|
333
|
+
configureRuntime({ stateDir: option('--state-dir') });
|
|
334
|
+
const humanChannel = option('--human-channel');
|
|
335
|
+
if (humanChannel && !['available', 'unavailable'].includes(humanChannel)) throw new Error('--human-channel must be available or unavailable');
|
|
336
|
+
switch (command) {
|
|
337
|
+
case '--version':
|
|
338
|
+
case '-v': {
|
|
339
|
+
const here = dirname(fileURLToPath(import.meta.url));
|
|
340
|
+
const pkg = JSON.parse(readFileSync(resolve(here, '..', '..', 'package.json'), 'utf8'));
|
|
341
|
+
output(`skeinn ${pkg.version}`);
|
|
342
|
+
break;
|
|
343
|
+
}
|
|
344
|
+
case '--help':
|
|
345
|
+
case '-h':
|
|
346
|
+
case undefined:
|
|
347
|
+
output(help());
|
|
348
|
+
break;
|
|
349
|
+
case 'help':
|
|
350
|
+
output(subcommand ? structuredHelp(subcommand) : help());
|
|
351
|
+
break;
|
|
352
|
+
case 'init':
|
|
353
|
+
output(initProject());
|
|
354
|
+
break;
|
|
355
|
+
case 'context':
|
|
356
|
+
case 'resume':
|
|
357
|
+
output(compileContext({ taskId: option('--task'), keeper: argv.includes('--keeper'), checkpoint: argv.includes('--checkpoint'), full: argv.includes('--full'), humanChannel: humanChannel || 'available' }));
|
|
358
|
+
break;
|
|
359
|
+
case 'prompts':
|
|
360
|
+
output(promptCatalog());
|
|
361
|
+
break;
|
|
362
|
+
case 'record':
|
|
363
|
+
output(subcommand === '--help' ? structuredHelp('record') : recordUnderstanding(jsonFile()));
|
|
364
|
+
break;
|
|
365
|
+
case 'clarify': {
|
|
366
|
+
if (argv.includes('--help') && subcommand === 'resolve') output(structuredHelp('clarify-resolve'));
|
|
367
|
+
else if (subcommand === '--help' || (argv.includes('--help') && !subcommand)) output(conceptHelp('clarify'));
|
|
368
|
+
else if (subcommand === 'start') output(startClarify({ reason: option('--reason') }));
|
|
369
|
+
else if (subcommand === 'resolve') output(resolveClarify(jsonFile()));
|
|
370
|
+
else if (subcommand === 'close') output(closeClarify());
|
|
371
|
+
else if (!subcommand || subcommand === 'status') output(clarifyStatus());
|
|
372
|
+
else throw new Error('Usage: skeinn clarify start|resolve|close|status');
|
|
373
|
+
break;
|
|
374
|
+
}
|
|
375
|
+
case 'decision':
|
|
376
|
+
output(subcommand === '--help' ? structuredHelp('decision') : recordDecision(jsonFile()));
|
|
377
|
+
break;
|
|
378
|
+
case 'check': {
|
|
379
|
+
const result = checkProject();
|
|
380
|
+
output(result);
|
|
381
|
+
if (!result.healthy) process.exitCode = 1;
|
|
382
|
+
break;
|
|
383
|
+
}
|
|
384
|
+
case 'project':
|
|
385
|
+
if (subcommand !== 'ready') throw new Error('Usage: skeinn project ready [--force-round --reason <text>]');
|
|
386
|
+
output(markReady(undefined, { forceRound: argv.includes('--force-round'), reason: option('--reason') }));
|
|
387
|
+
break;
|
|
388
|
+
case 'design': {
|
|
389
|
+
if (argv.includes('--help')) output(conceptHelp('design'));
|
|
390
|
+
else if (subcommand === 'add') {
|
|
391
|
+
const slug = rest[0];
|
|
392
|
+
const title = option('--title');
|
|
393
|
+
const kind = option('--kind');
|
|
394
|
+
if (!slug) throw new Error('Usage: skeinn design add <slug> --title <text> --kind <kind>');
|
|
395
|
+
output(createDesign(slug, { title, kind }));
|
|
396
|
+
} else if (subcommand === 'list') output(listDesigns());
|
|
397
|
+
else if (subcommand === 'get') {
|
|
398
|
+
if (!rest[0]) throw new Error('Usage: skeinn design get <slug>');
|
|
399
|
+
output(getDesign(rest[0]));
|
|
400
|
+
} else if (!subcommand) output(conceptHelp('design'));
|
|
401
|
+
else throw new Error('Usage: skeinn design add|list|get');
|
|
402
|
+
break;
|
|
403
|
+
}
|
|
404
|
+
case 'capability': {
|
|
405
|
+
if (argv.includes('--help')) output(conceptHelp('capability'));
|
|
406
|
+
else if (subcommand === 'add') {
|
|
407
|
+
const slug = rest[0];
|
|
408
|
+
const title = option('--title');
|
|
409
|
+
const mode = option('--mode');
|
|
410
|
+
if (!slug) throw new Error('Usage: skeinn capability add <slug> --title <text> [--mode external_researched|codebase_grounded|offline_reflection]');
|
|
411
|
+
output(createCapability(slug, { title, mode }));
|
|
412
|
+
} else if (subcommand === 'exempt') {
|
|
413
|
+
output(exemptCapabilities(option('--reason')));
|
|
414
|
+
} else if (subcommand === 'list') output(listCapabilities());
|
|
415
|
+
else if (subcommand === 'get') {
|
|
416
|
+
if (!rest[0]) throw new Error('Usage: skeinn capability get <slug>');
|
|
417
|
+
output(getCapability(rest[0]));
|
|
418
|
+
} else if (subcommand === 'research') {
|
|
419
|
+
if (!rest[0]) throw new Error('Usage: skeinn capability research <slug> --field <text>');
|
|
420
|
+
output(researchCapability(rest[0], { field: option('--field') }));
|
|
421
|
+
} else if (subcommand === 'synthesize') {
|
|
422
|
+
if (!rest[0]) throw new Error('Usage: skeinn capability synthesize <slug>');
|
|
423
|
+
output(synthesizeCapability(rest[0]));
|
|
424
|
+
} else if (subcommand === 'confirm') {
|
|
425
|
+
if (!rest[0]) throw new Error('Usage: skeinn capability confirm <slug> --scenario <text> --source human|agent');
|
|
426
|
+
output(confirmCapability(rest[0], { scenario: option('--scenario'), source: option('--source') }));
|
|
427
|
+
} else if (subcommand === 'status') {
|
|
428
|
+
if (!rest[0]) throw new Error('Usage: skeinn capability status <slug>');
|
|
429
|
+
output(getCapabilityStatus(rest[0]));
|
|
430
|
+
} else if (!subcommand) output(conceptHelp('capability'));
|
|
431
|
+
else throw new Error('Usage: skeinn capability add|exempt|list|get|status|confirm');
|
|
432
|
+
break;
|
|
433
|
+
}
|
|
434
|
+
case 'deliverable': {
|
|
435
|
+
if (argv.includes('--help')) output(conceptHelp('deliverable'));
|
|
436
|
+
else if (subcommand === 'add') {
|
|
437
|
+
const slug = rest[0];
|
|
438
|
+
const title = option('--title');
|
|
439
|
+
const kind = option('--kind');
|
|
440
|
+
if (!slug) throw new Error('Usage: skeinn deliverable add <slug> --title <text> --kind <module|feature|behavior|interface|artifact|operational|verification|other>');
|
|
441
|
+
output(addDeliverable(slug, { title, kind, notes: option('--notes') }));
|
|
442
|
+
} else if (subcommand === 'list') output(listDeliverables());
|
|
443
|
+
else if (subcommand === 'coverage') output(checkDeliverableCoverage());
|
|
444
|
+
else if (!subcommand) output(conceptHelp('deliverable'));
|
|
445
|
+
else throw new Error('Usage: skeinn deliverable add|list|coverage');
|
|
446
|
+
break;
|
|
447
|
+
}
|
|
448
|
+
case 'task': {
|
|
449
|
+
if (argv.includes('--help') && ['plan', 'update', 'block', 'done'].includes(subcommand)) output(structuredHelp(`task-${subcommand}`));
|
|
450
|
+
else if (subcommand === 'plan') output(importTasks(jsonFile()));
|
|
451
|
+
else if (subcommand === 'status') output(taskSummary(loadProject().taskStore.tasks));
|
|
452
|
+
else if (subcommand === 'next') output(getTask());
|
|
453
|
+
else if (subcommand === 'get') {
|
|
454
|
+
if (!rest[0]) throw new Error('Usage: skeinn task get <id>');
|
|
455
|
+
output(getTask(rest[0]));
|
|
456
|
+
} else if (subcommand === 'start') {
|
|
457
|
+
if (!rest[0]) throw new Error('Usage: skeinn task start <id>');
|
|
458
|
+
output(startTask(rest[0]));
|
|
459
|
+
} else if (subcommand === 'update') {
|
|
460
|
+
if (!rest[0]) throw new Error('Usage: skeinn task update <id> --json-file <patch.json>');
|
|
461
|
+
output(updateTask(rest[0], jsonFile()));
|
|
462
|
+
} else if (subcommand === 'block') {
|
|
463
|
+
if (!rest[0]) throw new Error('Usage: skeinn task block <id> --json-file <block.json>');
|
|
464
|
+
output(blockTask(rest[0], jsonFile()));
|
|
465
|
+
} else if (subcommand === 'reopen') {
|
|
466
|
+
if (!rest[0]) throw new Error('Usage: skeinn task reopen <id>');
|
|
467
|
+
output(reopenTask(rest[0], { reason: option('--reason') }));
|
|
468
|
+
} else if (subcommand === 'done') {
|
|
469
|
+
if (!rest[0]) throw new Error('Usage: skeinn task done <id> --json-file <evidence.json>');
|
|
470
|
+
output(completeTask(rest[0], jsonFile()));
|
|
471
|
+
} else if (!subcommand || argv.includes('--help')) output(conceptHelp('task'));
|
|
472
|
+
else throw new Error('Usage: skeinn task plan|status|next|get|start|update|block|reopen|done');
|
|
473
|
+
break;
|
|
474
|
+
}
|
|
475
|
+
case 'review':
|
|
476
|
+
if (subcommand && subcommand !== '--help') throw new Error('Usage: skeinn review [--help]');
|
|
477
|
+
output(reviewHelp());
|
|
478
|
+
break;
|
|
479
|
+
case 'keeper': {
|
|
480
|
+
if (argv.includes('--help') && subcommand === 'record') output(structuredHelp('keeper-record'));
|
|
481
|
+
else if (!subcommand || argv.includes('--help')) output(reviewHelp());
|
|
482
|
+
else if (subcommand === 'prompt') output(getKeeperPrompt());
|
|
483
|
+
else if (subcommand === 'record') output(recordKeeper(jsonFile()));
|
|
484
|
+
else if (subcommand === 'skip') output(skipKeeper(option('--reason')));
|
|
485
|
+
else if (subcommand === 'resolve') {
|
|
486
|
+
if (!rest[0]) throw new Error('Usage: skeinn keeper resolve <FND-ID> --evidence <proof>');
|
|
487
|
+
output(resolveFinding(rest[0], { evidence: option('--evidence') }));
|
|
488
|
+
} else if (subcommand === 'reset') {
|
|
489
|
+
output(resetKeeper(option('--reason')));
|
|
490
|
+
} else if (subcommand === 'checkpoint') {
|
|
491
|
+
const action = rest[0];
|
|
492
|
+
if (action === 'prompt') output(getCheckpointPrompt({ milestone: option('--milestone') }));
|
|
493
|
+
else if (action === 'record') output(recordCheckpoint(jsonFile()));
|
|
494
|
+
else throw new Error('Usage: skeinn keeper checkpoint prompt [--milestone <name>] | record --json-file <result.json>');
|
|
495
|
+
} else throw new Error('Usage: skeinn keeper prompt|record|skip|resolve|reset|checkpoint');
|
|
496
|
+
break;
|
|
497
|
+
}
|
|
498
|
+
case 'eval':
|
|
499
|
+
if (argv.includes('--help') && subcommand === 'scaffold') output(structuredHelp('eval-scaffold'));
|
|
500
|
+
else {
|
|
501
|
+
if (subcommand !== 'scaffold') throw new Error('Usage: skeinn eval scaffold --json-file <scenario.json>');
|
|
502
|
+
output(scaffoldEval(jsonFile()));
|
|
503
|
+
}
|
|
504
|
+
break;
|
|
505
|
+
default:
|
|
506
|
+
throw new Error(`Unknown command: ${command}\n\n${help()}`);
|
|
507
|
+
}
|
|
508
|
+
} catch (error) {
|
|
509
|
+
const topic = activeStructuredHelpTopic();
|
|
510
|
+
const pointer = topic && !argv.includes('--help') ? `\nRun ${STRUCTURED_HELP[topic].usage.replace(/ --json-file .+$/, ' --help').replace(/ <id>/, '')} for a canonical payload.` : '';
|
|
511
|
+
fail(`${error.message}${pointer}`);
|
|
512
|
+
}
|