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

PRD: Chunk 3 — Skills Library Rebuild

Status: In progress — 0015 ✅, 0016 ✅
Produced by: grill-with-docs session, 2026-05-17
Prerequisite: AGENTS.md refactor issue must be completed before skill implementation begins

---

Problem Statement

The 12 existing skills were written as Pocock placeholder content before the factory research was completed. They lack consistent frontmatter, carry no upstream provenance tracking, contain dead references (to setup-matt-pocock-skills, AGENT-BRIEF.md, OUT-OF-SCOPE.md), and do not align with the factory's authoring standard, phase taxonomy, or design phase structure. There is no mechanism to detect upstream drift, no established review cadence, and no eval coverage for any skill. The factory meta-skills — which enable the factory to build and validate itself — do not exist at all.

The skills library is the most immediately useful output of this repo. In its current state, it does not meet the quality bar required for professional-scale use.

---

Solution

Rebuild the skills library using the factory skills index (docs/research/ai-coding-factory/ai-coding-factory-skills-index.md) as the canonical build reference. Existing Pocock placeholder skills are refactored to the authoring standard; new skills are built from scratch. The factory meta-skills (factory/ category) are built first, starting with factory/write-eval, to bootstrap eval coverage before any other skill is written.

A source: array field in each skill's frontmatter tracks upstream provenance with full traceability (repo slug, commit SHA, files adopted). An upstream review cadence — per-chunk start during roadmap, quarterly after — prevents drift from upstream sources.

The design phase is restructured from its current ad-hoc state into a formal sequence: grill → write-prd → architecture-review (optional) → break-into-issues, with a lightweight secondary grill path for quick ideation without docs integration.

Before skill implementation begins, a dedicated grill session on the general skill implementation workflow is required. That grill produces the working conventions used across all subsequent skill issues.

---

User Stories

1. As a developer, I want each skill to have a consistent source: field so I can trace exactly which upstream commits and files were adopted when a skill was written.
2. As a developer, I want source: to support multiple upstream sources per skill so that combined/merged skills retain full provenance for each contribution.
3. As a developer, I want the updated: date in each source: entry so I can tell how stale the adoption may be.
4. As a developer, I want a defined upstream review cadence so I know when to check upstreams for improvements without having to remember ad hoc.
5. As a developer, I want factory/write-eval built first so every subsequent skill can be evaluated against a consistent standard from the start.
6. As a developer, I want each skill to have a co-located eval.yaml so I can verify the skill's trigger and output behaviour deterministically.
7. As a developer, I want skills organised by phase (design, factory, implement, test, review, deploy, operate, cross-cutting) with metadata.category in frontmatter so I can discover skills by what I am doing in the SDLC.
8. As a developer, I want design/grill-me to be the default deep-grill skill (calling factory/write-adr when decisions crystallise) so grilling sessions automatically produce ADRs without duplicate logic.
9. As a developer, I want design/grill-lean as a lightweight alternative so I can run a quick interrogation without domain model integration when that overhead is unnecessary.
10. As a developer, I want design/write-prd to enforce "why + what only, never how" via inline self-checks so PRDs don't drift into implementation territory.
11. As a developer, I want design/write-prd to verify a grill session exists as a prerequisite so PRDs are never written cold.
12. As a developer, I want design/architecture-review to present ≥2 options with tradeoffs so I never receive a single recommendation without alternatives.
13. As a developer, I want design/break-into-issues to propose Gitea milestone groupings for PRDs producing >5 issues so large bodies of work have a natural epic structure.
14. As a developer, I want design/break-into-issues to enforce independently shippable slices so no issue blocks another open issue.
15. As a developer, I want issue specs to carry EARS-format acceptance criteria so requirements are AI-parseable and testable.
16. As a developer, I want issue specs to use delta markers (ADDED/MODIFIED/REMOVED) for brownfield changes so reviewers can see exactly what is changing.
17. As a developer, I want factory/write-skill to validate the trigger description against explicit, implicit, and negative test cases before completing so skills activate reliably.
18. As a developer, I want factory/validate-skill to produce severity-rated findings (missing eval = critical, missing failure handling = high, weak trigger = high) so skill quality gaps are clearly prioritised.
19. As a developer, I want factory/upgrade-skill to always add a new eval test capturing the correction so the same failure cannot recur silently.
20. As a developer, I want implement/tdd to remain a separate skill from implement/implement-feature so the methodology (TDD) is composable and reusable outside of full feature implementation.
21. As a developer, I want implement/implement-feature to require a linked issue with an EARS spec (checking docs/issues/ in the file-based phase, Gitea when configured) so implementation never begins without a spec.
22. As a developer, I want review/security-review to apply OWASP LLM Top 10 + Agentic AI Top 10 for application code, and AST03/04/06/07/09 for self-authored factory skills, so the right checklist is applied in each context.
23. As a developer, I want review/changelog-entry to produce conventional changelog format entries so git-cliff can consume them deterministically.
24. As a developer, I want deploy/deployment-checklist to verify a linked issue exists and is closed or in-progress before any deployment so deployments are always traceable to a spec.
25. As a developer, I want cross-cutting/governance-check to validate proposed actions against AGENTS.md so governance rules are checked without requiring the developer to recall them from memory.
26. As a developer, I want cross-cutting/session-handoff to prompt LESSONS.md extraction as part of handoff so cross-session learnings are captured before context is lost.
27. As a developer, I want iac/write-docker-compose to include pinned image versions, secrets via env vars, and healthchecks by default so Docker Compose files are production-safe without additional review.
28. As a developer, I want iac/iac-security-review to check hardcoded secrets, unpinned versions, missing resource limits, and non-idempotent patterns so IaC security issues are caught before apply.
29. As a developer, I want all skills to have a source: field (array) when derived from an upstream, and no source: field when original, so the absence of the field unambiguously means self-authored.
30. As a developer, I want caveman preserved as-is so token compression works without disruption.
31. As a developer, I want design/prototype preserved and placed in design/ so design-phase exploratory work has a clear skill home.
32. As a developer, I want cross-cutting/triage preserved so incoming issue intake has a skill home.
33. As a developer, I want cross-cutting/improve-codebase-architecture preserved in cross-cutting so architecture improvement is invocable at any phase boundary.
34. As a developer, I want cross-cutting/zoom-out preserved as a standalone skill (merge into architect role revisited at Chunk 5 grill) so orientation is available now without waiting for Chunk 5.

