Moved the shipped iteration specs into docs/specs/completed and made the drafts to completed layout part of the rules, skills and doc links - #25
Merged
Conversation
…the drafts to completed layout part of the rules, skills and doc links
There was a problem hiding this comment.
Pull request overview
Moves shipped iteration specs into a dedicated docs/specs/completed/ folder and updates the repo’s documentation + agent skills so the “drafts → completed” lifecycle is part of the documented workflow (no runtime/extension behavior changes).
Changes:
- Relocated shipped specs
001–013intodocs/specs/completed/and updated their header links to../../Architecture.md/../../Features.md. - Updated canonical docs (
README.md,CONTRIBUTING.md,docs/Architecture.md,CLAUDE.md) to reference the new specs layout. - Updated relevant
.claude/skills/*procedures to reflect drafting indocs/specs/drafts/and shipping via move todocs/specs/completed/.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Updates “Iteration specs” link to the new location. |
| docs/specs/completed/013 - Visible And Cancellable Operations.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/012 - Create Before Attach.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/011 - Fresh Image Rebuild.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/010 - Marketplace Release.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/009 - Read-Only Discovery.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/008 - Lifecycle Progress Feedback.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/007 - Generated Project CLI.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/006 - Per-Project Secret Cache.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/005 - Dockerfile Base And Reuse.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/004 - Default Sandbox Picker.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/003 - Open-Source Readiness.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/002 - Managed Sandbox UI.md | Fixes canonical-doc header links for new folder depth. |
| docs/specs/completed/001 - Walking Skeleton.md | Fixes canonical-doc header links for new folder depth. |
| docs/Architecture.md | Updates the spec reference link to specs/completed/001 .... |
| CONTRIBUTING.md | Documents drafts vs completed spec lifecycle + continuous numbering. |
| CLAUDE.md | Updates the documentation model to describe drafts/ → completed/. |
| .claude/skills/spec-new-iteration/SKILL.md | Updates spec numbering and draft location guidance for the new layout. |
| .claude/skills/spec-implement/SKILL.md | Updates “ship” step to include moving the spec into completed/ and fixing links. |
| .claude/skills/dev-review-changes/SKILL.md | Updates docs-drift checklist to require both “shipped” status and the move to completed/. |
| .claude/skills/dev-onboard/SKILL.md | Updates “where truth lives” to point at completed/ (history) vs drafts/ (WIP). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - [Features](https://github.com/ainova-systems/code-sandbox-console/blob/main/docs/Features.md) | ||
| and [Architecture](https://github.com/ainova-systems/code-sandbox-console/blob/main/docs/Architecture.md) | ||
| - [Iteration specs](https://github.com/ainova-systems/code-sandbox-console/tree/main/docs/specs) | ||
| - [Iteration specs](https://github.com/ainova-systems/code-sandbox-console/tree/main/docs/specs/completed) |
| @@ -17,9 +17,11 @@ Two canonical docs are **always current**; history lives in append-only specs: | |||
| - `docs/Architecture.md` — the **technical truth** — read it before changing backend | |||
| behaviour. | |||
| - `docs/specs/00N - <Iteration>.md` — one numbered spec per substantial change: what | |||
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
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.
Risk & Size
Risk: Low
Size: Large
What & Why
Documentation and process only, no runtime behaviour: the thirteen shipped iteration specs
(001-013, all
Status: shipped with this iteration) moved out of the flatdocs/specs/root into
docs/specs/completed/, sodocs/specs/now separates history (completed/)from work in flight (
drafts/, which already held the planned 014). The rules and skillsthat create, flip and review a spec now carry that layout, so the folder does not drift back.
Changes
git mvof specs 001-013 intodocs/specs/completed/; their../Architecture.md/../Features.mdheader links rewritten to../../for the new depth (the samealready-broken links fixed in
drafts/014).CLAUDE.md: documentation model states thedrafts/->completed/layout withcontinuous numbering across both folders; flow step 1 drafts into
drafts/, step 4 flipsthe status and moves the file to
completed/in the same change.spec-new-iteration: next00Nis taken from both folders; the draft is written todocs/specs/drafts/; reference example points atcompleted/009.spec-implementstep 6: flipping the status now alsogit mvs the spec tocompleted/and fixes its relative doc links.
dev-review-changesdocs-drift check: verifies both the shipped status and the move.dev-onboard: "where truth lives" points atcompleted/for history,drafts/forwork in flight.
CONTRIBUTING.md,README.md("Iteration specs" link) anddocs/Architecture.md(specs/001 reference) updated to the new paths.
How to Verify
npm run verify— exits 0 (run on this branch before the commit).ls docs/specs— onlycompleted/anddrafts/;completed/holds 001-013,drafts/holds only the planned
014 - Truthful Recipe State.md.docs/specs/completed/001 - Walking Skeleton.mdanddocs/specs/drafts/014 - Truthful Recipe State.mdin a Markdown preview: the
../../Architecture.md/../../Features.mdheader links resolve.docs/Architecture.md§2 and follow thespecs/001link — it resolves todocs/specs/completed/001 - Walking Skeleton.md.