Refine CONTRIBUTING.md workflow documentation (#38)

## Summary

Refines the spec-driven development workflow documentation in
CONTRIBUTING.md to be more concise and clear, and updates all agent
quick reference files to reflect the new structure.

## Changes to CONTRIBUTING.md

**Consolidated and simplified:**
- Merged "Folder Structure" and "Naming Convention" into single section
- Removed redundant explanations of 3-character codes
- Standardized on `XXX-name` format throughout
- Added clarification that `<area>` = protocol, cli, sdk, or bridge
- Added proposal structure documentation:
  - `proposal.md` - Main specification
  - `research.md` - Background research
  - `decision-XXX-name.md` - Individual ADR-style decisions

**Added code-first workflow note:**
- Acknowledges contributors who implement code first
- Guides them to backfill proposal/spec/CHANGELOG before PR

## Updates to Agent Quick Reference Files

**CLAUDE.md:**
- Updated proposal structure details
- Added `<area>` clarification
- Updated repository structure diagram
- Added code-first workflow note
- Removed outdated v0.4/draft references

**AGENTS.md:**
- Same updates as CLAUDE.md for consistency

## Result

The workflow documentation is now:
- More concise and scannable
- Eliminates redundancy
- Provides clear guidance on proposal structure
- Welcomes both spec-first and code-first contributors
- Consistent across all reference files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: rjcorwin

AGENTS.md

@@ -1,8 +1,7 @@
 # 🤖 Agent Quick Reference - MEW Protocol
 
 ## Critical Docs (READ FIRST AND UPDATE AFTER COMPLETING WORK)
-- MEW Protocol: spec/protocol/v0.4/SPEC.md (current stable)
-- Protocol Draft: spec/protocol/draft/SPEC.md (next version)
+- MEW Protocol: spec/protocol/SPEC.md (v0.4)
 - CLI Spec: spec/cli/SPEC.md
 - SDK Spec: spec/sdk/SPEC.md
 - Bridge Spec: spec/bridge/SPEC.md
@@ -23,7 +22,10 @@ mew-protocol/
 ├── dist/                   # Compiled output
 ├── e2e/                    # End-to-end test scenarios
 ├── spec/                   # All specifications
-│   ├── protocol/          # Protocol spec (v0.4, draft)
+│   ├── protocol/          # Protocol spec (v0.4)
+│   │   ├── SPEC.md
+│   │   ├── proposals/     # All proposals
+│   │   └── rejected/      # Rejected proposals
 │   ├── cli/               # CLI spec
 │   ├── sdk/               # SDK spec
 │   └── bridge/            # Bridge spec
@@ -94,8 +96,9 @@ When making changes, follow the workflow in `CONTRIBUTING.md`:
 
 1. **Start with CHANGELOG** - Add entry to `CHANGELOG.md` "Next" section
 2. **Create proposal** - Document in `spec/<area>/proposals/XXX-name/`
-   - Use 3-char alphanumeric code: `a7z`, `k3p`, `m9w` (NOT 001, 002, or "bat", "tok")
-   - Include motivation, research, decisions, spec
+   - Use 3-char alphanumeric code: `a7z`, `k3p`, `m9w` (avoid 001, 002, or bat, tok)
+   - Each proposal contains: `proposal.md`, `research.md`, `decision-XXX-name.md` files
+   - `<area>` = protocol, cli, sdk, or bridge
 3. **Incorporate into specs** - Update main spec docs, mark CHANGELOG as needing implementation
 4. **Create implementation plan** (if complex) - `spec/integration-plans/XXX-name.md`
 5. **Implement code** - Write code, tests, examples; update CHANGELOG status
@@ -105,6 +108,7 @@ When making changes, follow the workflow in `CONTRIBUTING.md`:
 - Proposals stay in `proposals/` permanently (status tracked in CHANGELOG)
 - Specs and code developed together in same PR
 - All changes must update relevant specs
+- If you code first, backfill proposal/spec/CHANGELOG before opening PR
 - See `CONTRIBUTING.md` for full workflow details
 
 ## Key Files
@@ -140,12 +144,9 @@ When making changes, follow the workflow in `CONTRIBUTING.md`:
 - Testing: `docs/testing.md`
 - Templates: `docs/templates.md`
 - Releasing: `docs/releasing.md`
-- Spec guide: `docs/guides/SPEC-GUIDE.md`
-
 ## Specs Navigation
 - All specs: `spec/README.md`
-- Protocol v0.4 (stable): `spec/protocol/v0.4/SPEC.md`
-- Protocol draft (next): `spec/protocol/draft/SPEC.md`
+- Protocol (v0.4): `spec/protocol/SPEC.md`
 - CLI spec: `spec/cli/SPEC.md`
 - SDK spec: `spec/sdk/SPEC.md`
 - Bridge spec: `spec/bridge/SPEC.md`

CLAUDE.md

@@ -1,8 +1,7 @@
 # 🤖 Agent Quick Reference - MEW Protocol
 
 ## Critical Docs (READ FIRST AND UPDATE AFTER COMPLETING WORK)
-- MEW Protocol: spec/protocol/v0.4/SPEC.md (current stable)
-- Protocol Draft: spec/protocol/draft/SPEC.md (next version)
+- MEW Protocol: spec/protocol/SPEC.md (v0.4)
 - CLI Spec: spec/cli/SPEC.md
 - SDK Spec: spec/sdk/SPEC.md
 - Bridge Spec: spec/bridge/SPEC.md
@@ -23,7 +22,10 @@ mew-protocol/
 ├── dist/                   # Compiled output
 ├── e2e/                    # End-to-end test scenarios
 ├── spec/                   # All specifications
-│   ├── protocol/          # Protocol spec (v0.4, draft)
+│   ├── protocol/          # Protocol spec (v0.4)
+│   │   ├── SPEC.md
+│   │   ├── proposals/     # All proposals
+│   │   └── rejected/      # Rejected proposals
 │   ├── cli/               # CLI spec
 │   ├── sdk/               # SDK spec
 │   └── bridge/            # Bridge spec
@@ -94,8 +96,9 @@ When making changes, follow the workflow in `CONTRIBUTING.md`:
 
 1. **Start with CHANGELOG** - Add entry to `CHANGELOG.md` "Next" section
 2. **Create proposal** - Document in `spec/<area>/proposals/XXX-name/`
-   - Use 3-char alphanumeric code: `a7z`, `k3p`, `m9w` (NOT 001, 002, or "bat", "tok")
-   - Include motivation, research, decisions, spec
+   - Use 3-char alphanumeric code: `a7z`, `k3p`, `m9w` (avoid 001, 002, or bat, tok)
+   - Each proposal contains: `proposal.md`, `research.md`, `decision-XXX-name.md` files
+   - `<area>` = protocol, cli, sdk, or bridge
 3. **Incorporate into specs** - Update main spec docs, mark CHANGELOG as needing implementation
 4. **Create implementation plan** (if complex) - `spec/integration-plans/XXX-name.md`
 5. **Implement code** - Write code, tests, examples; update CHANGELOG status
@@ -105,6 +108,7 @@ When making changes, follow the workflow in `CONTRIBUTING.md`:
 - Proposals stay in `proposals/` permanently (status tracked in CHANGELOG)
 - Specs and code developed together in same PR
 - All changes must update relevant specs
+- If you code first, backfill proposal/spec/CHANGELOG before opening PR
 - See `CONTRIBUTING.md` for full workflow details
 
 ## Key Files
@@ -140,12 +144,9 @@ When making changes, follow the workflow in `CONTRIBUTING.md`:
 - Testing: `docs/testing.md`
 - Templates: `docs/templates.md`
 - Releasing: `docs/releasing.md`
-- Spec guide: `docs/guides/SPEC-GUIDE.md`
-
 ## Specs Navigation
 - All specs: `spec/README.md`
-- Protocol v0.4 (stable): `spec/protocol/v0.4/SPEC.md`
-- Protocol draft (next): `spec/protocol/draft/SPEC.md`
+- Protocol (v0.4): `spec/protocol/SPEC.md`
 - CLI spec: `spec/cli/SPEC.md`
 - SDK spec: `spec/sdk/SPEC.md`
 - Bridge spec: `spec/bridge/SPEC.md`

CONTRIBUTING.md

@@ -19,6 +19,8 @@ Thank you for contributing to MEW Protocol! This guide covers how to contribute
 
 MEW Protocol follows a spec-driven development approach where specifications are designed and documented before code implementation. All changes begin with a CHANGELOG entry that tracks the proposal and implementation status throughout the lifecycle.
 
+**Note:** If you've already implemented code changes, that's okay! Before opening your PR, create a proposal documenting the design, incorporate it into the relevant spec, and add a CHANGELOG entry. This ensures we maintain clear documentation of all changes.
+
 ### Lifecycle Stages
 
 1. **Draft** - Add CHANGELOG entry, design and write proposals in proposals/ (in Draft PR)
@@ -29,13 +31,23 @@ MEW Protocol follows a spec-driven development approach where specifications are
 6. **Merge** - Merge approved changes (specs + code together)
 7. **Release** - Tag version with all merged changes (happens later)
 
-### Folder Structure
+### Folder Structure & Naming
+
+**Note:** `<area>` refers to the spec area: `protocol`, `cli`, `sdk`, or `bridge`
+
+**Proposals:** `spec/<area>/proposals/XXX-name/`
+- XXX = unique 3-character alphanumeric code (e.g., `a7z`, `k3p`, `m9w`; avoid 001, 002, or bat, tok)
+- name = kebab-case description (e.g., `message-batching`, `token-limits`)
+- Each proposal directory contains:
+  - `proposal.md` - Main specification with motivation, goals, technical details
+  - `research.md` - Background research, constraints, current state, prior art
+  - `decision-XXX-name.md` - Individual ADR-style decision records as needed
 
-- **`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`)
+**Rejected proposals:** `spec/<area>/rejected/XXX-name/`
+
+**Implementation plans:** `spec/integration-plans/XXX-name.md`
+- Same XXX-name format as proposals
+- Optional, for complex changes requiring coordination
 
 ### Core Documents
 
