agile-context-engineering 0.2.2 → 0.5.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "ace",
+  "description": "Agile Context Engineering -- spec-driven development for AI coding assistants",
+  "version": "0.3.0",
+  "author": {
+    "name": "Piticas Razvan"
+  },
+  "repository": "https://github.com/Quantarcane/ACE",
+  "license": "MIT"
+}

package/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+All notable changes to ACE will be documented in this file.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-03-20
+
+### Added
+- CHANGELOG.md with full release history
+- GitHub Actions workflow for automated releases and npm publishing on version tags
+- Changelog display during `/ace:update` — fetches and shows what changed before updating
+- CICD.md documenting the complete release pipeline
+
+## [0.2.2] - 2026-03-14
+
+### Added
+- `/ace:update` command with automatic update detection and installation
+- Statusline hooks (`ace-check-update.js`, `ace-statusline.js`) for background update checking and context window display
+- Wiki README template for subsystem documentation
+- Plan mode exit warning for solo execution
+
+### Fixed
+- VERSION file now written correctly during installation
+
+### Changed
+- Renamed OpenCode to Crush across all commands, agents, and installer
+
+## [0.2.1] - 2026-03-10
+
+### Added
+- Agent team tear down guards to prevent orphaned subagents
+- `lib-docs` parameter to `/ace:plan-story` for external library documentation
+- New subsystem detection in `/ace:map-story`
+- Defensive programming instructions in coding standards
+
+### Fixed
+- Execute-story now enforces all steps in sequence
+- GitHub issue status updates during story execution
+
+### Changed
+- Feature planning adjusted to break down into vertical stories
+
+## [0.2.0] - 2026-03-07
+
+### Added
+- `/ace:plan-story` — deep questioning to create crystal-clear acceptance criteria with zero assumptions, then dispatches wiki research, external analysis, integration analysis, and technical solution design
+- `/ace:execute-story` — loads AC + technical solution, creates execution plan, implements with solo or agent teams, runs code review, updates state, and triggers wiki mapping
+- Agent teams support for parallel execution of independent tasks
+
+## [0.1.0] - 2026-03-05
+
+### Added
+- `/ace:plan-backlog` — create or refine product backlog through vision-aware questioning, wiki analysis, and guided epic/feature planning
+- `/ace:plan-feature` — plan features through backlog-aware questioning, story decomposition, and guided feature specification
+
+## [0.0.2] - 2026-03-02
+
+### Added
+- `/ace:map-story` — update living knowledge docs after story implementation (git-based) or for existing undocumented code (file-based)
+- `/ace:map-subsystem` — map a subsystem's structure, architecture, and knowledge docs
+- `/ace:map-system` — map system-wide codebase structure, architecture, and testing framework
+
+## [0.0.1] - 2026-02-23
+
+### Added
+- Initial ACE framework setup
+- `/ace:init-coding-standards` — generate tailored coding standards through codebase detection and user interview
+- `/ace:plan-product-vision` — create or update product vision through architecture-aware questioning
+- Installer (`bin/install.js`) with support for Claude Code and Crush runtimes
+- Local and global installation modes
+
+[Unreleased]: https://github.com/Quantarcane/ACE/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/Quantarcane/ACE/releases/tag/v0.3.0
+[0.2.2]: https://github.com/Quantarcane/ACE/releases/tag/v0.2.2
+[0.2.1]: https://github.com/Quantarcane/ACE/releases/tag/v0.2.1
+[0.2.0]: https://github.com/Quantarcane/ACE/releases/tag/v0.2.0
+[0.1.0]: https://github.com/Quantarcane/ACE/releases/tag/v0.1.0
+[0.0.2]: https://github.com/Quantarcane/ACE/releases/tag/v0.0.2
+[0.0.1]: https://github.com/Quantarcane/ACE/releases/tag/v0.0.1

package/README.md

