feat: scenario routing architecture redesign (020)

.gitignore

@@ -10,6 +10,8 @@ web/dist/
 internal/web/dist/
 bin/
 web/coverage/
+.specify/extensions/.cache/
+.specify/extensions/.backup/
 
 # Go
 *.exe

.specify/extensions.yml

@@ -0,0 +1,4 @@
+installed: []
+settings:
+  auto_execute_hooks: true
+hooks: {}

.specify/extensions/.registry

@@ -0,0 +1,22 @@
+{
+  "schema_version": "1.0",
+  "extensions": {
+    "retro": {
+      "version": "1.0.2",
+      "source": "local",
+      "manifest_hash": "sha256:07a038a57aa8125331ff346c2562976a1f7be5a3f0d6f041c8c4b72fd1ae426e",
+      "enabled": true,
+      "registered_commands": {
+        "claude": [
+          "speckit.retro.analyze",
+          "speckit.retro"
+        ],
+        "copilot": [
+          "speckit.retro.analyze",
+          "speckit.retro"
+        ]
+      },
+      "installed_at": "2026-03-10T11:02:55.438106+00:00"
+    }
+  }
+}

.specify/extensions/retro/.github/README.md

@@ -0,0 +1,51 @@
+# speckit-retro-extension
+
+Spec-kit extension for retrospective analysis and continuous self-improvement.
+
+## Quick Links
+
+- [Installation & Usage](README.md)
+- [Changelog](CHANGELOG.md)
+- [License](LICENSE)
+
+## Structure
+
+```
+speckit-retro-extension/
+├── extension.yml          # Extension manifest
+├── README.md             # Documentation
+├── LICENSE               # MIT License
+├── CHANGELOG.md          # Version history
+└── commands/
+    └── retro.md          # /speckit.retro command implementation
+```
+
+## Local Testing
+
+To test this extension locally before publishing:
+
+```bash
+cd ~/Code/speckit-retro-extension
+specify extension add --from .
+```
+
+Then in your spec-kit project:
+
+```bash
+/speckit.retro 015-019
+```
+
+## Publishing
+
+1. Update version in `extension.yml`
+2. Update `CHANGELOG.md`
+3. Commit changes
+4. Create git tag: `git tag v1.0.0`
+5. Push tag: `git push origin v1.0.0`
+6. Create GitHub release from tag
+
+Users can then install via:
+
+```bash
+specify extension add --from https://github.com/dopejs/speckit-retro-extension
+```

.specify/extensions/retro/.github/workflows/release.yml

