@ancleto/spec 0.6.4 → 0.6.5
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 +1 -1
- package/agents/coder.md +11 -11
- package/agents/documenter.md +27 -27
- package/agents/orchestrator.md +8 -8
- package/agents/reviewer.md +13 -13
- package/agents/spec-writer.md +9 -9
- package/agents/technical-discovery.md +5 -5
- package/agents/technical-seed-writer.md +1 -1
- package/agents/tester.md +9 -9
- package/commands/cleto-apply.md +5 -5
- package/commands/cleto-archive.md +13 -13
- package/commands/cleto-bulk-archive.md +7 -7
- package/commands/cleto-continue.md +5 -5
- package/commands/cleto-explore.md +8 -8
- package/commands/cleto-ff.md +8 -10
- package/commands/cleto-new.md +8 -10
- package/commands/cleto-onboard.md +24 -36
- package/commands/cleto-propose.md +8 -10
- package/commands/cleto-sync.md +5 -5
- package/commands/cleto-verify.md +4 -4
- package/package.json +2 -2
- package/skills/ancleto-apply/SKILL.md +4 -4
- package/skills/ancleto-archive/SKILL.md +9 -9
- package/skills/ancleto-bulk-archive/SKILL.md +7 -7
- package/skills/ancleto-continue/SKILL.md +3 -3
- package/skills/ancleto-explore/SKILL.md +5 -5
- package/skills/ancleto-ff/SKILL.md +2 -2
- package/skills/ancleto-new/SKILL.md +4 -4
- package/skills/ancleto-onboard/SKILL.md +9 -9
- package/skills/ancleto-propose/SKILL.md +2 -2
- package/skills/ancleto-sync-specs/SKILL.md +6 -6
- package/skills/ancleto-upgrade/SKILL.md +9 -11
- package/skills/ancleto-upgrade/references/templates.md +1 -1
- package/skills/ancleto-verify/SKILL.md +4 -4
- package/skills/ancleto-workflow/SKILL.md +2 -2
- package/src/cli/index.js +18 -8
- package/templates/AGENTS.md +4 -4
- package/templates/PRODUCT.md +1 -1
|
@@ -10,7 +10,7 @@ Archive a completed change in the experimental workflow.
|
|
|
10
10
|
|
|
11
11
|
1. **If no change name provided, prompt for selection**
|
|
12
12
|
|
|
13
|
-
Run `
|
|
13
|
+
Run `aspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
|
|
14
14
|
|
|
15
15
|
Show only active changes (not already archived).
|
|
16
16
|
Include the schema used for each change if available.
|
|
@@ -19,7 +19,7 @@ Archive a completed change in the experimental workflow.
|
|
|
19
19
|
|
|
20
20
|
2. **Check artifact completion status**
|
|
21
21
|
|
|
22
|
-
Run `
|
|
22
|
+
Run `aspec status --change "<name>" --json` to check artifact completion.
|
|
23
23
|
|
|
24
24
|
Parse the JSON to understand:
|
|
25
25
|
|
|
@@ -48,11 +48,11 @@ Archive a completed change in the experimental workflow.
|
|
|
48
48
|
|
|
49
49
|
4. **Assess delta spec sync state**
|
|
50
50
|
|
|
51
|
-
Check for delta specs at `
|
|
51
|
+
Check for delta specs at `aspec/changes/<name>/specs/`. If none exist, proceed without sync prompt.
|
|
52
52
|
|
|
53
53
|
**If delta specs exist:**
|
|
54
54
|
|
|
55
|
-
- Compare each delta spec with its corresponding main spec at `
|
|
55
|
+
- Compare each delta spec with its corresponding main spec at `aspec/specs/<capability>/spec.md`
|
|
56
56
|
- Determine what changes would be applied (adds, modifications, removals, renames)
|
|
57
57
|
- Show a combined summary before prompting
|
|
58
58
|
|
|
@@ -68,7 +68,7 @@ Archive a completed change in the experimental workflow.
|
|
|
68
68
|
Create the archive directory if it doesn't exist:
|
|
69
69
|
|
|
70
70
|
```bash
|
|
71
|
-
mkdir -p
|
|
71
|
+
mkdir -p aspec/changes/archive
|
|
72
72
|
```
|
|
73
73
|
|
|
74
74
|
Generate target name using current date: `YYYY-MM-DD-<change-name>`
|
|
@@ -81,13 +81,13 @@ Archive a completed change in the experimental workflow.
|
|
|
81
81
|
**Before moving**, delete scaffold-only files if present — they must not be preserved in the archive:
|
|
82
82
|
|
|
83
83
|
```bash
|
|
84
|
-
rm -f
|
|
84
|
+
rm -f aspec/changes/<name>/context.md
|
|
85
85
|
```
|
|
86
86
|
|
|
87
87
|
Then move:
|
|
88
88
|
|
|
89
89
|
```bash
|
|
90
|
-
mv
|
|
90
|
+
mv aspec/changes/<name> aspec/changes/archive/YYYY-MM-DD-<name>
|
|
91
91
|
```
|
|
92
92
|
|
|
93
93
|
6. **Display summary**
|
|
@@ -107,7 +107,7 @@ Archive a completed change in the experimental workflow.
|
|
|
107
107
|
|
|
108
108
|
**Change:** <change-name>
|
|
109
109
|
**Schema:** <schema-name>
|
|
110
|
-
**Archived to:**
|
|
110
|
+
**Archived to:** aspec/changes/archive/YYYY-MM-DD-<name>/
|
|
111
111
|
**Specs:** ✓ Synced to main specs
|
|
112
112
|
|
|
113
113
|
All artifacts complete. All tasks complete.
|
|
@@ -120,7 +120,7 @@ All artifacts complete. All tasks complete.
|
|
|
120
120
|
|
|
121
121
|
**Change:** <change-name>
|
|
122
122
|
**Schema:** <schema-name>
|
|
123
|
-
**Archived to:**
|
|
123
|
+
**Archived to:** aspec/changes/archive/YYYY-MM-DD-<name>/
|
|
124
124
|
**Specs:** No delta specs
|
|
125
125
|
|
|
126
126
|
All artifacts complete. All tasks complete.
|
|
@@ -133,7 +133,7 @@ All artifacts complete. All tasks complete.
|
|
|
133
133
|
|
|
134
134
|
**Change:** <change-name>
|
|
135
135
|
**Schema:** <schema-name>
|
|
136
|
-
**Archived to:**
|
|
136
|
+
**Archived to:** aspec/changes/archive/YYYY-MM-DD-<name>/
|
|
137
137
|
**Specs:** Sync skipped (user chose to skip)
|
|
138
138
|
|
|
139
139
|
**Warnings:**
|
|
@@ -150,7 +150,7 @@ Review the archive if this was not intentional.
|
|
|
150
150
|
## Archive Failed
|
|
151
151
|
|
|
152
152
|
**Change:** <change-name>
|
|
153
|
-
**Target:**
|
|
153
|
+
**Target:** aspec/changes/archive/YYYY-MM-DD-<name>/
|
|
154
154
|
|
|
155
155
|
Target archive directory already exists.
|
|
156
156
|
|
|
@@ -163,9 +163,9 @@ Target archive directory already exists.
|
|
|
163
163
|
**Guardrails**
|
|
164
164
|
|
|
165
165
|
- Always prompt for change selection if not provided
|
|
166
|
-
- Use artifact graph (
|
|
166
|
+
- Use artifact graph (aspec status --json) for completion checking
|
|
167
167
|
- Don't block archive on warnings - just inform and confirm
|
|
168
|
-
- Preserve .
|
|
168
|
+
- Preserve .aspec.yaml when moving to archive (it moves with the directory)
|
|
169
169
|
- Show clear summary of what happened
|
|
170
170
|
- If sync is requested, use the Skill tool to invoke `ancleto-sync-specs` (agent-driven)
|
|
171
171
|
- If delta specs exist, always run the sync assessment and show the combined summary before prompting
|
|
@@ -12,7 +12,7 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
|
|
|
12
12
|
|
|
13
13
|
1. **Get active changes**
|
|
14
14
|
|
|
15
|
-
Run `
|
|
15
|
+
Run `aspec list --json` to get all active changes.
|
|
16
16
|
|
|
17
17
|
If no active changes exist, inform user and stop.
|
|
18
18
|
|
|
@@ -30,17 +30,17 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
|
|
|
30
30
|
|
|
31
31
|
For each selected change, collect:
|
|
32
32
|
|
|
33
|
-
a. **Artifact status** - Run `
|
|
33
|
+
a. **Artifact status** - Run `aspec status --change "<name>" --json`
|
|
34
34
|
|
|
35
35
|
- Parse `schemaName` and `artifacts` list
|
|
36
36
|
- Note which artifacts are `done` vs other states
|
|
37
37
|
|
|
38
|
-
b. **Task completion** - Read `
|
|
38
|
+
b. **Task completion** - Read `aspec/changes/<name>/tasks.md`
|
|
39
39
|
|
|
40
40
|
- Count `- [ ]` (incomplete) vs `- [x]` (complete)
|
|
41
41
|
- If no tasks file exists, note as "No tasks"
|
|
42
42
|
|
|
43
|
-
c. **Delta specs** - Check `
|
|
43
|
+
c. **Delta specs** - Check `aspec/changes/<name>/specs/` directory
|
|
44
44
|
|
|
45
45
|
- List which capability specs exist
|
|
46
46
|
- For each, extract requirement names (lines matching `### Requirement: <name>`)
|
|
@@ -131,8 +131,8 @@ This skill allows you to batch-archive changes, handling spec conflicts intellig
|
|
|
131
131
|
b. **Perform the archive**:
|
|
132
132
|
|
|
133
133
|
```bash
|
|
134
|
-
mkdir -p
|
|
135
|
-
mv
|
|
134
|
+
mkdir -p aspec/changes/archive
|
|
135
|
+
mv aspec/changes/<name> aspec/changes/archive/YYYY-MM-DD-<name>
|
|
136
136
|
```
|
|
137
137
|
|
|
138
138
|
c. **Track outcome** for each change:
|
|
@@ -250,6 +250,6 @@ No active changes found. Create a new change to get started.
|
|
|
250
250
|
- Show clear per-change status before confirming
|
|
251
251
|
- Use single confirmation for entire batch
|
|
252
252
|
- Track and report all outcomes (success/skip/fail)
|
|
253
|
-
- Preserve .
|
|
253
|
+
- Preserve .aspec.yaml when moving to archive
|
|
254
254
|
- Archive directory target uses current date: YYYY-MM-DD-<name>
|
|
255
255
|
- If archive target exists, fail that change but continue with others
|
|
@@ -10,7 +10,7 @@ Continue working on a change by creating the next artifact.
|
|
|
10
10
|
|
|
11
11
|
1. **If no change name provided, prompt for selection**
|
|
12
12
|
|
|
13
|
-
Run `
|
|
13
|
+
Run `aspec list --json` to get available changes sorted by most recently modified. Then use the **AskUserQuestion tool** to let the user select which change to work on.
|
|
14
14
|
|
|
15
15
|
Present the top 3-4 most recently modified changes as options, showing:
|
|
16
16
|
|
|
@@ -26,7 +26,7 @@ Continue working on a change by creating the next artifact.
|
|
|
26
26
|
2. **Check current status**
|
|
27
27
|
|
|
28
28
|
```bash
|
|
29
|
-
|
|
29
|
+
aspec status --change "<name>" --json
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
Parse the JSON to understand current state. The response includes:
|
|
@@ -41,7 +41,7 @@ Continue working on a change by creating the next artifact.
|
|
|
41
41
|
|
|
42
42
|
Otherwise, read it as background context — it is NOT an artifact and must NOT be included in output files, but its contents inform what you write:
|
|
43
43
|
|
|
44
|
-
- `
|
|
44
|
+
- `aspec/changes/<name>/context.md` — Work Item context (title, description, acceptance criteria)
|
|
45
45
|
|
|
46
46
|
If either file is missing, skip silently.
|
|
47
47
|
|
|
@@ -63,7 +63,7 @@ Continue working on a change by creating the next artifact.
|
|
|
63
63
|
- Pick the FIRST artifact with `status: "ready"` from the status output
|
|
64
64
|
- Get its instructions:
|
|
65
65
|
```bash
|
|
66
|
-
|
|
66
|
+
aspec instructions <artifact-id> --change "<name>" --json
|
|
67
67
|
```
|
|
68
68
|
- Parse the JSON. The key fields are:
|
|
69
69
|
- `context`: Project background (constraints for you - do NOT include in output)
|
|
@@ -91,7 +91,7 @@ Continue working on a change by creating the next artifact.
|
|
|
91
91
|
|
|
92
92
|
5. **After creating an artifact, show progress**
|
|
93
93
|
```bash
|
|
94
|
-
|
|
94
|
+
aspec status --change "<name>"
|
|
95
95
|
```
|
|
96
96
|
|
|
97
97
|
**Output**
|
|
@@ -4,7 +4,7 @@ description: Enter explore mode - think through ideas, investigate problems, cla
|
|
|
4
4
|
|
|
5
5
|
Enter explore mode. Think deeply. Visualize freely. Follow the conversation wherever it goes.
|
|
6
6
|
|
|
7
|
-
**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create
|
|
7
|
+
**IMPORTANT: Explore mode is for thinking, not implementing.** You may read files, search code, and investigate the codebase, but you must NEVER write code or implement features. If the user asks you to implement something, remind them to exit explore mode first and create a change proposal. You MAY create aspec artifacts (proposals, designs, specs) if the user asks—that's capturing thinking, not implementing.
|
|
8
8
|
|
|
9
9
|
**This is a stance, not a workflow.** There are no fixed steps, no required sequence, no mandatory outputs. You're a thinking partner helping the user explore.
|
|
10
10
|
|
|
@@ -81,16 +81,16 @@ Depending on what the user brings, you might:
|
|
|
81
81
|
|
|
82
82
|
---
|
|
83
83
|
|
|
84
|
-
##
|
|
84
|
+
## aspec Awareness
|
|
85
85
|
|
|
86
|
-
You have full context of the
|
|
86
|
+
You have full context of the aspec system. Use it naturally, don't force it.
|
|
87
87
|
|
|
88
88
|
### Check for context
|
|
89
89
|
|
|
90
90
|
At the start, quickly check what exists:
|
|
91
91
|
|
|
92
92
|
```bash
|
|
93
|
-
|
|
93
|
+
aspec list --json
|
|
94
94
|
```
|
|
95
95
|
|
|
96
96
|
This tells you:
|
|
@@ -114,9 +114,9 @@ If the user mentions a change or you detect one is relevant:
|
|
|
114
114
|
|
|
115
115
|
1. **Read existing artifacts for context**
|
|
116
116
|
|
|
117
|
-
- `
|
|
118
|
-
- `
|
|
119
|
-
- `
|
|
117
|
+
- `aspec/changes/<name>/proposal.md`
|
|
118
|
+
- `aspec/changes/<name>/design.md`
|
|
119
|
+
- `aspec/changes/<name>/tasks.md`
|
|
120
120
|
- etc.
|
|
121
121
|
|
|
122
122
|
2. **Reference them naturally in conversation**
|
|
@@ -171,7 +171,7 @@ When things crystallize, you might offer a summary - but it's optional. Sometime
|
|
|
171
171
|
|
|
172
172
|
## Guardrails
|
|
173
173
|
|
|
174
|
-
- **Don't implement** - Never write code or implement features. Creating
|
|
174
|
+
- **Don't implement** - Never write code or implement features. Creating aspec artifacts is fine, writing application code is not.
|
|
175
175
|
- **Don't fake understanding** - If something is unclear, dig deeper
|
|
176
176
|
- **Don't rush** - Discovery is thinking time, not task time
|
|
177
177
|
- **Don't force structure** - Let patterns emerge naturally
|
package/commands/cleto-ff.md
CHANGED
|
@@ -13,7 +13,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
|
|
|
13
13
|
Resolve Work Item context in this order — stop at the first source that yields data:
|
|
14
14
|
|
|
15
15
|
a. **In-session context** — If WI data was already fetched in this session, use it. Proceed to name derivation below.
|
|
16
|
-
b. **`context.md`** — If a change name was provided as argument and `
|
|
16
|
+
b. **`context.md`** — If a change name was provided as argument and `aspec/changes/<name>/context.md` exists, read it and use its content. Proceed to name derivation.
|
|
17
17
|
c. **Ask the user** — Use the **AskUserQuestion tool** to ask for the Work Item reference. Two accepted formats:
|
|
18
18
|
|
|
19
19
|
- **ID + Project** — e.g., ID `12345` and project `MyProject`
|
|
@@ -42,16 +42,14 @@ Fast-forward through artifact creation - generate everything needed to start imp
|
|
|
42
42
|
|
|
43
43
|
2. **Create the change directory**
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
openspec new change "<name>"
|
|
47
|
-
```
|
|
45
|
+
Create the directory `aspec/changes/<name>/` in the repository.
|
|
48
46
|
|
|
49
|
-
This
|
|
47
|
+
This scaffolds the change at `aspec/changes/<name>/`.
|
|
50
48
|
|
|
51
49
|
3. **Get the artifact build order**
|
|
52
50
|
|
|
53
51
|
```bash
|
|
54
|
-
|
|
52
|
+
aspec status --change "<name>" --json
|
|
55
53
|
```
|
|
56
54
|
|
|
57
55
|
Parse the JSON to get:
|
|
@@ -69,7 +67,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
|
|
|
69
67
|
|
|
70
68
|
- Get instructions:
|
|
71
69
|
```bash
|
|
72
|
-
|
|
70
|
+
aspec instructions <artifact-id> --change "<name>" --json
|
|
73
71
|
```
|
|
74
72
|
- The instructions JSON includes:
|
|
75
73
|
- `context`: Project background (constraints for you - do NOT include in output)
|
|
@@ -87,7 +85,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
|
|
|
87
85
|
|
|
88
86
|
b. **Continue until all `applyRequires` artifacts are complete**
|
|
89
87
|
|
|
90
|
-
- After creating each artifact, re-run `
|
|
88
|
+
- After creating each artifact, re-run `aspec status --change "<name>" --json`
|
|
91
89
|
- Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
|
|
92
90
|
- Stop when all `applyRequires` artifacts are done
|
|
93
91
|
|
|
@@ -98,7 +96,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
|
|
|
98
96
|
|
|
99
97
|
5. **Show final status**
|
|
100
98
|
```bash
|
|
101
|
-
|
|
99
|
+
aspec status --change "<name>"
|
|
102
100
|
```
|
|
103
101
|
|
|
104
102
|
**Output**
|
|
@@ -112,7 +110,7 @@ After completing all artifacts, summarize:
|
|
|
112
110
|
|
|
113
111
|
**Artifact Creation Guidelines**
|
|
114
112
|
|
|
115
|
-
- Follow the `instruction` field from `
|
|
113
|
+
- Follow the `instruction` field from `aspec instructions` for each artifact type
|
|
116
114
|
- The schema defines what each artifact should contain - follow it
|
|
117
115
|
- Read dependency artifacts for context before creating new ones
|
|
118
116
|
- Use `template` as the structure for your output file - fill in its sections
|
package/commands/cleto-new.md
CHANGED
|
@@ -13,7 +13,7 @@ Start a new change using the experimental artifact-driven approach.
|
|
|
13
13
|
Resolve Work Item context in this order — stop at the first source that yields data:
|
|
14
14
|
|
|
15
15
|
a. **In-session context** — If WI data was already fetched in this session, use it. Proceed to name derivation below.
|
|
16
|
-
b. **`context.md`** — If a change name was provided as argument and `
|
|
16
|
+
b. **`context.md`** — If a change name was provided as argument and `aspec/changes/<name>/context.md` exists, read it and use its content. Proceed to name derivation.
|
|
17
17
|
c. **Ask the user** — Use the **AskUserQuestion tool** to ask for the Work Item reference. Two accepted formats:
|
|
18
18
|
|
|
19
19
|
- **ID + Project** — e.g., ID `12345` and project `MyProject`
|
|
@@ -45,22 +45,20 @@ Start a new change using the experimental artifact-driven approach.
|
|
|
45
45
|
**Use a different schema only if the user mentions:**
|
|
46
46
|
|
|
47
47
|
- A specific schema name → use `--schema <name>`
|
|
48
|
-
- "show workflows" or "what workflows" → run `
|
|
48
|
+
- "show workflows" or "what workflows" → run `aspec schemas --json` and let them choose
|
|
49
49
|
|
|
50
50
|
**Otherwise**: Omit `--schema` to use the default.
|
|
51
51
|
|
|
52
52
|
3. **Create the change directory**
|
|
53
53
|
|
|
54
|
-
|
|
55
|
-
openspec new change "<name>"
|
|
56
|
-
```
|
|
54
|
+
Create the directory `aspec/changes/<name>/` in the repository.
|
|
57
55
|
|
|
58
|
-
|
|
59
|
-
This
|
|
56
|
+
Record the schema selection in the change metadata only if the user requested a specific workflow.
|
|
57
|
+
This scaffolds the change at `aspec/changes/<name>/` with the selected schema.
|
|
60
58
|
|
|
61
59
|
4. **Persist Work Item context to `context.md`** (only if WI was resolved in step 1)
|
|
62
60
|
|
|
63
|
-
Write WI context to `
|
|
61
|
+
Write WI context to `aspec/changes/<name>/context.md`:
|
|
64
62
|
|
|
65
63
|
```
|
|
66
64
|
# Work Item Context
|
|
@@ -82,7 +80,7 @@ Start a new change using the experimental artifact-driven approach.
|
|
|
82
80
|
5. **Show the artifact status**
|
|
83
81
|
|
|
84
82
|
```bash
|
|
85
|
-
|
|
83
|
+
aspec status --change "<name>"
|
|
86
84
|
```
|
|
87
85
|
|
|
88
86
|
This shows which artifacts need to be created and which are ready (dependencies satisfied).
|
|
@@ -91,7 +89,7 @@ Start a new change using the experimental artifact-driven approach.
|
|
|
91
89
|
The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".
|
|
92
90
|
|
|
93
91
|
```bash
|
|
94
|
-
|
|
92
|
+
aspec instructions <first-artifact-id> --change "<name>"
|
|
95
93
|
```
|
|
96
94
|
|
|
97
95
|
This outputs the template and context for creating the first artifact.
|
|
@@ -1,27 +1,15 @@
|
|
|
1
1
|
---
|
|
2
|
-
description: Guided onboarding - walk through a complete
|
|
2
|
+
description: Guided onboarding - walk through a complete aspec workflow cycle with narration
|
|
3
3
|
---
|
|
4
4
|
|
|
5
|
-
Guide the user through their first complete
|
|
5
|
+
Guide the user through their first complete aspec workflow cycle. This is a teaching experience—you'll do real work in their codebase while explaining each step.
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## Preflight
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
```bash
|
|
14
|
-
# Unix/macOS
|
|
15
|
-
openspec --version 2>&1 || echo "CLI_NOT_INSTALLED"
|
|
16
|
-
# Windows (PowerShell)
|
|
17
|
-
# if (Get-Command openspec -ErrorAction SilentlyContinue) { openspec --version } else { echo "CLI_NOT_INSTALLED" }
|
|
18
|
-
```
|
|
19
|
-
|
|
20
|
-
**If CLI not installed:**
|
|
21
|
-
|
|
22
|
-
> OpenSpec CLI is not installed. Install it first, then come back to `/cleto-onboard`.
|
|
23
|
-
|
|
24
|
-
Stop here if not installed.
|
|
11
|
+
No external binaries are required: the change cycle runs on the aspec skills bundled
|
|
12
|
+
with your agent (`/cleto-*`). Proceed directly.
|
|
25
13
|
|
|
26
14
|
---
|
|
27
15
|
|
|
@@ -30,7 +18,7 @@ Stop here if not installed.
|
|
|
30
18
|
Display:
|
|
31
19
|
|
|
32
20
|
```
|
|
33
|
-
## Welcome to
|
|
21
|
+
## Welcome to aspec!
|
|
34
22
|
|
|
35
23
|
I'll walk you through a complete change cycle—from idea to implementation—using a real task in your codebase. Along the way, you'll learn the workflow by doing it.
|
|
36
24
|
|
|
@@ -110,7 +98,7 @@ Which task interests you? (Pick a number or describe your own)
|
|
|
110
98
|
If the user picks or describes something too large (major feature, multi-day work):
|
|
111
99
|
|
|
112
100
|
```
|
|
113
|
-
That's a valuable task, but it's probably larger than ideal for your first
|
|
101
|
+
That's a valuable task, but it's probably larger than ideal for your first aspec run-through.
|
|
114
102
|
|
|
115
103
|
For learning the workflow, smaller is better—it lets you see the full cycle without getting stuck in implementation details.
|
|
116
104
|
|
|
@@ -165,26 +153,26 @@ Now let's create a change to hold our work.
|
|
|
165
153
|
```
|
|
166
154
|
## Creating a Change
|
|
167
155
|
|
|
168
|
-
A "change" in
|
|
156
|
+
A "change" in aspec is a container for all the thinking and planning around a piece of work. It lives in `aspec/changes/<name>/` and holds your artifacts—proposal, specs, design, tasks.
|
|
169
157
|
|
|
170
158
|
Let me create one for our task.
|
|
171
159
|
```
|
|
172
160
|
|
|
173
|
-
**DO:** Create the change with a derived kebab-case name:
|
|
161
|
+
**DO:** Create the change directory with a derived kebab-case name:
|
|
174
162
|
|
|
175
163
|
```bash
|
|
176
|
-
|
|
164
|
+
mkdir -p aspec/changes/<derived-name>
|
|
177
165
|
```
|
|
178
166
|
|
|
179
167
|
**SHOW:**
|
|
180
168
|
|
|
181
169
|
```
|
|
182
|
-
Created: `
|
|
170
|
+
Created: `aspec/changes/<name>/`
|
|
183
171
|
|
|
184
172
|
The folder structure:
|
|
185
173
|
```
|
|
186
174
|
|
|
187
|
-
|
|
175
|
+
aspec/changes/<name>/
|
|
188
176
|
├── proposal.md ← Why we're doing this (empty, we'll fill it)
|
|
189
177
|
├── design.md ← How we'll build it (empty)
|
|
190
178
|
├── specs/ ← Detailed requirements (empty)
|
|
@@ -247,10 +235,10 @@ Does this capture the intent? I can adjust before we save it.
|
|
|
247
235
|
After approval, save the proposal:
|
|
248
236
|
|
|
249
237
|
```bash
|
|
250
|
-
|
|
238
|
+
aspec instructions proposal --change "<name>" --json
|
|
251
239
|
```
|
|
252
240
|
|
|
253
|
-
Then write the content to `
|
|
241
|
+
Then write the content to `aspec/changes/<name>/proposal.md`.
|
|
254
242
|
|
|
255
243
|
```
|
|
256
244
|
Proposal saved. This is your "why" document—you can always come back and refine it as understanding evolves.
|
|
@@ -276,9 +264,9 @@ For a small task like this, we might only need one spec file.
|
|
|
276
264
|
|
|
277
265
|
```bash
|
|
278
266
|
# Unix/macOS
|
|
279
|
-
mkdir -p
|
|
267
|
+
mkdir -p aspec/changes/<name>/specs/<capability-name>
|
|
280
268
|
# Windows (PowerShell)
|
|
281
|
-
# New-Item -ItemType Directory -Force -Path "
|
|
269
|
+
# New-Item -ItemType Directory -Force -Path "aspec/changes/<name>/specs/<capability-name>"
|
|
282
270
|
```
|
|
283
271
|
|
|
284
272
|
Draft the spec content:
|
|
@@ -305,7 +293,7 @@ Here's the spec:
|
|
|
305
293
|
This format—WHEN/THEN/AND—makes requirements testable. You can literally read them as test cases.
|
|
306
294
|
```
|
|
307
295
|
|
|
308
|
-
Save to `
|
|
296
|
+
Save to `aspec/changes/<name>/specs/<capability>/spec.md`.
|
|
309
297
|
|
|
310
298
|
---
|
|
311
299
|
|
|
@@ -351,7 +339,7 @@ Here's the design:
|
|
|
351
339
|
For a small task, this captures the key decisions without over-engineering.
|
|
352
340
|
```
|
|
353
341
|
|
|
354
|
-
Save to `
|
|
342
|
+
Save to `aspec/changes/<name>/design.md`.
|
|
355
343
|
|
|
356
344
|
---
|
|
357
345
|
|
|
@@ -390,7 +378,7 @@ Each checkbox becomes a unit of work in the apply phase. Ready to implement?
|
|
|
390
378
|
|
|
391
379
|
**PAUSE** - Wait for user to confirm they're ready to implement.
|
|
392
380
|
|
|
393
|
-
Save to `
|
|
381
|
+
Save to `aspec/changes/<name>/tasks.md`.
|
|
394
382
|
|
|
395
383
|
---
|
|
396
384
|
|
|
@@ -436,7 +424,7 @@ The change is implemented! One more step—let's archive it.
|
|
|
436
424
|
```
|
|
437
425
|
## Archiving
|
|
438
426
|
|
|
439
|
-
When a change is complete, we archive it. This moves it from `
|
|
427
|
+
When a change is complete, we archive it. This moves it from `aspec/changes/` to `aspec/changes/archive/YYYY-MM-DD-<name>/`.
|
|
440
428
|
|
|
441
429
|
Archived changes become your project's decision history—you can always find them later to understand why something was built a certain way.
|
|
442
430
|
```
|
|
@@ -444,13 +432,13 @@ Archived changes become your project's decision history—you can always find th
|
|
|
444
432
|
**DO:**
|
|
445
433
|
|
|
446
434
|
```bash
|
|
447
|
-
|
|
435
|
+
aspec archive "<name>"
|
|
448
436
|
```
|
|
449
437
|
|
|
450
438
|
**SHOW:**
|
|
451
439
|
|
|
452
440
|
```
|
|
453
|
-
Archived to: `
|
|
441
|
+
Archived to: `aspec/changes/archive/YYYY-MM-DD-<name>/`
|
|
454
442
|
|
|
455
443
|
The change is now part of your project's history. The code is in your codebase, the decision record is preserved.
|
|
456
444
|
```
|
|
@@ -462,7 +450,7 @@ The change is now part of your project's history. The code is in your codebase,
|
|
|
462
450
|
```
|
|
463
451
|
## Congratulations!
|
|
464
452
|
|
|
465
|
-
You just completed a full
|
|
453
|
+
You just completed a full aspec cycle:
|
|
466
454
|
|
|
467
455
|
1. **Explore** - Thought through the problem
|
|
468
456
|
2. **New** - Created a change container
|
|
@@ -513,7 +501,7 @@ Try `/cleto-propose` on something you actually want to build. You've got the rhy
|
|
|
513
501
|
If the user says they need to stop, want to pause, or seem disengaged:
|
|
514
502
|
|
|
515
503
|
```
|
|
516
|
-
No problem! Your change is saved at `
|
|
504
|
+
No problem! Your change is saved at `aspec/changes/<name>/`.
|
|
517
505
|
|
|
518
506
|
To pick up where we left off later:
|
|
519
507
|
- `/cleto-continue <name>` - Resume artifact creation
|
|
@@ -529,7 +517,7 @@ Exit gracefully without pressure.
|
|
|
529
517
|
If the user says they just want to see the commands or skip the tutorial:
|
|
530
518
|
|
|
531
519
|
```
|
|
532
|
-
##
|
|
520
|
+
## aspec Quick Reference
|
|
533
521
|
|
|
534
522
|
**Core workflow:**
|
|
535
523
|
|
|
@@ -23,7 +23,7 @@ When ready to implement, run /cleto-apply
|
|
|
23
23
|
Resolve Work Item context in this order — stop at the first source that yields data:
|
|
24
24
|
|
|
25
25
|
a. **In-session context** — If WI data was already fetched in this session, use it. Proceed to name derivation below.
|
|
26
|
-
b. **`context.md`** — If a change name was provided as argument and `
|
|
26
|
+
b. **`context.md`** — If a change name was provided as argument and `aspec/changes/<name>/context.md` exists, read it and use its content. Proceed to name derivation.
|
|
27
27
|
c. **Ask the user** — Use the **AskUserQuestion tool** to ask for the Work Item reference. Two accepted formats:
|
|
28
28
|
|
|
29
29
|
- **ID + Project** — e.g., ID `12345` and project `MyProject`
|
|
@@ -52,16 +52,14 @@ When ready to implement, run /cleto-apply
|
|
|
52
52
|
|
|
53
53
|
2. **Create the change directory**
|
|
54
54
|
|
|
55
|
-
|
|
56
|
-
openspec new change "<name>"
|
|
57
|
-
```
|
|
55
|
+
Create the directory `aspec/changes/<name>/` in the repository.
|
|
58
56
|
|
|
59
|
-
This
|
|
57
|
+
This scaffolds the change at `aspec/changes/<name>/` with `.aspec.yaml`.
|
|
60
58
|
|
|
61
59
|
3. **Get the artifact build order**
|
|
62
60
|
|
|
63
61
|
```bash
|
|
64
|
-
|
|
62
|
+
aspec status --change "<name>" --json
|
|
65
63
|
```
|
|
66
64
|
|
|
67
65
|
Parse the JSON to get:
|
|
@@ -79,7 +77,7 @@ When ready to implement, run /cleto-apply
|
|
|
79
77
|
|
|
80
78
|
- Get instructions:
|
|
81
79
|
```bash
|
|
82
|
-
|
|
80
|
+
aspec instructions <artifact-id> --change "<name>" --json
|
|
83
81
|
```
|
|
84
82
|
- The instructions JSON includes:
|
|
85
83
|
- `context`: Project background (constraints for you - do NOT include in output)
|
|
@@ -97,7 +95,7 @@ When ready to implement, run /cleto-apply
|
|
|
97
95
|
|
|
98
96
|
b. **Continue until all `applyRequires` artifacts are complete**
|
|
99
97
|
|
|
100
|
-
- After creating each artifact, re-run `
|
|
98
|
+
- After creating each artifact, re-run `aspec status --change "<name>" --json`
|
|
101
99
|
- Check if every artifact ID in `applyRequires` has `status: "done"` in the artifacts array
|
|
102
100
|
- Stop when all `applyRequires` artifacts are done
|
|
103
101
|
|
|
@@ -108,7 +106,7 @@ When ready to implement, run /cleto-apply
|
|
|
108
106
|
|
|
109
107
|
5. **Show final status**
|
|
110
108
|
```bash
|
|
111
|
-
|
|
109
|
+
aspec status --change "<name>"
|
|
112
110
|
```
|
|
113
111
|
|
|
114
112
|
**Output**
|
|
@@ -122,7 +120,7 @@ After completing all artifacts, summarize:
|
|
|
122
120
|
|
|
123
121
|
**Artifact Creation Guidelines**
|
|
124
122
|
|
|
125
|
-
- Follow the `instruction` field from `
|
|
123
|
+
- Follow the `instruction` field from `aspec instructions` for each artifact type
|
|
126
124
|
- The schema defines what each artifact should contain - follow it
|
|
127
125
|
- Read dependency artifacts for context before creating new ones
|
|
128
126
|
- Use `template` as the structure for your output file - fill in its sections
|
package/commands/cleto-sync.md
CHANGED
|
@@ -12,7 +12,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
|
|
|
12
12
|
|
|
13
13
|
1. **If no change name provided, prompt for selection**
|
|
14
14
|
|
|
15
|
-
Run `
|
|
15
|
+
Run `aspec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
|
|
16
16
|
|
|
17
17
|
Show changes that have delta specs (under `specs/` directory).
|
|
18
18
|
|
|
@@ -20,7 +20,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
|
|
|
20
20
|
|
|
21
21
|
2. **Find delta specs**
|
|
22
22
|
|
|
23
|
-
Look for delta spec files in `
|
|
23
|
+
Look for delta spec files in `aspec/changes/<name>/specs/*/spec.md`.
|
|
24
24
|
|
|
25
25
|
Each delta spec file contains sections like:
|
|
26
26
|
|
|
@@ -33,11 +33,11 @@ This is an **agent-driven** operation - you will read delta specs and directly e
|
|
|
33
33
|
|
|
34
34
|
3. **For each delta spec, apply changes to main specs**
|
|
35
35
|
|
|
36
|
-
For each capability with a delta spec at `
|
|
36
|
+
For each capability with a delta spec at `aspec/changes/<name>/specs/<capability>/spec.md`:
|
|
37
37
|
|
|
38
38
|
a. **Read the delta spec** to understand the intended changes
|
|
39
39
|
|
|
40
|
-
b. **Read the main spec** at `
|
|
40
|
+
b. **Read the main spec** at `aspec/specs/<capability>/spec.md` (may not exist yet)
|
|
41
41
|
|
|
42
42
|
c. **Apply changes intelligently**:
|
|
43
43
|
|
|
@@ -65,7 +65,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
|
|
|
65
65
|
|
|
66
66
|
d. **Create new main spec** if capability doesn't exist yet:
|
|
67
67
|
|
|
68
|
-
- Create `
|
|
68
|
+
- Create `aspec/specs/<capability>/spec.md`
|
|
69
69
|
- Add Purpose section (can be brief, mark as TBD)
|
|
70
70
|
- Add Requirements section with the ADDED requirements
|
|
71
71
|
|