@gredescerber/agent-crew 0.0.0-stage → 0.6.0

package/templates/product/.github/ISSUE_TEMPLATE/epic.yml

@@ -0,0 +1,22 @@
+name: Epic
+description: A large user scenario that is sliced into tasks.
+labels: ["epic"]
+body:
+  - type: textarea
+    id: scenario
+    attributes:
+      label: User scenario
+      description: What the user can do once the epic is done.
+    validations:
+      required: true
+  - type: textarea
+    id: tasks
+    attributes:
+      label: Tasks
+      description: Links to tasks (#N). Vertical slices, not layers.
+      value: |
+        - [ ] #
+  - type: textarea
+    id: demo
+    attributes:
+      label: How to demo

package/templates/product/.github/ISSUE_TEMPLATE/feedback.yml

@@ -0,0 +1,36 @@
+name: Feedback
+description: Tested the running app - what is wrong or what to improve. The product lead regularly turns feedback into tasks.
+labels: ["feedback"]
+body:
+  - type: dropdown
+    id: kind
+    attributes:
+      label: What is it
+      options: ["Bug", "Design / UX", "Functionality", "Idea"]
+    validations:
+      required: true
+  - type: textarea
+    id: did
+    attributes:
+      label: What you did
+      description: Steps to reproduce. A link to the page of the running app.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: What you saw
+      description: You can paste a screenshot (Ctrl+V).
+  - type: dropdown
+    id: severity
+    attributes:
+      label: How important
+      options: ["Breaks the demo", "Noticeable to stakeholders", "Minor"]
+    validations:
+      required: true

package/templates/product/.github/ISSUE_TEMPLATE/task.yml

@@ -0,0 +1,62 @@
+name: Task
+description: One task for one agent. Without acceptance criteria an agent will not take it.
+labels: ["status:needs-spec"]
+body:
+  - type: textarea
+    id: goal
+    attributes:
+      label: Goal
+      description: One sentence - why this task exists.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Given / When / Then. Every item must be verifiable by a test.
+      value: |
+        - [ ] Given ... When ... Then ...
+    validations:
+      required: true
+  - type: input
+    id: contract
+    attributes:
+      label: Contract
+      description: A link to a part of the contract, e.g. contracts/api.yaml#/paths/~1auth
+  - type: input
+    id: paths
+    attributes:
+      label: Allowed paths
+      description: For example web/src/features/auth/**
+  - type: input
+    id: after
+    attributes:
+      label: Dependencies
+      description: "After #N, #M - until they are closed the task stays in status:waiting (crew task promote moves it to ready)"
+  - type: input
+    id: req
+    attributes:
+      label: Brief requirements
+      description: Requirement IDs from docs/brief-analysis.md, e.g. R1, R3
+  - type: textarea
+    id: changes_acceptance
+    attributes:
+      label: Changes acceptance
+      description: "Only if the task changes EXISTING acceptance tests (e.g. because of feedback). One path per line: tests/acceptance/test_12_login.py. The task's PR cannot change any other existing tests (crew-guard)."
+  - type: textarea
+    id: out_of_scope
+    attributes:
+      label: Out of scope
+  - type: dropdown
+    id: risk
+    attributes:
+      label: Risk
+      options: ["low", "med", "high"]
+  - type: textarea
+    id: tests
+    attributes:
+      label: Required tests
+      value: |
+        - [ ] unit
+        - [ ] contract
+        - [ ] e2e (if it touches the demo path)

package/templates/product/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+Closes #
+
+**Agent:** `` <!-- claude/opus, codex/..., human -->
+
+## What was done
+-
+
+## Checks
+- [ ] `crew check` is green
+
+## Review checklist (filled in by a reviewer from another vendor, with evidence: file:line or test)
+- [ ] Behavior regressions / the demo path is not broken
+- [ ] Security assumptions (secrets, auth, untrusted input, prompt injection)
+- [ ] Data integrity and conformance to `contracts/`
+- [ ] Error handling (no swallowed exceptions, fallbacks for LLM/API)
+- [ ] Rollout safety (can be rolled back, main stays demo-ready)

package/templates/product/.github/workflows/crew-guard.yml

@@ -0,0 +1,45 @@
+# PR rules without a human "approve" button (crew guard). Sets the crew-guard commit status -
+# a required check in main's protection (crew github setup).
+#
+# Why pull_request_target and issue_comment: both events take THIS file and crew.config.json from main,
+# not from the PR branch, so a PR cannot weaken the check for itself. PR code is not run here -
+# only the file list and comments are read via the GitHub API, so write permissions are safe.
+#
+#   failure - the PR touches agent/CI rules or someone else's acceptance tests, or the reviewer asks for changes;
+#   pending - waiting for an agent review (crew pr review); success - can be merged (auto-merge will do it).
+name: crew-guard
+
+on:
+  pull_request_target:
+    types: [opened, synchronize, reopened, edited, labeled, unlabeled]
+  issue_comment:
+    types: [created, edited] # crew pr review writes a comment → recompute the status
+  workflow_dispatch:
+    inputs:
+      pr: { description: "PR number", required: true }
+
+permissions:
+  contents: read
+  pull-requests: read
+  issues: read
+  statuses: write # the crew-guard commit status
+
+jobs:
+  guard:
+    if: github.event_name != 'issue_comment' || (github.event.issue.pull_request && (contains(github.event.comment.body, 'crew:review') || contains(github.event.comment.body, 'crew:waive')))
+    runs-on: ubuntu-latest
+    concurrency:
+      group: crew-guard-${{ github.event.pull_request.number || github.event.issue.number || inputs.pr }}
+      cancel-in-progress: true
+    steps:
+      # checkout without ref → main (base). We do not take the PR branch: its code is not needed here and must not be executed.
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Install agent-crew (npm, pinned version)
+        run: npm install -g "${{ vars.CREW_HARNESS }}"
+      - name: crew guard
+        env:
+          GH_TOKEN: "${{ github.token }}"
+          PR: "${{ github.event.pull_request.number || github.event.issue.number || inputs.pr }}"
+        run: crew guard --pr "$PR" --report --json

package/templates/product/.github/workflows/crew.yml

@@ -0,0 +1,118 @@
+# Code checks: linter, types, tests from crew.config.json. They work the same for Claude, Codex, and humans.
+# PR rules (protected files, acceptance tests, agent review) live in crew-guard.yml, which runs from main.
+# Requires the variable CREW_HARNESS (Settings → Variables), e.g. @gredescerber/agent-crew@0.6.0
+# (installed from the public npm registry at a pinned version; no token).
+# Main's protection, the variable, and the labels are set up by `crew github setup --apply`.
+name: crew
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "*/15 * * * *" # return expired task leases
+  # closing an issue → tasks that were waiting for it (status:waiting) move to ready (job promote)
+  issues:
+    types: [closed]
+  workflow_dispatch:
+
+# Minimal permissions by default: the check job runs code from the PR (tests), so it needs no write access.
+# issues: write is only for sweep (returning expired leases) and promote (waiting → ready).
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  # The job name `check` is the required-check context in main's protection (crew github setup).
+  check:
+    if: github.event_name != 'schedule' && github.event_name != 'issues'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - uses: astral-sh/setup-uv@v6
+      - name: Install agent-crew (npm, pinned version)
+        run: npm install -g "${{ vars.CREW_HARNESS }}"
+      - name: Generated configs are up to date
+        run: crew adapters build --check --json
+      # On PRs the checks come from the base commit: an agent cannot "go green" by replacing check in crew.config.json with true.
+      # On push to main there is no base - crew.config.json from the commit itself is used.
+      - name: crew.config.json from the base commit (PR only)
+        if: github.event_name == 'pull_request'
+        env: { BASE_SHA: "${{ github.event.pull_request.base.sha }}" }
+        run: |
+          if git cat-file -e "$BASE_SHA:crew.config.json" 2>/dev/null; then
+            git show "$BASE_SHA:crew.config.json" > crew.config.json
+            echo "crew.config.json taken from base $BASE_SHA"
+          else
+            echo "::warning::The base commit has no crew.config.json - using the version from the PR"
+          fi
+      # Clean runner: without node_modules the lint/tsc/test steps from crew.config.json fail on every PR.
+      # Python dependencies are installed by `uv run` itself (it syncs the api/ environment before running).
+      - name: Product dependencies (web/, api/)
+        run: |
+          for d in web api; do
+            if [ -f "$d/package-lock.json" ]; then npm --prefix "$d" ci --no-audit --no-fund
+            elif [ -f "$d/package.json" ]; then npm --prefix "$d" install --no-audit --no-fund
+            fi
+          done
+      - name: crew check
+        run: crew check --json
+      - name: Event-mode compliance check (no-op unless event mode is configured)
+        env: { GH_TOKEN: "${{ github.token }}" }
+        run: crew compliance check --json
+
+  sweep:
+    if: github.event_name == 'schedule'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # crew merge-ready merges ready PRs
+      issues: write # change status labels and write release markers
+      pull-requests: write # recompute crew-guard and merge ready PRs
+      statuses: write # the crew-guard commit status
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Install agent-crew (npm, pinned version)
+        run: npm install -g "${{ vars.CREW_HARNESS }}"
+      - env: { GH_TOKEN: "${{ github.token }}" }
+        run: crew task sweep --json
+      # A same-vendor review is counted via fallback_minutes, but the status will not recompute without an event.
+      # Every 15 minutes we recompute crew-guard for open PRs (code and config come from main, PR code is not executed).
+      - name: Recompute crew-guard for open PRs
+        env: { GH_TOKEN: "${{ github.token }}" }
+        run: |
+          for n in $(gh pr list --state open --json number --jq '.[].number'); do
+            crew guard --pr "$n" --report --json > /dev/null || true
+          done
+
+      # Merge PRs that are ready but not auto-merged (risk:high, or auto-merge off): no agent session needed.
+      - name: Merge ready PRs
+        env: { GH_TOKEN: "${{ github.token }}" }
+        run: crew merge-ready --json
+
+      # Team status in one pinned issue (no LLM): who waits for a human, stale leases, PRs, idle members.
+      - name: Update crew digest
+        env: { GH_TOKEN: "${{ github.token }}" }
+        run: crew digest --post --json
+
+  # An issue was closed → waiting tasks whose crew:after are all closed become ready.
+  promote:
+    if: github.event_name == 'issues'
+    runs-on: ubuntu-latest
+    concurrency: { group: crew-promote, cancel-in-progress: false }
+    permissions:
+      contents: read
+      issues: write # change status labels and write a comment
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: Install agent-crew (npm, pinned version)
+        run: npm install -g "${{ vars.CREW_HARNESS }}"
+      - env: { GH_TOKEN: "${{ github.token }}" }
+        run: crew task promote --json

package/templates/product/AGENTS.md

@@ -0,0 +1,109 @@
+# AGENTS.md — rules for working in this repository
+
+This file is read by all agents (Claude Code via CLAUDE.md, Codex directly, and others).
+It is short on purpose. Details are in `agents/skills/*` and `docs/playbooks/*`; read them when needed.
+
+**Language.** Write everything that goes to GitHub (issues, PRs, comments, commit messages, review notes, handoffs) and to other agents in English. Talk to the human in the language the human uses with you.
+
+## Who we are
+A team of humans and AI agents builds a software project. Tasks live in GitHub Issues.
+Work is coordinated only through `crew` (CLI or the MCP tools `crew_*`). Do not make agreements "in chat".
+
+**Order:** brief (`docs/brief.md`) → brief analysis with a demo scenario (skill `crew-brief-analysis`) → plan (`crew-kickoff`) → approval → tasks → code.
+No product code is written before the plan is approved. Priority always goes to what is visible in the demo scenario.
+
+## The work cycle (mandatory)
+1. `crew task next [--area <area>] [--tier <low|mid|high>]` — what to do. It first hands out work that unblocks the team: `artifacts.kind: fix` (your PR is waiting for you: reviewer changes, red check, conflict with main), `merge` (merge a ready PR) or `review` (review per the skill `crew-review`), then tasks — first from your area (the `crew-team` block in `docs/prd.md`). Do what `next_actions` says.
+2. `crew task claim <id>` — take it. Work **only** in the created worktree/branch.
+3. Read the task (`gh issue view <id>`), especially the **acceptance criteria**.
+4. Tests for the acceptance criteria first, then the implementation.
+5. `crew check` — until it is green. Only a full run counts: `crew check --only <step>` is for debugging.
+6. `crew commit -m "feat: ..."` — a commit with trailers (do not use a bare `git commit`). Works only on the task's branch.
+7. `crew pr open` — submit the work. After review changes, `crew commit` and `crew pr open` again (a second PR is not created). Then `crew task next`.
+
+**Lease.** The task is yours while you are active: `crew check` and `crew commit` renew the lease themselves. If you think or wait for more than 30 minutes without them, run `crew task heartbeat <id>`. If a command returned `lease_lost`, the task was given to someone else: do not push your branch, leave a note in the issue about what you got done, and take a new task.
+
+Every `crew` command returns JSON: `status`, `summary`, `next_actions`, `artifacts`, `error`.
+**Do what `next_actions` says.** On an error look at `error.retry` and `error.stop_when`.
+
+## The executor and its subagents
+A task is taken by the **executor** — the agent that ran `crew task claim`. It is like a contractor: it may call its own subagents as needed, but **it submits the work and answers for it**.
+- Subagents may: search code and documentation, write tests and code on the executor's assignment, check the executor's code before submission (code-reviewer, security-reviewer), run `crew check`.
+- Executor only: `crew task next` / `claim` / `release` / `status`, `crew commit`, `crew pr open`. A subagent does not take a new task or submit a PR.
+- Subagents work in the task's worktree and in its area. In parallel — only reading and searching; edits to the same files go one at a time, otherwise they overwrite each other.
+- A subagent's review before submission is useful, but it is **not** the review for `crew-guard`: only a review by another agent counts (`crew pr review` not from the executor or its subagents).
+- Every subagent spends the subscription limits of whoever owns the laptop. Call them when it really speeds up the task.
+
+**Who gets what (saving limits).** The executor on the senior model thinks and verifies; cheaper helpers do the work:
+
+| Helper | Model (`crew.config.json → tiers`) | Assign |
+|---|---|---|
+| `scout` | low — Claude: haiku | searching code, reading documentation, running `crew check` with a brief retelling of errors. Changes nothing |
+| `implementer` | mid — Claude: sonnet | code or tests on a clear assignment: what, in which files, by which criteria |
+| the executor itself | high — Claude: opus | analyzing the task, decisions, contracts, verifying the helpers' work, `crew commit`, `crew pr open` |
+
+- Do not call the senior model as a subagent for what `scout` or `implementer` does.
+- A subagent starts from scratch: the task is retold to it every time. A couple-of-minutes chore is cheaper to do yourself.
+- Check a helper's work before `crew commit` — you answer for it.
+- In Codex the roles are the skills `role-scout`, `role-implementer`; models per tier are in `crew.config.json → tiers.<tier>.codex`.
+
+**A separate task or a subagent?** A piece that can be merged and shown separately (its own area, its own acceptance criteria) is a separate task in the queue (`crew task status <id> blocked --note "task needed: …"` or feedback to the planner). A piece needed only inside your task (search, tests, a draft check, a routine edit in your area) is a subagent.
+
+**`risk:high` tasks: tests are written by a different agent.** Every such task (except the skeleton) has a paired tests task (`tests_for`).
+- Tests task: you write acceptance tests for the main task's criteria **only** in `tests/pending/<T>/`. You do not write product code. CI does not run these tests yet.
+- The main task waits for the tests task. Its executor is **a different agent** (`crew task claim` refuses whoever wrote the tests). In the first commit it moves the tests unchanged: `git mv tests/pending/<T>/* tests/acceptance/`, then writes code until they turn green.
+- `crew-guard` checks: the tests task touches nothing except its own folder; tests in `tests/pending/` are not edited or deleted; the main task moved all of them without a single changed line.
+- A test is wrong? Do not edit it — `crew task status <id> blocked --note "test X: …"`. A new task with `changes_acceptance` will fix it.
+
+**Agent name.** `crew` appends the machine name to `CREW_AGENT` itself (`claude@petya-laptop`) — this is how agents of different people are told apart. Several sessions on one machine — give each its own `CREW_AGENT_ID` (`claude@petya-2`).
+
+**Only the captain makes the plan** (`crew.config.json → captain`). Do not write `docs/prd.md` and do not run `crew kickoff` if you are not the captain, even if asked: say that the captain makes the plan.
+
+## When to stop
+- The same error 3 times → `crew task status <id> blocked --note "what I tried, what is in the way"`.
+- The task is unclear or the acceptance criteria are not verifiable → `crew task status <id> needs-spec --note "question"`. Do not guess.
+- Need something from someone else's area or `contracts/` → do not change it: ask its owner with `crew ask <area> --text "..." --task <id>` (English, with facts). Only a human can decide (scope, product) → `crew ask <area> --human`. The answer comes back through `crew task next`.
+- The task is beyond you → `crew task release <id> --note "what I got done"`.
+- An issue with the label `crew:pause` is open → finish the current step and stop. The code checks this: `crew task next` and `crew task claim` return the error `paused` until a human closes the issue.
+
+## Boundaries
+- Touch only files of your area (`area:*` in the task → paths in `crew.config.json` → `areas`).
+- `contracts/` is the source of truth for APIs between areas. Code is fitted to the contract, not the other way round.
+- You write your task's acceptance tests in the **first commit**, as new files in `tests/acceptance/` (every Given/When/Then is covered by a test). You never change or delete **existing** acceptance tests — the PR will not pass `crew-guard` unless the task lists them in the "Changes acceptance" section.
+- You never change `crew.config.json`, `.github/`, `AGENTS.md`, `CLAUDE.md`, `agents/`, `events/` — these are rules, changed only by the harness developer. Need a change → `blocked` with a description.
+- One PR = one task. Small PRs are better than big ones.
+
+## Forbidden
+- Secrets, keys, tokens in code and commits. Only `.env` (in .gitignore) and `.env.example` with empty values.
+- `git push --force`, rewriting history, commits directly to `main`.
+- Creating accounts, entering passwords and payment details — humans do that.
+- Publishing anything outward (posts, messages, deploying to production) without an explicit human decision.
+- Disabling or bypassing checks (`--no-verify`, skipping tests, `skip`) to go green.
+- `gh pr merge --admin`, setting statuses by hand, reviewing your own PR, editing other people's `crew:review` markers.
+- `gh pr merge` on your own initiative. You merge only a PR that `crew task next` handed out as `kind: merge` (review exists, `check` and `crew-guard` are green). If main is not protected (a private repo on a free plan), GitHub will not enforce this — you do.
+
+## Definition of Done
+- [ ] All acceptance criteria are covered by tests, tests are green (`crew check`).
+- [ ] The contract is respected, the demo path (`tests/e2e/`) is not broken.
+- [ ] The PR is opened via `crew pr open`, with what was done in the description.
+- [ ] The review was done by **a different agent** (preferably of a different vendor: Claude's code is reviewed by Codex, and vice versa) per the skill `crew-review`, and the verdict was recorded with `crew pr review <n> --verdict approve`. The `crew-guard` status is green — after that the PR merges itself (`risk:high` is merged by the agent that `crew task next` hands `merge`).
+
+## Test levels
+| What | Requirement |
+|---|---|
+| Demo path | a happy-path E2E, on every merge to main. `main` is always demo-ready |
+| Area boundaries | contract tests on both sides |
+| The affected area | a regression test for every bug fix; explicit edge cases from the criteria |
+| LLM calls in tests | only through recorded fixtures, no network |
+
+## Style
+- Conventional Commits: `feat:`, `fix:`, `test:`, `refactor:`, `docs:`, `chore:`.
+- Formatting and lint are the automation's concern (`crew check`); do not spend review on them.
+- There are no hidden agreements: a rule that is not here or in the linter does not exist.
+
+## Where things are
+- `crew.config.json` — areas, checks, model tiers, MCP.
+- `agents/roles/` — roles (planner, builder, reviewer, integrator). `agents/skills/` — skills.
+- `contracts/` — API contracts. `tests/acceptance/`, `tests/e2e/` — acceptance and E2E tests.
+- `docs/brief.md` — the project brief as given. `docs/brief-analysis.md` — the analysis: **demo scenario**, requirements `R*`, stakeholder criteria. `docs/prd.md` — what we build (tasks reference `R*`). `docs/architecture.md` — how it is structured. `docs/playbooks/` — timeline, checklists, and the Issues rules (`issues.md`: statuses, labels, Definition of Ready).
+- `events/` — optional event mode (hackathon): the event's rules (time, team roster), compliance check, deadlines. Absent in a normal project.

package/templates/product/contracts/README.md

@@ -0,0 +1,8 @@
+# contracts/
+
+The source of truth for APIs between areas (web ↔ api ↔ external services).
+
+- `api.yaml` — OpenAPI 3.1. The architect writes it in the first hour, **before** parallel work starts.
+- Types and clients are generated from the contract (e.g. `openapi-typescript` for web, pydantic models for api).
+- Until the backend is ready, the frontend works against mocks from the contract (e.g. Prism: `npx @stoplight/prism-cli mock contracts/api.yaml`).
+- The contract may only be changed by a separate task with the label `area:contracts` and human review.

package/templates/product/docs/architecture.md

@@ -0,0 +1,41 @@
+# Architecture
+
+> Step 2 of the pipeline, written together with the PRD (planner/architect). In short: one page.
+> At the demo or review this is the answer to "how is it built" — keep it current.
+
+## Diagram
+
+```
+[web: React] ──HTTP──► [api: FastAPI/Node] ──► [DB]
+                              └──► [external APIs / LLM]
+```
+
+## Stack and areas
+
+| Area (`area:*`) | Technologies | Folder |
+|---|---|---|
+| web | | `web/` |
+| api | | `api/` |
+| contracts | OpenAPI 3.1 | `contracts/` |
+| e2e | Playwright | `tests/e2e/` |
+| infra | hosting, CI | `infra/`, `.github/` |
+
+## Contracts (draft)
+
+| Method | Path | Purpose | Demo step |
+|---|---|---|---|
+| POST | /auth/login | | 1 |
+
+The full version is `contracts/api.yaml` (a task with `area:contracts`).
+
+## Data
+
+Main entities and fields.
+
+## Deployment
+
+Where the running app lives, how main is deployed, who provided access.
+
+## Decisions and why
+
+- <decision> — <why this and not another>

package/templates/product/docs/brief-analysis.md

@@ -0,0 +1,62 @@
+# Brief analysis
+
+> Step 1 of the pipeline. Written by the analyst agent from `docs/brief.md` using the skill crew-brief-analysis. **Limit: 30 minutes.**
+> If we run out of time, we record assumptions and move on. Section order matters: the demo comes first.
+
+## 1. Demo scenario (3 minutes)
+
+What stakeholders (judges in event mode) will see so that we succeed. Scope is derived from here.
+
+| Step | What the user does | What stakeholders see | Requirements |
+|---|---|---|---|
+| 1 | | | R1 |
+| 2 | | | R2, R3 |
+| 3 | | | |
+
+**Wow moment:** <one phrase — what will be remembered>
+**Fallback plan if something does not work live:** <video / mocks / prepared data>
+
+## 2. Requirements
+
+IDs are stable: tasks in the PRD reference them (`req: [R1]`).
+
+| ID | Requirement (from the brief, in your own words) | Priority | In the demo? | Source in the brief |
+|---|---|---|---|---|
+| R1 | | must | yes | "quote of up to 15 words" |
+| R2 | | must | no | |
+| R3 | | should | | |
+| R4 | | could | | |
+
+Priority rules:
+- **on the demo path** → `must`, its tasks are `risk:high` and done first;
+- **a brief `must` but not in the demo** → done in a simplified way (a minimal working version);
+- **everything else** → `should`/`could`, as time allows; in the pitch — "planned".
+
+## 3. Constraints
+
+- Stack / mandatory technologies:
+- Partner/sponsor APIs (do we have keys? limits?):
+- Deployment and delivery format:
+- Rules (AI, prebuilt code, disclosure):
+
+## 4. Stakeholder criteria (judging criteria in event mode) → how we satisfy them
+
+| Criterion | Weight | How we satisfy it | Where it is visible in the demo |
+|---|---|---|---|
+| | | | step N |
+
+## 5. Ambiguities
+
+| # | Question | Whom to ask | Assumption until there is an answer |
+|---|---|---|---|
+| Q1 | | the brief's authors / organizers | we assume that … |
+
+## 6. Risks
+
+| Risk | Probability | What we do if it happens |
+|---|---|---|
+| A partner API is unstable | | mocks + recorded responses |
+
+## 7. What we deliberately do NOT do
+
+-

package/templates/product/docs/brief.md

@@ -0,0 +1,25 @@
+# Project brief
+
+> Step 0 of the pipeline. A human pastes the brief (the problem statement from the client, stakeholders, or event organizers) here **as is**, rewriting nothing.
+> Then the analyst agent turns it into `docs/brief-analysis.md` (skill crew-brief-analysis).
+
+- **Project / event:** <name>, <link to the page>
+- **Track / case:** <if any>
+- **Delivery deadline:** <date and time with time zone>
+- **Delivery format:** <repo / video / presentation / running app / form>
+
+## Brief (as is)
+
+<paste the full text of the assignment, with links and attachments>
+
+## Evaluation criteria
+
+<as is, with weights if given (judging criteria in event mode)>
+
+## Mandatory conditions
+
+<partner/sponsor APIs, mandatory technologies, constraints, rules on AI and prebuilt code>
+
+## What was said verbally / in chat
+
+<clarifications, answers to questions — with timestamps>

package/templates/product/docs/playbooks/issues.md

@@ -0,0 +1,91 @@
+# GitHub Issues rules
+
+Issues are the team's only task queue. Everything humans and agents need to know is here.
+
+## 1. Task lifecycle
+
+```
+needs-spec ──► ready ──► claimed ──► review ──► done
+    ▲            ▲          │  │
+    │            └──────────┘  └──► blocked ──► (a human sorted it out) ──► ready
+    └── agent: "criteria are not verifiable"
+```
+
+| Status | What it means | Who sets it |
+|---|---|---|
+| `status:needs-spec` | the task exists but cannot be taken: no verifiable criteria, or it waits for another task | the default template; the planner; an agent via `crew task status <id> needs-spec` |
+| `status:ready` | can be taken | **only the product lead or planner**, after a DoR check (section 3) |
+| `status:claimed` | an agent is working, the lease is running | only `crew task claim` |
+| `status:review` | a PR is open | only `crew pr open` |
+| `status:blocked` | a human is needed | an agent via `crew task status <id> blocked --note` |
+| `status:done` / closed | the PR is merged | GitHub closes the issue itself via `Closes #N` |
+
+The `claimed` and `review` statuses are never set by hand — only through `crew`. If something broke — `crew task release <id>`.
+
+## 2. How to write a task
+
+**Title** — a verb + a result visible to a user or the system:
+- ✅ "Login form: email + password, error on a wrong password"
+- ✅ "API: POST /auth/login per the contract"
+- ❌ "Authorization", "Do the backend", "Fix"
+
+**Body** — per the "Task" template (`.github/ISSUE_TEMPLATE/task.yml`):
+- **Goal** — one sentence, why.
+- **Acceptance criteria** — Given / When / Then, each verified by a test:
+  ```
+  - [ ] Given a user on /login, When they enter valid data and click "Sign in", Then they land on /dashboard
+  - [ ] Given a wrong password, When they click "Sign in", Then they see "Wrong email or password" and stay on /login
+  ```
+- **Contract** — a link to a part of `contracts/api.yaml`, if the task touches the API.
+- **Allowed paths** — which files may be touched.
+- **Out of scope** — what we definitely do not do (agents like doing extra).
+
+**Labels** (all three kinds are mandatory):
+- `area:<area>` — exactly one. A task for two areas → split into two.
+- `tier:low|mid|high` — how strong a model is needed (low: texts, small edits, tests; mid: a regular feature; high: architecture, the end-to-end skeleton, hard bugs).
+- `risk:high` — only if a mistake is expensive (auth, data, payments, the demo path). A human must look at such PRs.
+
+## 3. Definition of Ready — before setting `ready`
+
+- [ ] The title follows the rules of section 2
+- [ ] The acceptance criteria are verifiable by a test, with no "pretty", "convenient", "fast"
+- [ ] One area (`area:*`), `tier:*` is set
+- [ ] The task is 1–3 hours of agent work; bigger — split it
+- [ ] Dependencies are already `done` (or it is explicitly written which mocks we work against)
+- [ ] It is a **vertical slice**: the result can be shown or verified, not "a layer for the sake of a layer"
+
+## 4. Dependencies and epics
+
+- A task waits for another → `status:waiting` (or `status:needs-spec`) and a line in the body: `After #12`. When #12 is closed, the task becomes `ready` (`crew task promote`, or the product lead by hand).
+- An epic (the "Epic" template, label `epic`) is a user scenario with a task list `- [ ] #N`. Agents do not take epics.
+- Task #1 in any project is the **end-to-end skeleton** (web → api → DB, deploy, E2E hello-world). Until it is `done`, there are no parallel tasks in `ready`.
+
+## 5. Comments
+
+- Comments like `<!-- crew:claim ... -->`, `<!-- crew:heartbeat ... -->` are service comments: the lease is computed from them. **Do not edit or delete.**
+- On `blocked` / `needs-spec` / `release` an agent must leave a handoff: what is done, what is in the way, where the artifacts are. A human answers in the same issue.
+- Discussion of a task goes in its issue, not in chat: the next agent can restore the context only from here.
+
+## 6. Service issues
+
+| Issue | Purpose |
+|---|---|
+| `#ops-log` (pinned) | the integrator's reports, queue summaries |
+| an issue with the label `crew:pause` | **emergency stop**: while it is open, agents do not take tasks. Close it — work continues |
+
+## 7. Who is responsible for what
+
+| Role | Does |
+|---|---|
+| Product lead | moves tasks to `ready` per the DoR, holds the scope, cuts the extras, handles `needs-spec` |
+| Fleet operator | every 30–60 min looks at `crew status`, handles `blocked`, sets/clears `crew:pause` |
+| Planner (agent) | creates tasks and epics at kickoff and on re-slicing |
+| Builder (agent) | takes `ready`, submits a PR, honestly sets `blocked`/`needs-spec` |
+| Integrator (agent/human) | merges, writes to `#ops-log` |
+
+## 8. What not to do
+
+- Do not assign tasks to agents by hand (the assignee is set by `crew task claim`; the planner's `crew-team` assignment by area is the only exception).
+- Do not keep tasks without criteria in `ready` "so there is something to take" — an agent will do the wrong thing.
+- Do not create tasks like "fix everything" and "finish the frontend" — slice them.
+- Do not reopen a closed task for a new meaning — create a new one with a link.