cohorte 2.10.1 → 3.0.0-dev.0

package/profile/PIPELINE.template.md

@@ -1,259 +0,0 @@
-# PIPELINE.md — <PROJECT_NAME> profile
-
-> **Generated by `/cohorte-init-pipeline`.** This is the project profile: the single place the
-> portable multi-agent pipeline reads for everything stack-specific. The pipeline core
-> in the pipeline core is generic and references THIS file by section — keep project facts
-> here, never hardcoded into agent prompts. Kept current by `/cohorte-update-pipeline` (reconcile:
-> new fields are topped up, your values never overwritten). Rendered agent files are
-> regenerated from this profile on every reconcile — customize agents through §Conventions
-> here, never by editing the agent files. Free-form notes belong in `CLAUDE.md`.
->
-> **Machine block first, prose after.** The fenced `yaml pipeline-profile` block below is
-> the deterministic contract (flags, surfaces, commands) — commands parse it and branch on
-> it. The prose sections carry conventions agents read.
-
-```yaml pipeline-profile
-# ── identity ────────────────────────────────────────────────────────────────
-name: <PROJECT_NAME>
-one_liner: <one sentence: what this product is>
-ui_language: <English | French | …>          # language of ALL user-facing copy
-package_manager: <pnpm | npm | yarn | bun | pip | cargo | go>
-
-# ── vcs ─────────────────────────────────────────────────────────────────────
-vcs:
-  host: <github | gitlab | none>
-  remote: <owner/repo>                        # e.g. acme/webapp
-  default_branch: <main>
-  feature_branch_prefix: feature/            # branch = <prefix><feature_id>
-  patch_branch_prefix: fix/                  # same, for /cohorte-patch specs (kind: patch)
-
-# ── repo shape ──────────────────────────────────────────────────────────────
-repo:
-  layout: <monorepo | single>
-  workspace_tool: <turborepo | nx | none>
-
-# ── code retrieval (semantic navigation — cuts agent read time) ─────────────
-# Agents prefer symbol/graph MCP queries over grep-and-read when a provider is
-# wired. serena = live LSP symbol navigation (default, no index to maintain);
-# graphify = persistent tree-sitter knowledge graph over code + docs (needs an
-# index step + rescans); none = agents fall back to Grep/Glob/Read.
-# Registered by /cohorte-init-pipeline in the runtime's project MCP configuration.
-retrieval:
-  provider: serena                            # serena | graphify | none
-
-# ── surfaces ────────────────────────────────────────────────────────────────
-# One entry per independently-implemented code area. /cohorte-build dispatches ONE
-# implementer agent per surface, in parallel. Each surface is rendered by
-# /cohorte-init-pipeline into its own agent file (agent field) with the tools listed.
-# This list GROWS automatically: /cohorte-build §1.5 adds a surface (and renders its
-# agent) when a spec touches a tree no surface owns, or splits a bottleneck
-# surface into specialized sub-surfaces. Keep one owner per tree; shared code
-# (routing/state/DS) is its own single-owner surface. See SCHEMA.md §Specialization.
-surfaces:
-  - key: backend                              # short id, used as agent name + scope
-    path: apps/api                            # the ONLY tree this surface's agent may touch
-    label: backend (AdonisJS)
-    agent: backend                            # rendered in the runtime's project agents dir
-    tools: [Read, Write, Edit, Bash, Grep, Glob, mcp__serena]   # mcp__<provider> mirrors retrieval.provider
-<!-- cohorte:if runtime:codex -->
-    model: inherit                            # omit the TOML model pin; explicit Codex models also allowed
-<!-- cohorte:else -->
-    model: sonnet                             # frontmatter model tier: sonnet | haiku | inherit
-                                              #   sonnet = default (applies the frozen contract — cheap
-                                              #   vs the Opus lead); haiku = purely mechanical scaffolding;
-                                              #   inherit = only for surfaces with real design decisions
-<!-- cohorte:endif -->
-    test_cmd: pnpm --filter api test
-    # Bridled variants — what agents actually RUN (dot reporter / failures-only /
-    # --quiet), so a green run costs lines, not pages. "" ⇒ callers fall back to
-    # `<cmd> 2>&1 | tail -40`. /cohorte-init-pipeline asks for these; never store a bare
-    # `pnpm test` as the thing agents execute.
-    test_quiet_cmd: pnpm --filter api test --reporter=dot
-    lint_cmd: pnpm --filter api lint
-    lint_quiet_cmd: pnpm --filter api lint --quiet
-    format_cmd: pnpm --filter api format
-    typecheck_cmd: pnpm --filter api exec tsc --noEmit
-    build_cmd: ""
-    uses_design: false
-  - key: frontend
-    path: apps/web
-    label: frontend (React/TanStack)
-    agent: frontend
-    tools: [Read, Write, Edit, Bash, Grep, Glob, DesignSync, mcp__serena]
-<!-- cohorte:if runtime:codex -->
-    model: inherit                            # use the session model unless explicitly configured
-<!-- cohorte:else -->
-    model: sonnet                             # default even for design surfaces — designs + contract are
-                                              #   frozen inputs the agent applies; `inherit` (bills at the
-                                              #   lead's tier, often Opus) ONLY if this surface must make
-                                              #   novel design decisions
-<!-- cohorte:endif -->
-    test_cmd: pnpm --filter web test
-    test_quiet_cmd: pnpm --filter web test --reporter=dot
-    lint_cmd: pnpm --filter web lint
-    lint_quiet_cmd: pnpm --filter web lint --quiet
-    format_cmd: pnpm --filter web format
-    typecheck_cmd: pnpm check-types
-    build_cmd: pnpm --filter web build
-    uses_design: true
-
-# ── contract (the only cross-surface sync channel) ──────────────────────────
-contract:
-  enabled: <true | false>                     # false ⇒ no shared contract; skip §2 of /cohorte-build
-  mechanism: <shared-types-zod | openapi | protobuf | json-schema | none>
-  path: packages/shared-types/src             # where <feature_id>.<ext> is authored
-  ext: ts
-  index: packages/shared-types/src/index.ts   # barrel to export from, or "" if none
-  authored_by: lead                           # NEVER the implementer agents
-
-# ── release notes (optional) ────────────────────────────────────────────────
-# A per-feature release note the project's versioning tool consumes. When
-# enabled, /cohorte-ship authors it BEFORE dispatching the release agent, so it
-# ships inside the release commit. Repos whose CI fails a PR that lacks one
-# (Changesets' `changeset` job) MUST set this — otherwise every ship goes red.
-release_notes:
-  enabled: <true | false>                     # false ⇒ /cohorte-ship §2b is a no-op
-  tool: <changesets | none>                   # what consumes the file
-  dir: .changeset                             # where the note is authored
-  filename: "<feature_id>.md"                 # one file per feature
-  anchor_package: shared-types                # sole key in the front-matter; a lockstep/fixed group propagates the bump
-  language: <ui_language | English>           # language of the note's prose
-  forbid_levels: []                           # bumps project policy refuses, e.g. [major] while 0.x
-  empty_cmd: "pnpm changeset --empty"         # when no version should move; "" if the tool has no such escape hatch
-  ci_job: changeset                           # CI job that fails when the note is missing (name it so /cohorte-ship §5 recognizes the red)
-  guidance: |                                 # rules the lead follows when writing the note (project policy)
-    major = the deploy needs an operator action; minor = a user-visible capability;
-    patch = fix/perf/refactor with no change of use. No client names, no internal
-    paths, no exploitable attack vector.
-
-# ── repo-wide commands (root unless noted) ──────────────────────────────────
-commands:
-  install: pnpm install
-  dev: pnpm dev
-  lint: pnpm lint
-  lint_quiet: pnpm lint --quiet              # bridled variant (see surfaces[].*_quiet_cmd)
-  format: pnpm format
-  typecheck: pnpm check-types
-  test: pnpm test
-  test_quiet: pnpm test --reporter=dot       # bridled variant — what the /cohorte-review preflight runs
-  # migration commands — omit / leave "" if the project has no DB migrations
-  migrate: "cd apps/api && node ace migration:run"
-  make_migration: "cd apps/api && node ace make:migration"
-
-# ── rbac (optional) ─────────────────────────────────────────────────────────
-rbac:
-  enabled: <true | false>
-  hierarchy: [super-admin, admin, editor, member]   # highest → lowest, or []
-  note: "the platform must serve EVERY role, not just admins"
-
-# ── design system (optional) ────────────────────────────────────────────────
-design:
-  enabled: <true | false>                     # false ⇒ /cohorte-align-ds + design gates are no-ops
-  provider: <claude-design | figma | none>
-  design_system_project: <uuid-or-id>         # the UI-kit source of truth
-  design_project: none                        # legacy fallback for bare-filename design_files only; keep `none` — new specs use full links that carry their own project, so nothing here goes stale on a DS rebuild
-  snapshot_dir: apps/web/design-reference     # committed DS snapshot for /cohorte-align-ds diff
-  direction: design-to-code                   # NEVER push code→design for a curated DS
-  ui_kit_path: apps/web/src/components/ui
-  tokens_path: apps/web/src/index.css
-
-# ── isolation / parallelism (optional) ──────────────────────────────────────
-isolation:
-  enabled: <true | false>                     # false ⇒ features run in the main checkout
-  unit: git-worktree
-  db_per_worktree: <true | false>
-  db_name_pattern: "<name>_<id>"              # e.g. myapp_<id>
-  port_base: { api: 3333, web: 5173 }         # each worktree gets base+slot
-  compose_file: docker-compose.yml
-  registry: .worktrees/slots.tsv
-
-# ── gate (drives the pipeline gate hook + permissions) ─────────────────────
-# Confirm-first or hard-deny on dangerous Bash, inspecting the FULL command
-# string (so chained `cd x && …` forms are caught).
-gate:
-  # Three tiers. `deny` = always hard-blocked. `ask` = always confirm (branch-independent risk).
-  # `ask_on_default_branch` = confirm ONLY when the checked-out branch is `default_branch`; on
-  # feature branches these run freely. gate.py resolves the branch at run time (git rev-parse);
-  # unknown branch (no repo / detached) ⇒ gated, to stay safe. Keep git + docker here so agents
-  # move fast on feature branches but main stays protected.
-  default_branch: main                        # the protected branch (mirror vcs.default_branch)
-  deny:                                       # never allowed, on any branch
-    - "node ace migration:fresh"
-    - "node ace migration:reset"
-    - "node ace migration:rollback"
-    - "node ace db:wipe"
-  ask:                                         # always confirm, on any branch
-    - "node ace migration:run"
-    - "node ace db:"
-    - "psql"
-  ask_on_default_branch:                        # free on feature branches, confirm on default_branch
-    - "git commit"
-    - "git push"
-    - "git merge"
-    - "git rebase"
-    - "git reset"
-    - "docker compose"
-  # Phase gate: review dispatches require a fresh `preflight.ok` stamp,
-  # written by pipeline/scripts/preflight.sh when typecheck+lint+tests are green —
-  # gate.py "ask"s the dispatch when the stamp is missing, stale, or the code changed since.
-  # The stamp is local: keep `preflight.ok` gitignored, never committed.
-  preflight:
-    enabled: true
-    agents: [review]                          # subagent_types the stamp gates
-    max_age_minutes: 30
-
-```
-
-> **Note.** The **kanban** board link is **user-scoped** — NOT configured here. Its facts live in the
-> consolidated user config (`~/.claude/cohorte.config.yaml`, or `~/.cohorte/cohorte.config.yaml` on
-> a non-Claude runtime), read at runtime (the kanban board is keyed by this
-> profile's `name`). This project profile only governs the dev pipeline (`/cohorte-brainstorm…/cohorte-ship`).
-
----
-
-## Conventions
-
-> Read by the implementer + review agents. Keep these terse and rule-shaped; the machine
-> block above holds the paths/commands they enforce against.
-
-### Shared
-
-- User-facing copy (API messages, UI text) in **<ui_language>**.
-- <e.g. Zod v4 syntax `z.email()`/`z.uuid()`; ESM `.js` import extensions — project-specific>
-
-### Surface: `backend` (`apps/api`)
-
-- <one-action controllers · validator on every write · standardized response envelope · base model / UUID PK · `#`-alias imports · additive-only migrations · …>
-
-### Surface: `frontend` (`apps/web`)
-
-- <file-based routes with loaders/guards · domain `lib/api` modules over the shared client · design-system primitives, `cn()`+CVA · **mobile-first, fully responsive** · consume contract types, never redefine · …>
-
-### Testing — strict TDD (red → green → refactor)
-
-- <backend test runner + what a contract test must cover (status, validation, auth, payload) · DB isolation per test>
-- <frontend test runner + what to cover (hooks, api modules, component behavior); note layout is not unit-testable>
-
----
-
-## Design brief note (feeds `/cohorte-spec` §8 and Claude Design)
-
-- <design system name + primitives to use · mobile-first · copy language · brand/theming constraints>
-- A feature lists its design pages in the spec front-matter `design_files` as **full links** of the form
-  `https://claude.ai/design/p/<projectId>?file=<file>` — each carries its own project (`/p/<projectId>`)
-  and page (`?file=`), so an agent extracts both and reads it via `DesignSync get_file(<projectId>,
-  <file>)`. Paste the link at `/cohorte-build`'s design gate. No stored project id ⇒ a design-system rebuild
-  (new project) just means pasting the new links. (Bare file names are legacy, resolved in `design_project`.)
-
----
-
-## Personas for `/cohorte-brainstorm` (optional — the panel)
-
-<Panel members with a job AND a personality who challenge the idea from their angle and
-disagree with each other. Include a role-coverage guard if `rbac.enabled`. Example:>
-
-- **PM** (pragmatic, scope-cutting) — real value? what do we drop?
-- **Skeptical senior engineer** (blunt) — feasibility, edge cases, tech debt.
-- **UX/product designer** — mobile-first flows, accessibility, empty/error states.
-- **Security & RBAC** (paranoid) — permission leaks, cross-tenant exposure, least privilege.
-- <one persona per RBAC role so the feature serves every role, not just admins>