How Project Management Agents Convert Specifications into Executable Task Lists

Project management agents in the Agency-Agents repository convert specifications into executable task lists by reading ai/memory-bank/site-setup.md, extracting technical requirements, and generating discrete markdown tasks with acceptance criteria.

The Agency-Agents open-source project implements deterministic workflows through declarative Markdown "personality" files. Agents like SeniorProjectManager and Project Shepherd transform raw site specifications into developer-ready task lists without external orchestration, storing results in a shared memory bank for downstream consumption.

The Five-Step Workflow for Converting Specifications

The conversion process follows a rigid pipeline encoded directly in the agent's Markdown definition. Each step maps to specific sections within project-management/project-manager-senior.md.

Step 1: Specification Analysis

The agent begins by reading the actual specification file at ai/memory-bank/site-setup.md. According to lines 20-24 in project-manager-senior.md, the agent extracts exact requirement text and quotes the original specification lines verbatim. This prevents hallucination of "luxury" features not present in the source document.

Step 2: Gap Identification

The agent scans for missing or ambiguous requirements. As noted in lines 22-23 of the personality file, the agent highlights gaps and prompts for clarification when specifications contain vague points. This ensures the resulting task list contains only actionable, well-defined work units.

Step 3: Technical Stack Extraction

The agent parses the "stack" section at the bottom of site-setup.md to identify the development framework. Lines 31-36 in project-manager-senior.md define this extraction process, capturing technologies like Laravel, Livewire, or FluxUI for later reference in task definitions.

Step 4: Task List Generation

Using the Task List Format Template (lines 51-101), the agent breaks specifications into discrete, 30-60 minute developer tasks. Each task entry includes:

• Description: Concise explanation of the work
• Acceptance Criteria: Testable conditions for completion
• Files to Create/Edit: Specific file paths affected
• Reference: Link to the original specification section

Step 5: Persistence and Storage

The agent writes the completed markdown file to ai/memory-bank/tasks/[project-slug]-tasklist.md, as specified in line 27. The project slug derives automatically from the project name defined in the specification. This persistence makes the task list available to downstream agents and external tools.

Task List Structure and Template Format

The generated task lists follow a strict markdown schema defined in the agent's personality file. Below is a minimal example showing how a landing page specification converts into executable tasks:

# AwesomeLandingPage Development Tasks

## Specification Summary

**Original Requirements**:  
- A single‑page landing site with Hero, Features, and Contact sections.  
- Responsive layout, light‑weight CSS, no background processes.  

**Technical Stack**: Laravel, Livewire, FluxUI  

## Development Tasks

### [ ] Task 1: Basic Page Structure

**Description**: Create main page layout with header, hero, features, contact, and footer.  
**Acceptance Criteria**:
- Page loads without errors.
- All sections from the spec are present.
- Basic responsive layout works on desktop & mobile.

**Files to Create/Edit**:
- `resources/views/home.blade.php`
- `public/css/app.css`

**Reference**: Section “Page Layout” of specification.

### [ ] Task 2: Navigation Implementation

**Description**: Implement working navigation with smooth scroll and mobile hamburger menu.  
**Acceptance Criteria**:
- Navigation links scroll to correct sections.
- Mobile menu opens/closes.
- Active state highlights current section.

**Components**: `flux:navbar`, Alpine.js interactions  
**Reference**: “Navigation” requirements in spec.

The agent automatically writes this file to ai/memory-bank/tasks/awesome-landing-page-tasklist.md upon completion.

Key Implementation Files

The conversion workflow relies on these specific files within the Agency-Agents repository:

File	Role	Location
project-manager-senior.md	Core definition of the Senior Project Manager agent containing specification parsing logic, task-list template, and persistence rules.	project-management/project-manager-senior.md
project-management-project-shepherd.md	Higher-level orchestration agent that manages task lists within broader work-breakdown structures.	project-management/project-management-project-shepherd.md
convert.sh	Conversion script that transforms agent Markdown files into formats for external tools (OpenCode, Gemini-CLI, etc.).	scripts/convert.sh

Integration with External Tools

While the agent creates task lists in pure Markdown, the repository includes scripts/convert.sh to bridge external development environments. This script consumes every .md file under domain folders (project-management, design, etc.) and emits tool-specific bundles.

Importantly, convert.sh does not influence how the task list is built—it simply propagates the agent's Markdown output to formats like OpenCode's .opencode/agent/*.md structure. The task generation logic remains entirely declarative within the agent's personality definition.

Summary

• Project management agents convert specifications into executable task lists through a deterministic, five-step workflow defined in Markdown personality files.
• The process involves reading ai/memory-bank/site-setup.md, extracting exact requirements, identifying gaps, parsing the technical stack, and generating discrete 30-60 minute tasks.
• Each task includes description, acceptance criteria, file references, and specification links, stored in ai/memory-bank/tasks/[project-slug]-tasklist.md.
• The workflow is fully declarative, residing in files like project-manager-senior.md, with scripts/convert.sh handling external tool integration without modifying the core logic.

Frequently Asked Questions

What is the primary source file for specifications?

The agent reads specifications from ai/memory-bank/site-setup.md. According to the Senior Project Manager definition at lines 20-24, the agent extracts exact requirement text from this file and quotes it verbatim to prevent feature hallucination.

How does the agent handle missing requirements?

During the gap identification phase, the agent scans for ambiguous or missing items in the specification. As defined in project-manager-senior.md lines 22-23, the agent highlights these gaps and prompts for clarification before generating tasks, ensuring only well-defined work units enter the task list.

What format does the generated task list use?

The task list uses strict Markdown following the Task List Format Template defined in project-manager-senior.md lines 51-101. Each task includes a description, acceptance criteria, files to create or edit, and references to the original specification section.

How do external tools consume these task lists?

External tools consume task lists through the scripts/convert.sh script, which transforms the agent's Markdown output into tool-specific formats like OpenCode's .opencode/agent/*.md structure. The conversion script does not modify the task generation logic; it simply propagates the declarative agent definitions to external environments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}