beeops 0.1.0

package/skills/bo-dispatch/SKILL.md

@@ -0,0 +1,299 @@
+---
+name: bo-dispatch
+description: Launch Leader/Review Leader in tmux windows, wait for completion, read reports, and determine next action. Queen's dispatch skill for beeops.
+---
+
+# bo-dispatch: Leader launch + completion wait + report processing
+
+Operational skill for the Queen to delegate issues to Leaders and Review Leaders.
+Provides agent visualization via tmux windows, event-driven completion waiting, and next-action determination based on reports.
+
+## Launching Leaders
+
+### For issue tasks
+
+```bash
+# Implementation Leader
+bash $BO_SCRIPTS_DIR/launch-leader.sh leader {issue_number} {branch}
+
+# Review Leader
+bash $BO_SCRIPTS_DIR/launch-leader.sh review-leader {issue_number} {branch}
+
+# Fix mode (reuse existing worktree/branch)
+bash $BO_SCRIPTS_DIR/launch-leader.sh leader {issue_number} {branch} fix
+```
+
+`launch-leader.sh` automatically performs the following:
+- Creates a **new tmux window** for each issue (`issue-{N}` or `review-{N}`)
+- Leader: Launches `claude` with git worktree isolation and appropriate environment variables / tool restrictions
+- Review Leader: Launches `claude` on the main repo (read-only)
+- On completion, writes a report YAML and sends a `tmux wait-for -S queen-wake` signal
+- Users can simply tmux attach to see the Queen and each issue's Leader/Worker in separate windows
+
+## Completion Waiting (Event-Driven)
+
+### Waiting for Leader completion
+
+```bash
+# Wait with 30-minute timeout
+(sleep 1800 && tmux wait-for -S queen-wake) &
+TIMER_PID=$!
+tmux wait-for queen-wake
+kill $TIMER_PID 2>/dev/null
+```
+
+### Waiting for Review Leader completion
+
+```bash
+# Wait with 20-minute timeout
+(sleep 1200 && tmux wait-for -S queen-wake) &
+TIMER_PID=$!
+tmux wait-for queen-wake
+kill $TIMER_PID 2>/dev/null
+```
+
+### Post-wake determination
+
+Check `.claude/tasks/reports/`:
+- **New report found** — Normal completion. Proceed to report processing.
+- **No report (timeout)** — Check window state.
+
+### State check on timeout
+
+```bash
+tmux list-panes -t bo:{window_name} -F '#{@agent_label} #{pane_current_command}' 2>/dev/null
+```
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| `claude` is running | Work still in progress | Proceed to next wait-for |
+| Returned to `zsh`/`bash` | Completed but signal failed | Check report manually |
+| Window has disappeared | Abnormal termination | Update status to `error` |
+
+## Report Processing
+
+### Report files
+
+```
+.claude/tasks/reports/
+├── leader-{N}.yaml                      # Basic report written by launch-leader.sh (guaranteed)
+├── leader-{N}-summary.yaml              # Detailed summary written by Leader (optional)
+├── review-leader-{N}.yaml               # Basic report written by launch-leader.sh (guaranteed)
+├── review-leader-{N}-verdict.yaml       # Verdict written by Review Leader (optional)
+├── worker-{N}-{subtask_id}.yaml         # Basic report written by launch-worker.sh (guaranteed)
+├── worker-{N}-{subtask_id}-detail.yaml  # Detail written by Worker (optional)
+└── processed/                           # Storage for processed reports
+```
+
+### Basic report format
+
+```yaml
+issue: 42
+role: leader    # leader | review-leader
+status: completed # completed | failed
+exit_code: 0
+branch: feat/issue-42
+timestamp: "2026-03-02T12:00:00Z"
+```
+
+### Leader summary format
+
+```yaml
+issue: 42
+role: leader
+status: completed
+branch: "feat/issue-42"
+pr: "https://github.com/.../pull/42"
+summary: "High-level overview of the implementation"
+subtasks_completed: 3
+subtasks_total: 3
+concerns: null
+key_changes:
+  - file: "file path"
+    what: "description of change"
+design_decisions:
+  - decision: "what was chosen"
+    reason: "rationale"
+```
+
+### Review Leader verdict format
+
+```yaml
+issue: 42
+role: review-leader
+complexity: standard
+council_members: [worker-code-reviewer, worker-security]
+final_verdict: approve    # approve | fix_required
+anti_sycophancy_triggered: false
+merged_findings:
+  - source: worker-security
+    severity: high
+    file: src/api/route.ts
+    line: 23
+    message: "description of the finding"
+fix_instructions: null
+```
+
+## Next-Action Determination Rules
+
+### For Leader reports
+
+| Report content | queue.yaml update | Next action |
+|----------------|-------------------|-------------|
+| `status: completed` + summary present | → `review_dispatched` | Launch Review Leader |
+| `status: completed` + no summary | → `review_dispatched` | Launch Review Leader (acceptable without summary) |
+| `status: failed` | → `error` | Move to next task |
+
+### For Review Leader verdicts
+
+| Verdict | queue.yaml update | Next action |
+|---------|-------------------|-------------|
+| `final_verdict: approve` | → `ci_checking` | Proceed to **CI check phase** |
+| `final_verdict: fix_required` and review_count < 3 | → `fixing` | Restart Leader (fix mode) |
+| `final_verdict: fix_required` and review_count >= 3 | → `stuck` | Skip (awaiting user intervention) |
+
+### On Review Leader failure
+
+| State | Response |
+|-------|----------|
+| `status: failed` + 1st occurrence | Retry once |
+| `status: failed` + 2nd occurrence | → `error` |
+
+## Restarting Leader in fix mode
+
+When the Review Leader returns fix_required:
+
+1. Write a fix prompt to: `.claude/tasks/prompts/fix-leader-{N}.md`
+2. Include review findings and fix instructions in the fix prompt
+3. Restart with `launch-leader.sh leader {N} {branch} fix` (reuses existing worktree)
+
+Fix prompt content:
+```markdown
+You are a Leader agent. Fix the review findings for Issue #{N}.
+
+## Review Findings
+{contents of review-leader-{N}-verdict.yaml}
+
+## Fix Instructions
+{contents of fix_instructions}
+
+## Procedure
+1. Review the findings
+2. Launch Workers to perform the fixes
+3. After fixes are complete, write the summary
+4. Signal queen-wake
+```
+
+## CI Check Phase
+
+After the Review Leader approves, verify that CI passes before marking as done.
+
+### CI check procedure
+
+1. **Check CI status**:
+
+```bash
+gh pr checks {PR_number} 2>&1
+```
+
+2. **Determination**:
+
+| CI result | queue.yaml update | Next action |
+|-----------|-------------------|-------------|
+| All checks pass | → `done` | Move to next task |
+| Still running/pending | Wait 5 minutes and recheck (up to 3 times) | |
+| Failure present | → `ci_fixing` | Restart Leader in fix mode |
+
+3. **Launching CI fix** (on failure):
+
+On CI failure, restart the Leader in fix mode. Include the CI failure log in the fix prompt:
+
+```markdown
+You are a Leader agent. Fix the CI failures on branch '{branch}'.
+
+## CI Failure Details
+{output of gh pr checks}
+
+## Fix Instructions
+Launch Workers to fix the CI errors.
+```
+
+4. **Recheck after CI fix**:
+
+After Leader completion, check `gh pr checks` again.
+- pass → `done`
+- fail (ci_fix_count < 3) → Restart Leader in fix mode again
+- fail (ci_fix_count >= 3) → `stuck`
+
+### CI wait loop
+
+```bash
+MAX_WAIT=3
+WAIT_COUNT=0
+while [ $WAIT_COUNT -lt $MAX_WAIT ]; do
+  sleep 300  # Wait 5 minutes
+  CI_STATUS=$(gh pr checks {PR_number} 2>&1)
+  if echo "$CI_STATUS" | grep -q "fail"; then
+    break  # CI failure → proceed to fix phase
+  elif echo "$CI_STATUS" | grep -qE "pass|✓" && ! echo "$CI_STATUS" | grep -qE "pending|running|skipping"; then
+    break  # All checks pass → proceed to done
+  fi
+  WAIT_COUNT=$((WAIT_COUNT + 1))
+done
+```
+
+### After report processing
+
+Move processed reports to `processed/` to prevent reprocessing:
+
+```bash
+mv .claude/tasks/reports/leader-{N}.yaml .claude/tasks/reports/processed/
+mv .claude/tasks/reports/leader-{N}-summary.yaml .claude/tasks/reports/processed/ 2>/dev/null
+mv .claude/tasks/reports/review-leader-{N}*.yaml .claude/tasks/reports/processed/ 2>/dev/null
+mv .claude/tasks/reports/worker-{N}-*.yaml .claude/tasks/reports/processed/ 2>/dev/null
+```
+
+## Cleanup
+
+Resources have different lifecycles. Clean up each at the right time.
+
+### tmux windows — on task completion
+
+After task reaches done, stuck, or error, kill the tmux windows:
+
+```bash
+tmux kill-window -t bo:issue-{N} 2>/dev/null || true
+tmux kill-window -t bo:review-{N} 2>/dev/null || true
+```
+
+### Worktrees and branches — after PR merge
+
+Worktrees and branches **must be kept alive** until the PR is merged. The Leader's job ends at PR creation; the branch is still needed for review cycles and CI.
+
+Clean up only after confirming the PR is merged:
+
+```bash
+# Check if PR is merged
+PR_STATE=$(gh pr view {PR_number} --json state -q '.state' 2>/dev/null)
+if [ "$PR_STATE" = "MERGED" ]; then
+  REPO_DIR=$(git rev-parse --show-toplevel)
+  WORKTREE_PATH="$REPO_DIR/.claude/worktrees/{branch}"
+
+  # 1. Remove worktree
+  git -C "$REPO_DIR" worktree remove --force "$WORKTREE_PATH" 2>/dev/null || true
+
+  # 2. Delete branch
+  git branch -D {branch} 2>/dev/null || true
+
+  # 3. Prune stale references
+  git worktree prune
+fi
+```
+
+### Session-end cleanup
+
+When the Queen session ends (`tmux kill-session -t bo`), prune any stale worktree references:
+
+```bash
+git worktree prune
+```

