buildline 0.0.0-stage → 0.3.1

package/templates/bin/hook.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// Claude Code hooks for the factory. Managed by buildline.
+//
+//   session-start  prints a short factory briefing into the new session's context
+//   guard          blocks edits to a spec's "## Acceptance" section while the
+//                  feature is in build/verify/review, so agents can't move the goalposts
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = process.env.CLAUDE_PROJECT_DIR || path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+const featuresDir = path.join(root, '.buildline', 'features');
+const mode = process.argv[2];
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function features() {
+  if (!fs.existsSync(featuresDir)) return [];
+  return fs
+    .readdirSync(featuresDir)
+    .map((dir) => ({ dir, data: readJson(path.join(featuresDir, dir, 'feature.json')) }))
+    .filter((f) => f.data);
+}
+
+function sessionStart() {
+  const config = readJson(path.join(root, '.buildline', 'buildline.json')) || {};
+  const active = features().filter((f) => f.data.status !== 'done');
+  const lines = [`[buildline] autonomy L${config.autonomy ?? 2}. Rules: AGENTS.md › Software factory. Type /buildline for status and next steps.`];
+  for (const { dir, data } of active.slice(0, 8)) {
+    const tasks = data.tasks || [];
+    const done = tasks.filter((t) => t.passes).length;
+    const progress = tasks.length ? ` · ${done}/${tasks.length} tasks` : '';
+    const blocked = data.blocked ? ` · BLOCKED: ${data.blocked}` : '';
+    lines.push(`  ${dir} · ${data.status}${progress}${blocked}`);
+  }
+  if (active.length > 8) lines.push(`  …and ${active.length - 8} more`);
+  process.stdout.write(lines.join('\n') + '\n');
+}
+
+const acceptance = (text) => {
+  const m = /^## Acceptance\s*$([\s\S]*?)(?=^## |(?![\s\S]))/m.exec(text || '');
+  return m ? m[1].trim() : null;
+};
+
+function guard(input) {
+  const tool = input.tool_name;
+  const ti = input.tool_input || {};
+  const file = ti.file_path ? path.resolve(root, ti.file_path) : null;
+  if (!file || !file.startsWith(featuresDir + path.sep) || path.basename(file) !== 'spec.md') return;
+
+  const feature = readJson(path.join(path.dirname(file), 'feature.json'));
+  if (!feature || !['build', 'verify', 'review'].includes(feature.status)) return;
+
+  const before = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : '';
+  let after = before;
+  if (tool === 'Write') after = ti.content ?? '';
+  else if (tool === 'Edit') after = before.replace(ti.old_string ?? '', ti.new_string ?? '');
+  else if (Array.isArray(ti.edits)) for (const e of ti.edits) after = after.replace(e.old_string ?? '', e.new_string ?? '');
+
+  if (acceptance(before) !== acceptance(after)) {
+    process.stderr.write(
+      `buildline guard: "## Acceptance" in ${path.relative(root, file)} is locked while the feature is in "${feature.status}". ` +
+        'If a scenario is wrong, stop and ask the spec owner; they can change it at the spec station.\n',
+    );
+    process.exit(2);
+  }
+}
+
+let raw = '';
+process.stdin.on('data', (c) => (raw += c));
+process.stdin.on('end', () => {
+  let input = {};
+  try {
+    input = raw ? JSON.parse(raw) : {};
+  } catch {}
+  try {
+    if (mode === 'session-start') sessionStart();
+    else if (mode === 'guard') guard(input);
+  } catch (err) {
+    // A broken hook must never break the session.
+    process.stderr.write(`buildline hook error: ${err.message}\n`);
+  }
+});
+if (process.stdin.isTTY) process.stdin.emit('end');

package/templates/buildline-readme.md

