docs: factory integration grill — decision record, ADRs, and chunk scope update
- Decision record covering 12 decisions from the factory integration grill - ADR-0008 (factory boundary: this repo is a provider, not a factory instance) - ADR-0009 (flat skill taxonomy with category metadata in frontmatter) - ADR-0010 (role skills in .agents/skills/; core/agents/ for subagent definitions) - Issue 0013 (LESSONS.md at repo root) - Issue 0014 (docs/spec/ living spec layer + VISION.md refactor) - ROADMAP Chunk 3 scope expanded: skills rebuild, new skills (session-handoff, governance-check, git-guardrails, write-adr), IaC/Gitea global optional - Per-skill process: implementation guidance Sections 4-5 and skills index referenced as starting point before web research and grilling - factory-research-gaps-conflicts.md marked superseded Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
152
docs/notes/factory-integration-decisions.md
Normal file
152
docs/notes/factory-integration-decisions.md
Normal file
@@ -0,0 +1,152 @@
|
||||
# Exploration Note: AI Coding Factory Integration — Decision Record
|
||||
|
||||
**Date:** 2026-05-17
|
||||
**Status:** Decisions locked. Follow-on issues: 0013, 0014. 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-a-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:` — semantic version; increment on meaningful changes
|
||||
|
||||
**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/overview.md` — current deployed state, what works today (updated with each chunk)
|
||||
- `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 ROADMAP.md |
|
||||
| **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 |
|
||||
@@ -1,7 +1,7 @@
|
||||
# Exploration Note: AI Coding Factory Research — Gaps and Conflicts with Current Roadmap
|
||||
|
||||
**Date:** 2026-05-16
|
||||
**Status:** Pre-grill input. Not authoritative — decisions come from the grill session.
|
||||
**Date:** 2026-05-16
|
||||
**Status:** Superseded — grill complete. Decisions in `docs/notes/factory-integration-decisions.md`. ADRs: 0008, 0009, 0010. Issues: 0013, 0014.
|
||||
**Context:** Before starting Chunk 4 (workflows), the roadmap requires grilling the AI coding factory research against the existing repo. This note identifies where the research diverges from the current vision/roadmap/ADRs to frame that session.
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user