@gredescerber/agent-crew 0.0.0-stage → 0.5.0

package/src/commands/guard.js

@@ -0,0 +1,101 @@
+// crew guard --pr N [--report] — PR rules without manual approval (see src/core/guard.js).
+// In CI it runs from the crew-guard workflow (pull_request_target / issue_comment): the guard config and code come
+// from main, not from the PR branch, so a PR cannot weaken the check for itself.
+// --report sets the crew-guard commit status on the PR head (a required check of main protection).
+// An agent can run it without --report to understand why its PR is not merging.
+import { ok, warn, fail } from '../core/output.js';
+import { gh, ghJson, git } from '../core/exec.js';
+import { loadConfig } from '../core/config.js';
+import { evaluateGuard, linkedIssue, taskMarkers, GUARD_CONTEXT, PENDING_DIR } from '../core/guard.js';
+
+/** PR files from the GitHub API (with status and previous_filename; gh pr view does not return them). */
+function prFiles(pr, cwd) {
+  const out = gh(['api', '--paginate', `repos/{owner}/{repo}/pulls/${pr}/files`, '--jq', '.[] | {filename, status, previous_filename, additions, deletions, changes}'], { cwd }).stdout;
+  return out.split('\n').filter(Boolean).map((l) => JSON.parse(l));
+}
+
+/** PR commits without merge commits, including further API pages. PR code is not executed. */
+export function prCommits(pr, cwd, fetch = gh) {
+  const out = fetch(['api', '--paginate', `repos/{owner}/{repo}/pulls/${pr}/commits`, '--jq', '.[] | {sha, message: .commit.message, parents}'], { cwd }).stdout;
+  // GitHub merge / Update branch commits need not have Agent; a regular commit titled Merge must.
+  return out.split('\n').filter(Boolean).map((line) => JSON.parse(line)).filter((c) => (c.parents ?? []).length <= 1).map(({ sha, message }) => {
+    // Git distinguishes a real trailer from an Agent: line in the subject or plain text.
+    const trailers = git(['interpret-trailers', '--parse'], { cwd, input: message }).stdout;
+    const agent = /^Agent:[ \t]*(\S[^\r\n]*)$/im.exec(trailers)?.[1]?.trim() ?? null;
+    return { sha, agent };
+  });
+}
+
+/** Files tests/pending/<T>/ in the base commit (the task with code must move them). */
+function pendingInBase(baseSha, taskId, cwd) {
+  if (!baseSha || !taskId) return [];
+  const dir = `${PENDING_DIR}${taskId}/`;
+  const r = gh(['api', `repos/{owner}/{repo}/git/trees/${baseSha}?recursive=1`, '--jq', '.tree[] | select(.type == "blob") | .path'], { cwd, allowFail: true });
+  return r.code === 0 ? r.stdout.split('\n').filter((p) => p.startsWith(dir)) : [];
+}
+
+function runUrl() {
+  const { GITHUB_SERVER_URL: s, GITHUB_REPOSITORY: r, GITHUB_RUN_ID: id } = process.env;
+  return s && r && id ? `${s}/${r}/actions/runs/${id}` : undefined;
+}
+
+export default {
+  name: 'guard',
+  summary: 'Check a PR against the crew rules (protected files, acceptance tests, agent review); --report sets the crew-guard status',
+  args: [
+    { name: 'pr', type: 'number', required: true, description: 'PR number' },
+    { name: 'report', type: 'boolean', description: 'write the crew-guard commit status (done by CI)' },
+  ],
+  run({ pr, report = false }) {
+    const { config, root } = loadConfig();
+    const view = ghJson(['pr', 'view', String(pr), '--json', 'number,body,headRefOid,baseRefOid,labels,createdAt,comments,state'], { cwd: root });
+    if (!view) return fail('pr_not_found', `PR #${pr} not found`, { retry: 'gh pr list', stop_when: 'PR is closed or belongs to another repo' });
+    const files = prFiles(pr, root);
+    const commits = prCommits(pr, root);
+    const issueNo = linkedIssue(view.body);
+    const issue = issueNo ? ghJson(['issue', 'view', String(issueNo), '--json', 'body'], { cwd: root, allowFail: true }) : null;
+    const risk = (view.labels ?? []).map((l) => l.name).find((n) => n.startsWith('risk:'))?.slice(5) ?? 'med';
+    const tm = taskMarkers(issue?.body ?? '');
+    const pendingFiles = tm.testsIssue ? pendingInBase(view.baseRefOid, tm.taskId, root) : [];
+
+    const res = evaluateGuard({
+      pendingFiles,
+      files,
+      commits,
+      body: view.body,
+      issueBody: issue?.body ?? '',
+      comments: view.comments ?? [],
+      headSha: view.headRefOid,
+      risk,
+      createdAt: view.createdAt,
+      config,
+    });
+
+    if (report) {
+      const args = ['api', '-X', 'POST', `repos/{owner}/{repo}/statuses/${view.headRefOid}`, '-f', `state=${res.state}`, '-f', `context=${GUARD_CONTEXT}`, '-f', `description=${res.description}`];
+      const url = runUrl();
+      if (url) args.push('-f', `target_url=${url}`);
+      gh(args, { cwd: root });
+    }
+
+    const artifacts = { pr, sha: view.headRefOid, state: res.state, risk, problems: res.problems, review: res.review, author: res.author, issue: res.issue, reported: report };
+    if (res.state === 'failure') {
+      return fail('guard_failed', `PR #${pr}: ${res.problems.map((p) => p.message).join('; ')}`, {
+        cause_hint: res.problems[0].message,
+        retry: res.problems.some((p) => p.rule === 'agent_trailer') ? 'tell the team captain about commits without Agent; make new commits via crew commit' : res.problems.some((p) => p.rule === 'changes_requested') ? 'apply the reviewer changes, crew check, crew commit, git push' : 'remove the forbidden changes from the PR, crew commit, git push',
+        stop_when: res.problems.some((p) => p.rule === 'agent_trailer') ? 'agents do not rewrite git history — a human agrees on the fix' : 'cannot be done without changing the rules or other people tests → crew task status <id> blocked --note "need a task that changes acceptance"',
+        artifacts,
+      });
+    }
+    if (res.state === 'pending') {
+      return warn(`PR #${pr}: ${res.description}`, {
+        artifacts,
+        next_actions: [`reviewer: skill crew-review → crew pr review ${pr} --verdict approve|changes --note "..."`],
+      });
+    }
+    return ok(`PR #${pr}: ${res.description}`, {
+      artifacts,
+      next_actions: risk === 'high' ? ['integrator merges first: gh pr merge <n> --merge --delete-branch'] : ['auto-merge will merge the PR itself'],
+    });
+  },
+};

