@dhananjay_kaushik/claude-orchestrator 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dhananjay Kaushik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,370 @@
+# Claude Code Orchestrator
+
+Claude Code Orchestrator is a TypeScript CLI for running Claude Code through a test-driven, task-by-task workflow with verification, logs, resumability, and safe Git commits.
+
+The core rule is:
+
+**Claude implements one selected task. The orchestrator owns lifecycle state.**
+
+Claude task sessions do not mark tasks `DONE`, do not commit, and do not decide whether work is complete. The orchestrator validates the plan, runs Claude headlessly, checks structured results, runs verification commands, updates task state, and commits only after verification passes.
+
+## Status
+
+The MVP described below is implemented and tested. The original implementation contract is documented in [PLAN.md](./PLAN.md), [SKILLS.md](./SKILLS.md), and [AGENTS.md](./AGENTS.md).
+
+## Installation
+
+```bash
+npm install -g @dhananjay_kaushik/claude-orchestrator
+```
+
+Requires Node.js >= 18 and the `claude` CLI on your `PATH`.
+
+## Quick Start
+
+```bash
+cd your-project
+claude-orchestrator init      # create .claude-orchestrator.json
+claude-orchestrator plan      # generate a Markdown task plan
+claude-orchestrator run       # execute the next task
+claude-orchestrator run --loop  # execute tasks until one needs attention
+```
+
+## Workflow
+
+The intended workflow is:
+
+1. Create or validate config.
+2. Generate a Markdown implementation plan.
+3. Validate the plan.
+4. Select one task.
+5. Create or reuse an isolated per-task Git worktree.
+6. Run Claude Code headlessly for that task.
+7. Parse Claude's structured JSON result.
+8. Run verification commands.
+9. Mark the task `DONE` only if verification passes.
+10. Commit verified changes.
+11. Stop, resume later, or explicitly continue in loop mode.
+
+## Plan Format
+
+Plans live in `planDir`, defaulting to `workflow_generated_plans`.
+
+Tasks use a strict 5-state Markdown checkbox format:
+
+- `- [ ]` or `* [ ]`: `NOT_DONE`
+- `- [-]` or `* [-]`: `IN_PROGRESS`
+- `- [x]`, `- [X]`, `* [x]`, or `* [X]`: `DONE`
+- `- [f]`, `- [F]`, `* [f]`, or `* [F]`: `FAILED`
+- `- [b]`, `- [B]`, `* [b]`, or `* [B]`: `BLOCKED`
+
+Task identity is based on a stable slug/hash of normalized task text and heading context. Line numbers are not used as persistent task IDs because plan files can change as handoff notes or content are added.
+
+Task text must be unique across the whole plan, not just within a section — the parser rejects a plan with two tasks that read the same, even under different headings.
+
+Add a Status Tracker section near the top with running counts (`Total`, `NOT_DONE`, `IN_PROGRESS`, `DONE`, `FAILED`, `BLOCKED`) — the orchestrator's planning prompt generates one, and it's the fastest way for a human or a resumed session to see plan progress at a glance.
+
+## Claude Execution Contract
+
+Planning and execution use different Claude modes:
+
+- `plan` is interactive.
+- `run` is headless.
+
+Execution must use Claude Code's non-interactive JSON mode:
+
+```text
+claude -p "<prompt>" --output-format json
+```
+
+The orchestrator expects structured JSON fields such as:
+
+- `result`
+- `total_cost_usd`
+- `usage`
+- `session_id`
+- `is_error`
+
+The orchestrator stores the raw JSON response in the task log directory. Token usage and cost are read from structured JSON fields, not scraped from terminal text.
+
+The `result` field must include an orchestrator sentinel:
+
+- `ORCHESTRATOR_RESULT: SUCCESS`
+- `ORCHESTRATOR_RESULT: BLOCKED`
+- `ORCHESTRATOR_RESULT: NEEDS_RETRY_CONTEXT`
+
+`DONE` is never inferred from Claude output. `DONE` requires successful verification.
+
+## Commands
+
+### `claude-orchestrator init`
+
+Create or update `.claude-orchestrator.json` interactively.
+
+Expected behavior:
+
+- Prompt for plan directory, base branch, verification commands, timeouts, and Claude permission settings.
+- Write a validated config file.
+- Avoid adding post-MVP features such as notifications unless explicitly supported later.
+
+### `claude-orchestrator doctor`
+
+Check whether the current project can safely run orchestration.
+
+Checks include:
+
+- Claude binary exists.
+- Claude authentication can be verified if Claude exposes a stable check.
+- Current directory is a Git repository.
+- Config is valid.
+- Plan directory is readable.
+- State, log, and worktree directories are writable.
+- Verification commands satisfy command policy.
+- Claude permission settings are safe.
+
+No task state is mutated by `doctor`.
+
+### `claude-orchestrator validate`
+
+Validate config and plan files without executing Claude.
+
+Checks include:
+
+- `.claude-orchestrator.json` schema and defaults.
+- Structured verification commands.
+- Protected paths.
+- Plan checkbox states.
+- Duplicate or unstable task identity.
+- Unsupported or ambiguous task markers.
+
+### `claude-orchestrator plan`
+
+Start an interactive planning session with Claude Code.
+
+Expected behavior:
+
+- Prompt for planning model if needed.
+- Ensure the plan directory exists.
+- Inject the planning prompt.
+- Ask Claude to create a machine-parseable Markdown plan using the 5-state checkbox system.
+
+### `claude-orchestrator run`
+
+Execute one selected task from a plan.
+
+Default behavior:
+
+- Validate config and plan.
+- Run Claude binary/auth preflight.
+- Select the next executable task.
+- Create or reuse a per-task worktree.
+- Run Claude headlessly in JSON mode.
+- Enforce `taskTimeoutMs`.
+- Parse the sentinel from Claude's JSON `result`.
+- Run verification commands only after a `SUCCESS` sentinel.
+- Mark `DONE` and commit only after verification passes.
+- Stop after one task.
+
+### `claude-orchestrator run --loop`
+
+Run multiple tasks in sequence.
+
+Loop mode must be explicit. It should still stop on:
+
+- verification failure after retry cap
+- `BLOCKED`
+- session-limit pause
+- timeout
+- dirty worktree requiring user choice
+- invalid plan/config
+
+### `claude-orchestrator run --dry-run`
+
+Preview the next execution without mutating files.
+
+Shows:
+
+- selected plan
+- selected task
+- stable task ID
+- intended worktree
+- Claude command shape
+- verification commands
+- timeout settings
+- log and state paths
+
+Does not:
+
+- spawn Claude
+- edit Markdown
+- create commits
+- create branches
+- run verification commands
+
+### `claude-orchestrator status`
+
+Show current orchestration state.
+
+Expected output:
+
+- selected/current plan
+- task counts by status
+- active or next task
+- current worktree state
+- last Claude `session_id`
+- last result
+- retry count
+- session-limit pause details if present
+- resume command
+
+### `claude-orchestrator logs`
+
+Show paths to relevant logs without dumping full verbose output by default.
+
+Logs include:
+
+- raw Claude JSON response
+- Claude stderr
+- verification stdout/stderr
+- task state snapshots
+- command policy decisions
+- summary reports
+
+### Resuming interrupted work
+
+There is no separate `resume` command. An interrupted, `IN_PROGRESS`, or `BLOCKED: SESSION_LIMIT` task is just state on disk, so re-running `claude-orchestrator run --plan <path>` picks it back up automatically:
+
+- Re-validates config and plan.
+- Detects dirty task worktree state and prompts whether to continue in the existing worktree, retry from a clean base, or halt.
+- Preserves previous logs and retry context.
+- Does not consume retry budget for session-limit pauses.
+
+## Configuration
+
+Configuration lives in `.claude-orchestrator.json` at the project root.
+
+Top-level config areas:
+
+- `version`: config schema version.
+- `planDir`: project-relative plan directory.
+- `baseBranch`: base branch for task worktrees.
+- `branchPrefix`: branch name prefix for orchestrator work.
+- `models`: planning/execution model defaults.
+- `claude`: Claude binary, permission mode, allowed tools, and safe extra args.
+- `taskTimeoutMs`: per-task Claude wall-clock timeout.
+- `verificationCommands`: ordered structured verification commands.
+- `maxRetries`: bounded retry cap.
+- `logsDir`: log directory.
+- `stateDir`: state directory.
+- `worktreeDir`: per-task worktree directory.
+- `commitMessageTemplate`: verified task commit template.
+- `sessionLimits`: Claude usage-limit behavior.
+- `security`: command allowlist, denylist, protected paths, and network policy.
+
+### Verification Commands
+
+Verification commands must be structured objects, not shell strings.
+
+Required fields:
+
+- `command`: executable name or absolute path.
+- `args`: literal argument array.
+- `timeoutMs`: finite timeout.
+
+Optional fields:
+
+- `name`: display name.
+- `cwd`: project-relative working directory that must resolve inside the task worktree at execution time.
+- `env`: explicit environment key/value overrides.
+- `allowFailure`: advisory command flag, default false.
+
+Commands run with `shell: false`. Shell chains, redirection, command substitution, and interpolated environment expressions are not part of the MVP command model.
+
+## Safety Model
+
+The MVP safety model relies on real execution boundaries, not only prompt instructions.
+
+- Each task runs in an isolated Git worktree or equivalent sandbox.
+- Claude execution uses validated permission settings.
+- `--dangerously-skip-permissions` is not allowed for normal execution.
+- Protected path patterns are checked before and after execution.
+- Destructive Git operations are blocked.
+- Claude task sessions do not commit, amend, push, force-push, reset, clean, rebase, delete branches, or rewrite history.
+- The orchestrator does not auto-push in the MVP.
+- Verification commands are structured and policy-checked.
+- Secret-looking values are redacted from logs.
+
+Prompt instructions still tell Claude not to touch secrets or run destructive Git, but prompt text is treated as advisory unless backed by a technical boundary.
+
+## Timeouts, Retries & Resume
+
+Every Claude task execution has a finite wall-clock timeout. Timeout behavior:
+
+- Kill the Claude child process.
+- Preserve logs.
+- Preserve the task worktree for inspection.
+- Mark or report the task according to tested executor rules.
+- Do not commit.
+
+Retry behavior:
+
+- Verification or implementation failures increment retry count.
+- Retry prompts include concise, redacted prior failure context.
+- Session-limit pauses do not consume retry budget.
+- Retries stop at the configured cap and hard maximum.
+
+Resume behavior:
+
+- Interrupted work remains inspectable in its task worktree.
+- On resume, dirty worktree state is detected.
+- The user chooses whether to continue, retry cleanly, or halt.
+
+## Session Limits
+
+The orchestrator should show Claude session-limit information when Claude exposes it through stable output/status.
+
+If remaining usage or reset time is available, it appears in pre-run and summary output. If unavailable, the CLI says `unknown` rather than guessing.
+
+If Claude stops because of a session limit:
+
+- the task is paused as resumable work
+- normal retry count is not incremented
+- reset time is saved when known
+- the terminal shows the resume command
+- no commit is created
+
+Automatic resume after reset is post-MVP unless an explicit automation feature is added later.
+
+## Logs & Completion Overview
+
+Terminal output should stay concise. Full details go to files under `logsDir`.
+
+On task completion, the terminal should show:
+
+- task result
+- verification result
+- retry count
+- commit hash when created
+- log path
+- next action
+
+When all tasks are `DONE`, the orchestrator should close cleanly and show:
+
+- plan path
+- final status
+- completed, failed, and blocked counts
+- commits created
+- verification status
+- retry summary
+- estimated cost/usage from Claude JSON when available
+- detailed log directory
+
+## Post-MVP
+
+These features are explicitly post-MVP:
+
+- desktop notifications
+- webhooks
+- automatic resume after session reset
+- network-aware verification policy
+- dangerous override modes

