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
│       ├── disabled-models.json
│       ├── references/
│       │   ├── execution-examples.md
│       │   └── expansion-templates.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 sequencer in your chat session by prefixing commands with /agentflow:

/agentflow implement user registration with JWT authentication

Control Commands

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

Command	Action	Description
/status <task-id>	Print Status	Shows completed steps, pending steps, and last logs
/retry <task-id>	Retry	Re-executes the last failed step from the saved state
/pause	Pause	Pauses execution and saves the current state
/resume	Resume	Resumes execution from the last saved state
/stop	Stop	Halts execution completely

---

⚙️ How the Autonomous Pipeline Works

AgentFlow operates as a structured, non-blocking pipeline:

graph TD
    A["/agentflow <instruction>"] --> B["Command Intercept & CLI Dispatch"]
    B --> C["Workspace & Context Scan (.agents/workflows/)"]
    C --> D["Prompt Expansion (Gemini 3.1 Pro)"]
    D --> E["Domain Classification & Model Routing"]
    E --> F["Autonomous Execution (Claude/Gemini)"]
    F --> G["Post-Execution Validation (Dynamic Test/Build Check)"]
    G -- "Fail (Retry up to 3x)" --> F
    G -- "Success" --> H["Persist State to state/<id>.json"]
    H --> I["Update task-history.md & Sync Workflows"]
    I --> J["Return Structured Output Block"]

Loading

---

🛡️ License

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