@gredescerber/agent-crew 0.0.0-stage → 0.5.0

package/AGENTS.md

@@ -0,0 +1,24 @@
+# AGENTS.md: developing agent-crew itself
+
+These are the rules for agents and humans who **develop agent-crew**.
+The rules for a product built with it live in another file: `templates/product/AGENTS.md`.
+
+## Principles
+- **Vendor neutrality.** The core (`src/`) knows nothing about Claude or Codex. Everything vendor-specific lives in `adapters/<host>/`.
+- **No dependencies.** Node.js 22+ and the standard library only. A new dependency needs an issue with a justification.
+- **One response shape.** Every command returns `ok()/warn()/fail()` from `src/core/output.js`. Every error carries `cause_hint`, `retry`, `stop_when`.
+- **Rules live in CI, not in prose.** If a rule matters, code must enforce it.
+- **Cross-platform.** Windows, macOS, Linux. External commands go through `run()` without a shell.
+- **Language.** Everything written to GitHub (issues, PRs, commits, comments) and everything agents write to each other is English. Agents talk to each human in that human's language.
+
+## How to work
+1. Tasks are issues in this repo. We follow the same loop as any crew project (`skills/crew-workflow`).
+2. A new command: a file in `src/commands/`, registered in `src/core/registry.js`, a test in `test/`.
+3. A new host: `adapters/<host>/adapter.js` + a generation test.
+4. `npm test` must be green. Tests never touch the network or GitHub.
+5. Conventional Commits. One PR, one task.
+
+## Needs human review
+- `templates/product/AGENTS.md`, roles and skills: they change agent behavior for everyone.
+- `templates/product/.github/workflows/`: these are the protective checks.
+- The `crew/v1` response format: change it only together with a schema version bump.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,412 @@
-# Temporary Holding Version
+**English** | [Русский](README.ru.md)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# agent-crew
+
+**A vendor-neutral development environment where several coding agents (Claude Code, Codex, more through adapters) and humans work as one team on any project, coordinated through GitHub Issues and Pull Requests.**
+
+People write clear tasks, agents on the team members' own machines take them from a shared queue, write the code, check it and hand it in for review, and the tool makes sure they do not step on each other, do not break `main` and follow one set of rules, whether the agent is Claude or GPT. It was battle-tested at a 4-person hackathon (10-13 Nov 2026, about 160 merged PRs); the hackathon features are an optional [event mode](#event-mode).
+
+---
+
+## Why
+
+When several agents (and people) share one repository, the same problems show up every time:
+
+- two agents take the same task, or a crashed agent leaves a task stuck forever;
+- nobody reviews the code agents write, or an agent approves its own work;
+- an agent "turns CI green" by weakening a test or editing the CI config;
+- every vendor has its own instruction files, so the rules drift apart;
+- `main` is broken at the moment you need it working.
+
+agent-crew answers with a small protocol on top of GitHub, enforced by code and CI rather than by prose.
+
+## What it consists of
+
+| Part | What it is | Why |
+|---|---|---|
+| **Rules** | `AGENTS.md`, roles, skills | Like a handbook for a new employee: what to do, when to stop, what is forbidden |
+| **The `crew` control CLI** | a small dependency-free Node.js program (also an MCP server) | Take a task, check code, hand in work: the same for every agent |
+| **Checks** | GitHub Actions, templates, branch protection | An agent may ignore text, but cannot bypass CI |
+
+Everything lives in **GitHub**: Issues are the task queue, Pull Requests are the hand-in, Actions are the checks. There is no separate server. Agents run **on the team members' machines, on their own subscriptions**.
+
+**Language rule:** everything written to GitHub (issues, PRs, commits, comments) and everything agents write to each other is English. Agents talk to each human in that human's language.
+
+## How it works
+
+```mermaid
+flowchart LR
+    B[Brief<br/>docs/brief.md] --> P[Planner<br/>crew-kickoff]
+    P --> Q[(GitHub Issues<br/>task queue)]
+    Q -->|crew task next / claim| W1[Claude<br/>alice's laptop]
+    Q -->|crew task next / claim| W2[Codex<br/>bob's laptop]
+    Q -->|crew task next / claim| W3[...<br/>carol's laptop]
+    W1 & W2 & W3 -->|crew check -> crew pr open| PR[Pull Requests]
+    PR -->|review by an agent<br/>of another vendor| R[Review]
+    R -->|merge| M[main, always<br/>releasable]
+```
+
+The life of one task:
+
+```
+needs-spec ──(human adds criteria)──► ready ──(crew task claim)──► claimed ──(crew pr open)──► review ──► done
+                                        ▲                             │
+                                        └──── lease expired / ────────┘
+                                              crew task release
+```
+
+## Quick start
+
+**Fastest: one message to an agent.** The agent reads [docs/AGENT-SETUP.md](docs/AGENT-SETUP.md) and sets everything up itself. Ready-to-paste messages for the captain, a member and the plan are at the end of that file. The commands behind them:
+
+```bash
+# captain: create the project, the GitHub repo, invitations and protection of main
+crew up --repo owner/name --invite alice,bob
+
+# member: accept the invitation, clone, build local agent configs
+crew up --join owner/name
+```
+
+What stays manual, because an agent must not or cannot do it: logging in (`gh auth login`, Claude, Codex) and confirming project trust in Codex.
+
+### 1. Install (once per machine)
+
+Needs Node.js 22+, git, the [GitHub CLI](https://cli.github.com/) (`gh auth login`) and at least one agent: [Claude Code](https://code.claude.com) or [Codex CLI](https://github.com/openai/codex).
+
+The tool installs straight from the public GitHub repo (no registry, no tokens):
+
+```bash
+npm install -g @gredescerber/agent-crew
+```
+
+The command is `crew`. Straight from GitHub instead: `npm install -g --allow-git=all github:GredesCerber/agent-crew#v0.5.0` (npm 12+ blocks git installs without the flag).
+
+Or clone it and link it (no dependencies; `npm link` only puts `crew` on PATH):
+
+```bash
+gh repo clone GredesCerber/agent-crew && cd agent-crew && npm link
+```
+
+```bash
+crew doctor
+```
+
+`crew doctor` shows what is missing.
+
+**Windows:** enable long paths in git, otherwise it fails on task worktrees and `node_modules`:
+
+```bash
+git config --global core.longpaths true
+```
+
+### 2. Create the project (captain)
+
+```bash
+crew up my-product --repo owner/my-product --stack web-node --invite alice,bob --public
+```
+
+`crew up` runs `crew init`, makes the first commit, creates the GitHub repo and pushes, invites the members, and sets up `main` protection, labels and `CREW_HARNESS`. It is safe to re-run: finished steps are skipped. Add `--hosts claude,codex` to choose agent hosts.
+
+Or step by step:
+
+```bash
+crew init my-product --stack web-fastapi
+cd my-product && git add -A && git commit -m "chore: crew init"
+gh repo create owner/my-product --public --source . --push
+crew github setup --apply
+```
+
+What appears in `my-product/`:
+
+```
+AGENTS.md                ← the main rules for all agents
+CLAUDE.md                ← one line: @AGENTS.md (Claude reads the rules from there)
+crew.config.json         ← areas, checks, model tiers, MCP
+agents/roles/            ← analyst, planner, builder, reviewer, integrator + helpers scout, implementer
+agents/skills/           ← crew-workflow, crew-kickoff, crew-review, crew-brief-analysis
+.claude/ .mcp.json       ← generated for Claude Code (+ the ECC plugin)
+.codex/ .agents/skills/  ← generated for Codex
+.github/                 ← issue and PR templates, CI checks (crew.yml) and PR rules (crew-guard.yml)
+contracts/ tests/ docs/  ← API contracts, acceptance tests, brief and playbooks
+events/                  ← optional event rules (time window, team members)
+```
+
+Stack presets: `web-fastapi` (React + FastAPI) and `web-node` (React + Node.js). A preset is **not ready-made code** but a list of generators (`npm create vite`, `uv init`) and checks; the agent creates the skeleton itself.
+
+### 3. Set up the GitHub repo (`crew github setup`)
+
+One command instead of clicking through Settings (needs admin rights on the repo):
+
+```bash
+crew github setup           # show the plan of gh api calls, change nothing
+crew github setup --apply   # do it
+```
+
+With `--apply` it:
+
+- protects `main`: PRs only, green `check` (tests) and `crew-guard` (PR rules + agent review) required, no force-push. **Zero manual approvals**: a human is not an "approve button";
+- enables auto-merge and plain merge commits only (squash and rebase are off because they lose the `Agent`/`Issue` trailers);
+- sets the `CREW_HARNESS` repo variable: the install spec CI uses, by default `@gredescerber/agent-crew@<version>` (another one via `--harness`);
+- creates or updates all labels (like `crew labels sync`).
+
+Re-running is safe. The repo is taken from the current folder (`gh repo view`) or from `--repo owner/name`; another branch via `--branch`.
+
+> **Branch protection needs a public repo or GitHub Pro/Team.** On the free plan a private repo cannot protect `main`, and `crew github setup --apply` fails with HTTP 403.
+
+### 4. Join an existing project (members)
+
+```bash
+crew up --join owner/name
+```
+
+This accepts the invitation, clones the repo, configures git and runs `crew adapters build`, which creates the local agent configs (`.mcp.json`, `.codex/config.toml`, skills, roles). They depend on the machine and are not committed; `crew task claim` copies them into each task worktree.
+
+An agent's name in tasks and commits is `CREW_AGENT` plus the machine name (`claude@alice-laptop`), added by `crew`. For two sessions on one machine give each its own `CREW_AGENT_ID`.
+
+### 5. Plan: brief -> PRD -> tasks (captain)
+
+The captain puts the brief into `docs/brief.md`, and the planner agent turns it into `docs/prd.md` (skills `crew-brief-analysis` and `crew-kickoff`). The PRD contains a `crew-team` block (who owns which area, who reviews) and `crew-task` / `crew-epic` blocks. Then:
+
+```bash
+crew task lint            # validate the PRD offline
+crew kickoff              # dry run: what would be created
+crew kickoff --apply      # create the issues, once the PRD is approved
+```
+
+Details in [crew kickoff](#crew-kickoff).
+
+### 6. Run the agents
+
+**Claude Code**: open the project folder; it reads `CLAUDE.md` -> `AGENTS.md` and connects the `crew` MCP server on its own. Then:
+
+> /loop 10m Work the crew-workflow loop
+
+**Codex**: run `codex` in the project root and confirm you trust the project (otherwise it will not read `.codex/config.toml`). Codex has no `/loop`, so the loop runs in the chat on top of `crew task next --wait`:
+
+> Work the crew-workflow loop without stopping: run `crew task next --wait 20`, do what its next_actions say, then run it again. Stop after three "no free tasks" answers in a row.
+
+Members never plan; only the captain runs `crew kickoff`.
+
+## Concepts
+
+### Tasks and leases
+A task is a GitHub issue with `status:*`, `area:*`, `tier:*` and `risk:*` labels. `crew task claim <id>` takes it: the label changes, a lease marker is written to a comment, the branch `crew/<id>-...` and a separate worktree are created. The lease lasts 45 minutes and is extended by activity (`crew task heartbeat`, crew markers in the issue, or a push to the `crew/<id>-*` branch). If an agent dies, the task returns to the queue by itself (a GitHub Action sweeps every 15 minutes). `crew task cleanup` removes worktrees of closed tasks that have no uncommitted changes and whose work is already saved in `main` or on GitHub.
+
+### Areas and owners
+Every task belongs to exactly one area (`web`, `api`, `infra`, ...). The `crew-team` block of the PRD maps areas to people:
+
+````
+```crew-team
+alice: web, review   # frontend + reviewer
+bob: api
+```
+````
+
+`crew task next` offers a person's agent its own tasks first, then unowned ones, then other people's areas ("help the owner"). The `review` role marks the team's reviewers.
+
+### Review-first queue
+`crew task next` serves the team before itself: your own PR that needs fixes, then a ready PR to merge, then a PR waiting for your review, and only then a new task. This keeps work from piling up behind review.
+
+### Cross-agent review and `crew-guard`
+Claude's code is reviewed by Codex and vice versa: different models catch different mistakes. `crew-guard` is a commit status set on every PR:
+
+- `failure` if the PR changes the rules of agents or CI (`crew.config.json`, `.github/**`, `AGENTS.md`, `CLAUDE.md`, `agents/**`, `events/**`). Agents may not do this at all; the rules are changed by a maintainer;
+- `failure` if the PR changes or deletes an **existing** acceptance test and its task does not allow it (the `changes_acceptance` field of the PRD task). Adding new tests is fine;
+- `failure` if the reviewer asked for changes; `pending` while waiting for review; `success` when **another agent** reviewed the current commit (`crew pr review <n> --verdict approve`), two reviews for `risk:high`;
+- for `risk:high`, tests and code are written by **different agents**: the tests task (`tests_for`) puts them into `tests/pending/<T>/`, and the main task must move them into `tests/acceptance/` without a single edit (otherwise `failure`); `crew task claim` does not let the test author take the code;
+- who reviews is set in `crew.config.json -> review`: by default an agent of another vendor, and if none shows up within 30 minutes, any other agent. A Claude-only team uses `"require": "other-agent"` or `"hosts": ["claude"]`;
+- the `crew-guard.yml` workflow is taken from `main`, not from the PR branch (`pull_request_target`), and never runs PR code, so a PR cannot weaken its own check;
+- on a PR, `crew check` in CI uses the `crew.config.json` of the base commit, not of the PR branch; on push to `main` it uses its own.
+
+`crew guard --pr <n>` shows the same locally: why a PR does not merge.
+
+### Protected `main`
+`crew github setup --apply` makes `main` PR-only with `check` and `crew-guard` required. Humans do not approve every PR: they test the running product and file feedback, and the planner turns it into tasks. See the note about public repos above.
+
+**Emergency stop:** create an issue labeled `crew:pause`; agents finish the current step and stop. This is in code: while such an issue is open, `crew task next` and `crew task claim` return a `paused` error.
+
+## `crew` commands
+
+| Command | What it does |
+|---|---|
+| `crew task next [--area web] [--tier low] [--wait 20]` | the next item for you: own PR to fix, PR to merge, review, or a free task for your area and model tier; with `--wait N` it polls once a minute for up to N minutes when idle (the in-chat loop for Codex) |
+| `crew task claim <id>` | take a task: label, lease, branch `crew/<id>-...`, separate worktree |
+| `crew check` | run lint/types/tests from `crew.config.json`; short error summary, full log in `.crew/logs/`; each step has `timeout_s` (default 600), a hung step is killed and yields `ci_red` |
+| `crew commit -m "feat: ..."` | commit with `Agent` and `Issue` trailers |
+| `crew pr open` | open a PR (only after a green check), task -> `review` |
+| `crew pr review <n> --verdict approve\|changes --note "..."` | a reviewing agent's verdict (counted by `crew-guard`; you cannot review your own work) |
+| `crew guard --pr <n>` | why a PR does not merge: rules, acceptance tests, review (CI sets the status with `--report`) |
+| `crew task status <id> blocked --note "..."` | change the status and leave a handoff |
+| `crew task release <id>` / `heartbeat <id>` | give a task back / extend the lease (your own only; someone else's needs a human with `--force`) |
+| `crew shots before\|after --url <page> [--name <screen>]` | before/after screenshot (Playwright) for a task that changes the UI; `crew pr open` shows them as a Before / After table |
+| `crew task cleanup [--dry_run]` | remove worktrees of closed tasks (only those with no uncommitted changes and with work already saved in main or on GitHub) |
+| `crew task lint` | validate `docs/prd.md` offline: all errors at once (line, id, rule) |
+| `crew task sweep` / `crew task promote` | return expired leases to the queue / move `waiting` tasks to `ready` when their dependencies close (run by CI) |
+| `crew kickoff [--apply]` | create issues and epics from the approved PRD (dry run by default) |
+| `crew status` | what is in the queue, who does what, what is blocked |
+| `crew worker --host codex` | a headless loop that takes tasks and runs an agent on each (humans only) |
+| `crew metrics`, `crew eval` | per-agent metrics from the event log / comparing agents on reference tasks |
+| `crew compliance check` / `disclosure` | event mode: rules check / disclosure file for a submission |
+| `crew up`, `crew init`, `crew adapters build`, `crew labels sync`, `crew doctor` | setup (humans; `crew up` does it all, see docs/AGENT-SETUP.md) |
+| `crew github setup [--apply]` | `main` protection, `CREW_HARNESS` variable, labels: the plan, or with `--apply` execute it (humans) |
+| `crew mcp` | the MCP server: the same commands as `crew_*` tools for agents |
+
+The MCP server runs in the project root, so `crew_check`, `crew_commit`, `crew_pr_open`, `crew_task_claim` and `crew_compliance_check` accept an optional `cwd`: the absolute worktree path from `crew_task_claim -> artifacts.worktree`. Without it the tools work on the root, not on the task branch.
+
+Every command answers in one shape, so the agent never has to guess:
+
+```json
+{
+  "schema": "crew/v1",
+  "status": "error",
+  "summary": "Failed: api-test",
+  "next_actions": ["fix it and run crew check again"],
+  "artifacts": { "log": ".crew/logs/check-2026-12-05T12-00-00.txt" },
+  "error": {
+    "code": "ci_red",
+    "cause_hint": "FAILED tests/test_auth.py::test_login - assert 401 == 200",
+    "retry": "fix it and run crew check again",
+    "stop_when": "the same error 3 times in a row -> crew task status <id> blocked"
+  }
+}
+```
+
+## crew kickoff
+
+The planner (skill `crew-kickoff`) reads `docs/brief.md` and `docs/brief-analysis.md` and writes only `docs/prd.md` with `crew-team`, `crew-task` and `crew-epic` blocks ([format](skills/crew-kickoff/task-format.md)). Code creates the issues:
+
+```bash
+crew task lint            # validate the PRD offline: all errors at once (line, id, rule)
+crew kickoff              # plan (dry run): what will be created, statuses, order
+crew kickoff --apply      # create tasks and epics, only if the PRD is approved
+```
+
+- **Approval** is the first PRD line `<!-- crew:prd status: approved by: <login> at: <ISO> -->`. Without it `--apply` answers `plan_not_approved`. Only the captain can apply. `--apply` also refuses with `team_not_collaborator` when the `crew-team` block names someone who is not a collaborator of the repo.
+- **Skeleton**: the first block (`skeleton: true`, `tier/risk: high`); all other tasks implicitly wait for it. A task with dependencies is created as `status:waiting` ("after #N"), without them as `ready`, and `ready: false` gives `needs-spec`.
+- **waiting -> ready** is done by `crew task promote`: the `promote` job in `crew.yml` when an issue closes, and `crew task sweep` on a schedule.
+- **Risk** is `low | med | high` (default `med`), one area per task, acceptance criteria as `Given/When/Then` (Russian `Дано/Когда/Тогда` is also accepted), `req: [R1]` becomes "Brief requirements" in the issue.
+- **Safe to repeat**: tasks are found by the `crew:task` marker in the body and only new ones are created; changed or removed blocks only produce warnings. There is a 1 s pause between `gh issue create` calls and a retry after 10/30/60 s on rate limit; a failure midway is `kickoff_partial`, just run it again.
+
+## crew worker
+
+An agent can also work the queue headlessly: a human starts a worker and goes on with their own work.
+
+```bash
+crew worker --host codex --area api --tier mid       # Codex takes tasks of area api
+crew worker --host claude --max-tasks 3 --dry-run    # show what it would take, touch nothing
+```
+
+The loop: `crew task next` -> `crew task claim <id>` -> the agent starts in the task worktree (`CREW_AGENT=<host>/<model>`) with a short prompt ("work only on #id per crew-workflow; finish with `crew pr open` or `crew task status blocked/needs-spec`") -> the worker checks the issue status -> the next task. **Every task is a new agent process**, i.e. a clean context at the phase boundary.
+
+| Flag | Default | What it does |
+|---|---|---|
+| `--host claude\|codex` | none | which agent to launch (`adapter.headless()`) |
+| `--area`, `--tier` | any, `high` | as in `crew task next`; the model comes from `crew.config.json -> tiers` |
+| `--model` | from tier | a specific model |
+| `--max-tasks` | 5 | how many tasks to take per run |
+| `--max-failures` | 3 | stop after N failures in a row |
+| `--task-timeout-min` | 60 | kill the agent (the whole process tree) on a task |
+| `--wait` | off | empty queue: poll every 5 min instead of exiting |
+| `--dry-run` | off | only show the task and the launch command |
+
+- **Success**: after the agent exits, the task is in `review`/`done`. `blocked`/`needs-spec` is a handoff, not a failure.
+- **Failure**: the task stayed `claimed` (the agent crashed, exited silently, timed out): the worker runs `crew task release` with a note and a link to the log.
+- **Stops**: pause (`crew:pause`), empty queue, task limit, N failures in a row, 3 claim conflicts in a row, the agent will not start.
+- Task progress goes to stderr, agent output to `.crew/logs/worker-<id>-*.log`, the result is a `crew/v1` answer with `artifacts: { done, failed, blocked, stopped_reason }`.
+- Codex is launched as `codex exec --json -s workspace-write -c sandbox_workspace_write.network_access=true -C <worktree> --add-dir <repo .git> -` (the prompt goes to stdin). Claude as `claude -p <prompt> --output-format json --permission-mode acceptEdits` with an explicit `--allowedTools` list.
+- For humans only: the worker is not exposed over MCP.
+
+## Metrics and eval
+
+Without data you cannot tell whether the tool got better, so every `crew` command writes an event to a log.
+
+**The log.** After every command a line is appended to `.crew/metrics.jsonl` (in the root of the main repo, shared by all worktrees):
+
+```json
+{"command":"check","issue":12,"agent":"codex/gpt-5","status":"error","error_code":"ci_red","duration_ms":8123,"at":"2026-12-05T12:00:00.000Z"}
+```
+
+The task number comes from the `id` argument, from `artifacts.issue` or from the branch `crew/<id>-...`. It is written only inside a project with `crew.config.json`, and a write never breaks a command. Disable with `CREW_METRICS=off`.
+
+**Summary:** `crew metrics [--agent codex] [--since 2d]` shows, per agent:
+
+| Metric | How it is computed |
+|---|---|
+| completion rate | successful `pr open` / successful `task claim` |
+| checks per task (retries) | average number of `crew check` runs per task |
+| claim -> PR | median time from claim to the first successful `pr open` of the same task |
+| frequent errors | top 5 `error.code` over all events |
+
+`--agent codex` also matches `codex/gpt-5`; `--since` accepts a date, an ISO time or `30m` / `6h` / `2d`.
+
+**Eval.** `crew eval` compares agents on the same reference tasks. Use it to see whether a change to `AGENTS.md`, skills or roles made agents worse, and which model to put on which tier:
+
+```bash
+crew eval --dry-run                              # validate tasks and show the plan, no agents are started
+crew eval --agents claude,codex --runs 3         # tasks x agents x runs
+crew eval --agents claude:opus,claude:sonnet --task fix-off-by-one
+```
+
+Each run happens in a fresh temporary copy of the fixture repo (pinned to `commit` when given): the agent is started through its adapter's `headless()`, then deterministic judges (`command` for tests/build, `grep` for a pattern in files) decide pass/fail. The report is a table plus `artifacts.results`: **pass@1**, **pass@k**, **consistency**, average time and cost (if the agent reports it) per agent and task; the full report is in `.crew/evals/`.
+
+Tasks are `evals/tasks/*.json` in a format close to [agent-eval](https://github.com/joaquinhuigomez/agent-eval) (JSON instead of YAML, no dependencies), the fixture is `evals/fixtures/mini-app/`. The format, the mapping to agent-eval and how to add a task are in [`evals/README.md`](evals/README.md). In CI (`.github/workflows/eval.yml`) a `--dry-run` runs on PRs touching `templates/product/AGENTS.md`, `skills/`, `roles/`, `evals/`; a real run is started manually because agents need API keys.
+
+## ECC and optional MCP servers
+
+- **[ECC](https://github.com/affaan-m/ECC)** is enabled for Claude Code automatically (`.claude/settings.json`). Which ECC skills to use per role is in [`ecc/profile.json`](ecc/profile.json). ECC is an accelerator, not a dependency: the `crew` protocol works without it, so Codex works as an equal.
+- **Optional MCP servers** live in `crew.config.json -> mcp` and are off by default. Keys come only from environment variables, never from files:
+  - `context7`: fresh library and API documentation (enable this first);
+  - `perplexity`: deep web search for kickoff and pitches (`PERPLEXITY_API_KEY`; verify the package name before enabling);
+  - `playwright`: a browser for end-to-end demo paths.
+
+  After changing: `crew adapters build`.
+
+## Event mode
+
+The tool itself is neutral; for hackathons and other time-boxed events there is an optional mode driven by `events/event.json` (copy it from `event.example.json`, and set `"event": "events/event.json"` in `crew.config.json`; `crew up --start ... --end ...` does this for you):
+
+- CI checks that there are no commits before the start or after the end, that PRs come only from `team_members`, and that AI is used only if allowed;
+- `crew compliance check` runs those checks locally; `crew compliance disclosure` writes `DISCLOSURE.md`: which tools and agents were used and how many commits came from whom;
+- the repo of the product is created empty at the start (`crew init`), and during the event only team members commit to it;
+- the product playbooks in `templates/product/docs/playbooks/` describe a timeline for a day of such an event ([`timeline.md`](templates/product/docs/playbooks/timeline.md)), a pre-event checklist ([`preflight.md`](templates/product/docs/playbooks/preflight.md)) and the issue rules: statuses, labels, Definition of Ready, who does what ([`issues.md`](templates/product/docs/playbooks/issues.md)).
+
+Always re-read the rules of each event; organizers differ. Without `events/event.json` none of this applies.
+
+## Extending
+
+| I want | What to do |
+|---|---|
+| A new `crew` command | a file in `src/commands/` + a line in `src/core/registry.js`; it then appears in both the CLI and MCP |
+| Support for a new agent (Gemini, Cursor, ...) | `adapters/<host>/adapter.js` with `generate()` and `headless()`, add the host to `hosts` |
+| A new stack | `templates/stacks/<name>.json`: areas, generators, checks |
+| A new role or skill | `roles/<name>.md` or `skills/<name>/SKILL.md` (Agent Skills format) |
+
+Details: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). What prior art we studied and how we differ: [`docs/RESEARCH.md`](docs/RESEARCH.md).
+
+## Limitations
+
+- **Branch protection needs a public repo or GitHub Pro/Team.** A private repo on the free GitHub plan cannot protect `main`; `crew github setup --apply` returns HTTP 403.
+- **`crew-guard` catches laziness and mistakes, not malice.** Agents work under their humans' accounts, so an agent that deliberately forges a `crew:review` marker in someone else's name or merges with `--admin` is not technically stopped; that is forbidden in `AGENTS.md` and visible in PR history. Weakening a test, "fixing" CI or approving its own work by accident will not work.
+- **Headless Claude** for `crew worker` uses `claude -p` with `--permission-mode acceptEdits` and an explicit `--allowedTools` list (file edits, `npm`/`node`/`uv`, read-only `git`, `crew`); the flags follow the Claude Code docs and have had less live testing than Codex. Try one task on your machine first. Headless Codex (`codex exec`) was verified live on codex-cli 0.166: `crew` tools are called without confirmation (`default_tools_approval_mode = "approve"` for the `crew` server only).
+- **The Perplexity MCP package is not chosen:** `templates/mcp.optional.json` contains the placeholder `VERIFY-PACKAGE-NAME-BEFORE-ENABLING`; enable it only after verifying the package name.
+- **Privacy of your rules:** `crew init` copies rules, roles, skills and workflows into the product repo, so if that repo is public, those files are public too.
+- A commit status `crew-guard` set by `GITHUB_TOKEN` is counted with the GitHub Actions `app_id`; if your setup differs, set branch protection to accept "any source".
+
+## Roadmap
+
+- [x] **v0**: `crew` (CLI + MCP), AGENTS.md, roles and skills, Claude Code and Codex adapters, GitHub templates, CI, compliance
+- [x] **v1**: MCP in the task worktree (`cwd`), leases by commits, `crew:pause` in code, `crew check` timeouts, config protection in CI, `crew github setup`, `crew worker`, `crew metrics`, `crew eval`, `crew kickoff` with the `crew-team` block, `crew up`, review-first queue; see [`docs/ROADMAP-v1.md`](docs/ROADMAP-v1.md)
+- [ ] **v1 (remaining)**: a `--budget` flag for the worker, verified headless flags for Claude
+- [ ] **v2**: auto-merge of green PRs, nightly checks, a digest bot, adapters for Gemini and Cursor
+
+## Developing the tool itself
+
+```bash
+npm test
+```
+
+Rules for contributors (and their agents) are in [`AGENTS.md`](AGENTS.md) at the root of this repo.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).