Skip to content

Commit cfc0bf1

Browse files
docs(specops): adopt latest skill's CLAUDE.md hook + plan conventions
The specops skill update (5312a63) restructured its setup guidance: the project CLAUDE.md should carry a minimal "hook" block that counteracts the default agent reflexes (ship code without a spec; drop into built-in plan mode) and routes to the skill, rather than restating the full protocol. - Replace the verbose 7-step "Feature workflow" with the recommended "Spec-driven development (specops)" hook block: specs lead, plans/ is the planning system (not built-in plan mode), when-to-author-a-plan by intent, and spec-change-ripples-to-plans. Project-specific mechanics (branch naming, validation gate, merge rule) kept as a short tail. - Point the specops CLI invocations at the vendored .agents/skills/specops. - Update the skills-update command to `npx skills update`. - Fix stale links in plans/README.md: the renamed CLAUDE.md section anchor, and the plans-protocol reference now that specops ships from its own repo and is vendored locally (incl. the new proposal-plans/awaits guidance). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 5312a63 commit cfc0bf1

2 files changed

Lines changed: 33 additions & 16 deletions

File tree

‎.claude/CLAUDE.md‎

Lines changed: 31 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -12,25 +12,42 @@ These auto-trigger by topic — you don't load them manually. Mentioned here so
1212
| [`backend-fastify`](./skills/backend-fastify/SKILL.md) | New routes, services, plugins, env vars | Fastify 5 patterns, plugin ordering, `@fastify/env` validation, error handling |
1313
| [`frontend-shadcn`](./skills/frontend-shadcn/SKILL.md) | New screens, components, routing, styling | Vite + React 19 + shadcn/ui + Tailwind v4 + React Router v7 patterns |
1414

15-
Skills are version-pinned via `skills-lock.json`. To update: `agent-skills` CLI.
15+
Skills are version-pinned via `skills-lock.json`. To update: `npx skills update`.
1616

1717
### Working laterally on the data repo
1818

