docs: Chunk 3 issues 0015-0028 and doc updates

14 issues created covering AGENTS.md refactor prerequisite, skill
implementation workflow grill, bootstrap skills (write-eval, write-skill),
remaining factory skills, and one issue per skill category group through
to chunk closure. All HITL; acceptance criteria for 0017-0028 to be
refined after 0016 grill session.

Doc updates: CONTEXT.md PRD/issue scope clarified (HOW distribution
across architecture-review and issue design notes); ROADMAP.md housekeeping
updated with bootstrap order and issue range; spec/overview.md recent
changes entry added; PRD updated (skills-index: delete → update).

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 first). ADRs written: 0011 (provider-agnostic issue tracker), 0012 (AGENTS.md governance entry point, partially supersedes ADR-0005). Upstream review cadence: per-chunk start + quarterly post-roadmap.
+- **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-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-chunk start + quarterly post-roadmap. **Issues created 0015–0028** — all HITL; 0015 (AGENTS.md refactor, prerequisite), 0016 (skill workflow grill, produces conventions for 0017–0028), 0017–0018 (bootstrap skills: write-eval, write-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.

docs/issues/0015-agents-md-refactor.md

@@ -0,0 +1,37 @@
+# 0015 — AGENTS.md refactor (prerequisite)
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+Implement ADR-0012: create two AGENTS.md files and slim both CLAUDE.md files to thin adapters. As much provider-agnostic content as possible migrates to each respective AGENTS.md; only Claude Code-specific syntax (`@import`, inline `@file` directives) stays in the adapters.
+
+**Repo-level** `AGENTS.md` (new, at repo root):
+- Receives all provider-agnostic content from repo-level `CLAUDE.md`: working context, structure description, key rules (provider-agnostic core, sync model, edit discipline), the key documents list expressed in plain prose (no `@import` syntax)
+- Repo-level `CLAUDE.md` becomes: `@AGENTS.md` + Claude Code-specific additions (`@CONTEXT.md` auto-load, any `@import` directives)
+
+**Global** `core/AGENTS.md` (new, deployed to `~/.agents/AGENTS.md` via `install.sh`):
+- Receives all provider-agnostic content from `providers/claude-code/CLAUDE.md`: Communication rules, Behavior rules
+- `providers/claude-code/CLAUDE.md` becomes: `@~/.agents/AGENTS.md` + Claude Code-specific additions (`@import` for `governance.md`, content index `@import` directives)
+
+AGENTS.md files must be self-contained — no `@import` syntax. Where a file was previously auto-loaded via `@file` in CLAUDE.md, the AGENTS.md equivalent states the same instruction in plain prose.
+
+`docs/spec/architecture.md` is updated in this PR (per "updated in same PR as structural change" convention).
+
+HITL gate: human reviews both content splits, runs a fresh-session behavioral test to confirm all previously always-on rules still apply, and approves before committing.
+
+## Acceptance criteria
+
+- [ ] `AGENTS.md` exists at repo root; contains all provider-agnostic content from repo-level `CLAUDE.md`; no `@import` syntax
+- [ ] Repo-level `CLAUDE.md` contains `@AGENTS.md` + Claude Code-specific additions only; no duplicated always-on content
+- [ ] `core/AGENTS.md` exists; contains Communication and Behavior rules from `providers/claude-code/CLAUDE.md`; no `@import` syntax
+- [ ] `providers/claude-code/CLAUDE.md` contains `@~/.agents/AGENTS.md` + `@import` directives only; no duplicated always-on content
+- [ ] `install.sh` deploys `core/AGENTS.md` → `~/.agents/AGENTS.md`
+- [ ] `docs/spec/architecture.md` updated with AGENTS.md entries in the file structure
+- [ ] **HITL:** human confirms no always-on rule was lost or duplicated across the split
+- [ ] **HITL:** human runs fresh-session behavioral test confirming governance, communication, and behavior rules all apply without any manual load step
+
+## Blocked by
+
+None — can start immediately.

docs/issues/0016-skill-workflow-grill.md

@@ -0,0 +1,32 @@
+# 0016 — Second grill: skill implementation workflow
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+Run a dedicated grill session on the general skill implementation workflow before any skill is written. The PRD identifies this as the first issue after the AGENTS.md prerequisite — the grill produces the working conventions applied to all subsequent skill issues (0017–0028).
+
+The grill covers:
+- Per-skill process steps: trigger-first, eval-first, upstream review, source: field population
+- How the `factory/write-eval`-first bootstrap works in practice (hand-written eval for write-eval itself; write-eval used for all subsequent skills)
+- Working conventions for refactors (existing Pocock skills) vs new skills
+- How to handle a skill that combines patterns from multiple upstream sources
+- The upstream review process at chunk start: what to check, what to record, how to decide whether to pull changes in
+- Any open questions from the PRD flagged as "refine during implementation" (PRD/issue template scope, bidirectional reference convention in skill frontmatter)
+
+Output is documented in `docs/notes/skill-implementation-workflow.md`, used to update `docs/prd/chunk-3-skills-library.md` with any decisions made, and used to refine issues 0017–0028 with specific acceptance criteria.
+
+HITL: requires human participation in the grill session.
+
+## Acceptance criteria
+
+- [ ] Grill session completed covering all topics above
+- [ ] `docs/notes/skill-implementation-workflow.md` written with the agreed working conventions
+- [ ] `docs/prd/chunk-3-skills-library.md` updated with any decisions that change or extend the Implementation Decisions section
+- [ ] Issues 0017–0028 updated with specific acceptance criteria derived from the grill output
+- [ ] **HITL:** human participates in grill, reviews conventions, and approves before implementation of any skill begins
+
+## Blocked by
+
+- 0015 (AGENTS.md refactor must be complete so grill references stable file structure)

docs/issues/0017-factory-write-eval.md

@@ -0,0 +1,44 @@
+# 0017 — factory/write-eval (bootstrap skill)
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+Build `write-eval` — the first factory meta-skill, bootstrapped with a hand-written eval for itself. Every subsequent skill in Chunk 3 gets its eval produced via this skill. This issue is the smallest unblocker: get `write-eval` and its own hand-crafted eval in place, then all later skill issues can use it.
+
+**Trigger description** (from skills index): "Write evals for this skill, create eval.yaml for X, add tests for this skill"
+
+**Key constraints:**
+- Skill file (slash command): `.agents/skills/write-eval/SKILL.md` — flat per ADR-0009; `metadata.category: factory`
+- Produces eval files at: `.agents/evals/<category>/<skill-name>/eval.yaml` — nested by category (not skills; no discovery constraint)
+- Every eval must contain: ≥1 explicit trigger test, ≥1 implicit trigger test, ≥1 negative trigger test (adjacent task that must NOT activate), ≥2 deterministic output tests (schema/contains/regex), ≥1 LLM-rubric quality test
+- For this first issue: write-eval's own eval is hand-crafted (write-eval cannot produce its own eval before it exists)
+- Origin: new skill; `source:` field populated only if upstream content is adopted (determine during implementation)
+
+Process: upstream review → trigger description written and tested first → skill body → hand-write eval → behavioral test.
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review:**
+- `mattpocock/skills` — check for any eval-related content in the current set; record SHAs for any adopted content
+- `bmad-method/bmad-method` — check for QA/evaluation patterns relevant to skill testing
+- agentskills.io open standard — check whether an eval format is defined at the standard level before designing one from scratch; the eval schema in the PRD (5 test types) is derived from the factory design doc and may benefit from cross-referencing the standard
+
+write-eval has no direct Pocock equivalent. Expect to synthesize from multiple upstreams or author original.
+
+## Acceptance criteria
+
+- [ ] `.agents/skills/write-eval/SKILL.md` exists; `metadata.category: factory`; authoring standard met (frontmatter, role, when/when-not, required inputs, constraints, process, output format, failure handling)
+- [ ] Trigger description matches index or deviation is documented in SKILL.md with justification
+- [ ] `.agents/evals/factory/write-eval/eval.yaml` exists; hand-written; contains all 5 required test types
+- [ ] `install.sh` deploys `write-eval` to `~/.agents/skills/` (confirm idempotent re-run)
+- [ ] **HITL:** human runs fresh-session behavioral test: invoke "write evals for this skill" and verify correct eval.yaml structure is produced
+- [ ] **HITL:** human reviews hand-written eval.yaml for correctness before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (grill defines the per-skill implementation workflow this issue must follow)

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

@@ -0,0 +1,44 @@
+# 0018 — factory/write-skill (bootstrap skill)
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+Build `write-skill` — the second bootstrap skill, immediately after `write-eval`. Once `write-skill` exists, it is used to author all subsequent SKILL.md files in Chunk 3 rather than writing them by hand.
+
+**Trigger description** (from skills index): "Write a new skill for X, create a SKILL.md that does Y"
+
+**Key constraints:**
+- Produces a complete SKILL.md following the authoring standard (frontmatter, role, when/when-not, required inputs, constraints, process, output format, failure handling)
+- Validates trigger description against three test queries (explicit, implicit, negative) before completing
+- Flags if the proposed skill overlaps with an existing skill in the library
+- Skill file: `.agents/skills/write-skill/SKILL.md`; `metadata.category: factory`
+- Origin: new skill (check upstream for prior art during implementation); `source:` populated only if upstream content is adopted
+- Eval via `write-eval` (issue 0017)
+
+Process: upstream review → trigger-first → skill body → `write-eval` for eval.yaml → behavioral test.
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review:**
+- `mattpocock/skills` — contains `write-a-skill`, the direct Pocock equivalent; review at current HEAD; record SHA in `source:` for any adopted content
+- agentskills.io open standard — the SKILL.md format spec is the authoritative reference for what `write-skill` must produce; cross-reference against the standard before finalising output format constraints
+- `bmad-method/bmad-method` — check for any skill-authoring or template-writing patterns
+
+## 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/`
+- [ ] **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
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (grill defines per-skill workflow)
+- 0017 (`write-eval` needed to produce the eval for this skill)

docs/issues/0019-factory-skills-remaining.md

@@ -0,0 +1,55 @@
+# 0019 — Factory skills: write-adr, write-issue-spec, write-workflow, upgrade-skill, validate-skill
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+The remaining 5 factory meta-skills, authored using `write-skill` (0018). `write-adr` must be implemented first within this group — it is called by `design/grill-me` (issue 0020). All skills in this group are new.
+
+Each skill follows the per-skill workflow from issue 0016: upstream review → trigger-first → `write-skill` to author SKILL.md → `write-eval` to produce eval → behavioral test.
+
+**Skills and trigger descriptions** (from skills index):
+
+| Flat name | Trigger description |
+|---|---|
+| `write-adr` | Write an ADR, document this architectural decision, record this decision |
+| `write-issue-spec` | Write a spec for this issue, draft the issue description for X, create a Gitea issue spec |
+| `write-workflow` | Write a workflow for X, chain these skills into a workflow, create a workflow document |
+| `upgrade-skill` | This skill is wrong, fix this skill, update skill X, skill X is behaving incorrectly |
+| `validate-skill` | Check this skill, does this skill meet the standard, review this SKILL.md, audit skill X |
+
+**Key constraints per skill:**
+- `write-adr`: produces `docs/adr/NNN-title.md`; increments ADR number from existing files; never edits an existing Accepted ADR — creates a superseding one instead
+- `write-issue-spec`: produces complete issue body (Why + EARS Requirements with ADDED/MODIFIED/REMOVED delta markers + Design notes + independently completable Task checklist); scale-adaptive; does not post — outputs body for human review; must work for both file-based issues (`docs/issues/`) and Gitea MCP when configured — the active backend is determined at runtime per ADR-0011 (provider-agnostic issue tracker)
+- `write-workflow`: produces `.agents/workflows/<name>.md` with WorkflowContext schema (inputs/outputs per step), HITL gates before every irreversible action, failure paths documented
+- `upgrade-skill`: bumps `version` in frontmatter; always adds a new eval test capturing the correction; never reduces existing eval suite
+- `validate-skill`: severity-rated findings — missing eval = critical; missing failure handling = high; weak trigger description = high
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review for this category:**
+- `mattpocock/skills` — check for any meta-skill or skill-authoring patterns; record SHAs for any adopted content
+- `bmad-method/bmad-method` — BMAD architect role and ADR-writing patterns; relevant for `write-adr` and `write-issue-spec`
+- `github/spec-kit` and `Fission-AI/OpenSpec` — issue spec and workflow standards; relevant for `write-issue-spec` and `write-workflow`
+- Search agentskills.io and GitHub for open-source validate-skill and upgrade-skill implementations before writing from scratch
+
+For all skills in this group: these are meta-skills with no direct Pocock placeholder equivalent; expect to synthesize from multiple upstreams.
+
+## Acceptance criteria
+
+- [ ] All 5 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: factory`; authoring standard met for each
+- [ ] `write-adr` implemented and verified before the design skills issue (0020) begins
+- [ ] Each skill has a co-located eval at `.agents/evals/factory/<skill-name>/eval.yaml` produced via `write-eval`
+- [ ] `install.sh` deploys all 5 to `~/.agents/skills/`
+- [ ] **HITL:** human runs behavioral test per skill; output format matches constraints
+- [ ] **HITL:** human reviews each SKILL.md and eval before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (grill defines per-skill workflow)
+- 0017 (`write-eval` needed to produce evals)
+- 0018 (`write-skill` used to author these skills)

docs/issues/0020-design-skills.md

@@ -0,0 +1,61 @@
+# 0020 — Design skills: grill-lean, grill-me, write-prd, architecture-review, break-into-issues, prototype
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+The 6 design phase skills. Four are refactors of existing Pocock placeholders; two are new. All are authored using `write-skill` (0018) and evaluated using `write-eval` (0017).
+
+**Skills, origins, and trigger descriptions:**
+
+| Flat name | Origin | Trigger description |
+|---|---|---|
+| `grill-lean` | Refactored from Pocock `grill-me` | Lightweight: quick interrogation without docs integration |
+| `grill-me` | Refactored from `grill-with-docs`; calls `write-adr` | Grill me on this idea, help me think through X before building, interrogate my plan |
+| `write-prd` | Refactored from Pocock `to-prd` | Write a PRD, document requirements, write the product spec |
+| `architecture-review` | New | Review architecture, assess system design, evaluate technical approach |
+| `break-into-issues` | Refactored from Pocock `to-issues` | Break this into issues, decompose this spec into tasks, what issues do I need for this |
+| `prototype` | Preserved; frontmatter + standard added | Prototype this idea, explore this with a spike |
+
+**Key constraints per skill:**
+- `grill-me`: must refuse to produce code until all decisions are explicit; calls `write-adr` when a decision crystallises; integrates domain model from CONTEXT.md; output is a structured decision summary
+- `grill-lean`: lightweight secondary path — quick interrogation without domain model integration or ADR writing
+- `write-prd`: contains why + what only — problem statement, goals, explicit non-goals, functional requirements at feature level, success criteria. Never contains HOW: HOW is deferred to `architecture-review` (technical approach options with tradeoffs) and/or issue design notes (per-issue implementation specifics). Inline self-checks in the skill reject PRDs that drift into implementation territory.
+- `architecture-review`: the designated home for HOW at the workstream level — must present ≥2 technical approach options with tradeoffs; never recommends a single option without alternatives; optional step run after `write-prd` when the technical approach is non-obvious or carries meaningful risk
+- `break-into-issues`: independently shippable issue bodies; each issue may include a Design notes section for non-trivial implementation specifics (issue-level HOW); proposes Gitea milestone groupings for PRDs producing >5 issues; does not post — outputs bodies for human review
+- `prototype`: add frontmatter and authoring standard sections; preserve existing behavior; exploratory HOW artifacts (spikes, proofs of concept) that inform architecture-review or issue design notes
+
+**Composition:** `grill-me` calls `write-adr` by name. `write-adr` must exist (0019) before `grill-me` is finalized.
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review for this category:**
+- `mattpocock/skills` — original `grill-me`, `to-prd`, `to-issues`, `grill-with-docs` placeholders; review at current HEAD for improvements; record SHAs in `source:` for refactored skills
+- `bmad-method/bmad-method` — BMAD design phase patterns; relevant for `break-into-issues` (issue embedding, independently completable slices) and `write-prd` (PRD scope discipline)
+- `github/spec-kit` and `Fission-AI/OpenSpec` — PRD and issue spec standards; relevant for `write-prd` and `break-into-issues` constraint design
+
+For new skills (`architecture-review`, `grill-lean`): search for prior art in the above repos and agentskills.io before writing from scratch; document adoption in `source:`.
+
+## Acceptance criteria
+
+- [ ] All 6 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: design`; authoring standard met
+- [ ] Dead references removed from all refactored Pocock skills (`setup-matt-pocock-skills`, `AGENT-BRIEF.md`, `OUT-OF-SCOPE.md`)
+- [ ] `grill-me` correctly calls `write-adr` by skill name
+- [ ] `write-prd` includes inline self-checks that reject PRDs containing implementation approach, technical design, or EARS-level detail — and directs those to `architecture-review` or issue design notes
+- [ ] `architecture-review` presents ≥2 options with tradeoffs in all outputs
+- [ ] `source:` fields populated for all refactored skills (repo slug, commit SHA, files adopted, updated date)
+- [ ] Each skill has a co-located eval at `.agents/evals/design/<skill-name>/eval.yaml` produced via `write-eval`
+- [ ] `install.sh` deploys all 6 to `~/.agents/skills/`
+- [ ] **HITL:** human runs behavioral test per skill; output meets constraints
+- [ ] **HITL:** human reviews each SKILL.md and eval before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (grill defines per-skill workflow; `docs/notes/skill-implementation-workflow.md` must exist)
+- 0017 (`write-eval` needed to produce evals)
+- 0018 (`write-skill` used to author these skills)
+- 0019 (`write-adr` must exist before `grill-me` can call it)

docs/issues/0021-implement-skills.md

@@ -0,0 +1,53 @@
+# 0021 — Implement skills: implement-feature, tdd, refactor, write-docs, diagnose
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+The 5 implement phase skills. Two are new; three are preserved Pocock placeholders upgraded to the authoring standard. All authored via `write-skill` (0018), evals via `write-eval` (0017).
+
+**Skills, origins, and trigger descriptions:**
+
+| Flat name | Origin | Trigger description |
+|---|---|---|
+| `implement-feature` | New | Implement a feature, build this, write the code for X |
+| `tdd` | Preserved; frontmatter + standard added | TDD, test-driven, red-green-refactor |
+| `refactor` | New | Refactor this code, improve structure, clean up |
+| `write-docs` | New | Write documentation, add docstrings, generate README |
+| `diagnose` | Preserved; frontmatter + standard added | Diagnose this, what's wrong with X, debug this |
+
+**Key constraints per skill:**
+- `implement-feature`: must start from a linked issue with an EARS spec (checks `docs/issues/` in the file-based phase, Gitea MCP when configured); flags if none exists; no unrequested abstractions; updates `docs/spec/` as part of implementation if behaviour changes; calls `tdd` as its implementation methodology
+- `tdd`: composable and separate from `implement-feature` so TDD can be used outside full feature implementation; red-green-refactor loop
+- `refactor`: preserves all existing behaviour; documents what changed and why
+- `write-docs`: derives from code and spec; never invents behaviour
+- `diagnose`: preserved behavior; add frontmatter, authoring standard sections, and dead-reference cleanup
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review for this category:**
+- `mattpocock/skills` — original `tdd` and `diagnose` placeholders; review at current HEAD; record SHAs in `source:` for any adopted content
+- `bmad-method/bmad-method` — BMAD developer role and implementation patterns; relevant for `implement-feature` and `refactor`
+
+For new skills (`implement-feature`, `refactor`, `write-docs`): search for prior art in the above repos before writing from scratch.
+
+## Acceptance criteria
+
+- [ ] All 5 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: implement`; authoring standard met
+- [ ] Dead references removed from Pocock skills (`tdd`, `diagnose`)
+- [ ] `implement-feature` checks for linked issue with EARS spec before proceeding; calls `tdd` by name
+- [ ] `source:` fields populated for adopted upstream content
+- [ ] Each skill has a co-located eval at `.agents/evals/implement/<skill-name>/eval.yaml` via `write-eval`
+- [ ] `install.sh` deploys all 5 to `~/.agents/skills/`
+- [ ] **HITL:** human runs behavioral test per skill
+- [ ] **HITL:** human reviews each SKILL.md and eval before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (per-skill workflow)
+- 0017 (`write-eval`)
+- 0018 (`write-skill`)

docs/issues/0022-test-skills.md

@@ -0,0 +1,48 @@
+# 0022 — Test skills: write-tests, generate-test-data, review-test-coverage
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+The 3 test phase skills. All are new. Authored via `write-skill` (0018), evals via `write-eval` (0017).
+
+**Skills and trigger descriptions:**
+
+| Flat name | Trigger description |
+|---|---|
+| `write-tests` | Write tests, generate test cases, add unit tests |
+| `generate-test-data` | Generate test data, create fixtures, sample data |
+| `review-test-coverage` | Review test coverage, find untested paths, coverage gaps |
+
+**Key constraints per skill:**
+- `write-tests`: derives tests from spec (EARS acceptance criteria), NOT from implementation; uses pytest for Python, Vitest/Jest for TypeScript
+- `generate-test-data`: produces structurally valid, semantically unusual data; flags PII risk before generating
+- `review-test-coverage`: reports coverage gaps against spec acceptance criteria, not line coverage percentages
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review:**
+- `mattpocock/skills` — check for any test-phase skills in the current set
+- `bmad-method/bmad-method` — BMAD QA role patterns
+- Search agentskills.io and GitHub for open-source test generation skills before writing from scratch
+
+## Acceptance criteria
+
+- [ ] All 3 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: test`; authoring standard met
+- [ ] `write-tests` includes explicit constraint: derives from spec, not from implementation
+- [ ] `generate-test-data` includes PII flag check before generating any data
+- [ ] `source:` fields populated for any adopted upstream content
+- [ ] Each skill has a co-located eval at `.agents/evals/test/<skill-name>/eval.yaml` via `write-eval`
+- [ ] `install.sh` deploys all 3 to `~/.agents/skills/`
+- [ ] **HITL:** human runs behavioral test per skill
+- [ ] **HITL:** human reviews each SKILL.md and eval before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (per-skill workflow)
+- 0017 (`write-eval`)
+- 0018 (`write-skill`)

docs/issues/0023-review-skills.md

@@ -0,0 +1,58 @@
+# 0023 — Review skills + cliff.toml: code-review, security-review, pr-description, changelog-entry
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+The 4 review phase skills plus the `cliff.toml` changelog config. All skills are new. Authored via `write-skill` (0018), evals via `write-eval` (0017). `cliff.toml` is a deterministic config file added to the repo root (no skill implementation required for the config itself).
+
+**Skills and trigger descriptions:**
+
+| Flat name | Trigger description |
+|---|---|
+| `code-review` | Review this code, check this diff, pre-commit review |
+| `security-review` | Security review, OWASP check, pre-merge security scan |
+| `pr-description` | Write PR description, describe this change |
+| `changelog-entry` | Write changelog entry, add to CHANGELOG, release notes |
+
+**Key constraints per skill:**
+- `code-review`: severity-rated findings (critical/high/low); auto-fixes obvious style issues; flags architectural concerns for human review
+- `security-review`: OWASP LLM Top 10 + Agentic AI Top 10 for application code; AST03/04/06/07/09 categories for self-authored factory skills (AST01 excluded — requires attacker-controlled content, does not apply to self-authored skills); includes credential and licence checks
+- `pr-description`: derives from diff; covers what changed, why, and what to review carefully
+- `changelog-entry`: conventional changelog format; derives from PR description and diff; designed for git-cliff consumption
+
+**cliff.toml:**
+- Config file at repo root for git-cliff deterministic changelog generation
+- Selected over release-please (GitHub-only, incompatible with Gitea) and conventional-changelog (Node.js dependency, less actively maintained)
+- CI integration is Chunk 6; this issue only adds the config
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review:**
+- `mattpocock/skills` — check for code-review or security-review skills
+- `bmad-method/bmad-method` — BMAD reviewer and security role patterns
+- OWASP LLM Top 10 (current published version) and Agentic AI Top 10 (current published version) as authoritative checklists for `security-review`
+- OWASP Agentic Skills Top 10 (AST10) — incubator draft; use AST03/04/06/07/09 only for self-authored skills
+- git-cliff documentation for `cliff.toml` format
+
+## Acceptance criteria
+
+- [ ] All 4 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: review`; authoring standard met
+- [ ] `security-review` uses correct OWASP checklist per context (LLM Top 10 + Agentic AI Top 10 for app code; AST03/04/06/07/09 for self-authored factory skills)
+- [ ] `changelog-entry` produces output compatible with git-cliff conventional format
+- [ ] `cliff.toml` exists at repo root with conventional commits config; `git-cliff` runs against repo history without error
+- [ ] `source:` fields populated for any adopted upstream content
+- [ ] Each skill has a co-located eval at `.agents/evals/review/<skill-name>/eval.yaml` via `write-eval`
+- [ ] `install.sh` deploys all 4 skills to `~/.agents/skills/`
+- [ ] **HITL:** human runs behavioral test per skill
+- [ ] **HITL:** human reviews each SKILL.md, eval, and cliff.toml before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (per-skill workflow)
+- 0017 (`write-eval`)
+- 0018 (`write-skill`)

docs/issues/0024-deploy-skills.md

@@ -0,0 +1,50 @@
+# 0024 — Deploy skills: write-ci-pipeline, write-deployment-config, write-ai-review-workflow, deployment-checklist
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+The 4 deploy phase skills. All are new. Authored via `write-skill` (0018), evals via `write-eval` (0017).
+
+**Skills and trigger descriptions:**
+
+| Flat name | Trigger description |
+|---|---|
+| `write-ci-pipeline` | Write CI pipeline, create Gitea Actions workflow |
+| `write-deployment-config` | Write deployment config, Docker Compose, K8s manifest |
+| `write-ai-review-workflow` | Create AI review workflow, automated PR review |
+| `deployment-checklist` | Pre-deployment checklist, ready to deploy, deployment validation |
+
+**Key constraints per skill:**
+- `write-ci-pipeline`: targets Gitea Actions YAML; includes secret scan, dependency scan, licence scan, test, and build steps by default
+- `write-deployment-config`: pinned image/provider versions; resource limits on all K8s resources; no hardcoded secrets; secrets via env vars
+- `write-ai-review-workflow`: calls AI API via script; posts findings via Gitea API; never auto-merges; human remains in the loop
+- `deployment-checklist`: validates — linked issue exists and is closed or in-progress; secrets scan clean; dependency scan clean; licence scan clean; tests passing; rollback plan documented; `docs/spec/` updated if behaviour changed; which reviewer roles (Architect, Reviewer, Security) have been invoked on this change
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review:**
+- `bmad-method/bmad-method` — BMAD ops/deploy patterns and deployment checklist approach
+- Search GitHub for open-source Gitea Actions skill examples
+- Gitea Actions documentation (Gitea-specific CI syntax differences from GitHub Actions)
+
+## Acceptance criteria
+
+- [ ] All 4 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: deploy`; authoring standard met
+- [ ] `deployment-checklist` includes all listed validation checks, including reviewer role invocation check
+- [ ] `write-ai-review-workflow` includes explicit constraint that it never auto-merges
+- [ ] `source:` fields populated for any adopted upstream content
+- [ ] Each skill has a co-located eval at `.agents/evals/deploy/<skill-name>/eval.yaml` via `write-eval`
+- [ ] `install.sh` deploys all 4 to `~/.agents/skills/`
+- [ ] **HITL:** human runs behavioral test per skill
+- [ ] **HITL:** human reviews each SKILL.md and eval before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (per-skill workflow)
+- 0017 (`write-eval`)
+- 0018 (`write-skill`)

docs/issues/0025-operate-skills.md

@@ -0,0 +1,51 @@
+# 0025 — Operate skills: write-runbook, incident-diagnosis, post-mortem, inspect-deployment
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+The 4 operate phase skills. All are new. Authored via `write-skill` (0018), evals via `write-eval` (0017).
+
+**Skills and trigger descriptions:**
+
+| Flat name | Trigger description |
+|---|---|
+| `write-runbook` | Write runbook, operational guide, on-call playbook |
+| `incident-diagnosis` | Diagnose this incident, analyse these logs, root cause analysis |
+| `post-mortem` | Write post-mortem, incident review, after-action report |
+| `inspect-deployment` | Check deployment health, container status, what's running |
+
+**Key constraints per skill:**
+- `write-runbook`: covers common failure modes, detection steps, remediation steps, and escalation path; written for on-call engineers under pressure
+- `incident-diagnosis`: produces structured finding with confidence levels; never recommends production remediation directly — diagnosis only, human approves remediation
+- `post-mortem`: blameless format; covers timeline, root cause analysis, and governance change (what process/rule changes prevent recurrence)
+- `inspect-deployment`: read-only; uses Docker MCP and/or K8s MCP when configured; summarises health without modifying state
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review:**
+- `bmad-method/bmad-method` — BMAD ops role patterns
+- Google SRE book patterns for blameless post-mortem and runbook formats (public domain principles)
+- Search agentskills.io and GitHub for open-source ops/operate skill implementations
+
+## Acceptance criteria
+
+- [ ] All 4 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: operate`; authoring standard met
+- [ ] `incident-diagnosis` explicitly states it produces diagnosis only and does not recommend production remediation
+- [ ] `post-mortem` uses blameless format
+- [ ] `inspect-deployment` is read-only; uses MCP when available
+- [ ] `source:` fields populated for any adopted upstream content
+- [ ] Each skill has a co-located eval at `.agents/evals/operate/<skill-name>/eval.yaml` via `write-eval`
+- [ ] `install.sh` deploys all 4 to `~/.agents/skills/`
+- [ ] **HITL:** human runs behavioral test per skill
+- [ ] **HITL:** human reviews each SKILL.md and eval before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (per-skill workflow)
+- 0017 (`write-eval`)
+- 0018 (`write-skill`)

docs/issues/0026-iac-skills.md

@@ -0,0 +1,46 @@
+# 0026 — IaC skills: write-docker-compose, iac-security-review
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+The 2 IaC domain skills scoped for Chunk 3. Both are new. The 5 deferred IaC skills (Ansible, Molecule, Terraform, K8s, Proxmox) are explicitly out of scope. Authored via `write-skill` (0018), evals via `write-eval` (0017).
+
+**Skills and trigger descriptions:**
+
+| Flat name | Trigger description |
+|---|---|
+| `write-docker-compose` | Write Docker Compose, compose stack for X |
+| `iac-security-review` | Security review this IaC, check Terraform/Ansible for issues |
+
+**Key constraints per skill:**
+- `write-docker-compose`: pinned image versions; secrets via env vars (never hardcoded); healthchecks included on all services
+- `iac-security-review`: checks — hardcoded secrets, overly permissive access, missing resource limits, unpinned versions, Terraform provisioners (HashiCorp designates these "last resort"; break idempotency), non-idempotent Ansible patterns (shell/command without `creates:` guards, missing `notify`, unconditional handlers)
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review:**
+- Search GitHub and agentskills.io for open-source Docker Compose and IaC security review skills
+- OWASP IaC security guidance for `iac-security-review` checklist
+- HashiCorp provisioner documentation (to understand and reference the "last resort" designation)
+
+## Acceptance criteria
+
+- [ ] Both SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: iac`; authoring standard met
+- [ ] `write-docker-compose` defaults to pinned versions, env-var secrets, and healthchecks without requiring the user to ask
+- [ ] `iac-security-review` covers all listed check categories; non-idempotent Ansible patterns are explicitly enumerated
+- [ ] `source:` fields populated for any adopted upstream content
+- [ ] Each skill has a co-located eval at `.agents/evals/iac/<skill-name>/eval.yaml` via `write-eval`
+- [ ] `install.sh` deploys both to `~/.agents/skills/`
+- [ ] **HITL:** human runs behavioral test per skill
+- [ ] **HITL:** human reviews each SKILL.md and eval before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0016 (per-skill workflow)
+- 0017 (`write-eval`)
+- 0018 (`write-skill`)

docs/issues/0027-cross-cutting-skills.md

@@ -0,0 +1,57 @@
+# 0027 — Cross-cutting skills: session-handoff, governance-check, git-commit-message, improve-codebase-architecture, triage, zoom-out, caveman
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+The 7 cross-cutting skills (no single phase home). Three are new; four are preserved Pocock placeholders upgraded to the authoring standard. Authored via `write-skill` (0018), evals via `write-eval` (0017). `caveman` is kept as-is (no eval required — it is a formatting-only utility, not a content skill).
+
+**Skills, origins, and trigger descriptions:**
+
+| Flat name | Origin | Trigger description |
+|---|---|---|
+| `session-handoff` | New | Session handoff, save context, pausing work |
+| `governance-check` | New | Check this against governance rules, is this allowed |
+| `git-commit-message` | New | Write commit message, conventional commit, git message |
+| `improve-codebase-architecture` | Preserved; frontmatter + standard added | Improve architecture, refactor structure, codebase improvement |
+| `triage` | Preserved; fix dead references; frontmatter + standard added | Triage this issue, categorise, prioritise |
+| `zoom-out` | Preserved; frontmatter + standard added | Zoom out, big picture, what are we doing |
+| `caveman` | Kept as-is | (token compression utility — no trigger change) |
+
+**Key constraints per skill:**
+- `session-handoff`: captures current state, next steps, decisions with rationale, and linked issue reference; prompts LESSONS.md extraction before closing; does NOT manage `docs/spec/` — spec is updated in-PR, not at handoff
+- `governance-check`: validates proposed action against `AGENTS.md` (must reference AGENTS.md, not governance.md, now that AGENTS.md is the primary entry point post-0015)
+- `git-commit-message`: conventional commits format; derives from diff; does not invent scope or type
+- `triage`: remove dead references (`AGENT-BRIEF.md`, `OUT-OF-SCOPE.md`); add frontmatter and authoring standard sections
+- `zoom-out`: add frontmatter and authoring standard; merge into architect role revisited at Chunk 5 grill (this note should appear in the SKILL.md as a `when-not:` constraint or a note in failure handling)
+- `caveman`: no changes; no eval needed (not a content-generating skill)
+
+## Implementation notes
+
+Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
+
+**Known upstream sources to review:**
+- `mattpocock/skills` — original `improve-codebase-architecture`, `triage`, `zoom-out`, `caveman` placeholders; record SHAs for adopted content
+- For new skills (`session-handoff`, `governance-check`, `git-commit-message`): search for prior art before writing from scratch
+
+## Acceptance criteria
+
+- [ ] All 7 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: cross-cutting`; authoring standard met (except `caveman` — kept as-is)
+- [ ] Dead references removed from `triage` and any other affected skills
+- [ ] `governance-check` references `AGENTS.md` as the governance source (not `governance.md`); requires AGENTS.md refactor (0015) to be complete
+- [ ] `session-handoff` explicitly excludes `docs/spec/` management from its scope
+- [ ] `zoom-out` SKILL.md notes the Chunk 5 grill revisit for potential merge into architect role
+- [ ] `source:` fields populated for all Pocock-derived skills and any adopted upstream content
+- [ ] Each new or refactored skill has a co-located eval at `.agents/evals/cross-cutting/<skill-name>/eval.yaml` via `write-eval`; `caveman` exempt
+- [ ] `install.sh` deploys all 7 to `~/.agents/skills/`
+- [ ] **HITL:** human runs behavioral test for each new/refactored skill
+- [ ] **HITL:** human reviews each SKILL.md and eval before committing
+- [ ] _(Further criteria to be refined after issue 0016 grill session)_
+
+## Blocked by
+
+- 0015 (AGENTS.md must exist before `governance-check` can reference it correctly)
+- 0016 (per-skill workflow)
+- 0017 (`write-eval`)
+- 0018 (`write-skill`)

docs/issues/0028-chunk-3-closure.md

@@ -0,0 +1,40 @@
+# 0028 — Chunk 3 closure: update skills-index, update spec, behavioral tests
+
+**Type:** HITL  
+**Parent PRD:** `docs/prd/chunk-3-skills-library.md`
+
+## What to build
+
+Close out Chunk 3 once all 42 skills are complete: update the skills index to reflect the implemented state, update the living spec, and run the full behavioral acceptance test suite.
+
+**Tasks:**
+1. Update `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` — replace the pre-implementation build reference with the as-implemented state: actual flat skill names, categories, trigger descriptions as deployed, any deviations from the original index noted
+2. Update `docs/spec/overview.md` — reflect the full 42-skill library as the current deployed state; remove "Chunk 3 target" language; mark Chunk 3 ✅ complete
+3. Update `docs/spec/architecture.md` — reflect the `.agents/evals/` directory structure added in Chunk 3; any other structural changes from implementation
+4. Update `docs/ROADMAP.md` — mark Chunk 3 ✅ complete in the chunk table
+5. Run behavioral acceptance tests — for each skill, invoke with its trigger phrase in a fresh Claude session and verify the output meets the authoring standard; document results
+
+**Behavioral test scope:** All 42 skills (including `write-eval`, `write-skill`, and the 4 preserved skills). The `caveman` skill is exempt — it has no content-generating behavior to verify.
+
+**LESSONS.md:** Extract any cross-session learnings from Chunk 3 implementation and add entries per the LESSONS.md format. Three or more observations on the same pattern graduate to the relevant standing file.
+
+## Acceptance criteria
+
+- [ ] `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md` updated to reflect as-implemented state; deviations from original plan noted
+- [ ] `docs/spec/overview.md` updated; Chunk 3 marked ✅ complete; all 42 skills listed as deployed
+- [ ] `docs/spec/architecture.md` updated with `.agents/evals/` structure
+- [ ] `docs/ROADMAP.md` Chunk 3 row updated to ✅
+- [ ] Behavioral test run completed; all skills pass their trigger test; failures documented as issues for resolution
+- [ ] `LESSONS.md` updated with Chunk 3 observations
+- [ ] **HITL:** human verifies the complete skills library in a fresh session before marking Chunk 3 done
+
+## Blocked by
+
+- 0020 (design skills)
+- 0021 (implement skills)
+- 0022 (test skills)
+- 0023 (review skills)
+- 0024 (deploy skills)
+- 0025 (operate skills)
+- 0026 (IaC skills)
+- 0027 (cross-cutting skills)

docs/prd/chunk-3-skills-library.md

@@ -220,7 +220,7 @@ Skills are content, not code — they cannot be unit tested. Verification is beh
 
 ## Further Notes
 
-**Delete `ai-coding-factory-skills-index.md`** once all 42 skills exist as SKILL.md files. The index is a temporary build reference — its purpose ends when the library is complete.
+**Update `ai-coding-factory-skills-index.md`** once all 42 skills exist as SKILL.md files. Replace the pre-implementation build reference content with the as-implemented state: actual flat skill names, categories, trigger descriptions as deployed, and any deviations from the original plan noted. The index becomes a living reference rather than a deleted artifact — see issue 0028.
 
 **Upstream review at Chunk 3 start:** before writing any skill, review the upstreams listed in the implementation guidance (mattpocock/skills, bmad-method/bmad-method, github/spec-kit, Fission-AI/OpenSpec) at their current HEAD. Note the commit SHAs. These become the `commit:` values in `source:` fields.
 

docs/spec/overview.md

@@ -41,5 +41,6 @@ For chunk planning and open questions, see `docs/ROADMAP.md`.
 
 ## Recent changes
 
+- 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