Code Factory Template
Code Factory is a repo control-plane for autonomous coding + deterministic review.
This template implements the full pattern:
- one machine-readable contract
- risk-policy gate before expensive CI fanout
- current-head SHA review discipline
- canonical rerun comment dedupe
- optional deterministic remediation agent loop
- bot-only thread auto-resolve after clean rerun
- browser evidence verification for UI/user-flow changes
- incident -> harness-gap loop with weekly metrics
Contract (single source of truth)
All control-plane policy lives in ARCHITECTURE.yaml under control_plane:
riskTierRulesmergePolicydocsDriftRulesreviewAgentremediationAgentbrowserEvidenceharnessGapLoopbranchProtection
Workflow Order
Control Plane workflow (.github/workflows/preflight.yml) runs jobs in this order:
risk-policy-gate- fanout:
CI Pipeline, harness-smoke, Browser Evidence
risk-policy-finalize
For high tier changes, the gate auto-applies the PR label high-risk.
Greptile runs as the code review agent via GitHub App. Install the Greptile app and configure greptile.json in the repo root. The policy gate uses Greptile's check run directly (useCheckConclusionOnly: true).
greptile-event-handler workflow (.github/workflows/greptile-event-handler.yml) triggers on Greptile check completion: remediation (on failure) and auto-resolve of bot-only threads (on success).
SHA Discipline and Reruns
scripts/control-plane/risk-policy-gate.mjs enforces:
- review check must be for current PR head SHA
- stale review state is rejected
- actionable findings in review summary comment fail the gate
- canonical rerun request comment is deduped by marker +
sha:<head>
Browser Evidence
For UI-sensitive paths, Browser Evidence requires a valid manifest:
- path:
harness/browser-evidence/manifest.json
- freshness window and required flows defined in
ARCHITECTURE.yaml
Capture uses Playwright to take real screenshots of required flows. If no BROWSER_EVIDENCE_BASE_URL is set, the capture script builds and serves the flowchart app locally.
Generate/update evidence manifest:
npm run harness:ui:capture-browser-evidence
npm run harness:ui:verify-browser-evidence
In CI, capture + verify are both run in Browser Evidence job.
Harness Gap Loop
harness-gap-loop workflow:
- creates a
harness-gap issue when a production-regression issue appears
- runs weekly metrics (
npm run harness:weekly-metrics)
Local Command Set
npm run typecheck
npm run lint
npm test
npm run build:ci --if-present
npm run harness:legal-chat:smoke
npm run harness:ui:pre-pr
npm run harness:ui:capture-browser-evidence
npm run harness:ui:verify-browser-evidence
npm run harness:risk-tier
npm run harness:weekly-metrics
npm run spec:normalize
npm run spec:validate
npm run spec:check
In this template, typecheck, lint, and test delegate to the flowchart subproject.
Greptile Setup
- Install the Greptile GitHub App for your repository.
- Ensure
greptile.json exists in the repo root (this template includes a default).
- Set
statusCheck: true in greptile.json so the policy gate can enforce the Greptile check.
- The contract uses
checkName: "Greptile" and useCheckConclusionOnly: true (check conclusion is authoritative).
Branch Protection
Merge blocking is enforced via GitHub branch protection requiring risk-policy-finalize.
code-factory applies this automatically when it creates the GitHub repo (default behavior).- For repos created from GitHub template UI, run:
node scripts/control-plane/apply-branch-protection.mjs owner/repo
Note: GitHub may require a paid plan (or public repo) for private-repo branch protection.
Remediation Agent
Optional, disabled by default:
- add a self-hosted runner for the repo
- set repository variable
ENABLE_REMEDIATION=true
- optional variables:
REMEDIATION_ENGINE, REMEDIATION_CODEX_MODEL, REMEDIATION_VALIDATE_CMD
When enabled, failed Greptile checks trigger deterministic in-branch remediation:
- verify current PR head matches event SHA (skip if stale)
- read review context (Greptile comments or summary)
- run local CLI agent (
codex/claude/opencode/custom)
- run validation command
- commit + push fix to same PR branch
Agent Loop Files
ARCHITECTURE.yamlAGENTS.mdprd.jsonprogress.txt (auto-created by ralph.sh on first run)
Tool Rule Files
.cursorrulesCLAUDE.md.agent/rules/CodeFactory.mdprompt_template.txtchatgpt_architecture_prd_prompt.txtchatgpt_prd_format_prompt.txt
CLI Install
npm install -g @jnyross/code-factory
Create a New Project
Default (local scaffold + create/push GitHub repo):
code-factory my-next-app ~/Projects
wiggumdev
gmickel
snarktank
mylukin
wayne930242
mj-meyer