1919
When you `cd` into a clone of [`CodeForPhilly/codeforphilly-data`](https://github.com/CodeForPhilly/codeforphilly-data) (typically a sibling — see [Local setup](#local-setup) below), **read its `.claude/CLAUDE.md` first** — that repo has its own conventions and ships a `gitsheets` skill at `.claude/skills/gitsheets/` covering library use, transactions, path templates, indices. Don't write TOML records or shell out to git there by hand.
2020

21-
## Feature workflow
22-
23-
The shape of how features get built here — spec-driven, plans-tracked. The [`specops`](./skills/specops/SKILL.md) skill carries the full protocol (frontmatter schema, closeout ritual, Follow-ups taxonomy); this is the orientation map.
24-
25-
1. **Specs first** — propose what *should be true* in [`specs/`](../specs/). New behavior, new screen, new endpoint → write or update the relevant spec file. Get it reviewed. The spec is the source of truth, not the eventual code.
26-
2. **Write a plan** — `plans/<slug>.md`, `status: planned`. Frontmatter declares deps + which specs the plan implements. Body has Scope / Implements / Approach / Validation (checklist) / Risks / Notes / Follow-ups.
27-
3. **Open the plan** — flip `status: planned → in-progress`, branch off `main` (`feat/<slug>`, `fix/<slug>`, `chore/<slug>`). The plan is now the working contract for the branch.
28-
4. **Implement** — bring code into conformance with the specs the plan lists. `backend-fastify` / `frontend-shadcn` skills cover per-layer patterns. If the spec turns out wrong, *fix the spec first* — don't code around it.
29-
5. **Validate** — tick each Validation checkbox as you confirm it. Browser-test UI; spec-conformance check non-trivial features. `npm run type-check && npm run lint && npm test` clean.
30-
6. **Closeout commit** — flip `status: in-progress → done`, fill **Notes** (what shipped, surprises, deferred trade-offs) and **Follow-ups** using the Issue / Deferred to plan / Tracked as / None taxonomy from the specops skill. This is the last commit on the branch.
31-
7. **PR** — conventional subject ≤72 chars, body explains *why*. Rebase locally onto `main` before `gh pr merge --merge` (never `--rebase` / `--squash` — see [Source control](#source-control)).
32-
33-
For tiny fixes (typo, one-line bug) where writing a plan would be more ceremony than the change is worth, skip steps 2–3, 6 and go straight to a PR. Anything that touches behavior, schema, or a new file should go through the full loop.
21+
## Spec-driven development (specops)
22+
23+
This project uses spec-driven development. [`specs/`](../specs/) is the source of truth for what
24+
*should be true*; [`plans/`](../plans/) is the work-in-flight DAG that bridges specs to merged code.
25+
The **specops** skill carries the full methodology — invoke it (the skill triggers on
26+
"spec", "plan", starting a feature, etc.) before writing specs, planning, or building.
27+
28+
- **Specs lead.** Before changing behavior, change the spec; bring code into conformance
29+
after. Spec↔code drift is a bug, not debt. If a spec turns out wrong mid-plan, fix the
30+
spec in its own PR first — don't code around it.
31+
- **`plans/` is the planning system — not your built-in plan mode.** Every chunk of work
32+
lands as a file in `plans/` that freezes to `done` as the durable record of what got
33+
built. Don't let an ephemeral plan substitute for it, and don't skip it for "small"
34+
changes. (Classic trap: an ad-hoc plan of "write spec X, then build it" that ends with
35+
neither a reviewed spec nor a plan file — split those into the two real artifacts.)
36+
- **When to author a plan depends on intent:** mapping out a batch of specs → finish the
37+
batch first, then propose a *set* of plans; speccing one bounded feature in a mature
38+
project → draft the spec change and its plan in tandem; intent unclear → ask. The skill
39+
details each mode.
40+
- **A spec change ripples to its plans.** After editing a spec, review the plans that
41+
implement it (`grep -l '<spec-path>' plans/*.md`) and offer to update them.
42+
43+
This repo's mechanics: branch off `main` (`feat/<slug>`, `fix/<slug>`, `chore/<slug>`);
44+
validation gate is `npm run type-check && npm run lint && npm test` clean plus a browser
45+
test for UI; closeout + PR follow [Source control](#source-control) (rebase locally, then
46+
`gh pr merge --merge`).
47+
48+
Query the DAG: `.agents/skills/specops/scripts/specops next` (what to work on next) and
49+
`.agents/skills/specops/scripts/specops dag` (graph). Run `/audit-spec-drift` to compare
50+
specs against the implementation.
3451

3552
## Three repos in this project
3653

‎plans/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ If `specs/` is the architecture document, `plans/` is the project plan.
66

77
## Workflow
88

9-
Documented in [`.claude/CLAUDE.md`](../.claude/CLAUDE.md#plans). Briefly:
9+
Documented in [`.claude/CLAUDE.md`](../.claude/CLAUDE.md#spec-driven-development-specops) and, in full, the vendored [`specops` plans protocol](../.agents/skills/specops/references/plans-protocol.md). Briefly:
1010

1111
1. Add a plan to start new work. `status: planned` and `depends:` set.
1212
2. Move to `in-progress` when starting, as the first commit on the branch (`chore(plans): mark <slug> in-progress`). Skippable for tiny plans.
@@ -20,7 +20,7 @@ Per-plan frontmatter is the source of truth for both **status** (`status:`) and
2020
- To find what's in flight: `grep -l '^status: in-progress' plans/*.md`
2121
- To find what's done: same, with `done`
2222
- To trace dependencies: `grep '^depends:' plans/*.md` or read the plan whose name you care about
23-
- External blockers (`awaits:` field) are surfaced by `plans-next` in their own "Awaiting external" section — see [the plans protocol's External blockers section](https://github.com/JarvusInnovations/agent-skills/blob/main/skills/specops/references/plans-protocol.md#external-blockers)
23+
- External blockers (`awaits:` field) are surfaced by `specops next` in their own "awaiting" section — see [the plans protocol's External blockers section](../.agents/skills/specops/references/plans-protocol.md#external-blockers-awaits). Decision/contract deliverables that can't be built until a downstream party acts are [proposal plans](../.agents/skills/specops/references/plans-protocol.md#proposal-plans) (`status: blocked` + `awaits:`).
2424

2525
## What plans are NOT
2626

0 commit comments

Comments
 (0)