BREAKING: Remove AD Mode - architecture support now optional in all modes

- Removed 'ad' mode option from /mode command
- Only build and spec workflow modes remain
- /architect and /constitution commands now work in all modes
- Architecture and constitution files load silently when present
- Automatic migration: existing 'ad' configs treated as 'spec'
- Added get_current_mode() functions to bash and PowerShell
- Updated setup-plan scripts to detect mode and load architecture
- Architecture loading matches constitution pattern exactly
- No warnings when architecture.md or constitution.md missing

BREAKING CHANGE: Projects using 'ad' mode will automatically migrate to 'spec' mode.
Architecture commands remain available but are no longer tied to a specific mode.

Closes: unified workflow implementation
Version: 0.1.0

Author: kanfil

CHANGELOG.md

@@ -9,16 +9,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.1.0] - 2026-01-30
+
+### Changed
+
+- **BREAKING: Removed AD Mode**: Architecture support is now optional and available in all workflow modes
+  - Removed "ad" mode option from `/mode` command
+  - Only `build` and `spec` workflow modes remain
+  - `/speckit.architect` and `/speckit.constitution` commands now work in all modes
+  - Architecture and constitution files load silently when present, with no warnings if missing
+  - Automatic migration: existing "ad" mode configurations treated as "spec" mode
+  - Added `get_current_mode()` / `Get-CurrentMode` functions to bash and PowerShell scripts
+  - Updated `setup-plan.sh` and `setup-plan.ps1` to detect mode and load architecture automatically
+
 ### Added
 
-- **Architecture Description (AD) Mode**: New workflow mode for architecture-first development
-  - New `/speckit.architect` command implementing Rozanski & Woods "Software Systems Architecture" methodology
+- **Optional Architecture Support**: Architecture documentation available in all modes
+  - `/speckit.architect` command implementing Rozanski & Woods "Software Systems Architecture" methodology
   - 7 Core Viewpoints: Context, Functional, Information, Concurrency, Development, Deployment, Operational
   - 2 Cross-cutting Perspectives: Security, Performance & Scalability
   - Four actions: `init` (greenfield), `map` (brownfield/reverse-engineering), `update` (sync with changes), `review` (validation)
   - Language-agnostic codebase scanning for brownfield projects
   - Generates `memory/architecture.md` as central architecture artifact
-  - AD mode added to mode configuration alongside `build` and `spec` modes
+  - Works silently in both build and spec modes
   - Templates: `templates/architecture-template.md` and `templates/commands/architect.md`
   - Scripts: `scripts/bash/setup-architecture.sh` and `scripts/powershell/setup-architecture.ps1`
 

README.md

@@ -248,7 +248,6 @@ Specify supports two workflow modes that control the complexity level of the dev
 
 - **`spec` mode (default)**: Full structured specification with comprehensive requirements, research, and validation
 - **`build` mode**: Lightweight, conversational approach focused on quick validation and exploration
-- **`ad` mode**: Architecture-first workflow using Rozanski & Woods methodology for complex enterprise systems
 
 #### Mode Commands
 
@@ -262,9 +261,6 @@ Specify supports two workflow modes that control the complexity level of the dev
 # Switch to spec mode (comprehensive development)
 /mode spec
 
-# Switch to AD mode (architecture-driven development)
-/mode ad
-
 # Show detailed information about all modes
 /mode --info
 ```
@@ -285,13 +281,6 @@ Specify supports two workflow modes that control the complexity level of the dev
 - Production systems needing comprehensive validation
 - When you need full traceability and quality gates
 
-**Use `ad` mode for:**
-
-- Complex enterprise systems requiring formal architecture documentation
-- Brownfield/modernization projects needing existing system mapping
-- Microservices architectures with multiple stakeholders
-- Systems with strict security, performance, or compliance requirements
-
 #### Mode-Aware Commands
 
 All slash commands adapt their behavior based on the current mode:
@@ -313,26 +302,26 @@ specify init my-project \
   --async-agent jules
 ```
 
-### Architecture-Driven Development (AD Mode)
+### Optional Architecture Support
 
-For complex enterprise systems, use Architecture-Driven Development to establish system-level architecture before feature implementation.
+The toolkit includes comprehensive architecture documentation support that works with both build and spec modes. Architecture commands are optional and can be used at any time, regardless of workflow mode.
 
