Document as State Machine: How Agentic Souls Drives AI Software Development Workflows with Markdown

🇨🇳 中文版

I. Introduction

Agentic Souls is a document-driven AI software development workflow system. It defines three core roles—Planner, Evaluator, and Specialist—and uses structured Markdown files as state machines and control flow mechanisms to achieve high-quality software delivery.

II. Core Design

2.1 Design Decision 1: Markdown as State Machine and Control Flow

What intuition suggests: Use a database or complex JSON structures to manage task states, hardcoding process logic within the code.

What we actually did: Agentic Souls uses a series of structured Markdown files (task.md, plan.md, execution.md, evidence.md, verdict.md) as the single source of truth. Each file represents a stage in the workflow, and the creation or update of these files constitutes state transitions.

According to the definition in docs/campaign.md, a complete Campaign includes the following structure:

campaign:
  id: CAMP-XXX
  name: [Campaign Name]
  status: pending | in_progress | completed | failed

  task:           # Task Definition
    ...

  plan:           # Execution Plan
    ...

  execution:      # Execution Record
    ...

  evidence:       # Verification Evidence
    ...

  verdict:        # Final Verdict
    ...

Files are created incrementally by stage, rather than being generated all at once:

Document	Created By	Creation Timing	Content
task.md	Planner	At the start of the Campaign	Task Definition
plan.md	Planner	After task.md is completed	Execution Plan
execution.md	Specialist	During each Phase execution	Execution logs (appended step-by-step)
evidence.md	Evaluator	During each Phase verification	Verification evidence (appended step-by-step)
verdict.md	Evaluator	After all Phases are completed	Final Verdict

Why this is better:

1. Human Readability: Developers can directly read and understand task progress without parsing code logic.
2. Version Control Friendly: Git natively supports diff comparisons for Markdown, facilitating auditing and tracing back.
3. Decoupling: AI Agents act merely as consumers and producers of files; process logic is entirely defined by the file structure, making it easy to extend new workflows.

2.2 Design Decision 2: Evidence-Based Independent Evaluation (Evaluator)

What intuition suggests: The Planner claims the task is complete and marks it as passed directly; or the Evaluator relies on self-reports from the Specialist.

What we actually did: The Evaluator is designed as an independent sub_agent. It trusts no statements. It must obtain "first-hand evidence" by reading files and running commands (such as pytest, ruff), then mapping this evidence to specific Acceptance Criteria (AC).

From souls/evaluator.md, we can see the core constraints of the Evaluator:

Rule_1:
  description: Do not trust Planner's statements; verify independently
  reason: Independent verification ensures objectivity and fairness

Rule_2:
  description: Do not issue PASS without evidence; read files and run commands
  reason: Evidence-driven approach avoids subjective judgment

Rule_3:
  description: Do not provide advice outside of responsibilities; output only verdicts
  reason: Maintain role boundaries and prevent overreach

The actual evidence.md demonstrates this evidence-driven verification method. Taking campaigns/<your-campaign>/evidence.md as an example:

## Phase 1 (P0)

| AC | Status | Verification | Proof |
|----|--------|-------------|-------|
| AC-1 | PASS | Code Review | `SimilarityDetector(min_block_size=min_lines)` + `add_code_block` |
| AC-2 | PASS | Read pyproject.toml | `ai-analyze = "src.cli:main"` |
| AC-3 | PASS | Grep Search | `grep -r "from src\." src/` returns 0 results |
| AC-4 | PASS | Code Review | serena_stdio_client.py has no local Path imports |
| AC-5 | PASS | Tests Passed | `assert len(h) == 64` |

The Evaluator's verdict can only be one of the following four:

• PASS: All ACs are met.
• PARTIAL: Core ACs are met, but non-blocking issues exist.
• FAIL: Core ACs are not met.
• BLOCKED: Blocking issues exist requiring external intervention.

Why this is better:

1. Objectivity: Eliminates subjective judgment and "hallucinations"; all verdicts are based on verifiable evidence.
2. Traceability: evidence.md provides a complete audit trail, facilitating problem troubleshooting.
3. Role Boundaries: The Evaluator is strictly limited to outputting verdicts (PASS/FAIL) and does not provide advice, ensuring checks and balances.

