spex-cli 0.1.0__tar.gz

spex_cli-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: pip install -e ".[test]"
+
+      - name: Lint
+        run: |
+          pip install ruff
+          ruff check .
+
+      - name: Run tests
+        run: pytest

spex_cli-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Environment variables
+.env
+.env.local
+.env*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+__pycache__/
+*.pyc
+*.pyo
+.vite
+.pypirc

spex_cli-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: spex-cli
+Version: 0.1.0
+Summary: CLI tool for managing requirements and decisions
+Requires-Python: >=3.11
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: ruff>=0.15.1
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-cov>=4.0; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/logo.png" alt="speX Logo" width="120" />
+</p>
+
+<h1 align="center">🌋Spex CLI</h1>
+
+<p align="center">
+  <strong>Autonomous engineering experience enabled.</strong>
+  <br />
+  <em>Built by the MagmaAI Team</em>
+</p>
+
+<p align="center">
+  <a href="#overview">Overview</a> •
+  <a href="#features">Features</a> •
+  <a href="#getting-started">Getting Started</a> •
+  <a href="#project-structure">Project Structure</a> •
+  <a href="#development">Development</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+## Deployment
+
+To deploy a new version of `spex-cli` to PyPI, use the provided deployment script:
+
+```bash
+./scripts/deploy.sh
+```
+
+This script will:
+1. Verify no uncommitted changes exist.
+2. Build the package using `uv` (if available) or `build`.
+3. Check the distribution packages with `twine`.
+4. Prompt for upload to TestPyPI or PyPI.
+
+Make sure you have your PyPI credentials configured in `~/.pypirc` or set via environment variables (`TWINE_USERNAME` and `TWINE_PASSWORD`).

spex_cli-0.1.0/README.md

@@ -0,0 +1,38 @@
+<p align="center">
+  <img src="docs/logo.png" alt="speX Logo" width="120" />
+</p>
+
+<h1 align="center">🌋Spex CLI</h1>
+
+<p align="center">
+  <strong>Autonomous engineering experience enabled.</strong>
+  <br />
+  <em>Built by the MagmaAI Team</em>
+</p>
+
+<p align="center">
+  <a href="#overview">Overview</a> •
+  <a href="#features">Features</a> •
+  <a href="#getting-started">Getting Started</a> •
+  <a href="#project-structure">Project Structure</a> •
+  <a href="#development">Development</a> •
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+## Deployment
+
+To deploy a new version of `spex-cli` to PyPI, use the provided deployment script:
+
+```bash
+./scripts/deploy.sh
+```
+
+This script will:
+1. Verify no uncommitted changes exist.
+2. Build the package using `uv` (if available) or `build`.
+3. Check the distribution packages with `twine`.
+4. Prompt for upload to TestPyPI or PyPI.
+
+Make sure you have your PyPI credentials configured in `~/.pypirc` or set via environment variables (`TWINE_USERNAME` and `TWINE_PASSWORD`).

spex_cli-0.1.0/docs/spex-user-guide.md

