The premise
Harness over heroics. Evidence over confidence.
An effective agentic engineering environment is not defined by which model writes the most code. It is defined by whether people and agents share trusted context, work against clear outcomes, respect permissions, and produce changes that can be independently verified. GitHub is a natural control plane because it brings source, issues, specifications, pull requests, checks and release history together.
The reusable starting point is repo-template.bardenhagen.xyz: an agent-neutral GitHub template with a canonical repository contract, engineering guidance, security practices and a phased roadmap. It is a starting point, not a claim that every workflow or control is automatically enforced by a Markdown file.
The lifecycle
Five phases, one traceable loop.
Discover and define
Human accountability: Set business intent, users, boundaries, success measures and acceptance criteria.
Agent contribution: Inspect the existing code and documentation, identify unknowns, and propose a plan before editing.
Design and align
Human accountability: Review material trade-offs, domain models, data/API contracts and risk decisions.
Agent contribution: Draft architecture decision records, schemas, threat models and a verification plan.
Execute in small batches
Human accountability: Resolve ambiguity, keep scope focused and oversee consequential changes.
Agent contribution: Break work into reviewable tasks, implement on a short-lived branch, and keep tests and docs in step.
Verify and release
Human accountability: Review the pull request, accept residual risk and authorise production changes.
Agent contribution: Run reproducible lint, type checks, tests, security scans, accessibility checks and relevant evaluations.
Govern and improve
Human accountability: Validate outcomes and approve policy changes.
Agent contribution: Summarise evidence, identify recurring defects and propose improvements to instructions, tests and automation.
Make the repository do the remembering
The GitHub control plane
Conversation context is useful but transient. Durable instructions, specifications and decisions should travel with the code so a new person, model or agent can recover the reasoning without relying on yesterday’s chat.
- One global contract: a concise
AGENTS.mdexplains the project, boundaries, commands and definition of done. Tool-specific files point back to it instead of creating competing policies. - Path-level instructions: frontend, backend, infrastructure and data areas get relevant guidance without loading every rule for every task.
- Issues and pull requests: capture the problem, acceptance criteria, scope, risks, test evidence and remaining gaps.
- ADRs and specifications: record material decisions and contracts so implementation and future changes remain explainable.
- Required checks: repository rules, workflow permissions and protected environments enforce the controls that prose alone cannot enforce.
Security and quality
Autonomy must stay inside the guardrails.
Start with deterministic checks: formatting, lint, type checking, unit and integration tests, builds, dependency and secret scanning, schema validation and accessibility checks where relevant. Add evaluations for agent behaviour when it materially affects the product — for example tool selection, groundedness, policy adherence and task completion — and version the prompts, models, test cases and scoring criteria.
Use least-privilege credentials and short-lived identity wherever possible. MCP servers are capability adapters, not a policy boundary: inspect provenance, constrain permissions, document data egress and require explicit authorisation for write, delete, merge or production tools. Never commit credentials or customer data into source, prompts, issue text, test fixtures or logs.
A reviewer agent can find defects, but it is not a substitute for independent approval. The authoring agent must not approve its own pull request. Humans remain accountable for product intent, material architecture decisions, risk acceptance and production release.
Adopt progressively
A starter, not a big-bang platform.
- Phase 1 — reliable foundation: canonical instructions, issue/PR templates, safe secrets, meaningful CI, deterministic tests and basic MCP hygiene.
- Phase 2 — evaluated specialists: add Architect, Developer, Reviewer and SecOps role prompts, independent reviews, reproducible evaluations and clear escalation rules.
- Phase 3 — permission-aware memory: index approved code, ADRs and selected delivery history with provenance, freshness, access controls and deletion support.
For an existing repository, retrofit rather than replace: inspect the current stack, preserve useful conventions, classify each recommendation as keep, adopt, adapt or reject, and make changes in a focused feature branch. For a new repository, create it from the template at inception, then customise its architecture and controls before shipping production code.
Explore the implementation
Make the way of working repeatable.
Use the template as a foundation, then adapt it to your team, architecture and risk profile. The goal is not maximum autonomy; it is faster delivery with clearer context and better evidence.