Defame1297
3b5b1b5199
## Why overview.md described the chunk-based delivery model, which is superseded by the marketplace/plugin pivot. architecture.md was equally stale: it described .agents/skills/ as the canonical skills source (directory does not exist), a provider-manifest.sh symlink mechanism (never built), and sync.sh / init-project.sh as existing scripts (Chunk 6, not yet built). ## Implementation Notes - overview.md deleted; all cross-references scrubbed from AGENTS.md, CONTEXT.md, and three notes/research files - architecture.md fully rewritten: content deployment model reflects actual install.sh behaviour (DEPLOY_FILES / DEPLOY_EXECUTABLES / DEPLOY_DIRS); plugin model section added listing all 5 plugins; directory structure section removed (was describing a layout that no longer exists) - "Chunk 6" phase label → "planned"; "chunk workflow" removed from AGENTS.md description - Fixed broken path docs/HUMANS.md → docs/wiki/HUMANS.md in governance layer and core/instructions/governance.md Refs: #15
111 lines
8.0 KiB
Markdown
111 lines
8.0 KiB
Markdown
# Exploration Note: AI Coding Factory Research — Gaps and Conflicts with Current Roadmap
|
||
|
||
**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.
|
||
|
||
---
|
||
|
||
## 1. The Central Scope Question (must resolve first)
|
||
|
||
The factory research describes a **project-level development environment** — a repo where you build software with AI assistance. This repo is a **global config repo** that provides skills, instructions, and conventions to projects.
|
||
|
||
**The question:** Is this repo *building* the factory pattern for others to use in their projects? Or is this repo *itself* structured as a factory?
|
||
|
||
This changes almost every downstream decision. Until it's resolved, individual gap items below may be pointing at the wrong layer.
|
||
|
||
---
|
||
|
||
## 2. True Conflicts (one has to win)
|
||
|
||
### 2.1 Where coding conventions live
|
||
|
||
**Factory research:** Preferred/Avoid code blocks belong in `CONTEXT.md`. Convention lives in a single shared-vocabulary file the agent always loads.
|
||
**Chunk 2 plan:** Coding conventions go in a separate `core/instructions/coding.md` file, loaded on-demand.
|
||
|
||
One of these wins. If conventions go in `CONTEXT.md`, `coding.md` becomes much thinner or unnecessary. If they stay in `coding.md`, the factory's "CONTEXT.md is the primary context artefact" principle weakens.
|
||
|
||
### 2.2 Skill path structure: flat vs. nested
|
||
|
||
**Factory research:** 34 skills in 9 nested categories — `design/grill-me/SKILL.md`, `implement/tdd/SKILL.md`, `cross-cutting/session-handoff/SKILL.md`, etc. (phase × domain matrix)
|
||
**Current state:** 12 skills in a flat structure — `grill-me/SKILL.md`, `tdd/SKILL.md`, etc.
|
||
|
||
Changing to nested paths breaks any tool that discovers skills by path. The nested structure also implies a different deployment model from `install.sh`. This is a structural decision for Chunk 3 — if we're adopting the nested taxonomy, it needs to be decided before writing any more skill files.
|
||
|
||
### 2.3 Governance file naming
|
||
|
||
**Factory research:** `AGENTS.md` at repo root as the single governance file for agents.
|
||
**Current repo:** `core/instructions/governance.md` loaded via `@import` in `providers/claude-code/CLAUDE.md`.
|
||
|
||
These serve the same purpose. The factory's naming is cleaner (one file, obvious name), but the current structure fits the provider-agnostic model (governance isn't provider-specific). Not a blocking conflict, but naming inconsistency will cause confusion in grill sessions if not resolved.
|
||
|
||
---
|
||
|
||
## 3. Gaps (factory has it; this repo doesn't plan it yet)
|
||
|
||
### 3.1 LESSONS.md (impacts Chunk 2)
|
||
|
||
Factory treats `LESSONS.md` as a required committed file — the mechanism for long-loop feedback and convention graduation. Without it, there is no defined path from "I noticed a pattern" to "this is now a standing rule in CONTEXT.md". Not in the Chunk 2 scope. Question: is this a Chunk 2 addition or deferred?
|
||
|
||
### 3.2 `docs/spec/` living spec layer
|
||
|
||
Factory requires `docs/spec/architecture.md` — a spec that is updated in the same PR as any behaviour change. The current docs structure has no equivalent layer; workflow artifacts go in `docs/prd/`, `docs/ard/`, etc. Adding `docs/spec/` is additive (not conflicting), but it changes the docs convention and needs to be decided before Chunk 4 (workflows) defines workflow artifacts.
|
||
|
||
### 3.3 Session handoff skill (impacts Chunk 3)
|
||
|
||
Factory treats `cross-cutting/session-handoff` as a core cross-cutting skill — it explicitly prompts LESSONS.md extraction before closing a session. Not in the current skills roadmap. If LESSONS.md is adopted (see 3.1), session handoff becomes necessary. These are linked.
|
||
|
||
### 3.4 Eval infrastructure timing
|
||
|
||
Factory requires `eval.yaml` co-located with every skill. Current roadmap puts tooling in Chunk 6. Every skill built in Chunk 3 without an eval accumulates tech debt against this requirement. Chunk 6 either has to back-fill evals for all existing skills, or the decision is made now that evals are deferred deliberately.
|
||
|
||
### 3.5 `factory/` meta-skills category
|
||
|
||
Factory plans 7 meta-skills (write-skill, write-eval, write-adr, write-workflow, validate-skill, upgrade-skill, write-issue-spec) that let the factory build and verify itself. Not in the current roadmap at all. These would logically fit in Chunk 3 (skills), but they require the nested taxonomy decision (2.2) first.
|
||
|
||
### 3.6 References directory and stack versions registry
|
||
|
||
Factory requires a `references/` directory with `stack-versions.md` (authoritative version registry) and context files like `references/proxmox-cluster.md`. Not planned in the current structure. Low urgency unless IaC skills are being built.
|
||
|
||
### 3.7 Model routing
|
||
|
||
Factory defines an explicit model routing table (Haiku for classification/formatting, Sonnet for most coding, Opus for adversarial review). Not in current vision or chunk scope. The factory treats this as both a cost decision and a sustainability decision — using frontier models for tasks a smaller model can do is waste, and the governance constitution calls this out explicitly. Where does this decision live — in `governance.md`, in CONTEXT.md, or per-skill?
|
||
|
||
---
|
||
|
||
## 4. Questions the Grill Needs to Resolve
|
||
|
||
These don't have a "right answer" yet — they need explicit decisions.
|
||
|
||
**Q1:** Does this repo adopt the factory's nested skill taxonomy now (before Chunk 3 adds more skills), or does it stay flat and reorganize later? What does `install.sh` need to change to support nested paths?
|
||
|
||
**Q2:** Should LESSONS.md be added as part of Chunk 2? If yes, what's the graduation threshold and mechanism for this homelab/solo context?
|
||
|
||
**Q3:** What parts of the factory's proposed structure belong in the *global config repo* vs. in *project repos that inherit from it*? Specifically: IaC skills, Gitea integration skills, `docs/spec/`, and role skills (Architect, Developer, Reviewer, etc.) — are these global primitives or project-specific?
|
||
|
||
**Q4:** The factory's implementation guidance lists 6 grill-me sessions before building. Sessions 1 and 3 (repo vision and roadmap) are roughly done. Sessions 4 (documentation structure), 5 (governance file structure), and 6 (skill library scope) have not been formally grilled — these map directly to the decisions above. Should this grill session cover all three, or one at a time?
|
||
|
||
**Q5:** Where does the write-a-skill skill (already deployed as `write-a-skill/SKILL.md`) map in the factory taxonomy? Is it the same as `factory/write-skill`, or is it a different thing?
|
||
|
||
**Q6:** The factory says every skill needs trigger tests before production use. The current skills have no evals. Is this a hard blocker on declaring Chunk 3 "done", or is it consciously deferred to Chunk 6 with a known backlog?
|
||
|
||
---
|
||
|
||
## 5. What Is Already Aligned (don't re-litigate)
|
||
|
||
- `.agents/skills/` as canonical skill path — consistent with the Agent Skills standard
|
||
- SKILL.md format with YAML frontmatter — consistent
|
||
- `CONTEXT.md` exists and is ≤200 lines — consistent with factory's context architecture
|
||
- Pull-based distribution model — consistent with factory's "no runtime dependency" principle
|
||
- Governance.md loaded via `@import` — matches factory's "always-on" governance pattern
|
||
- No third-party skill installs without reading them — consistent with OWASP AST01 guidance
|
||
- ADRs in `docs/adr/` — consistent
|
||
- Conventional commits — consistent with factory's git-commit-message skill intent
|
||
- Multi-file skill structure (tdd/ is already multi-file) — consistent with factory's best practice
|
||
- Progressive disclosure (names load at startup, bodies on demand) — already how install.sh works
|
||
- HITL before irreversible actions — consistent with governance layer
|
||
|
||
---
|
||
|
||
*Input for the grill-me session. These are framing questions, not conclusions. The grill should surface what was missed here and challenge the framing of the conflicts before any decisions are locked.*
|