jared
/
cc-os
1
0
Fork 0
Code Issues 19 Pull Requests Packages Projects Releases Wiki Activity
cc-os/plugins/os-sdlc/reference/worktree-parallelism.md

3.6 KiB
Raw Blame History

worktree parallelism

Status: direction — as of 2026-07-16 Connects to: pipeline-stages, spec-and-ticket-layer, horizon, overview

Purpose

Defines how os-sdlc scopes concurrency: worktree-per-spec, sequential tickets within a spec, parallelism across specs. Load this when designing worktree lifecycle automation or any multi-ticket/multi-spec orchestration for os-sdlc.

Design

  • Worktree-per-spec. Tickets belonging to one spec run sequentially inside a single worktree — this avoids intra-spec merge conflicts entirely, since only one pipeline run is ever touching that worktree's files at a time.
  • Parallelism happens across specs, not within one. Multiple specs, each with its own worktree and its own sequential ticket queue, can run concurrently to keep overall progress rolling without any single spec's pipeline blocking another's.
  • Merge is a human gate in v1 — consistent with pipeline-stages's final stage. No automated merge choreography yet.
  • Tiered isolation ladder (from the vault taxonomy note): no isolation → single worktree → N parallel worktrees → full sandbox. os-sdlc v1 sits at "single worktree" per spec; a router agent that picks the isolation tier per task is explicitly deferred until a concrete case proves it's needed — not built ahead of that need.
  • Known bug — cc-os Forgejo issue #73: .cc-os/config is untracked, so worktrees don't inherit the tracker key, and os-backlog issue-create fails inside them. This blocks ticket-intake (stage 1 of pipeline-stages) from working inside a worktree today. The factory needs a native fix — either walking up to the owning repo root to find the config, or provisioning .cc-os/config at worktree-creation time. Per pipeline-stages's build sequencing: the once-only tracer walk hand-patches around this bug by manually copying .cc-os/config into the walk's worktree; the native fix (chosen from what the walk shows) is a hard dependency of the wiring step that follows the walk, so it must land before wiring starts.

Open questions

  • Whether Pocock's wayfinder:map tags should drive merge choreography — check the vault note matt-pocock-skills-v1-1-changes.md when designing this; not yet evaluated against os-sdlc's spec/ticket model. Related, sharper version of the same question: whether each spec should get an orchestration/"map" ticket that tracks its constituent tickets and their pipeline state, owned by the orchestrator, and used to drive merge choreography across a spec's worktree.
  • Worktree lifecycle automation: who creates a worktree for a new spec, who cleans it up after merge, and what triggers each.
  • Branch naming convention for spec-level and (if they ever become worth it) per-ticket branches under a spec branch.
  • PR-machinery plan. pipeline-stages stage 8 is a human merge gate in v1. Before that gate can automate, a plan is needed for what replaces it: PR creation, review attachment, and merge policy. Not scoped yet — flagged here so automation of the merge gate doesn't get built without one.

Sources

  • SecondBrain vault: agentic-sdlc-ai-developer-workflow-taxonomy.md (tiered isolation ladder), matt-pocock-skills-v1-1-changes.md (wayfinder:map)
  • cc-os Forgejo issue #73 (.cc-os/config untracked, worktree tracker-key inheritance bug)
  • ADR-0042 (2026-07-16, Planka retirement / git-issues-only os-backlog)
  • plugins/os-sdlc/OVERVIEW.md
  • 2026-07-16 design session (this doc's origin)