Label color-coding + HANDOFF.md workflow update
Part of Issue Contracts (umbrella: #57 ).
Depends on **Issues #58 and #59 ** being complete.
Context
Routing labels (rfc, for_cowork, for_session, regression, hotfix) now carry contracts. They direct AI engagement mode. Visual reinforcement in the GitHub UI helps humans scan the backlog at a glance and reinforces the contract meaning.
This issue also updates HANDOFF.md to document the full AI workflow (verify → knowledge → plan) now that both endpoints exist.
Color mapping
Consistent with common conventions (red = stop/urgent, green = go, yellow = caution, purple = design):
| Label |
Color |
Hex |
Meaning |
regression |
Red |
#d73a4a |
Drop everything |
hotfix |
Red |
#d73a4a |
Drop everything |
rfc |
Purple |
#7057ff |
Design spike — think first |
for_cowork |
Green |
#0e8a16 |
Ready to execute |
for_session |
Yellow |
#fbca04 |
Discussion required |
next-priority |
Dark blue |
#0052cc |
Owner-designated priority |
icebox |
Gray |
#e6e6e6 |
Parked |
architecture |
Light purple |
#c5b6ff |
Cross-cutting design |
server |
Dark gray |
#333333 |
Ops/infrastructure |
ui |
Cyan |
#1d76db |
User-facing rendering |
tests |
Light green |
#b4e59c |
Test infra |
tour |
Orange |
#ff8c00 |
Onboarding feature |
accessibility |
Pink |
#ff69b4 |
a11y concern |
external-assets |
Brown |
#8b4513 |
Assets fetched at runtime |
store |
Navy |
#1a3a7c |
Store/state layer |
HANDOFF.md updates
FIRST ACTIONS section
Add steps 6 and 7:
6. Before planning any issue, run `GET /verify-issue?number=N`.
If `ready_to_plan: false`, address errors. If warnings present,
acknowledge with user before proceeding.
7. After green verification, run `GET /knowledge?labels=<labels>`
(using labels from verify response). Apply principles returned.
DEV SERVER API table
Add rows:
| /verify-issue?number=N | Label-keyed verification + mode derivation |
| /knowledge?labels=X,Y | Label-keyed principle retrieval |
Issue Contracts section (new)
Add a new top-level section documenting:
- What an Issue Contract is (the four layers)
- The five routing labels and their modes
- How color coding reinforces contract meaning
- Link to the umbrella issue
Steps
- Apply colors via
gh label edit for each label in the mapping table
- Update HANDOFF.md FIRST ACTIONS with steps 6 and 7
- Update HANDOFF.md DEV SERVER API table with new endpoints
- Add Issue Contracts section to HANDOFF.md
- Commit HANDOFF.md changes
- Verify colors render correctly in GitHub UI (screenshot attached to issue)
Done when
Do not touch
- Any code files (this is documentation + GitHub API only)
- Label names (colors only; names are stable)
- Issue bodies (this issue doesn't relabel or re-triage anything)
Out of scope
- Auto-applying labels based on content
- Bulk re-triage of existing issues
- Renaming labels
Label color-coding + HANDOFF.md workflow update
Part of Issue Contracts (umbrella: #57 ).
Depends on **Issues #58 and #59 ** being complete.
Context
Routing labels (
rfc,for_cowork,for_session,regression,hotfix) now carry contracts. They direct AI engagement mode. Visual reinforcement in the GitHub UI helps humans scan the backlog at a glance and reinforces the contract meaning.This issue also updates HANDOFF.md to document the full AI workflow (verify → knowledge → plan) now that both endpoints exist.
Color mapping
Consistent with common conventions (red = stop/urgent, green = go, yellow = caution, purple = design):
regression#d73a4ahotfix#d73a4arfc#7057fffor_cowork#0e8a16for_session#fbca04next-priority#0052ccicebox#e6e6e6architecture#c5b6ffserver#333333ui#1d76dbtests#b4e59ctour#ff8c00accessibility#ff69b4external-assets#8b4513store#1a3a7cHANDOFF.md updates
FIRST ACTIONS section
Add steps 6 and 7:
DEV SERVER API table
Add rows:
Issue Contracts section (new)
Add a new top-level section documenting:
Steps
gh label editfor each label in the mapping tableDone when
Do not touch
Out of scope