package/src/commands/init.js

@@ -0,0 +1,76 @@
+// crew init <dir> [--stack web-fastapi] — create an empty product repo with all configs.
+// Creates no product code: only rules, templates and checks (also compatible with event rules that forbid code written before the start).
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { ok, fail } from '../core/output.js';
+import { git } from '../core/exec.js';
+import { HARNESS_ROOT, DEFAULT_CONFIG } from '../core/config.js';
+import { buildFiles } from './adapters.js';
+
+export const STACKS_DIR = join(HARNESS_ROOT, 'templates', 'stacks');
+
+export default {
+  name: 'init',
+  summary: 'Create a product repo: AGENTS.md, roles, skills, GitHub templates, CI, agent configs',
+  agent: false,
+  args: [
+    { name: 'dir', type: 'string', positional: true, required: true, description: 'new project folder' },
+    { name: 'stack', type: 'string', description: 'stack preset from templates/stacks (default web-fastapi)' },
+    { name: 'hosts', type: 'string', description: 'hosts, comma-separated (default claude,codex)' },
+    { name: 'force', type: 'boolean', description: 'write into a non-empty folder' },
+  ],
+  async run({ dir, stack = 'web-fastapi', hosts, force }) {
+    const root = resolve(dir);
+    if (existsSync(root) && readdirSync(root).length && !force) {
+      return fail('dir_not_empty', `${root} is not empty`, { retry: `crew init ${dir} --force (if you really need to)` });
+    }
+    const stackPath = join(STACKS_DIR, `${stack}.json`);
+    if (!existsSync(stackPath)) {
+      const list = readdirSync(STACKS_DIR).map((f) => f.replace(/\.json$/, ''));
+      return fail('unknown_stack', `No preset ${stack}`, { cause_hint: `available: ${list.join(', ')}`, retry: `crew init ${dir} --stack ${list[0]}` });
+    }
+    const preset = JSON.parse(readFileSync(stackPath, 'utf8'));
+    mkdirSync(root, { recursive: true });
+
+    // 1. Product template (AGENTS.md, .github, contracts/, events/, ...)
+    cpSync(join(HARNESS_ROOT, 'templates', 'product'), root, { recursive: true, force: true });
+    // 2. Vendor-neutral roles and skills → agents/ (source for adapters)
+    cpSync(join(HARNESS_ROOT, 'roles'), join(root, 'agents', 'roles'), { recursive: true });
+    cpSync(join(HARNESS_ROOT, 'skills'), join(root, 'agents', 'skills'), { recursive: true });
+    // 3. Config
+    const config = {
+      ...DEFAULT_CONFIG,
+      stack,
+      areas: preset.areas ?? DEFAULT_CONFIG.areas,
+      check: preset.check ?? [],
+      scaffold: preset.scaffold ?? [],
+      hosts: hosts ? hosts.split(',').map((h) => h.trim()) : DEFAULT_CONFIG.hosts,
+      ecc: JSON.parse(readFileSync(join(HARNESS_ROOT, 'ecc', 'profile.json'), 'utf8')),
+      mcp: JSON.parse(readFileSync(join(HARNESS_ROOT, 'templates', 'mcp.optional.json'), 'utf8')),
+    };
+    writeFileSync(join(root, 'crew.config.json'), JSON.stringify(config, null, 2) + '\n');
+    // 4. Per-host configs; machine-specific ones go to .gitignore
+    const { files } = await buildFiles(root, config);
+    for (const f of files) {
+      mkdirSync(dirname(join(root, f.path)), { recursive: true });
+      writeFileSync(join(root, f.path), f.content);
+    }
+    const local = [...new Set(files.filter((f) => !f.commit).map((f) => (f.path.includes('/skills/') ? f.path.split('/skills/')[0] + '/skills/' : f.path)))];
+    const gi = ['# crew: local files', '.crew/', ...local, '', '# secrets', '.env', '.env.*', '!.env.example', '', 'node_modules/', '__pycache__/', '.venv/', 'dist/', ''];
+    writeFileSync(join(root, '.gitignore'), gi.join('\n'));
+    // 5. git
+    if (!existsSync(join(root, '.git'))) git(['init', '-b', 'main'], { cwd: root });
+
+    return ok(`Project created: ${root} (stack ${stack}, hosts ${config.hosts.join(', ')})`, {
+      artifacts: { root, stack, hosts: config.hosts, files: files.length },
+      next_actions: [
+        `cd ${dir}`,
+        'git add -A && git commit -m "chore: crew init"',
+        'gh repo create <org>/<name> --private --source . --push',
+        'crew github setup --apply (main protection, auto-merge, labels, CREW_HARNESS)',
+        'optional event mode: fill in events/event.json (start time, team) and set "event" in crew.config.json',
+        'paste the organizers brief into docs/brief.md as is → tell the agent: "analyze the brief with the crew-brief-analysis skill" → then crew-kickoff',
+      ],
+    });
+  },
+};

