# Agentic Project Management (APM)

**A spec-driven multi-agent framework for AI-assisted software engineering.**

APM is an open-source framework for managing ambitious software projects with AI assistants - Claude Code, Cursor, GitHub Copilot, Antigravity, OpenCode, and Codex. Instead of working in a single, increasingly long conversation, APM structures your work into a coordinated system where different agents handle planning, coordination, and execution, and their messages pass through you.

## The Problem

A coding agent is an LLM working in a loop with tools. LLMs keep no state between calls: the agent resends the whole conversation for each step of a task. On long tasks, LLMs suffer from two problems:

- **Context decay** - The longer the conversation and the more context accumulates, the less reliably the LLM recalls earlier decisions and instructions, and the less consistently it reasons about them.
- **Context pressure** - Every call costs more than the last and brings the conversation closer to the context window's limit, where the platform must cut or summarise it, losing earlier detail.

## How APM Works

APM counters each problem, and keeps you in charge throughout.

- **Planning documents, against decay** - APM is **spec-driven**. Before any code is written, a Planner works with you to record the project's intent, requirements, and constraints in three planning documents: the Spec (what to build), the Plan (how the work is divided), and the Rules (how the work is carried out). Agents work from these documents instead of relying only on what their long conversation holds.
- **Separate agents, against pressure** - APM is a *multi-agent system* where a Manager hands out the work and Workers carry it out, each in its own conversation with only the context its work needs. Splitting the work this way keeps each conversation's context small and focused on its own job.
- **Coordination through you** - The Planner, the Manager, and the Workers communicate only through you, by design. When one writes a message for another, it informs you, and you deliver it by running a command. Each exchange is a chance to review the work behind it and ask for changes before it moves on. How the work is divided and assigned sets how often exchanges pass through you. We call this *productive friction*. These pauses are deliberate: they aim to keep your understanding of the software you are building, and to let you catch mistakes before they spread through the codebase.

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. When context fills, a Handoff transfers that working knowledge to a fresh instance rather than discarding it. Any APM agent may delegate heavy work to its own subagents.

