agile-context-engineering 0.3.0 → 0.5.1

package/{agile-context-engineering/workflows/map-system.xml → skills/map-system/workflow.xml}

@@ -1,672 +1,667 @@
-<workflow>
-
-    <purpose>
-        Orchestrate system-wide wiki mapping: detect environment, determine which documents need
-        creation or updates, spawn ace-wiki-mapper agents to produce them, and optionally add
-        CLAUDE.md instructions to keep the wiki current.
-
-        Produces documents in `.docs/wiki/system-wide/`:
-        - system-structure.md — physical layout, subsystem index, shared directories
-        - testing-framework.md — test runner, patterns, conventions
-        - system-architecture.md — L1/L2 views, core flows, tech stack
-
-        Brownfield projects get documents filled from codebase analysis.
-        Greenfield projects get system-architecture.md via deep questioning (structure and testing
-        are scaffolded with headings only — filled as code is added).
-    </purpose>
-
-    <mandatory-context>
-        Read all files referenced by the invoking command's execution-context before starting.
-        Also read any document or text passed as parameter ($ARGUMENTS) in the invoking command.
-    </mandatory-context>
-
-    <process>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 1: SETUP                                                     -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="setup" order="1">
-            **MANDATORY FIRST STEP — Execute environment detection before any user interaction:**
-
-            ```bash
-            INIT=$(node ~/.claude/agile-context-engineering/src/ace-tools.js init map-system)
-            ```
-
-            Parse JSON for: `mapper_model`, `commit_docs`, `is_brownfield`, `is_greenfield`,
-            `has_existing_code`, `has_package_file`, `wiki_dir_exists`, `existing_wiki_files`,
-            `has_system_structure`, `has_system_architecture`, `has_testing_framework`,
-            `has_coding_standards`, `has_git`.
-
-            Also resolve the mapper model for spawning agents:
-            ```bash
-            MAPPER_MODEL=$(node ~/.claude/agile-context-engineering/src/ace-tools.js resolve-model ace-wiki-mapper --raw)
-            ```
-
-            Display stage banner:
-
-            ```
-            ╔══════════════════════════════════════════════════╗
-            ║  ACE > Map System                                ║
-            ╚══════════════════════════════════════════════════╝
-            ```
-
-            **If `has_git` is false:** Initialize git:
-            ```bash
-            git init
-            ```
-
-            Continue to step 2 (document triage).
-        </step>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 2: DOCUMENT TRIAGE                                           -->
-        <!-- Determine per-document action: create, update, recreate, or skip  -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="document-triage" order="2">
-
-            Build a **document action plan** — a list of `{ document, action }` entries where
-            action is one of: `create`, `update`, `recreate`, `scaffold`, `skip`.
-
-            Evaluate each document independently:
-
-            <!-- ── system-structure.md ────────────────────────────────────── -->
-
-            **system-structure.md:**
-
-            If `is_greenfield`:
-            - Action: `scaffold` — create with headings and placeholder sections.
-              The document will be filled as subsystems are added.
-
-            If `is_brownfield` AND `has_system_structure` is false:
-            - Action: `create` — analyze codebase and produce full document.
-
-            If `is_brownfield` AND `has_system_structure` is true:
-            - Use AskUserQuestion:
-              - header: "Structure"
-              - question: "System structure document already exists at `.docs/wiki/system-wide/system-structure.md`. What would you like to do?"
-              - options:
-                - "Update" — Refresh the existing document with current codebase state
-                - "Recreate" — Discard and rebuild from scratch
-                - "Skip" — Keep the current document as-is
-            - Map user choice to action: `update`, `recreate`, or `skip`.
-
-            <!-- ── testing-framework.md ───────────────────────────────────── -->
-
-            **testing-framework.md:**
-
-            If `is_greenfield`:
-            - Action: `scaffold` — create with headings and placeholder sections.
-              Filled once a test framework is chosen and tests are written.
-
-            If `is_brownfield` AND `has_testing_framework` is false:
-            - Action: `create` — analyze codebase and produce full document.
-
-            If `is_brownfield` AND `has_testing_framework` is true:
-            - Use AskUserQuestion:
-              - header: "Testing"
-              - question: "Testing framework document already exists at `.docs/wiki/system-wide/testing-framework.md`. What would you like to do?"
-              - options:
-                - "Update" — Refresh the existing document with current codebase state
-                - "Recreate" — Discard and rebuild from scratch
-                - "Skip" — Keep the current document as-is
-            - Map user choice to action: `update`, `recreate`, or `skip`.
-
-            <!-- ── system-architecture.md ─────────────────────────────────── -->
-
-            **system-architecture.md:**
-
-            If `is_greenfield`:
-            - Action: `create_with_interview` — requires deep questioning before writing.
-              Cannot be scaffolded because architecture decisions must be made upfront.
-
-            If `is_brownfield` AND `has_system_architecture` is false:
-            - Action: `create` — analyze codebase and produce full document.
-
-            If `is_brownfield` AND `has_system_architecture` is true:
-            - Use AskUserQuestion:
-              - header: "Architecture"
-              - question: "System architecture document already exists at `.docs/wiki/system-wide/system-architecture.md`. What would you like to do?"
-              - options:
-                - "Update" — Refresh the existing document with current codebase state
-                - "Recreate" — Discard and rebuild from scratch
-                - "Skip" — Keep the current document as-is
-            - Map user choice to action: `update`, `recreate`, or `skip`.
-
-            **IMPORTANT:** Ask all questions that need asking in a SINGLE AskUserQuestion call
-            where possible (up to 4 questions). If multiple documents exist, batch the questions.
-
-            Display the action plan to the user:
-
-            ```
-            ┌──────────────────────────────────────────────────┐
-            │  ACE > Map System > Action Plan                  │
-            └──────────────────────────────────────────────────┘
-
-              Document                  Action
-              ────────────────────────  ──────────
-              system-structure.md       [create/update/recreate/scaffold/skip]
-              testing-framework.md      [create/update/recreate/scaffold/skip]
-              system-architecture.md    [create/update/recreate/scaffold/skip/create_with_interview]
-            ```
-
-            If ALL actions are `skip`, exit workflow with message:
-            ```
-              i  All documents already exist and were skipped. Nothing to do.
-
-              Next > `/clear` first for a fresh context window, then:
-
-                     /ace:map-subsystems
-                     Map individual subsystem internals.
-            ```
-
-            Continue to step 3 (create directory structure).
-        </step>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 3: CREATE DIRECTORY STRUCTURE                                -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="create-directories" order="3">
-            Create the wiki directory if it doesn't exist:
-
-            ```bash
-            mkdir -p .docs/wiki/system-wide
-            ```
-
-            **Generate wiki-readme.md if it does not already exist:**
-
-            Check if `.docs/wiki/wiki-readme.md` exists. If it does NOT exist, generate it
-            from the wiki-readme template (`~/.claude/agile-context-engineering/templates/wiki/wiki-readme.xml`).
-
-            Read the template's `<template>` section and write the markdown content to
-            `.docs/wiki/wiki-readme.md`. This is a mostly-static meta-document — fill it
-            directly without spawning an agent:
-            - Directory Structure section: use as-is from template (canonical layout)
-            - Document Types tables: use as-is from template
-            - How to Use sections: use as-is from template
-            - Creating New Documents section: use as-is from template
-            - Keeping Current section: use as-is from template
-            - Subsystems table: leave with placeholder rows — will be populated when
-              `/ace:map-subsystem` runs
-
-            If `.docs/wiki/wiki-readme.md` already exists, skip — do not overwrite.
-
-            Continue to step 4.
-        </step>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 4: SYSTEM STRUCTURE                                          -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="system-structure" order="4">
-            Skip this step if system-structure action is `skip`.
-
-            **If action is `scaffold` (greenfield):**
-
-            Create an empty file:
-
-            ```bash
-            touch .docs/wiki/system-wide/system-structure.md
-            ```
-
-            It will be filled by `/ace:map-system` once source code exists.
-
-            **If action is `create` or `recreate`:**
-
-            Spawn ace-wiki-mapper agent:
-
-            ```
-            Task(
-                prompt="Focus: system-structure
-
-                Analyze this codebase and produce the system-wide structure document.
-
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-structure.xml
-                **Output:** Write to .docs/wiki/system-wide/system-structure.md
-
-                Follow the template structure. Fill every section with real data from the codebase.
-                Identify all subsystems (microservices, monolith modules, or library packages).
-
-                Return confirmation only — do NOT return document contents.",
-                subagent_type="ace-wiki-mapper",
-                model="{MAPPER_MODEL}",
-                description="Map system structure"
-            )
-            ```
-
-            **If action is `update`:**
-
-            Spawn ace-wiki-mapper agent with existing content as context:
-
-            ```
-            Task(
-                prompt="Focus: system-structure
-
-                UPDATE the existing system structure document.
-
-                **Current document:** Read .docs/wiki/system-wide/system-structure.md
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-structure.xml
-
-                Compare the current document against the actual codebase state.
-                Update sections that are stale. Add new subsystems or shared directories
-                that were added since the document was written. Remove entries for
-                deleted subsystems or directories.
-
-                Preserve accurate content. Only change what's actually stale.
-
-                Write the updated file to .docs/wiki/system-wide/system-structure.md
-                Return confirmation only — do NOT return document contents.",
-                subagent_type="ace-wiki-mapper",
-                model="{MAPPER_MODEL}",
-                description="Update system structure"
-            )
-            ```
-
-            Continue to step 5.
-        </step>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 5: TESTING FRAMEWORK                                         -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="testing-framework" order="5">
-            Skip this step if testing-framework action is `skip`.
-
-            **NOTE:** This step can run IN PARALLEL with step 4 (system-structure) if both
-            need agent work. Use `run_in_background=true` for the agents in steps 4 and 5,
-            then collect results before step 6.
-
-            **If action is `scaffold` (greenfield):**
-
-            Create an empty file:
-
-            ```bash
-            touch .docs/wiki/system-wide/testing-framework.md
-            ```
-
-            It will be filled by `/ace:map-system` once tests exist.
-
-            **If action is `create` or `recreate`:**
-
-            Spawn ace-wiki-mapper agent:
-
-            ```
-            Task(
-                prompt="Focus: testing-framework
-
-                Analyze this codebase and produce the testing framework document.
-
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/testing-framework.xml
-                **Output:** Write to .docs/wiki/system-wide/testing-framework.md
-
-                Check package.json/config files for test runner and scripts.
-                Read 3-5 existing test files for patterns.
-                Look for test utilities, fixtures, factories.
-                If NO tests exist, write a minimal document noting 'No tests found'
-                instead of a document full of placeholders.
-
-                Return confirmation only — do NOT return document contents.",
-                subagent_type="ace-wiki-mapper",
-                model="{MAPPER_MODEL}",
-                description="Map testing framework"
-            )
-            ```
-
-            **If action is `update`:**
-
-            Spawn ace-wiki-mapper agent with update instructions:
-
-            ```
-            Task(
-                prompt="Focus: testing-framework
-
-                UPDATE the existing testing framework document.
-
-                **Current document:** Read .docs/wiki/system-wide/testing-framework.md
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/testing-framework.xml
-
-                Compare against current codebase state. Update stale sections only.
-                Check for new test runner config, new test patterns, changed coverage settings.
-
-                Write the updated file to .docs/wiki/system-wide/testing-framework.md
-                Return confirmation only — do NOT return document contents.",
-                subagent_type="ace-wiki-mapper",
-                model="{MAPPER_MODEL}",
-                description="Update testing framework"
-            )
-            ```
-
-            Continue to step 6 (wait for parallel agents from steps 4-5 if applicable).
-        </step>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 5.5: COLLECT PARALLEL RESULTS                                -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="collect-parallel" order="5.5">
-            If steps 4 and 5 spawned background agents, wait for both to complete.
-            Read each agent's output to collect confirmations.
-
-            If any agent failed, note the failure and inform the user.
-            Do NOT re-attempt — let the user decide.
-
-            Continue to step 6.
-        </step>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 6: SYSTEM ARCHITECTURE                                       -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="system-architecture" order="6">
-            Skip this step if system-architecture action is `skip`.
-
-            <!-- ── 6a: BROWNFIELD CREATE / RECREATE ──────────────────────── -->
-
-            **If action is `create` or `recreate` AND `is_brownfield`:**
-
-            Spawn ace-wiki-mapper agent directly (codebase provides all the answers):
-
-            ```
-            Task(
-                prompt="Focus: system-architecture
-
-                Analyze this codebase and produce the system-wide architecture document.
-
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml
-                **Output:** Write to .docs/wiki/system-wide/system-architecture.md
-
-                **Also read (if it exists):** .docs/wiki/system-wide/system-structure.md
-                — use the subsystem index from the structure doc to inform the L2 container diagram
-                and subsystem responsibility matrix. Do NOT duplicate content.
-
-                Follow the template structure. Fill every section with real data.
-                Generate C4 L1 and L2 Mermaid diagrams.
-                Trace 1-2 core flows as sequence diagrams.
-                Catalog the tech stack from actual dependency files (versions from lock files).
-
-                Return confirmation only — do NOT return document contents.",
-                subagent_type="ace-wiki-mapper",
-                model="{MAPPER_MODEL}",
-                description="Map system architecture"
-            )
-            ```
-
-            <!-- ── 6b: BROWNFIELD UPDATE ─────────────────────────────────── -->
-
-            **If action is `update`:**
-
-            Spawn ace-wiki-mapper agent with update instructions:
-
-            ```
-            Task(
-                prompt="Focus: system-architecture
-
-                UPDATE the existing system architecture document.
-
-                **Current document:** Read .docs/wiki/system-wide/system-architecture.md
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml
-                **Also read (if it exists):** .docs/wiki/system-wide/system-structure.md
-
-                Compare against current codebase state. Check:
-                - New subsystems or removed subsystems?
-                - New external integrations?
-                - Tech stack changes (new frameworks, version bumps)?
-                - Core flow shape changes?
-
-                Update only stale sections. Preserve accurate content.
-
-                Write the updated file to .docs/wiki/system-wide/system-architecture.md
-                Return confirmation only — do NOT return document contents.",
-                subagent_type="ace-wiki-mapper",
-                model="{MAPPER_MODEL}",
-                description="Update system architecture"
-            )
-            ```
-
-            <!-- ── 6c: GREENFIELD — DEEP QUESTIONING ─────────────────────── -->
-
-            **If action is `create_with_interview` (greenfield):**
-
-            Architecture cannot be inferred from code that doesn't exist yet.
-            Conduct a deep questioning session to gather architecture decisions.
-
-            Follow the questioning guide from `questioning.xml`. You are a thinking partner
-            helping the user articulate their system architecture.
-
-            **Opening:**
-            ```
-            ┌──────────────────────────────────────────────────┐
-            │  ACE > Map System > Architecture Interview        │
-            └──────────────────────────────────────────────────┘
-
-              This is a greenfield project — no codebase to analyze.
-              I need to understand your architecture plans to create
-              the system-architecture document.
-            ```
-
-            **Key areas to explore (adapt based on conversation, don't checklist):**
-
-            1. **System purpose**
-               "In 2-3 sentences, what does this system do and who uses it?"
-
-            2. **Subsystem breakdown**
-               "What are the major components/services/modules?"
-               Use AskUserQuestion:
-               - header: "Topology"
-               - question: "What's your deployment topology?"
-               - options:
-                 - "Monolith" — Single deployable with internal modules
-                 - "Microservices" — Multiple independently deployed services
-                 - "Monorepo packages" — Multiple packages in one repo
-                 - "Hybrid" — Mix of approaches
-
-            3. **External integrations**
-               "What external systems will this integrate with?"
-               (databases, auth providers, third-party APIs, message brokers)
-
-            4. **Communication patterns**
-               If multiple subsystems: "How will they communicate?"
-               - Sync (HTTP/gRPC) vs Async (events/queues) vs Hybrid
-
-            5. **Tech stack**
-               "What technologies are you using?"
-               Use AskUserQuestion:
-               - header: "Backend"
-               - question: "What's your primary backend technology?"
-               - options: (adapt to context, e.g., "Node.js/TypeScript", "C#/.NET", "Python", "Go")
-
-               Follow up for: frontend, database, cache, messaging if applicable.
-
-            6. **Key architectural decisions**
-               "Any architectural patterns you're committed to?"
-               (Clean Architecture, CQRS, Event Sourcing, etc.)
-
-            **Decision gate:**
-            When you understand the architecture:
-            - header: "Ready?"
-            - question: "I have enough to create your architecture document. Ready to generate?"
-            - options:
-              - "Generate" — Create the document
-              - "Keep exploring" — I have more to share
-
-            Loop until "Generate" selected.
-
-            **Then prepare a context brief (300-500 words) that distills:**
-            - System purpose and users
-            - Subsystem breakdown (names, responsibilities)
-            - External integrations (what, direction, protocol)
-            - Communication patterns between subsystems
-            - Tech stack with expected versions
-            - Key architectural decisions
-
-            **Spawn the ace-wiki-mapper agent with the interview context:**
-
-            ```
-            Task(
-                prompt="Focus: system-architecture
-
-                Create the system-wide architecture document for a GREENFIELD project.
-
-                **Architecture brief from user interview:**
-                {paste the context brief here}
-
-                **Template:** Read ~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml
-                **Output:** Write to .docs/wiki/system-wide/system-architecture.md
-
-                **Also read (if it exists):** .docs/wiki/system-wide/system-structure.md
-
-                Follow the template structure. Generate Mermaid C4 diagrams based on the
-                interview data. For greenfield, subsystem boxes in L2 may be planned but
-                not yet implemented — that's fine, document the intended architecture.
-
-                Return confirmation only — do NOT return document contents.",
-                subagent_type="ace-wiki-mapper",
-                model="{MAPPER_MODEL}",
-                description="Write system architecture (greenfield)"
-            )
-            ```
-
-            Continue to step 7.
-        </step>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 7: CLAUDE.MD INSTRUCTIONS                                    -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="claude-md-instructions" order="7">
-            **Add wiki maintenance instructions to CLAUDE.md** so that future code changes
-            trigger wiki updates.
-
-            Check if `CLAUDE.md` exists at project root. If not, create it.
-            If it exists, append the wiki section only if it's not already present.
-
-            Search for "Wiki Maintenance" in CLAUDE.md. If found, skip this step.
-
-            **Content to add:**
-
-            ```markdown
-
-            ## Wiki Maintenance
-
-            When adding, removing, or renaming files or directories:
-            - Update `.docs/wiki/system-wide/system-structure.md` if the change affects subsystem boundaries, shared directories, or root config files.
-            - Update `.docs/wiki/subsystems/[subsystem-name]/structure.md` for any subsystem where files changed.
-
-            When adding a new subsystem, external integration, or changing communication patterns:
-            - Update `.docs/wiki/system-wide/system-architecture.md`.
-
-            When changing test framework, runner, mocking approach, or coverage config:
-            - Update `.docs/wiki/system-wide/testing-framework.md`.
-            ```
-
-            Continue to step 8.
-        </step>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 8: VERIFY AND COMMIT                                         -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="verify-and-commit" order="8">
-            **Verify all expected documents exist and are non-empty:**
-
-            For each document where the action was NOT `skip`:
-            - Check file exists
-            - Check file has content (>5 lines for scaffold, >20 lines for create/update/recreate)
-
-            If any document is missing or empty, warn the user.
-
-            **Security scan** before commit — use the Grep tool (NOT bash grep):
-
-            ```
-            Grep(
-                pattern="(sk-[a-zA-Z0-9]{20,}|sk_live_|sk_test_|ghp_[a-zA-Z0-9]{36}|AKIA[A-Z0-9]{16}|-----BEGIN.*PRIVATE KEY)",
-                path=".docs/wiki/system-wide/",
-                glob="*.md",
-                output_mode="content"
-            )
-            ```
-
-            If matches found: SECRETS_FOUND — pause and alert user.
-            If no matches: CLEAN.
-
-            If SECRETS_FOUND: pause and alert user before committing.
-
-            **Commit** (if `commit_docs` is true):
-
-            ```bash
-            git add .docs/wiki/system-wide/
-            ```
-
-            If wiki-readme.md was created in step 3:
-            ```bash
-            git add .docs/wiki/wiki-readme.md
-            ```
-
-            If CLAUDE.md was created or updated:
-            ```bash
-            git add CLAUDE.md
-            ```
-
-            ```bash
-            git commit -m "docs: map system-wide wiki documents"
-            ```
-
-            Continue to step 9.
-        </step>
-
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-        <!-- STEP 9: COMPLETION                                                -->
-        <!-- ══════════════════════════════════════════════════════════════════ -->
-
-        <step name="completion" order="9">
-            Display completion banner and next steps.
-
-            ```
-            ╔══════════════════════════════════════════════════╗
-            ║  ACE > System Mapped                             ║
-            ╚══════════════════════════════════════════════════╝
-
-              Documents:
-              ──────────
-              [For each document, show action taken and line count]
-              +  wiki-readme.md           ([N] lines) — [created | already exists]
-              +  system-structure.md      ([N] lines) — [created/updated/recreated/scaffolded]
-              +  testing-framework.md     ([N] lines) — [created/updated/recreated/scaffolded]
-              +  system-architecture.md   ([N] lines) — [created/updated/recreated/scaffolded]
-              -  [document]               skipped
-
-              i  Wiki maintenance rules added to CLAUDE.md.
-
-              Next > `/clear` first for a fresh context window, then:
-
-                     /ace:map-subsystems
-                     Map individual subsystem internals.
-
-              Also available (`/clear` first):
-              - /ace:init-coding-standards — Define coding standards
-              - /ace:map-system — Re-run this command to refresh
-              - Review files in .docs/wiki/system-wide/
-            ```
-
-            End workflow.
-        </step>
-
-    </process>
-
-    <success_criteria>
-        - Init function executed (brownfield/greenfield detected, document existence checked)
-        - wiki-readme.md created at .docs/wiki/wiki-readme.md if it did not already exist
-        - Each document triaged independently (create/update/recreate/scaffold/skip)
-        - Greenfield: structure and testing scaffolded, architecture created via interview
-        - Brownfield: all documents created/updated by ace-wiki-mapper agents
-        - Agents spawned in parallel where possible (structure + testing)
-        - CLAUDE.md updated with wiki maintenance instructions
-        - All created documents verified for content (non-empty, non-placeholder for brownfield)
-        - Security scan passed (no secrets in generated docs)
-        - Documents committed to .docs/wiki/system-wide/ (and .docs/wiki/wiki-readme.md)
-        - User sees clear completion summary and next steps
-    </success_criteria>
-
-</workflow>
+<workflow>
+
+    <purpose>
+        Orchestrate system-wide wiki mapping: detect environment, determine which documents need
+        creation or updates, spawn ace-wiki-mapper agents to produce them, and optionally add
+        CLAUDE.md instructions to keep the wiki current.
+
+        Produces documents in `.docs/wiki/system-wide/`:
+        - system-structure.md — physical layout, subsystem index, shared directories
+        - testing-framework.md — test runner, patterns, conventions
+        - system-architecture.md — L1/L2 views, core flows, tech stack
+
+        Brownfield projects get documents filled from codebase analysis.
+        Greenfield projects get system-architecture.md via deep questioning (structure and testing
+        are scaffolded with headings only — filled as code is added).
+    </purpose>
+
+    <mandatory-context>
+        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>
+
+    <process>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 1: SETUP                                                     -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="setup" order="1">
+            **MANDATORY FIRST STEP — Execute environment detection before any user interaction:**
+
+            INIT is available from the preprocessed Environment Context above — do NOT re-run init.
+
+            Parse INIT JSON for: `mapper_model`, `commit_docs`, `is_brownfield`, `is_greenfield`,
+            `has_existing_code`, `has_package_file`, `wiki_dir_exists`, `existing_wiki_files`,
+            `has_system_structure`, `has_system_architecture`, `has_testing_framework`,
+            `has_coding_standards`, `has_git`.
+
+            MAPPER_MODEL is available from INIT.mapper_model — do NOT re-run resolve-model.
+
+            Display stage banner:
+
+            ```
+            ╔══════════════════════════════════════════════════╗
+            ║  ACE > Map System                                ║
+            ╚══════════════════════════════════════════════════╝
+            ```
+
+            **If `has_git` is false:** Initialize git:
+            ```bash
+            git init
+            ```
+
+            Continue to step 2 (document triage).
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 2: DOCUMENT TRIAGE                                           -->
+        <!-- Determine per-document action: create, update, recreate, or skip  -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="document-triage" order="2">
+
+            Build a **document action plan** — a list of `{ document, action }` entries where
+            action is one of: `create`, `update`, `recreate`, `scaffold`, `skip`.
+
+            Evaluate each document independently:
+
+            <!-- ── system-structure.md ────────────────────────────────────── -->
+
+            **system-structure.md:**
+
+            If `is_greenfield`:
+            - Action: `scaffold` — create with headings and placeholder sections.
+              The document will be filled as subsystems are added.
+
+            If `is_brownfield` AND `has_system_structure` is false:
+            - Action: `create` — analyze codebase and produce full document.
+
+            If `is_brownfield` AND `has_system_structure` is true:
+            - Use AskUserQuestion:
+              - header: "Structure"
+              - question: "System structure document already exists at `.docs/wiki/system-wide/system-structure.md`. What would you like to do?"
+              - options:
+                - "Update" — Refresh the existing document with current codebase state
+                - "Recreate" — Discard and rebuild from scratch
+                - "Skip" — Keep the current document as-is
+            - Map user choice to action: `update`, `recreate`, or `skip`.
+
+            <!-- ── testing-framework.md ───────────────────────────────────── -->
+
+            **testing-framework.md:**
+
+            If `is_greenfield`:
+            - Action: `scaffold` — create with headings and placeholder sections.
+              Filled once a test framework is chosen and tests are written.
+
+            If `is_brownfield` AND `has_testing_framework` is false:
+            - Action: `create` — analyze codebase and produce full document.
+
+            If `is_brownfield` AND `has_testing_framework` is true:
+            - Use AskUserQuestion:
+              - header: "Testing"
+              - question: "Testing framework document already exists at `.docs/wiki/system-wide/testing-framework.md`. What would you like to do?"
+              - options:
+                - "Update" — Refresh the existing document with current codebase state
+                - "Recreate" — Discard and rebuild from scratch
+                - "Skip" — Keep the current document as-is
+            - Map user choice to action: `update`, `recreate`, or `skip`.
+
+            <!-- ── system-architecture.md ─────────────────────────────────── -->
+
+            **system-architecture.md:**
+
+            If `is_greenfield`:
+            - Action: `create_with_interview` — requires deep questioning before writing.
+              Cannot be scaffolded because architecture decisions must be made upfront.
+
+            If `is_brownfield` AND `has_system_architecture` is false:
+            - Action: `create` — analyze codebase and produce full document.
+
+            If `is_brownfield` AND `has_system_architecture` is true:
+            - Use AskUserQuestion:
+              - header: "Architecture"
+              - question: "System architecture document already exists at `.docs/wiki/system-wide/system-architecture.md`. What would you like to do?"
+              - options:
+                - "Update" — Refresh the existing document with current codebase state
+                - "Recreate" — Discard and rebuild from scratch
+                - "Skip" — Keep the current document as-is
+            - Map user choice to action: `update`, `recreate`, or `skip`.
+
+            **IMPORTANT:** Ask all questions that need asking in a SINGLE AskUserQuestion call
+            where possible (up to 4 questions). If multiple documents exist, batch the questions.
+
+            Display the action plan to the user:
+
+            ```
+            ┌──────────────────────────────────────────────────┐
+            │  ACE > Map System > Action Plan                  │
+            └──────────────────────────────────────────────────┘
+
+              Document                  Action
+              ────────────────────────  ──────────
+              system-structure.md       [create/update/recreate/scaffold/skip]
+              testing-framework.md      [create/update/recreate/scaffold/skip]
+              system-architecture.md    [create/update/recreate/scaffold/skip/create_with_interview]
+            ```
+
+            If ALL actions are `skip`, exit workflow with message:
+            ```
+              i  All documents already exist and were skipped. Nothing to do.
+
+              Next > `/clear` first for a fresh context window, then:
+
+                     /ace:map-subsystems
+                     Map individual subsystem internals.
+            ```
+
+            Continue to step 3 (create directory structure).
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 3: CREATE DIRECTORY STRUCTURE                                -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="create-directories" order="3">
+            Create the wiki directory if it doesn't exist:
+
+            ```bash
+            mkdir -p .docs/wiki/system-wide
+            ```
+
+            **Generate wiki-readme.md if it does not already exist:**
+
+            Check if `.docs/wiki/wiki-readme.md` exists. If it does NOT exist, generate it
+            from the wiki-readme template (`${CLAUDE_SKILL_DIR}/templates/wiki-readme.xml`).
+
+            Read the template's `<template>` section and write the markdown content to
+            `.docs/wiki/wiki-readme.md`. This is a mostly-static meta-document — fill it
+            directly without spawning an agent:
+            - Directory Structure section: use as-is from template (canonical layout)
+            - Document Types tables: use as-is from template
+            - How to Use sections: use as-is from template
+            - Creating New Documents section: use as-is from template
+            - Keeping Current section: use as-is from template
+            - Subsystems table: leave with placeholder rows — will be populated when
+              `/ace:map-subsystem` runs
+
+            If `.docs/wiki/wiki-readme.md` already exists, skip — do not overwrite.
+
+            Continue to step 4.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 4: SYSTEM STRUCTURE                                          -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="system-structure" order="4">
+            Skip this step if system-structure action is `skip`.
+
+            **If action is `scaffold` (greenfield):**
+
+            Create an empty file:
+
+            ```bash
+            touch .docs/wiki/system-wide/system-structure.md
+            ```
+
+            It will be filled by `/ace:map-system` once source code exists.
+
+            **If action is `create` or `recreate`:**
+
+            Spawn ace-wiki-mapper agent:
+
+            ```
+            Task(
+                prompt="Focus: system-structure
+
+                Analyze this codebase and produce the system-wide structure document.
+
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-structure.xml
+                **Output:** Write to .docs/wiki/system-wide/system-structure.md
+
+                Follow the template structure. Fill every section with real data from the codebase.
+                Identify all subsystems (microservices, monolith modules, or library packages).
+
+                Return confirmation only — do NOT return document contents.",
+                subagent_type="ace-wiki-mapper",
+                model="{MAPPER_MODEL}",
+                description="Map system structure"
+            )
+            ```
+
+            **If action is `update`:**
+
+            Spawn ace-wiki-mapper agent with existing content as context:
+
+            ```
+            Task(
+                prompt="Focus: system-structure
+
+                UPDATE the existing system structure document.
+
+                **Current document:** Read .docs/wiki/system-wide/system-structure.md
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-structure.xml
+
+                Compare the current document against the actual codebase state.
+                Update sections that are stale. Add new subsystems or shared directories
+                that were added since the document was written. Remove entries for
+                deleted subsystems or directories.
+
+                Preserve accurate content. Only change what's actually stale.
+
+                Write the updated file to .docs/wiki/system-wide/system-structure.md
+                Return confirmation only — do NOT return document contents.",
+                subagent_type="ace-wiki-mapper",
+                model="{MAPPER_MODEL}",
+                description="Update system structure"
+            )
+            ```
+
+            Continue to step 5.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 5: TESTING FRAMEWORK                                         -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="testing-framework" order="5">
+            Skip this step if testing-framework action is `skip`.
+
+            **NOTE:** This step can run IN PARALLEL with step 4 (system-structure) if both
+            need agent work. Use `run_in_background=true` for the agents in steps 4 and 5,
+            then collect results before step 6.
+
+            **If action is `scaffold` (greenfield):**
+
+            Create an empty file:
+
+            ```bash
+            touch .docs/wiki/system-wide/testing-framework.md
+            ```
+
+            It will be filled by `/ace:map-system` once tests exist.
+
+            **If action is `create` or `recreate`:**
+
+            Spawn ace-wiki-mapper agent:
+
+            ```
+            Task(
+                prompt="Focus: testing-framework
+
+                Analyze this codebase and produce the testing framework document.
+
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/testing-framework.xml
+                **Output:** Write to .docs/wiki/system-wide/testing-framework.md
+
+                Check package.json/config files for test runner and scripts.
+                Read 3-5 existing test files for patterns.
+                Look for test utilities, fixtures, factories.
+                If NO tests exist, write a minimal document noting 'No tests found'
+                instead of a document full of placeholders.
+
+                Return confirmation only — do NOT return document contents.",
+                subagent_type="ace-wiki-mapper",
+                model="{MAPPER_MODEL}",
+                description="Map testing framework"
+            )
+            ```
+
+            **If action is `update`:**
+
+            Spawn ace-wiki-mapper agent with update instructions:
+
+            ```
+            Task(
+                prompt="Focus: testing-framework
+
+                UPDATE the existing testing framework document.
+
+                **Current document:** Read .docs/wiki/system-wide/testing-framework.md
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/testing-framework.xml
+
+                Compare against current codebase state. Update stale sections only.
+                Check for new test runner config, new test patterns, changed coverage settings.
+
+                Write the updated file to .docs/wiki/system-wide/testing-framework.md
+                Return confirmation only — do NOT return document contents.",
+                subagent_type="ace-wiki-mapper",
+                model="{MAPPER_MODEL}",
+                description="Update testing framework"
+            )
+            ```
+
+            Continue to step 6 (wait for parallel agents from steps 4-5 if applicable).
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 5.5: COLLECT PARALLEL RESULTS                                -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="collect-parallel" order="5.5">
+            If steps 4 and 5 spawned background agents, wait for both to complete.
+            Read each agent's output to collect confirmations.
+
+            If any agent failed, note the failure and inform the user.
+            Do NOT re-attempt — let the user decide.
+
+            Continue to step 6.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 6: SYSTEM ARCHITECTURE                                       -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="system-architecture" order="6">
+            Skip this step if system-architecture action is `skip`.
+
+            <!-- ── 6a: BROWNFIELD CREATE / RECREATE ──────────────────────── -->
+
+            **If action is `create` or `recreate` AND `is_brownfield`:**
+
+            Spawn ace-wiki-mapper agent directly (codebase provides all the answers):
+
+            ```
+            Task(
+                prompt="Focus: system-architecture
+
+                Analyze this codebase and produce the system-wide architecture document.
+
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-architecture.xml
+                **Output:** Write to .docs/wiki/system-wide/system-architecture.md
+
+                **Also read (if it exists):** .docs/wiki/system-wide/system-structure.md
+                — use the subsystem index from the structure doc to inform the L2 container diagram
+                and subsystem responsibility matrix. Do NOT duplicate content.
+
+                Follow the template structure. Fill every section with real data.
+                Generate C4 L1 and L2 Mermaid diagrams.
+                Trace 1-2 core flows as sequence diagrams.
+                Catalog the tech stack from actual dependency files (versions from lock files).
+
+                Return confirmation only — do NOT return document contents.",
+                subagent_type="ace-wiki-mapper",
+                model="{MAPPER_MODEL}",
+                description="Map system architecture"
+            )
+            ```
+
+            <!-- ── 6b: BROWNFIELD UPDATE ─────────────────────────────────── -->
+
+            **If action is `update`:**
+
+            Spawn ace-wiki-mapper agent with update instructions:
+
+            ```
+            Task(
+                prompt="Focus: system-architecture
+
+                UPDATE the existing system architecture document.
+
+                **Current document:** Read .docs/wiki/system-wide/system-architecture.md
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-architecture.xml
+                **Also read (if it exists):** .docs/wiki/system-wide/system-structure.md
+
+                Compare against current codebase state. Check:
+                - New subsystems or removed subsystems?
+                - New external integrations?
+                - Tech stack changes (new frameworks, version bumps)?
+                - Core flow shape changes?
+
+                Update only stale sections. Preserve accurate content.
+
+                Write the updated file to .docs/wiki/system-wide/system-architecture.md
+                Return confirmation only — do NOT return document contents.",
+                subagent_type="ace-wiki-mapper",
+                model="{MAPPER_MODEL}",
+                description="Update system architecture"
+            )
+            ```
+
+            <!-- ── 6c: GREENFIELD — DEEP QUESTIONING ─────────────────────── -->
+
+            **If action is `create_with_interview` (greenfield):**
+
+            Architecture cannot be inferred from code that doesn't exist yet.
+            Conduct a deep questioning session to gather architecture decisions.
+
+            Follow the questioning guide from `questioning.xml`. You are a thinking partner
+            helping the user articulate their system architecture.
+
+            **Opening:**
+            ```
+            ┌──────────────────────────────────────────────────┐
+            │  ACE > Map System > Architecture Interview        │
+            └──────────────────────────────────────────────────┘
+
+              This is a greenfield project — no codebase to analyze.
+              I need to understand your architecture plans to create
+              the system-architecture document.
+            ```
+
+            **Key areas to explore (adapt based on conversation, don't checklist):**
+
+            1. **System purpose**
+               "In 2-3 sentences, what does this system do and who uses it?"
+
+            2. **Subsystem breakdown**
+               "What are the major components/services/modules?"
+               Use AskUserQuestion:
+               - header: "Topology"
+               - question: "What's your deployment topology?"
+               - options:
+                 - "Monolith" — Single deployable with internal modules
+                 - "Microservices" — Multiple independently deployed services
+                 - "Monorepo packages" — Multiple packages in one repo
+                 - "Hybrid" — Mix of approaches
+
+            3. **External integrations**
+               "What external systems will this integrate with?"
+               (databases, auth providers, third-party APIs, message brokers)
+
+            4. **Communication patterns**
+               If multiple subsystems: "How will they communicate?"
+               - Sync (HTTP/gRPC) vs Async (events/queues) vs Hybrid
+
+            5. **Tech stack**
+               "What technologies are you using?"
+               Use AskUserQuestion:
+               - header: "Backend"
+               - question: "What's your primary backend technology?"
+               - options: (adapt to context, e.g., "Node.js/TypeScript", "C#/.NET", "Python", "Go")
+
+               Follow up for: frontend, database, cache, messaging if applicable.
+
+            6. **Key architectural decisions**
+               "Any architectural patterns you're committed to?"
+               (Clean Architecture, CQRS, Event Sourcing, etc.)
+
+            **Decision gate:**
+            When you understand the architecture:
+            - header: "Ready?"
+            - question: "I have enough to create your architecture document. Ready to generate?"
+            - options:
+              - "Generate" — Create the document
+              - "Keep exploring" — I have more to share
+
+            Loop until "Generate" selected.
+
+            **Then prepare a context brief (300-500 words) that distills:**
+            - System purpose and users
+            - Subsystem breakdown (names, responsibilities)
+            - External integrations (what, direction, protocol)
+            - Communication patterns between subsystems
+            - Tech stack with expected versions
+            - Key architectural decisions
+
+            **Spawn the ace-wiki-mapper agent with the interview context:**
+
+            ```
+            Task(
+                prompt="Focus: system-architecture
+
+                Create the system-wide architecture document for a GREENFIELD project.
+
+                **Architecture brief from user interview:**
+                {paste the context brief here}
+
+                **Template:** Read ${CLAUDE_SKILL_DIR}/templates/system-architecture.xml
+                **Output:** Write to .docs/wiki/system-wide/system-architecture.md
+
+                **Also read (if it exists):** .docs/wiki/system-wide/system-structure.md
+
+                Follow the template structure. Generate Mermaid C4 diagrams based on the
+                interview data. For greenfield, subsystem boxes in L2 may be planned but
+                not yet implemented — that's fine, document the intended architecture.
+
+                Return confirmation only — do NOT return document contents.",
+                subagent_type="ace-wiki-mapper",
+                model="{MAPPER_MODEL}",
+                description="Write system architecture (greenfield)"
+            )
+            ```
+
+            Continue to step 7.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 7: CLAUDE.MD INSTRUCTIONS                                    -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="claude-md-instructions" order="7">
+            **Add wiki maintenance instructions to CLAUDE.md** so that future code changes
+            trigger wiki updates.
+
+            Check if `CLAUDE.md` exists at project root. If not, create it.
+            If it exists, append the wiki section only if it's not already present.
+
+            Search for "Wiki Maintenance" in CLAUDE.md. If found, skip this step.
+
+            **Content to add:**
+
+            ```markdown
+
+            ## Wiki Maintenance
+
+            When adding, removing, or renaming files or directories:
+            - Update `.docs/wiki/system-wide/system-structure.md` if the change affects subsystem boundaries, shared directories, or root config files.
+            - Update `.docs/wiki/subsystems/[subsystem-name]/structure.md` for any subsystem where files changed.
+
+            When adding a new subsystem, external integration, or changing communication patterns:
+            - Update `.docs/wiki/system-wide/system-architecture.md`.
+
+            When changing test framework, runner, mocking approach, or coverage config:
+            - Update `.docs/wiki/system-wide/testing-framework.md`.
+            ```
+
+            Continue to step 8.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 8: VERIFY AND COMMIT                                         -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="verify-and-commit" order="8">
+            **Verify all expected documents exist and are non-empty:**
+
+            For each document where the action was NOT `skip`:
+            - Check file exists
+            - Check file has content (>5 lines for scaffold, >20 lines for create/update/recreate)
+
+            If any document is missing or empty, warn the user.
+
+            **Security scan** before commit — use the Grep tool (NOT bash grep):
+
+            ```
+            Grep(
+                pattern="(sk-[a-zA-Z0-9]{20,}|sk_live_|sk_test_|ghp_[a-zA-Z0-9]{36}|AKIA[A-Z0-9]{16}|-----BEGIN.*PRIVATE KEY)",
+                path=".docs/wiki/system-wide/",
+                glob="*.md",
+                output_mode="content"
+            )
+            ```
+
+            If matches found: SECRETS_FOUND — pause and alert user.
+            If no matches: CLEAN.
+
+            If SECRETS_FOUND: pause and alert user before committing.
+
+            **Commit** (if `commit_docs` is true):
+
+            ```bash
+            git add .docs/wiki/system-wide/
+            ```
+
+            If wiki-readme.md was created in step 3:
+            ```bash
+            git add .docs/wiki/wiki-readme.md
+            ```
+
+            If CLAUDE.md was created or updated:
+            ```bash
+            git add CLAUDE.md
+            ```
+
+            ```bash
+            git commit -m "docs: map system-wide wiki documents"
+            ```
+
+            Continue to step 9.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 9: COMPLETION                                                -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="completion" order="9">
+            Display completion banner and next steps.
+
+            ```
+            ╔══════════════════════════════════════════════════╗
+            ║  ACE > System Mapped                             ║
+            ╚══════════════════════════════════════════════════╝
+
+              Documents:
+              ──────────
+              [For each document, show action taken and line count]
+              +  wiki-readme.md           ([N] lines) — [created | already exists]
+              +  system-structure.md      ([N] lines) — [created/updated/recreated/scaffolded]
+              +  testing-framework.md     ([N] lines) — [created/updated/recreated/scaffolded]
+              +  system-architecture.md   ([N] lines) — [created/updated/recreated/scaffolded]
+              -  [document]               skipped
+
+              i  Wiki maintenance rules added to CLAUDE.md.
+
+              Next > `/clear` first for a fresh context window, then:
+
+                     /ace:map-subsystems
+                     Map individual subsystem internals.
+
+              Also available (`/clear` first):
+              - /ace:init-coding-standards — Define coding standards
+              - /ace:map-system — Re-run this command to refresh
+              - Review files in .docs/wiki/system-wide/
+            ```
+
+            End workflow.
+        </step>
+
+    </process>
+
+    <success_criteria>
+        - Init function executed (brownfield/greenfield detected, document existence checked)
+        - wiki-readme.md created at .docs/wiki/wiki-readme.md if it did not already exist
+        - Each document triaged independently (create/update/recreate/scaffold/skip)
+        - Greenfield: structure and testing scaffolded, architecture created via interview
+        - Brownfield: all documents created/updated by ace-wiki-mapper agents
+        - Agents spawned in parallel where possible (structure + testing)
+        - CLAUDE.md updated with wiki maintenance instructions
+        - All created documents verified for content (non-empty, non-placeholder for brownfield)
+        - Security scan passed (no secrets in generated docs)
+        - Documents committed to .docs/wiki/system-wide/ (and .docs/wiki/wiki-readme.md)
+        - User sees clear completion summary and next steps
+    </success_criteria>
+
+</workflow>