# Exploration Note: AI Coding Factory Integration — Decision Record

**Date:** 2026-05-17
**Status:** Complete. Follow-on issues: ~~0013~~, ~~0014~~ — both done (2026-05-17). ADRs: 0008, 0009, 0010.
**Input:** `docs/notes/factory-research-gaps-conflicts.md`, `docs/research/ai-coding-factory/`

---

## Central question resolved

**Is this repo building the factory pattern for others, or is it itself structured as a factory?**

Decision: **Model A — provider.** This repo ships skills, governance, and conventions to project repos. Factory artefacts that are project-specific (LESSONS.md, docs/spec/, references/, evals) belong in project repos, scaffolded by `init-project.sh` (Chunk 6). Exception: artefacts that are also needed while building *this repo itself* are added here too (LESSONS.md, docs/spec/). See ADR-0008.

A future orchestration layer (cross-project automation agents) is a natural Chunk 5 extension — it does not change the provider boundary.

---

## Decisions

### 1. Coding conventions stay in coding.md

CONTEXT.md is for domain vocabulary (≤200 lines, always loaded). `core/instructions/coding.md` carries coding conventions, loaded on demand. The factory's "conventions in CONTEXT.md" principle applies to project repos where CONTEXT.md is the primary shared artefact, not to this provider repo where the CLAUDE.md content index handles selective loading.

Project repos can override with their own `coding.md` at `.claude/core/instructions/coding.md`.

### 2. Flat skill taxonomy with category metadata

Nested skill paths (`design/grill-me/SKILL.md`) are not supported by Claude Code or the agentskills.io standard — both expect skills exactly one level deep under the skills root. See ADR-0009.

Categories are expressed via `metadata: category:` in SKILL.md frontmatter. Defined categories:

| Category | Scope |
|---|---|
| `design` | grill-me, grill-with-docs, to-prd, prototype, architecture-review |
| `plan` | to-issues, triage |
| `implement` | tdd, diagnose, implement-feature, refactor, write-docs |
| `test` | write-tests, generate-test-data, review-test-coverage |
| `review` | improve-codebase-architecture, code-review, security-review, pr-description, changelog-entry |
| `deploy` | write-ci-pipeline, write-deployment-config, write-ai-review-workflow, deployment-checklist |
| `operate` | write-runbook, incident-diagnosis, post-mortem, inspect-deployment |
| `iac` | write-ansible-role, write-terraform-module, write-k8s-manifest, write-docker-compose, proxmox-vm-spec, iac-security-review, write-molecule-test — **global optional** |
| `gitea` | setup-gitea-mcp, post-pr-review, create-issue — **global optional** |
| `cross-cutting` | zoom-out, caveman, session-handoff, governance-check, git-guardrails, git-commit-message |
| `factory` | write-skill, write-adr, write-workflow, write-eval, validate-skill, upgrade-skill, write-issue-spec |
| `roles` | architect, developer, reviewer, security, qa, ops — **Chunk 5** |

### 3. SKILL.md authoring standard (full)

All skills — new and rebuilt — must follow this standard:

**Frontmatter required fields:**
- `name:` — matches directory name
- `description:` — trigger-tested before writing the body (explicit, implicit, negative cases)
- `metadata: category:` — from the category table above

`version:`, `updated:`, `when:`, `source:`, and `references:` are provenance/audit fields — they live in `META.md` alongside the SKILL.md (not in frontmatter). See `META-TEMPLATE.md` in `.agents/skills/write-skill/` for the META.md schema.

**Body required sections:**
- Constraints (highest-ROI element — prevents overengineering)
- Self-check at the end (skill-specific correctness criteria)
- Failure handling

**Process discipline:**
- Write and validate the description field *before* writing the body
- Before researching: check `docs/research/ai-coding-factory/ai-coding-factory-implementation-guidance.md` Section 4 (framework analysis) and Section 5 (framework file mapping) to identify which open-source references apply to this skill and how to combine/adapt them; also check `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` for pre-researched trigger descriptions and constraints for 34 target skills
- Research and inspect the identified open-source implementations
- Grill each skill design before implementing

**Additional:**
- `allowed-tools:` for production-touching or scoped skills
- `disable-model-invocation: true` for side-effectful skills (deploy, commit, post)
- Body ≤500 lines; move reference material to `references/` subdirectory

### 4. Governance file naming unchanged