---

Implementation Decisions

Prerequisite: AGENTS.md refactor

Both the repo-level CLAUDE.md and the global providers/claude-code/CLAUDE.md become thin adapters importing AGENTS.md. Repo-level: AGENTS.md at repo root, CLAUDE.md imports it via @AGENTS.md. Global: core/AGENTS.md deployed to ~/.agents/AGENTS.md, providers/claude-code/CLAUDE.md imports it. Content currently in both CLAUDE.md files moves to their respective AGENTS.md. core/ deployment path (~/.claude/core/) unchanged — @import for on-demand files stays in the Claude Code adapter. An ADR superseding ADR-0005 is required. This issue must be closed before skill implementation begins.

Source field structure

Every skill derived from an upstream carries a source: array in frontmatter. Each entry:

source:
  - repo: mattpocock/skills        # GitHub slug — no URL (URL rots; slug is stable and searchable)
    commit: a3f8c21                # exact commit SHA reviewed at adoption time
    files:
      - tdd/SKILL.md               # red-green-refactor loop process
      - tdd/mocking.md             # mocking guidelines
    updated: 2026-05-17            # date of last upstream review for this entry

Multiple entries for skills combining patterns from multiple upstreams. Absence of source: means self-authored original. Single-source skills use a single-item array for schema consistency.

Upstream review cadence

Per-skill (not once at chunk start): during source review for each skill, check listed repos for commits since updated:, decide whether to pull changes in using the pull criteria documented in docs/notes/skill-implementation-workflow.md. After the roadmap is complete (post Chunk 7): quarterly calendar-based review. Cadence is a human responsibility — no tooling required until Chunk 6.

Factory bootstrap order

factory/write-eval is the first skill built in Chunk 3, with a hand-written eval for itself. factory/write-skill is second, also hand-written. implement/write-docs is the third skill — phase 2 of issue 0018, the first skill authored via write-skill itself (the factory eating itself for the first time). Every subsequent skill in Chunk 3 uses write-skill for SKILL.md authoring and write-eval for eval production. Eval YAML files live in .agents/evals/<category>/<skill-name>/eval.yaml. CI enforcement of evals is Chunk 6 — the files exist and document expected behaviour before then.

