AgentFlow: Autonomous Agent Multi-Step Workflow Orchestration

AgentFlow is a self-contained developer agent workflow framework and execution engine for Antigravity IDE (and compatible agents like Claude Code). It enables agents to execute complex, multi-step tasks autonomously by:

1. Prompt Expansion: Compiles brief instructions into structured, context-rich engineering briefs.
2. Context-Aware Loading: Automatically discovers and internalizes your project's workflow specifications (database models, coding guidelines, API maps) before running tasks.
3. Execution State Persistence: Tracks tasks in a state file so execution resumes seamlessly after interruptions.
4. Mandatory Post-Execution Validation: Automatically runs test suites, build compilation, and linting checks to guarantee that no broken code is committed.
5. Auto-Correction: Automatically detects and self-corrects build/test failures up to 3 times.
6. Documentation Sync: Automatically appends task history and updates project documentation mapping upon success.

---

Repository Structure

This repository is organized to serve both as an instant project template and as a skill distribution package:

agentflow-template/
├── README.md               # Main documentation
├── package.json            # Node manifest & scripts
├── skills/
│   └── agentflow/          # The distributable skill package
│       ├── SKILL.md        # The main skill definition
│       ├── references/
│       │   ├── review-and-land.md
│       │   └── writing-the-brief.md
│       └── scripts/
│           └── agentflow.mjs  # CLI dispatch script
├── templates/              # Generic developer workflow templates
│   ├── AGENTS.md           # Developer guidelines & protocols
│   └── workflows/          # Project documentation guides
│       ├── project-overview.md
│       ├── architecture.md
│       ├── database.md
│       ├── api-map.md
│       ├── coding-patterns.md
│       ├── folder-structure.md
│       ├── workflow.md
│       ├── task-rules.md
│       └── task-history.md
└── .agents/                # Pre-configured workspace directory
    ├── AGENTS.md           # Active agent protocol
    ├── skills/             # Active skills
    └── workflows/          # Active project documentation

---

🚀 First-Time Experience (Project Template)

If you are using this repository to start a new project from scratch, follow these steps:

1. Clone the Repository:

   git clone https://github.com/abdalrahman-ahmed/agentflow-template.git my-new-project
   cd my-new-project

2. Initialize Your Stack: Add your code, source files, and structure.
3. Customize Project Documentation: Go to .agents/workflows/ and edit the template files (project-overview.md, coding-patterns.md, database.md, etc.) to accurately reflect your new project's stack, conventions, and configuration.
4. Define Validation Rules: Open .agents/workflows/task-rules.md and customize the commands the agent must run to validate code changes (e.g. npm test, cargo test, pytest).

---

📦 Distributing and Installing the Skill

For existing projects, you can install the AgentFlow skill directly using the package manager for agent skills:

npx skills add abdalrahman-ahmed/agentflow-template --skill agentflow

This installs agentflow inside .agents/skills/agentflow/ in your workspace.

Manual Setup for Existing Projects

If you prefer not to use the installer:

1. Copy skills/agentflow into your project's .agents/skills/ directory.
2. Copy templates/AGENTS.md to your project's .agents/AGENTS.md.
3. Copy templates/workflows/ folder to your project's .agents/workflows/.
4. Review and modify the configurations inside .agents/ to suit your project.

---

🛠️ Usage & Control Commands

Once installed, trigger the process in your chat session by prefixing commands with /agentflow:

/agentflow implement user registration with JWT authentication

The orchestrator intercepts the instruction, scans project workflows, creates a structured engineering brief, and dispatches the task to the background agentflow.mjs script using the selected model.

Control Commands

While a task is executing in the background, you can check progress or control execution:

Command	Action	Description
/status <run-dir>	Print Status	Prints current run status (running, done, failed)
/log <run-dir> [lines]	Print Log Tail	Shows the tail of the background run's output log (defaults to last 50 lines)
/cleanup <run-dir>	Force Cleanup	Force removes the temporary git worktree and deletes the run directory

---

⚙️ How the Autonomous Pipeline Works

AgentFlow operates as a structured, non-blocking background pipeline:

graph TD
    A["User triggers /agentflow <instruction>"] --> B["Orchestrator scans workflows and compiles structured Brief"]
    B --> C["Orchestrator queries available models using 'agentflow.mjs models'"]
    C --> D["Orchestrator dispatches task via 'agentflow.mjs dispatch'"]
    D --> E["Script adds Git Worktree in runs/<run-id>/worktree on a disposable branch"]
    E --> F["Headless 'agy -p' background process runs autonomously in the worktree"]
    F --> G["Orchestrator periodically checks status and log output"]
    G -- "Task Done" --> H["Orchestrator reviews 'agentflow.mjs diff' and validates code changes"]
    H -- "Validation Fails (Self-correct up to 3x)" --> F
    H -- "Validation Passes" --> I["Orchestrator applies changes to Main Workspace using native file tools"]
    I --> J["Orchestrator updates workflows, cleans up run folder, and returns Structured Output"]

Loading

---

🛡️ License

This project is open source and available under the MIT License.