nold-ai · djm81 · Feb 6, 2026 · Feb 6, 2026 · Feb 6, 2026 · Feb 6, 2026
diff --git a/.github/workflows/claude-code-review.yml b/.github/workflows/claude-code-review.yml
@@ -1,14 +1,12 @@
 name: Claude Code Review
 
 on:
-  pull_request:
-    types: [opened, synchronize, ready_for_review, reopened]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
+  workflow_dispatch:
+    inputs:
+      pull_request_number:
+        description: "Pull request number to review"
+        required: true
+        type: string
 
 jobs:
   claude-review:
@@ -38,7 +36,6 @@ jobs:
           claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
           plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
           plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
+          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ inputs.pull_request_number }}'
           # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
           # or https://code.claude.com/docs/en/cli-reference for available options
-
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,6 +9,26 @@ All notable changes to this project will be documented in this file.
 
 ---
 
+## [0.29.0] - 2026-02-06
+
+### Added (0.29.0)
+
+- **Module lifecycle management and dependency safety** (OpenSpec change `arch-03-module-lifecycle-management`, fixes [#203](https://github.com/nold-ai/specfact-cli/issues/203))
+  - Added module manifest lifecycle validation for dependency integrity and CLI core compatibility (`core_compatibility`) during command registration.
+  - Added module lifecycle UX in `specfact init`: `--list-modules`, interactive arrow-key enable/disable selection in interactive mode, and explicit-id enforcement in non-interactive mode.
+  - Added force-mode dependency cascades:
+    - `--force` disable cascades to enabled dependents.
+    - `--force` enable cascades to required upstream dependencies.
+  - Added `specfact init ide` for dedicated IDE prompt/template setup, while keeping `specfact init` bootstrap/module-lifecycle focused.
+
+### Changed (0.29.0)
+
+- **Interaction default behavior**: Updated runtime prompt auto-detection to be interactive-by-default in interactive terminals, while remaining non-interactive in CI/non-interactive environments.
+- **Docs**: Updated README and docs reference pages for the new init/init-ide split, module lifecycle behavior, and roadmap positioning for future granular module enhancements and planned third-party/community module installation.
+- **Version**: Bumped to 0.29.0 (minor: new lifecycle features and UX improvements, backward compatible).
+
+---
+
 ## [0.28.0] - 2026-02-06
 
 ### Added (0.28.0)

diff --git a/README.md b/README.md
@@ -31,12 +31,16 @@ uvx specfact-cli@latest
 pip install -U specfact-cli
 ```
 
-### Initialize IDE Integration (optional but recommended)
+### Bootstrap and IDE Setup
 
 ```bash
+# Bootstrap module registry and local config (~/.specfact)
 specfact init
-specfact init --ide cursor
-specfact init --ide vscode
+
+# Configure IDE prompts/templates (interactive selector by default)
+specfact init ide
+specfact init ide --ide cursor
+specfact init ide --ide vscode
 ```
 
 ### Run Your First Flow
@@ -134,6 +138,34 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 - **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear
 - **Contracts**: Specmatic, OpenAPI
 
+### Module Lifecycle Baseline
+
+SpecFact now has a lifecycle-managed module system:
+
+- `specfact init` is bootstrap-first: initializes local CLI state, discovers installed modules, and reports prompt status.
+- `specfact init ide` handles IDE prompt/template sync and IDE settings updates.
+- `specfact init --list-modules` shows effective enabled/disabled state.
+- `specfact init --enable-module` / `--disable-module` support:
+  - interactive selection in interactive terminals when no module id is provided
+  - explicit ids in non-interactive mode (for automation)
+  - dependency-aware safety checks with `--force` cascading enable/disable behavior
+- Module manifests support dependency and core-version compatibility enforcement at registration time.
+
+This lifecycle model is the baseline for future granular module updates and enhancements. Module installation from third-party or open-source community providers is planned, but not implemented yet.
+
+---
+
+## Developer Note: Command Layout
+
+- Primary command implementations live in `src/specfact_cli/modules/<module>/src/commands.py`.
+- Legacy imports from `src/specfact_cli/commands/*.py` are compatibility shims and only guarantee `app` re-exports.
+- Preferred imports for module code:
+  - `from specfact_cli.modules.<module>.src.commands import app`
+  - `from specfact_cli.modules.<module>.src.commands import <symbol>`
+- Shim deprecation timeline:
+  - Legacy shim usage is deprecated for non-`app` symbols now.
+  - Shim removal is planned no earlier than `v0.30` (or the next major migration window).
+
 ---
 
 ## Developer Note: Command Layout

diff --git a/docs/README.md b/docs/README.md
@@ -58,6 +58,18 @@ Most tools help **either** coders **or** agile teams. SpecFact does both:
 - **Backlogs**: GitHub Issues, Azure DevOps, Jira, Linear
 - **Contracts**: Specmatic, OpenAPI
 
+## Module Lifecycle System
+
+SpecFact CLI uses a lifecycle-managed module system:
+
+- `specfact init` bootstraps local state and manages module enable/disable lifecycle.
+- `specfact init ide` handles IDE prompt/template installation and updates.
+- `specfact init --list-modules` shows current enabled/disabled state.
+- `--enable-module` and `--disable-module` support interactive selection in interactive terminals and explicit ids in non-interactive mode.
+- Dependency and compatibility guards prevent invalid module states; `--force` enables dependency-aware cascades.
+
+This is the baseline for future granular module updates and enhancements. Third-party/community module installation is planned, but not available yet.
+
 ---
 
 ## Documentation Sections

diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md
@@ -90,7 +90,7 @@ specfact import from-code my-project --repo .
 specfact --mode copilot import from-code my-project --repo .
 
 # IDE integration (slash commands)
-# First, initialize: specfact init --ide cursor
+# First, initialize: specfact init ide --ide cursor
 # Then use in IDE chat:
 /specfact.01-import legacy-api --repo . --confidence 0.7
 /specfact.02-plan init legacy-api
@@ -541,7 +541,7 @@ class ChangeArchive(BaseModel):
 - **Manifest**: Each package has a `module-package.yaml` with:
   - `name`, `version`, `commands` (list of command names the package provides)
   - optional `command_help` (name → short help for root `specfact --help`)
-  - optional `pip_dependencies`, `module_dependencies`, `tier` (e.g. community/enterprise), `addon_id`
+  - optional `pip_dependencies`, `module_dependencies`, `core_compatibility`, `tier` (e.g. community/enterprise), `addon_id`
 - **Entry point**: Each package has `src/app.py` that exposes a Typer `app` by importing from module-local `src/commands.py`.
 
 ### Legacy shim policy and timeline
@@ -557,7 +557,20 @@ class ChangeArchive(BaseModel):
 
 - **File**: `~/.specfact/registry/modules.json` (created when you run `specfact init`).
 - **Content**: List of `{ "id", "version", "enabled" }` per module. Only modules with `enabled: true` have their commands registered.
-- **CLI**: `specfact init --enable-module <id>` and `--disable-module <id>` update this state and persist it to `modules.json`.
+- **CLI**:
+  - `specfact init --list-modules` shows effective state.
+  - `specfact init --enable-module <id>` and `--disable-module <id>` update persisted state.
+  - In interactive terminals, `specfact init --enable-module` and `specfact init --disable-module` (without ids) open an interactive selector.
+  - In non-interactive mode, explicit module ids are required.
+  - Safe dependency guards block invalid enable/disable actions unless `--force` is used.
+  - With `--force`, enable cascades to required dependencies and disable cascades to enabled dependents.
+
+### Lifecycle notes and roadmap
+
+- `specfact init` is bootstrap/module-lifecycle focused.
+- `specfact init ide` is responsible for IDE prompt/template setup.
+- This lifecycle architecture is the baseline for future granular module updates and enhancements.
+- Third-party/community module installation is planned as a next step, but not implemented yet.
 
 ### Registry package layout
 

diff --git a/docs/reference/commands.md b/docs/reference/commands.md
@@ -69,7 +69,7 @@ specfact auth status
 
 - `--input-format {yaml,json}` - Override default structured input detection for CLI commands (defaults to YAML)
 - `--output-format {yaml,json}` - Control how plan bundles and reports are written (JSON is ideal for CI/copilot automations)
-- `--interactive/--no-interactive` - Force prompt behavior (overrides auto-detection from CI/CD vs Copilot environments)
+- `--interactive/--no-interactive` - Force prompt behavior (default auto-detection from terminal + CI environment)
 
 ### Commands by Workflow
 
@@ -176,7 +176,8 @@ specfact auth status
 
 **Setup & Maintenance:**
 
-- `init` - Initialize IDE integration
+- `init` - Bootstrap CLI local state and manage enabled/disabled modules
+- `init ide` - Initialize IDE prompt/template integration
 - `upgrade` - Check for and install CLI updates
 
 **⚠️ Deprecated (v0.17.0):**
@@ -540,7 +541,7 @@ When working with multiple projects in a single repository, external tool integr
 
 - Use `--entry-point` to analyze each project separately
 - Create separate project bundles for each project (`.specfact/projects/<bundle-name>/`)
-- Run `specfact init` from the repository root to ensure IDE integration works correctly (templates are copied to root-level `.github/`, `.cursor/`, etc. directories)
+- Run `specfact init ide` from the repository root to ensure IDE integration works correctly (templates are copied to root-level `.github/`, `.cursor/`, etc. directories)
 
 ---
 
@@ -4717,65 +4718,99 @@ Replace `implement tasks` with the new AI IDE bridge workflow:
 
 ---
 
-### `init` - Initialize IDE Integration
+### `init` - Bootstrap and Module Lifecycle Management
 
-Set up SpecFact CLI for IDE integration by copying prompt templates to IDE-specific locations.
+Bootstrap SpecFact local state and manage enabled/disabled command modules.
 
 ```bash
 specfact init [OPTIONS]
 ```
 
-**Options:**
+**Common options:**
 
 - `--repo PATH` - Repository path (default: current directory)
-- `--force` - Overwrite existing files
-- `--install-deps` - Install required packages for contract enhancement (beartype, icontract, crosshair-tool, pytest) via pip
+- `--list-modules` - Show discovered modules with effective enabled/disabled state and exit
+- `--enable-module TEXT` - Enable module by id (repeatable)
+- `--disable-module TEXT` - Disable module by id (repeatable)
+- `--force` - Override dependency guards; cascades dependency updates
 
-**Advanced Options** (hidden by default, use `--help-advanced` or `-ha` to view):
+**Interactive behavior:**
+
+- Default mode is auto-detected from terminal + CI environment.
+- In interactive terminals, passing `--enable-module` or `--disable-module` without ids opens an arrow-key selector.
+- In non-interactive mode, module ids are required (for example in CI/CD).
 
-- `--ide TEXT` - IDE type (auto, cursor, vscode, copilot, claude, gemini, qwen, opencode, windsurf, kilocode, auggie, roo, codebuddy, amp, q) (default: auto)
+**Dependency-aware behavior:**
+
+- Safe disable blocks disabling a module that is required by other enabled modules.
+- Safe enable blocks enabling a module when required dependencies are disabled.
+- `--force` performs dependency-aware cascading:
+  - disable cascades to enabled dependents
+  - enable cascades to required dependencies
 
 **Examples:**
 
 ```bash
-# Auto-detect IDE
+# Bootstrap only (no IDE prompt/template copy)
 specfact init
 
-# Specify IDE explicitly
-specfact init --ide cursor
-specfact init --ide vscode
-specfact init --ide copilot
+# List lifecycle state
+specfact init --list-modules
 
-# Force overwrite existing files
-specfact init --ide cursor --force
+# Interactive selection (TTY)
+specfact init --enable-module
+specfact init --disable-module
 
-# Install required packages for contract enhancement
-specfact init --install-deps
+# Non-interactive explicit ids
+specfact --no-interactive init --enable-module backlog
+specfact --no-interactive init --disable-module upgrade
 
-# Initialize IDE integration and install dependencies
-specfact init --ide cursor --install-deps
+# Force dependency cascade
+specfact init --enable-module sync --force
+specfact init --disable-module plan --force
 ```
 
 **What it does:**
 
-1. Detects your IDE (or uses `--ide` flag)
-2. Copies prompt templates from `resources/prompts/` to IDE-specific location **at the repository root level**
-3. Creates/updates VS Code settings.json if needed (for VS Code/Copilot)
-4. Makes slash commands available in your IDE
-5. **Copies default ADO field mapping templates** to `.specfact/templates/backlog/field_mappings/` for review and customization:
-   - `ado_default.yaml` - Default field mappings
-   - `ado_scrum.yaml` - Scrum process template mappings
-   - `ado_agile.yaml` - Agile process template mappings
-   - `ado_safe.yaml` - SAFe process template mappings
-   - `ado_kanban.yaml` - Kanban process template mappings
-   - Templates are only copied if they don't exist (use `--force` to overwrite)
-6. Optionally installs required packages for contract enhancement (if `--install-deps` is provided):
-   - `beartype>=0.22.4` - Runtime type checking
-   - `icontract>=2.7.1` - Design-by-contract decorators
-   - `crosshair-tool>=0.0.97` - Contract exploration
-   - `pytest>=8.4.2` - Testing framework
-
-**Important:** Templates are always copied to the repository root level (where `.github/`, `.cursor/`, etc. directories must reside for IDE recognition). The `--repo` parameter specifies the repository root path. For multi-project codebases, run `specfact init` from the repository root to ensure IDE integration works correctly.
+1. Initializes/updates user-level registry state under `~/.specfact/registry/`.
+2. Discovers installed modules and applies enable/disable operations.
+3. Enforces module dependency and compatibility constraints.
+4. Reports IDE prompt status and points to `specfact init ide` for prompt/template setup.
+
+### `init ide` - IDE Prompt/Template Setup
+
+Install and update prompt templates and IDE settings.
+
+```bash
+specfact init ide [OPTIONS]
+```
+
+**Options:**
+
+- `--repo PATH` - Repository path (default: current directory)
+- `--ide TEXT` - IDE type (cursor, vscode, copilot, claude, gemini, qwen, opencode, windsurf, kilocode, auggie, roo, codebuddy, amp, q, auto)
+- `--force` - Overwrite existing files
+- `--install-deps` - Install contract-enhancement dependencies (`beartype`, `icontract`, `crosshair-tool`, `pytest`)
+
+**Behavior:**
+
+- In interactive terminals, `specfact init ide` without `--ide` opens an arrow-key IDE selector.
+- In non-interactive mode, IDE auto-detection is used unless `--ide` is explicitly provided.
+- Prompt templates are copied to IDE-specific root-level locations (`.github/prompts`, `.cursor/commands`, etc.).
+
+**Examples:**
+
+```bash
+# Interactive IDE selection
+specfact init ide
+
+# Explicit IDE
+specfact init ide --ide cursor
+specfact init ide --ide vscode --force
+
+# Optional dependency installation
+specfact init ide --install-deps
+```
 
 **IDE-Specific Locations:**
 
@@ -4868,16 +4903,16 @@ Slash commands provide an intuitive interface for IDE integration (VS Code, Curs
 
 ```bash
 # Initialize IDE integration (one-time setup)
-specfact init --ide cursor
+specfact init ide --ide cursor
 
 # Or auto-detect IDE
-specfact init
+specfact init ide
 
 # Initialize and install required packages for contract enhancement
-specfact init --install-deps
+specfact init ide --install-deps
 
 # Initialize for specific IDE and install dependencies
-specfact init --ide cursor --install-deps
+specfact init ide --ide cursor --install-deps
 ```
 
 ### Usage
@@ -4903,7 +4938,7 @@ After initialization, use slash commands directly in your IDE's AI chat:
 
 **How it works:**
 
-Slash commands are **prompt templates** (markdown files) that are copied to IDE-specific locations by `specfact init`. The IDE automatically discovers and registers them as slash commands.
+Slash commands are **prompt templates** (markdown files) that are copied to IDE-specific locations by `specfact init ide`. The IDE automatically discovers and registers them as slash commands.
 
 **See [IDE Integration Guide](../guides/ide-integration.md)** for detailed setup instructions and supported IDEs.