# Plan Tracker

> Read-only status view for plan suites in the current project. Detects the active suite (one with chunks not yet done) and shows status, dependencies, and what's runnable next. Use when the user invokes /plan-tracker or asks "what's the state of the plan" / "what's next in the plan" / "what's left".

- **Type:** Skill
- **Install:** `agentstack add skill-vpaivag-skills-plan-tracker`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [vpaivag](https://agentstack.voostack.com/s/vpaivag)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [vpaivag](https://github.com/vpaivag)
- **Source:** https://github.com/vpaivag/skills/tree/main/skills/plan-tracker

## Install

```sh
agentstack add skill-vpaivag-skills-plan-tracker
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /plan-tracker

Show the current state of plan suites in this project. **Read-only** — this skill never modifies any plan file.

Every plan produced by `/deep-plan` is a suite (a directory containing `index.md` and one or more chunk files), including single-chunk plans. This tracker operates on every such suite uniformly.

## Operating mode

This skill is **strictly read-only**. Do not use `Edit`, `Write`, `MultiEdit`, or any `Bash` command that modifies files or repository state. Use `Read`, `Glob`, `Grep`, and read-only `Bash` (`ls`, `find`, `cat`) only.

## Asking questions

This skill prefers the `AskUserQuestion` tool for interactive prompts. If `AskUserQuestion` is not available (older Claude Code versions, restricted environments), fall back to plain text: print the question, list the options as a numbered list with the recommended option marked `(Recommended)`, and wait for the user's reply (a number or the option label). The skill proceeds normally in either mode — every call site below that says "call `AskUserQuestion`" follows this fallback rule.

## Plans directory

Resolve the plans directory before scanning: read `.claude/plans-config.json` if present and use its `plansDir`; otherwise default to `.claude/plans`. If the config file is missing or malformed, silently fall back to the default. Everywhere this skill says "the plans directory" or `` below, it means the resolved value.

## Phases

### Phase 1 — Discover suites

Look for plan suites in the plans directory (``). A suite is a subdirectory containing an `index.md` file.

Run roughly: `find  -name index.md -type f`

For each suite found, parse its index to determine:
- Suite name (from the `# Suite: ` heading)
- Goal (from the `## Goal` section)
- Chunk list with name, status, dependencies (from the `## Chunks` section)

If a bare `.md` file exists directly under the plans directory (not inside a suite directory), it's a legacy single-plan from before the suite-everywhere refactor. Note it under "Legacy plans (untracked)" but do not parse it. Suggest the user re-run `/deep-plan` if they want to track it.

If no suites exist, print:
```
No plan suites found in /.

Use /deep-plan to create a new plan.
```
End your turn.

### Phase 2 — Identify active suite

A suite is **active** if at least one of its chunks has status `pending`, `in-progress`, or `blocked`.

A suite is **complete** if all chunks are `done`.

Identify active suites and complete suites separately.

#### If exactly one active suite

Default to it. Skip to Phase 3.

#### If multiple active suites

Call `AskUserQuestion`:
- **Question**: "Which suite would you like to track?"
- **Options** (single-select, up to 4): list each active suite by name. If more than 4, list the 3 most recently modified plus a 4th option "List all suites".

If user picks "List all suites", print all active suites with their last-modified time, then ask in plain text: "Which suite? (paste the name or path)".

Once a suite is selected, proceed to Phase 3.

#### If zero active suites but one or more complete suites

Print:
```
No active suites. Completed suites:
  -  (all  chunks done)
  - ...
```

Ask via `AskUserQuestion`: "View a completed suite, or stop?" with options "View completed suite", "Stop". If view, list completed suites and let user pick.

### Phase 3 — Display suite status

Print a clear, scannable status view:

```
📋 Suite: 
   Goal: 
   Path: 

Chunks:
  ✅            done
  🟡            in-progress     (started: )
  ⏸️            blocked         (depends on: )
  ⏳            pending         (depends on: )
  ⏳            pending         (no dependencies — runnable now)

Progress: / chunks done

Runnable now (no blockers):
  - : claude "/execute-plan "
  - : claude "/execute-plan "

Blocked (waiting on dependencies):
  - : depends on  (status: )
```

Status icons:
- ✅ done
- 🟡 in-progress
- ⏸️ blocked
- ⏳ pending

A chunk is **runnable** if its status is `pending` and all its dependencies have status `done`.

A chunk is shown as **blocked** in the runnable section if its status is `pending` but a dependency is not `done`. (This is distinct from a chunk explicitly marked `blocked` — that one needs human resolution, not just waiting.)

If the user has multiple runnable chunks, list them all. Do not pick one for them.

### Phase 4 — Optional next step

After displaying status, end your turn. Do not call any further tools, do not modify any files, do not suggest concrete actions beyond the runnable commands already printed.

If the user wants to act, they will run `/execute-plan ` themselves. The tracker's job is to inform, not to drive.

## Constraints

- Strictly read-only. No file modifications under any circumstance.
- Only operates on suites (directories with `index.md`). Single plans are not tracked.
- Always end after Phase 4. Do not chain into `/execute-plan` or any action.
- If the index file is malformed (missing required sections, unparseable status), report the malformation rather than guessing.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vpaivag](https://github.com/vpaivag)
- **Source:** [vpaivag/skills](https://github.com/vpaivag/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-vpaivag-skills-plan-tracker
- Seller: https://agentstack.voostack.com/s/vpaivag
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.