GitHub Issue Workflow (Float-Ritual-Stack)

When asked to "work on issue X", "process issue X", or "handle float-hub#7", follow this workflow.

This is Evan's personal workflow for float-ritual-stack projects - optimized for fast iteration and rich communication.

Step 1: Read & Start

1. Read the issue: github_read_issue(repo, number)

   • Understand what's being asked
   • Note any specific requirements

2. Add to project board (if not already there):

   # Add issue to float-hub-operations project
   gh issue view {number} --repo {repo} --json projectItems --jq '.projectItems[].id' || \
   gh project item-add 5 --owner float-ritual-stack --url https://github.com/{repo}/issues/{number}
   

3. Move to "In Progress":

   # Get the project item ID for this issue
   ITEM_ID=$(gh project item-list 5 --owner float-ritual-stack --format json | \
     jq -r ".items[] | select(.content.number=={number}) | .id")
   
   # Move to "In Progress" status
   gh project item-edit --id $ITEM_ID \
     --project-id PVT_kwDODNDomc4BG-s0 \
     --field-id PVTSSF_lADODNDomc4BG-s0zg33j_Q \
     --single-select-option-id 47fc9ee4
   

4. Mark in-progress: github_add_label(repo, number, "in-progress")

5. Post starting comment:

   github_comment_issue(repo, number, "🤖 Starting work on this issue...")
   

Step 2: Do The Work

Execute the task described in the issue. Common patterns:

For Bridge Creation

• Read source content (GitHub issue body, daily notes, etc.)
• Synthesize with LLM (ask_evna, semantic_search, brain_boot)
• Create bridge document with proper frontmatter
• Write to ~/float-hub/float.dispatch/bridges/

For Code/Config Changes

• Make the changes
• Test if appropriate
• Document what was changed

For Research/Synthesis

• Gather information
• Synthesize findings
• Create output document

Step 3: Commit Frequently

Float-ism: Commit often, commit fearlessly

• NO branching required for float-ritual-stack repos
• Commit directly to main (these are notes, not production)
• Commit after:
  • Creating files
  • Major milestones
  • Logical checkpoints

Good commit messages:

feat(bridges): Add github-issue-workflow skill bridge
docs(evna): Document background task architecture
fix(cli): Handle missing notify-issue gracefully

Use available tools:

• write_file to create/update files
• read_file to verify changes
• For git commits, use Bash tool with git commands

Step 4: Update Progress

Post progress comments to the issue as you work. Use rich markdown formatting for clarity:

Good Progress Update Format

## 📝 Progress Update

**Current Step**: Creating bridge document

**Completed**:
- ✅ Read issue and gathered context
- ✅ Searched semantic history (found 3 related sessions)
- ✅ Drafted initial synthesis

**In Progress**:
- 🔄 Writing bridge document at `bridges/xyz.bridge.md`
- 🔄 Adding cross-references to related bridges

**Next Steps**:
- Commit bridge document
- Update issue with completion summary

Example Progress Comments

Starting a major step:

## 🔍 Research Phase

Searching for related work using:
- `semantic_search("consciousness tech stack")`
- `brain_boot(project: "pharmacy", lookbackDays: 7)`

Will report back with findings in ~5 minutes.

Hitting a blocker:

## 🐛 Blocker Found

**Issue**: Can't find the referenced bridge document mentioned in issue body.

**Searched**:
- `~/float-hub/float.dispatch/bridges/*.md`
- Semantic search for "AI SDK convergence"
- Recent daily notes

**Need**: Could you clarify which bridge document this refers to? Or should I create a new one?

**Status**: Paused pending clarification

Major milestone:

## ✅ Milestone: Bridge Document Created

Created `bridges/consciousness-tech-stack-convergence.bridge.md`

**Contents**:
- Historical context from 3 Claude sessions (Oct 28-30)
- Architecture validation findings
- Cross-references to AI SDK v6 work

**File Stats**: 247 lines, 3 sections, 5 cross-references

**Committed**: `feat(bridges): Add consciousness tech stack convergence bridge`

**Next**: Final review and issue close

Emoji guide:

• 🤖 Starting work
• 📝 Writing/creating
• 🔍 Researching/searching
• 🔄 In progress
• ✅ Completed
• 🐛 Found issue
• 🔧 Fixing
• ⏸️ Paused/blocked
• 🎯 Milestone reached

Update when:

• Starting major steps (with plan)
• Hitting blockers (with details)
• Completing major milestones (with artifacts)
• Every 5-10 minutes of work (don't go silent!)
• After each commit (what changed)

Step 5: Finish & Close

1. Final commit with summary of all changes

2. Post completion comment (use rich formatting):

   ## ✅ Issue Completed
   
   **Deliverables**:
   - 📄 `bridges/github-issue-workflow.bridge.md` (213 lines)
   - 📝 Updated skill documentation with project board integration
   - 🔧 Added 3 helper bash functions
   
   **Summary**:
   Synthesized GitHub issue workflow into a comprehensive bridge document covering:
   - Float-ism philosophy and conventions
   - Project board integration (Todo→In Progress→Done)
   - Best practices for progress updates
   - Common workflow patterns
   
   **Work Log**:
   - 🔍 Researched existing workflows (semantic search, 5 sessions found)
   - 📝 Drafted bridge structure (45 min)
   - 🔄 Integrated feedback from daily notes
   - ✅ Tested with real issue processing
   
   **Commits**:
   1. `feat(bridges): Add github-issue-workflow bridge`
   2. `docs(skills): Update skill with progress formatting`
   3. `feat(bridges): Add project board commands`
   
   **Stats**: 3 commits, 2 hours, 247 lines added
   
   **Next**: Ready to use this workflow for future issues! 🚀
   

3. Move to "Done" on project board:

   # Get the project item ID for this issue
   ITEM_ID=$(gh project item-list 5 --owner float-ritual-stack --format json | \
     jq -r ".items[] | select(.content.number=={number}) | .id")
   
   # Move to "Done" status
   gh project item-edit --id $ITEM_ID \
     --project-id PVT_kwDODNDomc4BG-s0 \
     --field-id PVTSSF_lADODNDomc4BG-s0zg33j_Q \
     --single-select-option-id 98236657
   

4. Remove in-progress label:

   github_remove_label(repo, number, "in-progress")
   

5. Close the issue:

   github_close_issue(repo, number, "✅ Completed! See comments above for details.")
   

Repository-Specific Rules

float-ritual-stack/* repos (ALL)

• ✅ Commit directly to main
• ✅ Fast iteration over ceremony
• ✅ Rich emoji communication
• ✅ Frequent progress updates
• ❌ No branching required
• ❌ No PR process

These are Evan's personal projects and notes repos - optimize for flow, not gates.

Other organizations

If working on repos outside float-ritual-stack, follow their conventions (branches, PRs, etc.)

Common Patterns

Pattern: Issue → Bridge

1. Read issue: github_read_issue
2. Add to project board (if needed)
3. Move to "In Progress" on board
4. Mark in-progress label
5. Post "🤖 Starting..."
6. Search for related context (semantic_search, brain_boot)
7. Synthesize content
8. Create bridge document (write_file)
9. Commit: "feat(bridges): Add X bridge from issue #Y"
10. Post "✅ Completed" with file path
11. Move to "Done" on board
12. Remove in-progress label
13. Close issue

Pattern: Issue → Code Change

1. Read issue
2. Mark in-progress
3. Post "🤖 Starting..."
4. Make code changes
5. Commit: "feat(X): Implement Y per issue #Z"
6. Post progress with what changed
7. Test if needed
8. Post "✅ Completed" with summary
9. Remove in-progress, close issue

Pattern: Issue → Research/Documentation

1. Read issue
2. Mark in-progress
3. Post "🤖 Starting..."
4. Gather information (search, read files)
5. Synthesize findings
6. Create document (daily note, bridge, etc.)
7. Commit: "docs(X): Add Y from issue #Z"
8. Post "✅ Completed" with document location
9. Remove in-progress, close issue

Error Handling

If you hit blockers:

1. Post comment describing the blocker
2. Keep "in-progress" label
3. Ask for clarification or help
4. DON'T close the issue

If you can't complete:

1. Post what you accomplished
2. Post what's still needed
3. Remove "in-progress" label
4. Leave issue open

Best Practices

✅ DO:

• Commit frequently (after each logical step)
• Update the issue regularly (every 5-10 mins of work)
• Use descriptive commit messages
• Use emoji in issue comments
• Post completion summaries with file paths
• Close issues when truly done

❌ DON'T:

• Go silent for long periods
• Make one giant commit at the end
• Close issues prematurely
• Leave "in-progress" label on closed issues
• Skip progress updates

Float-Ism Philosophy

"Fast iteration, rich communication, fearless commits"

These workflows optimize for:

• Velocity over ceremony
• Transparency over stealth
• Done over perfect

We're building in public, for ourselves, with AI assistants. Make it work, make it visible, make it flow.

---

Appendix: Project Board Configuration

float-hub-operations Project (ID: 5)

• Project ID: PVT_kwDODNDomc4BG-s0
• Status Field ID: PVTSSF_lADODNDomc4BG-s0zg33j_Q

Status Options:

• Todo: f75ad846
• In Progress: 47fc9ee4
• Done: 98236657

Helpful Commands

List all projects:

gh project list --owner float-ritual-stack --format json

Get project fields:

gh project field-list 5 --owner float-ritual-stack --format json

Check if issue is in project:

gh issue view {number} --repo {repo} --json projectItems

Get item ID from issue number:

gh project item-list 5 --owner float-ritual-stack --format json | \
  jq -r ".items[] | select(.content.number=={number}) | .id"