feat: worflow modes

Author: kanfil

.specify/config/mode.json

@@ -0,0 +1,16 @@
+{
+  "current_mode": "spec",
+  "default_mode": "spec",
+  "mode_history": [
+    {
+      "timestamp": null,
+      "from_mode": "spec",
+      "to_mode": "build"
+    },
+    {
+      "timestamp": null,
+      "from_mode": "build",
+      "to_mode": "spec"
+    }
+  ]
+}

README.md

@@ -228,6 +228,55 @@ specify init my-project --debug
 specify init my-project --github-token $GITHUB_TOKEN
 ```
 
+### Workflow Mode Management
+
+Specify supports two workflow modes that control the complexity level of the development process:
+
+#### Available Modes
+
+- **`spec` mode (default)**: Full structured specification with comprehensive requirements, research, and validation
+- **`build` mode**: Lightweight, conversational approach focused on quick validation and exploration
+
+#### Mode Commands
+
+```bash
+# Show current mode and available options
+specify mode
+
+# Switch to build mode (lightweight development)
+specify mode build
+
+# Switch to spec mode (comprehensive development)
+specify mode spec
+
+# Show detailed information about all modes
+specify mode --info
+```
+
+#### When to Use Each Mode
+
+**Use `build` mode for:**
+- Prototyping and exploration
+- Simple features with clear requirements
+- Quick validation of ideas
+- When you want to get something working fast
+
+**Use `spec` mode for:**
+- Complex features requiring thorough analysis
+- Team collaboration with detailed documentation
+- Production systems needing comprehensive validation
+- When you need full traceability and quality gates
+
+#### Mode-Aware Commands
+
+All slash commands adapt their behavior based on the current mode:
+
+- **`/speckit.specify`**: Build mode uses simplified templates, spec mode uses comprehensive validation
+- **`/speckit.clarify`**: Build mode limits questions to 2, spec mode allows up to 5
+- **`/speckit.plan`**: Build mode creates lightweight plans, spec mode includes full research
+- **`/speckit.implement`**: Build mode focuses on core functionality, spec mode includes comprehensive quality gates
+- **`/speckit.analyze`**: Auto-detects pre vs post-implementation context based on project state
+
 #### Complete Example
 
 ```bash
@@ -319,6 +368,7 @@ The `specify` command supports the following options:
 |-------------|----------------------------------------------------------------|
 | `init`      | Initialize a new Specify project from the latest template      |
 | `check`     | Check for installed tools (`git`, `claude`, `gemini`, `code`/`code-insiders`, `cursor-agent`, `windsurf`, `qwen`, `opencode`, `codex`) |
+| `mode`      | Manage workflow modes (build/spec) for development complexity control |
 
 ### `specify init` Arguments & Options
 
@@ -338,9 +388,16 @@ The `specify` command supports the following options:
 | `--issue-tracker`            | Option   | Issue tracker MCP: `github`, `jira`, `linear`, `gitlab`                    |
 | `--async-agent`              | Option   | Async agent MCP: `jules`, `async-copilot`, `async-codex`                   |
 | `--gateway-url`              | Option   | Central LLM gateway URL                                                    |
-| `--gateway-token`            | Option   | Gateway authentication token                                               |
+| `--gateway-token`             | Option   | Gateway authentication token                                               |
 | `--gateway-suppress-warning` | Flag     | Suppress gateway warning messages                                          |
 
+### `specify mode` Arguments & Options
+
+| Argument/Option | Type     | Description                                                                 |
+|-----------------|----------|-----------------------------------------------------------------------------|
+| `<mode>`        | Argument | Workflow mode: `build` (lightweight) or `spec` (comprehensive) - leave empty to show current mode |
+| `--info`, `-i`  | Flag     | Show detailed information about available modes                             |
+
 ### Examples
 
 ```bash
@@ -392,6 +449,12 @@ specify init enterprise-app --ai claude --script sh --team-ai-directives https:/
 
 # Check system requirements
 specify check
+
+# Workflow mode management
+specify mode                    # Show current mode
+specify mode build             # Switch to lightweight build mode
+specify mode spec              # Switch to comprehensive spec mode
+specify mode --info            # Show detailed mode information
 ```
 
 ### Available Slash Commands

docs/quickstart.md

@@ -10,6 +10,29 @@ This guide will help you get started with Spec-Driven Development using Agentic
 **Note:** Run these steps in a standard terminal before opening the Intelligent IDE.  
 **Alignment with 12 Factors:** This stage establishes the foundation guided by [I. Strategic Mindset](https://tikalk.github.io/agentic-sdlc-12-factors/content/strategic-mindset.html) and [II. Context Scaffolding](https://tikalk.github.io/agentic-sdlc-12-factors/content/context-scaffolding.html), positioning the developer as orchestrator and assembling necessary context for AI collaboration.
 
+### Choose Your Workflow Mode
+
+Specify supports two workflow modes that control development complexity:
+
+- **`spec` mode (default)**: Full structured development with comprehensive requirements, research, and validation
+- **`build` mode**: Lightweight approach focused on quick implementation and exploration
+
+```bash
+# Check current mode
+specify mode
+
+# Switch to lightweight mode for prototyping
+specify mode build
+
+# Switch to comprehensive mode for production features
+specify mode spec
+
+# Learn more about modes
+specify mode --info
+```
+
+**Recommendation:** Start with `build` mode for exploration, switch to `spec` mode when features become complex or need thorough documentation.
+
 1. **Project Initialization (`/init`)**  
    **Action:** From the project root, run the Agentic SDLC Spec Kit `init` command (e.g., `specify init <project> --team-ai-directives https://github.com/your-org/team-ai-directives.git`) to configure local settings and clone the shared `team-ai-directives` modules.  
    **Purpose:** Creates the handshake that brings the repository into the managed Agentic SDLC ecosystem, wiring credentials, endpoints, and shared knowledge needed for subsequent commands.
@@ -109,6 +132,8 @@ This guide will help you get started with Spec-Driven Development using Agentic
 
 Initialize your project depending on the coding agent you're using:
 
+> **Note:** All slash commands adapt their behavior based on your current workflow mode. Use `specify mode` to check or change modes.
+
 ```bash
 uvx --from git+https://github.com/github/agentic-sdlc-spec-kit.git specify init <PROJECT_NAME>
 ```
@@ -213,6 +238,35 @@ implement specs/002-create-taskify/plan.md
 - **Iterate and refine** your specifications before implementation
 - **Validate** the plan before coding begins
 - **Let the AI agent handle** the implementation details
+- **Choose your complexity level** with workflow modes (build for speed, spec for thoroughness)
+
+## Mode Transitions
+
+Your development needs may change as features evolve:
+
+### When to Switch from Build to Spec Mode
+
+```bash
+specify mode spec
+```
+
+**Indicators:**
+- Feature scope is growing beyond initial expectations
+- Multiple stakeholders need detailed documentation
+- Production deployment requires comprehensive testing
+- Integration with existing systems becomes complex
+
+### When to Switch from Spec to Build Mode
+
+```bash
+specify mode build
+```
+
+**Indicators:**
+- Shifting to exploratory prototyping
+- Need to quickly validate a technical approach
+- Working on throwaway proof-of-concepts
+- Time pressure requires simplified process
 
 ## Next Steps