9130ae8c7a
Add durable FIFO capacity-one resource leases for executable stages, including cleanup-confirmed release, conservative restart quarantine, queue state events, and CLI/TUI/Android waiting presentation. Add scheduler, cleanup, protocol, client, and Android coverage plus a proposed Android v3 resource draft. Checked packaged templates and authoring skill references: neither needs updating in this item. The per-item docs note records the shared documentation that docs-fold must update; no shared README or packaged reference was edited.
297 lines
11 KiB
Markdown
297 lines
11 KiB
Markdown
# stage implementer
|
|
|
|
```limits
|
|
{"max_visits":5,"on":["blocked_retryable"]}
|
|
```
|
|
|
|
|
|
```memory
|
|
{"task": "input.prompt", "code_findings": "reviewer.findings?", "ui_findings": "ui_reviewer.findings?"}
|
|
```
|
|
|
|
```output
|
|
{ task, acceptance_checks, changed_files, implementation_summary, new_helpers }
|
|
```
|
|
|
|
```prompt
|
|
Implement input.prompt in the run directory using the repository's actual languages and
|
|
file types; create files as needed.
|
|
|
|
Read android/AGENTS.md first. It is the map of this project - how to build, test, run and capture here, where
|
|
the pieces live, and the conventions that apply. Do not re-derive what it tells you and do not go
|
|
looking for what it already names; if it is wrong or out of date, say so in your output.
|
|
|
|
Read the surrounding code before editing so you extend the existing helpers and patterns rather than
|
|
duplicating them. Keep each change as small as the task allows and follow the repository's own
|
|
conventions and error handling.
|
|
|
|
This is the Android app. Build and test it with the project's own Gradle invocation as the map
|
|
gives it, and treat the map's geometry tokens as the only source of dimensions - a UI change that
|
|
adds a raw value fails the repository's own check. A change with a rendered surface is verified on
|
|
the device the map names (never an emulator), capturing what the map says to capture.
|
|
|
|
Record the acceptance checks in acceptance_checks, the actual changes in changed_files, and any new
|
|
shared helper in new_helpers. Verify with the checks this repository uses - as the map gives them -
|
|
and report the exact commands and observed output. Address any concrete findings the runner supplies
|
|
and note the actual fixes. Return blocked if the required scope or tools are unavailable. Do not
|
|
commit or push; the committer stage lands the work.
|
|
```
|
|
|
|
```tools
|
|
read
|
|
glob
|
|
grep
|
|
edit
|
|
shell
|
|
```
|
|
|
|
```configs
|
|
provider=openai
|
|
model=gpt-5.6-terra
|
|
retries=1
|
|
timeout=30m
|
|
```
|
|
|
|
|
|
```edges
|
|
success -> reviewer
|
|
blocked_retryable -> implementer
|
|
blocked -> #failure
|
|
error -> #failure
|
|
```
|
|
|
|
|
|
# stage reviewer
|
|
|
|
```limits
|
|
{"max_visits": 3, "on": ["rejected"]}
|
|
```
|
|
|
|
```memory
|
|
{"task": "input.prompt", "acceptance_checks": "implementer.acceptance_checks", "changed_files": "implementer.changed_files", "implementation": "implementer.implementation_summary?"}
|
|
```
|
|
|
|
|
|
```output
|
|
{ summary, changed_files, verification_evidence, duplication_review, performance_review, findings }
|
|
```
|
|
|
|
```prompt
|
|
Verify with the build and the unit tests as android/AGENTS.md gives them, and for a
|
|
change with a rendered surface check the captures against the running app on the device the map
|
|
names. Enforce the map's geometry-token rule: a raw dimension outside the token file is a must-fix
|
|
finding.
|
|
|
|
Review the actual changes against the task in input.prompt and the acceptance
|
|
checks the implementer recorded. Run the repository's relevant verification checks
|
|
with the stage tools (for example build, lint, tests or type checks) and report the
|
|
exact commands and observed results in verification_evidence.
|
|
|
|
Independently assess code quality:
|
|
- Duplication: search the run directory for repeated or near-identical functions,
|
|
blocks and copy-pasted logic introduced by the change; identify code that should be
|
|
shared and record concrete locations in duplication_review.
|
|
- Performance and resources: flag redundant computation, unnecessary dependencies,
|
|
and repeated I/O or database/filesystem work that wastes time, CPU or memory;
|
|
record it in performance_review.
|
|
- Workarounds: flag hacks, suppressed errors and shortcuts that trade reliability for
|
|
speed in findings.
|
|
|
|
Keep verification proportionate to the change: exercise the files and screens the diff
|
|
actually touches, capture at most one screenshot per changed surface plus one regression
|
|
screen, and do not repeat sweeps or measurements that an earlier visit already recorded.
|
|
|
|
Return rejected ONLY when at least one must-fix finding exists: a defect that blocks
|
|
acceptance and that you can locate concretely (file and line), with evidence and a
|
|
remedy. Do not return rejected for advisory-only, cosmetic or nit items. When there
|
|
is no must-fix finding but you have non-blocking notes (duplication, performance or
|
|
workaround observations), record them in findings and return advisory, which
|
|
continues the run without another implementer visit. Return success only when the
|
|
observed checks pass and you have nothing further to record. Do not edit files or
|
|
claim unexecuted checks.
|
|
```
|
|
|
|
```tools
|
|
read
|
|
glob
|
|
grep
|
|
shell
|
|
```
|
|
|
|
```configs
|
|
provider=openai
|
|
model=gpt-5.6-luna
|
|
retries=1
|
|
timeout=45m
|
|
```
|
|
|
|
|
|
```edges
|
|
success -> ui_reviewer
|
|
advisory -> ui_reviewer
|
|
rejected -> implementer
|
|
error -> #failure
|
|
```
|
|
|
|
|
|
# stage ui_reviewer
|
|
|
|
```limits
|
|
{"max_visits": 3, "on": ["rejected"]}
|
|
```
|
|
|
|
```memory
|
|
{"task": "input.prompt", "acceptance_checks": "implementer.acceptance_checks", "changed_files": "implementer.changed_files", "implementation": "implementer.implementation_summary?"}
|
|
```
|
|
|
|
|
|
```output
|
|
{ summary, changed_files, ui_applicable, screenshots, ui_review, platform_conventions, findings }
|
|
```
|
|
|
|
```prompt
|
|
Decide whether this change touches a user-facing UI. If it does not (a backend,
|
|
library, CLI, config or data-only change with no rendered surface), set
|
|
ui_applicable=false, explain briefly in summary, and return skipped. Do not invent
|
|
screenshots or visual work.
|
|
|
|
When the change does affect a user-facing UI, verify it visually:
|
|
- Build and launch the application the way the repository actually does it, then
|
|
capture screenshots of every relevant screen, state and viewport (default, empty,
|
|
loading, error, long content, small and large sizes) with the target platform's
|
|
screenshot tooling through shell. Prefer a headless or scripted capture when the
|
|
project supports one. Save the images under the run directory and list the exact
|
|
capture commands and image paths in screenshots.
|
|
- Read the captured images and review them as a UI/UX designer: layout, spacing,
|
|
alignment, typographic hierarchy, color and contrast, iconography, interaction
|
|
and focus states, loading/empty/error states, accessibility, and consistency.
|
|
- Judge the UI against established industry patterns and, above all, the native
|
|
conventions of the platform the app targets (operating system, toolkit or web
|
|
standards). Record the platform you reviewed against in platform_conventions,
|
|
and any deviations and concrete fixes in findings. Infer the target platform from
|
|
the task and the repository's actual UI toolkit when it is unstated.
|
|
- Approve only when the screenshots show the task and the acceptance checks are met
|
|
and the UI is correct, consistent and native to the target platform; otherwise
|
|
return rejected with specific, actionable findings the implementer can fix.
|
|
|
|
Keep the capture pass proportionate: capture each changed state once (for example one
|
|
collapsed and one expanded section, one run state, one stuck header) instead of every
|
|
screen at multiple viewports or pan directions, and reuse what this run already captured
|
|
rather than re-doing it.
|
|
|
|
If the change is UI-facing but screenshots genuinely cannot be captured
|
|
(for example no runnable UI or no display), return blocked rather than approving.
|
|
Do not edit files, and do not approve a UI you did not actually see.
|
|
|
|
Return rejected only for a must-fix visual defect with a concrete location, evidence
|
|
and remedy; record non-blocking polish, duplication or convention notes in findings
|
|
and return advisory, which continues the run without another implementer visit.
|
|
```
|
|
|
|
```tools
|
|
read
|
|
glob
|
|
grep
|
|
shell
|
|
```
|
|
|
|
```configs
|
|
provider=openai
|
|
model=gpt-5.6-luna
|
|
retries=1
|
|
timeout=45m
|
|
```
|
|
|
|
|
|
```edges
|
|
skipped -> committer
|
|
approved -> committer
|
|
advisory -> committer
|
|
rejected -> implementer
|
|
blocked -> #failure
|
|
error -> #failure
|
|
```
|
|
|
|
# stage committer
|
|
|
|
```memory
|
|
{"task": "input.prompt", "changed_files": "implementer.changed_files", "review": "reviewer.summary?", "ui_review": "ui_reviewer.summary?"}
|
|
```
|
|
|
|
```output
|
|
{ commit, files, conflicts_resolved, summary }
|
|
```
|
|
|
|
```prompt
|
|
Commit the work this run produced, and resolve any conflict that is present. This stage
|
|
runs after the reviews have approved and is the only stage allowed to commit.
|
|
|
|
Before committing, check that the change is reflected where it belongs: the packaged
|
|
templates, the packaged
|
|
authoring skill references. Update anything the change makes stale, and state in the
|
|
commit body what you checked, saying explicitly when none of them needs updating.
|
|
|
|
Stage exactly the files this run changed - the paths in changed_files that still exist -
|
|
using the repository's own version control commands, and commit them as one commit whose
|
|
subject says what the change does and whose body summarises it. Do not stage unrelated
|
|
files, generated or ignored files, or anything another change owns. Do not invent work
|
|
that was not done; describe what is actually in the diff.
|
|
|
|
If the workspace is in a conflicted state - unmerged paths, or a merge, rebase or
|
|
cherry-pick left unfinished - resolve each conflict: keep both intents where they are
|
|
compatible, and choose the result that satisfies the task where they are not, then
|
|
complete the operation so the tree is clean and the commit is finished. Never commit
|
|
conflict markers, and never discard the other side's work silently; record what you
|
|
resolved.
|
|
|
|
Do not push, tag, revert, or rewrite unrelated history. If there is nothing to commit,
|
|
report that instead of creating an empty commit. Report the commit identifier, the files
|
|
committed, whatever you resolved, and anything you deliberately left uncommitted.
|
|
|
|
|
|
Finally, bring this branch up to date with main, in this same stage. After committing the work
|
|
above, merge main into this branch here, resolve any conflict here - keeping both intents where they
|
|
are compatible, and choosing the result that satisfies this task where they are not - run the
|
|
repository's checks again after resolving, and commit the completed merge with a message naming what
|
|
was combined. The point is that this branch can later be merged back without conflict: leave the
|
|
tree clean and the merge finished. Never leave conflict markers, never discard the other side's work
|
|
silently. If the merge genuinely cannot be completed, say so with the path and the reason instead of
|
|
leaving the merge half-finished.
|
|
|
|
Then land it: this branch is the work and main is where it belongs, so merge this branch into main
|
|
as the last act of this stage. Find the repository's main working tree with `git worktree list` (the
|
|
entry checked out on main, not this one) and merge this branch into it there with `--no-ff`, with a
|
|
message saying what the change does. Two lanes can land at the same moment, so take a lock first -
|
|
`mkdir` a lock directory beside main's `git` directory in a bounded retry loop, and remove it when
|
|
done - and retry briefly if another lane holds it. Then verify with
|
|
`git merge-base --is-ancestor <this branch> main` and report the commit main now has. If main cannot
|
|
be updated, say exactly why and leave this branch committed and clean rather than leaving main
|
|
half-merged. There is no separate merge pipeline and nothing to hand this to: if it cannot be landed
|
|
here, it is reported here.
|
|
|
|
|
|
Do not edit README or other shared documentation files: an item records what it changed and which documentation is now stale in its own commit body, and the shared documents are folded by a single writer.
|
|
|
|
```
|
|
|
|
```tools
|
|
read
|
|
glob
|
|
grep
|
|
edit
|
|
shell
|
|
```
|
|
|
|
```configs
|
|
provider=openai
|
|
model=gpt-5.6-terra
|
|
retries=1
|
|
timeout=30m
|
|
```
|
|
|
|
```edges
|
|
success -> #success
|
|
blocked -> #failure
|
|
error -> #failure
|
|
```
|