Spec + Task Management

AI-native project management with structured specs, task breakdown, and session-persistent context

The Problem: AI Session State Loss

Traditional project management tools weren't designed for AI agents. When working with AI coding assistants, you face three critical challenges:

1. Stateless Sessions

Every new AI session starts from scratch. Without structured specs, you spend 30-40% of each session re-explaining context: "There's a cart table with...", "The API is at /api/cart..."

2. Ambiguous Requirements

Vague tasks like "Add shopping cart feature" lead to scope creep and misaligned implementations. Without clear acceptance criteria, agents make assumptions that drift from intended outcomes.

3. Lost Progress Tracking

No structured way to track what files changed, what tests passed, or why decisions were made. Progress information lives in scattered commit messages or gets lost entirely.

The Solution: Structured Spec + Task Management

Agiflow provides AI-native project management with three key primitives specifically designed for agent workflows:

Planning Layer

Break down high-level requirements into concrete, actionable tasks with clear acceptance criteria. The planning layer ensures nothing is ambiguous before work begins.

→ Break work into 5-15 small, focused tasks (15min - 2 hours each)
→ Define 2-5 concrete acceptance criteria per task
→ Group related tasks (3-8) into work units for cohesive features
→ Assign tasks to appropriate agent members

Work Unit Layer

Cohesive groups of 3-8 related tasks representing a single deliverable feature (completable in one 2-4 hour session). Work units maintain structured devInfo metadata for session continuity.

→ Track execution plans, progress, and file changes
→ Store test results and implementation notes
→ Maintain session context across multiple AI interactions
→ Enable agents to resume work without manual re-explanation

Task Execution Layer

Individual units of work with acceptance criteria tracking, devInfo persistence, and mandatory code quality validation through architect MCP.

→ Track status: Todo → In Progress → Review → Done
→ Check off acceptance criteria as work progresses
→ Document files changed, test results, and session details
→ Enforce design patterns and coding standards

Project (e.g., "E-commerce Platform")
└── Work Unit (e.g., "Shopping Cart Feature")
    ├── Task 1: Database schema & migrations
    ├── Task 2: Repository layer implementation
    ├── Task 3: API endpoint creation
    └── Task 4: Integration tests

Complete Workflow

Follow this end-to-end workflow from planning to execution using AI agents and MCP tools.

Phase 1: Planning (/agiflow:plan)

Break down high-level requirements into concrete tasks and organize them into work units.

Understand Context

→ Use get-project to understand current project context
→ Use list-members to see available agent members
→ Use list-tasks to check for similar/duplicate tasks
→ Use list-work-units to understand feature organization

Break Down Into Tasks

Create 5-15 small, focused tasks (15min - 2 hours each):

→ Clear, action-oriented titles (verb-led)
→ Detailed descriptions with context
→ 2-5 concrete acceptance criteria per task
→ Order tasks by dependencies

Create Tasks & Assign Agents

Use create-task MCP tool for each task with status "Todo". Optionally assign to agent members based on expertise.

Group Into Work Units

Group 3-8 related tasks into work units when:

✅ Tasks deliver single cohesive feature
✅ Can be completed in one session (2-4 hours)
✅ Have clear dependencies
❌ Don't group: 1-2 tasks (too small)
❌ Don't group: unrelated bugs or maintenance
❌ Don't group: > 8 tasks (split into multiple work units)

Phase 2: Work Unit Execution (/agiflow:run-work)

Execute a cohesive group of tasks as a single feature in one session.

Load Work Unit

Use get-work-unit to retrieve work unit with all tasks.

Review title, goals, all tasks, dependencies, and acceptance criteria.

Start Execution

Update status to "in_progress" and document execution plan in devInfo.

Execute Tasks

For each task in dependency order:

→ Set task status to "In Progress"
→ BEFORE editing: Use get-file-design-pattern
→ Implement following acceptance criteria
→ AFTER editing: Use review-code-change
→ Update task devInfo and mark as "Done"
→ Commit changes between tasks

Track Progress

Update work unit devInfo with progress, files changed, and test results.

Complete Work Unit

Verify all tasks done, run full test suite, update status to "completed".

Phase 3: Individual Task Execution (/agiflow:run-task)

Execute a single focused task with acceptance criteria tracking.

Load Task

