# Universal Spec Architect — IBM Bob-a-thon Submission

## Project Purpose
The **Universal Spec Architect** is an MCP (Model Context Protocol) server designed to enforce a rigorous, spec-driven engineering workflow for AI coding assistants like IBM Bob. 

The core problem it solves is the tendency of AI assistants to jump straight into writing code without proper planning, leading to architectural drift, missed requirements, and unmaintainable codebases. This project forces the assistant to pause, think, and document before writing a single line of implementation code.

## Key Features
- **Enforced 3-Phase Workflow**: Requires the assistant to complete Requirements → Design → Tasks before coding.
- **EARS Notation Validation**: Automatically validates that all requirements follow the Easy Approach to Requirements Syntax (`[WHEN <trigger>] THE <system> SHALL <response>`).
- **Real-time Task Tracking**: Provides tools for the assistant to update task statuses (`todo`, `in_progress`, `completed`) in a centralized `tasks.md` file.
- **IBM Bob Integration**: Includes custom `.bob/modes/spec-architect.json` and `.bob/rules/spec-workflow.md` to seamlessly integrate with IBM Bob's steering mechanisms.
- **Universal Compatibility**: Works not just with IBM Bob, but also with Cline, Cursor, VS Code (Copilot), Windsurf, and Claude Desktop.

## Technical Implementation
The project is built as a Python-based MCP server using the `fastmcp` framework. 

It exposes 6 core MCP tools to the AI assistant:
1. `initialize_spec`: Scaffolds the `.specs/` directory structure.
2. `write_requirements`: Validates and writes `requirements.md`.
3. `write_design`: Structures and writes `design.md`.
4. `write_tasks`: Breaks down work into `tasks.md`.
5. `update_task_status`: Modifies task states dynamically.
6. `run_hook`: Executes lifecycle hooks (`pre_task`, `post_task`).

The server runs locally and communicates with IBM Bob via stdio using the MCP protocol.

## How to Run the Application Locally

### Prerequisites
- Python 3.11+
- `uv` package manager installed

### Installation
1. Clone this repository.
2. Install the dependencies:
   ```bash
   pip install fastmcp pydantic
   pip install -e .
   ```

### Running with IBM Bob
1. Copy the `.bob/` directory from this repository into your target project's root directory.
2. Ensure `.bob/mcp.json` points to the correct server path:
   ```json
   {
     "mcpServers": {
       "universal-spec-architect": {
         "command": "uvx",
         "args": ["fastmcp", "run", "src/universal_spec_mcp/server.py"],
         "env": { "PYTHONPATH": "src" }
       }
     }
   }
   ```
3. Open your project in VS Code with the IBM Bob extension enabled.
4. Select the **Spec Architect** mode in Bob.
5. Ask Bob to "Build a new feature" — Bob will automatically start the MCP server and begin the 3-phase workflow.

### Running Tests
To verify the MCP server logic locally:
```bash
python3 tests/test_server.py
```

## Demo Video
A 3-minute demo video will be added to this repository before final submission to the IBM Bob-a-thon org. The video will cover:
- Project structure walkthrough
- IBM Bob Spec Architect mode in action
- Generated spec artifacts (requirements, design, tasks)
- Running the test suite locally