docs: Chunk 3 grill, PRD, ADRs, and doc updates
- docs/prd/chunk-3-skills-library.md: PRD for 42-skill library rebuild; AGENTS.md refactor as prerequisite; factory bootstrap order (write-eval first); source field schema; upstream review cadence; design phase sequence; IaC/Gitea scope decisions - docs/adr/0011-provider-agnostic-issue-tracker.md: file-based default, Gitea as provider adapter, "issue" as canonical cross-provider term - docs/adr/0012-agents-md-provider-agnostic-entry-point.md: AGENTS.md as content source, CLAUDE.md as thin adapter; partially supersedes ADR-0005 - CONTEXT.md: 8 new glossary terms (AGENTS.md, skill composition, source field, provider-agnostic issue tracker, design phase sequence, PRD scope, issue scope, bidirectional reference principle); CLAUDE.md index model updated; stale workflow example fixed - docs/ROADMAP.md: changelog tooling and IaC/Gitea scope resolved; when: field question updated; Chunk 3 grill housekeeping note added - docs/spec/overview.md: Chunk 3 target updated with PRD link, skill count, and AGENTS.md prerequisite Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
30
CONTEXT.md
30
CONTEXT.md
@@ -11,7 +11,7 @@ description: Domain language and decisions for the global AI development config
|
||||
`core/` content uses plain imperative language — no tool names, provider APIs, or format assumptions. Anything referencing a specific tool belongs in `providers/`, not `core/`. Providers translate core content into the tool's expected format and language.
|
||||
|
||||
### CLAUDE.md index model
|
||||
`providers/claude-code/CLAUDE.md` (source) is deployed to `~/.claude/CLAUDE.md` via `install.sh`. It has two tiers: (1) a short always-loaded section for universal rules that must apply every session — including communication style; (2) a content index of pointers to on-demand files in `~/.claude/core/` that the agent reads when needed. Context size is kept minimal.
|
||||
`AGENTS.md` is the source of always-on universal rules (provider-agnostic). `providers/claude-code/CLAUDE.md` is a thin adapter: it imports `AGENTS.md` via `@AGENTS.md` and appends Claude Code-specific additions (e.g. `@import` directives for on-demand files in `~/.claude/core/`). Deployed to `~/.claude/CLAUDE.md` via `install.sh`. Context size is kept minimal — only what is needed every session is loaded upfront; detailed content is pulled on demand. See ADR-0012. (Pending implementation in Chunk 3 prerequisite issue — current deployed state still uses `providers/claude-code/CLAUDE.md` as the content source.)
|
||||
|
||||
### Instruction file format
|
||||
`core/instructions/<topic>.md` files are plain markdown — no frontmatter, no schema. The agent decides when to read each file based on task context and the content index label in `providers/claude-code/CLAUDE.md`. Frontmatter is deferred until there is evidence that agents are loading the wrong files in practice.
|
||||
@@ -71,9 +71,9 @@ The set of machines and projects under management in Phase 2 of the Management A
|
||||
Reusable slash commands for AI coding tools, defined as `SKILL.md` files following the [Agent Skills open standard](https://agentskills.io). Canonical location: `.agents/skills/<skill-name>/SKILL.md` in this repo; deployed to `~/.agents/skills/` on install. Providers that don't read `~/.agents/skills/` natively get a symlink adapter declared in `providers/<name>/provider-manifest.sh` (e.g. Claude Code: `~/.claude/skills/ → ~/.agents/skills/`).
|
||||
|
||||
### Content types
|
||||
- **Instructions** — stateless rules defining AI behavior. Split into two tiers: (1) universal rules (communication, behavior) live in the always-on section of `providers/claude-code/CLAUDE.md`; (2) topic-specific rules (coding, git, testing) live in `core/instructions/<topic>.md` and are read on-demand.
|
||||
- **Instructions** — stateless rules defining AI behavior. Split into two tiers: (1) universal rules (communication, behavior) live in `AGENTS.md` (provider-agnostic), loaded into every session via the provider adapter (`CLAUDE.md` imports `AGENTS.md`); (2) topic-specific rules (coding, git, testing) live in `core/instructions/<topic>.md` and are read on-demand via `@import` in the Claude Code adapter.
|
||||
- **Agents** — role definitions activated on-demand for a specific task.
|
||||
- **Workflows** — compositions of skills chained into a larger task. Invokable by agents or humans. Example: grill-me → to-prd → to-issues as a product design workflow.
|
||||
- **Workflows** — compositions of skills chained into a larger task. Invokable by agents or humans. Example: `grill-me` → `write-prd` → `break-into-issues` as the canonical design workflow.
|
||||
- **Prompts** — shared fragments (system prompt sections, output formats) embedded into multiple skills or workflows.
|
||||
|
||||
### HITL (human-in-the-loop)
|
||||
@@ -100,6 +100,30 @@ Defined in full in `docs/ai-constitution.md` Section 3. Agent-actionable rules i
|
||||
### Sycophancy
|
||||
The failure mode where RLHF-trained models prioritise approval over accuracy. Treated as a first-class reliability risk: models change correct answers to wrong ones under user pressure in a majority of observed cases, then persist in the wrong answer. Designing against sycophancy is an explicit obligation, not a quality-of-life concern. Countermeasures: explicit pushback resistance instructions, prompting for dissent, cross-validating against independent sources. Never interpret AI agreement as AI accuracy.
|
||||
|
||||
### AGENTS.md
|
||||
The provider-agnostic governance and instruction entry point. Lives at the repo root (project-level) and at `core/AGENTS.md` → deployed to `~/.agents/AGENTS.md` (global). Contains all always-on rules in plain markdown with no provider-specific syntax. Provider-specific files (`CLAUDE.md`) become thin adapters that import it. Claude Code reads `CLAUDE.md` natively (not `AGENTS.md` directly); `CLAUDE.md` imports `AGENTS.md` via `@AGENTS.md`. This pattern means a single source of truth can serve multiple providers without duplication.
|
||||
|
||||
### Skill composition
|
||||
A skill calling another skill by name to delegate a sub-task. The calling skill focuses on the orchestration decision ("when to do X"); the called skill owns the mechanics ("how to do X"). Established compositions: `grill-me` calls `write-adr` when a decision crystallises; `implement-feature` calls `tdd` as its implementation methodology. Composition chains are formalised as workflows in Chunk 4.
|
||||
|
||||
### Source field
|
||||
Frontmatter field (`source:`) on skill files tracking upstream provenance. An array — supports multiple upstream sources per skill. Each entry: `repo` (GitHub slug, e.g. `mattpocock/skills` — no URL, slug is stable and searchable), `commit` (exact SHA reviewed at adoption), `files` (list of files adopted with inline comments on what was taken), `updated` (date of last upstream review for this entry). Absence of `source:` means self-authored original. Upstream review cadence: start of each chunk during roadmap; quarterly after roadmap completion (post Chunk 7).
|
||||
|
||||
### Provider-agnostic issue tracker
|
||||
Skills and workflows reference "linked issue" generically rather than a specific provider. In the file-based phase, an issue is a `docs/issues/NNNN-<slug>.md` file. When Gitea MCP is configured, the same skills use it instead. The active backend is determined at runtime by MCP availability. "Issue" is the canonical cross-provider term (GitHub, GitLab, Gitea all use it). Gitea-specific skills are a provider adapter (`providers/gitea/`), not part of the core library. See ADR-0011.
|
||||
|
||||
### Design phase sequence
|
||||
The canonical pre-implementation sequence within any workstream: `grill-lean` (optional lightweight interrogation, no docs) → `grill-me` (primary: deep interrogation + domain alignment + ADR writing) → `write-prd` (why + what only, never how) → `architecture-review` (optional: technical approach evaluation, ≥2 options) → `break-into-issues` (independently shippable slices; proposes Gitea milestone groupings for PRDs producing >5 issues).
|
||||
|
||||
### PRD scope
|
||||
A PRD contains: problem statement, goals, explicit non-goals, functional requirements at feature level, success criteria. Never contains: technical approach, implementation steps, or EARS-level detail (that is issue scope). Prerequisite: a completed grill session. Validated by inline self-checks in the `write-prd` skill.
|
||||
|
||||
### Issue scope
|
||||
An issue contains: link to parent PRD (inherited why) + one-line context for this slice, EARS-format acceptance criteria, brownfield delta markers (ADDED/MODIFIED/REMOVED), design notes (non-trivial issues only), independently completable task checklist. Prerequisite: parent PRD linked, or explicit standalone justification. No issue may block another open issue. Validated by inline self-checks in `write-issue-spec` and `break-into-issues`.
|
||||
|
||||
### Bidirectional reference principle
|
||||
Files that reference other files should declare those references explicitly. The referencing file carries the forward reference (e.g. content index in `CLAUDE.md`, `references:` in frontmatter). The referenced file carries a `when:` field describing when it is loaded. Both sides should agree — divergence signals staleness. The reverse map ("what files reference this file?") is derived by a reference scanner script (Chunk 6 tooling), not maintained manually. This principle applies to instruction files, skills, and workflow documents.
|
||||
|
||||
### Workstream
|
||||
A focused work session oriented around a single goal — a feature, bug, improvement, or exploration. Starts with a grill to produce an artifact (PRD, Bug Brief, ADR, etc.), runs through issue implementation, and closes with docs + commit. Ongoing skills (/diagnose, /prototype, /zoom-out) are invoked ad hoc within a workstream as needed.
|
||||
|
||||
|
||||
@@ -81,11 +81,11 @@ Items consciously not resolved — to be addressed in the relevant chunk PRD or
|
||||
| QA agent design — what does automated agent testing look like in practice? | Grill before Chunk 5 (agents) |
|
||||
| Automated deployment pipeline — CI/CD beyond gitops convention | Chunk 6 grill |
|
||||
| Formal CI gate for `/improve-codebase-architecture` | Chunk 6 grill |
|
||||
| Changelog tooling — which generator (git-cliff, conventional-changelog, etc.) and where it runs | Chunk 3 grill |
|
||||
| Content index frontmatter — replace inline `when:` hints in CLAUDE.md content index with a `when:` field in each instruction/skill file so the agent discovers load conditions from the file itself. Cover before implementing Chunk 3 skills. | Chunk 3 grill |
|
||||
| ~~Changelog tooling — which generator (git-cliff, conventional-changelog, etc.) and where it runs~~ | ✅ Resolved — Chunk 3 grill. **git-cliff** selected (Rust binary, no runtime deps, Gitea-compatible). `cliff.toml` config in Chunk 3; CI integration in Chunk 6. `review/changelog-entry` skill handles prose release notes where commit messages are insufficient. |
|
||||
| Content index frontmatter — bidirectional reference convention: files referencing others should carry a `when:` field in frontmatter; the referencing file (e.g. CLAUDE.md content index) and the referenced file should both document the relationship. `.claude/rules/` path-scoped rules resolve the path-based case natively. Reference scanner (reverse map: "what files point to X?") deferred to Chunk 6 tooling. Full `when:` field resolution deferred to Chunk 4+. | Chunk 4+ / Chunk 6 tooling |
|
||||
| ~~Skill taxonomy — flat vs nested paths, category organisation~~ | ✅ Resolved — factory integration grill. Flat paths (Claude Code + agentskills.io standard enforce one-level-deep discovery). Categories via `metadata: category:` in SKILL.md frontmatter. See ADR-0009. |
|
||||
| ~~Factory boundary — which factory features belong here vs project repos~~ | ✅ Resolved — factory integration grill. This repo is a provider (ADR-0008). LESSONS.md and docs/spec/ are exceptions: added here because this repo also develops itself. IaC and Gitea skills are global optional. Role skills in .agents/skills/; core/agents/ for subagent definitions (ADR-0010). |
|
||||
| IaC and Gitea skill scope — which specific skills to include in the global optional set, and in what order | Chunk 3 PRD |
|
||||
| ~~IaC and Gitea skill scope — which specific skills to include in the global optional set, and in what order~~ | ✅ Resolved — Chunk 3 PRD. IaC in Chunk 3: `write-docker-compose` + `iac-security-review`. Deferred: Ansible, Molecule, Terraform, K8s, Proxmox. Gitea skills moved to `providers/gitea/` provider adapter — not part of the core library. |
|
||||
| Agent behavior confirmation model — writes/edits/git currently require stating intent + approval before acting. Loosen to autonomy-first once skills and workflows are proven and automated agents replace direct interaction. | Phase 2 refinement (post Chunk 4) |
|
||||
| ~~CLAUDE.md always-on refinement — security floor (no credentials/auth URLs), scope discipline (no over-engineering), tool preference (Read/Edit over Bash); **plus instruction quality**: current rules are thin one-liners observed in practice to lose to RLHF-trained defaults (verbose responses, validating user positions); fix is specificity, counter-examples, and boundary framing — not accepting violations as expected. Needs its own grill session → PRD before implementation.~~ | ✅ Resolved — Governance workstream Phase 1. `core/instructions/governance.md` loaded via `@import` covers hard prohibitions, data classification, HITL, sycophancy resistance, and deterministic execution preference. Instruction quality principle documented in `CONTEXT.md`. |
|
||||
|
||||
@@ -98,3 +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.
|
||||
|
||||
11
docs/adr/0011-provider-agnostic-issue-tracker.md
Normal file
11
docs/adr/0011-provider-agnostic-issue-tracker.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# Provider-agnostic issue tracker with file-based default and provider adapters
|
||||
|
||||
Skills and workflows reference a "linked issue" generically rather than coupling to a specific issue tracker. In the file-based phase, an issue is a `docs/issues/NNNN-<slug>.md` file. When a provider MCP (e.g. Gitea MCP) is configured, skills detect it at runtime and use it instead. The active backend is determined by MCP availability — no config flag required. "Issue" is the canonical cross-provider term; GitHub, GitLab, and Gitea all use it natively.
|
||||
|
||||
Gitea-specific skills (`setup-gitea-mcp`, `post-pr-review`, `create-issue`) are a provider adapter at `providers/gitea/` — structurally identical to how `providers/claude-code/` adapts core content for Claude Code. They are not part of the core skill library.
|
||||
|
||||
Two alternatives were rejected. Gitea-specific skills in the core library would block use before Gitea is configured and embed a provider assumption into skills that are otherwise provider-neutral. Per-provider skill variants (e.g. `implement-feature` + `implement-feature-gitea`) create maintenance overhead with no functional gain — the only difference is the issue lookup mechanism, not the skill logic.
|
||||
|
||||
The file-based default was chosen because this repo must work before Gitea is set up. File-based issues are already the working convention (`docs/issues/`), established in Chunk 1. Gitea is the first concrete provider and will be configured after Chunk 3; existing file-based issues will be migrated at that point.
|
||||
|
||||
This decision makes the skills library usable on any machine without external service dependencies, while keeping Gitea integration as a first-class path once available. The provider adapter pattern (`providers/gitea/`) is consistent with ADR-0007 (provider adapters as symlinks) and ADR-0008 (factory boundary).
|
||||
11
docs/adr/0012-agents-md-provider-agnostic-entry-point.md
Normal file
11
docs/adr/0012-agents-md-provider-agnostic-entry-point.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# AGENTS.md as provider-agnostic governance entry point; CLAUDE.md as thin adapter
|
||||
|
||||
`AGENTS.md` is the single source of truth for always-on agent instructions. It lives at the repo root (project-level) and at `core/AGENTS.md` deployed to `~/.agents/AGENTS.md` (global). It contains all universal rules in plain markdown with no provider-specific syntax. Provider-specific files (`CLAUDE.md`) become thin adapters that import it — the repo-level `CLAUDE.md` contains `@AGENTS.md` plus any Claude Code-specific additions; the global `~/.claude/CLAUDE.md` imports `~/.agents/AGENTS.md` similarly.
|
||||
|
||||
Claude Code reads `CLAUDE.md` natively, not `AGENTS.md`. The Anthropic documentation explicitly recommends the import pattern for repos that use `AGENTS.md` for other tools: `CLAUDE.md` contains `@AGENTS.md` and appends Claude Code-specific content below. This means `CLAUDE.md` continues to exist as the Claude Code entry point but carries no original content — it is purely an adapter.
|
||||
|
||||
`AGENTS.md` must be self-contained: no `@import` syntax (which is Claude Code-specific and would make the file provider-specific). On-demand instruction loading via `@import` stays in the Claude Code adapter (`CLAUDE.md`), pointing to `core/instructions/` as today. The `core/` deployment path (`~/.claude/core/`) is unchanged in this chunk; migration to `~/.agents/` is deferred to Chunk 7 when a second provider (Copilot) provides evidence of what that provider needs.
|
||||
|
||||
This partially supersedes ADR-0005 (two-tier CLAUDE.md model). ADR-0005 established the always-on / on-demand split and remains correct as a structural pattern. What changes is where the always-on content lives: previously in `providers/claude-code/CLAUDE.md`, now in `AGENTS.md`. The adapter layer ADR-0005 described still exists; `CLAUDE.md` is now the adapter rather than the source.
|
||||
|
||||
The alternative — keeping always-on content in `providers/claude-code/CLAUDE.md` — was rejected because it violates ADR-0003 (provider-agnostic core). Content that applies to all agents regardless of provider has no business living in a provider-specific file. When Copilot arrives in Chunk 7, duplicating that content into a Copilot adapter or maintaining two sources of the same rules is exactly the drift ADR-0003 was written to prevent.
|
||||
231
docs/prd/chunk-3-skills-library.md
Normal file
231
docs/prd/chunk-3-skills-library.md
Normal file
@@ -0,0 +1,231 @@
|
||||
# PRD: Chunk 3 — Skills Library Rebuild
|
||||
|
||||
**Status:** Ready for issues
|
||||
**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:
|
||||
|
||||
```yaml
|
||||
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
|
||||
At the start of each chunk: grep all `source:` fields, check the listed repos for commits since `updated:`, decide whether to pull changes in. 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. Every subsequent skill in Chunk 3 gets an eval written via `write-eval`. 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` | New |
|
||||
| `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`, `metadata.category`, `source` (array, if upstream-derived). 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.
|
||||
|
||||
### 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
|
||||
|
||||
**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.
|
||||
|
||||
**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)
|
||||
@@ -100,25 +100,25 @@
|
||||
|
||||
## IaC Domain Skills
|
||||
|
||||
| Skill | Trigger description | Key constraints |
|
||||
|---|---|---|
|
||||
| `iac/write-ansible-role` | Write an Ansible role, create Ansible automation, Ansible role for X | Idempotency review must specifically check: missing `creates:` on file-creating tasks, unconditional handlers (should use `notify`), absent rollback strategies, `shell`/`command` tasks without guards. Molecule test scaffold included; version pinned in frontmatter |
|
||||
| `iac/write-terraform-module` | Write Terraform module, Terraform config for X | Pin provider versions; never use Terraform provisioners to call Ansible — HashiCorp designates provisioners a "last resort" and they break idempotency; use a separate CI/CD Ansible stage instead; includes variables, outputs, validation blocks |
|
||||
| `iac/write-k8s-manifest` | Write Kubernetes manifest, K8s deployment for X | Resource limits required; security context required; network policy required |
|
||||
| `iac/write-docker-compose` | Write Docker Compose, compose stack for X | Pinned image versions; secrets via env vars; healthchecks included |
|
||||
| `iac/proxmox-vm-spec` | Create Proxmox VM, Proxmox config for X | Loads references/proxmox-cluster.md; bpg/proxmox provider; version pinned |
|
||||
| `iac/iac-security-review` | Security review this IaC, check Terraform/Ansible for issues | Checks: hardcoded secrets, overly permissive access, missing limits, unpinned versions, Terraform provisioners, non-idempotent Ansible patterns (shell/command without guards, missing creates:, unconditional handlers) |
|
||||
| `iac/write-molecule-test` | Write Molecule tests, Ansible testing, role test | Generates converge.yml, verify.yml, molecule.yml |
|
||||
| Skill | Trigger description | Key constraints |
|
||||
| ------------------------------| ----------------------------------------------------------------------| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
||||
| `iac/write-ansible-role` | Write an Ansible role, create Ansible automation, Ansible role for X | Idempotency review must specifically check: missing `creates:` on file-creating tasks, unconditional handlers (should use `notify`), absent rollback strategies, `shell`/`command` tasks without guards. Molecule test scaffold included; version pinned in frontmatter |
|
||||
| `iac/write-terraform-module` | Write Terraform module, Terraform config for X | Pin provider versions; never use Terraform provisioners to call Ansible — HashiCorp designates provisioners a "last resort" and they break idempotency; use a separate CI/CD Ansible stage instead; includes variables, outputs, validation blocks |
|
||||
| `iac/write-k8s-manifest` | Write Kubernetes manifest, K8s deployment for X | Resource limits required; security context required; network policy required |
|
||||
| `iac/write-docker-compose` | Write Docker Compose, compose stack for X | Pinned image versions; secrets via env vars; healthchecks included |
|
||||
| `iac/proxmox-vm-spec` | Create Proxmox VM, Proxmox config for X | Loads references/proxmox-cluster.md; bpg/proxmox provider; version pinned |
|
||||
| `iac/iac-security-review` | Security review this IaC, check Terraform/Ansible for issues | Checks: hardcoded secrets, overly permissive access, missing limits, unpinned versions, Terraform provisioners, non-idempotent Ansible patterns (shell/command without guards, missing creates:, unconditional handlers) |
|
||||
| `iac/write-molecule-test` | Write Molecule tests, Ansible testing, role test | Generates converge.yml, verify.yml, molecule.yml |
|
||||
|
||||
---
|
||||
|
||||
## Gitea Integration Skills
|
||||
|
||||
| Skill | Trigger description | Key constraints |
|
||||
|---|---|---|
|
||||
| `gitea/setup-gitea-mcp` | Set up Gitea MCP, connect agent to Gitea, configure MCP | Generates config + dedicated agent user setup; includes --tools filter recommendations |
|
||||
| `gitea/post-pr-review` | Post review findings to PR, add review comments, submit review | Uses Gitea MCP; tiered severity; never auto-merges |
|
||||
| `gitea/create-issue` | Create a Gitea issue, log this as a bug, file an issue | Uses Gitea MCP; requires structured finding as input |
|
||||
| Skill | Trigger description | Key constraints |
|
||||
| -------------------------| ----------------------------------------------------------------| ----------------------------------------------------------------------------------------|
|
||||
| `gitea/setup-gitea-mcp` | Set up Gitea MCP, connect agent to Gitea, configure MCP | Generates config + dedicated agent user setup; includes --tools filter recommendations |
|
||||
| `gitea/post-pr-review` | Post review findings to PR, add review comments, submit review | Uses Gitea MCP; tiered severity; never auto-merges |
|
||||
| `gitea/create-issue` | Create a Gitea issue, log this as a bug, file an issue | Uses Gitea MCP; requires structured finding as input |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -11,7 +11,9 @@ Current deployed state of this repo — what you get if you run `install.sh` tod
|
||||
|
||||
Current skills: `caveman`, `diagnose`, `grill-me`, `grill-with-docs`, `improve-codebase-architecture`, `prototype`, `tdd`, `to-issues`, `to-prd`, `triage`, `write-a-skill`, `zoom-out`.
|
||||
|
||||
**Chunk 3 target:** the full skill library defined in `docs/research/ai-coding-factory/ai-coding-factory-skills-index.md`. That file is the canonical build reference — trigger descriptions, constraints, and category for each skill. Skills are stored flat (`skill-name/SKILL.md`) per ADR-0009; the `category/skill-name` notation in the skills-index is for identification only. Core categories: roles, design, factory, implement, test, review, deploy, operate, cross-cutting. Global optional: iac, gitea. Delete the skills-index once all skills exist.
|
||||
**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.
|
||||
|
||||
**Prerequisite:** AGENTS.md refactor must complete before Chunk 3 skill implementation begins — both `CLAUDE.md` files (repo-level and global) become thin adapters importing `AGENTS.md`. See ADR-0012 (to be written during implementation).
|
||||
|
||||
### Claude Code configuration
|
||||
- `~/.claude/CLAUDE.md` — global config index; always-on rules + content index pointers
|
||||
|
||||
Reference in New Issue
Block a user