Skip to content
/
Tier A A8 Cross-runtime harness

APM (Agentic Project Management)

apm-agentic-project-mgmt · sdi2200262/agentic-project-management · ★ 2.3k · last commit 2026-05-20

Manages complex multi-session software projects by coordinating specialized AI agents (Planner/Manager/Workers) with human-mediated message relay and structured Handoff when context fills.

Best whenThe human should be the deliberate relay point between agents — making every step visible and auditable — rather than automating away developer oversight.
Skip ifImplementing before planning documents are approved, Workers operating outside their assigned domain
vs seeds
bmad-methodin its Planner/Manager/Worker hierarchy and Markdown planning documents, but distinguishes itself by making the human th…
Primitive shape 16 total
Commands 9 Skills 4 Subagents 3
00

Summary

APM (Agentic Project Management) — Summary

APM is an open-source framework for managing ambitious software projects with AI assistants by structuring work across a coordinated team of three specialized agent types — Planner, Manager, and Workers — each operating in its own conversation context.

Problem it solves: Single AI chat sessions accumulate context debt on complex projects, causing agents to lose track of requirements, produce bad code, and hallucinate details. APM counteracts this by isolating each agent to just the information it needs and providing a structured Handoff mechanism when context fills.

Distinctive trait: The human acts as a deliberate message bus — running numbered commands to deliver Task Prompts to Workers and report results back to the Manager — making every step visible and giving full control over pacing and mid-task intervention, without losing the accumulated working context of each agent.

Target audience: Developers and teams using Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, or OpenCode who want a transparent, auditable project management workflow for complex multi-stage software development.

Production-readiness: Production-ready at v1.0+; actively maintained by the community with 2,296 stars, 7 contributors, and a full documentation site at agentic-project-management.dev. CLI available as apm via npm.

Differs from seeds: Most similar to BMAD-METHOD in its multi-agent persona model (Planner/Manager/Worker), but differs fundamentally in that APM makes the human the explicit relay point between agents rather than using autonomous sub-agent dispatch; unlike claude-flow which uses SQLite + HNSW memory and spawns agents as subprocesses, APM persists state in plain Markdown files outside all agent contexts, and the orchestration is human-mediated rather than machine-automated.

01

Overview

APM — Origin and Philosophy

Origin

APM was created by sdi2200262 (Discord: cobuter_man) and released under MPL-2.0. Versions prior to v0.4.0 were MIT. The v1.0.0 release was a ground-up redesign from the earlier v0.5.x codebase (preserved on the v0.5.x branch). The framework is published as agentic-pm on npm.

Philosophy

The core insight of APM is stated in the README:

"What distinguishes this from subagent-based approaches: the agents doing implementation work are not restarted fresh on each task. They accumulate working context across assignments — building familiarity with their domain as the project progresses."

And on the communication design:

"You mediate every exchange between agents by running commands in the appropriate conversation. This keeps every step visible and auditable, letting you set the pace and review work at each stage."

The framework takes an explicit stance against fully-autonomous "set and forget" agent systems. The human is not a passive observer — they are the routing layer. This design is intentional:

"APM is for people who build with AI agents and own what they ship. Delivering each message between agents is a built-in checkpoint; you see every task assignment before it reaches a Worker and every result before the Manager acts on it."

Architecture principles

  1. Context isolation — each agent type (Planner, Manager, Worker) runs in a separate conversation with only the context it needs
  2. Persistent state outside all contexts — planning documents (Spec, Plan, Rules, Tracker) live in .apm/ files on disk, readable by any agent
  3. Structured handoff over fresh start — when a context fills, Handoff transfers working knowledge to a fresh instance rather than losing it
  4. Human as relay point — numbered commands (/apm-1-initiate-planner, /apm-4-check-tasks, etc.) make the orchestration legible and stoppable at any point

Official custom adaptations

  • APM Auto — replaces human relay with autonomous subagent dispatch via Agent(); best for prototyping
  • APM Semi — human can claim any task to execute directly while AI stays on standby
02

Architecture

APM — Architecture

Distribution

Install

npm install -g agentic-pm
cd your-project
apm init

Then in the AI assistant: /apm-1-initiate-planner

Required runtime

  • Node.js (for CLI)
  • Any supported AI tool: Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, OpenCode

Target AI tools

Claude Code, Codex CLI, Cursor, GitHub Copilot, Gemini CLI, OpenCode — selected at apm init time

Directory structure (after apm init)

