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.
This commit is contained in:
@@ -0,0 +1,79 @@
|
||||
# Full-stack feature changes
|
||||
|
||||
How a Pipelines feature that crosses layers is built, checked and handed over.
|
||||
The **Feature** workflow (`docs/workflows/feature.md`) follows this guide; it
|
||||
records what worked for the chat, terminal, file and discovery features built on
|
||||
2026-11-08/09 (turn diffs, shell commands and the interactive terminal, the
|
||||
permanent terminal, Pipelines chat tools, thinking levels, file upload, rename,
|
||||
move and delete, dismissible commands, connection recovery).
|
||||
|
||||
## Layers and where a feature touches them
|
||||
|
||||
| Layer | Where | Typical change |
|
||||
|---|---|---|
|
||||
| Protocol | `internal/protocol/` | New request/frame types in their own file; the `Message` field in `message.go` is additive and `omitempty` so older peers keep working |
|
||||
| Persistence | `internal/pipeline/` | A new table in its own file with `init…` called from `store.go`; bounded rows; survives restarts |
|
||||
| Server | `internal/server/` | Handlers in new files named for the area (`chat_*`, `terminal_*`, `home_files_*`), routed from `chat.go`/`websocket.go`; pushed frames to every client watching |
|
||||
| Harness adapters | `internal/claude`, `internal/codex`, `internal/opencode` | Per-harness mechanism checked against the installed CLI or app-server schema; unsupported means no feature, never a fake |
|
||||
| Web proxy | `web/serve.mjs`, `web/src/peerRelay.js` | Only for new HTTP paths: authenticated route plus the peer-relay allowlist |
|
||||
| App | `app/lib/features/<area>/` | Small files; Material and Cupertino; reached through the chat's own gateway so multi-machine chats work |
|
||||
| Fixture | `app/tool/perf/*_fixture.dart`, `app/tool/search_selection_probe_entry.dart` | A `?param=1` option that renders the new states for captures |
|
||||
|
||||
Shared files every feature touches (`message.go`, `chat_hub.go`, `store.go`,
|
||||
`chat_thread_view.dart`, `perf_fixture.dart`): keep edits there to a few lines
|
||||
and put the logic in new files. Parallel features then merge with small,
|
||||
additive conflicts.
|
||||
|
||||
## Rules that held up
|
||||
|
||||
- **Security boundary.** Everything goes through the authenticated `/connect`
|
||||
websocket. Home-folder access uses `expandHomePath`, `resolveInsideHome` and
|
||||
`specialFilesystem`; symlinks are operated on, not followed. Internal
|
||||
endpoints (for example `/mcp`) must not be reachable through the web proxy;
|
||||
add a proxy test. Typed input, passwords and tokens are never logged or
|
||||
stored. Credentials never cross machines.
|
||||
- **Bounds.** Every retained buffer, list and payload has a limit (for example
|
||||
1 MiB output, 50 runs, 512 KiB views, 5 notifications a minute) and reports
|
||||
truncation instead of failing silently.
|
||||
- **Platform reality.** Check what the installed tools accept (for example
|
||||
`codex app-server generate-json-schema`, `claude` control requests,
|
||||
OpenCode's API). Browsers reserve some shortcuts (Ctrl/Cmd+T, Ctrl+Tab); say
|
||||
which ones work where.
|
||||
- **Desktop vs phone.** Web themes are pinned to Android, so desktop checks use
|
||||
`prefersCompactHitTargets` (device platform), not the theme platform.
|
||||
- **Shared environments.** Never use the production server (127.0.0.1:8080,
|
||||
web 8083), real chats, the personal Fold, or restart shared services.
|
||||
|
||||
## Verification
|
||||
|
||||
- **Focused tests while editing.** Go: `go test ./internal/<pkg> -run <Name>`.
|
||||
App: `cd app && tool/memwatch/full.sh 'test/a_test.dart test/b'` (the whole
|
||||
path list is one quoted argument) and `tool/analyze.sh`. Web:
|
||||
`cd web && node --test test/`. Never bare `flutter test`.
|
||||
- **Scratch end-to-end** for server behaviour: build `./cmd/pipelines-server`,
|
||||
run it with an isolated `HOME`, a scratch `-db`, `-addr 127.0.0.1:0` (an OS-chosen port) and
|
||||
`PIPELINES_MDNS=off`, drive it over the websocket, then stop every process.
|
||||
Real harness runs need credentials; when they are missing, say so rather
|
||||
than claim them.
|
||||
- **Rendered evidence** for visible changes: build the full-app fixture once
|
||||
(`flutter build web --target tool/search_selection_probe_entry.dart --output
|
||||
build/probe-app`) and capture with `app/tool/capture/` at wide (1400x900) and
|
||||
narrow (560x1000) sizes, light and dark, Material and Cupertino where
|
||||
relevant. Open every PNG cited.
|
||||
- **Known pre-existing failures** (as of 2026-11-09, on untouched main): 44
|
||||
tests in `app/test/application/*` (pending launch-update timer) and, under a
|
||||
`umask 077` shell, `internal/claude` `TestServiceTokenIsPassedOnlyFromAPrivateFile`
|
||||
and `internal/opencode` `TestStageDiscoveryRequiresPrivateRegistrationBeforeSessionWork`.
|
||||
The installed server (and so the delivery gate) runs with `Umask 63`
|
||||
(077), so the gate's Go check sets `umask 022` first. Compare against a
|
||||
worktree of main before blaming a change.
|
||||
- **Notes.** Each feature leaves `app/notes/<feature>.md` with behaviour,
|
||||
protocol, limits, security and the exact verification output.
|
||||
|
||||
## Delivery (manager, not the workflow)
|
||||
|
||||
The workflow commits a reviewed candidate; the server's delivery gate checks it
|
||||
and lands it on main. Deployment is separate and only on request: `./install`
|
||||
(web and server), a restart only when no chat or run is active, then
|
||||
`./install --apk` (native build), `./install --macos --publish --flutter
|
||||
<flutter executable>` and `./install --linux --publish`.
|
||||
@@ -0,0 +1,201 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user