[Diagram: The APM workflow: in the Planning Phase you and the Planner write the Spec, the Plan, and the Rules; in the Implementation Phase the Manager hands out assignments and Workers report back through you, with the session's state in shared files.]

Throughout implementation, the Manager checks the work against the planning documents and Workers follow the Rules, under your supervision. Shared files outside any conversation hold the session's state and history. When a session ends, you can archive it, and later Planners can build on the archive.

## Installation

APM is installed via the [`agentic-pm`](https://www.npmjs.com/package/agentic-pm) CLI, which scaffolds the commands, guides, and skills that APM agents use into your project workspace. To get started, see [Getting Started](Getting_Started.md).

If you want your AI assistant to explain APM concepts or help with migration from an older version, the [`apm-assist`](https://github.com/sdi2200262/agentic-project-management/tree/main/skills/apm-assist) skill can be installed into any project and answers questions by reading the live documentation.

## Contributing

APM is open source and welcomes contributions. Report bugs or request features via [GitHub Issues](https://github.com/sdi2200262/agentic-project-management/issues), or submit improvements via Pull Requests.

For contribution guidelines, see [CONTRIBUTING.md](https://github.com/sdi2200262/agentic-project-management/blob/main/CONTRIBUTING.md).

## Reading Order

**Start using APM** - [Getting Started](Getting_Started.md) walks you through installation and your first session end to end. There is also a [Quick Reference](Quick_Reference.md) with every command and workflow in one place, to keep at hand.

**Understand the architecture** - Three docs build on each other: [Agent Roles](Agent_Roles.md) covers the three roles, [Agent Orchestration](Agent_Orchestration.md) covers how they coordinate, and [Workflow Overview](Workflow_Overview.md) walks through every procedure.

**Go deeper** - [Prompt Engineering](Prompt_Engineering.md) explains how APM's files are designed. [Context Engineering](Context_Engineering.md) explains why each agent sees what it sees.

**Look things up** - [CLI Guide](CLI_Guide.md) for commands and options, [Troubleshooting](Troubleshooting_Guide.md) for common issues, [Customisation](Customisation_Guide.md) for custom repositories, [Security](Security_Guide.md) for the trust model, and [Tips and Tricks](Tips_and_Tricks.md) for model selection and workflow efficiency.

---

# Getting Started

This guide takes you through installation, planning and your first cycle of assignments and reports.

## Prerequisites

You need Node.js 18 or later, a project directory, and an assistant that supports `AGENTS.md` and `.agents/skills/`, or Claude Code.

## Installation

Install the CLI:

```bash
npm install -g agentic-pm
```

In your project directory, run:

```bash
apm init
```

Choose `agents` for agents using `AGENTS.md` and `.agents/skills/`, such as Codex, Cursor and GitHub Copilot, or `claude` for Claude Code. To install both:

```bash
apm init -a agents claude
```

The CLI installs skills and procedure guides for your target, plus session files under `.apm/`. See the [CLI Guide](CLI_Guide.md#installation) for local installation and file paths.

APM's commands are skills. Examples here use Claude Code's `/` syntax; in Codex, use `$`, such as `$apm-1-initiate-planner`. Other assistants use their skill picker or chat syntax. Each APM agent works in its own conversation; keep active chats available so you can switch between them.

## Step 1: Initiate the Planner

The **Planner** defines the work with you. Open a new chat in your project and run:

```markdown
/apm-1-initiate-planner
```

You can include your project request and reference documents:

```markdown
/apm-1-initiate-planner We're building Horse Tinder, a dating app for horses: owners swipe through profiles and match horses from nearby stables. Next.js frontend, Firebase backend. Here's the PRD: @docs/prd.md
```

The Planner uses this context to focus its questions.

## Step 2: Work Through the Planning Phase

### Context Gathering

The Planner surveys the workspace and explores relevant code while questioning you in three rounds:

1. Existing materials, vision and scope.
2. Technical requirements, constraints and validation.
3. Implementation approach, quality and coordination preferences, including Git use and conventions.

It develops design choices and a tentative division of work with you, resolves gaps, and agrees what this APM session covers. Review its **Understanding Summary** and correct anything missing before approving it.

### Work Breakdown

The Planner writes three documents, in order:

- **Spec** - What to build: design decisions, constraints and workspace references.
- **Plan** - How work is divided: bounded assignments called **Tasks**, grouped into ordered milestones called **Stages**. Each Task names its implementation agent (**Worker**), deliverables, dependencies and validation criteria.
- **Rules** - Shared Worker execution conventions, written inside `APM_RULES` in workspace-root `AGENTS.md`. For Claude Code, the Planner imports this file from an existing workspace `CLAUDE.md`, preserving your instructions.

Review and approve each document before the next begins. These documents guide implementation, so settle unclear requirements and checks here. After Rules approval, the Planner applies agreed repository setup and creates the Message Bus, the files agents use to exchange assignments and reports.

## Step 3: Initiate the Manager

The **Manager** coordinates implementation. Open a new chat and run:

```markdown
/apm-2-initiate-manager
```

It reads the planning documents, explores the codebases and presents its understanding for approval. Once approved, it starts assigning Tasks and maintains the **Tracker**, the live record of progress and next actions.

## Step 4: Your First Task Cycle

**1. Receive an assignment.** The Manager writes a **Task Prompt**, with the instructions and context a Worker needs, to the Message Bus. It tells you which Worker to start and what to run. Before delivering any message, you can review the work or ask for changes.

**2. Start the Worker.** A **Worker** carries out assignments in one area of the project. Open a new chat and use the identifier the Manager gives you:

```markdown
/apm-3-initiate-worker frontend-agent
```

The Worker reads its waiting prompt, executes the Task and validates the result. It pauses for checks or decisions that need you. You can also steer it during execution.

**3. Collect the result.** The Worker writes a **Task Log** to **Memory**, the session's work history, and a short **Task Report** to the Message Bus. It tells you when the report is ready.

**4. Deliver the report.** In the Manager's chat, run:

```markdown
/apm-5-check-reports frontend-agent
```

Without an identifier, this collects every pending report. The Manager checks the logs and deliverables, accepts the result, sends a follow-up or updates the planning documents. Unfinished work and validation limits remain recorded; a Task stays Active while review or follow-up is pending.

## Step 5: Continuing the Project

For later assignments, return to the same Worker's chat and run:

```markdown
/apm-4-check-tasks
```

Repeat the cycle as Tasks become ready. The Manager may send a batch to one Worker or independent work to several Workers in parallel. See [Dispatch Modes](Agent_Orchestration.md#dispatch-modes) for how those choices affect your review points.

Stages complete in order. [Workflow Overview](Workflow_Overview.md) covers follow-ups, planning changes, validation and Stage completion.

## Context Limits

When a Manager or Worker's context approaches its limit, use a **Handoff** to continue that role in a fresh conversation:

1. Run `/apm-6-handoff-manager` or `/apm-7-handoff-worker` in the outgoing chat.
2. Review and approve its Handoff Log and Handoff Prompt.
3. Open a new chat for the same role and run its initiation skill, with the identifier for a Worker.
4. Check its account of the current state and next action before continuing.

If context was lost through compaction or a closed chat, use `apm-9-recover` to rebuild it. See [Troubleshooting](Troubleshooting_Guide.md#context-recovery) for recovery commands and Handoff problems.

## After Completion

When the planned work is complete, or you stop early, pause active agents and record unfinished work. You can keep the session in place or archive it for later sessions.

For an optional summary first, invoke `/apm-8-summarize-session` in a new chat or ask the Manager at session end. To archive and start again:

```bash
apm archive --name horse-tinder-v1
apm init
```

Archiving preserves session records and remaining worktrees before clearing active APM files and installed instructions. The worktrees stay attached to their source repositories. The next Planner can use relevant archives as context. See [CLI archival](CLI_Guide.md#apm-archive) for details.

## Next Steps

Keep the [Quick Reference](Quick_Reference.md) at hand during a session. To understand the roles and their context boundaries, continue with [Agent Roles](Agent_Roles.md).

---

# Quick Reference

Commands, paths and workflow steps to keep at hand. For your first session, follow [Getting Started](Getting_Started.md).

## Commands

Invoke these skills by name in your agent conversations. Examples use Claude Code's `/` syntax; in Codex, use `$`. Other assistants use their own skill picker or chat syntax:

| Command | What it does |
| :--- | :--- |
| `/apm-1-initiate-planner` | Start the Planner (you can pass project context as an argument) |
| `/apm-2-initiate-manager` | Start the Manager |
| `/apm-3-initiate-worker <id>` | Start a Worker with the given identifier (e.g. `frontend-agent`) |
| `/apm-4-check-tasks` | Deliver a Task Prompt to the current Worker |
| `/apm-5-check-reports` | Deliver a Task Report to the Manager (add one or more Worker ids to target specific Workers) |
| `/apm-6-handoff-manager` | Initiate Manager Handoff before context fills |
| `/apm-7-handoff-worker` | Initiate Worker Handoff before context fills |
| `/apm-8-summarize-session` | Summarise a session and offer to archive it |
| `/apm-9-recover [role]` | Reconstruct context after compaction or a lost conversation (e.g. `manager` or `frontend-agent`) |

## CLI

You run these in your terminal from the project workspace:

| Command | What it does |
| :--- | :--- |
| `apm init` | Initialise APM with official templates |
| `apm custom -r owner/repo` | Initialise from a custom repository |
| `apm update` | Archive the current session, then update templates to the latest compatible version |
| `apm archive` | Archive the current session to `.apm/archives/` and remove installed assistant files |
| `apm archive --name my-feature` | Archive with a custom name |
| `apm add -a claude` | Add an installation target |
| `apm remove -a claude` | Remove an installation target |
| `apm status` | Show current installation state |

For every option, see the [CLI Guide](CLI_Guide.md).

## Project Structure

This is what `.apm/` looks like during a session:

```text
.apm/
├── spec.md              # What to build (design decisions, constraints, workspace)
├── plan.md              # How work is organised (Stages, Tasks, dependencies)
├── tracker.md           # Live session state (the Manager's dashboard)
├── metadata.json        # Installation metadata (source, version, assistants)
├── session.summary.md   # Optional, from /apm-8-summarize-session
├── memory/
│   ├── index.md         # Lasting findings and links to Stage summaries
│   ├── stage-01/        # Task Logs for Stage 1
│   │   ├── task-01-01.log.md
│   │   ├── task-01-01.followup-01.log.md
│   │   ├── task-01-02.log.md
│   │   └── stage-01.summary.md
│   └── handoffs/        # Handoff Logs per agent
│       ├── manager/
│       └── frontend-agent/
├── bus/                  # Message Bus (file-based agent communication)
│   ├── manager/
│   │   └── handoff.md
│   └── frontend-agent/
│       ├── task.md       # Task Prompt (Manager to Worker)
│       ├── report.md     # Task Report (Worker to Manager)
│       └── handoff.md    # Handoff Prompt
├── worktrees/            # Git worktrees for parallel dispatch
└── archives/             # Archived sessions from previous runs
    └── index.md          # One row per archived session
```

The Rules live in the `APM_RULES` block of workspace-root `AGENTS.md`. For Claude Code, the Planner imports it from an existing workspace `CLAUDE.md`.

## Planning Phase

1. **Start the Planner** - Open a new agent conversation, run `/apm-1-initiate-planner`
2. **Answer questions** - Three rounds: existing materials and vision, technical requirements, and implementation approach, quality and coordination, including Git agreements
3. **Approve the Understanding Summary** - Verify the Planner understands the project
4. **Review planning documents** - Approve the Spec, then the Plan, then the Rules
5. **Done** - The Planner initialises the Message Bus. Open a new conversation for the Manager.

## Implementation Phase

1. **Start the Manager** - Run `/apm-2-initiate-manager`, review and approve its Understanding Summary
2. **Manager dispatches** - It writes a Task Prompt and tells you which Worker to go to
3. **Start or switch to the Worker** - Run `/apm-3-initiate-worker <id>` for new Workers, or `/apm-4-check-tasks` for existing ones
4. **Worker executes** - It follows the Task Prompt, validates results, and logs the outcome
5. **Deliver the report** - Run `/apm-5-check-reports` in the Manager's conversation
6. **Manager reviews** - Proceeds, issues a follow-up, or modifies planning documents
7. **Repeat** - Steps 2-6 cycle until all Stages complete

## Handoff

When an agent's context fills or quality degrades:

1. Run `/apm-6-handoff-manager` or `/apm-7-handoff-worker` in the outgoing conversation
2. Review and approve its Handoff Log and Handoff Prompt
3. Open a new conversation for the same role and run its initiation skill (for a Worker, with its identifier)
4. Check the incoming agent's account of the current state and next action before continuing

For context lost without a Handoff, see [Recovery](Troubleshooting_Guide.md#context-recovery).

## After Completion

At completion or early stopping, pause active agents and record unfinished work. An optional `/apm-8-summarize-session` can run in a new chat or in the Manager's chat. To archive and start another session:

```bash
apm archive                        # move .apm/ artifacts to archives, clean workspace
apm init                           # reinstall and start a new session (the Planner detects past archives)
```

---

# Agent Roles

APM has three roles: the Planner defines the work, the Manager coordinates it, and Workers carry it out. Each works in its own conversation with the context its responsibilities need.

## Comparison

| Role | Context Scope | Conversations | Active Phase |
| :--- | :--- | :--- | :--- |
| **Planner** | Project requirements and workspace research | One | Planning Phase |
| **Manager** | Planning documents, live state and work history | Successive via Handoff | Implementation Phase |
| **Worker** | Its assignments, Rules and working context | One per area, successive via Handoff | Implementation Phase |

A **Handoff** moves a role to a fresh conversation when context runs low. The role continues from shared files; [Agent Orchestration](Agent_Orchestration.md#handoff-and-continuity) explains how.

## Planner

The Planner explores the workspace and questions you about the work, then writes the Spec (what to build), Plan (how work is divided) and Rules (shared Worker execution conventions). Its role ends after planning.

[Diagram: The overview diagram with the Planner, you, and the planning documents highlighted.]

- **[Context Gathering](Workflow_Overview.md#context-gathering)** - Researches requirements, develops design and the division of work with you, and presents its understanding for approval.
- **[Work Breakdown](Workflow_Overview.md#work-breakdown)** - Writes the three planning documents for separate approval, then prepares communication for the Manager and Workers.

## Manager

The Manager assigns Tasks, reviews results and maintains the planning documents, live progress and work history. During review, it can investigate, finish small amounts of remaining work and run final validation. Substantial implementation stays with Workers unless you approve the Manager doing it.

[Diagram: The overview diagram with the Manager and its Tracker highlighted.]

- **[Task Assignment](Workflow_Overview.md#task-assignment)** - Chooses ready work and sends each Worker a self-contained assignment, the **Task Prompt**.
- **[Task Review](Workflow_Overview.md#task-review)** - Checks reported results and decides whether to accept them, request another attempt or update planning documents.
- **State and version control** - Records progress and findings, manages branches and worktrees under the agreed conventions, and merges accepted work.

## Workers

Each Worker handles one area, such as the frontend or API, building familiarity across assignments. It works from its Task Prompts, the Rules and its conversation. The Manager supplies needed planning and dependency context; Workers do not read the Spec, Plan or coordination records unless you widen their scope.

[Diagram: The overview diagram with the Workers and Memory highlighted.]

- **[Task Execution](Workflow_Overview.md#task-execution)** - Implements and validates assigned work, investigates failures, and asks for guidance on problems beyond its Task.
- **[Task Logging](Workflow_Overview.md#task-logging)** - Records evidence in a **Task Log** and sends the Manager a short **Task Report** with the outcome and log path.
- **Rules proposals** - Offers to retain corrections to shared execution practices as Rules. Changes need your approval.

Any role may delegate focused work to native subagents and must verify their findings. These subagents are separate from APM Workers and stay within their parent's scope.

## Next Steps

[Agent Orchestration](Agent_Orchestration.md) explains how these roles communicate, share state and continue across conversations.

---

# Agent Orchestration

The [Planner, Manager and Workers](Agent_Roles.md) coordinate through planning documents, a file-based Message Bus and shared records. You deliver their messages, keeping each exchange open to review.

## Planning Documents

The Planner creates three documents:

- **Spec** (`.apm/spec.md`) - Required behavior, design decisions and constraints. Its Workspace section records repositories, references and agreed Git setup.
- **Plan** (`.apm/plan.md`) - Ordered milestones called **Stages**, each containing bounded assignments called **Tasks**. Tasks name a Worker, dependencies, outputs and validation criteria.
- **Rules** - Shared Worker execution conventions, in the `APM_RULES` block of workspace-root `AGENTS.md`. For Claude Code, the Planner imports it from an existing workspace `CLAUDE.md`, preserving your instructions.

Spec Notes hold design assumptions and context; Plan Notes hold coordination considerations. Settled requirements, dependencies and conventions stay in their owning sections. APM procedures stay in the role guides.

The Manager maintains these documents and copies relevant Spec and Plan content into assignments called **Task Prompts**. Workers read the Rules directly. [Workflow Overview](Workflow_Overview.md#task-review) covers changes during implementation.

## The Message Bus

The Message Bus lives in `.apm/bus/`. Each Worker has a folder named by its identifier, such as `frontend-agent`, with three files:

| Bus | File | Message |
| :--- | :--- | :--- |
| **Task Bus** | `task.md` | A Task Prompt from the Manager: the assignment |
| **Report Bus** | `report.md` | A Task Report from the Worker: the outcome and Task Log path |
| **Handoff Bus** | `handoff.md` | A Handoff Prompt: instructions for a fresh conversation |

The Manager's folder holds only `handoff.md`. Each file holds at most one temporary message. An agent clears a processed message before replying; Handoff Prompts are cleared after loading. A Task Prompt stays populated during execution, so its presence does not prove delivery is still needed.

You deliver each message by invoking a skill in its recipient's conversation. [Getting Started](Getting_Started.md#step-4-your-first-task-cycle) walks through the delivery steps.

[Diagram: The Manager writes to the Worker's Task Bus and the Worker reads it; the Worker writes to its Report Bus and the Manager reads it; you sit between them on both paths.]

Agents outside APM can contribute through their own bus folders. Their reports carry their evidence directly; they do not become Workers or write Task Logs.

## Task Prompts and Dispatch

### How Task Prompts Are Built

A Task Prompt gives a Worker the objective, instructions, working directory, expected output and validation. The Manager selects relevant Spec decisions, dependency outputs, coordination notes and lasting findings for the Plan's Task, including each needed contract once. This keeps each assignment self-contained.

### Dependency Context

A Task depends on another when it needs that Task's output. The Manager scales the supplied context to the Worker's familiarity:

- **Same-Worker dependency** - Its own earlier work: key outputs, paths and how to build on them.
- **Cross-Worker dependency** - Unfamiliar work: what was produced, which files to read and how to integrate it.

After a Handoff, a Worker has not loaded its earlier-Stage Task Logs, so those dependencies need Cross-Worker context. Recovery may also leave gaps that require fuller instructions.

### Dispatch Modes

A dispatch sends ready work to a free Worker:

- **Single** - One Task.
- **Batch** - Two or three Tasks for the same Worker: independent ready Tasks or a dependency chain. The Worker runs them in order and reports once.
- **Parallel** - Independent Tasks or batches for different Workers at the same time. This requires version control and a separate Git worktree for each Worker.

With version control, each dispatch gets a branch and the Manager coordinates merges. It reviews reports and dispatches ready work without waiting for unrelated Workers.

Task size and dispatch mode determine how often exchanges pass through you. Discuss Task size with the Planner and dispatch preferences with the Manager.

## Memory and Session State

Shared files keep the session's state outside any conversation. The **Tracker** holds live coordination state; **Memory** preserves work history and continuation context.

[Diagram: The overview diagram with the planning documents, the Tracker, and Memory highlighted.]

### The Tracker

The Tracker (`.apm/tracker.md`) records Task states and next actions, branches and worktrees, each Worker's conversation number and context, and coordination notes. Task IDs link to their latest reported logs; a pending attempt's destination stays in its Task Prompt. Notes remain while ongoing work needs them or their decisions await a Stage summary or Index entry. The Manager updates the Tracker after review and dispatch. Tasks are Waiting on dependencies, Ready to assign, Active through execution and review, or Done after a final decision.

### The Index

The Index (`.apm/memory/index.md`) holds brief findings and accepted or unresolved limits that later work needs, with source links and a table linking to Stage summaries. Each summary records accepted outcomes, consequential findings and decisions, validation and limits, with links to its Task Logs.

### File-based Memory

Memory lives in `.apm/memory/`:

- **Task Logs** - A Worker's evidence and findings for each attempt. The original is `stage-<NN>/task-<NN>-<MM>.log.md`; follow-ups use `task-<NN>-<MM>.followup-01.log.md`, `followup-02` and onward in that folder. Each follow-up links to the original and previous follow-up, preserving earlier evidence.
- **Stage summaries** - The Manager's record of a Stage, at `stage-<NN>/stage-<NN>.summary.md`.
- **Handoff Logs** - Working context for the next conversation, at `handoffs/<agent-slug>/handoff-<NN>.log.md`.

Stage summaries group each Task's attempt logs and record final review decisions. Index findings link to the attempt or summary that supports them. [Quick Reference](Quick_Reference.md#project-structure) shows the full directory layout.

[Diagram: Task Logs hold execution detail and the Tracker holds coordination detail; Stage summaries condense the results, and the Index links to them and records lasting findings.]

## Handoff and Continuity

A Handoff transfers a Manager or Worker role to a fresh conversation. The outgoing agent checks current files and Git state, prepares its continuation records and asks you to review them. The incoming agent uses the approved records to resume. [Getting Started](Getting_Started.md#context-limits) gives the steps.

### Why Handoff Works

A Handoff saves selected working context in files that later conversations can reread. It produces two records:

- **Handoff Log** - What was done, decided and observed beyond the Task Logs. It stays in Memory.
- **Handoff Prompt** - Checked current state, what to read and where to resume. It travels through the Handoff Bus.

[Context Engineering](Context_Engineering.md#context-across-conversations) explains why APM uses these records rather than relying on conversation compaction.

[Diagram: The outgoing agent writes a Handoff Log to Memory and a Handoff Prompt to the Handoff Bus; you open a new conversation, where the incoming agent reads both with other relevant session state.]

### Manager vs Worker Handoff

The Manager records outstanding assignments, reports and merges. A Worker mid-Task keeps its Task Prompt in the bus and records where to resume; mid-batch, it also records which Tasks are already logged.

### Context Reconstruction

An incoming Manager reads planning documents, the Tracker, the Index, its Handoff Log and the Task Logs needed for current coordination.

An incoming Worker reads the Rules, its Handoff Log and the latest relevant attempt logs for its Tasks in the current Stage, following earlier links where needed. A pending attempt resumes with the log path in its Task Prompt. The Manager supplies richer dependency context for earlier work it has not read.

### Recovery

Recovery rebuilds context after compaction or a lost conversation without changing the role's conversation number. It rereads instructions, bus messages and project files, asking you about gaps the records cannot settle. See [Troubleshooting](Troubleshooting_Guide.md#context-recovery) for commands and recovery problems.

## Next Steps

[Workflow Overview](Workflow_Overview.md) follows these mechanisms through planning, implementation and session closure.

---

# Workflow Overview

An APM session moves from planning to implementation, ending when the planned work is complete or you stop early. This walkthrough builds on [Agent Roles](Agent_Roles.md) and the mechanisms in [Agent Orchestration](Agent_Orchestration.md).

## Planning Phase

The Planner develops the design and division of work with you during Context Gathering, then writes the planning documents during Work Breakdown.

[Diagram: The Planner gathers context and elicits requirements from you, consolidates them and presents its understanding; once you agree, it creates the planning documents, which you review for completeness before planning completes.]

### Context Gathering

The Planner surveys repositories, existing materials, instructions and archives. It uses materials you identify as authoritative and asks which other planning materials are relevant before reading them. It checks findings against the current codebase.

Discovery follows three question rounds:

1. **Existing Materials and Vision** - Purpose, scope, deliverables and prior work.
2. **Technical Requirements** - Design choices, constraints, dependencies, risks and validation.
3. **Implementation Approach and Quality** - Tools, quality, Task size, Workers, parallelism and review points. This includes Git use, base branches, branch and commit conventions, and whether to track APM files. Ignoring `.apm/` is the default proposal when it is inside a repository.

Each round includes questions, research and follow-ups, then a short summary. The Planner resolves gaps needed to define the work or agrees with you how planned research will settle them. Context supplied at initiation makes questions more targeted but does not skip a round.

The Planner develops tentative Stages, Tasks and Workers as it learns. Once the session's scope and important choices are settled, it presents an **Understanding Summary** for your approval. Corrections are resolved before document writing begins.

### Work Breakdown

The Planner writes the [Spec, Plan and Rules](Agent_Orchestration.md#planning-documents) in that order. For each, it explains the proposal, writes the document and waits for your review and approval before starting the next. Corrections are applied to affected earlier documents too. Task boundaries reflect the work's size, complexity, uncertainty, dependencies and expertise. Research, implementation and validation may share a Task or need separate Tasks; each Task has a clear output and validation criteria.

After Rules approval, it performs any agreed repository initialisation and ignore-file changes. It then creates the Message Bus and directs you to start the Manager in a new conversation with `apm-2-initiate-manager`.

## Implementation Phase

The Manager coordinates repeated cycles of assignment, execution, logging and review.

[Diagram: The Manager reviews the planning documents and writes assignments, keeping the Tracker; you notify the Workers, who execute, log to Memory, and report through the Message Bus; you notify the Manager, who reviews logs and reports, until the project is complete.]

### First Manager Initialisation

The Manager reads the planning documents and explores the working codebases. It presents its understanding for your approval, then populates the Tracker and dispatches under the planning agreements.

### Task Cycles

Each Task passes through four procedures:

[Diagram: For each Task, the Manager prepares a Task Prompt and writes it to the Task Bus; the Worker reads it, executes and validates, writes a Task Log to Memory and a Task Report to the Report Bus; the Manager reads the report, reviews the log, and updates the session state.]

#### Task Assignment

The Manager chooses ready work and a [dispatch mode](Agent_Orchestration.md#dispatch-modes), prepares its branch or worktree when using Git, and writes a self-contained Task Prompt to the Worker's bus. It tells you which Worker conversation to use and which skill to invoke.

A Worker takes one dispatch at a time. New Workers receive it through `apm-3-initiate-worker <id>`; existing Workers through `apm-4-check-tasks`.

#### Task Execution

The Worker integrates the dependencies named in its prompt, follows the instructions under the Rules and validates the result. It runs autonomous checks first, then pauses for checks needing your judgement or outside action.

Failed checks lead to investigation and targeted fixes. Missing dependencies, conflicting instructions, repeated attempts without progress or work that substantially exceeds the assignment need guidance.

You can correct the Worker during execution. At completion, it asks whether corrections to shared execution practices should become Rules. Approved additions go in the existing shared Rules file and are recorded in the Task Log.

#### Task Logging

With version control, the Worker commits its changes. It writes a Task Log with deliverables, validation evidence and consequential findings, then a short Task Report. The outcome is:

- **Success** - The objective is achieved and every validation criterion passed.
- **Partial** - Some work or required validation remains, and guidance is needed.
- **Failed** - The objective was not achieved despite attempts to fix it.

Unavailable or unrun checks remain explicit limits. Findings that affect acceptance or later work are flagged as **Important Findings**; Partial and Failed outcomes always have them.

For a batch, the Worker validates and logs each Task before starting the next. It stops at the first Failed outcome and reports which Tasks were not started.

The Worker clears its Task Bus, writes its report and tells you how to deliver it with `apm-5-check-reports` in the Manager's conversation.

#### Task Review

The Manager checks the Task Log and deliverables against the assignment and planning documents. It investigates Important Findings, unmet criteria and inconsistent claims. When its context makes this more efficient than another dispatch, it can finish small amounts of remaining work, including code changes, and run final validation within the existing objective. Substantial implementation stays with Workers unless you approve the Manager doing it. It follows the Rules in the Task's workspace and records its work and validation separately from the Worker's outcome. It then decides:

- **Accept** - Mark completed work Done, including work the Manager finished and validated during review, merge accepted work before dependent Tasks, and dispatch newly ready work. You may agree to accept a Partial outcome; its remaining work and validation limits stay recorded.
- **Follow-up** - Send concrete remaining work, reviewed findings and a completion check to the same Worker, using its established context. The Task keeps its ID; each attempt has a new numbered log linked to the original and previous follow-up. Unresolved criteria remain part of the Task's outcome.
- **Planning change** - Update the affected requirements and Task fields before preparing further work. Contained changes can proceed; changes affecting several Tasks, design, scope or Stages need your approval.

The Manager compares follow-ups with previous attempts. If another attempt has no supported approach or the remaining work substantially exceeds the assignment, it presents options to you before dispatching again.

While a decision or follow-up is pending, the Task stays Active. Done is final: a later fix needs a new Task. Corrections to unreported active work preserve its current dispatch and valid progress; the Manager asks you to pause the Worker, revises the prompt and redelivers it through `apm-4-check-tasks`.

The Manager records its decision and next actions in the Tracker, then dispatches ready work without waiting for unrelated reports. Reports from agents outside APM carry their own evidence and skip Worker-log review.

### Stage Progression

Stages run in order, with parallel Tasks within a Stage.

[Diagram: Stage 1 holds Tasks such as data models, a storage layer, an auth handler, API endpoints, and integration tests; later Stages follow in order until the project is complete.]

The Manager verifies the Stage's combined result when you request it, the Plan calls for it, or any Task needed a follow-up or reported Important Findings. Otherwise it records why verification was skipped. It uses relevant checks and preserves their reference inputs and evidence through cleanup.

A Stage completes once all Tasks are Done, required verification is resolved and, with version control, its branches are merged. The Manager writes the Stage summary, links it from the Index and starts the next Stage. Summaries preserve consequential decisions, evidence and accepted limits.

### Project Completion

After all Stages complete, the Manager records completion and reports deliverables, consequential findings and any accepted limitations. It offers a session summary and archive; both are optional.

## Session Continuation

A larger goal can span several APM sessions. Before summarising or archiving, pause active agents and record unfinished work and Git state.

1. **Summarise** - Invoke `apm-8-summarize-session` in a new conversation, or ask the Manager at completion or early stopping. It checks records against deliverables and writes `.apm/session.summary.md` with outcomes, decisions, validation and remaining limits.
2. **Archive** - Run [`apm archive`](CLI_Guide.md#apm-archive), optionally with `--name <name>`. It preserves records and remaining worktrees before clearing active files and installed instructions. Archiving does not finish, commit or merge work.
3. **Continue** - Run `apm init`, then invoke `apm-1-initiate-planner` in a new conversation. The Planner checks relevant archives against the current workspace.

## Next Steps

- [Prompt Engineering](Prompt_Engineering.md) - How APM's instructions and file formats are designed
- [Context Engineering](Context_Engineering.md) - Why APM scopes and transfers context this way

---

# Prompt Engineering

APM runs on files that agents read and follow. This doc explains their structure and writing conventions, for readers who want to understand or [customise](Customisation_Guide.md) them.

## File Types

| Type | Purpose | How it enters context |
| :--- | :--- | :--- |
| **Command skills** | Initiate roles, deliver messages, hand off, recover or summarise | Invoked by you, using your assistant's skill syntax |
| **Shared skill** | Communication and Message Bus rules | Read by every role at initiation |
| **Guides** | A procedure for one role | Read by that role at initiation |
| **Initial documents** | Starting structure for the Spec, Plan, Tracker and Index | Filled in and maintained during the session |

The numbered command skills set `disable-model-invocation: true` and point to the files their action needs. Each skill has a name and description in YAML frontmatter; guides have none. The communication skill includes a supporting guide for agents outside APM to join the Message Bus.

Guides separate procedures from initiation. The Planner reads both Context Gathering and Work Breakdown at the start, so it can develop the division of work during questioning. The Manager reads Task Assignment and Task Review; Workers read Task Execution and Task Logging.

## Writing Patterns

Instructions address the agent following them and remain readable to the person inspecting or changing them. They name concrete actions, files and conditions in the order the agent needs them. Shared rules have one authoritative home, with references from other files. This keeps copies from drifting apart and leaves more context for the work.

## Structured Formats

Task Prompts, reports and logs pair YAML frontmatter with a Markdown body. YAML holds identifiers, paths and states that determine the next action; Markdown carries instructions, results and evidence that need reading and judgement.

For example, a Task Log with a non-Success `status` or `important_findings: true` tells the Manager to investigate. The Manager checks these fields against the log and deliverables before accepting the work. A flag does not establish that a claim is correct.

## Platform-Agnostic Design

The build produces two targets from the same sources: `agents` installs skills and guides under `.agents/`, and `claude` under `.claude/`. Both use `.apm/` for session files and workspace-root `AGENTS.md` for Rules.

Placeholders resolve paths, the template version and Claude-specific text. Instructions name skills without a command prefix because invocation syntax varies by assistant; procedures and document formats stay the same. See [The Build](Customisation_Guide.md#the-build) for source locations and configuration.

## Terminology

APM capitalises terms with a defined workflow meaning, such as Worker, Task, Stage and Handoff, and uses ordinary English elsewhere. Consistent names let agents identify the same roles, work units and records across files.

## Related Docs

- [Context Engineering](Context_Engineering.md) - Why each role loads particular information
- [Customisation Guide](Customisation_Guide.md) - Changing, building and distributing templates

---

# Context Engineering

Context engineering keeps a model's limited attention on relevant information. APM uses role boundaries, shared records and Handoffs to address the [context decay and pressure](Introduction.md#the-problem) that build up in long conversations.

[Agent Orchestration](Agent_Orchestration.md) explains the mechanisms. This doc explains why they are designed that way.

## Context Scoping

### Planner

The Planner's conversation is devoted to understanding and planning the work. Separating planning from implementation keeps execution history from competing with requirements while they are still being settled.

The Spec, Plan and Rules preserve the approved decisions from that exploration. These documents carry the result into implementation; the Manager and Workers do not need to reconstruct the planning conversation.

### Manager

The Manager works from planning documents, live coordination state and recorded outcomes. It reads source code when preparing an assignment or investigating a result, leaving routine implementation to Workers. This lets it coordinate across areas without carrying every Worker's debugging and execution history.

### Workers

A Worker receives the Rules and a self-contained Task Prompt. The Manager includes the design decisions, dependency context and constraints the Task needs. Keeping the Spec, Plan, Tracker and Index outside the Worker's usual scope leaves more room for code, implementation and validation.

Workers retain familiarity across assignments in their area. The Manager can refer briefly to a Worker's own earlier outputs, while unfamiliar dependencies need reading and integration instructions. A Handoff trades some of that familiarity for a fresh conversation, so later Task Prompts give fuller context for earlier work it has not read.

Any role may delegate focused work to native subagents within its scope, then verify their findings. This keeps isolated research or debugging out of the main conversation without changing the role's responsibilities.

## Context Across Conversations

Agents share files, not conversations. Reading another Worker's code may show what it does without explaining the decisions or constraints behind it. The Manager supplies that missing context through Task Prompts, using the earlier work's logs and evidence.

Shared records also keep the session independent of any one conversation:

- **Task Logs** preserve results, validation and consequential findings for each attempt. Follow-up logs link to earlier attempts, so continuation can follow the evidence it needs without loading the whole history.
- **The Tracker** holds current coordination state and next actions.
- **Stage summaries** condense accepted work, decisions and validation limits, with links to Task Logs.
- **The Index** links to those summaries and holds findings useful beyond a Stage.

An incoming Manager can start with the Index and summaries, then follow sources where more detail is needed. This reduces how much history it must load while keeping the evidence available.

A Handoff applies the same principle to a role's working context. The outgoing agent writes a durable record of what the next conversation needs and checks current state before transferring the role. Platform compaction instead replaces conversation history with a summary that later compactions may condense again. The Handoff files remain available for verification and continuation.

[Archives](Workflow_Overview.md#session-continuation) carry this history between APM sessions. A new Planner reads relevant records and checks their claims against the current codebase, since archived decisions and results may no longer describe it.

## Related Docs

- [Agent Orchestration](Agent_Orchestration.md) - Communication, Memory and continuity mechanisms
- [Prompt Engineering](Prompt_Engineering.md) - How instructions and records are structured

---

# CLI Guide

The `agentic-pm` CLI installs APM templates, updates them and manages session archives. This guide covers its commands, options and installation files.

## Installation

Requires Node.js v18 or higher.

**Global install (recommended):**

```bash
npm install -g agentic-pm
```

**Local install:**

```bash
npm install agentic-pm
```

Then run `apm init` in your project directory (with a local install, `npx apm init`).

## Commands

### apm init

Installs APM from the official releases, in a project without APM. If APM is already installed, it shows the current state and suggests `apm add`, `apm update`, or `apm archive`.

```bash
apm init
apm init -a claude
apm init -a agents claude -t v1.1.0
```

| Flag | Description |
| :--- | :--- |
| `-t, --tag <tag>` | Install a specific release version |
| `-a, --assistant <id...>` | Pre-select installation target(s) |

Without `--tag`, it selects the newest stable official release matching the CLI's major version, then checks the release's minimum CLI requirement. Choose an installation target, the file layout your assistant uses, or pass its ID with `-a`. The CLI installs:

- The `.apm/` directory with planning and tracking templates, the Memory Index and installation metadata.
- Command skills, the communication skill and procedure guides in the selected target's directories.

| Target | For | Skills | Guides |
| :--- | :--- | :--- | :--- |
| `agents` | Agents supporting `AGENTS.md` and `.agents/skills/` | `.agents/skills/` | `.agents/apm-guides/` |
| `claude` | Claude Code | `.claude/skills/` | `.claude/apm-guides/` |

Both targets share `.apm/`. Install both with `-a agents claude`, or add one later with `apm add`. Planning writes shared Rules to workspace-root `AGENTS.md`.

### apm custom

Installs APM from a custom repository, and manages saved custom repositories.

```bash
apm custom
apm custom -r owner/repo
apm custom -r owner/repo -t v1.0.0 -a claude
```

| Flag | Description |
| :--- | :--- |
| `-r, --repo <repo>` | Repository in `owner/repo` format |
| `-t, --tag <tag>` | Install specific release version (requires `--repo`) |
| `-a, --assistant <id...>` | Pre-select installation target(s) |
| `--add-repo <repos...>` | Save custom repositories for later use |
| `--remove-repo <repos...>` | Remove saved repositories |
| `--list` | List saved custom repositories |
| `--clear` | Clear all saved custom repositories |
| `-f, --force` | Skip confirmation when removing or clearing repositories |

Without `--repo`, choose a saved repository or enter another. Custom installation asks for a [security acknowledgement](Security_Guide.md#the-security-disclaimer) unless you saved the repository with that prompt disabled. `--force` applies only to `--remove-repo` and `--clear`.

### apm update

Updates the installed templates from the same source repository. Run it between sessions: the current session moves to the archive, and `.apm/` returns to blank templates.

```bash
apm update
apm update -f
apm update -n pre-update-backup
```

| Flag | Description |
| :--- | :--- |
| `-f, --force` | Skip confirmation prompt |
| `-n, --name <name>` | Custom archive name for the pre-update snapshot |

Stop active agents before updating. The CLI:

1. [Archives the session](#apm-archive), including remaining worktrees and uncommitted contents.
2. Removes installed template files.
3. Installs the new release, consolidating targets it replaces and dropping unsupported targets.
4. Writes fresh installation metadata.

Stable official installations update to the newest stable release. Pre-release installations offer available newer stable or pre-release versions. Custom installations offer newer releases from the same repository. To install a specific version, including a pre-release, use `apm init --tag <tag>` in a project without an active installation.

### apm archive

Archives the current APM session or manages existing archives.

```bash
apm archive
apm archive -n my-feature-v1
apm archive -l
apm archive --delete session-2026-03-04-001
apm archive --clear
```

| Flag | Description |
| :--- | :--- |
| `-f, --force` | Skip confirmation prompt |
| `-n, --name <name>` | Custom archive directory name |
| `-l, --list` | List archived sessions with metadata |
| `--delete <name>` | Delete a specific archive |
| `--clear` | Delete all archives |

Stop active agents before archiving. The CLI:

1. Copies session records into `.apm/archives/session-YYYY-MM-DD-NNN/` and moves remaining worktrees there through Git, including uncommitted contents.
2. Writes archive metadata and verifies preservation.
3. Clears active session files, installed templates and installation metadata.

Existing archives and the Rules in `AGENTS.md` remain. Worktrees stay attached to their source repositories, so the archive is local session context rather than a standalone Git backup. Archiving does not finish Tasks, commit changes or merge branches. If it fails, inspect the paths the error identifies before continuing.

Run `apm init` for fresh templates. The next Planner asks which archives are relevant.

Deleting an archive also removes its worktrees and their uncommitted, untracked and ignored files. The confirmation describes what will be deleted; `-f` skips it. If deletion fails, the CLI stops and warns that cleanup may be partial. Branches remain.

### apm add

Adds installation targets to an existing installation without affecting the current session.

```bash
apm add
apm add -a agents
apm add -a claude
```

| Flag | Description |
| :--- | :--- |
| `-a, --assistant <id...>` | Targets to add |

It fetches the installed release and offers only the targets not yet installed. For custom installations, it shows the security disclaimer unless the repository skips it.

### apm remove

Removes installation targets from the installation.

```bash
apm remove
apm remove -a agents
apm remove -a agents claude -f
```

| Flag | Description |
| :--- | :--- |
| `-a, --assistant <id...>` | Targets to remove |
| `-f, --force` | Skip confirmation prompt |

It removes those targets' files and updates the metadata, warning you before removing the last one. Files also used by targets that remain installed are kept. The `.apm/` artifacts stay.

### apm status

Shows the current installation state.

```bash
apm status
```

It shows the source repository, template and CLI versions, install date, installed targets with file counts, and archive count. It flags missing installed files and gives restoration commands; it does not check file contents. Without an installation, it shows any archives or suggests `apm init`.

## Directory Structure

The `agents` target installs this layout:

```text
project/
├── .apm/
│   ├── spec.md                # Design decisions and constraints
│   ├── plan.md                # Stages, Tasks and dependencies
│   ├── tracker.md             # Live session state
│   ├── memory/
│   │   └── index.md           # Lasting findings and summary links
│   └── metadata.json          # Installation metadata
├── .agents/
│   ├── skills/                # Command and communication skills
│   └── apm-guides/            # Procedure guides
└── AGENTS.md                  # Rules, written during planning
```

The `claude` target uses `.claude/skills/` and `.claude/apm-guides/`. During the session, agents create the Message Bus, Task Logs and summaries under `.apm/`; parallel dispatch also creates `.apm/worktrees/`. See [Quick Reference](Quick_Reference.md#project-structure) for the full session layout.

## Versioning

The CLI and templates follow Semantic Versioning separately and share a major version.

| Track | Distribution | Update method |
| :--- | :--- | :--- |
| **CLI** (`agentic-pm`) | npm | `npm update -g agentic-pm` |
| **Template releases** | GitHub Releases | `apm update` |

CLI v1.x fetches only v1.x.x releases from the official repository. Custom repositories have no version filter. A release's optional `minCliVersion` applies to both sources. The CLI refuses installation when it is older than that minimum. Older CLIs may not enforce it correctly; update the CLI before installing newer templates. Templates v1.1.0 require CLI v1.0.3 or later.

The [changelog](https://github.com/sdi2200262/agentic-project-management/blob/main/CHANGELOG.md) labels changes by track. See [Troubleshooting](Troubleshooting_Guide.md#upgrading-to-templates-v110) for the v1.1.0 upgrade steps.

## Terminal Input

Interactive choices need a terminal. For scripts, supply the target with `-a` and a release with `--tag` where required. `-f` skips destructive-action confirmations; it does not choose a release or accept a custom repository's security disclaimer.

## Global Configuration

The CLI keeps global settings in `~/.apm/config.json`: your saved custom repositories and their settings, such as whether to skip the disclaimer. `apm custom` and its flags manage the file.

## Workspace Metadata

Each installation has `.apm/metadata.json`, which `apm update`, `apm add`, `apm remove`, and `apm archive` read to know the current state.

| Field | Type | Description |
| :--- | :--- | :--- |
| `source` | string | `"official"` or `"custom"` |
| `repository` | string | Repository in `owner/repo` format |
| `releaseVersion` | string | Release tag (e.g. `"v1.0.0"`) |
| `cliVersion` | string | CLI version that performed the installation |
| `assistants` | string[] | Installed target IDs (e.g. `["agents", "claude"]`) |
| `assistantNames` | object | Display names by target ID; absent in older installations |
| `installedFiles` | object | Map of target ID to installed file paths; `_apm` records shared session templates |
| `installedAt` | string | ISO 8601 timestamp of installation |

### Archive Metadata

Each archive in `.apm/archives/` contains its own `metadata.json` with the same fields as the workspace metadata plus:

| Field | Type | Description |
| :--- | :--- | :--- |
| `archivedAt` | string | ISO 8601 timestamp of archival |
| `reason` | string | Why the archive was created (e.g. `"archive"`, `"update"`, `"migration"`) |

`archivedWorktrees` records moved worktree paths, source repositories, branches and whether unfinished files were present. `apm archive --list` reads the metadata and shows the worktree count.

## Related Docs

- [Troubleshooting Guide](Troubleshooting_Guide.md) - Restore an installation or recover a session
- [Customisation Guide](Customisation_Guide.md) - Build and publish custom templates
- [Security Guide](Security_Guide.md) - Bundle trust and security acknowledgements

---

# Troubleshooting Guide

Resolve interruptions and installation problems. For the normal session workflow, see [Getting Started](Getting_Started.md).

## Planning Changes and Interruptions

Give corrections to the Planner during planning, or to the Manager during implementation. The agent updates affected documents and asks for approval when a change affects the scope, design or several Tasks.

If planning is interrupted, continue in the same conversation. If that conversation is lost, invoke `apm-1-initiate-planner` in a new one. Tell it which documents were approved and what remains. It needs to reconstruct missing context before continuing.

## Blocked Tasks

When a Worker cannot resolve a problem within its Task, ask it to log the current result, failed or unavailable checks, and what guidance it needs. Deliver its report to the Manager with `apm-5-check-reports`.

The Manager can investigate, finish small amounts of remaining work and run final checks during review. It can ask you to settle a requirement or approach; substantial implementation goes to a Worker unless you approve the Manager doing it. Required validation that remains unmet stays visible in the result. See [Task Review](Workflow_Overview.md#task-review).

## Context Recovery

A [Handoff](Agent_Orchestration.md#handoff-and-continuity) is the planned way to move an agent to a fresh conversation. [Recovery](Agent_Orchestration.md#recovery) is for when context was lost without one: the platform compacted the conversation, or you closed or cleared it.

### Recovery

Recovery covers the Manager and Workers; for a Planner, see [Planning Changes and Interruptions](#planning-changes-and-interruptions). Run the recovery command in the agent's conversation, or in a new one if the old one is gone:

```markdown
/apm-9-recover manager          # recover the Manager
/apm-9-recover frontend-agent   # recover a Worker by its identifier
```

The agent rebuilds its context from the project's files and asks you for brief context where gaps remain. The Manager notes the recovery in the Tracker, and a Worker mentions it in its next Task Report. If the agent still seems confused or inconsistent afterwards, perform a Handoff to start a clean instance.

### Faulty Handoff

A Handoff written by an agent whose context had already degraded, after a compaction or past its context limit, may record inaccuracies. If compaction left gaps, run recovery and check the current files before preparing a Handoff.

If the incoming agent's account of the current state and next action shows errors anyway:

- **Minor gaps:** correct them in the incoming agent's conversation.
- **Major errors:** fix the Handoff artifacts, then open a new conversation for the same role and run its initiation command. The incoming agent reads the corrected artifacts.
  - The **Handoff Log**, in `.apm/memory/handoffs/`, holds the working context, decisions, and notes.
  - The **Handoff Prompt**, in `.apm/bus/<agent-slug>/handoff.md`, holds the current state and outstanding Tasks. The incoming agent clears it once read. Rewrite it from the corrected Handoff Log and current files, since the next agent detects a Handoff only when the file has content.

## Installation Issues

Keep the CLI up to date before installing newer templates. See [release compatibility](CLI_Guide.md#versioning) for version requirements.

### Missing Installed Files

`apm status` names targets with missing installed files. Run `apm remove -a <id>`, then `apm add -a <id>` to restore that target from the installed release. Session artifacts remain in `.apm/`.

### Upgrading to Templates v1.1.0

Update the CLI first, then update templates between APM sessions:

```bash
npm update -g agentic-pm
apm update
```

CLI v1.0.3 consolidates older official target IDs into `agents` and keeps `claude` when installed. The update archives the current session, removes recorded template files and installs fresh templates. Both targets can coexist.

If you installed a standalone APM skill in a directory that the CLI did not create, move it to your assistant's current skills directory yourself. Check `.apm/metadata.json` for the files managed by the CLI.

## Older Installations

For an installation the current CLI cannot manage, preserve its planning documents, logs and metadata before removing anything. Compare its files with the relevant [release notes](https://github.com/sdi2200262/agentic-project-management/blob/main/CHANGELOG.md) and keep your own assistant configuration.

The optional [apm-assist skill](https://github.com/sdi2200262/agentic-project-management/tree/main/skills/apm-assist) can inspect the installation, propose a migration and carry it out after your approval. Follow the [skills README](https://github.com/sdi2200262/agentic-project-management/blob/main/skills/README.md) to install it in your assistant's skills directory.

## Related Docs

- [CLI Guide](CLI_Guide.md) - Commands, installation targets and metadata
- [Agent Orchestration](Agent_Orchestration.md#handoff-and-continuity) - Handoff and recovery mechanics

---

# Tips and Tricks

Practical choices for models, coordination overhead and review points during an APM session.

## Model Selection

Use capable reasoning models for the Planner and Manager: their decisions shape many Tasks. Match each Worker to its Task's difficulty and required tools; a cheaper model may suit bounded, familiar work. Higher reasoning effort can be useful for complex planning or coordination when your model supports it.

### Switching Models

Check that a replacement model understands the current state and instructions. Switching between Tasks gives you a clear point to review this. To move a Manager or Worker to a fresh conversation, use a [Handoff](Agent_Orchestration.md#handoff-and-continuity). Keep the Planner's gathered context available until its documents are approved.

## Cost Efficiency

Reviewing requirements and validation before implementation can prevent follow-ups and rework. Task size and dispatch also affect how much coordination passes through you.

### Context Up Front

Give the Planner existing requirements, relevant code paths and known constraints when starting it. [Getting Started](Getting_Started.md#step-1-initiate-the-planner) shows how to include context with the initiation skill.

### Batch-Friendly Planning

Ask for smaller Tasks when you want frequent review points, or for batches when you prefer fewer deliveries covering more work. Discuss this during planning so Task boundaries support your preference. The Manager chooses actual [dispatches](Agent_Orchestration.md#dispatch-modes) as dependencies become ready.

### Handoff Timing

Use your assistant's context display or reminders to plan a Handoff before the limit. Review its continuation files while the current work is still clear. If compaction has already lost context, use [recovery](Troubleshooting_Guide.md#context-recovery) first.

### Subagents

Focused research, debugging or verification may suit a native subagent when it can work independently. The parent agent keeps its role's scope and checks the findings before using them.

## Workflow Efficiency

### Validation Criteria

Give concrete pass/fail checks and identify anything that needs your judgement, access or outside action. This helps Workers validate independently and makes remaining limits clear during review. For example:

```text
Each API endpoint must return the documented status codes and response shape. Run the existing test suite and add tests for the new endpoints, including timeout handling.
```

If a milestone needs verification across Tasks, tell the Planner so it appears in the Plan, or ask the Manager before the Stage closes.

### Steering

- Correct a Worker in its conversation; it records consequential corrections for the Manager and asks before adding them to Rules.
- Give the Manager your observations when delivering a report, such as a missed edge case or changed requirement.
- Ask the Manager to record pending decisions and blockers in the Tracker, or to change Task structure and dispatch where needed.

[Workflow Overview](Workflow_Overview.md#task-cycles) explains how these changes affect active work, follow-ups and approvals.

### Splitting Sessions

Split a large goal when later work depends on decisions the current session must settle. Natural boundaries include a feature, a software layer or a change in direction. Agree the current scope with the Planner; a later session can use its archive. See [Session Continuation](Workflow_Overview.md#session-continuation) for closing and restarting.

## Related Docs

- [Getting Started](Getting_Started.md) - Running a first session
- [Troubleshooting Guide](Troubleshooting_Guide.md) - Recovering context and resolving blocked work

---

# Customisation Guide

To customise APM, change its source templates in your own repository, build release bundles and install them with `apm custom`. Each bundle contains the files for one installation target, such as `agents` or `claude`.

## Custom Repositories

The [APM repository](https://github.com/sdi2200262/agentic-project-management) supports both a GitHub fork and "Use this template":

| | Fork | Template |
| :--- | :--- | :--- |
| **History** | Carries the upstream history | Starts with a clean history |
| **Upstream sync** | `git merge upstream/main` pulls in new APM releases | No upstream link; later changes need manual diffing |
| **Best for** | Customisation that keeps up with APM releases | Deep divergence, using APM as a starting point |

The workflow:

1. Fork or template the repository.
2. Change the templates, add skills, adjust procedures.
3. Run `npm ci` in the repository, then build with `VERSION=1.1.0 npm run build:release`, using your intended template version.
4. Inspect the ZIPs and `apm-release.json` in `dist/`: check installed paths, resolved placeholders and references. Try changed instructions in a separate project.
5. Create a version tag and GitHub Release, and attach the ZIPs and manifest. Adapt the repository's release workflow before using it.
6. Install with `apm custom -r owner/repo`.

The [customisation skill](https://github.com/sdi2200262/agentic-project-management/tree/main/skills/apm-customization) can guide your assistant through these changes and checks.

## The Build

Two files configure the build:

- **`build/build-config.json`** lists target IDs, display names, bundle names, skill and guide directories, and the minimum CLI version. Official targets are `agents` and `claude`. A target can declare older IDs it `replaces` so updates consolidate them.
- **`build/processors/placeholders.js`** resolves `{VERSION}`, `{SKILL_PATH:name}`, `{SKILL_DIR:name}`, `{GUIDE_PATH:name}` and `{CLAUDE_ONLY:text}`. Rules use workspace-root `AGENTS.md` for both targets.

Set `VERSION` when building locally. The Release Templates workflow sets it from the version input, or increments the latest stable patch when the input is empty.

`apm-release.json` identifies the targets and their ZIP bundles for the CLI. It must be attached to the release alongside the ZIPs.

## What You Can Change

| What | Where | Effect |
| :--- | :--- | :--- |
| **Procedures** | `templates/guides/` | How each procedure runs, from Context Gathering to Task Review |
| **Commands** | `templates/skills/apm-<N>-<action>/SKILL.md` | Each agent's role, what it reads, and how it initialises |
| **Communication** | `templates/skills/apm-communication/` | The Message Bus protocol and how agents address you |
| **Artifact templates** | `templates/apm/` | The starting structure of the Spec, the Plan, the Tracker, and the Index |
| **New skills** | `templates/skills/<name>/SKILL.md` | Protocols your agents can load |
| **Delegation** | Role initiation skills | Optional native subagent guidance within each role's scope |

For example, a team that wants authentication changes checked for security can add that requirement to `templates/guides/task-review.md`. State which Tasks need the review and what evidence the Manager should check. If the assistant supports native subagents, the Manager can delegate the review and verify its findings.

Follow the authoring standards in `templates/_standards/`; they are not shipped in bundles. For workflow changes, update `WORKFLOW.md` there first, then the affected skills, guides, formats and examples.

## Installing and Sharing

`apm update` uses the installed repository. Custom releases have no major-version filter, but manifest and minimum-CLI checks still apply. Private repositories need `GITHUB_TOKEN` or a signed-in `gh` CLI. See the [CLI Guide](CLI_Guide.md#apm-custom) for release selection and saved repositories.

When you share a repository, describe in its README what you changed, why, and how its behaviour differs from the official release.

:::warning[Security]
Custom bundles can overwrite project files and change agent instructions. Review them before installing; see the [Security Guide](Security_Guide.md) for the trust model and CLI safeguards.
:::

## Official Adaptations

Two adaptations offer different ways to divide the work. See their repositories for supported targets and full instructions.

### APM Auto

[APM Auto](https://github.com/sdi2200262/apm-auto) lets the Manager launch Worker subagents in Claude Code, review their output and continue without message delivery between separate Worker chats.

```bash
apm custom -r sdi2200262/apm-auto
```

### APM Semi

[APM Semi](https://github.com/sdi2200262/apm-semi) lets you claim Tasks and carry them out yourself. The Manager or paused Worker assists you, validates the result and writes the Task Log.

```bash
apm custom -r sdi2200262/apm-semi
```

## Related Docs

- [Prompt Engineering](Prompt_Engineering.md) - File types, formats and instruction design
- [CLI Guide](CLI_Guide.md) - Installation, updates and release requirements

---

# Security Guide

APM installs templates that guide your agents' work. Review their source and instructions before using them.

## Trust Model

APM installs from two sources:

- **Official** (`apm init`) - Templates from the [APM repository](https://github.com/sdi2200262/agentic-project-management), reviewed by its maintainers.
- **Custom** (`apm custom`) - Templates from any GitHub repository, which APM's maintainers have not reviewed.

Both use the same extraction process. See [CLI versioning](CLI_Guide.md#versioning) for release compatibility.

## Bundle Contents and Limits

A bundle is a ZIP archive extracted into your project. It can overwrite project files and install instructions that tell an agent to run harmful commands or expose data. Official bundles use `.agents/`, `.claude/` and `.apm/` by convention; custom bundles can use other project paths.

The CLI checks extracted paths and blocks entries that resolve outside the project. It does not scan content or verify release signatures. Installation extracts files without running bundle scripts, but agents may act on those instructions later. Updates and archives also move session files and remove installed files recorded in metadata.

## The Security Disclaimer

Installing, adding or updating from a custom repository requires your acknowledgement that its templates are unreviewed. Saving the repository with `skipDisclaimer` enabled suppresses that prompt on later use. This setting does not verify the repository or warn if it is later compromised.

To manage saved repositories:

```bash
apm custom --list              # Review saved repos and disclaimer status
apm custom --remove-repo owner/repo   # Remove a saved repo (re-enables disclaimer)
apm custom --clear             # Remove all saved repos
```

## Mitigation Strategies

1. **Review the source and instructions.** Check the repository's README and history, and inspect its skills and guides before agents use them.
2. **Choose and confirm a release.** Pin a known release with `--tag` and check the repository and version in `.apm/metadata.json`.
3. **Review saved repositories.** Check `apm custom --list`. Remove a saved source to restore its acknowledgement prompt.

## Reporting Security Issues

Report vulnerabilities through [GitHub Issues](https://github.com/sdi2200262/agentic-project-management/issues) or contact the maintainers directly. Share sensitive details privately until the issue is addressed.

## Related Docs

- [CLI Guide](CLI_Guide.md#apm-custom) - Manage saved repositories and their settings
- [Customisation Guide](Customisation_Guide.md) - Build and share custom templates