@gredescerber/agent-crew 0.0.0-stage → 0.6.0

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

@@ -0,0 +1,28 @@
+# Preflight — before the project starts
+
+Items marked (event mode) apply only when the project is run as an event such as a hackathon.
+
+## Rules
+- [ ] (event mode) The event's rules are read: is AI allowed? is disclosure required? is prebuilt code allowed in advance?
+- [ ] (event mode) `events/event.json` is filled in: start/end time, `team_members` (GitHub logins of team members only)
+
+## Accounts and access (done by humans, not agents)
+- [ ] Frontend and backend hosting, DB, auth service — accounts are created, someone on the team has access
+- [ ] API keys (LLM, partners/sponsors) — in a shared password manager, **not in the repo**
+- [ ] The GitHub organization, everyone on the team has permissions, Actions are enabled
+- [ ] The repo is set up: `crew github setup` (see the plan) → `crew github setup --apply` — protection of `main`, the variable `CREW_HARNESS`, labels
+- [ ] On a test PR the `crew-guard` status appears: `pending` without a review, `success` after `crew pr review <n> --verdict approve` from another agent
+
+## Machines
+- [ ] Everyone: `crew doctor` is green (node, git, gh authorized, claude/codex installed)
+- [ ] Windows: `git config --global core.longpaths true` (otherwise git fails on long worktree and `node_modules` paths)
+- [ ] Codex: the project is marked as trusted (otherwise it will not read `.codex/config.toml`)
+- [ ] Claude Code: the ECC plugin is installed
+- [ ] Subscription limits are checked and there are spare API keys
+
+## Network and fallbacks
+- [ ] 2+ people have mobile internet to share
+- [ ] A plan for "what we show if everything is down": a recorded demo video
+
+## Human roles
+- [ ] Product lead (acceptance criteria, scope), Architect (contracts), Fleet operator (workers, unblocking, `crew:pause`), Demo owner (demo, E2E, pitch)

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

@@ -0,0 +1,52 @@
+# Project timeline
+
+Agents write the code. Humans decide, approve, test, and present. Every phase has a **time limit and an action when it runs out** — the pipeline does not stall if someone gets stuck or falls asleep.
+
+In a normal project the limits are guidelines; scale the absolute numbers to the project. In event mode (hackathon) `T` is the delivery deadline from `events/event.json` and the `T−n` phases are enforced by deadlines.
+
+## Phases
+
+| # | Phase | Who | Limit | Done when | Ran out of time → |
+|---|---|---|---|---|---|
+| 0 | **Brief** | human | 10 min | the brief as is in `docs/brief.md` | — |
+| 1 | **Brief analysis** | the analyst agent (`crew-brief-analysis`) | 30 min | `docs/brief-analysis.md`: **demo scenario**, `R*`, stakeholder criteria, assumptions | hand in with assumptions |
+| 2 | **Plan** | planner (`crew-kickoff`) | 30 min | `docs/prd.md` + `architecture.md`, `crew task lint` is green | cut the scope to the demo path |
+| 3 | **Approval** | product lead | 15 min | the PRD has `status: approved` | **after 20 min without an answer** the planner sets `approved by: auto-timeout` |
+| 4 | **Tasks** | planner: `crew kickoff --apply` | 5 min | issues are created | — |
+| 5 | **Skeleton + contracts** | 1–2 agents, `risk:high` | 90 min | web → api → DB is deployed, the E2E hello-world is green, `contracts/api.yaml` | a human looks at what blocks (often — access) |
+| 6 | **Build** | all workers | until T−6 | tasks are moving, main is green | — |
+| 7 | **Freeze** | the product lead announces | T−6 | from here only fixes and polish | — |
+| 8 | **Demo** | demo owner + agents | T−3 | the demo-path E2E is green, **a fallback video is recorded** | show the video |
+| 9 | **Pitch** | humans | T−2 | slides, answers to "how is it built" (`architecture.md`) | — |
+| 10 | **Delivery** | human | T−1 | (event mode) `crew compliance check`, `crew compliance disclosure`, submission | — |
+
+**From the brief to the first task in progress — no more than 75 minutes.** This is the main guide for phases 0–4.
+
+## Merging is continuous
+- **Humans have no approve button.** `risk:low` / `risk:med` merge themselves (GitHub auto-merge) when `check` and `crew-guard` are green: the review was done by another agent (`crew pr review`), the rules and other people's acceptance tests are untouched.
+- Humans do not approve, they **notice**: they test the running app, write feedback (the "Feedback" issue), and the planner turns it into tasks. Went completely wrong — `crew:pause`.
+- `risk:high` (skeleton, auth, data, contracts, demo path) is merged by the integrator manually and **first** — everything else stands on it.
+- Tasks with status `waiting` move to `ready` as soon as their dependencies are closed.
+- **Main is red** → all workers fix main, no new tasks are taken. Red for more than 30 minutes → an issue `crew:pause`, call the humans.
+
+## Humans: roles and shifts
+
+| Role | Does |
+|---|---|
+| **Product lead** | approves the plan, holds the scope, triages feedback every hour, announces the freeze |
+| **Architect** | looks at the contracts and the skeleton, decides contested technical questions |
+| **Fleet operator** | watches the workers (`crew status`, `crew metrics`), unblocks `blocked`, subscription limits, `crew:pause` |
+| **Demo owner** | the demo scenario, the demo-path E2E, video, slides, pitch |
+
+All four **test the running app and write feedback** (the "Feedback" template in Issues): what they did, what they expected, what they saw. Every hour the product lead turns feedback into tasks or PRD changes.
+
+**Shifts:** at night at least one person (the fleet operator) is reachable. At night workers take only `risk:low`/`risk:med`; `risk:high` waits until morning if nobody can watch.
+
+## The brief changed along the way
+1. A human adds the changes to `docs/brief.md` (the "What was said verbally / in chat" section).
+2. The analyst updates `brief-analysis.md`: **do not renumber old `R*`**, new ones get new numbers, dropped ones are marked "dropped".
+3. The planner edits the PRD, the product lead approves, new tasks — `crew kickoff --apply` (already created ones are skipped).
+4. Tasks that are no longer needed are closed by the product lead by hand as "not planned".
+
+## Scope rule
+1–2 scenarios from the demo, taken to the end, beat 10 half-done. Everything that is not in the demo scenario is cut first.