-#### AD Mode Workflow
+#### Architecture Workflow
 
 ```bash
-# 1. Switch to AD mode
-/mode ad
-
-# 2. Initialize architecture (greenfield)
+# Initialize architecture documentation (greenfield projects)
 /speckit.architect init
 
-# 3. Or map existing codebase (brownfield)
+# Map existing codebase architecture (brownfield projects)
 /speckit.architect map
 
-# 4. Review architecture against constitution
+# Review architecture against constitution
 /speckit.architect review
 
-# 5. Then proceed with normal workflow
+# Update architecture as system evolves
+/speckit.architect update
+
+# Then proceed with normal workflow
 /speckit.specify "Feature within this architecture"
 ```
 
@@ -470,7 +459,7 @@ The `specify` command supports the following options:
 
 | Argument/Option | Type     | Description                                                                 |
 |-----------------|----------|-----------------------------------------------------------------------------|
-| `<mode>`        | Argument | Workflow mode: `build` (lightweight), `spec` (comprehensive), or `ad` (architecture-driven) - leave empty to show current mode |
+| `<mode>`        | Argument | Workflow mode: `build` (lightweight) or `spec` (comprehensive) - leave empty to show current mode |
 | `--tdd/--no-tdd` | Option | Enable/disable TDD (Test-Driven Development) |
 | `--contracts/--no-contracts` | Option | Enable/disable API contract generation |
 | `--data-models/--no-data-models` | Option | Enable/disable data model generation |
@@ -543,7 +532,6 @@ specify check
 /mode                    # Show current mode
 /mode build             # Switch to lightweight build mode
 /mode spec              # Switch to comprehensive spec mode
