home / skills / 0xdarkmatter / claude-mods / project-planner

project-planner skill

safe

This skill detects stale project plans in docs/PLAN.md and suggests session commands to keep planning on track without modifying any files.

npx playbooks add skill 0xdarkmatter/claude-mods --skill project-planner

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

Files (4)

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 TaskList TaskCreate"
---

# 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 monitors docs/PLAN.md and alerts when project plans need attention. It does not modify files; instead it recommends session commands to persist or restore plan state. It helps keep the plan aligned with recent repo activity and session progress.

How this skill works

The skill checks whether docs/PLAN.md exists, inspects its last-modified time, and compares that timestamp to recent git activity and working tree status. Based on simple heuristics (age, commits since change, commit message topics, uncommitted changes, and session context) it proposes the appropriate /save or /sync commands. It only suggests actions and never performs writes itself.

When to use it

After pulling new commits or resuming a session to confirm the plan is current
When you notice project progress but docs/PLAN.md hasn't been updated
If docs/PLAN.md is missing and you want to create an initial plan from conversation
When git shows commits since the plan was last edited
When there are uncommitted changes that might affect the plan

Best practices

Run the skill at session start to restore or validate plan state with /sync
Use /save to persist conversational decisions and /save "notes" for quick updates
Run /sync --git when commits touching plan topics appear since last edit
Archive old plans with /save --archive before replacing them
Treat docs/PLAN.md as the single source of truth and resolve conflicts manually

Example use cases

No plan file found after project kickoff -> suggest /save to create initial plan
Plan file untouched for several days while repo had commits -> suggest /sync --git
Working tree shows modified files and plan sections lag behind -> suggest /sync --status
Resuming a paused task from a previous session -> suggest /sync to restore state
Finishing a milestone and noting changes -> suggest /save "progress notes"

FAQ

Will this skill change my plan file automatically?

No. The skill only suggests commands; /save and /sync perform saves and restores under user control.

How does it decide a plan is stale?

It flags staleness when docs/PLAN.md is older than the configured threshold (default ~3 days), there are intervening git commits, and commit messages indicate plan-related work (feat:, fix:, refactor:).