agile-context-engineering 0.5.0 → 0.5.1

package/skills/map-sys-doc/SKILL.md

@@ -1,90 +1,125 @@
----
-name: map-sys-doc
-description: Create or update a system document in .docs/wiki/subsystems/[name]/systems/ — describes WHAT exists, HOW it works, WHERE things live
-argument-hint: "text='Drawing system - manages all drawing tools on chart' subsystem='qarc-charts-v2' commits=3"
-disable-model-invocation: true
-allowed-tools:
-  - Read
-  - Bash
-  - Glob
-  - Grep
-  - Write
-  - Edit
-  - AskUserQuestion
-model: opus
-effort: max
-context: fork
-agent: ace-wiki-mapper
----
-
-# Map Sys Doc
-
-Create or update a system document describing WHAT exists, HOW it works, WHERE things live.
-
-## When to Use
-
-- When a coherent domain system needs dedicated documentation
-- After implementing a new system or significantly changing an existing one
-- When an AI agent needs a reference doc for a domain system before implementing stories
-- A logical grouping of components delivers one domain capability
-- The system spans multiple files with entry points, data flow, and state
-- A system doc would benefit from dedicated focused analysis outside map-story
-
-## Input
-
-### Required
-
-- **`text`** (text) — Natural language description of the system to document. Describes WHAT the system does, its domain concern, and key components. E.g.: "Drawing system - manages all drawing tools on the chart", "User authentication and authorization system", "Order processing pipeline from cart to confirmation". If not provided, pause and ask the user.
-
-- **`subsystem`** (path | text) — Subsystem where this system doc belongs. Wiki location: `.docs/wiki/subsystems/[subsystem]/systems/`. If not provided, pause and ask the user.
-
-### Optional
-
-- **`story-context`** (path | GitHub issue) — Path to story artifacts folder (in `.ace/artifacts/`) OR GitHub issue number/URL. Provides intent context for WHY the system was built/changed. When not provided, the agent relies solely on code analysis.
-
-- **`commits`** (number | comma-separated commit SHAs) — Specifies which commits to analyze for understanding what was built/changed. As a number: analyze the N most recent commits (e.g., commits=3). As commit SHAs: analyze specific commits (e.g., commits='abc123,def456'). When not provided: search the codebase directly using the text description.
-
-## Supporting Resources
-
-Read ALL of these before starting the workflow:
-
-- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
-- **System template**: Read [system.xml](system.xml) — output format for the system document
-- **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 that's specialized in wiki exploration and documentation writing.
-
-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).
-
-**Objective:** Create or update a system document that describes a coherent domain system — WHAT exists, HOW it works, WHERE things live. Includes file tree, system boundary diagram, class hierarchy, entry points, data flow sequence diagrams (mandatory), components, key behaviors, state management, error propagation, and constants/enums. The primary document an AI agent reads before implementing a related story.
-
-## Artifacts
-
-```
-.docs/wiki/subsystems/[subsystem-name]/systems/[system-name].md
-```
-
-## Example Usage
-
-```
-# Basic system doc
-/ace:map-sys-doc text='Drawing system - manages all drawing tools on chart' subsystem='qarc-charts-v2'
-
-# With recent commits
-/ace:map-sys-doc text='User authentication and authorization system' subsystem='api' commits=3
-
-# With story context
-/ace:map-sys-doc text='Order processing pipeline' subsystem='commerce' story-context='.ace/artifacts/product/e1-orders/f1-pipeline/s1-cart/s1-cart.md'
-```
-
-## Next Steps
-
-- `/clear` first for a fresh context window
-- `/ace:map-sys-doc` — create another system document
-- `/ace:map-pattern` — document a pattern used by this system
-- `/ace:map-guide` — create a how-to guide for this system
-- `/ace:map-cross-cutting` — document a cross-cutting concern
-- Review file at `.docs/wiki/subsystems/[subsystem-name]/systems/`
+---
+name: map-sys-doc
+description: Create or update a system document in .docs/wiki/subsystems/[name]/systems/ — describes WHAT exists, HOW it works, WHERE things live
+argument-hint: "text='Drawing system - manages all drawing tools on chart' subsystem='qarc-charts-v2' commits=3"
+disable-model-invocation: false
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - AskUserQuestion
+model: opus
+effort: max
+context: fork
+agent: ace-wiki-mapper
+---
+
+## Supporting Resources (auto-loaded)
+
+!`cat "${CLAUDE_SKILL_DIR}/workflow.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/system.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>When a coherent domain system needs dedicated documentation</trigger>
+            <trigger>After implementing a new system or significantly changing an existing one</trigger>
+            <trigger>When an AI agent needs a reference doc for a domain system before implementing stories</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A logical grouping of components delivers one domain capability</condition>
+            <condition>The system spans multiple files with entry points, data flow, and state</condition>
+            <condition>A system doc would benefit from dedicated focused analysis outside map-story</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="text" type="text">
+                    Natural language description of the system to document. Describes WHAT
+                    the system does, its domain concern, and key components.
+
+                    E.g.:
+                    - "Drawing system - manages all drawing tools on the chart"
+                    - "User authentication and authorization system"
+                    - "Order processing pipeline from cart to confirmation"
+
+                    If not provided, pause and ask the user.
+                </param>
+                <param name="subsystem" type="path | text">
+                    Subsystem where this system doc belongs.
+                    Wiki location: `.docs/wiki/subsystems/[subsystem]/systems/`.
+                    If not provided, pause and ask the user.
+                </param>
+            </required>
+
+            <optional>
+                <param name="story-context" type="path | GitHub issue">
+                    Path to story artifacts folder (in `.ace/artifacts/`) OR GitHub issue
+                    number/URL. Provides intent context for WHY the system was built/changed.
+                    When not provided, the agent relies solely on code analysis.
+                </param>
+                <param name="commits" type="number | comma-separated commit SHAs">
+                    Specifies which commits to analyze for understanding what was built/changed.
+                    As a number: analyze the N most recent commits (e.g., commits=3).
+                    As commit SHAs: analyze specific commits (e.g., commits='abc123,def456').
+                    When not provided: search the codebase directly using the text description.
+                </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>
+            Create or update a system document that describes a coherent domain system —
+            WHAT exists, HOW it works, WHERE things live. Includes file tree, system boundary
+            diagram, class hierarchy, entry points, data flow sequence diagrams (mandatory),
+            components, key behaviors, state management, error propagation, and constants/enums.
+
+            The primary document an AI agent reads before implementing a related story.
+        </objective>
+
+        <artifacts>
+            .docs/wiki/subsystems/[subsystem-name]/systems/[system-name].md
+        </artifacts>
+    </output>
+
+    <process>
+        For this command use the `ace-wiki-mapper` agent
+        that's specialized in wiki exploration and documentation writing.
+
+        Execute the map-sys-doc workflow from
+        `workflow.xml` end-to-end.
+        Preserve all workflow gates (validation, user questions, commits).
+    </process>
+
+    <next-steps>
+        <step>/clear first for a fresh context window</step>
+        <step>/ace:map-sys-doc — create another system document</step>
+        <step>/ace:map-pattern — document a pattern used by this system</step>
+        <step>/ace:map-guide — create a how-to guide for this system</step>
+        <step>/ace:map-cross-cutting — document a cross-cutting concern</step>
+        <step>Review file at .docs/wiki/subsystems/[subsystem-name]/systems/</step>
+    </next-steps>
+
+</command>
+```

