This was written agentically; verify its assertions:
North star
Few turns, few tokens; the script owns the procedure, the markdown owns the intent. This epic tracks moving the kit's orchestration layer from bash to Python once the bash-first refactor of parallel-issues has landed and been measured. It is deliberately not scheduled.
Why
Research on 2026-09-23 (four parallel research passes over official Anthropic/OpenAI docs, the GNU/Google/clig.dev shell conventions, and the HANDBOOK.md adherence benchmark) converged on the same shape for the kit: few state-driven entry points that do many steps in one call and print a small digest plus the next command. Every shell-style source also agrees that shell past ~100 lines or with non-trivial control flow belongs in a structured language; the kit ships 41k lines of bash across 70 helpers and 28 libraries, with two files past 2,000 lines (hooks/lib/guard-lib.sh 2,288; .shared/scripts/agent-run.sh 2,031).
The operator's decision (2026-09-23): keep bash for now so the zero-dependency install contract holds, refactor parallel-issues first in bash, and revisit the language once that refactor has real-run numbers behind it.
What (when this epic is picked up)
- A Python orchestrator layer for the per-workflow entry points (state file → next step → digest), calling the existing bash units as subprocesses so the units and their tests survive.
- One output contract shared by both languages: data on stdout with
--format concise|json|tsv, diagnostics on stderr, bounded default output with a log path, errors that say what / expected / one fix, exit 0/1/2.
- Install contract decision recorded in RELEASING.md: which Python (system
python3 ≥ 3.x, no third-party packages) and how the plugin detects its absence and degrades.
- Slices to be filed as sub-issues after the bash-first parallel-issues refactor merges; each slice carries a before/after root tool-call count from a rollout as its acceptance test.
Not in scope
- Rewriting the hook guards (
guard-lib.sh); hooks stay bash so they load in milliseconds on both harnesses.
- Any change before the bash-first parallel-issues refactor has shipped and been measured.
Testing
🤖 Co-authored by Claude Fable 5.1
This was written agentically; verify its assertions:
North star
Few turns, few tokens; the script owns the procedure, the markdown owns the intent. This epic tracks moving the kit's orchestration layer from bash to Python once the bash-first refactor of parallel-issues has landed and been measured. It is deliberately not scheduled.
Why
Research on 2026-09-23 (four parallel research passes over official Anthropic/OpenAI docs, the GNU/Google/clig.dev shell conventions, and the HANDBOOK.md adherence benchmark) converged on the same shape for the kit: few state-driven entry points that do many steps in one call and print a small digest plus the next command. Every shell-style source also agrees that shell past ~100 lines or with non-trivial control flow belongs in a structured language; the kit ships 41k lines of bash across 70 helpers and 28 libraries, with two files past 2,000 lines (
hooks/lib/guard-lib.sh2,288;.shared/scripts/agent-run.sh2,031).The operator's decision (2026-09-23): keep bash for now so the zero-dependency install contract holds, refactor parallel-issues first in bash, and revisit the language once that refactor has real-run numbers behind it.
What (when this epic is picked up)
--format concise|json|tsv, diagnostics on stderr, bounded default output with a log path, errors that say what / expected / one fix, exit 0/1/2.python3≥ 3.x, no third-party packages) and how the plugin detects its absence and degrades.Not in scope
guard-lib.sh); hooks stay bash so they load in milliseconds on both harnesses.Testing
🤖 Co-authored by Claude Fable 5.1