2.3 Design Decision 3: Role Isolation via Constrained Soul Documents

What intuition suggests: Define different Agent classes in code and pass role information via parameters.

What we actually did: Each role (Planner, Specialist, Evaluator) corresponds to a Markdown file located in the souls/ directory. These files define not only responsibilities but also strict "codes of conduct" and "prohibited behaviors."

Taking souls/planner.md as an example, the core constraints for the Planner are:

Rule_1:
  description: Never write more than 20 lines of implementation code yourself
  reason: Maintain role boundaries and prevent overreach

Rule_2:
  description: Delegate all implementation to the Specialist via the Task tool
  reason: Separation of duties ensures execution quality

Rule_3:
  description: Must call the Evaluator before completion; self-evaluation is not allowed
  reason: Independent verification ensures delivery quality

souls/specialist.md defines the execution standards for the Specialist:

Rule_1:
  description: Perform only subtasks assigned by the Planner; do not expand scope independently
  reason: Maintain responsibility boundaries and prevent overreach

Rule_2:
  description: Do not perform overall planning or judge whether the overall task is complete
  reason: This is the Planner's responsibility, not the Specialist's

Rule_3:
  description: Report immediately upon completion, clearly stating what was done, where the artifacts are, and if Planner attention is needed
  reason: Timely feedback facilitates Planner decision-making

souls/evaluator.md emphasizes the independence of the Evaluator:

Isolation Mechanism:
  - The Evaluator is an independent sub_agent
  - Does not inherit judgments from the Planner
  - Does not accept advice from the Planner
  - Outputs verdicts solely based on its own verification

Why this is better:

1. Flexibility: New roles can be easily created or existing roles' behaviors modified simply by editing Markdown files.
2. Explicit Constraints: Business logic constraints (such as code line limits, role boundaries) are made explicit, preventing AI overreach.
3. Composability: Different workflows (Workflows) can reference different combinations of Souls, adapting to various scenarios.

III. Source Code Navigation

Module	File	Description
Core Definitions	docs/campaign.md	Complete structure and state machine definition for Campaigns
Role Definitions	souls/planner.md	Planner's responsibilities, constraints, and workflow
Role Definitions	souls/evaluator.md	Evaluator's independent verification mechanism and verdict criteria
Role Definitions	souls/specialist.md	Specialist's execution standards and reporting format
Practical Case Studies	campaigns/	Complete Campaign instance directory containing all stage files
Memory System	memories/	Knowledge base of historical questions and solutions

IV. Relationship with PSE Frameworks

Agentic Souls shares the Planner / Specialist / Evaluator three-role collaboration design with autogen-pse and crewai-pse, but with different emphases:

Project	Collaboration Mode	Orchestration	Key Feature
agentic-souls	Document-driven	Markdown state machine	Human-readable, Git-friendly, no code framework needed
autogen-pse	Discussion-based	AutoGen RoundRobinGroupChat	Multi-round negotiation, auto-retry, SSE real-time streaming
crewai-pse	Pipeline-based	CrewAI Sequential	Strict sequential execution, task-driven, structured output

Agentic Souls can be viewed as a "document-layer abstraction" of the PSE pattern — replacing code orchestration with Markdown files, suitable for scenarios requiring strong auditing and human-readable workflows.

V. Quick Start

git clone https://github.com/erishen/agentic-souls.git
cd agentic-souls

Agentic Souls is a document-driven system that requires no dependency installation to use. You can integrate it with any Agent framework that supports Markdown context loading (such as AutoGen, CrewAI, Claude Code, etc.):

1. Clone the repository: Get Soul documents, workflow definitions, and Campaign examples
2. Select a workflow: Choose an appropriate workflow from the workflows/ directory (e.g., feature-development.md)
3. Load roles: Use souls/planner.md, souls/specialist.md, souls/evaluator.md as Agent system prompts
4. Execute Campaign: Planner creates task.md → Specialist executes and appends execution.md → Evaluator verifies and writes evidence.md / verdict.md

Typical process:

1. Load Planner Soul: "Please read souls/planner.md"
2. Select Workflow: "Please execute according to workflows/feature-development.md"
3. Switch to Specialist: "Please read souls/specialist.md"
4. Switch to Evaluator: "Please read souls/evaluator.md"