flow-cc 0.5.8 → 0.6.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.
Files changed (9) hide show
  1. package/CHANGELOG.md +150 -131
  2. package/package.json +40 -40
  3. package/skills/flow-done.md +187 -136
  4. package/skills/flow-go.md +216 -197
  5. package/skills/flow-spec.md +305 -290
  6. package/skills/flow-status.md +104 -95
  7. package/skills/flow-task.md +150 -128
  8. package/skills/flow-triage.md +99 -0
  9. package/templates/session.md.template +9 -0
package/skills/flow-done.md CHANGED
@@ -1,136 +1,187 @@
1
- ---
2
- name: flow:done
3
- description: Session-end documentation — updates STATE.md, ROADMAP.md, lessons.md, generates handoff prompt
4
- user_invocable: true
5
- ---
6
-
7
- # /flow:done — Session End + Handoff
8
-
9
- You are executing the `/flow:done` skill. This finalizes the current session by updating all planning documents and generating a handoff prompt for the next session.
10
-
11
- **This is the most important skill for sustainability.** Without proper session-end docs, the next session starts blind.
12
-
13
- **Skill boundary:** You are inside the `/flow:*` workflow. NEVER invoke, suggest, or reference skills from other workflow systems (`/lisa:*`, `/gsd:*`, `/superpowers:*`, etc.). Only suggest `/flow:*` commands as next steps. Do NOT use the Skill tool to call any non-flow skill.
14
-
15
- ## Steps
16
-
17
- ### 1. Gather Context
18
-
19
- Read these files (in parallel where possible):
20
- - `.planning/STATE.md` — current state
21
- - `.planning/ROADMAP.md` — milestone/phase progress
22
- - `tasks/lessons.md` — active lessons (max 10)
23
- - `CLAUDE.md` — project rules
24
- - Active PRD from `.planning/prds/` (resolve via STATE.md "Active PRD" field, or fall back to legacy `PRD.md` at root)
25
-
26
- Also gather:
27
- - Run `git log --oneline -20` to see commits this session
28
- - Run `git diff --stat` to check for uncommitted changes
29
- - If uncommitted changes exist, warn the user before proceeding
30
-
31
- ### 2. Update STATE.md
32
-
33
- **REPLACE the entire file** (do NOT append). Keep under 80 lines.
34
-
35
- Structure:
36
- ```
37
- # [Project Name] — Project State
38
-
39
- ## Current Position
40
- - **Milestone:** [name] (vX)
41
- - **Phase:** [current phase status]
42
- - **Branch:** [current branch]
43
- - **Active PRD:** [path to active PRD, or "None" if milestone complete]
44
- - **Last Session:** [today's date]
45
-
46
- ## Milestone Progress
47
-
48
- | Phase | Name | Status |
49
- |-------|------|--------|
50
- | 1 | [name] | Complete (date) |
51
- | 2 | [name] | Complete (date) |
52
- | 3 | [name] | In Progress |
53
- | 4 | [name] | Pending |
54
-
55
- ## What Was Built (This Session)
56
- - [Bullet list of what was accomplished]
57
- - [Include file counts, key components, commit SHAs]
58
-
59
- ## Key Decisions
60
- - [Any architectural or design decisions made]
61
-
62
- ## Next Actions
63
- 1. [Specific next step — usually "Run /flow:go for Phase N"]
64
- ```
65
-
66
- ### 3. Update ROADMAP.md
67
-
68
- - Mark completed phases with completion date
69
- - Ensure pending phases have enough detail that the next session can start with a one-line prompt
70
- - **Archive check:** If the current milestone is fully complete:
71
- - If `.planning/` does not exist, skip archiving entirely — there's nothing to archive
72
- - Create `.planning/archive/` if it doesn't already exist (use `mkdir -p` or equivalent)
73
- - Move milestone phase details to `.planning/archive/milestones-vX.md`
74
- - Keep only the summary row in the ROADMAP milestone table
75
- - Archive the milestone's PRD: move `.planning/prds/{slug}.md` to `.planning/archive/PRD-{slug}.md`. If using legacy root `PRD.md`, move it to `.planning/archive/PRD-vX.md` instead.
76
- - Clear STATE.md "Active PRD" field (set to "None")
77
- - Mark the milestone as "Complete" in the ROADMAP table
78
- - **Milestone transition:** Check ROADMAP.md for the NEXT milestone with status "Planned":
79
- - **If a next milestone exists:** Update its status from "Planned" to "Pending — needs `/flow:spec`". Update STATE.md current milestone to point to the new milestone.
80
- - **If no next milestone exists:** No transition needed — all planned milestones are done.
81
-
82
- ### 4. Update lessons.md
83
-
84
- - Review the session for mistakes, corrections, or discovered issues
85
- - Auto-suggest lessons based on errors encountered (if any)
86
- - Ask the user: "Any lessons from this session?" using AskUserQuestion with options:
87
- - "No new lessons"
88
- - "Yes, let me add some" (user types them)
89
- - "Use your suggestions" (if you auto-suggested any)
90
- - Add new lessons as one-liners: `- **[topic]** The rule`
91
- - **Hard cap enforcement (max 10 active):**
92
- - If lessons.md already has 10 items and a new one needs to be added:
93
- 1. Identify the most battle-tested/internalized lesson
94
- 2. Promote it to `CLAUDE.md ## Learned Rules` section
95
- 3. Delete it from lessons.md
96
- 4. Add the new lesson
97
- - If `CLAUDE.md ## Learned Rules` hits 15 items, delete the most obvious/internalized rule to make room
98
-
99
- ### 5. Commit Doc Updates
100
-
101
- - Stage only the planning docs: STATE.md, ROADMAP.md, lessons.md, and any archived files
102
- - Commit with message: `docs: session-end updates — [brief summary]`
103
- - Do NOT push unless the user asks
104
-
105
- ### 6. Generate Handoff Prompt
106
-
107
- Determine the next action and generate a copyable handoff prompt:
108
-
109
- - If next phase exists in PRD:
110
- ```
111
- Phase [N]: [Name] — [short description]. Read STATE.md, ROADMAP.md, and .planning/prds/{slug}.md (US-X).
112
- [One sentence of context]. [One sentence of what NOT to do if relevant].
113
- ```
114
- - If milestone is complete AND a next milestone was transitioned to (from Step 3):
115
- ```
116
- Milestone [name] complete. Next: v[X] [next milestone name]. Run /flow:spec to plan it.
117
- ```
118
- - If milestone is complete AND no next milestone exists:
119
- ```
120
- All milestones complete! Run /flow:milestone to plan what's next, or enjoy the win.
121
- ```
122
-
123
- Print the handoff prompt in a fenced code block so the user can copy it.
124
-
125
- ### 7. Print Summary
126
-
127
- ```
128
- Session complete.
129
- - STATE.md: updated
130
- - ROADMAP.md: [N] phases marked complete
131
- - lessons.md: [N]/10 active, [N] promoted to CLAUDE.md
132
- - Committed: [SHA]
133
-
134
- Handoff prompt:
135
- [the prompt in a code block]
136
- ```
1
+ ---
2
+ name: flow:done
3
+ description: Session-end documentation — updates STATE.md, ROADMAP.md, lessons.md, generates handoff prompt
4
+ user_invocable: true
5
+ ---
6
+
7
+ # /flow:done — Session End + Handoff
8
+
9
+ You are executing the `/flow:done` skill. This finalizes the current session by updating all planning documents and generating a handoff prompt for the next session.
10
+
11
+ **This is the most important skill for sustainability.** Without proper session-end docs, the next session starts blind.
12
+
13
+ **Skill boundary:** You are inside the `/flow:*` workflow. NEVER invoke, suggest, or reference skills from other workflow systems (`/lisa:*`, `/gsd:*`, `/superpowers:*`, etc.). Only suggest `/flow:*` commands as next steps. Do NOT use the Skill tool to call any non-flow skill.
14
+
15
+ ## Steps
16
+
17
+ ### 1. Gather Context
18
+
19
+ Read these files (in parallel where possible):
20
+ - `.planning/STATE.md` — current state
21
+ - `.planning/ROADMAP.md` — milestone/phase progress
22
+ - `tasks/lessons.md` — active lessons (max 10)
23
+ - `CLAUDE.md` — project rules
24
+ - Active PRD from `.planning/prds/` (resolve via STATE.md "Active PRD" field, or fall back to legacy `PRD.md` at root)
25
+ - `.claude/memory/session.md` (if exists) — personal session state
26
+
27
+ Also gather:
28
+ - Run `git log --oneline -20` to see commits this session
29
+ - Run `git diff --stat` to check for uncommitted changes
30
+ - Run `git config user.name` to get developer identity
31
+ - If uncommitted changes exist, warn the user before proceeding
32
+
33
+ ### 2. Update STATE.md (Milestone Boundaries Only)
34
+
35
+ **Determine if a milestone was completed this session** by checking ROADMAP.md progress and commits.
36
+
37
+ **IF milestone completed this session** — REPLACE the entire file (do NOT append). Keep under 80 lines.
38
+
39
+ Structure:
40
+ ```
41
+ # [Project Name] — Project State
42
+
43
+ ## Current Position
44
+ - **Milestone:** [name] (vX)
45
+ - **Phase:** [current phase status]
46
+ - **Branch:** [current branch]
47
+ - **Active PRD:** [path to active PRD, or "None" if milestone complete]
48
+ - **Last Session:** [today's date]
49
+
50
+ ## Milestone Progress
51
+
52
+ | Phase | Name | Status |
53
+ |-------|------|--------|
54
+ | 1 | [name] | Complete (date) |
55
+ | 2 | [name] | Complete (date) |
56
+ | 3 | [name] | In Progress |
57
+ | 4 | [name] | Pending |
58
+
59
+ ## What Was Built (This Session)
60
+ - [Bullet list of what was accomplished]
61
+ - [Include file counts, key components, commit SHAs]
62
+
63
+ ## Key Decisions
64
+ - [Any architectural or design decisions made]
65
+
66
+ ## Next Actions
67
+ 1. [Specific next step — usually "Run /flow:go for Phase N"]
68
+ ```
69
+
70
+ **IF normal session (no milestone completed)** — SKIP STATE.md entirely. Print: "Normal session — STATE.md skipped (milestone boundaries only)."
71
+
72
+ ### 2.5. Write session.md (Every Session)
73
+
74
+ This step ALWAYS runs, regardless of whether a milestone was completed.
75
+
76
+ Create `.claude/memory/` directory if it doesn't exist.
77
+
78
+ Write `.claude/memory/session.md` with the following content:
79
+
80
+ ```
81
+ # Session State
82
+
83
+ **Date:** [today's date]
84
+ **Developer:** [git config user.name result]
85
+ **Branch:** [current git branch]
86
+ **Working On:** [Linear issue ID + description if detectable from branch name, or PRD phase, or "standalone task"]
87
+ **Status:** [what was accomplished this session — bullet list of key items]
88
+ **Next:** [what to pick up next session]
89
+ **Blockers:** [any blockers, or "None"]
90
+ ```
91
+
92
+ ### 3. Update ROADMAP.md (Milestone Boundaries Only)
93
+
94
+ **IF milestone completed this session:**
95
+
96
+ - Mark completed phases with completion date
97
+ - Ensure pending phases have enough detail that the next session can start with a one-line prompt
98
+ - **Archive check:** If the current milestone is fully complete:
99
+ - If `.planning/` does not exist, skip archiving entirely — there's nothing to archive
100
+ - Create `.planning/archive/` if it doesn't already exist (use `mkdir -p` or equivalent)
101
+ - Move milestone phase details to `.planning/archive/milestones-vX.md`
102
+ - Keep only the summary row in the ROADMAP milestone table
103
+ - Archive the milestone's PRD: move `.planning/prds/{slug}.md` to `.planning/archive/PRD-{slug}.md`. If using legacy root `PRD.md`, move it to `.planning/archive/PRD-vX.md` instead.
104
+ - Clear STATE.md "Active PRD" field (set to "None")
105
+ - Mark the milestone as "Complete" in the ROADMAP table
106
+ - **Milestone transition:** Check ROADMAP.md for the NEXT milestone with status "Planned":
107
+ - **If a next milestone exists:** Update its status from "Planned" to "Pending — needs `/flow:spec`". Update STATE.md current milestone to point to the new milestone.
108
+ - **If no next milestone exists:** No transition needed — all planned milestones are done.
109
+
110
+ **IF normal session (no milestone completed)** — SKIP ROADMAP.md entirely. Print: "Normal session — ROADMAP.md skipped (milestone boundaries only)."
111
+
112
+ ### 4. Update lessons.md
113
+
114
+ - Review the session for mistakes, corrections, or discovered issues
115
+ - Auto-suggest lessons based on errors encountered (if any)
116
+ - Ask the user: "Any lessons from this session?" using AskUserQuestion with options:
117
+ - "No new lessons"
118
+ - "Yes, let me add some" (user types them)
119
+ - "Use your suggestions" (if you auto-suggested any)
120
+ - Add new lessons as one-liners: `- **[topic]** The rule`
121
+ - **Hard cap enforcement (max 10 active):**
122
+ - If lessons.md already has 10 items and a new one needs to be added:
123
+ 1. Identify the most battle-tested/internalized lesson
124
+ 2. Promote it to `CLAUDE.md ## Learned Rules` section
125
+ 3. Delete it from lessons.md
126
+ 4. Add the new lesson
127
+ - If `CLAUDE.md ## Learned Rules` hits 15 items, delete the most obvious/internalized rule to make room
128
+
129
+ ### 5. Commit Doc Updates
130
+
131
+ **Normal session (no milestone completed):**
132
+ - Only stage `tasks/lessons.md` if it changed
133
+ - Skip STATE.md and ROADMAP.md (they were not modified)
134
+ - Do NOT stage `.claude/memory/session.md` (it is gitignored)
135
+ - If nothing needs staging (no changes to shared docs), skip the commit. Print: "No shared doc changes to commit."
136
+ - Otherwise commit with message: `docs: session-end updates — [brief summary]`
137
+
138
+ **Milestone boundary session:**
139
+ - Stage STATE.md, ROADMAP.md, lessons.md, and any archived files
140
+ - Do NOT stage `.claude/memory/session.md` (it is gitignored)
141
+ - Commit with message: `docs: session-end updates — [brief summary]`
142
+
143
+ - Do NOT push unless the user asks
144
+
145
+ ### 5.5. Linear Progress Comment
146
+
147
+ - Check if the current branch name contains a Linear issue identifier pattern (e.g., `msig-45` in `feat/msig-45-rate-modeling`)
148
+ - Extract the identifier (the `msig-45` part)
149
+ - If found:
150
+ - Attempt to call `mcp__linear__list_issues` with `query` matching the identifier
151
+ - If Linear MCP is available AND an issue is found: post a progress comment with `mcp__linear__create_comment` summarizing: developer name (from Step 1), what was done, what's next, any blockers
152
+ - If Linear MCP is not available OR no issue found: skip silently (no error, no output)
153
+ - If no identifier in branch name: skip silently
154
+
155
+ ### 6. Generate Handoff Prompt
156
+
157
+ Determine the next action and generate a copyable handoff prompt. Include the developer name in the prompt.
158
+
159
+ - If next phase exists in PRD:
160
+ ```
161
+ [Developer Name] — Phase [N]: [Name] — [short description]. Read STATE.md, ROADMAP.md, and .planning/prds/{slug}.md (US-X).
162
+ [One sentence of context]. [One sentence of what NOT to do if relevant].
163
+ ```
164
+ - If milestone is complete AND a next milestone was transitioned to (from Step 3):
165
+ ```
166
+ [Developer Name] — Milestone [name] complete. Next: v[X] [next milestone name]. Run /flow:spec to plan it.
167
+ ```
168
+ - If milestone is complete AND no next milestone exists:
169
+ ```
170
+ [Developer Name] — All milestones complete! Run /flow:milestone to plan what's next, or enjoy the win.
171
+ ```
172
+
173
+ Print the handoff prompt in a fenced code block so the user can copy it.
174
+
175
+ ### 7. Print Summary
176
+
177
+ ```
178
+ Session complete.
179
+ - STATE.md: [updated | skipped (normal session)]
180
+ - ROADMAP.md: [N phases marked complete | skipped (normal session)]
181
+ - session.md: updated
182
+ - lessons.md: [N]/10 active, [N] promoted to CLAUDE.md
183
+ - Committed: [SHA | nothing to commit]
184
+
185
+ Handoff prompt:
186
+ [the prompt in a code block]
187
+ ```