package/skills/bo-issue-sync/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: bo-issue-sync
+description: Sync GitHub Issues to queue.yaml. Detects new issues, analyzes dependencies, assigns priorities, and performs diff-merge.
+---
+
+# bo-issue-sync: Issue → queue.yaml Sync
+
+Fetches open Issues from GitHub and syncs them to `.claude/tasks/queue.yaml`.
+Handles adding new Issues, marking closed Issues as done, dependency analysis, and priority assignment in one operation.
+
+## Procedure
+
+### 1. Determine Repository
+
+```bash
+REPO=$(git remote get-url origin | sed -E 's#.*[:/]([^/]+/[^/.]+)(\.git)?$#\1#')
+```
+
+Use `-R $REPO` for all subsequent `gh` commands.
+
+### 2. Fetch Open Issues
+
+```bash
+gh issue list -R "$REPO" --state open --json number,title,labels,assignees --limit 100
+```
+
+If 0 issues, display "No issues to process" and exit.
+
+### 3. Load queue.yaml
+
+If `.claude/tasks/queue.yaml` exists, read it. Otherwise initialize:
+
+```yaml
+version: 1
+tasks: []
+```
+
+### 4. Diff Detection and Raw Addition
+
+Add Issues not present in queue.yaml with `raw` status:
+
+```yaml
+- id: "ISSUE-{number}"
+  issue: {number}
+  title: "{title}"
+  status: raw
+  priority: null
+  branch: null
+  depends_on: []
+  review_count: 0
+  pr: null
+  log:
+    - "{ISO8601} created from gh issue"
+```
+
+- Skip Issues already in queue.yaml (with status other than done)
+- Update status to `done` for Issues in queue.yaml that are closed on GitHub
+
+### 5. Dependency Analysis
+
+For each `raw` Issue:
+
+1. Fetch details: `gh issue view {N} -R "$REPO" --json body,labels`
+2. Determine dependencies:
+   - Issue body mentions "depends on #XX", "blocked by #XX", "after #XX", etc.
+   - Labels include `blocked`, `pending`, etc.
+   - Likely modifies the same files as other implementing/queued tasks (inferred from body)
+3. Add task IDs to `depends_on` if dependencies exist
+4. For issues with `pending` label, extract `blocked_reason` from the issue body
+
+### 6. Priority Assignment and Queued Status
+
+Set priority for each `raw` task and update to `queued`:
+
+| Condition | Priority |
+|-----------|----------|
+| Labels include `priority: high`, `urgent`, `bug` | high |
+| Normal feature additions/improvements, `priority: medium` | medium |
+| Labels include `priority: low`, `tech-debt` | low |
+
+**Branch name generation**: Derive from Issue title with `feat/`, `fix/`, `chore/` prefix + kebab-case
+
+### 7. Write queue.yaml
+
+```bash
+mkdir -p .claude/tasks
+```
+
+Write `.claude/tasks/queue.yaml` using the Write tool.
+
+### 8. Display Status
+
+```
+=== Queue Status ===
+Repository: {REPO}
+Total: {N} tasks
+
+[HIGH] Ready to start:
+  ISSUE-42  Add user authentication    queued  branch: feat/add-user-auth
+
+[BLOCKED] External blockers:
+  ISSUE-55  Database migration v2      queued  → Waiting for staging deploy
+```

