Defame1297
e3cc0b65f4
Complete 2026-05-18 workstream for write-skill refactor (issue 0018 phase 1). Grill output (handoff in docs/issues/0018-factory-write-skill.md): - 6-section standard replaces 8: Role and When/When not dropped (not in agentskills.io spec; description carries trigger scope and negatives) - Frontmatter reduced to 3 fields; provenance moves to META.md (progressive disclosure — not loaded at every skill scan) - SKILL-TEMPLATE.md and META-TEMPLATE.md as authoritative copy-fill artifacts - CATEGORIES.md as self-contained category reference in skill directory - Copy and fill explicitly split into separate process steps for determinism New files in .agents/skills/write-skill/: - SKILL-TEMPLATE.md — 6-section template with XML blocks and inline examples per section - META-TEMPLATE.md — provenance schema with inline-commented YAML; source vs references explicit - CATEGORIES.md — self-contained category table (no runtime dependency on factory docs) - META.md — write-skill's own provenance (v1.1, self-authored) SKILL.md rewritten: 8-step process, XML blocks (<requirements>, <steps>, <checks>), 3-field frontmatter, copy-then-fill steps explicit. Supporting docs updated: - skill-implementation-workflow.md: SKILL-TEMPLATE.md as authoritative template; source:/references: now reference META.md; when: marked resolved - factory-integration-decisions.md: frontmatter spec corrected - ROADMAP.md: authoring standard description updated - CONTEXT.md: Source field entry corrected; META.md added to glossary - docs/spec/overview.md: 2026-05-18 refactor entry added - docs/issues/0018: handoff status updated; acceptance criteria marked complete LESSONS.md: 3 entries added in grill session (cargo-culted body sections, provenance fields in frontmatter, copy-fill determinism) + 1 from implementation (planning meta-commentary does not belong in deployed artifacts). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
60 lines
8.2 KiB
Markdown
60 lines
8.2 KiB
Markdown
# Overview
|
||
|
||
Current deployed state of this repo — what you get if you run `install.sh` today. Updated at the close of each chunk and in the same PR as any behavior change.
|
||
|
||
*Last updated: 2026-05-18 (issue 0018 phase 1 refactor)*
|
||
|
||
## What is deployed
|
||
|
||
### Skills
|
||
14 skills deployed to `~/.agents/skills/` via `install.sh`. Available as slash commands in Claude Code via `~/.claude/skills/ → ~/.agents/skills/` symlink. 11 are first-draft placeholders pending rebuild in Chunk 3; 3 are new Chunk 3 skills (`write-eval`, `write-skill`, `write-docs`).
|
||
|
||
**Factory bootstrap (Chunk 3):**
|
||
- `write-eval` — produces `eval.yaml` test files for skills. Hand-written (bootstrap). Eval at `.agents/evals/factory/write-eval/eval.yaml`.
|
||
- `write-skill` — authors new SKILL.md files and converts placeholders to canonical format. Hand-written (bootstrap — cannot author itself before it exists). Eval at `.agents/evals/factory/write-skill/eval.yaml`. Invokes `write-eval` as part of its own process.
|
||
- `write-docs` — produces technical documentation derived from code and spec; never invents behaviour. **First factory-authored skill** (SKILL.md produced via `write-skill`, eval via `write-eval`). Eval at `.agents/evals/implement/write-docs/eval.yaml`. Sources: anthropics/skills `doc-coauthoring`, mattpocock/skills `write-a-skill`, bmad-code-org/BMAD-METHOD `bmad-advanced-elicitation`.
|
||
|
||
Current skills: `caveman`, `diagnose`, `grill-me`, `grill-with-docs`, `improve-codebase-architecture`, `prototype`, `tdd`, `to-issues`, `to-prd`, `triage`, `write-docs`, `write-eval`, `write-skill`, `zoom-out`.
|
||
|
||
**Chunk 3 target:** 42 skills across 9 categories. PRD: `docs/prd/chunk-3-skills-library.md`. Canonical build reference: `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` (delete once all skills exist). Skills stored flat (`skill-name/SKILL.md`) per ADR-0009; category in `metadata.category` frontmatter. Categories: design, factory, implement, test, review, deploy, operate, cross-cutting, iac (2 skills only — docker-compose + iac-security-review). Role skills (6) deferred to Chunk 5. Gitea skills moved to `providers/gitea/` provider adapter.
|
||
|
||
**Skill implementation workflow:** each skill follows the per-skill process in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016). Sub-agents handle source discovery, source review, and conflict checking; synthesis grill and HITL test are human steps. Bootstrap: write-eval (hand-written) → write-skill (hand-written) → write-docs (first factory-authored) → all others via factory.
|
||
|
||
### Claude Code configuration
|
||
- `~/.claude/CLAUDE.md` — thin adapter; imports `~/.agents/AGENTS.md` (Communication + Behavior) and `governance.md`; content index pointers only
|
||
- `~/.agents/AGENTS.md` — global always-on rules (Communication + Behavior); provider-agnostic source of truth
|
||
- `~/.claude/core/instructions/` — coding, git, testing, governance instruction files
|
||
- `~/.claude/settings.json` — Claude Code settings
|
||
|
||
### Governance layer
|
||
`core/instructions/governance.md` loads into every Claude Code session via `@import` in `~/.claude/CLAUDE.md`. Covers: hard prohibitions on secrets and data, data classification tiers, HITL requirements, sycophancy resistance, deterministic execution preference.
|
||
|
||
## What works end-to-end
|
||
|
||
- `install.sh` runs idempotently — safe to re-run after changes
|
||
- Provider adapter pattern: `providers/*/provider-manifest.sh` auto-discovered by `install.sh`
|
||
- Governance rules take effect at session start without any manual loading step
|
||
- Skills available as slash commands immediately after install
|
||
|
||
## What is not yet deployed
|
||
|
||
- `sync.sh` — pulls updates into existing projects (Chunk 6)
|
||
- `init-project.sh` — bootstraps a new project (Chunk 6)
|
||
- Copilot provider adapter (Chunk 7)
|
||
- Formal CI/pre-commit enforcement of governance rules (Chunk 6)
|
||
|
||
For chunk planning and open questions, see `docs/ROADMAP.md`.
|
||
|
||
## Recent changes
|
||
|
||
- 2026-05-18 — Issue 0018 phase 1 refactor complete: `write-skill` redesigned from scratch. New files added to skill directory: `SKILL-TEMPLATE.md` (authoritative 6-section template with XML blocks, human-usable), `META-TEMPLATE.md` (provenance schema with inline-commented YAML), `CATEGORIES.md` (self-contained category table), `META.md` (write-skill's own provenance). SKILL.md rewritten: 6 sections replacing 8 (Role and When/When not dropped — not in agentskills.io spec); frontmatter reduced to 3 fields (`name`, `description`, `metadata.category`); provenance fields (`version`, `updated`, `when`, `source`, `references`) moved to META.md (progressive disclosure — not loaded at startup). `docs/notes/skill-implementation-workflow.md` updated to reference SKILL-TEMPLATE.md as the authoritative template.
|
||
|
||
- 2026-05-17 — Issue 0018 phase 2 complete: `write-docs` skill written and deployed. First skill produced end-to-end by the factory (SKILL.md via `write-skill`, eval via `write-eval`). Category: implement. Key decisions: file-approval gate before reading (user names files or approves proposals); gap check before drafting (user fills what code doesn't explain); stage skipping allowed with logged reason; full revised section shown before confirmation gate; surgical edits only with per-round delta summary; Reader Testing via scoped sub-agent (doc + questions only, no source files); summary/overview sections written last. Sources: anthropics/skills doc-coauthoring (Reader Testing stage, surgical-edit constraint), mattpocock/skills write-a-skill (trigger pattern), bmad-code-org/BMAD-METHOD bmad-advanced-elicitation (confirmation gate). Open follow-up: documentation convention (file/folder/content structure, global vs repo-specific) — not yet defined.
|
||
- 2026-05-17 — Issue 0018 phase 1 complete: `write-skill` bootstrap skill written and deployed. Hand-written (factory bootstrap). Self-authored — no upstream content adopted; agentskills.io best-practices and optimizing-descriptions docs cited as references. Speckit excluded (AGPL-3.0). Key decisions: new-skill + placeholder-conversion scope only (upgrades → `upgrade-skill`); trigger description tested against 3 cases before body written; `write-eval` invoked as step 7 in process; HITL prompt as step 8. Eval at `.agents/evals/factory/write-skill/eval.yaml`.
|
||
- 2026-05-17 — Issue 0017 complete: `write-eval` bootstrap skill written and deployed. Two sections schema (`trigger_tests` + `output_tests`), provider-agnostic string assertions, show-plan-then-merge-on-rerun behaviour, conflict flagging (B model). Sources: agentskills/agentskills, darkrishabh/agent-skills-eval, bmad-code-org/BMAD-METHOD, mattpocock/skills. Hand-written eval at `.agents/evals/factory/write-eval/eval.yaml`.
|
||
- 2026-05-17 — Issue 0016 complete: skill implementation workflow grill completed. `docs/notes/skill-implementation-workflow.md` written. All issues 0017–0028 updated with specific acceptance criteria. Key conventions: sub-agents prescribed at each research/writing step; conflict check against constitution + factory principles before synthesis grill; `when:` and `references:` fields added to authoring standard; write-docs moved to issue 0018 phase 2 (first factory-authored skill).
|
||
- 2026-05-17 — Issue 0015 complete: AGENTS.md refactor implemented. Two AGENTS.md files created (`AGENTS.md` at repo root, `core/AGENTS.md` deployed to `~/.agents/AGENTS.md`). Both CLAUDE.md files slimmed to thin adapters. `deploy-manifest.sh` updated. `docs/spec/architecture.md` updated with new structure. ADR-0012 in effect.
|
||
- 2026-05-17 — Chunk 3 issues created (0015–0028): AGENTS.md refactor prerequisite, skill workflow grill, bootstrap skills (write-eval, write-skill), factory/design/implement/test/review/deploy/operate/IaC/cross-cutting skill groups, chunk closure; all HITL; acceptance criteria for 0017–0028 to be refined after issue 0016 grill session
|
||
- 2026-05-17 — behavioral tests fully resolved: `CONTEXT.md` now always-loaded via `@import` in repo `CLAUDE.md`; standing rule added to check `docs/adr/` and ROADMAP resolved entries before answering design questions; communication/behavior and secrets rules tightened; Chunk 2 and Governance Phase 1 ✅ complete
|
||
- 2026-05-17 — added `LESSONS.md` (issue 0013) and `docs/spec/` (issue 0014); refactored `docs/VISION.md` to goals/intent only
|