Skill taxonomy — phase × domain matrix

Phase axis: design, factory, implement, test, review, deploy, operate, cross-cutting. Domain axis: iac (tool-specific). Cross-cutting skills have no single phase home. Paths remain flat per ADR-0009; category expressed in metadata.category frontmatter only. Role skills (roles/) are Chunk 5.

Full Chunk 3 skill inventory

Design (6):

Flat name	Factory name	Origin
grill-lean	design/grill-lean	Refactored from Pocock grill-me
grill-me	design/grill-me	Refactored from grill-with-docs; calls write-adr
write-prd	design/write-prd	Refactored from Pocock to-prd
architecture-review	design/architecture-review	New
break-into-issues	design/break-into-issues	Refactored from Pocock to-issues
prototype	design/prototype	Preserved; frontmatter + standard added

Factory (7) — build write-eval first:

Flat name	Factory name	Origin
write-eval	factory/write-eval	New — build first
write-skill	factory/write-skill	Refactored from write-a-skill
write-issue-spec	factory/write-issue-spec	New
write-workflow	factory/write-workflow	New
write-adr	factory/write-adr	New; called by grill-me
upgrade-skill	factory/upgrade-skill	New
validate-skill	factory/validate-skill	New

Implement (5):

Flat name	Factory name	Origin
implement-feature	implement/implement-feature	New
tdd	implement/tdd	Preserved; frontmatter + standard added
refactor	implement/refactor	New
write-docs	implement/write-docs	Phase 2 of issue 0018 — first factory-authored skill
diagnose	implement/diagnose	Preserved; frontmatter + standard added

Test (3): write-tests, generate-test-data, review-test-coverage — all new.

Review (4): code-review, security-review, pr-description, changelog-entry — all new.

Deploy (4): write-ci-pipeline, write-deployment-config, write-ai-review-workflow, deployment-checklist — all new.

Operate (4): write-runbook, incident-diagnosis, post-mortem, inspect-deployment — all new.

IaC / domain (2):

Flat name	Factory name	Origin
write-docker-compose	iac/write-docker-compose	New
iac-security-review	iac/iac-security-review	New

Cross-cutting (7):

Flat name	Factory name	Origin
session-handoff	cross-cutting/session-handoff	New
governance-check	cross-cutting/governance-check	New; references AGENTS.md
git-commit-message	cross-cutting/git-commit-message	New
improve-codebase-architecture	cross-cutting/improve-codebase-architecture	Preserved; frontmatter + standard added
triage	cross-cutting/triage	Preserved; fix dead references; frontmatter + standard added
zoom-out	cross-cutting/zoom-out	Preserved; frontmatter + standard added
caveman	cross-cutting/caveman	Keep as-is

Total: 42 skills. Role skills (6) deferred to Chunk 5. Gitea skills (3) moved to providers/gitea/ adapter. 5 IaC skills deferred.

Skill composition pattern

Skills call other skills by name where appropriate, keeping each skill focused. Established compositions:

• grill-me calls write-adr when a decision crystallises
• grill-me uses grill-lean as its interview engine
• implement-feature calls tdd as its implementation methodology
• Future: write-workflow will formalise these chains (Chunk 4)

Design phase sequence

grill-lean (optional lightweight) → grill-me (primary, with docs) → write-prd → architecture-review (optional) → break-into-issues

PRD artifact scope (placeholder — refine during write-prd implementation)

PRDs contain: problem statement, goals, non-goals (explicit), functional requirements at feature level, success criteria. Never contain: implementation approach, technical design, EARS-level detail. Inline self-checks in write-prd enforce this. Prerequisite: linked grill session output.

Issue artifact scope (placeholder — refine during write-issue-spec implementation)

Issues contain: link to parent PRD (inherited why), EARS acceptance criteria, brownfield delta markers, design notes (non-trivial only), independently completable task checklist. Inline self-checks in break-into-issues and write-issue-spec enforce this. Large PRDs (>5 issues) include Gitea milestone groupings in the output.

Provider-agnostic issue tracker