@@ -0,0 +1,55 @@
+# {{project}} software factory
+
+This folder holds the factory: how ideas become shipped, verified changes in this project. It works with Claude Code, Codex, Cursor, Gemini CLI and any agent that reads `AGENTS.md`.
+
+## 60-second tour
+
+```
+.buildline/
+  buildline.json      config: autonomy level, quality gates, team, agents
+  principles.md     the non-negotiables every change is checked against   (yours to edit)
+  context/          product, architecture and design knowledge            (yours to edit)
+  stations/         playbooks agents follow at each step                  (managed)
+  features/         one folder per change: feature.json, spec.md, progress.md
+  bin/gates.mjs     runs the quality gates
+```
+
+Every change is a **feature** that moves through stations:
+`intake → spec → design → plan → build → verify → review → ship`. Fixes skip spec, design and plan.
+
+## Start here, by role
+
+### Product managers
+- See everything: `npx buildline ui` opens a dashboard in your browser. Create features, edit specs, approve.
+- In Claude Code: `/buildline-new <idea>`, then `/buildline-spec <id>`. Claude interviews you and writes the requirements and acceptance scenarios.
+- You own `## Acceptance` in each spec. Agents can't change it during build (a hook enforces this).
+- Approve specs in the dashboard or with `npx buildline approve <id> spec`.
+
+### Designers
+- Fill in `context/design.md` once: tokens, components, patterns, links to Figma or Storybook.
+- `/buildline-design <id>`: share a Figma link or screenshots; Claude writes flows, states and copy into the spec, and the design reviewer checks it against the system.
+- After build, screenshots land in `features/<id>/evidence/` for your review.
+
+### Developers
+- `/buildline` shows status and what's next. `/buildline-build <id>` works tasks one by one behind the gates.
+- `npx buildline run <id>` starts an unattended build → verify → review loop with `/goal` (autonomy L3+).
+- `node .buildline/bin/gates.mjs` runs lint, types, tests and build exactly as agents do.
+
+## Autonomy levels
+
+Set `autonomy` in `buildline.json`:
+
+| Level | Humans approve | Agents do alone |
+|---|---|---|
+| 1 Assist | every station | nothing without a yes |
+| 2 Guided | spec, plan, merge | build, verify, review |
+| 3 Autopilot | spec, merge | plan, build, verify, review |
+| 4 Dark factory | merge | everything up to a ready PR |
+
+Start at 2. Move up once the gates and acceptance scenarios have earned your trust.
+
+## Customising
+
+- Edit `principles.md` and `context/*`; the factory never overwrites them.
+- Edit station playbooks freely. `buildline update` won't overwrite files you've changed (it tells you instead).
+- Change gates in `buildline.json`, then run `npx buildline update` to refresh AGENTS.md.

package/templates/ci/buildline.yml

