project-management

Project Management Skill

Purpose

Comprehensive tools and workflows for managing project documentation using the markdown roadmap pattern:

• Session continuity: Start/end workflows that maintain context across sessions
• Progress tracking: Story points, velocity, burndown, completion metrics
• Script-based updates: Deterministic frontmatter management
• Validation: Schema compliance checking
• Documentation generation: Templates for epics, stories, and ADRs

When to Use

• Starting a session: Need orientation to current work, environment checks
• Ending a session: Validate changes, update status, commit progress
• Updating progress: Mark stories/epics as started, in-progress, or completed
• Creating documentation: Generate new epics, stories, or ADRs
• Querying progress: Get epic status, velocity metrics, burndown data
• Validating documentation: Ensure frontmatter consistency

Project Structure

project-root/
├── docs/
│   └── roadmap/
│       ├── 00-PROJECT-ROADMAP.md
│       ├── 01-ADR/
│       ├── 02-SESSION-MANAGEMENT.md
│       ├── 03-epics/
│       │   ├── epic-1-name/
│       │   │   ├── README.md
│       │   │   ├── story-1.1-name.md
│       │   │   └── ...
│       │   └── ...
│       └── .session-state.yaml

Core Workflows

Session Management

Starting:

bash <skill-path>/scripts/session/session_start.sh
python <skill-path>/scripts/frontmatter/query_progress.py

Ending:

bash <skill-path>/scripts/session/session_end.sh

Working with Stories

Start work:

python <skill-path>/scripts/frontmatter/start_work.py \
  docs/roadmap/03-epics/epic-1/story-1.1.md \
  --assignee claude --breadcrumb "Starting Story 1.1"

Complete work:

python <skill-path>/scripts/frontmatter/complete_work.py \
  docs/roadmap/03-epics/epic-1/story-1.1.md \
  --actual-points 3 --breadcrumb "Completed Story 1.1"

Update status:

python <skill-path>/scripts/frontmatter/update_status.py \
  docs/roadmap/03-epics/epic-1/story-1.2.md blocked

Valid transitions:

• pending -> in_progress or blocked
• in_progress -> completed or blocked
• blocked -> pending or in_progress
• completed -> (final, immutable)

Querying Progress

python <skill-path>/scripts/frontmatter/query_progress.py
python <skill-path>/scripts/frontmatter/query_progress.py --epic epic-1 --show-velocity
python <skill-path>/scripts/frontmatter/query_progress.py --status blocked

Validation

python <skill-path>/scripts/frontmatter/validate_all.py --project-root /path/to/project

Checks: Required fields, timestamp ordering, status transitions, cross-references, calculated fields, story point validity.

Important: Script-Based Updates

Do not edit YAML frontmatter directly. Always use the provided scripts. They ensure timestamps, status transitions, cross-references, and calculated fields stay correct.

Script Paths

<skill-path>/scripts/frontmatter/
  ├── start_work.py
  ├── complete_work.py
  ├── update_status.py
  ├── validate_all.py
  ├── query_progress.py
  └── migrate_existing.py

<skill-path>/scripts/session/
  ├── session_start.sh
  ├── session_end.sh
  └── update_session_state.sh

Best Practices

1. Always start/end sessions for consistency and context
2. Use scripts for frontmatter — avoid direct editing
3. Validate frequently to catch errors early
4. Log breadcrumbs for cross-session context
5. Update as you go — don't let documentation lag