package/src/commands/kickoff.js

@@ -0,0 +1,275 @@
+// crew task lint | crew kickoff [--apply] — tasks and epics in Issues from docs/prd.md (deterministic).
+// The core is the pure functions in src/core/prd.js; gh and sleep are passed in as dependencies (tests run without a network).
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { ok, warn, fail } from '../core/output.js';
+import { run } from '../core/exec.js';
+import { loadConfig, agentId } from '../core/config.js';
+import {
+  DEFAULT_PRD, parsePrd, lintPrd, planKickoff, prdApproval, renderTaskBody, renderEpicBody, formatLintItem,
+} from '../core/prd.js';
+
+const FILE_ARG = { name: 'file', type: 'string', description: `path to the PRD from the project root (default ${DEFAULT_PRD})` };
+const APPROVE_LINE = '<!-- crew:prd status: approved by: <login|auto-timeout> at: <ISO> -->';
+
+/** Pause between gh issue create calls and retry pauses on rate limit (ms). */
+export const CREATE_DELAY_MS = 1000;
+export const RATE_LIMIT_BACKOFF_MS = [10_000, 30_000, 60_000];
+const RATE_LIMIT_RE = /secondary rate limit|rate limit|abuse|HTTP 403/i;
+
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const defaultGh = (root) => (args, { input } = {}) => run('gh', args, { cwd: root, allowFail: true, input });
+
+/** Read and validate the PRD. → { text, parsed, lint } or fail(...). */
+export function loadPrd({ file = DEFAULT_PRD, root, areas }) {
+  const path = resolve(root, file);
+  if (!existsSync(path)) {
+    return {
+      result: fail('prd_missing', `File ${file} not found`, {
+        cause_hint: `expected a PRD with crew-task blocks: ${path}`,
+        retry: `write ${file} following skills/crew-kickoff/task-format.md and run crew task lint again`,
+        stop_when: 'the file is missing and it is unclear where the PRD is — ask the human',
+      }),
+    };
+  }
+  const text = readFileSync(path, 'utf8');
+  const parsed = parsePrd(text);
+  const lint = lintPrd(parsed, { areas });
+  if (lint.errors.length) {
+    return {
+      result: fail('prd_invalid', `PRD ${file}: errors ${lint.errors.length}${lint.warnings.length ? `, warnings ${lint.warnings.length}` : ''}`, {
+        cause_hint: lint.errors.slice(0, 3).map(formatLintItem).join(' | '),
+        retry: `fix ${file} and run crew task lint again`,
+        stop_when: 'the same errors after two fixes in a row — show the human',
+        artifacts: { errors: lint.errors, warnings: lint.warnings },
+      }),
+    };
+  }
+  return { text, parsed, lint };
+}
+
+const taskLint = {
+  name: 'task lint',
+  summary: 'Validate docs/prd.md: crew-task/crew-epic blocks, acceptance criteria, areas, dependencies (no network)',
+  args: [FILE_ARG],
+  run({ file = DEFAULT_PRD }) {
+    const { config, root } = loadConfig();
+    const r = loadPrd({ file, root, areas: config.areas });
+    if (r.result) return r.result;
+    const { parsed, lint, text } = r;
+    const approval = prdApproval(text);
+    const artifacts = { tasks: parsed.tasks.length, epics: parsed.epics.length, order: lint.order, warnings: lint.warnings, approved: approval.approved };
+    const next_actions = [approval.approved ? 'crew kickoff — plan (dry-run), then crew kickoff --apply' : `show the PRD and crew kickoff (dry-run) to the product lead; once approved, put this in the ${file} header: ${APPROVE_LINE}`];
+    const summary = `PRD ${file}: tasks ${parsed.tasks.length}, epics ${parsed.epics.length}`;
+    return lint.warnings.length
+      ? warn(`${summary}, warnings ${lint.warnings.length}`, { artifacts, next_actions: [...lint.warnings.map(formatLintItem), ...next_actions] })
+      : ok(`${summary} — no errors`, { artifacts, next_actions });
+  },
+};
+
+const LIST_ARGS = ['issue', 'list', '--state', 'all', '--limit', '1000', '--json', 'number,title,body,labels,state,stateReason'];
+
+/** Plan documents: after kickoff --apply they must be in main, otherwise the team works without the PRD. */
+export const PLAN_DOCS = ['docs/brief.md', 'docs/brief-analysis.md', DEFAULT_PRD];
+
+/**
+ * Publish the plan to main: commit the changed plan documents (with the Agent trailer) and push.
+ * The captain is a repo admin; main protection lets them through. → { state: 'done'|'clean'|'failed', note }
+ */
+export function publishPlan({ root, me, files = PLAN_DOCS, sh = (cmd, args) => run(cmd, args, { cwd: root, allowFail: true }) }) {
+  const first = (r) => (r.stderr || r.stdout || '').split('\n')[0];
+  // We push to main only from main and only the plan documents: an admin bypasses protection, so other code would reach main without review.
+  const branch = sh('git', ['branch', '--show-current']).stdout.trim();
+  if (branch !== 'main') return { state: 'failed', note: `kickoff was run on branch ${branch || '?'}, not main — plan not published; captain: go to the main project folder (main) and re-run crew kickoff --apply` };
+  const changed = sh('git', ['status', '--porcelain', '--', ...files]).stdout.split('\n').filter(Boolean);
+  if (changed.length) {
+    // Fresh clone without user.name/email: the commit would fail. Same as crew up — a noreply identity from the gh account, in this repo only.
+    if (!sh('git', ['config', 'user.email']).stdout.trim() || !sh('git', ['config', 'user.name']).stdout.trim()) {
+      const [login, id] = sh('gh', ['api', 'user', '--jq', '.login + " " + (.id|tostring)']).stdout.trim().split(/\s+/);
+      if (!login || !id) return { state: 'failed', note: 'git has no user.name/user.email and the GitHub login could not be determined — captain: set git config user.name/user.email and re-run crew kickoff --apply' };
+      if (!sh('git', ['config', 'user.name']).stdout.trim()) sh('git', ['config', 'user.name', login]);
+      if (!sh('git', ['config', 'user.email']).stdout.trim()) sh('git', ['config', 'user.email', `${id}+${login}@users.noreply.github.com`]);
+    }
+    sh('git', ['add', '--', ...files]);
+    const c = sh('git', ['commit', '-q', '-m', 'docs: project plan (brief, analysis, PRD)', '-m', `Agent: ${me}`, '--', ...files]);
+    if (c.code !== 0) return { state: 'failed', note: `could not commit the plan: ${first(c)}` };
+  }
+  const pull = sh('git', ['pull', '--rebase', '-q', 'origin', 'main']);
+  if (pull.code !== 0) return { state: 'failed', note: `could not pull main before publishing the plan: ${first(pull)} — captain: run git status, resolve, then git push origin HEAD:main` };
+  const ahead = sh('git', ['diff', '--name-only', 'origin/main..HEAD']).stdout.split('\n').map((s) => s.trim()).filter(Boolean);
+  if (!ahead.length) return { state: 'clean', note: 'the plan is already in main' };
+  const foreign = ahead.filter((f) => !files.includes(f));
+  if (foreign.length) return { state: 'failed', note: `local main has unpushed changes that are not part of the plan (${foreign.slice(0, 3).join(', ')}) — not pushing; the captain sorts it out` };
+  const p = sh('git', ['push', 'origin', 'HEAD:main']);
+  if (p.code !== 0) return { state: 'failed', note: `plan committed but not pushed to main: ${(p.stderr || p.stdout).split('\n')[0]} — captain: git push origin HEAD:main` };
+  return { state: 'done', note: 'brief, analysis and PRD pushed to main — the team can see them' };
+}
+
+/**
+ * Execute the plan: check labels, create tasks in order, then epics. Existing issues are left untouched.
+ * gh(args, { input }) → { code, stdout, stderr }; sleep(ms) → Promise. Both are stubbed in tests.
+ * A failure midway → kickoff_partial (a retry is idempotent — created issues are found by their markers).
+ * → { created, map } on success or a fail(...) result (status: 'error').
+ */
+export async function applyKickoff(plan, { parsed, prd = DEFAULT_PRD, gh, sleep = realSleep }) {
+  const creates = plan.ops.filter((o) => o.op === 'create');
+  const needed = [...new Set(creates.flatMap((o) => o.labels))];
+  const lr = gh(['label', 'list', '--limit', '500', '--json', 'name']);
+  if (lr.code !== 0) {
+    return fail('gh_failed', 'Could not read the repo labels', {
+      cause_hint: (lr.stderr || lr.stdout).split('\n')[0],
+      retry: 'crew doctor, then crew kickoff --apply',
+      stop_when: 'gh is not authenticated or there is no repo — tell the human',
+    });
+  }
+  const have = new Set((JSON.parse(lr.stdout || '[]') ?? []).map((l) => l.name));
+  const missing = needed.filter((l) => !have.has(l));
+  if (missing.length) {
+    return fail('labels_missing', `The repo is missing labels: ${missing.join(', ')}`, {
+      cause_hint: 'labels are created by crew labels sync (status:*, area:*, tier:*, risk:*, epic)',
+      retry: 'crew labels sync, then crew kickoff --apply',
+      stop_when: 'crew labels sync is unavailable to the agent — ask the human',
+      artifacts: { missing },
+    });
+  }
+
+  const map = { ...plan.map };
+  const created = [];
+  const skeletonId = parsed.tasks.find((t) => t.fields.skeleton === true)?.id ?? null;
+  const blocks = new Map([...parsed.tasks, ...parsed.epics].map((b) => [b.id, b]));
+  let first = true;
+  for (const op of creates) {
+    const block = blocks.get(op.id);
+    const body = op.kind === 'task'
+      ? renderTaskBody(block, { issueOf: map, prd, skeletonId, epics: parsed.epics, tasks: parsed.tasks })
+      : renderEpicBody(block, parsed.tasks, { issueOf: map, prd });
+    const args = ['issue', 'create', '--title', op.title, '--label', op.labels.join(','), '--body-file', '-', ...(op.assignee ? ['--assignee', op.assignee] : [])];
+    if (!first) await sleep(CREATE_DELAY_MS); // avoid hitting the GitHub secondary rate limit
+    first = false;
+    let r = gh(args, { input: body });
+    for (let attempt = 0; r.code !== 0 && attempt < RATE_LIMIT_BACKOFF_MS.length && RATE_LIMIT_RE.test(`${r.stderr}\n${r.stdout}`); attempt++) {
+      await sleep(RATE_LIMIT_BACKOFF_MS[attempt]);
+      r = gh(args, { input: body });
+    }
+    const number = Number(/\/issues\/(\d+)/.exec(r.stdout ?? '')?.[1]);
+    if (r.code !== 0 || !Number.isFinite(number)) {
+      const limited = RATE_LIMIT_RE.test(`${r.stderr}\n${r.stdout}`);
+      return fail('kickoff_partial', `Created ${created.length} of ${creates.length}, failed on ${op.id} "${op.title}"`, {
+        cause_hint: limited ? 'GitHub rate limit persisted after 3 retries' : (r.stderr || r.stdout || 'gh did not return an issue link').split('\n')[0],
+        retry: limited ? 'wait 5–10 minutes and run crew kickoff --apply again (created issues will be skipped)' : 'crew kickoff --apply (created issues are skipped by their markers)',
+        stop_when: 'fails on the same task twice — tell the human',
+        artifacts: { created, failed: op.id, map },
+      });
+    }
+    map[op.id] = number;
+    created.push({ id: op.id, number });
+  }
+  return { created, map };
+}
+
+/**
+ * crew kickoff: lint → existing issues → plan → (with --apply and an approved PRD) creation.
+ * deps: { gh, sleep, root, areas } — for tests.
+ */
+export async function runKickoff({ file = DEFAULT_PRD, apply = false } = {}, deps = {}) {
+  const cfg = deps.root ? null : loadConfig();
+  const root = deps.root ?? cfg.root;
+  const r = loadPrd({ file, root, areas: deps.areas ?? cfg?.config.areas });
+  if (r.result) return r.result;
+  const { parsed, lint, text } = r;
+  const approval = prdApproval(text);
+  // The approval gate comes before any GitHub calls.
+  if (apply && !approval.approved) {
+    return fail('plan_not_approved', `PRD ${file} is not approved — not creating issues`, {
+      cause_hint: approval.status ? `PRD header says status: ${approval.status}` : `${file} has no approval header ${APPROVE_LINE}`,
+      retry: 'show the PRD and crew kickoff (dry-run) to the product lead, once approved set status: approved and run crew kickoff --apply again',
+      stop_when: 'no answer from the product lead for 20 minutes — the planner sets status: approved by: auto-timeout; do not run --apply without the header',
+      next_actions: ['crew kickoff (dry-run) — show the plan to the human', `after approval: ${APPROVE_LINE} at the top of ${file}`, 'crew kickoff --apply'],
+      artifacts: { approval },
+    });
+  }
+  const gh = deps.gh ?? defaultGh(root);
+  const warnings = lint.warnings.map(formatLintItem);
+  let existing = [];
+  const lr = gh(LIST_ARGS);
+  if (lr.code === 0) existing = JSON.parse(lr.stdout || '[]') ?? [];
+  else if (apply) {
+    return fail('gh_failed', 'Could not read the repo issues', {
+      cause_hint: (lr.stderr || lr.stdout).split('\n')[0],
+      retry: 'crew doctor, then crew kickoff --apply',
+      stop_when: 'gh is not authenticated or there is no repo — tell the human',
+    });
+  } else warnings.push(`could not read issues (${(lr.stderr || lr.stdout).split('\n')[0]}) — the plan ignores existing ones`);
+
+  const plan = planKickoff(parsed, existing, { prd: file });
+  warnings.push(...plan.warnings);
+  const count = (op) => plan.ops.filter((o) => o.op === op).length;
+  const planView = plan.ops.map(({ op, kind, id, title, labels, after, tasks, number, assignee }) => ({ op, kind, id, title, ...(number ? { number } : {}), ...(assignee ? { assignee } : {}), ...(labels ? { labels } : {}), ...(after?.length ? { after } : {}), ...(tasks ? { tasks } : {}) }));
+
+  if (!apply) {
+    const artifacts = { apply: false, approved: approval.approved, approval, plan: planView, map: plan.map, warnings };
+    const summary = `Kickoff plan: create ${count('create')}, skip ${count('skip') + count('changed')}${count('orphan') ? `, orphans ${count('orphan')}` : ''} (dry-run)`;
+    const next_actions = approval.approved
+      ? ['crew kickoff --apply']
+      : ['show the PRD and this plan to the product lead', `once approved: ${APPROVE_LINE} at the top of ${file}`, 'crew kickoff --apply'];
+    return warnings.length ? warn(summary, { artifacts, next_actions }) : ok(summary, { artifacts, next_actions });
+  }
+
+  // One person drives the plan — the captain (crew.config.json → captain, written by crew up). Members do not plan.
+  const captain = deps.captain !== undefined ? deps.captain : cfg?.config.captain ?? null;
+  if (captain) {
+    const who = gh(['api', 'user', '--jq', '.login']);
+    const me = who.code === 0 ? who.stdout.trim() : null;
+    if (!me || me.toLowerCase() !== String(captain).toLowerCase()) {
+      return fail('not_captain', `Only the captain ${captain} creates the plan and tasks${me ? `, and you are ${me}` : ''}`, {
+        cause_hint: 'the team has one plan: a second kickoff creates duplicate tasks and a foreign skeleton',
+        retry: 'members: do not plan, work through the crew-workflow cycle (crew task next)',
+        stop_when: 'immediately: tell the human that the captain makes the plan',
+        artifacts: { captain, me },
+      });
+    }
+  }
+  // Kickoff runs from main: otherwise the issues get created but the plan does not reach main (or another branch does).
+  const branch = deps.branch !== undefined ? deps.branch : deps.gh ? 'main' : run('git', ['branch', '--show-current'], { cwd: root, allowFail: true }).stdout.trim();
+  if (branch !== 'main') {
+    return fail('not_main', `crew kickoff --apply must be run on main, but the current branch is ${branch || '?'}`, {
+      cause_hint: 'the plan is published to main together with the tasks; this is not possible from a task branch (worktree)',
+      retry: 'go to the main project folder (git switch main) and run crew kickoff --apply again',
+      stop_when: 'there is no main folder on main — tell the human',
+    });
+  }
+  const assignees = [...new Set(plan.ops.filter((o) => o.op === 'create' && o.assignee).map((o) => o.assignee))];
+  const outsiders = assignees.filter((l) => gh(['api', `repos/{owner}/{repo}/collaborators/${l}`]).code !== 0);
+  if (outsiders.length) {
+    return fail('team_not_collaborator', `crew-team contains people who are not repo members: ${outsiders.join(', ')}`, {
+      cause_hint: 'a task can only be assigned to a member with access (the invitation must be accepted)',
+      retry: `fix the logins in the crew-team block or invite them: crew up --repo <owner/name> --invite ${outsiders.join(',')}; then crew kickoff --apply`,
+      stop_when: 'the login is correct but the invitation is not accepted — ask the human to accept it',
+      artifacts: { outsiders },
+    });
+  }
+
+  const res = await applyKickoff(plan, { parsed, prd: file, gh, sleep: deps.sleep ?? realSleep });
+  if (res.status === 'error') return res;
+  // In tests (gh is stubbed) we do not touch git unless publishing is stubbed explicitly.
+  const pub = deps.publish ? deps.publish() : deps.gh ? { state: 'skipped' } : publishPlan({ root, me: agentId() });
+  if (pub.state === 'failed') warnings.push(pub.note);
+  const artifacts = { apply: true, created: res.created, map: res.map, skipped: plan.ops.filter((o) => o.op === 'skip' || o.op === 'changed').map((o) => o.id), warnings, plan_published: pub.state };
+  const summary = `Kickoff: created ${res.created.length}, skipped ${artifacts.skipped.length}`;
+  const next_actions = ['crew status', 'briefly tell the humans (in their language): how many tasks, who owns what, what is on the demo path, what was cut; members start the cycle: /loop 10m Work through the crew-workflow cycle'];
+  return warnings.length ? warn(summary, { artifacts, next_actions: [...warnings, ...next_actions] }) : ok(summary, { artifacts, next_actions });
+}
+
+const kickoff = {
+  name: 'kickoff',
+  summary: 'Tasks and epics in Issues from docs/prd.md: plan (dry-run) by default, --apply to create (the PRD must be approved)',
+  args: [
+    FILE_ARG,
+    { name: 'apply', type: 'boolean', description: 'create issues (only if the PRD header says status: approved)' },
+  ],
+  run(opts) {
+    return runKickoff(opts);
+  },
+};
+
+export default [taskLint, kickoff];

