agile-context-engineering 0.2.2 → 0.5.0

package/{agile-context-engineering/workflows/plan-feature.xml → skills/plan-feature/workflow.xml}

@@ -29,11 +29,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-feature)
-            ```
+            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_wiki_analysis`,
             `is_brownfield`, `is_greenfield`,
@@ -42,10 +40,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 agents:
-            ```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:
 
@@ -142,8 +137,8 @@
 
             Using `TARGET_FEATURE` (or user-described new feature), compute:
             ```bash
-            EPIC_SLUG=$(node ~/.claude/agile-context-engineering/src/ace-tools.js generate-slug "{Epic ID}-{Epic Title}" --raw)
-            FEATURE_SLUG=$(node ~/.claude/agile-context-engineering/src/ace-tools.js generate-slug "{Feature ID}-{Feature Title}" --raw)
+            EPIC_SLUG=$(node "${CLAUDE_SKILL_DIR}/script.js" generate-slug "{Epic ID}-{Epic Title}" --raw)
+            FEATURE_SLUG=$(node "${CLAUDE_SKILL_DIR}/script.js" generate-slug "{Feature ID}-{Feature Title}" --raw)
             ```
 
             Set `FEATURE_DIR = .ace/artifacts/product/{EPIC_SLUG}/{FEATURE_SLUG}`
@@ -153,7 +148,7 @@
 
             Check if `FEATURE_FILE` exists:
             ```bash
-            EXISTING_FEATURE=$(node ~/.claude/agile-context-engineering/src/ace-tools.js verify-path-exists {FEATURE_FILE} --raw)
+            EXISTING_FEATURE=$(node "${CLAUDE_SKILL_DIR}/script.js" verify-path-exists {FEATURE_FILE} --raw)
             ```
 
             If exists: set `RUN_MODE = REFINE`
@@ -293,7 +288,7 @@
 
             Check if `{FEATURE_DIR}/relevant-wiki.md` exists:
             ```bash
-            HAS_WIKI_RESEARCH=$(node ~/.claude/agile-context-engineering/src/ace-tools.js verify-path-exists {FEATURE_DIR}/relevant-wiki.md --raw)
+            HAS_WIKI_RESEARCH=$(node "${CLAUDE_SKILL_DIR}/script.js" verify-path-exists {FEATURE_DIR}/relevant-wiki.md --raw)
             ```
 
             If `HAS_WIKI_RESEARCH` is TRUE:
@@ -446,7 +441,7 @@
 
             Check if `{FEATURE_DIR}/relevant-code.md` exists:
             ```bash
-            HAS_CODE_RESEARCH=$(node ~/.claude/agile-context-engineering/src/ace-tools.js verify-path-exists {FEATURE_DIR}/relevant-code.md --raw)
+            HAS_CODE_RESEARCH=$(node "${CLAUDE_SKILL_DIR}/script.js" verify-path-exists {FEATURE_DIR}/relevant-code.md --raw)
             ```
 
             If `HAS_CODE_RESEARCH` is TRUE:
@@ -490,10 +485,7 @@
             After the notification arrives, verify the file with `wc -l {FEATURE_DIR}/relevant-code.md`,
             then READ the file directly from disk using the Read tool. That is how you get the results.
 
-            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.
 
             Task tool parameters:
             ```
@@ -505,7 +497,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.
 
             **Feature context:**
             - Feature: {Feature ID} — {Feature Title}
@@ -894,7 +886,7 @@
                 {paste the context brief here}
 
                 **Instructions:**
-                1. Read the feature template: ~/.claude/agile-context-engineering/templates/product/feature.xml
+                1. Read the feature template: ${CLAUDE_SKILL_DIR}/feature-template.xml
                 2. Write `{FEATURE_FILE}` following the template structure exactly
                 3. Include ALL sections: Header, Description, Benefit Hypothesis, Scope,
                    Acceptance Criteria, [Existing Implementation if brownfield],
@@ -961,7 +953,7 @@
                 prompt="You are an Agile Product Owner updating an existing feature specification.
 
                 **Read the current feature:** `{FEATURE_FILE}`
-                **Read the template for reference:** `~/.claude/agile-context-engineering/templates/product/feature.xml`
+                **Read the template for reference:** `${CLAUDE_SKILL_DIR}/feature-template.xml`
 
                 **Changes to apply:**
                 {paste the change brief here}
@@ -1005,7 +997,7 @@
 
             Compute story slugs:
             ```bash
-            STORY_SLUG=$(node ~/.claude/agile-context-engineering/src/ace-tools.js generate-slug "{Story ID}-{Story Title}" --raw)
+            STORY_SLUG=$(node "${CLAUDE_SKILL_DIR}/script.js" generate-slug "{Story ID}-{Story Title}" --raw)
             ```
 
             For each story, check if the file already exists:
@@ -1025,7 +1017,7 @@
 
                 File path pattern: `{FEATURE_DIR}/{story_slug}/{story_slug}.md`
                 where story_slug = generate-slug of '{Story ID}-{Story Title}'