@@ -0,0 +1,71 @@
+# Buildline CI. Managed by buildline.
+#  - gates:  runs the factory quality gates on every pull request
+#  - review: Claude reviews the PR against its factory spec (needs ANTHROPIC_API_KEY
+#            or CLAUDE_CODE_OAUTH_TOKEN as a repository secret; skipped if neither is set)
+#  - @claude mentions in PR/issue comments run Claude interactively
+name: buildline
+
+on:
+  pull_request:
+    types: [opened, synchronize, ready_for_review]
+  issue_comment:
+    types: [created]
+  pull_request_review_comment:
+    types: [created]
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+  id-token: write
+
+jobs:
+  gates:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+{{ciSetup}}
+      - run: node .buildline/bin/gates.mjs
+
+  review:
+    if: github.event_name == 'pull_request' && !github.event.pull_request.draft
+    runs-on: ubuntu-latest
+    env:
+      HAS_KEY: ${{ secrets.ANTHROPIC_API_KEY != '' || secrets.CLAUDE_CODE_OAUTH_TOKEN != '' }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - if: env.HAS_KEY == 'true'
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            Review pull request #${{ github.event.pull_request.number }} in ${{ github.repository }}.
+            Find the factory feature it implements (branch name or commit tags like [004/T1] → .buildline/features/004-*).
+            Follow .buildline/stations/review.md using the buildline-reviewer subagent against base origin/${{ github.base_ref }}.
+            Post one concise PR comment with the findings and verdict. Do not push commits.
+          claude_args: "--max-turns 30"
+
+  mention:
+    if: |
+      (github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment') &&
+      contains(github.event.comment.body, '@claude')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          claude_args: "--max-turns 30"

package/templates/context/architecture.md

@@ -0,0 +1,21 @@
+# Architecture
+
+> TODO: Run `/buildline-onboard` (or fill this in by hand). Prefer bullets and file paths over prose.
+
+## Stack
+{{stackBullets}}
+
+## Module map
+TODO: main folders/modules and what each is responsible for.
+
+## Data flow
+TODO: how a typical request or user action moves through the system.
+
+## Conventions
+TODO: naming, folder layout, state, errors, testing, with one real example path each.
+
+## Key decisions
+TODO: decision, then the reason (link ADRs if they exist).
+
+## Hazards
+TODO: generated code, fragile areas, things agents must not touch.

package/templates/context/design.md

@@ -0,0 +1,22 @@
+# Design system
+
+> TODO: Run `/buildline-onboard` (or fill this in by hand). Designers own this file.
+
+## Principles
+TODO: three to five principles that decide trade-offs (e.g. "clarity over density").
+
+## Source of truth
+TODO: Figma file, Storybook URL, token files (e.g. `src/styles/tokens.css`).
+
+## Tokens
+{{uiBullets}}
+TODO: colour, type scale, spacing, radius, shadow, motion. Name the token, not the raw value.
+
+## Components
+TODO: core components and where they live; when to use which.
+
+## Patterns
+TODO: forms, tables, empty states, errors, notifications, navigation.
+
+## Accessibility baseline
+WCAG 2.2 AA. TODO: anything stricter or project-specific.

package/templates/context/product.md

@@ -0,0 +1,22 @@
+# Product
+
+> TODO: Run `/buildline-onboard` (or fill this in by hand). Keep it under ~120 lines.
+
+## Vision
+TODO: one or two sentences: what this is and why it exists.
+
+## Users
+TODO: primary users, what they're trying to get done, and their context.
+
+## Problems we solve
+TODO
+
+## Success metrics
+TODO: one to three measurable signals.
+
+## Scope
+- In: TODO
+- Out (non-goals): TODO
+
+## Glossary
+TODO: domain terms and what they mean here.

package/templates/cursor.mdc

@@ -0,0 +1,11 @@
+---
+description: Software factory pipeline and rules for this project
+alwaysApply: true
+---
+
+This project uses a software factory. Follow the rules in `AGENTS.md` (section "Software factory").
+
+To run a station, read its playbook in `.buildline/stations/` and follow it:
+intake (`new.md`), `spec.md`, `design.md`, `plan.md`, `build.md`, `verify.md`, `review.md`, `ship.md`, `autopilot.md`.
+
+When the user says "buildline" or "factory" or asks what to do next, follow `.buildline/stations/buildline.md`.

package/templates/feature/progress.md

@@ -0,0 +1,6 @@
+# Progress · {{id}} {{title}}
+
+Append-only log. Every work session ends with an entry: what was done, how it was verified, what's next.
+
+## {{date}} · new
+- Feature opened as `{{type}}`.

package/templates/feature/spec.md

@@ -0,0 +1,34 @@
+# {{title}}
+
+`{{id}}` · {{type}} · created {{date}}
+
+## Brief
+**Problem:** TODO: what's wrong or missing, and for whom.
+**Outcome:** TODO: what's true when this ships.
+**Open questions:** none yet.
+
+## Requirements
+- R1 TODO
+
+## Acceptance
+<!-- Owned by the spec author. Agents must not edit this section during build. -->
+- A1 **Given** TODO **When** TODO **Then** TODO
+
+## Out of scope
+- TODO
+
+## Design
+### Experience
+_Flows, screens and states, components, copy, accessibility. Skip for non-UI changes._
+
+### Technical
+_Approach, changes, risks, test strategy._
+
+## Plan
+_Written by the plan station. Tasks live in feature.json._
+
+## Verification
+_Written by the verify station._
+
+## Review
+_Written by the review station; becomes the PR description._

package/templates/principles.md

@@ -0,0 +1,23 @@
+# Principles
+
+The non-negotiables every change is checked against. Keep this list short; every line should earn its place. Edit freely, since the factory never overwrites this file.
+
+## Product
+
+1. **Outcomes over output.** Every feature names the user problem it solves and how we'll know it worked.
+2. **Smallest valuable slice first.** Ship a thin version end to end, then improve it.
+3. **Plain language.** UI copy says what happened and what to do next.
+
+## Design
+
+4. **Use the system.** Reuse existing components and tokens; new ones need a reason.
+5. **Every state is designed.** Loading, empty, error, success and disabled are part of the feature, not polish.
+6. **Accessible by default.** WCAG 2.2 AA: keyboard reachable, labelled, sufficient contrast.
+
+## Engineering
+
+7. **Evidence, not claims.** Nothing is done until its verification has been run and observed.
+8. **Tests protect behaviour.** Tests assert what users and clients see; never weaken a test to make it pass.
+9. **Follow the codebase.** Match existing conventions; if you break one, say why in the spec.
+10. **No secrets in code.** Configuration and credentials come from the environment.
+11. **Reversible changes.** Prefer small commits, feature flags for risky changes, and migrations that can roll back.

package/templates/stations/autopilot.md

@@ -0,0 +1,52 @@
+# Station: autopilot
+
+Goal: run **build → verify → review** in a loop, unattended, until the feature is ready to ship or genuinely blocked. This is the long-running harness: progress lives in files and git, not in the conversation, so it survives context compaction and restarts.
+
+Resolve the feature from `$ARGUMENTS`.
+
+## Preconditions (check, don't assume)
+
+- `buildline.json → autonomy` is 3 or 4. At L1–L2, explain that autopilot needs a higher autonomy level and offer `/buildline-build` instead.
+- `approvals.spec` is recorded (unless autonomy is 4 or the type is `fix`).
+- `feature.json → tasks` exists. If not, run the `plan` station first.
+- The working tree is clean, and you're on a feature branch (create `feat/<id>-<slug>` if not).
+
+## The loop
+
+Repeat until done or blocked:
+
+1. **Build**: follow `.buildline/stations/build.md` for the next failing task. One task, gates, evidence, commit, `progress.md`.
+2. When all tasks pass → **verify**: follow `.buildline/stations/verify.md` using the `buildline-verifier` subagent. Failures become new tasks; loop back to 1.
+3. When verification passes → **review**: follow `.buildline/stations/review.md` using the `buildline-reviewer` subagent. Blockers become new tasks; loop back to 1.
+4. When review is clean → set status `ship`, write the `## Review` packet, and stop. Do **not** push or open a PR unless autonomy is 4 *and* the person asked for it.
+
+If `buildline.json → models` routes verify or review to another CLI (`codex…`, `gemini…`), run that step with `npx buildline step <station> <id> --headless` instead of the subagent, then read its output and the updated `feature.json` to decide the next loop.
+
+After each step, print a one-line status so progress is visible, e.g. `[autopilot 004] T3 passing · 4/6 tasks · gates green`.
+
+## Stop conditions (blocked)
+
+Stop and summarise instead of continuing if:
+
+- the same task fails after two genuinely different approaches,
+- a requirement or acceptance scenario looks wrong or contradictory,
+- the change needs a secret, a paid service, a production system or a destructive action,
+- `metrics.reworks` reaches 5 (the spec or plan probably needs a human).
+
+Write the blocker to `progress.md` and set `feature.json → blocked` to a one-line reason.
+
+## Running it with `/goal` (Claude Code)
+
+`/goal` keeps Claude working across turns until a condition is met. Its evaluator only sees the conversation, so the condition must be provable from printed output. From the terminal:
+
+```bash
+npx buildline run 004          # opens Claude Code with the goal below
+```
+
+or type it yourself:
+
+```
+/goal Feature 004 reaches status "ship": following .buildline/stations/autopilot.md, every task in its feature.json has "passes": true, the last `node .buildline/bin/gates.mjs` run printed "ALL GATES PASSED", and the verifier reported every acceptance scenario as PASS. Stop early if blocked as defined in the playbook, or after 60 turns.
+```
+
+Use auto-accept or auto permission mode for unattended runs, inside a sandbox, container or worktree if you can. Headless: `claude -p "/goal …" --permission-mode acceptEdits --output-format stream-json --verbose`.

package/templates/stations/build.md

@@ -0,0 +1,52 @@
+# Station: build
+
+Goal: implement the plan **one task at a time**, each behind the gates, each with evidence. This playbook is written so that any fresh session can resume exactly where the last one stopped.
+
+Resolve the feature from `$ARGUMENTS`, or use the most recent feature with status `build`.
+
+## 0. Check approvals
+
+- Autonomy ≤ 3 and `approvals.spec` missing → stop and ask for spec approval first (fixes are exempt).
+- Autonomy ≤ 2 and `approvals.plan` missing → stop and ask for plan approval first.
+
+## 1. Get your bearings (every session)
+
+1. `git status` and `git log --oneline -10`: know what's already there; don't build on uncommitted mystery changes without asking.
+2. Read `progress.md` (the last entry tells you where things stand) and `feature.json → tasks`.
+3. Read `spec.md`: Requirements, Acceptance, Design, Plan.
+4. Run `node .buildline/bin/gates.mjs`. If gates fail **before** you change anything, record it in `progress.md` and fix or report it first. Don't stack new work on a red baseline.
+
+For `fix` features with no tasks: create a single task `T1` ("Reproduce with a failing test, then fix") plus `T2` ("Gates pass and A1 verified").
+
+## 2. Work the next task
+
+Pick the first task with `"passes": false`.
+
+1. If the task adds behaviour, **write the failing test first** and run it to see it fail for the right reason.
+2. Implement the smallest change that makes it pass. Follow the conventions in `.buildline/context/architecture.md` and reuse existing components and utilities before making new ones.
+3. Run the task's `verify` step **and** the gates. Read the output; don't assume.
+4. For UI work, run the app and look at it (a screenshot via the browser tools if available). Check the states listed in the design.
+5. Only when everything above is green, set `"passes": true` and write in `notes` what you ran and what you observed (one or two lines).
+6. Commit with a clear message, e.g. `feat(saved-carts): add model and migration [004/T1]`.
+
+If you get stuck on the same task after two genuinely different attempts, stop: write what you tried in `progress.md`, set `notes` on the task, and ask for help. Don't thrash.
+
+## 3. Hard rules
+
+- Never edit `## Acceptance` in `spec.md`, never delete or weaken a test to make it pass, never disable a gate. If you believe the spec or a test is wrong, stop and explain.
+- Never mark a task as passing without running its verification in this session.
+- Stay inside the feature's scope. Note unrelated problems you find in `progress.md` under "Noticed" instead of fixing them.
+- Don't commit secrets, generated artefacts or debugging leftovers.
+
+## 4. End of session (always)
+
+Append to `progress.md`:
+
+```
+## <ISO date> · build
+- Done: T2 (saved cart API), verified with `npm test -- carts` + manual POST
+- State: gates green, 2/5 tasks passing
+- Next: T3 (UI list); watch out for the cart total rounding in utils/money.ts
+```
+
+When every task passes: set status to `verify`, append a `history` entry, and continue with `/buildline-verify <id>` (or tell the person to).

package/templates/stations/buildline.md

@@ -0,0 +1,48 @@
+# Station: front door
+
+You are the factory's front desk. Your job is to work out what the person needs and send them to the right station. Keep it short: people use this to get unstuck, not to read essays.
+
+## 1. Read the floor
+
+- Read `.buildline/buildline.json` (autonomy level, gates, team roles).
+- List `.buildline/features/*/feature.json`. For each, note `id`, `title`, `type`, `status`, `owner`, open approvals, and task progress (`passes: true` count / total).
+- If `.buildline/context/product.md` still contains `TODO`, the factory has not been onboarded yet.
+
+## 2. Show a compact status
+
+```
+Buildline · <project> · autonomy L<n>
+  003  Checkout redesign       design   ▸ waiting on design approval
+  004  Fix double-charge bug   build    ▸ 2/3 tasks passing
+  005  Saved carts             spec     ▸ needs acceptance scenarios
+```
+
+Then say the single most useful next action and the exact command, for example: "Next: `/buildline-build 004` to finish the last task."
+
+## 3. Route the request
+
+If the person said what they want (`$ARGUMENTS` or their message), route it:
+
+| They want to… | Send to |
+|---|---|
+| set up / refresh the factory, "where do I start" on a new repo | `onboard` |
+| report a bug, propose an idea or feature | `new` |
+| write or refine requirements | `spec` |
+| work on UX, screens, flows, or technical approach | `design` |
+| break work into tasks | `plan` |
+| implement | `build` (or `autopilot` if autonomy ≥ 3 and the plan is approved) |
+| check if something works | `verify` |
+| review a change | `review` |
+| open a PR / release / wrap up | `ship` |
+
+If onboarding is missing, recommend `onboard` first but don't force it for a quick fix.
+
+Hand over by reading `.buildline/stations/<station>.md` and continuing with it in the same session; tell the person which station you're running.
+
+## Role hints
+
+Adapt your language to who is asking. If unsure, ask once: "Are you working on this as a PM, designer, or developer?"
+
+- **PMs** care about scope, acceptance, status and trade-offs. Avoid code details unless asked.
+- **Designers** care about flows, states, components and visual consistency. Point them to `spec.md → ## Design` and `.buildline/context/design.md`.
+- **Developers** want the next task, the gates, and the diff.

package/templates/stations/design.md

@@ -0,0 +1,39 @@
+# Station: design
+
+Goal: decide *how it should look and behave* (UX) and *how it should be built* (technical design) before anyone writes production code. Owners: designer for UX, engineer for technical design. Skip either half if it doesn't apply, and say so.
+
+Resolve the feature from `$ARGUMENTS`, or use the most recent feature with status `design`.
+
+Read `spec.md` (Brief, Requirements, Acceptance), `.buildline/context/design.md` and `.buildline/context/architecture.md`.
+
+## Part A: UX design (`spec.md → ## Design → ### Experience`)
+
+Work with the designer. Ask what they already have (Figma link, screenshots, sketches, a reference product) and start from that. If they share images, describe what you see and confirm your reading.
+
+Write down, briefly:
+
+1. **Flow**: the steps the user takes, as a numbered list or a small mermaid flowchart. Include the entry point and where they end up.
+2. **Screens and states**: for every screen or component, list the states: default, loading, empty, error, success, disabled, and any permission variants. Missing states are the most common design bug.
+3. **Components**: which existing components from the design system are reused (with file paths). Anything new needs a one-line justification.
+4. **Content**: key labels, messages and error copy. Plain language; say what happened and what to do next.
+5. **Accessibility**: keyboard path, focus order, labels for icon-only controls, contrast, motion. Meet WCAG 2.2 AA unless `principles.md` says otherwise.
+6. **Responsive behaviour**: what changes at small widths.
+
+Use design tokens from `.buildline/context/design.md` by name. Never invent raw hex values or pixel sizes if a token exists.
+
+Optional: for visual work, build a quick throwaway prototype (a single HTML file or a story) and share a screenshot before committing to the build. Ask the `buildline-design-reviewer` subagent to check the design against the design system and the acceptance scenarios.
+
+## Part B: Technical design (`spec.md → ## Design → ### Technical`)
+
+1. **Approach**: the chosen approach in a few sentences, plus the strongest alternative and why it lost.
+2. **Changes**: modules and files to add or change, data model or schema changes, API contracts (request/response shapes), events.
+3. **Risks**: migrations, performance, security, backwards compatibility, feature flags. How each is mitigated.
+4. **Test strategy**: which acceptance scenarios are covered by unit, integration or end-to-end tests, and how they'll be run.
+
+Follow the conventions in `architecture.md`. If you're breaking one, say so explicitly.
+
+## Handoff
+
+- Set status to `plan`. Append a `history` entry.
+- **Approval:** at autonomy L1, ask for explicit design approval and record `approvals.design` only when given. At other levels, the designer can approve UX in the dashboard; flag the feature as waiting for design approval if UX changed and nobody has approved it yet.
+- Next: `/buildline-plan <id>`.

package/templates/stations/new.md

@@ -0,0 +1,39 @@
+# Station: intake (new)
+
+Goal: turn a raw idea, request or bug report into a feature folder with the right size and a one-paragraph brief. This should take a couple of minutes, not an hour.
+
+## 1. Understand the request
+
+From `$ARGUMENTS` or the conversation, get:
+
+- **What** should change, in the user's words.
+- **Why** it matters (who is affected, what it costs them today).
+- For bugs: steps to reproduce, expected vs actual behaviour, and where it was seen.
+
+Ask at most two clarifying questions. If something is still unknown, write it down as an open question in the brief instead of blocking.
+
+## 2. Size it
+
+Look at the code briefly (search, don't read everything) and pick a type:
+
+- `fix`: a bug or a small, well-understood change; roughly one file or one component; no new UX decisions.
+- `feature`: new behaviour or UI, touches several modules, or needs a product or design decision.
+- `epic`: more than one PR's worth, or several independent user outcomes. Plan to split it.
+
+State the type and the reason in one line. The person can override.
+
+## 3. Create the feature
+
+Preferred: run `npx buildline new "<title>" --type <type>`. It creates `.buildline/features/<id>-<slug>/` with `feature.json`, `spec.md` and `progress.md`.
+
+If the CLI isn't available, do it by hand: next id = highest existing id + 1, zero-padded to 3 digits; slug = kebab-case title (max 5 words); copy the files from `.buildline/templates/`.
+
+Then fill in `spec.md → ## Brief` (problem, who, outcome, open questions) and set `owner` in `feature.json` if the person told you who owns it.
+
+## 4. Route
+
+- `fix` → set status to `build`. In `spec.md`, also fill `## Acceptance` with a single scenario that reproduces the bug (it must fail before the fix). Next: `/buildline-build <id>`.
+- `feature` → status `spec`. Next: `/buildline-spec <id>`.
+- `epic` → status `spec`. Next: `/buildline-spec <id>`, which will end by proposing the split into child features.
+
+Append a `history` entry to `feature.json`: `{ "at": "<ISO date>", "station": "new", "note": "<type and one-line reason>" }`.

package/templates/stations/onboard.md

@@ -0,0 +1,57 @@
+# Station: onboard
+
+Goal: give every future agent session the context a new senior teammate would need on day one, in as few words as possible. Output lives in `.buildline/context/` and `.buildline/buildline.json`.
+
+First decide which path applies: if the repo has little or no source code it is **greenfield**; otherwise it is **brownfield**.
+
+---
+
+## Greenfield (empty or near-empty project)
+
+Run a short interview. Ask **one question at a time**, offer sensible defaults, and stop once you have enough. Skip anything the person has already told you.
+
+1. What are we building, in one sentence? Who is it for?
+2. What problem does it solve for them, and how do they solve it today?
+3. What does success look like in 3 months? (one or two measurable signals)
+4. What is in scope for the first release, and what is explicitly out?
+5. Platform and constraints: web, mobile, CLI, API? Any required stack, hosting, compliance, or budget limits?
+6. Look and feel: any brand, design system, or reference products?
+
+Then:
+
+- **Recommend a stack** that fits the answers. Give a one-line reason and one alternative. Prefer boring, well-documented choices that agents know well. Wait for confirmation (unless autonomy is L4).
+- **Scaffold** with the framework's official generator (e.g. `npm create vite@latest`, `npx create-next-app@latest`, `uv init`, `cargo new`). Don't hand-write what a generator produces.
+- Add a test runner and a linter if the generator didn't, plus one passing smoke test.
+- Fill in `buildline.json → gates` with the real commands and run `node .buildline/bin/gates.mjs` until it passes.
+- Write the context files (below) and commit: `chore: scaffold project and onboard buildline`.
+- Suggest the first features as `/buildline-new …` commands, ordered as a thin vertical slice first.
+
+## Brownfield (existing code)
+
+Don't interview first; read first. Delegate the reading to the `buildline-mapper` subagent if available (it keeps the main context clean), and ask it for a summary you can turn into the context files.
+
+What to find out:
+
+- **Product:** README, docs, landing copy, route names. What does it do, and for whom?
+- **Architecture:** entry points, main modules and their responsibilities, data stores, external services, how a request flows through the system.
+- **Conventions:** folder layout, naming, state management, error handling, testing patterns. Quote one real file path as the example for each convention.
+- **Design system:** tokens/CSS variables, theme files, component library, Storybook, icon set, spacing and type scales.
+- **Commands:** how to install, run, test, lint, type-check, build. Run them. A gate that doesn't run is worse than no gate.
+- **Hazards:** generated code, vendored folders, fragile areas, secrets, anything that must not be touched.
+
+Then ask the person only what code can't tell you: the product's goals, who the users are, what's planned next, and what "good" looks like to them.
+
+Update `buildline.json → gates` with commands you have **seen pass** (or note the ones currently failing in `progress` so nobody is surprised).
+
+---
+
+## Context files to write
+
+Keep each file under ~120 lines. Prefer bullet points and file paths over prose. Replace every `TODO`.
+
+- `.buildline/context/product.md`: vision, users, problems, success metrics, scope, non-goals, glossary.
+- `.buildline/context/architecture.md`: stack, module map, data flow, key decisions (with the reason), hazards.
+- `.buildline/context/design.md`: design principles, tokens, components, patterns, accessibility baseline, where the source of truth lives (Figma link, Storybook, token files).
+- `.buildline/principles.md`: review the defaults with the person and adjust. These are the rules every change is checked against.
+
+Finish with a short summary of what you learned, what's still unknown, and the recommended next step.