Epic Cockpit Guide

What Is the Epic Cockpit?

When you run work through Generacy, the cluster already automates the agent side: it picks up labeled issues, drives them through specification, planning, implementation, and validation, and opens pull requests.

What it can't automate away is your side of the workflow. Agents pause at gates — points where they need a human decision: answering clarifying questions, reviewing a spec or a PR, deciding to merge. On an epic with many issues in flight, noticing which issue is waiting on you means refreshing the GitHub UI across all of them.

The Epic Cockpit replaces that polling treadmill with a set of /cockpit:* commands in Claude Code:

• It watches for you. One watcher covers every issue in the epic, across every repository the epic touches, and notifies you on each state change.
• It pre-assembles every decision. Drafted clarification answers, a code review summary, merge readiness — each gate collapses to a single approval.
• You keep the judgment. The cockpit automates the legwork; answers, review verdicts, and scope decisions are always yours.

Prerequisites

On a Generacy cluster: nothing to set up. Cluster setup installs the cockpit plugin automatically, so /cockpit:* commands resolve in any fresh Claude Code session. If you haven't launched a cluster yet, start with the Onboarding Guide.

Standalone (outside a cluster), you need three things:

1. The cockpit plugin. Add the Generacy marketplace to your Claude Code settings, then install the cockpit plugin:
   text

   {
     "extraKnownMarketplaces": ["generacy-ai/agency"]
   }

2. The generacy CLI on your PATH:
   bash

   npm install -g @generacy-ai/generacy

3. The GitHub CLI, authenticated: gh auth login

Filing an Epic

The cockpit has no config files or manifests to maintain — the epic issue itself is the source of truth. File a GitHub issue whose body lists the child issues as task-list items, grouped under ### phase headings:

## Overview
Ship the new billing flow.

### P1 — Backend
- [ ] acme/api#101 — Billing service skeleton
- [ ] acme/api#102 — Stripe webhook handler

### P2 — Frontend
- [ ] acme/web#55 — Checkout page
- [ ] acme/web#56 — Billing settings panel

• Each - [ ] owner/repo#N line is a child issue. Children can live in different repositories — the cockpit watches them all.
• Each ### heading is a phase you can queue as a unit.
• The body is re-read on every poll, so issues you add mid-epic — say, a ### Bugs section appended after manual testing — join the watch automatically.

The Loop at a Glance

A phase of an epic flows through the cockpit like this:

1. Queue — /cockpit:queue hands a phase's issues to the cluster.
2. Watch — /cockpit:watch notifies you as issues change state, suggesting the next command each time.
3. Clarify — when an agent asks questions, /cockpit:clarify drafts grounded answers for your approval.
4. Review — when a spec, plan, or pull request is ready, /cockpit:review assembles it for your verdict.
5. Merge — when validation completes and checks are green, /cockpit:merge lands it.
6. Repeat for the next phase — or let /cockpit:auto drive the loop.

At any point, /cockpit:status <epic-ref> prints a one-shot snapshot of every child issue: its phase, current state, and pull request with a checks rollup. Epic refs and issue refs can be given as a bare number (in the current repo), owner/repo#N, or a full GitHub URL.

Queue a Phase

/cockpit:queue acme/planning#42 P1

Queueing is the "go" trigger: it assigns the phase's issues to the cluster account and applies the workflow label (default process:speckit-feature) so the cluster picks them up. The command always shows you a preview — exactly which issues will be queued — and asks for confirmation before doing anything.