@@ -44,14 +56,6 @@ MEW Protocol follows a spec-driven development approach where specifications are
 - **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`)
-- Codes must be unique within their scope (proposals per spec area, implementation plans globally)
-- Use random alphanumeric combinations (mix letters and numbers) to avoid conflicts across concurrent PRs
-- Avoid sequential numbers (001, 002) or word-like abbreviations (bat, tok) that may conflict
-
 ---
 
 ## Development Setup

README.md

@@ -51,7 +51,7 @@ The **proposal mechanism** ensures humans stay in control. New agents start with
 
 **v0.4** - Released 2025-09-26 🎉
 
-MEW Protocol is in experimental phase (v0.x) with breaking changes allowed between versions. See [spec/protocol/v0.4/SPEC.md](spec/protocol/v0.4/SPEC.md) for the current specification.
+MEW Protocol is in experimental phase (v0.x) with breaking changes allowed between versions. See [spec/protocol/SPEC.md](spec/protocol/SPEC.md) for the current specification.
 
 ## 🚀 Quick Start
 
@@ -97,9 +97,11 @@ See [docs/README.md](docs/README.md) for complete documentation including:
 
 ## 📋 Specifications
 
-- [Current Specification (v0.4)](spec/protocol/v0.4/SPEC.md)
-- [Draft Specification (next version)](spec/protocol/draft/SPEC.md)
-- [Architecture Decision Records](spec/protocol/v0.4/accepted/)
+- [Protocol Specification](spec/protocol/SPEC.md) - Core MEW Protocol (v0.4)
+- [CLI Specification](spec/cli/SPEC.md) - Command-line interface
+- [SDK Specification](spec/sdk/SPEC.md) - TypeScript SDK
+- [Bridge Specification](spec/bridge/SPEC.md) - MCP-MEW bridge
+- [All Specifications](spec/README.md) - Complete spec hub
 - [Changelog](CHANGELOG.md)
 
 ## 🐈 Why "MEW"?

TODO.md

@@ -4,16 +4,21 @@
 11. Compact support
 2. mew needs to return status that includes token usage, and depending on model we'll add some context window info for reference so %usage can be reported.
 
+- upgrading Ink from 3.2.0 to 6.3.1
+
 ## ui/ux
 1. ctrl-c the first time should clear the input buffer.
 3. When proposal select list appears, if there was input in the input box, should restore it when the select list disappears.
 10. File ref autocomplete
+11. fix pasting of content into input
 
 8. Add MCP bash server
+10. Support for running commands with `!`
 
 9. MCP Responses formatter for edit_file, needs better formatting
 
 6. CLAUDE.md/AGENTS.md support for automatically adding to context.
 5. /thinking slash command to toggle display of those sections in chat messages.
 7. "Selected code" VSCode integration
 
+- Figure out how to give coding agents the ability to run mew interactive cli and test