Use get-task to retrieve task details and acceptance criteria.

Start Task

Update status to "In Progress" and create TODO list from acceptance criteria.

Implement

For each acceptance criterion:

→ BEFORE: get-file-design-pattern
→ Implement keeping changes minimal
→ AFTER: review-code-change
→ Check off criterion, update devInfo
→ Commit incrementally

Complete Task

Verify all criteria met, run tests, update status to "Review", document files changed.

devInfo Structure

Work Units maintain structured devInfo metadata that agents programmatically access via MCP for session continuity:

// Agent reads this via get-work-unit MCP tool
{
  "devInfo": {
    "executionPlan": "Backend → Frontend → Tests",
    "progress": { "completedTasks": 2, "totalTasks": 6 },
    "filesChanged": [
      "backend/migrations/003_cart.sql:1",
      "backend/src/repos/CartRepo.ts:15"
    ],
    "commits": ["a1b2c3: Add cart schema", "d4e5f6: Cart repo"],
    "testResults": { "passed": 12, "coverage": "85%" }
  }
}

Frequently Asked Questions

What's the difference between Agiflow and OpenSpec?

OpenSpec focuses on spec-driven development with a file-based approach where specs live in openspec/specs/ and changes in openspec/changes/. It's designed for brownfield codebases (1→n modifications) and provides a lightweight specification workflow.

Agiflow extends this concept with:

→ Cloud-native specs: Specs live in the cloud, accessible via MCP, enabling multi-agent collaboration
→ Task management layer: Break specs into concrete tasks with acceptance criteria and assignees
→ Work unit orchestration: Group related tasks (3-8) into cohesive features with devInfo persistence
→ Session state tracking: Agents can resume work across sessions without re-explanation
→ Architecture enforcement: Mandatory architect MCP validation ensures code quality

Best for: OpenSpec excels at local spec management for individual developers. Agiflow is ideal for teams using multiple AI agents with cloud-backed project management.

How does Agiflow compare to GitHub Spec Kit?

GitHub Spec Kit provides a four-phase workflow (Specify → Plan → Tasks → Implement) focused on greenfield development (0→1). It's agent-agnostic and works with slash commands like /speckit.plan.

Agiflow differs in several ways:

→ Brownfield + greenfield: Designed for both new features and modifying existing code
→ Persistent specs in cloud: Not file-based; specs live in your project dashboard
→ Multi-agent by design: Built for teams with agent members (assignees, roles, capabilities)
→ Progress tracking: devInfo tracks files changed, test results, commits across sessions
→ Work unit layer: Cohesive task groups (3-8 tasks) completable in one session (2-4 hours)

Best for: Spec Kit is great for solo developers starting new features. Agiflow is built for teams managing ongoing development with multiple agents and session continuity needs.

Can I migrate from OpenSpec? How does it work?

Migrating from OpenSpec is straightforward since both use spec-driven approaches:

Import existing specs

Copy your openspec/specs/ content into Agiflow project description or create work units with the spec content in the description field.

Break down into tasks

Use /agiflow:plan to convert specs into concrete tasks with acceptance criteria. OpenSpec's implementation details become task descriptions.

Group into work units

Organize related tasks (3-8) into work units representing cohesive features. Map your OpenSpec changes to work units.

Use MCP tools

Replace OpenSpec CLI commands with Agiflow MCP tools: get-work-unit, update-task, etc. Your AI agents access specs via MCP instead of file reads.

Key benefit: You keep the spec-driven workflow you love, but gain cloud-backed collaboration, multi-agent support, and session state persistence.

Can I migrate from GitHub Spec Kit?

Agiflow complements Spec Kit's workflow by adding persistent task management and multi-agent support:

Map Spec Kit phases

Specify phase → Agiflow work unit description

Plan phase → Use /agiflow:plan for task breakdown

Tasks phase → Agiflow tasks with acceptance criteria

Implement phase → /agiflow:run-work or /agiflow:run-task

Add multi-agent workflow

Use list-members to add agent members to your project. Assign tasks to specific agents based on expertise (backend, frontend, testing).

Enable session continuity

Work units track devInfo (files changed, test results, progress) so agents can resume work across sessions without re-explanation—something Spec Kit doesn't provide.

Key benefit: Keep your four-phase workflow, but add team collaboration, agent assignments, and persistent context tracking.

