spex-cli 0.1.7

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 & Git Strategy • 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.

3. Launch Spex UI (Optional)

Visualize your project's memory, requirements, and decisions in the browser:

spex ui

---

🔄 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
  

💡 Best Practices & Expectations

• One-Time Setup: Onboarding is performed only once per repository to establish the baseline memory.
• Pre-Development: Onboarding should happen before any actual development work begins.
• Commit to Main: Once onboarding is complete, the generated .spex/memory/apps.jsonl should be committed to your main branch.
• Continuous Learning: Extending Spex's memory is key to long-term autonomy. While not mandatory, feeding the agent with context ensures it respects your project's soul.

🧠 Learn Skill (spex learn / spex memorize)

Builds the project's long-term memory by ingesting documentation or capturing technical context from your interactions.

📄 Mode 1: Learning from Docs

Use this to feed existing knowledge into Spex's memory. It's most effective for established patterns and high-level architecture.

• Useful examples:
  • ARCHITECTURE.md: Core system design and component boundaries.
  • PRODUCT_SPECS.md: Requirements and business logic rules.
  • BEST_PRACTICES.md: Coding standards, testing strategies, and security policies.
  • API_DESIGN.md: Contract standards and integration patterns.
• Usage:

  spex learn from docs/architecture.md
  

💬 Mode 2: Learning from Conversations

Use this to capture the technical "why" behind decisions discussed in real-time. This is perfect for complex task breakdowns or ad-hoc architectural choices.

• Useful examples:
  • Past Context: Memorize a previous conversation where important changes were made to the codebase to capture the "why" behind those changes.
  • Post-Task Capture: If you just finished a task with an agent that didn't use Spex, use this to ensure the interaction is recorded in memory.
• Usage:

  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 & Git Strategy

Spex memory files (.spex/memory/*.jsonl) are part of your codebase and should follow a disciplined Git strategy to ensure consistency across your team and prevent agent confusion.

• Onboarding is a Baseline: Initial onboarding (spex onboard) happens once per repository. The resulting memory files should be committed directly to your main branch to establish the foundation.
• Branch-Based Development: Technical decisions and requirements for new features must stay within their respective feature branches. Memory files should only be merged into main when the code itself is approved and merged.
  • Warning: Never merge feature-specific memory into main prematurely. Doing so can "pollute" the project context for agents working on parallel tasks.
• Independent Learning: When using the spex learn skill to ingest existing docs or architecture, do so in a dedicated, independent branch. This allows you to merge the enriched memory into main as quickly as possible, making it available for everyone immediately.

---

📁 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