package/bin/claude-orchestrator.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/cli.js

@@ -0,0 +1,79 @@
+import { Command } from 'commander';
+export const program = new Command();
+program
+    .name('claude-orchestrator')
+    .description('Stateful Workflow Engine on top of Claude Code')
+    .version('0.1.0')
+    .option('-c, --config <path>', 'path to config file')
+    .option('-v, --verbose', 'enable verbose logging');
+import { runInitCommand } from './commands/init.js';
+program
+    .command('init')
+    .description('create or update .claude-orchestrator.json interactively')
+    .action(async () => {
+    const parentOpts = program.opts();
+    await runInitCommand({ config: parentOpts.config });
+});
+import { runDoctorCommand } from './commands/doctor.js';
+import { runValidateCommand } from './commands/validate.js';
+program
+    .command('doctor')
+    .description('check environment, config, Git, and Claude binary')
+    .action(async () => {
+    const parentOpts = program.opts();
+    await runDoctorCommand({ config: parentOpts.config });
+});
+program
+    .command('validate')
+    .description('validate config and plan files without executing Claude')
+    .option('--plan <path>', 'path to a specific plan file')
+    .action(async (options) => {
+    const parentOpts = program.opts();
+    await runValidateCommand({ ...options, config: parentOpts.config });
+});
+import { runPlanCommand } from './commands/plan.js';
+import { runCommand } from './commands/run.js';
+program
+    .command('plan')
+    .description('run interactive planning')
+    .option('--plan <path>', 'path to a specific plan file')
+    .action(async (options) => {
+    const parentOpts = program.opts();
+    await runPlanCommand({ ...options, config: parentOpts.config });
+});
+program
+    .command('run')
+    .description('execute one selected task by default')
+    .option('--plan <path>', 'path to a specific plan file')
+    .option('--task <id>', 'stable ID of a specific task to run')
+    .option('--loop', 'optional explicit loop mode; never implicit')
+    .option('--yes', 'auto-confirm prompts (e.g. commit with no verification configured) for unattended runs')
+    .option('--dry-run', 'show intended execution without mutating state')
+    .action(async (options) => {
+    const parentOpts = program.opts();
+    await runCommand({ ...options, config: parentOpts.config });
+});
+import { runStatusCommand } from './commands/status.js';
+import { runLogsCommand } from './commands/logs.js';
+program
+    .command('status')
+    .description('show selected plan state, active task, and resume command')
+    .option('--plan <path>', 'path to a specific plan file')
+    .option('--task <id>', 'stable ID of a specific task')
+    .action(async (options) => {
+    const parentOpts = program.opts();
+    await runStatusCommand({ ...options, config: parentOpts.config });
+});
+program
+    .command('logs')
+    .description('show paths to relevant logs')
+    .option('--plan <path>', 'path to a specific plan file')
+    .option('--task <id>', 'stable ID of a specific task')
+    .action(async (options) => {
+    const parentOpts = program.opts();
+    await runLogsCommand({ ...options, config: parentOpts.config });
+});
+const isTest = process.env.NODE_ENV === 'test' || process.env.VITEST;
+if (!isTest) {
+    program.parse(process.argv);
+}

