agile-context-engineering 0.2.2 → 0.5.0

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

@@ -0,0 +1,83 @@
+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-backlog 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_features_research, 'boolean');
+      assert.strictEqual(typeof result.has_architecture_research, 'boolean');
+      assert.strictEqual(typeof result.has_wiki_analysis, '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/{agile-context-engineering/workflows/plan-backlog.xml → skills/plan-backlog/workflow.xml}

@@ -28,11 +28,9 @@
         <step name="setup" order="1">
             **MANDATORY FIRST STEP — Execute environment detection before any user interaction:**
 
-            ```bash
-            INIT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js init plan-backlog)
-            ```
+            INIT is available from the preprocessed Environment Context above — do NOT re-run init.
 
-            Parse JSON for: `product_owner_model`, `researcher_model`, `commit_docs`,
+            Parse INIT JSON for: `product_owner_model`, `researcher_model`, `commit_docs`,
             `has_product_vision`, `has_product_backlog`,
             `has_features_research`, `has_architecture_research`, `has_wiki_analysis`,
             `is_brownfield`, `is_greenfield`,
@@ -41,10 +39,7 @@
             `has_system_structure`, `has_testing_framework`, `has_git`, `has_gh_cli`,
             `github_project` (object: `enabled`, `gh_installed`, `repo`, `project_number`, `owner`).
 
-            Also resolve the product owner model for spawning the writing agent:
-            ```bash
-            PO_MODEL=$(node ~/.claude/agile-context-engineering/src/ace-tools.js resolve-model ace-product-owner --raw)
-            ```
+            PO_MODEL is available from INIT.product_owner_model — do NOT re-run resolve-model.
 
             Display stage banner:
 
@@ -145,7 +140,7 @@
             **Fetch all epics and features with full field data (single command):**
 
             ```bash
-            GITHUB_ISSUES=$(node ~/.claude/agile-context-engineering/src/ace-tools.js github fetch-issues \
+            GITHUB_ISSUES=$(node "${CLAUDE_SKILL_DIR}/script.js" fetch-issues \
               repo={REPO} owner={OWNER} project={PROJECT_NUMBER})
             ```
 
@@ -549,10 +544,7 @@
               i  Skipping architecture research — wiki architecture already captured in step 4.
             ```
 
-            Resolve the researcher model:
-            ```bash
-            RESEARCHER_MODEL=$(node ~/.claude/agile-context-engineering/src/ace-tools.js resolve-model ace-project-researcher --raw)
-            ```
+            RESEARCHER_MODEL is available from INIT.researcher_model — do NOT re-run resolve-model.
 
             **Features Researcher (always spawned):**
 
@@ -566,7 +558,7 @@
 
             Prompt:
             ```
-            First, read ~/.claude/agents/ace-project-researcher.md for your role and instructions.
+            You are the ace-project-researcher agent. Follow your agent instructions.
 
             <research_type>
             Project Research — Features dimension for [domain].
@@ -609,7 +601,7 @@
 
             Prompt:
             ```
-            First, read ~/.claude/agents/ace-project-researcher.md for your role and instructions.
+            You are the ace-project-researcher agent. Follow your agent instructions.
 
             <research_type>
             Project Research — Architecture/Epic structure dimension for [domain].
@@ -948,7 +940,7 @@
                 {paste the context brief here}
 
                 **Instructions:**
-                1. Read the product backlog template: ~/.claude/agile-context-engineering/templates/product/product-backlog.xml
+                1. Read the product backlog template: ${CLAUDE_SKILL_DIR}/product-backlog-template.xml
                 2. Write `.ace/artifacts/product/product-backlog.md` following the template structure exactly
                 3. Include the header paragraph explaining product direction
                 4. Write the Epic Index table (ordered by strategic priority)
@@ -1020,7 +1012,7 @@
                 prompt="You are an Agile Product Owner editing an existing product backlog.
 
                 **Read the current backlog:** `.ace/artifacts/product/product-backlog.md`
-                **Read the template for reference:** `~/.claude/agile-context-engineering/templates/product/product-backlog.xml`
+                **Read the template for reference:** `${CLAUDE_SKILL_DIR}/product-backlog-template.xml`
 
                 **Changes to apply:**
                 {paste the change brief here}
@@ -1085,7 +1077,7 @@
                   - Keep Feature IDs globally sequential — if adding new features, use the next available F[N]
                   - Update Epic status to reflect aggregate feature status
                   - Size values must be Fibonacci×10 only: 10, 20, 30, 50, 80, 130
-                  - Re-read the template for reference: ~/.claude/agile-context-engineering/templates/product/product-backlog.xml
+                  - Re-read the template for reference: ${CLAUDE_SKILL_DIR}/product-backlog-template.xml
 
                   Use the Edit tool to modify in place. Return only a confirmation of what changed.",
                   subagent_type="general-purpose",
@@ -1164,7 +1156,7 @@
             **Prerequisite — Resolve all field and type IDs (once, before creating any issues):**
 
             ```bash
-            GH_FIELDS=$(node ~/.claude/agile-context-engineering/src/ace-tools.js github resolve-fields repo={REPO} owner={OWNER} project={PROJECT_NUMBER})
+            GH_FIELDS=$(node "${CLAUDE_SKILL_DIR}/script.js" resolve-fields repo={REPO} owner={OWNER} project={PROJECT_NUMBER})
             ```
 
             Parse the JSON response. Extract and cache:
@@ -1182,7 +1174,7 @@
             **For each unlinked Epic (in order):**
 
             ```bash
-            EPIC_RESULT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js github create-issue \
+            EPIC_RESULT=$(node "${CLAUDE_SKILL_DIR}/script.js" create-issue \
               type=Epic \
               "title={Epic Title}" \
               "body={Epic Description}" \
@@ -1206,7 +1198,7 @@
             **If "Create new only" or "Sync all" was selected, for each unlinked Feature (in order):**
 
             ```bash
-            FEATURE_RESULT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js github create-issue \
+            FEATURE_RESULT=$(node "${CLAUDE_SKILL_DIR}/script.js" create-issue \
               type=Feature \
               "title={Feature Title}" \
               "body={Feature Description}" \

package/skills/plan-feature/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: plan-feature
+description: Plan a feature through backlog-aware questioning, story decomposition, and guided feature specification
+argument-hint: "[feature-id] [optional: context='text or file with feature description prompt']"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Write, Task, AskUserQuestion
+model: opus
+effort: high
+---
+
+# Plan Feature
+
+Plan a feature through backlog-aware questioning, story decomposition, and guided feature specification.
+
+## When to Use
+
+- After `/ace:plan-backlog` — once the backlog exists, plan individual features
+- Anytime — to create or refine a feature and its story breakdown
+- Product backlog exists and you want to break a feature into stories
+- Starting feature-level planning and need to decompose into stories
+- Refining an existing feature with updated acceptance criteria or scope
+- Adding a new feature to an existing epic
+
+## Input
+
+### Optional
+
+- **`feature-id`** — Feature identifier from the product backlog (e.g., F3, #78). If provided, locates existing feature for planning or refinement. If omitted, presents the backlog for selection or allows creating a new feature.
+- **`context`** — Feature description, acceptance criteria, user stories, or any context to seed the feature planning process. Will be absorbed and refined through questioning, 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
+- **Feature template**: Read [feature-template.xml](feature-template.xml) — output format for the feature specification
+- **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 feature 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
+
+```
+.ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-feature_name>.md
+.ace/artifacts/product/<id-epic_name>/<id-feature_name>/<id-story_name>/<id-story_name>.md
+```
+
+## Example Usage
+
+```
+# Plan a feature by ID from the backlog
+/ace:plan-feature F3
+
+# Plan a feature with seed context
+/ace:plan-feature context="OAuth2 login with Google and GitHub providers"
+
+# Plan a feature by GitHub issue number
+/ace:plan-feature #78
+```
+
+## Next Steps
+
+- `/ace:plan-story story=...` — Plan a story from this feature
+- `/ace:plan-feature feature-id` — Plan another feature
+- `/ace:help` — Check project initialization status

package/skills/plan-feature/script.js

@@ -0,0 +1,148 @@
+#!/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);
+}

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

@@ -0,0 +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);
+    });
+  });
+});