holocron/docs/notes/factory-integration-decisions.md

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
• metadata: version: — mandatory for every skill (ADR-0022)

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