agile-context-engineering 0.5.0 → 0.5.1

package/skills/execute-story/workflow.xml

@@ -17,7 +17,7 @@
     </purpose>
 
     <mandatory-context>
-        Read all files referenced by the invoking command's execution-context before starting.
+        All supporting resource files are auto-loaded in the skill prompt above. Do NOT re-read them.
         Also read any document or text passed as parameter ($ARGUMENTS) in the invoking command.
     </mandatory-context>
 
@@ -556,6 +556,8 @@
                     - Follow the plan step by step — do NOT skip steps or reorder
                     - After each significant step: run build check + test check
                     - NO commits — all changes stay as working tree changes
+                    - NEVER use node -e with Windows backslash paths in bash — backslashes
+                      get eaten as escape characters. Use the Read tool to read files.
                     - Auto-fix bugs, missing critical code, and blocking issues (Rules 1-3)
                     - For architectural changes beyond story scope (Rule 4): STOP and include
                       in your return report — main will ask the user

package/skills/help/SKILL.md

@@ -1,69 +1,71 @@
----
-name: help
-description: Check project initialization status and suggest next steps
-argument-hint: ""
-disable-model-invocation: false
-allowed-tools: Read, Bash, Write, AskUserQuestion
-model: sonnet
-effort: medium
----
-
-# Help
-
-Interactive state-checker, settings configurator, and guided router for project initialization. Detects which ACE documents exist, ensures settings are configured (including GitHub Project integration), displays a status dashboard, and offers to run missing setup commands.
-
-## When to Use
-
-- At any time to check which ACE documents exist and what to do next
-- At the start of a new project to see the initialization checklist
-- Returning to a project and want to check initialization status
-- Unsure which ACE command to run next
-
-## Input
-
-No parameters required.
-
-## Supporting Resources
-
-Read ALL of these before starting the workflow:
-
-- **Workflow**: Read [workflow.xml](workflow.xml) -- complete orchestration process with all steps
-- **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
-
-Execute the help workflow from [workflow.xml](workflow.xml) end-to-end.
-This is a lightweight state-check and routing workflow.
-
-CRITICAL MANDATORY STEP -- DO NOT SKIP:
-Before displaying the status dashboard, run:
-```bash
-node "${CLAUDE_SKILL_DIR}/script.js" sync-agent-teams --raw
-```
-Then you MUST use `AskUserQuestion` to ask the user whether they want to
-enable or disable Claude Code Agent Teams (experimental feature).
-This step is NOT optional. You MUST present this question every time.
-
-When the user chooses to enable or disable Agent Teams, you MUST run the
-bash command -- NEVER directly edit .ace/settings.json or .claude/settings.json:
-```bash
-node "${CLAUDE_SKILL_DIR}/script.js" write-agent-teams true
-```
-or
-```bash
-node "${CLAUDE_SKILL_DIR}/script.js" write-agent-teams false
-```
-The write-agent-teams command updates BOTH .ace/settings.json AND .claude/settings.json.
-Direct file edits will cause the two files to go out of sync.
-
-## Artifacts
-
-- `.ace/settings.json` (created on first run if missing)
-
-## Next Steps
-
-**Specialized commands for each document:**
-- `/ace:plan-product-vision` -- Create or update the product vision
-- `/ace:map-system` -- Map codebase structure, architecture, and testing framework
-- `/ace:init-coding-standards` -- Generate tailored coding standards
+---
+name: help
+description: Check project initialization status and suggest next steps
+argument-hint: ""
+disable-model-invocation: false
+allowed-tools: Read, Bash, Write, AskUserQuestion
+model: sonnet
+effort: medium
+---
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.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>At any time — to check which ACE documents exist and what to do next</trigger>
+            <trigger>At the start of a new project — to see the initialization checklist</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Starting a new project and want to see what needs to be set up</condition>
+            <condition>Returning to a project and want to check initialization status</condition>
+            <condition>Unsure which ACE command to run next</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+            </optional>
+        </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>
+            Detect which ACE documents exist (product vision, system architecture, system structure,
+            coding standards, testing framework). Display a status dashboard showing what's done
+            and what's missing. Suggest the next command to run based on gaps.
+        </objective>
+
+        <artifacts>
+            - .ace/settings.json (created on first run if missing)
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the help workflow from
+        `workflow.xml` end-to-end.
+        This is a lightweight state-check and routing workflow.
+
+        CRITICAL MANDATORY STEP — DO NOT SKIP:
+        Before displaying the status dashboard, you MUST run:
+        ```

package/skills/help/script.js

@@ -22,7 +22,7 @@ const path = require('path');
 const {
   loadConfig, pathExists, resolveModel,
   detectBrownfieldStatus, loadSettings, writeSettings,
-  output, error,
+  output, error, runSkillScript,
 } = require('../../shared/lib/ace-core');
 
 // ─── Runtime Config Dir ─────────────────────────────────────────────────────
@@ -31,7 +31,7 @@ const {
  * Detect the runtime config directory name.
  * In the plugin context, the script lives at:
  *   <base>/<config-dir>/skills/help/script.js
- * Default to '.claude' since the plugin always runs in Claude Code.
+ * Default to '.claude' for backwards compatibility.
  */
 function getRuntimeConfigDirName() {
   try {
@@ -39,7 +39,7 @@ function getRuntimeConfigDirName() {
     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') {
+    if (dirName === '.opencode' || dirName === '.codex' || dirName === '.claude') {
       return dirName;
     }
   } catch {}
@@ -50,40 +50,20 @@ 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);
-    break;
-  case 'ensure-settings':
-    cmdEnsureSettings(cwd, raw);
-    break;
-  case 'setup-github':
-    cmdSetupGithubProject(cwd, raw);
-    break;
-  case 'write-github-settings':
-    cmdWriteGithubSettings(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  case 'sync-agent-teams':
-    cmdSyncAgentTeams(cwd, raw);
-    break;
-  case 'write-agent-teams':
-    cmdWriteAgentTeamsSetting(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  case 'verify-path-exists': {
-    const targetPath = args[1];
+runSkillScript({
+  init: cmdInit,
+  'ensure-settings': (cwd, raw) => cmdEnsureSettings(cwd, raw),
+  'setup-github': (cwd, raw) => cmdSetupGithubProject(cwd, raw),
+  'write-github-settings': (cwd, raw, args) => cmdWriteGithubSettings(cwd, raw, args),
+  'sync-agent-teams': (cwd, raw) => cmdSyncAgentTeams(cwd, raw),
+  'write-agent-teams': (cwd, raw, args) => cmdWriteAgentTeamsSetting(cwd, raw, args),
+  'verify-path-exists': (cwd, raw, args, parsed) => {
+    const targetPath = parsed._positional || args[0];
     if (!targetPath) error('path required for verify-path-exists');
     const exists = pathExists(cwd, targetPath);
     output({ exists, path: targetPath }, raw, exists ? 'true' : 'false');
-    break;
-  }
-  default:
-    error(`Unknown command: ${cmd}\nAvailable: init, ensure-settings, setup-github, write-github-settings, sync-agent-teams, write-agent-teams, verify-path-exists`);
-}
+  },
+});
 
 // ─── Init: Help ─────────────────────────────────────────────────────────────
 
@@ -103,6 +83,7 @@ function cmdInit(cwd, raw) {
 
     // Config
     commit_docs: config.commit_docs,
+    runtime_config_dir: RUNTIME_CONFIG_DIR,
 
     // Existing state
     has_product_vision: pathExists(cwd, '.docs/product/product-vision.md'),
@@ -252,6 +233,17 @@ function cmdWriteGithubSettings(cwd, raw, extraArgs) {
 // ─── Sync Agent Teams ───────────────────────────────────────────────────────
 
 function cmdSyncAgentTeams(cwd, raw) {
+  if (RUNTIME_CONFIG_DIR === '.codex') {
+    const settings = loadSettings(cwd);
+    const wasDifferent = settings.agent_teams !== false;
+    if (wasDifferent) {
+      settings.agent_teams = false;
+      writeSettings(cwd, settings);
+    }
+    output({ agent_teams: false, synced: wasDifferent, runtime: 'codex' }, raw);
+    return;
+  }
+
   // Source of truth: runtime settings.json env var (e.g. .claude/settings.json)
   const claudeSettingsPath = path.join(cwd, RUNTIME_CONFIG_DIR, 'settings.json');
   let claudeEnabled = false;
@@ -280,9 +272,14 @@ function cmdSyncAgentTeams(cwd, raw) {
 function cmdWriteAgentTeamsSetting(cwd, raw, extraArgs) {
   const enabled = extraArgs[0] === 'true';
   const settings = loadSettings(cwd);
-  settings.agent_teams = enabled;
+  settings.agent_teams = RUNTIME_CONFIG_DIR === '.codex' ? false : enabled;
   writeSettings(cwd, settings);
 
+  if (RUNTIME_CONFIG_DIR === '.codex') {
+    output({ written: true, agent_teams: false, settings, runtime: 'codex' }, raw);
+    return;
+  }
+
   // Also update the project's runtime settings.json (e.g. .claude/)
   const claudeDir = path.join(cwd, RUNTIME_CONFIG_DIR);
   const claudeSettingsPath = path.join(claudeDir, 'settings.json');

package/skills/help/script.test.js

@@ -1,183 +1,183 @@
-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;
-}
-
-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('help script', () => {
-
-  describe('init', () => {
-    let tmpDir;
-
-    before(() => { tmpDir = createTestProject(); });
-    after(() => { cleanup(tmpDir); });
-
-    it('returns valid JSON with environment detection', () => {
-      const result = JSON.parse(runScript('init', '', tmpDir));
-
-      assert.strictEqual(typeof result.commit_docs, 'boolean');
-      assert.strictEqual(typeof result.has_git, 'boolean');
-      assert.strictEqual(typeof result.has_product_vision, 'boolean');
-      assert.strictEqual(typeof result.has_system_architecture, 'boolean');
-      assert.strictEqual(typeof result.has_system_structure, 'boolean');
-      assert.strictEqual(typeof result.has_coding_standards, 'boolean');
-      assert.strictEqual(typeof result.has_testing_framework, 'boolean');
-      assert.strictEqual(typeof result.is_brownfield, 'boolean');
-      assert.strictEqual(typeof result.is_greenfield, 'boolean');
-      assert.ok(result.product_owner_model, 'should have product_owner_model');
-    });
-
-    it('detects brownfield vs greenfield correctly', () => {
-      const result = JSON.parse(runScript('init', '', tmpDir));
-      assert.strictEqual(result.is_brownfield, !result.is_greenfield);
-    });
-  });
-
-  describe('ensure-settings', () => {
-    let tmpDir;
-
-    before(() => { tmpDir = createTestProject(); });
-    after(() => { cleanup(tmpDir); });
-
-    it('reports settings already exist when they do', () => {
-      const result = JSON.parse(runScript('ensure-settings', '', tmpDir));
-      assert.strictEqual(result.created, false);
-      assert.ok(result.settings);
-    });
-
-    it('creates settings when they do not exist', () => {
-      const freshDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
-      const aceDir = path.join(freshDir, '.ace');
-      fs.mkdirSync(aceDir, { recursive: true });
-      fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
-        version: '0.1.0',
-        projectName: 'test',
-        model_profile: 'balanced',
-        commit_docs: true,
-        github: { enabled: false },
-      }, null, 2));
-
-      const result = JSON.parse(runScript('ensure-settings', '', freshDir));
-      assert.strictEqual(result.created, true);
-      assert.ok(result.settings);
-      assert.strictEqual(result.settings.model_profile, 'balanced');
-
-      cleanup(freshDir);
-    });
-  });
-
-  describe('sync-agent-teams', () => {
-    let tmpDir;
-
-    before(() => { tmpDir = createTestProject(); });
-    after(() => { cleanup(tmpDir); });
-
-    it('returns agent_teams boolean', () => {
-      const result = JSON.parse(runScript('sync-agent-teams', '', tmpDir));
-      assert.strictEqual(typeof result.agent_teams, 'boolean');
-      assert.strictEqual(typeof result.synced, 'boolean');
-    });
-  });
-
-  describe('write-agent-teams', () => {
-    let tmpDir;
-
-    before(() => { tmpDir = createTestProject(); });
-    after(() => { cleanup(tmpDir); });
-
-    it('enables agent teams', () => {
-      const result = JSON.parse(runScript('write-agent-teams', 'true', tmpDir));
-      assert.strictEqual(result.written, true);
-      assert.strictEqual(result.agent_teams, true);
-
-      // Verify .ace/settings.json updated
-      const settings = JSON.parse(fs.readFileSync(path.join(tmpDir, '.ace', 'settings.json'), 'utf-8'));
-      assert.strictEqual(settings.agent_teams, true);
-    });
-
-    it('disables agent teams', () => {
-      const result = JSON.parse(runScript('write-agent-teams', 'false', tmpDir));
-      assert.strictEqual(result.written, true);
-      assert.strictEqual(result.agent_teams, false);
-
-      const settings = JSON.parse(fs.readFileSync(path.join(tmpDir, '.ace', 'settings.json'), 'utf-8'));
-      assert.strictEqual(settings.agent_teams, false);
-    });
-  });
-
-  describe('verify-path-exists', () => {
-    let tmpDir;
-
-    before(() => { tmpDir = createTestProject(); });
-    after(() => { cleanup(tmpDir); });
-
-    it('returns true for existing path', () => {
-      const result = runScript('verify-path-exists', '.ace/config.json --raw', tmpDir).trim();
-      assert.strictEqual(result, 'true');
-    });
-
-    it('returns false for non-existing path', () => {
-      const result = runScript('verify-path-exists', 'nonexistent/file.md --raw', tmpDir).trim();
-      assert.strictEqual(result, 'false');
-    });
-  });
-
-  describe('error handling', () => {
-    it('errors on unknown command', () => {
-      assert.throws(() => {
-        execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
-      });
-    });
-
-    it('errors on verify-path-exists without path', () => {
-      assert.throws(() => {
-        execSync(`node "${SCRIPT}" verify-path-exists`, { 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;
+}
+
+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('help script', () => {
+
+  describe('init', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns valid JSON with environment detection', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+
+      assert.strictEqual(typeof result.commit_docs, 'boolean');
+      assert.strictEqual(typeof result.has_git, 'boolean');
+      assert.strictEqual(typeof result.has_product_vision, 'boolean');
+      assert.strictEqual(typeof result.has_system_architecture, 'boolean');
+      assert.strictEqual(typeof result.has_system_structure, 'boolean');
+      assert.strictEqual(typeof result.has_coding_standards, 'boolean');
+      assert.strictEqual(typeof result.has_testing_framework, 'boolean');
+      assert.strictEqual(typeof result.is_brownfield, 'boolean');
+      assert.strictEqual(typeof result.is_greenfield, 'boolean');
+      assert.ok(result.product_owner_model, 'should have product_owner_model');
+    });
+
+    it('detects brownfield vs greenfield correctly', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+      assert.strictEqual(result.is_brownfield, !result.is_greenfield);
+    });
+  });
+
+  describe('ensure-settings', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('reports settings already exist when they do', () => {
+      const result = JSON.parse(runScript('ensure-settings', '', tmpDir));
+      assert.strictEqual(result.created, false);
+      assert.ok(result.settings);
+    });
+
+    it('creates settings when they do not exist', () => {
+      const freshDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+      const aceDir = path.join(freshDir, '.ace');
+      fs.mkdirSync(aceDir, { recursive: true });
+      fs.writeFileSync(path.join(aceDir, 'config.json'), JSON.stringify({
+        version: '0.1.0',
+        projectName: 'test',
+        model_profile: 'balanced',
+        commit_docs: true,
+        github: { enabled: false },
+      }, null, 2));
+
+      const result = JSON.parse(runScript('ensure-settings', '', freshDir));
+      assert.strictEqual(result.created, true);
+      assert.ok(result.settings);
+      assert.strictEqual(result.settings.model_profile, 'balanced');
+
+      cleanup(freshDir);
+    });
+  });
+
+  describe('sync-agent-teams', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns agent_teams boolean', () => {
+      const result = JSON.parse(runScript('sync-agent-teams', '', tmpDir));
+      assert.strictEqual(typeof result.agent_teams, 'boolean');
+      assert.strictEqual(typeof result.synced, 'boolean');
+    });
+  });
+
+  describe('write-agent-teams', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('enables agent teams', () => {
+      const result = JSON.parse(runScript('write-agent-teams', 'true', tmpDir));
+      assert.strictEqual(result.written, true);
+      assert.strictEqual(result.agent_teams, true);
+
+      // Verify .ace/settings.json updated
+      const settings = JSON.parse(fs.readFileSync(path.join(tmpDir, '.ace', 'settings.json'), 'utf-8'));
+      assert.strictEqual(settings.agent_teams, true);
+    });
+
+    it('disables agent teams', () => {
+      const result = JSON.parse(runScript('write-agent-teams', 'false', tmpDir));
+      assert.strictEqual(result.written, true);
+      assert.strictEqual(result.agent_teams, false);
+
+      const settings = JSON.parse(fs.readFileSync(path.join(tmpDir, '.ace', 'settings.json'), 'utf-8'));
+      assert.strictEqual(settings.agent_teams, false);
+    });
+  });
+
+  describe('verify-path-exists', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('returns true for existing path', () => {
+      const result = runScript('verify-path-exists', '.ace/config.json --raw', tmpDir).trim();
+      assert.strictEqual(result, 'true');
+    });
+
+    it('returns false for non-existing path', () => {
+      const result = runScript('verify-path-exists', 'nonexistent/file.md --raw', tmpDir).trim();
+      assert.strictEqual(result, 'false');
+    });
+  });
+
+  describe('error handling', () => {
+    it('errors on unknown command', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+
+    it('errors on verify-path-exists without path', () => {
+      assert.throws(() => {
+        execSync(`node "${SCRIPT}" verify-path-exists`, { encoding: 'utf-8', stdio: 'pipe' });
+      });
+    });
+  });
+});