Agent-Skills.md

Agent Skills: Planning System Skill

Comprehensive feature planning and execution system. Provides workflows for creating plans, decomposing into features, and pull-based execution. Uses Beads as source of truth for state management.

UncategorizedID: NotMyself/planning-system/planning

Repository

NotMyself/planning-system
NotMyselfLicense: MIT
6

Install this agent skill to your local

pnpm dlx add-skill https://github.com/NotMyself/planning-system/tree/HEAD/skills/planning

Skill Files

Browse the full folder contents for planning.

Download Skill

Loading file tree…

skills/planning/SKILL.md

Skill Metadata

Name
planning
Description
"Comprehensive feature planning and execution system. Provides workflows for creating plans, decomposing into features, and pull-based execution. Uses Beads as source of truth for state management."

Planning System Skill

Overview

This skill provides a reliable system for planning and executing features. It uses Beads as the source of truth for plans and task state, with mechanical enforcement of quality gates.

Architecture

Standard Planning (single feature)

plan:new ──► Beads Epic (plan in description)
                │
                ▼
plan:optimize <epic-id> ──► Beads Tasks (prompts in descriptions)
                │              + dev/plans/<name>/ (supporting files)
                ▼
bd ready ──► Pull-based execution (one task at a time)

Master Planning (large initiative)

plan:new --master ──► Beads Epic + Features (high-level decomposition)
                          │
                          ▼
plan:new <feature-id> ──► Detailed plan in feature description
                          │   (optional: research tasks first)
                          ▼
plan:optimize <feature-id> ──► Beads Tasks under feature
                          │       + dev/plans/<name>/ (supporting files)
                          ▼
bd ready ──► Pull-based execution (one task at a time)

Key Components

| Component | Purpose | |-----------|---------| | Commands | Lean workflow coordinators | | Workflows | Detailed phase instructions (loaded on-demand) | | Templates | Standardized file formats | | Verification | TypeScript scripts for mechanical enforcement | | Hooks | Block shortcuts at Stop events |

Beads Integration (Required)

All plans are stored in Beads epics. Each feature becomes a task under that epic with the full prompt in the description.

# Epic created by plan:new (plan content in description)
bd create --type=epic --title="Feature Name" --description="<full plan>" --silent

# Tasks created by plan:optimize (prompts in description)
bd create --type=task --parent=<epic-id> --title="F001: Setup types" --description="<full prompt>" --silent

# Dependencies between features
bd dep add <task-F002> <task-F001>

# Pull-based execution
bd ready                                    # Find available work
bd update <task-id> --status=in_progress    # Claim work
bd close <task-id>                          # Complete work

DevOps Integration (Optional)

Azure DevOps Story status can sync with Beads epic via sync-devops.ts.

Verification System

Hooks in hooks/hooks.json run TypeScript verification scripts:

  • Stop hook: Blocks completion if quality gates fail

Quality gates (all configurable via .planconfig):

  • No uncommitted changes
  • Build command succeeds
  • Test command succeeds
  • Lint command succeeds
  • Format command succeeds
  • Static analysis succeeds
  • Verification agent approves test quality and requirements

Quick Reference

| Task | Command | |------|---------| | Start new plan (standard) | plan:new | | Start master plan | plan:new --master | | Plan a feature | plan:new <feature-id> | | Optimize epic into tasks | plan:optimize <epic-id> | | Optimize feature into tasks | plan:optimize <feature-id> | | Find work | bd ready | | View task | bd show <task-id> | | Claim work | bd update <task-id> --status=in_progress | | Complete work | bd close <task-id> | | Reflect on conversation | /reflect | | Toggle auto-reflect | /reflect on or /reflect off | | Reflect status | /reflect status |

Workflow Files

Load these on-demand during command execution:

  • workflows/1-planning.md - Planning phase details
  • workflows/2-optimization.md - Optimization phase details

Templates

  • templates/plan.md - Plan document structure
  • templates/prompt.md - Feature prompt structure
  • templates/context.md - Context file template
  • templates/constraints.md - Constraints file template

Supporting Files

Created by plan:optimize in dev/plans/<name>/:

  • context.md - Project background and architecture
  • constraints.md - Global rules for all features
  • decisions.md - Architectural decisions log
  • edge-cases.md - Known edge cases and handling
  • testing-strategy.md - Testing approach

Project Configuration

.planconfig (YAML, project root):

build_command: "npm run build"
test_command: "npm test"
lint_command: "eslint ."
format_command: "prettier --check ."
static_analysis_command: "sonar-scanner"

All commands optional. Missing commands skip that verification step.