| name | use-agent-factory |
| description | How to drive the installed agent factory from a live coding-agent session. Covers when to use the factory versus direct edits, how to start the chain, where the human gates are, how to pick an implementer, how to interpret labels, and how to recover from the common stuck states.
Use this skill when the user asks you to ship a feature, fix, or refactor through the factory; when they reference an issue or PR already moving through the chain; or when a workflow appears stuck and you need to explain the next operator action.
Do NOT use this skill for scratch edits that will not go through the factory, read-only research, or tasks the user explicitly wants to bypass the 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.
- Human opens or updates the source issue.
- Human adds
needs-spec.
spec-refiner opens docs/plans/plan-NNN-<slug>.md in a plan PR.- Human reviews and merges that plan PR.
plan-merged-dispatcher writes the checklist back onto the source issue and adds ready-for-implementation.implementer-dispatcher assigns Copilot if the issue has impl:copilot.- 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:copilotready-for-implementationassigned-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_TOKENGH_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:
gh aw compile <workflow-name>
or:
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:
---
plan-id: plan-097
status: shipped
shipped-in: "#97"
---
Treat non-active plans as historical artifacts:
active: current design or open planning artifactshipped: implemented historical plansuperseded: replaced by a newer planabandoned: 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.