package/skills/map-sys-doc/workflow.xml

@@ -14,7 +14,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/map-system/SKILL.md

@@ -1,85 +1,103 @@
----
-name: map-system
-description: Map system-wide codebase structure, architecture, and testing framework into .docs/wiki/system-wide/
-argument-hint: "[optional: references='existing artifacts and documents to be considered alongside the codebase']"
-disable-model-invocation: true
-allowed-tools: Read, Bash, Glob, Grep, Write, Task, AskUserQuestion
-model: opus
-effort: max
----
-
-# Map System
-
-Map system-wide codebase structure, architecture, and testing framework into .docs/wiki/system-wide/.
-
-## When to Use
-
-- Before `/ace:help` (brownfield codebases) — understand existing code first
-- After `/ace:help` (greenfield codebases) — document architecture decisions
-- Anytime to refresh system-wide wiki documents
-- Onboarding to an existing codebase (brownfield — analyzes code automatically)
-- Starting a new project and need to document architecture decisions (greenfield — interviews you)
-- System-wide documents are stale or missing
-- After major refactoring that changed subsystem boundaries or tech stack
-
-## Input
-
-### Optional
-
-- **`references`** — Existing architecture docs, ADRs, or design notes to consider alongside the codebase analysis. Absorbed before analysis begins.
-
-## 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
-- **System structure template**: Read [templates/system-structure.xml](templates/system-structure.xml) — output format for system structure
-- **System architecture template**: Read [templates/system-architecture.xml](templates/system-architecture.xml) — output format for system architecture
-- **Testing framework template**: Read [templates/testing-framework.xml](templates/testing-framework.xml) — output format for testing framework
-- **Wiki readme template**: Read [templates/wiki-readme.xml](templates/wiki-readme.xml) — output format for wiki readme
-- **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).
-
-## Artifacts
-
-```
-.docs/wiki/wiki-readme.md              (created if not already present)
-.docs/wiki/system-wide/system-structure.md
-.docs/wiki/system-wide/system-architecture.md
-.docs/wiki/system-wide/testing-framework.md
-CLAUDE.md                              (wiki maintenance instructions appended)
-```
-
-## Example Usage
-
-```
-# Map system from codebase analysis (brownfield)
-/ace:map-system
-
-# Map system with reference docs
-/ace:map-system references="docs/architecture-decisions/"
-
-# Refresh system-wide wiki after refactoring
-/ace:map-system
-```
-
-## Next Steps
-
-After this command, `/clear` first for a fresh context window, then:
-
-- `/ace:map-subsystem subsystem="src/api"` — Map individual subsystem internals
-- `/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
+---
+name: map-system
+description: Map system-wide codebase structure, architecture, and testing framework into .docs/wiki/system-wide/
+argument-hint: "[optional: references='existing artifacts and documents to be considered alongside the codebase']"
+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/system-structure.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/system-architecture.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/testing-framework.xml"`
+
+!`cat "${CLAUDE_SKILL_DIR}/templates/wiki-readme.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>Before /ace:help (brownfield codebases) — understand existing code first</trigger>
+            <trigger>After /ace:help (greenfield codebases) — document architecture decisions</trigger>
+            <trigger>Anytime to refresh system-wide wiki documents</trigger>
+        </runs-after>
+        <use-when>
+            <condition>Onboarding to an existing codebase (brownfield — analyzes code automatically)</condition>
+            <condition>Starting a new project and need to document architecture decisions (greenfield — interviews you)</condition>
+            <condition>System-wide documents are stale or missing</condition>
+            <condition>After major refactoring that changed subsystem boundaries or tech stack</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+            </required>
+
+            <optional>
+                <param name="references" type="file | text">
+                    Existing architecture docs, ADRs, or design notes
+                    to consider alongside the codebase analysis. Absorbed before analysis begins.
+                </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 brownfield/greenfield status and existing wiki state. For each system-wide
+            document (structure, architecture, testing), determine whether to create, update,
+            recreate, scaffold, or skip. Spawn ace-wiki-mapper agents to produce documents.
+            For greenfield architecture, conduct deep questioning before generating.
+            Add CLAUDE.md instructions to keep wiki current with future code changes.
+        </objective>
+
+        <artifacts>
+            - .docs/wiki/wiki-readme.md (created if not already present)
+            - .docs/wiki/system-wide/system-structure.md
+            - .docs/wiki/system-wide/system-architecture.md
+            - .docs/wiki/system-wide/testing-framework.md
+            - CLAUDE.md (wiki maintenance instructions appended)
+        </artifacts>
+    </output>
+
+    <process>
+        Execute the map-system workflow from
+        `workflow.xml` end-to-end.
+        Preserve all workflow gates (validation, user questions, commits).
+    </process>
+
+    <next-steps>
+        **After this command, `/clear` first for a fresh context window, then:**
+        - `/ace:map-subsystems` — Map individual subsystem internals (structure, dependencies)
+        - `/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-system/script.js

