DOCSEARCHbyAlgolia
Submit Docs

Simone Task and Project Management System

repository·master·Indexed 20 days ago

https://github.com/helmi/claude-simone

A task and project management system engineered for AI-assisted development workflows, specifically for Claude Code. It implements Context Engineering to provide structured, layered, and just-in-time information to LLMs using Markdown and YAML. The project offers two versions: a stable directory-based Legacy system and an early-access MCP Server (simone-mcp) for structured prompts and activity tracking. Both can be managed via the hello-simone NPM installer.

Tokens
22.2K
Snippets
67
Records
105
Agent score
68%

What's inside claude-simone

  1. Overview of Simone for Claude Code

    master

    Simone is a project and task management system designed for AI-assisted development workflows. It provides structured prompts and tools that enable AI assistants (like Claude Code) to better understand and manage your projects.

    The project currently offers two distinct implementations depending on your needs:

    1. Legacy System (Original): A directory-based task management system. It is a mature implementation with a complete feature set that has been proven in real-world projects.
    2. MCP Server (Early Access): A new implementation built on the Model Context Protocol (MCP). This version provides structured prompts and activity tracking, but is currently in active development and intended for early adopters.

  2. Overview of Simone for AI Agents

    master

    Simone is a specialized framework designed to empower AI agents (such as Claude Code) to operate effectively within complex software engineering projects. It solves the problem of "context decay"—where critical project details are lost as an AI's conversational memory cycles—by providing a structured, task-based approach to context management.

    Instead of relying on the AI's long-term conversational memory, Simone primes the AI with the project's authoritative "ground truth" (documentation, requirements, and architectural blueprints) at the start of every distinct task. This ensures the AI always has a fresh, complete, and precisely relevant context.

  3. What is Context Engineering in Simone

    master

    Context Engineering is the foundational practice of the Simone framework. It is the discipline of designing, managing, and delivering precise, relevant information to an AI to overcome the limitations of finite context windows in large, complex software projects.

    Instead of providing a monolithic codebase, Simone uses Context Engineering to ensure the AI receives only the information necessary for a specific task, maximizing signal and minimizing noise.

  4. What is the Simone MCP Server?

    master

    The MCP (Model Context Protocol) Server is the next-generation implementation of the Simone framework. Unlike the legacy version which relied on file-based command systems, the MCP server uses a standardized protocol to provide prompts and tools to compatible AI clients in a structured, discoverable, and reliable way.

    Key improvements over the legacy system include:

    • Protocol-Based Interaction: Communicates via a formal protocol instead of requiring the AI to interpret Markdown command files, reducing misinterpretation.
    • Advanced Templating: Uses Handlebars for dynamic prompt templating, supporting complex logic, partials, and helpers.
    • Centralized Configuration: Uses a structured .simone/project.yaml file to define the project's stack, tooling, and methodology.
    • Activity Logging: Includes a built-in activity logger that uses an SQLite database to maintain a persistent record of development activities for tracking and analysis.

  5. Apply Conditional Logic for Risk Management

    master

    Use Handlebars to implement risk-based behavior. Risk levels range from 1 (most careful) to 10 (most risky). Typically, prompts handle three levels: 1, 5, and 10.

    Example Implementation

    {{#if (eq project.riskLevel 1)}}
- Ask user for confirmation before proceeding
{{else if (lte project.riskLevel 5)}}
- Show plan and proceed unless user objects
{{else}}
- Execute immediately without confirmation
{{/if}}

  6. Understand the Simone MCP Server architecture

    master

    The Simone MCP Server is a modular, persistent background process designed to serve context to an AI client (like Claude Code) via the Model Context Protocol (MCP). It operates by bridging the AI client with your project's local files and metadata.

    Core Interaction Model

    • AI Client <-> MCP Server: Communicates via MCP over Stdio.
    • MCP Server <-> Project: The server reads from .simone/project.yaml (configuration), .simone/prompts/ (prompt templates), and .simone/simone.db (activity logs) to provide context.
    • AI Client <-> Project Source: The AI client performs actual work directly on the project source code, while the MCP server provides the tools and prompts to guide that work.

  7. Understand the Simone MCP Server testing strategy

    master

    The Simone MCP server employs a multi-layered testing strategy to ensure reliability across different execution environments. The testing is organized into four main categories:

    1. Unit Tests: Tests individual components in isolation (e.g., Config Loader, Template System, Activity Logger, Prompt Handler) using mocked dependencies.
    2. Integration Tests: Tests the complete server with real components but within a controlled environment, covering MCP protocol initialization, tool/prompt execution, and concurrent requests.
    3. STDIO Integration Tests: Tests real server process spawning and client communication via standard I/O, including real-time template hot-reloading and graceful shutdown.
    4. Smoke Tests: Basic sanity checks to ensure the server starts without errors, handles missing PROJECT_PATH, and manages required directory creation.

    Test Infrastructure:

    • Framework: Vitest
    • Coverage: @vitest/coverage-v8

  8. Use prompts to initiate complex actions

    master
    The primary way to initiate complex, multi-step actions is by invoking a prompt by name (e.g., create-task or summarize-activity). The MCP server uses a Handlebars templating engine to render these prompts into detailed, context-rich instructions for the AI, based on your .simone/project.yaml configuration and any provided arguments.

  9. Choose between the Legacy System and the MCP Server

    master

    Simone offers two distinct ways to manage AI context and workflows. Choose the one that fits your current needs:

    Legacy System (Stable & Ready)

    Best for users who want a stable, production-ready version based on file-based context.

    • File-Based Context: Uses a structured directory of Markdown files to organize project knowledge.
    • AI-Guided Commands: Uses human-readable Markdown files as detailed instructions for executing complex tasks.
    • Iterative Workflow: Supports a structured cycle from planning milestones to executing and committing tasks.

    MCP Server (Early Access)

    Best for users wanting to explore the future of Simone using the Model Context Protocol (MCP).

    • Protocol-Driven Interaction: Communicates with AI agents via the Model Context Protocol (MCP) for standardized interactions.
    • Activity Logging: Uses a built-in SQLite database to persistently log all AI-assisted development activities.
    • Dynamic Prompts: Uses Handlebars templating to create highly configurable, context-aware prompts.

  10. Understand the principles of Context Engineering in Simone

    master

    Simone is built on the discipline of Context Engineering, which aims to solve the finite context window limitation of LLMs by delivering precise, relevant information rather than flooding the model with an entire codebase.

    Simone follows four core principles:

    1. Structured Knowledge: Project information is organized into logical, queryable components (vision, architecture, requirements, tasks) rather than a monolithic block.
    2. Layered Context: Information is delivered in layers, moving from general (project goals) to specific (fine-grained task details).
    3. Just-in-Time Context: Context is retrieved and provided only when needed, typically tied to specific commands, to maximize signal and minimize noise.
    4. AI-Friendly Format: All project artifacts are stored in machine-readable formats, primarily Markdown and YAML, to facilitate easy parsing and reasoning by the AI.

  11. Architectural components of the Simone MCP Server

    master

    The Simone MCP Server is composed of several specialized internal components:

    ComponentResponsibility
    Server CoreThe entry point (index.ts) that initializes the @modelcontextprotocol/sdk and sets up request handlers.
    Config LoaderLoads and validates project metadata and context paths from .simone/project.yaml.
    Prompt HandlerManages prompt loading and rendering using Handlebars templates. Supports built-in and project-specific prompts.
    Tool RegistryA central registry for all available MCP tools (e.g., ActivityLogger).
    Activity LoggerA service providing the log_activity tool, which persists development activities to an SQLite database at .simone/simone.db.
    Transport LayerHandles communication; currently uses StdioServerTransport (Stdio) for standard input/output communication with the AI client.

  12. Implement the Interview Pattern for User Input

    master

    Because MCP arguments do not support spaces, most prompts must use an Interview Pattern to gather necessary information from the user.

    Implementation Logic

    Use Handlebars logic to check if an argument was provided. If not, instruct the LLM to ask the user for the specific information needed.

    Pattern Template

    {{#if argument_name}}
Initial input provided: "{{argument_name}}"
{{else}}
Ask the user: "What is [the specific thing you need]?"
{{/if}}

Additional questions to ask:
- [Specific question 1]
- [Specific question 2]
- [Context-gathering question]