From aa3351a22d1058f8a4af7614d0ba97af4bed1b06 Mon Sep 17 00:00:00 2001 From: Chris Alfano Date: Sat, 16 May 2026 12:19:24 -0400 Subject: [PATCH 1/3] docs(plans): adopt awaits: field for external blockers Mirrors the awaits: field convention introduced upstream in JarvusInnovations/agent-skills#9. The canonical protocol lives in that skill's references/plans-protocol.md; this file just summarizes for in-repo readers and points at it. .claude/CLAUDE.md: * Frontmatter example gains the awaits: block alongside upstream-specs:. * Adds a paragraph explaining the field's semantics, lifecycle relationship to status (orthogonal), and resolution (deletion). Notes that plans-next surfaces non-empty awaits in its own "Awaiting external" section. plans/README.md: * Adds a bullet to the discovery list explaining where awaits shows up in plans-next output. storage-foundation.md picks up its concrete awaits: entry in the following commit. Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/CLAUDE.md | 4 ++++ plans/README.md | 1 + 2 files changed, 5 insertions(+) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 4cc8c0d..1cfdde7 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 that aren't represented by an in-repo plan or an upstream spec — upstream library releases, vendor deliveries, partner decisions. Each entry is a one-line free-form pointer (URL, `repo@tag`, "vendor X delivery", etc.). `awaits:` is structural ("we're waiting on this"); `status:` is lifecycle ("can the plan move?"). They're independent: a `planned` plan can carry `awaits:` from day one, a `blocked` plan should always have `awaits:` populated to say why. 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 From 6d0078fa99ea6ff0b4885663eace899bda696c4f Mon Sep 17 00:00:00 2001 From: Chris Alfano Date: Sat, 16 May 2026 12:20:06 -0400 Subject: [PATCH 2/3] chore(plans): declare storage-foundation awaits gitsheets v1.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plan's Scope already says "Assumes gitsheets v1.0 has shipped" in prose, but until now that block lived only in the body — invisible to plans-next, ungreppable, and at risk of being lost when the plan freezes. Adopting the awaits: field (introduced in the preceding commit and upstream in agent-skills#9) captures the structural fact: awaits: - "JarvusInnovations/gitsheets@v1.0 — consumed via Repository / Sheet / openStore TypeScript API (https://github.com/JarvusInnovations/gitsheets/milestone/1)" The Scope prose stays — it has more context than the YAML line. `plans-next plans/` now surfaces storage-foundation under "Awaiting external" with the entry visible, alongside the test-harness [planned] dep callout. plans-dag will overlay a dashed border on the storage-foundation node once both this PR and the upstream agent-skills#9 are merged. Resolution: delete the awaits: entry from this file once gitsheets v1.0 ships and the consumer-side code in this plan can actually start. Co-Authored-By: Claude Opus 4.7 (1M context) --- plans/storage-foundation.md | 2 ++ 1 file changed, 2 insertions(+) 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: [] --- From 8481260e500037233bb17f213d64ab767abe8037 Mon Sep 17 00:00:00 2001 From: Chris Alfano Date: Sat, 16 May 2026 12:44:05 -0400 Subject: [PATCH 3/3] docs(plans): align awaits prose with merged agent-skills convention MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The PR's original prose framed awaits: as for "external blockers that aren't represented by an in-repo plan or an upstream spec" — the same mutually-exclusive misreading caught and fixed by review on the upstream agent-skills PR (JarvusInnovations/agent-skills#9, merged). Our storage-foundation.md is literally the canonical counterexample: gitsheets shows up in BOTH upstream-specs: (the specs we'll implement against) AND awaits: (the v1.0 release we're waiting for). Different axes of the same upstream — not exclusive categories. Rewrite the paragraph to: * Call out orthogonality of depends / upstream-specs / awaits explicitly * Use the storage-foundation frontmatter example shown immediately above (gitsheets in both fields) as the worked illustration * Add the "trailing em-dash clause for the why" guidance that matches the upstream protocol's recommendation * Note the new smell warning (plans-next/dag warn when status: blocked has neither awaits: nor unfinished depends:) so readers know the smell isn't just rhetorical Co-Authored-By: Claude Opus 4.7 (1M context) --- .claude/CLAUDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 1cfdde7..d37777d 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -69,7 +69,7 @@ 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 that aren't represented by an in-repo plan or an upstream spec — upstream library releases, vendor deliveries, partner decisions. Each entry is a one-line free-form pointer (URL, `repo@tag`, "vendor X delivery", etc.). `awaits:` is structural ("we're waiting on this"); `status:` is lifecycle ("can the plan move?"). They're independent: a `planned` plan can carry `awaits:` from day one, a `blocked` plan should always have `awaits:` populated to say why. 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). +`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."