Agent Factory Template

An agent factory template for GitHub repositories, built on GitHub Agentic Workflows (gh-aw).

Status

This repository is still very much an experimental template.

It is not entirely stable yet. The flow, prompts, labels, and installer behavior are still being adjusted. Treat this repo as an evolving baseline, not a finished production product.

Current Factory Shape

The source issue is the unit of work from start to finish.

spec-refiner now has three paths:

1. Plan-worthy: open a plan PR, wait for merge, then dispatch the source issue.
2. Direct route: for clearly bounded trivial work, assign Copilot directly without a plan PR.
3. Blocked or terminal: hand the issue back to a human with blocked-on-human.

Core properties of the current flow:

• Plan files use the source issue number in the filename.
• The implementation checklist is written back onto the source issue after a plan PR merges.
• Merged plan files are stamped as status: shipped, so older plans can be treated as historical artifacts.
• Trivial issues can go straight to Copilot without a plan PR.
• Non-trivial issues go through a plan PR and human merge gate.
• Only impl:copilot can be auto-routed.
• factory-health creates a weekly observability issue for workflow outcomes and stuck-state signals.

Recent stabilizations included here:

• reviewer auto-labels PRs that are behind main with needs-rebase
• reviewer refuses to self-review PRs that modify its own instructions or adjacent guardrails
• reviewer blocks bot-authored implementation PRs that do not close their source issue
• reviewer blocks plan PRs that contain closing keywords in the PR body
• conflict-resolver can safely merge workflow-file changes from main
• eval-creator-ci raises eval-regression when promoted learnings fail on a PR and clears it on the next green run
• agent-backed workflows emit session transcript artifacts for the outer learning loop
• learning-aggregator-ci consumes those transcript artifacts and routes transcript-only patterns back into self-improvement-meta
• factory-health emits a stable weekly report issue for workflow health and operator follow-up

Repository Layout

This repo is a template source, not a live installed factory:

• .github/workflows/ contains source-repo checks for the template itself.
• workflows/ contains the custom gh-aw Markdown workflow sources.
• workflow-support/ contains plain GitHub Actions workflows that the factory needs.
• skills/ contains the vendored skill sources that install.sh copies into .claude/skills/ in the target repo.
• .evals/ contains regression checks that installed repos receive when the template ships hand-crafted evals.
• scripts/ contains template verification helpers plus installed operator test harnesses.
• docs/AGENT_FACTORY.md is the operator guide.
• docs/chain.md explains the chain and handoffs.
• docs/FACTORY_STATE_MACHINE.md is the quick operator reference, including the optional Projects board model.
• install.sh installs the factory into another repository.

Factory Chain

issue opened
  |
  v
issue-triage
  |
  v
human adds "needs-spec"
  |
  v
spec-refiner
  |
  +---> plan-worthy
  |       |
  |       v
  |     plan PR
  |       |
  |       v
  |     human reviews and merges
  |       |
  |       v
  |     plan-merged-dispatcher
  |       |
  |       v
  |     implementer-dispatcher
  |
  +---> direct route
  |       |
  |       v
  |     Copilot assigned in the same run
  |
  +---> blocked or terminal
          |
          v
        blocked-on-human

PR opened
  |
  +---> reviewer
  +---> contribution-checker
  +---> simplify-and-harden-ci
  +---> eval-creator-ci
  |
  +---> conflict-resolver (when PR is labeled needs-rebase)
  |
  v
pr-fix / ci-cleaner / self-improvement-meta

Factory State

The factory is state-driven. Labels are the control plane.

Core state labels:

Label	Meaning
needs-spec	source issue is ready for spec refinement
needs-plan	plan PR is open and waiting for human review
blocked-on-human	automation is paused until a human acts
ready-for-implementation	source issue is ready for an implementer
assigned-to-agent	source issue has been dispatched to Copilot
needs-rebase	PR branch is behind main
ai-reviewed	reviewer found no blocking problems
needs-changes	reviewer found blocking issues or missed criteria
eval-regression	one or more promoted learnings failed on the PR
human-review	emergency circuit breaker; workflows should noop

Routing labels:

Label	Meaning
impl:copilot	only auto-routable implementer

Operator rules:

• Only impl:copilot auto-routes.
• Applying needs-plan manually is a supported skip-spec shortcut when you want to activate an issue without running spec-refiner.
• eval-regression means the PR needs human attention even though evals are still advisory.
• To re-dispatch a source issue, remove assigned-to-agent if present and then re-add ready-for-implementation.
• human-review stops the chain on the current issue or PR.