package/src/commands/labels.js

@@ -0,0 +1,28 @@
+// crew labels sync — create/update labels in the GitHub repo (status:*, area:*, tier:*, risk:*, agent:*).
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ok } from '../core/output.js';
+import { gh } from '../core/exec.js';
+import { HARNESS_ROOT, loadConfig } from '../core/config.js';
+
+export function allLabels(config) {
+  const base = JSON.parse(readFileSync(join(HARNESS_ROOT, 'templates', 'labels.json'), 'utf8'));
+  const areas = Object.keys(config.areas ?? {}).map((a) => ({ name: `area:${a}`, color: 'c5def5', description: `area ${a}` }));
+  const agents = (config.hosts ?? []).map((h) => ({ name: `agent:${h}`, color: 'ededed', description: `done by agent ${h}` }));
+  return [...base, ...areas, ...agents];
+}
+
+export default {
+  name: 'labels sync',
+  summary: 'Create status, area, tier and agent labels in the GitHub repo',
+  agent: false,
+  args: [],
+  run() {
+    const { config, root } = loadConfig();
+    const labels = allLabels(config);
+    for (const l of labels) {
+      gh(['label', 'create', l.name, '--color', l.color, '--description', l.description, '--force'], { cwd: root });
+    }
+    return ok(`Labels synced: ${labels.length}`, { artifacts: { labels: labels.map((l) => l.name) } });
+  },
+};

