agile-context-engineering 0.5.0 → 0.5.1

package/skills/plan-feature/script.js

@@ -1,148 +1,131 @@
-#!/usr/bin/env node
-
-/**
- * plan-feature skill script — Entry point for ace-tools operations
- * needed by the plan-feature skill.
- *
- * Subcommands:
- *   init [args]              Environment detection for plan-feature workflow
- *   resolve-fields [args]    Resolve GitHub Project field IDs
- *   create-issue [args]      Create a GitHub issue in a project
- *   update-issue [args]      Update a GitHub issue
- *   generate-slug <text>     Generate a URL-safe slug from text
- *   verify-path-exists <path> Check if a file/directory exists
- *
- * Usage: node script.js <subcommand> [args] [--raw]
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const {
-  loadConfig, pathExists, generateSlug, resolveModel,
-  detectBrownfieldStatus, loadSettings, output, error,
-} = require('../../shared/lib/ace-core');
-
-const {
-  resolveFields, createIssue, updateIssue,
-} = require('../../shared/lib/ace-github');
-
-// ─── 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 'resolve-fields':
-    resolveFields(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  case 'create-issue':
-    createIssue(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  case 'update-issue':
-    updateIssue(cwd, raw, args.slice(1).filter(a => a !== '--raw'));
-    break;
-  case 'generate-slug': {
-    const text = args.slice(1).filter(a => a !== '--raw').join(' ');
-    if (!text) error('generate-slug requires text argument');
-    const slug = generateSlug(text);
-    output({ slug }, raw, slug);
-    break;
-  }
-  case 'verify-path-exists': {
-    const targetPath = args.slice(1).filter(a => a !== '--raw').join(' ');
-    if (!targetPath) error('verify-path-exists requires path argument');
-    const exists = pathExists(cwd, targetPath);
-    output({ exists, path: targetPath }, raw, String(exists));
-    break;
-  }
-  default:
-    error(`Unknown command: ${cmd}\nAvailable: init, resolve-fields, create-issue, update-issue, generate-slug, verify-path-exists`);
-}
-
-// ─── Init: Plan Feature ─────────────────────────────────────────────────────
-
-function cmdInit(cwd, raw) {
-  const config = loadConfig(cwd);
-  const brownfield = detectBrownfieldStatus(cwd);
-
-  // Wiki detection — system-wide
-  const wikiSystemDir = '.docs/wiki/system-wide';
-  const has_wiki_system_wide = pathExists(cwd, wikiSystemDir);
-  const has_system_architecture = pathExists(cwd, path.join(wikiSystemDir, 'system-architecture.md'));
-  const has_system_structure = pathExists(cwd, path.join(wikiSystemDir, 'system-structure.md'));
-  const has_testing_framework = pathExists(cwd, path.join(wikiSystemDir, 'testing-framework.md'));
-
-  // Wiki detection — subsystems
-  const wikiSubsystemsDir = '.docs/wiki/subsystems';
-  const has_wiki_subsystems = pathExists(cwd, wikiSubsystemsDir);
-
-  let wiki_subsystem_names = [];
-  if (has_wiki_subsystems) {
-    try {
-      const entries = fs.readdirSync(path.join(cwd, wikiSubsystemsDir), { withFileTypes: true });
-      wiki_subsystem_names = entries
-        .filter(e => e.isDirectory())
-        .map(e => e.name);
-    } catch {}
-  }
-
-  const has_wiki = has_wiki_system_wide || has_wiki_subsystems;
-
-  const result = {
-    // Models
-    product_owner_model: resolveModel(cwd, 'ace-product-owner'),
-    researcher_model: resolveModel(cwd, 'ace-project-researcher'),
-
-    // Config
-    commit_docs: config.commit_docs,
-
-    // Product artifacts
-    has_product_vision: pathExists(cwd, '.docs/product/product-vision.md'),
-    has_product_backlog: pathExists(cwd, '.ace/artifacts/product/product-backlog.md'),
-
-    // Wiki analysis cache (from previous runs)
-    has_wiki_analysis: pathExists(cwd, '.ace/artifacts/wiki/wiki-analysis.md'),
-
-    // Brownfield detection
-    ...brownfield,
-
-    // Wiki state — system-wide
-    has_wiki,
-    has_wiki_system_wide,
-    has_system_architecture,
-    has_system_structure,
-    has_testing_framework,
-
-    // Wiki state — subsystems
-    has_wiki_subsystems,
-    wiki_subsystem_names,
-
-    // Git state
-    has_git: pathExists(cwd, '.git'),
-
-    // GitHub CLI
-    has_gh_cli: (() => {
-      try {
-        const { execSync } = require('child_process');
-        execSync('gh --version', { stdio: 'pipe' });
-        return true;
-      } catch {
-        return false;
-      }
-    })(),
-
-    // GitHub Project settings (from settings.json)
-    github_project: (() => {
-      const settings = loadSettings(cwd);
-      return settings.github_project;
-    })(),
-  };
-
-  output(result, raw);
-}
+#!/usr/bin/env node
+
+/**
+ * plan-feature skill script — Entry point for ace-tools operations
+ * needed by the plan-feature skill.
+ *
+ * Subcommands:
+ *   init [args]              Environment detection for plan-feature workflow
+ *   resolve-fields [args]    Resolve GitHub Project field IDs
+ *   create-issue [args]      Create a GitHub issue in a project
+ *   update-issue [args]      Update a GitHub issue
+ *   generate-slug <text>     Generate a URL-safe slug from text
+ *   verify-path-exists <path> Check if a file/directory exists
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  loadConfig, pathExists, generateSlug, resolveModel,
+  detectBrownfieldStatus, loadSettings, output, error, runSkillScript,
+} = require('../../shared/lib/ace-core');
+
+const {
+  resolveFields, createIssue, updateIssue,
+} = require('../../shared/lib/ace-github');
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+runSkillScript({
+  init: cmdInit,
+  'resolve-fields': (cwd, raw, args) => resolveFields(cwd, raw, args),
+  'create-issue': (cwd, raw, args) => createIssue(cwd, raw, args),
+  'update-issue': (cwd, raw, args) => updateIssue(cwd, raw, args),
+  'generate-slug': (cwd, raw, args, parsed) => {
+    const text = parsed._positional || args.join(' ');
+    if (!text) error('generate-slug requires text argument');
+    const slug = generateSlug(text);
+    output({ slug }, raw, slug);
+  },
+  'verify-path-exists': (cwd, raw, args, parsed) => {
+    const targetPath = parsed._positional || args.join(' ');
+    if (!targetPath) error('verify-path-exists requires path argument');
+    const exists = pathExists(cwd, targetPath);
+    output({ exists, path: targetPath }, raw, String(exists));
+  },
+});
+
+// ─── Init: Plan Feature ─────────────────────────────────────────────────────
+
+function cmdInit(cwd, raw, args, parsed) {
+  const config = loadConfig(cwd);
+  const brownfield = detectBrownfieldStatus(cwd);
+
+  // Wiki detection — system-wide
+  const wikiSystemDir = '.docs/wiki/system-wide';
+  const has_wiki_system_wide = pathExists(cwd, wikiSystemDir);
+  const has_system_architecture = pathExists(cwd, path.join(wikiSystemDir, 'system-architecture.md'));
+  const has_system_structure = pathExists(cwd, path.join(wikiSystemDir, 'system-structure.md'));
+  const has_testing_framework = pathExists(cwd, path.join(wikiSystemDir, 'testing-framework.md'));
+
+  // Wiki detection — subsystems
+  const wikiSubsystemsDir = '.docs/wiki/subsystems';
+  const has_wiki_subsystems = pathExists(cwd, wikiSubsystemsDir);
+
+  let wiki_subsystem_names = [];
+  if (has_wiki_subsystems) {
+    try {
+      const entries = fs.readdirSync(path.join(cwd, wikiSubsystemsDir), { withFileTypes: true });
+      wiki_subsystem_names = entries
+        .filter(e => e.isDirectory())
+        .map(e => e.name);
+    } catch {}
+  }
+
+  const has_wiki = has_wiki_system_wide || has_wiki_subsystems;
+
+  const result = {
+    // Models
+    product_owner_model: resolveModel(cwd, 'ace-product-owner'),
+    researcher_model: resolveModel(cwd, 'ace-project-researcher'),
+
+    // Config
+    commit_docs: config.commit_docs,
+
+    // Product artifacts
+    has_product_vision: pathExists(cwd, '.docs/product/product-vision.md'),
+    has_product_backlog: pathExists(cwd, '.ace/artifacts/product/product-backlog.md'),
+
+    // Wiki analysis cache (from previous runs)
+    has_wiki_analysis: pathExists(cwd, '.ace/artifacts/wiki/wiki-analysis.md'),
+
+    // Brownfield detection
+    ...brownfield,
+
+    // Wiki state — system-wide
+    has_wiki,
+    has_wiki_system_wide,
+    has_system_architecture,
+    has_system_structure,
+    has_testing_framework,
+
+    // Wiki state — subsystems
+    has_wiki_subsystems,
+    wiki_subsystem_names,
+
+    // Git state
+    has_git: pathExists(cwd, '.git'),
+
+    // GitHub CLI
+    has_gh_cli: (() => {
+      try {
+        const { execSync } = require('child_process');
+        execSync('gh --version', { stdio: 'pipe' });
+        return true;
+      } catch {
+        return false;
+      }
+    })(),
+
+    // GitHub Project settings (from settings.json)
+    github_project: (() => {
+      const settings = loadSettings(cwd);
+      return settings.github_project;
+    })(),
+  };
+
+  output(result, raw);
+}

package/skills/plan-feature/script.test.js

@@ -1,80 +1,80 @@
-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');
-
-function createTestProject() {
-  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
-
-  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));
-
-  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 });
-}
-
-describe('plan-feature script', () => {
-  it('errors on unknown command', () => {
-    assert.throws(() => {
-      execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
-    });
-  });
-
-  describe('init', () => {
-    let tmpDir;
-
-    before(() => { tmpDir = createTestProject(); });
-    after(() => { cleanup(tmpDir); });
-
-    it('init returns valid JSON', () => {
-      const result = JSON.parse(runScript('init', '', tmpDir));
-      assert.ok(typeof result === 'object');
-      assert.ok(result.product_owner_model, 'should have product_owner_model');
-      assert.ok(result.researcher_model, 'should have researcher_model');
-      assert.strictEqual(typeof result.commit_docs, 'boolean');
-      assert.strictEqual(typeof result.has_git, 'boolean');
-      assert.strictEqual(typeof result.is_brownfield, 'boolean');
-      assert.strictEqual(typeof result.has_product_vision, 'boolean');
-      assert.strictEqual(typeof result.has_product_backlog, 'boolean');
-      assert.strictEqual(typeof result.has_wiki, 'boolean');
-      assert.strictEqual(typeof result.has_gh_cli, 'boolean');
-      assert.ok(result.github_project !== undefined, 'should have github_project');
-    });
-
-    it('returns brownfield detection fields', () => {
-      const result = JSON.parse(runScript('init', '', tmpDir));
-      assert.strictEqual(typeof result.is_brownfield, 'boolean');
-      assert.strictEqual(typeof result.is_greenfield, 'boolean');
-      assert.strictEqual(result.is_brownfield, !result.is_greenfield);
-    });
-  });
-});
+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');
+
+function createTestProject() {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ace-test-'));
+
+  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));
+
+  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 });
+}
+
+describe('plan-feature script', () => {
+  it('errors on unknown command', () => {
+    assert.throws(() => {
+      execSync(`node "${SCRIPT}" bogus`, { encoding: 'utf-8', stdio: 'pipe' });
+    });
+  });
+
+  describe('init', () => {
+    let tmpDir;
+
+    before(() => { tmpDir = createTestProject(); });
+    after(() => { cleanup(tmpDir); });
+
+    it('init returns valid JSON', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+      assert.ok(typeof result === 'object');
+      assert.ok(result.product_owner_model, 'should have product_owner_model');
+      assert.ok(result.researcher_model, 'should have researcher_model');
+      assert.strictEqual(typeof result.commit_docs, 'boolean');
+      assert.strictEqual(typeof result.has_git, 'boolean');
+      assert.strictEqual(typeof result.is_brownfield, 'boolean');
+      assert.strictEqual(typeof result.has_product_vision, 'boolean');
+      assert.strictEqual(typeof result.has_product_backlog, 'boolean');
+      assert.strictEqual(typeof result.has_wiki, 'boolean');
+      assert.strictEqual(typeof result.has_gh_cli, 'boolean');
+      assert.ok(result.github_project !== undefined, 'should have github_project');
+    });
+
+    it('returns brownfield detection fields', () => {
+      const result = JSON.parse(runScript('init', '', tmpDir));
+      assert.strictEqual(typeof result.is_brownfield, 'boolean');
+      assert.strictEqual(typeof result.is_greenfield, 'boolean');
+      assert.strictEqual(result.is_brownfield, !result.is_greenfield);
+    });
+  });
+});

package/skills/plan-feature/workflow.xml

@@ -16,7 +16,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>
 

package/skills/plan-product-vision/SKILL.md

@@ -1,75 +1,91 @@
----
-name: plan-product-vision
-description: Create or update the product vision through architecture-aware questioning and guided writing
-argument-hint: "[optional: context='PRD, specs, or notes to build on']"
-disable-model-invocation: true
-allowed-tools: Read, Bash, Write, Task, AskUserQuestion
-model: opus
-effort: high
----
-
-# Plan Product Vision
-
-Create or update the product vision through architecture-aware questioning and guided writing.
-
-## When to Use
-
-- During `/ace:help` — as part of initial project setup
-- After `/ace:map-system` — once codebase is mapped, leverage architecture context
-- Anytime — to create or refresh the product vision for a project
-- Starting a new project and want to define the product vision (greenfield or brownfield)
-- Existing product vision is outdated or missing
-- System architecture has been mapped and you want to align vision with subsystem capabilities
-- Pivoting the product direction and need to rewrite the vision
-
-## Input
-
-### Optional
-
-- **`context`** — Existing PRD, specs, or notes to use as a starting point. Will be refined through the interview process, not used as-is.
-
-## 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
-- **Product vision template**: Read [product-vision-template.xml](product-vision-template.xml) — output format for the product vision
-- **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
-
-Use the `ace-product-owner` agent for requirements gathering, deep questioning, and vision specification.
-
-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. Preserve all workflow gates (validation, approvals, commits).
-
-## Artifacts
-
-```
-.docs/product/product-vision.md
-```
-
-## Example Usage
-
-```
-# Create a new product vision from scratch
-/ace:plan-product-vision
-
-# Create vision with existing PRD as seed
-/ace:plan-product-vision context="path/to/existing-prd.md"
-
-# Update vision after architecture changes
-/ace:plan-product-vision
-```
-
-## Next Steps
-
-- `/ace:init-coding-standards` — Establish coding standards for the project
-- `/ace:map-system` — Map codebase structure and architecture
-- `/ace:help` — Check project initialization status and next steps
+---
+name: plan-product-vision
+description: Create or update the product vision through architecture-aware questioning and guided writing
+argument-hint: "[optional: context='PRD, specs, or notes to build on']"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Write, Task, AskUserQuestion
+model: opus
+effort: high
+---
+
+## Environment Context (preprocessed)
+
+!`node "${CLAUDE_SKILL_DIR}/script.js" init 2>/dev/null`
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/product-vision-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>During /ace:help — as part of initial project setup</trigger>
+            <trigger>After /ace:map-system — once codebase is mapped, leverage architecture context</trigger>
+            <trigger>Anytime — to create or refresh the product vision for a project</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Starting a new project and want to define the product vision (greenfield or brownfield)</condition>
+            <condition>Existing product vision is outdated or missing</condition>
+            <condition>System architecture has been mapped and you want to align vision with subsystem capabilities</condition>
+            <condition>Pivoting the product direction and need to rewrite the vision</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+                <param name="context" type="file | text">
+                    Existing PRD, specs, or notes to use as a starting point.
+                    Will be refined through the interview process, not used as-is.
+                </param>
+            </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 the project's brownfield/greenfield status and architecture context.
+            If brownfield with system architecture, use the Subsystem Responsibility Matrix
+            to inform high-level capabilities. Interview the user about their product vision,
+            goals, and audience. Generate a comprehensive product-vision.md.
+        </objective>
+
+        <artifacts>
+            .docs/product/product-vision.md
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the plan-product-vision workflow from
+        `workflow.xml` end-to-end.
+        Preserve all workflow gates (validation, approvals, commits).
+    </process>
+
+    <next-steps>
+        **After this command:**
+        - `/ace:init-coding-standards` — Establish coding standards for the project
+        - `/ace:map-system` — Map codebase structure and architecture
+        - `/ace:help` — Check project initialization status and next steps
+    </next-steps>
+
+</command>
+```