ace-docs 0.31.0

data/handbook/guides/documents-embedding.g.md

@@ -0,0 +1,276 @@
+---
+doc-type: guide
+title: Documents Embedding Standards and Principles
+purpose: Documentation for ace-docs/handbook/guides/documents-embedding.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Documents Embedding Standards and Principles
+
+This guide establishes standards for embedding documents (templates and guides) within workflow instruction files using XML-based `<documents>` containers, ensuring consistency and enabling automated synchronization across the development handbook system.
+
+## Goal
+
+Define clear principles and standards for:
+
+- How to properly embed documents using universal `<documents>` XML format
+- Document organization and placement within workflow files
+- Maintaining document consistency across workflow instructions
+- Enabling automated document synchronization through structured XML
+- Supporting both templates and guides in a unified format
+
+## Core Principles
+
+1. **Universal Container Format**: Use `<documents>` container with `<template>` and `<guide>` tags for all document embedding
+2. **Separation of Concerns**: Document content should be separated from workflow logic using XML structure
+3. **Structured Metadata**: All document references should use XML attributes for path information
+4. **XML Format Only**: Use XML sections for all document embedding (no markdown escaping)
+5. **Automated Synchronization**: XML document format enables easy parsing and automated updates
+
+## Universal Document Embedding Format
+
+### XML-Based Document Container (Current Standard)
+
+Use the universal `<documents>` container for clean, parseable document inclusion:
+
+```xml
+<documents>
+    <template path="{source-template-path}">
+    <!-- Template content goes here -->
+    </template>
+    
+    <guide path="{source-guide-path}">
+    <!-- Guide content goes here -->
+    </guide>
+    
+    <template path="{another-template-path}">
+    <!-- Another template content -->
+    </template>
+</documents>
+```
+
+**Components:**
+
+- `<documents>`: Universal container for all embedded documents
+- `<template path="...">`: Embedded template content from templates (use `tmpl://` protocol)
+- `<guide path="...">`: Embedded guide content from guides (use `guide://` protocol)
+- `path`: Source document file path (supports variables like `{current-release-path}`)
+
+**Examples:**
+
+```xml
+<documents>
+    <template path="tmpl://task-management/task-draft">
+---
+id: v.X.Y.Z+task.N
+status: pending
+priority: medium
+---
+
+# Task Title
+Task description and requirements.
+    </template>
+    
+    <guide path="guide://version-control-system">
+# Version Control System Guide
+
+This guide covers Git workflow standards...
+    </guide>
+    
+    <template path="tmpl://project-docs/adr">
+# ADR-NNN: Decision Title
+
+## Status
+Proposed
+
+## Context
+Context description.
+    </template>
+</documents>
+```
+
+## Code Block Escaping Standards
+
+### XML Document Embedding: For Templates and Guides
+
+Use XML `<documents>` sections for all embedded document content (NO escaping needed):
+
+```xml
+<documents>
+    <template path="tmpl://category/example">
+<!-- Template content here -->
+    </template>
+    
+    <guide path="guide://example">
+<!-- Guide content here -->
+    </guide>
+</documents>
+```
+
+### Three-Tick Escaping (```): For All Code Examples
+
+Use standard three-tick escaping for:
+
+- Command examples
+- Code snippets  
+- Configuration examples
+- Any code that is NOT a template/guide or markdown demonstration
+
+```markdown
+## Example Commands
+
+```bash
+git status
+git add .
+git commit -m "feat: add new feature"
+```
+
+## Configuration Example  
+
+```yaml
+version: 1.0
+settings:
+  debug: false
+```
+
+```
+
+### Four-Tick Escaping (````): Not for Documents
+
+Four-tick escaping is reserved for markdown-within-markdown demonstrations (see [Markdown Definition Guide](guide://markdown-definition)). 
+
+**Important**: Do NOT use four-tick escaping for templates or guides - use XML format instead.
+
+## Document Organization Structure
+
+### Embedded Documents Section
+
+All embedded documents must be placed at the end of workflow documents using XML format:
+
+```xml
+<documents>
+    <template path="{source-template-path}">
+<!-- Template content here -->
+    </template>
+    
+    <guide path="{source-guide-path}">
+<!-- Guide content here -->
+    </guide>
+    
+    <!-- additional documents -->
+    <template path="{another-template-path}">
+<!-- Another template content -->
+    </template>
+</documents>
+```
+
+### Benefits of Universal XML Format
+
+- **Clear Structure**: Documents are explicitly contained and separated
+- **Machine Parseable**: Easy to extract documents programmatically
+- **Metadata Rich**: Path information is structured as attributes
+- **Multiple Documents**: Simple to include multiple templates and guides in one section
+- **Variable Support**: Path attributes can use variables like `{current-release-path}`
+- **Type Safety**: Clear distinction between templates and guides
+- **Unified Format**: Single container format for all document types
+
+## Document Path Conventions
+
+### Templates
+
+Templates should be organized in logical directories in the handbook templates directory:
+
+- `project-docs/` - Core project documentation templates
+- `release-tasks/` - Task templates for releases
+- `release-management/` - Release planning and tracking templates
+- `code-docs/` - API and code documentation templates
+- `user-docs/` - User-facing documentation templates
+- `workflow-components/` - Reusable workflow step templates
+
+### Guides
+
+Guides should be organized in the handbook guides directory:
+
+- Root level: Core development guides (`.g.md` extension)
+- `.meta/` subdirectory: Meta-documentation and framework guides
+- Specialized subdirectories for domain-specific guides
+
+## Content Guidelines
+
+### Template Content Standards
+
+- Always include YAML frontmatter for metadata
+- Use clear placeholder syntax (e.g., `{variable-name}`)
+- Provide comprehensive documentation comments
+- Follow consistent formatting and structure
+- Include validation criteria where applicable
+
+### Guide Content Standards
+
+- Use clear, actionable headings
+- Provide concrete examples and code snippets
+- Include troubleshooting sections where relevant
+- Cross-reference related guides and templates
+- Maintain consistent tone and structure
+
+## Synchronization Integration
+
+The universal `<documents>` format integrates with the automated synchronization system:
+
+- **Tool**: `handbook sync-templates`
+- **Parsing**: XML structure enables reliable content extraction
+- **Updates**: Automated synchronization between source files and embedded content
+- **Validation**: Path verification and content consistency checks
+- **Maintenance**: Automated detection of missing or outdated documents
+
+## Migration from Legacy Formats
+
+### From Individual Template Containers
+
+```xml
+<!-- Old format -->
+<templates>
+    <template path="...">...</template>
+</templates>
+
+<!-- New universal format -->
+<documents>
+    <template path="...">...</template>
+</documents>
+```
+
+### From Mixed Formats
+
+Consolidate all document types into single `<documents>` containers:
+
+```xml
+<documents>
+    <template path="tmpl://task">
+    <!-- Template content -->
+    </template>
+    
+    <guide path="guide://workflow-guide">
+    <!-- Guide content -->
+    </guide>
+</documents>
+```
+
+## Best Practices
+
+1. **Single Container**: Use one `<documents>` container per workflow file
+2. **Logical Grouping**: Group related templates and guides together
+3. **Path Accuracy**: Ensure all path attributes are correct and up-to-date
+4. **Content Freshness**: Regularly synchronize embedded content with source files
+5. **Documentation**: Document the purpose and usage of embedded documents
+6. **Validation**: Test embedded content in actual workflow contexts
+7. **Consistency**: Follow established naming and organization conventions
+
+## Related Documentation
+
+- [Documents Embedded Sync Guide](./documents-embedded-sync.g.md) - Tool usage and operations
+- [Markdown Definition Guide](guide://markdown-definition) - Markdown standards
+- [Workflow Instructions Organization](guide://workflow-instructions-organization) - Workflow structure
+
+This universal documents embedding format provides a consistent, maintainable approach to including both templates and guides within workflow instructions while enabling automated synchronization and content management.

data/handbook/guides/markdown-style.g.md

@@ -0,0 +1,290 @@
+---
+doc-type: guide
+title: Markdown Style Guide
+purpose: Documentation for ace-docs/handbook/guides/markdown-style.g.md
+ace-docs:
+  last-updated: 2026-02-23
+  last-checked: 2026-03-21
+---
+
+# Markdown Style Guide
+
+This guide defines typography and formatting conventions for technical markdown documents. These standards optimize readability in monospace environments - terminals, code editors, and documentation tools.
+
+## Goal
+
+Establish consistent markdown styling that:
+- Reads well in monospace fonts and terminal displays
+- Supports both human and AI-agent consumption
+- Creates visual hierarchy without relying on rich rendering
+- Maintains clarity when viewed as plain text
+
+## Core Principles
+
+1. **Terminal-First**: Style choices should work in monospace environments
+2. **Plain-Text Friendly**: Documents should be readable without rendering
+3. **Visual Anchors**: Use emojis sparingly as scannable landmarks
+4. **Vertical Rhythm**: Align related elements for visual coherence
+
+## Typography Standards
+
+### Em-Dashes: Use Spaced Hyphens
+
+Em-dashes (`—`) render inconsistently across fonts and terminals. Use space-hyphen-space instead.
+
+**Avoid:**
+```
+The toolkit—designed for AI agents—supports multiple workflows.
+```
+
+**Prefer:**
+```
+The toolkit - designed for AI agents - supports multiple workflows.
+```
+
+This ensures consistent width and readability in monospace displays.
+
+### Quotation Marks
+
+Use straight quotes (`"`, `'`) rather than curly/smart quotes (`"`, `"`, `'`, `'`).
+
+**Avoid:**
+```
+"Smart quotes" cause encoding issues.
+```
+
+**Prefer:**
+```
+"Straight quotes" work everywhere.
+```
+
+### Bullet Characters
+
+Use standard ASCII hyphens (`-`) for unordered lists. Avoid fancy bullets or custom characters.
+
+```markdown
+- First item
+- Second item
+  - Nested item
+```
+
+## File Tree Formatting
+
+Use Unicode box-drawing characters in code blocks for file trees. This creates clear visual hierarchy.
+
+### Basic Structure
+
+```
+project/
+├── src/
+│   ├── components/
+│   │   ├── Button.tsx         # UI component
+│   │   └── Modal.tsx          # Dialog component
+│   └── utils/
+│       └── helpers.ts         # Utility functions
+├── docs/
+│   ├── architecture.md        # Technical design
+│   └── vision.md              # Project vision
+└── README.md                  # Entry point
+```
+
+### Box-Drawing Characters
+
+| Character | Name | Usage |
+|-----------|------|-------|
+| `├──` | Branch | Non-final sibling |
+| `└──` | End | Final sibling |
+| `│` | Pipe | Continuation |
+
+### Comment Alignment
+
+Align `#` comments vertically within each tree section for scannability.
+
+```
+ace-docs/
+├── lib/
+│   ├── cli.rb                 # Command-line entry
+│   ├── config.rb              # Configuration loader
+│   └── generator.rb           # Document generator
+└── handbook/
+    ├── guides/                # How-to documentation
+    ├── prompts/               # LLM system prompts
+    └── templates/             # Document templates
+```
+
+**Tip:** Use a text editor with column selection (block mode) to align comments efficiently.
+
+## Emoji Usage
+
+Emojis serve as **visual anchors** for scannability - not decoration.
+
+### When to Use Emojis
+
+- **Section headers** in lists or principles
+- **Status indicators** (completed, in-progress, blocked)
+- **Category markers** for quick visual grouping
+
+### Guidelines
+
+1. **One emoji per item** - avoid stacking multiple emojis
+2. **Consistent per category** - use the same emoji for the same concept
+3. **Meaningful placement** - at the start of headers, not inline
+4. **Skip when not scanning** - prose paragraphs rarely need emojis
+
+### Numbered Lists with Emojis
+
+For principles or key concepts, use numbered lists with leading emojis:
+
+```markdown
+1. 🖥️ **Terminal-First** - Optimize for monospace display
+2. 🔍 **Discoverable** - Easy to find and navigate
+3. 🤖 **Agent-Ready** - Structured for AI consumption
+4. ✨ **Minimal** - Only what's necessary
+```
+
+### Category Markers
+
+```markdown
+## Features
+
+- 📦 **Bundling** - Context aggregation
+- 🔍 **Search** - Code discovery
+- 📝 **Docs** - Documentation generation
+```
+
+## Headers and Sections
+
+### Link Preservation
+
+When a header's content moves to a code block, keep the link in the header:
+
+```markdown
+## [Project Structure](./docs/architecture.md)
+
+```
+project/
+├── src/
+└── docs/
+```
+```
+
+This maintains navigation while showing structured content.
+
+### Manifesto-Style Openers
+
+For vision documents, use blockquote openers to set tone:
+
+```markdown
+> **Clarity through constraint.** Build tools that make developers faster,
+> not tools that require learning curves.
+```
+
+## Code Block Conventions
+
+### Language Tags
+
+Always specify language for syntax highlighting:
+
+```markdown
+```ruby
+def example
+  # implementation
+end
+```
+```
+
+### Indentation in Examples
+
+Use 2-space indentation in code examples for compactness.
+
+### Shell Commands
+
+Use `bash` or `sh` for shell examples. Include `$` prompt only when showing interactive sessions:
+
+```bash
+ace-bundle project
+ace-test atoms
+```
+
+## Before/After Examples
+
+### Typography Transformation
+
+**Before (problematic):**
+```
+The toolkit—designed for AI agents—provides:
+• "Smart quotes" for text
+• Bullet using special character
+```
+
+**After (correct):**
+```
+The toolkit - designed for AI agents - provides:
+- "Straight quotes" for text
+- Bullet using hyphen
+```
+
+### File Tree Transformation
+
+**Before (plain text):**
+```
+docs/
+  guides/
+    style.md
+  templates/
+    vision.md
+```
+
+**After (structured):**
+```
+docs/
+├── guides/
+│   └── style.md               # Style guidance
+└── templates/
+    └── vision.md              # Vision template
+```
+
+### Principle List Transformation
+
+**Before (flat):**
+```
+Core Principles:
+- Terminal-First: Optimize for monospace display
+- Discoverable: Easy to find and navigate
+- Agent-Ready: Structured for AI consumption
+```
+
+**After (scannable):**
+```
+Core Principles:
+
+1. 🖥️ **Terminal-First** - Optimize for monospace display
+2. 🔍 **Discoverable** - Easy to find and navigate
+3. 🤖 **Agent-Ready** - Structured for AI consumption
+```
+
+## Validation
+
+### Manual Checks
+
+1. View document in terminal: `cat docs/example.md`
+2. Check for em-dash rendering: search for `—`
+3. Verify tree alignment in monospace font
+4. Ensure emoji display correctly in target environments
+
+### Automated Checks
+
+ace-lint can detect typography violations (planned feature):
+
+```bash
+ace-lint --check typography docs/
+```
+
+## Related Documentation
+
+- [Documentation Guide](guide://documentation) - Document structure and placement
+- [Vision Template](tmpl://project-docs/vision) - Styled vision document template
+
+---
+
+*These conventions prioritize universal readability over visual richness.*

data/handbook/prompts/ace-change-analyzer.system.md

@@ -0,0 +1,113 @@
+# ACE Dual Change Analyzer — System Prompt v3.0
+
+You are **ACE Dual Change Analyzer**, a specialized assistant that examines git diffs and produces two separate analyses:
+1. **Code Change Analysis**
+2. **Documentation / Configuration Change Analysis**
+
+Each analysis should be complete on its own, but code-related findings always take precedence.
+
+---
+
+## INPUT
+
+- A **git diff** (can include code, config, examples, docs)
+- Optional filters (paths, modules, time range)
+- Optional context files for architectural reference
+
+---
+
+## OUTPUT STRUCTURE
+
+Produce **two top-level sections** in your markdown report:
+
+## 🧩 1. Code Change Analysis
+Focus on code, logic, architecture, and test changes.
+- Summarize new features, API changes, refactors, tests, performance, or security updates.
+- Include CLI, Ruby, YAML, or configuration logic only if it affects runtime behavior.
+
+### Summary
+2–3 sentences on the scope and impact of code-level changes.
+
+### Changes Detected
+Group by **Priority** and optionally by **Type**:
+
+**HIGH Priority**
+- *File / Component:* `<path>`
+  *Type:* Feature / API / Security / Architecture / Performance / Breaking
+  *Change:* `<concise description>`
+  *Impact:* `<why this matters>`
+  *Evidence:* `<file::@@ hunk header or Lx–Ly>`
+
+**MEDIUM Priority**
+- *File / Component:* ...
+- ...
+
+**LOW Priority**
+- Minor improvements, internal refactoring, test updates.
+
+### Self-Check
+
+```yaml
+hunks_total: [N]
+hunks_mapped: [M]
+hunks_ambiguous: [K]
+coverage_ratio: [M/N]
+ambiguous_list:
+  - file::@@ -hunk — reason ambiguous
+```
+
+### Patterns / Trends
+- Architectural shifts, refactor patterns, or API standardization.
+- Mention broader ecosystem themes (LLM integration, testing unification, etc.)
+
+---
+
+## 📚 2. Documentation & Configuration Change Analysis
+Focus on examples, guides, config YAMLs, markdown docs, usage guides, workflow instructions.
+
+### Summary
+Explain the overall scope of doc/config updates and what they describe or enable.
+
+### Changes Detected
+Group by **Priority** (HIGH, MEDIUM, LOW) and **Category** (Docs / Config / Workflow / Example):
+
+- *File / Component:* `<path>`
+  *Category:* Docs / Config / Example
+  *Change:* `<summary>`
+  *Impact:* `<who benefits>`
+  *Evidence:* `<file::@@ hunk or Lx–Ly>`
+
+### Self-Check
+Same schema as above.
+
+### Additional Notes
+- Which documentation sections may need human validation.
+- Whether config changes affect developer onboarding or automation.
+
+---
+
+## ANALYSIS GUIDELINES
+
+**1. Classify files before analyzing**
+- Code files: `.rb`, `.js`, `.py`, `.go`, `.ts`, `.java`, etc.
+- Config files: `.yml`, `.yaml`, `.json`
+- Docs: `.md`, `.rst`, `.wf.md`, `.ag.md`
+- Tests: always part of the code analysis unless they're illustrative examples.
+
+**2. Prioritize impact**
+- HIGH → new APIs, breaking changes, major workflows.
+- MEDIUM → behavior or test logic changes, new flags, moderate refactors.
+- LOW → small enhancements, comments, doc clarity.
+
+**3. Detect patterns**
+Aggregate similar changes: multiple test helper additions → "test infra standardization."
+
+**4. Maintain completeness**
+Every diff hunk must be accounted for in one of the two analyses.
+
+**5. Be precise**
+No speculation. Only state what's clearly evidenced in the diff.
+
+---
+
+**Prompt version:** v3.0 — 2025-10-18