ace-docs 0.31.0

data/handbook/skills/as-docs-update-tools/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: as-docs-update-tools
+description: Update ace-* package documentation from implementation and tests
+# bundle: wfi://docs/update-tools
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-handbook:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - Edit
+  - MultiEdit
+  - Glob
+  - Grep
+  - LS
+  - TodoWrite
+argument-hint: [component]
+last_modified: 2026-01-10
+source: ace-docs
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+  providers: {}
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://docs/update-tools
+---
+
+Load and run `ace-bundle wfi://docs/update-tools` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/skills/as-docs-update-usage/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: as-docs-update-usage
+description: Update usage documentation based on feedback or requirements
+# bundle: wfi://docs/update-usage
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+argument-hint: [usage-file-path or feedback-description]
+last_modified: 2026-01-10
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://docs/update-usage
+
+---
+
+Load and run `ace-bundle wfi://docs/update-usage` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

data/handbook/templates/code-docs/javascript-jsdoc.template.md

@@ -0,0 +1,102 @@
+---
+doc-type: template
+title: JavaScript JSDoc Documentation Template
+purpose: Documentation for ace-docs/handbook/templates/code-docs/javascript-jsdoc.template.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# JavaScript JSDoc Documentation Template
+
+```javascript
+/**
+ * [Brief description of what this function/class does]
+ * 
+ * @description [Detailed description including purpose, behavior, and context.
+ * Explain what the function/class does, why it's useful, and how it fits
+ * into the larger system.]
+ *
+ * @param {Type} parameterName - [Description of parameter]
+ * @param {Type} anotherParam - [Description with constraints/validation]
+ * @param {Object} [options={}] - [Description of options object]
+ * @param {Type} [options.optionName=defaultValue] - [Description of option]
+ * @param {Type} [options.anotherOption] - [Description of another option]
+ * 
+ * @returns {Type|Promise<Type>} [Description of what is returned]
+ * 
+ * @throws {ErrorClass} [Description of when this error is thrown]
+ * @throws {AnotherError} [Description of another error condition]
+ * 
+ * @example
+ * // [Example title - basic usage]
+ * const result = functionName(param1, param2);
+ * 
+ * @example
+ * // [Example title - advanced usage]
+ * try {
+ *   const result = await functionName({
+ *     param: 'value',
+ *     options: { setting: true }
+ *   });
+ * } catch (error) {
+ *   console.error('Error:', error.message);
+ * }
+ * 
+ * @since [version when added]
+ * @deprecated [version when deprecated] Use [alternative] instead
+ */
+function functionName(parameterName, anotherParam, options = {}) {
+  // Implementation
+}
+```
+
+## JSDoc Tag Reference
+
+### Basic Tags
+
+- `@param {Type} name - description` - Parameter documentation
+- `@returns {Type} description` - Return value documentation  
+- `@throws {ErrorType} description` - Exception documentation
+- `@example` - Code examples
+- `@description` - Detailed description
+
+### Type Annotations
+
+- `{string}` - String type
+- `{number}` - Number type
+- `{boolean}` - Boolean type
+- `{Object}` - Object type
+- `{Array<Type>}` - Array of specific type
+- `{Type|null}` - Union types
+- `{Promise<Type>}` - Promise types
+
+### Optional Parameters
+
+- `{Type} [paramName]` - Optional parameter
+- `{Type} [paramName=defaultValue]` - Optional with default
+
+### Metadata Tags
+
+- `@since` - Version when added
+- `@deprecated` - Deprecation notice
+- `@author` - Author information
+- `@version` - Version information
+
+### Advanced Tags
+
+- `@namespace` - Namespace documentation
+- `@class` - Class documentation
+- `@module` - Module documentation
+- `@async` - Async function marker
+- `@static` - Static method marker
+
+## Documentation Guidelines
+
+1. **Use TypeScript-style type annotations**
+2. **Provide clear parameter descriptions**
+3. **Include realistic examples**
+4. **Document all possible exceptions**
+5. **Use @description for complex explanations**
+6. **Mark optional parameters clearly**
+7. **Include version information for new features**

data/handbook/templates/code-docs/ruby-yard.template.md