package/src/commands/metrics.js

@@ -0,0 +1,48 @@
+// crew metrics [--agent codex] [--since 2d] — summary of the .crew/metrics.jsonl log:
+// completion rate, check reruns per task, median claim→PR per agent, top-5 errors.
+import { join } from 'node:path';
+import { ok, warn, fail } from '../core/output.js';
+import { loadConfig } from '../core/config.js';
+import { readEvents, filterEvents, parseSince, aggregate, metricsRoot, humanMs, table, METRICS_FILE } from '../core/metrics.js';
+
+const pct = (x) => (x == null ? null : `${Math.round(x * 100)}%`);
+
+export default {
+  name: 'metrics',
+  summary: 'Team metrics: share of tasks taken to a PR, check reruns, claim→PR time, frequent errors',
+  args: [
+    { name: 'agent', type: 'string', description: 'only this agent: codex or codex/gpt-5 (empty = all)' },
+    { name: 'since', type: 'string', description: 'since when: 2026-12-05, ISO time or 30m / 6h / 2d' },
+  ],
+  run({ agent, since } = {}) {
+    const { root } = loadConfig();
+    const sinceMs = parseSince(since);
+    if (since !== undefined && sinceMs === null) {
+      return fail('bad_input', `--since: cannot parse "${since}"`, {
+        cause_hint: 'expected a date (2026-12-05), ISO time or 30m / 6h / 2d',
+        retry: 'crew metrics --since 1d',
+      });
+    }
+    const file = join(metricsRoot(root), METRICS_FILE);
+    const events = filterEvents(readEvents(root), { agent, sinceMs });
+    if (!events.length) {
+      return warn('No events in the metrics log yet', {
+        artifacts: { file },
+        next_actions: ['work with crew commands (task claim, check, pr open) — events are recorded automatically', 'crew metrics without filters'],
+      });
+    }
+    const agg = aggregate(events);
+    const t = table(
+      ['agent', 'claim', 'PR', 'completed', 'check/task', 'claim→PR (median)', 'errors'],
+      agg.agents.map((a) => [a.agent, a.claims, a.prs, pct(a.completion_rate), a.retries_per_task, humanMs(a.median_claim_to_pr_ms), a.errors]),
+    );
+    const errs = agg.top_errors.length ? `\nFrequent errors: ${agg.top_errors.map((e) => `${e.code} ×${e.count}`).join(', ')}` : '';
+    const weak = agg.agents.filter((a) => a.completion_rate != null && a.completion_rate < 0.5).map((a) => a.agent);
+    return ok(`Metrics: ${agg.total} events, agents: ${agg.agents.length}\n${t}${errs}`, {
+      artifacts: { file, events: agg.total, agents: agg.agents, top_errors: agg.top_errors },
+      next_actions: weak.length
+        ? [`find out why ${weak.join(', ')} drop tasks: gh issue list --label status:blocked`, 'crew eval --dry-run — compare agents on reference tasks']
+        : ['crew status'],
+    });
+  },
+};