cohorte 1.0.0

package/core/templates/review-feedback.md

@@ -0,0 +1,36 @@
+# REVIEW REPORT
+
+feature_id: <feature_id>
+Feature branch: <feature_branch_prefix><feature_id>
+Commit SHA: <first 12 chars>
+
+| Severity | Count | Status |
+| -------- | ----- | ------ |
+| CRITICAL | 0     | pass   |
+| HIGH     | 0     | noted  |
+| MEDIUM   | 0     | noted  |
+| LOW      | 0     | -      |
+
+Verdict: <SHIP | REVISE | BLOCK>
+
+## Verdict rules
+
+- **SHIP** — no CRITICAL and no security issue. Cleared for the human's manual QA + `/ship`.
+- **REVISE** — one or more CRITICAL (spec violation / correctness). Must fix.
+- **BLOCK** — a security vulnerability. Must fix immediately.
+
+## Findings
+
+> Every finding is self-sufficient: a stateless agent must be able to act on it with no other
+> context. Order by severity. If none, write "None."
+
+- **[CRITICAL]** `<surface.path>/...:42` · spec-violation · <what's wrong vs spec §X> → **Fix:** <concrete change>
+- **[HIGH]** `<path>:88` · quality · <issue> → **Fix:** <concrete change>
+- **[BLOCK/security]** `<path>:line` · security · <vuln> → **Fix:** <concrete change>
+
+Each finding line format (so it pastes straight into the spec's `## Remediation`):
+`[<SEVERITY>] <file:line> · <spec-violation|quality|security> · <problem> → Fix: <concrete fix>`
+
+## Notes
+
+<optional: patterns to watch, things verified clean; RBAC / mobile-first assessment if the profile enables them>

package/core/templates/spec.template.md

@@ -0,0 +1,84 @@
+---
+feature_id: <slug>
+title: <Feature title>
+status: draft # draft → frozen → in-review → shipped
+branch: <feature_branch_prefix><slug>
+created: <YYYY-MM-DD>
+reviewed_base: # merge-base sha at the last SHIP verdict — freshness-gate anchor (written by /review)
+reviewed_digest: # sha256 (16 hex) of the reviewed source diff vs reviewed_base, specs excluded — /ship re-checks
+design_files: [] # design page links — full URLs of the form https://claude.ai/design/p/<projectId>?file=<file> (each carries its own project + page); blank until designed; omit if no UI
+---
+
+# <Feature title>
+
+## 1. Goal & user story
+
+<one paragraph: what · who · why>
+
+## 2. Scope
+
+**In:** …
+**Out (non-goals):** …
+
+## 3. Roles & permissions
+
+> Only if `PIPELINE.md` §rbac is enabled — which roles can do what; note the lowest-privilege experience.
+
+## 4. Data model & migrations
+
+> Additive only (never gate.deny commands). Omit if the feature has no persistence.
+
+| table | column | type | null? | default | notes |
+| ----- | ------ | ---- | ----- | ------- | ----- |
+|       |        |      |       |         |       |
+
+## 5. CONTRACT (frozen)
+
+> The only sync channel. Complete enough to build every surface independently. Uses the profile's
+> `contract.mechanism`. If `contract.enabled` is false, capture the interface precisely in prose here.
+
+### `<METHOD> /<path>` · auth: `<middleware/role>`
+
+- **Request** — params / query / body: `field` · type · required? · nullable? · validation
+- **Success** — `<status>` · response shape
+- **Errors** — `<status>` · when (422 validation · 401 · 403 · 404 · 409 …)
+
+<repeat per endpoint/interface>
+
+### Contract types — lead authors `<contract.path>/<slug>.<ext>` before /build
+
+- `<slug>...Request` / `<slug>...Response` / `<slug>Base` … (sketch the schemas here)
+
+## 6+. Surface tasks
+
+> One subsection per surface in `PIPELINE.md` §surfaces (e.g. backend, frontend), each TDD.
+
+### <surface.key>
+
+- …
+
+## 8. Design brief (the "spec return")
+
+> Only if the project has UI. Standalone; mirrors `.claude/templates/design-brief.md`.
+
+- **Screens / views:** …
+- **Flows:** …
+- **Responsive:** mobile (base) → `md:` → `lg:`
+- **States:** empty · loading · error · success
+
+## 9. Acceptance criteria / DoD
+
+- [ ] Every contract endpoint/interface implemented exactly
+- [ ] Each surface's tests (TDD) green
+- [ ] `PIPELINE.md` commands.lint · typecheck · test green
+- [ ] Mobile-first / responsive verified (if UI)
+- [ ] User-facing copy in `ui_language`
+
+## 10. Assumptions & open questions
+
+- …
+
+## Remediation
+
+> Filled by `/spec` in review-return mode; empty otherwise. Each item:
+> `[ ] <SEVERITY> · <file:line> · <spec-violation|quality|security> · <concrete fix>`

package/core/templates/steps/init-pipeline/01-detect-stack.md

@@ -0,0 +1,40 @@
+# /init-pipeline · 01 Detect the stack
+
+### Phase 1 — Detect the stack (read-only, no questions yet)
+
+Gather evidence, then summarize what you found. Look for:
+
+- **Package manager & workspaces:** root `package.json` (`packageManager`, `workspaces`),
+  `pnpm-workspace.yaml`, `turbo.json`, `nx.json`, `lerna.json`; lockfiles (`pnpm-lock.yaml`,
+  `package-lock.json`, `yarn.lock`, `bun.lockb`); or non-JS: `pyproject.toml`/`requirements.txt`,
+  `go.mod`, `Cargo.toml`, `Gemfile`, `composer.json`.
+- **Surfaces (independently-built areas):** `apps/*`, `packages/*`, `services/*`, `cmd/*`, or a single
+  root app. For each, detect its framework from its own `package.json`/config:
+  backend markers (`adonisrc.ts`, `@adonisjs/*`, `nestjs`, `express`, `fastify`, `django`, `fastapi`,
+  `rails`, `.go`), frontend markers (`vite.config.*`, `next.config.*`, `@tanstack/react-router`,
+  `angular.json`, `nuxt`, `svelte`), and its test runner (`@japa/*`, `vitest`, `jest`, `playwright`,
+  `pytest`, `go test`), linter/formatter (`eslint`, `prettier`, `biome`, `ruff`).
+- **Split candidates (sub-surface boundaries):** inside each surface, look for a clean internal partition
+  — feature modules (`src/features/*`, `src/modules/*`, `app/(group)/*`), or independent services
+  (`services/*`, domain folders). Note the surface's rough size (module/file count) so a *large* surface
+  with a *clean* boundary can be proposed as several specialized surfaces in Phase 2. See SCHEMA.md
+  §"Specialization — when to split one surface into more agents" for the heuristic. Don't split yet — just
+  flag candidates + their would-be shared-code tree.
+- **Per-surface commands:** derive `test`/`lint`/`format`/`typecheck`/`build` from each surface's
+  `package.json` scripts + the workspace filter syntax (e.g. `pnpm --filter <pkg> test`).
+- **Contract mechanism:** a shared types/schema package (`packages/shared-types`, Zod/`z.`),
+  an `openapi.*`/`swagger.*` file, `.proto` files, or none.
+- **DB / migrations:** migration tooling (`node ace make:migration`, `knex`, `prisma`, `alembic`,
+  `golang-migrate`), a `docker-compose.yml`, DB service.
+- **Design system:** an existing `design-reference/` snapshot, `components/ui`, a DesignSync MCP
+  connection, Figma links, or none.
+- **Code retrieval:** is the `serena` CLI resolvable (`command -v serena`)? If not, does
+  `~/.local/bin/serena` exist anyway — installed but PATH-broken (see SCHEMA.md §Code retrieval)?
+  `graphify`? Is either already registered in this repo's `.mcp.json` or `claude mcp list`? (Feeds
+  the retrieval question + Phase 4 wiring — default provider is `serena`.)
+- **VCS:** `git remote -v` → host + `owner/repo`; the default branch (`git symbolic-ref refs/remotes/origin/HEAD` or `git branch`).
+- **Existing `CLAUDE.md`** — read it; it may already state stack/conventions to fold in. **Existing
+  `PIPELINE.md`** — if present, this is a re-run: load it as the starting draft and only reconcile deltas.
+
+Print a compact **Detection Report**: layout, surfaces (with framework + commands), contract, DB,
+design, vcs. Mark each field `detected` / `guessed` / `unknown`.

