diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 4cc8c0d..d37777d 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -60,6 +60,8 @@ specs: # spec files in THIS repo that this plan implements upstream-specs: # (optional) specs in OTHER repos this plan consumes - gitsheets:specs/behaviors/transactions.md - gitsheets:specs/api/errors.md +awaits: # (optional) external blockers — releases, decisions, deliveries + - "JarvusInnovations/gitsheets@v1.0 — Repository / Sheet / openStore API" issues: [128, 129] # related GitHub issues (optional) pr: 42 # merged PR once done (optional) --- @@ -67,6 +69,8 @@ pr: 42 # merged PR once done (optional) `specs:` is for specs we own — the spec-drift-auditor matches them against implementation. `upstream-specs:` is for specs owned by dependencies (e.g., gitsheets) that this plan consumes; they're informational only and the spec-drift-auditor doesn't check them. Use the `:` form so it's obvious where to look. +`awaits:` captures external blockers — upstream library releases, vendor deliveries, partner decisions. Each entry is a one-line free-form pointer (URL, `repo@tag`, "vendor X delivery", etc., with a trailing em-dash clause for the *why* so the entry self-explains when grep surfaces it). The three structural fields (`depends:`, `upstream-specs:`, `awaits:`) are **orthogonal axes**, not mutually exclusive categories — the same upstream relationship can carry multiple. The example above is the canonical case: gitsheets appears in `upstream-specs:` (the specs we'll implement against) *and* in `awaits:` (the v1.0 release we're waiting for). Different axes of the same upstream. `awaits:` is also independent of `status:`: a `planned` plan can carry `awaits:` from day one; a `blocked` plan should always have `awaits:` populated to say why (the scripts warn if `status: blocked` is set with neither `awaits:` nor unfinished `depends:`). Resolution is just deleting the entry when the awaited thing happens. `plans-next` never lists a plan with non-empty `awaits:` under "Ready" — it surfaces in an "Awaiting external" section. Full convention: [`agent-skills/skills/specops/references/plans-protocol.md`](https://github.com/JarvusInnovations/agent-skills/blob/main/skills/specops/references/plans-protocol.md#external-blockers). + A plan's body follows the template in [plans/README.md](../plans/README.md): Scope, Implements, Approach, Validation, Risks/unknowns, Notes, Follow-ups. The Validation section is the load-bearing part — it converts "in-progress" to "done." **Plans are not specs.** They're project-management artifacts. Plans rot fast — once a plan is `done`, it's a historical record; don't keep editing it. The `spec-drift-auditor` reads `specs/`, not `plans/`. diff --git a/plans/README.md b/plans/README.md index 950a670..37f75fb 100644 --- a/plans/README.md +++ b/plans/README.md @@ -20,6 +20,7 @@ Per-plan frontmatter is the source of truth for both **status** (`status:`) and - To find what's in flight: `grep -l '^status: in-progress' plans/*.md` - To find what's done: same, with `done` - To trace dependencies: `grep '^depends:' plans/*.md` or read the plan whose name you care about +- 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) ## What plans are NOT diff --git a/plans/storage-foundation.md b/plans/storage-foundation.md index fe7f62e..22c6e51 100644 --- a/plans/storage-foundation.md +++ b/plans/storage-foundation.md @@ -13,6 +13,8 @@ upstream-specs: - gitsheets:specs/behaviors/transactions.md - gitsheets:specs/behaviors/validation.md - gitsheets:specs/behaviors/normalization.md +awaits: + - "JarvusInnovations/gitsheets@v1.0 — consumed via Repository / Sheet / openStore TypeScript API (https://github.com/JarvusInnovations/gitsheets/milestone/1)" issues: [] ---