Blitz

The Blitz: Parallel Worktree + Agent Workflow

Parallelizes multi-issue sprints by running independent agents in isolated git worktrees. Each agent implements their issue, self-reviews to 10/10 with 100% issue coverage, then changes are sequentially merged to avoid conflicts. Herding 🐲.

Platform-agnostic. Works with GitHub (gh CLI), Forgejo (API/tea CLI), or local tk tickets.

See skills/obsidian-plan-wiki/references/platform-detection.md for detection rules and command mapping.

⚠️ MANDATORY: 100% Issue Coverage Per Agent

Every agent MUST implement 100% of their assigned issue's requirements before their PR can be merged.

• Each agent receives COMPLETE issue requirements (extracted from issue/task)
• Review must verify ALL requirements are implemented
• Coverage < 100% = agent sent back to complete the work
• No PR merges until all requirements from the issue are addressed

Prerequisites

Required Tools:

• Platform CLI — gh for GitHub, tea/API for Forgejo, or tk for local tickets
• Git with worktree support (2.5+)
• teams tool for parallel worker delegation

Required Skills:

• 4-step-program - Guides agents through fix-review-iterate-present loop
• code-reviewer - Self-review to 10/10 quality gate
• delphi - Parallel oracles for triage decisions (optional, for ambiguous triage)

Workflow Phases

Phase 1: Issue Triage

For ambiguous decisions on which issues to tackle, use the delphi skill:

Invoke Delphi: "Audit these open issues. For each, recommend: close (complete), fix (actionable), or defer (blocked)."

Interpreting Delphi Results:

• Unanimous agreement → Act on recommendation
• 2/3 agreement → Lean toward majority, investigate minority view
• Full divergence → Need more context; investigate manually

Close complete issues immediately:

• GitHub: gh issue close 1 2 3 --comment "Complete per Delphi audit"
• Forgejo: Forgejo API PATCH /repos/{owner}/{repo}/issues/{index} with "state": "closed"
• Local tk: tk close <id> for each completed task

For clear-cut issue lists, skip Delphi and proceed directly to Phase 2.

Phase 2: Worktree Setup

Create one worktree per fixable issue from main:

git worktree add .worktrees/<slug> -b fix/<slug> main

Branch Naming: fix/<descriptive-slug> or feat/<descriptive-slug>

Example setup for 4 issues:

git worktree add .worktrees/test-isolation -b fix/test-isolation main
git worktree add .worktrees/config-theater -b fix/config-theater main
git worktree add .worktrees/wire-salience -b fix/wire-salience main
git worktree add .worktrees/testing-quality -b fix/testing-quality main

Why Worktrees:

• Complete filesystem isolation per agent
• No stash/checkout conflicts
• Agents work truly in parallel
• Each has independent node_modules, build artifacts

Phase 3: Delegate to Parallel Agents

Delegate to workers using teams. Each worker needs:

1. Working directory (absolute path to worktree) 2. Issue context (number, description, acceptance criteria) 3. COMPLETE list of ALL requirements from the issue (extracted via platform — see above) 4. Explicit instruction to use 4-step-program skill

CRITICAL: Before delegating, extract ALL requirements from each issue:

• GitHub: gh issue view <number>
• Forgejo: tea issue view <number> or Forgejo API
• Local tk: tk show <id>

List EVERY requirement, acceptance criterion, and edge case in the agent prompt.

Agent Prompt Template (adapt to platform):

<details><summary><strong>GitHub variant</strong></summary>

Working directory: /absolute/path/to/.worktrees/<slug>
Issue: #<number> - <title>

**ALL REQUIREMENTS FROM ISSUE (100% must be implemented):**
1. [Requirement 1 from issue]
2. [Requirement 2 from issue]
3. [Requirement 3 from issue]
... (list ALL of them)

