spex-cli 0.1.1

CLI tool for managing requirements and decisions

🌋 Spex CLI

Autonomous engineering experience enabled.
A set of skills and cli tools to enable autonomous AI engineering.

⚠️ Note: Spex is currently in Beta and considered experimental.

Overview • Autonomous AI Engineering • Quick Start • Workflow •

---

🌟 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:

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:

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:

  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.

  spex learn from docs/architecture.md
  

• Learning from Conversation: Captures decisions made during your chat session.

  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:

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.

---

Brought to you with ❤️ by the MagmaAI Team