ace-idea 0.18.0

data/docs/handbook.md

@@ -0,0 +1,39 @@
+---
+doc-type: user
+title: ace-idea Handbook Catalog
+purpose: Catalog of ace-idea workflows and skills
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-idea Handbook Catalog
+
+Reference for package-owned handbook resources in `ace-idea/handbook/`.
+
+## Skills
+
+| Skill | What it does |
+|------|---------------|
+| `as-idea-capture` | Capture a development idea into a structured idea file |
+| `as-idea-capture-features` | Document application features from a user perspective |
+| `as-idea-review` | Review idea clarity, scope, and readiness before task creation |
+
+## Workflow Instructions
+
+| Protocol Path | Purpose | Invoked by |
+|------|---------|------------|
+| `wfi://idea/capture` | Capture raw ideas from text or clipboard and store them as structured idea files | `as-idea-capture` |
+| `wfi://idea/capture-features` | Document application features from a user perspective | `as-idea-capture-features` |
+| `wfi://idea/review` | Critically review ideas for clarity, impact, and execution readiness | `as-idea-review` |
+| `wfi://idea/prioritize` | Prioritize and align ideas with current project architecture | Direct via `ace-bundle` |
+
+## Agents
+
+* None currently shipped in this package.
+
+## Related Docs
+
+* [Getting Started](getting-started.md)
+* [CLI Usage Reference](usage.md)
+* Load workflows directly with `ace-bundle wfi://idea/capture`

data/docs/usage.md

