agile-context-engineering 0.3.0 → 0.5.0

package/skills/map-subsystem/SKILL.md

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

package/skills/map-subsystem/script.js

@@ -0,0 +1,60 @@
+#!/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);
+}

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>

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

@@ -0,0 +1,137 @@
+<guide>
+    <purpose>
+        Template for `.docs/wiki/subsystems/[subsystem-name]/guides/<task-name>.md` — a step-by-step
+        recipe for a common implementation task. Answers "How do I add/create/implement X?"
+
+        Each guide combines knowledge from multiple systems, patterns, and cross-cutting concerns
+        into one actionable recipe. It is the document an AI agent follows when performing a
+        recurring task end-to-end.
+
+        A "guide" is a task recipe for something developers do repeatedly:
+        e.g., "How to Add a New Drawing Tool", "How to Add a New CRUD Endpoint",
+        "How to Add a New Indicator", "How to Add a New Repository".
+
+        Complements:
+        - patterns/ docs (the structural patterns that guides reference)
+        - systems/ docs (the domain systems where guide steps take place)
+        - cross-cutting/ docs (the registrations and setup that guides include as steps)
+    </purpose>
+
+    <template>
+        <title>
+            # How to [Task]
+        </title>
+
+        <prerequisites>
+            ## Prerequisites
+
+            What you need to know or have in place before starting.
+            - Read: [Pattern Doc](../patterns/relevant-pattern.md) — understand the structural pattern
+            - Read: [System Doc](../systems/relevant-system.md) — understand the domain context
+            - Read: [Cross-Cutting Doc](../cross-cutting/relevant-concern.md) — understand registrations
+        </prerequisites>
+
+        <steps>
+            ## Steps
+
+            ### 1. [First Step]
+
+            What to do, where to do it, reference implementation to copy from.
+            - Create file: `[path]`
+            - Copy from: `file:ExistingImplementation` (closest reference)
+            - Key changes: [what to modify from the reference]
+
+            ### 2. [Second Step]
+
+            ...
+
+            ### 3. [Third Step]
+
+            ...
+        </steps>
+
+        <verification>
+            ## Verification
+
+            How to verify the implementation works.
+            - [ ] [Check 1]: [What to verify and how]
+            - [ ] [Check 2]: [What to verify and how]
+            - [ ] [Check 3]: [What to verify and how]
+        </verification>
+
+        <common-mistakes>
+            ## Common Mistakes
+
+            What people typically get wrong.
+            - [Mistake 1]: [Why it happens and how to avoid it]
+            - [Mistake 2]: [Why it happens and how to avoid it]
+        </common-mistakes>
+    </template>
+
+    <guidelines>
+
+        **Documentation Style:**
+        - EXTREMELY SUCCINCT — every word must add value
+        - NO FLUFF — direct, actionable information only
+        - Numbered steps — the agent follows these in order
+        - Code references as `file-path:ClassName.methodName` (not line numbers)
+        - Inline snippets ONLY for non-obvious configuration or registration code
+        - Every step must have a clear deliverable (a file created, a registration added, etc.)
+
+        **Prerequisites:**
+        - Link to the docs an agent should read BEFORE starting.
+        - Don't repeat content from those docs — just link.
+        - List any tools, dependencies, or environment requirements.
+
+        **Steps:**
+        - NUMBERED, ORDERED steps. An agent follows these sequentially.
+        - Each step has: WHAT to do, WHERE to do it, WHAT to copy from.
+        - Reference existing implementations as "copy from" targets — agents copy patterns, not invent.
+        - Include ALL steps: file creation, registration, configuration, wiring.
+        - Don't skip "obvious" steps — agents don't infer implicit requirements.
+
+        **Verification:**
+        - Checklist format. Agent runs through these after completing all steps.
+        - Include compilation check, runtime check, and behavioral check.
+        - Reference specific files or commands for verification.
+
+        **Common Mistakes:**
+        - Things agents (and developers) typically get wrong on first attempt.
+        - Each mistake should include WHY it happens and HOW to avoid it.
+        - Drawn from actual experience (gotchas from pattern and system docs).
+
+        **What does NOT belong here:**
+        - Detailed pattern explanations (link to patterns/ docs instead)
+        - System domain knowledge (link to systems/ docs instead)
+        - Cross-cutting mechanism details (link to cross-cutting/ docs instead)
+        - Story numbers, sprint context, revision history
+        - Testing strategy or test code (verification section covers basic checks only)
+
+    </guidelines>
+
+    <evolution>
+
+        This is a LIVING document — updated when the recipe changes.
+
+        **Update triggers:**
+        - New step required (new registration, new file to create)
+        - Step removed (registration no longer needed)
+        - Step order changed
+        - New common mistake discovered
+        - Reference implementation changed (new "copy from" target)
+        - Prerequisite docs added or removed
+
+        **NOT an update trigger:**
+        - New feature that follows the existing recipe without changes
+        - Bug fix in one implementation that followed the guide
+        - Internal refactoring that doesn't change the steps
+
+        **Update rules:**
+        - UPDATE steps when the recipe changes
+        - ADD new common mistakes as they are discovered
+        - UPDATE "copy from" references when better examples exist
+        - Keep the guide current — an agent should be able to follow it TODAY
+
+    </evolution>
+
+</guide>