How do Agile teams use Agiflow?

Agiflow maps naturally to Agile practices, augmenting human collaboration with AI agent workflows:

Sprint Planning → Planning Phase

Use /agiflow:plan during sprint planning to break user stories into concrete tasks. Product owners define work units (epics/features), developers break them into tasks with acceptance criteria.

User Stories → Work Units

Map user stories to work units (3-8 tasks). Each work unit is a deliverable feature completable in 2-4 hours—similar to story points but time-bounded for AI agent execution.

Tasks → Acceptance Criteria

Agiflow's tasks with 2-5 acceptance criteria map to Agile task definitions. The difference: AI agents execute them with mandatory code quality checks (architect MCP).

Standups → devInfo Tracking

Work unit devInfo provides real-time progress visibility. Teams see completed tasks, files changed, test results—no need to ask "what did you work on?"

Code Reviews → Task Status: Review

Tasks move to "Review" status after implementation. Human reviewers validate acceptance criteria and approve, just like traditional pull requests.

Sprint Retrospectives → Work Unit Metrics

Review work unit completion rates, blocker frequency, and devInfo notes to identify process improvements—data-driven retrospectives.

Key benefit: Agiflow doesn't replace Agile—it augments it by enabling AI agents to participate in your existing sprint workflow with structured specs and session state.

Ready to organize your development workflow?

Start using Work Units to bring structure to your AI-powered development process.

Get Started Try Agiflow Free

The Problem: AI Session State Loss

Traditional project management tools weren't designed for AI agents. When working with AI coding assistants, you face three critical challenges:

1. Stateless Sessions

Every new AI session starts from scratch. Without structured specs, you spend 30-40% of each session re-explaining context: "There's a cart table with...", "The API is at /api/cart..."

2. Ambiguous Requirements

Vague tasks like "Add shopping cart feature" lead to scope creep and misaligned implementations. Without clear acceptance criteria, agents make assumptions that drift from intended outcomes.

3. Lost Progress Tracking

No structured way to track what files changed, what tests passed, or why decisions were made. Progress information lives in scattered commit messages or gets lost entirely.

The Solution: Structured Spec + Task Management

Agiflow provides AI-native project management with three key primitives specifically designed for agent workflows:

Planning Layer

Break down high-level requirements into concrete, actionable tasks with clear acceptance criteria. The planning layer ensures nothing is ambiguous before work begins.

→ Break work into 5-15 small, focused tasks (15min - 2 hours each)
→ Define 2-5 concrete acceptance criteria per task
→ Group related tasks (3-8) into work units for cohesive features
→ Assign tasks to appropriate agent members

Work Unit Layer

Cohesive groups of 3-8 related tasks representing a single deliverable feature (completable in one 2-4 hour session). Work units maintain structured devInfo metadata for session continuity.

→ Track execution plans, progress, and file changes
→ Store test results and implementation notes
→ Maintain session context across multiple AI interactions
→ Enable agents to resume work without manual re-explanation

Task Execution Layer

Individual units of work with acceptance criteria tracking, devInfo persistence, and mandatory code quality validation through architect MCP.

→ Track status: Todo → In Progress → Review → Done
→ Check off acceptance criteria as work progresses
→ Document files changed, test results, and session details
→ Enforce design patterns and coding standards

Project (e.g., "E-commerce Platform")
└── Work Unit (e.g., "Shopping Cart Feature")
    ├── Task 1: Database schema & migrations
    ├── Task 2: Repository layer implementation
    ├── Task 3: API endpoint creation
    └── Task 4: Integration tests

Complete Workflow

Follow this end-to-end workflow from planning to execution using AI agents and MCP tools.

Phase 1: Planning (/agiflow:plan)

Break down high-level requirements into concrete tasks and organize them into work units.

Understand Context

→ Use get-project to understand current project context
→ Use list-members to see available agent members
→ Use list-tasks to check for similar/duplicate tasks
→ Use list-work-units to understand feature organization

Break Down Into Tasks

Create 5-15 small, focused tasks (15min - 2 hours each):

→ Clear, action-oriented titles (verb-led)
→ Detailed descriptions with context
→ 2-5 concrete acceptance criteria per task
→ Order tasks by dependencies

Create Tasks & Assign Agents

