1017293270/claude-task-lines

Main Line and Side Lines: Coordinator's Manual

Working on a long task in a single conversation means it gets compressed repeatedly, and details are lost. This skill addresses that:

• Coordinator (the session that calls this skill): Understands requirements, scouts, splits into lines, writes briefs, spawns sessions, collects reports, merges, validates, and communicates with the user. The coordinator does not write large chunks of implementation, keeping context for the bigger picture. Minor conflict resolution and one- or two-line fixes can be done by the coordinator.
• Line: Each line is a side panel session working in its own worktree according to its brief, then sends a report back to the coordinator. The user can directly enter that session to chat with it.
• Ledger: ~/.claude/mods-data/task-lines/boards/<board id>/ – all details are stored here. Conversations get compressed, but the ledger does not. After compression, the task-lines plugin automatically puts the ledger back into context: the coordinator gets the latest parts of board.md and log.md, and each line gets its own brief and progress.

scripts/ below refers to the scripts folder under this skill's directory (shown as Base directory when loading this skill).

Getting Started

1. Create Ledger: Call task_board with title set to the short title of the task. Then use mcp__ccd_session_mgmt__get_session (with session_id set to self) to get the desktop session ID (starting with local_) of the current session, and write it into board.md. Lines use this ID to send reports to you.

2. Record Original Words: Paste the user's requirements verbatim into board.md under "User's Original Words". Do not paraphrase or summarize.

3. Scout: Read until the brief can be clearly written, including relevant code, documentation, and the project's CLAUDE.md. Understand the current state, relevant files, project conventions, and validation commands. Write conclusions under "Constraints and Decisions Made".

4. Split into Lines: Follow the rules under "How to Split" below, and write the results into the "Lines" table.

5. Take Baseline Snapshot: Run scripts/snapshot.sh <main directory> refs/task-lines/<board id>/base-1, and write the output commit ID into "Current Baseline". The snapshot includes uncommitted changes and untracked files in the main directory, but does not touch the staging area, HEAD, or branches.

6. Write Briefs: For each line that can start now, write lines/<line id>/brief.md following the template below.

7. Spawn Sessions: For each line, call mcp__ccd_session__spawn_task:

   • title: [L1] Short title starting with a verb, within 60 characters. The [line id] prefix is used later to find this session.
   • tldr: A sentence or two in plain language describing what this line does.
   • prompt: The full brief. The prompt must be self-contained and understandable without having to "go read the ledger".

   Each line will appear as a card that the user clicks to open the session. New sessions get their own independent worktree.

8. Tell the User: Explain which lines were created, what each does, which can start now, and which must wait until previous lines are merged. Ask the user to click the cards. Start work immediately after splitting; do not wait for the user to approve the plan. The user can stop or change things at any time.

9. Log: Use task_note to record a note.

How to Split

• Main line is the trunk of the task. A very long main line is cut into phases L1, L2, etc. Each phase opens a new session starting from the latest baseline. Each session has only the context of one phase – this is key to preventing detail loss.
  • Phases are serial: after a previous phase is merged and validated, take a new baseline, write the next phase's brief (including handoff from the previous phase).
• Side lines are relatively independent pieces of work, such as another module, utility scripts, tests, or research. Side lines can run in parallel with the main line, and are numbered S1, S2, etc.
• Size of a line: A session that can be completed from start to finish without being compressed multiple times. When in doubt, make it smaller.
• Lines running in parallel should avoid modifying the same files: Worktrees only isolate runtime environments; if they touch the same area, conflicts will need resolution during merge.
  • Agree on shared interfaces (function signatures, data formats, file paths) before starting work, and write the exact text into each relevant brief.
• How many to open at once: Typically 2–3. Each line may request permissions or ask questions from the user; too many lines and the user becomes overwhelmed.
• Don't split what doesn't need splitting: If a task can be completed smoothly in one session, just do it directly without opening a ledger.

Brief Template

Content inside angle brackets is filled by the coordinator. If a section is not applicable, write "None" – do not delete it.

# [<line id>] <Title>

You are a line in task board <board id>, and the coordinator is another session. Follow the instructions below, and send the report back to the coordinator when done.

