Skip to content

Commit 24c1ecc

Browse files
dragon-ai-agentdragon-ai-agent
authored
Merge pull request #221 from monarch-initiative/add-projman-skill-and-project-updates
Add projman skill and standardize project file naming
2 parents 061dd3a + 5f6d317 commit 24c1ecc

File tree

11 files changed

+1411
-5
lines changed

11 files changed

+1411
-5
lines changed

‎.claude/commands/pm.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,10 @@
11
---
2-
description: Manage and drive forward an ongoing project, tracked in projects/ dir
2+
description: "[DEPRECATED - use projman skill] Manage projects in projects/ dir"
33
argument-hint: [PROJECT_NAME]
44
---
55

6+
> **Note**: This command is deprecated. Use the `projman` skill instead, which adds GitHub Project sync capability. The skill will be triggered automatically when you work with projects.
7+
68
You should find either a file or a folder:
79

810
./PROJECT_NAME.md

‎.claude/skills/projman/SKILL.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
---
2+
name: projman
3+
description: >
4+
Project management skill for markdown-based projects with GitHub Project sync.
5+
Use when: (1) viewing/managing projects in projects/ folder, (2) syncing project
6+
checkboxes to GitHub Projects, (3) picking up next work item from a project,
7+
(4) updating project status after completing work, (5) generating project dashboards.
8+
Replaces the older /pm command with enhanced GitHub integration.
9+
---
10+
11+
# Project Management (projman)
12+
13+
## Overview
14+
15+
Manage markdown-based project files in `projects/` with optional sync to GitHub Projects.
16+
Markdown files are the source of truth; GitHub Projects provides visibility/collaboration.
17+
18+
## Project File Structure
19+
20+
Projects live in `projects/` as either:
21+
- `PROJECT_NAME.md` - single file project
22+
- `PROJECT_NAME/` - folder with multiple materials
23+
24+
### Standard Sections
25+
26+
```markdown
27+
# Project Title
28+
29+
## Overview
30+
[Project description, goals, selection criteria]
31+
32+
## Items to Process
33+
| Item | Field1 | Field2 | Status |
34+
|------|--------|--------|--------|
35+
| Item A | value | value | [ ] |
36+
| Item B | value | value | [x] |
37+
38+
---
39+
# STATUS
40+
## Tier/Category 1 (N/M) ✓
41+
- [x] Completed item - Date, notes
42+
- [ ] Pending item
43+
44+
## Tier/Category 2 (N/M)
45+
- [ ] Item
46+
47+
# NOTES
48+
## YYYY-MM-DD
49+
[Session notes - add new entries at top]
50+
```
51+
52+
## Core Workflows
53+
54+
### 1. View Project Status
55+
56+
```bash
57+
# List all projects
58+
ls projects/
59+
60+
# Quick status - count checkboxes
61+
grep -c "^\- \[x\]" projects/CANCER.md # completed
62+
grep -c "^\- \[ \]" projects/CANCER.md # pending
63+
```
64+
65+
### 2. Pick Up Next Item
66+
67+
Read project file → find first unchecked item in priority order → work on it.
68+
69+
```python
70+
# Parse checkboxes from markdown
71+
import re
72+
with open("projects/CANCER.md") as f:
73+
content = f.read()
74+
# Find unchecked items: - [ ] Item name
75+
pending = re.findall(r'- \[ \] (.+)', content)
76+
next_item = pending[0] if pending else None
77+
```
78+
79+
### 3. Update Status After Work
80+
81+
After completing an item:
82+
1. Change `- [ ]` to `- [x]`
83+
2. Add date/compliance info: `- [x] Item Name - Created 2026-01-30, 55% compliance`
84+
3. Add session notes under `# NOTES` with today's date
85+
86+
### 4. Add Session Notes
87+
88+
Always add notes incrementally:
89+
```markdown
90+
# NOTES
91+
92+
## 2026-01-30
93+
[Today's work - add at TOP]
94+
- Completed X, Y, Z
95+
- Key findings: ...
96+
97+
## 2026-01-29
98+
[Previous session - don't edit unless continuing]
99+
```
100+
101+
Get today's date: `date +%Y-%m-%d`
102+
103+
## GitHub Project Sync
104+
105+
### Setup (One-Time)
106+
107+
```bash
108+
# Check auth has project scope
109+
gh auth status # should show 'project' in scopes
110+
111+
# If missing:
112+
gh auth refresh -s project
113+
114+
# Create a new GitHub Project for a markdown project
115+
gh project create --owner @me --title "dismech: CANCER Curation"
116+
# Note the project number returned (e.g., 4)
117+
```
118+
119+
### Sync Checkboxes → GitHub Project Items
120+
121+
Parse markdown checkboxes and create/update GitHub Project items:
122+
123+
```bash
124+
# List existing items in project
125+
gh project item-list PROJECT_NUMBER --owner @me --format json
126+
127+
# Create a draft item (not linked to issue)
128+
gh project item-create PROJECT_NUMBER --owner @me \
129+
--title "Chronic Myeloid Leukemia" \
130+
--body "Tier 1: BCR-ABL1 paradigmatic cancer"
131+
132+
# Update item status (need field ID and option ID)
133+
# First, get field info:
134+
gh project field-list PROJECT_NUMBER --owner @me --format json
135+
136+
# Then update:
137+
gh project item-edit --id ITEM_ID \
138+
--field-id STATUS_FIELD_ID \
139+
--single-select-option-id DONE_OPTION_ID \
140+
--project-id PROJECT_ID
141+
```
142+
143+
### Useful gh project commands
144+
145+
```bash
146+
# List your projects
147+
gh project list --owner @me
148+
149+
# View project details
150+
gh project view NUMBER --owner @me
151+
152+
# Get items as JSON for parsing
153+
gh project item-list NUMBER --owner @me --format json | jq '.items[]'
154+
155+
# Get field definitions (needed for updates)
156+
gh project field-list NUMBER --owner @me --format json
157+
158+
# Delete an item
159+
gh project item-delete NUMBER --owner @me --id ITEM_ID
160+
161+
# Archive an item (keeps it but hides from view)
162+
gh project item-archive NUMBER --owner @me --id ITEM_ID
163+
```
164+
165+
### Field IDs Quick Reference
166+
167+
Status field typically has these option IDs (varies per project):
168+
- Todo: find in `gh project field-list` output
169+
- In Progress: find in output
170+
- Done: find in output
171+
172+
Example parsing:
173+
```bash
174+
gh project field-list 4 --owner @me --format json | \
175+
jq '.fields[] | select(.name=="Status") | .options'
176+
```
177+
178+
## Integration with dismech Workflow
179+
180+
When working on dismech projects:
181+
182+
1. **Pick item from project** → consult `initiate-new-disorder-creation` skill
183+
2. **After creating disorder file** → run `just compliance kb/disorders/NewFile.yaml`
184+
3. **Update project checkbox** → add compliance score
185+
4. **Sync to GitHub Project** → if project has linked GH Project
186+
187+
### Example Session
188+
189+
```
190+
1. Read projects/CANCER.md
191+
2. Find next pending: "- [ ] Chronic Myeloid Leukemia"
192+
3. Use initiate-new-disorder-creation skill
193+
4. Run validation: just qc
194+
5. Update markdown:
195+
"- [x] Chronic Myeloid Leukemia - Created 2026-01-30, 60% compliance"
196+
6. Add session notes
197+
7. (Optional) Sync to GitHub Project
198+
```
199+
200+
## Deprecation Note
201+
202+
This skill replaces the older `/pm` command. Key differences:
203+
- GitHub Project sync capability (new)
204+
- More structured checkbox parsing (improved)
205+
- Clearer session notes format (improved)
206+
207+
The `/pm` command remains available but should be considered deprecated.

