ace-task 0.31.0

data/exe/ace-task

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ace/task"
+require_relative "../lib/ace/task/cli"
+
+# No args → show help
+args = ARGV.empty? ? ["--help"] : ARGV
+
+# Handle SIGINT with exit code 130
+trap("INT") { exit 130 }
+
+# Start ace-support-cli with exception-based exit code handling (per ADR-023)
+begin
+  Ace::Task::TaskCLI.start(args)
+rescue Ace::Support::Cli::Error => e
+  warn e.message
+  exit(e.exit_code)
+rescue ArgumentError => e
+  warn "Error: #{e.message}"
+  exit(1)
+end

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

@@ -0,0 +1,156 @@
+---
+doc-type: guide
+purpose: Guide for writing clear, actionable task definitions in ace-task
+ace-docs:
+  last-updated: '2026-03-21'
+---
+
+<!-- markdownlint-disable -->
+# 📑 Writing Clear, Actionable Dev Tasks
+
+## A playbook for documentation‑oriented tickets, with a complete worked example
+
+## Introduction & Goal
+
+This guide provides a structured approach and template for writing effective development tasks, particularly those
+focused on documentation changes within this toolkit. Following these steps ensures tasks are clear, scoped correctly,
+actionable, and easily understood by both human developers and AI agents contributing to the project. The goal is to
+minimize ambiguity and streamline the process of defining and executing documentation work.
+
+---
+
+## 0. Directory Audit Step ✅
+
+**Always start by discovering what actually exists in the repo.**
+
+1. Run a tree or ls command (exclude `node_modules`, `vendor`, etc.).
+2. Copy the relevant excerpt into the ticket.
+3. From that listing, build the deliverable manifest.
+
+> **Tip:**
+> • If you don’t have repo access, create a tiny *pre‑ticket* titled “Generate Guide‑Audit Manifest”.
+> • Commit the tree output as a comment or markdown file, then reference it in the main ticket.
+
+Example audit snippet to embed:
+
+```bash
+tree -L 2 ace-handbook/handbook/guides | sed 's/^/    /'
+
+guides
+├── coding-standards.g.md
+├── error-handling.g.md
+├── performance.g.md
+└── ...
+```
+
+---
+
+## 1. Anatomy of a Great Task
+
+| Section | Purpose | Key Questions |
+|---------|---------|---------------|
+| **Front‑matter** | Helps tooling & humans filter | id (use `task-manager generate-id VERSION` to generate), status, priority, estimate, dependencies |
+| **Objective / Problem** | *Why* are we doing this? | What pain are we fixing? |
+| **Directory Audit (0)** | Source‑of‑truth for scope | Did we include the current tree? |
+| **Scope of Work** | *What* to touch | Which guides/folders? |
+| **Deliverables / Manifest** | Exact files to create / modify / delete | Could a newcomer do it with just this? |
+| **Phases** | Bite‑sized plan | Audit → Extract → Refactor → Index |
+| **Implementation Plan** | Divided into Planning Steps (`* [ ]`) for analysis/design and Execution Steps (`- [ ]`) for implementation actions. Consider embedding automated test/verification steps directly. | |
+| **Acceptance Criteria** | Definition of Done | Check‑list style `[ ]`. **Can include references to automated checks defined in the Implementation Plan's Planning and Execution sections or be high-level checks themselves.** |
+| **Out of Scope** | Prevent scope creep | What must *not* be touched? |
+| **References & Risks** | Links to style guides, ADRs, **testing standards (like [Embedded Testing Guide](ace-docs/handbook/guides/embedded-testing-guide.g.md))**; mitigations | Any scripts to run? **Use links relative to the project root (e.g., `ace-handbook/handbook/guides/some-guide.g.md`), not relative to the current file (`../guides/some-guide.md`)** |
+
+---
+
+## 2. Task Template
+
+A re-usable Markdown template for tasks is available at:
+[`ace-task/handbook/templates/task/draft.template.md`](../templates/task/draft.template.md)
+
+This template includes all the standard sections discussed in "Anatomy of a Great Task". You should copy this template and fill it out for each new task. Remember to use `task-manager generate-id VERSION` to generate the task ID.
+
+### Planning vs. Execution Steps
+
+The template's Implementation Plan section is divided into two subsections to support different phases of task work:
+
+- **Planning Steps (`* [ ]`)**: Optional but recommended for complex tasks. Use asterisk markers for research, analysis, and design activities that help clarify the approach before implementation begins. These steps are typically worked on during task review or initial planning phases.
+
+- **Execution Steps (`- [ ]`)**: Required section. Use hyphen markers for concrete implementation actions that modify code, create files, or change the system state. These steps are the actual work performed when implementing the task.
+
+This distinction supports workflow separation where review/planning phases focus on Planning Steps, while implementation phases focus on Execution Steps. Both sections can include embedded tests as guardrails.
+
+> **Tip: Generating Task IDs with `task-manager generate-id`**
+> Always use the `task-manager generate-id VERSION` command (run from the project root)
+> to generate the task ID for the `id` field in the front-matter.
+> This script ensures the ID is unique, correctly formatted, and uses the next sequential
+> number for the current release, as per the conventions in
+> `ace-task/handbook/guides/project-management.g.md#task-id-convention`.
+
+---
+
+## 3. **Full Worked Example**
+
+A full worked example of a task, "Tailor Guides to Tech Stack," has been moved to a separate file:
+[`ace-task/handbook/templates/release-tasks/example.md`](../templates/release-tasks/example.md)
+
+This example demonstrates how to fill out the template for a real-world scenario.
+
+---
+
+### 4. Planning vs. Execution Examples
+
+#### Simple Task (Execution Steps Only)
+
+For straightforward tasks that don't require research or design, you can skip Planning Steps:
+
+```markdown
+## Implementation Plan
+
+### Execution Steps
+- [ ] Update the configuration file with new API endpoint
+- [ ] Test the connection to verify it works
+  > TEST: API Connection Check
+  >   Type: Action Validation
+  >   Assert: The new API endpoint responds with status 200
+  >   Command: # Run project-specific test command --check-api-connection
+- [ ] Update documentation with the new endpoint URL
+```
+
+#### Complex Task (Both Planning and Execution)
+
+For complex tasks requiring analysis or design decisions, include both sections:
+
+```markdown
+## Implementation Plan
+
+### Planning Steps
+* [ ] Research existing authentication patterns in the codebase
+  > TEST: Pattern Analysis Complete
+  >   Type: Pre-condition Check
+  >   Assert: Current auth patterns are documented and understood
+  >   Command: # Run project-specific test command --check-analysis-exists auth-patterns.md
+* [ ] Design new OAuth integration approach considering security requirements
+* [ ] Plan database schema changes needed for user sessions
+
+### Execution Steps
+- [ ] Create new OAuth service class
+- [ ] Implement session management database tables
+  > TEST: Schema Migration
+  >   Type: Action Validation
+  >   Assert: Database migration runs successfully
+  >   Command: # Run project-specific test command --check-migration-success
+- [ ] Update user authentication flow
+- [ ] Add comprehensive tests for OAuth integration
+```
+
+### 5. Quick Checklist 🚦
+
+1. Is the **Directory Audit** present?
+2. Could a newcomer complete the work using only the manifest?
+3. Do the Acceptance Criteria read like QA steps?
+4. Is scope creep prevented by an **Out of Scope** section?
+5. Are references & scripts one click away?
+6. Are Planning Steps used for complex tasks requiring analysis/design?
+7. Do visual markers distinguish planning (`* [ ]`) from execution (`- [ ]`) steps?
+
+Tick them all → merge the ticket.

