agile-context-engineering 0.2.2 → 0.5.0

package/skills/execute-story/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: execute-story
+description: Execute a fully-planned story -- loads AC + Technical Solution, creates execution plan via Plan Mode, implements (solo or agent teams), runs code review, updates state, and triggers wiki mapping
+argument-hint: "story=<file-path|github-url> [--agent-teams-off]"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Write, Edit, AskUserQuestion, Glob, Grep, Agent, EnterPlanMode, ExitPlanMode
+model: opus
+effort: max
+---
+
+# Execute Story
+
+Orchestrate story execution: load a fully-planned story (with AC + Technical Solution), create an execution plan via Claude Code Plan Mode, execute the plan (solo or agent teams), run code review, present results for user verification, update state across all ACE artifacts, and trigger wiki mapping.
+
+## When to Use
+
+- After `/ace:plan-story` -- when a story has AC + Technical Solution
+- Anytime -- to execute a fully-planned story specification
+- When a story has both Acceptance Criteria AND Technical Solution sections
+- When story status is "Refined" (ready for implementation)
+
+## Input
+
+### Required
+
+- **`story`** -- Story source:
+  - **File path**: Path to a fully-planned story markdown file (must have AC + Technical Solution sections)
+  - **GitHub URL or issue number**: GitHub story reference
+  - Must be a valid, accessible file or GitHub issue.
+  - The story MUST have been through `/ace:plan-story` (has AC + Technical Solution).
+
+### Flags
+
+- **`--agent-teams-off`** -- Force solo execution mode regardless of agent_teams setting. Overrides the agent_teams flag in settings.json. Use when you want single-context execution even if teams are enabled.
+
+## Environment Context (preprocessed)
+
+!`node "${CLAUDE_SKILL_DIR}/script.js" init "$ARGUMENTS" 2>/dev/null`
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) -- complete orchestration process with all steps
+- **Story template**: Read [story-template.xml](story-template.xml) -- output format for the story specification
+- **Walkthrough template**: Read [walkthrough-template.xml](walkthrough-template.xml) -- walkthrough format for wiki docs
+- **Questioning guide**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml` -- deep questioning techniques
+- **UI formatting**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md` -- ACE output formatting rules
+
+## Process
+
+**STRICT WORKFLOW EXECUTION -- Follow the execute-story workflow STEP BY STEP.
+Do NOT skip steps. Do NOT improvise. Do NOT start reading code or planning
+until step 1 (init & validate) is fully complete with the init command output parsed.**
+
+Execute the execute-story workflow from [workflow.xml](workflow.xml) end-to-end.
+
+The Environment Context above contains the preprocessed INIT JSON -- use it directly instead of running the init script manually. The workflow's step 1 setup can skip the init bash call since that data is already available.
+
+**MANDATORY FIRST ACTION: Parse the preprocessed INIT JSON from Environment Context BEFORE doing anything else.
+Do NOT read the story file manually. Do NOT explore the codebase. Do NOT start planning.
+The init output validates the story and provides all paths and context needed.**
+
+**CRITICAL REQUIREMENTS:**
+- Story MUST have Acceptance Criteria -- STOP if missing
+- Story MUST have Technical Solution -- STOP if missing
+- NO intermediary commits during implementation
+- ONE single commit per story after user approval (code + state + docs)
+- Code review is MANDATORY -- blockers must be fixed before approval
+- Coding standards violations are BLOCKERS, not warnings
+- Dead code and backwards-compatible shims must be DELETED
+
+Two execution modes:
+- **Solo Mode** (default or --agent-teams-off): Single context, plan mode then execute
+- **Agent Teams Mode** (when enabled + plan recommends): Lead + teammates for parallel work
+
+## Artifacts
+
+Story file updated with Summary & State section and Wiki Updates section.
+Feature file updated with story status.
+Product backlog updated with story (and possibly feature) status.
+Wiki documents updated/created based on implementation changes.
+
+## Example Usage
+
+```
+# Execute a story from a file path
+/ace:execute-story \
+  story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
+
+# Execute from a GitHub issue
+/ace:execute-story \
+  story=https://github.com/owner/repo/issues/95
+
+# Force solo mode (no agent teams)
+/ace:execute-story \
+  story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md \
+  --agent-teams-off
+
+# With just an issue number
+/ace:execute-story story=#95
+```
+
+## Next Steps
+
+**After this command:**
+- `/ace:execute-story story=...` -- Execute the next story in the feature
+- `/ace:review-story story=...` -- Re-run code review (standalone)
+- `/ace:plan-story story=...` -- Plan the next story
+- `/ace:help` -- Check project status

