vgpu agent flow

You are the lead. Specialists live in .subharness/agents/ and run through the subharness CLI (root devDependency; call it as pnpm exec subharness or npx subharness). You own every conversation with the human, every decision, every worktree, and every merge. Specialists never talk to the human and never see this conversation — each prompt must carry the full context.

Team

Fallback (→) only happens when the first harness is unavailable before the task starts (missing CLI, no login, no fx Gateway access). A task that fails after starting is never retried elsewhere; re-run it yourself if needed.

Workspace

All pipeline artifacts are gitignored scratch under .context/work/<topic>/ (kebab-case topic):

.context/work/<topic>/
  brief.md                 # you: the problem statement in the human's words + constraints
  research/<angle>.md      # researchers: raw findings
  design/api-options.md    # api-designer: alternatives + snippets
  decisions.md             # you: locked decisions (after human validation)
  plan/index.md            # planner
  plan/tasks/T01-*.md      # planner
  plan/progress.md         # planner creates; you keep it current
  plan/progress/T01.md     # implementers
  reviews/integration-*.md # you: saved integration review output
.context/worktrees/<topic>-<lane>/   # git worktrees for parallel lanes

Never commit .context/.

Phase 0 — Select the repository workflow

Before Phase 1, follow AGENTS.md and .github/guides/workflow-context.md: establish the directing person's role (run its gh permission lookup if unknown) and the task's origin, then select maintainer-original (internal work), maintainer-adoption (anything originating from an external issue/PR), or external-contributor. Announce the workflow and record it in brief.md:

Workflow: maintainer-original | maintainer-adoption
Origin: internal request, or source issue/PR URL + author
Triage: confirmed problem, evidence, disposition
Scope: accepted outcome and non-goals

The phases below implement that workflow's plan and implementation stages; they do not replace its rules on baseline, changesets, PR delivery, or merge authorization. Every lane branches from a freshly fetched origin/canary (<base> below) unless the task is a documented production lane. For adoption, pass the source links to every specialist as evidence and state that the external implementation must not be copied, cherry-picked, or merged. Stop at the stage the human asked for: a research or design request ends with findings, a planning request with the plan.

Phase 1 — Research

1. Write brief.md. Split the question into 2–5 independent angles (e.g. "three.js / Babylon API shape", "Bevy / wgpu resource lifetime", "screen-space GI papers 2018–2025").
2. Launch one researcher per angle in parallel, each as its own background command:

   npx subharness run repo:api-researcher --prompt "Topic: <topic>. Brief: .context/work/<topic>/brief.md. Question: <angle question>. Write .context/work/<topic>/research/<angle-slug>.md."
   

   Use api-researcher for API questions and graphics-researcher for shaders, materials, simulations, and rendering techniques.
3. Researchers do not conclude. Skim their files yourself only to decide whether an angle needs a follow-up run (subharness send <session-id> --prompt "...").

Phase 2 — API design (skip for work with no public API change)

npx subharness run repo:api-designer --prompt "Topic: <topic>. Read brief.md and research/ under .context/work/<topic>/. Design the public API for <problem>. Write design/api-options.md."

Expect 2–4 alternatives; a single recommendation only when one clearly wins.

Phase 3 — Validate with the human and lock decisions

1. Present the alternatives to the human: short summary, one key snippet each, trade-offs, the designer's open decisions, and your recommendation. Use the ask-question tool for each open decision. Iterate (re-run the designer with feedback via send) until every decision is settled.
2. Write decisions.md: one numbered section per decision (D1, D2, ...) with the chosen option, the final signatures/defaults/error codes, rejected alternatives with one-line reasons, and explicit non-goals. Mark it Status: locked (<date>). Only the human can reopen a decision.

Phase 4 — Plan

npx subharness run repo:planner --prompt "Topic: <topic>. Plan the implementation of .context/work/<topic>/decisions.md. Write plan/ under .context/work/<topic>/."

Review plan/index.md for lane isolation (disjoint files between lanes) and missing tasks (docs, changeset, examples, bundle budgets, native GPU tests), and check that its PR record is self-contained. Show the human the lane summary before starting implementation.

Phase 5 — Implement