`core/instructions/governance.md` is kept. The factory's `AGENTS.md` convention applies to project repos with a single root-level governance file. This provider repo uses the on-demand instruction file convention (`coding.md`, `git.md`, `testing.md`, `governance.md`).

### 5. LESSONS.md — two-layer split

- **This repo:** `LESSONS.md` at repo root, created in issue 0013. Captures lessons learned while building the config itself.
- **Project repos:** `LESSONS.md` scaffolded by `init-project.sh` (Chunk 6 template).
- **Session-handoff skill:** writes to whichever LESSONS.md is in scope before closing a session.
- **Graduation threshold:** three or more entries covering the same pattern → promote to CONTEXT.md (or `coding.md`, `git.md`, `testing.md` if domain-specific) as a standing rule.

### 6. Evals consciously deferred to Chunk 6

Evals require a runner to be meaningful. Chunk 3 ships skills without evals; the debt is documented, not hidden. Chunk 6 delivers: eval runner (promptfoo, version-pinned), eval format, backfill of all existing skills, evals-as-acceptance-criteria for future skills.

### 7. docs/spec/ — living spec layer

Both this repo and project repos get `docs/spec/`. The distinction from VISION.md:

- `docs/VISION.md` — goals, intent, long-term roadmap (stable)
- `docs/spec/architecture.md` — current directory structure, install behavior, provider model as-deployed

VISION.md is refactored in issue 0014 to goals/intent only; architecture content moves to `docs/spec/`. The `implement-feature` skill constraint: update `docs/spec/` in the same PR as any behavior change.

Project repos: `docs/spec/` scaffolded by `init-project.sh` (Chunk 6 template).

### 8. Skills rebuild in Chunk 3

The 12 existing skills are first-draft placeholders. Chunk 3 rebuilds each from scratch: research open-source references → grill design → implement following the full authoring standard. This is a rebuild, not an extension.

### 9. Role skills in .agents/skills/, core/agents/ for subagents

See ADR-0010. Role skills (Architect, Developer, Reviewer, Security, QA, Ops) are skills with `category: roles` — they load into the main conversation to activate a cognitive mode. `core/agents/` is reserved for provider-agnostic subagent definitions that run in isolated execution contexts (`context: fork`), translated to `.claude/agents/` by the Claude Code adapter.

### 10. Model routing via per-skill frontmatter

The `model:` frontmatter field expresses model routing per skill. Guiding principle (from factory research): match capability to task — do not use frontier models for tasks a smaller model handles adequately.

| Task type | Model tier |
|---|---|
| Formatting, classification, commit messages | Lightweight (Haiku) |
| Most coding and review | Standard (Sonnet) |
| Adversarial and complex (architecture review, security, incident diagnosis) | Flagship (Opus) |

### 11. IaC and Gitea skills: global optional

IaC skills (category: `iac`) and Gitea integration skills (category: `gitea`) live in this global config repo, installed by default. They are optional — relevant only when the project uses IaC or Gitea. Foundational subset defined in Chunk 3 PRD.

### 12. References directory: project repos only

`references/stack-versions.md` and infrastructure context files belong in project repos. No equivalent needed in this provider repo. Scaffolded by `init-project.sh` (Chunk 6 template).

---

## What is already aligned (not re-litigated)

- `.agents/skills/` as canonical skill path (ADR-0004)
- SKILL.md format with YAML frontmatter (agentskills.io standard)
- CONTEXT.md ≤200 lines
- Pull-based distribution (ADR-0001)
- governance.md via `@import` always-on
- No third-party skills without reading them (OWASP AST01 / governance.md)
- ADRs in `docs/adr/` for hard-to-reverse decisions
- Conventional commits
- Progressive disclosure (names at startup, bodies on demand)
- HITL before irreversible actions

---

## Chunk scope impact

| Chunk | Change |
|---|---|
| **2 follow-on** | Add issues 0013 (LESSONS.md) and 0014 (docs/spec/ + VISION.md refactor) |
| **3** | Scope substantially expanded — see Gitea milestone "Skills & Agents" |
| **4** | WorkflowContext schema is a design prerequisite; docs/spec/ must exist before workflows reference it |
| **5** | Role skills in `.agents/skills/` (category: roles); `core/agents/` for subagent definitions |
| **6** | Eval runner, backfill, project LESSONS.md template, project docs/spec/ template, references/ template |