@@ -0,0 +1,320 @@
+---
+doc-type: user
+title: ace-idea CLI Usage Reference
+purpose: Command reference for ace-idea
+ace-docs:
+  last-updated: 2026-03-22
+  last-checked: 2026-03-22
+---
+
+# ace-idea CLI Usage Reference
+
+Reference for `ace-idea` commands, options, and everyday workflows.
+
+## Installation
+
+```bash
+gem install ace-idea
+```
+
+## Command Overview
+
+`ace-idea` ships six workflow commands:
+
+* `create` captures a new idea from text or clipboard input
+* `show` prints one idea by short or full ID
+* `list` filters ideas by folder, status, tags, or generic field filters
+* `update` edits frontmatter fields and folder placement
+* `doctor` checks idea storage and metadata health
+* `status` shows up-next and recently-done summaries
+
+Run `ace-idea --help` for the top-level command list. Use `ace-idea version` when you only need the installed version.
+
+## Quick Start
+
+Capture one idea, review it, and move it into your next queue:
+
+```bash
+ace-idea create "Dark mode for night coding" --title "Dark mode"
+ace-idea list
+ace-idea update q7w --move-to next
+ace-idea status
+```
+
+Success looks like a new folder appearing in `.ace-ideas/`, a matching ID in list output, and the idea moving into the
+root-scope `next` queue after the update.
+
+## Common Scenarios
+
+### Scenario 1: Capture from Clipboard and Expand It
+
+**Goal:** Turn a copied note into a structured idea file.
+
+```bash
+ace-idea create --clipboard --llm-enhance
+```
+
+**Expected output:**
+
+```text
+Idea created: 8ppq7w Dark mode
+  Path: /path/to/project/.ace-ideas/8ppq7w-dark-mode/8ppq7w-dark-mode.idea.s.md
+```
+
+### Scenario 2: Move an Idea Through GTD-Style Folders
+
+**Goal:** Keep active ideas separate from maybe-later work.
+
+```bash
+ace-idea update q7w --move-to next
+ace-idea update q7w --move-to maybe
+ace-idea update q7w --move-to root
+```
+
+**Expected output:**
+
+```text
+Idea updated: 8ppq7w Dark mode -> root
+```
+
+### Scenario 3: Audit the Idea Store
+
+**Goal:** Find broken structure or metadata before ideas drift.
+
+```bash
+ace-idea doctor --auto-fix --dry-run
+ace-idea status --up-next-limit 5
+```
+
+## Commands
+
+### `ace-idea create [CONTENT]`
+
+Create a new idea from direct text or clipboard input.
+
+**Syntax:**
+
+```bash
+ace-idea create [CONTENT] [options]
+```
+
+**Options:**
+
+* `--title`, `-t` - Explicit title for the new idea
+* `--tags`, `-T` - Comma-separated tags
+* `--move-to`, `-m` - Place the idea in a named folder (e.g. `maybe`, `review`, `archive`) or `next` for root
+* `--clipboard`, `-c` - Read idea content from the system clipboard
+* `--llm-enhance`, `-l` - Expand or refine the captured content with the configured LLM
+* `--dry-run`, `-n` - Preview the capture without writing files
+* `--git-commit`, `--gc` - Commit the created idea automatically
+* `--quiet`, `-q` - Suppress non-essential output
+* `--verbose`, `-v` - Show verbose output
+* `--debug`, `-d` - Show debug output
+
+**Examples:**
+
+```bash
+ace-idea create "My idea"
+ace-idea create "Dark mode" --title "Dark mode" --tags ux,design
+ace-idea create --clipboard --llm-enhance --move-to maybe
+ace-idea create "Rough note" --dry-run
+```
+
+### `ace-idea show REF`
+
+Display one idea by full 6-character ID or 3-character shortcut.
+
+**Syntax:**
+
+```bash
+ace-idea show REF [options]
+```
+
+**Options:**
+
+* `--path` - Print only the file path
+* `--content` - Print the raw markdown content
+* `--quiet`, `-q` - Suppress non-essential output
+* `--verbose`, `-v` - Show verbose output
+* `--debug`, `-d` - Show debug output
+
+**Examples:**
+
+```bash
+ace-idea show q7w
+ace-idea show 8ppq7w --path
+ace-idea show q7w --content
+```
+
+### `ace-idea list`
+
+List ideas with folder, status, tag, or generic field filters.
+
+**Syntax:**
+
+```bash
+ace-idea list [options]
+```
+
+**Options:**
+
+* `--status`, `-s` - Filter by status: `pending`, `in-progress`, `done`, `obsolete`
+* `--tags`, `-T` - Filter by comma-separated tags
+* `--in`, `-i` - Filter by folder: `next`, `all`, `maybe`, `anytime`, `archive`
+* `--root`, `-r` - Override the root path within the ideas tree
+* `--filter`, `-f` - Repeatable `key:value` filter, including `a|b` and negation forms
+* `--quiet`, `-q` - Suppress non-essential output
+* `--verbose`, `-v` - Show verbose output
+* `--debug`, `-d` - Show debug output
+
+**Examples:**
+
+```bash
+ace-idea list
+ace-idea list --in maybe
+ace-idea list --status pending --tags ux,design
+ace-idea list --filter status:pending --filter tags:ux|design
+```
+
+### `ace-idea update REF`
+
+Update idea frontmatter and folder placement.
+
+**Syntax:**
+
+```bash
+ace-idea update REF [options]
+```
+
+**Options:**
+
+* `--set` - Set a scalar field with `key=value`
+* `--add` - Add a value to an array field with `key=value`
+* `--remove` - Remove a value from an array field with `key=value`
+* `--move-to`, `-m` - Move the idea to any named folder (e.g. `archive`, `maybe`, `review`) or `next`/`root` for top-level
+* `--git-commit`, `--gc` - Commit the update automatically
+* `--quiet`, `-q` - Suppress non-essential output
+* `--verbose`, `-v` - Show verbose output
+* `--debug`, `-d` - Show debug output
+
+**Examples:**
+
+```bash
+ace-idea update q7w --set status=done
+ace-idea update q7w --set status=in-progress --add tags=research
+ace-idea update q7w --remove tags=research --move-to next
+ace-idea update q7w --move-to archive
+```
+
+### `ace-idea doctor`
+
+Run health checks across the idea store.
+
+**Syntax:**
+
+```bash
+ace-idea doctor [options]
+```
+
+**Options:**
+
+* `--quiet`, `-q` - Exit silently unless the check fails
+* `--verbose`, `-v` - Show warnings and additional detail
+* `--auto-fix`, `-f` - Apply safe fixes after confirmation
+* `--auto-fix-with-agent` - Apply safe fixes and then launch an agent for the remaining issues
+* `--model` - Provider/model override for agent-assisted fixes
+* `--errors-only` - Hide warnings and show only errors
+* `--no-color` - Disable ANSI colors
+* `--json` - Emit JSON output
+* `--dry-run`, `-n` - Preview fixes without writing changes
+* `--check` - Restrict checks to `frontmatter`, `structure`, or `scope`
+
+**Examples:**
+
+```bash
+ace-idea doctor
+ace-idea doctor --auto-fix --dry-run
+ace-idea doctor --check frontmatter --json
+```
+
+### `ace-idea status`
+
+Show a dashboard view of up-next and recently completed ideas.
+
+**Syntax:**
+
+```bash
+ace-idea status [options]
+```
+
+**Options:**
+
+* `--up-next-limit` - Maximum items to show in the up-next section
+* `--recently-done-limit` - Maximum items to show in the recently-done section
+
+**Examples:**
+
+```bash
+ace-idea status
+ace-idea status --up-next-limit 5
+ace-idea status --recently-done-limit 3
+```
+
+**Expected output:**
+
+```text
+Up Next:
+  ○ 8ppq7w  Dark mode
+  ○ 8rrab4  API rate limiting
+
+Ideas: ○ 3 | ✓ 2 • 5 total
+
+Recently Done:
+  ✓ 8nn1k2  Onboarding flow  (2d ago)
+  ✓ 8mm3j1  Error page redesign  (5d ago)
+```
+
+## Storage Notes
+
+By default, ideas are stored in `.ace-ideas/` under the current directory. Each idea gets its own folder and spec file:
+
+```text
+.ace-ideas/
+  8ppq7w-dark-mode/
+    8ppq7w-dark-mode.idea.s.md
+```
+
+Special folders such as `_maybe`, `_anytime`, and `_archive` sit under the same root and are managed through
+`ace-idea update --move-to ...`. The `next` queue is the virtual root-only view, so `ace-idea update --move-to next`
+returns an idea to the root and `ace-idea list --in next` filters for root-scope ideas.
+
+## Troubleshooting
+
+### Problem: `ace-idea create` says no content was provided
+
+**Symptom:** You ran `create` with no positional text and no `--clipboard`.
+
+**Solution:**
+
+```bash
+ace-idea create "Your idea text here"
+```
+
+### Problem: Clipboard capture fails
+
+**Symptom:** `--clipboard` cannot read copied content on your system.
+
+**Solution:** Fall back to direct text input or install the clipboard support expected by your environment.
+
+### Problem: An idea cannot be found by shortcut
+
+**Symptom:** `ace-idea show q7w` or `ace-idea update q7w ...` reports that the idea does not exist.
+
+**Solution:** Use `ace-idea list --in all` to confirm the idea ID and folder placement, then retry with the full 6-character
+ID if needed.
+
+### Problem: `ace-idea doctor` says the idea directory is missing
+
+**Symptom:** The configured ideas root does not exist yet.
+
+**Solution:** Create an idea first or set `idea.root_dir` in config before running `doctor`.

