spex-cli 0.1.3

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 • Memory Taxonomy • Troubleshooting

---

🌟 Overview

Spex is an autonomous engineering toolset 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 specialized agent skills and git hooks, Spex ensures that every major decision is grounded in requirements and traced back to the commits that implemented it.

The toolset is comprised of three core components:

• 📟 CLI - Handles installation and environment configuration.
• 🧠 Skills - Orchestrates the workflow between agents and engineers during development.
• 💾 Memory - A persistent, versioned layer that tracks decisions across the project's lifecycle.

Every interaction with Spex skills—whether you're initializing a project, solving a bug, or building a feature—is an opportunity for the agent to learn. Spex automatically captures the reasoning, technical choices, and patterns from these interactions, ensuring they are persisted in memory and utilized to ground future tasks.

---

🤖 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 - CLI

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 - Agent Skills

Spex provides a set of specialized skills for your AI agent to orchestrate the development lifecycle, ensuring knowledge capture and architectural alignment.

🛠️ Onboarding Skill (spex onboard)

The entry point for any project. This skill allows the agent to map the codebase structure, identifying applications and libraries to create a foundation for localized decisions.

• Goal: Establish the project scope and application boundaries.
• Usage:

  spex onboard
  

🧠 Knowledge Capture Skill (spex learn / spex memorize)

Builds the project's long-term memory by ingesting documentation or capturing real-time decisions.

• Learning from Docs: Agent reads architectural files and extracts structured requirements/decisions.

  spex learn from docs/architecture.md
  

• Learning from Conversation: Agent captures technical choices made during your chat session.

  spex memorize this conversation
  

🌋 Development Orchestrator Skill (spex)

The primary skill for executing engineering tasks. It intelligently routes requests based on complexity while ensuring every interaction contributes to the project's long-term memory:

• 💡 Lightweight Flow (Small Tasks): For bug fixes or minor refactors. The agent researches memory, implements the fix, and automatically captures the decision.
  • Example: "Fix the bug where the user's name doesn't update."
• 🗺️ Plan Mode (Large Features): For complex changes. The agent follows a structured state machine: RESEARCH → PLAN → REVIEW → EXECUTE → AUDIT.
  • Example: "Spex, let's build a new user-to-user messaging feature."

💾 Automatic Capture: Both flows conclude by extracting technical decisions and linking them to your git commits, ensuring the project memory grows with every task.

🔍 Reflection Skill (spex reflect)

A post-development skill used to analyze completed features and capture structural patterns.

• Goal: Propose new Policies (reusable rules) for the project memory based on what was learned during execution.
• Usage: Run after a feature is verified to improve the agent's future performance.

  spex reflect on the last feature
  

---

📁 Memory Taxonomy

Spex organizes project knowledge through a structured hierarchy, ensuring every line of code has a clear purpose.

1. Requirements (The "What")

• Functional (FR): Specific behaviors or features the system must provide.
• Non-Functional (NFR): Quality attributes like performance, security, and scalability.
• Constraints (CR): Non-negotiable technical or business limitations.

2. Policies (The "Laws")

Mandatory, reusable rules that govern the project. Policies bridge high-level requirements into standing engineering practices (e.g., "All API calls must use circuit breakers").

3. Decisions (The "How")

• Architectural: High-impact choices affecting core frameworks or system primitives.
• Structural: Component-level organization and API contract definitions.
• Tactical: Localized implementation patterns and algorithms.

4. Traces (The "Proof")

The immutable link between a code commit and the specific decisions and requirements it implements, ensuring complete auditability.

---

🔧 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