Optional Board View

If you add the optional Projects v2 board layer, use the labels as the source of truth and let the board derive from them.

Suggested lane mapping:

Priority	Condition	Lane
1	item is closed	Done
2	has any of needs-changes, needs-rebase, human-review, blocked-on-human, ai-reviewed, plan-file, eval-regression	Your turn
3	is an open draft PR with no stronger signal	Factory building
4	is an open PR with no stronger signal	Your turn
5	has any of ready-for-implementation, assigned-to-agent, needs-plan	Factory building
6	everything else	Waiting for spec

The board is optional. The factory works without it.

If you add the board-sync workflow, make the scheduled reconcile sweep every board item already on the project, not just a recent-item window from the repo. Otherwise older issues and PRs can keep stale lane values forever.

Installing Into A Target Repo

From the target repository:

git clone <template-repo-url> /tmp/agent-factory-template
/tmp/agent-factory-template/install.sh

The installer:

• copies workflows/*.md into .github/workflows/
• copies workflow-support/*.yml into .github/workflows/
• copies the lock-sync helper script into scripts/
• copies the optional factory smoke and e2e harnesses into scripts/
• vendors skills into .claude/skills/
• copies AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md when missing
• seeds .learnings/, .evals/, and docs/plans/
• creates the labels used by the factory
• runs gh aw compile

The full setup checklist, required secrets, and label reference live in docs/AGENT_FACTORY.md.

Permanent Verification

This template repo now includes a permanent install smoke test:

• scripts/smoke-test-install.sh creates a temporary git repo, installs the template into it, compiles the installed workflows, and verifies lock-file sync.
• .github/workflows/template-smoke-test.yml runs that smoke test on pushes to main and on pull requests.

Included Workflows

Custom gh-aw sources in this repo:

• workflows/spec-refiner.md
• workflows/implementer-dispatcher.md
• workflows/reviewer.md
• workflows/conflict-resolver.md
• workflows/contribution-checker.md
• workflows/ci-cleaner.md
• workflows/factory-health.md
• workflows/self-improvement-meta.md
• workflows/simplify-and-harden-ci.md
• workflows/learning-aggregator-ci.md
• workflows/eval-creator-ci.md
• workflows/issue-triage.md
• workflows/pr-fix.md

Plain GitHub Actions support workflows:

• workflow-support/factory-smoke.yml
• workflow-support/plan-merged-dispatcher.yml
• workflow-support/trigger-plan.yml
• workflow-support/lock-file-sync.yml

Installed repos also receive optional operator harness scripts:

• scripts/factory-smoke.sh
• scripts/factory-e2e.sh

This template still does not auto-install any Projects board sync workflow because those workflows are usually tied to repo-specific Projects v2 IDs, field IDs, and PAT configuration. If you want the same board-style operator view, treat it as an optional project-level customization after installation. The generic setup model is documented in docs/AGENT_FACTORY.md and docs/FACTORY_STATE_MACHINE.md.

Skills

The factory depends on these skill sources:

• External skill repository: pskoett/pskoett-ai-skills
• skills/plan-interview
• skills/self-improvement
• skills/intent-framed-agent
• skills/simplify-and-harden
• skills/learning-aggregator
• skills/eval-creator
• skills/context-surfing
• skills/verify-gate
• skills/pre-flight-check
• skills/use-agent-factory

The use-agent-factory skill is the operator handbook for installed repos. It explains how to start work through the factory, how to interpret labels, when to wait for a human gate, and how to recover from the common stuck states.

Notes

• Plan filenames use the source issue number, not a sequential scan.
• Merged plans can carry lifecycle frontmatter such as status: shipped; treat non-active plans as historical context.
• Plan PRs must not close the source issue.
• Bot-authored implementation PRs should close the source issue with a PR-body closing keyword such as Closes #NN.
• Direct route is only for clearly bounded trivial work. When uncertain, bias toward a plan PR.
• impl:copilot is the only label that auto-routes today.
• If the template ships hand-crafted evals in .evals/, installed repos should receive them too.
• If you edit a workflow source after installation, re-run gh aw compile in the target repo and commit the matching .lock.yml.
• The lock-sync guard exists because stale compiled workflow files were a real source of drift during testing.
• Expect this template to change again as the flow continues to evolve.