package/templates/product/docs/prd.md

@@ -0,0 +1,58 @@
+<!-- crew:prd status: draft by: - at: - -->
+# PRD: <product name>
+
+> Written by the planner from `docs/brief.md` and `docs/brief-analysis.md` (skill `crew-kickoff`), at most one page of text + task blocks.
+> Block format — `agents/skills/crew-kickoff/task-format.md`. Check: `crew task lint`. Plan: `crew kickoff`.
+> The header on the first line is the approval. `crew kickoff --apply` creates issues only with
+> `<!-- crew:prd status: approved by: <github-login> at: <ISO-time> -->`
+> (no answer from the product lead in 20 minutes — the planner sets `by: auto-timeout`).
+
+## Problem and who it is for
+
+<1–2 sentences>
+
+## Demo path
+
+The steps stakeholders will see in the demo (judges in event mode). Requirements on this path are must, `risk: high`, done first.
+
+1. <step> — R1
+2. <step> — R2
+3. <step> — R3
+
+## Scenarios
+
+- <main scenario 1>
+
+## NOT doing
+
+- <what was deliberately cut>
+
+## Stakeholder criteria (judging criteria in event mode) → how we satisfy them
+
+| Criterion | How we satisfy it |
+|---|---|
+| <from docs/brief.md> | <task / epic> |
+
+## Stack
+
+From `crew.config.json → stack`; skeleton generators — `crew.config.json → scaffold`.
+
+## Epics and tasks
+
+The first `crew-task` block is always the end-to-end skeleton. The other tasks implicitly wait for it (no need to write `after`).
+
+```crew-task
+id: T1
+title: End-to-end skeleton web → api → deploy
+area: infra
+tier: high
+risk: high
+skeleton: true
+paths: [web/**, api/**, infra/**, .github/**]
+goal: An empty app builds, deploys, and answers an E2E hello-world
+acceptance:
+  - Given a clean repository When I run the generators from crew.config.json → scaffold Then crew check is green
+  - Given a deployed environment When I open the home page Then I see the api /health response
+tests: [e2e]
+req: [R1]
+```

package/templates/product/events/event.example.json

@@ -0,0 +1,10 @@
+{
+  "name": "Example Hackathon 2026",
+  "rules_url": "https://example.com/rules",
+  "start": "2026-12-05T10:00:00+03:00",
+  "end": "2026-12-07T10:00:00+03:00",
+  "ai_allowed": true,
+  "ai_disclosure_required": true,
+  "prebuilt_code": "tooling_only",
+  "team_members": ["github-login-1", "github-login-2"]
+}

package/templates/product/tests/acceptance/README.md

@@ -0,0 +1,9 @@
+# tests/acceptance/
+
+Acceptance tests for tasks' acceptance criteria. The builder writes them in the **first commit** of their task, before the implementation.
+
+- One file per task: `test_<issue>_<slug>.*` / `<issue>-<slug>.spec.ts`.
+- You may add new files. **Existing** ones are not changed or deleted: the `crew-guard` check rejects such a PR.
+- The exception is a task whose "Changes acceptance" section lists these files (the `changes_acceptance` field in the PRD). The planner/analyst writes it, usually from human feedback ("login must be by phone, not by email").
+- The reviewer agent checks that every Given/When/Then of the task is covered by a test and that the test is not fitted to the code.
+- For `risk:high` the tests are written by **a different agent** in a separate task, in `tests/pending/<T>/` (CI does not run them there). The main task's executor moves them here unchanged in the first commit: `git mv tests/pending/<T>/* tests/acceptance/`.