data/handbook/skills/as-bug-analyze/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: as-bug-analyze
+description: Analyze bugs to identify root cause, reproduction status, and fix plan
+# bundle: wfi://bug/analyze
+# context: no-fork
+# agent: Plan
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+argument-hint: [bug-description]
+last_modified: 2025-12-09
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://bug/analyze
+
+---
+
+Load and run `ace-bundle wfi://bug/analyze` 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-bug-fix/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: as-bug-fix
+description: Execute bug fix plan, apply changes, create tests, and verify resolution
+# bundle: wfi://bug/fix
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Bash(ace-test:*)
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+argument-hint: [bug-description-or-analysis-file]
+last_modified: 2026-01-10
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://bug/fix
+
+---
+
+Load and run `ace-bundle wfi://bug/fix` 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-task-document-unplanned/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: as-task-document-unplanned
+description: Document Unplanned Work
+# bundle: wfi://task/document-unplanned
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Bash(ace-git-commit:*)
+  - Read
+  - Write
+  - Edit
+  - TodoWrite
+argument-hint: [description]
+last_modified: 2026-01-10
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://task/document-unplanned
+
+---
+
+Load and run `ace-bundle wfi://task/document-unplanned` 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-task-draft/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: as-task-draft
+description: Draft Task with Idea File Movement (SPECS ONLY - no code)
+# bundle: wfi://task/draft
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - TodoWrite
+argument-hint: [task-description or idea-file-path]
+last_modified: 2026-01-10
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://task/draft
+
+---
+
+Load and run `ace-bundle wfi://task/draft` 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-task-finder/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: as-task-finder
+description: FIND tasks - list, filter, and discover tasks
+# bundle: wfi://task/finder
+# agent: Explore
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: "[list|show] [options]"
+last_modified: 2026-01-09
+source: ace-task
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://task/finder
+---
+
+Load and run `ace-bundle wfi://task/finder` 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-task-plan/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: as-task-plan
+description: Creates JIT implementation plan with ephemeral output, no task file modifications
+# bundle: wfi://task/plan
+# context: no-fork
+# agent: Plan
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - TodoWrite
+argument-hint: [task-id]
+last_modified: 2026-03-09
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://task/plan
+assign:
+  source: wfi://task/plan
+  steps:
+    - name: plan-task
+      description: Analyze task requirements and create an implementation plan
+      tags: [planning, analysis]
+      context:
+        default: fork
+---
+
+Load and run `ace-bundle wfi://task/plan` 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-task-review/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: as-task-review
+description: Reviews draft behavioral specs, promotes to pending when ready
+# bundle: wfi://task/review
+# context: no-fork
+# agent: Plan
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - TodoWrite
+argument-hint: [task-id like 123]
+last_modified: 2026-02-16
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://task/review
+
+---
+
+Load and run `ace-bundle wfi://task/review` 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-task-review-questions/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: as-task-review-questions
+description: Review and answer clarifying questions about task or implementation
+# bundle: wfi://task/review-questions
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - TodoWrite
+argument-hint: [question-context]
+last_modified: 2026-01-10
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://task/review-questions
+
+---
+
+Load and run `ace-bundle wfi://task/review-questions` 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-task-update/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: as-task-update
+description: Update task metadata, status, position, or location
+# bundle: wfi://task/update
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Read
+argument-hint: "<ref> [--set K=V] [--move-to FOLDER] [--move-as-child-of PARENT|none] [--position first|after:<ref>]"
+last_modified: 2026-03-21
+source: ace-task
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://task/update
+
+---
+
+Load and run `ace-bundle wfi://task/update` 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-task-work/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: as-task-work
+description: Execute task implementation with context loading and change commits
+# bundle: wfi://task/work
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Bash(ace-git-commit:*)
+  - Read
+  - Write
+  - Edit
+  - TodoWrite
+  - Task
+argument-hint: [task-id like 123]
+last_modified: 2026-02-17
+source: ace-task
+assign:
+  source: wfi://task/work
+  steps:
+    - name: work-on-task
+      description: Implement task changes following project conventions
+      intent:
+        phrases:
+          - "work on task"
+          - "implement task"
+          - "task work"
+          - "build feature"
+      tags: [implementation, core-workflow]
+      context:
+        default: fork
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://task/work
+---
+
+## Instructions
+
+- read and run `ace-bundle wfi://task/work`