Use create-task MCP tool for each task with status "Todo". Optionally assign to agent members based on expertise.

Group Into Work Units

Group 3-8 related tasks into work units when:

✅ Tasks deliver single cohesive feature
✅ Can be completed in one session (2-4 hours)
✅ Have clear dependencies
❌ Don't group: 1-2 tasks (too small)
❌ Don't group: unrelated bugs or maintenance
❌ Don't group: > 8 tasks (split into multiple work units)

Phase 2: Work Unit Execution (/agiflow:run-work)

Execute a cohesive group of tasks as a single feature in one session.

Load Work Unit

Use get-work-unit to retrieve work unit with all tasks.

Review title, goals, all tasks, dependencies, and acceptance criteria.

Start Execution

Update status to "in_progress" and document execution plan in devInfo.

Execute Tasks

For each task in dependency order:

→ Set task status to "In Progress"
→ BEFORE editing: Use get-file-design-pattern
→ Implement following acceptance criteria
→ AFTER editing: Use review-code-change
→ Update task devInfo and mark as "Done"
→ Commit changes between tasks

Track Progress

Update work unit devInfo with progress, files changed, and test results.

Complete Work Unit

Verify all tasks done, run full test suite, update status to "completed".

Phase 3: Individual Task Execution (/agiflow:run-task)

Execute a single focused task with acceptance criteria tracking.

Load Task

Use get-task to retrieve task details and acceptance criteria.

Start Task

Update status to "In Progress" and create TODO list from acceptance criteria.

Implement

For each acceptance criterion:

→ BEFORE: get-file-design-pattern
→ Implement keeping changes minimal
→ AFTER: review-code-change
→ Check off criterion, update devInfo
→ Commit incrementally

Complete Task

Verify all criteria met, run tests, update status to "Review", document files changed.

devInfo Structure

Work Units maintain structured devInfo metadata that agents programmatically access via MCP for session continuity:

// Agent reads this via get-work-unit MCP tool
{
  "devInfo": {
    "executionPlan": "Backend → Frontend → Tests",
    "progress": { "completedTasks": 2, "totalTasks": 6 },
    "filesChanged": [
      "backend/migrations/003_cart.sql:1",
      "backend/src/repos/CartRepo.ts:15"
    ],
    "commits": ["a1b2c3: Add cart schema", "d4e5f6: Cart repo"],
    "testResults": { "passed": 12, "coverage": "85%" }
  }
}

Frequently Asked Questions

What's the difference between Agiflow and OpenSpec?

Agiflow extends this concept with:

→ Cloud-native specs: Specs live in the cloud, accessible via MCP, enabling multi-agent collaboration
→ Task management layer: Break specs into concrete tasks with acceptance criteria and assignees
→ Work unit orchestration: Group related tasks (3-8) into cohesive features with devInfo persistence
→ Session state tracking: Agents can resume work across sessions without re-explanation
→ Architecture enforcement: Mandatory architect MCP validation ensures code quality

Best for: OpenSpec excels at local spec management for individual developers. Agiflow is ideal for teams using multiple AI agents with cloud-backed project management.

How does Agiflow compare to GitHub Spec Kit?

Agiflow differs in several ways:

→ Brownfield + greenfield: Designed for both new features and modifying existing code
→ Persistent specs in cloud: Not file-based; specs live in your project dashboard
→ Multi-agent by design: Built for teams with agent members (assignees, roles, capabilities)
→ Progress tracking: devInfo tracks files changed, test results, commits across sessions
→ Work unit layer: Cohesive task groups (3-8 tasks) completable in one session (2-4 hours)

Best for: Spec Kit is great for solo developers starting new features. Agiflow is built for teams managing ongoing development with multiple agents and session continuity needs.

Can I migrate from OpenSpec? How does it work?

Migrating from OpenSpec is straightforward since both use spec-driven approaches:

Import existing specs

Copy your openspec/specs/ content into Agiflow project description or create work units with the spec content in the description field.

Break down into tasks

Use /agiflow:plan to convert specs into concrete tasks with acceptance criteria. OpenSpec's implementation details become task descriptions.

Group into work units

Organize related tasks (3-8) into work units representing cohesive features. Map your OpenSpec changes to work units.

Use MCP tools

