feat(plans): adopt awaits: field; declare storage-foundation awaits gitsheets v1.0#10
Merged
Merged
Conversation
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
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) <noreply@anthropic.com>
Member
Author
|
Update following the merge of JarvusInnovations/agent-skills#9: One drift item caught and fixed ( Nothing else needs syncing. Audited:
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adopts the new
awaits:frontmatter field — introduced upstream in JarvusInnovations/agent-skills#9 — for capturing external blockers (upstream library releases, vendor deliveries, partner decisions). Mirrors the convention in this repo's.claude/CLAUDE.md+plans/README.md, then applies the field toplans/storage-foundation.mdwhere the long-standing "Assumes gitsheets v1.0 has shipped" prose has lived in Scope.Two commits:
docs(plans): adopt awaits: field for external blockers— mirror the convention..claude/CLAUDE.mdfrontmatter example gains theawaits:block plus an explanatory paragraph (semantics, lifecycle orthogonality withstatus:, resolution rule, script behavior).plans/README.mdgains a single bullet pointing at the upstream protocol's "External blockers" section.chore(plans): declare storage-foundation awaits gitsheets v1.0— adds the concrete entry:The "Assumes gitsheets v1.0 has shipped" Scope prose stays — the YAML is structural; the prose has more context.
Why this matters
Before this PR,
plans-nextlistedstorage-foundationunder "Blocked by unfinished deps" with atest-harness [planned]callout — which is technically true (test-harness is in the DAG before storage-foundation) but misleading: the load-bearing blocker is gitsheets v1.0, an external upstream release. After this PR:Both blockers visible. A reader instantly knows what to track. And
git grep awaits.*gitsheets plans/answers "what's everything we're waiting on gitsheets for?" in a single command.Dependency on upstream PR
The
plans-nextandplans-dagbehavior described above requires agent-skills#9 — the script update that parsesawaits:and adds the "Awaiting external" section. Until that lands,awaits:here is a no-op for the scripts (still useful as greppable structural metadata; the cost is zero).Recommended merge order: agent-skills#9 first, then this. Not strictly required — this PR doesn't break anything if it lands first.
Test plan
<agent-skills>/skills/specops/scripts/plans-next plans/(with agent-skills#9 branch checked out locally) correctly surfacesstorage-foundationunder "Awaiting external" with both the⌛ gitsheets@v1.0entry and the↳ test-harness [planned]dep callout.<agent-skills>/skills/specops/scripts/plans-dag plans/emitsclass storage_foundation awaitsoverlaid onclass storage_foundation planned.🤖 Generated with Claude Code