You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit cfc0bf1
Browse filesBrowse the repository at this point in the historyBrowse 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>
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`.
16
16
17
17
### Working laterally on the data repo
18
18
19
19
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.
20
20
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
Copy file name to clipboardExpand all lines: plans/README.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,7 @@ If `specs/` is the architecture document, `plans/` is the project plan.
6
6
7
7
## Workflow
8
8
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:
10
10
11
11
1. Add a plan to start new work. `status: planned` and `depends:` set.
12
12
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
20
20
- To find what's in flight: `grep -l '^status: in-progress' plans/*.md`
21
21
- To find what's done: same, with `done`
22
22
- 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:`).
0 commit comments