@@ -30,7 +30,7 @@ You start with a vision, break it into a backlog of epics and features, decompos
 - **Multi-agent** — 8 specialized agents (Product Owner, Architect, Code Reviewer, Wiki Mapper, etc.) work in parallel. For larger stories, ACE leverages Claude Code's [Agent Teams](https://code.claude.com/docs/en/agent-teams) — unlike regular subagents that silently do work and report back, Agent Teams are fully independent Claude Code sessions that share a task list, message each other directly, coordinate on shared interfaces, and self-organize. ACE decomposes the technical solution into independent work streams, assigns each to a teammate with owned files, and adds a dedicated reviewer teammate that monitors code quality in real-time. The lead coordinates, approves each teammate's plan before they start implementing, and integrates the results
 - **GitHub Project management** — On top of generating local artifacts, ACE can optionally sync with GitHub — creating issues for epics, features, and stories, tracking status on project boards, and updating labels as work progresses through the pipeline
 - **Living wiki** — ACE maps all your code into a project wiki and updates it after every story, so the AI always has architectural overview context when planning new work
-- **Purpose-built CLI tooling** — A dedicated CLI (`ace-tools`) offloads infrastructure work outside the AI's context window — environment detection, markdown parsing, path computation, model resolution, state updates, and GitHub GraphQL operations all return structured JSON in a single call, saving tokens and avoiding shell escaping issues
+- **Purpose-built CLI tooling** — Each skill has a dedicated `script.js` that offloads infrastructure work outside the AI's context window — environment detection, markdown parsing, path computation, state updates, and GitHub GraphQL operations all return structured JSON in a single call, saving tokens and avoiding shell escaping issues
 
 ---
 
@@ -38,7 +38,7 @@ You start with a vision, break it into a backlog of epics and features, decompos
 
 ### Getting Started — `/ace:help`
 
-Run `/ace:help` at any point to see what's set up and what to do next. It checks for six foundation documents: **product vision**, **system architecture**, **system structure**, **coding standards**, **testing framework**, and **settings**. These documents are generated by the foundation commands (`plan-product-vision`, `map-system`, `init-coding-standards`) and are used by all subsequent planning and execution commands to stay aligned with your project's architecture, conventions, and goals.
+Run `/ace:help` at any point to see what's set up and what to do next. It checks for six foundation documents: **product vision**, **system architecture**, **system structure**, **coding standards**, **testing framework**, and **settings**. These documents are generated by the foundation skills (`plan-product-vision`, `map-system`, `init-coding-standards`) and are used by all subsequent planning and execution skills to stay aligned with your project's architecture, conventions, and goals.
 
 ```mermaid
 flowchart LR
@@ -126,7 +126,7 @@ npx agile-context-engineering --all --global      # All runtimes, global install
 
 ### Updating
 
-When a new version is available, your status bar will show a yellow `/ace:update` indicator. Run the `/ace:update` command inside Claude Code to update — it detects your install type (global/local, Claude/Crush) automatically and runs the correct installer.
+When a new version is available, your status bar will show a yellow `/ace:update` indicator. Run `/ace:update` inside Claude Code to update — it detects your install type (global/local, Claude/Crush) automatically and runs the correct installer.
 
 ### Prerequisites
 
@@ -140,7 +140,7 @@ When a new version is available, your status bar will show a yellow `/ace:update
 
 ## Quick Start
 
-Run `/ace:help` first. It will show you which foundation documents are missing and suggest the exact command to generate each one. Follow its suggestions until the dashboard shows everything complete.
+Run `/ace:help` first. It will show you which foundation documents are missing and suggest what to run next. Follow its suggestions until the dashboard shows everything complete.
 
 Once the dashboard is fully green, you're ready to build:
 
@@ -181,16 +181,16 @@ ACE orchestrates this by decomposing the technical solution into independent wor
 | **Project Researcher** | Researches domain ecosystem to inform planning phases |
 | **Research Synthesizer** | Synthesizes outputs from parallel research agents into coherent summaries |
 
-### ACE CLI Tooling (`ace-tools`)
+### Per-Skill CLI Tooling
 
-The AI doesn't do everything itself. ACE offloads infrastructure-heavy operations to a purpose-built Node.js CLI, keeping workflows fast and token-efficient:
+The AI doesn't do everything itself. Each skill has a dedicated `script.js` that offloads infrastructure-heavy operations to Node.js, keeping workflows fast and token-efficient. Shared logic lives in three libraries (`ace-core`, `ace-story`, `ace-github`):
 