Use --label to queue with a different workflow (for example a bugfix pass over a ### Bugs phase), and --issue to queue a single issue instead of a whole phase.

Watch for Transitions

/cockpit:watch acme/planning#42

Watch is a pure sensor: it polls the epic's issues (default every 30 seconds, batched per repository to respect rate limits) and never changes anything on GitHub. Each real state transition becomes one notification in your session, with the suggested next command:

[cockpit] acme/api#101 phase:implement → waiting-for:implementation-review · suggested: /cockpit:review 101 --gate implementation-review

The watcher reports every actionable or terminal state — including agent errors and failures, with the error comment attached. Silence is never mistaken for success. What you'll see, and what to do about it:

The watcher also emits phase-complete when every issue in a phase has merged ("all P1 issues merged — queue P2?") and epic-complete when the whole epic is done.

Answer Clarifications

/cockpit:clarify acme/api#101

When an agent pauses with questions, answering them well means digging back through the spec, the plan, and the code. Clarify does that digging for you:

1. It fetches the agent's questions plus the relevant spec, plan, and code.
2. It drafts an answer per question, grounded in that context — each one presented with the question, the options the agent posted, a recommendation, and the reasoning behind it.
3. You approve the whole batch, edit individual answers, or skip — one decision for the batch.
4. On approval it posts a single comment and advances the gate; the agent resumes on the cluster's next poll.

Agents sometimes come back with a follow-up round of questions — the watcher will tell you, and you run clarify again.

Review Gates

/cockpit:review acme/api#101 --gate implementation-review

Review handles every human-verdict gate in the workflow. The --gate name is one of: spec-review, clarification-review, plan-review, tasks-review, or implementation-review.

• Artifact gates (spec, clarification, plan, tasks) summarize the artifact so you can judge it without opening the branch.
• Implementation review runs a full code review of the pull request in a dedicated subagent and presents the findings with a suggested verdict.

Approve, and the gate advances — the agent moves to its next phase. Request changes, and the cockpit posts your feedback as inline PR comments; the agent picks the threads up, addresses them, and the watcher tells you when it's ready for another look.

Merge on Green

/cockpit:merge acme/api#101

When an issue reaches completed:validate and every required check is green, merge squash-merges the pull request. If checks are red, it refuses — and instead spawns a bounded fixer subagent to repair the failing checks, then re-evaluates. Still red after the fix attempt? It stops and hands the decision back to you.

Auto Mode

/cockpit:auto acme/planning#42

The six commands above are assist mode: watch suggests, you invoke. Auto mode removes that last bit of legwork. One sentence: auto mode automates transport — running the next command — and leaves judgment exactly where assist mode put it.

Auto watches the epic, dispatches each transition through the same flows you'd run by hand, and interrupts you for exactly four kinds of decision:

• Clarification batches — drafted answers, one batch approval.
• Review and validation verdicts — approve or request changes.
• Phase-queue confirmations — "P1 complete — queue P2 (4 issues)?"
• Escalations — red checks that survived a fix attempt, or agent errors: retry, skip, or stop.

Nothing outside that list ever prompts you; nothing on it ever proceeds without you. The one deliberate exception to "every action gates": a validated issue with green checks merges without asking, because your verdict already happened at implementation review — validation plus green checks is mechanical.

Every action auto takes is recorded as a one-line ledger entry (issue · transition · action · outcome), printed in the session and appended to a run file under .generacy/cockpit/auto-runs/ — a complete audit trail of the run. The loop exits with a summary when the epic completes.

No epic? Use a tracking issue

Auto doesn't require a formal phased epic. Point it at any issue whose body carries task-list refs, or have it file one for you:

/cockpit:auto --tracking acme/api#120   # drive an existing tracking issue
/cockpit:auto --new "Payment bugs"      # file a fresh tracking issue, then drive it

Because the scope lives on the tracking issue rather than in your session, a restarted session picks up exactly where the last one left off.

Safety Guarantees

• Merge never fires on red checks. No exceptions, no override flag.
• Every gate prompts. There is no per-gate auto-approve and no "full auto" — judgment is never delegated.
• Cockpit comments are marked. Every comment the cockpit posts carries an HTML marker, so you can always audit what was automated versus written by hand.
• Mutations confirm first. Queue previews its issue set before acting; advance refuses if the issue's active gate isn't the one you named.
• Actions re-check live state. Every actuator re-fetches the issue's current state immediately before acting, so a stale notification can't trigger the wrong action.

Configuration

None required. Two optional overrides live in a cockpit: block in .generacy/config.yaml:

cockpit:
  owner: alice          # GitHub owner; defaults to your gh login
  assignee: some-bot    # queue target; defaults to your gh login

Per-run knobs are flags instead: --interval on watch (default 30s), --label and --assignee on queue.

Quick Reference

Every command wraps a generacy cockpit CLI verb you can also run directly in a terminal — generacy cockpit --help is the canonical reference.

Troubleshooting