-/mode ad                # Switch to architecture-driven mode
 /mode --info            # Show detailed mode information
 ```
 

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-sdlc-specify-cli"
-version = "0.0.26"
+version = "0.1.0"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [

roadmap.md

@@ -114,10 +114,11 @@
 #### **Configurable Framework Options** *(100% Complete)* - **MEDIUM PRIORITY** - Addresses over-opinionated critique
 
 - ✅ **Opt-in Architecture Patterns**: TDD, contracts, data models, risk-based testing become user-configurable via `/mode` command
-- ✅ **Consolidated Configuration**: Unified `mode.json` with `options` section (renamed from `opinions.json`)
+- ✅ **Consolidated Configuration**: Unified `config.json` with `options` section
 - ✅ **Mode-Based Preferences**: Different defaults for build vs spec modes
 - ✅ **Reduced Mandatory Options**: Core workflow preserved, options made optional
 - ✅ **User-Driven Defaults**: Users can override mode defaults with custom settings
+- ✅ **Architecture Support**: Optional architecture documentation available in all modes via `/architect` commands
 
 ---
 
@@ -131,82 +132,22 @@
 - ❌ **Smart Trace Validation**: Enhanced `/analyze` claims trace detection but implementation not found
 - ❌ **Task-to-Issues Command**: Template exists but actual implementation script missing
 
-### **Architecture Description (AD) Mode** *(40% Complete)* - **HIGH PRIORITY** - Enterprise Architecture Support
-
-**Codebase Status**: Infrastructure 90% complete; critical blocker preventing user adoption. See implementation plan below.
-
-- ✅ **CLI Config Update**: AD mode in `src/specify_cli/__init__.py:433-438` with all options enabled by default.
-- ✅ **Architecture Templates**: `templates/architecture-template.md` complete with 7 Rozanski & Woods viewpoints + 2 perspectives (Security, Performance & Scalability).
-- ✅ **Architect Command**: `templates/commands/architect.md` fully implemented with init/map/update/review actions + handoffs.
-- ✅ **Setup Scripts (Bash)**: `scripts/bash/setup-architecture.sh` (449 lines) with tech detection, directory mapping, API scanning - production-ready.
-- ✅ **Setup Scripts (PS1)**: `scripts/powershell/setup-architecture.ps1` - PowerShell equivalent complete.
-- ✅ **Mode Documentation**: `templates/commands/mode.md:128-138` - AD mode workflow fully documented with use cases and artifacts.
-- ✅ **Codebase Mapper (/map)**: `/architect map` action fully implemented with language, framework, database, and infrastructure detection for brownfield projects. **[DESIGN DECISION LOCKED - Option A]**: Detects technologies and **populates `architecture.md` Section C** (Tech Stack Summary) directly. Single source of truth: `architecture.md` Section C (no separate `tech-stack.md` file). Enables Constitution validation against architecture.
-- ⚠️ **Plan Script Updates**: `scripts/bash/setup-plan.sh:46` hardcoded to `plan-template.md` - **MISSING MODE DETECTION** (critical blocker).
-- ⚠️ **plan-template-ad.md**: **DOES NOT EXIST** - template file missing (blocks schema generation guidance).
-- ❌ **Mode Detection Utility**: No `get_current_mode()` function in `scripts/bash/common.sh` - needed by setup-plan.sh.
-- ❌ **Schema Generation** *(ThoughtWorks SDD - Executable Specifications)*: Enhance `plan` templates in AD mode to explicitly output standard schema formats (OpenAPI, JSON Schema, AsyncAPI) into the `contracts/` folder, making the spec "executable." Templates exist but no generation logic or `/contracts/` scaffolding. **Phase 2 feature (design + decision required)**.
-- ❌ **Spec-Code Drift Detector** *(ThoughtWorks SDD - Drift Detection)*: No drift detection in `/analyze` command. **Phase 3 feature (design + decision required)**.
-
-**🎯 AD Mode Implementation Plan** *(3-Phase Critical Path - See Below)*
-
-| Phase | Duration | Blocker | Result |
-|-------|----------|---------|--------|
-| **Phase 1: Enable AD Mode** | 2-3 days | Mode detection + templates | Users can use `/mode ad` → `/plan` → get AD-specific template |
-| **Phase 2: Schema Generation** | 3-4 days | Format decisions (OpenAPI? + JSON Schema?) | `/contracts/openapi.yaml` + schema generation working |
-| **Phase 3: Drift Detection** | 4-5 days | Scope decisions (API only?) | `/analyze` reports spec-code misalignment |
-
-**Phase 1 Tasks (CRITICAL - Must Complete First)**:
-1. Add `get_current_mode()` function to `scripts/bash/common.sh` (2-3 hours)
-2. Update `scripts/bash/setup-plan.sh` with mode detection logic (1-2 hours)
-3. Create `templates/plan-template-ad.md` with schema guidance (3-4 hours)
-4. Add `Get-CurrentMode` to `scripts/powershell/common.ps1` (2-3 hours)
-5. Update `scripts/powershell/setup-plan.ps1` with mode detection (1-2 hours)
-6. Update `src/specify_cli/__init__.py` help text to mention AD mode (1 hour)
-7. **[NEW] Modify `scripts/bash/setup-architecture.sh` action_map()** to populate `architecture.md` Section C (2-3 hours)
-   - Parse architecture.md and locate Section C: Tech Stack Summary
-   - Replace [PLACEHOLDER] values with detected technologies
-   - Update architecture.md directly (single source of truth)
-   - **REMOVE tech-stack.md generation** (no separate inventory file)
-   - Add PowerShell equivalent in `scripts/powershell/setup-architecture.ps1`
-
-**Total Phase 1: ~12-17 hours (~3 days)** (was 10-13 hours; design improvement adds proper integration)
-
-**Phase 2 Decisions (Before Implementation)**:
-- Which schema formats? (Recommendation: OpenAPI 3.1 + JSON Schema)
-- When to generate? (Recommendation: On-demand + optional auto during /plan)
-- How to generate? (Recommendation: AI generation from plan.md description)
-
-**Phase 3 Decisions (Before Implementation)**:
-- Drift scope? (Recommendation: API endpoints focus, expand to database later)
-- Detection strategy? (Recommendation: Language-specific pattern matching)
-- Integration? (Recommendation: Both auto in /analyze + on-demand command)
-
-**🎯 CRITICAL DESIGN DECISION - SINGLE SOURCE OF TRUTH FOR TECH STACK** *(User-Identified & Locked)*:
-
-**Issue Identified**: architecture.md already has Section C (Tech Stack Summary), but `/architect map` was creating separate `memory/tech-stack.md` → redundancy and broken Constitution validation.
-
-**Decision LOCKED - Option A** ✅:
-- `/architect map` detects tech from codebase (existing ✅)
-- **POPULATES `architecture.md` Section C directly** (NEW)
-- **NO separate `tech-stack.md` file** (removed from design)
-- **Single source of truth**: `architecture.md` Section C
-- **Constitution can validate** against official architecture doc
-
-**Rationale**:
-- ✅ One authoritative system design document (architecture.md)
-- ✅ Constitution validation path clear (references architecture.md Section C)
-- ✅ Complete architecture docs (no [PLACEHOLDER] format)
-- ✅ Phases 2 & 3 can reference unified tech context
-- ✅ Easier maintenance (no file sync needed)
-
-**Implementation Impact**:
-- Phase 1 Task 7 (NEW): Modify setup-architecture.sh action_map() to populate architecture.md Section C
-- Phase 1F adds 2-3 hours → total Phase 1 now 12-17 hours
-- Both Bash and PowerShell scripts updated
-
-**Phase 2 Benefit**: Schema generation references architecture.md Section C for tech context
-**Phase 3 Benefit**: /analyze validates code against architecture.md Section C AND constitution
+### **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.
+
+- ✅ **Architecture Templates**: Complete Rozanski & Woods 7 viewpoints + 2 perspectives (Security, Performance & Scalability)
+- ✅ **Architect Command**: `/architect` with init/map/update/review actions fully implemented
+- ✅ **Setup Scripts**: Both bash and PowerShell implementations complete
+- ✅ **Brownfield Support**: `/architect map` detects technologies and populates `architecture.md` Section C directly
+- ✅ **Mode Integration**: Architecture commands available in both build and spec modes
+- ✅ **Silent Operation**: No errors or warnings when architecture.md missing
+- ✅ **Constitution Support**: Optional project principles via `/constitution` command
+- ✅ **Single Source of Truth**: `architecture.md` Section C contains tech stack (no separate files)
+
+**Future Enhancements** *(Deferred - Not Blocking)*:
+- **Schema Generation** *(ThoughtWorks SDD - Executable Specifications)*: Auto-generate OpenAPI/JSON Schema from plan.md into `contracts/` folder
+- **Spec-Code Drift Detector** *(ThoughtWorks SDD - Drift Detection)*: Automated detection of spec-code misalignment in `/analyze` command
 
 ---
 
@@ -402,6 +343,8 @@
 - ❌ **Mode Compatibility Validation**: Ensure feature modes are compatible with project infrastructure
 - ❌ **Mode Migration Support**: Tools to change feature modes mid-development
 
+**Note**: Architecture support is now available in all modes, not tied to specific workflow modes.
+
 #### **Issue Tracker Automation** *(0% Complete)* - **FUTURE ENHANCEMENT** - Separate from documentation updates
 
 - ❌ **Automated Status Updates**: Sync documentation changes with issue status (GitHub/Jira/Linear)
@@ -508,10 +451,12 @@
 3. **HIGH**: Levelup command build mode compatibility (0% → 100%) - AI session context management blocker (depends on #2)
 4. **HIGH**: Persistent issue ID storage enhancement (0% → 100%) - Issue-tracker-first workflow improvement
 5. **HIGH**: Build Mode "GSD" Upgrade (0% → 100%) - High-velocity execution mode (depends on #2)
-6. **HIGH**: Architecture Description (AD) Mode - Phase 1 (40% → 100%) - **CRITICAL BLOCKER: Mode detection + plan-template-ad.md** (2-3 days work unlocks enterprise architecture support)
-   - Phase 1 (2-3 days): Mode detection utility + plan-template-ad.md → AD mode becomes USABLE
-   - Phase 2 (3-4 days): Schema generation design + implementation → EXECUTABLE SPECIFICATIONS
-   - Phase 3 (4-5 days): Drift detection design + implementation → SPEC-CODE SYNC
+6. **COMPLETED**: Optional Architecture Support (100%) - Architecture commands now available in all modes
+   - ✅ Mode detection utilities implemented (get_current_mode functions)
+   - ✅ Architecture loading matches constitution pattern
+   - ✅ Silent operation - no warnings when files missing
+   - ⏭️  Schema generation (deferred - future enhancement)
+   - ⏭️  Drift detection (deferred - future enhancement)
 7. **MEDIUM**: Context Intelligence & Optimization (0% → 100%) - Directives scanner + compliance validation
 8. **MEDIUM**: Multi-tracker task-to-issues extension (0% → 100%) - Enhanced traceability across platforms
 9. **MEDIUM**: Spec management & cleanup (0% → 100%) - Workflow maintenance

scripts/bash/common.sh

@@ -13,6 +13,30 @@ get_global_config_path() {
     echo "$config_home/specify/config.json"
 }
 
+# Get current workflow mode from global config (build or spec)
+# Defaults to "spec" if config doesn't exist or mode is invalid
+get_current_mode() {
+    local config_file
+    config_file=$(get_global_config_path)
+    
+    # Default to spec mode if no config exists
+    if [[ ! -f "$config_file" ]] || ! command -v jq >/dev/null 2>&1; then
+        echo "spec"
+        return
+    fi
+    
+    # Read mode from config, default to spec
+    local mode
+    mode=$(jq -r '.workflow.current_mode // "spec"' "$config_file" 2>/dev/null)
+    
+    # Validate mode (only build or spec allowed, treat "ad" as spec for migration)
+    if [[ "$mode" == "build" || "$mode" == "spec" ]]; then
+        echo "$mode"
+    else
+        echo "spec"  # Fallback for invalid values including "ad"
+    fi
+}
+
 load_team_directives_config() {
     local repo_root="$1"
 

scripts/bash/setup-plan.sh

@@ -42,8 +42,15 @@ fi
 # Ensure the feature directory exists
 mkdir -p "$FEATURE_DIR"
 
-# Copy plan template if it exists
-TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
+# Detect current workflow mode and select appropriate plan template
+CURRENT_MODE=$(get_current_mode)
+
+if [[ "$CURRENT_MODE" == "build" ]]; then
+    TEMPLATE="$REPO_ROOT/.specify/templates/plan-template-build.md"
+else
+    TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
+fi
+
 if [[ -f "$TEMPLATE" ]]; then
     cp "$TEMPLATE" "$IMPL_PLAN"
     echo "Copied plan template to $IMPL_PLAN"
@@ -90,10 +97,21 @@ else
     TEAM_DIRECTIVES_DIR=""
 fi
 
+# Resolve architecture path (prefer env override, silent if missing)
+ARCHITECTURE_FILE="${SPECIFY_ARCHITECTURE:-}"
+if [[ -z "$ARCHITECTURE_FILE" ]]; then
+    ARCHITECTURE_FILE="$REPO_ROOT/.specify/memory/architecture.md"
+fi
+if [[ -f "$ARCHITECTURE_FILE" ]]; then
+    export SPECIFY_ARCHITECTURE="$ARCHITECTURE_FILE"
+else
+    ARCHITECTURE_FILE=""
+fi
+
 # Output results
 if $JSON_MODE; then
-    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s","CONSTITUTION":"%s","TEAM_DIRECTIVES":"%s","CONTEXT_FILE":"%s"}\n' \
-        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT" "$CONSTITUTION_FILE" "$TEAM_DIRECTIVES_DIR" "$CONTEXT_FILE"
+    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s","CONSTITUTION":"%s","TEAM_DIRECTIVES":"%s","ARCHITECTURE":"%s","CONTEXT_FILE":"%s"}\n' \
+        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT" "$CONSTITUTION_FILE" "$TEAM_DIRECTIVES_DIR" "$ARCHITECTURE_FILE" "$CONTEXT_FILE"
 else
     echo "FEATURE_SPEC: $FEATURE_SPEC"
     echo "IMPL_PLAN: $IMPL_PLAN" 
@@ -110,6 +128,11 @@ else
     else
         echo "TEAM_DIRECTIVES: (missing)"
     fi
+    if [[ -n "$ARCHITECTURE_FILE" ]]; then
+        echo "ARCHITECTURE: $ARCHITECTURE_FILE"
+    else
+        echo "ARCHITECTURE: (missing)"
+    fi
     echo "CONTEXT_FILE: $CONTEXT_FILE"
 fi