data/handbook/templates/task/draft.template.md

@@ -0,0 +1,166 @@
+---
+id:
+  id:
+status: draft
+priority:
+  priority:
+estimate: TBD
+dependencies:
+  dependencies:
+bundle:
+  presets:
+  - project
+  files: []
+  commands: []
+doc-type: template
+purpose: Template for drafting task definitions
+ace-docs:
+  last-updated: '2026-03-21'
+---
+
+# {title}
+
+## Behavioral Specification
+
+### User Experience
+- **Input**: [What users provide - data, commands, interactions]
+- **Process**: [What users experience during interaction - feedback, states, flows]
+- **Output**: [What users receive - results, confirmations, artifacts]
+
+### Expected Behavior
+<!-- Describe WHAT the system should do from the user's perspective -->
+<!-- Focus on observable outcomes, system responses, and user experience -->
+<!-- Avoid implementation details - no mention of files, code structure, or technical approaches -->
+
+[Describe the desired behavior, user experience, and system responses]
+
+### Interface Contract
+<!-- Define all external interfaces, APIs, and interaction points -->
+<!-- Include normal operations, error conditions, and edge cases -->
+
+```bash
+# CLI Interface (if applicable)
+command-name [options] <arguments>
+# Expected outputs, error messages, and status codes
+
+# API Interface (if applicable)
+GET/POST/PUT/DELETE /endpoint
+# Request/response formats, error responses, status codes
+
+# UI Interface (if applicable)
+# User interactions, form behaviors, navigation flows
+```
+
+**Exit Codes** (CLI tasks):
+<!-- Define exit code semantics - what each code means -->
+| Code | Meaning |
+|------|---------|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid arguments/usage |
+| 130 | Interrupted (Ctrl+C) |
+
+**Error Handling:**
+- [Error condition 1]: [Expected system response]
+- [Error condition 2]: [Expected system response]
+
+**Input Validation** (data-driven features):
+<!-- Define what validation is required for input data -->
+- [Required field 1]: [Validation rule and error if missing]
+- [Required field 2]: [Validation rule and error if missing]
+
+**Edge Cases:**
+- [Edge case 1]: [Expected behavior]
+- [Edge case 2]: [Expected behavior]
+
+**Concurrency Considerations** (if applicable):
+<!-- Document multi-process safety requirements -->
+- [ ] File operations: [Atomic write requirements]
+- [ ] ID generation: [Uniqueness guarantees under concurrent access]
+- [ ] State management: [Race condition handling]
+
+**Cleanup Behavior:**
+<!-- What happens to resources on success, failure, and interruption -->
+- Success: [Expected cleanup]
+- Failure: [Expected cleanup - no orphan temp files]
+- Interruption: [Expected cleanup on SIGINT]
+
+### Success Criteria
+<!-- Define measurable, observable criteria that indicate successful completion -->
+<!-- Focus on behavioral outcomes and user experience, not implementation artifacts -->
+
+- [ ] **Behavioral Outcome 1**: [Observable user/system behavior or capability]
+- [ ] **User Experience Goal 2**: [Measurable user experience improvement]
+- [ ] **System Performance 3**: [Measurable system behavior or performance metric]
+
+### Validation Questions
+<!-- Questions to clarify requirements, resolve ambiguities, and validate understanding -->
+<!-- Ask about unclear requirements, edge cases, and user expectations -->
+
+- [ ] **Requirement Clarity**: [Question about unclear or ambiguous requirements]
+- [ ] **Edge Case Handling**: [Question about boundary conditions or unusual scenarios]  
+- [ ] **User Experience**: [Question about user expectations, workflows, or interactions]
+- [ ] **Success Definition**: [Question about how success will be measured or validated]
+
+### Vertical Slice Decomposition (Task/Subtask Model)
+<!-- Describe end-to-end slices using task/subtask structure -->
+<!-- Use orchestrator + subtasks for multiple slices; use standalone task for one slice -->
+
+- **Slice Type**: [Standalone task | Orchestrator | Subtask]
+- **Slice Outcome**: [Observable end-to-end capability delivered by this task/subtask]
+- **Advisory Size**: [small | medium | large]
+- **Context Dependencies**: [Critical files/presets/commands this slice needs in fresh sessions]
+
+### Verification Plan
+<!-- Define verification strategy before implementation -->
+<!-- Include unit/equivalent checks, integration/e2e where applicable, and failure-path validation -->
+
+#### Unit / Component Validation
+- [ ] [Scenario]: [Expected observable result]
+
+#### Integration / E2E Validation (if cross-boundary behavior exists)
+- [ ] [Scenario]: [Expected observable result]
+
+#### Failure / Invalid-Path Validation
+- [ ] [Scenario]: [Expected error handling behavior]
+
+#### Verification Commands
+- [ ] [Command/check]: [Expected outcome]
+
+## Objective
+
+Why are we doing this? Focus on user value and behavioral outcomes.
+
+## Scope of Work
+<!-- Define the behavioral scope - what user experiences and system behaviors are included -->
+
+- **User Experience Scope**: [Which user interactions, workflows, and experiences are included]
+- **System Behavior Scope**: [Which system capabilities, responses, and behaviors are included]  
+- **Interface Scope**: [Which APIs, commands, or interfaces are included]
+
+### Deliverables
+<!-- Focus on behavioral and experiential deliverables, not implementation artifacts -->
+
+#### Behavioral Specifications
+- User experience flow definitions
+- System behavior specifications  
+- Interface contract definitions
+
+#### Validation Artifacts
+- Success criteria validation methods
+- User acceptance criteria
+- Behavioral test scenarios
+
+## Out of Scope
+<!-- Explicitly exclude implementation concerns to maintain behavioral focus -->
+
+- ❌ **Implementation Details**: File structures, code organization, technical architecture
+- ❌ **Technology Decisions**: Tool selections, library choices, framework decisions  
+- ❌ **Performance Optimization**: Specific performance improvement strategies
+- ❌ **Future Enhancements**: Related features or capabilities not in current scope
+
+## References
+
+- Related capture-it output (if applicable)
+- User experience requirements
+- Interface specification examples

