docs: issue 0016 — skill implementation workflow grill
Produces docs/notes/skill-implementation-workflow.md with agreed conventions for all Chunk 3 skill issues (0017–0028). Key decisions: - Per-skill process: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check vs constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively - Bootstrap: write-eval (hand-written) → write-skill (hand-written) → write-docs (first factory-authored, phase 2 of 0018) → everything else - Upstream review changed from per-chunk-start to per-skill - `when:` and `references:` frontmatter fields added to authoring standard - Sub-agent usage prescribed as named steps in the workflow - HITL: human reviewed and approved conventions Updates: PRD implementation decisions; issues 0016–0028 with specific acceptance criteria; docs/spec/overview.md; ROADMAP Chunk 3 housekeeping note (bootstrap order, cadence, acceptance criteria status); CONTEXT.md Source field (per-skill cadence, references: companion field); LESSONS.md with three patterns from the grill session. Post-grill additions (same session): Step 6 (session handoff) added to the workflow; handoff section appended to issue 0016; handoff checklist item added to Chunk 3 closure issue (0028). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -98,4 +98,4 @@ Items consciously not resolved — to be addressed in the relevant chunk PRD or
|
||||
- **Chunk 2 behavioral tests** — run and fully resolved 2026-05-17. 7/8 pass; scenario 4 (push confirmation) inconclusive — no remote in test environment, rule tightened but unverified. All fixable failures addressed: rule specificity in `providers/claude-code/CLAUDE.md`; context-loading guarantee via `@import CONTEXT.md` in repo CLAUDE.md; standing rule in CONTEXT.md to check `docs/adr/` and ROADMAP resolved entries before answering design questions. Chunk 2 ✅ complete.
|
||||
- **Governance Phase 1 behavioral tests** — run 2026-05-17. 3/4 testable scenarios pass. Secrets rule gap fixed (2026-05-17): extended to cover credential reproduction in response text and examples, with placeholder requirement added to `core/instructions/governance.md`. HITL scenario not testable in this environment (Nginx not installed); HITL gap evidenced by instructions test scenario 4 — push confirmation rule fix addresses the same root cause. Governance Phase 1 ✅ complete.
|
||||
- **AI ethics/security workstream** — `docs/notes/ai-ethics-security-principles.md` exploration note is superseded. Governance Phase 1 (`core/instructions/governance.md`) covers all planned scope: credentials, data classification, HITL, scope discipline, agent autonomy, transparency, and security code review. Tier-placement architectural question resolved by the `@import` always-on model. No separate workstream needed.
|
||||
- **Chunk 3 grill complete** — 2026-05-17. PRD at `docs/prd/chunk-3-skills-library.md`. Key decisions: 42-skill target library, AGENTS.md refactor as prerequisite issue (both CLAUDE.md files become thin adapters), git-cliff for changelog, provider-agnostic issue tracker abstraction, grill-me/grill-lean design phase split, factory bootstrap order (write-eval → write-skill → write-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.
|
||||
- **Chunk 3 grill complete** — 2026-05-17. PRD at `docs/prd/chunk-3-skills-library.md`. Key decisions: 42-skill target library, AGENTS.md refactor as prerequisite issue (both CLAUDE.md files become thin adapters), git-cliff for changelog, provider-agnostic issue tracker abstraction, grill-me/grill-lean design phase split, factory bootstrap order (write-eval → write-skill → write-docs phase 2 → write-adr → remaining factory → design → parallel category groups). ADRs written: 0011 (provider-agnostic issue tracker), 0012 (AGENTS.md governance entry point, partially supersedes ADR-0005). Upstream review cadence: per-skill + quarterly post-roadmap (per-chunk-start changed to per-skill by issue 0016 grill). **Issues created 0015–0028** — all HITL; ~~0015 (AGENTS.md refactor, prerequisite)~~ ✅, ~~0016 (skill workflow grill, produces conventions for 0017–0028)~~ ✅, 0017–0018 (bootstrap skills: write-eval; write-skill + write-docs as phase 2), 0019 (remaining factory skills), 0020–0027 (design/implement/test/review/deploy/operate/iac/cross-cutting), 0028 (chunk closure). ~~Acceptance criteria for 0017–0028 to be refined after 0016 grill session.~~ ✅ Refined 2026-05-17 — see `docs/notes/skill-implementation-workflow.md`.
|
||||
|
||||
@@ -21,11 +21,30 @@ 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
|
||||
- [x] Grill session completed covering all topics above
|
||||
- [x] `docs/notes/skill-implementation-workflow.md` written with the agreed working conventions
|
||||
- [x] `docs/prd/chunk-3-skills-library.md` updated with any decisions that change or extend the Implementation Decisions section
|
||||
- [x] Issues 0017–0028 updated with specific acceptance criteria derived from the grill output
|
||||
- [x] **HITL:** human participates in grill, reviews conventions, and approves before implementation of any skill begins
|
||||
|
||||
## Handoff
|
||||
|
||||
**Status:** complete
|
||||
**Files produced:**
|
||||
- `docs/notes/skill-implementation-workflow.md`
|
||||
|
||||
**Key decisions:**
|
||||
- Step 6 (session handoff) added post-grill: each skill session closes by appending a `## Handoff` section to the skill's issue file. Cross-cutting observations go to `LESSONS.md` immediately, not batched to chunk end.
|
||||
- Handoff artifact is the issue file, not a separate `docs/notes/` file — avoids proliferating per-skill note files.
|
||||
|
||||
**Open threads:**
|
||||
- `when:` full bidirectional reference convention — deferred to Chunk 4
|
||||
- PRD/issue template scope — refined during 0019/0020 implementation
|
||||
- Merging `zoom-out` into architect role — revisit at Chunk 5 grill
|
||||
|
||||
**Next session start:**
|
||||
- Load: `CONTEXT.md`, `docs/notes/skill-implementation-workflow.md`, issue 0017 or 0018
|
||||
- First action: Step 1 (source discovery) for `write-eval`
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -16,7 +16,7 @@ Build `write-eval` — the first factory meta-skill, bootstrapped with a hand-wr
|
||||
- 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.
|
||||
Process: follow `docs/notes/skill-implementation-workflow.md`. Bootstrap exception: steps 1–3 (source discovery, source review, conflict check) still apply; SKILL.md and eval.yaml are hand-written rather than factory-produced.
|
||||
|
||||
## Implementation notes
|
||||
|
||||
@@ -37,7 +37,14 @@ write-eval has no direct Pocock equivalent. Expect to synthesize from multiple u
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description tested against explicit, implicit, and negative queries before body was written
|
||||
- [ ] `when:` frontmatter field present
|
||||
- [ ] `source:` field present only if upstream content adopted; absent if self-authored
|
||||
- [ ] `references:` field present if external citations used; absent otherwise
|
||||
- [ ] eval.yaml contains all 5 required test types: explicit trigger, implicit trigger, negative trigger, ≥2 deterministic output, ≥1 LLM-rubric quality
|
||||
- [ ] Body ≤500 lines; XML tags used only if ≥3 logical sections and 500+ tokens
|
||||
- [ ] `docs/spec/overview.md` updated to reflect `write-eval` deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -5,19 +5,31 @@
|
||||
|
||||
## 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.
|
||||
### Phase 1: `write-skill`
|
||||
|
||||
Build `write-skill` — the second bootstrap skill. Once complete, it is used to author all subsequent SKILL.md files in Chunk 3.
|
||||
|
||||
**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
|
||||
- Produces a complete SKILL.md following the authoring standard in `docs/notes/skill-implementation-workflow.md`
|
||||
- Validates trigger description against explicit, implicit, and negative test queries 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
|
||||
- SKILL.md is hand-written (write-skill cannot author itself before it exists)
|
||||
- Eval via `write-eval` (issue 0017)
|
||||
|
||||
Process: upstream review → trigger-first → skill body → `write-eval` for eval.yaml → behavioral test.
|
||||
### Phase 2: `write-docs`
|
||||
|
||||
Build `write-docs` — the first skill authored via `write-skill` itself (the factory eating itself for the first time). Implement immediately after phase 1 is complete and deployed.
|
||||
|
||||
**Trigger description** (from skills index): "Write documentation for X, document this module, create docs for this feature"
|
||||
|
||||
**Key constraints:**
|
||||
- Skill file: `.agents/skills/write-docs/SKILL.md`; `metadata.category: implement`
|
||||
- SKILL.md authored via `write-skill`; eval via `write-eval`
|
||||
- Follow full per-skill workflow from `docs/notes/skill-implementation-workflow.md` (sub-agents for discovery, review, conflict check)
|
||||
- Derives from code and spec; never invents behaviour
|
||||
|
||||
## Implementation notes
|
||||
|
||||
@@ -36,7 +48,14 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for both phases (see `docs/notes/skill-implementation-workflow.md`)
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in both SKILL.md files
|
||||
- [ ] `source:` and `references:` fields correctly populated or absent
|
||||
- [ ] eval.yaml for each skill contains all 5 required test types
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] Phase 2 (`write-docs`) is the first skill produced end-to-end by the factory
|
||||
- [ ] `docs/spec/overview.md` updated to reflect both skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -7,7 +7,7 @@
|
||||
|
||||
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.
|
||||
Each skill follows the per-skill workflow from `docs/notes/skill-implementation-workflow.md`. `write-adr` must be verified before starting issue 0020.
|
||||
|
||||
**Skills and trigger descriptions** (from skills index):
|
||||
|
||||
@@ -46,7 +46,14 @@ For all skills in this group: these are meta-skills with no direct Pocock placeh
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for all 5 skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in all SKILL.md files
|
||||
- [ ] `source:` and `references:` fields correctly populated or absent
|
||||
- [ ] eval.yaml for each skill contains all 5 required test types
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] `write-adr` implemented and passing behavioral test before design skills issue (0020) begins
|
||||
- [ ] `docs/spec/overview.md` updated to reflect all 5 skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -30,7 +30,7 @@ The 6 design phase skills. Four are refactors of existing Pocock placeholders; t
|
||||
|
||||
## Implementation notes
|
||||
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md`.
|
||||
|
||||
**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
|
||||
@@ -51,7 +51,14 @@ For new skills (`architecture-review`, `grill-lean`): search for prior art in th
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for all 6 skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in all SKILL.md files
|
||||
- [ ] `source:` fields populated for all refactored Pocock skills; `references:` present if external citations used
|
||||
- [ ] eval.yaml for each skill contains all 5 required test types
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] Conflict check run against constitution before synthesis grill; no unresolved HITL or data classification violations
|
||||
- [ ] `docs/spec/overview.md` updated to reflect all 6 skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
# 0021 — Implement skills: implement-feature, tdd, refactor, write-docs, diagnose
|
||||
# 0021 — Implement skills: implement-feature, tdd, refactor, 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).
|
||||
The 4 implement phase skills. One is new; three are preserved Pocock placeholders upgraded to the authoring standard. All authored via `write-skill` (0018), evals via `write-eval` (0017). `write-docs` has been moved to issue 0018 phase 2.
|
||||
|
||||
**Skills, origins, and trigger descriptions:**
|
||||
|
||||
@@ -14,19 +14,17 @@ The 5 implement phase skills. Two are new; three are preserved Pocock placeholde
|
||||
| `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).
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md`.
|
||||
|
||||
**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
|
||||
@@ -36,15 +34,22 @@ For new skills (`implement-feature`, `refactor`, `write-docs`): search for prior
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
- [ ] All 5 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: implement`; authoring standard met
|
||||
- [ ] All 4 SKILL.md files exist at `.agents/skills/<skill-name>/SKILL.md`; `metadata.category: implement`; authoring standard met (`write-docs` is in issue 0018 phase 2)
|
||||
- [ ] 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/`
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for all 4 skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in all SKILL.md files
|
||||
- [ ] `source:` and `references:` fields correctly populated or absent
|
||||
- [ ] eval.yaml for each skill contains all 5 required test types
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] `write-docs` confirmed removed from scope (implemented in issue 0018 phase 2)
|
||||
- [ ] `docs/spec/overview.md` updated to reflect all 4 skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -22,7 +22,7 @@ The 3 test phase skills. All are new. Authored via `write-skill` (0018), evals v
|
||||
|
||||
## Implementation notes
|
||||
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md`.
|
||||
|
||||
**Known upstream sources to review:**
|
||||
- `mattpocock/skills` — check for any test-phase skills in the current set
|
||||
@@ -39,7 +39,13 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for all 3 skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in all SKILL.md files
|
||||
- [ ] `source:` and `references:` fields correctly populated or absent
|
||||
- [ ] eval.yaml for each skill contains all 5 required test types
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] `docs/spec/overview.md` updated to reflect all 3 skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ The 4 review phase skills plus the `cliff.toml` changelog config. All skills are
|
||||
|
||||
## Implementation notes
|
||||
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md`.
|
||||
|
||||
**Known upstream sources to review:**
|
||||
- `mattpocock/skills` — check for code-review or security-review skills
|
||||
@@ -49,7 +49,13 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for all 4 skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in all SKILL.md files
|
||||
- [ ] `source:` and `references:` fields correctly populated or absent
|
||||
- [ ] eval.yaml for each skill contains all 5 required test types
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] `docs/spec/overview.md` updated to reflect all 4 skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ The 4 deploy phase skills. All are new. Authored via `write-skill` (0018), evals
|
||||
|
||||
## Implementation notes
|
||||
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md`.
|
||||
|
||||
**Known upstream sources to review:**
|
||||
- `bmad-method/bmad-method` — BMAD ops/deploy patterns and deployment checklist approach
|
||||
@@ -41,7 +41,13 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for all 4 skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in all SKILL.md files
|
||||
- [ ] `source:` and `references:` fields correctly populated or absent
|
||||
- [ ] eval.yaml for each skill contains all 5 required test types
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] `docs/spec/overview.md` updated to reflect all 4 skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -24,7 +24,7 @@ The 4 operate phase skills. All are new. Authored via `write-skill` (0018), eval
|
||||
|
||||
## Implementation notes
|
||||
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md`.
|
||||
|
||||
**Known upstream sources to review:**
|
||||
- `bmad-method/bmad-method` — BMAD ops role patterns
|
||||
@@ -42,7 +42,13 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for all 4 skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in all SKILL.md files
|
||||
- [ ] `source:` and `references:` fields correctly populated or absent
|
||||
- [ ] eval.yaml for each skill contains all 5 required test types
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] `docs/spec/overview.md` updated to reflect all 4 skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ The 2 IaC domain skills scoped for Chunk 3. Both are new. The 5 deferred IaC ski
|
||||
|
||||
## Implementation notes
|
||||
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md`.
|
||||
|
||||
**Known upstream sources to review:**
|
||||
- Search GitHub and agentskills.io for open-source Docker Compose and IaC security review skills
|
||||
@@ -37,7 +37,13 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for both skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in both SKILL.md files
|
||||
- [ ] `source:` and `references:` fields correctly populated or absent
|
||||
- [ ] eval.yaml for each skill contains all 5 required test types
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] `docs/spec/overview.md` updated to reflect both skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -29,7 +29,7 @@ The 7 cross-cutting skills (no single phase home). Three are new; four are prese
|
||||
|
||||
## Implementation notes
|
||||
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016).
|
||||
Follow the per-skill workflow defined in `docs/notes/skill-implementation-workflow.md`.
|
||||
|
||||
**Known upstream sources to review:**
|
||||
- `mattpocock/skills` — original `improve-codebase-architecture`, `triage`, `zoom-out`, `caveman` placeholders; record SHAs for adopted content
|
||||
@@ -47,7 +47,13 @@ Follow the per-skill workflow defined in `docs/notes/skill-implementation-workfl
|
||||
- [ ] `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)_
|
||||
- [ ] Per-skill process followed for all new/refactored skills: source discovery (sub-agent) → source review with licence/security check (sub-agent) → conflict check against constitution + factory principles (sub-agent) → synthesis grill → co-write iteratively
|
||||
- [ ] Trigger description for each skill tested against explicit, implicit, and negative queries before body written
|
||||
- [ ] `when:` frontmatter field present in all new/refactored SKILL.md files (`caveman` exempt)
|
||||
- [ ] `source:` and `references:` fields correctly populated or absent
|
||||
- [ ] eval.yaml for each new/refactored skill contains all 5 required test types (`caveman` exempt)
|
||||
- [ ] Body ≤500 lines for each skill
|
||||
- [ ] `docs/spec/overview.md` updated to reflect all skills deployed
|
||||
|
||||
## Blocked by
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@ Close out Chunk 3 once all 42 skills are complete: update the skills index to re
|
||||
**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.
|
||||
6. Review `docs/notes/skill-implementation-workflow.md` — verify the conventions are still accurate; update any entries that changed during implementation.
|
||||
|
||||
## Acceptance criteria
|
||||
|
||||
@@ -26,6 +27,8 @@ Close out Chunk 3 once all 42 skills are complete: update the skills index to re
|
||||
- [ ] `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
|
||||
- [ ] `docs/notes/skill-implementation-workflow.md` reviewed and updated to reflect any workflow changes discovered during Chunk 3
|
||||
- [ ] All skill issues (0017–0027) have a `## Handoff` section with status `complete`
|
||||
- [ ] **HITL:** human verifies the complete skills library in a fresh session before marking Chunk 3 done
|
||||
|
||||
## Blocked by
|
||||
|
||||
229
docs/notes/skill-implementation-workflow.md
Normal file
229
docs/notes/skill-implementation-workflow.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# Skill Implementation Workflow
|
||||
|
||||
**Produced by:** issue 0016 grill session, 2026-05-17
|
||||
**Applies to:** all Chunk 3 skill issues (0017–0028)
|
||||
|
||||
---
|
||||
|
||||
## Bootstrap sequence
|
||||
|
||||
The first two skills are hand-authored because the factory cannot build itself before it exists. Everything from step 3 onward uses the factory.
|
||||
|
||||
| Step | Skill | SKILL.md | eval.yaml |
|
||||
|---|---|---|---|
|
||||
| 1 | `write-eval` | Hand-written | Hand-written |
|
||||
| 2 | `write-skill` (phase 1 of issue 0018) | Hand-written | Via `write-eval` |
|
||||
| 3 | `write-docs` (phase 2 of issue 0018) | Via `write-skill` | Via `write-eval` |
|
||||
| 4+ | Everything else | Via `write-skill` | Via `write-eval` |
|
||||
|
||||
Step 3 (`write-docs`) is the first real factory output — `write-skill` authors its own SKILL.md.
|
||||
|
||||
---
|
||||
|
||||
## Per-skill process
|
||||
|
||||
Every skill — new or refactor — follows this sequence. Sub-agents are the default for research and writing steps to keep the main context lean.
|
||||
|
||||
### Step 1 — Source discovery (sub-agent)
|
||||
|
||||
Spawn an Explore agent to:
|
||||
- Check the issue and skills index for listed upstream sources
|
||||
- Web search for additional sources not already listed
|
||||
- For refactors: retrieve the current SKILL.md as one of the inputs
|
||||
|
||||
Return: list of sources with repo slugs and current HEAD commit SHAs.
|
||||
|
||||
### Step 2 — Source review (sub-agent)
|
||||
|
||||
Spawn a research agent to read each source and extract relevant content. The agent must:
|
||||
- Read relevant files from each upstream source
|
||||
- Note the commit SHA at time of review
|
||||
- Flag any changes since the last `updated:` date (for skills with an existing `source:` field)
|
||||
- Apply the pull criteria below to recommend whether to incorporate each change
|
||||
- Run a licence check: note the licence of each upstream repo; flag any copyleft (GPL, AGPL) material before adoption
|
||||
- Flag any third-party skill files that appear unreviewed or have unusual structure (documented 36% prompt injection rate in community skill sets — treat unreviewed upstream skills as untrusted)
|
||||
|
||||
Return: extracted content per source, commit SHAs, licence notes, security flags.
|
||||
|
||||
**Pull criteria:**
|
||||
|
||||
| Change type | Action |
|
||||
|---|---|
|
||||
| Trigger description or process sections changed | Always pull |
|
||||
| New constraints or failure-handling cases added | Evaluate — pull if it closes a real gap |
|
||||
| Formatting, wording, minor structural changes | Skip |
|
||||
| Any upstream reviewed (pull or skip) | Update `updated:` date in `source:` regardless |
|
||||
|
||||
### Step 3 — Conflict check (sub-agent)
|
||||
|
||||
Spawn an agent to cross-check the extracted upstream content against:
|
||||
- `core/instructions/governance.md` — hard prohibitions, data classification, HITL requirements
|
||||
- `docs/ai-constitution.md` — scope discipline, deterministic execution preference, licence obligations, output volume constraint, transparency requirements
|
||||
|
||||
The agent flags conflicts and tensions as numbered items for the synthesis grill. It does **not** resolve them — that is the grill's job.
|
||||
|
||||
Common conflicts to check:
|
||||
- Does any upstream pattern require the agent to take irreversible action without HITL? Flag.
|
||||
- Does any adopted content handle Restricted-tier data (credentials, health data)? Flag.
|
||||
- Does any upstream skip licence scanning before code commit? Flag.
|
||||
- Does any upstream encourage repeated AI inference for a deterministic task? Flag — note deterministic execution preference.
|
||||
- Does the upstream skill body exceed 500 lines or load excessive context at startup? Flag — note token architecture constraint.
|
||||
|
||||
Return: numbered conflict/tension list, or "no conflicts found."
|
||||
|
||||
### Step 4 — Synthesis grill
|
||||
|
||||
Short grill session with the human covering:
|
||||
- How to combine elements from the upstreams (what to take from each, what to leave)
|
||||
- How to resolve any flagged conflicts from step 3
|
||||
- Any open design questions specific to this skill
|
||||
|
||||
This is not a full grill-with-docs session — it is focused and bounded. If there are no conflicts and the combining decision is obvious, the grill can be a single confirmation exchange.
|
||||
|
||||
### Step 5 — Co-write iteratively
|
||||
|
||||
Work through the following in order, iterating with the human. Sub-agents handle writing tasks where context accumulation is a risk.
|
||||
|
||||
**a. Trigger description**
|
||||
Write the `description:` frontmatter field first. Test it against three cases before writing the body:
|
||||
1. Explicit invocation — user says the trigger phrase directly
|
||||
2. Implicit invocation — user describes the task without the trigger phrase
|
||||
3. Negative case — adjacent task that must NOT activate this skill
|
||||
|
||||
Do not proceed to the body until all three pass.
|
||||
|
||||
**b. SKILL.md** (sub-agent)
|
||||
Spawn a write agent to produce the SKILL.md using `write-skill` (or hand-write for bootstrap skills). The agent receives: trigger description, synthesis grill decisions, upstream content to incorporate, authoring standard (see below).
|
||||
|
||||
**c. `source:` and `references:` fields**
|
||||
Populate after upstream review. Two distinct fields:
|
||||
- `source:` — upstream provenance tracking (repo slug, commit SHA, files adopted with inline comments, updated date). Present only if content was adopted. Absence = self-authored.
|
||||
- `references:` — general citations (research papers, documentation, standard specifications). Present only if the skill cites external research.
|
||||
|
||||
**d. eval.yaml** (sub-agent)
|
||||
Spawn an agent to produce the eval via `write-eval`. Co-located at `.agents/evals/<category>/<skill-name>/eval.yaml`. Must contain all five required test types (see Eval schema below).
|
||||
|
||||
**e. HITL behavioral test**
|
||||
Human opens a fresh Claude session, invokes the skill with its trigger phrase, and verifies output. Do not batch more than 2–3 skills before running behavioral tests — output volume must stay within genuine human review capacity. An approval that cannot be meaningfully evaluated is not an approval.
|
||||
|
||||
### Step 6 — Session handoff
|
||||
|
||||
After the behavioral test passes, close the skill session by appending a `## Handoff` section to the skill's issue file. This is the entry point for the next session — write it assuming zero shared context.
|
||||
|
||||
```markdown
|
||||
## Handoff
|
||||
|
||||
**Status:** complete
|
||||
**Files produced:**
|
||||
- `.agents/skills/<name>/SKILL.md`
|
||||
- `.agents/evals/<category>/<name>/eval.yaml`
|
||||
|
||||
**Key decisions:**
|
||||
- <any non-obvious choices made during synthesis or co-write — if obvious from the files, omit>
|
||||
|
||||
**Open threads:**
|
||||
- <deferred items, follow-on issues, or unresolved tensions — if none, write "none">
|
||||
|
||||
**Next session start:**
|
||||
- Load: `CONTEXT.md`, `docs/notes/skill-implementation-workflow.md`, next skill's issue file
|
||||
- First action: Step 1 (source discovery) for `<next-skill-name>`
|
||||
```
|
||||
|
||||
If this skill produced a cross-cutting observation — a pattern that appeared across two or more skills — add an entry to `LESSONS.md` now. Do not batch LESSONS.md updates to the end of the chunk; they lose precision.
|
||||
|
||||
---
|
||||
|
||||
## Authoring standard
|
||||
|
||||
### Frontmatter (required)
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: skill-name
|
||||
description: <trigger description — written and tested first>
|
||||
version: "1.0"
|
||||
updated: YYYY-MM-DD
|
||||
when: <when this skill is invoked — e.g. "invoked by /skill-name trigger">
|
||||
metadata:
|
||||
category: <design|factory|implement|test|review|deploy|operate|cross-cutting|iac>
|
||||
source: # omit entirely if self-authored
|
||||
- repo: org/repo
|
||||
commit: abc1234
|
||||
files:
|
||||
- path/to/file.md # inline comment: what was taken
|
||||
updated: YYYY-MM-DD
|
||||
references: # omit if no external citations
|
||||
- <URL or citation>
|
||||
---
|
||||
```
|
||||
|
||||
`when:` is added to all Chunk 3 skills now; full bidirectional reference convention (reverse map, reference scanner) is deferred to Chunk 4 for refinement.
|
||||
|
||||
`allowed-tools:` — optional field to restrict which tools the skill may invoke. Reduces token cost of tool definitions. Add when the skill has a narrow, well-defined tool surface.
|
||||
|
||||
### Body sections (required, in this order)
|
||||
|
||||
1. **Role** — one sentence: who the agent is when this skill is active
|
||||
2. **When to use / When not to use** — explicit inclusion and exclusion criteria; negative cases are as important as positive
|
||||
3. **Required inputs** — what must be present before the skill proceeds
|
||||
4. **Constraints** — non-negotiable rules; the highest-ROI section for preventing over-engineering
|
||||
5. **Process** — numbered steps (not bullets)
|
||||
6. **Output format** — exactly what the skill produces; structured if downstream workflow steps depend on it
|
||||
7. **Failure handling** — what to return if inputs are missing or a step fails; never silent failure
|
||||
8. **Self-check** — skill-specific correctness criteria the agent verifies before responding; must be concrete, not generic
|
||||
|
||||
**Size:** body ≤500 lines. Use XML tags only for skills with ≥3 logical sections and 500+ tokens; default to prose.
|
||||
|
||||
### Refactor conventions
|
||||
|
||||
When refactoring an existing Pocock placeholder skill:
|
||||
- The existing SKILL.md is one input to step 2 (source review)
|
||||
- Use `write-skill` to produce the new SKILL.md — do not edit the old one in place
|
||||
- Remove all dead references: `setup-matt-pocock-skills`, `AGENT-BRIEF.md`, `OUT-OF-SCOPE.md`
|
||||
- Populate `source:` with the Pocock repo entry plus any other upstreams adopted
|
||||
- Flat skill name may change (e.g. `grill-with-docs` → `grill-me`) — delete old directory, create new
|
||||
|
||||
---
|
||||
|
||||
## Eval schema
|
||||
|
||||
**Location:** `.agents/evals/<category>/<skill-name>/eval.yaml` — committed to the repo.
|
||||
**Enforcement:** CI gates are Chunk 6. The files document expected behaviour before then.
|
||||
|
||||
Every eval must contain all five required test types:
|
||||
|
||||
| Type | Minimum count | Purpose |
|
||||
|---|---|---|
|
||||
| Explicit trigger test | ≥1 | User says the exact trigger phrase — skill must activate |
|
||||
| Implicit trigger test | ≥1 | User describes the task without trigger phrase — skill must activate |
|
||||
| Negative trigger test | ≥1 | Adjacent task that must NOT activate this skill |
|
||||
| Deterministic output test | ≥2 | Schema/contains/regex assertions — blocking gates |
|
||||
| LLM-rubric quality test | ≥1 | Quality catches that deterministic assertions cannot capture |
|
||||
|
||||
Three eval categories (align language when writing evals):
|
||||
- **Trigger evals** — does the description field activate correctly?
|
||||
- **Output evals** — is the structured output correct and high-quality?
|
||||
- **Regression evals** — did a model update break established behaviour? (run weekly in CI, Chunk 6)
|
||||
|
||||
When a human corrects a skill's output, that correction becomes a new eval test case. The eval suite grows from real failures.
|
||||
|
||||
---
|
||||
|
||||
## `source:` pull criteria (upstream review, per-skill)
|
||||
|
||||
Upstream review happens per-skill during step 2, not once at chunk start.
|
||||
|
||||
| Change type | Action |
|
||||
|---|---|
|
||||
| Trigger description or process sections changed | Always pull |
|
||||
| New constraints or failure-handling cases added | Evaluate — pull if it closes a real gap |
|
||||
| Formatting, wording, minor structural changes | Skip |
|
||||
| Any upstream reviewed (pull or skip) | Update `updated:` date in `source:` |
|
||||
|
||||
---
|
||||
|
||||
## Open decisions carried forward
|
||||
|
||||
- **`when:` full resolution** — Chunk 4 (bidirectional reference convention, reference scanner tooling)
|
||||
- **PRD/issue template scope** — refined during `write-prd` (0020) and `write-issue-spec` (0019) implementation
|
||||
- **Merging `zoom-out` into architect role** — revisit at Chunk 5 grill
|
||||
@@ -1,6 +1,6 @@
|
||||
# PRD: Chunk 3 — Skills Library Rebuild
|
||||
|
||||
**Status:** Ready for issues
|
||||
**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
|
||||
|
||||
@@ -86,10 +86,10 @@ source:
|
||||
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.
|
||||
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. 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.
|
||||
`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.
|
||||
@@ -123,7 +123,7 @@ Phase axis: `design`, `factory`, `implement`, `test`, `review`, `deploy`, `opera
|
||||
| `implement-feature` | `implement/implement-feature` | New |
|
||||
| `tdd` | `implement/tdd` | Preserved; frontmatter + standard added |
|
||||
| `refactor` | `implement/refactor` | New |
|
||||
| `write-docs` | `implement/write-docs` | 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.
|
||||
@@ -173,7 +173,10 @@ Issues contain: link to parent PRD (inherited why), EARS acceptance criteria, br
|
||||
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.
|
||||
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).
|
||||
|
||||
@@ -13,7 +13,7 @@ Current skills: `caveman`, `diagnose`, `grill-me`, `grill-with-docs`, `improve-c
|
||||
|
||||
**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).
|
||||
**Skill implementation workflow:** each skill follows the per-skill process in `docs/notes/skill-implementation-workflow.md` (produced by issue 0016). Sub-agents handle source discovery, source review, and conflict checking; synthesis grill and HITL test are human steps. Bootstrap: write-eval (hand-written) → write-skill (hand-written) → write-docs (first factory-authored) → all others via factory.
|
||||
|
||||
### Claude Code configuration
|
||||
- `~/.claude/CLAUDE.md` — thin adapter; imports `~/.agents/AGENTS.md` (Communication + Behavior) and `governance.md`; content index pointers only
|
||||
@@ -42,6 +42,7 @@ For chunk planning and open questions, see `docs/ROADMAP.md`.
|
||||
|
||||
## Recent changes
|
||||
|
||||
- 2026-05-17 — Issue 0016 complete: skill implementation workflow grill completed. `docs/notes/skill-implementation-workflow.md` written. All issues 0017–0028 updated with specific acceptance criteria. Key conventions: sub-agents prescribed at each research/writing step; conflict check against constitution + factory principles before synthesis grill; `when:` and `references:` fields added to authoring standard; write-docs moved to issue 0018 phase 2 (first factory-authored skill).
|
||||
- 2026-05-17 — Issue 0015 complete: AGENTS.md refactor implemented. Two AGENTS.md files created (`AGENTS.md` at repo root, `core/AGENTS.md` deployed to `~/.agents/AGENTS.md`). Both CLAUDE.md files slimmed to thin adapters. `deploy-manifest.sh` updated. `docs/spec/architecture.md` updated with new structure. ADR-0012 in effect.
|
||||
- 2026-05-17 — Chunk 3 issues created (0015–0028): AGENTS.md refactor prerequisite, skill workflow grill, bootstrap skills (write-eval, write-skill), factory/design/implement/test/review/deploy/operate/IaC/cross-cutting skill groups, chunk closure; all HITL; acceptance criteria for 0017–0028 to be refined after issue 0016 grill session
|
||||
- 2026-05-17 — behavioral tests fully resolved: `CONTEXT.md` now always-loaded via `@import` in repo `CLAUDE.md`; standing rule added to check `docs/adr/` and ROADMAP resolved entries before answering design questions; communication/behavior and secrets rules tightened; Chunk 2 and Governance Phase 1 ✅ complete
|
||||
|
||||
Reference in New Issue
Block a user