@@ -0,0 +1,44 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Create release archive
+        run: |
+          VERSION=${GITHUB_REF#refs/tags/}
+          zip -r speckit-retro-extension-${VERSION}.zip . \
+            -x ".git/*" \
+            -x ".github/*" \
+            -x "*.zip"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          files: speckit-retro-extension-*.zip
+          generate_release_notes: true
+          body: |
+            ## Installation
+
+            ```bash
+            specify extension add retro --from https://github.com/dopejs/speckit-retro-extension/archive/refs/tags/${{ github.ref_name }}.zip
+            ```
+
+            ## Usage
+
+            ```bash
+            /speckit.retro 015-019
+            ```
+
+            See [README](https://github.com/dopejs/speckit-retro-extension#readme) for full documentation.

.specify/extensions/retro/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+All notable changes to the Spec Retrospective & Self-Improvement Extension will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.2] - 2026-03-10
+
+### Added
+- GitHub Action for automated release packaging
+
+## [1.0.1] - 2026-03-10
+
+### Fixed
+- Command naming to follow `speckit.{extension}.{command}` pattern
+- Command is now `speckit.retro.analyze` with alias `speckit.retro`
+
+## [1.0.0] - 2026-03-10
+
+### Added
+- Initial release of spec retrospective extension
+- Automatic clustering for 5+ specs by component and feature
+- Pattern extraction across multiple dimensions:
+  - Shared constraints (constitution candidates)
+  - Template gaps (missing sections)
+  - Quality gate patterns (checklist items)
+  - Constitution violations (principle refinements)
+  - Implementation deviations (process improvements)
+- Evidence-based proposals with spec citations
+- Multi-group analysis with separate proposals per group
+- User approval workflow for applying changes
+- Optional spec archival to reduce token usage
+- Constitution versioning support (MAJOR/MINOR/PATCH)
+- Progressive loading for token efficiency

.specify/extensions/retro/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

.specify/extensions/retro/README.md

@@ -0,0 +1,181 @@
+# Spec Retrospective & Self-Improvement Extension
+
+A spec-kit extension that enables continuous improvement by analyzing completed specs to extract shared constraints, patterns, and lessons learned, then proposing improvements to your project's constitution, templates, and checklists.
+
+## Overview
+
+As your project accumulates specs, this extension helps you:
+
+- **Extract cross-cutting patterns** from completed implementations
+- **Identify shared constraints** that should be codified in your constitution
+- **Discover template gaps** where manual additions are repeatedly needed
+- **Build quality checklists** based on recurring validation needs
+- **Reduce token usage** by archiving analyzed specs after extracting their lessons
+
+## Philosophy
+
+**Self-Improvement Loop**: Each completed spec is a learning opportunity. The retro process distills implementation experience into reusable governance rules, better templates, and quality gates that make future specs higher quality with less ambiguity.
+
+**Constitution-First**: The constitution is the only artifact loaded by all future specs. Extracting shared constraints into the constitution has maximum leverage—it improves every subsequent spec automatically.
+
+**No New Artifacts**: This extension does NOT create summary.md or other new file types. It strengthens existing infrastructure (constitution, templates, checklists) that spec-kit commands already use.
+
+## Installation
+
+### From GitHub (recommended)
+
+```bash
+specify extension add --from https://github.com/dopejs/speckit-retro-extension
+```
+
+### From Local Path (for development)
+
+```bash
+specify extension add --from /path/to/speckit-retro-extension
+```
+
+## Usage
+
+### Basic Usage
+
+Analyze a range of completed specs:
+
+```bash
+/speckit.retro 015-019
+```
+
+Analyze specific specs:
+
+```bash
+/speckit.retro 015,017,019
+```
+
+Analyze all specs:
+
+```bash
+/speckit.retro all
+```
+
+### Workflow
+
+1. **Identify specs** — Specify which completed specs to analyze
+2. **Automatic clustering** — For 5+ specs, automatically groups by topic/component
+3. **Select groups** — Choose which groups to analyze (or analyze all)
+4. **Pattern extraction** — Identifies cross-spec patterns in:
+   - Shared constraints (constitution candidates)
+   - Template gaps (missing sections)
+   - Quality gates (checklist items)
+   - Constitution violations (principle refinements)
+   - Implementation deviations (process improvements)
+5. **Review proposals** — Structured improvement proposals with evidence
+6. **Apply changes** — Select which improvements to apply
+7. **Optional archival** — Move analyzed specs to `.archive/` to reduce token usage
+
+### Example Output
+
+```markdown
+## Group 1: Backend & API - Improvement Proposals
+
+### Constitution Amendments
+
+#### Amendment 1.1: API Response Time Limits
+
+**Type**: New constraint
+**Rationale**: Specs 017, 019 both implemented 10-second timeout mechanisms
+**Proposed Text**: All API endpoints MUST respond within 10 seconds...
+**Version Bump**: MINOR
+
+### Template Updates
+
+#### Template Update 1.1: Add Error Handling Strategy
+
+**Template**: plan-template.md
+**Rationale**: Specs 017, 019, 020 all added this section manually
+**Proposed Diff**: [shows exact changes]
+
+### Checklist Additions
+
+#### Checklist Addition 1.1: API Design Checklist
+
+**Items**:
+- [ ] CHK-API-001: All endpoints have timeout handling
+- [ ] CHK-API-002: Error responses follow consistent format
+...
+```
+
+## Features
+
+### Automatic Clustering (5+ specs)
+
+When analyzing many specs, the extension automatically clusters them by:
+
+**Component-based**: Backend/API, Frontend/UI, CLI/Tooling, Infrastructure, Testing
+**Feature-based**: Stability, Performance, Security, Data, User Experience
+
+This ensures proposals are focused and domain-specific rather than mixing unrelated constraints.
+
+### Evidence-Based Proposals
+
+Every proposal cites specific specs as evidence. Minimum 2-3 specs must show the same pattern before it's proposed as a shared constraint.
+
+### Safe Application
+
+- User approval required for all changes
+- Constitution versioning follows governance rules (MAJOR/MINOR/PATCH)
+- All changes are git-tracked and reversible
+- Original specs preserved in `.archive/` if archived
+
+### Token Efficiency
+
+- Progressive loading (specs loaded incrementally)
+- Minimal context extraction (only relevant sections)
+- Optional archival reduces future token usage by 90%+
+
+## When to Run Retro
+
+**Recommended cadence**: After completing every 5-10 specs
+
+**Good times to run**:
+- After a major feature milestone
+- Before starting a new development phase
+- When you notice repeated patterns across recent specs
+- When constitution feels outdated or incomplete
+
+**Signs you need retro**:
+- Specs repeatedly add the same manual sections
+- Similar quality issues appear across multiple specs
+- Constitution violations have similar justifications
+- Token usage is growing due to many historical specs
+
+## Requirements
+
+- spec-kit >= 0.1.0
+- Existing spec-kit project with completed specs
+- Constitution file at `.specify/memory/constitution.md`
+
+## Configuration
+
+No configuration needed. The extension works with your existing spec-kit setup.
+
+## Contributing
+
+Contributions welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Test on real projects
+4. Submit a pull request
+
+## License
+
+MIT License - see LICENSE file for details
+
+## Support
+
+- Issues: https://github.com/dopejs/speckit-retro-extension/issues
+- Discussions: https://github.com/dopejs/speckit-retro-extension/discussions
+
+## Related
+
+- [spec-kit](https://github.com/github/spec-kit) - The core spec-kit framework
+- [Extension Development Guide](https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-DEVELOPMENT-GUIDE.md)