data/handbook/templates/task/file-modification-checklist.template.md

@@ -0,0 +1,26 @@
+---
+doc-type: template
+purpose: Checklist template for tracking file changes in task and code reviews
+ace-docs:
+  last-updated: '2026-03-21'
+---
+
+## File Modifications
+
+### Create
+- path/to/new/file.ext
+  - Purpose: [why this file]
+  - Key components: [what it contains]
+  - Dependencies: [what it depends on]
+
+### Modify
+- path/to/existing/file.ext
+  - Changes: [what to modify]
+  - Impact: [effects on system]
+  - Integration points: [how it connects]
+
+### Delete
+- path/to/obsolete/file.ext
+  - Reason: [why removing]
+  - Dependencies: [what depends on this]
+  - Migration strategy: [how to handle removal]

data/handbook/templates/task/technical-approach.template.md

@@ -0,0 +1,26 @@
+---
+doc-type: template
+purpose: Technical approach template for implementation planning and architecture
+  decisions
+ace-docs:
+  last-updated: '2026-03-21'
+---
+
+## Technical Approach
+
+### Architecture Pattern
+- [ ] Pattern selection and rationale
+- [ ] Integration with existing architecture
+- [ ] Impact on system design
+
+### Technology Stack
+- [ ] Libraries/frameworks needed
+- [ ] Version compatibility checks
+- [ ] Performance implications
+- [ ] Security considerations
+
+### Implementation Strategy
+- [ ] Step-by-step approach
+- [ ] Rollback considerations
+- [ ] Testing strategy
+- [ ] Performance monitoring