‎.claude/skills/projman/references/gh_project_api.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# GitHub Projects CLI Reference
2+
3+
Quick reference for `gh project` commands. Load this when doing project sync operations.
4+
5+
## Authentication
6+
7+
```bash
8+
# Check current scopes
9+
gh auth status
10+
11+
# Add project scope if missing
12+
gh auth refresh -s project
13+
```
14+
15+
## Project Operations
16+
17+
```bash
18+
# List projects
19+
gh project list --owner @me
20+
gh project list --owner monarch-initiative
21+
22+
# View project
23+
gh project view NUMBER --owner OWNER
24+
25+
# Create project
26+
gh project create --owner @me --title "Project Name"
27+
28+
# Close/reopen
29+
gh project close NUMBER --owner OWNER
30+
gh project edit NUMBER --owner OWNER --visibility public
31+
```
32+
33+
## Item Operations
34+
35+
```bash
36+
# List items (JSON for parsing)
37+
gh project item-list NUMBER --owner OWNER --format json --limit 500
38+
39+
# Create draft item
40+
gh project item-create NUMBER --owner OWNER \
41+
--title "Item Title" \
42+
--body "Description"
43+
44+
# Add issue/PR to project
45+
gh project item-add NUMBER --owner OWNER --url "https://github.com/..."
46+
47+
# Delete item
48+
gh project item-delete NUMBER --owner OWNER --id ITEM_ID
49+
50+
# Archive item (hides but keeps)
51+
gh project item-archive NUMBER --owner OWNER --id ITEM_ID
52+
```
53+
54+
## Field Operations
55+
56+
```bash
57+
# List fields (get IDs for updates)
58+
gh project field-list NUMBER --owner OWNER --format json
59+
60+
# Create custom field
61+
gh project field-create NUMBER --owner OWNER \
62+
--name "Tier" \
63+
--data-type "SINGLE_SELECT"
64+
65+
# Delete field
66+
gh project field-delete NUMBER --owner OWNER --id FIELD_ID
67+
```
68+
69+
## Updating Item Fields
70+
71+
This is the complex part - you need IDs from field-list:
72+
73+
```bash
74+
# Get field info
75+
gh project field-list NUMBER --owner OWNER --format json | \
76+
jq '.fields[] | select(.name=="Status")'
77+
78+
# Update status (single-select field)
79+
gh project item-edit \
80+
--id ITEM_ID \
81+
--field-id STATUS_FIELD_ID \
82+
--single-select-option-id DONE_OPTION_ID \
83+
--project-id PROJECT_ID
84+
85+
# Update text field
86+
gh project item-edit \
87+
--id ITEM_ID \
88+
--field-id TEXT_FIELD_ID \
89+
--text "New value" \
90+
--project-id PROJECT_ID
91+
92+
# Update number field
93+
gh project item-edit \
94+
--id ITEM_ID \
95+
--field-id NUMBER_FIELD_ID \
96+
--number 42 \
97+
--project-id PROJECT_ID
98+
99+
# Update date field
100+
gh project item-edit \
101+
--id ITEM_ID \
102+
--field-id DATE_FIELD_ID \
103+
--date "2026-01-30" \
104+
--project-id PROJECT_ID
105+
```
106+
107+
## JSON Parsing Patterns
108+
109+
```bash
110+
# Get all item titles
111+
gh project item-list NUMBER --owner OWNER --format json | \
112+
jq -r '.items[].title'
113+
114+
# Get item IDs and titles
115+
gh project item-list NUMBER --owner OWNER --format json | \
116+
jq -r '.items[] | "\(.id)\t\(.title)"'
117+
118+
# Find specific item ID
119+
gh project item-list NUMBER --owner OWNER --format json | \
120+
jq -r '.items[] | select(.title=="Item Name") | .id'
121+
122+
# Get Status field options
123+
gh project field-list NUMBER --owner OWNER --format json | \
124+
jq '.fields[] | select(.name=="Status") | .options'
125+
126+
# Get project ID (needed for item-edit)
127+
gh project view NUMBER --owner OWNER --format json | jq -r '.id'
128+
```
129+
130+
## Common Field Types
131+
132+
| Type | Update Flag | Example |
133+
|------|-------------|---------|
134+
| SingleSelect | `--single-select-option-id` | Status field |
135+
| Text | `--text` | Notes |
136+
| Number | `--number` | Priority |
137+
| Date | `--date` | Due date |
138+
| Iteration | `--iteration-id` | Sprint |
139+
140+
## Default Status Options
141+
142+
Most projects have these status options (IDs vary):
143+
- Todo
144+
- In Progress
145+
- Done
146+
147+
Get actual IDs:
148+
```bash
149+
gh project field-list NUMBER --owner OWNER --format json | \
150+
jq '.fields[] | select(.name=="Status") | .options[] | {name, id}'
151+
```

0 commit comments

Comments
 (0)