---
name: projects
description: "Structured project execution. Phased sprints, operational investigations, deliverable reviews, and retrospectives — backed by graph tasks with dependency tracking and health signals."
requires:
  - tasks
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 that create Task nodes, check dependencies, track progress, and produce a structured record of what happened.

## 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.

## Project Data Model

A project is a Task node with child tasks linked via `PART_OF`. The parent Task is the project; child Tasks are individual work items.

When creating a project:
1. Create a parent Task with the project name and `[PROJECT:START]` in the first note
2. Create child Tasks for each work item, linked to the parent via `task-relate` with `PART_OF`
3. Add `BLOCKS` relationships between child tasks that have sequential dependencies
4. Add `AFFECTS` relationships to entities the project will modify

The `[PROJECT:START]` note marks this Task as a project (not a regular task). Include the tier and scope summary: `[PROJECT:START] Kitchen Refit — Full tier, 7 tasks planned`.

## Session-Start Awareness

At session start, after surfacing open tasks (per the tasks plugin behaviour), also check for active projects:

1. Call `task-list` with status `active`
2. Identify project tasks — those with `[PROJECT:START]` in their notes
3. For each active project, report:
   - Project name and current phase (from the latest `[PROJECT:PHASE]` note)
   - Health signal (see below)
   - What's next — the next actionable step or blocker

If no active projects exist, proceed normally.

## Health Signal

Compute a RAG (Red/Amber/Green) health status for each active project using `task-list` filtered to the project's child tasks:

| Signal | Condition |
|--------|-----------|
| Green | All child tasks on track: none overdue, no unresolved blockers, completion rate consistent with timeline |
| Amber | Warning signs: at least one overdue task OR an unresolved blocker exists OR completion rate is behind schedule |
| Red | Project at risk: multiple overdue tasks OR critical-path blocker unresolved OR no progress in recent sessions |

When due dates are not set on child tasks, degrade gracefully: report completion count ("3 of 5 tasks done") without RAG colouring.

Surface the health signal at session start and when the user asks about project status.

## Structured Lifecycle Notes

Append structured notes to the parent Task at key lifecycle moments. These notes 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}` |
| Project complete | `[PROJECT:COMPLETE] {name} — {n}/{total} tasks done, {n} deferred` |
| Project abandoned | `[PROJECT:ABANDONED] {name} — Reason: {why}` |

## Dependencies

This plugin requires the `tasks` plugin to be enabled. If task tools are unavailable (tasks plugin not enabled), tell the user: "I need the tasks plugin to run structured projects. Would you like to enable it?" Do not attempt structured execution without task tools — fall back to a regular conversational approach until the dependency is resolved.
