cclaw-cli 0.5.5 → 0.5.6
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/dist/content/examples.js +31 -49
- package/dist/content/stage-schema.js +58 -61
- package/dist/content/templates.js +23 -34
- package/package.json +1 -1
package/dist/content/examples.js
CHANGED
|
@@ -1,69 +1,51 @@
|
|
|
1
1
|
const STAGE_EXAMPLES = {
|
|
2
|
-
brainstorm: `###
|
|
2
|
+
brainstorm: `### Context
|
|
3
3
|
|
|
4
|
-
- **
|
|
5
|
-
- **
|
|
4
|
+
- **Project state:** Monorepo with CI pipeline using custom release scripts. Release checks are scattered across shell scripts with no shared validation logic.
|
|
5
|
+
- **Relevant existing code/patterns:** \`scripts/pre-publish.sh\` does metadata checks. \`src/release/\` has partial validation helpers.
|
|
6
6
|
|
|
7
|
-
###
|
|
7
|
+
### Problem
|
|
8
8
|
|
|
9
|
-
- **
|
|
10
|
-
- **
|
|
9
|
+
- **What we're solving:** release checks are fragile and inconsistent between CI and local runs. Invalid metadata sometimes reaches npm publish.
|
|
10
|
+
- **Success criteria:** invalid release preconditions are caught before publish with explicit operator feedback, in both CI and local workflows.
|
|
11
|
+
- **Constraints:** no new runtime dependencies; must work within existing CI pipeline structure.
|
|
11
12
|
|
|
12
|
-
###
|
|
13
|
+
### Clarifying Questions
|
|
13
14
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
**Q2:** "Do we allow new runtime dependencies for speed, or keep runtime dependency set unchanged?"
|
|
20
|
-
**A2:** "Keep runtime dependencies unchanged."
|
|
21
|
-
|
|
22
|
-
**Decision impact:** implementation should reuse existing tooling and built-in capabilities.
|
|
23
|
-
|
|
24
|
-
### Grounding checkpoint after Round 2
|
|
25
|
-
|
|
26
|
-
- **Fixed:** hard-block behavior, no new runtime dependencies.
|
|
27
|
-
- **Unknown:** rollback command details and status reporting format.
|
|
28
|
-
|
|
29
|
-
### Round 3 forcing questions (trade-offs)
|
|
30
|
-
|
|
31
|
-
**Q3:** "For v1, prioritize rapid delivery or maximum configurability?"
|
|
32
|
-
**A3:** "Rapid delivery."
|
|
33
|
-
|
|
34
|
-
**Decision impact:** choose a minimal deterministic validation surface; defer advanced configuration.
|
|
35
|
-
|
|
36
|
-
### Options comparison
|
|
37
|
-
|
|
38
|
-
| Option | Pros | Cons | Effort | Recommendation |
|
|
39
|
-
| --- | --- | --- | --- | --- |
|
|
40
|
-
| Script-only checks | Lowest implementation cost | Weak reuse and long-term maintainability | Low | Useful fallback, not preferred |
|
|
41
|
-
| Reusable validation module | Reusable across CI and local runs | Slightly higher upfront design effort | Medium | **Recommended** |
|
|
42
|
-
| Full release framework rewrite | Highest long-term flexibility | High risk and delivery delay | High | Not recommended for v1 |
|
|
15
|
+
| # | Question | Answer | Decision impact |
|
|
16
|
+
| --- | --- | --- | --- |
|
|
17
|
+
| 1 | If release metadata is invalid, should we block publishing hard or only warn? | Block hard. | Validation becomes a mandatory gate — no warning-only fallback. |
|
|
18
|
+
| 2 | Should the validation logic live in a reusable module or stay as shell scripts? | Reusable module. | Architecture: shared TypeScript module imported by CI and local tooling, not duplicated shell scripts. |
|
|
19
|
+
| 3 | For v1, prioritize rapid delivery or maximum configurability? | Rapid delivery. | Minimal deterministic validation surface; defer plugin/config system to v2. |
|
|
43
20
|
|
|
44
|
-
###
|
|
21
|
+
### Approaches
|
|
45
22
|
|
|
46
|
-
|
|
23
|
+
| Approach | Architecture | Trade-offs | Recommendation |
|
|
24
|
+
| --- | --- | --- | --- |
|
|
25
|
+
| A: Reusable validation module | Shared TS module with typed validators, imported by CI scripts and local CLI. Existing \`pre-publish.sh\` calls the module. | Medium upfront effort, high reuse. Requires test coverage for the module. | **Recommended** — best balance of reuse and delivery speed. |
|
|
26
|
+
| B: Hardened shell scripts | Keep existing script approach, add stricter checks and error messages. | Lowest effort. Weak reuse, CI/local divergence risk grows over time. | Viable fallback if TS module is blocked. |
|
|
27
|
+
| C: Full release framework | New release orchestrator with plugin system, config files, rollback commands. | Maximum flexibility. High risk, delivery delay, over-engineered for current needs. | Not recommended for v1. |
|
|
47
28
|
|
|
48
|
-
###
|
|
29
|
+
### Selected Direction
|
|
49
30
|
|
|
50
|
-
-
|
|
51
|
-
-
|
|
31
|
+
- **Approach:** A — Reusable validation module
|
|
32
|
+
- **Rationale:** shared TS module gives consistent behavior in CI and local, avoids script duplication, and stays within the no-new-dependency constraint.
|
|
33
|
+
- **Approval:** approved
|
|
52
34
|
|
|
53
|
-
###
|
|
35
|
+
### Design
|
|
54
36
|
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
-
|
|
37
|
+
- **Architecture:** single \`release-validator\` module in \`src/release/\` exporting typed check functions. CI script and local CLI both import and run the same checks.
|
|
38
|
+
- **Key components:** \`validateMetadata()\`, \`validateChangelog()\`, \`validateVersion()\` — each returns a typed result with error details. A \`runAll()\` orchestrator runs checks and exits non-zero on any failure.
|
|
39
|
+
- **Data flow:** package.json + CHANGELOG.md → validator module → structured result → CI/CLI renders human-readable report.
|
|
58
40
|
|
|
59
|
-
###
|
|
41
|
+
### Assumptions and Open Questions
|
|
60
42
|
|
|
61
|
-
-
|
|
62
|
-
-
|
|
43
|
+
- **Assumptions:** CI remains the primary execution path; existing release metadata files remain the source of truth; v1 prioritizes determinism over customization.
|
|
44
|
+
- **Open questions:** What exact rollback sequence for failed publish? Should status output include machine-readable JSON alongside markdown?
|
|
63
45
|
|
|
64
46
|
### Notes for the next stage
|
|
65
47
|
|
|
66
|
-
Carry
|
|
48
|
+
Carry the no-new-dependency constraint and hard-block behavior directly into scope in/out boundaries.`,
|
|
67
49
|
scope: `### Scope contract
|
|
68
50
|
|
|
69
51
|
**Mode selected:** SELECTIVE EXPANSION
|
|
@@ -22,9 +22,9 @@ const BRAINSTORM = {
|
|
|
22
22
|
stage: "brainstorm",
|
|
23
23
|
skillFolder: "brainstorming",
|
|
24
24
|
skillName: "brainstorming",
|
|
25
|
-
skillDescription: "Design-first stage.
|
|
25
|
+
skillDescription: "Design-first stage. Explore context, understand intent through collaborative dialogue, propose distinct approaches, and lock an approved direction before scope/design work.",
|
|
26
26
|
hardGate: "Do NOT invoke implementation skills, write code, scaffold projects, or mutate product behavior until a concrete direction is approved by the user.",
|
|
27
|
-
purpose: "Turn an initial idea into an approved direction through
|
|
27
|
+
purpose: "Turn an initial idea into an approved design direction through natural collaborative dialogue — understanding the problem before proposing solutions.",
|
|
28
28
|
whenToUse: [
|
|
29
29
|
"Starting a new feature or behavior change",
|
|
30
30
|
"Requirements are ambiguous or trade-offs are unclear",
|
|
@@ -36,52 +36,49 @@ const BRAINSTORM = {
|
|
|
36
36
|
"The task is retrospective only (post-ship audit with no new solution choices)"
|
|
37
37
|
],
|
|
38
38
|
checklist: [
|
|
39
|
-
"
|
|
40
|
-
"
|
|
41
|
-
"
|
|
42
|
-
"
|
|
43
|
-
"
|
|
44
|
-
"
|
|
45
|
-
"
|
|
46
|
-
"
|
|
47
|
-
"
|
|
39
|
+
"**Explore project context** — check files, docs, recent commits to understand what already exists.",
|
|
40
|
+
"**Assess scope** — if the request covers multiple independent subsystems, flag it and help decompose before deep-diving. Each sub-project gets its own brainstorm cycle.",
|
|
41
|
+
"**Ask clarifying questions** — one at a time, understand purpose, constraints, and success criteria. Prefer multiple choice when possible. Each question should change what we build, not just gather trivia.",
|
|
42
|
+
"**Propose 2-3 architecturally distinct approaches** — with real trade-offs and your recommendation. Lead with the recommended option and explain why.",
|
|
43
|
+
"**Present design by sections** — scale each section to its complexity. Ask after each section whether it looks right so far. Cover: architecture, key components, data flow.",
|
|
44
|
+
"**Write artifact** to `.cclaw/artifacts/01-brainstorm.md`.",
|
|
45
|
+
"**Self-review** — scan for placeholders/TODOs, check internal consistency, verify scope is focused, resolve any ambiguity.",
|
|
46
|
+
"**User reviews artifact** — ask the user to review the written artifact and explicitly approve or request changes.",
|
|
47
|
+
"**Handoff** — only then complete stage and point to `/cc-next`."
|
|
48
48
|
],
|
|
49
49
|
interactionProtocol: [
|
|
50
|
-
"
|
|
51
|
-
"
|
|
52
|
-
"
|
|
53
|
-
"
|
|
54
|
-
"
|
|
50
|
+
"Explore what exists before asking what to build — check project files first.",
|
|
51
|
+
"Ask exactly one question per turn. Prefer multiple choice. No bundled questions.",
|
|
52
|
+
"Each question should change a concrete design decision. If a question only gathers trivia, skip it.",
|
|
53
|
+
"Present design in sections scaled to their complexity — a few sentences for simple aspects, detailed for nuanced ones. Get approval after each section.",
|
|
54
|
+
"When proposing approaches, lead with your recommendation and explain why.",
|
|
55
55
|
"State explicitly what is being approved when requesting approval.",
|
|
56
|
-
"Run a brief
|
|
56
|
+
"Run a brief self-review (placeholders, contradictions, scope, ambiguity) before presenting the artifact.",
|
|
57
57
|
"**STOP.** Wait for explicit user approval after writing the artifact. Do NOT auto-advance."
|
|
58
58
|
],
|
|
59
59
|
process: [
|
|
60
|
-
"
|
|
61
|
-
"
|
|
62
|
-
"
|
|
63
|
-
"
|
|
64
|
-
"
|
|
65
|
-
"
|
|
66
|
-
"
|
|
67
|
-
"
|
|
60
|
+
"Explore project context: check files, docs, recent activity.",
|
|
61
|
+
"Assess scope: flag if request is too broad, help decompose first.",
|
|
62
|
+
"Ask clarifying questions one at a time — focus on purpose, constraints, success criteria.",
|
|
63
|
+
"Propose 2-3 architecturally distinct approaches with trade-offs and a recommendation.",
|
|
64
|
+
"Present design sections incrementally, get approval after each.",
|
|
65
|
+
"Write approved direction to `.cclaw/artifacts/01-brainstorm.md`.",
|
|
66
|
+
"Self-review: placeholder scan, internal consistency, scope check, ambiguity check.",
|
|
67
|
+
"Request explicit user approval of the artifact.",
|
|
68
68
|
"Handoff to scope only after approval is explicit."
|
|
69
69
|
],
|
|
70
70
|
requiredGates: [
|
|
71
|
-
{ id: "
|
|
72
|
-
{ id: "
|
|
73
|
-
{ id: "
|
|
74
|
-
{ id: "brainstorm_round3_tradeoff_decisions", description: "Round 3 forcing questions locked explicit trade-off priorities and assumptions." },
|
|
75
|
-
{ id: "brainstorm_options_compared", description: "Multiple solution approaches were compared with real trade-offs and a recommendation." },
|
|
71
|
+
{ id: "brainstorm_context_explored", description: "Project context (files, docs, existing patterns) was checked before asking questions." },
|
|
72
|
+
{ id: "brainstorm_idea_understood", description: "Agent and user share the same understanding of the problem, constraints, and success criteria." },
|
|
73
|
+
{ id: "brainstorm_approaches_compared", description: "2-3 architecturally distinct approaches were compared with real trade-offs and a recommendation." },
|
|
76
74
|
{ id: "brainstorm_direction_approved", description: "User approved a concrete direction and what exactly was approved is stated." },
|
|
77
75
|
{ id: "brainstorm_artifact_reviewed", description: "User reviewed the written brainstorm artifact and confirmed readiness." }
|
|
78
76
|
],
|
|
79
77
|
requiredEvidence: [
|
|
80
78
|
"Artifact written to `.cclaw/artifacts/01-brainstorm.md`.",
|
|
81
|
-
"
|
|
82
|
-
"
|
|
83
|
-
"
|
|
84
|
-
"Approaches and recommendation are recorded with explicit trade-offs.",
|
|
79
|
+
"Project context was explored (files, docs, or recent activity referenced).",
|
|
80
|
+
"Clarifying questions and their answers are captured.",
|
|
81
|
+
"2-3 approaches with trade-offs and recommendation are recorded.",
|
|
85
82
|
"Approved direction and approval marker are present.",
|
|
86
83
|
"Assumptions and open questions are captured (or explicitly marked as none)."
|
|
87
84
|
],
|
|
@@ -99,7 +96,7 @@ const BRAINSTORM = {
|
|
|
99
96
|
blockers: [
|
|
100
97
|
"no explicit approval",
|
|
101
98
|
"critical ambiguity unresolved",
|
|
102
|
-
"
|
|
99
|
+
"project context not explored"
|
|
103
100
|
],
|
|
104
101
|
exitCriteria: [
|
|
105
102
|
"approved design direction documented",
|
|
@@ -108,58 +105,58 @@ const BRAINSTORM = {
|
|
|
108
105
|
"artifact reviewed by user"
|
|
109
106
|
],
|
|
110
107
|
antiPatterns: [
|
|
111
|
-
"
|
|
112
|
-
"Asking
|
|
113
|
-
"
|
|
108
|
+
"Asking questions without exploring existing project context first",
|
|
109
|
+
"Asking bundled or purely informational questions that don't change decisions",
|
|
110
|
+
"Proposing cosmetic option variants instead of architecturally distinct approaches",
|
|
114
111
|
"Jumping directly into implementation",
|
|
115
112
|
"Requesting approval without stating what decision is being approved"
|
|
116
113
|
],
|
|
117
114
|
rationalizations: [
|
|
118
|
-
{ claim: "
|
|
119
|
-
{ claim: "Any question is useful context.", reality: "Only
|
|
120
|
-
{ claim: "
|
|
115
|
+
{ claim: "I already know what to build, so exploration is unnecessary.", reality: "Checking files and context catches wrong assumptions that waste hours later." },
|
|
116
|
+
{ claim: "Any question is useful context.", reality: "Only questions whose answers change what we build improve the design." },
|
|
117
|
+
{ claim: "Two options that differ only in tooling count as distinct approaches.", reality: "Distinct means different architecture, not different libraries for the same approach." }
|
|
121
118
|
],
|
|
122
119
|
redFlags: [
|
|
123
|
-
"
|
|
124
|
-
"
|
|
125
|
-
"
|
|
120
|
+
"No project context exploration before questions",
|
|
121
|
+
"Questions that only gather preferences without design impact",
|
|
122
|
+
"Options that are variants of one approach, not distinct alternatives",
|
|
126
123
|
"Approval requested without explicit decision context"
|
|
127
124
|
],
|
|
128
125
|
policyNeedles: [
|
|
129
|
-
"
|
|
130
|
-
"One
|
|
131
|
-
"
|
|
132
|
-
"Multiple approaches with trade-offs",
|
|
126
|
+
"Explore project context",
|
|
127
|
+
"One question at a time",
|
|
128
|
+
"2-3 architecturally distinct approaches",
|
|
133
129
|
"State what is being approved",
|
|
130
|
+
"Self-review before handoff",
|
|
134
131
|
"Do NOT implement, scaffold, or modify behavior"
|
|
135
132
|
],
|
|
136
133
|
artifactFile: "01-brainstorm.md",
|
|
137
134
|
next: "scope",
|
|
138
135
|
cognitivePatterns: [
|
|
139
|
-
{ name: "
|
|
140
|
-
{ name: "
|
|
141
|
-
{ name: "
|
|
142
|
-
{ name: "
|
|
136
|
+
{ name: "Context Before Questions", description: "Understand what exists before asking what to build." },
|
|
137
|
+
{ name: "Depth Matches Complexity", description: "Brief design for simple tasks, thorough exploration for complex ones." },
|
|
138
|
+
{ name: "Diverge Then Commit", description: "Explore multiple architecturally distinct options first, commit only after explicit approval." },
|
|
139
|
+
{ name: "Question Quality Over Quantity", description: "Each question should change what we build, not just gather trivia." }
|
|
143
140
|
],
|
|
144
141
|
reviewSections: [],
|
|
145
142
|
completionStatus: ["DONE", "DONE_WITH_CONCERNS", "BLOCKED"],
|
|
146
143
|
crossStageTrace: {
|
|
147
144
|
readsFrom: [],
|
|
148
145
|
writesTo: [".cclaw/artifacts/01-brainstorm.md"],
|
|
149
|
-
traceabilityRule: "Scope and design decisions must trace back to
|
|
146
|
+
traceabilityRule: "Scope and design decisions must trace back to explored context and approved brainstorm direction."
|
|
150
147
|
},
|
|
151
148
|
artifactValidation: [
|
|
152
|
-
{ section: "
|
|
153
|
-
{ section: "
|
|
154
|
-
{ section: "
|
|
155
|
-
{ section: "
|
|
156
|
-
{ section: "
|
|
157
|
-
{ section: "
|
|
149
|
+
{ section: "Context", required: true, validationRule: "Must reference project state and relevant existing code or patterns." },
|
|
150
|
+
{ section: "Problem", required: true, validationRule: "Must define what we're solving, success criteria, and constraints." },
|
|
151
|
+
{ section: "Clarifying Questions", required: true, validationRule: "Must capture question, answer, and decision impact for each clarifying question." },
|
|
152
|
+
{ section: "Approaches", required: true, validationRule: "Must compare 2-3 architecturally distinct options with real trade-offs and recommendation." },
|
|
153
|
+
{ section: "Selected Direction", required: true, validationRule: "Must include the selected approach, rationale, and explicit approval marker." },
|
|
154
|
+
{ section: "Design", required: true, validationRule: "Must cover architecture, key components, and data flow scaled to complexity." },
|
|
158
155
|
{ section: "Assumptions and Open Questions", required: true, validationRule: "Must capture unresolved assumptions/open questions, or explicitly state none." }
|
|
159
156
|
],
|
|
160
157
|
namedAntiPattern: {
|
|
161
|
-
title: "This Is Too Simple To
|
|
162
|
-
description: "
|
|
158
|
+
title: "This Is Too Simple To Need A Design",
|
|
159
|
+
description: "Every project goes through this process. Simple projects are where unexamined assumptions cause the most wasted work. The design can be short, but you MUST present it and get approval."
|
|
163
160
|
}
|
|
164
161
|
};
|
|
165
162
|
// ---------------------------------------------------------------------------
|
|
@@ -3,46 +3,35 @@ import { orderedStageSchemas } from "./stage-schema.js";
|
|
|
3
3
|
export const ARTIFACT_TEMPLATES = {
|
|
4
4
|
"01-brainstorm.md": `# Brainstorm Artifact
|
|
5
5
|
|
|
6
|
-
##
|
|
7
|
-
- **
|
|
8
|
-
- **
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
- **
|
|
13
|
-
- **
|
|
14
|
-
|
|
15
|
-
##
|
|
16
|
-
|
|
17
|
-
- **What is fixed now:**
|
|
18
|
-
- **What is still unknown:**
|
|
19
|
-
|
|
20
|
-
### Round 2 grounding
|
|
21
|
-
- **What is fixed now:**
|
|
22
|
-
- **What is still unknown:**
|
|
23
|
-
|
|
24
|
-
### Round 3 grounding
|
|
25
|
-
- **What is fixed now:**
|
|
26
|
-
- **What is still unknown:**
|
|
27
|
-
|
|
28
|
-
## Forcing Questions Log
|
|
29
|
-
| Round | Question | User answer | Decision impact |
|
|
6
|
+
## Context
|
|
7
|
+
- **Project state:**
|
|
8
|
+
- **Relevant existing code/patterns:**
|
|
9
|
+
|
|
10
|
+
## Problem
|
|
11
|
+
- **What we're solving:**
|
|
12
|
+
- **Success criteria:**
|
|
13
|
+
- **Constraints:**
|
|
14
|
+
|
|
15
|
+
## Clarifying Questions
|
|
16
|
+
| # | Question | Answer | Decision impact |
|
|
30
17
|
|---|---|---|---|
|
|
31
|
-
|
|
|
32
|
-
| 2 | | | |
|
|
33
|
-
| 3 | | | |
|
|
18
|
+
| 1 | | | |
|
|
34
19
|
|
|
35
|
-
##
|
|
36
|
-
|
|
|
20
|
+
## Approaches
|
|
21
|
+
| Approach | Architecture | Trade-offs | Recommendation |
|
|
37
22
|
|---|---|---|---|
|
|
38
23
|
| A | | | |
|
|
39
24
|
| B | | | |
|
|
40
25
|
|
|
41
|
-
##
|
|
42
|
-
- **
|
|
43
|
-
- **
|
|
44
|
-
- **
|
|
45
|
-
|
|
26
|
+
## Selected Direction
|
|
27
|
+
- **Approach:**
|
|
28
|
+
- **Rationale:**
|
|
29
|
+
- **Approval:** pending
|
|
30
|
+
|
|
31
|
+
## Design
|
|
32
|
+
- **Architecture:**
|
|
33
|
+
- **Key components:**
|
|
34
|
+
- **Data flow:**
|
|
46
35
|
|
|
47
36
|
## Assumptions and Open Questions
|
|
48
37
|
- **Assumptions:**
|