data/exe/ace-idea

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/ace/idea"
+require_relative "../lib/ace/idea/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::Idea::IdeaCLI.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/skills/as-idea-capture/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: as-idea-capture
+description: Capture development idea to structured idea file with tags
+# bundle: wfi://idea/capture
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-idea:*)
+  - Bash(ace-bundle:*)
+  - Bash(ace-git-commit:*)
+  - Write
+  - TodoWrite
+argument-hint: [idea-description]
+last_modified: 2026-01-10
+source: ace-idea
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://idea/capture
+
+---
+
+Load and run `ace-bundle wfi://idea/capture` 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-idea-capture-features/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: as-idea-capture-features
+description: Capture Application Features
+# bundle: wfi://idea/capture-features
+# context: no-fork
+# agent: Explore
+user-invocable: true
+allowed-tools:
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Bash(ace-git-commit:*)
+  - Read
+  - Write
+  - Edit
+  - TodoWrite
+argument-hint: [app-path]
+last_modified: 2026-01-10
+source: ace-idea
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://idea/capture-features
+
+---
+
+Load and run `ace-bundle wfi://idea/capture-features` 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-idea-review/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: as-idea-review
+description: Critically review ideas for clarity, feasibility, and readiness for task creation
+# bundle: wfi://idea/review
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-idea:*)
+  - Bash(ace-task:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - Edit
+  - MultiEdit
+  - TodoWrite
+argument-hint: [idea-id]
+last_modified: 2026-03-12
+source: ace-idea
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://idea/review
+---
+
+Load and run `ace-bundle wfi://idea/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/workflow-instructions/idea/capture-features.wf.md

@@ -0,0 +1,243 @@
+---
+doc-type: workflow
+title: Capture Application Features
+purpose: Documentation for ace-idea/handbook/workflow-instructions/idea/capture-features.wf.md
+ace-docs:
+  last-updated: 2026-03-01
+  last-checked: 2026-03-21
+---
+
+# Capture Application Features
+
+## Goal
+
+Document application features from a user perspective to ensure clarity for developers, product managers, QA engineers, and content editors.
+
+## Prerequisites
+
+* Understanding of the application's user interface and functionality
+* Access to the application or its design documentation
+* Knowledge of user interaction patterns and workflows
+* Familiarity with tracking and analytics requirements
+
+## Project Context Loading
+
+* Load workflow standards: `ace-nav guide://workflow-instructions-definition`
+* Load template embedding guide: `ace-nav guide://template-embedding`
+* Review existing feature documentation patterns if available
+
+## Process Steps
+
+1. **Identify the Feature or Section:**
+   * Name the feature or page section (e.g., Hero Banner, Blog List, User Dashboard)
+   * Write a one-line purpose statement describing its value to users
+   * Note technical dependencies (CMS fields, APIs, static assets, databases)
+   
+   **Validation:**
+   * Feature name is clear and consistent with existing nomenclature
+   * Purpose statement answers "what value does this provide to users?"
+
+2. **Document Structure and Components:**
+   * List all UI components and subsections within the feature
+   * Mark each component as required or optional
+   * Include field types, data sources, and display conditions
+   * Document responsive behavior across device types
+   
+   **Example Format:**
+   ```markdown
+   **Components:**
+   - Header text (required) - CMS field: `hero_title`
+   - Subheading (optional) - CMS field: `hero_subtitle`
+   - Background image (required) - Asset: `hero_background`
+   - CTA button (optional) - Links to: `cta_url`
+   ```
+
+3. **Capture User Interactions:**
+   * Document all interactive elements using action → reaction format
+   * Include state changes and feedback mechanisms
+   * Note any conditional logic or personalization rules
+   
+   **Interaction Pattern:**
+   ```markdown
+   - Click "Learn More" button → Navigate to detailed page
+   - Hover over image → Display caption overlay
+   - Submit form → Show success message and redirect
+   ```
+
+4. **Define Tracking and Analytics:**
+   * Specify all tracking events using consistent naming (snake_case)
+   * Include event parameters and data attributes
+   * Document when each event fires
+   
+   **Tracking Format:**
+   ```markdown
+   **Tracking Events:**
+   - `hero_cta_clicked` — User clicks main CTA [section_id, cta_text]
+   - `blog_article_viewed` — Article enters viewport [article_id, position]
+   - `form_submission_started` — User begins form [form_id, source]
+   ```
+
+5. **Document States and Variations:**
+   * Identify all possible states for the feature
+   * Describe expected behavior in each state
+   * Include error handling and edge cases
+   
+   **State Documentation:**
+   ```markdown
+   **States:**
+   - Loading: Display skeleton loader with animations
+   - Empty: Show helpful message with action suggestions
+   - Error: Display error message with retry option
+   - Success: Show confirmation with next steps
+   ```
+
+6. **Capture Business Rules:**
+   * Document any conditional display logic
+   * Note permission requirements or user role restrictions
+   * Include time-based or geographic variations
+   
+   **Example Rules:**
+   ```markdown
+   **Display Rules:**
+   - Show only to logged-in users with active subscription
+   - Display between 9 AM - 5 PM user's local time
+   - Hide on mobile devices under 375px width
+   ```
+
+7. **Create Feature Documentation:**
+   * Use the embedded template structure below
+   * Save in appropriate documentation location
+   * Include screenshots or mockups if available
+   * Cross-reference with technical implementation docs
+
+## Embedded Templates and Examples
+
+<templates>
+<template path="feature-documentation-template.md">
+# Feature: [Feature Name]
+
+## Overview
+**Purpose:** [One sentence describing the feature's value to users]
+**Location:** [Where in the application this appears]
+**User Types:** [Which users see/use this feature]
+
+## Structure
+
+### Components
+- **[Component Name]** ([required/optional])
+  - Type: [text/image/button/form/etc.]
+  - Source: [CMS field/API/static]
+  - Description: [What it displays or does]
+
+### Layout
+[Describe the visual arrangement and responsive behavior]
+
+## User Interactions
+
+| Action | System Response | Notes |
+|--------|----------------|-------|
+| [User action] | [What happens] | [Additional context] |
+
+## Tracking & Analytics
+
+### Events
+| Event Name | Trigger | Parameters |
+|------------|---------|------------|
+| `[event_name]` | [When it fires] | [Data sent] |
+
+### Metrics
+- [Key metric 1]: [How measured]
+- [Key metric 2]: [How measured]
+
+## States & Variations
+
+### States
+- **Default:** [Normal display state]
+- **Loading:** [What shows while loading]
+- **Empty:** [No data available]
+- **Error:** [Error handling]
+
+### Variations
+- **[Variation name]:** [When shown and differences]
+
+## Business Rules
+- [Rule 1]: [Condition and behavior]
+- [Rule 2]: [Condition and behavior]
+
+## Technical Notes
+- **Dependencies:** [Required services/data]
+- **Performance:** [Loading considerations]
+- **Accessibility:** [WCAG compliance notes]
+
+## Examples
+
+### Scenario 1: [Common Use Case]
+[Step-by-step user journey]
+
+### Scenario 2: [Edge Case]
+[How system handles unusual situation]
+
+## Related Documentation
+- [Link to design specs]
+- [Link to API docs]
+- [Link to implementation guide]
+</template>
+
+<template path="quick-feature-capture.md">
+### Section: [Name]
+**Purpose:** [one sentence describing user value]
+
+**Components:**
+- [component 1] (required/optional) - [source/type]
+- [component 2] (required/optional) - [source/type]
+
+**User Interactions:**
+- [action] → [reaction]
+- [action] → [reaction]
+
+**Tracking Events:**
+- `[event_name]` — [trigger] [parameters]
+
+**States:**
+- [state]: [description]
+- [state]: [description]
+</template>
+</templates>
+
+## Success Criteria
+
+* Feature documentation captures all user-facing aspects
+* Interactive elements and their behaviors are clearly defined
+* Tracking events follow consistent naming conventions
+* All states and error conditions are documented
+* Business rules and display logic are explicit
+* Documentation is accessible to both technical and non-technical stakeholders
+* Cross-references to implementation details are included
+
+## Error Handling
+
+**Missing Information:**
+* **Symptoms:** Unable to determine feature behavior or requirements
+* **Solution:** Interview stakeholders, review designs, or test the live feature
+
+**Inconsistent Naming:**
+* **Symptoms:** Same feature called different names in different contexts
+* **Solution:** Establish naming conventions and update all references
+
+**Unclear User Value:**
+* **Symptoms:** Cannot articulate why users need this feature
+* **Solution:** Conduct user research or review product requirements
+
+## Usage Example
+
+> "Document the blog listing page that shows articles from our CMS, including the hero section, article cards, pagination, and newsletter signup."
+
+Following this workflow would produce:
+
+1. Identify each section (hero, article list, pagination, newsletter)
+2. Document components (titles, images, buttons, forms)
+3. Map interactions (click to read, page navigation, form submission)
+4. Define tracking (article_clicked, page_viewed, newsletter_subscribed)
+5. Document states (loading articles, no results, pagination limits)
+6. Capture rules (articles per page, sort order, filtering)
+7. Create comprehensive feature documentation using the template