Universal Spec Architect

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:

   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:

   {
     "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:

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