agile-context-engineering 0.5.0 → 0.5.1

package/skills/init-coding-standards/script.js

@@ -1,59 +1,50 @@
-#!/usr/bin/env node
-
-/**
- * init-coding-standards skill script — Entry point for ace-tools operations
- * needed by the init-coding-standards skill.
- *
- * Subcommands:
- *   init [args]        Environment detection for init-coding-standards workflow
- *
- * Usage: node script.js <subcommand> [args] [--raw]
- */
-
-const {
-  loadConfig, pathExists,
-  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: Coding Standards ─────────────────────────────────────────────────
-
-function cmdInit(cwd, raw) {
-  const config = loadConfig(cwd);
-  const brownfield = detectBrownfieldStatus(cwd);
-
-  const result = {
-    // Config
-    commit_docs: config.commit_docs,
-
-    // Brownfield detection
-    ...brownfield,
-
-    // Existing coding standards
-    has_coding_standards: pathExists(cwd, '.docs/wiki/system-wide/coding-standards.md'),
-    wiki_dir_exists: pathExists(cwd, '.docs/wiki/system-wide'),
-
-    // Existing wiki context (useful for cross-referencing)
-    has_system_architecture: pathExists(cwd, '.docs/wiki/system-wide/system-architecture.md'),
-    has_system_structure: pathExists(cwd, '.docs/wiki/system-wide/system-structure.md'),
-
-    // Git state
-    has_git: pathExists(cwd, '.git'),
-  };
-
-  output(result, raw);
-}
+#!/usr/bin/env node
+
+/**
+ * init-coding-standards skill script — Entry point for ace-tools operations
+ * needed by the init-coding-standards skill.
+ *
+ * Subcommands:
+ *   init [args]        Environment detection for init-coding-standards workflow
+ *
+ * Usage: node script.js <subcommand> [args] [--raw]
+ */
+
+const {
+  loadConfig, pathExists,
+  detectBrownfieldStatus, output, error, runSkillScript,
+} = require('../../shared/lib/ace-core');
+
+// ─── CLI Dispatch ────────────────────────────────────────────────────────────
+
+runSkillScript({
+  init: cmdInit,
+});
+
+// ─── Init: Coding Standards ─────────────────────────────────────────────────
+
+function cmdInit(cwd, raw, args, parsed) {
+  const config = loadConfig(cwd);
+  const brownfield = detectBrownfieldStatus(cwd);
+
+  const result = {
+    // Config
+    commit_docs: config.commit_docs,
+
+    // Brownfield detection
+    ...brownfield,
+
+    // Existing coding standards
+    has_coding_standards: pathExists(cwd, '.docs/wiki/system-wide/coding-standards.md'),
+    wiki_dir_exists: pathExists(cwd, '.docs/wiki/system-wide'),
+
+    // Existing wiki context (useful for cross-referencing)
+    has_system_architecture: pathExists(cwd, '.docs/wiki/system-wide/system-architecture.md'),
+    has_system_structure: pathExists(cwd, '.docs/wiki/system-wide/system-structure.md'),
+
+    // Git state
+    has_git: pathExists(cwd, '.git'),
+  };
+
+  output(result, raw);
+}

package/skills/init-coding-standards/script.test.js

@@ -1,70 +1,70 @@
-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('init-coding-standards 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.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_coding_standards, 'boolean');
-      assert.strictEqual(typeof result.wiki_dir_exists, 'boolean');
-      assert.strictEqual(typeof result.has_system_architecture, 'boolean');
-      assert.strictEqual(typeof result.has_system_structure, '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('init-coding-standards 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.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_coding_standards, 'boolean');
+      assert.strictEqual(typeof result.wiki_dir_exists, 'boolean');
+      assert.strictEqual(typeof result.has_system_architecture, 'boolean');
+      assert.strictEqual(typeof result.has_system_structure, '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/init-coding-standards/workflow.xml

@@ -10,7 +10,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-cross-cutting/SKILL.md

@@ -1,89 +1,126 @@
----
-name: map-cross-cutting
-description: Create or update a cross-cutting concern doc in .docs/wiki/subsystems/[name]/cross-cutting/ — shared infrastructure spanning multiple systems
-argument-hint: "text='Event system used across all drawing components' 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 Cross-Cutting
-
-Create or update a cross-cutting concern document for shared infrastructure spanning multiple systems.
-
-## When to Use
-
-- When a cross-cutting concern needs dedicated documentation
-- After implementing shared infrastructure that multiple systems depend on
-- When agents need to understand how to register with or plug into shared concerns
-- A concern spans multiple domain systems within a subsystem
-- Multiple systems register with or depend on this infrastructure
-- An agent needs to know WHERE to register and HOW to interact with the concern
-
-## Input
-
-### Required
-
-- **`text`** (text) — Natural language description of the cross-cutting concern to document. Describes WHAT the concern addresses, which systems it spans. E.g.: "Event system used across all drawing components", "Dependency injection container and service registration", "Authentication middleware and authorization pipeline". If not provided, pause and ask the user.
-
-- **`subsystem`** (path | text) — Subsystem where this cross-cutting doc belongs. Wiki location: `.docs/wiki/subsystems/[subsystem]/cross-cutting/`. 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 context about a story that introduced or modified this cross-cutting concern. When not provided, the agent discovers the concern from codebase 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 to find all registration points, usages, and integration points.
-
-## Supporting Resources
-
-Read ALL of these before starting the workflow:
-
-- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
-- **Cross-cutting template**: Read [system-cross-cutting.xml](system-cross-cutting.xml) — output format for the cross-cutting concern doc
-- **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 cross-cutting concern document that describes shared infrastructure spanning multiple systems — how it works, registration/setup points, usage patterns, current registrations, integration points, and gotchas. The document an AI agent reads to understand how to register with or plug into shared concerns when implementing new features.
-
-## Artifacts
-
-```
-.docs/wiki/subsystems/[subsystem-name]/cross-cutting/[concern-name].md
-```
-
-## Example Usage
-
-```
-# Basic cross-cutting concern
-/ace:map-cross-cutting text='Event system used across all drawing components' subsystem='qarc-charts-v2'
-
-# With recent commits for context
-/ace:map-cross-cutting text='Dependency injection container' subsystem='api' commits=3
-
-# With story context
-/ace:map-cross-cutting text='Authentication middleware' subsystem='api' story-context='.ace/artifacts/product/e1-auth/f1-middleware/s1-setup/s1-setup.md'
-```
-
-## Next Steps
-
-- `/clear` first for a fresh context window
-- `/ace:map-cross-cutting` — create another cross-cutting concern doc
-- `/ace:map-sys-doc` — document a system that uses this concern
-- `/ace:map-guide` — create a guide that includes registration steps
-- Review file at `.docs/wiki/subsystems/[subsystem-name]/cross-cutting/`
+---
+name: map-cross-cutting
+description: Create or update a cross-cutting concern doc in .docs/wiki/subsystems/[name]/cross-cutting/ — shared infrastructure spanning multiple systems
+argument-hint: "text='Event system used across all drawing components' 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-cross-cutting.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 cross-cutting concern needs dedicated documentation</trigger>
+            <trigger>After implementing shared infrastructure that multiple systems depend on</trigger>
+            <trigger>When agents need to understand how to register with or plug into shared concerns</trigger>
+        </runs-after>
+        <use-when>
+            <condition>A concern spans multiple domain systems within a subsystem</condition>
+            <condition>Multiple systems register with or depend on this infrastructure</condition>
+            <condition>An agent needs to know WHERE to register and HOW to interact with the concern</condition>
+        </use-when>
+    </execution-time>
+
+    <input>
+        <flags>
+        </flags>
+
+        <parameters>
+            <required>
+                <param name="text" type="text">
+                    Natural language description of the cross-cutting concern to document.
+                    Describes WHAT the concern addresses, which systems it spans.
+
+                    E.g.:
+                    - "Event system used across all drawing components"
+                    - "Dependency injection container and service registration"
+                    - "Authentication middleware and authorization pipeline"
+
+                    If not provided, pause and ask the user.
+                </param>
+                <param name="subsystem" type="path | text">
+                    Subsystem where this cross-cutting doc belongs.
+                    Wiki location: `.docs/wiki/subsystems/[subsystem]/cross-cutting/`.
+                    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 context about a story that introduced or modified
+                    this cross-cutting concern.
+                    When not provided, the agent discovers the concern from codebase 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
+                    to find all registration points, usages, and integration points.
+                </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 cross-cutting concern document that describes shared
+            infrastructure spanning multiple systems — how it works, registration/setup
+            points, usage patterns, current registrations, integration points, and gotchas.
+
+            The document an AI agent reads to understand how to register with or plug
+            into shared concerns when implementing new features.
+        </objective>
+
+        <artifacts>
+            .docs/wiki/subsystems/[subsystem-name]/cross-cutting/[concern-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-cross-cutting 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-cross-cutting — create another cross-cutting concern doc</step>
+        <step>/ace:map-sys-doc — document a system that uses this concern</step>
+        <step>/ace:map-guide — create a guide that includes registration steps</step>
+        <step>Review file at .docs/wiki/subsystems/[subsystem-name]/cross-cutting/</step>
+    </next-steps>
+
+</command>
+```

package/skills/map-cross-cutting/workflow.xml

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