start-work

name	start-work
description	Start implementation work with worktree isolation and cross-session file conflict avoidance. Use this skill when beginning any non-trivial code change: after planning, when creating a new branch, implementing features, fixing bugs across multiple files, or refactoring. Also use when the user mentions worktree, bit issue, session coordination, or parallel work.

Overview

pi fork of the Claude Code start-work skill. Declare work scope and Target Files via bit issue + git worktree so that parallel agent sessions (pi, Claude Code, and codex alike — they share the same bit issue store) can see each other's file ownership and avoid conflicts.

Every session working in a worktree creates a bit issue listing its Target Files. Since all worktrees share the same .git, any worktree can instantly read any other session's issues.

bit issue works transparently from any worktree.

Session Lifecycle

 worktree_create tool     bit issue create
 ┌──────────┐          ┌──────────────┐
 │ worktree │─────────►│ issue create │
 │  create  │          │ (Target decl)│
 └──────────┘          └──────┬───────┘
                              │
                    issue list (race check)
                              │
                       ┌──────▼───────┐
                  ┌───►│   working    │◄───┐
                  │    └──────┬───────┘    │
                  │           │            │
            scope change   pre-close    overlap
            (re-run §3)    (issue list) → adjust
                  │           │            │
                  └───────────┤            │
                              │
                    task_completed tool (per task)
                              │
                       ┌──────▼───────┐
                       │ parent close │
                       └──────┬───────┘
                              │
                    worktree_remove tool (user-approved)

0. Prerequisites

Worktree lifecycle is managed by pi-harness tools

Worktree creation/removal is handled by the pi-harness worktree_create / worktree_remove tools — never run gwq commands directly.

Tool	Contract
worktree_create	{name: <branch>} → creates a validated linked worktree (gwq) and returns its absolute path
worktree_remove	{path: <abs>, confirmed: true} — set confirmed ONLY after the USER explicitly approved; refuses dirty trees

pi has no "enter worktree" concept: after worktree_create, run subsequent bash commands with the worktree as the working directory (cd <worktree> && …).

After worktree creation, install dependencies based on the lock file:

if [ -f "bun.lock" ] || [ -f "bun.lockb" ]; then bun install
elif [ -f "pnpm-lock.yaml" ]; then pnpm install
fi

CRITICAL: Prohibited commands

These commands communicate via the bit relay server. Running them on a private repo leaks repository content externally. Never execute them.

Prohibited	Reason
bit issue claim / unclaim / claims / watch	relay-based exclusive control
bit issue import / bit pr import	GitHub API access
bit relay serve / bit relay sync	relay publishing
bit clone relay+*	relay-based clone

The pi-harness permission policy also denies them.

Allowed commands (local only)

bit issue init / create / list / view / update / close / reopen / comment add / comment list / search

Project memory is feature-owned

The pi-harness project-memory feature performs bounded aggregate startup recall for trusted repositories. start-work must not repeat that recall or turn it into a per-branch setup step.

Bit issues remain authoritative for the session plan, Target Files, task progress, decisions, and blockers. Durable project knowledge is a separate concern handled through the structured memory_recall / memory_update tools and the project-memory skill. Never access bit notes or git notes directly, and never add a memory consolidation step to this lifecycle: managed session/writer refs remain readable through aggregate recall.

1. Decide: New Session or Resume

bit issue list --open

• Open session exists for this branch → go to Resume Session
• No existing session → continue to §2

2. Read the Plan File

Worktrees have isolated filesystems. Plan files are .gitignored, so git show won't work. Read from the main repo's absolute path.

1. If the plan file path is still in the session context, use it directly
2. Otherwise, find the latest file in the plans directory (default: ./plans) relative to the main repo