## Before Starting
1. Call task_line_attach with board set to "<board id>" and line set to "<line id>". This tool is from the task-lines plugin; if the tool is not available, skip this step and mention it in the report.
2. Confirm you are in your own worktree: the output of `git rev-parse --show-toplevel` must NOT be <main directory>. If it is, stop and tell the user.
3. Align with the baseline: First confirm `git status --porcelain` is empty, then run `git reset --hard <baseline commit>`. The baseline includes uncommitted changes from the main directory; without aligning, your changes cannot be merged back.
4. Set up environment: <e.g., pnpm install. The worktree has no node_modules; Rust's target directory is also empty, so the first build may be slower>

## Background & Goal
<User's original words relevant to this line, quoted verbatim; what the line should look like when done; why it's being done>

## Known Facts
<Scouting conclusions: relevant files and line numbers, current status, project conventions, existing patterns to follow, decisions already made>

## Scope
- Can modify: <files or directories>
- Do not touch: <files or directories>
- Other lines running in parallel: <line id: which files they are modifying>
- Never touch the main directory <path>. Only modify within your own worktree.

## Interface Contracts
<Signatures and formats shared with other lines, quoted verbatim>

## Validation
<Specific commands: tests, type checking, build, actual run. For UI-related tasks, take screenshots and review visually>

## Discipline
- You may commit to your own branch for archival, but do not push or touch other branches.
- Follow the conventions in the project's CLAUDE.md.
- Record key decisions, findings, and progress using task_note. After the conversation is compressed, you will rely on it to continue.
- If the user makes new requests directly in this session, fulfill them and also relay the exact original words to the coordinator in your report.
- For decisions requiring the coordinator or user, or tasks outside scope: first record with task_note, then send a message asking the coordinator — do not expand scope on your own.

## Completion
Use SendMessage to send a message to the coordinator, with `to` set to "<coordinator's desktop session ID>". If SendMessage is unavailable, use mcp__ccd_session_mgmt__send_message with the same session_id.
The first line must be "[<line id>] Completed: <one sentence>", followed in order by:
- Worktree path (output of `git rev-parse --show-toplevel`) and branch name
- What was changed (per file), why those changes were made, and any trade-offs you considered
- Validation: which commands were run, and the actual results. If tests failed, say so.
- Remaining issues and matters requiring the coordinator or user to decide
- New requests made by the user in this session (original words)

Also record the same report using task_note. After sending, stop and wait for the coordinator's response — they may ask you to rework.

While Lines Are Running

• Do not poll. Lines will send a message when they finish, which appears as a message from that session.
• Check progress: When the user asks about progress, use mcp__ccd_session_mgmt__list_sessions to find sessions by the title prefix [line id], and mcp__ccd_session_mgmt__list_events to see what they've been doing recently. Record found session IDs in the lines table.
• Line asks a question: If you can decide, reply directly to that session and log it in the ledger. If the user needs to decide, forward the question to the user.
• User makes a new request in the main conversation: First append it verbatim to "User's Original Words" in board.md with a timestamp. Then assess which lines are affected: either send a message to that line, or defer it to the next phase.
• Line gets stuck or goes off track: Send a message to correct it.

Receiving and Merging (for every line)

1. Dry run: First read the report, then run: scripts/merge-line.sh --check <main directory> <this line's baseline> <line's worktree path>. This will list files to be updated, three-way merged, added, deleted, and which will conflict. The last line gives a command to view the full diff of the line.

2. Review:

   • Are there changes to files outside scope?
   • Is the logic correct, and does it resemble existing code in the project?
   • Are there any leftover or unnecessary items?
   • Do comments and text follow project conventions?

   If it fails, ask the line to rework, explaining clearly what is wrong and what should be changed. After rework, repeat from step 1.

3. Merge: Run scripts/merge-line.sh <main directory> <baseline> <line's worktree path>. This only modifies files in the main directory's working tree; it does not touch the staging area, HEAD, or branches.

   • If there are conflicts, conflict markers (<<<<<<< Current to >>>>>>> Line) will be present in the files. If conflicts are few, resolve them yourself. If they are numerous or unclear, stop and inform the user to decide together.
   • If the script refuses to merge (exit code 2 with message "Not starting from baseline"): the line did not align with the baseline when starting. Ask the line what happened, and do not force the merge.

