buildline 0.0.0-stage → 0.3.0

package/templates/stations/plan.md

@@ -0,0 +1,44 @@
+# Station: plan
+
+Goal: turn the spec into an ordered list of small, verifiable tasks in `feature.json`. A good plan lets a fresh agent session, with no memory of today, pick up the next task and finish it.
+
+Resolve the feature from `$ARGUMENTS`, or use the most recent feature with status `plan`. Read the whole `spec.md` and the code areas named in the technical design.
+
+## Write the tasks
+
+Write them into `feature.json → tasks` (replace the placeholder):
+
+```json
+{
+  "id": "T1",
+  "title": "Add `saved_carts` table and model",
+  "covers": ["R1", "A2"],
+  "verify": "`npm test -- saved-cart.model` passes; migration runs up and down",
+  "passes": false,
+  "notes": ""
+}
+```
+
+Rules:
+
+- **Small**: each task fits in one focused session and one commit, usually under ~200 changed lines.
+- **Vertical first**: the first task should produce a thin end-to-end path (even if ugly) that later tasks fill out. Avoid "all the backend, then all the frontend".
+- **Verifiable**: `verify` says exactly what to run or observe. "Works" is not a verification.
+- **Traceable**: `covers` lists the requirement and acceptance ids it moves forward. Every `A*` scenario must be covered by at least one task.
+- **Test-first where it's cheap**: when a task introduces logic, its first step is a failing test for the acceptance scenario.
+- **Ordered**: dependencies come first. Mark tasks that could run in parallel with `"parallel": true`.
+- Include the boring tasks: migrations, feature flags, docs, analytics events, cleanup of temporary code.
+
+Then write a one-paragraph `## Plan` summary in `spec.md` (approach, order, risks) so humans don't have to read JSON.
+
+## Check
+
+- Every acceptance scenario is covered by at least one task.
+- No task changes the acceptance criteria.
+- The final task is "All gates pass and acceptance scenarios verified end to end."
+
+## Handoff
+
+- Set status to `build`. Append a `history` entry.
+- **Approval:** at autonomy ≤ 2, ask the person to approve the plan and record `approvals.plan` only on an explicit yes. At L3+, continue without waiting.
+- Next: `/buildline-build <id>`, or `/buildline-autopilot <id>` to run build → verify → review unattended.

package/templates/stations/review.md

@@ -0,0 +1,37 @@
+# Station: review
+
+Goal: catch what tests don't (wrong behaviour against the spec, security holes, maintainability problems) and prepare the change so a human reviewer can approve it in minutes.
+
+Resolve the feature from `$ARGUMENTS`, or use the most recent feature with status `review`.
+
+## 1. Get the diff
+
+Work out the base (usually the default branch) and collect the full diff for this feature: `git diff <base>...HEAD`. If the feature isn't on its own branch, use the commits tagged with the feature id.
+
+## 2. Independent review
+
+Ask the `buildline-reviewer` subagent to review the diff against `spec.md` and `.buildline/principles.md`. In Claude Code you can also run `/code-review` for an extra correctness pass.
+
+The reviewer reports only findings that matter, each with file:line, severity (`blocker` / `should-fix` / `nit`) and a concrete fix:
+
+- **Spec fit:** every requirement implemented; nothing extra that wasn't asked for.
+- **Correctness:** edge cases, error handling, concurrency, off-by-one, null handling.
+- **Security:** injection, authz checks on every new endpoint, secrets, unsafe input handling, dependency risk.
+- **Maintainability:** follows existing conventions, no dead code or debug leftovers, names make sense.
+- **Tests:** the tests actually assert the behaviour (not just "doesn't crash"); no skipped or weakened tests.
+- **UX (UI changes):** matches `## Design`; use the `buildline-design-reviewer` subagent with screenshots from `evidence/`.
+
+Reviewers tend to over-report. Discard style opinions that the linter doesn't enforce, and anything speculative without a concrete failure scenario.
+
+## 3. Act on findings
+
+- `blocker` and `should-fix`: add a task per finding, go back to `build` (increment `metrics.reworks`), and fix it. Fixes go through the normal task loop, gates included.
+- `nit`: fix if trivial, otherwise list in the PR description.
+
+## 4. Human review packet
+
+Write `## Review` in `spec.md`: a summary of what changed and why, risk areas to look at first (with file paths), what was verified and how (link to `## Verification`), and remaining nits. This becomes the PR description.
+
+## 5. Route
+
+When there are no open blockers or should-fix findings: status `ship`, history entry, next `/buildline-ship <id>`. A human still approves the merge at every autonomy level.

