@erclx/aitk 0.86.2 → 0.87.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.
|
@@ -108,9 +108,17 @@ Write no shape for a correction. A correction is a sentence, and a format for ad
|
|
|
108
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.
|
|
109
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.
|
|
110
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
|
-
|
|
113
|
-
|
|
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. That runbook holds the routing, and a summary of it here is a second source that drifts from it.
|
|
112
|
+
7. Dispatch the handback. A pass posting a critical or should-fix finding 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.
|
|
113
|
+
- Send only above that floor. A minor posts under the same heading and is visibility alone, so a rule keyed on any open finding sends a worker to act on a note
|
|
114
|
+
- Resolve the target from a fresh session listing at the moment of sending, 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
|
|
115
|
+
- 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
|
|
116
|
+
- Name the skill for the reader to run rather than writing an invocation, which arrives as text
|
|
117
|
+
- 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
|
|
118
|
+
|
|
119
|
+
A session is reachable when it appears in a live listing, which reads what each session registered on disk rather than probing it, and a message carries plain text and no authority. When no live session holds the branch, report the invocation for the human, naming the branch, the pull request, and the skill to run, then stop. Retrying or waiting leaves the loop believing it is open while nothing acts on it. Every dispatch in the trial behind this step found a live session, so this branch stands on reasoning rather than on observation.
|
|
120
|
+
|
|
121
|
+
The channel runs both ways and the return leg carries what the pull request cannot. A worker answering a posted finding by naming the plan question that had already declined it changes the outcome in the moment, where a thread comment waits on whoever reads it next. Read what a worker volunteers as part of the review rather than as an aside.
|
|
114
122
|
|
|
115
123
|
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.
|
|
116
124
|
|
|
@@ -119,7 +127,7 @@ A plan written here is written against a tree several branches are already chang
|
|
|
119
127
|
- 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.
|
|
120
128
|
- Do not implement features in this session. Hand the plan to a worker.
|
|
121
129
|
- Do not merge. Recommend merge or changes. The human merges.
|
|
122
|
-
- Do not spawn worker sessions with agents. The human launches each worktree so every build is an independent, steerable stream with its own PR.
|
|
130
|
+
- 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 7 reaches a session the human already launched, so it leaves this boundary where it is.
|
|
123
131
|
- Do not edit tracked files from this session, at any size. The boundary offers no proportionality exception and nothing enforces it.
|
|
124
132
|
- 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.
|
|
125
133
|
|
|
@@ -3,7 +3,7 @@ title: Orchestrator poll runbook
|
|
|
3
3
|
description: The review trigger, the condition under which it runs, and how to read what it reports
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Run the orchestrator's review trigger. The poll reports pull request movement and the session acts on what it reports.
|
|
6
|
+
Run the orchestrator's review trigger. The poll reports pull request movement and the session acts on what it reports. The script reads and never writes, and the routing block below decides which report earns a review, which earns a dispatch, and which earns neither.
|
|
7
7
|
|
|
8
8
|
`${CLAUDE_SKILL_DIR}/scripts/poll.sh` is the script. It needs `gh` authenticated against the remote and `jq` on the path, and it reads the base branch from `origin/HEAD` rather than assuming a name.
|
|
9
9
|
|
|
@@ -17,6 +17,8 @@ Nothing enforces this. No hook starts the poll and no check stops it, so the con
|
|
|
17
17
|
|
|
18
18
|
The poll is session-scoped and dies with the session that started it. Restart it after a compaction, and take the prompt from this file rather than from a transcript, since a running loop holds whatever wording it was started with and a correction here does not reach it.
|
|
19
19
|
|
|
20
|
+
The reverse direction is the one that goes unnoticed. A scheduled prompt cannot be edited, so every routing fix is a cancel and a re-create, and three made inside one session each reached the running loop and none reached this file. Edit the block here first and re-create the loop from what this file then says. Rewriting the block from memory drops what the shipped one covered, which is how a `SEEN` report once fell through to no rule at all.
|
|
21
|
+
|
|
20
22
|
## The prompt
|
|
21
23
|
|
|
22
24
|
The requirement is a recurring prompt at roughly three minutes carrying the block below. `/loop 3m <the block>` is the mechanism this repository uses and one example among the schedulers a client may hold, so a client without that command reaches the same requirement through whatever recurring prompt it can schedule. Naming one vendor's command as the only path dates a file that ships to every target holding the plugin.
|
|
@@ -28,15 +30,16 @@ Resolve `${CLAUDE_SKILL_DIR}/scripts/poll.sh` to an absolute path and paste that
|
|
|
28
30
|
```plaintext
|
|
29
31
|
Poll GitHub for pull request movement by running <POLL_SCRIPT>, then act on what it reports.
|
|
30
32
|
|
|
33
|
+
- A release pull request, whatever state follows it: report it and stop. Its sweep carries no findings, so no pass is owed. Test this before any rule below, since a release pull request is reported OPENED like any other and would otherwise match that rule first.
|
|
31
34
|
- MOVED or RESPONSE on a pull request I have already reviewed: run the aitk:claude-pr-review skill on it immediately, narrow pass. Re-reviews read prior..head and gain nothing from waiting.
|
|
32
|
-
- OPENED, or a pull request with no prior review pass:
|
|
35
|
+
- OPENED, or a pull request with no prior review pass: run the aitk:claude-pr-review skill on it. A draft counts, since every pull request here opens as one and skipping drafts skips everything.
|
|
33
36
|
- SEEN: report it and stop. A pass already covers that head, whether it arrived out of band or before the poll first saw the pull request, so no review follows.
|
|
34
37
|
- CONFLICT: report it and stop. The branch owner rebases, not this session.
|
|
35
38
|
- GONE: report it, then sweep the board by invoking the aitk:claude-orchestrate skill and following its queue-refill sweep.
|
|
36
39
|
- A line starting `poll:`: report it verbatim and treat that pull request as unread this run. It is a failed query, not a state.
|
|
37
40
|
- Nothing changed: say exactly "No movement." and nothing else.
|
|
38
41
|
|
|
39
|
-
|
|
42
|
+
After any pass that posts a critical or should-fix finding, tell the session holding that branch to run the aitk:claude-address-review skill, resolving it from a session listing taken at that moment. Name the worktree and branch you believe the reader holds and ask to be corrected. Report the invocation for me instead when no live session holds it. A pass carrying only minor findings dispatches nobody.
|
|
40
43
|
```
|
|
41
44
|
|
|
42
45
|
## Reading the output
|
package/docs/ai-workflow.md
CHANGED
|
@@ -73,7 +73,7 @@ When features are independent, run them in parallel instead of sequentially. Use
|
|
|
73
73
|
- Ship each worktree separately with `aitk:git-ship`
|
|
74
74
|
- For full autonomy per worktree, invoke `aitk:claude-autoship` instead of the manual chain. Approve the plan, walk away, come back to draft PRs.
|
|
75
75
|
|
|
76
|
-
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 owns the roadmap, handing a needed draft or resequence to a worker that runs `aitk:claude-roadmap` in its branch, plans each feature, refills the ready queue so a free worker never waits, and reviews each worker's PR with `aitk:claude-pr-review`,
|
|
76
|
+
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 owns the roadmap, handing a needed draft or resequence to a worker that runs `aitk:claude-roadmap` in its branch, 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 critical or should-fix finding. The human launches workers and merges. See [operating model](operating-model.md) for the full loop.
|
|
77
77
|
|
|
78
78
|
Roadmap ownership holds while a scope exists to sequence. Once the MVP list in `.claude/REQUIREMENTS.md` has shipped, later work arrives as discrete items and the orchestrator reads `.claude/tasks/priority.md` for execution order instead.
|
|
79
79
|
|
package/docs/operating-model.md
CHANGED
|
@@ -40,8 +40,8 @@ One feature travels this path end to end.
|
|
|
40
40
|
2. 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.
|
|
41
41
|
3. 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.
|
|
42
42
|
4. Orchestrator reviews the PR with `claude-pr-review` and posts findings to it.
|
|
43
|
-
5.
|
|
44
|
-
6. 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 closed` when it finds nothing open or under `## Review` when it does, so a reader learns the state from the heading. Repeat from step 5 until the review closes.
|
|
43
|
+
5. Orchestrator tells the session holding that branch to run `claude-address-review` once the pass posted a critical or should-fix finding, resolving the target from a session listing taken at that moment 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 nobody and goes straight to step 7, since a minor is visibility alone and leaves nothing for a worker to act on.
|
|
44
|
+
6. 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 closed` when it finds nothing open or under `## Review` when it does, so a reader learns the state from the heading. Repeat from step 5 until the review closes or leaves only minor findings open.
|
|
45
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.
|
|
46
46
|
|
|
47
47
|
There is no loop construct here. Each worker is a single build that halts at the
|
|
@@ -63,10 +63,16 @@ merge is the final gate. No layer repeats another.
|
|
|
63
63
|
|
|
64
64
|
## The review channel
|
|
65
65
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
66
|
+
Findings travel on the PR. `claude-pr-review` posts them there.
|
|
67
|
+
`claude-address-review` reads them back, fixes each, replies or resolves the
|
|
68
|
+
threads, and pushes a follow-up. `claude-pr-review` then runs again, reading only
|
|
69
|
+
what the follow-up added.
|
|
70
|
+
|
|
71
|
+
What the session channel carries is the handback instruction and the worker's
|
|
72
|
+
reply to it, which is a notification layer over a record that stays on the PR. A
|
|
73
|
+
reply that changes an outcome, such as a worker naming the plan question that
|
|
74
|
+
already declined a finding, still belongs back on the PR, since the session
|
|
75
|
+
holding it ends and the thread is what a later reader opens.
|
|
70
76
|
|
|
71
77
|
A finding answered without a commit leaves the head where the first pass read it,
|
|
72
78
|
which a gitignored record and a finding accepted as recorded both produce. The
|