# Planning

Create structured plan documents and track work items using YAML frontmatter.

- Repository: https://github.com/nimbalyst/nimbalyst (2013 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-31
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add nimbalyst/nimbalyst --skill planning -g -a claude-code -y`
Codex: `npx skills add nimbalyst/nimbalyst --skill planning -g -a codex -y`
Cursor: `npx skills add nimbalyst/nimbalyst --skill planning -g -a cursor -y`
Gemini CLI: `npx skills add nimbalyst/nimbalyst --skill planning -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add nimbalyst/nimbalyst`

## Description

Create structured plan documents and track work items using YAML frontmatter. Use when the user wants to plan a feature, track progress, log bugs/tasks/ideas, or organize project work.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Planning and Tracking System

Nimbalyst uses structured markdown documents with YAML frontmatter for planning and tracking work.

## Plan Documents

Plans live in `nimbalyst-local/plans/` with YAML frontmatter:

```yaml
---
planStatus:
  planId: plan-[unique-identifier]
  title: [Plan Title]
  status: draft
  planType: feature
  priority: medium
  owner: [owner-name]
  stakeholders: []
  tags: []
  created: "YYYY-MM-DD"
  updated: "YYYY-MM-DDTHH:MM:SS.sssZ"
  progress: 0
---
```

### Status Values

- `draft`: Initial planning phase
- `ready-for-development`: Approved and ready to start
- `in-development`: Currently being worked on
- `in-review`: Implementation complete, pending review
- `completed`: Successfully completed
- `rejected`: Plan has been rejected
- `blocked`: Progress blocked by dependencies

### Plan Types

- `feature`: New feature development
- `bug-fix`: Bug fix or issue resolution
- `refactor`: Code refactoring/improvement
- `system-design`: Architecture/design work
- `research`: Research/investigation task
- `initiative`: Large multi-feature effort
- `improvement`: Enhancement to existing feature

## Tracking Items

Track bugs, tasks, ideas, and other items in `nimbalyst-local/tracker/`:

```markdown
- [Brief description] #[type][id:[idPrefix]_[ulid] status:[default-status] priority:medium created:YYYY-MM-DD]
```

### CRITICAL: Custom Tracker Types

**Before creating any tracker item, always check `.nimbalyst/trackers/*.yaml` in the workspace root for custom tracker type definitions.** Each YAML file defines a tracker type with:
- `type`: The type name used in `#[type][...]` syntax (e.g., `devblog-post`)
- `idPrefix`: The prefix for generated IDs (e.g., `dev` produces `dev_abc123`)
- `fields`: Available fields including status options with custom values
- `sync`: Whether items sync to the team (shared/local/hybrid)

The rest: https://github.com/nimbalyst/nimbalyst/blob/HEAD/packages/extensions/planning/claude-plugin/skills/planning/SKILL.md