agile-context-engineering 0.5.0 → 0.5.1

package/skills/review-story/SKILL.md

@@ -1,100 +1,99 @@
----
-name: review-story
-description: Standalone code review -- performs 3-level artifact verification, anti-pattern detection, coding standards enforcement, and tech debt discovery against a story's implementation
-argument-hint: "story=<file-path|github-url>"
-disable-model-invocation: true
-allowed-tools: Read, Bash, Glob, Grep
-model: sonnet
-effort: high
-context: fork
-agent: ace-code-reviewer
----
-
-# Review Story
-
-Review a story's implementation directly -- performing 3-level artifact verification, anti-pattern detection, coding standards enforcement, and tech debt discovery.
-
-## When to Use
-
-- After `/ace:execute-story` -- to re-run code review after manual changes
-- Anytime to review a story implementation standalone
-- When a story has been implemented and needs code review
-- Re-checking after manual changes post-execution
-- Verifying stories implemented outside ACE
-- Pre-merge quality gate
-
-## 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 Acceptance Criteria and Technical Solution.
-  - If not valid, stop and prompt the user.
-
-## 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) -- story document structure reference
-- **UI formatting**: Read `${CLAUDE_SKILL_DIR}/../../shared/utils/ui-formatting.md` -- ACE output formatting rules
-
-## Process
-
-Use the `ace-code-reviewer` agent for code review.
-
-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.
-
-Read all supporting resources listed above, then execute the workflow defined in [workflow.xml](workflow.xml) end-to-end.
-
-**CRITICAL REQUIREMENTS:**
-- Story MUST have Acceptance Criteria -- STOP if missing
-- Story MUST have Technical Solution -- STOP if missing
-- This is a READ-ONLY command -- do NOT modify any code
-- Coding standards violations are BLOCKERS, not warnings
-- Dead code and backwards-compatible shims must be flagged for DELETION
-
-The review process:
-1. Load story context (AC, Technical Solution, Out of Scope)
-2. Identify changed/created files related to the story
-3. Run 3-level artifact verification (EXISTS -> SUBSTANTIVE -> WIRED)
-4. Detect anti-patterns (dead code, stubs, TODOs, hardcoded values)
-5. Enforce coding standards (mandatory, blocker-level)
-6. Check AC coverage (all Gherkin scenarios implemented)
-7. Discover pre-existing tech debt in touched files
-8. Report results with structured format
-
-## Artifacts
-
-```
-No files modified -- this command is read-only.
-Outputs a structured review report to the conversation.
-```
-
-## Example Usage
-
-```
-# Review a story from a file path
-/ace:review-story \
-  story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
-
-# Review from a GitHub issue
-/ace:review-story \
-  story=https://github.com/owner/repo/issues/95
-
-# With just an issue number
-/ace:review-story story=#95
-```
-
-## Next Steps
-
-- `/ace:execute-story story=...` -- Re-execute to fix reported issues
-- `/ace:review-story story=...` -- Re-run review after fixes
-- `/ace:help` -- Check project status
+---
+name: review-story
+description: Standalone code review -- performs 3-level artifact verification, anti-pattern detection, coding standards enforcement, and tech debt discovery against a story's implementation
+argument-hint: "story=<file-path|github-url>"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Glob, Grep
+model: sonnet
+effort: high
+context: fork
+agent: ace-code-reviewer
+---
+
+## 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}/../../shared/utils/ui-formatting.md"`
+
+```xml
+<command>
+
+    <execution-time>
+        <runs-after>
+            <trigger>After /ace:execute-story — to re-run code review after manual changes</trigger>
+            <trigger>Anytime — to review a story implementation standalone</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A story has been implemented and needs code review</condition>
+            <condition>Re-checking after manual changes post-execution</condition>
+            <condition>Verifying stories implemented outside ACE</condition>
+            <condition>Pre-merge quality gate</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </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 Acceptance Criteria and 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>
+            Review a story's implementation directly (the session IS the reviewer):
+            1. Load story context (AC, Technical Solution, Out of Scope)
+            2. Identify changed/created files related to the story
+            3. Run 3-level artifact verification (EXISTS → SUBSTANTIVE → WIRED)
+            4. Detect anti-patterns (dead code, stubs, TODOs, hardcoded values)
+            5. Enforce coding standards (mandatory, blocker-level)
+            6. Check AC coverage (all Gherkin scenarios implemented)
+            7. Discover pre-existing tech debt in touched files
+            8. Report results with structured format
+        </objective>
+
+        <artifacts>
+            No files modified — this command is read-only.
+            Outputs a structured review report to the conversation.
+        </artifacts>
+    </output>
+
+    <process>
+        For this command use the `ace-code-reviewer` agent
+        that's specialized in code review.
+
+        Execute the review-story workflow from
+        `workflow.xml` end-to-end.
+
+        **CRITICAL REQUIREMENTS:**
+        - Story MUST have Acceptance Criteria — STOP if missing
+        - Story MUST have Technical Solution — STOP if missing
+        - This is a READ-ONLY command — do NOT modify any code
+        - Coding standards violations are BLOCKERS, not warnings
+        - Dead code and backwards-compatible shims must be flagged for DELETION
+    </process>
+
+    <example-usage>
+        ```