ls -t <main-repo-path>/plans/*.md 2>/dev/null | head -1

If no plan file exists (minor work without a plan), omit the Plan section from the issue body.

Important: Read the plan file before switching to the worktree directory; afterwards you can still access it via the main repo's absolute path.

3. Work Declaration Protocol

pi has no built-in task list. Assign task ids yourself as sequential integers (1..N) unique within this session and embed them in the bit issue titles. The task_completed tool later uses the same id to close the issue.

Assign a sequence number

Count all issues (not just open) with the session label to avoid reuse after close/reopen cycles:

bit issue list --all --label "session:<branch-name>"
# → N issues found → next seq = N+1

Create parent issue (plan)

Create a single parent issue containing the full plan. This serves as the root for all task issues in this session.

bit issue create \
  --title "[plan:<branch-name>#<seq>] <plan title in English>" \
  --label "session:<branch-name>" \
  --body "$(cat <<'BODY'
## Session Info

- **branch**: <branch-name>
- **worktree**: <worktree-absolute-path>
- **main repo**: <main-repo-absolute-path>

## Plan

<full plan file content>
BODY
)"

Note the returned issue ID — all task issues reference it as their parent.

Create task issues (one per task, all upfront)

For each task in the plan, pick the next task id, then create a bit issue linked to the parent. Create all task issues before starting work.

# Repeat for each task in the plan
bit issue create \
  --title "[task:<branch-name>#<seq>:<task_id>] <task summary in English>" \
  --label "session:<branch-name>" \
  --body "$(cat <<'BODY'
parent: #<parent_issue_id>

## Target Files

- path/to/file.ts (modify|create|delete)

## Task Description

<task description>
BODY
)"

Including <branch-name> and #<seq> in the title prevents collision when multiple sessions have the same sequential task_id.

Why create a parent issue? It groups all tasks under one plan, making it easy to see the full scope of a session. On resume, reading the parent issue restores the complete plan context.

Why create all task issues upfront? Other sessions need to see the full scope of your work across all phases to avoid conflicts. Creating issues only for the current phase causes false "no overlap" results for later phases.

Why use absolute paths for worktree? Needed for orphan detection and as the working-directory target on session resume.

4. Cross-Session Awareness Protocol

Check other sessions' Target Files at these three points:

1. After issue create: Run bit issue list --open immediately (race condition mitigation — two sessions creating issues simultaneously may both see "no overlap")
2. On scope change: When you need to modify files not in your original Target Files
3. Before close: Final check before completing

For each open issue other than your own, view it and extract Target Files from the body. Only consider modify and delete operations for overlap — create files are unowned by definition.

bit issue list --open
bit issue view <other-session-id>

5. Overlap Detection & Autonomous Adjustment

Decision Matrix

overlapping = my modify/delete files ∩ other modify/delete files
remaining   = my total targets - overlapping files

- 0 overlapping:              proceed
- some overlapping, remaining > 0: exclude overlapping files, update issue body + add comment
- all modify/delete files overlap:  ask user whether to proceed with exclusions or abort

Dynamic Target Files Update

When excluding or adding files, update the issue body to keep Target Files authoritative, then add a comment for audit trail:

• Files owned by another session → exclude from issue body, find alternative approach

bit issue view <id>                      # read current body
bit issue update <id> --body "<revised body with excluded files removed>"
bit issue comment add <id> --body "Excluded path/to/file.ts (owned by session X)"

• Files owned by nobody → add to issue body, record in comment

bit issue view <id>                      # read current body
bit issue update <id> --body "<revised body with new file added>"
bit issue comment add <id> --body "Target added: path/to/new-file.ts (modify) - reason: ..."

6. Resume Session

1. Find the Session

bit issue list --open --label "session:<branch-name>"
# or
bit issue list --open

2. Restore Context

bit issue view <id>              # plan + target files
bit issue comment list <id>      # scope changes + progress

The issue body contains the canonical Target Files and plan. Comments track scope changes and progress.

3. Continue

Resume work using the restored context. The issue body is the source of truth for current Target Files.

4. Clean Up Orphans

If a session is abandoned with no committed work:

bit issue comment add <id> --body "Orphan: session abandoned"
bit issue close <id>

Use bit issue list --all to find both open and closed sessions.

7. Completion Protocol

Close task issues before removing the worktree. Reversing this order creates orphan issues (issue stays open but its worktree is gone).

Proactive durable-memory checkpoint

Before closing each task, creating or materially updating a pull request, closing the parent plan, pausing work, or ending the session, the main parent agent MUST evaluate whether the completed work produced a verified durable fact, decision, constraint, reusable feedback item, or stable reference. Do not wait for an explicit user request.

Follow the project-memory recall-before-put workflow. A no-candidate or already-represented result is a valid no-op. When a candidate clearly meets the criteria, promote it through memory_update without asking merely for confirmation; uncertainty requires verification or no write. Memory unavailability does not block task/issue completion. Children only return a proposed path, description, distilled content, and evidence to the parent.

Task issue close

MUST: When each task completes, immediately call the task_completed tool with the task's id:

task done → task_completed {task_id: "<task_id>", task_subject: "<summary>"}

The tool runs the bit issue close hook for the matching [task:<branch>#<seq>:<task_id>] title and then verifies the issue is actually closed (fail-closed; verification is skipped only when the bit executable is unavailable). If the tool reports failure, fall back to manual close:

bit issue comment add <id> --body "Done: <summary of changes>"
bit issue close <id>

Parent issue close

After all task issues are closed, close the parent plan issue, then ask the USER whether to remove the worktree. Only after explicit approval call:

worktree_remove {path: "<worktree-absolute-path>", confirmed: true}

The tool refuses dirty trees and verifies the removal afterwards.

There is no project-memory consolidation or branch-note cleanup step before closing the parent. The proactive checkpoint above promotes only genuinely durable items through the project-memory workflow; temporary session state stays in the issues.

8. Error Handling

Situation	Response
bit command fails	Notify user: "Coordination disabled — overlap detection is not working." Continue work.
bit not installed	Solo mode — notify user that coordination is skipped.
Orphan issue	Check gwq list for worktree existence. If no matching worktree, exclude from overlap detection.
Worktree trouble	gwq list (list all), gwq prune (clean stale refs), gwq status (check changes)

Cross-Model Stages (workflow tool)

For multi-agent fan-out on the work started here, use the pi-harness workflow tool. It takes a declarative plan and the engine enforces the cross-model ground rules in code. The call returns an acceptance/invocation ID immediately; do not synthesize that acceptance text. Continue only when the automatic background-completion message delivers the staged results to the parent:

• Fan-out stages default to codex agents; a stage whose roster has no codex-family task is rejected unless the USER explicitly opted out (codexSkip: true).
• codex-reviewer for read-only review/verification fan-outs.
• codex-poc for competing implementation PoCs — the engine REQUIRES isolation: "worktree" and provisions a dedicated linked worktree per task.
• codex-runner for write-capable parallel workers — parallel runners must declare disjoint writeScope paths (the engine rejects overlap).
• Created worktrees are never merged or removed automatically; results are reported and cleanup stays with you and the user.
• Claude-family tasks are optional additions (+α) alongside the codex baseline, never the roster by themselves. You (the parent agent) still orchestrate, synthesize, and judge.

Cross-model vs fresh-context. A codex-default fan-out gives true cross-model coverage only when the reviewer's model family differs from the author's — e.g. a Claude parent orchestrating codex reviewers, or a Claude +α lens over a codex PoC. When author and reviewer share a family (a codex parent with codex reviewers, or a Claude lens over Claude-authored work) the review is fresh-context: a new context window of the same family, which catches context/anchoring bias but NOT model-family blind spots. Child agents run on pi's global default model unless their frontmatter pins model:, so pin it on any agent whose family the coverage depends on, and say which kind of coverage a stage actually provided when you synthesize.

Example plan (review fan-out + a judge stage):

{
  "stages": [
    {
      "mode": "fanout",
      "tasks": [
        {
          "agentType": "codex-reviewer",
          "task": "Review the uncommitted diff for correctness bugs. Run: ~/.claude/hooks/lib/codex-stage.sh review --uncommitted --dir <repo>"
        },
        {
          "agentType": "codex-reviewer",
          "task": "Review the uncommitted diff for convention violations via codex prompt mode"
        }
      ]
    }
  ]
}

For ready-made plan shapes (review fan-out, competing codex PoCs, parallel codex-runner writes), read references/multi-model-workflows.md.

Worked Examples

For concrete workflow examples (solo session, parallel sessions without overlap, parallel sessions with overlap adjustment), read references/examples.md.

Commands Reference

bit issue create --title "..." --label "..." [--label "..."] --body "..."
bit issue list [--open] [--closed] [--all] [--label <name>] [--parent <id>]
bit issue view <id>
bit issue update <id> [--title "..."] [--body "..."] [--label "..."]
bit issue close <id>                     # idempotent
bit issue reopen <id>                    # idempotent
bit issue comment add <id> --body "..."
bit issue comment list <id>