holocron/docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md

AI Coding Factory — Implementation Guidance

Version: 1.2 Date: May 2026 Status: Guidance — not yet adapted to repo vision, roadmap, or ADRs Audience: Human implementing the factory; Claude Code executing against it Prerequisite reading: ai-coding-factory-principles.md, ai-coding-factory-research.md, ai-coding-factory-skills-index.md

Important: This document is research-derived implementation guidance, not a finalised plan. It must be reconciled with the repo's actual vision and roadmap (to be established via grill-me sessions in Claude Code) before implementation begins. Where this guidance conflicts with those outputs, the grill-me session outputs win. ADRs produced in Claude Code are the authoritative implementation decisions; this document provides the evidence base and recommendations that inform them.

---

1. Purpose and Scope

This document translates the factory's research and principles into concrete implementation guidance. It answers questions the principles document does not: what to build first, where to take it from, how documentation stays in sync, and what good looks like when done.

The factory is a governed, AI-assisted development environment implemented as a set of repo-committed files. It is not a SaaS tool, not a framework import, and not a third-party dependency. Everything lives in the repo and travels with it.

What this document covers:

• Documentation layer hierarchy and drift prevention strategy
• Framework file mapping — what to take from each external source and exactly where it goes
• Repository structure (the actual directory layout)
• Phased build plan with acceptance criteria
• Anti-patterns to explicitly exclude
• Best-practice sources for each implementation area

What this document does not cover:

• The repo vision or roadmap (established via Claude Code grill-me sessions — see Section 10)
• ADR decisions (produced in Claude Code and stored in docs/adr/)
• Skill body content (that lives in ai-coding-factory-skills-index.md)
• Governance rules (that lives in AGENTS.md)
• Research rationale (that lives in ai-coding-factory-research.md)

---

2. Current Gaps

The existing research and principles are complete and evidence-based. The gap is implementation. Specifically:

1. No canonical repository structure exists yet — the factory is documented but not built.
2. Skill files (SKILL.md) exist only as a design table in the skills index, not as actual files.
3. The workflow chain (spec → plan → implement → review → deploy) is defined in principles but not wired into a repeatable process.
4. No eval infrastructure exists to validate skill behaviour or catch model-version regressions.
5. Repo vision, roadmap, and ADRs do not yet exist — these are prerequisites for adapting this guidance to the actual build.

---

3. Documentation-Driven Development

3.1 The documentation drift problem

Drift has a direction: implementation moves faster than docs, so docs lag. Disciplinary fixes ("remember to update the docs") don't work at scale. The only reliable fixes are structural.

The factory is documentation-driven by default. This means: every implementation decision either derives from an existing document or produces a new one. Code that cannot be traced to a spec is out-of-scope code. A convention that isn't in CONTEXT.md isn't a convention — it's undiscoverable tribal knowledge.

Current tooling: git + markdown. This is the correct starting point. Every layer described below is future-compatible: when better tools arrive (living-spec platforms, architecture-as-code, doc coverage CI), they read the file structure that already exists. No migration required.

Future upgrade path (no breaking changes):

• docs/spec/ → input for a living-spec synchronisation platform or architecture-as-code tool (Structurizr C4 DSL)
• docs/adr/ → machine-readable decision graph with tooling like adr-tools or Log4brains
• Gitea issues → exportable to any future work-tracking platform; structure is plain markdown
• SKILL.md evals → input for a doc-coverage CI metric ("what % of skills have passing evals?")

3.2 Documentation layer hierarchy

Five layers, each with a clear scope and update frequency. The rule: content lives in exactly one layer. Duplication between layers is prohibited — it is the primary cause of drift.

