feat: implement Lean Architecture Improvements with 6 new features

- Lean Architecture Views: configurable --views flag (core 5 or all 7 views)
- Surprise-Value Heuristic: --adr-heuristic for skipping obvious defaults
- Constitution Cross-Reference: always-enabled ADR/constitution validation
- ADR Template Improvements: Common Alternatives, Discovered status, no fabricated rejection
- Existing Docs Deduplication: scan docs/ and *.md files to reference not duplicate
- Risks & Gaps Analysis: cross-cutting Phase 2.5 in /architect.clarify

Updates bash and PowerShell scripts, templates, and documentation.

Author: kanfil

CHANGELOG.md

@@ -9,6 +9,59 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- **Lean Architecture Views**: Configurable view generation with core vs optional views
+  - Default "core" views: Context, Functional, Information, Development, Deployment
+  - Optional views: Concurrency, Operational (via `--views` flag)
+  - Support for: `--views all`, `--views core`, `--views concurrency,operational`
+  - Marked optional views in templates with HTML comments
+
+- **Surprise-Value Heuristic for ADRs**: Skip obvious ecosystem defaults, document only surprising/risky decisions
+  - Configurable via `--adr-heuristic` flag: `surprising` (default), `all`, `minimal`
+  - Heuristic rules distinguish obvious (PostgreSQL for relational) vs surprising (custom auth)
+  - Configuration in `config.json`: `architecture.adr.heuristic`
+
+- **Constitution Cross-Reference**: Strict checking for ADR/Constitution alignment
+  - Always enabled in `/architect.clarify`
+  - Detects duplicates (constitution already mandates), violations, unclear alignment
+  - **Option A (Amend Constitution) as PRIMARY resolution** for violations
+  - Adds "Constitution Alignment" section to ADR template
+
+- **ADR Template Improvements**:
+  - Renamed "Alternatives Considered" to "Common Alternatives"
+  - Changed framing from "Rejected because" to neutral "Trade-offs"
+  - Added "Discovered" status for reverse-engineered ADRs
+  - Removed fabricated rejection rationale requirement
+  - Added "Constitution Alignment" section with compliance tracking
+
+- **Existing Docs Deduplication**: Scan and reference instead of duplicate
+  - Scans `docs/` directory and root `*.md` files (configurable paths)
+  - References existing docs (README, AGENTS.md, CONTRIBUTING) instead of duplicating
+  - Auto-merges when existing architecture found (no prompt)
+  - New `scan_existing_docs()` function in setup-architecture.sh
+
+- **Risks & Gaps Analysis**: Cross-cutting analysis in `/architect.clarify`
+  - Identifies operational gaps, technical debt, SPOFs, security concerns
+  - Section-based gap IDs (e.g., `3.6.1` = Deployment view, gap #1)
+  - Runs BEFORE constitution cross-reference (Phase 2.5)
+  - Output integrated into existing view sections
+
+### Changed
+
+- **BREAKING: Architecture File Paths**: Updated to new two-file structure
+  - Architecture Description: `AD.md` at project root (was `memory/architecture.md`)
+  - Architecture Decision Records: `memory/adr.md` (unchanged)
+  - Updated all scripts: `setup-architecture.sh`, `setup-plan.sh`, `common.sh`
+  - Updated command templates: `architect.init.md`, `architect.specify.md`, `architect.clarify.md`
+
+- **Configuration**: Added comprehensive architecture configuration
+  - `architecture.views`: "core", "all", or comma-separated list
+  - `architecture.adr.heuristic`: "surprising", "all", "minimal"
+  - `architecture.adr.check_constitution`: true (always enabled)
+  - `architecture.deduplication.scan_paths`: ["docs/", "*.md"]
+  - Helper functions: `get_architecture_views()`, `get_adr_heuristic()`, `get_architecture_config()`
+
 ## [0.3.0] - 2026-02-08
 
 ### Added

README.md

@@ -380,6 +380,44 @@ The toolkit includes comprehensive architecture documentation support that works
 
 **Feature Architecture**: Use `/spec.plan --architecture` or set `architecture=true` in spec.md Framework Options to generate feature-level architecture (`specs/{feature}/AD.md` and `specs/{feature}/adr.md`).
 
+#### Architecture Configuration Options
+
+The architecture commands support additional configuration options for fine-tuned control:
+
+**Views Selection** (`--views`):
+
+- `core` (default) - Generate the essential 5 views: Context, Functional, Information, Development, Deployment
+- `all` - Include all 7 views including Concurrency and Operational
+- `concurrency,operational` - Custom selection (comma-separated), always includes core views
+
+```bash
+# Default core views
+/architect.init "E-commerce platform"
+
+# All views including concurrency and operational
+/architect.init --views all "High-throughput trading system"
+
+# Custom selection
+/architect.init --views concurrency "Real-time data processing pipeline"
+```
+
+**ADR Generation Heuristic** (`--adr-heuristic`):
+
+- `surprising` (default) - Only document decisions that deviate from obvious ecosystem defaults
+- `all` - Document every architectural decision
+- `minimal` - Document only high-risk or non-obvious decisions
+
+```bash
+# Skip documenting obvious choices (PostgreSQL for relational data, React for SPA)
+/architect.specify --adr-heuristic surprising "Standard web application"
+
+# Document every decision
+/architect.specify --adr-heuristic all "Complex multi-tenant system"
+
+# Minimal documentation
+/architect.specify --adr-heuristic minimal "Internal tool with simple requirements"
+```
+
 #### Rozanski & Woods Viewpoints
 
 The `architect.*` commands generate documentation covering:

roadmap.md

@@ -165,6 +165,44 @@
 - ✅ **Smart Trace Validation**: Documented and implemented in `/analyze` command (lines 209-236)
 - ⚠️ **Task-to-Issues Command**: Template exists at `templates/commands/taskstoissues.md` but only supports GitHub (multi-tracker support planned in Tier 1.5)
 
+### **Lean Architecture Improvements** *(100% Complete)* - **COMPLETED** - 6 Architecture Enhancements
+
+Major enhancements to the architecture system making it more flexible, intelligent, and integrated with existing documentation.
+
+- ✅ **Lean Architecture Views**: Configurable view generation (core 5 + optional 2)
+  - Default "core" views: Context, Functional, Information, Development, Deployment
+  - Optional views: Concurrency, Operational (via `--views` flag)
+  - `--views all`, `--views core`, `--views concurrency,operational`
+  
+- ✅ **Surprise-Value Heuristic**: Skip obvious ecosystem defaults, document only surprising/risky decisions
+  - `--adr-heuristic surprising` (default), `all`, `minimal`
+  - Configuration in `config.json`: `architecture.adr.heuristic`
+  
+- ✅ **Constitution Cross-Reference**: Strict checking for ADR/Constitution alignment
+  - Always enabled in `/architect.clarify`
+  - Detects duplicates, violations, unclear alignment
+  - **Option A (Amend Constitution) as PRIMARY resolution**
+  
+- ✅ **ADR Template Improvements**:
+  - "Common Alternatives" (not "Alternatives Considered")
+  - Neutral "Trade-offs" framing (not "Rejected because")
+  - "Discovered" status for reverse-engineered ADRs
+  - "Constitution Alignment" section
+  
+- ✅ **Existing Docs Deduplication**: Scan and reference instead of duplicate
+  - Scans `docs/` directory and root `*.md` files
+  - References existing docs (README, AGENTS.md, CONTRIBUTING)
+  - Auto-merges when existing architecture found
+  
+- ✅ **Risks & Gaps Analysis**: Cross-cutting analysis in `/architect.clarify`
+  - Identifies operational gaps, tech debt, SPOFs, security concerns
+  - Section-based gap IDs (e.g., `3.6.1`)
+  - Runs BEFORE constitution cross-reference
+
+**Files Modified**: 13 files including templates, scripts, and configuration
+
+---
+
 ### **Optional Architecture Support** *(100% Complete)* - **COMPLETED** - Enterprise Architecture Features
 
 Architecture support is now available in all workflow modes as optional commands. The `/architect` and `/constitution` commands work silently in any mode, with no warnings if files are missing.
@@ -742,6 +780,115 @@ Consolidates: Command-level model selection + context budgeting + two-model revi
 
 ### **Future Enhancement Categories**
 
+### **Compound Engineering Integration** *(0% Complete)* - **MEDIUM PRIORITY** - Insights from EveryInc's Compound Engineering Plugin
+
+**Reference**: Analysis of [EveryInc/compound-engineering-plugin](https://github.com/EveryInc/compound-engineering-plugin) (7.5k stars, 598 forks)
+
+**Key Insight**: Compound Engineering Plugin focuses on workflow efficiency through multi-agent parallelization and knowledge compounding, while Agentic SDLC Spec Kit focuses on structured SDLC methodology. These approaches are complementary.
+
+#### **Swarm Mode Parallel Execution** *(0% Complete)* - **HIGH PRIORITY**
+
+- **Description**: Implement swarm mode execution (like Compound's `/slfg`) that runs multiple sub-agents in parallel for tasks marked with `[P]` markers, dramatically accelerating development workflows
+- **Key Components**:
+  - Parallel agent spawning for independent tasks within phases
+  - Worktree-based isolation (validates incident.io pattern with 5+ agents)
+  - Coordinated execution with dependency awareness
+  - Phase-respecting orchestration (Setup → Foundational → Stories)
+- **Benefits**: 
+  - 3-5x faster execution for parallelizable tasks
+  - Validates incident.io multi-agent + worktree pattern
+  - Maintains code isolation and merge safety
+- **Implementation**: Extend existing `[P]` marker system with swarm orchestration layer
+- **References**: incident.io workflow pattern, Worktrunk integration
+
+#### **Multi-Agent Review System** *(0% Complete)* - **MEDIUM PRIORITY**
+
+- **Description**: Implement specialized reviewer agents (like Compound's 15 review agents) that perform focused code reviews:
+  - `security-sentinel`: Security vulnerability detection
+  - `performance-oracle`: Performance optimization suggestions  
+  - `rails-reviewer`: Framework-specific best practices
+  - `accessibility-guardian`: A11y compliance checking
+  - `test-coverage-analyst`: Test quality validation
+- **Key Components**:
+  - Temperature-tuned agents (review: 0.1, planning: 0.2, creative: 0.6)
+  - Parallel review execution before merge
+  - Review agent selection based on code changes
+  - Aggregated review reports with actionable items
+- **Benefits**: 
+  - Comprehensive pre-merge validation
+  - Specialized expertise without context bloat
+  - Consistent quality gates across team
+- **Integration**: Hook into `/spec.analyze` and pre-merge workflows
+
+#### **Knowledge Compounding System** *(0% Complete)* - **MEDIUM PRIORITY**
+
+- **Description**: Enhance `/spec.levelup` with systematic knowledge capture inspired by Compound's philosophy: "Each unit of engineering work should make subsequent units easier"
+- **Key Components**:
+  - Pattern extraction from completed features
+  - Anti-pattern documentation from failed approaches
+  - Reusable solution templates for common problems
+  - Team knowledge base with searchable patterns
+  - Automatic skill generation from recurring patterns
+- **Workflow Enhancement**:
+  ```
+  Plan → Work → Review → Compound → Repeat
+  ```
+- **Benefits**: 
+  - Institutional knowledge preservation
+  - Accelerated future development through pattern reuse
+  - Reduced repeated mistakes
+  - Team learning velocity increase
+- **Integration**: Extend existing `/spec.levelup` with structured knowledge packets
+
+#### **Browser Automation Integration** *(0% Complete)* - **LOW PRIORITY**
+
+- **Description**: Integrate browser automation capabilities (like Compound's agent-browser CLI) for e2e testing and UI validation
+- **Key Components**:
+  - Automated e2e test generation from specifications
+  - Visual regression testing integration
+  - UI interaction recording and replay
+  - Screenshot-based validation in `/spec.implement`
+- **Benefits**: 
+  - Automated visual validation
+  - Reduced manual QA effort
+  - Better spec-to-implementation alignment
+- **Implementation**: Integration with Playwright, Puppeteer, or agent-browser
+
+#### **Cross-Platform Plugin Converter** *(0% Complete)* - **LOW PRIORITY**
+
+- **Description**: Create plugin conversion system (like Compound's Bun/TypeScript CLI) to convert between agent formats:
+  - Claude Code plugins ↔ OpenCode format
+  - Claude Code plugins ↔ Codex format
+  - Custom agent format support
+- **Key Components**:
+  - Agent format parsers and transformers
+  - Tool mapping between platforms (bash/read/write/edit)
+  - Temperature inference from agent names
+  - MCP server conversion
+- **Benefits**: 
+  - Broader agent ecosystem compatibility
+  - Reduced vendor lock-in
+  - Easier migration between AI tools
+- **Implementation**: Python-based converter leveraging existing AGENT_CONFIG
+
+#### **Task Delegation Templates** *(0% Complete)* - **MEDIUM PRIORITY*
+
+- **Description**: Create rich task delegation system with specialized agent types inspired by Compound's agent ecosystem:
+  - **Explore Agents**: Read-only codebase search (fresh slate, no context inheritance)
+  - **Plan Agents**: Design/implementation planning (full context inheritance)
+  - **Execute Agents**: Multi-step task execution with tool sequencing
+  - **Review Agents**: Focused quality validation
+- **Key Components**:
+  - Agent type selection matrix based on task characteristics
+  - Context inheritance rules per agent type
+  - Model selection guidance per agent type
+  - "When NOT to Spawn" guidelines to prevent context bloat
+- **Benefits**: 
+  - Optimized agent utilization
+  - Reduced unnecessary context window usage
+  - Better task-agent matching
+- **Integration**: Extend Tier 2 Sub-Agent Coordination Framework
+
 ### **Beads-Backed Task Execution Tracker** *(0% Complete)* - **MEDIUM PRIORITY** - Agent-native persistent work tracking
 
 **Problem Statement**:

scripts/bash/common.sh

@@ -297,9 +297,11 @@ get_feature_paths() {
     local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
 
     # Project-level governance documents
-    local memory_dir="$repo_root/.specify/memory"
+    local memory_dir="$repo_root/memory"
     local constitution_file="$memory_dir/constitution.md"
-    local architecture_file="$memory_dir/architecture.md"
+    # New architecture structure: AD.md at root, ADRs in memory/
+    local ad_file="$repo_root/AD.md"
+    local adr_file="$memory_dir/adr.md"
 
     cat <<EOF
 REPO_ROOT='$repo_root'
@@ -316,7 +318,8 @@ CONTEXT='$feature_dir/context.md'
 CONTRACTS_DIR='$feature_dir/contracts'
 TEAM_DIRECTIVES='${SPECIFY_TEAM_DIRECTIVES:-}'
 CONSTITUTION='$constitution_file'
-ARCHITECTURE='$architecture_file'
+AD='$ad_file'
+ADR='$adr_file'
 EOF
 }