For each lane that can start:

1. Create an isolated worktree and bring the pipeline folder into it:

   git fetch origin canary
   git worktree add .context/worktrees/<topic>-<lane> -b <topic>/<lane> <base>   # <base> = origin/canary
   mkdir -p .context/worktrees/<topic>-<lane>/.context/work
   cp -R .context/work/<topic> .context/worktrees/<topic>-<lane>/.context/work/
   (cd .context/worktrees/<topic>-<lane> && pnpm install --frozen-lockfile && pnpm build)
   

   A single-lane plan can run in the current workspace instead.
2. Run the lane's tasks in order, one implementer session per task, each lane as its own background command:

   npx subharness run repo:implementer --cwd .context/worktrees/<topic>-<lane> --prompt "Topic: <topic>. Implement task .context/work/<topic>/plan/tasks/T03-<slug>.md. Base ref: <base>. Governing: .context/work/<topic>/decisions.md."
   

   The implementer writes tests first, runs writer for docs in parallel, runs reviewer (max 2 rounds), commits on the lane branch, and writes plan/progress/<id>.md.
3. After each task, copy the lane's plan/progress/<id>.md back and update plan/progress.md. Report blocked tasks and disputed findings to the human instead of forcing them through.

Phase 6 — Integrate, review, polish

1. Merge lane branches into the feature branch in the plan's integration order; resolve conflicts yourself and run the checks the plan lists after each merge.
2. Run your own integration review over the whole branch:

   npx subharness run repo:reviewer --prompt "Integration review for <topic>. Base: <base>. Governing: .context/work/<topic>/decisions.md and plan/index.md. Review the full branch diff, focusing on cross-task consistency, public API contract, docs vs code, and release hygiene."
   

   Save the output to reviews/integration-<n>.md.
3. Hand blocker/major findings (and cheap polish) to the builder as a numbered list:

   npx subharness run repo:builder --prompt "Topic: <topic>. Fix these findings on the current branch: 1. ... 2. ... Verify with: <commands>."
   

   Re-review if the builder changed behavior. Then summarize to the human: what shipped, checks run, and remaining findings. When the human asks for a PR, follow .github/guides/pull-requests.md and .github/pull_request_template.md against canary. Build the description from plan/index.md's PR record, the key decisions.md entries, and the implementers' validation notes; reviewers cannot see .context/. Declare exactly one PR type (development for normal work) and one release impact matching the diff, and run pnpm migrations:check. For adoption, link the sources and credit the actual contribution; add a Co-authored-by trailer only when verified and warranted. Opening a PR does not authorize merging, closing sources, or releasing.
4. Remove finished worktrees: git worktree remove .context/worktrees/<topic>-<lane>.

Running specialists

• Prefer one ordinary subharness run ... per specialist through your background-command controls, continue other work, and collect the result. Otherwise use --detach and later subharness wait <task-id>. Never use shell &.
• Follow up in the same session with subharness send <session-id> --prompt "..."; cancel with subharness cancel <task-id>. subharness dashboard shows live sessions.
• Exit code 0 means a response arrived, not that the goal was met — read the response.
• Check readiness without spending a model turn: npx subharness check repo:<name>.

Personal access (per user, not committed)

Research runs on fx through AI Gateway, which needs an explicit connection. Use the OIDC token of the vercel-labs/vgpu project, configured once in the main checkout (worktrees read it from there):

cd <main-checkout>
vercel link --yes --project vgpu --scope vercel-labs   # writes .vercel/project.json
vercel env pull .env.local --yes                       # writes VERCEL_OIDC_TOKEN

vercel link may append .vercel / .env*.local to .gitignore; revert that and add them to .git/info/exclude instead. Then create <main-checkout>/.subharness/agents.local.json (auto-excluded from Git):

{
  "access": {
    "fx": [{ "type": "vercel-oidc", "project": ".", "envFile": ".env.local" }]
  }
}

Verify with npx subharness check repo:graphics-researcher. The OIDC token expires after about 12 hours; when fx fails with an expired-token error, re-run vercel env pull .env.local --yes in the main checkout. Without fx access the researchers fall back to Codex. Codex and Claude Code use their native subscription logins by default.