spec-flow

Name: spec-flow
Author: alexei-led

35stars5forks

How to install spec-flow?

alexei-led/cc-thingz/spec-flow

$npx -y skills add alexei-led/cc-thingz --skill spec-flow

Installs into the current project.

Summary

Lightweight spec loop for controlled task-by-task work.

Files · 1

View on GitHub

SKILL.md

1	# Spec flow
2
3	Lightweight spec loop for controlled task-by-task work.
4
5	Loop: plan one slice → execute one task → checkpoint or close → repeat.
6
7	`specctl` owns state. Do not edit task status or `.spec/SESSION.yaml` by hand.
8
9	## Read first
10
11	- `references/method.md` for artifact shapes, planning rules, task quality, and mini-interview guidance.
12	- `references/specctl-commands.md` for CLI commands.
13
14	## State model
15
16	- `.spec/tasks/TASK-*.md` — executable vertical slices. Required for work.
17	- `.spec/epics/EPIC-*.md` — optional group for multi-task plans.
18	- `.spec/reqs/REQ-*.md` — optional WHY/WHAT context for ambiguous work.
19	- `.spec/SESSION.yaml` — active task, step, base commit.
20	- `.spec/PROGRESS.md` — append-only activity log.
21
22	Task states: `todo`, `in-progress`, `done`.
23
24	## Common flows
25
26	New project:
27
28	```bash
29	scripts/specctl init
30	```
31
32	Then plan the first executable slice. Do not build a full backlog unless the user asks.
33
34	Existing project:
35
36	1. Inspect current code and project instructions.
37	2. Create the smallest task that can be verified.
38	3. Link optional REQ/EPIC context only when it reduces ambiguity.
39
40	Stop and resume:
41
42	```bash
43	scripts/specctl checkpoint --message "<where to resume>"
44	scripts/specctl session handoff
45	```
46
47	Iterate:
48
49	```bash
50	scripts/specctl ready
51	scripts/specctl start TASK-<id>
52	# implement + verify
53	scripts/specctl done TASK-<id> --summary "..." --tests "..."
54	```
55
56	## Modes
57
58	### Orient
59
60	Use when the user asks for status, next task, resume, health, or what to do next.
61
62	```bash
63	scripts/specctl status
64	scripts/specctl ready
65	scripts/specctl session handoff
66	scripts/specctl validate
67	```
68
69	Report active session, next ready task, validation issues, and the smallest next action.
70
71	### Plan
72
73	Use when the user has an idea, requirement, bug, or project gap and wants an executable plan.
74
75	1. Run `scripts/specctl init`.
76	2. Check status/session before changing files.
77	3. Ask 3-5 questions only if the slice is unclear.
78	4. Optionally scan the codebase for relevant files and patterns.
79	5. Draft the smallest useful artifact set:
80	- one clear slice → one `TASK-*`
81	- several slices → one `EPIC-*` plus tasks
82	- unclear WHY/WHAT → one `REQ-*` first
83	6. Show the proposed plan and ask before writing.
84	7. Write with `scripts/specctl new task <slug>` when possible, then edit details.
85	8. Run `scripts/specctl validate` and `scripts/specctl ready`.
86
87	Do not write implementation code in plan files.
88
89	### Execute
90
91	Use when the user wants to work, continue, or implement a task.
92
93	1. Run `scripts/specctl status` and `scripts/specctl session show`.
94	2. If a session exists, ask whether to resume, checkpoint, clear, or stop.
95	3. Select with `scripts/specctl ready` or verify the named task with `scripts/specctl show TASK-<id>`.
96	4. Start with `scripts/specctl start TASK-<id>`.
97	5. Make a short implementation plan; ask before editing.
98	6. Implement only the approved task.
99	7. Run project-appropriate checks from project instructions and changed files.
100	8. Show scoped diff or `scripts/specctl session handoff` before close.
101	9. Close with `scripts/specctl done ...` or checkpoint with `scripts/specctl checkpoint`.
102
103	### Checkpoint or close
104
105	Use when the user stops, switches context, or finishes.
106
107	Checkpoint:
108
109	```bash
110	scripts/specctl checkpoint --message "<where to resume>"
111	```
112
113	Close:
114
115	```bash
116	scripts/specctl done TASK-<id> \
117	--summary "<what changed>" \
118	--tests "<checks passed or not run: reason>" \
119	--files "<changed files or none>" \
120	--commits "<sha or none>"
121	```
122
123	`specctl done` needs `--summary` and `--tests` unless the user explicitly approves `--force`.
124
125	## Guardrails
126
127	- One task is the execution unit.
128	- Checkpoint before stopping or switching.
129	- Keep work inside the approved task.
130	- File follow-up tasks instead of expanding scope.
131	- Verification is adaptive; do not assume every project has `make`.
132	- User approval is required before writing plan files, editing code, forcing state, or clearing another session.
133
134	## Output
135
136	```markdown
137	## Spec flow
138
139	Mode: orient \| plan \| execute \| checkpoint \| close
140	Task: <TASK-id or none>
141	Status: <ready \| in-progress \| checkpointed \| done \| blocked>
142	Evidence: <commands/tests/checks or skipped reason>
143	Next: <one command or action>
144	```
145
146	## Failure handling
147
148	- No `.spec/`: run or offer `scripts/specctl init`.
149	- Acti

People who liked this also viewed

