Metadata-Version: 2.4
Name: spex-cli
Version: 0.1.1
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>A set of skills and cli tools to enable autonomous AI engineering.</em>
  <br />
  <br />
  ⚠️ <strong>Note:</strong> Spex is currently in <strong>Beta</strong> and considered experimental.
</p>

<p align="center">
  <a href="#-overview">Overview</a> •
  <a href="#-autonomous-ai-engineering">Autonomous AI Engineering</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-workflow">Workflow</a> •
</p>

---

## 🌟 Overview

**Spex** is a CLI tool designed to capture the "why" behind your code. It manages requirements, technical decisions, and project-wide policies in a versioned, git-friendly format (`.jsonl`).

By integrating directly into your development workflow via agent skills and git hooks, Spex ensures that every major decision is grounded in requirements and traced back to the commits that implemented it.

---

## 🤖 Autonomous AI Engineering

True autonomy in AI engineering cannot be achieved without **trust**. Spex is built on three pillars to establish and maintain this trust:

1.  **Confidence through Delegation**: Trust means we are confident that the instructions given to the agent are clear. When ambiguity arises over important decisions—past or present—the agent proactively delegates them back to the engineer.
2.  **Reliable Grounding**: Trust means knowing the agent intimately understands your system and product. Spex allows the agent to navigate and ground itself in the correct architecture, constraints and previous decisions.
3.  **Continuous Evolution**: To build trust over time, the agent must get better with every task. By reflecting on past experiences and mistakes, Spex enables the agent to learn and improve continuously.

---

## 🚀 Quick Start

### 1. Installation

Install Spex via pip:

```bash
pip install spex-cli
```

### 2. Initialize Spex

Run the following command in your git repository to set up the necessary directory structure and git hooks:

```bash
spex enable
```

> 💡 **Recommendation:** Choose to use Spex as your **default workflow** during initialization. This ensures your agent automatically leverages Spex memory and state machines for all development tasks.

---

## 🔄 Workflow

Spex orchestrates development through a structured lifecycle, ensuring that knowledge is captured and code is aligned with requirements.

### 1. Onboarding (`spex-onboard`)
The first step in any project is to map the codebase structure. This identifies all applications and libraries, creating a foundation for localized decisions.

- **Description**: Scans for `package.json`, `pyproject.toml`, etc., and prompts for component owners.
- **Example**:
  ```bash
  spex-onboard analyze the codebase
  ```

### 2. Knowledge Capture (`spex learn`)
Build your project memory by ingesting existing documentation or capturing real-time decisions.

- **Learning from Docs**: Reads architecture files and extracts structured requirements/decisions.
  ```bash
  spex learn from docs/architecture.md
  ```
- **Learning from Conversation**: Captures decisions made during your chat session.
  ```bash
  spex memorize this conversation
  ```

### 3. Development Flow (`spex`)
Spex intelligently routes your requests based on their complexity.

#### 💡 Lightweight Flow (Small Tasks)
For bug fixes, UI tweaks, or minor refactors that don't change the architecture.
- **Description**: Researches memory, executes the change, and automatically "memorizes" the result.
- **Example**: `"Fix the bug where the user's name doesn't update in the header."`

#### 🗺️ Plan Mode (Large Features)
For new functionality or complex changes requiring deliberate planning and human review.
- **Description**: Follows a full state machine: `RESEARCH` → `PLAN` → `REVIEW` → `EXECUTE` → `AUDIT`.
- **Example**: `"spex, let's build a new feature: user-to-user direct messaging."`

### 4. Continuous Improvement (`spex reflect`)
After a feature is implemented, use reflection to capture learnings and improve the agent's future performance.

- **Description**: Analyzes the completed feature, identifies patterns, and proposes new **Policies** for the project memory.
- **Usage**: Run this only after **Plan Mode** has successfully finished and you have verified the feature is working as expected (even if extra tweaks were required during execution).
- **Example**: `"spex reflect on the last feature"`

---

## 🔧 Troubleshooting

If you encounter issues with git hooks or memory integrity, use the built-in healthcheck command:

```bash
spex healthcheck
```

This command will:
- Verify that git hooks are correctly installed and executable.
- Audit the integrity of the `.spex/memory/` JSONL files.
- Ensure the agent skills are correctly configured.

---

<p align="center">
  Brought to you with ❤️ by the <strong>MagmaAI Team</strong>
</p>