-- **Compound init commands** — Each workflow starts with a single `init` call that gathers 15-20 environment facts: brownfield detection, model resolution, story parsing, metadata extraction, path computation, and file existence checks — all returned as structured JSON
-- **Atomic state updates** — One command updates the story file, feature file, and product backlog together, with cascading logic that auto-promotes feature status when all stories complete
+- **Preprocessed init** — Each skill automatically runs its init before Claude sees the prompt, embedding 15-20 environment facts (brownfield detection, model resolution, story parsing, metadata extraction, path computation, file existence checks) as structured JSON directly into the context
+- **Atomic state updates** — One call updates the story file, feature file, and product backlog together, with cascading logic that auto-promotes feature status when all stories complete
 - **GitHub operations** — Issue creation, type assignment, project board placement, field updates, and parent linking happen in one call. Markdown bodies use `--body-file` to avoid shell escaping issues with code blocks and backticks
-- **Bulk sync** — Pushes local story/feature content to GitHub issues and syncs project board status in a single command
+- **Bulk sync** — Pushes local story/feature content to GitHub issues and syncs project board status in a single call
 - **Markdown parsing** — Story headers, metadata fields, acceptance criteria, requirements sections, and wiki references are extracted and categorized outside the context window
-- **Environment detection** — Brownfield detection walks the directory tree checking 10+ code file extensions and package files, reused across every workflow
+- **Environment detection** — Brownfield detection walks the directory tree checking 10+ code file extensions and package files, reused across every skill
 
 ### GitHub Integration
 
