specsoloist 0.2.0__tar.gz

specsoloist-0.2.0/.claude/settings.local.json

@@ -0,0 +1,26 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /home/toby/_code/specular log --oneline -15)",
+      "Bash(uv run pytest:*)",
+      "Bash(uv run ruff:*)",
+      "Bash(git -C /home/toby/_code/specular status)",
+      "Bash(git -C /home/toby/_code/specular log --oneline -5)",
+      "Bash(git -C /home/toby/_code/specular add -A)",
+      "Bash(git -C /home/toby/_code/specular commit -m \"$\\(cat <<''EOF''\nrefactor: extract modules and add LLM provider abstraction \\(Phase 1.5\\)\n\n- Extract parser.py: spec parsing, validation, frontmatter handling\n- Extract runner.py: test execution and build file management\n- Extract compiler.py: prompt construction and LLM code generation\n- Extract config.py: SpecularConfig with env-based loading\n- Add providers/: LLMProvider protocol with Gemini and Anthropic implementations\n- Refactor SpecularCore as thin orchestrator delegating to modules\n- Update tests to use mock provider injection pattern\n\nThis lays the foundation for Phase 2''s multi-spec architecture.\n\n🤖 Generated with [Claude Code]\\(https://claude.com/claude-code\\)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git -C /home/toby/_code/specular commit -m \"$\\(cat <<''EOF''\ndocs: update specs and roadmap for Phase 1.5 completion\n\n- Update self_hosting/specular_core.spec.md \\(The Quine\\) to reflect\n  modular architecture with all new components documented\n- Update README with multi-provider support and configuration examples\n- Update ROADMAP: add Phase 1.5 as completed, split Phase 2 into 2a/2b\n\n🤖 Generated with [Claude Code]\\(https://claude.com/claude-code\\)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git -C /home/toby/_code/specular commit -m \"$\\(cat <<''EOF''\nrefactor: clean up technical debt before Phase 2a\n\n- Move create_spec and template loading to SpecParser \\(fixes internal access smell\\)\n- Use pyyaml for proper frontmatter parsing \\(prepares for dependency syntax\\)\n- Add model override to LLMProvider.generate\\(\\) \\(makes model param actually work\\)\n- Make get_spec_path public \\(was _get_spec_path\\)\n- Add load_global_context to SpecParser\n- Make max_tokens configurable in AnthropicProvider\n- Update tests for new provider interface\n\n🤖 Generated with [Claude Code]\\(https://claude.com/claude-code\\)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git -C /home/toby/_code/specular commit -m \"$\\(cat <<''EOF''\nfeat: implement Phase 2a multi-spec architecture\n\n- Add dependency syntax in frontmatter \\(YAML list of name/from pairs\\)\n- Create DependencyResolver with topological sort for build order\n- Add CircularDependencyError and MissingDependencyError\n- Support type: typedef specs with specialized compile_typedef\\(\\)\n- Add compile_project\\(\\) for multi-spec builds in dependency order\n- Add get_build_order\\(\\) and get_dependency_graph\\(\\) for introspection\n- Add run_all_tests\\(\\) for project-wide test execution\n- Add get_affected_specs\\(\\) for incremental build support\n- Include import context in compilation prompts\n- Add examples/user_project demonstrating multi-spec dependencies\n- Add comprehensive resolver tests \\(circular deps, diamond pattern, etc.\\)\n\n🤖 Generated with [Claude Code]\\(https://claude.com/claude-code\\)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git -C /home/toby/_code/specular diff --stat)",
+      "Bash(git -C /home/toby/_code/specular commit -m \"$\\(cat <<''EOF''\nfeat: implement Phase 2b build optimization\n\n- Add manifest.py with BuildManifest and IncrementalBuilder for tracking\n  spec file hashes and build metadata \\(.specular-manifest.json\\)\n- Add incremental build support to compile_project\\(\\) - only recompiles\n  specs when content, dependencies, or dependency outputs change\n- Add parallel compilation using ThreadPoolExecutor - specs at the same\n  dependency level compile concurrently\n- Add get_parallel_build_order\\(\\) to DependencyResolver returning specs\n  grouped into parallelizable levels\n- Add specs_skipped to BuildResult for incremental build reporting\n- Update The Quine spec with Phase 2b features \\(FR-21 through FR-25\\)\n- Add comprehensive manifest tests \\(11 tests\\)\n- Add parallel build order tests \\(2 tests\\)\n\n🤖 Generated with [Claude Code]\\(https://claude.com/claude-code\\)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(uv run:*)",
+      "Bash(git -C /home/toby/_code/specular commit -m \"$\\(cat <<''EOF''\nfeat: add human-friendly CLI\n\n- Add cli.py with commands: list, create, validate, compile, test, fix, build\n- Build command supports --incremental and --parallel flags\n- Change entry point: `specular` now runs CLI, `specular-mcp` runs MCP server\n- Fix demo.py to use parser.get_spec_path\\(\\) \\(was broken after refactor\\)\n- Update README with CLI-focused quick start and reference\n\n🤖 Generated with [Claude Code]\\(https://claude.com/claude-code\\)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(git -C /home/toby/_code/specular commit -m \"$\\(cat <<''EOF''\nchore: add PyPI metadata and MIT license\n\n- Add author, license, keywords, classifiers to pyproject.toml\n- Add project URLs \\(homepage, repository, issues\\)\n- Add LICENSE file \\(MIT\\)\n- Fix GitHub URL placeholder in README\n\n🤖 Generated with [Claude Code]\\(https://claude.com/claude-code\\)\n\nCo-Authored-By: Claude <noreply@anthropic.com>\nEOF\n\\)\")",
+      "Bash(uv build:*)",
+      "Bash(unzip:*)",
+      "Bash(git -C /home/toby/_code/specular commit -m \"docs: update README with pip install instructions\")",
+      "Bash(git -C /home/toby/_code/specular commit -m \"docs: update ROADMAP and add CLAUDE.md for future sessions\")",
+      "Bash(git -C /home/toby/_code/specular log --oneline origin/main..HEAD)"
+    ]
+  }
+}

