Files
pipelines/docs/workflows/feature.md
T
alan 93682f9ce6 Add the Feature workflow and its full-stack change guide
docs/feature-changes.md records how cross-layer features (protocol,
persistence, server, harness adapters, web proxy, app, fixtures) were built
and verified in this session; docs/workflows/feature.md is the reviewed
prepare → plan → implement → review → ui-review → land definition that
follows it, with a delivery gate for Go, web and app checks.
2026-11-09 23:38:57 +00:00

202 lines
6.8 KiB
Markdown

# stage prepare
```prompt
Prepare this branch for the task; do not implement it. Follow AGENTS.md. Preserve unfinished task edits in a local commit if any; a clean tree is a successful no-op, never an empty commit. Merge current main into this branch, resolving conflicts by keeping both intents and leaving unrelated files untouched. Run `cd app && /Users/alan/development/flutter/bin/flutter pub get` once. Run no test suites. Report HEAD and any task-owned paths.
```
```tools
read
glob
grep
edit
shell
```
```configs
provider=openai
model=gpt-5.6-luna
retries=1
timeout=30m
```
```checks
none: preparation only; implement runs focused tests and the land delivery gate runs the suites
```
```edges
success -> plan
blocked -> #failure
error -> #failure
```
# stage plan
```prompt
Plan the task as one full-stack Pipelines feature using docs/feature-changes.md. Read only the code the task touches. Produce a short plan: the behaviour and acceptance checks; per layer (protocol, persistence, server, harness adapters, web proxy, app, fixture) what changes and in which files, keeping shared files to small hooks; security boundary and limits; how each harness or platform supports it, or that it does not; and the focused tests, scratch end-to-end check and rendered states to capture. Name open questions instead of guessing. Do not edit.
```
```tools
read
glob
grep
```
```configs
provider=openai
model=gpt-5.6-luna
retries=1
timeout=20m
```
```edges
success -> implement
blocked -> #failure
error -> #failure
```
# stage implement
```limits
{"max_visits":5,"on":["blocked_retryable"]}
```
```prompt
Implement the task and plan across every layer it needs, following AGENTS.md, app/AGENTS.md and docs/feature-changes.md. Put logic in new small files; keep shared files to hooks; keep protocol fields additive. Add a fixture option for new rendered states.
Run focused, quiet checks for what you touched (Go package tests, `tool/memwatch/full.sh` with one quoted path list, `tool/analyze.sh`, `node --test` for web changes). For server behaviour run the scratch end-to-end check from the guide and stop every process afterwards. Do not build or capture UI here; ui-review does that. Write app/notes/<feature>.md with behaviour, limits, security and the exact verification output, stating what was not tested.
On re-entry fix only the handed-off must-fix findings. Do not commit, push, deploy or restart anything. Use blocked_retryable only for an evidenced transient prerequisite, otherwise blocked.
```
```tools
read
glob
grep
edit
shell
```
```configs
provider=openai
model=gpt-5.6-luna
retries=1
timeout=90m
```
```checks
none: focused tests and the scratch end-to-end check only; the land delivery gate runs the suites
```
```edges
success -> review
blocked_retryable -> implement
blocked -> #failure
error -> #failure
```
# stage review
```limits
{"max_visits":3,"on":["rejected"]}
```
```prompt
Review this run's diff against the task, the plan (in history.md) and docs/feature-changes.md. Start from the changed-file list and `git diff --stat`, then read per-file hunks and the code around them. Check correctness across layers, the authentication and home-folder boundary, nothing exposed through the web proxy, no logged or stored secrets or input, bounds on retained data, restart and reconnect behaviour, multi-machine routing through the chat's own gateway, additive protocol changes, harness support claims, Material and Cupertino controls, desktop vs phone behaviour, and meaningful tests including the reported end-to-end check.
Run no suites, builds or captures; ui-review owns rendered evidence. Do not edit or commit. On a revisit inspect only the fixes and new hunks. Return rejected for a concrete must-fix with location, evidence and fix; advisory for non-blocking notes; otherwise success.
```
```tools
read
glob
grep
shell
```
```configs
provider=openai
model=gpt-5.6-luna
retries=1
timeout=45m
```
```checks
none: read-only review; shell is used only for git status and git diff
```
```edges
success -> ui-review
advisory -> ui-review
rejected -> implement
error -> #failure
```
# stage ui-review
```limits
{"max_visits":3,"on":["rejected"]}
```
```prompt
Verify the changed UI in a real browser, per app/AGENTS.md, app/tool/capture/README.md and docs/feature-changes.md. Build the full-app fixture once, use the task's fixture option, and interact with every affected state: wide and narrow, light and dark, Material and Cupertino where relevant, including hover, keyboard and focus on desktop. Open every screenshot you cite and save captures and a short report in public/. Use only owned loopback servers and browsers; stop them afterwards.
Run no suites; do not edit or commit. Return skipped only when the change has no rendered effect; rejected for a concrete visual or interaction defect with evidence and fix; blocked for an evidenced capture failure; advisory for non-blocking findings; otherwise approved.
```
```tools
read
glob
grep
shell
```
```configs
provider=openai
model=gpt-5.6-luna
retries=1
timeout=45m
```
```checks
none: read-only visual review; shell only builds the fixture and captures, the land delivery gate runs the suites
```
```edges
approved -> land
advisory -> land
skipped -> land
rejected -> implement
blocked -> #failure
error -> #failure
```
# stage land
```prompt
Commit this run's reviewed change locally and leave a clean candidate. Inspect `git status --short` and the changed-file list; stage only this task's changes and its app/notes entry; check the staged diff (`git diff --cached --stat`, then per file as needed) for unrelated work, secrets and generated artifacts. Create no empty commit: when nothing is staged, report success with a clear note. Commit with a plain imperative subject and report the hash. Do not push, tag, amend, rebase or merge main, and run no suites: the server's delivery gate merges a moved main, runs the checks and lands the candidate. Do not deploy or restart anything. Return blocked with the paths if a clean candidate cannot be produced safely.
```
```tools
read
glob
grep
shell
```
```configs
provider=openai
model=gpt-5.6-luna
retries=1
timeout=45m
delivery=true
```
```checks
git diff --check main...HEAD
cd "$(git rev-parse --show-toplevel)" && if git diff --quiet main...HEAD -- '*.go' go.mod go.sum; then echo "go: no Go changes since main"; else umask 022 && go build ./... && go vet ./... && go test ./...; fi
cd "$(git rev-parse --show-toplevel)" && if git diff --quiet main...HEAD -- web; then echo "web: no web changes since main"; else cd web && node --test test/; fi
cd "$(git rev-parse --show-toplevel)" && if git diff --quiet main...HEAD -- app; then echo "app: no app changes since main"; else cd app && /Users/alan/development/flutter/bin/flutter pub get >/dev/null && tool/analyze.sh && tool/memwatch/full.sh test; fi
```
```edges
success -> #success
blocked -> #failure
error -> #failure
```