@erclx/aitk 0.108.0 → 0.109.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/claude/.claude-plugin/plugin.json +1 -1
- package/claude/skills/claude-orchestrate/REQUIREMENT.md +1 -3
- package/claude/skills/claude-orchestrate/SKILL.md +10 -18
- package/claude/skills/claude-pr-review/REQUIREMENT.md +1 -1
- package/claude/skills/claude-pr-review/SKILL.md +6 -6
- package/claude/skills/migration-superseded/REQUIREMENT.md +1 -1
- package/claude/skills/migration-superseded/SKILL.md +1 -1
- package/docs/ai-workflow.md +2 -3
- package/docs/operating-model.md +18 -19
- package/package.json +1 -1
- package/standards/requirements.md +2 -2
- package/standards/tasks.md +4 -3
- package/claude/skills/claude-roadmap/REQUIREMENT.md +0 -41
- package/claude/skills/claude-roadmap/SKILL.md +0 -61
- package/claude/skills/claude-roadmap/references/roadmap.md +0 -62
- package/standards/bundled/roadmap.md +0 -62
|
@@ -45,7 +45,6 @@ The session also records nothing of what it learns. Both other callers of memory
|
|
|
45
45
|
- List a candidate's file set against every track in flight, and serialize when the sets are not disjoint
|
|
46
46
|
- Place every finding a merged pull request produced against the surface that owns it
|
|
47
47
|
- Place what the return leg carries by what it changes, sending an answer that settles a finding onto the pull request and one that corrects this session's model of the world to the task owning that surface, since neither becomes a record by being read
|
|
48
|
-
- Date the roadmap line from that file's last commit, so an old sequence reads as old
|
|
49
48
|
- Keep one planned, non-conflicting task in reserve beyond what is running
|
|
50
49
|
- Refill the queue while a wave is still building, rather than on a merge and a thinning list alone, since neither of those fires across the window planning costs nothing
|
|
51
50
|
- Carry a constraint naming each in-flight track's file set in every plan written from here, stating per set which of the two acts it forbids, since a bare path list leaves a broken citation in place
|
|
@@ -86,8 +85,7 @@ The session also records nothing of what it learns. Both other callers of memory
|
|
|
86
85
|
## Guards
|
|
87
86
|
|
|
88
87
|
- Priority file absent: report the queue and say the order is unrecorded rather than inferring it from the index
|
|
89
|
-
-
|
|
90
|
-
- Roadmap present but never committed: report the date as uncommitted, since a blank reads as a formatting slip
|
|
88
|
+
- Cross-version sequencing asked for: say no surface carries it, rather than asserting an active version the tree does not state
|
|
91
89
|
- This body dropped from a long session approaching a compaction: name the re-invocation and the runbook paths, since the routing lives in the body and a user-invoked skill routes nothing once it is gone
|
|
92
90
|
- Blocker only an operator can clear: record the row as untestable this pass and name the action owed, rather than re-measuring what no session can move
|
|
93
91
|
|
|
@@ -28,7 +28,6 @@ Read the board in parallel, resolving the paths at the main worktree root per Wo
|
|
|
28
28
|
- `.claude/tasks/backlog.md`: what is not being scheduled, when the file exists
|
|
29
29
|
- `.claude/tasks/index.md`: what is queued
|
|
30
30
|
- `.claude/plans/*.md`: features already planned and ready to hand off
|
|
31
|
-
- `.claude/ROADMAP.md`: sequencing rationale, when the file exists
|
|
32
31
|
- open PRs via `gh pr list --json number,title,headRefName,isDraft`
|
|
33
32
|
|
|
34
33
|
Then output the state of play so the human knows what to launch, review, and merge.
|
|
@@ -37,7 +36,7 @@ Then output the state of play so the human knows what to launch, review, and mer
|
|
|
37
36
|
|
|
38
37
|
Row position under `## Needs a plan` is what gets planned next, top first, per `.claude/standards/tasks.md`. `backlog.md` carries what nobody is scheduling and is explicitly unordered, so read it for what exists and never as a queue. Report a backlog count rather than its rows, since listing them puts the length back in front of the reader the cut took it away from.
|
|
39
38
|
|
|
40
|
-
|
|
39
|
+
No surface carries cross-version sequencing, so report none. A row's `Waiting on` cell states why that row sits where it does, and reasoning spanning several rows reaches this session only through whoever remembers it. Say nothing about an active version, since nothing in the tree states one and a version asserted from the board is the unsourced claim this omission exists against.
|
|
41
40
|
|
|
42
41
|
A compaction is a moment this skill cannot detect, so the human asks for each side of it and this skill reads the matching runbook when they do.
|
|
43
42
|
|
|
@@ -56,8 +55,6 @@ That routing lives in this body and this skill is user-invoked, so a session tha
|
|
|
56
55
|
```plaintext
|
|
57
56
|
Orchestrator ready.
|
|
58
57
|
|
|
59
|
-
Roadmap: vX.Y, <the Now row's outcome>, as of <date>.
|
|
60
|
-
|
|
61
58
|
Ready to build (hand each to its own worker):
|
|
62
59
|
|
|
63
60
|
<feature>
|
|
@@ -80,9 +77,7 @@ Next: <the single most useful action>
|
|
|
80
77
|
|
|
81
78
|
Omit any section with nothing in it. Recommend a handoff only for a plan whose file set is disjoint from every track already in flight, per Parallelism below.
|
|
82
79
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
That command returns nothing for a roadmap that exists but has never been committed, which is the state `claude-roadmap` leaves behind when it writes the file and declines to stage it. Write `uncommitted` as the date in that case. A blank there would read as a formatting slip rather than as the newest possible sequence.
|
|
80
|
+
The block opens on the board rather than on a version, because no committed file states one. Adding a version line here would restate what a reader can already see on the rows, dated by nothing, which is how the retired sequencing surface produced an unsourced claim on every run.
|
|
86
81
|
|
|
87
82
|
### Every later turn
|
|
88
83
|
|
|
@@ -103,18 +98,15 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
|
|
|
103
98
|
|
|
104
99
|
## The loop
|
|
105
100
|
|
|
106
|
-
1.
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
4. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
|
|
112
|
-
5. Hand off. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The orchestrator does not spawn workers.
|
|
113
|
-
6. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
|
|
101
|
+
1. Plan the next feature. Run `claude-feature` here, with the cross-feature context, to write a plan to `.claude/plans/`. Planning stays in this warm session so the plan front-loads reasoning a cold worker would otherwise re-derive. Every plan written from here also carries a constraint per track in flight, which the paragraph below this list states.
|
|
102
|
+
2. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
|
|
103
|
+
3. Verify the plan against the tree. Reading it is not enough, since a plan goes stale from whatever merged after it was written. Grep for each construct it names and count the sites against the count it claims. Check that every phase label it cites is still open. Open each file it describes rather than trusting its account of the contents. Correct the plan before handing it over.
|
|
104
|
+
4. Hand off. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The orchestrator does not spawn workers.
|
|
105
|
+
5. Review the PR. When a worker opens a PR, run `claude-pr-review` to post findings to it. This is the deep, independent pass. The worker's autoship self-review was only the green gate.
|
|
114
106
|
- Learning that a PR moved is the mechanical half, so read `${CLAUDE_SKILL_DIR}/references/orchestrator-poll.md` and start the poll it carries on the first dispatch rather than checking the board by hand. That runbook holds the routing, and a summary of it here is a second source that drifts from it.
|
|
115
|
-
|
|
107
|
+
6. Dispatch the handback. A pass posting a finding at any severity tells the session holding that branch to run `claude-address-review`, rather than waiting for a person to relay it. Re-review when the answer lands, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
|
|
116
108
|
- Read the threshold off `claude-pr-review`, which states it once and governs the heading with it, so an open heading and an owed dispatch answer the same question and either one is enough to send
|
|
117
|
-
- Resolve the target at the moment of sending with `aitk sessions list --branch`, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour. The runbook read at step
|
|
109
|
+
- Resolve the target at the moment of sending with `aitk sessions list --branch`, never from a mapping written down earlier, since names rotate as sessions end and one recorded earlier in a session has failed inside the hour. The runbook read at step 5 routes on the count and the confidence it answers with
|
|
118
110
|
- Open the message with the worktree and branch the sender believes the reader holds, asking to be corrected, whenever that mapping is inferred rather than confirmed
|
|
119
111
|
- Name the skill for the reader to run rather than writing an invocation, which arrives as text
|
|
120
112
|
- Read the pull request's own draft flag rather than the state a worker reports, since two reported a draft that read ready inside ninety seconds
|
|
@@ -134,7 +126,7 @@ Stamp the block with the commit this session read the tree at, which the same se
|
|
|
134
126
|
- Run one orchestrator at a time. The board is gitignored, so a second session sees none of this one's writes: two task files land minutes apart under different labels for the same work, one session archives a task mid-sweep in the other, and each archives a plan the other had retargeted. An Owner column does not fix this, since neither session can read the other's rows.
|
|
135
127
|
- Do not implement features in this session. Hand the plan to a worker.
|
|
136
128
|
- Do not merge. Recommend merge or changes. The human merges.
|
|
137
|
-
- Do not spawn worker sessions with agents. The human launches each worktree so every build is an independent, steerable stream with its own PR. The handback dispatch in step
|
|
129
|
+
- Do not spawn worker sessions with agents. The human launches each worktree so every build is an independent, steerable stream with its own PR. The handback dispatch in step 6 reaches a session the human already launched, so it leaves this boundary where it is.
|
|
138
130
|
- Do not edit tracked files from this session, at any size. The boundary offers no proportionality exception and nothing enforces it.
|
|
139
131
|
- Do not hand a worker anything but a plan, since scope lives there. A plan carries exact diffs only when they are already known, otherwise it states the scope and the open questions and lets the worker write the diff.
|
|
140
132
|
|
|
@@ -7,7 +7,7 @@ description: What the independent pull request review is for, the gaps it closes
|
|
|
7
7
|
|
|
8
8
|
## Gap
|
|
9
9
|
|
|
10
|
-
Without this skill, a pull request is reviewed only by the session that wrote it, which cannot see the
|
|
10
|
+
Without this skill, a pull request is reviewed only by the session that wrote it, which cannot see the board's order or a sibling branch in flight. Findings land in chat, where they are read once and leave the thread with no record. A review that opens and never closes is worse than none, since a reader scanning the thread cannot tell an unanswered review from a confirmed one, and the author's claim that findings are fixed is the only evidence they are.
|
|
11
11
|
|
|
12
12
|
A finding also stops being true by argument rather than by a fix. A worker naming the plan question that already declined it, or a constraint the pass could not see, settles it in the exchange that carried the answer, and the pass that accepts the argument drops the finding from its next body. A reader then sees a finding raised once and never mentioned again, which is indistinguishable from one everyone forgot.
|
|
13
13
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: claude-pr-review
|
|
3
|
-
description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass against the whole change and every later pass against only the commits added since, under `## Review` while any finding is open and `## Review closed` once a pass carries none. Reads project docs and the
|
|
3
|
+
description: Reviews an open pull request from an independent session and posts findings as a review comment on the PR. Posts a first pass against the whole change and every later pass against only the commits added since, under `## Review` while any finding is open and `## Review closed` once a pass carries none. Reads project docs and the task board for cross-feature context a self-review lacks. Use when asked to "review the PR", "review this feature's PR", "post a PR review", "re-review the PR", "close out the review", "confirm the findings are fixed", or acting as the orchestrator reviewing a worker's PR. Do NOT use to review local uncommitted changes. That is `claude-review`.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Claude PR review
|
|
@@ -32,7 +32,7 @@ Read these in parallel from the project root, skipping any that do not exist:
|
|
|
32
32
|
- `CLAUDE.md`: project type, conventions, and commands
|
|
33
33
|
- `.claude/REQUIREMENTS.md`: feature scope and non-goals
|
|
34
34
|
- `.claude/ARCHITECTURE.md`: technical design decisions
|
|
35
|
-
- `.claude/
|
|
35
|
+
- `.claude/tasks/priority.md`: where this feature sits on the board and what each neighboring row waits on. Resolve this one at the main worktree root per Worktrees in `CLAUDE.md`, since the board is gitignored and a linked worktree holds no copy of it
|
|
36
36
|
- `.claude/plans/feature-<slug>.md` for the branch, when present: the intent the PR should satisfy
|
|
37
37
|
|
|
38
38
|
Coding standards from `.claude/rules/` are auto-loaded by Claude Code.
|
|
@@ -79,7 +79,7 @@ Read each changed file in scope. Skip deleted files. Run reads in parallel.
|
|
|
79
79
|
|
|
80
80
|
Review the diff and files for the same axes as `claude-review` (bugs, edge cases, error handling, logic flaws, security, rule violations), then add the three lenses a self-review structurally cannot apply:
|
|
81
81
|
|
|
82
|
-
- Integration: does this fit the
|
|
82
|
+
- Integration: does this fit the board's order, the shared wiring seam, and any sibling PR in flight?
|
|
83
83
|
- Contract: does a contract downstream features depend on land correctly, and should the plan itself be questioned?
|
|
84
84
|
- Consumers: when the change touches a resource with more than one consumer, enumerate them and check the rule against each. A rule written for the consumer the change targets can be wrong for a sibling that writes.
|
|
85
85
|
|
|
@@ -116,7 +116,7 @@ The comment is a rendered-for-human GitHub surface, so load the `write-human` sk
|
|
|
116
116
|
```markdown
|
|
117
117
|
## Review
|
|
118
118
|
|
|
119
|
-
X critical, Y should-fix, Z minor. Reviewed against project docs and
|
|
119
|
+
X critical, Y should-fix, Z minor. Reviewed against project docs and the board.
|
|
120
120
|
|
|
121
121
|
**`path/to/file.ext`**
|
|
122
122
|
|
|
@@ -172,14 +172,14 @@ Before posting, run the scan in `.claude/standards/publish.md` against the body,
|
|
|
172
172
|
gh pr review <number> --comment --body-file .claude/.tmp/pr-review/body-<number>-<short-sha>.md
|
|
173
173
|
```
|
|
174
174
|
|
|
175
|
-
A pass carrying nothing at all takes `## Review closed` and a short body, with the footer line included either way. On a first pass, post `✅ No findings. Reviewed against project docs and
|
|
175
|
+
A pass carrying nothing at all takes `## Review closed` and a short body, with the footer line included either way. On a first pass, post `✅ No findings. Reviewed against project docs and the board.` On a later pass, post `✅ Prior findings addressed. Re-reviewed <short-sha>, N commits since the prior pass.`
|
|
176
176
|
|
|
177
177
|
A pass carrying only minors is an ordinary finding-carrying pass, so it takes the open heading and the full shape rather than either short line, since the minors have to be readable and neither line reports them. Keep whichever scope sentence the pass owes on the summary line:
|
|
178
178
|
|
|
179
179
|
```markdown
|
|
180
180
|
## Review
|
|
181
181
|
|
|
182
|
-
0 critical, 0 should-fix, Z minor. Reviewed against project docs and
|
|
182
|
+
0 critical, 0 should-fix, Z minor. Reviewed against project docs and the board.
|
|
183
183
|
|
|
184
184
|
**`path/to/file.ext`**
|
|
185
185
|
|
|
@@ -11,7 +11,7 @@ Without this skill, a target holding a retired `.claude/` file is told what repl
|
|
|
11
11
|
|
|
12
12
|
A second failure comes from the ordering nobody gets right unaided. A retired file committed before its ignore entry was written is tracked and ignored at once, and removing the entry first leaves the file tracked with nothing naming it. No report catches that state, so the mistake is discovered by whoever next wonders why a gitignored path keeps appearing in diffs.
|
|
13
13
|
|
|
14
|
-
Two more follow from where a session looks when the report is thin. An uppercase stem under `.claude/` is not the test for a superseded file, so a session substituting a folder listing reaches `ARCHITECTURE.md`, `REQUIREMENTS.md`,
|
|
14
|
+
Two more follow from where a session looks when the report is thin. An uppercase stem under `.claude/` is not the test for a superseded file, so a session substituting a folder listing reaches `ARCHITECTURE.md`, `REQUIREMENTS.md`, and `DESIGN.md`, each a single file the layout intends to stay one, and proposes shredding three documents. A session falling back to the plugin's own copy of the destination standard proposes a shape the project never adopted, against content only the user can place.
|
|
15
15
|
|
|
16
16
|
The last is the two-speed release skew arriving as a confident wrong answer. `superseded` reached a release in `0.46.0`, and an older CLI exits zero with a well-formed report that never mentions the field. A session reading that absent key as an empty array reports a clean layout to exactly the population holding the retired files.
|
|
17
17
|
|
|
@@ -27,7 +27,7 @@ Stop on any of three conditions, naming which one fired:
|
|
|
27
27
|
|
|
28
28
|
Test for the key rather than for emptiness. A current CLI reporting `"superseded": []` has looked and found nothing, which is the pass above, and reading an absent key as an empty answer reports a clean layout to the projects this skill exists for.
|
|
29
29
|
|
|
30
|
-
No listing substitutes for the field. The pairing runs against the seed folder names the toolkit ships, and an uppercase stem is not the test, so a listing of `.claude/*.md` also reaches `ARCHITECTURE.md`, `REQUIREMENTS.md`,
|
|
30
|
+
No listing substitutes for the field. The pairing runs against the seed folder names the toolkit ships, and an uppercase stem is not the test, so a listing of `.claude/*.md` also reaches `ARCHITECTURE.md`, `REQUIREMENTS.md`, and `DESIGN.md`. Each of those is a single file the layout intends to stay one. A fallback that proposed splitting them would shred three documents to avoid reporting a stale CLI, which is why this skill stops where its siblings degrade.
|
|
31
31
|
|
|
32
32
|
## Step 2: resolve the destination standard
|
|
33
33
|
|
package/docs/ai-workflow.md
CHANGED
|
@@ -75,9 +75,9 @@ When features are independent, run them in parallel instead of sequentially. Use
|
|
|
75
75
|
- Ship each worktree separately with `aitk:git-ship`
|
|
76
76
|
- For full autonomy per worktree, invoke `aitk:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
|
|
77
77
|
|
|
78
|
-
To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `aitk:claude-orchestrate`. It
|
|
78
|
+
To run several worktrees as a coordinated flow rather than ad hoc, assert the orchestrator role in one warm session with `aitk:claude-orchestrate`. It plans each feature, refills the ready queue so a free worker never waits, and reviews each worker's PR with `aitk:claude-pr-review`, then tells the session holding that branch to run `aitk:claude-address-review` whenever the pass posted a finding at any severity, which is the same threshold `aitk:claude-pr-review` states and posts its open heading under. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
|
|
79
79
|
|
|
80
|
-
|
|
80
|
+
Execution order comes off `.claude/tasks/priority.md` and nothing sequences work into versions. Scope stays in `.claude/REQUIREMENTS.md` as a statement of what is wanted, and it reaches the board as discrete tasks the orchestrator orders by readiness.
|
|
81
81
|
|
|
82
82
|
Run one orchestrator at a time. The board is gitignored, so a second session reads none of the first one's writes and the two collide on labels and archives. No fixed number caps the worker tracks underneath it. Collision between file sets is what binds, so a candidate opens only when its files are disjoint from every track in flight, and the ceiling in practice is how many outputs one session can still review properly.
|
|
83
83
|
|
|
@@ -193,7 +193,6 @@ This section is the corpus the coverage claim is measured against: every name `a
|
|
|
193
193
|
| `aitk:claude-intake-answer` | When an intake folder holds unread slots waiting on your decision |
|
|
194
194
|
| `aitk:claude-groundwork` | When the state is unmeasured and more than one approach is live |
|
|
195
195
|
| `aitk:decision-escalate` | When open decisions turn on your preference and want batching into one set |
|
|
196
|
-
| `aitk:claude-roadmap` | When MVP scope needs sequencing into ordered versions |
|
|
197
196
|
| `aitk:claude-tasks` | When a decided item needs a file on the board, or a shipped one needs archiving |
|
|
198
197
|
| `aitk:claude-feature` | When the approach is settled and the next step is a plan |
|
|
199
198
|
|
package/docs/operating-model.md
CHANGED
|
@@ -17,10 +17,10 @@ order, port collisions), see [Claude Code and git worktrees](../wiki/claude/clau
|
|
|
17
17
|
|
|
18
18
|
The split is by vantage, not by capability. Both are Claude Code sessions.
|
|
19
19
|
|
|
20
|
-
| Role | Session | Owns
|
|
21
|
-
| ------------ | ------------------------------------- |
|
|
22
|
-
| Orchestrator | One warm, long-lived session |
|
|
23
|
-
| Worker | One cold worktree session per feature | Implement, self-check, open PR
|
|
20
|
+
| Role | Session | Owns | Does not |
|
|
21
|
+
| ------------ | ------------------------------------- | ------------------------------------- | ----------------------------- |
|
|
22
|
+
| Orchestrator | One warm, long-lived session | Planning, deep PR review, merge order | Edit tracked files, merge PRs |
|
|
23
|
+
| Worker | One cold worktree session per feature | Implement, self-check, open PR | Question the plan, merge |
|
|
24
24
|
|
|
25
25
|
The orchestrator is worth asserting explicitly at the start of a session with
|
|
26
26
|
`claude-orchestrate`, which loads the loop and its boundaries. It is framing and
|
|
@@ -36,13 +36,12 @@ and no later session recovers that vantage.
|
|
|
36
36
|
|
|
37
37
|
One feature travels this path end to end.
|
|
38
38
|
|
|
39
|
-
1. Orchestrator
|
|
40
|
-
2.
|
|
41
|
-
3.
|
|
42
|
-
4. Orchestrator
|
|
43
|
-
5. Orchestrator
|
|
44
|
-
6.
|
|
45
|
-
7. The human reads the result and merges. The orchestrator tells any trailing worker whose branch shares a seam with the merged one to run `claude-address-review`, which rebases whether or not the review left anything open.
|
|
39
|
+
1. Orchestrator plans the next feature with `claude-feature`, writing a plan to `.claude/plans/`. Planning stays in the warm session because good planning is cross-feature. It needs the contract other features consume and the shared wiring seam. A cold session would re-derive or guess.
|
|
40
|
+
2. The human opens a worker worktree with `claude-worktree` and runs `claude-autoship` against the plan. The worker builds, self-checks, opens a PR, and stops at the PR boundary.
|
|
41
|
+
3. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
|
|
42
|
+
4. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a finding at any severity, resolving the target then with `aitk sessions list --branch` and reporting the invocation for the human when no live session holds it. The worker addresses the findings, rebases onto `origin/main` when a sibling landed first and left the branch unable to merge, then pushes a follow-up. A pass carrying only minor findings dispatches too, since the grade runs low often enough that a floor at should-fix loses fixes a worker would have made. `claude-pr-review` states that threshold and the heading follows it, so an open heading is itself the signal to send.
|
|
43
|
+
5. Orchestrator closes the review out with `claude-pr-review` again. The second pass reads only the commits the follow-up added, or the worker's response alone when the follow-up added none, and posts under `## Review` when it finds anything and under `## Review closed` when it finds nothing, so a reader learns from the heading whether work is still owed and takes the merge decision from the counts on the line under it. Repeat from step 4 until a pass closes the review.
|
|
44
|
+
6. The human reads the result and merges. The orchestrator tells any trailing worker whose branch shares a seam with the merged one to run `claude-address-review`, which rebases whether or not the review left anything open.
|
|
46
45
|
|
|
47
46
|
There is no loop construct here. Each worker is a single build that halts at the
|
|
48
47
|
PR. The merge stays a manual human gate. Reliability comes from the plan being
|
|
@@ -55,7 +54,7 @@ The worker's self-review and the orchestrator's review are not the same pass run
|
|
|
55
54
|
twice. They differ by vantage.
|
|
56
55
|
|
|
57
56
|
- Worker self-review, inside `claude-autoship`: the session that wrote the code. Its job is "did I build the plan and does it pass?" Mechanical, and structurally blind to its own misreadings, because the same misreading wrote both the code and the review. This is the green gate that decides whether the PR opens.
|
|
58
|
-
- Orchestrator review, via `claude-pr-review`: a fresh session with cross-feature context (the
|
|
57
|
+
- Orchestrator review, via `claude-pr-review`: a fresh session with cross-feature context (the board, a sibling PR in flight, a downstream contract). Its job is "is this right and does it fit?" It can question the plan itself. This is the merge gate.
|
|
59
58
|
|
|
60
59
|
They collide only if the worker also runs a deep pass. Keep the worker's review
|
|
61
60
|
light and let the orchestrator own the deep, independent one. The human read at
|
|
@@ -127,19 +126,19 @@ coordination costs more than the change it was too small.
|
|
|
127
126
|
|
|
128
127
|
## Where work comes from
|
|
129
128
|
|
|
130
|
-
|
|
129
|
+
Two tiers hold work at different altitudes.
|
|
131
130
|
|
|
132
|
-
-
|
|
133
|
-
- Tasks (`.claude/tasks/`): the active few pulled into the current turn, one file each. Gitignored, high churn. Shape governed by `standards/tasks.md`.
|
|
131
|
+
- Tasks (`.claude/tasks/`): the active few pulled into the current turn, one file each. Gitignored, high churn. Shape governed by `standards/tasks.md`. `priority.md` beside them carries execution order, and `backlog.md` carries what nobody is scheduling.
|
|
134
132
|
- Edits: a few lines, done immediately with no ceremony.
|
|
135
133
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
134
|
+
Nothing above these sequences work into versions. Scope is stated in
|
|
135
|
+
`.claude/REQUIREMENTS.md` and reaches the board as discrete tasks, so why one
|
|
136
|
+
task runs before its neighbors is on its row and why one group of work runs
|
|
137
|
+
before another is carried nowhere at all.
|
|
139
138
|
|
|
140
139
|
## Parallelism
|
|
141
140
|
|
|
142
|
-
The binding constraint is the human and the shared files, not the
|
|
141
|
+
The binding constraint is the human and the shared files, not the board. Cap
|
|
143
142
|
at two or three worker tracks and split them across the stack so they do not
|
|
144
143
|
collide on the same files.
|
|
145
144
|
|
package/package.json
CHANGED
|
@@ -14,7 +14,7 @@ Governs the product-scope document at `.claude/REQUIREMENTS.md`: problem, goals,
|
|
|
14
14
|
Does not govern:
|
|
15
15
|
|
|
16
16
|
- Rationale for a technical choice: `architecture.md`
|
|
17
|
-
-
|
|
17
|
+
- Execution order across the work the scope generates: `tasks.md`
|
|
18
18
|
- Per-domain structure and narrative: `context.md`
|
|
19
19
|
|
|
20
20
|
## What goes in
|
|
@@ -39,7 +39,7 @@ Use `## Problem`, `## Goals`, `## Non-goals`, `## MVP features`, `## Tech stack`
|
|
|
39
39
|
|
|
40
40
|
The MVP list is a historical record of the original scope. Once those features ship it stays as written. Do not renumber it, do not append to it, and do not annotate entries with status. A reader telling the original scope apart from what followed depends on the first one staying legible.
|
|
41
41
|
|
|
42
|
-
Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated.
|
|
42
|
+
Later scope arrives as a new section rather than as an extension of the MVP list. Name the section for what it delivers and state its entries as outcomes, the same way the goals are stated. Nothing sequences either list into versions. Work reaches the board as discrete tasks under `tasks.md`, which orders them by readiness, so a section here states what is wanted and never when it lands.
|
|
43
43
|
|
|
44
44
|
## Distribution
|
|
45
45
|
|
package/standards/tasks.md
CHANGED
|
@@ -19,7 +19,6 @@ Does not govern:
|
|
|
19
19
|
|
|
20
20
|
- The plan file a task cites, its sections, and its answer contract: `plan.md`
|
|
21
21
|
- Phase-label format and which surfaces a label may appear on: `versioning.md`
|
|
22
|
-
- Sequencing across versions and why the order is what it is: `roadmap.md`
|
|
23
22
|
- Architectural reasoning that outlives a task: `architecture.md`
|
|
24
23
|
- The pre-compaction handoff sitting in the folder, its filename and its sections: `session.md`
|
|
25
24
|
- When a project opens a task at all, which is project policy rather than a shape rule
|
|
@@ -52,7 +51,9 @@ The `claude-tasks` skill creates and archives task files. `claude-docs` marks ou
|
|
|
52
51
|
|
|
53
52
|
## Ordering
|
|
54
53
|
|
|
55
|
-
`priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why
|
|
54
|
+
`priority.md` carries execution order and what each task is waiting on. The generated index sorts by filename and says nothing about order, so without this file board state gets reconstructed by hand every session. Why a row sits where it does inside its group is stated on the row itself, in the column that already carries what the task is waiting on, one line per row.
|
|
55
|
+
|
|
56
|
+
That cell is the only home sequencing rationale has. Rationale spanning several rows, why one group of work runs before another, is carried by nothing and reaches a later session only through whoever remembers it. Naming the gap is deliberate: a second document holding it would be the version-sequencing surface this board replaced, and a row already states what it waits on, which is the part of the reasoning a reader acts on.
|
|
56
57
|
|
|
57
58
|
Group tasks by readiness rather than by status, one row per task, under the columns each group fixes below. Keep it to links and blockers: tables, plus at most one sentence per section. A paragraph in `priority.md` is a defect whatever it says. Stating the shape this way is what lets a single diff fail, since a size cap only trips after the fact and every addition looks defensible on its own.
|
|
58
59
|
|
|
@@ -240,7 +241,7 @@ The line is what lets a merge close its own task. Every merge on `main` is a squ
|
|
|
240
241
|
- Architectural reasoning that outlives the task. A finding explains why this task is shaped as it is. A decision the system keeps after the task closes belongs in `.claude/ARCHITECTURE.md`.
|
|
241
242
|
- Narrative of the session that produced the task. A finding states what constrains the task, so what was probed, what it cost, and who decided belongs in the groundwork folder the `Groundwork:` line names. A task with no groundwork folder cuts the narrative rather than relocating it, since the board is not the fallback destination for it.
|
|
242
243
|
- "In progress" or "Blocked" headings. Note status inline on the outcome instead.
|
|
243
|
-
- Sequencing rationale or which version is active. Why this task is planned before its neighbors goes on its row in `priority.md`, in the cell that already carries what it is waiting on.
|
|
244
|
+
- Sequencing rationale or which version is active. Why this task is planned before its neighbors goes on its row in `priority.md`, in the cell that already carries what it is waiting on. Rationale wider than one row has no home at all, so cut it rather than filing it here.
|
|
244
245
|
|
|
245
246
|
## Archiving
|
|
246
247
|
|
|
@@ -1,41 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: claude-roadmap
|
|
3
|
-
description: Why versions are sequenced from the MVP list alone, what makes a version a usable increment, and the lifecycle gate that stops a second pass
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Claude roadmap requirement
|
|
7
|
-
|
|
8
|
-
## Gap
|
|
9
|
-
|
|
10
|
-
Without this skill, versions are invented from a sense of what should come next rather than sequenced from the scope the requirements already fixed. Each one reads as a milestone nobody can use, because the ordering follows what feels foundational instead of what a user can then do, and a version that de-risks nothing sits ahead of the subsystem the whole plan rests on. The roadmap then drifts into task-level steps, which duplicates the plan folder and goes stale the first time a file moves.
|
|
11
|
-
|
|
12
|
-
An update is where the file quietly breaks. Rewriting rows that never changed hides the one line that moved, so a reader diffing the roadmap learns nothing from it. And a project whose MVP already shipped gets its later scope sequenced here, which puts a fresh requirements pass's work into a file that only ever sequenced the MVP.
|
|
13
|
-
|
|
14
|
-
## Must
|
|
15
|
-
|
|
16
|
-
- Sequence from the MVP list in the requirements file and name it as the source
|
|
17
|
-
- Make every version a usable increment, stated as what the user can then do
|
|
18
|
-
- Order by dependency and by de-risking, placing an unproven subsystem inside the version that first needs it
|
|
19
|
-
- Preserve rows that still hold when updating, resequencing or splitting only where scope shifted
|
|
20
|
-
- Follow the reference for the document shape and version format rather than inventing one
|
|
21
|
-
- Report which versions changed on an update
|
|
22
|
-
|
|
23
|
-
## Must not
|
|
24
|
-
|
|
25
|
-
- Break a version into task-level steps or a file list
|
|
26
|
-
- Rewrite a row that did not change
|
|
27
|
-
- Sequence a later scope section without an explicit override from the caller
|
|
28
|
-
- Stage or commit the file, which is tracked but belongs to the git skills
|
|
29
|
-
|
|
30
|
-
## Guards
|
|
31
|
-
|
|
32
|
-
- Requirements file absent or carrying no MVP features: stop, because there is nothing to sequence
|
|
33
|
-
- A later scope section present after the MVP list: stop and name the override, since that scope belongs to a fresh requirements pass
|
|
34
|
-
- Neither copy of the requirements standard resolves: draft without the lifecycle gate. Refusing on a rule that could not be read stops more than it protects.
|
|
35
|
-
|
|
36
|
-
## Out of scope
|
|
37
|
-
|
|
38
|
-
- Task-level steps and file lists, which `claude-feature` and the task board own
|
|
39
|
-
- Writing the requirements being sequenced
|
|
40
|
-
- Committing the file, which the git skills own
|
|
41
|
-
- Deciding what to build next once the MVP list has shipped
|
|
@@ -1,61 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: claude-roadmap
|
|
3
|
-
description: Drafts or updates `.claude/ROADMAP.md` by sequencing the MVP scope from `.claude/REQUIREMENTS.md` into ordered versions, each a usable increment. Use when asked to "draft a roadmap", "build the roadmap", "sequence the versions", "plan the roadmap", or "update the roadmap". Do NOT break versions into task-level steps. That is `claude-feature` and `.claude/tasks/`.
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
# Claude roadmap
|
|
7
|
-
|
|
8
|
-
## Guards
|
|
9
|
-
|
|
10
|
-
- If `.claude/REQUIREMENTS.md` is absent or has no MVP features, stop: `❌ No requirements to sequence. Draft .claude/REQUIREMENTS.md first.`
|
|
11
|
-
- If the requirements file carries a later scope section, stop per Lifecycle gate below
|
|
12
|
-
- Sequence versions and their outcomes only. Do not produce file lists or task steps.
|
|
13
|
-
|
|
14
|
-
## Lifecycle gate
|
|
15
|
-
|
|
16
|
-
A roadmap sequences the MVP list alone, so a later scope section means that list has shipped and a fresh requirements pass owns what follows. The rule is the Lifecycle section of `.claude/standards/requirements.md`, falling back to `${CLAUDE_SKILL_DIR}/../../standards/requirements.md` when the project has no copy.
|
|
17
|
-
|
|
18
|
-
- A later scope section is a `##` heading after `## MVP features` that `.claude/standards/requirements.md` names nowhere, neither among the six it fixes nor as the conditional `## Distribution`
|
|
19
|
-
- On finding one, stop: `❌ MVP scope already sequenced. ## <section> is later scope, which a fresh requirements pass sequences rather than this roadmap. Say to sequence it anyway to override.`
|
|
20
|
-
- Draft without the gate when neither copy of the standard resolves. Refusing on a rule that could not be read stops more than it protects.
|
|
21
|
-
- When the caller overrides, sequence the later scope section's entries as versions and proceed
|
|
22
|
-
|
|
23
|
-
## Step 1: read context
|
|
24
|
-
|
|
25
|
-
Read these in parallel from the project root, skipping any that do not exist:
|
|
26
|
-
|
|
27
|
-
- `.claude/REQUIREMENTS.md`: the MVP feature scope to sequence
|
|
28
|
-
- `.claude/ROADMAP.md`: the existing roadmap, when updating rather than drafting
|
|
29
|
-
- `.claude/tasks/index.md`: what is in flight, to mark the active version
|
|
30
|
-
- `.claude/ARCHITECTURE.md`: technical dependencies that constrain ordering
|
|
31
|
-
|
|
32
|
-
Follow `${CLAUDE_SKILL_DIR}/references/roadmap.md` for the doc shape, sections, and version format.
|
|
33
|
-
|
|
34
|
-
## Step 2: sequence
|
|
35
|
-
|
|
36
|
-
Group the MVP features into versions, each a usable increment that stands on its own. Order the versions by two forces:
|
|
37
|
-
|
|
38
|
-
- Dependency: a version that produces data or a contract another version consumes comes first.
|
|
39
|
-
- De-risking: a version that de-risks an unproven subsystem comes early, inside the version that first needs it.
|
|
40
|
-
|
|
41
|
-
For each version, state the observable outcome as what the user can then do, list the features it groups by name, and note what it depends on and why.
|
|
42
|
-
|
|
43
|
-
When updating an existing roadmap, preserve rows that still hold. Resequence, add, or split only where scope shifted. Do not rewrite rows that did not change.
|
|
44
|
-
|
|
45
|
-
## Step 3: write
|
|
46
|
-
|
|
47
|
-
Write the roadmap to `.claude/ROADMAP.md` at the project root, following `${CLAUDE_SKILL_DIR}/references/roadmap.md`. Create the file when absent.
|
|
48
|
-
|
|
49
|
-
Unlike `.claude/plans/` and `.claude/tasks/`, `.claude/ROADMAP.md` is committed. Do not stage or commit it here. Leave staging to the git skills.
|
|
50
|
-
|
|
51
|
-
## Step 4: output
|
|
52
|
-
|
|
53
|
-
```markdown
|
|
54
|
-
📝 Wrote .claude/ROADMAP.md
|
|
55
|
-
|
|
56
|
-
<N> versions sequenced. Active: vX.Y.
|
|
57
|
-
|
|
58
|
-
Next: /claude-feature for the first version's opening feature.
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
When updating, replace the first line with `📝 Updated .claude/ROADMAP.md` and name which versions changed.
|
|
@@ -1,62 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Roadmap reference
|
|
3
|
-
description: Shape and content rules for .claude/ROADMAP.md
|
|
4
|
-
consumers: claude-roadmap
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Roadmap reference
|
|
8
|
-
|
|
9
|
-
Applies to `.claude/ROADMAP.md`. Sequences the scope from `.claude/REQUIREMENTS.md` into ordered versions, each a usable increment. Update when the sequence changes or a version ships. The roadmap is committed because the sequence and its rationale are shared strategic truth a fresh session needs, unlike `.claude/tasks/`, which is ephemeral scratch.
|
|
10
|
-
|
|
11
|
-
The roadmap is one scannable table. That is what keeps it distinct from `.claude/tasks/`: the roadmap is an overview read at a glance, while tasks are worked one file at a time.
|
|
12
|
-
|
|
13
|
-
## Scope
|
|
14
|
-
|
|
15
|
-
Governs the sequencing document at `.claude/ROADMAP.md`: the version table, its columns, and its lifecycle.
|
|
16
|
-
|
|
17
|
-
Does not govern:
|
|
18
|
-
|
|
19
|
-
- What the scope is, which the roadmap sequences rather than defines: `requirements.md`
|
|
20
|
-
- Task files, outcomes, and board state: `tasks.md`
|
|
21
|
-
- Phase-label format and semver discipline: `versioning.md`
|
|
22
|
-
- Rationale for a technical choice: `architecture.md`
|
|
23
|
-
|
|
24
|
-
## What goes in
|
|
25
|
-
|
|
26
|
-
- One row per version, ordered top to bottom by sequence
|
|
27
|
-
- A status per version: active, next in line, or deferred
|
|
28
|
-
- The observable outcome each version delivers, as a short phrase
|
|
29
|
-
- The features a version groups, by name, drawn from the MVP list in `.claude/REQUIREMENTS.md`
|
|
30
|
-
- The version each row depends on, and a short why
|
|
31
|
-
|
|
32
|
-
## What does not go in
|
|
33
|
-
|
|
34
|
-
- Task breakdown, checkboxes, or per-feature file lists
|
|
35
|
-
- Implementation detail, API names, or component references
|
|
36
|
-
- Sentence-long cells. Keep each cell terse so the table stays scannable.
|
|
37
|
-
|
|
38
|
-
## Format
|
|
39
|
-
|
|
40
|
-
One table. Columns, in order:
|
|
41
|
-
|
|
42
|
-
- `Version`: the `vX.Y` phase label. Phase-label format is governed by `standards/versioning.md`.
|
|
43
|
-
- `Status`: `Now` for the active version, `Next` for sequenced upcoming versions, `Later` for deferred themes.
|
|
44
|
-
- `Outcome`: what the user can do once this version ships, as a phrase.
|
|
45
|
-
- `Features`: the feature names this version groups, comma-separated.
|
|
46
|
-
- `Depends on`: the version this one needs and a short why, or `none` when independent.
|
|
47
|
-
|
|
48
|
-
## Template
|
|
49
|
-
|
|
50
|
-
```markdown
|
|
51
|
-
# Roadmap
|
|
52
|
-
|
|
53
|
-
| Version | Status | Outcome | Features | Depends on |
|
|
54
|
-
| ------- | ------ | -------- | -------------------- | ------------------ |
|
|
55
|
-
| v0.1 | Now | <phrase> | <feature>, <feature> | none |
|
|
56
|
-
| v0.2 | Next | <phrase> | <feature> | v0.1, for <reason> |
|
|
57
|
-
| v0.3 | Later | <phrase> | <feature> | none |
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
## Lifecycle
|
|
61
|
-
|
|
62
|
-
The roadmap sequences a finite, known scope. When the last version ships, the scope is exhausted and the project cuts a semver release per `standards/versioning.md`. Later work arrives as discrete items, a fresh requirements pass or tracked issues, rather than extending the original roadmap without end.
|
|
@@ -1,62 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
title: Roadmap reference
|
|
3
|
-
description: Shape and content rules for .claude/ROADMAP.md
|
|
4
|
-
consumers: claude-roadmap
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Roadmap reference
|
|
8
|
-
|
|
9
|
-
Applies to `.claude/ROADMAP.md`. Sequences the scope from `.claude/REQUIREMENTS.md` into ordered versions, each a usable increment. Update when the sequence changes or a version ships. The roadmap is committed because the sequence and its rationale are shared strategic truth a fresh session needs, unlike `.claude/tasks/`, which is ephemeral scratch.
|
|
10
|
-
|
|
11
|
-
The roadmap is one scannable table. That is what keeps it distinct from `.claude/tasks/`: the roadmap is an overview read at a glance, while tasks are worked one file at a time.
|
|
12
|
-
|
|
13
|
-
## Scope
|
|
14
|
-
|
|
15
|
-
Governs the sequencing document at `.claude/ROADMAP.md`: the version table, its columns, and its lifecycle.
|
|
16
|
-
|
|
17
|
-
Does not govern:
|
|
18
|
-
|
|
19
|
-
- What the scope is, which the roadmap sequences rather than defines: `requirements.md`
|
|
20
|
-
- Task files, outcomes, and board state: `tasks.md`
|
|
21
|
-
- Phase-label format and semver discipline: `versioning.md`
|
|
22
|
-
- Rationale for a technical choice: `architecture.md`
|
|
23
|
-
|
|
24
|
-
## What goes in
|
|
25
|
-
|
|
26
|
-
- One row per version, ordered top to bottom by sequence
|
|
27
|
-
- A status per version: active, next in line, or deferred
|
|
28
|
-
- The observable outcome each version delivers, as a short phrase
|
|
29
|
-
- The features a version groups, by name, drawn from the MVP list in `.claude/REQUIREMENTS.md`
|
|
30
|
-
- The version each row depends on, and a short why
|
|
31
|
-
|
|
32
|
-
## What does not go in
|
|
33
|
-
|
|
34
|
-
- Task breakdown, checkboxes, or per-feature file lists
|
|
35
|
-
- Implementation detail, API names, or component references
|
|
36
|
-
- Sentence-long cells. Keep each cell terse so the table stays scannable.
|
|
37
|
-
|
|
38
|
-
## Format
|
|
39
|
-
|
|
40
|
-
One table. Columns, in order:
|
|
41
|
-
|
|
42
|
-
- `Version`: the `vX.Y` phase label. Phase-label format is governed by `standards/versioning.md`.
|
|
43
|
-
- `Status`: `Now` for the active version, `Next` for sequenced upcoming versions, `Later` for deferred themes.
|
|
44
|
-
- `Outcome`: what the user can do once this version ships, as a phrase.
|
|
45
|
-
- `Features`: the feature names this version groups, comma-separated.
|
|
46
|
-
- `Depends on`: the version this one needs and a short why, or `none` when independent.
|
|
47
|
-
|
|
48
|
-
## Template
|
|
49
|
-
|
|
50
|
-
```markdown
|
|
51
|
-
# Roadmap
|
|
52
|
-
|
|
53
|
-
| Version | Status | Outcome | Features | Depends on |
|
|
54
|
-
| ------- | ------ | -------- | -------------------- | ------------------ |
|
|
55
|
-
| v0.1 | Now | <phrase> | <feature>, <feature> | none |
|
|
56
|
-
| v0.2 | Next | <phrase> | <feature> | v0.1, for <reason> |
|
|
57
|
-
| v0.3 | Later | <phrase> | <feature> | none |
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
## Lifecycle
|
|
61
|
-
|
|
62
|
-
The roadmap sequences a finite, known scope. When the last version ships, the scope is exhausted and the project cuts a semver release per `standards/versioning.md`. Later work arrives as discrete items, a fresh requirements pass or tracked issues, rather than extending the original roadmap without end.
|