AgentFlow

A markdown-first lifecycle and execution orchestrator for autonomous AI agents.

What AgentFlow Solves

Unstructured agent execution is chaotic. When AI agents write code without strict boundaries, they easily get lost in infinite loops, overwrite working solutions, and leave behind undocumented messes. Current frameworks either obscure the agent's reasoning inside opaque API calls or provide zero structure, expecting the LLM to somehow manage the entire software development lifecycle (SDLC) flawlessly on its own.

AgentFlow solves this by forcing agents to follow a markdown-first lifecycle. Instead of raw conversational loops, the agent's entire workflow is externalized into version-controlled markdown files. Every plan, attempt, test result, and review is documented. Skills are chained explicitly.

If an agent fails a task, it doesn't just guess again; it reads its WORKLOG, analyzes the error, increments an attempt counter, and iterates deliberately. This provides observability, deterministic limits, and a natural way for human developers to audit and intervene.

Lifecycle Diagram

 [Prompt] 
    │
    ▼
 ┌─────────────┐        ┌─────────────┐
 │  Plan       │───────▶│  Implement  │
 └─────────────┘        └─────────────┘
                              │
                              ▼
 ┌─────────────┐        ┌─────────────┐
 │  Review     │◀───────│  Test       │
 └─────────────┘        └─────────────┘
    │                         │
    ▼ (Fail) ─────────────────┘
    │
    ▼ (Pass)
 ┌─────────────┐
 │  Merge      │
 └─────────────┘

Quick start

Scaffold .agentflow/ in your current repository using NPX (Zero installation required):

npx agentflow-scaffold --all

The CLI is interactive! If you run npx agentflow-scaffold, it will ask you what you want to download. You can also specify exact configurations via flags:

# Download only core files + specific skills
npx agentflow-scaffold --skills=implement,test,review

# Download exact files only
npx agentflow-scaffold --files=WORKFLOW.md,AGENTFLOW.md

(Note: We also retain a Python version scaffold_agentflow.py for legacy usage).

Next Steps (How to use this)

Once you have scaffolded the .agentflow/ directory into your project, here is how you and your AI agent actually use it:

1. Configure Context: Open .agentflow/AGENT_CONTEXT.md and fill in your project's tech stack, build commands, and any overarching rules.
2. Write a Prompt: Create a new markdown file in .agentflow/prompts/ (e.g., my_feature.md) detailing the task you want the agent to accomplish.
3. Kickoff the Agent: Point your AI coding agent (e.g. Cline, Antigravity, OpenHands, Aider) at the entry point and your prompt. For example:

   "Read .agentflow/AGENTFLOW.md to understand the workflow. Then, execute the task described in .agentflow/prompts/my_feature.md."

4. Watch it Work: The agent will automatically read the workflow rules, create a plan in plans/, write code, test it, and document everything in a worklogs/ folder.

What's Included

| Component | Purpose | | --- | --- | | AGENTFLOW.md | Entry point and catalog of all agent behaviors. | | WORKFLOW.md | The state machine engine detailing stages, transitions, and limits. | | AGENT_CONTEXT.md | The universal context loaded by agents before starting any work. | | /skills/ | The modular toolbelt for the agent. Each skill runs one stage. | | /prompts/ | User-authored requests detailing the feature/bug to solve. | | /worklogs/ | Agent-authored execution state, keeping track of attempts and outcomes. |

.agentflow/ Structure

.agentflow/
├── AGENTFLOW.md         # The main entry point
├── WORKFLOW.md          # State machine and transition rules
├── AGENT_CONTEXT.md     # Project-specific context
├── skills/              # Skill definitions (FOLDERS)
│   ├── plan/
│   │   ├── SKILL.md     # Instructions & chain_to
│   │   ├── scripts/     # Skill-specific helpers
│   │   └── references/  # Supplemental docs
│   ├── implement/
│   ├── test/
│   ├── review/
│   └── document/
├── plans/               # Agent-generated execution plans
├── prompts/             # User-authored task inputs
├── worklogs/            # State tracking per branch
│   ├── attempts/        # Created on demand
│   └── artifacts/       # Created on demand
├── docs-generated/      # Agent-generated system documentation
└── postmortems/         # Rollup of completed or failed tasks

Skill Chaining

AgentFlow uses a Chained Skill Architecture. Instead of a monolithic loop, the agent executes specialized skills sequentially. The transition is governed by the chain_to field in each skill's SKILL.md frontmatter. For example, skills/plan/SKILL.md declares chain_to: skills/implement/SKILL.md. This allows the orchestrator to automatically hand off execution from planning to implementation, isolating responsibilities.

Extending the Scaffold

To add new capabilities:

1. New Skills: Create a new folder in skills/ (e.g., skills/deploy/). Add a SKILL.md with instructions, a chain_to directive, and any helper scripts in skills/deploy/scripts/.
2. New Reference Material: Add .md files to skills/<name>/references/ for agents to read when executing that skill.
3. New Scripts: Add .sh or .py files to skills/<name>/scripts/ to give the agent automated tools for its task.

Requirements

• A markdown-aware AI agent system (e.g., Antigravity, OpenHands)
• Bash-compatible shell for executing skill scripts
• Git (for branch and rollback management)

Design

For a deep dive into the architectural decisions and invariant guarantees, see AGENTFLOW_DESIGN.md (if present) or refer to the WORKFLOW.md.

Contributing

Sync Invariant Note: When modifying the .agentflow/ directory, ensure that changes to WORKFLOW.md state transitions are accurately reflected in the corresponding chain_to links in SKILL.md files. State must remain perfectly synchronized across the scaffold.