spets 0.1.3 → 0.1.5

package/dist/index.js

@@ -3,7 +3,9 @@ import {
   generateTaskId,
   getGitHubConfig,
   getOutputPath,
+  getOutputsDir,
   getSpetsDir,
+  getStepsDir,
   getWorkflowState,
   listTasks,
   loadConfig,
@@ -14,7 +16,7 @@ import {
   saveTaskMetadata,
   spetsExists,
   updateDocumentStatus
-} from "./chunk-XYU22TND.js";
+} from "./chunk-YK5ZZE4P.js";
 
 // src/index.ts
 import { Command } from "commander";
@@ -23,7 +25,24 @@ import { Command } from "commander";
 import { mkdirSync, writeFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
+import { execSync } from "child_process";
 var __dirname = dirname(fileURLToPath(import.meta.url));
+function getGitHubInfoFromRemote() {
+  try {
+    const remoteUrl = execSync("git remote get-url origin", { encoding: "utf-8" }).trim();
+    const sshMatch = remoteUrl.match(/git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
+    if (sshMatch) {
+      return { owner: sshMatch[1], repo: sshMatch[2] };
+    }
+    const httpsMatch = remoteUrl.match(/https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/);
+    if (httpsMatch) {
+      return { owner: httpsMatch[1], repo: httpsMatch[2] };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
 async function initCommand(options) {
   const cwd = process.cwd();
   const spetsDir = getSpetsDir(cwd);
@@ -36,7 +55,8 @@ async function initCommand(options) {
   mkdirSync(join(spetsDir, "outputs"), { recursive: true });
   mkdirSync(join(spetsDir, "hooks"), { recursive: true });
   const templatesDir = join(__dirname, "..", "templates");
-  writeFileSync(join(spetsDir, "config.yml"), getDefaultConfig());
+  const githubInfo = getGitHubInfoFromRemote();
+  writeFileSync(join(spetsDir, "config.yml"), getDefaultConfig(githubInfo));
   createDefaultSteps(spetsDir);
   createClaudeCommand(cwd);
   console.log("Initialized spets in .spets/");
@@ -48,27 +68,39 @@ async function initCommand(options) {
   console.log("  .claude/commands/spets.md   - Claude Code command");
   if (options.github) {
     createGitHubWorkflow(cwd);
-    console.log("  .github/workflows/spets.yml - GitHub Actions workflow");
+    console.log("  .github/workflows/spets.yml       - GitHub Actions workflow");
+    console.log("  .github/ISSUE_TEMPLATE/spets-task.yml - Issue template");
   }
   console.log("");
   console.log("Next steps:");
   console.log("  1. Edit .spets/config.yml to customize your workflow");
   console.log("  2. Customize step instructions in .spets/steps/");
   if (options.github) {
-    console.log("  3. Add ANTHROPIC_API_KEY to your repo secrets");
-    console.log('  4. Run: spets start "task" --platform github --owner <owner> --repo <repo> --issue <n>');
+    console.log("  3. Add CLAUDE_CODE_OAUTH_TOKEN to your repo secrets");
+    console.log('  4. Create a new Issue using the "Spets Task" template');
   } else {
     console.log('  3. Run: spets start "your task description"');
   }
 }
-function getDefaultConfig() {
+function getDefaultConfig(githubInfo) {
+  const githubSection = githubInfo ? `
+# GitHub integration (auto-detected from git remote)
+github:
+  owner: ${githubInfo.owner}
+  repo: ${githubInfo.repo}
+` : `
+# GitHub integration (uncomment and fill in to enable)
+# github:
+#   owner: your-org
+#   repo: your-repo
+`;
   return `# Spets Configuration
 # Define your workflow steps here
 
 steps:
   - 01-plan
   - 02-implement
-
+${githubSection}
 # Optional hooks (shell scripts)
 # hooks:
 #   preStep: "./hooks/pre-step.sh"
@@ -247,82 +279,179 @@ function createClaudeCommand(cwd) {
 function getClaudeCommand() {
   return `# Spets - Spec Driven Development
 
-Run spets workflows from Claude Code.
+Spec-Driven Development workflow execution skill for Claude Code.
+
+---
 
-## Usage
+## CRITICAL: Execution Model
 
+This skill runs **deterministically** within the current Claude Code session.
+- NO subprocess spawning for AI/LLM calls
+- The orchestrator manages state via JSON protocol
+- Each step follows a strict state machine flow
+
+---
+
+## Orchestrator Commands
+
+All workflow state is managed by the orchestrator CLI:
+
+\`\`\`bash
+npx spets orchestrate init "<description>"      # Start new workflow
+npx spets orchestrate done <taskId>             # Mark step complete
+npx spets orchestrate clarified <taskId> '<json>'  # Submit answers
+npx spets orchestrate approve <taskId>          # Approve and continue
+npx spets orchestrate revise <taskId> "<feedback>" # Request revision
+npx spets orchestrate reject <taskId>           # Stop workflow
+npx spets orchestrate stop <taskId>             # Pause (can resume)
+npx spets orchestrate status <taskId>           # Get current status
 \`\`\`
-/spets start "task description"  - Start a new workflow
-/spets status                     - Show workflow status
-/spets resume                     - Resume paused workflow
+
+---
+
+## Execution Flow
+
+### 1. Workflow Start (FIRST ACTION - NO EXCEPTIONS)
+
+When skill is loaded, **immediately** run:
+
+\`\`\`bash
+npx spets orchestrate init "{user_request}"
 \`\`\`
 
-## Instructions
+### 2. Document Generation (type: step)
+
+When you receive \`type: "step"\`:
+
+1. **Read the instruction file** from context.instruction
+2. **Read the template file** from context.template (if exists)
+3. **Read previous output** from context.previousOutput (if exists)
+4. **Generate the document** following the instruction and template
+5. **Write the document** to context.output
+6. **Mark step as done**: \`npx spets orchestrate done {taskId}\`
+
+### 3. Question Resolution (type: checkpoint, checkpoint: clarify)
+
+1. **Use AskUserQuestion** to ask the questions
+2. **Collect answers** into JSON format
+3. **Submit answers**: \`npx spets orchestrate clarified {taskId} '<answers_json>'\`
+
+### 4. Approval Request (type: checkpoint, checkpoint: approve)
+
+1. **Display document summary** from specPath
+2. **Use AskUserQuestion** with options: Approve, Revise, Reject, Stop
+3. **Execute the selected action**
+
+### 5. Workflow Complete (type: complete)
 
-When the user invokes this command:
+Display completion message based on status (completed, stopped, rejected)
 
-1. Parse the subcommand (start, status, resume)
-2. Execute the appropriate spets CLI command using Bash
-3. For 'start', read the generated documents and help iterate
+---
 
-### Start Flow
+## Response Type Actions Summary
 
-1. Run: \`npx spets start "<query>"\`
-2. Read the generated plan document from .spets/outputs/<taskId>/
-3. Present the plan to the user
-4. If user approves, continue. If they want changes, provide feedback.
+| Type | Checkpoint | Action |
+|------|------------|--------|
+| step | - | Generate document, write to output, call done |
+| checkpoint | clarify | Ask questions, call clarified with answers |
+| checkpoint | approve | Show doc, ask for decision, call appropriate command |
+| complete | - | Show final message, end skill |
+| error | - | Show error, end skill |
 
-### Status Flow
+---
 
-1. Run: \`npx spets status\`
-2. Present the current workflow state
+## Critical Implementation Rules
 
-### Resume Flow
+1. **ORCHESTRATOR FIRST** - Always call orchestrator before any action
+2. **ONE STEP AT A TIME** - Complete one step, get approval, then next
+3. **DETERMINISTIC FLOW** - Follow the exact state machine transitions
+4. **NO PROCESS SPAWN** - Generate documents in current session
+5. **WAIT FOR APPROVAL** - Never proceed without user approval
 
-1. Run: \`npx spets resume\`
-2. Continue the workflow from where it paused
+---
 
 ## Example Session
 
-User: /spets start "Create a REST API for user management"
+\`\`\`
+User: /spets Add user authentication
+
+[Skill calls: npx spets orchestrate init "Add user authentication"]
+[Receives: type=step, step=01-plan]
+
+[Skill reads instruction.md and template.md]
+[Skill generates plan document]
+[Skill writes to .spets/outputs/.../01-plan.md]
+[Skill calls: npx spets orchestrate done mku3abc-xyz]
+
+[Receives: type=checkpoint, checkpoint=approve]
+[Skill shows document summary]
+[Skill asks user: Approve/Revise/Reject/Stop?]
 
-Claude:
-1. Runs \`npx spets start "Create a REST API for user management"\`
-2. Reads the generated plan
-3. Asks user: "Here's the plan. [shows plan] Would you like to approve or revise?"
-4. On approve: \`npx spets resume --approve\`
-5. On revise: \`npx spets resume --revise "user feedback"\`
+User: Approve
+
+[Skill calls: npx spets orchestrate approve mku3abc-xyz]
+[Receives: type=step, step=02-implement]
+
+[... continues with implementation step ...]
+\`\`\`
 
 $ARGUMENTS
-command: The spets command to run (start, status, resume)
-args: Additional arguments for the command
+description: The task description for the workflow
 `;
 }
 function createGitHubWorkflow(cwd) {
   const workflowDir = join(cwd, ".github", "workflows");
+  const templateDir = join(cwd, ".github", "ISSUE_TEMPLATE");
   mkdirSync(workflowDir, { recursive: true });
+  mkdirSync(templateDir, { recursive: true });
   writeFileSync(join(workflowDir, "spets.yml"), getGitHubWorkflow());
+  writeFileSync(join(templateDir, "spets-task.yml"), getIssueTemplate());
+}
+function getIssueTemplate() {
+  return `name: Spets Task
+description: Start a Spets workflow
+labels: ["spets"]
+body:
+  - type: input
+    id: task
+    attributes:
+      label: Task Description
+      description: What do you want to accomplish?
+      placeholder: "Add user authentication"
+    validations:
+      required: true
+  - type: input
+    id: branch
+    attributes:
+      label: Branch Name
+      description: Leave empty to auto-generate (spets/<issue-number>)
+      placeholder: "feature/my-feature"
+    validations:
+      required: false
+`;
 }
 function getGitHubWorkflow() {
   const gh = (expr) => `\${{ ${expr} }}`;
   return `# Spets GitHub Action
-# Runs Claude Code to handle /approve, /revise, /reject commands
+# Handles workflow start from Issue creation and commands from comments
 
 name: Spets Workflow
 
 on:
+  issues:
+    types: [opened]
   issue_comment:
     types: [created]
 
-jobs:
-  handle-spets-command:
-    # Only run if comment contains a spets command
-    if: |
-      contains(github.event.comment.body, '/approve') ||
-      contains(github.event.comment.body, '/revise') ||
-      contains(github.event.comment.body, '/reject') ||
-      contains(github.event.comment.body, '/answer')
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
 
+jobs:
+  # Start workflow when a spets Issue is created
+  start-workflow:
+    if: github.event.action == 'opened' && contains(github.event.issue.labels.*.name, 'spets')
     runs-on: ubuntu-latest
 
     steps:
@@ -331,6 +460,30 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Parse Issue body
+        id: parse
+        env:
+          ISSUE_BODY: ${gh("github.event.issue.body")}
+          ISSUE_NUMBER: ${gh("github.event.issue.number")}
+        run: |
+          # Parse task description
+          TASK=$(echo "$ISSUE_BODY" | sed -n '/### Task Description/,/###/{/###/!p;}' | sed '/^$/d' | head -1)
+          echo "task=$TASK" >> $GITHUB_OUTPUT
+
+          # Parse branch name (optional)
+          BRANCH=$(echo "$ISSUE_BODY" | sed -n '/### Branch Name/,/###/{/###/!p;}' | sed '/^$/d' | head -1)
+          if [ -z "$BRANCH" ]; then
+            BRANCH="spets/$ISSUE_NUMBER"
+          fi
+          echo "branch=$BRANCH" >> $GITHUB_OUTPUT
+
+      - name: Create and checkout branch
+        run: |
+          git checkout -b ${gh("steps.parse.outputs.branch")}
+          git push -u origin ${gh("steps.parse.outputs.branch")}
+        env:
+          GH_TOKEN: ${gh("secrets.GITHUB_TOKEN")}
+
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
@@ -342,44 +495,70 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Determine context
-        id: context
+      - name: Start Spets workflow
         run: |
-          if [ -n "${gh("github.event.issue.pull_request")}" ]; then
-            echo "type=pr" >> $GITHUB_OUTPUT
-          else
-            echo "type=issue" >> $GITHUB_OUTPUT
+          npx spets start "$TASK" --github --issue ${gh("github.event.issue.number")}
+        env:
+          TASK: ${gh("steps.parse.outputs.task")}
+          CLAUDE_CODE_OAUTH_TOKEN: ${gh("secrets.CLAUDE_CODE_OAUTH_TOKEN")}
+          GH_TOKEN: ${gh("secrets.GITHUB_TOKEN")}
+
+      - name: Push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git diff --staged --quiet || git commit -m "Spets: Start workflow for #${gh("github.event.issue.number")}"
+          git push
+        env:
+          GH_TOKEN: ${gh("secrets.GITHUB_TOKEN")}
+
+  # Handle commands from Issue/PR comments
+  handle-command:
+    if: |
+      github.event.action == 'created' && (
+        contains(github.event.comment.body, '/approve') ||
+        contains(github.event.comment.body, '/revise') ||
+        contains(github.event.comment.body, '/reject')
+      )
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Find linked branch
+        id: branch
+        run: |
+          # Try to find branch linked to this issue
+          BRANCH=$(gh api repos/${gh("github.repository")}/issues/${gh("github.event.issue.number")} --jq '.body' | grep -oP 'spets/\\d+' || echo "")
+          if [ -z "$BRANCH" ]; then
+            BRANCH="spets/${gh("github.event.issue.number")}"
           fi
-          echo "number=${gh("github.event.issue.number")}" >> $GITHUB_OUTPUT
+          echo "name=$BRANCH" >> $GITHUB_OUTPUT
+        env:
+          GH_TOKEN: ${gh("secrets.GITHUB_TOKEN")}
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          ref: ${gh("steps.branch.outputs.name")}
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
 
-      - name: Run Claude Code
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Spets command
         run: |
-          claude -p "
-          You are running a Spets workflow via GitHub Actions.
-
-          Context:
-          - Repository: ${gh("github.repository")}
-          - Issue/PR: #${gh("github.event.issue.number")}
-          - Comment author: ${gh("github.event.comment.user.login")}
-          - Command received: $COMMENT_BODY
-
-          Instructions:
-          1. Parse the command from the comment (/approve, /revise, /reject, or /answer)
-          2. Find the active spets task in .spets/outputs/
-          3. Execute the appropriate action:
-             - /approve: Mark current step as approved, generate next step
-             - /revise <feedback>: Regenerate current step with feedback
-             - /reject: Mark workflow as rejected
-             - /answer: Process answers and continue
-          4. If generating content (plan or implementation), actually write the code/changes
-          5. Post a summary comment to the PR/Issue using gh cli
-          6. Commit any changes with a descriptive message
-
-          Use 'gh issue comment' or 'gh pr comment' to post updates.
-          "
+          npx spets github --issue ${gh("github.event.issue.number")} --comment "$COMMENT"
         env:
-          COMMENT_BODY: ${gh("github.event.comment.body")}
-          ANTHROPIC_API_KEY: ${gh("secrets.ANTHROPIC_API_KEY")}
+          COMMENT: ${gh("github.event.comment.body")}
+          CLAUDE_CODE_OAUTH_TOKEN: ${gh("secrets.CLAUDE_CODE_OAUTH_TOKEN")}
           GH_TOKEN: ${gh("secrets.GITHUB_TOKEN")}
 
       - name: Push changes
@@ -387,7 +566,7 @@ jobs:
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git add -A
-          git diff --staged --quiet || git commit -m "Spets: Update from workflow"
+          git diff --staged --quiet || git commit -m "Spets: Update from #${gh("github.event.issue.number")}"
           git push
         env:
           GH_TOKEN: ${gh("secrets.GITHUB_TOKEN")}
@@ -523,7 +702,7 @@ var Executor = class {
     this.config = options.config;
     this.cwd = options.cwd || process.cwd();
   }
-  async executeWorkflow(taskId, userQuery, startIndex = 0) {
+  async executeWorkflow(taskId, userQuery, startIndex = 0, feedback) {
     let previousOutput;
     if (startIndex > 0) {
       const prevStepName = this.config.steps[startIndex - 1];
@@ -543,7 +722,9 @@ var Executor = class {
         instruction: stepDef.instruction,
         template: stepDef.template,
         previousOutput,
-        outputPath: getOutputPath(taskId, stepName, this.cwd)
+        outputPath: getOutputPath(taskId, stepName, this.cwd),
+        feedback: i === startIndex ? feedback : void 0
+        // Only apply feedback to the target step
       };
       if (this.config.hooks?.preStep) {
         await runHook(this.config.hooks.preStep, {
@@ -653,7 +834,7 @@ var Executor = class {
 };
 
 // src/platform/cli.ts
-import { spawn as spawn2, execSync } from "child_process";
+import { spawn as spawn2, execSync as execSync2 } from "child_process";
 import { input, select, confirm } from "@inquirer/prompts";
 
 // src/platform/interface.ts
@@ -805,7 +986,7 @@ var CliPlatform = class extends BasePlatform {
   isClaudeInstalled() {
     try {
       const command = process.platform === "win32" ? "where" : "which";
-      execSync(`${command} claude`, { stdio: "ignore" });
+      execSync2(`${command} claude`, { stdio: "ignore" });
       return true;
     } catch {
       return false;
@@ -856,6 +1037,12 @@ function parseGitHubCommand(comment) {
   if (trimmed === "/approve") {
     return { command: "approve" };
   }
+  if (trimmed === "/approve --pr") {
+    return { command: "approve", createPR: true };
+  }
+  if (trimmed === "/approve --issue") {
+    return { command: "approve", createIssue: true };
+  }
   if (trimmed === "/reject") {
     return { command: "reject" };
   }
@@ -881,6 +1068,7 @@ function parseGitHubCommand(comment) {
 var GitHubPlatform = class extends BasePlatform {
   config;
   currentTaskId;
+  currentOutputPath;
   constructor(config) {
     super();
     this.config = config;
@@ -890,6 +1078,7 @@ var GitHubPlatform = class extends BasePlatform {
   }
   async generateDocument(context) {
     this.currentTaskId = context.taskId;
+    this.currentOutputPath = context.outputPath;
     const prompt = this.buildPrompt(context);
     const response = await this.callClaude(prompt);
     const { document, questions } = this.parseResponse(response);
@@ -903,7 +1092,7 @@ var GitHubPlatform = class extends BasePlatform {
     throw new PauseForInputError("questions", questions);
   }
   async requestApproval(doc, stepName) {
-    const comment = this.formatApprovalComment(doc, stepName, this.currentTaskId);
+    const comment = this.formatApprovalComment(doc, stepName, this.currentTaskId, this.currentOutputPath);
     await this.postComment(comment);
     console.log("\n\u23F8\uFE0F  Waiting for approval on GitHub...");
     console.log("   Comment /approve, /revise <feedback>, or /reject on the PR/Issue.");
@@ -936,20 +1125,31 @@ var GitHubPlatform = class extends BasePlatform {
       lines.push("");
     }
     lines.push("---");
-    lines.push("**Reply with:**");
+    lines.push("");
+    lines.push("**How to answer:**");
+    lines.push("");
     lines.push("```");
     lines.push("/answer");
     for (let i = 0; i < questions.length; i++) {
-      lines.push(`Q${i + 1}: your answer here`);
+      lines.push(`Q${i + 1}: <your answer for question ${i + 1}>`);
     }
     lines.push("```");
+    lines.push("");
+    lines.push("Example:");
+    lines.push("```");
+    lines.push("/answer");
+    lines.push("Q1: Use TypeScript");
+    lines.push("Q2: Yes, add unit tests");
+    lines.push("```");
     return lines.join("\n");
   }
-  formatApprovalComment(doc, stepName, taskId) {
+  formatApprovalComment(doc, stepName, taskId, outputPath) {
+    const relativePath = outputPath ? outputPath.replace(process.cwd() + "/", "") : `.spets/outputs/${taskId}/${stepName}.md`;
     const lines = [
       `## \u{1F4C4} Spets: ${stepName} - Review Required`,
       "",
       `> Task ID: \`${taskId}\``,
+      `> Output: \`${relativePath}\``,
       "",
       "<details>",
       "<summary>\u{1F4DD} View Document</summary>",
@@ -966,8 +1166,12 @@ var GitHubPlatform = class extends BasePlatform {
       "| Command | Description |",
       "|---------|-------------|",
       "| `/approve` | Approve and continue to next step |",
+      "| `/approve --pr` | Approve and create a Pull Request |",
+      "| `/approve --issue` | Approve and create/update an Issue |",
       "| `/revise <feedback>` | Request changes with feedback |",
-      "| `/reject` | Reject and stop workflow |"
+      "| `/reject` | Reject and stop workflow |",
+      "",
+      "Example: `/revise Please add more details about error handling`"
     ];
     return lines.join("\n");
   }
@@ -1032,12 +1236,11 @@ var GitHubPlatform = class extends BasePlatform {
   async callClaude(prompt) {
     return new Promise((resolve, reject) => {
       const proc = spawn3("claude", [
-        "--print",
+        "-p",
+        prompt,
         "--permission-mode",
         "bypassPermissions"
-      ], { stdio: ["pipe", "pipe", "pipe"] });
-      proc.stdin.write(prompt);
-      proc.stdin.end();
+      ], { stdio: ["ignore", "pipe", "pipe"] });
       let stdout = "";
       let stderr = "";
       proc.stdout.on("data", (data) => {
@@ -1048,7 +1251,7 @@ var GitHubPlatform = class extends BasePlatform {
       });
       proc.on("close", (code) => {
         if (code !== 0) {
-          reject(new Error(`Claude CLI failed: ${stderr}`));
+          reject(new Error(`Claude CLI failed (code ${code}): stderr=${stderr}, stdout=${stdout}`));
         } else {
           resolve(stdout);
         }
@@ -1080,6 +1283,83 @@ var GitHubPlatform = class extends BasePlatform {
 };
 
 // src/commands/start.ts
+import { execSync as execSync3 } from "child_process";
+function getGitHubInfo(cwd) {
+  const config = getGitHubConfig(cwd);
+  if (config?.owner && config?.repo) {
+    return { owner: config.owner, repo: config.repo };
+  }
+  try {
+    const remoteUrl = execSync3("git remote get-url origin", { encoding: "utf-8", cwd }).trim();
+    const sshMatch = remoteUrl.match(/git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
+    if (sshMatch) {
+      return { owner: sshMatch[1], repo: sshMatch[2] };
+    }
+    const httpsMatch = remoteUrl.match(/https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/);
+    if (httpsMatch) {
+      return { owner: httpsMatch[1], repo: httpsMatch[2] };
+    }
+  } catch {
+  }
+  return null;
+}
+function createGitHubIssue(info, query, taskId) {
+  const body = `## Task
+${query}
+
+## Spets Workflow
+- Task ID: \`${taskId}\`
+- Status: In Progress
+
+---
+_Managed by [Spets](https://github.com/eatnug/spets)_`;
+  const result = execSync3(
+    `gh issue create --repo ${info.owner}/${info.repo} --title "${query.slice(0, 50)}" --body "${body.replace(/"/g, '\\"')}" --label spets`,
+    { encoding: "utf-8" }
+  );
+  const match = result.match(/\/issues\/(\d+)/);
+  if (!match) {
+    throw new Error("Failed to parse issue number from gh output");
+  }
+  return parseInt(match[1], 10);
+}
+function createGitHubPR(info, query, taskId) {
+  const branchName = `spets/${taskId}`;
+  execSync3(`git checkout -b ${branchName}`, { encoding: "utf-8" });
+  execSync3(`git push -u origin ${branchName}`, { encoding: "utf-8" });
+  const body = `## Task
+${query}
+
+## Spets Workflow
+- Task ID: \`${taskId}\`
+- Status: In Progress
+
+---
+_Managed by [Spets](https://github.com/eatnug/spets)_`;
+  const result = execSync3(
+    `gh pr create --repo ${info.owner}/${info.repo} --title "${query.slice(0, 50)}" --body "${body.replace(/"/g, '\\"')}" --label spets`,
+    { encoding: "utf-8" }
+  );
+  const match = result.match(/\/pull\/(\d+)/);
+  if (!match) {
+    throw new Error("Failed to parse PR number from gh output");
+  }
+  return parseInt(match[1], 10);
+}
+function findLinkedIssueOrPR(info) {
+  try {
+    const result = execSync3(
+      `gh pr view --repo ${info.owner}/${info.repo} --json number`,
+      { encoding: "utf-8" }
+    );
+    const pr = JSON.parse(result);
+    if (pr.number) {
+      return { type: "pr", number: pr.number };
+    }
+  } catch {
+  }
+  return null;
+}
 async function startCommand(query, options) {
   const cwd = process.cwd();
   if (!spetsExists(cwd)) {
@@ -1088,35 +1368,67 @@ async function startCommand(query, options) {
   }
   const config = loadConfig(cwd);
   const taskId = generateTaskId();
-  console.log(`Starting new workflow: ${taskId}`);
-  console.log(`Query: ${query}`);
-  console.log(`Platform: ${options.platform || "cli"}`);
-  console.log("");
   saveTaskMetadata(taskId, query, cwd);
   let platform;
-  if (options.platform === "github") {
-    const githubConfig = getGitHubConfig(cwd);
-    const owner = options.owner || githubConfig?.owner;
-    const repo = options.repo || githubConfig?.repo;
-    const pr = options.pr || (githubConfig?.defaultPr ? String(githubConfig.defaultPr) : void 0);
-    const issue = options.issue || (githubConfig?.defaultIssue ? String(githubConfig.defaultIssue) : void 0);
-    if (!owner || !repo) {
-      console.error("GitHub platform requires --owner and --repo (or set in .spets/config.yml)");
+  if (options.github || options.issue !== void 0 || options.pr !== void 0) {
+    const githubInfo = getGitHubInfo(cwd);
+    if (!githubInfo) {
+      console.error("Could not determine GitHub owner/repo. Set in .spets/config.yml or add git remote.");
       process.exit(1);
     }
-    if (!pr && !issue) {
-      console.error("GitHub platform requires --pr or --issue (or set defaultPr/defaultIssue in .spets/config.yml)");
-      process.exit(1);
+    let issueNumber;
+    let prNumber;
+    if (options.issue !== void 0) {
+      if (typeof options.issue === "string") {
+        issueNumber = parseInt(options.issue, 10);
+        console.log(`Using existing Issue #${issueNumber}`);
+      } else {
+        console.log("Creating new GitHub Issue...");
+        issueNumber = createGitHubIssue(githubInfo, query, taskId);
+        console.log(`Created Issue #${issueNumber}`);
+      }
+    }
+    if (options.pr !== void 0) {
+      if (typeof options.pr === "string") {
+        prNumber = parseInt(options.pr, 10);
+        console.log(`Using existing PR #${prNumber}`);
+      } else {
+        console.log("Creating new GitHub PR...");
+        prNumber = createGitHubPR(githubInfo, query, taskId);
+        console.log(`Created PR #${prNumber}`);
+      }
+    }
+    if (issueNumber === void 0 && prNumber === void 0) {
+      const linked = findLinkedIssueOrPR(githubInfo);
+      if (linked) {
+        console.log(`Found linked ${linked.type} #${linked.number}`);
+        if (linked.type === "pr") {
+          prNumber = linked.number;
+        } else {
+          issueNumber = linked.number;
+        }
+      } else {
+        console.log("No linked Issue/PR found. Running in GitHub mode without Issue/PR.");
+      }
     }
     platform = new GitHubPlatform({
-      owner,
-      repo,
-      prNumber: pr ? parseInt(pr, 10) : void 0,
-      issueNumber: issue ? parseInt(issue, 10) : void 0
+      owner: githubInfo.owner,
+      repo: githubInfo.repo,
+      prNumber,
+      issueNumber
     });
+    console.log(`Starting workflow: ${taskId}`);
+    console.log(`Query: ${query}`);
+    console.log(`Platform: github (${githubInfo.owner}/${githubInfo.repo})`);
+    if (issueNumber) console.log(`Issue: #${issueNumber}`);
+    if (prNumber) console.log(`PR: #${prNumber}`);
   } else {
     platform = new CliPlatform();
+    console.log(`Starting workflow: ${taskId}`);
+    console.log(`Query: ${query}`);
+    console.log(`Platform: cli`);
   }
+  console.log("");
   const executor = new Executor({ platform, config, cwd });
   try {
     await executor.executeWorkflow(taskId, query);
@@ -1264,23 +1576,31 @@ function installClaudePlugin() {
   const claudeDir = join3(homedir(), ".claude");
   const commandsDir = join3(claudeDir, "commands");
   mkdirSync2(commandsDir, { recursive: true });
-  const skillPath = join3(commandsDir, "spets.md");
+  const skillPath = join3(commandsDir, "sdd-do.md");
   writeFileSync2(skillPath, getClaudeSkillContent());
   console.log("Installed Claude Code plugin.");
   console.log(`Location: ${skillPath}`);
   console.log("");
   console.log("Usage in Claude Code:");
-  console.log('  /spets start "your task description"');
-  console.log("  /spets status");
-  console.log("  /spets resume");
+  console.log('  /sdd-do "your task description"');
   console.log("");
-  console.log("Note: The plugin uses npx to run spets, so global installation is not required.");
+  console.log("This skill runs deterministically within your Claude Code session.");
+  console.log("No additional Claude processes are spawned.");
 }
 async function uninstallPlugin(name) {
   if (name === "claude") {
-    const skillPath = join3(homedir(), ".claude", "commands", "spets.md");
-    if (existsSync3(skillPath)) {
-      rmSync(skillPath);
+    const oldSkillPath = join3(homedir(), ".claude", "commands", "spets.md");
+    const newSkillPath = join3(homedir(), ".claude", "commands", "sdd-do.md");
+    let uninstalled = false;
+    if (existsSync3(oldSkillPath)) {
+      rmSync(oldSkillPath);
+      uninstalled = true;
+    }
+    if (existsSync3(newSkillPath)) {
+      rmSync(newSkillPath);
+      uninstalled = true;
+    }
+    if (uninstalled) {
       console.log("Uninstalled Claude Code plugin.");
     } else {
       console.log("Claude Code plugin not installed.");
@@ -1293,10 +1613,11 @@ async function uninstallPlugin(name) {
 async function listPlugins() {
   console.log("Available plugins:");
   console.log("");
-  console.log("  claude - Claude Code slash command integration");
+  console.log("  claude - Claude Code /sdd-do skill");
   console.log("");
-  const claudeSkillPath = join3(homedir(), ".claude", "commands", "spets.md");
-  const claudeInstalled = existsSync3(claudeSkillPath);
+  const oldSkillPath = join3(homedir(), ".claude", "commands", "spets.md");
+  const newSkillPath = join3(homedir(), ".claude", "commands", "sdd-do.md");
+  const claudeInstalled = existsSync3(oldSkillPath) || existsSync3(newSkillPath);
   console.log("Installed:");
   if (claudeInstalled) {
     console.log("  - claude");
@@ -1305,81 +1626,202 @@ async function listPlugins() {
   }
 }
 function getClaudeSkillContent() {
-  return `# Spets - Spec Driven Development
+  return `# SDD-Do Skill
+
+Spec-Driven Development workflow execution skill for Claude Code.
+
+---
+
+## When to Use This Skill
 
-Run spets workflows from Claude Code.
+Automatically invoked when user uses:
+- \`/sdd-do\` - Run SDD workflow
 
-## Usage
+---
 
+## CRITICAL: Execution Model
+
+This skill runs **deterministically** within the current Claude Code session.
+- NO subprocess spawning for AI/LLM calls
+- The orchestrator manages state via JSON protocol
+- Each step follows a strict state machine flow
+
+---
+
+## Orchestrator Commands
+
+All workflow state is managed by the orchestrator CLI:
+
+\`\`\`bash
+npx spets orchestrate init "<description>"      # Start new workflow
+npx spets orchestrate done <taskId>             # Mark step complete
+npx spets orchestrate clarified <taskId> '<json>'  # Submit answers
+npx spets orchestrate approve <taskId>          # Approve and continue
+npx spets orchestrate revise <taskId> "<feedback>" # Request revision
+npx spets orchestrate reject <taskId>           # Stop workflow
+npx spets orchestrate stop <taskId>             # Pause (can resume)
+npx spets orchestrate status <taskId>           # Get current status
 \`\`\`
-/spets start "task description"  - Start a new workflow
-/spets status                     - Show workflow status
-/spets resume                     - Resume paused workflow
+
+---
+
+## Execution Flow
+
+### 1. Workflow Start (FIRST ACTION - NO EXCEPTIONS)
+
+When skill is loaded, **immediately** run:
+
+\`\`\`bash
+npx spets orchestrate init "{user_request}"
+\`\`\`
+
+**JSON Output:**
+\`\`\`json
+{
+  "type": "step",
+  "step": "01-plan",
+  "stepIndex": 1,
+  "totalSteps": 2,
+  "taskId": "mku3abc-xyz",
+  "description": "User request here",
+  "context": {
+    "instruction": ".spets/steps/01-plan/instruction.md",
+    "template": ".spets/steps/01-plan/template.md",
+    "output": ".spets/outputs/mku3abc-xyz/01-plan.md",
+    "revisionFeedback": null
+  },
+  "onComplete": "done mku3abc-xyz"
+}
 \`\`\`
 
-## Instructions
+---
 
-When the user invokes this command:
+### 2. Document Generation (type: step)
 
-1. Parse the subcommand (start, status, resume)
-2. Execute the appropriate spets CLI command using Bash
-3. For 'start', read the generated documents and help iterate
+When you receive \`type: "step"\`:
 
-**Important**: Use \`npx spets\` to run commands. This ensures the command works even if spets is not globally installed.
+1. **Read the instruction file** using Read tool
+2. **Read the template file** (if exists) using Read tool
+3. **Read previous output** (if exists) using Read tool
+4. **Generate the document** following the instruction and template
+5. **Write the document** to context.output using Write tool
+6. **Mark step as done**:
+   \`\`\`bash
+   npx spets orchestrate done {taskId}
+   \`\`\`
 
-### Start Flow
+---
 
-1. Run: \`npx spets start "<query>"\`
-2. Read the generated plan document from .spets/outputs/<taskId>/
-3. Present the plan to the user
-4. If user approves, continue. If they want changes, provide feedback.
+### 3. Question Resolution (type: checkpoint, checkpoint: clarify)
 
-### Status Flow
+When you receive \`type: "checkpoint"\` with \`checkpoint: "clarify"\`:
 
-1. Run: \`npx spets status\`
-2. Present the current workflow state
+1. **Use AskUserQuestion** tool to ask the questions
+2. **Collect answers** into JSON format
+3. **Submit answers**:
+   \`\`\`bash
+   npx spets orchestrate clarified {taskId} '[{"questionId":"q1","answer":"..."}]'
+   \`\`\`
 
-### Resume Flow
+---
 
-1. Run: \`npx spets resume\`
-2. Continue the workflow from where it paused
+### 4. Approval Request (type: checkpoint, checkpoint: approve)
 
-## Example Session
+When you receive \`type: "checkpoint"\` with \`checkpoint: "approve"\`:
+
+1. **Display document summary** from specPath using Read tool
+2. **Use AskUserQuestion** with options:
+   - Approve & Continue
+   - Revise (with feedback)
+   - Reject
+   - Stop (pause for later)
+
+3. **Execute the selected action**:
+   - **Approve**: \`npx spets orchestrate approve {taskId}\`
+   - **Revise**: \`npx spets orchestrate revise {taskId} "{feedback}"\`
+   - **Reject**: \`npx spets orchestrate reject {taskId}\`
+   - **Stop**: \`npx spets orchestrate stop {taskId}\`
+
+---
+
+### 5. Workflow Complete (type: complete)
+
+Display completion message based on status:
+- \`completed\`: Show success and list outputs
+- \`stopped\`: Show resume instructions
+- \`rejected\`: Show rejection message
+
+---
+
+## Response Type Actions Summary
+
+| Type | Checkpoint | Action |
+|------|------------|--------|
+| step | - | Generate document, write to output, call done |
+| checkpoint | clarify | Ask questions, call clarified with answers |
+| checkpoint | approve | Show doc, ask for decision, call appropriate command |
+| complete | - | Show final message, end skill |
+| error | - | Show error, end skill |
+
+---
 
-User: /spets start "Create a REST API for user management"
+## Critical Implementation Rules
 
-Claude:
-1. Runs \`npx spets start "Create a REST API for user management"\`
-2. Reads the generated plan
-3. Asks user: "Here's the plan. [shows plan] Would you like to approve or revise?"
-4. On approve: \`npx spets resume --approve\`
-5. On revise: \`npx spets resume --revise "user feedback"\`
+1. **ORCHESTRATOR FIRST** - Always call orchestrator before any action
+2. **ONE STEP AT A TIME** - Complete one step, get approval, then next
+3. **DETERMINISTIC FLOW** - Follow the exact state machine transitions
+4. **NO PROCESS SPAWN FOR AI** - Generate documents in current session
+5. **WAIT FOR APPROVAL** - Never proceed without user approval
+
+---
+
+## Error Handling
+
+- If \`.spets/\` not found, suggest running \`npx spets init\`
+- If orchestrator returns \`type: "error"\`, display the error and stop
+- If file read fails, show error and allow retry
 
 $ARGUMENTS
-command: The spets command to run (start, status, resume)
-args: Additional arguments for the command
+request: The user's task description for the workflow
 `;
 }
 
 // src/commands/github.ts
+import { execSync as execSync4 } from "child_process";
+function getGitHubInfo2(cwd) {
+  const config = getGitHubConfig(cwd);
+  if (config?.owner && config?.repo) {
+    return { owner: config.owner, repo: config.repo };
+  }
+  try {
+    const remoteUrl = execSync4("git remote get-url origin", { encoding: "utf-8", cwd }).trim();
+    const sshMatch = remoteUrl.match(/git@github\.com:([^/]+)\/(.+?)(?:\.git)?$/);
+    if (sshMatch) {
+      return { owner: sshMatch[1], repo: sshMatch[2] };
+    }
+    const httpsMatch = remoteUrl.match(/https:\/\/github\.com\/([^/]+)\/(.+?)(?:\.git)?$/);
+    if (httpsMatch) {
+      return { owner: httpsMatch[1], repo: httpsMatch[2] };
+    }
+  } catch {
+  }
+  return null;
+}
 async function githubCommand(options) {
   const cwd = process.cwd();
   if (!spetsExists(cwd)) {
     console.error("Spets not initialized.");
     process.exit(1);
   }
-  const configGitHub = getGitHubConfig(cwd);
-  const owner = options.owner || configGitHub?.owner;
-  const repo = options.repo || configGitHub?.repo;
-  const pr = options.pr || (configGitHub?.defaultPr ? String(configGitHub.defaultPr) : void 0);
-  const issue = options.issue || (configGitHub?.defaultIssue ? String(configGitHub.defaultIssue) : void 0);
-  const { comment, task } = options;
-  if (!owner || !repo) {
-    console.error("GitHub requires --owner and --repo (or set in .spets/config.yml)");
+  const githubInfo = getGitHubInfo2(cwd);
+  if (!githubInfo) {
+    console.error("Could not determine GitHub owner/repo. Set in .spets/config.yml or add git remote.");
     process.exit(1);
   }
+  const { owner, repo } = githubInfo;
+  const { pr, issue, comment, task } = options;
   if (!pr && !issue) {
-    console.error("Either --pr or --issue is required (or set defaultPr/defaultIssue in .spets/config.yml)");
+    console.error("Either --pr or --issue is required");
     process.exit(1);
   }
   const parsed = parseGitHubCommand(comment);
@@ -1397,7 +1839,7 @@ async function githubCommand(options) {
   }
   if (!taskId) {
     const config2 = loadConfig(cwd);
-    const { listTasks: listTasks2 } = await import("./state-H2GQS43T.js");
+    const { listTasks: listTasks2 } = await import("./state-JLYPJWUT.js");
     const tasks = listTasks2(cwd);
     for (const tid of tasks) {
       const state2 = getWorkflowState(tid, config2, cwd);
@@ -1430,6 +1872,15 @@ async function githubCommand(options) {
     case "approve": {
       console.log(`Approving step: ${state.currentStepName}`);
       updateDocumentStatus(outputPath, "approved");
+      if (parsed.createPR) {
+        console.log("Creating Pull Request...");
+        const prNumber = await createPullRequest(githubConfig, taskId, userQuery, state.currentStepName);
+        console.log(`Created PR #${prNumber}`);
+      }
+      if (parsed.createIssue) {
+        console.log("Creating/Updating Issue...");
+        await createOrUpdateIssue(githubConfig, taskId, userQuery, state.currentStepName);
+      }
       const nextIndex = state.currentStepIndex + 1;
       if (nextIndex >= config.steps.length) {
         console.log("\u2705 Workflow completed!");
@@ -1452,7 +1903,7 @@ async function githubCommand(options) {
       const platform = new GitHubPlatform(githubConfig);
       const executor = new Executor({ platform, config, cwd });
       try {
-        await executor.executeWorkflow(taskId, userQuery, state.currentStepIndex);
+        await executor.executeWorkflow(taskId, userQuery, state.currentStepIndex, parsed.feedback);
       } catch (error) {
         if (error.name !== "PauseForInputError") {
           throw error;
@@ -1521,14 +1972,527 @@ async function postComment(config, body) {
     proc.on("error", reject);
   });
 }
+async function createPullRequest(config, taskId, userQuery, stepName) {
+  const { execSync: execSync5 } = await import("child_process");
+  const { owner, repo } = config;
+  const title = userQuery.slice(0, 50) + (userQuery.length > 50 ? "..." : "");
+  const body = `## Spets Workflow
+
+- Task ID: \`${taskId}\`
+- Current Step: **${stepName}**
+
+### Description
+${userQuery}
+
+---
+_Created by [Spets](https://github.com/eatnug/spets)_`;
+  const result = execSync5(
+    `gh pr create --repo ${owner}/${repo} --title "${title.replace(/"/g, '\\"')}" --body "${body.replace(/"/g, '\\"')}"`,
+    { encoding: "utf-8" }
+  );
+  const match = result.match(/\/pull\/(\d+)/);
+  if (!match) {
+    throw new Error("Failed to parse PR number from gh output");
+  }
+  return parseInt(match[1], 10);
+}
+async function createOrUpdateIssue(config, taskId, userQuery, stepName) {
+  const { execSync: execSync5 } = await import("child_process");
+  const { owner, repo, issueNumber } = config;
+  const body = `## Spets Workflow Update
+
+- Task ID: \`${taskId}\`
+- Current Step: **${stepName}** \u2705 Approved
+
+### Description
+${userQuery}
+
+---
+_Updated by [Spets](https://github.com/eatnug/spets)_`;
+  if (issueNumber) {
+    execSync5(
+      `gh issue comment ${issueNumber} --repo ${owner}/${repo} --body "${body.replace(/"/g, '\\"')}"`,
+      { encoding: "utf-8" }
+    );
+  } else {
+    const title = userQuery.slice(0, 50) + (userQuery.length > 50 ? "..." : "");
+    execSync5(
+      `gh issue create --repo ${owner}/${repo} --title "${title.replace(/"/g, '\\"')}" --body "${body.replace(/"/g, '\\"')}" --label spets`,
+      { encoding: "utf-8" }
+    );
+  }
+}
+
+// src/orchestrator/index.ts
+import { readFileSync, writeFileSync as writeFileSync3, existsSync as existsSync4, mkdirSync as mkdirSync3 } from "fs";
+import { join as join4, dirname as dirname2 } from "path";
+import matter from "gray-matter";
+var Orchestrator = class {
+  cwd;
+  constructor(cwd = process.cwd()) {
+    this.cwd = cwd;
+  }
+  // ===========================================================================
+  // Config & Path Helpers
+  // ===========================================================================
+  getSteps() {
+    const config = loadConfig(this.cwd);
+    return config.steps;
+  }
+  getOutputPath() {
+    return getOutputsDir(this.cwd);
+  }
+  getStatePath(taskId) {
+    return join4(this.getOutputPath(), taskId, ".state.json");
+  }
+  getSpecPath(taskId, step) {
+    return join4(this.getOutputPath(), taskId, `${step}.md`);
+  }
+  getStepInstructionPath(step) {
+    return join4(getStepsDir(this.cwd), step, "instruction.md");
+  }
+  getStepTemplatePath(step) {
+    return join4(getStepsDir(this.cwd), step, "template.md");
+  }
+  // ===========================================================================
+  // State Management
+  // ===========================================================================
+  loadState(taskId) {
+    const statePath = this.getStatePath(taskId);
+    if (!existsSync4(statePath)) {
+      return null;
+    }
+    const data = JSON.parse(readFileSync(statePath, "utf-8"));
+    return data;
+  }
+  saveState(state) {
+    state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    const statePath = this.getStatePath(state.taskId);
+    const dir = dirname2(statePath);
+    if (!existsSync4(dir)) {
+      mkdirSync3(dir, { recursive: true });
+    }
+    writeFileSync3(statePath, JSON.stringify(state, null, 2));
+  }
+  // ===========================================================================
+  // Spec Helpers
+  // ===========================================================================
+  checkUnresolvedQuestions(specPath) {
+    if (!existsSync4(specPath)) {
+      return [];
+    }
+    const content = readFileSync(specPath, "utf-8");
+    const { data } = matter(content);
+    const questions = [];
+    if (data.open_questions && Array.isArray(data.open_questions)) {
+      for (let i = 0; i < data.open_questions.length; i++) {
+        const q = data.open_questions[i];
+        if (!q.resolved) {
+          questions.push({
+            id: `q${i + 1}`,
+            question: q.question || q.id || `Question ${i + 1}`,
+            context: q.context,
+            options: q.options,
+            resolved: false
+          });
+        }
+      }
+    }
+    return questions;
+  }
+  generateTaskId(description) {
+    const timestamp = Date.now().toString(36);
+    const random = Math.random().toString(36).substring(2, 6);
+    return `${timestamp}-${random}`;
+  }
+  // ===========================================================================
+  // Protocol Response Builders
+  // ===========================================================================
+  responseStep(state) {
+    const steps = this.getSteps();
+    const outputPath = this.getOutputPath();
+    let previousOutput;
+    if (state.stepIndex > 1) {
+      const prevStep = steps[state.stepIndex - 2];
+      const prevPath = join4(outputPath, state.taskId, `${prevStep}.md`);
+      if (existsSync4(prevPath)) {
+        previousOutput = prevPath;
+      }
+    }
+    const templatePath = this.getStepTemplatePath(state.currentStep);
+    const hasTemplate = existsSync4(templatePath);
+    return {
+      type: "step",
+      step: state.currentStep,
+      stepIndex: state.stepIndex,
+      totalSteps: state.totalSteps,
+      taskId: state.taskId,
+      description: state.description,
+      context: {
+        instruction: this.getStepInstructionPath(state.currentStep),
+        template: hasTemplate ? templatePath : void 0,
+        previousOutput,
+        output: join4(outputPath, state.taskId, `${state.currentStep}.md`),
+        revisionFeedback: state.revisionFeedback
+      },
+      onComplete: `done ${state.taskId}`
+    };
+  }
+  responseCheckpointClarify(state, questions) {
+    return {
+      type: "checkpoint",
+      checkpoint: "clarify",
+      taskId: state.taskId,
+      step: state.currentStep,
+      questions: questions.map((q) => ({
+        id: q.id,
+        question: q.question,
+        context: q.context,
+        options: q.options
+      })),
+      onComplete: `clarified ${state.taskId} '<answers_json>'`
+    };
+  }
+  responseCheckpointApprove(state) {
+    const outputPath = this.getOutputPath();
+    return {
+      type: "checkpoint",
+      checkpoint: "approve",
+      taskId: state.taskId,
+      step: state.currentStep,
+      stepIndex: state.stepIndex,
+      totalSteps: state.totalSteps,
+      specPath: join4(outputPath, state.taskId, `${state.currentStep}.md`),
+      options: ["approve", "revise", "reject", "stop"],
+      onComplete: {
+        approve: `approve ${state.taskId}`,
+        revise: `revise ${state.taskId} '<feedback>'`,
+        reject: `reject ${state.taskId}`,
+        stop: `stop ${state.taskId}`
+      }
+    };
+  }
+  responseComplete(state, status) {
+    const steps = this.getSteps();
+    const outputPath = this.getOutputPath();
+    const outputs = [];
+    for (let i = 0; i < state.stepIndex; i++) {
+      const specPath = join4(outputPath, state.taskId, `${steps[i]}.md`);
+      if (existsSync4(specPath)) {
+        outputs.push(specPath);
+      }
+    }
+    const messages = {
+      completed: "Workflow completed successfully",
+      stopped: `Workflow stopped. Resume with: spets resume --task ${state.taskId}`,
+      rejected: "Workflow rejected"
+    };
+    return {
+      type: "complete",
+      status,
+      taskId: state.taskId,
+      outputs,
+      message: messages[status]
+    };
+  }
+  responseError(error, taskId, step) {
+    const response = { type: "error", error };
+    if (taskId) response.taskId = taskId;
+    if (step) response.step = step;
+    return response;
+  }
+  // ===========================================================================
+  // Command Handlers
+  // ===========================================================================
+  /**
+   * Initialize a new workflow
+   */
+  cmdInit(description) {
+    try {
+      const steps = this.getSteps();
+      const taskId = this.generateTaskId(description);
+      const state = {
+        taskId,
+        description,
+        currentStep: steps[0],
+        stepIndex: 1,
+        totalSteps: steps.length,
+        status: "awaiting_spec",
+        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      };
+      this.saveState(state);
+      return this.responseStep(state);
+    } catch (e) {
+      return this.responseError(e.message);
+    }
+  }
+  /**
+   * Mark current step as done, check for questions or go to approve
+   */
+  cmdDone(taskId) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
+    }
+    const specPath = this.getSpecPath(taskId, state.currentStep);
+    if (!existsSync4(specPath)) {
+      return this.responseError(`Spec not found: ${specPath}`, taskId, state.currentStep);
+    }
+    const questions = this.checkUnresolvedQuestions(specPath);
+    if (questions.length > 0) {
+      state.status = "awaiting_clarify";
+      this.saveState(state);
+      return this.responseCheckpointClarify(state, questions);
+    }
+    state.status = "awaiting_approve";
+    this.saveState(state);
+    return this.responseCheckpointApprove(state);
+  }
+  /**
+   * Submit clarification answers
+   */
+  cmdClarified(taskId, answers) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
+    }
+    const specPath = this.getSpecPath(taskId, state.currentStep);
+    if (existsSync4(specPath)) {
+      const content = readFileSync(specPath, "utf-8");
+      const { content: body, data } = matter(content);
+      if (data.open_questions && Array.isArray(data.open_questions)) {
+        data.open_questions = data.open_questions.map((q, i) => ({
+          ...q,
+          resolved: true,
+          answer: answers.find((a) => a.questionId === `q${i + 1}`)?.answer
+        }));
+      }
+      writeFileSync3(specPath, matter.stringify(body, data));
+    }
+    state.status = "awaiting_spec";
+    state.revisionFeedback = `Answers provided: ${JSON.stringify(answers)}`;
+    this.saveState(state);
+    return this.responseStep(state);
+  }
+  /**
+   * Approve current step and move to next
+   */
+  cmdApprove(taskId) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
+    }
+    const steps = this.getSteps();
+    const specPath = this.getSpecPath(taskId, state.currentStep);
+    if (existsSync4(specPath)) {
+      const content = readFileSync(specPath, "utf-8");
+      const { content: body, data } = matter(content);
+      data.status = "approved";
+      data.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+      writeFileSync3(specPath, matter.stringify(body, data));
+    }
+    if (state.stepIndex < state.totalSteps) {
+      state.currentStep = steps[state.stepIndex];
+      state.stepIndex += 1;
+      state.status = "awaiting_spec";
+      state.revisionFeedback = void 0;
+      this.saveState(state);
+      return this.responseStep(state);
+    } else {
+      state.status = "completed";
+      this.saveState(state);
+      return this.responseComplete(state, "completed");
+    }
+  }
+  /**
+   * Request revision with feedback
+   */
+  cmdRevise(taskId, feedback) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
+    }
+    state.status = "awaiting_spec";
+    state.revisionFeedback = feedback;
+    this.saveState(state);
+    return this.responseStep(state);
+  }
+  /**
+   * Reject and stop workflow
+   */
+  cmdReject(taskId) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
+    }
+    const specPath = this.getSpecPath(taskId, state.currentStep);
+    if (existsSync4(specPath)) {
+      const content = readFileSync(specPath, "utf-8");
+      const { content: body, data } = matter(content);
+      data.status = "rejected";
+      data.updated_at = (/* @__PURE__ */ new Date()).toISOString();
+      writeFileSync3(specPath, matter.stringify(body, data));
+    }
+    state.status = "rejected";
+    this.saveState(state);
+    return this.responseComplete(state, "rejected");
+  }
+  /**
+   * Stop workflow (can resume later)
+   */
+  cmdStop(taskId) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
+    }
+    state.status = "stopped";
+    this.saveState(state);
+    return this.responseComplete(state, "stopped");
+  }
+  /**
+   * Get current workflow status
+   */
+  cmdStatus(taskId) {
+    const state = this.loadState(taskId);
+    if (!state) {
+      return this.responseError(`No workflow found: ${taskId}`, taskId);
+    }
+    switch (state.status) {
+      case "awaiting_spec":
+        return this.responseStep(state);
+      case "awaiting_clarify": {
+        const questions = this.checkUnresolvedQuestions(this.getSpecPath(taskId, state.currentStep));
+        return this.responseCheckpointClarify(state, questions);
+      }
+      case "awaiting_approve":
+        return this.responseCheckpointApprove(state);
+      case "completed":
+      case "stopped":
+      case "rejected":
+        return this.responseComplete(state, state.status);
+      default:
+        return this.responseError(`Unknown status: ${state.status}`, taskId);
+    }
+  }
+};
+
+// src/commands/orchestrate.ts
+function outputJSON(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function outputError(error) {
+  console.log(JSON.stringify({ type: "error", error }, null, 2));
+  process.exit(1);
+}
+async function orchestrateCommand(action, args) {
+  try {
+    const orchestrator = new Orchestrator();
+    switch (action) {
+      case "init": {
+        const description = args[0];
+        if (!description) {
+          outputError("Description is required for init");
+          return;
+        }
+        const result = orchestrator.cmdInit(description);
+        outputJSON(result);
+        break;
+      }
+      case "done": {
+        const taskId = args[0];
+        if (!taskId) {
+          outputError("Task ID is required for done");
+          return;
+        }
+        const result = orchestrator.cmdDone(taskId);
+        outputJSON(result);
+        break;
+      }
+      case "clarified": {
+        const taskId = args[0];
+        const answersJson = args[1];
+        if (!taskId || !answersJson) {
+          outputError("Task ID and answers JSON are required for clarified");
+          return;
+        }
+        let answers;
+        try {
+          answers = JSON.parse(answersJson);
+        } catch {
+          outputError("Invalid JSON for answers");
+          return;
+        }
+        const result = orchestrator.cmdClarified(taskId, answers);
+        outputJSON(result);
+        break;
+      }
+      case "approve": {
+        const taskId = args[0];
+        if (!taskId) {
+          outputError("Task ID is required for approve");
+          return;
+        }
+        const result = orchestrator.cmdApprove(taskId);
+        outputJSON(result);
+        break;
+      }
+      case "revise": {
+        const taskId = args[0];
+        const feedback = args[1];
+        if (!taskId || !feedback) {
+          outputError("Task ID and feedback are required for revise");
+          return;
+        }
+        const result = orchestrator.cmdRevise(taskId, feedback);
+        outputJSON(result);
+        break;
+      }
+      case "reject": {
+        const taskId = args[0];
+        if (!taskId) {
+          outputError("Task ID is required for reject");
+          return;
+        }
+        const result = orchestrator.cmdReject(taskId);
+        outputJSON(result);
+        break;
+      }
+      case "stop": {
+        const taskId = args[0];
+        if (!taskId) {
+          outputError("Task ID is required for stop");
+          return;
+        }
+        const result = orchestrator.cmdStop(taskId);
+        outputJSON(result);
+        break;
+      }
+      case "status": {
+        const taskId = args[0];
+        if (!taskId) {
+          outputError("Task ID is required for status");
+          return;
+        }
+        const result = orchestrator.cmdStatus(taskId);
+        outputJSON(result);
+        break;
+      }
+      default:
+        outputError(`Unknown action: ${action}. Valid actions: init, done, clarified, approve, revise, reject, stop, status`);
+    }
+  } catch (e) {
+    outputError(e.message);
+  }
+}
 
 // src/index.ts
 var program = new Command();
-program.name("spets").description("Spec Driven Development Execution Framework").version("0.1.0");
+program.name("spets").description("Spec Driven Development Execution Framework").version("0.1.3");
 program.command("init").description("Initialize spets in current directory").option("-f, --force", "Overwrite existing config").option("--github", "Add GitHub Actions workflow for PR/Issue integration").action(initCommand);
 program.command("status").description("Show current workflow status").option("-t, --task <taskId>", "Show status for specific task").action(statusCommand);
-program.command("start").description("Start a new workflow").argument("<query>", "User query describing the task").option("-p, --platform <platform>", "Platform to use (cli, github)", "cli").option("--owner <owner>", "GitHub owner (for github platform)").option("--repo <repo>", "GitHub repo (for github platform)").option("--pr <number>", "GitHub PR number (for github platform)").option("--issue <number>", "GitHub issue number (for github platform)").action(startCommand);
+program.command("start").description("Start a new workflow").argument("<query>", "User query describing the task").option("--github", "Use GitHub platform (reads owner/repo from config or git remote)").option("--issue [number]", "Use or create GitHub Issue (optional: specify existing issue number)").option("--pr [number]", "Use or create GitHub PR (optional: specify existing PR number)").action(startCommand);
 program.command("resume").description("Resume paused workflow").option("-t, --task <taskId>", "Resume specific task").option("--approve", "Approve current document and proceed").option("--revise <feedback>", "Request revision with feedback").action(resumeCommand);
-program.command("github").description("Handle GitHub Action callback (internal)").option("--owner <owner>", "GitHub owner (or set in .spets/config.yml)").option("--repo <repo>", "GitHub repo (or set in .spets/config.yml)").option("--pr <number>", "PR number (or set defaultPr in .spets/config.yml)").option("--issue <number>", "Issue number (or set defaultIssue in .spets/config.yml)").option("-t, --task <taskId>", "Task ID").requiredOption("--comment <comment>", "Comment body").action(githubCommand);
+program.command("github").description("Handle GitHub Action callback (internal)").option("--pr <number>", "PR number").option("--issue <number>", "Issue number").option("-t, --task <taskId>", "Task ID").requiredOption("--comment <comment>", "Comment body").action(githubCommand);
 program.command("plugin").description("Manage plugins").argument("<action>", "Action: install, uninstall, list").argument("[name]", "Plugin name").action(pluginCommand);
+program.command("orchestrate").description("Workflow orchestration (JSON API for Claude Code)").argument("<action>", "Action: init, done, clarified, approve, revise, reject, stop, status").argument("[args...]", "Action arguments").action(orchestrateCommand);
 program.parse();