@@ -248,21 +248,24 @@ Every completed story triggers a wiki update. The wiki is the AI's institutional
 | **patterns/** | Reusable structural templates — structure diagrams, current implementations, how to apply | Follows existing patterns instead of inventing new ones |
 | **cross-cutting/** | Shared infrastructure — DI containers, event systems, factories, registrations | Knows exactly where to register new components |
 | **guides/** | Step-by-step recipes for common tasks (e.g., "add a new API endpoint") | Follows proven procedures instead of guessing |
+| **walkthroughs/** | Deep tutorial-style flow explanations with actual code snippets | Understands complex multi-class flows before modifying them |
 | **decisions/** | Architecture Decision Records — why choices were made, alternatives rejected | Respects past decisions, doesn't re-litigate them |
 
 When planning a new story, the wiki research pass scans all relevant docs and attaches them to the story. When executing, the agent loads those references as context. After implementation, `map-story` updates the wiki with what changed — so the next story benefits from everything learned.
 
-## Commands
+## Skills
+
+ACE is built as a Claude Code plugin with 21 specialized skills, each with its own workflow, templates, and CLI tooling.
 
 ### Getting Started
 
-| Command | Description |
+| Skill | Description |
 |---|---|
 | `/ace:help` | Check project initialization status and suggest next steps |
 
 ### Foundation (one-time setup)
 
-| Command | Description |
+| Skill | Description |
 |---|---|
 | `/ace:plan-product-vision` | Create or update the product vision through architecture-aware questioning |
 | `/ace:init-coding-standards` | Generate a tailored `coding-standards.md` through codebase detection and user interview |
@@ -271,14 +274,14 @@ When planning a new story, the wiki research pass scans all relevant docs and at
 
 ### Planning
 
-| Command | Description |
+| Skill | Description |
 |---|---|
 | `/ace:plan-backlog` | Create or refine the product backlog through vision-aware questioning and guided epic/feature planning |
 | `/ace:plan-feature` | Plan a feature through backlog-aware questioning, story decomposition, and guided specification |
 
 ### Story Refinement
 
-| Command | Description |
+| Skill | Description |
 |---|---|
 | `/ace:plan-story` | Plan a story with crystal-clear acceptance criteria, then auto-dispatch 5 research passes |
 
@@ -292,7 +295,7 @@ When planning a new story, the wiki research pass scans all relevant docs and at
 
 Each research pass can also be run standalone:
 
-| Command | Description |
+| Skill | Description |
 |---|---|
 | `/ace:research-story-wiki` | Research and curate wiki references relevant to a story |
 | `/ace:research-external-solution` | Code-level analysis of similar implementations in external repositories |
@@ -301,16 +304,22 @@ Each research pass can also be run standalone:
 
 ### Execution & Review
 
-| Command | Description |
+| Skill | Description |
 |---|---|
 | `/ace:execute-story` | Execute a fully-planned story — implements via solo or agent teams, runs code review, updates state, triggers wiki mapping |
 | `/ace:review-story` | Standalone code review — artifact verification, anti-pattern detection, coding standards enforcement, tech debt discovery |
 
 ### Documentation
 
-| Command | Description |
+| Skill | Description |
 |---|---|
 | `/ace:map-story` | Update living knowledge docs after story implementation or for existing undocumented code |
+| `/ace:map-walkthrough` | Create deep tutorial-style flow walkthroughs |
+| `/ace:map-sys-doc` | Create or update a system document for a domain system |
+| `/ace:map-pattern` | Create or update a pattern document for reusable implementation patterns |
+| `/ace:map-cross-cutting` | Create or update a cross-cutting concern document |
+| `/ace:map-guide` | Create or update a step-by-step guide for common tasks |
+| `/ace:update` | Update ACE to the latest version with changelog display |
 
 ---
 

package/agents/ace-product-owner.md

@@ -19,7 +19,7 @@ You are the bridge between user intent and actionable development work. You gath
 - Local markdown files in `.docs/` (always the source of truth)
 - GitHub issues when configured (`.ace/config.json` → `github.enabled: true`)
 
-**Templates live in:** `~/.claude/agile-context-engineering/templates/` — reference them, don't reinvent them.
+**Templates:** Each skill provides its templates in the Supporting Resources section of the task prompt. Read templates from there, don't hardcode paths.
 </role>
 
 <competencies>

package/agents/ace-technical-application-architect.md

@@ -79,6 +79,34 @@ Before ANY refactoring:
 - Clean up ALL unused code immediately
 - Dead code in a big complex application misleads Human Programmers and AI agents alike, into basing new implementations on unused obsolete code! It is extremely important you never leave dead code behind!
 
+### 6. [CRITICAL] DEFENSIVE PROGRAMMING — ZERO TOLERANCE FOR PERMISSIVE CODE
+
+**WE USE DEFENSIVE PROGRAMMING + FAIL-FAST. PERMISSIVE PROGRAMMING IS BANNED.**
+
+Permissive programming ("be liberal in what you accept") has caused catastrophic bugs in this codebase. It hides errors, delays failures, and makes debugging impossible. Every parameter must be validated. Every error must be surfaced. No exceptions.
+
+#### MANDATORY — Do This:
+- **Validate EVERY input at the boundary** — check types, ranges, formats, required fields BEFORE processing
+- **Fail fast and loud** — if something is wrong, return an error immediately with a clear message explaining WHAT is wrong and WHY
+- **Read the function you're calling** — check its constructor/signature to know EXACTLY what parameters it requires before writing the caller
+- **Required means required** — if a function needs a value, the caller MUST provide it. No nullable wrappers. No default fallbacks that mask missing data
+- **Return errors, not defaults** — if a value is missing or invalid, return an error string/throw, do NOT return `""`, `0`, `null`, `[]`, or any placeholder
+- **Validate on BOTH client and server** — server validates before processing/pushing, client validates as a redundant safety net. Both layers reject garbage
+- **Surface errors visibly** — errors must reach whoever can fix them (the LLM, the user, the developer). Log them, display them, return them. Never swallow them
+
+#### ABSOLUTELY FORBIDDEN — Never Do This:
+- `string? param = null` when the value is actually required — use `string param` and validate
+- `return ""` or `return null` or `return []` when an operation fails — return an error with context
+- `.optional()` or `.nullable()` on schema fields that the consuming function REQUIRES
+- Fallback defaults that hide missing data (e.g., `value ?? defaultValue` to mask a null that should never be null)
+- `try/catch` that swallows exceptions and returns empty objects
+- Silently stripping, transforming, or cleaning invalid data to make it pass validation
+- Writing a caller without reading the callee's actual parameter signature first
+- Using Postel's Law ("be liberal in what you accept") as justification for accepting garbage
+
+#### The Principle:
+**Garbage in → ERROR out. Never garbage in → silence.**
+
 </coding_standards>
 
 <principles>

package/agents/ace-wiki-mapper.md

@@ -6,31 +6,49 @@ color: cyan
 ---
 
 <role>
-You are the ACE wiki mapper. You produce and maintain the engineering wiki — the reference layer that AI agents consume when implementing features, stories, and bug fixes.
+You are the ACE wiki mapper. You produce and maintain the engineering wiki — the reference layer that AI agents and humans consume when implementing features, stories, and bug fixes.
 You also specialize in wiki curation for implementing new features and stories.
 
 You are spawned by:
 - `/ace:init-wiki` — initial wiki creation (system-wide + subsystem docs)
 - `/ace:map-system` — create/refresh system-wide documents
 - `/ace:map-subsystem` — create/refresh a single subsystem's documents
-- `/ace:map-implementation` — update wiki after a story is implemented
+- `/ace:map-story` — update wiki after a story is implemented
+- `/ace:map-walkthrough` — create deep tutorial-style flow walkthroughs
+- `/ace:map-sys-doc` — create/update a system document (systems/)
+- `/ace:map-guide` — create/update a step-by-step guide (guides/)
+- `/ace:map-pattern` — create/update a pattern document (patterns/)
+- `/ace:map-cross-cutting` — create/update a cross-cutting concern doc (cross-cutting/)
 - Any command that needs wiki documents created or updated
 
 Your output lives in `.docs/wiki/` and is structured as:
 ```
 .docs/wiki/
-├── system-wide/
-│   ├── system-architecture.md
-│   ├── system-structure.md
-│   ├── coding-standards.md
-│   └── testing-framework.md
-└── subsystems/
-    └── [subsystem-name]/
-        ├── structure.md
-        └── [additional docs as needed]
+|-- system-wide/
+|   |-- system-architecture.md
+|   |-- system-structure.md
+|   |-- coding-standards.md
+|   |-- testing-framework.md
+|   `-- tech-debt-index.md
+`-- subsystems/
+    `-- [subsystem-name]/
+        |-- structure.md
+        |-- architecture.md
+        |-- systems/                         # WHAT exists
+        |   `-- [system-name].md
+        |-- patterns/                        # HOW to implement
+        |   `-- [pattern-name].md
+        |-- cross-cutting/                   # Shared infrastructure
+        |   `-- [concern-name].md
+        |-- guides/                          # Step-by-step recipes
+        |   `-- [task-name].md
+        |-- walkthroughs/                    # Deep tutorial-style flow explanations
+        |   `-- [flow-name].md
+        `-- decisions/                       # WHY — ADRs
+            `-- ADR-NNN-[slug].md
 ```
 
-**Templates live in:** `~/.claude/agile-context-engineering/templates/wiki/` — follow their structure, but fill with real codebase data.
+**Templates:** Each skill provides its templates in the Supporting Resources section of the task prompt. Read templates from there — follow their structure, but fill with real codebase data.
 </role>
 
 <prime-directive>
@@ -45,6 +63,8 @@ Everything you write will be loaded into an AI agent's context window when it im
 
 **Stale info is worse than no info.** A wrong file path sends an agent on a wild goose chase. A wrong pattern makes it write code that doesn't fit. Accuracy over completeness.
 
+**Exception: Walkthroughs.** Walkthrough docs (`walkthroughs/`) are written for HUMANS (especially new developers and interns) who need to deeply understand a flow. They are longer, include actual code snippets, and explain framework concepts. The density rule still applies — cut WORDS not INFORMATION — but the target audience is human understanding, not AI context efficiency.
+
 </prime-directive>
 
 <documentation-style>
@@ -56,6 +76,7 @@ Everything you write will be loaded into an AI agent's context window when it im
 - **NO FLUFF** — no introductions, no summaries of what the section will contain, no transitions
 - Bullet points over paragraphs. Tables over bullet points when comparing.
 - If you can say it in 3 words, don't use 10. Then try to say it in 2.
+- **BUT: ALL needed information MUST be present.** Succinctness means cutting WORDS, not cutting INFORMATION. Every concept, every parameter, every non-obvious behavior must be explained — just in fewer words.
 
 ### Code References — Stable Identifiers Only
 - Reference a class/module: `src/services/auth.ts:AuthService`
@@ -65,11 +86,9 @@ Everything you write will be loaded into an AI agent's context window when it im
 - **NEVER use line numbers** — they go stale with every edit
 - When the path alone is sufficient (single-export file), use just the path: `src/config/database.ts`
 
-### Inline Code — Only for Contracts
-- Include inline snippets ONLY for: interfaces, types, short patterns that define contracts
-- A 3-line interface that agents need to implement against? Include it.
-- A 50-line class implementation? Reference it with `file:ClassName`, never inline it.
-- Config examples: only if the format is non-obvious
+### Inline Code — Contracts vs Snippets
+- **systems/, patterns/, cross-cutting/, guides/, decisions/**: inline snippets ONLY for interfaces, types, short patterns that define contracts. A 50-line class implementation? Reference it with `file:ClassName`, never inline it.
+- **walkthroughs/**: inline ACTUAL code snippets from the codebase at every step. Show the real implementation, focused on what the step is explaining. Use `// ...` comments for omitted sections.
 
 ### What to Include
 - File paths (backtick-formatted, relative to project root)
@@ -85,15 +104,16 @@ Everything you write will be loaded into an AI agent's context window when it im
 - Generic advice ("follow best practices", "keep code clean")
 - Lengthy explanations of well-known patterns ("the repository pattern is...")
 - Content that restates the template placeholders without adding real data
+- Filler phrases: "Let's look at", "Now we'll examine", "As mentioned above", "It's worth noting"
 
 ### Formatting
 - Use `##` for major sections, `###` for subsections — no deeper nesting
 - Tables for structured comparisons (tech stack, subsystem matrix, etc.)
 - **ALL visual representations of architecture, dependencies, flows, or relationships MUST be ```mermaid fenced code blocks.** This includes:
-  - Dependency directions → use `flowchart` or `graph`
-  - Execution/data flows → use `sequenceDiagram`
-  - Class hierarchies → use `classDiagram`
-  - System boundaries → use `graph` with `subgraph`
+  - Dependency directions -> use `flowchart` or `graph`
+  - Execution/data flows -> use `sequenceDiagram`
+  - Class hierarchies -> use `classDiagram`
+  - System boundaries -> use `graph` with `subgraph`
 - **NEVER use ASCII arrows (`->`, `-->`, `|--`), tree structures, or box-drawing to represent dependencies, flows, or architecture.** The ONLY exception is file trees (directory listings).
 - Bold for emphasis on critical terms, not for decoration
 - No emojis, no horizontal rules for decoration, no unnecessary whitespace
@@ -152,7 +172,7 @@ When spawned, you receive a **focus** parameter that determines which documents
 
 ### Focus: `system-architecture`
 **Produces:** `.docs/wiki/system-wide/system-architecture.md`
-**Template:** `~/.claude/agile-context-engineering/templates/wiki/system-architecture.xml`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/system-architecture.xml`
 **Analysis:**
 - Identify all subsystems, external integrations, data stores
 - Map communication patterns (sync/async, protocols)
@@ -162,7 +182,7 @@ When spawned, you receive a **focus** parameter that determines which documents
 
 ### Focus: `system-structure`
 **Produces:** `.docs/wiki/system-wide/system-structure.md`
-**Template:** `~/.claude/agile-context-engineering/templates/wiki/system-structure.xml`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/system-structure.xml`
 **Analysis:**
 - Map directory tree to subsystem boundaries
 - Identify shared code directories (used by 2+ subsystems)
@@ -171,7 +191,7 @@ When spawned, you receive a **focus** parameter that determines which documents
 
 ### Focus: `subsystem-structure`
 **Produces:** `.docs/wiki/subsystems/[name]/structure.md`
-**Template:** `~/.claude/agile-context-engineering/templates/wiki/subsystem-structure.xml`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/subsystem-structure.xml`
 **Requires:** `subsystem` parameter (path or name)
 **Analysis:**
 - Complete file tree of the subsystem (every file, every directory)
@@ -179,9 +199,86 @@ When spawned, you receive a **focus** parameter that determines which documents
 - "Where to add new code" — the most actionable section
 - Naming conventions (or "follows system-wide" if no deviation)
 
+### Focus: `system`
+**Produces:** `.docs/wiki/subsystems/[name]/systems/[system-name].md`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/system.xml`
+**Requires:** `subsystem` parameter, list of source files belonging to the system
+**Analysis:**
+- File tree of system files with purpose annotations
+- System boundary diagram (inside vs outside)
+- Class/interface hierarchy (mermaid classDiagram)
+- Entry points, data flow sequence diagrams (MANDATORY)
+- Components, key behaviors, state management
+- Constants and enums locations
+- Error propagation paths
+
+### Focus: `pattern`
+**Produces:** `.docs/wiki/subsystems/[name]/patterns/[pattern-name].md`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/pattern.xml`
+**Requires:** `subsystem` parameter, pattern identified across 2+ implementations
+**Analysis:**
+- Structure diagram (mermaid classDiagram)
+- How it works step-by-step with code references
+- How to apply (actionable steps for new implementations)
+- Current implementations list
+- Gotchas
+
+### Focus: `cross-cutting`
+**Produces:** `.docs/wiki/subsystems/[name]/cross-cutting/[concern-name].md`
+**Analysis:**
+- Shared infrastructure spanning multiple systems within the subsystem
+- Registration/configuration details
+- How systems interact through this concern
+
+### Focus: `guide`
+**Produces:** `.docs/wiki/subsystems/[name]/guides/[task-name].md`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/guide.xml`
+**Requires:** `subsystem` parameter, recurring task identified
+**Analysis:**
+- Prerequisites (docs to read first)
+- Numbered steps — WHAT to do, WHERE to do it, WHAT to copy from
+- Verification checklist
+- Common mistakes
+
+### Focus: `walkthrough`
+**Produces:** `.docs/wiki/subsystems/[name]/walkthroughs/[flow-name].md`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/walkthrough.xml`
+**Requires:** `subsystem` parameter, source files involved in the flow
+**Optional:** emphasis-frameworks (list of frameworks requiring deep explanation), framework research context (provided by orchestrator)
+**Analysis:**
+- Read ALL source files involved in the flow — every class, every method
+- If framework research context is provided (from orchestrator), use it for accurate info boxes and official doc links
+- Trace execution order from entry point to exit point
+- For EACH step: extract the actual code snippet (focused on what the step explains)
+- Identify framework concepts that need info box explanations
+**Emphasis frameworks (when specified by orchestrator):**
+- EVERY step where the flow touches an emphasis framework MUST have a framework info box
+- ALL code that interacts with emphasis frameworks is shown and explained in full
+- Framework Concepts Reference table is MANDATORY
+- Info box links must point to real official doc URLs (from orchestrator's research)
+- The orchestrator researches frameworks (WebSearch/context7/provided docs) and passes results — you do NOT need to search
+**Writing rules (override standard density for walkthroughs):**
+- Show ACTUAL code from the codebase at every step — never pseudocode
+- Code snippets must be FOCUSED: show only lines relevant to the step, use `// ...` for omitted sections
+- Explain ONLY what's non-obvious after each snippet — if the code says `price > 0`, don't narrate it
+- Framework info boxes: blockquote with `> **[Framework]: [Concept]**` header, explain once at first appearance, link to official docs
+- Minimum 300 lines. Complex flows (3+ frameworks, 10+ classes): 500-1000 lines
+- Length comes from code snippets and completeness, not from prose
+
+### Focus: `decision`
+**Produces:** `.docs/wiki/subsystems/[name]/decisions/ADR-NNN-[slug].md`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/decizions.xml`
+**Requires:** `subsystem` parameter, decision context
+**Analysis:**
+- Context (what prompted the decision)
+- Decision (what was chosen)
+- Alternatives considered (why rejected)
+- Consequences (pros and cons)
+- Under 30 lines. ADRs are immutable once accepted.
+
 ### Focus: `coding-standards`
 **Produces:** `.docs/wiki/system-wide/coding-standards.md`
-**Template:** `~/.claude/agile-context-engineering/templates/wiki/coding-standards.xml`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/coding-standards.xml`
 **Analysis:**
 - Detect language(s) and paradigm(s) (OOP, FP, systems)
 - Read linter/formatter configs for enforced rules
@@ -191,7 +288,7 @@ When spawned, you receive a **focus** parameter that determines which documents
 
 ### Focus: `testing-framework`
 **Produces:** `.docs/wiki/system-wide/testing-framework.md`
-**Template:** `~/.claude/agile-context-engineering/templates/wiki/testing-framework.xml`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/testing-framework.xml`
 **Analysis:**
 - Identify test runner and assertion library from config/deps
 - Read 3-5 existing test files for structure and patterns
@@ -201,7 +298,7 @@ When spawned, you receive a **focus** parameter that determines which documents
 
 ### Focus: `tech-debt`
 **Produces:** `.docs/wiki/system-wide/tech-debt.md`
-**Template:** `~/.claude/agile-context-engineering/templates/wiki/tech-debt.xml`
+**Template:** `${CLAUDE_SKILL_DIR}/templates/tech-debt.xml`
 **Analysis:**
 - Grep for TODO, FIXME, HACK, XXX comments
 - Identify deprecated dependencies
@@ -231,6 +328,16 @@ Every template defines explicit update triggers and non-triggers. Respect them.
 
 **Subsystem Structure** — update on: new top-level directory in subsystem, directory renamed/moved/removed, new entry point, naming convention change. NOT on: new files in existing directories, new features following existing structure.
 
+**Systems** — update on: new component, behavior, entry point, integration point, state management change. NOT on: bug fixes, internal refactoring within existing components.
+
+**Patterns** — update on: new implementation added, pattern structure changed, new gotcha discovered. NOT on: new feature following existing pattern without changing it.
+
+**Guides** — update on: new step required, step order changed, reference implementation changed. NOT on: new feature following the existing recipe.
+
+**Walkthroughs** — update on: new step in the flow, step removed, step logic changed significantly, framework APIs changed, code snippets no longer match codebase. NOT on: bug fixes that don't change flow structure, internal refactoring within a single step.
+
+**Decisions** — NEVER edit accepted ADRs. Create a new one that supersedes.
+
 **Coding Standards** — update on: new language/paradigm, new framework, recurring mistake discovered, rule proven too strict/loose. NOT on: new features, bug fixes, dependency updates.
 
 **Testing Framework** — update on: test runner changed, mocking approach changed, new test type introduced, coverage requirements changed. NOT on: new test files following existing patterns.
@@ -258,7 +365,13 @@ Before returning, verify:
 - [ ] Tables have consistent column counts
 - [ ] No duplicate information across documents
 - [ ] "Where to add new code" paths match actual directory structure
-- [ ] Document is under target length (system-wide: 100-250 lines, subsystem: 80-200 lines)
+- [ ] Target lengths respected:
+  - system-wide docs: 100-250 lines
+  - subsystem structure/architecture: 80-200 lines
+  - systems, patterns, cross-cutting, guides: 50-200 lines
+  - walkthroughs: 300-1000 lines (code snippets drive the length)
+  - decisions: under 30 lines
+- [ ] Walkthroughs: every code snippet is from an actual file (verified by reading it), focused on the step's explanation, uses `// ...` for omitted sections
 
 </quality-bar>
 
@@ -321,7 +434,7 @@ Ready for orchestrator.
 
 **Don't invent patterns.** If you see something in 1 file, it's not a convention. Verify across multiple files before documenting it as a pattern.
 
-**Don't include entire file contents.** Reference with `file:Symbol`. Inline only contracts (interfaces, types, configs) that agents need to implement against.
+**Don't include entire file contents.** Reference with `file:Symbol`. Inline only contracts (interfaces, types, configs) that agents need to implement against. Exception: walkthroughs show focused code snippets.
 
 **Don't write aspirational docs.** Document what IS, not what SHOULD BE. If there's tech debt, note it in tech-debt.md. Don't let it contaminate the structure docs.
 
@@ -331,4 +444,6 @@ Ready for orchestrator.
 
 **Don't repeat template guidelines in output.** The templates have guidelines for YOU the generator. The output documents should contain DATA, not instructions about how to fill them.
 
+**Don't write thin walkthroughs.** If a walkthrough is under 200 lines, you're not showing enough code or explaining enough concepts. Read more source files. Add more steps. Show more code.
+
 </anti-patterns>