@@ -0,0 +1,159 @@
+# Spex Skills: A User Guide
+
+The Spex ecosystem is designed to bring structure, traceability, and knowledge retention to your development process. It consists of two core skills: `spex-onboard` for initial setup and `spex` for orchestrating development tasks.
+
+This guide will help you understand when and how to use each skill effectively.
+
+## 1. `spex-onboard`: Setting Up Your Project
+
+The `spex-onboard` skill is the first step to integrating your project with Spex. Its sole purpose is to analyze your codebase, identify all the distinct applications and reusable libraries within it, and create a record of them. This record is crucial for all future Spex operations.
+
+### When to Use `spex-onboard`
+
+You should use this skill in two primary scenarios:
+
+1.  **Initial Project Setup:** When you first start using Spex on a new or existing codebase. This is a mandatory first step.
+2.  **Major Codebase Restructuring:** If you add or remove entire applications or libraries (e.g., adding a new microservice, monolothic repo refactor).
+
+**Example Invocation:**
+```
+spex-onboard analyze the codebase
+```
+
+### How It Works
+
+When invoked, `spex-onboard` performs the following automated steps:
+
+1.  **Detects Code:** It scans your project for common application and library indicators.
+    *   **Supported Types:** Node.js (`package.json`), Python (`requirements.txt`, `pyproject.toml`), Rust (`Cargo.toml`), Go (`go.mod`), Docker (`Dockerfile`), Kubernetes manifests, and more.
+2.  **Identifies Components:** It categorizes each finding as either an `application` (deployable service/site) or a `library` (reusable package).
+3.  **Prompts for Owners (Interactive):** For each component found, it will pause and ask you: *"Who is the owner/maintainer?"*. You can provide a name/team or press Enter to skip.
+4.  **Persists to Memory:** It saves this structural map to `.spex/memory/apps.jsonl`. This file is the "atlas" for all subsequent Spex operations.
+5.  **Suggests Next Steps:** Finally, it identifies potential documentation files (e.g., `README.md`, `ARCHITECTURE.md`) and suggests using them to "teach" the agent (see **Section 4: Knowledge Capture**).
+
+---
+
+## 2. `spex`: Orchestrating Development Work
+
+The `spex` skill is your day-to-day workhorse. It intelligently sizes up your request and directs it into one of two powerful workflows: a **Lightweight Flow** for small fixes or a **Full State Machine** for larger features.
+
+### Choosing the Right Flow: Small vs. Large Requests
+
+The `spex` skill automatically evaluates your request to decide which path to take. Here’s how it differentiates:
+
+| Request Type | Criteria | Examples |
+| :--- | :--- | :--- |
+| **Small** | Affects a single file, is an unambiguous bug fix, or a minor cosmetic change with no architectural impact. | "Fix the typo on the login button."<br>"Adjust the margin on the user profile card."<br>"Refactor this function to be more readable." |
+| **Large** | Involves multiple files, introduces new functionality, requires architectural decisions, or is ambiguous. | "Build a new settings page."<br>"Implement two-factor authentication."<br>"Redesign the data processing pipeline." |
+
+### A. The Lightweight Flow (for Small Requests)
+
+This flow is designed to be fast, efficient, and minimally intrusive for everyday tasks. It skips the heavy planning phase but ensures code quality and knowledge retention.
+
+#### When to Use
+
+You should use the lightweight flow for small, self-contained changes. Simply state your request directly.
+
+**Example Invocations:**
+*   `"Fix the bug where the user's name doesn't update in the header."`
+*   `"Change the primary button color to the new brand blue."`
+*   `"Add a loading spinner while the data is fetching."`
+
+#### How It Works
+
+1.  **Research Memory:** It checks Spex's memory for existing policies or decisions to ensure compliance.
+2.  **Execute Directly:** It performs the change using Test-Driven Development (TDD) where applicable.
+3.  **Memorize (Capture Knowledge):** After completion, it automatically extracts requirements and decisions and saves them to memory.
+
+**Important:** This flow does **not** create a feature folder (`.spex/<feature-name>`). It keeps your repository clean for small, tactical changes.
+
+### B. The Full State Machine (for Large Requests)
+
+This is a structured, traceable workflow for building new features and handling complex changes. It ensures that all decisions are deliberate, grounded in evidence, and documented.
+
+#### When to Use
+
+You should use the full state machine for any significant piece of work.
+
+**Example Invocations:**
+*   `"spex, let's build a new feature: user-to-user direct messaging."`
+*   `"I need to add support for Google authentication. Use spex for planning."`
+*   `"Plan and implement a dashboard for viewing analytics."`
+
+#### How It Works
+
+The full flow moves through a series of states, creating a dedicated folder at `.spex/<feature-name>/` to track all artifacts.
+
+1.  **`INIT` → `RESEARCH_CODE` → `RESEARCH_MEMORY`:** The agent researches your current codebase and its own memory to gather all relevant context and identify potential conflicts.
+2.  **`GENERATE_PLAN`:** Based on the research, it generates a detailed, step-by-step implementation plan.
+3.  **`REVIEWING_PLAN` (Human Checkpoint):** You are presented with the plan for review. You have the final say and must approve it before work begins. This is where you make the key architectural and structural decisions.
+4.  **`COMPILING_TASKS` → `EXECUTE`:** Once you approve the plan, the agent breaks it down into executable tasks and begins implementing them one by one.
+5.  **`AUDITING`:** After each task, the agent audits the code changes against the approved plan to ensure there is no scope creep. **This step is mandatory and cannot be skipped.**
+6.  **`COMPLETE`:** Once all tasks are executed and audited, the feature is complete. The agent proposes a final summary.
+
+### C. (See Section 4 for Knowledge Capture)
+This functionality has been promoted to its own main section below.
+
+---
+
+## 3. `spex-reflect`: Improving Future Work
+
+The `spex-reflect` skill is a powerful tool for continuous improvement. It analyzes completed features to extract learnings and propose reusable policies.
+
+### When to Use
+
+You should use this skill **manually** after a feature has been marked as `COMPLETE` by the `spex` skill.
+
+**Example Invocations:**
+*   `"spex reflect"`
+*   `"use spex to reflect on this feature"`
+*   `"analyze this feature and propose policies"`
+
+### How It Works
+
+1.  **Gather Context:** It reviews the entire feature history: the plan, decisions made, audit results, and execution traces.
+2.  **Analyze Learnings:** It identifies what went well (e.g., accurate planning) and what didn't (e.g., scope creep, conflicts).
+3.  **Evaluate Decisions:** It assesses the architectural and structural decisions for quality and impact.
+4.  **Propose Policies:** It identifies recurring patterns and proposes them as **Policies** (standing rules) to guide future development.
+5.  **Persist:** Upon your approval, it saves these policies to Spex's memory, making the agent "smarter" for the next task.
+
+---
+
+## 4. Knowledge Capture: Teaching the Agent
+
+Separate from feature development, you can use `spex` to "teach" the agent at any time. This captures Requirements, Decisions, and Policies directly into memory.
+
+### A. Learning from Conversation
+
+Capture decisions or requirements that emerge dynamically during a chat.
+
+**When to Use:**
+*   You just made a verbal decision in the chat (e.g., "Let's always use strict typing").
+*   You want to record a requirement found during debugging.
+
+**Example Invocations:**
+*   `"spex memorize this conversation"`
+*   `"capture this decision"`
+*   `"spex, record that we decided to use red for all error states"`
+
+**How It Works:**
+The agent scans the recent conversation, extracts structured items (Requirements, Decisions), presents them for your review, and saves them.
+
+### B. Learning from Documentation
+
+Teach the agent by having it read existing files.
+
+**When to Use:**
+*   You have an `ARCHITECTURE.md` or `API_GUIDELINES.md` file.
+*   You want to ingest a project spec or requirements document.
+
+**Example Invocations:**
+*   `"spex learn from docs/auth-flow.md"`
+*   `"teach spex via README.md"`
+*   `"analyze infrastructure.md for policies"`
+
+**How It Works:**
+1.  **Read:** The agent reads the specified file.
+2.  **Extract:** It identifies User Requirements (UR), Functional Requirements (FR), Non-Functional Requirements (NFR), and technical Decisions.
+3.  **Review:** It presents these items to you for confirmation.
+4.  **Save:** Once approved, they are persisted to Spex memory, making that document's knowledge available to all future workflows.

