agile-context-engineering 0.5.0 → 0.5.1

package/skills/map-subsystem/SKILL.md

@@ -1,111 +1,155 @@
----
-name: map-subsystem
-description: Map a subsystem's structure, architecture, and knowledge docs into .docs/wiki/subsystems/[name]/
-argument-hint: "subsystem='src/api' (or subsystem name) existing-docs=comma separated paths | directory"
-disable-model-invocation: true
-allowed-tools: Read, Bash, Glob, Grep, Write, Task, AskUserQuestion
-model: opus
-effort: max
----
-
-# Map Subsystem
-
-Map a subsystem's structure, architecture, and knowledge docs into .docs/wiki/subsystems/[name]/.
-
-## When to Use
-
-- After `/ace:map-system` — drill into individual subsystems
-- Anytime to refresh an existing subsystem's wiki documents
-- When a new subsystem is added and needs to be documented
-- A subsystem has not yet been documented in `.docs/wiki/subsystems/`
-- An existing subsystem's docs are stale after a significant refactor
-- You want a deep-dive view of a specific subsystem's internals (components, flows, data)
-
-## Input
-
-### Required
-
-- **`subsystem`** — Path to the subsystem (e.g., `src/api`) or its name. If not provided, pause execution and ask the user for it. If provided but ambiguous, or not found in the codebase, ask clarifying questions.
-
-### Optional
-
-- **`existing-docs`** — Pre-existing documentation relevant to this subsystem. Accepts file paths, directory paths, or a mix of both. When a directory is provided, recursively discover all files within it (including nested subdirectories). All resolved file paths are passed through to every map-story invocation (file mode) alongside any per-module docs discovered during module-discovery. Use this when the caller already knows about documentation that should inform knowledge-doc generation.
-
-## 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
-- **Subsystem structure template**: Read [templates/subsystem-structure.xml](templates/subsystem-structure.xml) — output format for subsystem structure
-- **Subsystem architecture template**: Read [templates/subsystem-architecture.xml](templates/subsystem-architecture.xml) — output format for subsystem architecture
-- **Module discovery template**: Read [templates/module-discovery.xml](templates/module-discovery.xml) — format for module discovery artifact
-- **System template**: Read [templates/system.xml](templates/system.xml) — format for system documents
-- **Pattern template**: Read [templates/pattern.xml](templates/pattern.xml) — format for pattern documents
-- **Cross-cutting template**: Read [templates/system-cross-cutting.xml](templates/system-cross-cutting.xml) — format for cross-cutting concern documents
-- **Guide template**: Read [templates/guide.xml](templates/guide.xml) — format for guide documents
-- **Walkthrough template**: Read [templates/walkthrough.xml](templates/walkthrough.xml) — format for walkthrough documents
-- **Decisions template**: Read [templates/decizions.xml](templates/decizions.xml) — format for decision documents
-- **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-wiki-mapper` agent for codebase analysis and document generation.
-
-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, user questions, commits).
-
-The workflow has 13 steps:
-1-5: Setup, context loading, subsystem resolution, document triage, directory creation
-6-8: Structure + architecture agents (parallel) + collect results
-9: Update system-wide docs (system-structure.md, system-architecture.md)
-10: Module discovery (3 parallel discovery agents + 1 synthesis agent)
-11: Knowledge documentation — run map-story for EACH discovered module (sequential)
-12: Verify and commit all documents
-13: Completion report
-
-Steps 10-11 are CRITICAL — they produce the knowledge docs (systems/, patterns/, cross-cutting/, guides/, walkthroughs/, decisions/) that AI agents need for future implementations. Do NOT skip them.
-
-## Artifacts
-
-```
-.docs/wiki/subsystems/[subsystem-name]/structure.md
-.docs/wiki/subsystems/[subsystem-name]/architecture.md
-.docs/wiki/subsystems/[subsystem-name]/systems/*.md
-.docs/wiki/subsystems/[subsystem-name]/patterns/*.md
-.docs/wiki/subsystems/[subsystem-name]/cross-cutting/*.md
-.docs/wiki/subsystems/[subsystem-name]/guides/*.md
-.docs/wiki/subsystems/[subsystem-name]/walkthroughs/*.md
-.docs/wiki/subsystems/[subsystem-name]/decisions/*.md
-.ace/artifacts/subsystems/[subsystem-name]/module-discovery/module-discovery.md
-.ace/artifacts/subsystems/[subsystem-name]/module-discovery/existing-docs-inventory.md
-.docs/wiki/system-wide/system-structure.md    (subsystem entry added if new)
-.docs/wiki/system-wide/system-architecture.md (subsystem responsibility matrix updated)
-```
-
-## Example Usage
-
-```
-# Map a subsystem by path
-/ace:map-subsystem subsystem="src/api"
-
-# Map a subsystem with existing docs
-/ace:map-subsystem subsystem="src/auth" existing-docs="docs/auth-design.md,docs/auth/"
-
-# Map a subsystem by name
-/ace:map-subsystem subsystem="authentication"
-```
-
-## Next Steps
-
-After this command, `/clear` first for a fresh context window, then:
-
-- `/ace:map-subsystem subsystem="src/other"` — Map another subsystem
-- `/ace:init-coding-standards` — Define prescriptive coding standards
-- `/ace:help` — Check project initialization status and next steps
-- Review and edit files in `.docs/wiki/subsystems/` anytime
+---
+name: map-subsystem
+description: Map a subsystem's structure, architecture, and knowledge docs into .docs/wiki/subsystems/[name]/
+argument-hint: "subsystem='src/api' (or subsystem name) existing-docs=comma separated paths | directory"
+disable-model-invocation: true
+allowed-tools: Read, Bash, Glob, Grep, Write, Task, AskUserQuestion
+model: opus
+effort: max
+---
+
+## 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}/templates/subsystem-structure.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/subsystem-architecture.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/module-discovery.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/system.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/system-cross-cutting.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/pattern.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/guide.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/walkthrough.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/decizions.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>After /ace:map-system — drill into individual subsystems</trigger>
+            <trigger>Anytime to refresh an existing subsystem's wiki documents</trigger>
+            <trigger>When a new subsystem is added and needs to be documented</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A subsystem has not yet been documented in `.docs/wiki/subsystems/`</condition>
+            <condition>An existing subsystem's docs are stale after a significant refactor</condition>
+            <condition>You want a deep-dive view of a specific subsystem's internals (components, flows, data)</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="subsystem" type="path | text">
+                    Path to the subsystem (e.g., `src/api`) or its name.
+                    If not provided, pause execution and ask the user for it.
+                    If provided but ambiguous, or not found in the codebase, ask clarifying questions.
+                </param>
+            </required>
+
+            <optional>
+                <param name="existing-docs" type="comma-separated paths or directories">
+                    Pre-existing documentation relevant to this subsystem. Accepts file paths,
+                    directory paths, or a mix of both. When a directory is provided, recursively
+                    discover all files within it (including nested subdirectories).
+                    All resolved file paths are passed through to every map-story invocation
+                    (file mode) alongside any per-module docs discovered during module-discovery.
+                    Use this when the caller already knows about documentation that should
+                    inform knowledge-doc generation.
+                </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>
+            Resolve the target subsystem, load system-wide wiki context, and determine whether
+            to create, update, or recreate per-subsystem wiki documents. Then:
+
+            1. Spawn ace-wiki-mapper agents to produce structure and architecture documents.
+            2. Update system-structure.md if this subsystem was not previously listed there.
+            3. Update the subsystem responsibility matrix in system-architecture.md if missing.
+            4. Run module discovery — trace E2E flows, identify patterns, find cross-cutting
+               concerns by reading actual source code. Produce module-discovery.md artifact.
+            5. For EACH discovered module, run map-story in file mode to create or update
+               knowledge documentation (systems/, patterns/, cross-cutting/, guides/, walkthroughs/, decisions/).
+        </objective>
+
+        <artifacts>
+            - .docs/wiki/subsystems/[subsystem-name]/structure.md
+            - .docs/wiki/subsystems/[subsystem-name]/architecture.md
+            - .docs/wiki/subsystems/[subsystem-name]/systems/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/patterns/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/cross-cutting/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/guides/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/walkthroughs/*.md (created/updated by map-story)
+            - .docs/wiki/subsystems/[subsystem-name]/decisions/*.md (created/updated by map-story)
+            - .ace/artifacts/subsystems/[subsystem-name]/module-discovery/module-discovery.md
+            - .ace/artifacts/subsystems/[subsystem-name]/module-discovery/existing-docs-inventory.md (if existing-docs directory provided)
+            - .docs/wiki/system-wide/system-structure.md (subsystem entry added if new)
+            - .docs/wiki/system-wide/system-architecture.md (subsystem responsibility matrix updated if missing)
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the map-subsystem workflow from
+        `workflow.xml` end-to-end.
+        Preserve all workflow gates (validation, user questions, commits).
+
+        The workflow has 13 steps:
+        1-5: Setup, context loading, subsystem resolution, document triage, directory creation
+        6-8: Structure + architecture agents (parallel) + collect results
+        9: Update system-wide docs (system-structure.md, system-architecture.md)
+        10: Module discovery (3 parallel discovery agents + 1 synthesis agent)
+        11: Knowledge documentation — run map-story for EACH discovered module (sequential)
+        12: Verify and commit all documents
+        13: Completion report
+
+        Steps 10-11 are CRITICAL — they produce the knowledge docs (systems/, patterns/,
+        cross-cutting/, guides/, walkthroughs/, decisions/) that AI agents need for future implementations.
+        Do NOT skip them.
+    </process>
+
+     <next-steps>
+        **After this command, `/clear` first for a fresh context window, then:**
+
+        For each subsystem found and defined in the Subsystem Responsibility Matrix,
+        suggest a `/ace:map-subsystem` command. Example:
+        - `/ace:map-subsystem subsystem="src/api"` — Map the API subsystem
+        - `/ace:map-subsystem subsystem="src/auth"` — Map the Auth subsystem
+        - `/ace:map-subsystem subsystem="src/db"` — Map the DB subsystem
+        (list one per subsystem discovered during this command's execution)
+
+        Also suggest:
+        - `/ace:init-coding-standards` — Define prescriptive coding standards
+        - `/ace:help` — Check project initialization status and next steps
+        - Review and edit files in `.docs/wiki/system-wide/` anytime
+    </next-steps>
+
+</command>
+```

package/skills/map-subsystem/script.js

@@ -1,60 +1,51 @@
-#!/usr/bin/env node
-
-/**
- * map-subsystem skill script — Entry point for ace-tools operations
- * needed by the map-subsystem skill.
- *
- * Subcommands:
- *   init [args]        Environment detection for map-subsystem 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: Map Subsystem ────────────────────────────────────────────────────
-
-function cmdInit(cwd, raw) {
-  const config = loadConfig(cwd);
-  const brownfield = detectBrownfieldStatus(cwd);
-
-  const wikiDir = '.docs/wiki/subsystems';
-  const wikiDirExists = pathExists(cwd, wikiDir);
-
-  const result = {
-    // Models
-    mapper_model: resolveModel(cwd, 'ace-wiki-mapper'),
-
-    // Config
-    commit_docs: config.commit_docs,
-
-    // Brownfield detection
-    ...brownfield,
-
-    // Wiki directory state
-    wiki_dir_exists: wikiDirExists,
-
-    // Git state
-    has_git: pathExists(cwd, '.git'),
-  };
-
-  output(result, raw);
-}
+#!/usr/bin/env node
+
+/**
+ * map-subsystem skill script — Entry point for ace-tools operations
+ * needed by the map-subsystem skill.
+ *
+ * Subcommands:
+ *   init [args]        Environment detection for map-subsystem workflow
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const {
+  loadConfig, pathExists, resolveModel,
+  detectBrownfieldStatus, output, error, runSkillScript,
+} = require('../../shared/lib/ace-core');
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+runSkillScript({
+  init: cmdInit,
+});
+
+// ─── Init: Map Subsystem ────────────────────────────────────────────────────
+
+function cmdInit(cwd, raw, args, parsed) {
+  const config = loadConfig(cwd);
+  const brownfield = detectBrownfieldStatus(cwd);
+
+  const wikiDir = '.docs/wiki/subsystems';
+  const wikiDirExists = pathExists(cwd, wikiDir);
+
+  const result = {
+    // Models
+    mapper_model: resolveModel(cwd, 'ace-wiki-mapper'),
+
+    // Config
+    commit_docs: config.commit_docs,
+
+    // Brownfield detection
+    ...brownfield,
+
+    // Wiki directory state
+    wiki_dir_exists: wikiDirExists,
+
+    // Git state
+    has_git: pathExists(cwd, '.git'),
+  };
+
+  output(result, raw);
+}

package/skills/map-subsystem/script.test.js

@@ -1,68 +1,68 @@
-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('map-subsystem 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.mapper_model, 'should have mapper_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.wiki_dir_exists, '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);
-    });
-  });
-});
+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('map-subsystem 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.mapper_model, 'should have mapper_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.wiki_dir_exists, '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);
+    });
+  });
+});