@@ -0,0 +1,85 @@
+---
+doc-type: template
+title: Ruby YARD Documentation Template
+purpose: Documentation for ace-docs/handbook/templates/code-docs/ruby-yard.template.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# Ruby YARD Documentation Template
+
+```ruby
+# [Brief description of what this method/class does]
+#
+# [Detailed description including purpose, behavior, and context.
+# Explain what the method/class does, why it's useful, and how it fits
+# into the larger system.]
+#
+# @example [Example title]
+#   [code example showing basic usage]
+#
+# @example [Another example title] 
+#   [code example showing advanced usage or error handling]
+#
+# @param [parameter_name] [Type] [Description of parameter]
+# @param [another_param] [Type] [Description with constraints/validation]
+# @param [options] [Hash] [Description of options hash]
+# @option options [Type] :option_name (default_value) [Description]
+# @option options [Type] :another_option [Description]
+#
+# @return [ReturnType] [Description of what is returned]
+#
+# @raise [ExceptionClass] [Description of when this exception is raised]
+# @raise [AnotherException] [Description of another exception condition]
+#
+# @note [Important note about usage, threading, performance, etc.]
+# @note [Another important note]
+#
+# @see [RelatedClass]
+# @see [RelatedMethod]
+# @see [URL to external documentation]
+#
+# @since [version when this was added]
+# @deprecated [version when deprecated] Use [alternative] instead
+#
+def method_name(parameter_name:, another_param:, **options)
+  # Implementation
+end
+```
+
+## YARD Tag Reference
+
+### Basic Tags
+
+- `@param` - Parameter documentation
+- `@return` - Return value documentation  
+- `@raise` - Exception documentation
+- `@example` - Code examples
+- `@note` - Important notes
+- `@see` - Cross-references
+
+### Metadata Tags
+
+- `@since` - Version when added
+- `@deprecated` - Deprecation notice
+- `@author` - Author information
+- `@version` - Version information
+
+### Advanced Tags
+
+- `@option` - Hash option documentation
+- `@overload` - Method overloads
+- `@yield` - Block documentation
+- `@yieldparam` - Block parameter documentation
+- `@yieldreturn` - Block return documentation
+
+## Documentation Guidelines
+
+1. **Start with a brief one-line summary**
+2. **Follow with detailed description if needed**
+3. **Provide realistic examples**
+4. **Document all parameters and return values**
+5. **Include exception conditions**
+6. **Add notes for important behavior**
+7. **Use cross-references for related code**

data/handbook/templates/project-docs/README.template.md

