Working Copy Start

Working Copy Start

Orchestrates the start of a parallel working copy: it creates a git worktree, satisfies the plan-before-work gate, and hands the work off to a fresh, resumable top-level session. It operationalises spec/project/parallel-working-copies/ — specifically §Lifecycle: Create, §Lifecycle: Plan before work, and §Claude Code session scoping. It does not perform the substantive feature work in the worktree (that happens in the handed-off session) and it does not open the pull request (that is pull-request-create).

Why this is a skill, not an agent

• Mid-flow interactivity is the contract — confirming the branch/slug, then filling the plan's load-bearing design decision and its open questions, are per-step operator dialogues; an agent's fire-and-forget contract would lose them.
• Persistent on-disk artefacts are the deliverable — the worktree and its .resume/<slug>/plan.md are durable state the operator carries into the next session; skills own persistent state.
• Orchestrator role — this is the first step of a "ship a feature" flow that later chains into pull-request-create; per spec/claude/skill-vs-agent/ the orchestrator defaults to skill form.

User-language policy

Detect the operator's language and respond in it. The plan stub and any committed configuration stay in English; the operator's free-form plan content may be in their own language.

Guardrails

• The primary checkout stays on develop. Never switch it onto a feature branch. The worktree is the place the work happens; the primary checkout is only the launchpad it branches from. This is enforced by the guard-primary-checkout pre-commit hook and the PreToolUse feature-branch guard — do not work around them.
• Create only via the conformant path. Use task worktree:add -- <branch> [slug], which branches off origin/develop with an explicit base ref and places the worktree under ${NOLTE_WORKTREE_ROOT:-~/repos/.worktrees}/<repo>/<slug>/. Never git worktree add to an ad-hoc path, and never nest a worktree under .claude/.
• The plan gate is documentary, not mechanical. Fill the stub; do not add a hard-blocking hook. The value is the plan existing before work, not an enforced abort.

Operations

1. Start a working copy

1. Collect the branch and optional slug. The branch MUST carry an allowed prefix (feat/, fix/, chore/, docs/, exp/) per spec/project/branching-model/. Propose a kebab-case slug if the operator does not give one (defaults to the branch name minus its prefix).

2. Create the worktree. Run task worktree:add -- <branch> [slug]. This branches off origin/develop, seeds .resume/<slug>/plan.md with a plan stub, and prints the worktree path. Confirm the worktree path back to the operator.

3. Fill the plan-before-work stub. Open the seeded .resume/<slug>/plan.md inside the new worktree and walk the operator through completing every section: the goal, the researched current state, the load-bearing design decision with the open questions to confirm before work starts, the ordered work steps, the invariants and guardrails carried over from CLAUDE.md and the governing specs, and a status/resume-anchor checklist whose first unchecked box is where the next session resumes. Do not start the substantive work — capturing the plan is the gate.

4. Hand off to a fresh resumable session. Instruct the operator to do the substantive work in a fresh top-level session started from the worktree (cd <worktree> && claude), not a dispatched subagent or Workflow run, because only a top-level session's transcript is claude --resume-able (recoverable later via task resume). Emit both halves of the hand-off so the operator can paste them straight through:

   • the launch command, with the concrete worktree path filled in:

     cd <worktree-path> && claude
     

   • a ready-to-paste kickoff prompt for that fresh session. It MUST lead with an invocation of /nolte-shared:requirements-elicit, so the substantive work begins by capturing the working copy's requirement precisely (the same upstream gate roadmap-plan, feature-decompose, and issue-orchestrate rely on) rather than by acting on the first plausible guess; only then does it pick the work up from the plan. Use this shape:

     /nolte-shared:requirements-elicit capture the requirement for this working
     copy. Once the requirement artifact is at or above threshold, read the plan
     at .resume/<slug>/plan.md and begin the work from the first unchecked
     resume-anchor box, keeping the plan's status/resume-anchor checklist up to
     date as you go.
     

   Substitute the real <worktree-path> and <slug> so the operator copies a working command and prompt, not placeholders.

Gotchas

Per spec/claude/skill-management/ §Gotchas — concrete corrections to non-obvious environment facts the executing agent would otherwise get wrong.

• The worktree root is NOLTE_WORKTREE_ROOT, not a fixed path. task worktree:add reads ${NOLTE_WORKTREE_ROOT:-~/repos/.worktrees} per machine; the worktree lands under whatever that variable points to. Don't assume ~/repos/.worktrees when confirming the path back to the operator — read the actual path the task command prints.
• The primary-checkout guards go silent inside the worktree — that's expected, not a disabled guard. The PreToolUse feature-branch guard and the guard-primary-checkout pre-commit hook only fire in the primary checkout; inside a linked worktree feature branches are correct, so both no-op. Don't misread that silence as the guard being off.
• A harness subagent worktree can nest under .claude/worktrees/ unless redirected. Before the first Agent({isolation: "worktree"}) call, CLAUDE_AGENT_WORKTREE_ROOT must point under the same spec-conformant NOLTE_WORKTREE_ROOT root; otherwise the harness default materialises the worktree under .claude/worktrees/, which spec/project/parallel-working-copies/ §Path layout forbids.

Resumability

Per spec/claude/resumable-work/, this skill is resumable: true. State is persisted to .resume/working-copy-start/<run-id>.yml after every successful user-approval gate (worktree created, plan filled) and after each named phase boundary. On re-invocation, scan that directory for files with status: in_progress whose inputs: snapshot matches the current invocation; if one matches, prompt the operator with Resume run <run_id> from phase <phase> (last checkpoint <last_checkpoint_at>)? [resume / start-new / discard]. The state-file envelope and fail-closed semantics on schema or YAML errors are load-bearing in the spec; do not duplicate those rules here.

Hard rules

• Never switch the primary checkout off develop; all feature work happens in the worktree.
• Always create the worktree through task worktree:add; never an ad-hoc git worktree add path, and never nested under .claude/.
• Never skip the plan gate: the plan at .resume/<slug>/plan.md MUST be filled before the substantive work begins.
• Never do the substantive feature work or open the PR from this skill; prepare and hand off only.
• When spec/project/parallel-working-copies/ disagrees with this skill, the spec wins; propose updating this skill rather than diverging.