@@ -1,84 +1,75 @@
-#!/usr/bin/env node
-
-/**
- * map-system skill script — Entry point for ace-tools operations
- * needed by the map-system skill.
- *
- * Subcommands:
- *   init [args]        Environment detection for map-system workflow
- *
- * Usage: node script.js <subcommand> [args] [--raw]
- */
-
-const fs = require('fs');
-const path = require('path');
-
-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 System ───────────────────────────────────────────────────────
-
-function cmdInit(cwd, raw) {
-  const config = loadConfig(cwd);
-  const brownfield = detectBrownfieldStatus(cwd);
-
-  // Check existing wiki documents
-  const wikiDir = '.docs/wiki/system-wide';
-  const wikiDirExists = pathExists(cwd, wikiDir);
-
-  const has_system_structure = pathExists(cwd, path.join(wikiDir, 'system-structure.md'));
-  const has_system_architecture = pathExists(cwd, path.join(wikiDir, 'system-architecture.md'));
-  const has_testing_framework = pathExists(cwd, path.join(wikiDir, 'testing-framework.md'));
-  const has_coding_standards = pathExists(cwd, path.join(wikiDir, 'coding-standards.md'));
-
-  // List existing wiki files if directory exists
-  let existing_wiki_files = [];
-  if (wikiDirExists) {
-    try {
-      existing_wiki_files = fs.readdirSync(path.join(cwd, wikiDir)).filter(f => f.endsWith('.md'));
-    } catch {}
-  }
-
-  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,
-    existing_wiki_files,
-
-    // Per-document existence
-    has_system_structure,
-    has_system_architecture,
-    has_testing_framework,
-    has_coding_standards,
-
-    // Git state
-    has_git: pathExists(cwd, '.git'),
-  };
-
-  output(result, raw);
-}
+#!/usr/bin/env node
+
+/**
+ * map-system skill script — Entry point for ace-tools operations
+ * needed by the map-system skill.
+ *
+ * Subcommands:
+ *   init [args]        Environment detection for map-system workflow
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const {
+  loadConfig, pathExists, resolveModel,
+  detectBrownfieldStatus, output, error, runSkillScript,
+} = require('../../shared/lib/ace-core');
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+runSkillScript({
+  init: cmdInit,
+});
+
+// ─── Init: Map System ───────────────────────────────────────────────────────
+
+function cmdInit(cwd, raw, args, parsed) {
+  const config = loadConfig(cwd);
+  const brownfield = detectBrownfieldStatus(cwd);
+
+  // Check existing wiki documents
+  const wikiDir = '.docs/wiki/system-wide';
+  const wikiDirExists = pathExists(cwd, wikiDir);
+
+  const has_system_structure = pathExists(cwd, path.join(wikiDir, 'system-structure.md'));
+  const has_system_architecture = pathExists(cwd, path.join(wikiDir, 'system-architecture.md'));
+  const has_testing_framework = pathExists(cwd, path.join(wikiDir, 'testing-framework.md'));
+  const has_coding_standards = pathExists(cwd, path.join(wikiDir, 'coding-standards.md'));
+
+  // List existing wiki files if directory exists
+  let existing_wiki_files = [];
+  if (wikiDirExists) {
+    try {
+      existing_wiki_files = fs.readdirSync(path.join(cwd, wikiDir)).filter(f => f.endsWith('.md'));
+    } catch {}
+  }
+
+  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,
+    existing_wiki_files,
+
+    // Per-document existence
+    has_system_structure,
+    has_system_architecture,
+    has_testing_framework,
+    has_coding_standards,
+
+    // Git state
+    has_git: pathExists(cwd, '.git'),
+  };
+
+  output(result, raw);
+}