Add spec-driven development workflow to CONTRIBUTING.md #37
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting
| ### Folder Structure | ||
|
|
||
| - **`spec/<area>/proposals/XXX-name/`** - All proposals (status tracked in CHANGELOG) | ||
| - XXX = unique 3-character alphanumeric code (e.g., `a7z`, `k3p`, `m9w`) | ||
| - **`spec/<area>/rejected/XXX-name/`** - Rejected proposals (moved out of proposals/) | ||
| - **`spec/integration-plans/XXX-name.md`** - Implementation plans for complex changes | ||
| - XXX = unique 3-character alphanumeric code (e.g., `b4x`, `r8n`) | ||
|
|
||
| ### Core Documents | ||
|
|
||
| - **Proposals** - Design rationale, research, decisions (stay in `proposals/` permanently) | ||
| - **Main Specs** - Authoritative documentation (updated from proposals) | ||
| - **CHANGELOG.md** - Tracks status of all proposals (Draft → Needs Implementation → In Progress → Done → Released) | ||
| - **Implementation Plans** - Guides code development (optional, for complex changes) | ||
|
|
||
| ### Naming Convention | ||
|
|
||
| - Proposals and implementation plans use unique 3-character alphanumeric codes | ||
| - Format: `XXX-descriptive-name` (e.g., `a7z-message-batching`, `k3p-token-limits`, `m9w-new-feature`) |
There was a problem hiding this comment.
The new spec‑driven workflow tells contributors to place proposals in spec/<area>/proposals/XXX-name/, rejected items in spec/<area>/rejected/, and implementation plans in spec/integration-plans/XXX-name.md, and to name everything with random 3‑character codes. None of these directories or naming conventions exist in the repo today—the tree still uses spec/<area>/{proposed,accepted,rejected} and there is no spec/integration-plans folder. Following the current text will lead new contributors to create paths the build/test tooling does not reference. Please align the documentation with the actual structure (or land the structure change alongside the docs).
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Thanks, we'll do it the other way around by reorganizing the specs to fit this.
Summary
Reorganizes specification structure and updates CONTRIBUTING.md with comprehensive spec-driven development workflow.
Specification Reorganization
Flattened all spec folders to consistent structure:
spec/protocol/- Removed v0.4/ and draft/ directories, flattened to single SPEC.mdspec/cli/- Moved proposals from accepted/ and proposed/ to proposals/spec/sdk/- Moved proposals from accepted/ and proposed/ to proposals/spec/bridge/- Moved proposals from proposed/ to proposals/New unified structure:
Removed:
spec/archive/- Historical versions removedspec/scratch/- Scratch work removedspec/repo/- Retireddocs/guides/SPEC-GUIDE.md- Obsolete guide deletedCONTRIBUTING.md Updates
Added comprehensive spec-driven workflow:
a7z,k3p,m9w)Documentation Updates
Updated all outdated spec references:
docs/README.md- Fixed spec pathsdocs/development.md- Updated protocol spec referencedocs/getting-started.md- Updated protocol spec referencedocs/templates.md- Updated protocol spec referencedocs/architecture.md- Updated protocol spec referencespec/README.md- Simplified to reflect new structureUpdated CLAUDE.md:
Key Principles
a7z,k3p) to avoid conflicts🤖 Generated with Claude Code
Co-Authored-By: Claude [email protected]