package/skills/review-story/script.js

@@ -15,7 +15,7 @@ const path = require('path');
 
 const {
   loadConfig, pathExists, safeReadFile, loadSettings, resolveModel,
-  execCommand, output, error,
+  execCommand, output, error, runSkillScript,
 } = require('../../shared/lib/ace-core');
 
 const {
@@ -26,18 +26,9 @@ const {
 
 // ─── 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').join(' ') || undefined);
-    break;
-  default:
-    error(`Unknown command: ${cmd}\nAvailable: init`);
-}
+runSkillScript({
+  init: cmdInit,
+});
 
 // ─── Init: Execute/Review Story ─────────────────────────────────────────────
 
@@ -53,7 +44,8 @@ switch (cmd) {
  * 6. computeStoryPaths
  * 7. Output JSON with all data
  */
-function cmdInit(cwd, raw, storyParam) {
+function cmdInit(cwd, raw, args, parsed) {
+  const storyParam = parsed.story || parsed._positional || null;
   const config = loadConfig(cwd);
 
   // ── Environment detection ──
@@ -70,9 +62,9 @@ function cmdInit(cwd, raw, storyParam) {
 
   // ── Agent teams detection (sync from runtime settings) ──
   // RUNTIME_CONFIG_DIR is not in shared libs — detect inline
-  // Try .claude first, then .opencode
+  // Try runtime settings files that can carry ACE agent-team state.
   let agent_teams = settings.agent_teams || false;
-  for (const configDir of ['.claude', '.opencode']) {
+  for (const configDir of ['.claude', '.codex', '.opencode']) {
     const claudeSettingsPath = path.join(cwd, configDir, 'settings.json');
     try {
       const claudeRaw = fs.readFileSync(claudeSettingsPath, 'utf-8');

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

@@ -1,169 +1,169 @@
-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('review-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**: Todo | **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',
-        '',
-        'Add a LoginButton component to the 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, 'Todo');
-      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.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');
-      assert.ok(result.story_content, 'should include story_content');
-    });
-
-    it('errors on init without story param', () => {
-      const result = JSON.parse(runScript('init', '', tmpDir));
-      assert.strictEqual(result.story_valid, 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('detects missing technical solution section', () => {
-      const storyContent = [
-        '# S2: Simple Story',
-        '**Feature**: F1 Test | **Epic**: E1 Test',
-        '**Status**: Todo | **Size**: 1 | **Sprint**: — | **Link**: —',
-        '',
-        '## Description',
-        '',
-        'A simple story without technical solution.',
-      ].join('\n');
-
-      const storyPath = createStoryFile(
-        tmpDir,
-        '.ace/artifacts/product/e1-test/f1-test/s2-simple-story/s2-simple-story.md',
-        storyContent
-      );
-
-      const result = JSON.parse(runScript('init', storyPath, tmpDir));
-
-      assert.strictEqual(result.story_valid, true);
-      assert.strictEqual(result.has_technical_solution, false);
-      assert.strictEqual(result.has_acceptance_criteria, false);
-    });
-  });
-
-  describe('error handling', () => {
-    it('errors on unknown command', () => {
-      assert.throws(() => {
-        execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
-      });
-    });
-  });
-});
+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('review-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**: Todo | **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',
+        '',
+        'Add a LoginButton component to the 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, 'Todo');
+      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.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');
+      assert.ok(result.story_content, 'should include story_content');
+    });
+
+    it('errors on init without story param', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+      assert.strictEqual(result.story_valid, 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('detects missing technical solution section', () => {
+      const storyContent = [
+        '# S2: Simple Story',
+        '**Feature**: F1 Test | **Epic**: E1 Test',
+        '**Status**: Todo | **Size**: 1 | **Sprint**: — | **Link**: —',
+        '',
+        '## Description',
+        '',
+        'A simple story without technical solution.',
+      ].join('\n');
+
+      const storyPath = createStoryFile(
+        tmpDir,
+        '.ace/artifacts/product/e1-test/f1-test/s2-simple-story/s2-simple-story.md',
+        storyContent
+      );
+
+      const result = JSON.parse(runScript('init', storyPath, tmpDir));
+
+      assert.strictEqual(result.story_valid, true);
+      assert.strictEqual(result.has_technical_solution, false);
+      assert.strictEqual(result.has_acceptance_criteria, false);
+    });
+  });
+
+  describe('error handling', () => {
+    it('errors on unknown command', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+  });
+});