6 picks

Type

spec-flow

35stars5forks

View on GitHub

How to install spec-flow?

alexei-led/cc-thingz/spec-flow

$npx -y skills add alexei-led/cc-thingz --skill spec-flow

Installs into the current project.

Summary

Lightweight spec loop for controlled task-by-task work.

Files · 1

View on GitHub

SKILL.md

1	# Spec flow
2
3	Lightweight spec loop for controlled task-by-task work.
4
5	Loop: plan one slice → execute one task → checkpoint or close → repeat.
6
7	`specctl` owns state. Do not edit task status or `.spec/SESSION.yaml` by hand.
8
9	## Read first
10
11	- `references/method.md` for artifact shapes, planning rules, task quality, and mini-interview guidance.
12	- `references/specctl-commands.md` for CLI commands.
13
14	## State model
15
16	- `.spec/tasks/TASK-*.md` — executable vertical slices. Required for work.
17	- `.spec/epics/EPIC-*.md` — optional group for multi-task plans.
18	- `.spec/reqs/REQ-*.md` — optional WHY/WHAT context for ambiguous work.
19	- `.spec/SESSION.yaml` — active task, step, base commit.
20	- `.spec/PROGRESS.md` — append-only activity log.
21
22	Task states: `todo`, `in-progress`, `done`.
23
24	## Common flows
25
26	New project:
27
28	```bash
29	scripts/specctl init
30	```
31
32	Then plan the first executable slice. Do not build a full backlog unless the user asks.
33
34	Existing project:
35
36	1. Inspect current code and project instructions.
37	2. Create the smallest task that can be verified.
38	3. Link optional REQ/EPIC context only when it reduces ambiguity.
39
40	Stop and resume:
41
42	```bash
43	scripts/specctl checkpoint --message "<where to resume>"
44	scripts/specctl session handoff
45	```
46
47	Iterate:
48
49	```bash
50	scripts/specctl ready
51	scripts/specctl start TASK-<id>
52	# implement + verify
53	scripts/specctl done TASK-<id> --summary "..." --tests "..."
54	```
55
56	## Modes
57
58	### Orient
59
60	Use when the user asks for status, next task, resume, health, or what to do next.
61
62	```bash
63	scripts/specctl status
64	scripts/specctl ready
65	scripts/specctl session handoff
66	scripts/specctl validate
67	```
68
69	Report active session, next ready task, validation issues, and the smallest next action.
70
71	### Plan
72
73	Use when the user has an idea, requirement, bug, or project gap and wants an executable plan.
74
75	1. Run `scripts/specctl init`.
76	2. Check status/session before changing files.
77	3. Ask 3-5 questions only if the slice is unclear.
78	4. Optionally scan the codebase for relevant files and patterns.
79	5. Draft the smallest useful artifact set:
80	- one clear slice → one `TASK-*`
81	- several slices → one `EPIC-*` plus tasks
82	- unclear WHY/WHAT → one `REQ-*` first
83	6. Show the proposed plan and ask before writing.
84	7. Write with `scripts/specctl new task <slug>` when possible, then edit details.
85	8. Run `scripts/specctl validate` and `scripts/specctl ready`.
86
87	Do not write implementation code in plan files.
88
89	### Execute
90
91	Use when the user wants to work, continue, or implement a task.
92
93	1. Run `scripts/specctl status` and `scripts/specctl session show`.
94	2. If a session exists, ask whether to resume, checkpoint, clear, or stop.
95	3. Select with `scripts/specctl ready` or verify the named task with `scripts/specctl show TASK-<id>`.
96	4. Start with `scripts/specctl start TASK-<id>`.
97	5. Make a short implementation plan; ask before editing.
98	6. Implement only the approved task.
99	7. Run project-appropriate checks from project instructions and changed files.
100	8. Show scoped diff or `scripts/specctl session handoff` before close.
101	9. Close with `scripts/specctl done ...` or checkpoint with `scripts/specctl checkpoint`.
102
103	### Checkpoint or close
104
105	Use when the user stops, switches context, or finishes.
106
107	Checkpoint:
108
109	```bash
110	scripts/specctl checkpoint --message "<where to resume>"
111	```
112
113	Close:
114
115	```bash
116	scripts/specctl done TASK-<id> \
117	--summary "<what changed>" \
118	--tests "<checks passed or not run: reason>" \
119	--files "<changed files or none>" \
120	--commits "<sha or none>"
121	```
122
123	`specctl done` needs `--summary` and `--tests` unless the user explicitly approves `--force`.
124
125	## Guardrails
126
127	- One task is the execution unit.
128	- Checkpoint before stopping or switching.
129	- Keep work inside the approved task.
130	- File follow-up tasks instead of expanding scope.
131	- Verification is adaptive; do not assume every project has `make`.
132	- User approval is required before writing plan files, editing code, forcing state, or clearing another session.
133
134	## Output
135
136	```markdown
137	## Spec flow
138
139	Mode: orient \| plan \| execute \| checkpoint \| close
140	Task: <TASK-id or none>
141	Status: <ready \| in-progress \| checkpointed \| done \| blocked>
142	Evidence: <commands/tests/checks or skipped reason>
143	Next: <one command or action>
144	```
145
146	## Failure handling
147
148	- No `.spec/`: run or offer `scripts/specctl init`.
149	- Acti

People who liked this also viewed

6 picks

Type