Open-source Agile Format for AI coding agents
AgileSpec
Bring clearer structure, better coordination, and stronger quality checks to AI-driven development.
Product
Features
Specs
Develop
Installation
npmi -g @agilespec/cli@latest
What Is AgileSpec?
A simplified agile methodology for harnessing coding agents
AI-friendly workflow
AgileSpec helps agents understand what to build, how to build it, and how to verify it.
Shared structure
It gives humans and agents a clearer process for working on the same project.
The Five Pillars
Meet the practices that AgileSpec harnesses to move your work in the right order.
Scrum
The manager that keeps the work moving in the right order.
SDD
The architect that turns ideas into a clear project shape.
BDD
The user that describes behavior in simple, testable steps.
TDD
The engineer that protects quality as the code takes shape.
AGENTS.md Support
The widely adopted standard for cross agent compatibility. Built to work with shared agent rules across different AI coding tools.
Why It Works
AgileSpec turns complex work into a clear, granular level, repeatable flow.
High-velocity workflow
AgileSpec keeps structure, visibility, and verification working together.
Multi-agent alignment
Multiple agents can move together without stepping on each other.
Human-in-the-loop
People stay in control at every meaningful step.
How to Use
Experience effortless setup and maximize your project's effectiveness with an intuitive workflow.
Initialize the project
npmi -g @agilespec/cli@latest
cd/path/to/your/project
agilespecinit
npx@agilespec/cli@latest init
Open your coding agent and start the product development cycle
user:/agile-init or "Start an AgileSpec session"
agent:I validated the project is already initialized, I will start a /agile-refine-session to understand the project better.
agent:What would you like to build? Please describe the features or the high-level goal of this project.
user:I want to build a Task Management CLI for adding tasks on the fly, and store them in superlight JSON database.
agent:I will start a /agile-feature-add to add the new feature to the project.
agent:Based on your requirement, we have a new feature for this project:
┌───────────┬─────────────────────┬─────────────┐
│ ID │ Title │ Status │
├───────────┼─────────────────────┼─────────────┤
│ ft-000001 │ Task Management CLI │ NOT-STARTED │
└───────────┴─────────────────────┴─────────────┘
agent:And we have three user stories on backlog:
┌───────────┬─────────────────────────────┬─────────────┐
│ ID │ Title │ Status │
├───────────┼─────────────────────────────┼─────────────┤
│ st-000001 │ Initialize database storage │ NOT-STARTED │
├───────────┼─────────────────────────────┼─────────────┤
│ st-000002 │ Add a task via CLI │ NOT-STARTED │
├───────────┼─────────────────────────────┼─────────────┤
│ st-000003 │ List all tasks │ NOT-STARTED │
└───────────┴─────────────────────────────┴─────────────┘
agent:I recommend beginning with st-000001: Initialize database storage. Shall I proceed?
user:Yes please start working that feature
agent:I will start the user story st-000001.
agent:I've completed the implementation of the database storage initialization!
### Achievements:
- st-000001: Initialize database storage:
Successfully set up db.js to initialize an empty tasks.json file if it doesn't exist.
All tests passed.
The story is now IN-REVIEW.
You can review the code or let me know if I should proceed with the next story: st-000002: Add a task via CLI.
Should I mark st-000001 as DONE and start working on adding tasks?
user:Yes please go ahead.
agent:I've completed the implementation of adding tasks via the CLI!
### Achievements:
- st-000002: Add a task via CLI: Implemented the addTask function in db.js
Updated index.js to handle the add command.
You can now run node index.js add "My task".
The story is now IN-REVIEW. If you approve,
I'll mark it as DONE and move on to the final story: st-000003: List all tasks.
user:I reviewed, approved
agent:I've completed the implementation of listing all tasks!
### Achievements:
- st-000003: List all tasks: Implemented the getTasks function in db.js
Added the list command to index.js.
It now displays all tasks with their status, or a friendly message if the list is empty.
The story is now IN-REVIEW. All tests (both database logic and CLI integration) are passing.
Once you approve this final story, I will mark the entire feature ft-000001 as DONE.
user:The story looks ok, approved
agent:I've completed the Task Management CLI!
### Summary of Achievements:
- st-000001: Initialize database storage: Set up the JSON persistence layer.
- st-000002: Add a task via CLI: Implemented adding tasks with unique IDs.
- st-000003: List all tasks: Implemented the display of all saved tasks.
The feature ft-000001: Task Management CLI is now officially DONE.
You can use the CLI now:
- node index.js add "Learn AgileSpec"
- node index.js list
Skills
Explore the skills that drive each step of the workflow.
/agile-init
Initialize the project and create the AgileSpec workspace.
/agile-refine-session
Review the project structure and refine specific requirements.
/agile-feature-add
Register a new high-level requirement as a feature.
/agile-feature-comment
Add a comment to a feature.
/agile-feature-slice
Break a feature into smaller, actionable slices.
/agile-story-add
Create a user story for a specific requirement.
/agile-story-comment
Add a comment to a user story.
/agile-story-start
Move a story into active implementation.
/agile-story-in-review
Send a completed story to review.
/agile-story-done
Mark a verified story as complete.
Lifecycle Status
Watch your workflow come alive as every status reveals the next step.
WAITING-ON-DEPENDENCY
The work cannot start yet because a prerequisite is missing.
NOT-STARTED
The path is clear and the story is ready to be picked up.
IN-PROGRESS
Work is actively moving forward.
BLOCKED
Progress is paused until the next input or decision arrives.
CANCELED / REJECTED
The work is no longer moving forward or did not meet the required standard.
IN-REVIEW
The work is complete and waiting for validation.
DONE
The work is verified, tested, and finished.
Governance
Learn the guardrails that keep the process honest and reliable.
Anti-greenwashing
The project should not pretend work is complete by changing tests instead of fixing the code.
-
[*]Immutable Standards Uses the User Story file, and Requirement Docs as the single source of truth that cannot be modified by the AI.
-
[*]External Auditing Maintains clear separation between the agent’s implementation code and the requirements.
-
[*]Truth-Based Completion Requires the agent to provide evidence of passing original requirements, preventing the 'faking' of progress.
Non-Negotiable Tests
Immutable behavioral guardrails that the AI cannot modify without explicit human authorization.
-
[*]Quality Gate Establishes objective, pass-fail behavioral requirements that cannot be ignored or bypassed.
-
[*]Gherkin Specification Uses human-readable Gherkin syntax to ensure clear, unambiguous expectations for functionality.
-
[*]Verification-First Mandates that the agent proves code integrity through these immutable, protected guardrails before a task can be marked complete.
Dependency tracking
Clear dependency links help multiple agents coordinate safely.
-
[*]Logical Sequencing Prevents tasks from starting until their specific prerequisite conditions are fully satisfied.
-
[*]Automated Validation Uses a reactive graph to physically check the backlog status before unlocking new work.
-
[*]Safe Orchestration Coordinates multi-agent development by ensuring no work begins on unstable or unbuilt foundational features.
More
Get a quick look at what is coming next for AgileSpec.
Still evolving
AgileSpec is still growing and more documentation will be added over time.