package/templates/stations/ship.md

@@ -0,0 +1,32 @@
+# Station: ship
+
+Goal: get the change merged cleanly and leave the factory smarter than it was. The second part is what makes the factory improve over time instead of rotting.
+
+Resolve the feature from `$ARGUMENTS`, or use the most recent feature with status `ship`.
+
+## 1. Final check
+
+- `node .buildline/bin/gates.mjs` is green on the latest commit.
+- All tasks have `"passes": true`; `## Verification` shows every scenario passing; `## Review` has no open blockers.
+
+## 2. Pull request
+
+- Make sure the work is on a feature branch named like `feat/<id>-<slug>` (or `fix/…`). Ask before pushing.
+- Open a PR (with `gh pr create` if available). Use the `## Review` section as the body, link the spec file, and list the acceptance scenarios with their results.
+- If the project keeps a CHANGELOG, add an entry written for users, not developers.
+- Merging is a human decision. Never merge on your own, whatever the autonomy level.
+
+## 3. Fold learnings back (living context)
+
+Specs are written for one change; the context files carry what lasts. Update them in the same PR:
+
+- `.buildline/context/architecture.md`: new modules, data model changes, decisions made in `### Technical` that future work must respect.
+- `.buildline/context/design.md`: new components, patterns or tokens introduced.
+- `.buildline/context/product.md`: new capabilities and glossary terms.
+- `AGENTS.md` (outside the Buildline block) or `.buildline/principles.md`: any **recurring** mistake an agent made during this feature that a one-line rule would have prevented. Keep these lean; delete rules that no longer earn their place.
+
+## 4. Close
+
+- Set status to `done`, fill `metrics.shippedAt`, append a `history` entry with the PR link.
+- Append a final `progress.md` entry.
+- Suggest the next feature in the queue (`/buildline`).

package/templates/stations/spec.md

@@ -0,0 +1,46 @@
+# Station: spec
+
+Goal: a spec short enough to actually read, precise enough that "done" can be checked by someone who didn't write the code. Owner: product (PM), with anyone's input.
+
+Resolve the feature from `$ARGUMENTS` (id like `004` or a slug). If none is given, use the most recently updated feature whose status is `spec`, or ask.
+
+## 1. Load context
+
+Read `spec.md → ## Brief`, `.buildline/context/product.md`, and `.buildline/principles.md`. Skim the code areas involved so the requirements fit what already exists.
+
+## 2. Grill, briefly
+
+Interview the person **one question at a time** until these are clear. Offer your best guess with each question so they can just say "yes".
+
+- Who exactly is the user, and what are they trying to get done?
+- What is the smallest version that delivers the outcome?
+- What happens on the unhappy paths: empty, error, slow, offline, no permission, huge data?
+- What must **not** change (existing behaviour, APIs, data)?
+- How will we know it worked after release (a metric, an event, a support ticket that stops)?
+
+Stop as soon as you could write the acceptance scenarios with confidence. Five to eight questions is typical; for small features, two or three.
+
+## 3. Write the spec
+
+Fill these sections of `spec.md` (keep the headings exactly; tooling reads them):
+
+- `## Requirements`: numbered, testable statements (`R1`, `R2`, …). Use "must" for required and "should" for nice-to-have. No implementation details.
+- `## Acceptance`: scenarios in Given / When / Then form, numbered `A1`, `A2`, … Cover the main path, the important unhappy paths, and the "must not change" items. Each scenario must be observable from the outside: UI, API response, CLI output, or a database state.
+- `## Out of scope`: what we are deliberately not doing.
+- `## Open questions`: anything unresolved, with an owner.
+
+Aim for one screen of text. If it's getting longer than two, the feature is probably an epic.
+
+## 4. Critique
+
+Ask the `buildline-spec-critic` subagent to review `spec.md` (it checks for untestable requirements, missing unhappy paths, contradictions and hidden scope). Fix what's valid; mention anything you chose to leave and why.
+
+## 5. Epics: split
+
+If `type` is `epic`, end by proposing 2–6 child features, each a thin, shippable vertical slice. With the person's agreement, create them (`npx buildline new "<title>" --type feature --parent <epic-id>`) and copy the relevant requirements and acceptance into each child. The epic stays at `spec` as an index.
+
+## 6. Approval and handoff
+
+- Set status to `design` (or `plan` if the change has no UX or architecture decisions; say why).
+- **Approval:** the spec needs human approval when autonomy ≤ 3. Ask: "Approve this spec?" Only when the person explicitly approves, record `approvals.spec = { "by": "<name or role>", "at": "<ISO date>" }`. Never record an approval on someone's behalf. They can also approve from `npx buildline ui` or with `npx buildline approve <id> spec`.
+- Append a `history` entry and suggest the next command.

