agile-context-engineering 0.3.0 → 0.5.1

package/{commands/ace/map-subsystem.md → skills/map-subsystem/SKILL.md}

@@ -1,140 +1,155 @@
----
-name: ace: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"
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Task
-  - AskUserQuestion
----
-
-```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>
-        <map-subsystem-workflow>@~/.claude/agile-context-engineering/workflows/map-subsystem.xml</map-subsystem-workflow>
-        <subsystem-structure-template>@~/.claude/agile-context-engineering/templates/wiki/subsystem-structure.xml</subsystem-structure-template>
-        <subsystem-architecture-template>@~/.claude/agile-context-engineering/templates/wiki/subsystem-architecture.xml</subsystem-architecture-template>
-        <module-discovery-template>@~/.claude/agile-context-engineering/templates/wiki/module-discovery.xml</module-discovery-template>
-        <map-story-workflow>@~/.claude/agile-context-engineering/workflows/map-story.xml</map-story-workflow>
-        <system-template>@~/.claude/agile-context-engineering/templates/wiki/system.xml</system-template>
-        <pattern-template>@~/.claude/agile-context-engineering/templates/wiki/pattern.xml</pattern-template>
-        <cross-cutting-template>@~/.claude/agile-context-engineering/templates/wiki/system-cross-cutting.xml</cross-cutting-template>
-        <guide-template>@~/.claude/agile-context-engineering/templates/wiki/guide.xml</guide-template>
-        <walkthrough-template>@~/.claude/agile-context-engineering/templates/wiki/walkthrough.xml</walkthrough-template>
-        <decisions-template>@~/.claude/agile-context-engineering/templates/wiki/decizions.xml</decisions-template>
-        <questioning>@~/.claude/agile-context-engineering/utils/questioning.xml</questioning>
-        <ui-formatting>@~/.claude/agile-context-engineering/utils/ui-formatting.md</ui-formatting>
-    </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
-        `@~/.claude/agile-context-engineering/workflows/map-subsystem.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>
-```
+---
+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

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

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

package/skills/map-subsystem/templates/decizions.xml

@@ -0,0 +1,115 @@
+<decisions>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/decisions/<decision-name>.md` — an
+        Architecture Decision Record (ADR) capturing WHY a significant choice was made.
+        Answers "Why did we choose X over Y?"
+
+        Each decision doc captures one significant technical decision with its context and
+        trade-offs. It is the document an AI agent reads to understand WHY things are built
+        a certain way, preventing it from making the wrong choice.
+
+        Create an ADR ONLY when a significant "why" decision was made:
+        - Choosing one approach over another with meaningful trade-offs
+        - Deviating from an established pattern for a specific reason
+        - Adopting a new technology, pattern, or architectural approach
+        - Rejecting a seemingly obvious solution for non-obvious reasons
+
+        Do NOT create ADRs for trivial or obvious decisions.
+
+        Complements:
+        - systems/ docs (WHAT exists — systems reference decisions that shaped them)
+        - patterns/ docs (HOW things work — patterns reference decisions that defined them)
+        - cross-cutting/ docs (shared infrastructure shaped by architectural decisions)
+    </purpose>
+
+    <template>
+        <decision-record>
+            # ADR-NNN: [Decision Title]
+
+            **Status**: Accepted | Superseded by [ADR-MMM](./ADR-MMM-slug.md)
+            **Date**: YYYY-MM-DD
+            **Story**: [story reference, if applicable]
+
+            ## Context
+            What situation prompted this decision. 2-3 sentences max.
+
+            ## Decision
+            What was decided. 2-3 sentences max.
+
+            ## Alternatives Considered
+            - **[Alternative A]**: [Why rejected — 1 sentence]
+            - **[Alternative B]**: [Why rejected — 1 sentence]
+
+            ## Consequences
+            - Pro: [positive outcome]
+            - Pro: [positive outcome]
+            - Con: [trade-off accepted]
+        </decision-record>
+    </template>
+
+    <guidelines>
+
+        **Documentation Style:**
+        - EXTREMELY SUCCINCT — each ADR should be under 30 lines
+        - NO FLUFF — every sentence must convey a decision, reason, or consequence
+        - Bullet points for alternatives and consequences
+        - Code references as `file-path:ClassName` only when the decision is about specific code
+
+        **ADR Numbering:**
+        - Sequential within the subsystem: ADR-001, ADR-002, etc.
+        - Filename format: `ADR-NNN-kebab-case-slug.md`
+        - To find the next number, read existing ADRs in the decisions/ directory.
+
+        **Status:**
+        - `Accepted` — the decision is in effect
+        - `Superseded by ADR-MMM` — replaced by a later decision (link to it)
+        - ADRs are IMMUTABLE — never edit an accepted ADR. Create a new one that supersedes it.
+
+        **Context:**
+        - 2-3 sentences. What problem or situation forced a choice.
+        - Reference the system or pattern this decision affects.
+
+        **Decision:**
+        - 2-3 sentences. What was chosen and at what scope.
+        - Be specific — "We use X for Y" not "We decided to improve things."
+
+        **Alternatives Considered:**
+        - List each rejected alternative with ONE sentence explaining why.
+        - If there were no meaningful alternatives, omit this section.
+
+        **Consequences:**
+        - Bullet list of pros and cons.
+        - Be honest about trade-offs — future agents need to know the downsides.
+        - Include migration/compatibility consequences if applicable.
+
+        **What does NOT belong here:**
+        - Implementation details (that's in systems/ and patterns/ docs)
+        - Step-by-step instructions (that's in guides/)
+        - Full analysis or research documents (those are in .ace/artifacts/)
+        - Revision history or meeting notes
+
+    </guidelines>
+
+    <evolution>
+
+        ADRs are IMMUTABLE once accepted. They are historical records.
+
+        **When to create a new ADR:**
+        - A significant architectural or pattern choice is made during a story
+        - An existing decision is reversed or significantly modified (supersede the old one)
+        - A new technology, pattern, or approach is adopted
+
+        **When NOT to create an ADR:**
+        - Routine implementation following existing patterns
+        - Bug fixes or refactoring that don't change architectural direction
+        - Trivial decisions with no meaningful trade-offs
+        - Decisions already captured in an existing ADR
+
+        **Superseding:**
+        - Create the new ADR with its own number
+        - Update the old ADR's Status to: `Superseded by [ADR-MMM](./ADR-MMM-slug.md)`
+        - This is the ONLY edit allowed on an accepted ADR
+
+    </evolution>
+
+</decisions>