ace-handbook 0.19.0

data/handbook/guides/meta/guides-definition.g.md

@@ -0,0 +1,322 @@
+---
+doc-type: guide
+title: Writing Development Guides
+purpose: Documentation for ace-handbook/handbook/guides/meta/guides-definition.g.md
+ace-docs:
+  last-updated: 2026-02-22
+  last-checked: 2026-03-21
+---
+
+# Writing Development Guides
+
+This guide outlines best practices for creating and maintaining the development guides located within the handbook guides directory. These guides serve as the primary reference for project standards, processes, and technical approaches, intended for both human developers and AI agents collaborating on the project.
+
+## Goal of Guides
+
+The primary goal of these guides is to:
+- Document established standards, best practices, and workflows.
+- Ensure consistency across the project.
+- Provide clear, actionable instructions and explanations.
+- Serve as a reliable knowledge base for both human developers and AI agents.
+
+## Core Principles
+
+1.  **Conceptual Focus:** Guides explain the "Why" - principles, concepts, standards, and best practices. Workflows explain the "How" - step-by-step procedural instructions. Guides should focus on understanding and decision-making rather than execution.
+2.  **Clarity & Conciseness:** Write clearly and avoid ambiguity. Get straight to the point. Use simple language where possible.
+3.  **Accuracy & Up-to-Date:** Ensure information is correct and reflects the current project state and decisions. Update guides promptly when processes or standards change.
+4.  **Conceptual Actionability:** Provide practical advice, principles, and context that help readers understand what to do and why, while linking to self-contained workflows for specific execution steps.
+5.  **Structure & Scanability:** Use clear headings, subheadings, lists, and code blocks to organize information logically. Make it easy for readers (human or AI) to quickly find relevant sections.
+6.  **Consistency:** Use consistent terminology, formatting, and structure across all guides. Refer to terms defined in other guides or the main [Project Management Guide](guide://project-management).
+7.  **Examples:** Provide concrete examples (code snippets, file structures, command outputs) to illustrate concepts and principles, not step-by-step procedures.
+8.  **Target Audience:** Write for both human developers (potentially new to the project) and AI agents. This means being explicit, structured, and providing sufficient context.
+9.  **Language Modularity:** When a guide mixes language‑specific details with general advice, extract each language's specifics into a dedicated sub‑guide (e.g., `testing/ruby-rspec.md`, `security/rust.md`). Keep the parent guide language‑agnostic.
+
+## File Naming Convention
+
+All guide files must use the `.g.md` suffix to distinguish them from workflow instructions (which use `.wf.md`). This convention enables proper editor configuration and clear separation of content types.
+
+### Naming Pattern
+- **Format:** `<noun-phrase>.g.md`
+- **Style:** Use noun-based naming that describes what the guide covers, avoiding action verbs
+- **Examples:**
+  - `coding-standards.g.md` (not `write-coding-standards.g.md`)
+  - `testing-tdd-cycle.g.md` (not `implement-tdd-cycle.g.md`)
+  - `release-publish.g.md` (not `publish-release.g.md`)
+  - `debug-troubleshooting.g.md` (not `troubleshoot-issues.g.md`)
+
+### Contrast with Workflow Instructions
+Unlike workflow instructions (`.wf.md` files) which use verb-first naming to indicate actions:
+- **Guides** document standards and knowledge: `security.g.md`, `performance.g.md`
+- **Workflows** describe processes to execute: `commit.wf.md`, `fix-tests.wf.md`
+
+This naming distinction helps both humans and AI agents quickly identify whether a file provides reference information (guide) or executable instructions (workflow).
+
+## Content Guidelines: Guides vs Workflows
+
+Guides and workflows serve distinct purposes and should contain different types of content. Understanding this separation is essential for maintaining consistency across the handbook system.
+
+### What Belongs in Guides
+
+**Conceptual Content:**
+- Principles, philosophies, and best practices
+- Standards and coding conventions
+- Architecture patterns and design approaches
+- Explanation of why certain approaches are preferred
+- Context and rationale behind decisions
+- Deep-dive knowledge and understanding
+
+**Appropriate Guide Content Examples:**
+- "Test-driven development principles and benefits"
+- "Security considerations for input validation" 
+- "Code review standards and what to look for"
+- "Performance optimization strategies"
+- "Error handling patterns and when to use them"
+
+### What Does NOT Belong in Guides
+
+**Procedural Content:**
+- Step-by-step instructions for executing tasks
+- Command sequences and specific CLI operations
+- Implementation workflows and task execution
+- Interactive checklists meant to be completed
+- Detailed "how-to" procedures
+
+**Content That Should Be in Workflows Instead:**
+- "How to set up test environment" → Move to workflow
+- "Steps to perform security audit" → Move to workflow  
+- "Checklist for code review process" → Move to workflow
+- "Commands to deploy application" → Move to workflow
+
+### Linking Between Guides and Workflows
+
+**From Guides to Workflows:**
+- Guides should link to relevant workflows when discussing how principles are applied
+- Use clear language: "To implement these security principles, see [Security Audit Workflow](wfi://security-audit)"
+- Avoid embedding procedural steps directly in guides
+
+**From Workflows to Guides:**
+- Workflows can reference guides for context and rationale
+- Link to guides when explaining why certain steps are necessary
+- Use format: "For background on these testing principles, see [Testing Guide](guide://testing)"
+
+## Standard Guide Structure
+
+While the specific sections will vary based on the guide's topic, aim for a general structure like this:
+
+1.  **Title (`# Title`):** Clear and descriptive title.
+2.  **Introduction/Goal:** Briefly state the purpose of the guide and what the reader will learn or understand after reading it.
+3.  **Core Sections (Using `##` and `###`):** Break down the topic into logical sections with clear headings.
+    *   Explain key concepts, principles, and philosophies first.
+    *   Detail standards, conventions, or rules with rationale.
+    *   Provide context and background for decision-making.
+    *   Link to relevant workflows for implementation details.
+4.  **Examples:** Include well-formatted code blocks, file structure examples, or command outputs to illustrate concepts and patterns. Use realistic examples relevant to the toolkit's domain, focusing on demonstrating principles rather than step-by-step procedures.
+5.  **Best Practices/Tips:** Offer conceptual advice, highlight common pitfalls, and explain the reasoning behind recommendations.
+6.  **Related Documentation:** Link to other relevant guides, workflow instructions, or templates using paths relative to the project root (e.g., `[Project Management Guide](guide://project-management)`), **not** relative to the current file (e.g., `../project-management.g.md`). Always link to workflows when discussing implementation of the concepts covered.
+
+## Language‑Specific Sub‑Guides
+
+When splitting language‑dependent examples out of a general guide, follow these rules:
+
+1. **Directory & File Names**  
+   * Place sub‑guides in a directory that matches the parent guide’s slug.  
+   * Use lower‑case filenames that match the language, e.g. `ruby.md`, `rust.md`, `typescript.md`.  
+   * For testing, prefer more descriptive names such as `ruby-rspec.md` or `typescript-bun.md` when tool‑specific.
+
+3. **Cross‑Linking**  
+   * At the top of each sub‑guide add a short note:  
+     ```markdown
+     > This page is a language‑specific companion to [Testing Guide](guide://testing)
+     ```  
+   * Add reciprocal links from the parent guide to its sub‑guides.
+
+3. **Index Updates**  
+   * Whenever you add or delete a sub‑guide, update the guides README (or `index.md`) so the navigation tree stays accurate.
+
+4. **Example Tree**
+
+   ```
+   guides
+   ├── security.g.md
+   └── security
+       ├── ruby.md
+       ├── rust.md
+       └── typescript.md
+   ```
+
+## Writing for Humans and AI
+
+- **Structure is Key:** Use Markdown headings (`#`, `##`, `###`), lists (`*`, `-`, `1.`), and code blocks (```) consistently. AI agents parse structure effectively.
+- **Explicit Instructions:** Use action verbs and clearly define steps.
+- **Define Terminology:** If introducing a specific term, define it clearly or link to where it's defined (using root-relative paths).
+- **Contextual Links:** Link to related guides or specific sections where appropriate using root-relative paths to build a connected knowledge graph.
+- **Use Standard Markdown Links:** When linking to other guides, workflow instructions, or project documents, always use the standard Markdown link format with proper file extensions e.g.: `[Writing Guides Guide](./meta/writing-guides-guide.md)`, `[Commit Workflow](wfi://git/commit)`. Avoid using just the path in backticks unless discussing the path itself.
+- **Code Examples:** Use clear, minimal, and correct code examples. Specify the language in fenced code blocks (e.g., ```ruby).
+
+## Content Examples: Appropriate vs Inappropriate
+
+Understanding the distinction between conceptual guide content and procedural workflow content is crucial. Here are specific examples to illustrate what belongs in guides vs workflows.
+
+### ✅ Appropriate Guide Content
+
+**Conceptual Explanations:**
+```markdown
+## Test-Driven Development Philosophy
+
+TDD follows the Red-Green-Refactor cycle, which promotes:
+- **Design thinking**: Writing tests first forces you to think about API design
+- **Confidence**: Comprehensive tests provide safety for refactoring
+- **Documentation**: Tests serve as living documentation of expected behavior
+
+The key insight is that TDD is not just about testing - it's a design methodology that leads to better code architecture.
+```
+
+**Standards and Conventions:**
+```markdown
+## Code Review Standards
+
+When reviewing code, focus on these core areas:
+- **Clarity**: Is the code self-documenting and easy to understand?
+- **Security**: Are there potential vulnerabilities or data exposure risks?
+- **Performance**: Are there obvious inefficiencies or bottlenecks?
+- **Maintainability**: Will this code be easy to modify in the future?
+
+For the specific steps to conduct a code review, see [Code Review Workflow](wfi://code-review).
+```
+
+### ❌ Inappropriate Guide Content (Move to Workflows)
+
+**Step-by-Step Procedures:**
+```markdown
+❌ Don't put this in a guide:
+## How to Set Up Testing Environment
+
+1. Install Ruby 3.2+
+2. Run `bundle install`
+3. Copy `.env.example` to `.env`
+4. Run `bin/setup`
+5. Execute `bin/test` to verify setup
+
+✅ This belongs in a workflow file instead.
+```
+
+**Interactive Checklists:**
+```markdown
+❌ Don't put this in a guide:
+## Deployment Checklist
+- [ ] Run tests
+- [ ] Update version number  
+- [ ] Create git tag
+- [ ] Push to production
+
+✅ This belongs in a workflow file instead.
+```
+
+**Command Sequences:**
+```markdown
+❌ Don't put this in a guide:
+## Git Branch Management
+To create a feature branch:
+```bash
+git checkout main
+git pull origin main
+git checkout -b feature/new-feature
+```
+
+✅ This belongs in a workflow file instead.
+```
+
+### 🔄 Converting Procedural to Conceptual Content
+
+**Before (Procedural - belongs in workflow):**
+```markdown
+## Database Migration Process
+1. Create migration file: `rails generate migration AddColumn`
+2. Edit the migration to add your changes
+3. Run `rails db:migrate`
+4. Test the changes
+5. Commit the migration file
+```
+
+**After (Conceptual - appropriate for guide):**
+```markdown
+## Database Migration Principles
+
+Database migrations should be:
+- **Reversible**: Always include a `down` method or use reversible operations
+- **Atomic**: Each migration should represent a single, complete change
+- **Tested**: Verify migrations work in both directions before deployment
+- **Documented**: Include comments explaining complex migrations
+
+The key principle is that migrations are permanent historical records of database changes. They should never be modified once committed to a shared branch.
+
+For the specific steps to create and run migrations, see [Database Migration Workflow](wfi://database-migration).
+```
+
+This transformation maintains the valuable knowledge while removing the procedural steps that belong in self-contained workflows.
+
+## Checkbox Usage Guidelines
+
+Guides are **informational and reference documents**, not actionable tasks. Proper checkbox usage is critical to prevent AI agents from treating guides as interactive checklists.
+
+### ❌ Inappropriate Use (Don't Do This)
+
+**Interactive Checklists in Guides:**
+```markdown
+## Security Review Process
+- [ ] Check input validation
+- [ ] Verify authentication
+- [ ] Test authorization
+```
+
+This treats the guide as a task to be completed, which is incorrect.
+
+### ✅ Appropriate Use (Do This Instead)
+
+**Informational Bullet Points:**
+```markdown
+## Security Review Areas
+- **Input Validation**: Check all user inputs are sanitized
+- **Authentication**: Verify login mechanisms work correctly
+- **Authorization**: Test that permissions are properly enforced
+```
+
+### ✅ Legitimate Checkbox Uses in Guides
+
+**1. Template Examples:**
+When showing what a task or checklist should look like:
+
+```markdown
+## Example Task Format
+Here's how to structure implementation steps:
+
+- [ ] Step 1: Implement feature A
+- [ ] Step 2: Add tests for feature A
+- [ ] Step 3: Update documentation
+```
+
+**2. Reference Templates:**
+When providing copyable templates:
+
+```markdown
+## Pull Request Template
+Copy this template for your PRs:
+
+## Changes
+- Implemented new feature
+
+## Testing
+- [ ] Unit tests added
+- [ ] Integration tests updated
+```
+
+**Key Principle:** If the checkboxes are meant to be copied/used elsewhere or serve as examples, they're appropriate. If they suggest the guide itself should be "completed," they're inappropriate.
+
+## Maintaining Guides
+
+- **Review Regularly:** Periodically review guides for accuracy and relevance, especially when related processes change.
+- **Run a Directory Audit before Large Refactors:** Use `tree -L 2` on your guides directory (or similar) to list the current structure, paste the excerpt into your refactor ticket, and build an explicit file‑manifest from it.
+- **Update After Decisions:** If an ADR changes a standard or process, update the corresponding guide(s).
+- **Refactor When Needed:** Don't hesitate to restructure or rewrite sections for clarity as the project evolves.
+
+By adhering to these guidelines, we can build and maintain a high-quality set of development guides that effectively support the project's workflow and collaboration.

data/handbook/guides/meta/markdown-definition.g.md

@@ -0,0 +1,210 @@
+---
+doc-type: guide
+title: Markdown Usage Standards
+purpose: Documentation for ace-handbook/handbook/guides/meta/markdown-definition.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Markdown Usage Standards
+
+This guide establishes standards for markdown formatting within the development handbook system, focusing on proper code block escaping and markdown-within-markdown examples.
+
+## Goal
+
+Define clear principles for:
+- When to use three-tick vs four-tick code block escaping
+- How to properly demonstrate markdown syntax within documentation
+- Markdown formatting consistency across guides and workflows
+
+## Core Principles
+
+1. **Appropriate Escaping**: Use the right level of escaping for the content being demonstrated
+2. **Clarity**: Examples should clearly show the intended markdown syntax
+3. **Consistency**: Uniform application of escaping rules across all documentation
+4. **Readability**: Markdown demonstrations should be easy to follow and understand
+
+## Code Block Escaping Standards
+
+### Three-Tick Escaping (```): Standard Code Examples
+
+Use standard three-tick escaping for:
+- Command examples
+- Code snippets
+- Configuration examples
+- Any code that is NOT 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 (````): ONLY for Markdown-within-Markdown
+
+Reserve four-tick escaping **exclusively** for demonstrating markdown syntax within documentation:
+
+````markdown
+To show markdown examples in guides:
+
+````markdown
+# This is a markdown example
+Content here demonstrates markdown syntax.
+````
+````
+
+## Markdown Demonstration Examples
+
+### Showing Markdown Headers
+
+````markdown
+Use this format to demonstrate header syntax:
+
+````markdown
+# Main Title
+## Section Header
+### Subsection Header
+````
+````
+
+### Showing Markdown Lists
+
+````markdown
+Example of list formatting:
+
+````markdown
+- First item
+- Second item
+  - Nested item
+  - Another nested item
+
+1. Numbered list
+2. Second item
+   1. Nested numbered item
+````
+````
+
+### Showing Markdown Links and References
+
+````markdown
+Link examples:
+
+````markdown
+[Link Text](https://example.com)
+[Internal Link](path/to/file.md)
+[Reference Link][ref-id]
+
+[ref-id]: https://example.com "Reference title"
+````
+````
+
+### Showing Markdown Code Blocks
+
+````markdown
+Code block examples:
+
+````markdown
+Inline `code` formatting.
+
+```javascript
+function example() {
+    return "code block";
+}
+```
+````
+````
+
+## Common Validation Issues
+
+### ❌ Incorrect: Four-tick for regular code examples
+
+````markdown
+````bash
+git status  # This should use three ticks
+````
+````
+
+### ✅ Correct: Three-tick for regular code examples
+
+````markdown
+```bash
+git status  # Proper three-tick escaping
+```
+````
+
+### ❌ Incorrect: Three-tick for markdown demonstrations
+
+````markdown
+```markdown
+# This markdown example won't render properly
+```
+````
+
+### ✅ Correct: Four-tick for markdown demonstrations
+
+````markdown
+````markdown
+# This markdown example renders correctly
+````
+````
+
+## Validation Patterns
+
+### Find incorrect four-tick usage (should be three-tick for code examples)
+```regex
+^````(?!markdown).*$
+```
+This finds four-tick blocks that aren't for markdown-within-markdown demonstrations.
+
+### Find orphaned four-tick blocks (should only be for markdown demonstrations)
+```regex
+````(?!markdown)[\s\S]*?````
+```
+This finds four-tick blocks not used for markdown-within-markdown examples.
+
+### Find three-tick markdown blocks (should be four-tick)
+```regex
+^```markdown[\s\S]*?^```
+```
+This finds markdown demonstrations using three-tick escaping instead of four-tick.
+
+## Best Practices
+
+### Markdown Documentation
+- Use four-tick escaping when showing markdown syntax examples
+- Always specify the language for code blocks
+- Provide clear context for what the example demonstrates
+- Keep examples focused and relevant to the documentation purpose
+
+### Code Examples
+- Use three-tick escaping for all non-markdown code examples
+- Always specify the language (bash, yaml, json, etc.)
+- Keep examples concise and functional
+- Test command examples before including them
+
+### Consistency
+- Apply escaping rules uniformly across all documentation
+- Review examples to ensure they render as intended
+- Use validation patterns to catch incorrect escaping usage
+- Update examples when markdown standards change
+
+## Related Documentation
+
+- [Template Embedding Guide](./template-embedding.g.md) - For template-specific formatting
+- [Guides Definition](./guides-definition.g.md) - For guide writing standards
+- [Writing Development Guides](./writing-guides-guide.md) - For comprehensive guide creation
+
+This standardized approach ensures markdown consistency and proper rendering across the entire development handbook system.

data/handbook/guides/meta/tools-definition.g.md

@@ -0,0 +1,159 @@
+---
+doc-type: guide
+title: Development Tools Guide
+purpose: Documentation for ace-handbook/handbook/guides/meta/tools-definition.g.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Development Tools Guide
+
+This guide outlines best practices for creating, maintaining, and using development tools located within the tools directory. These tools are helper scripts and utilities designed to automate common tasks, enforce standards, and support the overall development workflow for both human developers and AI agents.
+
+## Goal of Tools
+
+The primary goal of development tools is to:
+- Automate repetitive or complex development tasks.
+- Ensure consistency in project operations (e.g., task management, documentation checks).
+- Provide support for workflows defined via `wfi://` protocol.
+- Enhance developer productivity and reduce manual error.
+- Be easily usable by both human developers and AI agents.
+
+## Core Principles for Tool Development
+
+1.  **Clarity & Simplicity:** Tools should have a clear purpose and be straightforward to use.
+2.  **Reliability:** Tools must be robust and produce consistent, predictable results.
+3.  **Well-Documented:** Each tool should have clear usage instructions, either as comments within the script or as part of this guide if complex. Simple tools often have a `print_usage` function or respond to `--help`.
+4.  **Idempotency (where applicable):** If a tool modifies state, it should ideally be idempotent, meaning running it multiple times has the same effect as running it once.
+5.  **Single Responsibility:** Each tool should focus on a single task or a small set of closely related tasks.
+6.  **Standard Naming Conventions:** Adhere to the naming conventions outlined below.
+7.  **Cross-Platform Compatibility (where feasible):** Strive to make tools runnable on common development operating systems (Linux, macOS). If a tool has specific OS dependencies (e.g., `tree` command), document them.
+8.  **Error Handling:** Tools should provide clear error messages and exit with non-zero status codes on failure.
+9.  **Minimal Dependencies:** Prefer tools written in standard scripting languages (e.g., Bash, Ruby, Python) that are commonly available or have minimal external dependencies. If dependencies are required, document them.
+10. **Project-Relative Paths**: Tools should assume they are run from the project root (an assumption typically ensured by `bin/` wrappers). Paths within tools (e.g., to access `dev-taskflow/` files) should be constructed relative to this root (e.g., `dev-taskflow/current/vX.Y.Z/tasks/001.md`) and not include the top-level project directory name.
+
+## Naming Conventions
+
+To ensure clarity and consistency, tools within the tools directory should follow these naming conventions:
+
+1.  **Verb-Prefix:** Tool names should start with a verb that describes their primary action.
+    *   Examples: `get-next-task`, `build-contextual-prompt`, `lint-md-links`, `show-directory-tree`.
+2.  **Lowercase & Hyphenated:** Use lowercase letters and separate words with hyphens.
+    *   Example: `fetch-github-pr-data` (not `fetchGithubPRData` or `fetch_github_pr_data`).
+3.  **Descriptive:** The name should clearly indicate the tool's purpose.
+4.  **File Extension (if applicable):** Include the appropriate file extension (e.g., `.rb` for Ruby scripts, `.sh` for shell scripts). For executable scripts without an extension, ensure the shebang line (e.g., `#!/usr/bin/env ruby`) is present.
+
+## Standard Tool Structure (Example for a script)
+
+```bash
+#!/usr/bin/env ruby
+# tool-name: Brief description of what the tool does.
+# (Additional comments about usage, dependencies, or important notes)
+
+# require 'optparse' # For command-line option parsing
+# require 'other_libs'
+
+# Default options or constants
+# DEFAULT_SETTING = "value"
+
+# Function to print usage instructions
+# def print_usage
+#   puts "Usage: tool-name [OPTIONS] [ARGUMENTS]"
+#   puts ""
+#   puts "Options:"
+#   puts "  -o, --option  Description of option"
+#   puts "  -h, --help    Display this help message"
+# end
+
+# Parse command-line arguments (using OptParse or similar)
+# options = {}
+# OptionParser.new do |opts|
+#   opts.banner = "Usage: tool-name [options] [arguments]"
+#   opts.on("-h", "--help", "Prints this help") do
+#     print_usage
+#     exit
+#   end
+#   # Define other options
+# end.parse!
+
+# Main logic of the tool
+# begin
+#   # ... tool implementation ...
+# rescue => e
+#   warn "Error: #{e.message}"
+#   exit 1
+# end
+
+# Exit with success
+# exit 0
+```
+
+## `bin/` Wrappers
+
+Simple, frequently used tools from the tools directory may have thin wrapper scripts in the project's root `bin/` directory for easier access from anywhere in the project.
+
+- **Naming:** Wrappers in `bin/` should typically be short, memorable, and reflect the tool's purpose (e.g., `bin/tn` for the get-next-task tool, `bin/gl` for the get-recent-git-log tool).
+- **Functionality:** These wrappers should primarily set up the correct execution path to the actual tool in the tools directory and pass along any arguments. These wrappers should be kept as minimal as possible. If no special environment setup or argument manipulation is needed beyond what the target script handles, a simple `exec` call (like the example below for Ruby scripts, or its shell script equivalent) is preferred.
+
+Example `bin/tn` wrapper:
+```ruby
+#!/usr/bin/env ruby
+# bin/tn: Thin wrapper for get-next-task utility
+exec(File.expand_path('../tools/get-next-task', __dir__), *ARGV)
+```
+
+## Adding a New Tool
+
+1.  **Define Purpose:** Clearly define what the tool will do and why it's needed.
+2.  **Choose Language:** Select an appropriate scripting language.
+3.  **Implement Logic:** Write the tool, adhering to the core principles and naming conventions.
+4.  **Add Usage Info:** Include a help option (`-h`, `--help`) or clear comments explaining how to use the tool.
+5.  **Test Thoroughly:** Ensure the tool works as expected in various scenarios, including edge cases and error conditions. Document example invocations or create test cases if the tool's logic is complex. Verify that the tool produces correct output and handles failures gracefully (e.g., proper exit codes, informative error messages).
+6.  **Place in the tools directory:** Add the new tool to the tools directory.
+7.  **(Optional) Create `bin/` Wrapper:** If the tool is frequently used, consider adding a wrapper in the root `bin/` directory.
+8.  **Update Documentation:**
+    *   If the tool is significant or complex, add a section to this guide describing it.
+    *   Update the guides README if necessary to reflect the new tool's availability, especially if it supports a key workflow.
+    *   Mention the tool in relevant workflow instructions or other guides if it automates a step.
+
+## Maintaining Tools
+
+- **Keep Them Updated:** As project structures or workflows evolve, update tools accordingly.
+- **Refactor for Clarity:** If a tool becomes too complex, consider refactoring it or splitting its functionality.
+- **Address Issues:** Fix bugs or issues reported in tools promptly.
+- **Version Control:** All tools must be version-controlled within the `docs-dev` repository.
+
+## Current Development Tools
+
+### Documentation Review Tools
+
+#### `generate-doc-review-prompt`
+**Purpose:** Creates comprehensive AI agent prompts for reviewing code diffs and updating related documentation.
+
+**Usage:**
+```bash
+# Basic usage - generate prompt from diff file
+generate-doc-review-prompt -d changes.diff
+
+# Specify custom output location
+generate-doc-review-prompt -d changes.diff -o review-prompt.md
+
+# Include full documentation content for detailed analysis
+generate-doc-review-prompt -d changes.diff --include-content
+```
+
+**Options:**
+- `-d, --diff FILE`: Path to the diff file (required)
+- `-o, --output FILE`: Output file for the prompt (optional, auto-generates if not specified)
+- `-r, --root DIR`: Project root directory (default: current directory)
+- `-c, --include-content`: Include full content of documentation files (default: just list files)
+- `-h, --help`: Show help message
+
+**Wrapper:** Available as `bin/cr-docs` for convenient access.
+
+**Dependencies:** Standard Ruby libraries only (optparse, pathname, fileutils).
+
+**Related Documentation:** See [Code Review: Diff-Based Documentation Updates](./code-review-diff-for-docs-update.g.md) for comprehensive workflow guidance.
+
+By following these guidelines, we can build a robust and useful set of development tools that enhance our workflow.