Replace OpenSpec CLI commands with Agiflow MCP tools: get-work-unit, update-task, etc. Your AI agents access specs via MCP instead of file reads.

Key benefit: You keep the spec-driven workflow you love, but gain cloud-backed collaboration, multi-agent support, and session state persistence.

Can I migrate from GitHub Spec Kit?

Agiflow complements Spec Kit's workflow by adding persistent task management and multi-agent support:

Map Spec Kit phases

Specify phase → Agiflow work unit description

Plan phase → Use /agiflow:plan for task breakdown

Tasks phase → Agiflow tasks with acceptance criteria

Implement phase → /agiflow:run-work or /agiflow:run-task

Add multi-agent workflow

Use list-members to add agent members to your project. Assign tasks to specific agents based on expertise (backend, frontend, testing).

Enable session continuity

Work units track devInfo (files changed, test results, progress) so agents can resume work across sessions without re-explanation—something Spec Kit doesn't provide.

Key benefit: Keep your four-phase workflow, but add team collaboration, agent assignments, and persistent context tracking.

How do Agile teams use Agiflow?

Agiflow maps naturally to Agile practices, augmenting human collaboration with AI agent workflows:

Sprint Planning → Planning Phase

Use /agiflow:plan during sprint planning to break user stories into concrete tasks. Product owners define work units (epics/features), developers break them into tasks with acceptance criteria.

User Stories → Work Units

Map user stories to work units (3-8 tasks). Each work unit is a deliverable feature completable in 2-4 hours—similar to story points but time-bounded for AI agent execution.

Tasks → Acceptance Criteria

Agiflow's tasks with 2-5 acceptance criteria map to Agile task definitions. The difference: AI agents execute them with mandatory code quality checks (architect MCP).

Standups → devInfo Tracking

Work unit devInfo provides real-time progress visibility. Teams see completed tasks, files changed, test results—no need to ask "what did you work on?"

Code Reviews → Task Status: Review

Tasks move to "Review" status after implementation. Human reviewers validate acceptance criteria and approve, just like traditional pull requests.

Sprint Retrospectives → Work Unit Metrics

Review work unit completion rates, blocker frequency, and devInfo notes to identify process improvements—data-driven retrospectives.

Key benefit: Agiflow doesn't replace Agile—it augments it by enabling AI agents to participate in your existing sprint workflow with structured specs and session state.

Spec + Task Management

The Problem: AI Session State Loss

1. Stateless Sessions

2. Ambiguous Requirements

3. Lost Progress Tracking

The Solution: Structured Spec + Task Management

Planning Layer

Work Unit Layer

Task Execution Layer

Complete Workflow

Phase 1: Planning (/agiflow:plan)

Understand Context

Break Down Into Tasks

Create Tasks & Assign Agents

Group Into Work Units

Phase 2: Work Unit Execution (/agiflow:run-work)

Load Work Unit

Start Execution

Execute Tasks

Track Progress

Complete Work Unit

Phase 3: Individual Task Execution (/agiflow:run-task)

Load Task

Start Task

Implement

Complete Task

devInfo Structure

Frequently Asked Questions

Import existing specs

Break down into tasks

Group into work units

Use MCP tools

Map Spec Kit phases

Add multi-agent workflow

Enable session continuity

Related Documentation

Project MCP

Agent Members

Ready to organize your development workflow?

Spec + Task Management

The Problem: AI Session State Loss

1. Stateless Sessions

2. Ambiguous Requirements

3. Lost Progress Tracking

The Solution: Structured Spec + Task Management

Planning Layer

Work Unit Layer

Task Execution Layer

Complete Workflow

Phase 1: Planning (/agiflow:plan)

Understand Context

Break Down Into Tasks

Create Tasks & Assign Agents

Group Into Work Units

Phase 2: Work Unit Execution (/agiflow:run-work)

Load Work Unit

Start Execution

Execute Tasks

Track Progress

Complete Work Unit

Phase 3: Individual Task Execution (/agiflow:run-task)

Load Task

Start Task

Implement

Complete Task

devInfo Structure

Frequently Asked Questions

Import existing specs

Break down into tasks

Group into work units

Use MCP tools

Map Spec Kit phases

Add multi-agent workflow

Enable session continuity

Related Documentation

Project MCP

Agent Members

Ready to organize your development workflow?