feat: implement issue 0018 phase 1 — factory/write-skill bootstrap skill

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/ROADMAP.md

@@ -98,4 +98,4 @@ Items consciously not resolved — to be addressed in the relevant chunk PRD or
 - **Chunk 2 behavioral tests** — run and fully resolved 2026-05-17. 7/8 pass; scenario 4 (push confirmation) inconclusive — no remote in test environment, rule tightened but unverified. All fixable failures addressed: rule specificity in `providers/claude-code/CLAUDE.md`; context-loading guarantee via `@import CONTEXT.md` in repo CLAUDE.md; standing rule in CONTEXT.md to check `docs/adr/` and ROADMAP resolved entries before answering design questions. Chunk 2 ✅ complete.
 - **Governance Phase 1 behavioral tests** — run 2026-05-17. 3/4 testable scenarios pass. Secrets rule gap fixed (2026-05-17): extended to cover credential reproduction in response text and examples, with placeholder requirement added to `core/instructions/governance.md`. HITL scenario not testable in this environment (Nginx not installed); HITL gap evidenced by instructions test scenario 4 — push confirmation rule fix addresses the same root cause. Governance Phase 1 ✅ complete.
 - **AI ethics/security workstream** — `docs/notes/ai-ethics-security-principles.md` exploration note is superseded. Governance Phase 1 (`core/instructions/governance.md`) covers all planned scope: credentials, data classification, HITL, scope discipline, agent autonomy, transparency, and security code review. Tier-placement architectural question resolved by the `@import` always-on model. No separate workstream needed.
-- **Chunk 3 grill complete** — 2026-05-17. PRD at `docs/prd/chunk-3-skills-library.md`. Key decisions: 42-skill target library, AGENTS.md refactor as prerequisite issue (both CLAUDE.md files become thin adapters), git-cliff for changelog, provider-agnostic issue tracker abstraction, grill-me/grill-lean design phase split, factory bootstrap order (write-eval → write-skill → write-docs phase 2 → write-adr → remaining factory → design → parallel category groups). ADRs written: 0011 (provider-agnostic issue tracker), 0012 (AGENTS.md governance entry point, partially supersedes ADR-0005). Upstream review cadence: per-skill + quarterly post-roadmap (per-chunk-start changed to per-skill by issue 0016 grill). **Issues created 0015–0028** — all HITL; ~~0015 (AGENTS.md refactor, prerequisite)~~ ✅, ~~0016 (skill workflow grill, produces conventions for 0017–0028)~~ ✅, ~~0017 (bootstrap skill: write-eval)~~ ⏳ HITL pending, 0018 (write-skill + write-docs as phase 2), 0019 (remaining factory skills), 0020–0027 (design/implement/test/review/deploy/operate/iac/cross-cutting), 0028 (chunk closure). ~~Acceptance criteria for 0017–0028 to be refined after 0016 grill session.~~ ✅ Refined 2026-05-17 — see `docs/notes/skill-implementation-workflow.md`.
+- **Chunk 3 grill complete** — 2026-05-17. PRD at `docs/prd/chunk-3-skills-library.md`. Key decisions: 42-skill target library, AGENTS.md refactor as prerequisite issue (both CLAUDE.md files become thin adapters), git-cliff for changelog, provider-agnostic issue tracker abstraction, grill-me/grill-lean design phase split, factory bootstrap order (write-eval → write-skill → write-docs phase 2 → write-adr → remaining factory → design → parallel category groups). ADRs written: 0011 (provider-agnostic issue tracker), 0012 (AGENTS.md governance entry point, partially supersedes ADR-0005). Upstream review cadence: per-skill + quarterly post-roadmap (per-chunk-start changed to per-skill by issue 0016 grill). **Issues created 0015–0028** — all HITL; ~~0015 (AGENTS.md refactor, prerequisite)~~ ✅, ~~0016 (skill workflow grill, produces conventions for 0017–0028)~~ ✅, ~~0017 (bootstrap skill: write-eval)~~ ⏳ HITL pending, ~~0018 phase 1 (write-skill)~~ ⏳ HITL pending, 0018 phase 2 (write-docs — first factory-authored skill), 0019 (remaining factory skills), 0020–0027 (design/implement/test/review/deploy/operate/iac/cross-cutting), 0028 (chunk closure). ~~Acceptance criteria for 0017–0028 to be refined after 0016 grill session.~~ ✅ Refined 2026-05-17 — see `docs/notes/skill-implementation-workflow.md`.

docs/issues/0018-factory-write-skill.md

@@ -42,10 +42,10 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
 
 ## Acceptance criteria
 