your-project/
├── .apm/
│   ├── spec.md          # What to build (design decisions, constraints)
│   ├── plan.md          # How work is organized (Stages, Tasks, Workers)
│   ├── tracker.md       # Project state (completion status per task)
│   ├── rules.md         # How work is performed (coding conventions)
│   ├── memory/
│   │   └── index.md     # Memory notes + Stage summaries
│   └── bus/
│       ├── manager/
│       │   └── handoff.md
│       └── <worker-slug>/
│           ├── task.md      # Task Prompt delivered here
│           ├── report.md    # Worker writes Task Report here
│           └── handoff.md   # Handoff knowledge when context fills
├── .apm/archives/       # Archived completed sessions

CLI commands

Command Purpose
apm init Initialize workspace with official templates
apm custom -r owner/repo Install from custom fork
apm update Update to latest compatible version
apm archive Archive current session
apm add / remove Add or remove AI assistant
apm status Show installation state

Template structure installed

templates/
├── commands/            # 9 slash commands
│   └── apm-1-initiate-planner.md
│   └── apm-2-initiate-manager.md
│   └── apm-3-initiate-worker.md
│   └── ...
├── agents/              # Archive explorer agent
├── guides/              # Context gathering, task assignment, etc.
├── skills/              # apm-communication skill
└── apm/                 # Planning document templates (spec.md, plan.md, tracker.md)
03

Components

APM — Components

Slash Commands (9)

Installed to .claude/commands/ (or equivalent per AI tool):

Command Purpose
apm-1-initiate-planner Start Planner agent; runs context gathering + work breakdown + produces Spec/Plan/Rules
apm-2-initiate-manager Start Manager agent; reads planning docs, confirms VC conventions, begins coordination
apm-3-initiate-worker Start a Worker agent in a domain (frontend, backend, etc.)
apm-4-check-tasks Run in Worker chat: Worker executes task, validates, logs, writes report
apm-5-check-reports Run in Manager chat: Manager reads Worker reports, reviews, updates tracker
apm-6-handoff-manager Initiate Manager Handoff to fresh instance when context fills
apm-7-handoff-worker Initiate Worker Handoff to fresh instance when context fills
apm-8-summarize-session Create session summary for archiving
apm-9-recover Recover from failures or interrupted sessions

Skills (2)

Skill Purpose
apm-communication Message Bus protocol, agent slug format, task/report format standards
apm-customization Guides AI agents through customizing APM for team-specific needs

Standalone Skills (2 additional)

Skill Purpose
apm-assist APM-aware helper for any project: explains APM, detects version, answers questions from live docs
apm-archive-explorer Agent for exploring archived sessions

Planning Document Templates

Template Content
spec.md What to build: design decisions, constraints, references, stakeholder intent
plan.md How work is organized: Stages, Tasks, Workers, dependencies
tracker.md Project state: task status, version control table, Worker assignments
rules.md How work is performed: coding conventions, commit formats, quality gates
memory/index.md Memory notes and Stage summaries

Guides (in templates/guides/)

  • context-gathering — Planner guide: deep codebase exploration, iterative question rounds
  • work-breakdown — Planner guide: Spec/Plan/Rules creation with approval checkpoints
  • task-assignment — Manager guide: dispatch assessment, Task Prompt construction
  • task-review — Manager guide: Task Review procedure, review outcomes, parallel coordination

Message Bus (runtime files)

  • .apm/bus/<agent-slug>/task.md — Manager writes Task Prompt here; Worker reads
  • .apm/bus/<agent-slug>/report.md — Worker writes Task Report here; Manager reads
  • .apm/bus/<agent-slug>/handoff.md — Outgoing agent writes Handoff knowledge here
  • .apm/bus/manager/handoff.md — Manager Handoff bus

Agent Types (3)

Agent Role
Planner Conducts project discovery, produces Spec + Plan + Rules
Manager Coordinates execution: assigns Tasks, reviews reports, maintains Tracker
Worker Executes Tasks in a specific domain; logs to memory, reports to Manager
05

Prompts

APM — Prompt Files (Verbatim Excerpts)

Excerpt 1: Planner Initiation Command (apm-1-initiate-planner.md)

Technique: Procedural decomposition with explicit phase gates and authority hierarchy

---
command_name: initiate-planner
description: Initiate an APM Planner.
---

# APM {VERSION} - Planner Initiation Command

## 1. Overview

You are the **Planner** for an Agentic Project Management (APM) session. **Your sole purpose
is to gather requirements and produce three planning documents - Spec, Plan, and Rules - that
other agents (Manager and Worker) use to execute the project.**

