@erclx/aitk 0.82.0 → 0.82.1
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.
|
@@ -7,9 +7,10 @@ disable-model-invocation: true
|
|
|
7
7
|
# Claude orchestrate
|
|
8
8
|
|
|
9
9
|
This session is the orchestrator: the one warm session that holds the
|
|
10
|
-
cross-feature picture. It plans and reviews.
|
|
11
|
-
|
|
12
|
-
|
|
10
|
+
cross-feature picture. It plans and reviews.
|
|
11
|
+
|
|
12
|
+
It does not build, and it does not merge. Building happens in cold worker
|
|
13
|
+
sessions the human launches. Merging is the human's gate.
|
|
13
14
|
|
|
14
15
|
This skill holds the framing, the board procedure, and the dispatch. Every step
|
|
15
16
|
that builds something runs an existing skill. The queue rules below decide which
|
|
@@ -35,7 +36,11 @@ Then output the state of play so the human knows what to launch, review, and mer
|
|
|
35
36
|
|
|
36
37
|
The roadmap is optional and this skill does not require it. It carries why a sequence is what it is, changes only when strategy changes, and is absent in a project whose scope has already shipped. Report what it says and name it as the source. Never assert an active version the file does not state, and say nothing about one when the file is missing.
|
|
37
38
|
|
|
38
|
-
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.
|
|
39
|
+
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.
|
|
40
|
+
|
|
41
|
+
On a request to write the handoff or save the session, read `${CLAUDE_SKILL_DIR}/references/orchestrator-handoff.md` and follow it. It captures what the session learned, then writes `.claude/tasks/session.md` with the state of play, the decisions taken under delegated authority, the mistakes worth not repeating, and the standing cautions. That capture is the only one this session runs, since the refill sweep reports it as owed rather than paying it. Write nothing to the handoff that the board, a task file, or a groundwork folder already carries.
|
|
42
|
+
|
|
43
|
+
On a request to resume after a compaction, read `${CLAUDE_SKILL_DIR}/references/orchestrator-resume.md`, which reads that file back with the board and the groundwork behind the live work.
|
|
39
44
|
|
|
40
45
|
The review trigger takes the same shape. `references/orchestrator-poll.md` holds the loop prompt and the condition under which the poll runs, and `scripts/poll.sh` is what the prompt invokes. A session holding a recurring-prompt scheduler starts and cancels that loop itself, and no hook or check does, so the condition holds only while whoever holds the loop applies it.
|
|
41
46
|
|
|
@@ -95,12 +100,16 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
|
|
|
95
100
|
|
|
96
101
|
## The loop
|
|
97
102
|
|
|
98
|
-
1. Own the roadmap while a scope exists to sequence.
|
|
103
|
+
1. Own the roadmap while a scope exists to sequence.
|
|
104
|
+
- Capture a needed draft or resequence of `.claude/ROADMAP.md` in the plan or a task file, naming the MVP list in `.claude/REQUIREMENTS.md` as the source, so a worker runs `claude-roadmap` in its branch and the tracked edit ships in a PR rather than dirtying main
|
|
105
|
+
- Stop owning it once that list has shipped, since later work then arrives as discrete items rather than as versions
|
|
99
106
|
2. 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.
|
|
100
107
|
3. Decide parallelism and merge order. Note which plans touch a shared wiring seam so their PRs merge in sequence, not at once.
|
|
101
108
|
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.
|
|
102
109
|
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.
|
|
103
|
-
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.
|
|
110
|
+
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.
|
|
111
|
+
- 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
|
|
112
|
+
- The poll routes a moved or answered pull request straight to a re-review and reports an opened one without acting, which keeps every first pass a batched judgment this session triggers
|
|
104
113
|
7. Close the loop. After the worker runs `claude-address-review`, re-review if needed, then the human merges. Tell the trailing worker to rebase when its branch shares a seam with the merged one.
|
|
105
114
|
|
|
106
115
|
A plan written here is written against a tree several branches are already changing, so it names the file set of every track in flight as a constraint, one set per track, read from the Touches column of that track's row. State for each set which of the two acts it forbids, per Constraints in `.claude/standards/plan.md`, or `${CLAUDE_SKILL_DIR}/../../standards/plan.md` when the project does not have it. A bare path list leaves the worker guessing, which is how a plan ends up forbidding the repair of a citation the change broke.
|
|
@@ -114,7 +123,9 @@ A plan written here is written against a tree several branches are already chang
|
|
|
114
123
|
- Do not edit tracked files from this session, at any size. The boundary offers no proportionality exception and nothing enforces it.
|
|
115
124
|
- 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.
|
|
116
125
|
|
|
117
|
-
The tracked-file boundary collides with `CLAUDE.md`, which says to handle a small edit immediately without a task entry, and this rule wins wherever the two meet. A session that writes a change cannot review it independently afterwards and no later session recovers that vantage, which is the separation `claude-pr-review` exists to supply.
|
|
126
|
+
The tracked-file boundary collides with `CLAUDE.md`, which says to handle a small edit immediately without a task entry, and this rule wins wherever the two meet. A session that writes a change cannot review it independently afterwards and no later session recovers that vantage, which is the separation `claude-pr-review` exists to supply.
|
|
127
|
+
|
|
128
|
+
Record a change identified while orchestrating against the task that owns it, fold one no task owns into the next task touching the same surface, and file a task only when no such task exists or is expected. Run `claude-review` when the boundary is crossed anyway, since a branch-diff pass is not independent and is the only check a self-authored change can get.
|
|
118
129
|
|
|
119
130
|
## Refilling the ready queue
|
|
120
131
|
|
|
@@ -128,10 +139,13 @@ It counts unclaimed plans against workers rather than reading the reserve in ste
|
|
|
128
139
|
|
|
129
140
|
1. Run `gh pr list --state open` and `git log --oneline -8`. Report any pull request whose review has not been posted and stop for that one first.
|
|
130
141
|
2. For each pull request merged since the last sweep, place every finding it produced. Route a finding that changes a rule to the standard or rule that states it, one that changes another task to that task's Findings, and one that overturns a groundwork lean to that folder marked answered. Never leave a finding in a pull request thread alone.
|
|
131
|
-
3. Archive what closed.
|
|
142
|
+
3. Archive what closed.
|
|
143
|
+
- A task whose outcomes are all `[x]` runs `claude-docs` for the plan sweep, then `claude-tasks` to archive
|
|
144
|
+
- A task whose outcomes describe standing policy rather than a deliverable never closes on its own, so hand it to a worker to encode the policy where it is enforced, then cut the outcomes with the reason recorded and archive once that branch merges. Encoding it from this session would write a tracked file, which Boundaries forbids.
|
|
132
145
|
4. Read `.claude/tasks/priority.md` and count entries under its `## Run now` heading that carry a written plan. Keep one in reserve beyond what is running.
|
|
133
146
|
5. Promote by whether a task establishes functionality rather than by age. Prefer a task that adds or proves a mechanism over one that trims, tidies, or audits an existing surface.
|
|
134
|
-
6. Before promoting a candidate, list the files it touches against every task already running, per Parallelism below. Name the overlap and serialize when the sets are not disjoint.
|
|
147
|
+
6. Before promoting a candidate, list the files it touches against every task already running, per Parallelism below. Name the overlap and serialize when the sets are not disjoint.
|
|
148
|
+
- A candidate held by something outside the tree stays where it is whatever those sets show. A collision is one of the reasons a task cannot start, so disjointness clears that reason alone and leaves an external condition standing.
|
|
135
149
|
7. Write a plan for each newly promoted task with `claude-feature`, carrying the in-flight constraint that The loop above states, then report:
|
|
136
150
|
|
|
137
151
|
```plaintext
|
|
@@ -158,8 +172,10 @@ Promoting, demoting, and archiving a row all write `.claude/tasks/priority.md`,
|
|
|
158
172
|
- Edit the file with the file-editing tool. A shell stream editor and an inline string replace both exit clean on a non-match, so a promotion that matched nothing leaves the board wrong with nothing reporting it, and the file-editing tool errors instead.
|
|
159
173
|
- Put a pointer in the Plan column, never prose. `## Run now` claims a written plan covers every open outcome, and `claude-autoship` refuses at its guard when it follows the column and finds no plan, which spends a worker dispatch to learn what the row should have said.
|
|
160
174
|
- Name the file set in the Touches column. The disjointness call in step 6 is only checkable later when the sets are written down rather than reasoned once and discarded.
|
|
161
|
-
- Re-resolve every Plan pointer after anything archives a plan
|
|
162
|
-
- Read the file back after writing it, since the row that lands is the row a worker acts on
|
|
175
|
+
- Re-resolve every Plan pointer after anything archives a plan
|
|
176
|
+
- Read the file back after writing it, since the row that lands is the row a worker acts on
|
|
177
|
+
|
|
178
|
+
A Plan pointer goes stale from a branch this board never sees. `claude-docs` moves a plan to `.claude/plans-archive/` and rewrites the citation in the task file alone, so a row for a task still on the board keeps pointing into `.claude/plans/` at a file that has moved. Workers running the ship chain on their own branches archive plans this board still cites, and the board reads as correct until a pointer is followed.
|
|
163
179
|
|
|
164
180
|
## Parallelism
|
|
165
181
|
|
|
@@ -167,9 +183,11 @@ No fixed number caps worker tracks. Collision between file sets is what binds, s
|
|
|
167
183
|
list the files a candidate touches against every track already in flight and open
|
|
168
184
|
it only when the sets are disjoint. What thins as tracks multiply is the review
|
|
169
185
|
attention each output gets, so add a track while you can still review every one
|
|
170
|
-
properly and stop when you cannot.
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
186
|
+
properly and stop when you cannot.
|
|
187
|
+
|
|
188
|
+
Serialize any track that touches a shared wiring seam with another in flight.
|
|
189
|
+
Merge the branch with the smallest shared-file footprint first, and merge a
|
|
190
|
+
branch touching `CLAUDE.md`, a Claude context entry, or a regenerated `index.md`
|
|
191
|
+
last. Have every sibling rebase on the new `main` before the next merge. Assign
|
|
192
|
+
a distinct port per track when two workers run a server, since each session
|
|
193
|
+
spawns its own process.
|
package/package.json
CHANGED
|
@@ -8,4 +8,4 @@ runtime = ""
|
|
|
8
8
|
scaffold = ""
|
|
9
9
|
|
|
10
10
|
[gitignore]
|
|
11
|
-
"# Claude" = [".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/plans-archive/", ".claude/review/", ".claude/task-archive/", ".claude/worktrees/", ".claude/tasks/"]
|
|
11
|
+
"# Claude" = [".claude/.records.git/", ".claude/.tmp/", ".claude/groundwork/", ".claude/intake/", ".claude/memory/", ".claude/plans/", ".claude/plans-archive/", ".claude/review/", ".claude/task-archive/", ".claude/worktrees/", ".claude/tasks/"]
|