---
name: projects
description: "Structured project execution. Phased sprints, operational investigations, deliverable reviews, and retrospectives — backed by :Project:Task graph nodes with HAS_TASK relationships, health signals, and lifecycle tracking."
requires:
  - work
metadata: {"platform":{"always":false,"embed":["admin"],"pluginKey":"projects","optional":true,"recommended":true}}
---

# Projects

Structured execution discipline for business work. When the user has a project — a kitchen refit, a client engagement, a product launch, an operational investigation — this plugin provides phased workflows backed by dedicated project tools that handle graph operations atomically.

## When to Apply

When the user describes work that involves multiple steps, dependencies, or deliverables, offer structured execution. Ask: "Would you like to run this as a structured project, or just handle it as a task?" Learn the user's preference over time — if they consistently choose one mode, stop asking and default to it.

Explicit triggers always apply structured execution without asking:
- "let's sprint on..."
- "run a project on..."
- "investigate why..."
- "review the deliverables for..."
- "let's do a retro on..."

## Modes

| Mode | When | Reference |
|------|------|-----------|
| Sprint | Multi-step project execution with deliverables | `references/sprint.md` |
| Investigation | Operational problem that needs root-cause diagnosis | `references/investigation.md` |
| Review | Deliverable ready for quality check against the brief | `references/review.md` |
| Retrospective | Project completed, extract learnings for future work | `references/retrospective.md` |

Load the relevant reference via `plugin-read` when entering a mode. Each reference describes outcomes and constraints for that mode — follow them.

## Method References

Beyond the four modes, the plugin carries method references for recurring needs that attach to a mode rather than defining one. Load the relevant reference via `plugin-read` when the need arises. Each one terminates in a graph write — a Task, a relationship, or a `[PROJECT:*]` note — never a free-text artefact the graph never sees.

| Method | Reference | Attaches to |
|--------|-----------|-------------|
| Identify and engage stakeholders (Power × Interest) | `references/stakeholder-map.md` | Sprint Plan (Standard + Full) |
| Surface and rank risks before execution | `references/risk-premortem.md` | Sprint Challenge Premise (Full) |
| Order ready tasks by impact and effort (RICE / ICE / MoSCoW / Kano) | `references/prioritization.md` | Sprint Plan |
| Turn a meeting transcript into decisions and tasks | `references/meeting-to-tasks.md` | Any mode |

## Creating a Project

Use `project-create` to create a project atomically. One tool call creates the parent `:Project:Task` node, all child work items, dependency relationships (`BLOCKS`), and entity relationships (`RAISED_BY`, `AFFECTS`) in a single transaction.

Choose a tier based on scope:
- **quick** — straightforward work, few steps (e.g., boiler install)
- **standard** — moderate complexity, multiple phases (e.g., kitchen refit)
- **full** — significant scope, many dependencies (e.g., new build project)

Include work items with their dependencies when the scope is known. If the user describes work incrementally, create the project first and add tasks later via `work-create` + `work-relate`.

## Checking Project Status

Use `project-list` to see all active projects with health signals. Use `project-get` for detailed status on a specific project including children, blockers, and lifecycle history.

Health signals are computed server-side from child task data:

| Signal | Meaning |
|--------|---------|
| Green | On track — no overdue tasks, no unresolved blockers |
| Amber | Warning — at least one overdue task or blocker |
| Red | At risk — multiple overdue, critical blocker, or stale |
| Grey | No due dates set — shows completion count only |

## Updating a Project

Use `project-update` to change phase, tier, target date, client reference, status, or append notes. Phase changes automatically record `[PROJECT:PHASE]` lifecycle notes — no need to pass a separate note for transitions.

## Completing a Project

Use `project-complete` to mark a project done. The tool returns any incomplete children so you can confirm with the user: "2 tasks are still pending: X and Y. Mark them as cancelled and complete the project?" The tool always completes — it informs rather than gates.

## Session-Start Awareness

Active project summaries are injected into the session context automatically. At session start, project health data (name, phase, signal, next action) appears in the `<previous-context>` block without any tool calls needed.

When project context is present, surface it conversationally: "You have 2 active projects. The kitchen refit is on track (3 of 5 done). The boiler install is blocked — waiting on parts."

## Structured Lifecycle Notes

The project tools append structured notes to the project node at key lifecycle moments. These create a searchable audit trail consumed by the retrospective to reconstruct project timelines.

| Event | Note format |
|-------|-------------|
| Project start | `[PROJECT:START] {name} — {tier} tier, {n} tasks planned` |
| Phase transition | `[PROJECT:PHASE] {phase name} — {brief summary of outcome}` |
| Scope change | `[PROJECT:CHANGE] {what changed} — Reason: {why}` |
| Issue recorded | `[PROJECT:ISSUE] {description} — Impact: {assessment}` |
| Project complete | `[PROJECT:COMPLETE] {name} — {done}/{total} tasks done, {n} deferred` |
| Project abandoned | `[PROJECT:ABANDONED] {name} — Reason: {why}` |

For scope changes and issues, use `project-update` with a `note` parameter following the format above.

## Dependencies

This plugin requires the `work` plugin to be enabled. Project tools are co-located in the work MCP server — same data domain, same Neo4j connection. If work tools are unavailable (work plugin not enabled), tell the user: "I need the work plugin to run structured projects. Would you like to enable it?" Do not attempt structured execution without work tools — fall back to a regular conversational approach until the dependency is resolved.