All necessary guides are available in `{GUIDES_DIR}/`. **Read every referenced document in
full - every line, every section.** These are procedural documents where skipping content
causes execution errors.

**Initiation context from User:** {ARGS}

If the line above contains text, the User has front-loaded project context. This may establish
which materials are authoritative and focus discovery. Do not skip Context Gathering regardless
of how much context is provided.

## 2. Workspace Discovery and Authority

Before reading the Context Gathering guide, scan the workspace and establish which materials
are authoritative. This determines what you carry into Context Gathering.

Perform the following actions:
1. Light scan: list root directory structure, identify git repositories and their recent
   commit history and branch structure, locate materials that could inform planning (PRDs,
   requirements docs, specifications, design docs, TODOs). Check if `.apm/archives/` exists.
   Read `{RULES_FILE}` if it exists.
   
2. Assess what you found in step 1 against the initiation context:
   - Materials and archives identified directly or implicitly by the initiation context are
     authoritative. Read them and proceed to §3 Context Gathering Procedure without pausing
     for User confirmation.
   - Materials not clearly established as relevant - pause and ask the User which are current
     and relevant before reading them.
   - When there is no initiation context, ask the User about everything you found in step 1.

## 5. Planning Phase Completion

Perform the following actions:
1. Initialize the Message Bus. Read the Plan to identify all Workers defined in the Workers
   field. For each Worker, derive the agent slug (lowercase, hyphenated name) per
   `{SKILL_PATH:apm-communication}` §4.3 Agent Slug Format and create the agent directory:
   - Create directory: `.apm/bus/<agent-slug>/`
   - Create empty Task Bus: `.apm/bus/<agent-slug>/task.md`
   - Create empty Report Bus: `.apm/bus/<agent-slug>/report.md`
   - Create empty Handoff Bus: `.apm/bus/<agent-slug>/handoff.md`

Excerpt 2: Manager Initiation Command — Continuous Coordination loop (apm-2-initiate-manager.md)

Technique: State machine pattern — explicit evaluation of condition after each step, looping without user input

## 3. Continuous Coordination

After each review, reassess readiness and continue to dispatch in the same turn when Tasks
are Ready without waiting for User input per `{GUIDE_PATH:task-review}` §2.4 Parallel
Coordination Standards. Repeat until all Stages complete, User input is needed, User
intervenes, or Handoff is needed.

1. **Dispatch:** Run dispatch assessment per `{GUIDE_PATH:task-assignment}` §3.1 Dispatch
   Assessment, construct and deliver Task Prompt(s) per `{GUIDE_PATH:task-assignment}` §3.3
   Task Prompt Construction. Direct User to the Worker(s).

2. **Await Report:** User runs `/apm-4-check-tasks` in Worker chat(s). Workers execute,
   validate, log, and write Task Report(s) to Report Bus. User runs `/apm-5-check-reports`
   in this chat.

3. **Review and Continue.** Process the report per `{GUIDE_PATH:task-review}` §3 Task
   Review Procedure: review the Task Log, investigate further if needed and determine review
   outcome, modify planning documents if needed, update the Tracker. Then in the same turn:
   - *Tasks Ready:* Continue to step 1.
   - *No Tasks Ready, Workers active:* Communicate wait state and direct User to return
     the next report (repeat step 2).
   - *Follow-up needed:* Construct refined prompt (repeat step 2).
   - *Stage complete:* Stage summary, then continue to step 1 for next Stage. If all
     Stages complete, proceed to §4 Project Completion.

Prompting techniques observed

  1. Version template substitution — {VERSION}, {GUIDES_DIR}, {GUIDE_PATH:name}, {SKILL_PATH:name} are replaced by the CLI at install time with real paths
  2. Explicit authority hierarchy — "guide > plan > description" ordering prevents agent from picking silently between conflicting instructions
  3. State machine loops — numbered steps with conditional branching (*Tasks Ready:* Continue to step 1) keep the Manager in coordination without user prompting
  4. Separation of roles — each agent type has a different command with strict scope boundaries ("Read only the APM documents listed in this command")
09

Uniqueness

APM — Uniqueness and Positioning

Differs from seeds

