razbakov/inbox

Inbox — Fire-and-Forget Agent Dispatch

Dispatch a background Claude agent to handle a task autonomously. You start it and walk away.

Process

1. Log raw input

Append to ~/Tasks/inbox.log with timestamp. This is the retry source of truth.

echo "$(date -Iseconds) | DISPATCHED | SLUG | PROJECT | RAW_INPUT" >> ~/Tasks/inbox.log

Every field matters — if the agent fails, the user can grep this log and re-dispatch.

2. Parse the task

From the user's raw input, determine:

• PROJECT: Which project from ~/Projects/ this belongs to. Infer from keywords (e.g. "wedance" → WeDance, "blog" → razbakov.com, "contact" → ikigai). If ambiguous, pick the most likely. If truly unknown, use ikigai.
• TASK: A short kebab-case slug (3-5 words max). E.g. "fix-login-bug", "add-carousel-post", "update-readme".
• PROMPT: The full task description to give the agent. Include enough context for it to work autonomously. Reference the project's README/CLAUDE.md for conventions.

3. Create worktree

TASK_DIR=~/Tasks/${PROJECT}-${TASK}
git -C ~/Projects/${PROJECT} worktree add ${TASK_DIR} -b agent/${TASK} main

If the worktree already exists (same slug), append a number: ${TASK}-2, ${TASK}-3.

If the project has no git repo, just create a plain directory:

mkdir -p ${TASK_DIR}
cp -r ~/Projects/${PROJECT}/ ${TASK_DIR}/

4. Install dependencies (if applicable)

Check if the project has package.json, bun.lockb, or node_modules:

# Only if package.json exists in the worktree
cd ${TASK_DIR} && bun install --frozen-lockfile 2>/dev/null || npm ci 2>/dev/null || true

Skip this step for non-JS projects or projects without package.json.

5. Create GitHub issue (Control Center tracking)

Every agent must have a tracking issue. Create one before launching.

Pick the target repo: use the repo that matches ${PROJECT} (see the Project Path Registry in the org CLAUDE.md). If the project has no GitHub repo, default to razbakov/ikigai.

Pick the agent label: based on the task domain, choose one of agent:maya, agent:viktor, agent:luna, agent:marco, agent:sage, agent:kai.

REPO=<owner/repo for ${PROJECT}>
AGENT_LABEL=<agent:xxx>

ISSUE_URL=$(gh issue create --repo "$REPO" \
  --title "<TASK title>" \
  --label "$AGENT_LABEL" \
  --body "$(cat <<'EOF'
## S3 Analysis

### Tension
<1-2 sentences>

### Driver
| Conditions | Effect | Relevance |
|------------|--------|-----------|
| <facts> | <consequences> | <why it matters> |

### Requirement
> <who needs what so that what>

### Response Options
- [ ] <option A>
- [ ] <option B>
- [ ] <defer/skip>

---

**Agent:** tmux wf-${TASK}
**Worktree:** ${TASK_DIR}
EOF
)")

# Add to the Ikigai Control Center Project v2 board
gh project item-add 5 --owner razbakov --url "$ISSUE_URL"

Save $ISSUE_URL — it goes into the agent prompt file so the agent can reference and close it.

6. Write prompt file

Write the full prompt to ${TASK_DIR}/agent-prompt.md. Include the GitHub issue URL so the agent can reference and close it. This is the raw input log for this specific task.

# Agent Task: ${TASK}

**Project:** ${PROJECT}
**Dispatched:** $(date -Iseconds)
**GitHub issue:** <ISSUE_URL>
**Raw input:** <exact user input, unedited>

## Instructions

<expanded prompt with context>

When done:
1. The PR created in the delivery checklist must reference this issue with `Closes #<N>` in the body — merging the PR auto-closes the issue and moves it to Done on the Project board.
2. If this task does NOT produce a PR (rare), comment on the issue with the result and close it manually: `gh issue close <N> --comment "<what was done, where to find it, next steps>"`.

The expanded prompt MUST always end with a delivery checklist. Agents that finish without a PR leave invisible work in worktrees.

For tasks implementing a GitHub issue:

### Delivery checklist
1. Run build/tests to verify no errors
2. Commit changes with a descriptive message referencing the issue (e.g. "Add hero image #11")
3. Push the branch: `git push -u origin agent/${TASK}`
4. Create a pull request: `gh pr create --title "<short title>" --body "<summary + Closes #N>"`
5. The PR body must include: a Summary section, a Test Plan section, and `Closes #<ISSUE_NUMBER>`

For all other tasks (research, skill creation, config changes, etc.):

### Delivery checklist
1. Commit all changes with a descriptive message
2. Push the branch: `git push -u origin agent/${TASK}`
3. Create a pull request: `gh pr create --title "<short title>" --body "<summary of what was done>"`

Every agent must deliver a reviewable PR, not just a local commit.

7. Launch in tmux

PROMPT=$(cat ${TASK_DIR}/agent-prompt.md)
SESSION_NAME="wf-${TASK}"

cat > /tmp/run-${TASK}.sh << SCRIPT
#!/bin/bash
cd ${TASK_DIR}
claude --permission-mode bypassPermissions --output-format stream-json --verbose -p "$(cat ${TASK_DIR}/agent-prompt.md)" \
  2>&1 | tee ${TASK_DIR}/agent.log
echo "EXIT_CODE=\$?" >> ${TASK_DIR}/agent.log
echo "AGENT_FINISHED=$(date -Iseconds)" >> ${TASK_DIR}/agent.log
bash
SCRIPT
chmod +x /tmp/run-${TASK}.sh

tmux new-session -d -s "${SESSION_NAME}" -c "${TASK_DIR}" "/tmp/run-${TASK}.sh"

8. Report and move on

Tell the user ONE line:

Agent dispatched: tmux attach -t ${SESSION_NAME}

Do NOT:

• Wait for the agent to finish
• Check if it started successfully
• Offer to monitor it
• Ask follow-up questions

Just dispatch and stop. The user will use /scrum to check later.

Important

• Never skip logging. The inbox.log and agent-prompt.md are the retry mechanism.
• Never wait. This is fire-and-forget.
• Never ask. Infer the project. Pick a slug. Dispatch.
• Always use tmux. The agent must survive terminal closure.
• Always log output. The agent.log via tee is how /scrum checks status.

Retry Pattern

If a task needs retry, the user will say /inbox: retry wf-TASK. In that case:

1. Read ~/Tasks/*/agent-prompt.md for the matching task
2. Check agent.log for what went wrong
3. Re-dispatch with adjusted prompt (mention the previous failure)
4. Use a new slug: ${TASK}-retry or ${TASK}-2