Layer	Files	Changes when	Update mechanism
Governance	AGENTS.md, HUMANS.md, CONTROLS.md, ai-constitution.md	Principles change or tooling changes fundamentally	Human deliberate edit; reviewed in PR
Convention	CONTEXT.md, LESSONS.md, references/stack-versions.md	New pattern adopted; LESSONS.md threshold hit	LESSONS.md auto-graduates to CONTEXT.md at 3× same pattern
Specification	docs/spec/ (what the system does now), docs/adr/ (decisions)	Behaviour changes or decision made	Spec updated in same PR as implementation; ADRs via architect role; never deleted
Work tracking	Gitea issues + feature branches	New work begins or completes	Issue created with EARS spec; branch per issue; closed when PR merges
Skills & workflows	.agents/skills/**, .agents/workflows/, .agents/evals/	Skill behaviour changes or new skill added	PR with co-located eval update; CI blocks merge if eval fails
Implementation	src/, tests/, infra/, docs/api/, CHANGELOG.md	Any code change	Derives from issue spec; changelog derives from conventional commits

Work tracking is not committed files. Gitea issues and branches are the work layer. They are queryable by agents via Gitea MCP, isolated per feature, and their history lives in Gitea — not in the repo working tree. The working tree only contains what is true right now and worth preserving permanently.

3.3 Anti-drift mechanisms

Six structural mechanisms prevent drift. All six must be active — any one of them alone is insufficient.

One source per concern. No content is duplicated across layers or tool-specific files. CLAUDE.md references AGENTS.md; it does not duplicate it. A skill's trigger description appears only in its SKILL.md; it is not copied into CONTEXT.md or a workflow file.

Issue spec precedes code. No implementation work begins without a Gitea issue containing an EARS-format spec. The factory/write-issue-spec skill drafts this; the Gitea MCP posts it. Code on a feature branch cannot drift from a spec that must exist before the branch is created. The deploy/deployment-checklist skill verifies a linked issue exists before any deployment.

Living spec updates in the same PR as the behaviour change. docs/spec/ is updated as part of the PR that changes system behaviour — not as a separate "archive" step. If a PR changes behaviour without touching docs/spec/, CI flags it as spec drift. Git history preserves the full change trail; the working tree only shows current truth.

CI eval gates block skill drift. Every skill has an eval.yaml co-located in .agents/evals/. A change to any file under .agents/skills/** triggers the co-located eval in CI. A failing eval blocks merge. This means a skill body can never drift from its documented behaviour without a deliberate eval update.

LESSONS.md graduation. Three or more occurrences of the same pattern in LESSONS.md trigger promotion to CONTEXT.md as a standing rule. This is the only sanctioned upward flow in the documentation hierarchy — and only into the convention layer, not higher.

Tool adapter pattern. Tool-specific files (CLAUDE.md, .cursor/rules, copilot-instructions.md) are thin adapters that reference the source layer. They contain no original content. When a tool changes its format, only the adapter changes. The source — AGENTS.md, CONTEXT.md — is untouched.

---

4. External Framework Analysis — What to Take and From Where

Five external frameworks are relevant. Each contributes a specific, non-overlapping element. None should be imported wholesale.

---

4.1 Matt Pocock / mattpocock/skills

What it is: ~68K star MIT-licensed collection of 20+ production engineering skills built from Pocock's personal .claude directory. Workflow enforcement focus, not capability extension. TypeScript-centric but format-agnostic.

Key elements to adopt:

Element	What it is	Why adopt it
/grill-me skill	Relentless pre-coding interrogation until every decision is explicit	Already in factory's skills index; validate against Pocock's implementation for completeness
/to-prd skill	Converts conversation into a structured PRD artifact	Adopt the forcing-function pattern: refuse to proceed until synthesis is complete
/to-issues skill	Breaks PRD into independently shippable issues	Maps to factory's design/break-into-issues skill — check Pocock's "independently shippable slices" constraint
/tdd skill structure	Multi-file skill: SKILL.md + tests.md + mocking.md + refactoring.md + deep-modules.md	The multi-file skill pattern is best practice for complex skills. Factory's test/write-tests skill should adopt this structure
CONTEXT.md generation	Setup skill creates a shared vocabulary file on init	Factory already has this concept; Pocock's implementation provides a concrete template
/git-guardrails	Blocks risky agent actions (force pushes, direct main commits)	Adopt as factory's cross-cutting/git-guardrails skill — currently absent
/diagnose	Structured debugging state machine	Adopt as factory's implement/diagnose skill — currently absent
/improve-codebase-architecture	Architecture debt hunting using CONTEXT.md + ADRs	Reinforces factory's Reviewer role; drives ADR creation workflow
/zoom-out	Periodic architecture perspective shift	Maps to Architect role; adopt the "zoom out before diving in" forcing function
caveman skill	~75% token reduction through compressed output mode	Adopt for token optimisation — maps to factory's orientation problem solution

What NOT to take: TypeScript-specific skill content (typing gymnastics, TS-specific patterns). The factory is language-agnostic.

Source: github.com/mattpocock/skills (MIT). Install via: npx skills@latest add mattpocock/skills/<skill-name> — use for inspection only; copy and adapt into factory's own skill format rather than runtime dependency.

---

4.2 BMAD-METHOD (Breakthrough Method for Agile AI-Driven Development)

What it is: Open-source MIT-licensed multi-agent framework with 12+ specialized agent personas, 34+ agile workflows, and scale-adaptive planning depth. Most complete full-SDLC framework available.

Key elements to adopt:

Element	What it is	Why adopt it
Scale-adaptive planning	Automatically adjusts depth based on complexity: bug fix vs. enterprise feature	Factory's spec skill currently has a binary "skip for simple tasks" rule. BMAD's graduated approach is more practical — adopt a complexity-gated checklist
Party Mode concept	Multiple agent personas in one session for collaborative decision-making	Useful framing for the Architect role when design alternatives need to be stress-tested. Implement as an architect/design-review skill variant
Scrum Master agent pattern	Transforms planning docs into hyper-detailed stories embedding full context	The "embed full context in each story" principle directly prevents context loss between sessions. Adopt this in design/break-into-issues
Analyst → PRD → Epics → Stories pipeline	Structured handoff chain with artifacts at each stage	Maps cleanly to factory's spec → plan → implement chain. Use BMAD's artifact naming conventions as reference
Market analysis as gate	Reality-check before PRD creation	Consider adapting as an optional /validate-idea skill that runs before write-spec
5 official modules model	Core + Builder + Test + GameDev + Creative modules	Adopt this modular structure for the factory's skill library — group skills by domain module

What NOT to take: The full BMAD CLI installation or its agent persona system as-is. The factory runs on Claude Code + SKILL.md; BMAD's runtime is not compatible. Take the conceptual patterns, not the implementation.

Caveat: BMAD productivity claims are not independently verified. The framework is heavy by design — its ceremony is appropriate for greenfield enterprise builds, not single-developer homelabs. Apply scale-adaptive gating aggressively.

Source: github.com/bmad-method/bmad-method (MIT).

---

4.3 GitHub Spec Kit

What it is: GitHub's open-source SDD toolkit, 90K+ stars, May 2026. CLI (specify) + slash commands implementing a specify → plan → tasks → implement workflow. Agent-agnostic (20+ supported). Has a constitution concept for non-negotiable project principles.

Key elements to adopt:

Element	What it is	Why adopt it
Constitution file	Non-negotiable principles (CLI-first, testing conventions) that govern all AI output	This is AGENTS.md under a different name. The Spec Kit implementation is worth inspecting for structure — particularly how it enforces constitution compliance during implementation
specify → plan → tasks → implement command sequence	Repeatable 4-step workflow encoded as slash commands	Factory's workflow already mirrors this. The Spec Kit format for linking artifacts (requirements.md → design.md → tasks.md) is the reference implementation to follow
Community extensions model	70+ extensions across documentation, code, process	Adopt the extension/module model for the factory's skill library. Third-party skills should have a documented contribution pattern
Brownfield support	Works on existing codebases, not just greenfield	Ensure factory's write-spec skill explicitly handles brownfield case — Spec Kit has the best documented approach here
EARS notation	Easy Approach to Requirements Statements: "WHEN [trigger] AND [condition] THE system SHALL [response]"	Factory already mandates EARS in the write-spec skill. Spec Kit's validation approach (checking EARS syntax before implementation) is worth adopting as a spec linting step

What NOT to take: Python/uv CLI dependency. The factory is CLI-optional; context lives in files. Don't introduce a Python runtime requirement.

Caveat: Thoughtworks Radar rates it "Assess, not Adopt" (November 2025) with the observation: "We may be relearning a bitter lesson — that handcrafting detailed rules for AI ultimately doesn't scale." Treat Spec Kit as a reference pattern, not a silver bullet.

Source: github.com/github/spec-kit (MIT). Best for: EARS constraint examples, brownfield spec patterns, constitution file format.

---

4.4 OpenSpec

What it is: "Brownfield-first, fluid not rigid" SDD framework. MIT. Unique differentiator: per-change folder isolation (openspec/changes/<name>/) with delta specs that track what's changing relative to existing functionality.

What to adopt — patterns only, no runtime:

Element	What it is	Where the pattern goes
Delta spec format	ADDED/MODIFIED/REMOVED markers track what's changing vs. existing	PR description template + docs/spec/ update convention
Proposal-first workflow	Explicit "why" before any implementation	Gitea issue template (proposal section before tasks)
Verify step (/opsx:verify)	Post-implementation check against the spec	test/review-test-coverage/SKILL.md (verify-against-spec mode)
Fast-forward concept	Single command scaffolds all planning artifacts	factory/write-issue-spec/SKILL.md (creates full issue body in one pass)

What NOT to adopt:

• The openspec/changes/ directory — this is work tracking, which belongs in Gitea issues and feature branches. Committed working documents in the repo working tree create drift, not prevent it.
• The archive lifecycle — git history is the archive. The working tree shows current truth only.
• The Node.js CLI or any runtime dependency.

Source: github.com/Fission-AI/OpenSpec (MIT). Best for: delta notation, brownfield proposal structure, verify-against-spec pattern.

---

4.5 GSD (Get Stuff Done)

What it is: Lean, low-ceremony spec-driven framework built primarily for Claude Code. Positions itself as the "fast alternative to BMAD." Context engineering first; subagents in parallel; optimised for execution speed.

Key elements to adopt:

Element	What it is	Why adopt it
"Lean default, escalate to ceremony" principle	Start with minimal process; add ceremony only when complexity warrants	This is the right default posture for a single-developer factory. Adopt as a meta-principle for skill invocation
Context engineering patterns	4 strategies: write (persist), select (RAG), compress, isolate	Factory already applies this. GSD's specific compression techniques are worth reviewing — particularly context isolation between subagents
Subagent parallelism patterns	How to decompose tasks for parallel execution	Useful reference for orchestrator-worker implementation. Note: the factory currently runs roles sequentially by design. GSD's parallel approach is a future optimisation, not day-one

What NOT to take: GSD's "speed first" philosophy as a governing principle. The factory prioritises quality and auditability over throughput.

Source: Search GitHub for GSD framework Claude Code — community tool, no single canonical repo. Best for: context engineering examples and lean skill implementations.

---

4.6 AWS Kiro (Inspiration Only)

What it is: AWS's agentic IDE (not open-source). Relevant because it popularised the three-document system (requirements.md + design.md + tasks.md) and EARS notation in production tooling.

Elements to take as inspiration:

• The three-document structure (requirements → design → tasks) is the reference for factory's spec artifact layout.
• Autonomous agent hooks (auto-generating tests and docs after implementation) suggest a future enhancement to the CI/CD pipeline.
• Spec-as-artifact model: structured requirements give future agents richer context than commit history. The factory should treat all spec artifacts as long-lived references, not throwaway planning docs.

Source: kiro.dev — closed source. Use only as a reference pattern; no code to adopt.

---

5. Framework File Mapping — What Goes Where

Nothing from external frameworks enters the repo as a runtime dependency. Every row below is: copy the pattern, adapt the content, commit it as your own file. The source column is for reference only.

Rows marked (pattern only) mean adopt the structural approach or output format, not the file content verbatim. Rows marked (adopt directly) are close enough in format that the file can be copied and lightly adapted.

Source	Element	Action	Factory file
Pocock/skills	grill-me/SKILL.md	Adopt directly	.agents/skills/design/grill-me/SKILL.md
Pocock/skills	to-prd/SKILL.md	Pattern only — forcing-function approach	.agents/skills/factory/write-issue-spec/SKILL.md
Pocock/skills	to-issues/SKILL.md	Pattern only — independently shippable slices	.agents/skills/design/break-into-issues/SKILL.md
Pocock/skills	tdd/ (multi-file)	Adopt directly — entire folder structure	.agents/skills/implement/tdd/ (SKILL.md + tests.md + mocking.md + refactoring.md)
Pocock/skills	diagnose/SKILL.md	Adopt directly	.agents/skills/implement/diagnose/SKILL.md
Pocock/skills	git-guardrails/SKILL.md	Adopt directly	.agents/skills/cross-cutting/git-guardrails/SKILL.md
Pocock/skills	CONTEXT.md generation (setup skill)	Pattern only — content is yours	CONTEXT.md at repo root (content file, not a skill)
Pocock/skills	zoom-out/SKILL.md	Adopt directly — merge as a mode	.agents/skills/roles/architect/SKILL.md
BMAD-METHOD	Scale-adaptive planning depth	Pattern only — complexity gate logic	.agents/skills/factory/write-issue-spec/SKILL.md (complexity-gating section)
BMAD-METHOD	Scrum Master story format	Pattern only — embed full context	.agents/skills/design/break-into-issues/SKILL.md (output format)
BMAD-METHOD	5-module directory model	Pattern only — directory grouping	.agents/skills/ directory structure (design/, implement/, factory/ etc.)
GitHub Spec Kit	Constitution file concept	Already exists — inspect for improvements	AGENTS.md
GitHub Spec Kit	specify→plan→tasks→implement sequence	Pattern only — orchestration order	.agents/workflows/feature-workflow.md
GitHub Spec Kit	EARS notation examples	Pattern only — extract constraint examples	.agents/skills/factory/write-issue-spec/SKILL.md (acceptance criteria section)
GitHub Spec Kit	Brownfield spec approach	Pattern only — delta notation	PR description template + docs/spec/ update convention
OpenSpec	Delta spec format (ADDED/MODIFIED/REMOVED)	Pattern only — apply to PR descriptions	PR description template in deploy/pr-description/SKILL.md
OpenSpec	Proposal-first workflow	Pattern only — "why" section before tasks	Gitea issue template (section in factory/write-issue-spec/SKILL.md)
OpenSpec	Verify step	Pattern only — post-impl spec check	.agents/skills/test/review-test-coverage/SKILL.md (verify-against-spec mode)
Kiro (AWS)	EARS notation reference	Pattern only — examples	.agents/skills/factory/write-issue-spec/SKILL.md
Kiro (AWS)	Three-document system (req + design + tasks)	Pattern only — maps to issue structure	Gitea issue template sections: requirements, design notes, task checklist
GSD	"Lean default, escalate to ceremony"	Pattern only — meta-principle	AGENTS.md (skill invocation guidance)
GSD	Context compression techniques	Pattern only	All skills (constraints section: prefer compressed output)

Gitea issue template structure (replaces openspec/changes/): the spec lives in the issue, not in the working tree.

## Why (proposal)
<!-- Problem being solved; out-of-scope explicitly stated -->

## Requirements
<!-- EARS format: WHEN [trigger] AND [condition] THE system SHALL [response] -->
<!-- Delta markers for brownfield: ADDED / MODIFIED / REMOVED -->

## Design notes
<!-- Technical approach; data model; API surface if relevant -->

## Tasks
- [ ] Task 1 (independently completable)
- [ ] Task 2

This is the three-document structure from Kiro and the proposal + delta format from OpenSpec — expressed as a single Gitea issue body instead of committed files.

---

6. Repository Structure

The working tree contains only permanent, final-state content. Work in progress lives in Gitea issues and feature branches — not in committed files.

repo/
├── AGENTS.md                    # Agent governance (all rules)
├── CONTEXT.md                   # Shared vocabulary and conventions
├── LESSONS.md                   # Feedback → graduates to CONTEXT.md at 3× threshold
├── HUMANS.md                    # Human orientation guide
├── CONTROLS.md                  # Operational safety controls
│
├── .agents/
│   ├── skills/                  # Canonical skill library
│   │   ├── roles/
│   │   │   ├── architect/SKILL.md
│   │   │   ├── developer/SKILL.md
│   │   │   ├── reviewer/SKILL.md
│   │   │   ├── security/SKILL.md
│   │   │   ├── qa/SKILL.md
│   │   │   └── ops/SKILL.md
│   │   ├── design/
│   │   │   ├── grill-me/SKILL.md
│   │   │   ├── architecture-review/SKILL.md
│   │   │   └── break-into-issues/SKILL.md
│   │   ├── factory/             ← Meta-skills: factory builds itself
│   │   │   ├── write-issue-spec/SKILL.md   # Drafts Gitea issue with EARS spec
│   │   │   ├── write-skill/SKILL.md        # Creates new SKILL.md files
│   │   │   ├── write-workflow/SKILL.md     # Creates workflow documents
│   │   │   ├── write-adr/SKILL.md          # Creates ADR documents
│   │   │   ├── write-eval/SKILL.md         # Creates eval.yaml for a skill
│   │   │   ├── upgrade-skill/SKILL.md      # Updates skill + eval on correction
│   │   │   └── validate-skill/SKILL.md     # Audits skill against standard
│   │   ├── implement/
│   │   │   ├── implement-feature/SKILL.md
│   │   │   ├── refactor/SKILL.md
│   │   │   ├── write-docs/SKILL.md
│   │   │   ├── diagnose/SKILL.md
│   │   │   └── tdd/
│   │   │       ├── SKILL.md
│   │   │       ├── tests.md
│   │   │       ├── mocking.md
│   │   │       └── refactoring.md
│   │   ├── test/
│   │   │   ├── write-tests/SKILL.md
│   │   │   ├── generate-test-data/SKILL.md
│   │   │   └── review-test-coverage/SKILL.md
│   │   ├── review/
│   │   │   ├── code-review/SKILL.md
│   │   │   ├── security-review/SKILL.md
│   │   │   ├── pr-description/SKILL.md     # Includes ADDED/MODIFIED/REMOVED convention
│   │   │   └── changelog-entry/SKILL.md
│   │   ├── deploy/
│   │   │   ├── write-ci-pipeline/SKILL.md
│   │   │   ├── write-deployment-config/SKILL.md
│   │   │   ├── write-ai-review-workflow/SKILL.md
│   │   │   └── deployment-checklist/SKILL.md  # Verifies linked issue exists
│   │   ├── operate/
│   │   │   ├── write-runbook/SKILL.md
│   │   │   ├── incident-diagnosis/SKILL.md
│   │   │   ├── post-mortem/SKILL.md
│   │   │   └── inspect-deployment/SKILL.md
│   │   ├── iac/
│   │   │   ├── write-ansible-role/SKILL.md
│   │   │   ├── write-terraform-module/SKILL.md
│   │   │   ├── write-k8s-manifest/SKILL.md
│   │   │   ├── write-docker-compose/SKILL.md
│   │   │   ├── proxmox-vm-spec/SKILL.md
│   │   │   ├── iac-security-review/SKILL.md
│   │   │   └── write-molecule-test/SKILL.md
│   │   ├── gitea/
│   │   │   ├── setup-gitea-mcp/SKILL.md
│   │   │   ├── post-pr-review/SKILL.md
│   │   │   └── create-issue/SKILL.md
│   │   └── cross-cutting/
│   │       ├── session-handoff/SKILL.md
│   │       ├── governance-check/SKILL.md
│   │       ├── git-commit-message/SKILL.md
│   │       └── git-guardrails/SKILL.md
│   │
│   ├── evals/                   # Co-located eval suites (one dir per skill)
│   │   └── <category>/<skill>/eval.yaml
│   │
│   └── workflows/               # Multi-skill orchestration documents
│       ├── feature-workflow.md
│       ├── bugfix-workflow.md
│       └── iac-workflow.md
│
├── docs/
│   ├── spec/                    # Living system spec — what the system does NOW
│   │   ├── overview.md          # Purpose, scope, system boundaries
│   │   ├── architecture.md      # Current architecture (updated with code)
│   │   └── <domain>.md          # Per-domain functional specs (add as needed)
│   ├── adr/                     # Architecture Decision Records (append-only, never deleted)
│   │   └── NNN-title.md
│   ├── runbooks/                # Operational procedures
│   └── api/                     # Generated from code where possible
│
├── references/
│   ├── stack-versions.md        # Authoritative version registry
│   └── proxmox-cluster.md       # Cluster context (AI training data can't know this)
│
└── src/, tests/, infra/         # Implementation

What is NOT in the working tree:

Excluded	Where it lives instead
Active feature work	Gitea issue (spec) + feature branch (code)
Completed change history	Git commit history + closed Gitea issues
Working drafts / scratch	.gitignored scratch/ dir or local only
Session handoff notes	Created locally; deleted once session resumes

Design rationale:

docs/spec/ replaces openspec/specs/ and openspec/changes/. It is the single source of truth for what the system does now. It is updated in the same PR as any behaviour change — there is no separate archive step, because git history is the archive.

docs/adr/ is append-only. ADRs are never deleted or edited after they are marked Accepted — only superseded by a new ADR that references them. This is what makes architectural decisions auditable across time.

factory/ skill category is new. It contains meta-skills that build the factory itself: writing new skills, evals, ADRs, and issue specs. The factory is self-extending.

.agents/skills/ as canonical skill path: consistent with Anthropic's SKILL.md open standard (December 2025). Tool adapters (CLAUDE.md, .cursor/rules) reference this; they do not duplicate it.

---

7. Phased Implementation Plan

Phase 1 — Foundation (Week 1–2)

Goal: A working factory skeleton that a real task can be run through end-to-end.

Acceptance criteria (EARS format):

• WHEN any task is started, THE system SHALL have a Gitea issue with an EARS-format spec before a branch is created
• WHEN a Claude Code session begins, THE system SHALL have AGENTS.md and CONTEXT.md in context
• WHEN any skill is invoked, THE system SHALL load only that skill's SKILL.md (not the full library)
• WHEN a PR is raised, THE system SHALL include updates to docs/spec/ if behaviour changed

Tasks:

1. Commit AGENTS.md — merge existing governance content; validate against principles doc
2. Generate CONTEXT.md — manually populate shared vocabulary (10–15 domain terms to start)
3. Create docs/spec/architecture.md — initial living spec, even if sparse
4. Create docs/adr/ with an adr-template.md
5. Implement Phase 1 skill set (7 files):
   • roles/architect, roles/developer, roles/reviewer
   • factory/write-issue-spec (primary pre-work skill — replaces old write-spec)
   • factory/write-adr (produces ADR documents)
   • implement/tdd (multi-file structure from Pocock)
   • cross-cutting/session-handoff
6. Set up Gitea issue template using the spec structure from Section 5

Quality gate: Run one real feature end-to-end: write-issue-spec → post issue to Gitea → create branch → tdd → code-review → update docs/spec/ → pr-description → merge. Human reviews all outputs. No eval infrastructure yet — manual review is the gate.

---

Phase 2 — Full Skill Library (Week 3–4)

Goal: All 27 skills from the skills index exist as real SKILL.md files.

Priority order within Phase 2:

1. Remaining factory meta-skills: write-skill, write-eval, upgrade-skill, validate-skill, write-workflow
2. Remaining roles: security, qa, ops
3. review/code-review and review/security-review — highest daily use
4. design/grill-me and design/break-into-issues — completes the planning chain
5. IaC skills (Ansible, Terraform, K8s, Docker Compose, Proxmox)
6. Deploy and operate skills
7. Gitea integration skills
8. New skills from Pocock: implement/diagnose, cross-cutting/git-guardrails

Skill authoring standard:

• Every SKILL.md must have: name, description (trigger), constraints section, explicit failure handling, version metadata in frontmatter
• Complex skills (tdd, write-spec, architect) use multi-file pattern: SKILL.md + supplementary .md files
• Description field is the trigger — test it by asking: "would this description activate the skill correctly for the intended case AND exclude adjacent cases?"

---

Phase 3 — Eval Infrastructure (Week 5–6)

Goal: Every skill has an eval.yaml; CI runs evals on change; weekly regression cron is live.

Per-skill eval requirements:

• Trigger tests: explicit invocation, implicit invocation, ≥1 negative case (adjacent task that must NOT activate)
• Output tests: deterministic assertions (JSON schema, contains, regex) as primary gate; LLM-as-judge for quality catches
• Every human correction to a skill output generates a new test case

Tooling: promptfoo (MIT, YAML-based, self-hosted). Version-pin to a known-good release (not latest) given the OpenAI acquisition in March 2026. Document DeepEval and Arize Phoenix as fallback options.

CI rule:

on:
  push:
    paths:
      - '.agents/skills/**'
jobs:
  skill-evals:
    runs-on: self-hosted
    steps:
      - run: promptfoo eval --config .agents/evals/${{ matrix.skill }}/eval.yaml

---

Phase 4 — Workflow Wiring and Token Optimisation (Week 7–8)

Goal: Multi-skill workflows are documented and tested; token cost is measurable and managed.

Workflow documents (in .agents/workflows/):

• feature-workflow.md: grill-me → write-issue-spec → [human posts issue to Gitea] → architect-review → [human gate] → break-into-issues → tdd + implement-feature → code-review → security-review → [human gate] → update docs/spec/ → pr-description → deployment-checklist
• bugfix-workflow.md: Lean path — diagnose → tdd → code-review → [human gate] → git-commit-message
• iac-workflow.md: write-issue-spec → write-[iac-type] → iac-security-review → [human gate] → write-ci-pipeline

Token optimisation measures to implement:

• Prompt caching enabled for all role and cross-cutting skills (stable system prompts)
• Orientation block in each skill: role context loaded first, compresses subsequent interaction
• caveman output mode (from Pocock) available as a flag for high-volume generation tasks
• Model routing: route simple code review to Haiku; complex architectural reasoning to Sonnet/Opus

---

8. What NOT to Build

Explicit exclusions with rationale:

Excluded pattern	Why
openspec/changes/ directory	Work tracking belongs in Gitea issues and feature branches, not committed files. Working documents in the working tree create drift rather than prevent it.
Import BMAD, Spec Kit, or OpenSpec as runtime dependencies	Factory convention lives in committed files; runtime dependencies create maintenance debt and tool-specific format lock-in
Concurrent agent teams	Research confirms this compounds error rates and explodes token cost. Sequential roles remain the pattern.
LLM auto-memory (~/.claude/memory)	Machine-local, not repo-shared. LESSONS.md is the repo mechanism.
Single all-skills-loaded context	Skills load on demand. Dumping the full library into context is the failure mode skills solve.
Spec Kit's Python CLI as a hard dependency	Python 3.11+ runtime requirement for a workflow tool is unnecessary friction. The slash command pattern matters — implement it in SKILL.md.
"Living spec" synchronisation platforms (Intent/Augment)	Requires a platform product. docs/spec/ updated in-PR is the factory's approach — spec drift is managed by process and CI, not external software.
Concurrent role execution	Always sequential on demand. Parallel agent teams are not the factory pattern.

---

9. Best Practice Sources

Organised by implementation area. Use these when writing each skill:

Issue spec writing:

• EARS notation: Mavin & Maiden, EARS: The Easy Approach to Requirements Syntax (IEEE, 2009)
• Addy Osmani's spec guide: addyosmani.com/blog/good-spec/ — treat spec like code; commit it; agents read git diff to understand changes
• OpenSpec delta notation (ADDED/MODIFIED/REMOVED): github.com/Fission-AI/OpenSpec
• GitHub Spec Kit EARS examples: github.com/github/spec-kit

TDD and testing:

• Matt Pocock's tdd skill (multi-file pattern): github.com/mattpocock/skills/tdd/
• Test architecture: test-driven.io — Roy Osherove, The Art of Unit Testing (3rd ed.)
• Spec-to-test derivation (not implementation-to-test): factory's own principles doc, Topic 3

Security:

• OWASP LLM Top 10: owasp.org/www-project-top-10-for-large-language-model-applications/
• OWASP Agentic AI Top 10 (AST10, Incubator draft, Q3 2026 target): owasp.org/www-project-agentic-ai-top-10/
• Veracode 2025 GenAI Code Security Report (45% OWASP Top 10 in AI-generated samples)
• CodeRabbit December 2025 report (1.7× more issues in AI-generated code)

Prompt/context engineering:

• LangChain 4-strategy framework (write, select, compress, isolate): blog.langchain.dev
• Context Engineering paper: arxiv.org/pdf/2603.09619 (2026)
• OOLONG benchmark (long context degradation): arxiv.org/abs/2511.02817

IaC:

• Ansible idempotency: docs.ansible.com/ansible/latest/playbook_guide/playbooks_best_practices.html
• Terraform style guide: developer.hashicorp.com/terraform/language/style
• Molecule testing: ansible.readthedocs.io/projects/molecule/
• Proxmox bpg provider: github.com/bpg/terraform-provider-proxmox (pin version; changes frequently)

Eval infrastructure:

• promptfoo docs (version-pin): promptfoo.dev/docs/ — acquired OpenAI March 2026; monitor neutrality
• DeepEval (fallback): docs.confident-ai.com
• Arize Phoenix (self-hosted fallback): phoenix.arize.com
• SkillsBench (benchmark methodology): arxiv.org/abs/2602.12670

Agent role design:

• gstack reference implementation: github.com/garrytan/gstack — inspect role structure; caveat productivity claims (810× self-reported, non-verifiable methodology)
• AORCHESTRA orchestrator-worker paper: arxiv.org/abs/2602.03786 (+16.28% on GAIA/SWE-Bench, Gemini-specific)
• Cognitive separation principle: cio.com/article/4166035 (Anthropic, May 2026)

Token optimisation:

• Prompt caching: docs.anthropic.com/en/docs/build-with-claude/prompt-caching
• Model routing guidance: Anthropic cost documentation (current pricing)

---

10. Skill Authoring Guide

When writing each skill file, follow this template:

---
name: <category>/<skill-name>
description: <trigger description — this is what the agent reads to decide whether to load this skill>
version: 1.0
updated: YYYY-MM
references:
  - <source 1>
  - <source 2>
---

## Role

<One sentence: who is the agent when this skill is active>

## When to use / When NOT to use

<Explicit inclusion and exclusion criteria — the negative cases are as important as positive>

## Required inputs

<What must be provided before this skill proceeds>

## Constraints

<Non-negotiable rules — what the agent must always/never do>

## Process

<Step-by-step — numbered, not bullet points>

## Output format

<Exactly what the skill produces; structured if the next step in a workflow depends on it>

## Failure handling

<What to return if inputs are missing or a step fails — never silent failure>

Trigger description quality check: Before writing the body, validate the description against three test queries: (1) an explicit invocation that should activate it, (2) an implicit invocation that should activate it, (3) an adjacent task that must NOT activate it. If the description fails any test, rewrite before proceeding.

---

11. Success Metrics

The factory is working when:

Metric	Target
Issue spec before branch	100% of non-trivial features have a Gitea issue with EARS spec before branch creation
Spec–implementation sync	0 PRs merged that change behaviour without updating docs/spec/
HITL gate compliance	100% of irreversible actions have a human approval before execution
Eval coverage	Every skill has trigger tests and output tests before use in production
LESSONS.md graduation rate	Recurring patterns promoted to CONTEXT.md within 2 weeks of third occurrence
Session handoff rate	All sessions that pause mid-task have a handoff document
Model regression detection	Weekly eval cron catches skill degradation before it reaches production use

---

12. Open Questions Before Grill-Me Sessions

These must be resolved before implementation begins. Most are inputs to the grill-me sessions, not outputs from them — bring them as context, not as questions to answer from scratch.

1. Primary language/stack for this repo: Skill body content varies by language. What is the repo's primary stack? This determines test framework defaults (pytest vs Vitest), linting rules, and IaC tooling.

2. Gitea instance available? The gitea integration skills and the issue-spec workflow both require a live Gitea instance with MCP access. If not yet live, defer gitea skills and use manual issue creation in Phase 1.

3. Gitea issue template: The issue spec structure (why / requirements / design notes / tasks) needs to be set as the default issue template. Confirm which Gitea repo this applies to before Phase 1.

4. promptfoo hosting: Self-hosted promptfoo on the homelab, or Gitea Actions cloud runners? This affects eval architecture.

5. CONTEXT.md bootstrap: What are the 10–15 most important domain terms for this project? These must be manually written before any skill invokes CONTEXT.md.

6. docs/spec/ initial scope: How much of the current system needs to be described in the initial living spec before Phase 1 begins? Even a sparse overview.md + architecture.md is better than nothing — agents need something to read before they can update it correctly.

---

13. Claude Code Grill-Me Sessions — Handoff

This document is the research and recommendation layer. It is not the authoritative implementation plan. The authoritative plan emerges from grill-me sessions in Claude Code, which produce the vision, roadmap, and ADRs that this guidance must then be adapted to.

What needs a grill-me session

Each of the following warrants its own session. They are ordered by dependency — earlier sessions produce inputs that later sessions need.

Session	Produces	Feeds into
1. Repo vision and goals	Vision statement, success criteria, what the factory is and is not for	All subsequent sessions; CONTEXT.md bootstrap
2. Stack and tooling decisions	Primary language(s), test frameworks, IaC tooling, CI platform	Skill body content for implement/, test/, iac/ skills; stack-versions.md
3. Roadmap and phasing	Milestone sequence, phase gates, what "done" looks like per phase	Phase plan (Section 7 of this document becomes concrete)
4. ADR: documentation structure	Decision on docs/spec/ scope, Gitea issue template, ADR conventions, Diátaxis applicability	write-issue-spec skill, docs/spec/ initial structure, issue template
5. ADR: governance file structure	Decision on which governance files exist, what each owns, what adapters look like	AGENTS.md, CLAUDE.md, CONTEXT.md
6. ADR: skill library scope	Which skills to build first; factory/ vs other categories; which to defer	Phase 1 and 2 skill build order

What to give Claude Code before each session

For each grill-me session, load the following into Claude Code context:

# Mandatory context for all sessions
AGENTS.md
ai-coding-factory-principles.md
ai-coding-factory-skills-index.md

# This document (the implementation guidance)
ai-coding-factory-implementation-guidance.md

# Add for sessions 2-6 (outputs from session 1)
CONTEXT.md (once bootstrapped)
docs/adr/ (any ADRs already produced)

The grill-me skill will refuse to proceed until every decision is explicit. Let it. The friction is the point.

How ADR outputs from Claude Code relate to this document

ADRs produced in Claude Code override specific recommendations in this document where they conflict. The override rule:

• This document recommends a pattern (e.g., openspec/changes/<name>/ structure).
• The ADR session may decide on a different structure for legitimate reasons.
• The ADR is authoritative. Update this document's relevant section to reference the ADR and mark it as superseded.
• This document's research rationale still stands — the ADR should record why it diverged, not just what it decided.

The intended final state: every concrete recommendation in this document either has a matching ADR confirming it, or a note saying "superseded by ADR-NNN." At that point, this document transitions from guidance to historical record and the ADRs become the implementation reference.

Suggested grill-me session prompt for Claude Code

/grill-me

Context: I'm building an AI coding factory — a governed, AI-assisted development environment
implemented as committed files in a repo. I have completed research and implementation
guidance (loaded in context). I need to establish [session topic] before building.

Grill me until every decision is explicit. Do not let me proceed with vague answers.
Output: a structured decision record suitable for converting to an ADR.

---

This is a living guidance document. Update it as grill-me sessions produce decisions. When an ADR supersedes a recommendation, mark the section with > Superseded by ADR-NNN and link the ADR. Version in git alongside the rest of the factory.