specsoloist-0.2.0/.github/workflows/ci.yaml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Set up Python
+      run: uv python install 3.10
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Run Tests
+      run: uv run pytest tests/
+
+    - name: Lint (Ruff)
+      run: uv run ruff check src/

specsoloist-0.2.0/.github/workflows/docs.yaml

@@ -0,0 +1,36 @@
+name: Deploy Documentation
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - ".github/workflows/docs.yaml"
+
+permissions:
+  contents: write
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Configure Git Credentials
+        run: |
+          git config user.name github-actions[bot]
+          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
+          
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+          
+      - name: Install dependencies
+        run: |
+          pip install mkdocs-material
+          
+      - name: Deploy to GitHub Pages
+        run: mkdocs gh-deploy --force

specsoloist-0.2.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Project Specific
+test_env/
+test_env_pytest/
+.specular/
+
+# IDEs
+.vscode/
+.idea/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class

specsoloist-0.2.0/AGENTS.md

@@ -0,0 +1,44 @@
+# Specular for Agents
+
+Specular is designed to be **Agent-Native**. It provides a set of high-level tools via the **Model Context Protocol (MCP)** that allow an AI Agent to act as a Software Architect.
+
+## The Role of the Agent
+When using Specular, the Agent's role shifts from "Writing Code" to **"Defining Behavior"**.
+*   **The Agent (Architect)**: Writes `*.spec.md` files.
+*   **Specular (Builder)**: Compiles specs to code, writes tests, runs them, and fixes low-level bugs.
+
+## MCP Toolset
+
+### 1. `create_spec(name, description, type)`
+Initializes a new component specification.
+*   *Usage*: "Create a user authentication component."
+
+### 2. `compile_spec(name)`
+Compiles the Markdown spec into source code (e.g., Python).
+*   *Usage*: "Build the auth component."
+
+### 3. `compile_tests(name)`
+Generates a test suite based on the `Test Scenarios` and `Design Contract` in the spec.
+*   *Usage*: "Generate tests for auth."
+
+### 4. `run_tests(name)`
+Executes the test suite and returns the results.
+*   *Usage*: "Verify the auth component."
+
+### 5. `attempt_fix(name)`
+Triggers the **Self-Healing Loop**. If tests fail, Specular analyzes the logs and automatically patches the Code or the Test file.
+*   *Usage*: "The tests failed. Fix it."
+
+## Example System Prompt for an Architect Agent
+
+If you are configuring a custom agent to use Specular, use this system prompt:
+
+> You are a Lead Software Architect. Your goal is to build robust software using the **Specular Framework**.
+>
+> **Rules:**
+> 1.  **Never write source code** (Python/JS) directly. Always create or edit `*.spec.md` files.
+> 2.  **Be Rigorous**: When editing specs, clearly define **Functional Requirements (FRs)** and **Design Contracts**.
+> 3.  **Iterate**:
+>     -   Create Spec -> `compile_spec` -> `compile_tests` -> `run_tests`.
+>     -   If tests fail, use `attempt_fix` first.
+>     -   If that fails, read the spec and refine the requirements.

