agile-context-engineering 0.2.2 → 0.5.0

package/skills/map-pattern/workflow.xml

@@ -0,0 +1,331 @@
+<workflow>
+
+    <purpose>
+        Create or update a pattern document in
+        `.docs/wiki/subsystems/[subsystem-name]/patterns/`.
+
+        A pattern doc describes a reusable structural approach used by 2+ implementations.
+        It is the document an AI agent reads to ensure new code follows established
+        conventions — structure diagram, how it works, how to apply, current implementations.
+
+        This workflow is executed directly — NO sub-agents are spawned.
+        The executing agent does everything: finding implementations, extracting the
+        abstract pattern, and writing the document.
+    </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 AND VALIDATE                                        -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="setup" order="1">
+
+            <substep order="1.1" name="display-banner">
+                Display stage banner:
+
+                ```
+                ╔══════════════════════════════════════════════════╗
+                ║  ACE > Map Pattern                                 ║
+                ╚══════════════════════════════════════════════════╝
+                ```
+            </substep>
+
+            <substep order="1.2" name="parse-and-validate">
+                Parse $ARGUMENTS for: `text`, `subsystem`, `story-context`, `commits`.
+
+                **If `text` is missing:** Ask the user:
+                - header: "Pattern"
+                - question: "Describe the pattern to document — what structural approach is reused?\nE.g., 'Template Method pattern used by all drawing paths'"
+
+                **If `subsystem` is missing:** Ask the user:
+                - header: "Pattern"
+                - question: "Which subsystem does this pattern belong to?"
+            </substep>
+
+            <substep order="1.3" name="resolve-subsystem">
+                Resolve the subsystem. Check if `.docs/wiki/subsystems/[subsystem-name]/` exists.
+
+                **If not found:**
+                ```
+                  !  No wiki found for subsystem "[subsystem]".
+                     Run /ace:map-subsystem first to create the subsystem wiki.
+                ```
+                Exit.
+
+                Ensure patterns directory exists:
+                ```bash
+                mkdir -p .docs/wiki/subsystems/[subsystem_name]/patterns
+                ```
+            </substep>
+
+            Display:
+            ```
+              i  Pattern: [text description]
+                 Subsystem: [subsystem-name]
+                 Story context: [path/issue, or "none"]
+                 Commits: [value, or "search codebase directly"]
+            ```
+
+            Continue to step 2.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 2: CHECK FOR EXISTING PATTERN DOC                            -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="check-existing" order="2">
+
+            Scan for existing pattern docs:
+
+            ```
+            Glob(pattern='*.md', path='.docs/wiki/subsystems/[subsystem_name]/patterns')
+            ```
+
+            **If existing pattern docs found:**
+            Read their titles and "The Pattern" sections. Check if any covers the same
+            or overlapping structural approach.
+
+            **If overlap detected:**
+            Use AskUserQuestion:
+            - header: "Pattern"
+            - question: "An existing pattern doc may cover a similar approach:\n\n- `[existing-file]`: [title]\n\nShould I update the existing doc or create a new one?"
+            - options:
+              - "Update existing" — set MODE = update, set TARGET_FILE = existing path
+              - "Create new" — set MODE = create
+
+            **If no overlap or no existing pattern docs:** Set MODE = create.
+
+            **If MODE = create:**
+            Derive file name from pattern name in kebab-case.
+            Set TARGET_FILE = `.docs/wiki/subsystems/[subsystem_name]/patterns/[pattern-name].md`
+
+            Continue to step 3.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 3: GATHER CODE CONTEXT AND FIND IMPLEMENTATIONS              -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="gather-context" order="3">
+
+            <substep order="3.1" name="read-story-context">
+                <variant condition="story-context is a path">
+                    Read all markdown files in the story artifacts folder.
+                    Extract: what pattern was used, what was implemented.
+                </variant>
+
+                <variant condition="story-context is a GitHub issue">
+                    ```bash
+                    gh issue view [issue-number] --json title,body,labels,comments
+                    ```
+                    Extract context about the pattern.
+                </variant>
+
+                <variant condition="no story-context">
+                    Skip — discover pattern from codebase only.
+                </variant>
+            </substep>
+
+            <substep order="3.2" name="find-all-implementations">
+                <variant condition="commits provided as number N">
+                    ```bash
+                    git diff --name-only HEAD~[N]..HEAD
+                    ```
+                    Start with changed files. Read them to identify the pattern.
+                    Then search the full codebase for other implementations of the same pattern.
+                </variant>
+
+                <variant condition="commits provided as SHAs">
+                    ```bash
+                    git diff --name-only [first-sha]^..[last-sha]
+                    ```
+                    Start with changed files. Read them to identify the pattern.
+                    Then search the full codebase for other implementations.
+                </variant>
+
+                <variant condition="no commits — search codebase directly">
+                    Use the `text` description to find the pattern and its implementations:
+
+                    1. Read the subsystem's structure.md and architecture.md for orientation
+                    2. Grep for keywords from the text description (base classes, interfaces, etc.)
+                    3. Find the abstract base/interface that defines the pattern
+                    4. Find ALL concrete implementations (use Grep for extends/implements)
+                    5. Read each implementation to understand the pattern mechanics
+                </variant>
+
+                **A pattern requires 2+ implementations.** If only 1 found, ask the user:
+                - header: "Pattern"
+                - question: "I found only 1 implementation of this pattern. Patterns typically need 2+. Should I continue documenting it as a pattern, or is there another implementation I'm missing?"
+            </substep>
+
+            <substep order="3.3" name="extract-pattern-structure">
+                From the implementations, extract the abstract pattern:
+
+                1. What is the base class / interface contract?
+                2. What factory methods / abstract methods must be overridden?
+                3. What is the template method / orchestration flow?
+                4. What are the extension points?
+                5. What registrations/configurations are required?
+                6. What are the common gotchas across implementations?
+
+                Build a complete mental model of the pattern.
+            </substep>
+
+            Continue to step 4.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 4: WRITE THE PATTERN DOC                                     -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="write-doc" order="4">
+
+            Read ALL existing wiki docs under `.docs/wiki/subsystems/[subsystem_name]/`
+            for cross-referencing.
+
+            Follow the pattern template structure exactly.
+
+            <substep order="4.1" name="write-the-pattern">
+                - Title: "# [Pattern Name]"
+                - The Pattern: ONE paragraph — what it is, when to use it.
+                  Name the GoF/industry pattern if applicable, then explain how it
+                  manifests in THIS codebase. Not a textbook definition.
+            </substep>
+
+            <substep order="4.2" name="write-structure">
+                Build a mermaid classDiagram showing the pattern's structure.
+                Show the abstract/interface hierarchy with key method signatures.
+                Show the pattern skeleton — not every concrete implementation.
+            </substep>
+
+            <substep order="4.3" name="write-how-it-works">
+                Numbered steps tracing the pattern's execution flow.
+                Every step references actual code with `file:ClassName.method`.
+                Focus on mechanics an agent needs to understand.
+            </substep>
+
+            <substep order="4.4" name="write-how-to-apply">
+                The MOST ACTIONABLE section. Steps for creating a new instance:
+                - Which files to create
+                - Which registrations to add
+                - Which factories to update
+                - Reference existing implementations as "copy from" targets
+            </substep>
+
+            <substep order="4.5" name="write-current-implementations">
+                Complete list of ALL known implementations with file paths.
+                Agent uses this as a reference gallery.
+            </substep>
+
+            <substep order="4.6" name="write-gotchas">
+                Timing issues, naming conventions, registration requirements, common mistakes.
+                Anything an agent would get wrong on first attempt.
+            </substep>
+
+            <substep order="4.7" name="write-or-update">
+                **If MODE = create:** Write the complete document to TARGET_FILE.
+                **If MODE = update:** Read the existing doc, add new implementations,
+                update How to Apply if changed, add new gotchas. Write to TARGET_FILE.
+            </substep>
+
+            Continue to step 5.
+        </step>
+
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+        <!-- STEP 5: VERIFY, COMMIT, AND REPORT                               -->
+        <!-- ══════════════════════════════════════════════════════════════════ -->
+
+        <step name="verify-and-report" order="5">
+
+            <substep order="5.1" name="quality-check">
+                Re-read TARGET_FILE and verify:
+
+                <verification-checklist>
+                    <check>50+ lines of substantial content</check>
+                    <check>"The Pattern" section present (ONE paragraph, codebase-specific)</check>
+                    <check>Mermaid classDiagram present showing pattern structure</check>
+                    <check>"How It Works" has numbered steps with code references</check>
+                    <check>"How to Apply" is actionable with concrete steps and "copy from" targets</check>
+                    <check>"Current Implementations" lists ALL known implementations with file paths</check>
+                    <check>At least 2 implementations listed (pattern requires 2+)</check>
+                    <check>"Gotchas" section present</check>
+                    <check>Code references use `file:Symbol` format, not line numbers</check>
+                    <check>No textbook definitions — pattern is codebase-specific</check>
+                    <check>No filler phrases, no generic advice</check>
+                </verification-checklist>
+
+                Fix any failures by editing the document directly.
+            </substep>
+
+            <substep order="5.2" name="security-scan">
+                ```
+                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="[TARGET_FILE]",
+                    output_mode="content"
+                )
+                ```
+
+                <variant condition="matches found">SECRETS_FOUND — alert user, do NOT commit.</variant>
+                <variant condition="no matches">CLEAN.</variant>
+            </substep>
+
+            <substep order="5.3" name="commit">
+                ```bash
+                git add [TARGET_FILE]
+                git commit -m "docs([subsystem_name]): add pattern — [pattern-name]"
+                ```
+            </substep>
+
+            <substep order="5.4" name="report">
+                Display:
+
+                ```
+                ╔══════════════════════════════════════════════════╗
+                ║  ACE > Map Pattern > Complete                      ║
+                ╚══════════════════════════════════════════════════╝
+
+                  +  [TARGET_FILE] ([line count] lines)
+
+                     Pattern: [text description]
+                     Implementations found: [count]
+                     Gotchas: [count]
+
+                  Next > /clear first for a fresh context window, then:
+
+                         /ace:map-pattern — create another pattern document
+                         /ace:map-guide — create a guide that uses this pattern
+                         /ace:map-sys-doc — document a system that uses this pattern
+                         Review file at [TARGET_FILE]
+                ```
+            </substep>
+
+            End workflow.
+        </step>
+
+    </process>
+
+    <success_criteria>
+        <criterion>Pattern description parsed and subsystem validated</criterion>
+        <criterion>All implementations discovered (from commits or codebase search)</criterion>
+        <criterion>At least 2 implementations found (pattern requires 2+)</criterion>
+        <criterion>Abstract pattern extracted from implementations</criterion>
+        <criterion>Existing pattern docs checked to avoid duplication (create vs update)</criterion>
+        <criterion>Pattern doc follows template structure from pattern.xml</criterion>
+        <criterion>Mermaid classDiagram present showing pattern structure</criterion>
+        <criterion>"How to Apply" is actionable with concrete steps and "copy from" targets</criterion>
+        <criterion>All current implementations listed with file paths</criterion>
+        <criterion>Gotchas section present with practical warnings</criterion>
+        <criterion>Code references use file:Symbol format, no line numbers</criterion>
+        <criterion>No textbook definitions — pattern is codebase-specific</criterion>
+        <criterion>No filler, no generic advice, no pseudocode</criterion>
+        <criterion>Security scan passed, document committed</criterion>
+    </success_criteria>
+
+</workflow>