package/templates/stacks/web-fastapi.json

@@ -0,0 +1,74 @@
+{
+  "about": "React (Vite + TypeScript) + FastAPI (Python, uv). Frontend in web/, backend in api/, OpenAPI contract in contracts/.",
+  "areas": {
+    "web": [
+      "web/**"
+    ],
+    "api": [
+      "api/**"
+    ],
+    "contracts": [
+      "contracts/**"
+    ],
+    "e2e": [
+      "tests/e2e/**",
+      "tests/acceptance/**",
+      "tests/pending/**"
+    ],
+    "infra": [
+      "infra/**",
+      ".github/**",
+      "docker-compose.yml"
+    ],
+    "design": [
+      "design/**",
+      "web/src/styles/**"
+    ],
+    "research": [
+      "docs/research/**"
+    ]
+  },
+  "scaffold": [
+    "npm create vite@latest web -- --template react-ts",
+    "uv init --app api && uv add --directory api fastapi uvicorn pydantic && uv add --directory api --dev pytest ruff httpx",
+    "npm init playwright@latest -- --quiet tests/e2e"
+  ],
+  "check": [
+    {
+      "name": "web-lint",
+      "run": "npm --prefix web run lint --if-present",
+      "when_exists": "web/package.json"
+    },
+    {
+      "name": "web-types",
+      "run": "npm --prefix web exec -- tsc -b web --noEmit",
+      "when_exists": "web/tsconfig.json"
+    },
+    {
+      "name": "web-test",
+      "run": "npm --prefix web run test --if-present",
+      "when_exists": "web/package.json"
+    },
+    {
+      "name": "api-lint",
+      "run": "uv run --directory api ruff check .",
+      "when_exists": "api/pyproject.toml"
+    },
+    {
+      "name": "api-test",
+      "run": "uv run --directory api pytest -q",
+      "when_exists": "api/pyproject.toml",
+      "ok_exit_codes": [
+        0,
+        5
+      ]
+    },
+    {
+      "name": "acceptance",
+      "run": "uv run --directory api pytest -q ../tests/acceptance",
+      "tests_dir": "tests/acceptance",
+      "tests_pattern": "(^test_.*\\.py$)|(_test\\.py$)",
+      "timeout_s": 900
+    }
+  ]
+}

package/templates/stacks/web-node.json

@@ -0,0 +1,70 @@
+{
+  "about": "React (Vite + TypeScript) + Node.js API (Fastify + TypeScript). Everything in one language - faster for agents.",
+  "areas": {
+    "web": [
+      "web/**"
+    ],
+    "api": [
+      "api/**"
+    ],
+    "contracts": [
+      "contracts/**"
+    ],
+    "e2e": [
+      "tests/e2e/**",
+      "tests/acceptance/**",
+      "tests/pending/**"
+    ],
+    "infra": [
+      "infra/**",
+      ".github/**",
+      "docker-compose.yml"
+    ],
+    "design": [
+      "design/**",
+      "web/src/styles/**"
+    ],
+    "research": [
+      "docs/research/**"
+    ]
+  },
+  "scaffold": [
+    "npm create vite@latest web -- --template react-ts",
+    "mkdir api && npm --prefix api init -y && npm --prefix api i fastify zod && npm --prefix api i -D typescript tsx vitest @types/node",
+    "npm init playwright@latest -- --quiet tests/e2e"
+  ],
+  "check": [
+    {
+      "name": "web-lint",
+      "run": "npm --prefix web run lint --if-present",
+      "when_exists": "web/package.json"
+    },
+    {
+      "name": "web-types",
+      "run": "npm --prefix web exec -- tsc -b web --noEmit",
+      "when_exists": "web/tsconfig.json"
+    },
+    {
+      "name": "web-test",
+      "run": "npm --prefix web run test --if-present",
+      "when_exists": "web/package.json"
+    },
+    {
+      "name": "api-types",
+      "run": "npm --prefix api exec -- tsc -b api --noEmit",
+      "when_exists": "api/tsconfig.json"
+    },
+    {
+      "name": "api-test",
+      "run": "npm --prefix api run test --if-present",
+      "when_exists": "api/package.json"
+    },
+    {
+      "name": "acceptance",
+      "run": "node --test \"tests/acceptance/**/*.test.*js\"",
+      "tests_dir": "tests/acceptance",
+      "tests_pattern": "\\.test\\.[cm]?js$",
+      "timeout_s": 900
+    }
+  ]
+}