package/skills/bo-leader-dispatch/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: bo-leader-dispatch
+description: Launch Workers in tmux panes, wait for completion, and evaluate quality. Shared dispatch skill for Leader and Review Leader.
+---
+
+# bo-leader-dispatch: Worker launch + completion wait + quality evaluation
+
+Operational skill for Leaders and Review Leaders to delegate subtasks to Workers.
+Provides Worker visualization via tmux split-pane, event-driven completion waiting, and retry determination based on quality evaluation.
+
+## Prerequisite: Prepare the prompt file
+
+Before launching a Worker, the Leader/Review Leader must write out a prompt file.
+
+Path: `.claude/tasks/prompts/worker-{issue}-{subtask_id}.md`
+
+If the prompt file does not exist, `launch-worker.sh` will exit with an error.
+
+## Launching Workers
+
+### Basic syntax
+
+```bash
+bash $BO_SCRIPTS_DIR/launch-worker.sh {role} {issue} {subtask_id} {branch}
+```
+
+### Available roles
+
+| Role | Purpose | Launched by |
+|------|---------|-------------|
+| worker-coder | Code implementation | Leader |
+| worker-tester | Test creation | Leader |
+| worker-code-reviewer | Code review | Review Leader |
+| worker-security | Security review | Review Leader |
+| worker-test-auditor | Test audit | Review Leader |
+
+### Launch examples
+
+```bash
+# Launch 2 implementation Workers in parallel
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-coder 42 impl-1 feat/issue-42
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-coder 42 impl-2 feat/issue-42
+
+# Test Worker
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-tester 42 test-1 feat/issue-42
+
+# Launch Review Workers in parallel
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-code-reviewer 42 review-code feat/issue-42
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-security 42 review-sec feat/issue-42
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-test-auditor 42 review-test feat/issue-42
+```
+
+`launch-worker.sh` automatically performs the following:
+- **Splits a pane** within the Leader's window (`tmux split-window -h`)
+- Evenly arranges all panes with `tmux select-layout tiled`
+- Launches `claude --dangerously-skip-permissions --no-session-persistence` with appropriate environment variables and tool restrictions
+- Workers share the Leader's worktree (no new worktree is created)
+- On completion, writes a report YAML and sends a `tmux wait-for -S leader-{issue}-wake` signal
+
+## Completion Waiting (Event-Driven)
+
+### Blocking wait (until all Workers complete)
+
+```bash
+EXPECTED=2  # Set to 1, 2, or 3 based on the number of launched Workers
+RECEIVED=0
+while [ $RECEIVED -lt $EXPECTED ]; do
+  (sleep 600 && tmux wait-for -S leader-{issue}-wake) &
+  TIMER_PID=$!
+  tmux wait-for leader-{issue}-wake
+  kill $TIMER_PID 2>/dev/null
+  RECEIVED=$((RECEIVED + 1))
+done
+```
+
+- All Workers use the same `leader-{issue}-wake` signal, so a counter detects when all have completed
+- The counter increments by 1 each time a Worker completes
+- The 10-minute timeout applies per Worker (not for the entire group)
+
+### Post-wake determination
+
+Check `.claude/tasks/reports/`:
+- **New report found** — Normal completion. Proceed to quality evaluation.
+- **No report (timeout)** — Check pane state.
+
+### State check on timeout
+
+```bash
+tmux list-panes -t bo:{window_name} -F '#{@agent_label} #{pane_current_command}' 2>/dev/null
+```
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| `claude` is running | Work still in progress | Proceed to next wait-for |
+| Returned to `zsh`/`bash` | Completed but signal failed | Check report manually |
+| Pane has disappeared | Abnormal termination | Record in concerns |
+
+## Report Files
+
+```
+.claude/tasks/reports/
+├── worker-{N}-{subtask_id}.yaml         # Basic report written by launch-worker.sh (guaranteed)
+└── worker-{N}-{subtask_id}-detail.yaml  # Detail written by Worker (optional)
+```
+
+### Basic report format
+
+```yaml
+issue: 42
+subtask_id: impl-1
+role: worker-coder
+status: completed  # completed | failed
+exit_code: 0
+branch: feat/issue-42
+timestamp: "2026-03-02T12:00:00Z"
+```
+
+## Quality Evaluation Rules
+
+Read Worker reports and evaluate quality:
+
+### Evaluation flow
+
+1. Read the basic report (`worker-{N}-{subtask_id}.yaml`)
+2. Read the detail report (`worker-{N}-{subtask_id}-detail.yaml`) if it exists
+3. Determine based on the following rules:
+
+| Condition | Verdict | Action |
+|-----------|---------|--------|
+| `exit_code != 0` | NG | Restart (up to 2 times) |
+| No detail report + exit_code == 0 | Warning | Record in concerns, continue |
+| Detail report does not cover required content | NG | Restart (up to 2 times) |
+| Still failing after 2 restarts | Give up | Record in concerns and continue |
+| `exit_code == 0` and content is sufficient | OK | Proceed to next subtask |
+
+### Restart procedure
+
+1. Modify the original prompt file (append previous failure information)
+2. Relaunch with the same `launch-worker.sh` command
+3. Wait again
+
+```markdown
+# Append previous execution results
+## Previous Failure
+- exit_code: {code}
+- Problem: {description of the problem}
+
+## Fix Instructions
+{what needs to be fixed}
+```
+
+## Subtask Group Execution Patterns
+
+### Parallel execution (independent subtasks)
+
+Launch subtasks that do not depend on each other simultaneously:
+
+```bash
+# Write prompt files first
+# Write worker-42-impl-api.md
+# Write worker-42-impl-ui.md
+
+# Launch in parallel
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-coder 42 impl-api feat/issue-42
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-coder 42 impl-ui feat/issue-42
+
+# Wait for 2 Workers
+EXPECTED=2
+RECEIVED=0
+while [ $RECEIVED -lt $EXPECTED ]; do
+  (sleep 600 && tmux wait-for -S leader-42-wake) &
+  TIMER_PID=$!
+  tmux wait-for leader-42-wake
+  kill $TIMER_PID 2>/dev/null
+  RECEIVED=$((RECEIVED + 1))
+done
+
+# Read both reports and evaluate quality
+```
+
+### Sequential execution (dependent subtasks)
+
+When a subtask depends on the output of a previous one:
+
+```bash
+# Phase 1: Implementation
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-coder 42 impl-1 feat/issue-42
+# Wait + quality evaluation
+
+# Phase 2: Tests (after implementation)
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-tester 42 test-1 feat/issue-42
+# Wait + quality evaluation
+
+# Phase 3: PR creation (after all complete)
+bash $BO_SCRIPTS_DIR/launch-worker.sh worker-coder 42 pr feat/issue-42
+# Wait + quality evaluation
+```
+
+### Mixed pattern
+
+```
+Phase 1: [worker-coder:impl-api, worker-coder:impl-ui]  ← parallel
+Phase 2: [worker-tester:test-1]                          ← sequential
+Phase 3: [worker-coder:pr]                               ← sequential
+```
+
+## Important Notes
+
+- Workers share the Leader's worktree, so do not launch Workers in parallel if they edit the same files
+- Review Workers are read-only and safe to launch in parallel
+- subtask_id can be any string, but must be unique within the same issue (no duplicates allowed)