@@ -0,0 +1,73 @@
+---
+doc-type: template
+title: Package README
+purpose: Selling-page README template for ACE packages
+ace-docs:
+  last-updated: 2026-03-23
+  last-checked: 2026-03-23
+---
+
+<div align="center">
+  <h1> ACE - {package-title} </h1>
+
+  {one-sentence tagline}
+
+  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <br><br>
+
+  <a href="https://rubygems.org/gems/{package-name}"><img alt="Gem Version" src="https://img.shields.io/gem/v/{package-name}.svg" /></a>
+  <a href="https://www.ruby-lang.org"><img alt="Ruby" src="https://img.shields.io/badge/Ruby-3.2+-CC342D?logo=ruby" /></a>
+  <a href="https://opensource.org/licenses/MIT"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg" /></a>
+</div>
+
+> Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.
+
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md)
+
+
+<!-- Nav row: pipe-separated links above the demo. Always use "Handbook - Skills, Agents, Templates"
+     as the expanded label so readers know what the handbook contains.
+     Place above the demo so readers find docs before scrolling. -->
+
+![demo](docs/demo/{package-name}-getting-started.gif)
+
+<!-- Keep {package-title} as humanized package name, e.g. `ACE - Task` or `ACE - Test Runner E2E`. -->
+<!-- If this package has no docs/ directory, use only:
+Part of [ACE](https://github.com/cs3b/ace)
+and do not add documentation links in the footer. -->
+
+<!-- Include GIF for CLI tools. Omit for support libraries and integrations. -->
+
+<!-- Intro paragraph: 2-4 sentences that describe the problem space and what the package
+     does about it. Do NOT list subcommands or features here — Use Cases covers those.
+     Weave the value proposition naturally instead of splitting into Problem/Solution.
+     IMPORTANT: Read the implementation code before describing features - do not write from plan notes. -->
+
+## How It Works
+
+<!-- Mermaid diagram OR 3-step numbered list.
+     Show the mental model, not the implementation.
+     Optional - include only when the mental model isn't obvious from Use Cases.
+
+     Example Mermaid (add as a fenced mermaid code block):
+       graph LR
+         A[Input] then B[Process] then C[Output]
+     Replace "then" with the Mermaid arrow syntax. -->
+
+## Use Cases
+
+<!-- Each entry: **bold title** - description paragraph.
+     Inline references:
+       - Skills: always use `/as-` prefix (e.g., `/as-task-draft`)
+       - CLI commands: link to usage docs (e.g., [`ace-task create`](docs/usage.md#ace-task-create-title))
+       - Ecosystem packages: link to sibling directories inline (e.g., [ace-overseer](../ace-overseer))
+     Write 3-6 use cases. Each should show a real workflow, not just name a feature.
+
+     Example:
+       **Draft and structure work** - create a task, split it into subtasks, add new subtasks as work
+       reveals scope. Use `/as-task-draft` to draft from an earlier captured [idea](../ace-idea) or
+       short note, or [`ace-task create`](docs/usage.md#ace-task-create-title) from the CLI. -->
+
+---
+
+[Getting Started](docs/getting-started.md) | [Usage Guide](docs/usage.md) | [Handbook - Skills, Agents, Templates](docs/handbook.md) | Part of [ACE](https://github.com/cs3b/ace)

data/handbook/templates/project-docs/architecture.template.md

@@ -0,0 +1,300 @@
+---
+doc-type: template
+title: "[Project Name] - Architecture"
+purpose: Documentation for ace-docs/handbook/templates/project-docs/architecture.template.md
+ace-docs:
+  last-updated: 2026-01-08
+  last-checked: 2026-03-21
+---
+
+# [Project Name] - Architecture
+
+## Overview
+
+<!-- High-level description of the system architecture -->
+
+This document outlines the architectural design and technical implementation details for [Project Name]. It serves as a guide for developers and AI agents working on the project.
+
+## Technology Stack
+
+<!-- List the primary technologies, frameworks, and tools -->
+
+### Core Technologies
+
+- **Primary Language**: [e.g., JavaScript, Python, Rust, Ruby]
+- **Runtime/Framework**: [e.g., Node.js, Django, Rails, Actix]
+- **Database**: [e.g., PostgreSQL, MySQL, MongoDB, SQLite]
+- **Package Manager**: [e.g., npm, pip, cargo, bundler]
+
+### Development Tools
+
+- **Build System**: [e.g., Webpack, Vite, Cargo, Make]
+- **Testing Framework**: [e.g., Jest, PyTest, RSpec, Criterion]
+- **Linting/Formatting**: [e.g., ESLint/Prettier, Black, RuboCop, rustfmt]
+- **Type System**: [e.g., TypeScript, mypy, Sorbet, native]
+
+### Infrastructure & Deployment
+
+- **Containerization**: [e.g., Docker, Podman]
+- **Cloud Platform**: [e.g., AWS, GCP, Azure, Heroku]
+- **CI/CD**: [e.g., GitHub Actions, GitLab CI, Jenkins]
+- **Monitoring**: [e.g., Sentry, DataDog, Prometheus]
+
+## System Architecture
+
+### High-Level Components
+
+<!-- Describe the main components and their relationships -->
+
+```
+[Component Diagram - describe or link to actual diagram]
+
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Frontend/UI   │◄──►│   Backend/API   │◄──►│    Database     │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+                              │
+                              ▼
+                       ┌─────────────────┐
+                       │ External APIs/  │
+                       │    Services     │
+                       └─────────────────┘
+```
+
+### Component Descriptions
+
+#### [Component 1 - e.g., Frontend]
+
+- **Purpose**: [What this component does]
+- **Technology**: [Specific tech stack]
+- **Key Responsibilities**:
+  - Responsibility 1
+  - Responsibility 2
+- **Interfaces**: [How it communicates with other components]
+
+#### [Component 2 - e.g., Backend API]
+
+- **Purpose**: [What this component does]
+- **Technology**: [Specific tech stack]
+- **Key Responsibilities**:
+  - Responsibility 1
+  - Responsibility 2
+- **Interfaces**: [How it communicates with other components]
+
+#### [Component 3 - e.g., Database]
+
+- **Purpose**: [What this component does]
+- **Technology**: [Specific tech stack]
+- **Schema**: [Brief description or link to schema docs]
+
+## Data Flow
+
+### Request Processing Flow
+
+<!-- Describe how data flows through the system -->
+
+1. **Input**: [How requests/data enters the system]
+2. **Processing**: [How data is processed]
+3. **Storage**: [How data is persisted]
+4. **Output**: [How results are returned]
+
+### Data Models
+
+<!-- Key data structures and relationships -->
+
+#### Core Entities
+
+- **[Entity 1]**: [Description and key attributes]
+- **[Entity 2]**: [Description and key attributes]
+- **[Entity 3]**: [Description and key attributes]
+
+## Command-line Tools (bin/)
+
+The `bin/` directory provides convenient wrappers for project automation and development tasks.
+
+### Development Scripts
+
+- **bin/run** — Start the development server or main application
+- **bin/build** — Build the project for production deployment
+- **# Run project-specific test command** — Run the complete test suite
+- **# Run project-specific lint command** — Run code quality checks and linting
+
+### Project Management Scripts
+
+- **task-manager next** — Find the next actionable task in the current release
+- **task-manager recent** — Summarize recently updated or completed tasks
+- **git-commit** — Commit changes across the project and submodules
+- **git-log** — Show recent git commits across all repositories
+
+### Utility Scripts
+
+- **task-manager recentee** — Display the project directory structure
+- **release-manager current** — Get current release path and version information
+
+<!-- Add project-specific scripts -->
+
+### Custom Scripts
+
+- **bin/[custom-script]** — [Description of what this script does]
+
+## File Organization
+
+### Source Code Structure
+
+```
+src/
+├── [main-module]/          # Core application logic
+├── [feature-module]/       # Feature-specific code
+├── utils/                  # Shared utilities
+├── config/                 # Configuration management
+├── types/                  # Type definitions (if applicable)
+└── [other-modules]/        # Additional modules
+```
+
+### Configuration Files
+
+- **[config-file]**: [Purpose and key settings]
+- **[env-file]**: [Environment-specific configurations]
+- **[build-config]**: [Build and deployment settings]
+
+## Development Patterns
+
+### Code Organization Principles
+
+<!-- Describe key patterns and conventions -->
+
+- **[Pattern 1]**: [Description and usage]
+- **[Pattern 2]**: [Description and usage]
+- **[Pattern 3]**: [Description and usage]
+
+### Error Handling
+
+<!-- How errors are handled throughout the system -->
+
+- **Error Types**: [Different categories of errors]
+- **Error Propagation**: [How errors flow through the system]
+- **Logging Strategy**: [How errors are logged and monitored]
+
+## Security Considerations
+
+### Authentication & Authorization
+
+<!-- Security measures implemented -->
+
+- **Authentication Method**: [How users are authenticated]
+- **Authorization Model**: [How permissions are managed]
+- **Session Management**: [How sessions are handled]
+
+### Data Protection
+
+- **Encryption**: [What data is encrypted and how]
+- **Input Validation**: [How inputs are validated]
+- **Security Headers**: [Security headers implemented]
+
+## Performance Considerations
+
+### Optimization Strategies
+
+<!-- Performance optimization approaches -->
+
+- **Caching**: [Caching strategies used]
+- **Database Optimization**: [Query optimization, indexing]
+- **Asset Optimization**: [How static assets are optimized]
+
+### Monitoring & Metrics
+
+- **Key Metrics**: [Important performance indicators]
+- **Alerting**: [When and how alerts are triggered]
+- **Profiling**: [Tools and strategies for performance profiling]
+
+## Deployment Architecture
+
+### Environment Strategy
+
+<!-- Different deployment environments -->
+
+- **Development**: [Local development setup]
+- **Staging**: [Staging environment configuration]
+- **Production**: [Production environment details]
+
+### Deployment Process
+
+1. **Build**: [How the application is built]
+2. **Test**: [Testing in deployment pipeline]
+3. **Deploy**: [Deployment steps and strategies]
+4. **Monitor**: [Post-deployment monitoring]
+
+## Extension Points
+
+### Adding New Features
+
+<!-- How to extend the system -->
+
+- **[Extension Point 1]**: [How to add functionality here]
+- **[Extension Point 2]**: [How to add functionality here]
+
+### Plugin Architecture
+
+<!-- If applicable, describe plugin/module system -->
+
+- **Plugin Interface**: [How plugins integrate]
+- **Plugin Discovery**: [How plugins are found and loaded]
+
+## Dependencies
+
+### Runtime Dependencies
+
+<!-- Key libraries and their purposes -->
+
+- **[Library 1]** (v[version]): [Purpose and why it was chosen]
+- **[Library 2]** (v[version]): [Purpose and why it was chosen]
+
+### Development Dependencies
+
+- **[Dev Tool 1]**: [Purpose in development workflow]
+- **[Dev Tool 2]**: [Purpose in development workflow]
+
+## Decision Records
+
+### Significant Architectural Decisions
+
+<!-- Link to or summarize key architectural decisions -->
+
+- **[Decision 1]**: [Brief summary and rationale]
+- **[Decision 2]**: [Brief summary and rationale]
+
+For detailed decision records, see [docs/decisions/](docs/decisions/).
+
+## Troubleshooting
+
+### Common Issues
+
+<!-- Common problems and their solutions -->
+
+**Issue**: [Problem description]
+
+- **Symptoms**: [How to identify this issue]
+- **Solution**: [How to resolve it]
+
+**Issue**: [Problem description]
+
+- **Symptoms**: [How to identify this issue]
+- **Solution**: [How to resolve it]
+
+## Future Considerations
+
+### Planned Improvements
+
+<!-- Architectural improvements planned for future releases -->
+
+- **[Improvement 1]**: [Description and timeline]
+- **[Improvement 2]**: [Description and timeline]
+
+### Scalability Roadmap
+
+- **Short-term**: [Immediate scalability plans]
+- **Medium-term**: [6-12 month scalability goals]
+- **Long-term**: [Future architectural evolution]
+
+---
+
+*This architecture document should be updated when significant changes are made to the system design or technology stack.*