package/skills/execute-story/script.js

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+
+/**
+ * execute-story skill script — Entry point for all ace-tools operations
+ * needed by the execute-story skill.
+ *
+ * Subcommands:
+ *   init [story-param]                Environment detection for execute-story workflow
+ *   update-state story=X status=Y     Update story status across files
+ *   sync-github repo=X story_file=Y   Sync story/feature to GitHub
+ *   resolve-model <agent-type>        Get model for agent based on profile
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  loadConfig, pathExists, safeReadFile, resolveModel,
+  loadSettings, execCommand, output, error,
+} = require('../../shared/lib/ace-core');
+
+const {
+  classifyStoryParam, extractStoryMetadata, extractStoryRequirements,
+  extractMarkdownSection, extractIssueNumber, extractIssueNumberFromFile,
+  computeStoryPaths, updateState,
+} = require('../../shared/lib/ace-story');
+
+const { syncStory } = require('../../shared/lib/ace-github');
+
+// ─── Runtime Config Dir ─────────────────────────────────────────────────────
+
+/**
+ * Detect the runtime config directory name.
+ * In the plugin context, the script lives at:
+ *   <base>/<config-dir>/skills/execute-story/script.js
+ * Default to '.claude' since the plugin always runs in Claude Code.
+ */
+function getRuntimeConfigDirName() {
+  try {
+    const skillDir = __dirname;                // <base>/<config-dir>/skills/execute-story
+    const skillsDir = path.dirname(skillDir);  // <base>/<config-dir>/skills
+    const configDir = path.dirname(skillsDir); // <base>/<config-dir>
+    const dirName = path.basename(configDir);
+    if (dirName === '.opencode' || dirName === '.claude') {
+      return dirName;
+    }
+  } catch {}
+  return '.claude';
+}
+
+const RUNTIME_CONFIG_DIR = getRuntimeConfigDirName();
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+const cwd = process.cwd();
+const args = process.argv.slice(2);
+const raw = args.includes('--raw');
+const cmd = args[0];
+
+switch (cmd) {
+  case 'init':
+    cmdInit(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'update-state':
+    updateState(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'sync-github':
+    syncStory(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
+    break;
+  case 'resolve-model': {
+    const agentType = args[1];
+    if (!agentType) error('resolve-model requires agent-type argument');
+    const model = resolveModel(cwd, agentType);
+    output({ model, agent: agentType }, raw, model);
+    break;
+  }
+  default:
+    error(`Unknown command: ${cmd}\nAvailable: init, update-state, sync-github, resolve-model`);
+}
+
+// ─── Init: Execute Story ────────────────────────────────────────────────────
+
+/**
+ * Environment detection for the execute-story workflow.
+ *
+ * Detects: git, gh CLI, GitHub project, agent teams, story source/content/metadata,
+ * acceptance criteria, technical solution, wiki refs, coding standards, computed paths.
+ */
+function cmdInit(cwd, raw, initArgs) {
+  const config = loadConfig(cwd);
+
+  // ── Environment detection ──
+  const has_git = pathExists(cwd, '.git');
+  const has_gh_cli = (() => {
+    try {
+      const { execSync } = require('child_process');
+      execSync('gh --version', { stdio: 'pipe' });
+      return true;
+    } catch { return false; }
+  })();
+  const settings = loadSettings(cwd);
+  const github_project = settings.github_project;
+
+  // ── Agent teams detection (sync from runtime settings) ──
+  const claudeSettingsPath = path.join(cwd, RUNTIME_CONFIG_DIR, 'settings.json');
+  let agent_teams = settings.agent_teams || false;
+  try {
+    const claudeRaw = fs.readFileSync(claudeSettingsPath, 'utf-8');
+    const claudeSettings = JSON.parse(claudeRaw);
+    const val = claudeSettings?.env?.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS;
+    agent_teams = val === '1' || val === 'true';
+  } catch {}
+
+  // ── Parse story param ──
+  const storyParam = initArgs.join(' ').trim() || null;
+
+  // ── Classify the story parameter ──
+  const classified = classifyStoryParam(storyParam);
+
+  // Early exit if invalid
+  if (classified.type === null || classified.type === 'invalid') {
+    output({
+      executor_model: resolveModel(cwd, 'ace-executor'),
+      reviewer_model: resolveModel(cwd, 'ace-code-reviewer'),
+      commit_docs: config.commit_docs,
+      has_git, has_gh_cli, github_project, agent_teams,
+      story_source: null,
+      story_valid: false,
+      story_error: classified.reason || 'No story parameter provided',
+      story_content: null,
+      story: { id: null, title: null, status: null, size: null },
+      feature: { id: null, title: null },
+      epic: { id: null, title: null },
+      has_acceptance_criteria: false,
+      acceptance_criteria_count: 0,
+      has_technical_solution: false,
+      has_wiki_refs: false,
+      has_coding_standards: false,
+      paths: null,
+    }, raw);
+    return;
+  }
+
+  // ── Load story content ──
+  let storyContent = null;
+  let storySource = classified.type === 'file' ? 'file' : 'github';
+  let storyError = null;
+  let storyFilePath = null;
+
+  if (classified.type === 'file') {
+    const resolvedPath = path.isAbsolute(classified.filePath)
+      ? classified.filePath
+      : path.join(cwd, classified.filePath);
+    if (!pathExists(cwd, classified.filePath)) {
+      storyError = `Story file not found: ${classified.filePath}`;
+    } else {
+      storyContent = safeReadFile(resolvedPath);
+      storyFilePath = classified.filePath;
+      if (!storyContent) storyError = `Could not read story file: ${classified.filePath}`;
+    }
+  } else {
+    // github-url or issue-number
+    if (!has_gh_cli) {
+      storyError = 'GitHub CLI (gh) not installed. Cannot fetch GitHub issues.';
+    } else {
+      const repo = classified.repo || (github_project.repo || null);
+      if (!repo) {
+        storyError = 'No repository configured. Provide a full GitHub URL or configure github_project.repo in settings.';
+      } else {
+        const ghResult = execCommand(
+          `gh issue view ${classified.issueNumber} --repo ${repo} --json title,body,labels,state`,
+          cwd
+        );
+        if (!ghResult) {
+          storyError = `Could not fetch GitHub issue #${classified.issueNumber} from ${repo}.`;
+        } else {
+          try {
+            const issue = JSON.parse(ghResult);
+            storyContent = issue.body || '';
+            if (storyContent && !storyContent.match(/^#\s+/m)) {
+              storyContent = `# ${issue.title}\n\n${storyContent}`;
+            }
+          } catch {
+            storyError = `Failed to parse GitHub issue response for #${classified.issueNumber}.`;
+          }
+        }
+      }
+    }
+  }
+
+  // ── Extract metadata & requirements ──
+  const metadata = extractStoryMetadata(storyContent);
+  const requirements = extractStoryRequirements(storyContent);
+
+  // ── Detect key sections ──
+  const has_acceptance_criteria = requirements.acceptance_criteria_count > 0;
+  const has_technical_solution = storyContent
+    ? !!extractMarkdownSection(storyContent, 'Technical Solution', 2)
+    : false;
+  const has_wiki_refs = storyContent
+    ? !!extractMarkdownSection(storyContent, 'Relevant Wiki', 2)
+    : false;
+  const has_coding_standards = pathExists(cwd, '.docs/wiki/system-wide/coding-standards.md');
+
+  // ── Compute paths ──
+  let paths = null;
+  let has_story_file = false;
+
+  if (storyFilePath) {
+    const resolvedPath = path.isAbsolute(storyFilePath)
+      ? storyFilePath
+      : path.join(cwd, storyFilePath);
+    const storyDir = path.dirname(resolvedPath);
+    const relStoryDir = path.relative(cwd, storyDir).replace(/\\/g, '/');
+    const storySlug = path.basename(storyDir);
+    const featureDir = path.dirname(storyDir);
+    const relFeatureDir = path.relative(cwd, featureDir).replace(/\\/g, '/');
+    const featureSlug = path.basename(featureDir);
+
+    paths = {
+      epic_slug: null,
+      feature_slug: featureSlug,
+      story_slug: storySlug,
+      story_dir: relStoryDir,
+      story_file: storyFilePath.replace(/\\/g, '/'),
+      external_analysis_file: `${relStoryDir}/external-analysis.md`,
+      integration_analysis_file: `${relStoryDir}/integration-analysis.md`,
+      feature_dir: relFeatureDir,
+      feature_file: `${relFeatureDir}/${featureSlug}.md`,
+      product_backlog: '.ace/artifacts/product/product-backlog.md',
+      coding_standards: '.docs/wiki/system-wide/coding-standards.md',
+    };
+    has_story_file = true;
+  } else if (metadata.epic.id && metadata.feature.id && metadata.id) {
+    const computed = computeStoryPaths(
+      metadata.epic.id, metadata.epic.title || '',
+      metadata.feature.id, metadata.feature.title || '',
+      metadata.id, metadata.title || ''
+    );
+    if (computed) {
+      paths = {
+        ...computed,
+        product_backlog: '.ace/artifacts/product/product-backlog.md',
+        coding_standards: '.docs/wiki/system-wide/coding-standards.md',
+      };
+      has_story_file = pathExists(cwd, paths.story_file);
+    }
+  }
+
+  // ── Extract GitHub issue numbers ──
+  const storyIssueNumber = extractIssueNumber(metadata.link);
+  const featureIssueNumber = paths ? extractIssueNumberFromFile(cwd, paths.feature_file) : null;
+
+  // ── Build result ──
+  const result = {
+    // Models
+    executor_model: resolveModel(cwd, 'ace-executor'),
+    reviewer_model: resolveModel(cwd, 'ace-code-reviewer'),
+
+    // Config
+    commit_docs: config.commit_docs,
+
+    // Environment
+    has_git, has_gh_cli, github_project, agent_teams,
+
+    // Story source
+    story_source: storySource,
+    story_valid: storyContent !== null && storyError === null,
+    story_error: storyError,
+
+    // Raw story content
+    story_content: storyContent,
+
+    // Story metadata
+    story: {
+      id: metadata.id,
+      title: metadata.title,
+      status: metadata.status,
+      size: metadata.size,
+      issue_number: storyIssueNumber,
+    },
+    feature: {
+      ...metadata.feature,
+      issue_number: featureIssueNumber,
+    },
+    epic: metadata.epic,
+
+    // Section detection
+    has_acceptance_criteria,
+    acceptance_criteria_count: requirements.acceptance_criteria_count,
+    has_technical_solution,
+    has_wiki_refs,
+    has_coding_standards,
+
+    // Computed paths
+    paths,
+
+    // Artifact existence
+    has_story_file,
+  };
+
+  output(result, raw);
+}

package/skills/execute-story/script.test.js

@@ -0,0 +1,261 @@
+const { describe, it, before, after } = require('node:test');
+const assert = require('node:assert');
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const SCRIPT = path.join(__dirname, 'script.js');
+
+/**
+ * Create a minimal ACE project structure in a temp directory.
+ */
+function createTestProject() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+
+  // .ace/config.json
+  const aceDir = path.join(tmpDir, '.ace');
+  fs.mkdirSync(aceDir, { recursive: true });
+  fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
+    version: '0.1.0',
+    projectName: 'test-project',
+    model_profile: 'quality',
+    commit_docs: true,
+    github: { enabled: false },
+  }, null, 2));
+
+  // .ace/settings.json
+  fs.writeFileSync(path.join(aceDir, 'settings.json'), JSON.stringify({
+    model_profile: 'quality',
+    commit_docs: true,
+    agent_teams: false,
+    github_project: { enabled: false, gh_installed: false, repo: '', project_number: null, owner: '' },
+  }, null, 2));
+
+  return tmpDir;
+}
+
+/**
+ * Create a story file in the test project.
+ */
+function createStoryFile(tmpDir, relPath, content) {
+  const fullPath = path.join(tmpDir, relPath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, content, 'utf-8');
+  return relPath;
+}
+
+function runScript(subcommand, args, cwd) {
+  return execSync(`node "${SCRIPT}" ${subcommand} ${args}`, {
+    cwd,
+    encoding: 'utf-8',
+    timeout: 10000,
+  });
+}
+
+function cleanup(tmpDir) {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe('execute-story script', () => {
+
+  describe('init', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns valid JSON with environment detection for a story file', () => {
+      const storyContent = [
+        '# S1: Add Login Button',
+        '**Feature**: F1 User Auth | **Epic**: E1 Platform',
+        '**Status**: Refined | **Size**: 3 | **Sprint**: — | **Link**: —',
+        '',
+        '## User Story',
+        '',
+        '> As a user,',
+        '> I want to click a login button,',
+        '> so that I can access my account.',
+        '',
+        '## Description',
+        '',
+        'Adds a login button to the header.',
+        '',
+        '## Acceptance Criteria',
+        '',
+        '### Scenario: Click login button',
+        '',
+        '**Given** the user is on the homepage',
+        '**When** they click "Login"',
+        '**Then** they see the login form',
+        '',
+        '## Technical Solution',
+        '',
+        '### Architecture',
+        '',
+        'Simple button component in the header.',
+        '',
+        '### Implementation Plan',
+        '',
+        '1. Create LoginButton component',
+        '2. Add to Header',
+      ].join('\n');
+
+      const storyPath = createStoryFile(
+        tmpDir,
+        '.ace/artifacts/product/e1-platform/f1-user-auth/s1-add-login-button/s1-add-login-button.md',
+        storyContent
+      );
+
+      const result = JSON.parse(runScript('init', storyPath, tmpDir));
+
+      assert.ok(result.executor_model, 'should have executor_model');
+      assert.ok(result.reviewer_model, 'should have reviewer_model');
+      assert.strictEqual(result.story_valid, true, 'story should be valid');
+      assert.strictEqual(result.story_source, 'file');
+      assert.strictEqual(result.story.id, 'S1');
+      assert.strictEqual(result.story.title, 'Add Login Button');
+      assert.strictEqual(result.story.status, 'Refined');
+      assert.strictEqual(result.has_acceptance_criteria, true);
+      assert.strictEqual(result.acceptance_criteria_count, 1);
+      assert.strictEqual(result.has_technical_solution, true);
+      assert.ok(result.paths, 'should have computed paths');
+      assert.ok(result.paths.story_file.includes('s1-add-login-button'));
+      assert.ok(result.paths.product_backlog);
+      assert.ok(result.paths.coding_standards);
+      assert.strictEqual(result.has_story_file, true);
+      assert.strictEqual(typeof result.commit_docs, 'boolean');
+      assert.strictEqual(typeof result.has_git, 'boolean');
+      assert.strictEqual(typeof result.agent_teams, 'boolean');
+    });
+
+    it('returns invalid when story has no AC', () => {
+      const storyContent = [
+        '# S2: No AC Story',
+        '**Feature**: F1 Test Feature | **Epic**: E1 Test Epic',
+        '**Status**: Todo | **Size**: 3 | **Sprint**: — | **Link**: —',
+        '',
+        '## Description',
+        '',
+        'A story without acceptance criteria.',
+      ].join('\n');
+
+      const storyPath = createStoryFile(
+        tmpDir,
+        '.ace/artifacts/product/e1-test-epic/f1-test-feature/s2-no-ac/s2-no-ac.md',
+        storyContent
+      );
+
+      const result = JSON.parse(runScript('init', storyPath, tmpDir));
+
+      assert.strictEqual(result.story_valid, true);
+      assert.strictEqual(result.has_acceptance_criteria, false);
+      assert.strictEqual(result.acceptance_criteria_count, 0);
+      assert.strictEqual(result.has_technical_solution, false);
+    });
+
+    it('handles non-existent story file gracefully', () => {
+      const result = JSON.parse(runScript('init', 'nonexistent/story.md', tmpDir));
+
+      assert.strictEqual(result.story_valid, false);
+      assert.ok(result.story_error.includes('not found'));
+    });
+
+    it('returns invalid with no story parameter', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+
+      assert.strictEqual(result.story_valid, false);
+      assert.ok(result.story_error);
+    });
+  });
+
+  describe('resolve-model', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns a model string with --raw', () => {
+      const result = runScript('resolve-model', 'ace-executor --raw', tmpDir).trim();
+      assert.match(result, /^(opus|sonnet|haiku)$/);
+    });
+
+    it('returns JSON without --raw', () => {
+      const result = JSON.parse(runScript('resolve-model', 'ace-executor', tmpDir));
+      assert.ok(result.model);
+      assert.strictEqual(result.agent, 'ace-executor');
+    });
+
+    it('returns correct model for reviewer', () => {
+      const result = runScript('resolve-model', 'ace-code-reviewer --raw', tmpDir).trim();
+      assert.match(result, /^(opus|sonnet|haiku)$/);
+    });
+  });
+
+  describe('update-state', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('updates story status in the story file', () => {
+      const storyContent = [
+        '# S1: Test Story',
+        '**Feature**: F1 Test Feature | **Epic**: E1 Test Epic',
+        '**Status**: Refined | **Size**: 3 | **Sprint**: — | **Link**: —',
+      ].join('\n');
+
+      const storyPath = createStoryFile(
+        tmpDir,
+        '.ace/artifacts/product/e1-test-epic/f1-test-feature/s1-test-story/s1-test-story.md',
+        storyContent
+      );
+
+      const result = JSON.parse(runScript('update-state', `story=${storyPath} status=Done`, tmpDir));
+
+      assert.strictEqual(result.story_updated, true);
+      assert.strictEqual(result.new_status, 'Done');
+
+      // Verify file was actually updated
+      const updated = fs.readFileSync(path.join(tmpDir, storyPath), 'utf-8');
+      assert.ok(updated.includes('**Status**: Done'));
+    });
+
+    it('normalizes InProgress to "In Progress"', () => {
+      const storyContent = [
+        '# S2: Another Story',
+        '**Feature**: F1 Test Feature | **Epic**: E1 Test Epic',
+        '**Status**: Refined | **Size**: 2 | **Sprint**: — | **Link**: —',
+      ].join('\n');
+
+      const storyPath = createStoryFile(
+        tmpDir,
+        '.ace/artifacts/product/e1-test-epic/f1-test-feature/s2-another-story/s2-another-story.md',
+        storyContent
+      );
+
+      const result = JSON.parse(runScript('update-state', `story=${storyPath} status=InProgress`, tmpDir));
+
+      assert.strictEqual(result.new_status, 'In Progress');
+
+      const updated = fs.readFileSync(path.join(tmpDir, storyPath), 'utf-8');
+      assert.ok(updated.includes('**Status**: In Progress'));
+    });
+  });
+
+  describe('error handling', () => {
+    it('errors on unknown command', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+
+    it('errors on resolve-model without agent type', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" resolve-model`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+  });
+});