APM is closest to BMAD-METHOD in its Planner/Manager/Worker persona structure and its use of Markdown planning documents as first-class artifacts. However, APM differs in three key ways: (1) the human is the deliberate message relay between agents rather than automated subagent dispatch; (2) state persistence is file-based .apm/ Markdown (not memory-indexed like claude-flow's SQLite) with no auto-compaction; (3) APM's Handoff mechanism explicitly transfers accumulated working knowledge to a fresh agent instance rather than relying on the agent to summarize its own context on demand. Compared to spec-kit and openspec, APM focuses on ongoing project management coordination rather than per-feature spec authoring — it governs the entire project lifecycle across multiple sessions, not individual feature implementation cycles. Compared to taskmaster-ai, APM adds the Manager coordination layer and the Handoff mechanism; Taskmaster manages a flat task list while APM organizes work into Stages with domain-specialized Workers.

Positioning

APM targets the class of projects where: (a) the codebase is large enough that context limits become a real problem mid-session; (b) the work involves multiple domains requiring specialized focus; (c) the developer wants visibility into and control over every agent decision. It fills the gap between single-session tools (spec-kit, superpowers) and fully-autonomous multi-agent systems (claude-flow, APM Auto).

Observable failure modes

  1. Human relay fatigue — shuttling messages between conversations manually becomes tedious on large projects with many tasks and Workers; APM Auto exists to address this
  2. Planning quality dependence — if the Planner's Spec/Plan/Rules are thin or incorrect, all downstream work diverges; there's no spec-verification step after implementation
  3. File proliferation — .apm/ grows with each session; archives help but the framework doesn't have automated cleanup
  4. Parallel cost — running multiple AI tool sessions simultaneously multiplies subscription costs; APM provides no cost tracking or budget alerts

Explicit antipatterns

  • Jumping into implementation before the three planning documents are approved
  • Workers executing tasks outside their assigned domain
  • Skipping sections of procedural guides ("These are procedural documents where skipping content causes execution errors")
  • Merging PRs without Manager review of the Task Report
04

Workflow

APM — Workflow

Phases

Phase What Happens Artifacts Produced
1. Planning Planner runs context gathering (3 iterative question rounds), deep codebase exploration, and work breakdown spec.md, plan.md, rules.md, Message Bus directories
2. Implementation Prep Manager reads all planning docs, confirms VC conventions with user, generates first Task Prompt(s) tracker.md populated, .gitignore updated, branch conventions confirmed
3. Task Execution Human runs /apm-4-check-tasks in Worker chat; Worker executes, validates, logs, writes report Task Log in .apm/, .apm/bus/<worker>/report.md filled
4. Review & Dispatch Human runs /apm-5-check-reports; Manager reviews report, updates tracker, dispatches next task(s) tracker.md updated, planning docs potentially revised
5. Stage Completion Manager creates Stage summary; proceeds to next Stage Stage summary written to .apm/memory/index.md
6. Project Completion All Stages done; Manager writes completed_at timestamp Final project summary presented

Handoff Mechanism

When an agent's context fills:

  1. Current agent writes accumulated working knowledge to its Handoff Bus file
  2. Human starts fresh instance of same agent type in new conversation
  3. New instance reads Handoff Bus and continues without gaps

Approval Gates

Gate Type When
Understanding summary + VC conventions freetext-clarify After Planner context gathering; must be approved before work breakdown
Spec approval freetext-clarify Planner presents Spec; must be approved before Plan creation
Plan approval freetext-clarify Planner presents Plan; must be approved before Rules creation
Rules approval freetext-clarify Planner presents Rules; must be approved before Manager initiation
Task assignment review yes-no User sees each Task Prompt before it reaches a Worker
Work result review yes-no User sees each report before Manager acts on it

Parallel coordination

The Manager can dispatch multiple Workers simultaneously when tasks have no dependencies. Each Worker runs in its own conversation context with its own git worktree. The Manager waits for reports from active Workers and continues dispatch in the same turn when tasks become ready.

06

Memory Context

APM — Memory and Context

State storage

All project state lives in plain Markdown and YAML files under .apm/ — outside any agent's context window.

File Content Who writes Who reads
.apm/spec.md Design decisions, constraints, stakeholder intent Planner Manager, Workers
.apm/plan.md Stages, Tasks, Workers, dependencies Planner Manager, Workers
.apm/rules.md Coding conventions, commit formats, quality gates Planner, Manager Workers
.apm/tracker.md Task completion status, VC conventions Manager Manager (between sessions)
.apm/memory/index.md Memory notes + Stage summaries Workers, Manager Manager (for context)
.apm/bus/<worker>/task.md Task Prompt Manager Worker
.apm/bus/<worker>/report.md Task Report (execution log, validation results, deliverables) Worker Manager
.apm/bus/<worker>/handoff.md Accumulated working knowledge for Handoff Current agent Incoming agent
.apm/archives/ Archived session files CLI (apm archive) Archive Explorer agent

Persistence

  • Per-project — .apm/ is typically gitignored by default (with user opt-in to track planning docs)
  • Session-spanning — because state is file-based, sessions can be paused and resumed; new agent instances pick up from Tracker + Memory Index
  • Handoff — structured transfer between instances of the same agent type when context fills, preserving accumulated working knowledge

Context compaction handling

APM addresses context limits proactively: when a Worker or Manager approaches context saturation, the Handoff mechanism is used. The outgoing agent writes a summary of:

  • Current task state and in-progress work
  • Key decisions made
  • Known issues and blockers
  • What the incoming instance should do next

This is written to .apm/bus/<agent>/handoff.md before the session ends.

Cross-session continuity

The Manager reads .apm/tracker.md, .apm/memory/index.md, .apm/plan.md, .apm/spec.md, and rules.md on each initiation — whether it's the first Manager or an incoming Handoff instance. This ensures full project continuity across sessions.

Search mechanism

None — agents read files directly via file system tools. No vector search or semantic retrieval.

07

Orchestration

APM — Orchestration

Multi-agent pattern

Hierarchical — Planner → Manager → Worker(s). The Manager coordinates Workers; the human relays messages between conversations.

Execution mode

Interactive-loop — the human is the explicit relay. Each step requires a command run in the right conversation. This is not a set-and-forget autonomous system; every task assignment and report is a human checkpoint.

Subagent definition format

persona-md — each agent type is a Markdown command file (apm-1-initiate-planner.md, apm-2-initiate-manager.md, apm-3-initiate-worker.md) that establishes role, scope, and operating rules when loaded into an AI session.

Spawn mechanism

Human-mediated. The human opens a new conversation with the target AI tool and runs the appropriate initiation command. No programmatic subprocess spawning.

Official autonomous variant

APM Auto (sdi2200262/apm-auto) — replaces the human relay with Manager-autonomous subagent dispatch via the Agent() tool. The Manager spawns ephemeral Workers, reviews output, and continues without user involvement.

Isolation mechanism

git-worktree (supported, documented) — the Manager recommends a worktree per Worker when parallel dispatch is active, each Worker getting its own branch and working directory.

Multi-model

No — APM does not prescribe specific models; users select their AI tool at install time. All agents use the same tool/model the user has configured.

Consensus mechanism

None — Manager has final authority over task review outcomes. Workers do not vote or negotiate.

Parallel fan-out

Yes — the Manager can dispatch multiple Workers simultaneously (parallel tasks within a Stage), directing the human to run /apm-4-check-tasks in multiple conversations concurrently. Manager waits for reports before acting on them.

Prompt chaining

Yes — the Planner's output (Spec, Plan, Rules) becomes the input context for the Manager's initiation; the Manager's Task Prompt is the Worker's operating context for each task; the Worker's Task Report is the Manager's input for review.

Crash recovery

Yes — the Handoff mechanism and persistent file-based state allow recovery from any agent failure: read the Tracker and Memory Index, initiate a new agent instance.

08

Ui Cli Surface

APM — UI and CLI Surface

CLI binary

apm — dedicated CLI binary installed via npm install -g agentic-pm.

Subcommands

Subcommand Purpose
apm init Initialize workspace with official templates for selected AI tool
apm custom -r owner/repo Install from a custom fork/template repository
apm update Update to latest compatible version
apm archive Archive current session or manage archives
apm add Add a new AI assistant profile
apm remove Remove an AI assistant profile
apm status Show installation state and current version

The CLI is not a thin wrapper over claude/codex CLI — it installs templates into the workspace, not just configuration.

Local UI

None — APM has no web dashboard, desktop app, or TUI. Interaction is entirely through AI chat sessions using slash commands.

IDE integration

None built-in. The slash commands (/apm-1-initiate-planner, etc.) work within any IDE that supports the target AI tool's command format (Claude Code, Cursor, etc.).

Observability

  • Tracker — .apm/tracker.md shows task completion status and Worker assignments at a glance
  • Memory Index — .apm/memory/index.md shows Stage summaries and memory notes
  • Task Logs — Workers write detailed execution logs documenting what was done and validation results
  • Archive — apm archive preserves completed sessions for retrospective review

No structured metrics, dashboards, or log streams.

Documentation site

Full documentation at agentic-project-management.dev covering installation, getting started, agent types, orchestration mechanics, and workflow overview.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k
A8 Cross-runtime harness

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k
A8 Cross-runtime harness

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k
A8 Cross-runtime harness

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k
A8 Cross-runtime harness

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k
A8 Cross-runtime harness

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k
A8 Cross-runtime harness

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.