package/dist/commands/doctor.js

@@ -0,0 +1,43 @@
+import { execa } from 'execa';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { loadConfig } from '../config/loader.js';
+import { isGitRepository } from '../git/repo.js';
+export async function runDoctorCommand(options) {
+    p.intro(pc.bgBlue(pc.white(' Claude Orchestrator: Doctor ')));
+    let ok = true;
+    const isGit = await isGitRepository();
+    if (isGit) {
+        p.log.success(pc.green('Git repository detected.'));
+    }
+    else {
+        ok = false;
+        p.log.error(pc.red('Not a Git repository. Run "git init" or "claude-orchestrator run" to initialize one.'));
+    }
+    let config;
+    try {
+        config = await loadConfig(options.config);
+        p.log.success(pc.green('Config loaded and valid.'));
+    }
+    catch (error) {
+        ok = false;
+        p.log.error(pc.red(`Config invalid: ${error instanceof Error ? error.message : String(error)}`));
+    }
+    if (config) {
+        try {
+            await execa(config.claude.binary, ['--version'], { timeout: 5000 });
+            p.log.success(pc.green(`Claude binary "${config.claude.binary}" is executable.`));
+        }
+        catch (error) {
+            ok = false;
+            p.log.error(pc.red(`Claude binary "${config.claude.binary}" is not runnable: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+    if (ok) {
+        p.outro(pc.green('All checks passed.'));
+    }
+    else {
+        p.outro(pc.red('One or more checks failed.'));
+        process.exit(1);
+    }
+}

package/dist/commands/init.js

@@ -0,0 +1,36 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { defaultConfig } from '../config/defaults.js';
+export async function runInitCommand(options) {
+    p.intro(pc.bgBlue(pc.white(' Claude Orchestrator: Init ')));
+    const configPath = path.resolve(process.cwd(), options.config || '.claude-orchestrator.json');
+    const configExists = await fs
+        .access(configPath)
+        .then(() => true)
+        .catch(() => false);
+    if (configExists) {
+        p.log.warn(`Config already exists at ${pc.cyan(configPath)}. Leaving it untouched.`);
+    }
+    else {
+        const planDirResult = await p.text({
+            message: 'Where should plan files be stored?',
+            initialValue: defaultConfig.planDir,
+        });
+        if (p.isCancel(planDirResult)) {
+            p.cancel('Init cancelled.');
+            process.exit(0);
+        }
+        const config = { ...defaultConfig, planDir: planDirResult };
+        await fs.writeFile(configPath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+        p.log.success(`Created config at ${pc.cyan(configPath)}.`);
+    }
+    const config = configExists
+        ? JSON.parse(await fs.readFile(configPath, 'utf8'))
+        : { planDir: defaultConfig.planDir };
+    const resolvedPlanDir = path.resolve(process.cwd(), config.planDir || defaultConfig.planDir);
+    await fs.mkdir(resolvedPlanDir, { recursive: true });
+    p.log.success(`Plan directory ready at ${pc.cyan(resolvedPlanDir)}.`);
+    p.outro(pc.green(`Run ${pc.cyan('claude-orchestrator plan')} to create your first plan.`));
+}

package/dist/commands/logs.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { loadConfig } from '../config/loader.js';
+import { discoverPlan } from '../plans/discovery.js';
+export async function runLogsCommand(options) {
+    p.intro(pc.bgBlue(pc.white(' Claude Orchestrator: Logs ')));
+    const config = await loadConfig(options.config);
+    let planPath = options.plan;
+    if (!planPath) {
+        const defaultPlanDir = config.planDir || '.claude-orchestrator/plans';
+        planPath = (await discoverPlan({ planDir: defaultPlanDir })) || undefined;
+        if (!planPath) {
+            process.exit(0);
+        }
+    }
+    const planId = path.basename(planPath, path.extname(planPath));
+    const logsDir = config.logsDir || '.claude-orchestrator/logs';
+    const stateDir = config.stateDir || '.claude-orchestrator/state';
+    const planLogDir = path.join(logsDir, planId);
+    const stateFile = path.join(stateDir, `${planId}.json`);
+    p.log.info(pc.blue('--- Log Locations ---'));
+    p.log.info(`State File:      ${stateFile}${fs.existsSync(stateFile) ? '' : pc.yellow(' (not found)')}`);
+    if (options.task) {
+        const taskLogDir = path.join(planLogDir, options.task);
+        p.log.info(`Task Log Dir:    ${taskLogDir}${fs.existsSync(taskLogDir) ? '' : pc.yellow(' (not found)')}`);
+        if (fs.existsSync(taskLogDir)) {
+            for (const file of fs.readdirSync(taskLogDir)) {
+                p.log.info(`  - ${path.join(taskLogDir, file)}`);
+            }
+        }
+    }
+    else {
+        p.log.info(`Plan Log Dir:    ${planLogDir}${fs.existsSync(planLogDir) ? '' : pc.yellow(' (not found)')}`);
+        if (fs.existsSync(planLogDir)) {
+            for (const taskId of fs.readdirSync(planLogDir)) {
+                p.log.info(`  - ${path.join(planLogDir, taskId)}`);
+            }
+        }
+    }
+    p.outro(pc.green('Done.'));
+}