package/templates/stations/verify.md

@@ -0,0 +1,44 @@
+# Station: verify
+
+Goal: an **independent** check that the feature does what the acceptance scenarios say, run by someone who didn't build it. The builder's own "it works" doesn't count here.
+
+Resolve the feature from `$ARGUMENTS`, or use the most recent feature with status `verify`.
+
+## 1. Delegate to a clean context
+
+Hand the job to the `buildline-verifier` subagent. Give it only:
+
+- the feature folder path,
+- the dev/start command from `buildline.json → commands.dev`,
+- the instruction to verify every `A*` scenario in `spec.md → ## Acceptance` and report evidence.
+
+Don't pass it your build notes or your opinion of the code: the point is a fresh pair of eyes. If subagents aren't available in your tool, start a new session and run the steps below yourself, reading only the spec.
+
+## 2. What the verifier does
+
+1. Runs `node .buildline/bin/gates.mjs`. Any red gate is a fail.
+2. For each acceptance scenario, sets up the *Given*, performs the *When*, and observes the *Then* the way a user or client would:
+   - **UI:** run the app; use browser automation (Playwright or browser tools) to click through; take screenshots of key states.
+   - **API:** real HTTP requests against the running service; check status codes and bodies.
+   - **CLI / library:** run the command or a small script and check output.
+   - Prefer an existing automated end-to-end test that encodes the scenario; run it and confirm it actually asserts the *Then*.
+3. Checks the design states listed in `## Design` (loading, empty, error…) and basic accessibility (keyboard path, labels) for UI changes.
+4. Reports each scenario as `PASS` / `FAIL` / `BLOCKED` with evidence (command + output excerpt, or screenshot path).
+
+## 3. Record the result
+
+Write `## Verification` in `spec.md`:
+
+```
+<ISO date> · verifier
+- A1 PASS: `npx playwright test saved-carts.spec.ts` (3 passed)
+- A2 PASS: POST /api/carts → 201, body has id; screenshot .buildline/features/004-saved-carts/evidence/a2.png
+- A3 FAIL: empty state shows "undefined items" instead of the empty message
+```
+
+Save screenshots and logs to `.buildline/features/<id>-<slug>/evidence/`.
+
+## 4. Route
+
+- All pass → status `review`, history entry, next `/buildline-review <id>`.
+- Any fail → status back to `build`. For each failure, add a new task to `feature.json` (`"title": "Fix A3: empty state copy"`, `"covers": ["A3"]`, `"passes": false`) and increment `metrics.reworks` in `feature.json`. Next: `/buildline-build <id>`.