Agent-friendly planning convention: validator + progressive disclosure + leaner frontmatter#236
Merged
Merged
Conversation
Progressive-disclosure restructure (Quick-path on-ramp, deterministic lane decision, de-duplicated text) plus a just check-planning validator. Findings 1, 2, 4, 5 from the agent-convenience evaluation. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ntion Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Backfill pr: on 8 shipped design.md files (bug-hunt-audit→188-197, singleton-rlock→188, validate-rework→189, mkdocs-github-pages-migration→198, scheduled-dep-check→200, code-docs-audit→202-203, docs-improvements→198, migration-guide-from-that-depends→198) - docs-improvements and migration-guide-from-that-depends: no dedicated merged PR found (gh pr list and git log show no separate PR); both shipped with the GitHub Pages migration PR #198 - Backfill outcome: on 7 shipped change.md files (audit-fixes, audit-fixes-round2, alias-scope-transparency, audit-doc-rulings-batch1, audit-fixes-batch2, audit-fixes-batch3, audit-fixes-batch4-5); each derived from its own summary/body, not invented - Fix spec: in 5 plan.md files to design.md (bundle-relative path) - Fix docs-ux-fixes/plan.md: add full missing frontmatter from sibling design.md - Fix planning/_templates/plan.md: spec: my-change → spec: design.md - Wire check-planning into lint-ci as final step
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
… field Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Multi-line block scalars (outcome: |) no longer let an indented line shaped like a key overwrite a real frontmatter field. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…nge bundles Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Decisions keep status/supersedes/superseded_by; changes do not. outcome is now required on every change spec; the index is a flat newest-first list. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Makes the portable planning convention agent-friendly: a machine-checkable validator, a progressive-disclosure on-ramp, and a much leaner frontmatter. Spec + plan:
planning/changes/2026-06-25.01-agent-friendly-planning-convention/.What ships
just check-planningvalidator — a--checkmode inplanning/index.py(reusesparse_frontmatter), wired intojust lint-ci. Validates bundle shape, required frontmatter keys, field validity,outcomepresence on every change spec, andplan.mdspec:link resolution. Reports all violations in one run. Not imported by tests, so the 100% coverage gate is unaffected (CLI-verified).planning/README.md— a first-match lane decision tree + create/ship steps. The full Conventions section stays as the authoritative reference;CLAUDE.md's## Workflowis de-duplicated down to a pointer (keeping only the repo-specific release process).Convention simplifications (decided during the work)
prdropped entirely — it was the only hand-supplied, post-hoc, git-recoverable field; traceability lives in git + theoutcomeline.status+supersedes/superseded_bydropped from change bundles — onmaina bundle is always shipped, so thedraft→shippedflip was pointless ceremony. The index is now a flat newest-first list. Decisions keepstatus+ supersession (load-bearing there).outcomeis now the sole enforced lifecycle field, with a written definition (one line, ~1–3 sentences, the realized result, filled at PR-finalize time).A change spec's frontmatter is now
date/slug/summary/outcome; aplan.md's isdate/slug/spec.spec:standardized to a bundle-relative path. Historical bundles reconciled to green.Verification
just check-planning→planning: OKjust test-ci→ 232 passed, 100% coveragejust lint-ci→ clean (includescheck-planning)just docs-build→ OKSibling-repo rollout (faststream-outbox et al.) is tracked in
planning/deferred.md.🤖 Generated with Claude Code