package/core/templates/steps/init-pipeline/02-interview-gaps.md

@@ -0,0 +1,41 @@
+# /init-pipeline · 02 Interview the gaps
+
+### Phase 2 — Interview the gaps (AskUserQuestion)
+
+Ask ONLY what you couldn't confidently detect. Batch related questions. Cover:
+
+- **Surfaces & ownership** — confirm the surface list and each one's path + owning agent name. (If a
+  single-app repo, one surface.) Confirm the `tools` each agent needs (add `DesignSync` only to a
+  surface with `uses_design: true`), and each surface's `model` tier: `sonnet` (Recommended default —
+  implementers mostly apply a frozen contract, which Sonnet handles at a fraction of the Opus-lead
+  cost), `haiku` for purely mechanical surfaces (scaffolding), `inherit` only for surfaces with real
+  design decisions worth running on the lead's model.
+- **Specialization (only if Phase 1 flagged a large + cleanly-separable surface)** — offer to split it
+  into specialized sub-surfaces (e.g. `web-checkout`, `web-billing`) so `/build` runs them in parallel,
+  per SCHEMA.md §Specialization. If the human accepts, apply the rules: **shared code (routing, global
+  state, DS kit/tokens) becomes its own single-owner surface**, and cross-slice shapes go through the
+  contract. Default to NOT splitting when boundaries are tangled or slices are tiny — coarse is fine.
+- **Contract** — mechanism (`shared-types-zod` / `openapi` / `protobuf` / `json-schema` / `none`) and
+  where feature contracts are authored. If `none`, surfaces sync by the spec prose alone.
+- **UI language** — language of all user-facing copy.
+- **RBAC** — is there a role hierarchy? If yes, list it highest→lowest.
+- **Design system** — enabled? provider (Claude Design / Figma / none) + project ids + kit/token paths.
+- **Code retrieval** — confirm the provider (see SCHEMA.md §Code retrieval): `serena` (Recommended
+  default — live LSP symbol navigation, no index to maintain), `graphify` (persistent knowledge graph
+  over code + docs — better on very large or mixed code+docs repos, but needs an index step + rescans),
+  or `none`. Only demote from `serena` if the human objects or the provider CLI can't be installed.
+- **Isolation** — build features in parallel git worktrees with per-feature DB + ports, or just in the
+  main checkout? If worktrees: DB-per-worktree? port bases? compose file?
+- **Gate** — confirm the destructive commands to hard-deny and the ones to confirm-first (seed from the
+  detected DB/migration tooling + always git commit/push/merge/rebase/reset).
+- **Personas** — keep the default `/brainstorm` panel, or customize members for this domain?
+
+Prefer sensible defaults from Phase 1 as the first (Recommended) option in each question.
+
+- **Kanban** (optional) — mirror this project's pipeline (`/brainstorm`…`/ship`) onto an Obsidian
+  Kanban board? If the human says yes: confirm the shared vault path (`obsidian.vault_path` in
+  `~/.claude/cohorte.config.yaml`; ask if empty) and the board's location inside it (default
+  `<ProjectName>/Tasks.md`). Phase 4 creates the board and records the link. Default: no.
+
+> The **kanban** link is user-scoped (it points at a personal vault, so it never goes in the committed
+> `PIPELINE.md`), but IS wired here because it is per-project — see Phase 4.

