playbooks

home / skills / codingheader / myskills / 0xdarkmatter-project-planner

0xdarkmatter-project-planner skill

/Skillstore/project-planner/0xdarkmatter-project-planner

This skill analyzes project plans to detect staleness and guides you with session commands to keep docs/PLAN.md current.

npx playbooks add skill codingheader/myskills --skill 0xdarkmatter-project-planner

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.9 KB
---
name: project-planner
description: "Detects stale project plans and suggests session commands. Triggers on: sync plan, update plan, check status, plan is stale, track progress, project planning."
allowed-tools: "Read Glob TodoWrite"
---

# Project Planner Skill

Lightweight awareness layer for `docs/PLAN.md`. Detects when plans need attention and points to `/save` and `/sync` commands.

## Purpose

This skill does NOT manage plans directly. It:
- Detects when `docs/PLAN.md` exists or is missing
- Identifies stale plans (no recent updates vs git activity)
- Suggests appropriate session commands

All plan operations go through `/save` (persist) and `/sync` (restore/status).

## Detection Logic

### Plan Missing
```
No docs/PLAN.md found
-> Suggest: /save to create initial plan from conversation
```

### Plan Stale
```
docs/PLAN.md last modified: 5 days ago
git log shows: 12 commits since then
-> Suggest: /sync --git to update from commits
```

### Uncommitted Work
```
git status shows: 5 modified files
docs/PLAN.md "In Progress" section outdated
-> Suggest: /sync --status to review
```

### Session Start
```
Resuming work on project with docs/PLAN.md
-> Suggest: /sync to restore state
```

## Quick Reference

| Situation | Suggestion |
|-----------|------------|
| No plan exists | `/save` after discussing goals |
| Plan is stale | `/sync --git` |
| Need to see plan | `/sync --status` |
| Update progress | `/save "notes"` |
| Start fresh | `/save --archive` |

## Staleness Heuristics

A plan is considered **stale** when:
- Last modified > 3 days ago AND
- Git shows commits since last modification AND
- Commits relate to plan topics (feat:, fix:, refactor:)

A plan **needs review** when:
- Session just started
- Significant uncommitted changes exist
- User mentions progress or completion

## Notes

- This skill only suggests, never modifies
- `/sync` reads state, `/save` writes state
- Single source of truth: `docs/PLAN.md`

Overview

This skill detects stale or missing project plans and recommends in-session commands to restore or persist plan state. It watches docs/PLAN.md and Git activity to decide when to suggest /save or /sync actions. The skill never changes files; it only advises the next steps to keep the plan current.

How this skill works

The skill checks for the presence and modification time of docs/PLAN.md, compares that timestamp to recent Git commits, and inspects working-tree status for uncommitted changes. Based on simple heuristics (e.g., last modified > 3 days plus related commits), it classifies the plan as missing, stale, or needing review and recommends appropriate session commands like /save, /sync --git, or /sync --status.

When to use it

  • When starting or resuming a project session to restore plan state (/sync).
  • When docs/PLAN.md is absent and you need to create an initial plan (/save).
  • When the plan hasn't been edited but Git shows recent commits that may affect it (/sync --git).
  • When there are uncommitted changes or the plan’s progress section looks outdated (/sync --status).
  • When you want to persist conversation notes or progress into the plan (/save "notes").

Best practices

  • Treat docs/PLAN.md as the single source of truth; rely on /save to write and /sync to read.
  • Run /sync at the start of each work session to detect drift and restore state.
  • Use clear commit messages (feat:, fix:, refactor:) so staleness heuristics are more accurate.
  • Run /save after substantive planning conversations or when you update progress.

Example use cases

  • A team member opens the project after days away; the skill detects stale plan and suggests /sync --git to incorporate recent commits.
  • You realize there is no PLAN.md; the skill prompts /save to capture the initial goals from the discussion.
  • During a session you made code changes unrelated to the plan; the skill sees modified files and recommends /sync --status to review plan impact.
  • Before closing a meeting, you summarize decisions and use /save "meeting notes" as the skill suggested to persist them.
  • After major refactors committed to repo, the skill flags the plan as stale and suggests /sync --git to reconcile updates.

FAQ

Will this skill edit my plan automatically?

No. The skill only detects state and suggests commands; all plan writes happen only when you run /save.

How does it decide a plan is stale?

It looks for docs/PLAN.md modified over 3 days ago combined with intervening Git commits, prioritizing commits with relevant types like feat:, fix:, or refactor:.