agile-context-engineering 0.3.0 → 0.5.1

package/{commands/ace/execute-story.md → skills/execute-story/SKILL.md}

@@ -1,138 +1,116 @@
----
-name: ace: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]"
-allowed-tools:
-  - Read
-  - Bash
-  - Write
-  - Edit
-  - AskUserQuestion
-  - Glob
-  - Grep
-  - Agent
-  - EnterPlanMode
-  - ExitPlanMode
----
-
-```xml
-<command>
-
-    <execution-time>
-        <runs-after>
-            <trigger>After /ace:plan-story — once a story has AC + Technical Solution</trigger>
-            <trigger>Anytime — to execute a fully-planned story specification</trigger>
-        </runs-after>
-        <use-when>
-            <condition>A story has both Acceptance Criteria AND Technical Solution sections</condition>
-            <condition>Story status is "Refined" (ready for implementation)</condition>
-        </use-when>
-    </execution-time>
-
-    <input>
-        <flags>
-            <flag name="--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.
-            </flag>
-        </flags>
-
-        <parameters>
-            <required>
-                <param name="story" type="file | github-url">
-                    Story source — can be either:
-                    - **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).
-                </param>
-            </required>
-        </parameters>
-    </input>
-
-    <execution-context>
-        <execute-story-workflow>@~/.claude/agile-context-engineering/workflows/execute-story.xml</execute-story-workflow>
-        <story-template>@~/.claude/agile-context-engineering/templates/product/story.xml</story-template>
-        <walkthrough-template>@~/.claude/agile-context-engineering/templates/wiki/walkthrough.xml</walkthrough-template>
-        <questioning>@~/.claude/agile-context-engineering/utils/questioning.xml</questioning>
-        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
-    </execution-context>
-
-    <output>
-        <objective>
-            Take a fully-planned story (with AC + Technical Solution) and:
-            1. Create an execution plan via Claude Code Plan Mode
-            2. Execute the plan — solo or with Agent Teams
-            3. Run code review (3-level verification, anti-pattern detection, coding standards)
-            4. Present results to user for verification/approval
-            5. Commit implementation (single commit after approval)
-            6. Update state: story file, feature file, product backlog, GitHub
-            7. Trigger wiki mapping (background) with tech debt integration
-
-            Two execution modes:
-            - **Solo Mode** (default or --agent-teams-off): Single context, plan mode → execute
-            - **Agent Teams Mode** (when enabled + plan recommends): Lead + teammates for parallel work
-        </objective>
-
-        <artifacts>
-            Story file updated with Summary &amp; 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.
-        </artifacts>
-    </output>
-
-    <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 &amp; validate) is fully complete with the init command output parsed.**
-
-        Execute the execute-story workflow from
-        `@~/.claude/agile-context-engineering/workflows/execute-story.xml` end-to-end.
-
-        **MANDATORY FIRST ACTION: Run the init command (step 1.2) BEFORE doing anything else.
-        Do NOT read the story file manually. Do NOT explore the codebase. Do NOT start planning.
-        The init command 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
-    </process>
-
-    <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
-        ```
-    </example-usage>
-
-    <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
-    </next-steps>
-
-</command>
-```
+---
+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
+---
+
+## Environment Context (preprocessed)
+
+!`node "${CLAUDE_SKILL_DIR}/script.js" init "$ARGUMENTS" 2>/dev/null`
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/story-template.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/walkthrough-template.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/questioning.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md"`
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:plan-story — once a story has AC + Technical Solution</trigger>
+            <trigger>Anytime — to execute a fully-planned story specification</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A story has both Acceptance Criteria AND Technical Solution sections</condition>
+            <condition>Story status is "Refined" (ready for implementation)</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+            <flag name="--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.
+            </flag>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="story" type="file | github-url">
+                    Story source — can be either:
+                    - **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).
+                </param>
+            </required>
+        </parameters>
+    </input>
+
+    <execution-context>
+        <!-- All supporting files are auto-loaded in the Supporting Resources section above.
+             The model does NOT need to Read these files — they are already in context. -->
+    </execution-context>
+
+    <output>
+        <objective>
+            Take a fully-planned story (with AC + Technical Solution) and:
+            1. Create an execution plan via Claude Code Plan Mode
+            2. Execute the plan — solo or with Agent Teams
+            3. Run code review (3-level verification, anti-pattern detection, coding standards)
+            4. Present results to user for verification/approval
+            5. Commit implementation (single commit after approval)
+            6. Update state: story file, feature file, product backlog, GitHub
+            7. Trigger wiki mapping (background) with tech debt integration
+
+            Two execution modes:
+            - **Solo Mode** (default or --agent-teams-off): Single context, plan mode → execute
+            - **Agent Teams Mode** (when enabled + plan recommends): Lead + teammates for parallel work
+        </objective>
+
+        <artifacts>
+            Story file updated with Summary &amp; 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.
+        </artifacts>
+    </output>
+
+    <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 &amp; validate) is fully complete with the init command output parsed.**
+
+        Execute the execute-story workflow from
+        `workflow.xml` end-to-end.
+
+        **MANDATORY FIRST ACTION: Run the init command (step 1.2) BEFORE doing anything else.
+        Do NOT read the story file manually. Do NOT explore the codebase. Do NOT start planning.
+        The init command 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
+    </process>
+
+    <example-usage>
+        ```

package/skills/execute-story/script.js

@@ -0,0 +1,291 @@
+#!/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, runSkillScript,
+} = 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' for backwards compatibility.
+ */
+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 === '.codex' || dirName === '.claude') {
+      return dirName;
+    }
+  } catch {}
+  return '.claude';
+}
+
+const RUNTIME_CONFIG_DIR = getRuntimeConfigDirName();
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+runSkillScript({
+  init: cmdInit,
+  'update-state': (cwd, raw, args) => updateState(cwd, raw, args),
+  'sync-github': (cwd, raw, args) => syncStory(cwd, raw, args),
+  'resolve-model': (cwd, raw, args, parsed) => {
+    const agentType = parsed._positional || args[0];
+    if (!agentType) error('resolve-model requires agent-type argument');
+    const model = resolveModel(cwd, agentType);
+    output({ model, agent: agentType }, raw, 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, args, parsed) {
+  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 = parsed.story || parsed._positional || 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);
+}