4. Validate: Run full checks in the main directory, including project tests, type checking, and build. The script only does file-level merging; the merge is not complete without validation.

5. Update Ledger: Change the line's status in the lines table to "Merged". Under "Merge Records", add: timestamp, line, baseline, snapshot ID, merge result (how conflicts were resolved), and validation result.

6. Inform the user: Tell them what this line contributed. Let the user decide whether to commit. If the user does not ask, do not commit. If they do, commit according to the project's commit conventions.

7. Line's session: After merging and when the user no longer needs to revisit it, ask the user if they want to archive the session (mcp__ccd_session_mgmt__archive_session). Do not delete the worktree yourself.

Next Phase

For the next phase of the main line, or for side lines that depend on a merged line, follow this order:

1. Take a new baseline: scripts/snapshot.sh <main directory> refs/task-lines/<board id>/base-<n>.
2. Update "Current Baseline" in board.md.
3. Write the brief, specifying the new baseline and the handoff from the previous phase: what was done, what remains, and what to watch out for.
4. Open new cards.

Existing lines still running continue to use their own baselines. The merge script performs three-way merges based on each line's individual baseline, without interference.

After Compression

The task-lines plugin puts the recent parts of board.md and log.md back into context. Before continuing:

1. Cross-reference the ledger's lines table, use list_sessions to find each line's session (by the title prefix [line id]), and use list_events to see their current status.
2. If anything from the summary is not yet in the ledger (new decisions, new user requests), add it to the ledger first.
3. Then proceed.

If the summary and ledger disagree, trust the ledger and actual state; check session records and git for the real status.

How to Keep the Ledger

• board.md is the master ledger: User's original words, goals, constraints, decisions made, lines table, merge records, and items awaiting user decisions. Edit this file directly so it always reflects the current real state.
• log.md is the running log: Append entries with task_note recording decisions made, reports received, merge results, etc.
• Update after every milestone: After splitting lines, opening cards, receiving reports, merging, or user changing requirements. If the ledger falls behind the conversation, details are lost upon compression.
• Never write keys, passwords, or tokens in the ledger.

Handing Over to Another Coordinator Session

If the original coordinator session gets too long, you can start a new session to take over:

1. Call task_board with board set to the board ID.
2. Follow the "After Compression" section to reconcile.
3. Lines currently send reports using the original coordinator's session ID. Update the session ID in board.md to the new session's ID, and send a message to each running line telling them where to send reports from now on.

Pitfalls to Watch For

• Lines can only be spawned in projects that the user has opened in the desktop client. If Claude creates a new repo in scratchpad or any other session-writable directory, the desktop client refuses to create a worktree for security reasons, and clicking the card will only show "Couldn't start the suggested task." Set cwd in spawn_task to empty (defaults to the current project) or to a project path the user has opened.
• When a card fails to open, Claude gets no notification; you rely on the user to tell you. The cause is in the desktop client log ~/Library/Logs/Claude/main.log, search for createWorktree or Worktree creation failed.
• Worktrees in line sessions have no ignored directories, such as node_modules or Rust's target. The brief's "Set up environment" section must clearly state how to restore them.
• Baseline snapshots are stored under refs/task-lines/<board id>/ and do not appear in any branch list. After the entire task is done, use git for-each-ref refs/task-lines/<board id> to list them and git update-ref -d to delete them, but ask the user first.
• When two sessions have different permission modes, messages between them require user approval. Remind the user when opening lines.
• merge-line.sh handles text files and regular files. Symbolic links and binary files modified by both sides will be listed as "requires manual handling."

Wrapping Up

After all lines are merged and full validation passes:

1. Mark board.md as "Completed".
2. Report to the user: what each line did, merge results, validation results, remaining issues, and items awaiting user decisions.
3. Ask the user whether to archive each line's session and whether to clean up the baseline snapshots.