use-agent-factory

# Use The Agent Factory ## Purpose This skill is the operator handbook for an installed target repo that uses this template. The factory is issue-first and label-driven. The source issue is the unit of work from start to finish. There is no sub-issue layer. Use this skill to answer: - how to start new work through the factory - which labels mean what - when to wait for a human gate - when direct route applies - how to recover from stuck workflow states ## When to invoke Activate this skill when any of these are true: - the user wants to ship a non-trivial change through the factory - the user references a source issue, plan PR, or implementation PR already in the chain - the user asks what a factory label means - the user asks why the chain is stuck or what should happen next - the user asks you to prepare work so the factory can pick it up correctly Skip this skill when the work is intentionally bypassing the factory, is purely exploratory, or does not produce a PR to `main`. ## Factory flow The chain is: `issue -> needs-spec -> spec-refiner -> plan-worthy OR direct route OR blocked -> plan-merged-dispatcher -> implementer-dispatcher -> PR review -> merge -> learn` There is also a manual shortcut: `issue -> needs-plan -> trigger-plan -> ready-for-implementation -> implementer-dispatcher` ### Path 1: Plan-worthy Use this for most non-trivial work. 1. Human opens or updates the source issue. 2. Human adds `needs-spec`. 3. `spec-refiner` opens `docs/plans/plan-NNN-<slug>.md` in a plan PR. 4. Human reviews and merges that plan PR. 5. `plan-merged-dispatcher` writes the checklist back onto the source issue and adds `ready-for-implementation`. 6. `implementer-dispatcher` assigns Copilot if the issue has `impl:copilot`. 7. The coding agent opens an implementation PR. ### Path 2: Direct route Use this only for clearly bounded trivial work. `spec-refiner` skips the plan PR, assigns Copilot in the same run, and adds: - `impl:copilot` - `ready-for-implementation` - `assigned-to-agent` ### Path 3: Blocked or terminal If the issue is unclear, duplicated, paused, or needs human input, `spec-refiner` removes `needs-spec`, adds `blocked-on-human`, and leaves a comment explaining the next human action. ## Required setup Before the factory can work end to end, the target repo needs: - Actions workflow permissions set to read and write - GitHub Actions allowed to create pull requests - Copilot coding agent enabled - Copilot code review enabled if you want inline review help - Actions permissions set broadly enough for the factory - `COPILOT_GITHUB_TOKEN` - `GH_AW_AGENT_TOKEN` - the factory label set created by `install.sh` If the optional Projects board layer is enabled, add the repo-specific `PROJECTS_PAT` secret and its supporting workflows too. ## Routing rules Only one implementer label auto-routes: | Label | Meaning | |-------|---------| | `impl:copilot` | the only auto-routable implementer | If a human wants Claude or Codex, do that handoff outside the automated path after the source issue is active. ## Operator moves by label | Label | What it means | Operator move | |-------|---------------|---------------| | `needs-spec` | issue is waiting for spec refinement | wait for `spec-refiner` | | `needs-plan` | plan PR is open, or the issue is using the manual skip-spec shortcut | review the plan PR if one exists; otherwise let `trigger-plan` activate the issue | | `ready-for-implementation` | source issue is ready for assignment | wait for `implementer-dispatcher` | | `assigned-to-agent` | source issue has been dispatched | wait for the implementation PR | | `ai-reviewed` | reviewer found no blockers | ready for human merge review | | `fast-track` | reviewer found the PR small and clean | ready for merge | | `needs-changes` | reviewer found blockers | use `/pr-fix` or push a manual fix | | `spec-drift` | PR went beyond the plan | decide whether to narrow the PR or expand the plan | | `needs-rebase` | PR branch is behind `main` | let `conflict-resolver` run | | `eval-regression` | promoted-learnings regression failed on the PR | inspect the eval result and decide whether to fix before merge | | `blocked-on-human` | automation is paused | read the latest comment and act on it | | `human-review` | hard stop | keep automation paused until a human removes the label | ## Common stuck states ### No plan PR appeared after `needs-spec` Check whether the issue was direct-routed instead. If it now has `assigned-to-agent`, `ready-for-implementation`, and a comment explaining the fast track, that is expected. If neither a plan PR nor a direct-route comment exists, inspect the failed workflow run and the issue comments for missing setup or `NEEDS HUMAN INPUT`. ### Issue was labeled `needs-plan` directly That is a supported operator shortcut. `trigger-plan` should activate the issue into `ready-for-implementation`. If the issue stays on `needs-plan`, check which of these cases applies: - a merged plan file exists and `trigger-plan` is trying to recover the checklist path - a plan PR is still in flight and `spec-refined` is present - the workflow failed before it could activate the issue ### Reviewer did not post a verdict If the PR is ready for review and still got no verdict, retrigger by toggling draft state or by pushing a new commit. ### PR is behind `main` Use `needs-rebase`. `conflict-resolver` will attempt a clean merge from `origin/main`. If it cannot, resolve the conflict manually and push. ### `/pr-fix` could not edit the needed file The source repo version of `/pr-fix` needs an allowlist that covers the real edit surface. If it hits an allowlist failure on root-level docs or harness files, update the workflow source and recompile. ### Lock-file sync failed A workflow source changed without regenerating its `.lock.yml`. Run: ```bash gh aw compile <workflow-name> ``` or: ```bash gh aw compile ``` Then commit the regenerated lock file alongside the workflow source. ## Plan file lifecycle Merged plans may be stamped with YAML frontmatter like: ```yaml --- plan-id: plan-097 status: shipped shipped-in: "#97" --- ``` Treat non-`active` plans as historical artifacts: - `active`: current design or open planning artifact - `shipped`: implemented historical plan - `superseded`: replaced by a newer plan - `abandoned`: intentionally not completed Do not use a `shipped`, `superseded`, or `abandoned` plan as the current source of truth without checking the live code. ## When to bypass the factory Bypass can make sense for: - emergency fixes while the factory itself is broken - edits to the factory that would cause automation loops - tiny changes the user explicitly wants handled directly When bypassing, say so clearly and do not pretend the normal chain is running. ## One-line summary Write a crisp source issue, add `needs-spec`, let the workflows move the issue through planning or direct route, react to labels instead of improvising state changes, and treat plan files plus the source issue as the durable record of the work.