Research and design choices
The template builds on established software engineering practices and on ideas from existing frameworks for AI-assisted development. This page explains which ideas influenced it, how we adapted them, and which we chose not to include.
We compared approaches to planning, code review, verification, and agent orchestration, and kept the parts that fit a lightweight workflow on GitHub. A similarity with another project does not mean code was reused: no code was copied from the projects named here.
Implemented available in the template today · Partially implemented some of it is available · Design principle shapes the workflow, without being a separate feature · Under consideration researched, not built · Not adopted deliberately left out
Our approach
We want one workflow that is easy to understand, inspect, and maintain. AI agents plan, write code, and review changes. Scripts check whether the required steps were completed. People approve the requirements and the important decisions.
For every external framework we asked one question: would this improve the workflow we have, or would it add complexity we do not need?
Frameworks we compared
| Framework | What influenced us | What we didn't include | Status |
|---|---|---|---|
| GitHub Spec Kit | Clear links between requirements, plans, tasks, and implementation; consistency checks | A second specification system with its own commands and directories | Partially implemented requirements, roadmap, feature issues, planning review |
| OpenSpec | Explicit change requests for an approved plan | A separate change-management tool with its own set of documents | Implemented the planning change process, with a new approval |
| Superpowers | Verification before calling work done, independent reviews, short task contexts, systematic debugging | Installing every skill, or requiring test-first development for every change | Partially implemented reviews, verification, resuming; a debugging method is under consideration |
| BMAD Method | Separate responsibilities for planning, implementation, and review | A large set of mandatory agent personas and documents | Design principle focused agent roles |
| GSD Core | Small tasks, progress notes that survive a session, resuming with a fresh context | A second orchestrator, or parallel execution by default | Partially implemented handoff notes and resuming; task scheduling is under consideration |
Ideas from talks and development workflows
Talks and workshops
- Matt Pocock: Full Walkthrough: Workflow for AI Coding. Influenced our approach to clarifying requirements, vertical slices, and dependencies between tasks.
- Eric Zakariasson: Building your own software factory. Prompted our research into isolated development environments, parallel agents, and better verification evidence.
Clarify requirements before implementation
The Project Grill is a round of questions about goals, users, and scope. It turns a first idea into agreed requirements before an agent writes the plan. Implemented A similar step for a single feature is Under consideration.
We encourage vertical slices: features that deliver useful behavior from end to end, in place of separate database, API, and user-interface tasks. Design principle
The roadmap describes the dependencies between features, but nothing schedules work from them yet. A task queue that knows the dependencies is Under consideration.
We create a GitHub issue when a feature is ready to start. Opening issues for the whole roadmap in advance is Not adopted.
Separate work and record evidence
Each feature has its own Git branch and worktree. Verification results and code reviews are recorded, so the workflow can check whether they still apply after a change. Implemented
A worktree does not isolate the whole runtime. Separate databases, caches, services, ports, and credentials need containers or virtual machines. Full environment isolation is Under consideration.
Screenshots, recordings, and similar evidence can come from a project's own tests. The template does not provide them as a general feature.
Allow autonomy, with clear boundaries
run-feature.sh carries out implementation, verification, review, fixes, and the pull request without asking for input at each stage. It stops at an open pull request and does not merge or deploy. Implemented
The template assesses risk from protected paths and from the reviewer's assessment. A model's own assessment never decides alone whether an important change needs approval. Implemented
A task scheduler, a central dashboard, and better support for several agents at once are Under consideration.
Specialized agent skills
We looked at collections of skills for security, front-end development, cloud infrastructure, design, and the evaluation of AI systems. The goal is not to install everything: a project uses only the skills its work needs. The table shows five of them; the complete inventory lists all twenty collections we looked at.
| Source | Why it was interesting | Current approach |
|---|---|---|
| Cloudflare security audit skill | Repeatable security reviews with structured findings | An optional specialist audit is under consideration |
| Trail of Bits skills | Security checks for code and for automation workflows | Select skills per project; not bundled |
| Addy Osmani's agent skills | Engineering quality and disciplined review | Design inspiration |
| Anthropic skills | Packaging and evaluating reusable skills | A skills registry is under consideration |
| Impeccable | Structured design reviews | An optional design review is under consideration |
Why we built it
AI coding agents can help plan a project, implement features, write tests, and review changes. Using them across a whole development process raises practical questions. How do you keep the requirements consistent? How do you know a change was reviewed and tested? How do you let agents work on their own without giving up the important decisions?
The answers are established engineering practices, applied to work with agents. Three of them shaped the template most:
- Clear requirements reduce rework. That is why every plan starts with a round of questions and your approval.
- Independent reviews help catch problems the implementer may miss. A separate reviewer that cannot edit the code reads every change, and every finding gets an explicit decision.
- Approval rules should not depend on an agent's judgment alone. Rules about the files a change touches come first; the reviewer's assessment comes on top and can only make the outcome stricter.
What we learned from using the template
Keeping existing projects up to date
GitHub does not update a repository that was created from a template. We compared several approaches and added sync-template.sh, which brings workflow improvements into an existing project and leaves the project's own files alone.
Keeping reviews and approvals current
A review is useful only if it describes the code that is merged. The workflow records which version was reviewed and checks whether that is still the current one. The approval of a plan is tied to the approved requirements and roadmap in the same way.
Making verification more efficient
As a project gains tests and checks, verification takes longer. The template reuses a successful run when the content has not changed. Running only the tests a change affects, caching, and limits on the duration of a check are still being explored.
What we may add next
See Possible improvements for the current list of proposals.