-- [ ] `.agents/skills/write-skill/SKILL.md` exists; `metadata.category: factory`; authoring standard met
-- [ ] Trigger description validates against explicit, implicit, and negative test queries
-- [ ] `.agents/evals/factory/write-skill/eval.yaml` exists; produced via `write-eval`
-- [ ] `install.sh` deploys `write-skill` to `~/.agents/skills/`
+- [x] `.agents/skills/write-skill/SKILL.md` exists; `metadata.category: factory`; authoring standard met
+- [x] Trigger description validates against explicit, implicit, and negative test queries
+- [x] `.agents/evals/factory/write-skill/eval.yaml` exists; produced via `write-eval`
+- [x] `install.sh` deploys `write-skill` to `~/.agents/skills/`
 - [ ] **HITL:** human runs behavioral test: invoke "write a new skill for X" and verify the produced SKILL.md meets the authoring standard
 - [ ] **HITL:** human reviews SKILL.md and eval before committing
 - [ ] Per-skill process followed for both phases (see `docs/notes/skill-implementation-workflow.md`)
@@ -61,3 +61,27 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
 
 - 0016 (grill defines per-skill workflow)
 - 0017 (`write-eval` needed to produce the eval for this skill)
+
+## Handoff — Phase 1
+
+**Status:** complete — pending HITL behavioral test (acceptance criteria steps 5–6)
+
+**Files produced:**
+- `.agents/skills/write-skill/SKILL.md`
+- `.agents/evals/factory/write-skill/eval.yaml`
+
+**Key decisions:**
+- Scope: new-skill creation + placeholder→canonical conversion only. Updating/fixing existing skills → `upgrade-skill` (separate skill in the index).
+- Trigger validation (3 cases) is a named gate in write-skill's process before body content is written.
+- `write-eval` is step 7 of write-skill's process — the skill invokes it automatically. HITL prompt is step 8.
+- Self-authored (no `source:` field); `references:` cites agentskills.io best-practices and optimizing-descriptions.
+- speckit-agent-skills (dceoy) excluded — AGPL-3.0 copyleft.
+- Role is self-contained (no reference to workflow doc) so it can be used standalone after chunk 3.
+
+**Open threads:**
+- HITL behavioral test: open a fresh session, invoke "write a new skill for X" in this repo context, verify trigger is tested before body, per-section walk-through happens, write-eval is invoked, HITL prompt appears.
+- Phase 2 (`write-docs`): first skill authored end-to-end by the factory. Follow full per-skill workflow from `docs/notes/skill-implementation-workflow.md`.
+
+**Next session start:**
+- Load: `CONTEXT.md`, `docs/notes/skill-implementation-workflow.md`, `docs/issues/0018-factory-write-skill.md`
+- First action: HITL behavioral test for write-skill, then begin phase 2 (`write-docs`) using write-skill

docs/spec/overview.md

@@ -2,16 +2,18 @@
 
 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-17 (issue 0017)*
+*Last updated: 2026-05-17 (issue 0018 phase 1)*
 
 ## What is deployed
 
 ### Skills
-13 skills deployed to `~/.agents/skills/` via `install.sh`. Available as slash commands in Claude Code via `~/.claude/skills/ → ~/.agents/skills/` symlink. 12 are first-draft placeholders pending rebuild in Chunk 3; 1 is a new Chunk 3 factory skill (`write-eval`).
+14 skills deployed to `~/.agents/skills/` via `install.sh`. Available as slash commands in Claude Code via `~/.claude/skills/ → ~/.agents/skills/` symlink. 12 are first-draft placeholders pending rebuild in Chunk 3; 2 are new Chunk 3 factory skills (`write-eval`, `write-skill`).
 
-**Factory bootstrap (Chunk 3):** `write-eval` deployed — produces `eval.yaml` test files for skills. Hand-written (bootstrap skill). Eval at `.agents/evals/factory/write-eval/eval.yaml`.
+**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.
 
-Current skills: `caveman`, `diagnose`, `grill-me`, `grill-with-docs`, `improve-codebase-architecture`, `prototype`, `tdd`, `to-issues`, `to-prd`, `triage`, `write-a-skill`, `zoom-out`.
+Current skills: `caveman`, `diagnose`, `grill-me`, `grill-with-docs`, `improve-codebase-architecture`, `prototype`, `tdd`, `to-issues`, `to-prd`, `triage`, `write-a-skill`, `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.
 
@@ -44,6 +46,7 @@ For chunk planning and open questions, see `docs/ROADMAP.md`.
 
 ## Recent changes
 
+- 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.