Agentic Project Management (APM)

The apm-assist skill is a support utility designed to help users understand Agentic Project Management (APM). It is not part of the active APM workflow (Planner, Manager, or Worker sessions). Instead, it is used for:

• Explaining APM concepts: Architecture, workflows, and agent roles.
• Detecting installation state: Identifying the current version and configuration of an APM project.
• Answering questions: Providing up-to-date information by fetching live documentation.
• Guiding migration: Helping users move from older versions (e.g., v0.5.x) to the current release.

If you want to start an actual APM session, follow the Getting Started guide rather than using this skill.

APM uses a decoupled versioning system with two independent tracks that share the same major version to ensure compatibility:

1. APM CLI (agentic-pm): Distributed via NPM. It manages templates using commands like apm init, apm custom, and apm update.
2. APM Template Releases: Distributed via GitHub Releases as ZIP bundles. These are decoupled from the CLI versioning; while the CLI and templates share a major version, their minor and patch versions may differ.

Compatibility Rule: CLI v1.x will only fetch v1.x.x template releases from the official repository.

Stage Summaries

Write descriptive prose for future Manager instances and retrospectives. Cover outcomes, agents involved, notable findings, patterns, and key decisions (pointing to commits). Do not include implementation details (which belong in Task Logs) or duplicate Memory notes.

Note Categories

• Working Notes (Tracker): Capture coordination context (pending considerations, User preferences, technical observations) during the Stage. These are distilled into the Stage Summary and Memory Notes at the end of the Stage.
• Memory Notes (Index): Capture observations with lasting impact on future Stages (architectural insights, permanent User preferences). These are forward-looking and do not contain Stage-specific implementation details.

Agent roles (Manager, Workers) are numbered sequentially (e.g., Manager 1, Frontend Agent 1).

• Instance Increment: Instance numbers increment only via a Handoff.
• Recovery: If an agent undergoes Recovery (context reconstruction after platform auto-compaction), it continues as the same instance number. The agent must note the recovery in its next communication (Task Report for Workers, Tracker for the Manager) and in its Handoff Log.
• Worker States: Workers are either uninitialized (defined in the Plan but no instance started) or assigned to a specific Instance N.

The Manager operates under specific constraints to ensure effective orchestration:

• Coordination-level role: Focus on assigning tasks and reviewing results using Task Logs and summaries. Only dive into implementation/source code if explicitly requested or if investigation requires it.
• Initialization tracking: Use the Worker tracking section in the Tracker to manage which Workers have been initialized.
• Handoff tracking: Use Worker tracking and cross-agent overrides in the Tracker to manage Worker Handoffs.
• Context scope: Only read the specific APM documents listed in the Initiation section (Tracker, Index, Plan, Spec, Rules, and specific Guides/Skills). Do not read other agents' guides or internal procedural documents unless explicitly cross-referenced.

When running apm init, the system creates a .apm/ directory containing several scaffold files. The Planner is responsible for populating these files with content during the Work Breakdown phase. These files are used by the {GUIDE_PATH:work-breakdown} guide.

Scaffold Files:

• Spec: Detailed project specification.
• Plan: The execution plan for the project.
• Tracker: Used for tracking progress.
• Memory Index: Used for maintaining project context and knowledge.

Project history and state are captured in a hierarchical file structure within .apm/memory/ to support progress tracking and Handoff continuity.

Core Memory Components

• Tracker (.apm/tracker.md): The live project state document. It tracks Tasks, Workers, version control state, and working notes. The Manager updates this to drive dispatch decisions and dependency analysis.
• Index (.apm/memory/index.md): Durable memory containing Memory notes (persistent observations/patterns) and Stage summaries.
• Task Log (.apm/memory/stage-<NN>/task-<NN>-<MM>.log.md): Structured logs created by Workers after task completion, capturing outcomes, validation, and deliverables.
• Handoff Log (.apm/memory/handoffs/<agent>/handoff-<NN>.log.md): Logs created during a Handoff containing context not captured in other files.

Upon completing the Work Breakdown procedure, the Planner must initialize the Message Bus to enable communication between the Manager and Workers. This involves creating a specific directory structure and empty markdown files for each agent defined in the Plan.

Agent Directory Structure

For every Worker identified in the Plan, derive an agent slug (lowercase, hyphenated name) following the {SKILL_PATH:apm-communication} standards. Create the following structure:

• .apm/bus/<agent-slug>/task.md (Task Bus)
• .apm/bus/<agent-slug>/report.md (Report Bus)
• .apm/bus/<agent-slug>/handoff.md (Handoff Bus)

Manager Directory Structure

The Manager requires its own directory and a handoff bus:

• .apm/bus/manager/handoff.md

Agents should be initialized using a single terminal command combining mkdir -p and touch for efficiency.

APM uses specific standards for managing Git state during task execution:

• Branching: Create a descriptive feature branch off the repository's base branch. Record the branch name in the Task row's Branch column in the Tracker.
• Worktrees (Parallel Dispatch): For parallel tasks, use git worktree add .apm/worktrees/<branch-slug> -b <branch-name>. The workspace section of the prompt should include the worktree path.
• Tracker Configuration: The Tracker must include a Version Control table for each repository, defining the Base Branch, Branch Convention, and Commit Convention.
• Worktree Constraints: Worktrees are located under .apm/worktrees/. They contain a full checkout of tracked files but do not include untracked files.

The project uses different types of summaries to capture state and facilitate user approval:

• Session summary (.apm/session-summary.md): An optional artifact produced by a standalone agent. It captures project scope, stage outcomes, deliverables, known issues, and codebase state. It can be produced at any point in the session.
• Understanding summary: A consolidated presentation for User review and approval that acts as an approval gate:
  • Planner: Presents one at the end of Context Gathering (covers requirements, design, work structure, and technical context).
  • Manager: Presents one during first initiation (covers project scope, design decisions, and version control conventions).

APM uses two distinct outputs to communicate task outcomes to the Manager:

1. Task Log: A detailed, structured markdown file stored in .apm/memory/stage-<NN>/task-<NN>-<MM>.log.md. It captures the full context, including validation, deliverables, and specific findings. This is the source of truth for what happened during a task.
2. Task Report: A concise summary written to the Report Bus at .apm/bus/<agent-slug>/report.md. This is what the Manager reads to quickly assess progress and decide on the next steps. It points to the Task Log for deeper detail.

Workers should follow a sequential procedure: complete the task, write the Task Log, and then deliver the Task Report via the bus.