Issue Lifecycle

Creating an Issue for the Executor

1. Create a GitHub issue in any managed repo
2. Add the agent-ready label
3. The executor picks it up within 60 seconds

Tips for Good Issues

• Clear title with conventional prefix: feat:, fix:, docs:, refactor:
• Specific requirements — list exactly what needs to change
• Acceptance criteria — how to verify the fix
• Add agent-opus label for complex tasks that need the stronger model

Example

Title: fix: allow joining a family without a subscription

## Problem
The "Join Family" button requires premium. Parent B can't join.

## Expected
Parent B can join via invite code without paying.

## Acceptance Criteria
- [ ] Free-tier signed-in user can tap "Join Family"
- [ ] Premium status shared via Firebase after joining

What Happens After Assignment

Step	Time	What
1. Claim	~1s	Executor adds agent-claimed, removes agent-ready
2. Clone	~5s	Clones repo to /tmp/executor-workspaces/
3. Claude	1-10 min	Reads issue, explores code, recalls memory, implements
4. Push	~5s	Pushes branch, creates PR
5. Review	1-3 min	Copilot reviews, auto-resolve runs
6. Merge	~30s	Auto-merge merges to main
7. Release	~1 min	Release-please creates version bump

Total: ~5-15 minutes from assignment to merged.

Monitoring

Discord (#ibuild-e)

The executor posts to Discord at key moments:

• "Claimed repo#N: title"
• "PR created for repo#N: URL"
• "Agent failed on repo#N: reason"

Executor Health

curl http://100.92.170.124:8090/health

Returns uptime, issues processed, and current status.

Logs

ssh -i ~/.ssh/mac-executor claude@100.92.170.124

# Main executor log
tail -f ~/.claude/executor-logs/executor.log

# LaunchAgent stderr (startup errors)
tail -f /tmp/mac-executor-launchd-err.log

# LaunchAgent stdout (debug output)
tail -f /tmp/mac-executor-launchd.log

Handling Failures

When the executor fails on an issue:

1. Issue gets agent-failed label
2. Comment explains what went wrong
3. Discord notification sent

To Retry

# Remove failed label, re-add ready
gh issue edit N --repo Owner/repo --remove-label agent-failed --add-label agent-ready

Common Failures

Failure	Cause	Fix
No commits made	Claude couldn't figure out the fix	Add more detail to the issue, or use agent-opus label
Build failed	Code doesn't compile	Check if the issue description has enough context
PR creation error	GitHub API timeout	Usually self-recovers (PR exists despite error)
Clone failed	Repo access issue	Check GitHub App token