/agentflow — the interactive surface (ADR 0019)

The daemon runs intake → build → review → merge unattended. This skill is the same pipeline, driven by hand: it shares agentflow's core (agentflow.intake — the routes, the label set, apply_intake, the brief format), so an issue you drive lands in exactly the shape the daemon would produce.

The skip invariant (never break it): these verbs only ever skip the front steps (triage / grilling / mockup). However an issue gets scoped, it still goes through build → review → your merge, governed by the repo's profile:. You are adding convenience, never authority — nothing here merges code.

Every issue comment you post starts with > *agentflow intake — generated by AI.* (the marker the daemon keys resume off — keep it).

Verbs

/agentflow <verb> <N> in a repo enrolled in the fleet. pickup/triage/scope/build take an issue <N>; review and revise take a PR (number or URL); enroll is the odd one out — it takes a repository path, not an issue or PR, since it's what makes a repo part of the fleet in the first place. There's no issue to race the daemon over, so enroll needs no agentflow:triaging claim.

enroll <path> — bring a repo into the fleet

The first thing you do for a new repo, before any of the verbs above apply. Wraps agentflow enroll (ADR 0049, docs/capabilities.md) with the judgment calls the command can't make for you.

1. Dry run first — agentflow enroll <path> --profile <profile> with no --apply is the default; it prints the plan without writing anything. Read it back to the operator before applying.
2. Choose the autonomy profile deliberately — it's the one decision the command won't make for you (it silently defaults to reviewed if you don't ask):
   • autonomous — the daemon self-grounds, builds, reviews, and merges on its own once the gate is clean. Vibe-code / low domain risk, where the worst case is a revert.
   • reviewed (the safe default) — the daemon builds and gets it reviewed; a human glances and merges. Most repos.
   • guarded — the most conservative rung, not a middle one: grounding against real data or a running app is mandatory, review is dual-tool or human, and a human always merges. Safety-critical projects (ADR 0002).
3. Confirm the surface declaration — an explicit ui-surfaces: in the repo's instructions wins over the tool's guess, and it's what decides whether the heavier UI tooling (Playwright, the screenshot harness) gets installed. Ask if it's not already declared rather than trusting the proposal silently.
4. Apply, then verify — rerun with --apply, then confirm health with the inspection command: agentflow doctor --repo <path>. It should report every required capability ok, not missing or drifted.
5. Do the one thing enrollment refuses to do: harden pull-request CI on public repos — apply prints a warning that it doesn't touch this, and it's the only manual GitHub follow-up. Run /ci-design to shape it — it owns the vocabulary for what belongs on a PR trigger vs. a deploy trigger, and the noise/cost tradeoffs. A hand-rolled ci.yml here becomes the merge gate for every future build in this repo. Queue labels need no manual step (intake creates them on demand), and the fleet's config.toml entry is already written by --apply — don't duplicate either.
6. Review and commit the files enrollment generated inside the target repo (repository instructions, the bundled skill, the screenshot harness if UI-enabled) — apply writes them to disk but doesn't commit.
7. Re-running is a no-op only when nothing drifted. A plain --apply refuses to fix a bundled skill or screenshot harness that has since drifted from the pinned content — it prints WARN: … is drifted … — repository left unchanged and changes nothing. Converging drift is agentflow enroll --sync (dry run) and --sync --apply (writes, commits, pushes agentflow/enroll-sync, and opens a PR per repo) — a fleet-wide sweep, not a per-repo flag. Convergence covers only agentflow's own bundled assets; a drifted vendored skill pack (ui-craft, drive-local-webapp) is reported by agentflow doctor, never rewritten.

Claiming — prevent daemon races on manual verbs

pickup, triage, and scope all do grounding work that takes time. Without a claim, the daemon can reach the same issue in parallel and post a duplicate intake summary. Before starting grounding on any of these verbs, set the agentflow:triaging claim:

gh label create agentflow:triaging --repo "$REPO" --color d4c5f9 \
   --description "A grounding session is triaging this issue" --force
gh issue edit "$N" --repo "$REPO" --add-label agentflow:triaging

Release it when the state label lands or when you give up (the state label dedups from that point; the claim alone is not enough if you abandon mid-session):

gh issue edit "$N" --repo "$REPO" --remove-label agentflow:triaging

A stranded agentflow:triaging claim blocks the issue (fail-safe — never double-triaged) but must be cleared by hand, since intake opens no PR to check liveness against.

pickup <N> — resume a held issue live

The main verb — for a held issue. (A parked PR is the sibling case: use revise <PR>.) For an issue at agentflow:needs-grilling or agentflow:needs-mockup:

1. Claim agentflow:triaging (see above) before any grounding work.
2. Read the issue, its intake comment (the questions/kickoff), and any replies.
3. Ground first if it helps — read the code; if the repo declares a read-only data pull (ciq's ciq-pull-db → ciq.readonly.db), run it and check real numbers.
4. needs-grilling → run /scope in its interview mode and grill the user live — it owns the cadence (the whole answerable frontier per numbered round) and the voice rules. Non-negotiable here: speak in their voice — the app's behavior and their real numbers, never code symbols / ADR numbers / file paths — and every question carries symptom + concrete options + your recommendation. When the decision tree is locked, go to Land it as ready below.
5. needs-mockup → decide the scope first (ADR 0048): local (an addition inside a shipping surface — inherit agentflow/webui/'s identity, vary only the addition) or surface (a whole-surface replacement — the open 3-4 concept tournament). Run /ui-craft in its lock mode to a locked visual spec (charter gate); each variant carries a ≤150-word LOCKED contract (thesis, user path, first viewport, visual rules, required interactions/states, states to screenshot, out-of-scope). Land it as ready with the ★ LOCKED visual spec handoff — the chosen variant's committed mockup path AND its LOCKED contract copied verbatim into the brief so review stays self-contained after archival — and set complexity/effort as usual.
6. Release agentflow:triaging once the state label lands — or immediately if you give up.

triage <N> — force intake on a specific issue now

Run the full intake pass on one issue immediately (don't wait for the daemon to reach it).

1. Claim agentflow:triaging (see above) before any grounding work.
2. Ground → rewrite title/body → route. If it's clear, land it as ready; if a real fork survives, post grilling questions and label agentflow:needs-grilling; if it's UI beyond a minor fix, label agentflow:needs-mockup.
3. Release agentflow:triaging once the state label lands — or immediately if you give up.

scope <N> (or from the conversation) — skip the front, go straight to ready

When the issue is already clear — because you just discussed it with the user, or they filed it well — write the Agent Brief and land it as ready without a grilling round. This is the "I'll just tell you what I want" path.

1. Claim agentflow:triaging (see above) before composing the brief.
2. Run Land it as ready below.
3. Release agentflow:triaging once the state label lands — or immediately if you give up.

build <N> — build a ready issue on demand

The by-hand trigger for an already-ready-for-agent issue (ADR 0022) — the replacement for the retired /go. It submits the same durable Build record as the daemon and returns; the coordinator owns provider launch, continuation, Review/Revise, permits, and final merge/park policy. Do not re-implement or directly launch the build in-session:

uv run python - "$REPO" "$N" <<'PY'
import sys
from agentflow.loop import RepoConfig, build_issue
repo, n = sys.argv[1], int(sys.argv[2])
print(build_issue(RepoConfig(repo, WORKDIR), n))   # WORKDIR = the repo's local main checkout
PY

build_issue refuses and redirects on anything not ready: a held issue points you at pickup <N>; an un-triaged one at triage <N> / scope <N>; one already claimed or in flight is left alone. Only a ready, free issue builds — build adds convenience, never authority (the skip invariant holds).

review <PR> — submit or explicitly force an exact-head review

Agentflow's own reviewer (reviewer.py) — exact-head, cross-tool, policy-gated — is the fleet's review; /review's two-sub-agent Standards+Spec pass is the by-hand tool for work that never entered the pipeline, not a substitute for this.

Resolve <PR> to its repository and local enrolled checkout, then call the durable review entry point. The default follows the repo profile and never weakens autonomous independence:

uv run python - "$REPO" "$PR" <<'PY'
import sys
from agentflow.loop import RepoConfig, review_pr
repo, pr = sys.argv[1], int(sys.argv[2])
print(review_pr(RepoConfig(repo, WORKDIR), pr))  # WORKDIR = enrolled local main checkout
PY

If the maintainer explicitly asks to force same-tool review, call it once with force_same_tool=True and show the returned warning verbatim. Do not continue on an ambiguous reply. Only after they explicitly confirm the human-merge-only trade-off, call:

review_pr(RepoConfig(repo, WORKDIR), pr,
          force_same_tool=True, maintainer_confirmed=True)

The confirmed path marks the review tainted, never auto-merges it, and leaves automatic exact-head cross-tool recovery to the daemon if the other tool returns while the PR remains open.

revise <PR> — resume a parked PR live

The PR-side sibling of pickup (which is issue-only). For an open PR the daemon parked — it carries a > *agentflow: parked for human review.* comment (gate.park), typical of a reviewed/guarded repo where a human merges, so the daemon won't touch it again. This skips nothing that gates code (it does not go through Land it as ready); it hands the human a clean PR to merge.

1. Resolve <PR> (number or URL) → repo, head branch, the issue it Closes.
2. Read the latest park comment and any human replies after it. gate.park writes a Review actions: list as - **<action>** <file>:<line> — <summary>. Interpret the four actions exactly: fix_before_completion is the code worklist; necessary_follow_up identifies an already-filed out-of-scope issue; ask_maintainer requires a human choice before editing; discard_preference creates no work.
3. Ground on the branch, never on main: work in a worktree on the PR head branch (/spin-worktree, or the existing build worktree). git fetch origin and rebase once onto origin/main — a parked PR is usually CONFLICTING; resolve the conflicts. If you can't resolve them safely, stop and say so rather than forcing.
4. Ship each fix_before_completion action, honor the outcome of any ask_maintainer choice, leave proved follow-up issues out of this PR, discard preferences, and keep the repo's test gate green. Same output contract as a coordinated Revise (loop.REVISE_PROMPT), driven by hand only because this command is explicitly taking over a parked human boundary.
5. Push to the same branch — never open a new PR.
6. Skip invariant holds — you do not merge. Post one PR comment, prefixed > *agentflow revise — generated by AI.*, saying what you fixed and that it's rebased and ready for the human's merge.

Land it as ready

When a decision is settled, produce the same artifact the daemon does and write it with agentflow's own code so the shape is identical:

1. Compose the Agent Brief (Markdown), starting with the disclaimer line, with these sections: Summary · Verified (claim re-derived against named code on the real data, with numbers) · Current behavior · Desired behavior · Key interfaces ("explore fresh; pointers, not line numbers" + traps) · Interface shape (one or two sentences on the caller-facing front door judged by the charter's depth test; if the change is purely internal to an existing interface, say so instead of omitting the section) · Acceptance criteria (a checkbox list; grounded numeric literals where they apply, and a test that fails if the bug regressed) · Out of scope.
2. Pick the two dials: complexity ∈ {standard, deep}, effort ∈ {low, medium, high, extra}.

3. Write it with the shared core (retitles, writes the brief into the issue body — where the builder and reviewer actually read it, ADR 0016/0022 — preserving the as-filed text under a collapsed <details> block and leaving a short conversational comment on the thread; sets ready-for-agent + the dials, clears any hold label). A re-intake updates the body brief in place, never a second one:

   LABELS=$(gh issue view "$N" --repo "$REPO" --json labels -q '[.labels[].name]')
   uv run python - "$REPO" "$N" "$TITLE" "$LABELS" <<'PY'
   import sys, json
   from agentflow.intake import IntakeResult, IntakeRoute, apply_intake
   from agentflow.runner import Complexity, Effort
   repo, n, title, labels_json = sys.argv[1], int(sys.argv[2]), sys.argv[3], sys.argv[4]
   brief = """<the Agent Brief markdown you composed>"""
   result = IntakeResult(IntakeRoute.READY, brief, title,
                         Complexity.DEEP, Effort.MEDIUM)   # set the dials you chose
   print(apply_intake(repo, n, title, current_labels=json.loads(labels_json), result=result))
   PY

   The LABELS fetch passes the issue's real labels so apply_intake clears the old needs-grilling/needs-mockup hold — passing [] would leave both hold and state label set, causing the daemon to treat the issue as both held and ready simultaneously. The daemon's build queue picks it up from there — or run build <N> (above) to build it now.

Notes

• Don't invent labels or a brief format — use agentflow.intake so the daemon and you stay one source of truth.
• A plain GitHub reply on a held issue also resumes it: the daemon re-checks on your comment and promotes or sharpens, no /agentflow needed (ADR 0019). Use pickup when you'd rather drive live.
• revise never merges and never re-triggers the daemon — a parked PR stays yours to merge (ADR 0017). It resolves the park comment's four-action worklist plus named conflicts; it is not a fresh review, and it touches nothing in the profile: gate.
• Install: symlink skills/agentflow into your skills dir (e.g. ~/.claude/skills/).