specsoloist-0.2.0/CLAUDE.md

@@ -0,0 +1,56 @@
+# Claude Context for Specular
+
+## What is Specular?
+
+Specular is a "Spec-as-Source" AI coding framework. Users write rigorous Markdown specifications (SRS-style), and Specular uses LLMs to compile them into executable Python code with tests.
+
+**Key insight**: Code is a build artifact. Specs are source of truth.
+
+## Architecture
+
+```
+src/specular/
+├── core.py          # SpecularCore - thin orchestrator
+├── parser.py        # Spec parsing, validation, frontmatter
+├── compiler.py      # Prompt construction, LLM code generation
+├── runner.py        # Test execution, build file management
+├── resolver.py      # Dependency resolution, topological sort
+├── manifest.py      # Build caching, incremental builds
+├── config.py        # SpecularConfig, env-based loading
+├── cli.py           # Human-friendly CLI
+├── server.py        # MCP server for AI agents
+├── providers/       # LLM backends (Gemini, Anthropic)
+└── templates/       # Spec template, global context
+```
+
+## Key Commands
+
+```bash
+uv run pytest tests/           # Run tests (25 tests)
+uv run ruff check src/         # Lint
+uv run specular --help         # CLI help
+uv run specular-mcp            # Start MCP server
+```
+
+## Self-Hosting Spec ("The Quine")
+
+`self_hosting/specular_core.spec.md` is Specular's own specification - it describes itself. Keep this updated when making architectural changes.
+
+## Current State (v0.1.0)
+
+- Phases 1, 1.5, 2a, 2b, 2c complete
+- Published to PyPI as `specular-ai`
+- CLI and MCP server both functional
+- Supports Gemini and Anthropic providers
+
+## What's Next (Phase 3)
+
+See ROADMAP.md. Main items:
+- CLI polish (spinners, colors)
+- Multi-language support (TypeScript, Go)
+- Documentation site
+- Better error messages
+
+## Testing Changes
+
+Always run `uv run pytest tests/ && uv run ruff check src/` before committing.

specsoloist-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Toby Lightheart
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

