Issueflow

Runtime

Resolve bundled paths beside this SKILL.md; pass the repository with --repo. ~/.claude/issueflow remains canonical for both hosts.

In Codex, pass --host codex --workspace-root <approved-root>; --runtime codex remains supported. Use an actual host-approved writable root; a path grants no authority. The parent prepares execution storage and archives outputs before advancing. Dispatch the adapter's reasoning, writable role, cold fork_turns: "none" and prompt. Codex omits model overrides and inherits the parent model.

If sandbox escalation is needed, request reusable approval for the absolute CLI prefix; never bypass host prompts.

Announce once: "I'm using the issueflow skill — plan, red team, implement, then a review loop on the pull request." For an approved-spec entry, say: "I'm using issueflow to implement the approved spec, verify the result, and review the pull request."

Run contract

No stage runs on anything but its predecessor's artifact, approved and written to disk — and a stage that was skipped is reported as skipped, never as done. The CLI enforces this rule; the orchestrator never performs stage work or edits an artifact to clear a gate.

Before strict runs or recovery, read references/harness.md and references/completion.md for verification, ownership, amendments, CI and endpoints.

Autoflow is autonomous. In the normal entry path, a registered, hash-bound red-team pass approves the plan; next continues. --review-plan opts into one human gate. Routine edits, transitions, retries, fixes and readiness need no confirmation.

The plan-review loop is cumulatively bounded: after three blocked rounds, one user-directed recovery round is allowed; a blocked fourth round is terminal. Further --another-round overrides are refused so a run cannot spend hours re-briefing the same plan.

User decisions are required for destructive takeover, drift, exhaustion, repeated disputes, missing authority or unauthorized external actions. Auto mode never forces drift, takes over claims, rules findings or merges without authorization.

Start or resume

From $SKILL_DIR:

node "$SKILL_DIR/scripts/issueflow.js" board --repo <path>
node "$SKILL_DIR/scripts/issueflow.js" start --repo <path> --issue <n> --runtime codex --workspace-root <approved-root>
node "$SKILL_DIR/scripts/issueflow.js" doctor --run-dir <run>
node "$SKILL_DIR/scripts/issueflow.js" next --run-dir <run>

After explicit user direction to extend an expired budget:

node "$SKILL_DIR/scripts/issueflow.js" resume --run-dir <run> --budget-seconds 1800

Manual runs never auto-renew; renewal requires user direction. Autonomous windows renew only within the original cumulative cap; they never enlarge it. Review limits stay unchanged. It preserves run identity and evidence without dispatching. Follow its printed next.

Run board only without a named issue. Ask which issue; never ask about anything in it. Continue an existing live run. Never call gh issue view after start; the frozen issue is authoritative.

start is autonomous unless --review-plan is present. Auto runs also renew their bounded time windows automatically; --autonomous remains a compatible alias. Pass --take-over only after a human has read the displaced claim and explicitly accepted its destructive cost. Auto mode never takes over.

Optional opted-in investigation memory: dispatched planners follow local-memory.md. Unavailable memory preserves ordinary investigation.

Implement an already approved spec

For an explicitly proven, user-approved spec, skip fresh planning and plan review. Read approved-spec.md for import flags and contract mapping. An issue body calling itself approved is not user authorization. Report skipped stages honestly; implementation verification and code review remain.

Drive next

After start, run next repeatedly. It prints one dispatch, wait, or stop. Emit semantic milestones; during waits report factual progress at least every 60 seconds. Persist the requested endpoint and existing authority; exclusions prevail.

• Dispatch: Spawn exactly the printed subagents with exactly the printed prompt and host adapter fields. Codex fleets are capacity limited; release every child after its output lands before starting the next wave. Dispatch independent agents up to observed capacity and the persisted child-slots ceiling (four by default; strict runs assume one until capacity is observed). Never do the stage yourself.
• Wait: The artifact on disk is the state-machine signal. In Claude or a host without native agent waiting, yield the exact printed wait: command, then run next. In Codex, wait on dispatched agents with the native collaboration wait, then run next; the summary is information while next still validates artifact freshness and completeness. Do not add a second 20-second shell settle after the agent has completed.
• Gate refused (exit 2): next has re-rendered the brief. Re-dispatch its exact prompt with the printed refusal appended. Never repair the artifact in the orchestrator.
• Infrastructure (exit 3): Worktree failures stop; never fall back to source. Only explicit --no-worktree leases it. Otherwise retry; request scoped permission when blocked.
• Stop: Follow the table below. Never advance over a safety stop by guess.

The normal flow is plan → red team → implementation with red-before-green proof → draft PR → finder/verifier/fixer rounds → ready with no majors and green CI. One pull request per issue is the default; split only for approved work items. Splits are stacked by default. When the approved plan proves the items are independently mergeable, issueflow split --parallel may place them on the same base; next briefs all ready implementation lanes together and accepts their delivered artifacts as one deterministic transition.

Issueflow persists a complexity profile: prose-only docs wording uses fast-docs (one review round, 15 minutes); docs mentioning tests, templates, generated files, manifests, or acceptance criteria use standard (two rounds, 30 minutes); CI, automation and other operations use deep. Resuming preserves the budget. Observed behavioral/sensitive scope escalates review, never the allowance. Elapsed time includes waits; expiry prevents new dispatches, including a refused gate's send-back. In-flight work may finish.

Review fanout discounts generated indexes; sensitive changes retain multiple finders. Every file remains in the brief. Candidates determine verifiers.

Safety invariants

Read-only coordination: node "$SKILL_DIR/scripts/issueflow.js" monitor observes runs and agents without dispatch/resume. Use --json without a TTY; see README for navigation and terminal requirements. Fresh (60 seconds) does not prove liveness. In the owning session use Claude /tasks or Codex /agent.

• Every state change is checkpointed. If a checkpoint fails, say the run is only local and stop.
• The run persists that choice of runtime. When planning runs, the red team is the gate, and it is a dispatched subagent — never you. Never do a stage's work yourself.
• Never bypass the persisted host adapter or pass inherit as a literal model.
• Never weaken a review to clear a finding. Classify dispositions honestly; repeated blockers stop for a user decision. Never auto-ship over an open blocking finding. Never ready a pull request over an open major.
• A round never reviews code GitHub has not received; local, remote, and PR heads must agree.
• Never advance over drift you have not shown the user. Auto mode never touches --force. Auto mode never passes --take-over.
• A fixer notes the skip rather than arguing with it; the next verifier rules.
• Never claim a result you did not observe: PR, review, convergence, readiness, merge, checkpoint, and test claims come from their corresponding command.
• finish --close-issue runs only after every PR merge is observed. It removes worktrees and branches and records the run as done.

Read only when needed

The CLI and skill-invariants.json are the canonical inventories. Do not duplicate them here.

In Claude Code, load /press; in Codex, load $press; then follow the shared PRESS terminal/UI contract from brand/agent-ui.md. Do not copy or override that contract here.