Use the 4-step-program skill to:
1. Implement ALL the above requirements (100% coverage required)
2. Run tests, verify passing
3. Create PR with `gh pr create` — **MUST include `Closes #<issue-number>` in body**
4. Self-review using code-reviewer skill (which will verify 100% coverage)
5. POST review to GitHub with `gh api`

**PR MUST include:**
- `Closes #<issue-number>` to auto-close the issue on merge
- "Related Issues" section in PR body
- Verify with `gh pr view --json closingIssuesReferences`

Do not return until you achieve 10/10 review score WITH 100% of issue requirements implemented AND issue properly linked.

</details>

<details><summary><strong>Forgejo variant</strong></summary>

Working directory: /absolute/path/to/.worktrees/<slug>
Issue: #<number> - <title>

**ALL REQUIREMENTS FROM ISSUE (100% must be implemented):**
1. [Requirement 1 from issue]
2. [Requirement 2 from issue]
3. [Requirement 3 from issue]
... (list ALL of them)

Use the 4-step-program skill to:
1. Implement ALL the above requirements (100% coverage required)
2. Run tests, verify passing
3. Create PR with Forgejo API or `tea pr create` — **MUST include `Closes #<issue-number>` in body**
4. Self-review using code-reviewer skill (which will verify 100% coverage)
5. POST review to Forgejo via API

**PR MUST include:**
- `Closes #<issue-number>` to auto-close the issue on merge
- "Related Issues" section in PR body

Do not return until you achieve 10/10 review score WITH 100% of issue requirements implemented AND issue properly linked.

</details>

<details><summary><strong>Local tk variant</strong></summary>

Working directory: /absolute/path/to/.worktrees/<slug>
Task: <tk-id> - <title>

**ALL REQUIREMENTS FROM TASK (100% must be implemented):**
1. [Requirement 1 from task]
2. [Requirement 2 from task]
3. [Requirement 3 from task]
... (list ALL of them)

Use the 4-step-program skill to:
1. Implement ALL the above requirements (100% coverage required)
2. Run tests, verify passing
3. Commit all changes — no PR needed, merge happens locally
4. Self-review using code-reviewer skill (which will verify 100% coverage)
5. Post review as a ticket: `todos_oneshot(title: "Review: <branch>", tags: "review")`

Do not return until you achieve 10/10 review score WITH 100% of task requirements implemented.

</details>

CRITICAL: Agents must POST reviews to the platform, not just print them:

• GitHub: gh api repos/OWNER/REPO/pulls/NUMBER/reviews -f body="..." -f event="COMMENT"
• Forgejo: POST /repos/{owner}/{repo}/pulls/{index}/reviews via Forgejo API
• Local tk: todos_oneshot(title: "Review: <branch>", tags: "review") — review lives as a ticket

Launch workers in parallel using teams:

teams(action: 'delegate', tasks: [
  {text: '<agent prompt for issue 1>', assignee: 'fix-issue-1'},
  {text: '<agent prompt for issue 2>', assignee: 'fix-issue-2'},
  {text: '<agent prompt for issue 3>', assignee: 'fix-issue-3'}
])

Phase 4: Review Iteration Loop

Monitor each PR/branch review status:

• GitHub: gh pr view <NUMBER> --json reviews --jq '.reviews[-1].body'
• Forgejo: Forgejo API GET /repos/{owner}/{repo}/pulls/{index}/reviews
• Local tk: tk show <review-ticket-id> — check review ticket notes

TWO gates must pass for each PR:

GATE 1: 100% Issue Coverage

• Verify ALL requirements from original issue are implemented
• If ANY requirement is missing → Resume agent with missing requirements

GATE 2: 10/10 Review Quality

• Zero suggestions in review
• All verification commands pass

If coverage < 100%: Resume the agent with specific missing requirements:

PR #<NUMBER> coverage: 80% (4 of 5 requirements).
Missing requirement: [Requirement 5 from issue - specific text]
Implement this requirement and re-review.

If score < 10/10 (but coverage 100%): Resume the agent with specific feedback:

PR #<NUMBER> has 100% coverage but scored 8/10. Issues:
- <specific issue 1>
- <specific issue 2>

Fix these issues and re-review.

10/10 + 100% Coverage Criteria:

• ALL requirements from original issue implemented
• All functionality working
• Tests pass
• No obvious bugs or security issues
• Code follows project conventions
• Documentation updated if needed

Phase 4.5: FINAL COVERAGE GATE (Before Merge)

MANDATORY: Before merging ANY PR, perform LINE-BY-LINE requirement verification.

For EACH PR ready to merge:

Step 1: Extract ALL Requirements

GitHub:

gh issue view <issue-number> --json body --jq '.body' | grep -E "^\- \["
gh issue view <issue-number>

Forgejo:

# Via Forgejo API: GET /repos/{owner}/{repo}/issues/{index}
tea issue view <issue-number>

Local tk:

tk show <task-id>

Step 2: Create Line-by-Line Table

MANDATORY for each PR:

## Issue #X - Full Requirements Check

| Requirement | PR Status | Evidence |
|-------------|-----------|----------|
| [exact text from issue] | ✅ | `file.cs:line` - [implementation] |
| [exact text from issue] | ❌ MISSING | Not found in PR |
| [exact text from issue] | ⚠️ PARTIAL | `file.cs:line` - [what's missing] |
| [exact text from issue] | ⚠️ MANUAL | Requires Unity Editor |

Step 3: Honest Assessment

**Honest Assessment**:
- Coverage: X% (Y of Z requirements fully implemented)
- Missing: [list specific items]
- Partial: [list items and what's missing]
- Manual: [list items needing editor/runtime]

FINAL GATE DECISION:

If Final Coverage < 100%:

Resume agent: "FINAL COVERAGE GATE FAILED for PR #<NUMBER>.

Issue #X - Full Requirements Check:

| Requirement | Status | Evidence |
|-------------|--------|----------|
| MeshDeformer component created | ✅ | MeshDeformer.cs |
| Create scene GameObject | ❌ MISSING | No scene modification |
| Cache hit rate >90% | ⚠️ MANUAL | Requires runtime profiler |

Honest Assessment:
- Coverage: 85% (11 of 13 requirements)
- Missing: scene GameObject creation
- Partial: none
- Manual: cache hit rate verification

Implement ALL items marked ❌. Items marked ⚠️ MANUAL that CAN be automated via mcp-unity MUST be automated.

Do not return until 100% coverage."

→ Loop back to Phase 4 (Review Iteration)

Phase 5: Sequential Squash-Merge + Rebase

Merge PRs one at a time. Order by dependency (infrastructure first).

Before merging, verify issue linking:

• GitHub: gh pr view <NUMBER> --json closingIssuesReferences --jq '.closingIssuesReferences[].number' — if empty, send agent back to fix
• Forgejo: Check PR body for Closes #X keywords
• Local tk: tk show <id> — verify deps/links are set

For each PR/branch:

GitHub:

# 1. Squash merge — issues auto-close on merge
gh pr merge <NUMBER> --squash --delete-branch
# 2. Update local main
git checkout main && git pull
# 3. Rebase next PR onto updated main
cd .worktrees/<next-slug>
git fetch origin main
git rebase origin/main
git push --force-with-lease

Forgejo:

# 1. Merge via Forgejo API: POST /repos/{owner}/{repo}/pulls/{index}/merge
#    with "Do": "squash"
# 2-3. Same rebase workflow as above

Local tk:

# 1. Fast-forward merge locally
git checkout main
git merge --ff-only fix/<slug>
# 2. Close the task
tk close <task-id>
# 3. Rebase next branch onto updated main
cd .worktrees/<next-slug>
git rebase main

Why This Order:

• Squash merge (or ff-only for local) keeps main history linear
• Rebasing before merge prevents conflicts
• Sequential merging catches integration issues early
• --force-with-lease prevents overwriting others' work (remote platforms)

Handling Conflicts:

git rebase origin/main
# If conflicts:
# 1. Fix conflicts in affected files
# 2. git add <fixed-files>
# 3. git rebase --continue
# 4. git push --force-with-lease

Phase 6: Cleanup

After all branches merge:

# Remove worktrees
git worktree remove .worktrees/<slug>  # Repeat for each

# Delete local branches
git branch -D fix/<slug>  # Repeat for each

# Sync main (remote platforms only)
git checkout main && git pull

# Verify clean state
git worktree list  # Should show only main
git branch         # Should show only main

Quick Reference

See references/commands.md for complete command reference. See references/pitfalls.md for common issues and solutions.

Mermaid Diagrams in Blitz PRs

Each agent's PR/commit SHOULD include Mermaid diagrams when the change warrants visualization.

When Agents Should Add Diagrams

Agent Delegation Should Include

When delegating to agents, add to the prompt:

If your changes involve flow modifications, state changes, or API interactions,
include a Mermaid diagram in the PR body (or commit message / review ticket) showing the new behavior.

Example PR with Diagram

````markdown

Summary

Fixed race condition in WebSocket reconnection.

Before/After

flowchart LR
    subgraph Before
        A1[Disconnect] --> B1[Reconnect]
        B1 --> C1[Duplicate handlers]
    end
    subgraph After
        A2[Disconnect] --> B2[Cleanup handlers]
        B2 --> C2[Reconnect]
        C2 --> D2[Single handler]
    end

Related Issues

• Closes #45 - WebSocket reconnection bug

````

---

Checklist Summary

1. [ ] Triage issues (use delphi if ambiguous) 2. [ ] Extract ALL requirements from each issue (platform: gh issue view / tea issue view / tk show) 3. [ ] Create worktrees for each fixable issue 4. [ ] Launch parallel agents with 4-step-program including complete requirement lists 5. [ ] Monitor and iterate until all PRs/branches hit 100% issue coverage AND 10/10 6. [ ] FINAL COVERAGE GATE: Re-verify 100% coverage before each merge 7. [ ] Sequential merge with rebase between (only after gate passes) 8. [ ] Cleanup worktrees and branches 9. [ ] PRs/commits include Mermaid diagrams where helpful

Blitz Command Reference

Platform-agnostic. Commands vary by platform. See skills/obsidian-plan-wiki/references/platform-detection.md for detection rules.

Worktree Commands

# Create worktree with new branch from main
git worktree add .worktrees/NAME -b fix/NAME main

# List all worktrees
git worktree list

# Remove a worktree
git worktree remove .worktrees/NAME

# Clean stale worktree references (if manually deleted)
git worktree prune

Issue / Task Management

GitHub

gh issue close 1 2 3 --comment "Complete per audit"
gh issue view NUMBER
gh issue list --state open

Forgejo

tea issue view NUMBER
tea issue list
# Or via Forgejo API:
# PATCH /repos/{owner}/{repo}/issues/{index} — close
# GET /repos/{owner}/{repo}/issues/{index} — view

Local tk

tk close <id>
tk show <id>
tk ls

PR / Merge Commands

GitHub

# Create PR from current branch
gh pr create --title "TITLE" --body "BODY"

# View PR with reviews
gh pr view NUMBER --json reviews

# Get last review body
gh pr view NUMBER --json reviews --jq '.reviews[-1].body'

# Post review
gh api repos/OWNER/REPO/pulls/NUMBER/reviews \
  -f body="REVIEW_CONTENT" -f event="COMMENT"

# Squash merge and delete branch
gh pr merge NUMBER --squash --delete-branch

Forgejo

# Create PR
tea pr create --title "TITLE" --description "BODY"
# Or via API: POST /repos/{owner}/{repo}/pulls

# View PR reviews
# GET /repos/{owner}/{repo}/pulls/{index}/reviews

# Post review
# POST /repos/{owner}/{repo}/pulls/{index}/reviews

# Merge PR
# POST /repos/{owner}/{repo}/pulls/{index}/merge with "Do": "squash"

Local tk

# No PRs — merge locally
git checkout main
git merge --ff-only fix/NAME

# Post review as ticket
# todos_oneshot(title: "Review: <branch>", tags: "review")

# Close task after merge
tk close <id>

Rebase Workflow

# Fetch latest main
git fetch origin main

# Rebase current branch onto main
git rebase origin/main

# Force push after rebase (safe version — remote platforms only)
git push --force-with-lease

# If conflicts during rebase:
# 1. Fix conflicts
git add <fixed-files>
git rebase --continue
# Or abort:
git rebase --abort

Branch Cleanup

# Delete local branch
git branch -D fix/NAME

# Sync main after merges (remote platforms)
git checkout main && git pull

# Verify clean state
git worktree list
git branch

Process Monitoring

# Check for orphaned processes
ps aux | grep -E "(node|cargo|npm)"

# Kill specific process
kill <PID>

Blitz Pitfalls and Gotchas

Agent Resume Errors

Agents cannot resume after API disconnection. If an agent fails mid-task:

1. Check its worktree state:

   cd .worktrees/NAME && git status

2. Spawn fresh agent with context of what's already done 3. The new agent picks up from the current state

Reviews as Comments vs Formal Reviews

How agent-posted reviews work depends on the platform:

GitHub:

• gh api posts reviews as PR comments, not GitHub's formal review system
• Won't trigger "Changes requested" status or block merge via branch protection
• Fine for self-review workflow
• If formal reviews needed: use the GitHub web UI or different API endpoint

Forgejo:

• API-posted reviews behave similarly to GitHub
• Use POST /repos/{owner}/{repo}/pulls/{index}/reviews for formal reviews
• Comment-style reviews won't block merge

Local tk:

• Reviews are posted as tickets via todos_oneshot(title: "Review: <branch>", tags: "review")
• No merge protection — review is advisory
• Review ticket should be closed when agent achieves 10/10

Worktree Directory Confusion

Agents may drift to wrong directory during execution.

Prevention:

• Always specify absolute paths in prompts
• Verify with pwd in agent's first command
• Use cd /absolute/path && prefix for safety

Example prompt prefix:

Working directory: /Users/name/project/.worktrees/feature-x
First, verify: cd /Users/name/project/.worktrees/feature-x && pwd

Background Processes Accumulating

Long-running agents spawn background processes (dev servers, watchers, etc.).

Monitor with:

ps aux | grep -E "(node|cargo|npm)"

Clean up orphans after workflow completes.

Stale Worktree References

If worktree directory was deleted manually (rm -rf instead of git worktree remove):

git worktree prune  # Cleans stale references

Merge Conflicts During Rebase

When rebasing onto updated main causes conflicts:

# During rebase
git rebase origin/main

# If conflicts appear:
# 1. Open conflicted files, resolve conflicts
# 2. Stage resolved files
git add <resolved-files>

# 3. Continue rebase
git rebase --continue

# 4. Force push (safe)
git push --force-with-lease

If too messy: Abort and restart

git rebase --abort
git reset --hard origin/fix/NAME  # Reset to remote state

Agent Quality Loop Stuck

If an agent keeps scoring below 10/10 after multiple iterations:

1. Review the feedback being given - is it actionable? 2. Check if the issue is actually fixable (may need deferral) 3. Consider human intervention for complex edge cases 4. Document the blocker and move on

Worktree Already Exists

fatal: '.worktrees/NAME' already exists

Solutions:

• Use different slug name
• Remove existing: git worktree remove .worktrees/NAME
• Or prune if stale: git worktree prune

Branch Already Exists

fatal: a branch named 'fix/NAME' already exists

Solutions:

• Delete the branch: git branch -D fix/NAME
• Or use different branch name
• Check if work already exists on that branch