package/skills/map-story/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: map-story
+description: Update living knowledge docs — either after a story implementation (git-based, with new subsystem detection) or for existing undocumented code (file-based, called by map-subsystem)
+argument-hint: "story-context='.ace/artifacts/...' commits=3  |  files='a.ts,b.ts' module-name='User Management' subsystem-name='api'"
+disable-model-invocation: true
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Task
+  - AskUserQuestion
+  - Agent
+model: opus
+effort: max
+---
+
+# Map Story
+
+Update living knowledge docs after story implementation or for existing undocumented code.
+
+## When to Use
+
+### Story Mode (invoked by user)
+- After a story is implemented and tested
+- Analyzes git changes (diff) to determine what was built
+- Reads story artifacts for intent context
+- Detects affected subsystem(s) from changed file paths
+- Creates or updates living knowledge docs to reflect the CURRENT system state
+- Detects NEW subsystems not yet in system-structure.md and offers full mapping via map-subsystem
+
+### File Mode (invoked by map-subsystem Step 8.7)
+- Called automatically during subsystem mapping
+- Receives a curated file list + module metadata from module-discovery
+- Documents existing undocumented code — no git diff needed
+- Receives pre-curated existing documentation as additional context
+
+## Input
+
+### Mode Detection
+
+- If `files` is provided → file mode
+- If `story-context` is provided → story mode
+- If neither is provided → story mode (staged + unstaged changes)
+
+### Story Mode Parameters
+
+**Optional:**
+
+- **`story-context`** (path) — Path to story artifacts folder (in `.ace/artifacts/` or legacy `documentation/features/`). Used to understand WHAT the story intended to build. If not provided, the agent relies solely on git changes.
+- **`commits`** (number | comma-separated commit SHAs) — Specifies which commits to analyze. 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: analyze staged + unstaged changes (git diff + git diff --cached).
+- **`tech-debt`** (text | path) — Tech debt items discovered during code review. Can be plain text, YAML, or a path to a file containing the items. When provided, the wiki mapper integrates these items into the relevant subsystem wiki docs (## Tech Debt sections) AND updates the system-wide tech-debt-index.md.
+
+### File Mode Parameters
+
+**Required:**
+
+- **`files`** (comma-separated paths) — Source code files to document. These are the files discovered by module-discovery (Step 8.5) that together form one coherent module.
+- **`module-name`** (text) — Human-readable name of the module (e.g., "User Management", "Repository Pattern").
+- **`subsystem-name`** (text) — Name of the subsystem this module belongs to.
+
+**Optional:**
+
+- **`existing-docs`** (comma-separated paths or directories) — Pre-existing documentation relevant to this module. Accepts file paths, directory paths, or a mix of both. When a directory is provided, recursively discover all files within it. Read these FIRST for additional context about intent, decisions, and history. The actual source code remains the source of truth; existing docs provide the WHY.
+
+## Supporting Resources
+
+Read ALL of these before starting the workflow:
+
+- **Workflow**: Read [workflow.xml](workflow.xml) — complete orchestration process with all steps
+- **System template**: Read [templates/system.xml](templates/system.xml) — system document format
+- **Cross-cutting template**: Read [templates/system-cross-cutting.xml](templates/system-cross-cutting.xml) — cross-cutting concern format
+- **Pattern template**: Read [templates/pattern.xml](templates/pattern.xml) — pattern document format
+- **Guide template**: Read [templates/guide.xml](templates/guide.xml) — guide document format
+- **Walkthrough template**: Read [templates/walkthrough.xml](templates/walkthrough.xml) — walkthrough format
+- **Decisions template**: Read [templates/decizions.xml](templates/decizions.xml) — decisions document format
+- **Tech debt index template**: Read [templates/tech-debt-index.xml](templates/tech-debt-index.xml) — tech debt index format
+- **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
+
+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:** Read the provided source code files (and any existing docs for context), then autonomously create or update living knowledge documents. One call may produce multiple docs across different categories (systems/, patterns/, cross-cutting/, guides/, walkthroughs/, decisions/).
+
+In story mode: analyze git changes to determine what was built, detect affected subsystem(s), identify NEW subsystems not yet in system-structure.md (offering full map-subsystem mapping with user approval), and update/create docs to reflect the CURRENT system state. Also suggests potential walkthroughs for complex flows discovered in the code — the user can choose to create them.
+
+In file mode: document existing undocumented code from the provided file list.
+
+## Artifacts
+
+```
+.docs/wiki/subsystems/[subsystem-name]/systems/[system-name].md
+.docs/wiki/subsystems/[subsystem-name]/patterns/[pattern-name].md
+.docs/wiki/subsystems/[subsystem-name]/cross-cutting/[concern-name].md
+.docs/wiki/subsystems/[subsystem-name]/guides/[guide-name].md
+.docs/wiki/subsystems/[subsystem-name]/walkthroughs/[flow-name].md (if user approves suggestions)
+.docs/wiki/subsystems/[subsystem-name]/decisions/[decision-name].md
+.docs/wiki/system-wide/system-structure.md (updated if new subsystem mapped)
+.docs/wiki/system-wide/system-architecture.md (updated if new subsystem mapped)
+```
+
+## Example Usage
+
+```
+# After a story implementation (staged + unstaged changes)
+/ace:map-story
+
+# After a story with specific commits
+/ace:map-story story-context='.ace/artifacts/product/e1-auth/f2-login/s1-form/s1-form.md' commits=3
+
+# For existing undocumented code (called by map-subsystem)
+/ace:map-story files='a.ts,b.ts' module-name='User Management' subsystem-name='api'
+
+# With tech debt items from code review
+/ace:map-story story-context='.ace/artifacts/...' tech-debt='Missing error handling in auth flow'
+```
+
+## Next Steps
+
+- `/clear` first for a fresh context window
+- `/ace:map-story` — document another story or module
+- `/ace:map-subsystem [subsystem]` — map or refresh an entire subsystem
+- Review and edit files in `.docs/wiki/subsystems/[subsystem-name]/`

package/skills/map-story/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>