docs: improve workflow with spec-driven development

.gitignore

@@ -1,11 +1,10 @@
-/target
-**/*.rs.bk
+/target/
 Cargo.lock
-.DS_Store
 *.swp
 *.swo
 *~
-.idea
-.vscode
-*.iml
-.specs/
+.DS_Store
+
+# Specs are temporary - reviewed, implemented, then deleted
+.specs/*.md
+!.specs/TEMPLATE.md

.specs/TEMPLATE.md

@@ -0,0 +1,49 @@
+# Spec Template
+
+## Feature: [Name]
+
+### Problem
+[What problem does this solve?]
+
+### Solution
+[High-level approach]
+
+### Acceptance Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+### Edge Cases
+- [ ] Edge case 1: [expected behavior]
+- [ ] Edge case 2: [expected behavior]
+
+### Test Plan
+- Unit tests: [what to test]
+- Integration tests: [what to test]
+- Manual verification: [steps]
+
+### Files to Modify
+- [ ] file1.rs
+- [ ] file2.rs
+
+### Documentation Updates
+- [ ] CHANGELOG.md
+- [ ] README.md (if user-facing)
+- [ ] AGENTS.md (if process changes)
+
+---
+
+## Checkpoint Reviews
+
+- [ ] 25%: [what's done, blockers?]
+- [ ] 50%: [what's done, blockers?]
+- [ ] 75%: [what's done, blockers?]
+- [ ] 100%: [final review before PR]
+
+## Post-Mortem (fill after merge)
+
+**What went well:**
+
+**What could improve:**
+
+**Lessons learned:**

AGENTS.md

@@ -83,5 +83,36 @@ Each file covers the corresponding module's public API. Tests that validate erro
 
 Verify → Test → Build
 
+## Spec-Driven Development
+
+1. Create `.specs/feature-name.md` from TEMPLATE.md before coding
+2. Define acceptance criteria and test plan
+3. Review spec with user before implementation
+4. Checkpoint at 25%, 50%, 75% for feedback
+5. Delete spec after merge (gitignored, temporary)
+
+## PR Discipline
+
+- Always branch: `feat/`, `fix/`, `docs/`, `chore/`
+- Never push to main directly
+- Squash merge after review
+- Include tests and documentation updates
+
+## Definition of Done
+
+- [ ] Code complete
+- [ ] Tests pass (`cargo test`)
+- [ ] Lint clean (`cargo fmt && cargo clippy`)
+- [ ] Documentation updated (CHANGELOG, README if needed)
+- [ ] Manual verification done
+- [ ] PR opened and reviewed
+
+## Post-Mortems
+
+After any significant issue or rework, document:
+- What went wrong
+- Root cause
+- Prevention for next time
+
 *Last updated: 2026-04-23*