spex_cli-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "spex-cli"
+version = "0.1.0"
+description = "CLI tool for managing requirements and decisions"
+requires-python = ">=3.11"
+readme = "README.md"
+dependencies = [
+    "rich>=13.0",
+    "questionary>=2.0",
+    "ruff>=0.15.1",
+]
+
+[project.scripts]
+spex = "spex_cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spex_cli"]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-cov>=4.0"]
+dev = [
+    "twine>=5.0.0",
+    "build>=1.0.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = ["-v", "--strict-markers", "--tb=short"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 88

spex_cli-0.1.0/scripts/deploy.sh

@@ -0,0 +1,82 @@
+#!/bin/bash
+
+# Exit immediately if a command exits with a non-zero status
+set -e
+
+# Define colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
+
+echo -e "${YELLOW}Starting deployment process for spex-cli...${NC}"
+
+# Ensure we are in the project root
+cd "$(dirname "$0")/.."
+
+# 1. Check for uncommitted changes
+if [[ -n $(git status -s) ]]; then
+    echo -e "${RED}Error: You have uncommitted changes. Please commit or stash them before deploying.${NC}"
+    exit 1
+fi
+
+# 2. Ensure build and twine are installed
+echo -e "${YELLOW}Ensuring twine is available...${NC}"
+if command -v uv &> /dev/null; then
+    # Use uv to run twine
+    RUN_TWINE="uv run twine"
+    BUILD_CMD="uv build"
+else
+    echo -e "${YELLOW}uv not found, falling back to pip and python -m build...${NC}"
+    python3 -m pip install --upgrade build twine
+    RUN_TWINE="python3 -m twine"
+    BUILD_CMD="python3 -m build"
+fi
+
+# Detect local .pypirc
+TWINE_OPTS=""
+if [[ -f ".pypirc" ]]; then
+    echo -e "${YELLOW}Using local .pypirc file...${NC}"
+    TWINE_OPTS="--config-file .pypirc"
+fi
+
+# 3. Clean previous builds
+echo -e "${YELLOW}Cleaning up previous builds...${NC}"
+rm -rf dist/ build/ *.egg-info
+
+# 4. Build the package
+echo -e "${YELLOW}Building the package...${NC}"
+$BUILD_CMD
+
+# 5. Check the distribution packages
+echo -e "${YELLOW}Running twine check...${NC}"
+$RUN_TWINE check dist/*
+
+# 6. Prompt for deployment target
+echo -e "${GREEN}Build successful and verified!${NC}"
+echo "Where would you like to upload?"
+echo "1) TestPyPI (recommended for testing)"
+echo "2) PyPI (production)"
+echo "3) Exit"
+read -p "Enter choice [1-3]: " choice
+
+case $choice in
+    1)
+        echo -e "${YELLOW}Uploading to TestPyPI...${NC}"
+        $RUN_TWINE upload $TWINE_OPTS --repository testpypi dist/*
+        ;;
+    2)
+        echo -e "${YELLOW}Uploading to PyPI...${NC}"
+        $RUN_TWINE upload $TWINE_OPTS dist/*
+        ;;
+    3)
+        echo -e "${YELLOW}Exiting without upload.${NC}"
+        exit 0
+        ;;
+    *)
+        echo -e "${RED}Invalid choice. Exiting.${NC}"
+        exit 1
+        ;;
+esac
+
+echo -e "${GREEN}Deployment complete!${NC}"

spex_cli-0.1.0/src/spex_cli/__init__.py

@@ -0,0 +1,69 @@
+from rich.align import Align
+from rich.console import Console
+from rich.panel import Panel
+from rich.text import Text
+
+from spex_cli.spex import main as _main
+
+_BANNER_LINES = [
+    " ███████╗██████╗ ███████╗██╗  ██╗",
+    " ██╔════╝██╔══██╗██╔════╝╚██╗██╔╝",
+    " ███████╗██████╔╝█████╗   ╚███╔╝ ",
+    " ╚════██║██╔═══╝ ██╔══╝   ██╔██╗ ",
+    " ███████║██║     ███████╗██╔╝ ██╗",
+    " ╚══════╝╚═╝     ╚══════╝╚═╝  ╚═╝",
+]
+
+_ROW_COLORS = [
+    "#F97316",
+    "#F97316",
+    "#FBBF24",
+    "#FBBF24",
+    "#EC4899",
+    "#EC4899",
+]
+
+
+def print_banner() -> None:
+    console = Console(stderr=True)
+
+    art = Text(justify="center")
+    for i, (line, color) in enumerate(zip(_BANNER_LINES, _ROW_COLORS)):
+        art.append(line, style=f"bold {color}")
+        if i < len(_BANNER_LINES) - 1:
+            art.append("\n")
+
+    subtitle = Text(justify="center")
+    subtitle.append("Autonomous Engineering experience", style="bold #8B5CF6")
+    subtitle.append("  ·  ", style="dim")
+    subtitle.append("v0.1.0", style="#FBBF24")
+
+    console.print(
+        Panel(
+            Align.center(Text.assemble(art, "\n\n", subtitle)),
+            border_style="#8B5CF6",
+            padding=(1, 4),
+        )
+    )
+
+
+_BANNER_COMMANDS = frozenset({"healthcheck", "enable", "disable"})
+
+
+def _should_show_banner() -> bool:
+    import sys
+    args = sys.argv[1:]
+    if not args:
+        return True
+    first = args[0]
+    if first in ("-h", "--help"):
+        return True
+    if first in _BANNER_COMMANDS:
+        return True
+    return False
+
+
+def main() -> None:
+    if _should_show_banner():
+        print_banner()
+    _main()

spex_cli-0.1.0/src/spex_cli/_help.py

@@ -0,0 +1,130 @@
+import json
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+_console = Console()
+
+_COMMANDS = [
+    ("Developers", [
+        ("enable",      [], "Set up spex in the current repository"),
+        ("disable",     [], "Remove spex git hook and revert agent settings"),
+        ("healthcheck", [], "Audit hooks and memory integrity"),
+    ]),
+    ("Memory", [
+        ("requirement", ["add", "deprecate"],                  "Track functional and non-functional requirements"),
+        ("decision",    ["add", "deprecate"],                  "Record technical decisions with rationale and impact"),
+        ("policy",      ["add", "deprecate"],                  "Project-wide policies and guidelines"),
+        ("app",         ["add", "update"],                     "Register applications and libraries"),
+        ("plan",        ["add", "update-status", "deprecate"], "Feature planning lifecycle"),
+    ]),
+    ("System", [
+        ("trace", ["add"],               "Link commits to decisions via git trailers"),
+        ("blame", ["<file>[:<lines>]"],  "Find decisions and requirements for a file or line range"),
+        ("validate-and-route", ["--feature-name", "--target-state"], "Enforce state machine transitions"),
+    ]),
+]
+
+_SUBCOMMANDS = {
+    "requirement": [
+        ("add",       "Add a new requirement to memory"),
+        ("deprecate", "Deprecate an existing requirement"),
+    ],
+    "decision": [
+        ("add",       "Add a new technical decision"),
+        ("deprecate", "Mark a decision as obsolete"),
+    ],
+    "policy": [
+        ("add",       "Add a new project-wide policy or guideline"),
+        ("deprecate", "Deprecate an existing policy"),
+    ],
+    "app": [
+        ("add",    "Register a new application or library"),
+        ("update", "Update app or library details"),
+    ],
+    "plan": [
+        ("add",           "Create a new feature plan"),
+        ("update-status", "Update the current status of a plan"),
+        ("deprecate",     "Abandon a plan"),
+    ],
+    "trace": [
+        ("add", "Link a commit hash to a decision"),
+    ],
+}
+
+
+def print_help() -> None:
+    _console.print()
+    _console.print(
+        "  [bold]Usage:[/bold]  [bold #F97316]spex[/bold #F97316] "
+        "[#FBBF24]<command>[/#FBBF24] [dim][options][/dim]"
+    )
+    _console.print()
+
+    for section, commands in _COMMANDS:
+        _console.rule(f"[bold #8B5CF6] {section} [/bold #8B5CF6]", style="dim #8B5CF6")
+        _console.print()
+
+        table = Table(box=None, padding=(0, 2, 0, 4), show_header=False, expand=False)
+        table.add_column("cmd",     style="bold #F97316", no_wrap=True)
+        table.add_column("actions", no_wrap=True)
+        table.add_column("desc",    style="dim", no_wrap=False)
+
+        for cmd, actions, desc in commands:
+            action_text = Text()
+            for i, action in enumerate(actions):
+                if i > 0:
+                    action_text.append("  ", style="dim")
+                action_text.append(action, style="#FBBF24")
+            table.add_row(cmd, action_text, desc)
+
+        _console.print(table)
+        _console.print()
+
+    _console.print(
+        "  [dim]Run [/dim][bold #F97316]spex[/bold #F97316]"
+        " [dim]<command> --help for more information.[/dim]"
+    )
+    _console.print()
+
+
+def print_subcommand_help(command: str) -> None:
+    actions = _SUBCOMMANDS.get(command, [])
+    _console.print()
+    _console.rule(
+        f"[bold #8B5CF6] spex {command} [/bold #8B5CF6]",
+        style="dim #8B5CF6",
+    )
+    _console.print()
+
+    table = Table(box=None, padding=(0, 2, 0, 4), show_header=False, expand=False)
+    table.add_column("action", style="bold #FBBF24", no_wrap=True)
+    table.add_column("desc",   style="dim", no_wrap=True)
+
+    for action, desc in actions:
+        table.add_row(action, desc)
+
+    _console.print(table)
+    _console.print()
+    _console.print(
+        f"  [dim]Run [/dim][bold #F97316]spex {command}[/bold #F97316]"
+        " [dim]<action> --help for details.[/dim]"
+    )
+    _console.print()
+
+
+def print_help_json() -> None:
+    output = {
+        "usage": "spex <command> [options]",
+        "sections": [
+            {
+                "section": section,
+                "commands": [
+                    {"name": cmd, "actions": actions, "description": desc}
+                    for cmd, actions, desc in commands
+                ],
+            }
+            for section, commands in _COMMANDS
+        ],
+    }
+    print(json.dumps(output, indent=2))

spex_cli-0.1.0/src/spex_cli/agents.py

@@ -0,0 +1,33 @@
+AGENT_CONFIG = {
+    "claude": {
+        "name": "Claude Code",
+        "folder": ".claude/",
+        "settings_file": "claude_settings/settings.json",
+    },
+    "gemini": {
+        "name": "Gemini CLI",
+        "folder": ".gemini/",
+        "settings_file": "claude_settings/settings.json"
+    },
+    "cursor-agent": {
+        "name": "Cursor",
+        "folder": ".cursor/",
+        "settings_file": "claude_settings/settings.json"
+    },
+    "opencode": {
+        "name": "opencode",
+        "folder": ".opencode/"
+    },
+    "codex": {
+        "name": "Codex CLI",
+        "folder": ".codex/"
+    },
+    "agy": {
+        "name": "Antigravity",
+        "folder": ".agent/"
+    },
+    "copilot": {
+        "name": "GitHub Copilot",
+        "folder": ".github/"
+    }
+}