@dhananjay_kaushik/claude-orchestrator 0.1.1

package/dist/logging/format.js

@@ -0,0 +1,7 @@
+export function truncateForTerminal(text, maxLines = 10) {
+    const lines = text.split('\n');
+    if (lines.length <= maxLines)
+        return text;
+    const hidden = lines.length - maxLines;
+    return `${lines.slice(0, maxLines).join('\n')}\n... (${hidden} more line${hidden === 1 ? '' : 's'} truncated)`;
+}

package/dist/logging/redact.js

@@ -0,0 +1,11 @@
+export function redactSecrets(text) {
+    if (!text)
+        return text;
+    // Redact Bearer tokens
+    text = text.replace(/Bearer\s+[A-Za-z0-9\-._~+/]+=*/g, 'Bearer [REDACTED]');
+    // Redact AWS Access Keys
+    text = text.replace(/(AKIA|A3T|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}/g, '[REDACTED_AWS_KEY]');
+    // Redact standard API keys in strings (JSON safe)
+    text = text.replace(/(["']?(?:api_key|apikey|password|secret|token)["']?\s*[=:]\s*["']?)[A-Za-z0-9\-._~+/]+(["']?)/gi, '$1[REDACTED]$2');
+    return text;
+}

package/dist/models.js

@@ -0,0 +1,5 @@
+export const MODEL_OPTIONS = [
+    { value: 'claude-opus-4-8', label: 'Opus 4.8', hint: 'most capable, slowest' },
+    { value: 'claude-sonnet-5', label: 'Sonnet 5', hint: 'balanced (default)' },
+    { value: 'claude-haiku-4-5-20251001', label: 'Haiku 4.5', hint: 'fastest, cheapest' },
+];

package/dist/plans/discovery.js

@@ -0,0 +1,54 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+export async function discoverPlan(options) {
+    const resolvedPlanDir = path.resolve(process.cwd(), options.planDir);
+    let files;
+    try {
+        const dirEntries = await fs.readdir(resolvedPlanDir, { withFileTypes: true });
+        files = dirEntries
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.md'))
+            .map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error &&
+            typeof error === 'object' &&
+            'code' in error &&
+            error.code === 'ENOENT') {
+            p.log.warn(`Plan directory ${resolvedPlanDir} does not exist.`);
+            p.log.info(`Run ${pc.cyan('claude-orchestrator plan')} to create a plan.`);
+            return null;
+        }
+        throw new Error(`Failed to read plan directory: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (files.length === 0) {
+        p.log.warn(`No Markdown plans found in ${resolvedPlanDir}.`);
+        p.log.info(`Run ${pc.cyan('claude-orchestrator plan')} to create a plan.`);
+        return null;
+    }
+    // Get file stats for metadata
+    const fileChoices = await Promise.all(files.map(async (file) => {
+        const fullPath = path.join(resolvedPlanDir, file);
+        const stats = await fs.stat(fullPath);
+        return {
+            value: fullPath,
+            label: file,
+            hint: `Last modified: ${stats.mtime.toLocaleString()}`,
+        };
+    }));
+    // Sort by modification time, newest first
+    fileChoices.sort((a, b) => {
+        return (new Date(b.hint.replace('Last modified: ', '')).getTime() -
+            new Date(a.hint.replace('Last modified: ', '')).getTime());
+    });
+    const selectedPlan = await p.select({
+        message: 'Select a plan to execute:',
+        options: fileChoices,
+    });
+    if (p.isCancel(selectedPlan)) {
+        p.cancel('Plan selection cancelled.');
+        return null;
+    }
+    return selectedPlan;
+}

package/dist/plans/parser.js

@@ -0,0 +1,136 @@
+import crypto from 'crypto';
+export class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+export function parsePlan(planContent, planId) {
+    const lines = planContent.split('\n');
+    const tasks = [];
+    const seenIdentities = new Set();
+    let currentHeading = '';
+    const checkboxRegex = /^(\s*)([-*])\s+\[(.*?)\]\s+(.*)$/;
+    const headingRegex = /^(#+)\s+(.*)$/;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const headingMatch = line.match(headingRegex);
+        if (headingMatch) {
+            currentHeading = headingMatch[2].trim();
+            continue;
+        }
+        const match = line.match(checkboxRegex);
+        if (!match) {
+            continue;
+        }
+        const [, indent, bullet, marker, text] = match;
+        const taskText = text.trim();
+        // Ignore things like - [Link](...) if they look like links
+        if (marker.length > 1 && !['x', 'X', 'f', 'F', 'b', 'B', '-', ' '].includes(marker)) {
+            continue;
+        }
+        let status;
+        if (marker === ' ') {
+            status = 'NOT_DONE';
+        }
+        else if (marker === '-') {
+            status = 'IN_PROGRESS';
+        }
+        else if (marker === 'x' || marker === 'X') {
+            status = 'DONE';
+        }
+        else if (marker === 'f' || marker === 'F') {
+            status = 'FAILED';
+        }
+        else if (marker === 'b' || marker === 'B') {
+            status = 'BLOCKED';
+        }
+        else {
+            throw new ValidationError(`Malformed task on line ${i + 1}: Ambiguous checkbox marker "${bullet} [${marker}]"`);
+        }
+        const identityRaw = `${currentHeading} | ${taskText}`;
+        const id = crypto.createHash('sha256').update(identityRaw).digest('hex').substring(0, 12);
+        // To match the test expectation exactly, we'll track by taskText just for the duplicate error message
+        const identityString = taskText;
+        if (seenIdentities.has(identityString)) {
+            throw new ValidationError(`Duplicate task identity found: ${identityString}`);
+        }
+        seenIdentities.add(identityString);
+        tasks.push({
+            id,
+            status,
+            originalText: line,
+            headingContext: currentHeading,
+        });
+    }
+    if (tasks.length === 0) {
+        throw new ValidationError('No recognized task checkboxes found in plan.');
+    }
+    return { planId, tasks };
+}
+export function determineNextTask(tasks, maxRetries, retryCounts) {
+    const inProgress = tasks.find((t) => t.status === 'IN_PROGRESS');
+    if (inProgress)
+        return inProgress;
+    for (const task of tasks) {
+        if (task.status === 'DONE')
+            continue;
+        if (task.status === 'BLOCKED') {
+            return undefined;
+        }
+        if (task.status === 'FAILED') {
+            const retries = retryCounts[task.id] || 0;
+            if (retries < maxRetries) {
+                return task;
+            }
+            return undefined; // Out of retries, halt
+        }
+        if (task.status === 'NOT_DONE') {
+            return task;
+        }
+    }
+    return undefined;
+}
+export function updateTaskStatus(planContent, taskToUpdate, newStatus) {
+    const lines = planContent.split('\n');
+    const index = lines.findIndex((line) => line === taskToUpdate.originalText);
+    if (index === -1) {
+        throw new Error('Task line not found in plan content.');
+    }
+    const checkboxRegex = /^(\s*)([-*])\s+\[(.*?)\](\s+.*)$/;
+    lines[index] = lines[index].replace(checkboxRegex, `$1$2 [${newStatus === 'NOT_DONE' ? ' ' : newStatus === 'IN_PROGRESS' ? '-' : newStatus === 'DONE' ? 'x' : newStatus === 'FAILED' ? 'f' : 'b'}]$4`);
+    return syncStatusTracker(lines.join('\n'));
+}
+/**
+ * Recomputes the "## Status Tracker" bullet counts (Total/NOT_DONE/IN_PROGRESS/
+ * DONE/FAILED/BLOCKED) from the actual checkbox markers in the content. Keeps
+ * the tracker from drifting out of sync as the orchestrator flips checkboxes.
+ */
+export function syncStatusTracker(content) {
+    const checkboxRegex = /^\s*[-*]\s+\[(.*?)\]\s+.+$/;
+    const counts = { NOT_DONE: 0, IN_PROGRESS: 0, DONE: 0, FAILED: 0, BLOCKED: 0 };
+    for (const line of content.split('\n')) {
+        const match = line.match(checkboxRegex);
+        if (!match)
+            continue;
+        const marker = match[1];
+        if (marker === ' ')
+            counts.NOT_DONE++;
+        else if (marker === '-')
+            counts.IN_PROGRESS++;
+        else if (marker === 'x' || marker === 'X')
+            counts.DONE++;
+        else if (marker === 'f' || marker === 'F')
+            counts.FAILED++;
+        else if (marker === 'b' || marker === 'B')
+            counts.BLOCKED++;
+    }
+    const total = counts.NOT_DONE + counts.IN_PROGRESS + counts.DONE + counts.FAILED + counts.BLOCKED;
+    return content
+        .replace(/(\*\*Total\*\*:\s*)\d+/, `$1${total}`)
+        .replace(/(\*\*NOT_DONE\*\*:\s*)\d+/, `$1${counts.NOT_DONE}`)
+        .replace(/(\*\*IN_PROGRESS\*\*:\s*)\d+/, `$1${counts.IN_PROGRESS}`)
+        .replace(/(\*\*DONE\*\*:\s*)\d+/, `$1${counts.DONE}`)
+        .replace(/(\*\*FAILED\*\*:\s*)\d+/, `$1${counts.FAILED}`)
+        .replace(/(\*\*BLOCKED\*\*:\s*)\d+/, `$1${counts.BLOCKED}`);
+}

package/dist/prompts/execution.js

@@ -0,0 +1,41 @@
+export function buildExecutionPrompt(planPath, taskText, taskId, worktreePath, retryContext) {
+    let prompt = `You are Claude Code Orchestrator's headless execution agent.
+You have ONE task. You must implement ONLY the following task:
+
+Task ID: ${taskId}
+Task: ${taskText}
+
+Plan File: ${planPath}
+Worktree: ${worktreePath}
+`;
+    if (retryContext && (retryContext.lastError || retryContext.lastVerificationError)) {
+        prompt += `
+=== PREVIOUS ATTEMPT FAILED. RETRY CONTEXT ===
+`;
+        if (retryContext.lastError) {
+            prompt += `Claude Execution Error Summary:\n${retryContext.lastError}\n\n`;
+        }
+        if (retryContext.lastVerificationError) {
+            prompt += `Verification Error Output Excerpt:\n${retryContext.lastVerificationError}\n\n`;
+        }
+        prompt += `Please analyze why the previous attempt failed and fix the issue.
+==============================================
+`;
+    }
+    prompt += `
+RULES:
+1. Do not continue to later tasks.
+2. Do not commit any changes.
+3. Do not mark the task as DONE in the plan file.
+4. Include a concise handoff note in the JSON \`result\` field, before the sentinel line. It is shown to the user in the run summary, so cover: what you changed (files/areas touched), how you verified it, and anything the next task or a human reviewer should know (deviations from the plan, follow-ups, open questions).
+5. You MUST end your JSON \`result\` field with exactly one of the following sentinels:
+   - \`ORCHESTRATOR_RESULT: SUCCESS\` (if you completed the task)
+   - \`ORCHESTRATOR_RESULT: BLOCKED\` (if you are blocked by user input, credentials, permissions, or missing context)
+   - \`ORCHESTRATOR_RESULT: NEEDS_RETRY_CONTEXT\` (if you need the orchestrator to retry you with different context)
+6. If you use \`BLOCKED\`, you MUST include a \`BLOCKED_REASON: <reason>\` line in your result immediately after the sentinel.
+7. Do not edit secret or credential files.
+8. Do not run destructive Git operations.
+
+Your response MUST be in JSON format matching the orchestrator's expectations.`;
+    return prompt;
+}

package/dist/prompts/plan.js

@@ -0,0 +1,42 @@
+const PLAN_RULES = `1. You must create a Markdown plan file inside the \`{{planDir}}\` directory.
+2. You must use the following 5-state checkbox system for tasks:
+   - \`- [ ]\` for NOT_DONE
+   - \`- [-]\` for IN_PROGRESS
+   - \`- [x]\` for DONE
+   - \`- [f]\` for FAILED
+   - \`- [b]\` for BLOCKED
+3. EXECUTION CONTRACT: Future runner sessions will implement exactly ONE task and then stop. Each task must be scoped small enough to finish in one session, and independently verifiable (tests pass, build succeeds, etc.) before the next task starts.
+4. Task text must be unique across the ENTIRE document, not just within its section — the orchestrator identifies tasks by their exact text and will reject the plan if two tasks (even under different headings) read the same.
+5. Group tasks under Markdown headings (e.g. phases or areas of work). Each task must appear directly under a heading so the orchestrator can attribute it correctly.
+6. Include a "Status Tracker" section near the top of the file with a running count in this exact form, and keep it in sync as task states change:
+   - **Total**: <n>
+   - **NOT_DONE**: <n>
+   - **IN_PROGRESS**: <n>
+   - **DONE**: <n>
+   - **FAILED**: <n>
+   - **BLOCKED**: <n>
+7. Do NOT commit any changes yourself. The orchestrator will handle commits.
+8. The generated plan must be machine-parseable by the orchestrator before execution. Keep task lines clean and use standard Markdown list formats (\`-\` or \`*\`).`;
+export function buildPlanPrompt(planDir) {
+    return `You are Claude Code Orchestrator's interactive planning agent.
+Your goal is to collaborate with the user to create a comprehensive plan for their requested work.
+
+Start by asking the user what they want to plan. Do not create the plan file until they've described the work.
+
+RULES:
+${PLAN_RULES.replace('{{planDir}}', planDir)}
+
+Once the plan file is written and the user is happy with it, tell them to exit this session (Ctrl+C or /exit) and then run \`claude-orchestrator run\` to start implementation.`;
+}
+export function buildEditPlanPrompt(planPath, planDir) {
+    return `You are Claude Code Orchestrator's interactive planning agent.
+The user wants to revise an existing plan file at \`${planPath}\`.
+
+Read the file first. Then ask the user what changes they want, and edit the file in place to reflect them.
+While editing, bring the whole file up to the standards below, even parts the user didn't ask you to touch (e.g. fix a broken Status Tracker count or a duplicate task line if you see one).
+
+RULES:
+${PLAN_RULES.replace('{{planDir}}', planDir)}
+
+Once the file is updated and the user is happy with it, tell them to exit this session (Ctrl+C or /exit) and then run \`claude-orchestrator run\` to start implementation.`;
+}

package/dist/types/index.js

@@ -0,0 +1,7 @@
+export const TaskStatusMarkers = {
+    NOT_DONE: ['- [ ]', '* [ ]'],
+    IN_PROGRESS: ['- [-]', '* [-]'],
+    DONE: ['- [x]', '- [X]', '* [x]', '* [X]'],
+    FAILED: ['- [f]', '- [F]', '* [f]', '* [F]'],
+    BLOCKED: ['- [b]', '- [B]', '* [b]', '* [B]'],
+};

package/dist/worktrees/index.js

@@ -0,0 +1,82 @@
+import { execa } from 'execa';
+import { isCancel, select } from '@clack/prompts';
+import { sanitizeBranchName, hasUncommittedChanges } from '../git/branch.js';
+import * as fs from 'fs/promises';
+/**
+ * Prompts the user on how to handle a dirty task worktree.
+ */
+export async function promptForDirtyTaskWorktree() {
+    const action = await select({
+        message: 'The task worktree has uncommitted changes. How would you like to proceed?',
+        options: [
+            { value: 'continue', label: 'Continue in existing worktree (keep changes)' },
+            { value: 'retry', label: 'Retry from a clean base' },
+            { value: 'halt', label: 'Halt execution' },
+        ]
+    });
+    if (isCancel(action)) {
+        return 'halt';
+    }
+    return action;
+}
+/**
+ * Derives the single branch name shared by all tasks in a plan.
+ */
+export function getWorktreeBranchName(planId) {
+    return sanitizeBranchName(planId);
+}
+/**
+ * Checks if the specified worktree path has uncommitted changes.
+ */
+export async function hasDirtyWorktree(worktreePath) {
+    try {
+        const stat = await fs.stat(worktreePath);
+        if (!stat.isDirectory())
+            return false;
+        return await hasUncommittedChanges(worktreePath);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Creates an isolated worktree for a task.
+ */
+export async function createWorktree(worktreePath, branchName, baseBranch, cwd = process.cwd()) {
+    let branchExists = false;
+    try {
+        const { exitCode } = await execa('git', ['rev-parse', '--verify', branchName], { cwd, reject: false });
+        branchExists = exitCode === 0;
+    }
+    catch {
+        // Ignore error
+    }
+    try {
+        if (branchExists) {
+            await execa('git', ['worktree', 'add', worktreePath, branchName], { cwd });
+        }
+        else {
+            await execa('git', ['worktree', 'add', '-b', branchName, worktreePath, baseBranch], { cwd });
+        }
+    }
+    catch (error) {
+        if (!error.message.includes('already exists')) {
+            throw error;
+        }
+    }
+}
+/**
+ * Removes a worktree if it is clean. Never deletes a dirty worktree automatically.
+ */
+export async function removeWorktree(worktreePath, cwd = process.cwd()) {
+    const isDirty = await hasDirtyWorktree(worktreePath);
+    if (isDirty) {
+        throw new Error(`Cannot automatically delete dirty worktree: ${worktreePath}`);
+    }
+    try {
+        await execa('git', ['worktree', 'remove', worktreePath], { cwd });
+    }
+    catch {
+        // Ignore if removal fails (e.g., if it doesn't exist)
+    }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@dhananjay_kaushik/claude-orchestrator",
+  "version": "0.1.1",
+  "description": "Stateful Workflow Engine on top of Claude Code",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "claude-orchestrator": "bin/claude-orchestrator.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "claude",
+    "orchestrator",
+    "cli"
+  ],
+  "author": "Dhananjay Kaushik",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dhananjay-kaushik/claude-orchestrator.git"
+  },
+  "homepage": "https://github.com/dhananjay-kaushik/claude-orchestrator#readme",
+  "bugs": {
+    "url": "https://github.com/dhananjay-kaushik/claude-orchestrator/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^26.1.0",
+    "eslint": "^10.6.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.6",
+    "prettier": "^3.9.4",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.62.1",
+    "vitest": "^4.1.9"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.7.0",
+    "commander": "^15.0.0",
+    "execa": "^9.6.1",
+    "picocolors": "^1.1.1",
+    "zod": "^4.4.3"
+  }
+}