specsoloist-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: specsoloist
+Version: 0.2.0
+Summary: Spec-as-Source Framework: AI-driven development where specifications are the source of truth.
+Project-URL: Homepage, https://github.com/symbolfarm/specsoloist
+Project-URL: Repository, https://github.com/symbolfarm/specsoloist
+Project-URL: Issues, https://github.com/symbolfarm/specsoloist/issues
+Author-email: Toby Lightheart <code@symbolfarm.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,code-generation,llm,mcp,specifications
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Requires-Dist: mcp>=0.1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: mkdocs-material>=9.0.0; extra == 'dev'
+Requires-Dist: mkdocs>=1.5.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# SpecSoloist
+
+**SpecSoloist** is a "Spec-as-Source" AI coding framework. It treats rigorous, SRS-style specifications as the source of truth and uses LLMs to compile them into executable code.
+
+## Why SpecSoloist?
+
+Code is often messy, poorly documented, and prone to drift from original requirements. SpecSoloist flips the script:
+
+1.  **Write Specs**: You write high-level, human-readable specifications (Markdown).
+2.  **Compile to Code**: SpecSoloist uses LLMs (Gemini/Claude) to implement the spec.
+3.  **Self-Healing**: If tests fail, SpecSoloist analyzes the failure and patches the code or tests automatically.
+
+## Installation
+
+```bash
+pip install specsoloist
+```
+
+## Quick Start
+
+1.  Clone the repository (or create a new folder):
+    ```bash
+    git clone https://github.com/symbolfarm/specsoloist.git
+    cd specsoloist
+    ```
+
+2.  Set your API Key (Gemini or Anthropic):
+    ```bash
+    export GEMINI_API_KEY="your_key_here"
+    # or
+    export ANTHROPIC_API_KEY="your_key_here"
+    ```
+
+3.  Create a new specification:
+    ```bash
+    sp create calculator "A simple calculator with add and multiply"
+    ```
+    This creates `src/calculator.spec.md`.
+
+4.  Compile it to code:
+    ```bash
+    sp compile calculator
+    ```
+    This generates `build/calculator.py` and `build/test_calculator.py`.
+
+5.  Run the tests:
+    ```bash
+    sp test calculator
+    ```
+
+6.  (Optional) If tests fail, try auto-fix:
+    ```bash
+    sp fix calculator
+    ```
+
+## The Workflow
+
+SpecSoloist isn't just a code generator; it's an architecture tool.
+
+*   **Edit Spec** -> `sp compile` -> `sp test`.
+*   **Failure?** -> `sp fix` (Let the AI patch the code).
+*   **Architecture Change?** -> Edit `src/*.spec.md`.
+
+## CLI Reference
+
+| Command | Description |
+| :--- | :--- |
+| `sp list` | List all specs in `src/` |
+| `sp create <name> <desc>` | Create a new spec from template |
+| `sp validate <name>` | Check spec structure |
+| `sp compile <name>` | Compile spec to code + tests |
+| `sp test <name>` | Run tests for a spec |
+| `sp fix <name>` | Auto-fix failing tests |
+| `sp build` | Compile all specs in dependency order |
+
+## Configuration
+
+You can configure SpecSoloist via environment variables or a `.env` file:
+
+```bash
+export SPECSOLOIST_LLM_PROVIDER="gemini"  # or "anthropic"
+export SPEC_LLM_MODEL="gemini-2.0-flash"  # optional
+```
+
+For Anthropic:
+
+```bash
+export SPECSOLOIST_LLM_PROVIDER="anthropic"
+export ANTHROPIC_API_KEY="your_key_here"
+export SPECSOLOIST_LLM_MODEL="claude-sonnet-4-20250514"  # optional
+```
+
+## Agent Integration (MCP)
+
+SpecSoloist can run as an MCP server for Claude Desktop or other AI agents:
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "specsoloist": {
+      "command": "uv",
+      "args": ["run", "specsoloist-mcp"],
+      "env": {
+        "GEMINI_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+Or use the CLI: `sp mcp`

specsoloist-0.2.0/README.md

@@ -0,0 +1,113 @@
+# SpecSoloist
+
+**SpecSoloist** is a "Spec-as-Source" AI coding framework. It treats rigorous, SRS-style specifications as the source of truth and uses LLMs to compile them into executable code.
+
+## Why SpecSoloist?
+
+Code is often messy, poorly documented, and prone to drift from original requirements. SpecSoloist flips the script:
+
+1.  **Write Specs**: You write high-level, human-readable specifications (Markdown).
+2.  **Compile to Code**: SpecSoloist uses LLMs (Gemini/Claude) to implement the spec.
+3.  **Self-Healing**: If tests fail, SpecSoloist analyzes the failure and patches the code or tests automatically.
+
+## Installation
+
+```bash
+pip install specsoloist
+```
+
+## Quick Start
+
+1.  Clone the repository (or create a new folder):
+    ```bash
+    git clone https://github.com/symbolfarm/specsoloist.git
+    cd specsoloist
+    ```
+
+2.  Set your API Key (Gemini or Anthropic):
+    ```bash
+    export GEMINI_API_KEY="your_key_here"
+    # or
+    export ANTHROPIC_API_KEY="your_key_here"
+    ```
+
+3.  Create a new specification:
+    ```bash
+    sp create calculator "A simple calculator with add and multiply"
+    ```
+    This creates `src/calculator.spec.md`.
+
+4.  Compile it to code:
+    ```bash
+    sp compile calculator
+    ```
+    This generates `build/calculator.py` and `build/test_calculator.py`.
+
+5.  Run the tests:
+    ```bash
+    sp test calculator
+    ```
+
+6.  (Optional) If tests fail, try auto-fix:
+    ```bash
+    sp fix calculator
+    ```
+
+## The Workflow
+
+SpecSoloist isn't just a code generator; it's an architecture tool.
+
+*   **Edit Spec** -> `sp compile` -> `sp test`.
+*   **Failure?** -> `sp fix` (Let the AI patch the code).
+*   **Architecture Change?** -> Edit `src/*.spec.md`.
+
+## CLI Reference
+
+| Command | Description |
+| :--- | :--- |
+| `sp list` | List all specs in `src/` |
+| `sp create <name> <desc>` | Create a new spec from template |
+| `sp validate <name>` | Check spec structure |
+| `sp compile <name>` | Compile spec to code + tests |
+| `sp test <name>` | Run tests for a spec |
+| `sp fix <name>` | Auto-fix failing tests |
+| `sp build` | Compile all specs in dependency order |
+
+## Configuration
+
+You can configure SpecSoloist via environment variables or a `.env` file:
+
+```bash
+export SPECSOLOIST_LLM_PROVIDER="gemini"  # or "anthropic"
+export SPEC_LLM_MODEL="gemini-2.0-flash"  # optional
+```
+
+For Anthropic:
+
+```bash
+export SPECSOLOIST_LLM_PROVIDER="anthropic"
+export ANTHROPIC_API_KEY="your_key_here"
+export SPECSOLOIST_LLM_MODEL="claude-sonnet-4-20250514"  # optional
+```
+
+## Agent Integration (MCP)
+
+SpecSoloist can run as an MCP server for Claude Desktop or other AI agents:
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "specsoloist": {
+      "command": "uv",
+      "args": ["run", "specsoloist-mcp"],
+      "env": {
+        "GEMINI_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+Or use the CLI: `sp mcp`

specsoloist-0.2.0/ROADMAP.md

@@ -0,0 +1,44 @@
+# Specular Roadmap
+
+## Phase 1: Core Framework & Self-Healing (Completed)
+- [x] **Spec-as-Source**: Define components using rigorous SRS-style Markdown.
+- [x] **LLM Compilation**: Compile specs to Python code using Google Gemini.
+- [x] **Test Generation**: Automatically generate `pytest` suites from spec scenarios.
+- [x] **Integrated Runner**: Run tests in isolated environments.
+- [x] **Agentic Self-Healing**: `attempt_fix` loop that analyzes failures and patches code/tests.
+- [x] **MCP Server**: Expose all tools via the Model Context Protocol.
+
+## Phase 1.5: Foundation Hardening (Completed)
+- [x] **Code Separation**: Extract specialized modules (parser, compiler, runner, config).
+- [x] **LLM Provider Abstraction**: `LLMProvider` protocol with Gemini and Anthropic implementations.
+- [x] **Configuration System**: `SpecularConfig` with environment-based loading.
+- [x] **Thin Orchestrator**: Refactor `SpecularCore` to delegate to specialized modules.
+- [x] **Updated Self-Hosting Spec**: The Quine updated to reflect new architecture.
+
+## Phase 2a: Multi-Spec Architecture (Completed)
+- [x] **Dependency Syntax**: YAML frontmatter syntax for declaring spec dependencies.
+- [x] **Dependency Graph**: `DependencyResolver` with topological sort for build order.
+- [x] **Type Specs**: Support `type: typedef` specs with specialized compilation.
+- [x] **Multi-Spec Builds**: `compile_project()` compiles all specs in dependency order.
+- [x] **Affected Specs**: Track which specs need rebuilding when a dependency changes.
+
+## Phase 2b: Build Optimization (Completed)
+- [x] **Incremental Builds**: Only recompile specs that have changed.
+- [x] **Build Caching**: Track file hashes and build manifest (`.specular-manifest.json`).
+- [x] **Parallel Compilation**: Compile independent specs concurrently using `ThreadPoolExecutor`.
+
+## Phase 2c: Release Prep (Completed)
+- [x] **Human CLI**: `specular` command with list, create, compile, test, fix, build commands.
+- [x] **PyPI Publication**: Released `specular-ai` v0.1.0 to PyPI.
+
+## Phase 3: Polish (Completed)
+- [x] **CLI Polish**: Rich terminal output (spinners, tables, colored panels).
+- [x] **Multi-Language Support**: Config-driven runner with TypeScript support (via `tsx` and `node:test`).
+- [x] **Documentation Site**: MkDocs Material site with "Leaves-Up" workflow guide.
+- [x] **Error Handling**: Friendly messages for circular dependencies and missing API keys.
+
+## Phase 4: Developer Experience (Future)
+- [ ] **Sandboxed Execution**: Run generated code in Docker containers for safety.
+- [ ] **VS Code Extension**: Live preview of generated code/tests while editing specs.
+- [ ] **Visual Spec Editor**: A GUI for defining Functional Requirements and Contracts.
+

specsoloist-0.2.0/demo.py

@@ -0,0 +1,110 @@
+import os
+import sys
+from specsoloist.core import SpecSoloistCore
+
+def main():
+    # Ensure API Key is present
+    if "GEMINI_API_KEY" not in os.environ:
+        print("ERROR: GEMINI_API_KEY environment variable not found.")
+        print("Please run: export GEMINI_API_KEY='your_key_here'")
+        sys.exit(1)
+
+    print("--- SpecSoloist Demo: End-to-End Flow ---")
+    
+    # Initialize Core
+    core = SpecSoloistCore(".")
+
+    spec_name = "math_demo"
+    
+    # 1. Create a spec from template
+    try:
+        core.create_spec(spec_name, "A robust factorial and prime check library.")
+    except FileExistsError:
+        print(f"Spec {spec_name} already exists, proceeding to overwrite with demo content.")
+
+    # 2. Overwrite with a high-quality definition to ensure LLM success
+    spec_path = core.parser.get_spec_path(spec_name)
+    demo_spec_content = """---
+name: math_demo
+type: module
+language_target: python
+status: draft
+---
+
+# 1. Overview
+A library for mathematical operations including factorial calculation and primality testing.
+
+# 2. Interface Specification
+
+## 2.1 Inputs
+### `factorial(n: int) -> int`
+*   `n`: The non-negative integer to calculate the factorial of.
+
+### `is_prime(n: int) -> bool`
+*   `n`: The integer to check for primality.
+
+## 2.2 Outputs
+*   `factorial`: Returns the factorial as an integer.
+*   `is_prime`: Returns True if n is prime, False otherwise.
+
+# 3. Functional Requirements (Behavior)
+*   **FR-01**: `factorial` shall return 1 for input 0.
+*   **FR-02**: `factorial` shall return the product of all positive integers less than or equal to n.
+*   **FR-03**: `is_prime` shall return False for numbers less than or equal to 1.
+*   **FR-04**: `is_prime` shall return True for 2 and 3.
+*   **FR-05**: `is_prime` shall use an efficient primality test (e.g., trial division up to sqrt(n)).
+
+# 4. Non-Functional Requirements (Constraints)
+*   **NFR-Purity**: Both functions must be pure.
+*   **NFR-Robustness**: `factorial` should raise a ValueError for negative inputs.
+
+# 5. Design Contract
+*   **Pre-condition**: `factorial` input `n >= 0`.
+*   **Post-condition**: `is_prime` output is always boolean.
+
+# 6. Test Scenarios
+| Scenario | Input | Expected Output |
+|----------|-------|-----------------|
+| Factorial 0 | `factorial(0)` | `1` |
+| Factorial 5 | `factorial(5)` | `120` |
+| Prime 7 | `is_prime(7)` | `True` |
+| Not Prime 10 | `is_prime(10)` | `False` |
+| Negative Factorial | `factorial(-1)` | `ValueError` |
+""".strip()
+    with open(spec_path, 'w') as f:
+        f.write(demo_spec_content)
+    print(f"1. Spec created/updated at: {spec_path}")
+
+    # 3. Compile Code
+    print(f"2. Compiling {spec_name} to code...")
+    print(core.compile_spec(spec_name))
+
+    # 4. Compile Tests
+    print(f"3. Compiling {spec_name} to tests...")
+    print(core.compile_tests(spec_name))
+
+    # 5. Run Tests
+    print("4. Running tests...")
+    result = core.run_tests(spec_name)
+    
+    if result["success"]:
+        print("\nSUCCESS: All tests passed!")
+    else:
+        print("\nFAILURE: Tests failed.")
+        print("--- Test Output ---")
+        print(result["output"][:500] + "...") # Print snippet
+        
+        print("\n5. Attempting Auto-Fix (Self-Correction)...")
+        fix_msg = core.attempt_fix(spec_name)
+        print(fix_msg)
+        
+        print("6. Rerunning tests after fix...")
+        result_retry = core.run_tests(spec_name)
+        if result_retry["success"]:
+            print("\nSUCCESS: Auto-fix worked! All tests passed.")
+        else:
+            print("\nFAILURE: Auto-fix failed to resolve the issue.")
+            print(result_retry["output"])
+
+if __name__ == "__main__":
+    main()