From 7e7d50b61a28279cecca7f37fe7648a349ea76c2 Mon Sep 17 00:00:00 2001
From: clawdeeo <clawdeeo@airscript.it>
Date: Thu, 23 Apr 2026 11:01:23 +0000
Subject: [PATCH] docs: add spec-driven development and improved workflow
 guidelines

- Add .specs/TEMPLATE.md for feature specifications
- Update .gitignore to exclude temporary specs
- Enhance AGENTS.md with:
  - Spec-driven development process
  - Strict PR discipline guidelines
  - Definition of Done checklist
  - Post-mortem guidelines

This formalizes the workflow improvements discussed to match
OpenCode-style development practices.
---
 .gitignore         | 13 ++++++------
 .specs/TEMPLATE.md | 49 ++++++++++++++++++++++++++++++++++++++++++++++
 AGENTS.md          | 31 +++++++++++++++++++++++++++++
 3 files changed, 86 insertions(+), 7 deletions(-)
 create mode 100644 .specs/TEMPLATE.md

diff --git a/.gitignore b/.gitignore
index 66267fc..dd91f5b 100644
--- a/.gitignore
+++ b/.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
diff --git a/.specs/TEMPLATE.md b/.specs/TEMPLATE.md
new file mode 100644
index 0000000..63f19d4
--- /dev/null
+++ b/.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:**
diff --git a/AGENTS.md b/AGENTS.md
index c55ec70..c5d8d0c 100644
--- a/AGENTS.md
+++ b/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*