Skills reference "linked issue" generically. In the file-based phase (docs/issues/), skills check for a matching docs/issues/NNNN-*.md. When Gitea MCP is configured, skills use it instead. The active backend is determined at runtime by MCP availability, not a config flag. An ADR (0011) documents this decision. Gitea-specific skills (setup-gitea-mcp, post-pr-review, create-issue) are a provider adapter at providers/gitea/ — not part of the core library.

Authoring standard for all skills

Every SKILL.md carries: name, description (trigger — written and tested first), version, updated, when (when the skill is invoked — deferred to Chunk 4 for full bidirectional reference convention), metadata.category, source (array, if upstream-derived), references (array, if external citations needed). Body sections: role, when/when-not, required inputs, constraints, process, output format, failure handling, self-check. Body under 500 lines. XML tags only for skills with ≥3 logical sections and 500+ tokens.

Sub-agent usage in skill implementation

Skills are implemented using the per-skill workflow in docs/notes/skill-implementation-workflow.md. Sub-agents handle source discovery, source review (including licence and security checks), conflict checking against the constitution and factory principles, and eval writing. This keeps the main context lean and ensures each step is independently reviewable. The synthesis grill and HITL behavioral test are human-in-the-loop steps that cannot be delegated.

Changelog tooling

git-cliff adopted as the deterministic changelog generator. Config (cliff.toml) added to this repo in Chunk 3; CI integration in Chunk 6. review/changelog-entry skill handles prose release notes for cases where conventional commit messages alone are insufficient. git-cliff is selected over release-please (GitHub-only, incompatible with Gitea) and conventional-changelog (Node.js dependency, less actively maintained).

Open decisions carried forward

• when: frontmatter + bidirectional reference convention: principle documented in CONTEXT.md now; reference scanner tooling in Chunk 6; full resolution deferred to Chunk 4+.
• Merging zoom-out into architect role: revisit at Chunk 5 grill session.
• PRD/issue template refinement: placeholder scope used during implementation; templates refined when writing write-prd and write-issue-spec.

---

Testing Decisions

Skills are content, not code — they cannot be unit tested. Verification is behavioural.

What makes a good skill eval:

• Tests trigger behaviour (does the skill activate on the right prompts?), not implementation (does the SKILL.md contain specific text?)
• Each eval has: ≥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

Every skill gets an eval. Written via factory/write-eval (except write-eval itself, which gets a hand-written eval). Co-located at .agents/evals/<category>/<skill-name>/eval.yaml.

CI enforcement: eval files exist in Chunk 3; CI gates that run them on skill changes are Chunk 6.

Behavioural acceptance testing (human-executed post-commit, per skill): open a fresh Claude session, invoke the skill with the trigger phrases from its description, verify the output meets the authoring standard. Each issue includes a short acceptance checklist.

Prior art: tests/test-governance-layer.sh and tests/test-chunk2-behavioral.sh — behavioural test scripts from Chunks 2 and governance workstream. Same pattern applies here.

---

Out of Scope

• Role skills (architect, developer, reviewer, security, qa, ops) — Chunk 5
• 5 deferred IaC skills (write-ansible-role, write-terraform-module, write-k8s-manifest, proxmox-vm-spec, write-molecule-test) — dedicated IaC workstream
• Gitea integration skills (setup-gitea-mcp, post-pr-review, create-issue) — providers/gitea/ adapter, not Chunk 3
• CI eval gates — Chunk 6
• Reference scanner tooling — Chunk 6
• core/ → ~/.agents/ migration — Chunk 7
• git-cliff CI integration — Chunk 6 (config only in Chunk 3)
• Changelog tooling (beyond cliff.toml config) — Chunk 6
• Workflow formalisation — Chunk 4
• when: frontmatter full implementation — open, Chunk 4+

---

Further Notes

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.

Second grill before implementation: the first issue in Chunk 3 (after the AGENTS.md prerequisite) is a dedicated grill on the general skill implementation workflow — what the per-skill process looks like, what the working conventions are, and how the factory/write-eval-first bootstrap works in practice. That grill produces the conventions applied to all subsequent skill issues.

ADRs to produce during implementation:

• ADR-0011: Provider-agnostic issue tracker abstraction (file-based default, Gitea first adapter)
• ADR-0012: AGENTS.md as provider-agnostic governance entry point (supersedes ADR-0005 partially)