Design Decisions
These decisions were made through structured design review and are final. They represent the constraints the implementation must respect.
| # | Decision | Choice | Rationale |
|---|---|---|---|
| 1 | Packaging | npm CLI + slash commands + agents | One npx spexso init bootstraps everything. No manual setup. |
| 2 | Spec sizing | Tiered — XS/S lite, M/L/XL full spec | Prevents overhead-kills-adoption for small tasks. |
| 3 | Storage | GitLab issues = truth, .spexso/index.json = local cache (~300 tok) | ~300 tokens passive vs ~6000 for all-markdown. No sync drift. |
| 4 | Worktrees | One per issue, enforced by framework | Guarantees isolation. No cross-contamination between features. |
| 5 | Autonomy | Developer-controlled modes: yolo / pilot / copilot | Different tasks need different levels of human involvement. |
| 6 | Code review | Critical+High = auto-rewrite, Low = comment only | Blocks bad code without blocking velocity on minor style issues. |
| 7 | TDD | Strict — tests before implementation, always | Enterprise quality requires it. AI is excellent at test generation. |
| 8 | Finish flow | Push + MR + update issue + cleanup worktree automatically | One command, zero manual steps, clean state for next task. |
| 9 | Issue reporting | Anyone reports, Claude auto-classifies type + auto-sizes | Zero-friction issue reporting for non-developers. |
| 10 | Competitive research | Web + SAP ecosystem + comparison + auto-create issues | Competitive intelligence meets feature discovery. |
| 11 | Context protection | Hybrid: lean orchestrator + disposable subagent per task | Prevents context window explosion in long yolo sessions. |
| 12 | Skills | Native .claude/skills/, user-installed. Agent = process, Skill = knowledge | Skills provide domain knowledge; agents provide choreography. |
| 13 | Duplicate prevention | GitLab assignment lock — assign on start, refuse if already assigned | Prevents two developers working the same issue simultaneously. |
| 14 | Wiki sync | ADRs + research to wiki via /spexso-docs. Force README.md + CHANGELOG.md | Mandatory documentation with automatic wiki synchronization. |
| 15 | Plan behavior | Auto-decided: yolo auto-plans silently, pilot/copilot show for approval | All modes generate plans; difference is human checkpoint. |
| 16 | Model selection | Developer's choice via --model flag, project default in CLAUDE.md | Flexible model selection with session-wide consistency. |