-                (use Bash: `node ~/.claude/agile-context-engineering/src/ace-tools.js generate-slug '{Story ID}-{Story Title}' --raw`)
+                (use Bash: `node "${CLAUDE_SKILL_DIR}/script.js" generate-slug '{Story ID}-{Story Title}' --raw`)
 
                 Each story gets its own subdirectory. Create the directory with `mkdir -p` before writing.
 
@@ -1094,7 +1086,7 @@
                 - Insert in the correct epic's detail section, ordered by delivery sequence
                 - Update the Epic Index table if needed (aggregate status change)
                 - Maintain table formatting — pad ALL cells so | separators align vertically
-                - Read template for reference: ~/.claude/agile-context-engineering/templates/product/product-backlog.xml
+                - Read template for reference: ${CLAUDE_SKILL_DIR}/../plan-backlog/product-backlog-template.xml
 
                 Use Edit tool to modify in place. Return only a confirmation of what changed.",
                 subagent_type="ace-product-owner",
@@ -1161,7 +1153,7 @@
                   {user's requested changes}.
 
                   **Rules:**
-                  - Read the template for reference: ~/.claude/agile-context-engineering/templates/product/feature.xml
+                  - Read the template for reference: ${CLAUDE_SKILL_DIR}/feature-template.xml
                   - Maintain all template formatting — especially table column alignment:
                     pad cells with spaces so | separators align vertically across all rows
                   - Keep Story IDs stable — do NOT renumber
@@ -1249,7 +1241,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:
@@ -1269,7 +1261,7 @@
             - If the parent epic has no GitHub issue (Link = "—"), warn user and skip parent assignment.
 
             ```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_file={FEATURE_FILE} \
@@ -1300,7 +1292,7 @@
             The feature file IS the body. 100% of `{FEATURE_FILE}` goes to GitHub as-is.
 
             ```bash
-            node ~/.claude/agile-context-engineering/src/ace-tools.js github update-issue \
+            node "${CLAUDE_SKILL_DIR}/script.js" update-issue \
               number={feature_issue_number} \
               repo={REPO} \
               "title={Feature Title}" \
@@ -1322,7 +1314,7 @@
             goes to GitHub as-is. The story stub files were created in step 9c.
 
             ```bash
-            STORY_RESULT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js github create-issue \
+            STORY_RESULT=$(node "${CLAUDE_SKILL_DIR}/script.js" create-issue \
               type=Story \
               "title={Story Title}" \
               body_file={FEATURE_DIR}/{STORY_SLUG}/{STORY_SLUG}.md \
@@ -1351,7 +1343,7 @@
             goes to GitHub as-is.
 
             ```bash
-            node ~/.claude/agile-context-engineering/src/ace-tools.js github update-issue \
+            node "${CLAUDE_SKILL_DIR}/script.js" update-issue \
               number={story_issue_number} \
               repo={REPO} \
               "title={Story Title}" \

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

@@ -0,0 +1,75 @@
+---
+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

package/skills/plan-product-vision/script.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+
+/**
+ * plan-product-vision skill script — Entry point for ace-tools operations
+ * needed by the plan-product-vision skill.
+ *
+ * Subcommands:
+ *   init [args]        Environment detection for plan-product-vision workflow
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const {
+  loadConfig, pathExists, resolveModel,
+  detectBrownfieldStatus, output, error,
+} = require('../../shared/lib/ace-core');
+
+// ─── 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;
+  default:
+    error(`Unknown command: ${cmd}\nAvailable: init`);
+}
+
+// ─── Init: Plan Product Vision ──────────────────────────────────────────────
+
+function cmdInit(cwd, raw) {
+  const config = loadConfig(cwd);
+  const brownfield = detectBrownfieldStatus(cwd);
+
+  const result = {
+    // Models
+    product_owner_model: resolveModel(cwd, 'ace-product-owner'),
+
+    // Config
+    commit_docs: config.commit_docs,
+
+    // Existing state
+    has_product_vision: pathExists(cwd, '.docs/product/product-vision.md'),
+
+    // Brownfield detection
+    ...brownfield,
+
+    // Architecture context
+    has_system_architecture: pathExists(cwd, '.docs/wiki/system-wide/system-architecture.md'),
+
+    // Git state
+    has_git: pathExists(cwd, '.git'),
+  };
+
+  output(result, raw);
+}

package/skills/plan-product-vision/script.test.js

@@ -0,0 +1,69 @@
+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));
+
+  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-product-vision 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.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_system_architecture, 'boolean');
+    });
+
+    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-product-vision.xml → skills/plan-product-vision/workflow.xml}

@@ -24,18 +24,13 @@
         <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 product-vision)
-            ```
+            INIT is available from the preprocessed Environment Context above — do NOT re-run init.
 
-            Parse JSON for: `product_owner_model`, `commit_docs`, `has_product_vision`,
+            Parse INIT JSON for: `product_owner_model`, `commit_docs`, `has_product_vision`,
             `is_brownfield`, `is_greenfield`, `has_existing_code`, `has_package_file`,
             `has_system_architecture`, `has_git`.
 
-            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:
 
@@ -223,7 +218,7 @@
                 {paste the context brief here}
 
                 **Instructions:**
-                1. Read the product vision template: ~/.claude/agile-context-engineering/templates/product/product-vision.xml
+                1. Read the product vision template: ${CLAUDE_SKILL_DIR}/product-vision-template.xml
                 2. Write `.docs/product/product-vision.md` following the template structure and guidelines
                 3. Do not compress — capture everything from the context brief
                 4. Write the file using the Write tool

package/skills/plan-story/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: plan-story
+description: Plan a story through deep questioning to create CRYSTAL-CLEAR acceptance criteria with ZERO assumptions, then dispatch wiki research, external analysis, integration analysis, and technical solution design. Use this whenever the user wants to plan a story, specify a story, create acceptance criteria, refine story requirements, or take a story stub and turn it into a full specification — whether from a feature stub, GitHub issue, inline text, or from scratch.
+argument-hint: "[story=<file-path|github-url>] [text=<inline-description>] [external-codebase=<source-path|github-url>] [external-docs=<weblink|filepath>] [lib-docs=<weblinks-and-filepaths>]"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Write, Edit, AskUserQuestion, Glob, Grep, Agent
+model: opus
+effort: high
+---
+
+# Plan Story
+
+Orchestrate story specification through deep questioning and multi-pass research.
+
+## When to Use
+
+- After `/ace:plan-feature` — when a feature's story breakdown exists with stub story files
+- To create or refine a story specification from a description or GitHub issue
+- When a story stub needs formal INVEST-compliant specification
+- When an existing story needs refinement due to scope changes or AC gaps
+- When you have a new story idea (text or no input) and need it placed in the backlog
+
+## Input
+
+### Optional
+
+- **`story`** — Story source:
+  - **File path**: Path to a markdown file containing the story seed (typically from plan-feature, or any markdown with a description)
+  - **GitHub URL or issue number**: e.g., `story=#95` or `story=https://github.com/owner/repo/issues/95`
+  - When omitted, enters "new story" mode and guides the user through backlog placement.
+
+- **`text`** — Inline story description to seed the planning session. Used when no story file exists yet — the text becomes the initial description and the workflow asks where in the backlog this story belongs. Ignored if `story` is provided.
+
+- **`external-codebase`** — Path or GitHub repo to an external system to analyze. Triggers pass 3 automatically.
+
+- **`external-docs`** — Link or filepath to external system documentation. Only used with external-codebase.
+
+- **`lib-docs`** — Space-separated weblinks and/or filepaths to library/API documentation. Injected into the Relevant Wiki section after pass 2.
+
+## 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) — output format for the story 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 story 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).
+
+**Context Window Protection:**
+Passes 2-5 run as background agents. Each agent writes output directly to files.
+The orchestrator MUST NOT call TaskOutput on any background agent.
+Only track when each pass finishes to start the next one.
+
+**Pass execution order:**
+Pass 2 + Pass 3 (if applicable) → wait → Pass 4 → wait → Pass 5 → wait → done
+
+## Artifacts
+
+```
+.ace/artifacts/product/<epic>/<feature>/<story>/
+├── <story>.md                    # Story specification (passes 1, 2, 5)
+├── external-analysis.md          # OPTIONAL (pass 3)
+└── integration-analysis.md       # Integration analysis (pass 4)
+```
+
+## Example Usage
+
+```
+# New story from inline text — workflow asks for backlog placement
+/ace:plan-story text="User can reset their password via email link"
+
+# New story with no input — workflow asks title then placement
+/ace:plan-story
+
+# From a plan-feature stub file
+/ace:plan-story story=.ace/artifacts/product/e1-auth/f3-oauth/s1-buttons/s1-buttons.md
+
+# From a loose markdown file (no ACE structure yet — triggers placement flow)
+/ace:plan-story story=notes/password-reset-idea.md
+
+# From a GitHub issue
+/ace:plan-story story=https://github.com/owner/repo/issues/95
+
+# With external system analysis
+/ace:plan-story \
+  story=.ace/artifacts/product/e1-charts/f2-rendering/s3-canvas/s3-canvas.md \
+  external-codebase=src/external/lightweight-charts/ \
+  external-docs=https://tradingview.github.io/lightweight-charts/
+
+# With library documentation
+/ace:plan-story \
+  story=.ace/artifacts/product/e1-charts/f2-rendering/s3-canvas/s3-canvas.md \
+  lib-docs="https://docs.some-lib.io/api src/vendor/some-lib/README.md"
+
+# With just an issue number
+/ace:plan-story story=#95
+```
+
+## Next Steps
+
+- `/ace:execute-story story=...` — Execute the story implementation
+- `/ace:plan-story story=...` — Plan the next story in the feature
+- `/ace:verify-story story=...` — Verify a completed story
+- `/ace:help` — Check project initialization status