Project Management Workflow¶

This document describes the GitHub-native project management approach for gepa-adk, using labels, native issue dependencies, and GitHub Projects views.

Philosophy¶

• Labels as metadata - Priority, fit, size and track labels drive all views
• Native dependencies - Use GitHub's blocked by relationships between issues; the blocked label is only for blockers that are not issues
• Views as filters - Project views slice existing data, no manual board management
• Release-driven - Work P1 and P2 until empty, then release and re-prioritize
• Zero ceremony - No sprints, no timeboxes, just continuous flow

Label Schema¶

Priority Labels (Required for "Groomed" Status)¶

Priority measures impact, not urgency. The scale is shared with judgevet.

No P label = Ungroomed - Appears in Needs Grooming view.

The former priority:high, priority:medium and priority:low labels were retired on 2026-09-25. They remain on closed issues for history and must not be applied to new ones.

Fit and Size Labels (Required for "Groomed" Status)¶

Fit says who does the work. Size says whether it can be dispatched whole. Size is defined once, by behaviour, in Delegate a bounded change; the rows below only summarize it.

Workflow Labels¶

ready is the definition of ready. An issue earns it when a comment records the decision, the necessary evidence, the allowed repairs and the stopping condition, under 150 words, as the repository's bounded-execution rule in CLAUDE.md requires. The specifier agent writes that comment when the brief authorizes posting. A P label alone does not make an issue ready.

blocked is a label because GitHub's native is:blocked filter only sees issue-to-issue dependencies. Use both: the label for a dependency on a release, a credential or a date, and the native relationship for another issue.

Track Labels (Context/Category)¶

Type Labels (Auto-applied by templates)¶

Status (Inferred, Not Labeled)¶

GitHub Project Views¶

From the CLI:

# what is ready to be worked
gh issue list --search "is:open label:ready -label:blocked -is:blocked no:assignee"
# wrong records a worker can fix now
gh issue list --search "is:open label:P2 label:pi-fit -label:blocked -is:blocked"
# what needs splitting (inventory, so blocked issues stay in)
gh issue list -l size-L

-l alone cannot see GitHub-native dependencies, so every actionable query goes through --search with -is:blocked.

Optional Views¶

Workflow¶

Daily Work¶

1. Look at the Ready view (or the P1 / P2 view when choosing what to specify next)
2. Pick an unassigned issue
3. Assign yourself (now "In Progress")
4. Work on it
5. Close when done (moves to "Done")
6. Repeat

Grooming¶

1. Open Needs Grooming view
2. For each issue:
3. Read and understand
4. Add one P label by impact, one fit label and one size label
5. Add track labels (core, adk, etc.)
6. Add blocked and name the blocker in the body, or add a GitHub dependency
7. Issue automatically moves to appropriate view
8. To make a triaged issue Ready, post the definition of ready and done as a comment, then add ready

Release Cycle¶

1. Work until P1 / P2 is empty (except epics)
2. Release
3. Re-read the open P3 issues:
4. Promote any whose impact grew to P2
5. Demote any that turned into drift to P4
6. Check Needs Grooming for anything missed
7. Repeat

Dependencies¶

GitHub supports native issue dependencies (GA August 2025).

Adding a Dependency¶

Via UI: 1. Open the issue that is blocked 2. In right sidebar, find Relationships 3. Click "Mark as blocked by" 4. Select the blocking issue(s)

Via CLI (GraphQL):

# Get issue node IDs first
gh api graphql -f query='{
  repository(owner: "Alberto-Codes", name: "gepa-adk") {
    issue(number: ISSUE_NUMBER) { id title }
  }
}'

# Add dependency
gh api graphql -f query='
mutation {
  addBlockedBy(input: {
    issueId: "BLOCKED_ISSUE_NODE_ID"
    blockingIssueId: "BLOCKING_ISSUE_NODE_ID"
  }) { issue { number } }
}'

Filtering Blocked Issues¶

• is:blocked - All blocked issues
• -is:blocked - All unblocked issues
• Use -is:blocked in the Ready, P1 / P2 and Delegable views to show only actionable work

Issue Templates¶

All templates include invisible maintainer/AI guidance comments with: - Priority, fit and size label guidance - Track label hints - Dependency setup instructions via GraphQL

Maintenance¶

Regular Tasks¶

Health Checks¶

• Needs Grooming not empty too long - Schedule grooming
• Ready empty while P1 / P2 is not - Run a specification pass
• P1 / P2 empty - Time for release or re-prioritize
• Blocked growing - Check if blockers are being worked

References¶

• GitHub Projects Documentation
• Creating Issue Dependencies