package/core/templates/steps/init-pipeline/03-draft-profile.md

@@ -0,0 +1,10 @@
+# /init-pipeline · 03 Draft the profile
+
+### Phase 3 — Draft the profile (show, don't write yet)
+
+Assemble the full `PIPELINE.md` from the installer's `pipeline/PIPELINE.template.md` (resolve
+bundled-vs-global per the note above), filling the `yaml pipeline-profile`
+block and every prose section from Phases 1–2. **Keep it lean**: every stateless agent re-reads this
+file on every dispatch, so its length is a per-dispatch token+latency tax — terse rule-shaped
+conventions, no narration, no facts derivable from the code. **Show the human the drafted
+`PIPELINE.md` in a fenced block and get a go-ahead** before writing.

package/core/templates/steps/init-pipeline/04-write-render.md

@@ -0,0 +1,88 @@
+# /init-pipeline · 04 Write & render
+
+### Phase 4 — Write & render (after go-ahead)
+
+1. **Write `PIPELINE.md`** at the repo root (source: the installer's `pipeline/PIPELINE.template.md`).
+2. **Wire it into `CLAUDE.md`:** if `CLAUDE.md` exists, ensure it references the profile (add a line
+   near the top: `> Project profile & pipeline facts: **@PIPELINE.md**`). If not, create a minimal
+   `CLAUDE.md` with that reference + a one-paragraph project intro.
+3. **Render one agent per surface** — for each surface, follow SCHEMA.md §"Rendering / reconciling a
+   surface agent" (steps 2–3): render `.claude/agents/<agent>.md` from the installer's
+   `pipeline/implementer.template.md`, substituting `<SURFACE_AGENT>`, `<SURFACE_LABEL>`, `<SURFACE_PATH>`,
+   `<SURFACE_TOOLS>`, `<SURFACE_MODEL>`, `<PROJECT_NAME>`, and the surface-specific blocks
+   (`<SURFACE_EXTRA_NEVER>`, `<SURFACE_DESIGN_INPUT>`, `<SURFACE_TDD_STEP1>` — fill design-related ones
+   only when `uses_design`).
+   Leave `review.md` + `release.md` as-is (generic).
+4. **Generate `.claude/gate-config.json`** from the `gate` block — copy all four keys verbatim:
+   `{"deny": [...], "ask": [...], "ask_on_default_branch": [...], "default_branch": "<vcs.default_branch>"}`.
+5. **Write `.claude/settings.json`** permissions (`ask`/`deny` lists mirroring the gate, **plus an
+   `allow` list of the project's read-only / verification commands** so agents don't stall on
+   permission prompts: the detected per-surface `test_cmd`/`lint_cmd`/`typecheck_cmd`/`build_cmd`
+   and repo-wide `commands.*` equivalents as `Bash(<cmd>:*)` rules, plus read-only git —
+   `Bash(git status:*)`, `Bash(git diff:*)`, `Bash(git log:*)`. Never allowlist anything matching a
+   `gate.ask`/`gate.deny` pattern. Mention the human can widen it later with
+   `/fewer-permission-prompts`) + the hooks, **conditioned on the install mode:**
+   - **bundled:** register the PreToolUse `Bash` hook `.claude/hooks/gate.py` and the PostToolUse
+     formatter (detected formatter).
+   - **global:** the PreToolUse gate hook is
+     already in `~/.claude/settings.json` and reads this repo's `gate-config.json` — do **not** re-register
+     it here (double-registration double-prompts). It no-ops where its config is absent, so one
+     registration serves every repo; you only supply this repo's `gate-config.json`. Still write the
+     PostToolUse formatter hook + the permissions.
+   Preserve any existing custom keys.
+6. **Wire the retrieval provider** (skip if `retrieval.provider: none`):
+   - **serena:** if the `serena` CLI is missing, have the human install it (`uv tool install -p 3.13
+     serena-agent`) — or set the provider to `none` if they decline, and say `/update-pipeline` can wire
+     it later. If the binary exists (e.g. `~/.local/bin/serena`) but `command -v serena` fails,
+     recommend the PATH fix (`uv tool update-shell`, or add `~/.local/bin` to the shell profile) for
+     CLI use. Then register at **project scope** (committed `.mcp.json`, portable —
+     `--project-from-cwd` resolves the project at server start) using the **PATH-proof launcher**
+     from SCHEMA.md §Code retrieval (`sh -c 'exec "$(command -v serena || echo
+     "$HOME/.local/bin/serena")" start-mcp-server …'` — a bare `serena` entry dies with ENOENT when
+     Claude Code was launched from an environment without `~/.local/bin` on PATH; Windows-native
+     teams use the bare form + PATH instead). If `.mcp.json` already has a bare `serena` entry,
+     upgrade it to the launcher form rather than skipping. Add `.serena/` to the repo's `.gitignore`
+     (per-machine cache/config Serena creates on first launch). On a large repo, offer the one-off
+     `serena project index`. Finish with the **health check** from SCHEMA.md §Code retrieval and
+     report each result — if the static checks pass but the server isn't connected in this session,
+     say a session restart is needed; never report Serena wired on registration alone.
+   - **graphify:** have the human install it (`uv tool install graphify` then `graphify install`),
+     build the initial graph (`/graphify .`), and note it needs incremental rescans (`--update`) after
+     big changes.
+   - Either way the rendered agents already carry the provider's MCP tools in their `tools:` list
+     (step 3 / SCHEMA §Rendering); remind the human the new MCP server appears after a session restart.
+7. **Render the isolation scripts** (if `isolation.enabled`) from the installer's
+   `pipeline/scripts/*.template` to this repo's `scripts/new-feature.sh` and `scripts/remove-feature.sh`,
+   substituting the `__TOKENS__` (project
+   slug, DB pattern, port bases, compose file, branch prefix, install/dev/migrate commands, per-surface
+   env stanzas). `chmod +x` them. If isolation is disabled, skip and note features build in the main checkout.
+8. **Ensure `specs/_template.md`** exists (copy from the installer's `templates/spec.template.md` if missing).
+9. **Write the pointer** `.claude/pipeline.json` (committed — this is how a teammate who clones the repo
+   knows which core to install):
+   `{ "pipeline": "cohorte", "mode": "<bundled|global>", "core_version": "<contents of the
+   installer's pipeline/VERSION>", "install": "<per mode: bundled ⇒ \"npx cohorte install\"
+   note that the core is committed under .claude/; global ⇒ \"npx cohorte install --global\"
+   (or, without npm: curl -fsSL https://raw.githubusercontent.com/TheBidouilleAgency/cohorte/main/install.sh | sh -s -- --global;
+   Windows: install.ps1 -Global from the same repo)> " }`.
+   In **global** mode also add, near the top of `CLAUDE.md`, a one-liner:
+   `> Pipeline: global core — run the installer above if /brainstorm etc. are missing.`
+10. **CI workflow** (if `vcs.host: github` and no existing workflow already runs the profile's
+    checks): with the human's go-ahead, generate `.github/workflows/pipeline-ci.yml` — on
+    `pull_request` to `<default_branch>`: checkout, set up the `package_manager` toolchain,
+    `commands.install`, then `commands.lint` · `commands.typecheck` · `commands.test` (+ per-surface
+    `build_cmd`s that are non-empty). Derive the setup steps from the detected stack — mirror what a
+    sibling workflow does if one exists. `/ship` watches these checks before the merge.
+11. **Metrics sink & report buffer:** add `.claude/pipeline-metrics.jsonl` to `.gitignore` — `/build`,
+    `/review`, `/fix` and `/smoke` append per-dispatch evidence there (SCHEMA §Specialization reads it).
+    Also add `specs/reports/` — `/review` and `/smoke` stage their last report there so a `/fix` (or
+    `/spec` Mode B) survives a `/clear`; it's a derived buffer, not a versioned artifact.
+12. **Design system:** if `design.enabled` with a snapshot dir, note that `/align-ds` is active; else the
+    `/align-ds` command will no-op with a clear message.
+13. **Kanban** (only if the human opted in at Phase 2): wire it per SCHEMA.md §Kanban, writing into the
+    **global** `~/.claude/cohorte.config.yaml` (never into this repo — the board points at a
+    personal vault). Create the file from `pipeline/cohorte.config.template.yaml` if absent; set
+    `kanban.enabled: true` and `obsidian.vault_path` if it was empty. Add a `kanban.boards[<PIPELINE
+    name>]` entry with `board: <folder>/Tasks.md`. Then **create the board file**
+    `<vault>/<folder>/Tasks.md` (per §Kanban) if it doesn't exist — one column per `kanban.columns`
+    stage, in pipeline order. Finally run the §Kanban backfill so any spec already in `specs/` lands on
+    the board. Report the board path + the `obsidian://` URI. Skip silently if the human declined.

package/core/templates/steps/init-pipeline/05-report.md

@@ -0,0 +1,12 @@
+# /init-pipeline · 05 Report
+
+### Phase 5 — Report
+
+Print: the install mode (bundled core under `.claude/` vs global core in `~/.claude/` + the committed
+`.claude/pipeline.json` pointer), the files written/rendered, the surface→agent mapping, and the
+tailored workflow line, e.g.
+`/brainstorm → /spec → (design) → /build <id> → test → /review → /ship`. Tell the human to sanity-check
+`PIPELINE.md`, commit it, and run `/brainstorm` to start a feature. Note that this was the one-time
+setup: from now on `/update-pipeline` both refreshes the core AND reconciles the generated files
+(SCHEMA.md §Reconcile), and `/build` auto-grows surfaces — re-running `/init-pipeline` is only for deep
+stack changes (package manager, contract mechanism, surface overhaul).

package/dashboard/README.md

@@ -0,0 +1,54 @@
+# Dashboard — architecture
+
+A local web cockpit for the pipeline, launched with `npx cohorte dashboard`
+(see the [root README](../README.md#dashboard--a-local-web-cockpit) for user-facing docs).
+
+## Two halves: shipped runtime vs dev build
+
+```
+dashboard/
+  server/      → RUNTIME, dependency-free (node built-ins only). Shipped in the npm package.
+  app/         → DEV source: Vite + React. NOT shipped (see ../.npmignore-style dashboard/.npmignore).
+  dist/        → app/ built output. Shipped, served by server/. Git-ignored, rebuilt at publish.
+```
+
+- **`server/`** is plain node (`http`, `fs`, `child_process`) — no deps, so `npx … dashboard`
+  needs no install. It serves `dist/` as static files + a small JSON/stream API.
+- **`app/`** is a Vite+React app built to `dist/`. `npm run build:dashboard` (root) runs
+  `npm --prefix dashboard/app ci && … run build`; CI does this before `npm pack`/`publish`
+  (`.github/workflows/publish.yml`), and `dashboard/.npmignore` lets the git-ignored `dist/` ship.
+
+## Server modules (`server/`)
+
+| File | Responsibility |
+| --- | --- |
+| `index.js` | HTTP server, routing, static serving (SPA fallback), streamed actions, `--host`/bind |
+| `versions.js` | installed core vs npm latest (registry fetch → `npm view` fallback, 5-min cache) |
+| `doctor.js` | the `/doctor` checks reimplemented in JS → `/api/state` (profile, agents, gate, hooks, …) |
+| `yaml.js` | minimal block-YAML subset parser (for the `pipeline-profile` block + the config) |
+| `fleet.js` | tracked-project registry (`~/.claude/cohorte-dashboard.json`) + folder browse |
+| `kanban.js` | linked Obsidian board → columns/cards; PR enrichment + ship-date sort via `gh` |
+
+## API
+
+Read: `GET /api/versions`, `/api/state?project=`, `/api/fleet`, `/api/browse?dir=`,
+`/api/kanban?project=`. Mutate: `POST /api/projects` (add) · `DELETE /api/projects` (remove);
+`POST /api/action` — `{action:'install'|'update', scope, project}` (spawns the CLI),
+`{action:'reset', project, purgeSpecs}` (backup+wipe+reinstall), or
+`{action:'claude', command:'/init-pipeline'|'/update-pipeline', project}` (headless `claude -p`).
+Action responses stream chunked plain text ending in `__EXIT__ <code>`; the client reads the
+`ReadableStream` (`app/src/api.js` `streamAction`).
+
+## Security
+
+Binds `127.0.0.1` by default — the action endpoints **execute code**. `--host=ADDR` opts into
+exposing it (prints a warning). CORS is not enabled: the frontend is same-origin (served by the
+agent). If a hosted-frontend model is ever added, lock CORS to the exact frontend origin (never `*`),
+or any site could drive the local agent.
+
+## Dev loop
+
+```sh
+node bin/cli.js dashboard              # terminal 1: the node API on :4317
+npm --prefix dashboard/app run dev     # terminal 2: Vite on :4318, proxies /api → :4317
+```