docs: adopt spec/ADR/plan lifecycle + prune coded plans#80
Merged
Conversation
Adopt an explicit documentation lifecycle and directory convention: - docs/specs/ — committed, point-in-time design docs (what & why) - docs/adrs/ — committed, permanent, immutable decision records - docs/plans/ — local-only, gitignored implementation checklists Code is the source of truth for *how*; the durable value of docs is the *why*. Plans go stale the moment code merges, so they are local-only. Changes: - Add docs/adrs/ (README + ADR template: Context/Decision/Consequences/Status). - Document the lifecycle and a Status vocabulary (Proposed → Accepted → Implemented → Superseded by <link>) in docs/specs/README.md. - Gitignore docs/plans/ (keep its README so the dir stays discoverable); repoint the writing-plans destination to docs/plans/. - Remove all 17 now-merged plans from docs/superpowers/plans/ and the now-empty docs/superpowers/ tree; the matching specs carry the why. Merge status confirmed against history — the three "verify before deleting" plans landed via PRs #5 (m7 cluster experiments), #14/#15 (human-gate), and #16 (registry hardening hygiene). Closes #79 Assisted-By: Claude (Anthropic AI) <noreply@anthropic.com> Signed-off-by: Paolo Dettori <dettori@us.ibm.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.
Summary
Adopts an explicit documentation lifecycle + directory convention for the harness and prunes plans whose work has already merged. No runtime code changes — docs/convention only.
Three artifact types, three lifecycles:
Superseded by …, not deleteddocs/specs/docs/adrs/docs/plans/(gitignored)Rationale: code is the source of truth for how; the durable value of docs is the why.
Changes
docs/adrs/— newREADME.md(purpose, immutability, supersession) +0000-adr-template.md(Context / Decision / Consequences / Status).docs/specs/README.md— new Documentation lifecycle section + Status vocabulary (Proposed → Accepted → Implemented → Superseded by <link>); writing-plans destination repointed fromdocs/superpowers/plans/→docs/plans/.docs/plans/— newREADME.md; gitignored viadocs/plans/*+!docs/plans/README.md(dir stays discoverable, plan files stay local).docs/superpowers/plans/and the now-emptydocs/superpowers/tree.docs/superpowers/specs/was already migrated todocs/specs/in docs: SandboxTransport remote-exec design (language-neutral gRPC) #78.Plan audit
All 17 plans are confirmed merged, so all were deleted (none needed relocating). The issue's three "verify before deleting" items were checked against merge history and all found merged:
m7-cluster-experiments→ PR feat(knative): M7 cluster experiments — E1 economics + E3 mobility + E4 recovery #5human-gate→ PR Add human-gate (gate-while-idle, Archetype B) to the leaf-session backend #14 / Address human-gate (#14) review follow-ups #15registry-hardening-hygiene→ PR Registry + securityContext hardening hygiene (post-archetype consolidation) #16The remaining 14 match the issue's confirmed-merged list. Each plan's durable why is preserved in its matching spec under
docs/specs/.Closes #79
Assisted-By: Claude Code