projman

name	projman
description	Project management skill for markdown-based projects with GitHub Project sync. Use when: (1) viewing/managing projects in projects/ folder, (2) syncing project checkboxes to GitHub Projects, (3) picking up next work item from a project, (4) updating project status after completing work, (5) generating project dashboards. Replaces the older /pm command with enhanced GitHub integration.

Project Management (projman)

Overview

Manage markdown-based project files in projects/ with optional sync to GitHub Projects. Markdown files are the source of truth; GitHub Projects provides visibility/collaboration.

Project File Structure

Projects live in projects/ as either:

• PROJECT_NAME.md - single file project
• PROJECT_NAME/ - folder with multiple materials

Standard Sections

# Project Title

## Overview
[Project description, goals, selection criteria]

## Items to Process
| Item | Field1 | Field2 | Status |
|------|--------|--------|--------|
| Item A | value | value | [ ] |
| Item B | value | value | [x] |

---
# STATUS
## Tier/Category 1 (N/M) ✓
- [x] Completed item - Date, notes
- [ ] Pending item

## Tier/Category 2 (N/M)
- [ ] Item

# NOTES
## YYYY-MM-DD
[Session notes - add new entries at top]

Core Workflows

1. View Project Status

# List all projects
ls projects/

# Quick status - count checkboxes
grep -c "^\- \[x\]" projects/CANCER.md    # completed
grep -c "^\- \[ \]" projects/CANCER.md    # pending

2. Pick Up Next Item

Read project file → find first unchecked item in priority order → work on it.

# Parse checkboxes from markdown
import re
with open("projects/CANCER.md") as f:
    content = f.read()
# Find unchecked items: - [ ] Item name
pending = re.findall(r'- \[ \] (.+)', content)
next_item = pending[0] if pending else None

3. Update Status After Work

After completing an item:

1. Change - [ ] to - [x]
2. Add date/compliance info: - [x] Item Name - Created 2026-01-30, 55% compliance
3. Add session notes under # NOTES with today's date

4. Add Session Notes

Always add notes incrementally:

# NOTES

## 2026-01-30
[Today's work - add at TOP]
- Completed X, Y, Z
- Key findings: ...

## 2026-01-29
[Previous session - don't edit unless continuing]

Get today's date: date +%Y-%m-%d

GitHub Project Sync

Setup (One-Time)

# Check auth has project scope
gh auth status  # should show 'project' in scopes

# If missing:
gh auth refresh -s project

# Create a new GitHub Project for a markdown project
gh project create --owner @me --title "dismech: CANCER Curation"
# Note the project number returned (e.g., 4)

Sync Checkboxes → GitHub Project Items

Parse markdown checkboxes and create/update GitHub Project items:

# List existing items in project
gh project item-list PROJECT_NUMBER --owner @me --format json

# Create a draft item (not linked to issue)
gh project item-create PROJECT_NUMBER --owner @me \
  --title "Chronic Myeloid Leukemia" \
  --body "Tier 1: BCR-ABL1 paradigmatic cancer"

# Update item status (need field ID and option ID)
# First, get field info:
gh project field-list PROJECT_NUMBER --owner @me --format json

# Then update:
gh project item-edit --id ITEM_ID \
  --field-id STATUS_FIELD_ID \
  --single-select-option-id DONE_OPTION_ID \
  --project-id PROJECT_ID

Useful gh project commands

# List your projects
gh project list --owner @me

# View project details
gh project view NUMBER --owner @me

# Get items as JSON for parsing
gh project item-list NUMBER --owner @me --format json | jq '.items[]'

# Get field definitions (needed for updates)
gh project field-list NUMBER --owner @me --format json

# Delete an item
gh project item-delete NUMBER --owner @me --id ITEM_ID

# Archive an item (keeps it but hides from view)
gh project item-archive NUMBER --owner @me --id ITEM_ID

Field IDs Quick Reference

Status field typically has these option IDs (varies per project):

• Todo: find in gh project field-list output
• In Progress: find in output
• Done: find in output

Example parsing:

gh project field-list 4 --owner @me --format json | \
  jq '.fields[] | select(.name=="Status") | .options'

Integration with dismech Workflow

When working on dismech projects:

1. Pick item from project → consult initiate-new-disorder-creation skill
2. After creating disorder file → run just compliance kb/disorders/NewFile.yaml
3. Update project checkbox → add compliance score
4. Sync to GitHub Project → if project has linked GH Project

Example Session

1. Read projects/CANCER.md
2. Find next pending: "- [ ] Chronic Myeloid Leukemia"
3. Use initiate-new-disorder-creation skill
4. Run validation: just qc
5. Update markdown:
   "- [x] Chronic Myeloid Leukemia - Created 2026-01-30, 60% compliance"
6. Add session notes
7. (Optional) Sync to GitHub Project

Deprecation Note

This skill replaces the older /pm command. Key differences:

• GitHub Project sync capability (new)
• More structured checkbox parsing (improved)
• Clearer session notes format (improved)

The /pm command remains available but should be considered deprecated.