shep-kit:parallel-task

Parallel Task via Git Worktree

Create an isolated worktree in .worktrees/ branched from up-to-date main, with spec directory scaffolded.

When to Use

• Working on an independent task that doesn't block or depend on current work
• Need isolation from the current branch's in-progress changes
• Running long builds/tests while continuing other work

Workflow

digraph parallel_task {
    rankdir=TB;
    node [shape=box];

    start [label="Start" shape=ellipse];
    get_desc [label="User provides high-level\ntask description"];
    derive [label="Derive dir name, branch name,\nand feature name from description"];
    create_wt [label="create-worktree.sh\n<dir-name> <branch-name>"];
    install [label="pnpm install in worktree"];
    init_spec [label="Run init-feature.sh\ninside worktree"];
    fix_yaml [label="Patch feature.yaml\nwith correct branch name"];
    fill_spec [label="Fill spec.md with\nrequirements (if provided)"];
    commit [label="git add + commit\nspec scaffold"];
    open_editor [label="Open editor in worktree"];
    success [label="Report: editor opening..." shape=ellipse];
    fail [label="Report: manual instructions" shape=ellipse];

    start -> get_desc;
    get_desc -> derive;
    derive -> create_wt;
    create_wt -> install;
    install -> init_spec;
    init_spec -> fix_yaml;
    fix_yaml -> fill_spec;
    fill_spec -> commit;
    commit -> open_editor;
    open_editor -> success [label="success"];
    open_editor -> fail [label="fail"];
}

Steps

1. Get Task Description

The user provides a high-level description of what the parallel task is about.

Examples:

• "fix the version display bug in settings"
• "add retry logic to the agent HTTP calls"
• "refactor DI container registration"

2. Derive Names

From the description, generate:

• Dir name: Short kebab-case identifier for the worktree directory (e.g., fix-version-display, add-agent-retry, refactor-di-container)
• Branch name: Conventional branch name using the project's prefix conventions (e.g., fix/version-display, feat/agent-retry, refactor/di-container)
• Feature name: Kebab-case name for the spec directory (same as dir name or adjusted)