ace-retro 0.16.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: eb5b8024dc50731df20e18afc1d1bcc018c84fe5a516aef9047f28c0a20b4d43
+  data.tar.gz: 904ef67f12f2254d81a5ac09569304d81509e1f95603238256e78c8dea94056f
+SHA512:
+  metadata.gz: f170bc514bd1b7161db5c72aba36c31abf96fe4346f106e6b8a1b059e8f7c0c05b6be469b5cdb03814132c6a164ad27627518300ccd8fdc95f496ba23fe58f4f
+  data.tar.gz: 0da214c947afd6a4d9015be9503ff5c29f3283d10a82ad5926cb67df31fbeab642495edc15b9e9323a72839d9dea9b7194ca5d6ede4587d90b9b5b7d87b7082d

data/.ace-defaults/nav/protocols/wfi-sources/ace-retro.yml

@@ -0,0 +1,19 @@
+---
+# WFI Sources Protocol Configuration for ace-retro gem
+# This enables workflow discovery from the installed ace-retro gem
+
+name: ace-retro
+type: gem
+description: Retrospective workflow instructions from ace-retro gem
+priority: 10
+
+# Configuration for workflow discovery within the gem
+config:
+  # Relative path within the gem (default: handbook/workflow-instructions)
+  relative_path: handbook/workflow-instructions
+
+  # Pattern for finding workflow files (default: *.wf.md)
+  pattern: "*.wf.md"
+
+  # Enable discovery
+  enabled: true

data/.ace-defaults/retro/config.yml

@@ -0,0 +1,16 @@
+# ace-retro default configuration
+retro:
+  # Root directory for retros storage
+  root_dir: .ace-retros
+
+  # Default status for new retros
+  default_status: active
+
+  # Default retro type
+  default_type: standard
+
+  # Prefix used to identify special folders (e.g., "_archive")
+  special_folder_prefix: "_"
+
+  # LLM model for doctor --auto-fix-with-agent
+  doctor_agent_model: gemini:flash-latest@yolo

data/CHANGELOG.md

@@ -0,0 +1,252 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.16.0] - 2026-03-24
+
+### Changed
+- Removed `task_ref` feature: dropped `--task-ref` CLI flag, model field, frontmatter key, and display formatting.
+- Aligned README tagline with gemspec summary; added CLI-first onboarding language.
+- Re-recorded getting-started demo with dynamic ID capture.
+
+### Fixed
+- VHS tape compiler now uses backtick quoting for commands containing quotes, `$`, or backslashes.
+
+### Technical
+- Cleaned task_ref references from docs, handbook workflow, test helper, and all test layers.
+- Added inline jargon definitions for short IDs and frontmatter in docs.
+
+## [0.15.4] - 2026-03-23
+
+### Changed
+- Refreshed the package README with a stronger overview, quick documentation navigation, and use-case-first structure aligned with current README layout patterns.
+
+## [0.15.3] - 2026-03-22
+
+### Changed
+- Updated the getting-started demo to create a retro and capture its runtime ID before invoking `ace-retro show`, replacing the hard-coded `001` reference.
+
+## [0.15.2] - 2026-03-22
+
+### Changed
+- Add commit step (step 7) to the retro creation workflow so retros created inside fork subtrees are preserved in git history.
+- Add review-aware reflection prompts for cross-cycle analysis when review session data is available.
+
+## [0.15.1] - 2026-03-22
+
+### Fixed
+- Add ID discovery hints to getting-started guide so tutorial steps are runnable from a clean workspace.
+
+## [0.15.0] - 2026-03-22
+
+### Changed
+- Reworked package documentation into a landing-page experience with a new README, tutorial-style getting-started guide, comprehensive usage reference, handbook catalog, and demo artifacts.
+- Updated gem metadata messaging to align with the new value-first tagline and included `docs/**/*` in packaged gem files.
+
+## [0.14.0] - 2026-03-21
+
+### Changed
+- Added initial value-gated TS-format E2E smoke coverage under `TS-RETRO-001` for CLI help/error surface, create/list/show lifecycle, folder/filter views, and doctor health-to-failure transitions.
+- Added a package E2E Decision Record documenting ADD/SKIP outcomes with unit-test coverage evidence.
+
+## [0.13.1] - 2026-03-18
+
+### Changed
+- Migrated CLI namespace from `Ace::Core::CLI::*` to `Ace::Support::Cli::*` (ace-support-cli is now the canonical home for CLI infrastructure).
+
+
+## [0.13.0] - 2026-03-18
+
+### Changed
+- Removed legacy backward-compatibility behavior as part of the 0.10 cleanup release.
+
+
+## [0.12.2] - 2026-03-15
+
+### Changed
+- Migrated CLI framework from dry-cli to ace-support-cli
+
+## [0.12.1] - 2026-03-13
+
+### Changed
+- Updated the canonical handbook self-improvement skill to explicitly run its bundled workflow in the current project and execute it end-to-end.
+
+## [0.12.0] - 2026-03-10
+
+### Added
+- Added the canonical handbook-owned self-improve skill under the retro package.
+
+
+## [0.11.0] - 2026-03-08
+
+### Changed
+- Remove hardcoded `providers.cli_args` config; use ace-llm `@preset` suffixes for provider permission flags
+
+## [0.10.1] - 2026-03-04
+
+### Fixed
+- Restored backward-compatible legacy `doctor_cli_args` fallback when using nested `retro.doctor.cli_args`.
+
+### Changed
+- Preserved compatibility for legacy codex default shorthand values when normalizing provider CLI args.
+
+## [0.10.0] - 2026-03-04
+
+### Changed
+- Renamed doctor agent CLI argument config from `doctor_cli_args` to nested `doctor.cli_args`.
+- Converted default doctor CLI args for `gemini` to array format.
+
+- Switched default doctor arg values to provider-array format.
+
+## [0.9.0] - 2026-03-03
+
+### Added
+- Doctor `--auto-fix-with-agent` option: runs deterministic auto-fixes first, then launches an LLM agent to handle remaining issues
+- Doctor `--model` option: configure provider:model for agent sessions
+- Default `doctor_agent_model` and `doctor_cli_args` config entries
+
+## [0.8.3] - 2026-03-03
+
+### Changed
+- Config: replaced `special_folders` map with `special_folder_prefix: "_"` (prefix-based detection replaces hardcoded folder list)
+
+## [0.8.2] - 2026-03-03
+
+### Changed
+- RetroCreator uses two-tier naming: folder slug (5 words) and file slug (7 words) for concise folders with descriptive filenames
+
+## [0.8.1] - 2026-03-03
+
+### Changed
+- List items: ID, type label, tags, task reference, and folder are dimmed for visual contrast with title
+
+## [0.8.0] - 2026-03-03
+
+### Added
+- Colored status symbols in list output: active (yellow), done (green) — TTY-aware, no color when piped
+- `last_folder_counts` on `RetroScanner` and `RetroManager`: exposes per-folder item counts from the full scan for use in stats line
+- `list --help` status legend with ANSI colors matching list output
+
+### Changed
+- Status symbols replaced from emoji (🟡🟢) to Unicode shapes (○✓) for consistent terminal rendering and colorization support
+- `format_list` and `format_stats_line` accept `global_folder_stats:` parameter, always showing folder breakdown in stats line even when viewing a filtered subset
+
+## [0.7.0] - 2026-03-02
+
+### Added
+- `--move-to` / `-m` option on `update` command: relocate retro to a special folder (archive) or back to root (next/root//)
+
+### Changed
+- `update` command now accepts `--move-to` alone (no `--set` required), replacing the standalone `move` command
+
+### Removed
+- Standalone `move` command — use `update --move-to` instead
+- `RetroManager#move` method — use `RetroManager#update(move_to:)` instead
+
+## [0.6.0] - 2026-03-02
+
+### Added
+- `--git-commit` / `--gc` flag on `create`, `update`, and `move` commands to auto-commit changes via `ace-git-commit`
+
+## [0.5.0] - 2026-03-02
+
+### Added
+- `RetroScanner#last_scan_total` exposes total item count before folder filtering
+- `RetroManager#last_list_total` exposes total item count for "X of Y" stats display
+- `RetroDisplayFormatter.format_list` and `format_stats_line` accept `total_count:` parameter
+- CLI list command passes total count through to formatter for contextual stats
+
+## [0.4.0] - 2026-03-02
+
+### Added
+- `RetroDisplayFormatter.format_stats_line` for generating stats summary (e.g., "Retros: 🟡 2 | 🟢 5 • 7 total • 71% complete")
+- `format_list` now appends a stats summary line after the item list (omitted for empty lists)
+
+## [0.3.0] - 2026-03-02
+
+### Changed
+- `RetroManager#list` defaults to `in_folder: "next"` — shows only root retros by default (excludes _archive)
+- `RetroScanner#scan_in_folder` supports virtual filters ("next" for root-only, "all" for everything)
+- Use `--in all` to see all retros including archived (previous default behavior)
+
+## [0.2.3] - 2026-03-01
+
+### Changed
+
+- Rewrite create.wf.md: simplify from 486 to ~90 lines, reference `tmpl://retro/retro` instead of embedding template, use `ace-retro create` CLI
+- Rewrite selfimprove.wf.md: broaden input sources (session/retros/user), use `ace-nav` protocol paths, add retro creation and archive steps
+- Rewrite synthesize.wf.md: reduce to N retros → 1 retro pattern using `ace-retro` CLI, remove `reflection-synthesize` command references
+
+### Removed
+
+- Delete `synthesis-analytics.template.md` (synthesize workflow is self-contained)
+- Delete `synthesize.system.prompt.md` (synthesize workflow is self-contained)
+
+## [0.2.2] - 2026-03-01
+
+### Fixed
+
+- Doctor flags invalid archive partitions (e.g., `_archive/2025-09/`) and fixer relocates retros to correct b36ts partitions via RetroMover
+- Doctor accepts valid b36ts archive partitions (e.g., `_archive/8o/`)
+
+## [0.2.1] - 2026-03-01
+
+### Fixed
+
+- Wire `--root` option in `list` command to pass through to RetroManager
+- Use DatePartitionPath for doctor auto-fix archive moves (consistent with RetroMover)
+
+### Added
+
+- Regression test for `--root` option in list CLI command
+
+## [0.2.0] - 2026-03-01
+
+### Added
+
+- `doctor` command for comprehensive retro health checks
+- RetroValidationRules atom with status validation, scope consistency, required/recommended field checks
+- RetroFrontmatterValidator molecule for per-file frontmatter validation
+- RetroStructureValidator molecule for directory structure checks (folder naming, retro files, backups, empty dirs)
+- RetroDoctorFixer molecule with auto-fix support for 15 fixable patterns and dry-run mode
+- RetroDoctorReporter molecule with terminal, JSON, and summary output formats
+- RetroDoctor organism orchestrating structure, frontmatter, and scope checks with health scoring
+- CLI options: `--auto-fix`, `--check`, `--verbose`, `--json`, `--errors-only`, `--no-color`, `--dry-run`, `--quiet`
+- Exit code 0 when healthy, non-zero when errors found
+
+## [0.1.0] - 2026-03-01
+
+Extracted from ace-taskflow into standalone gem with b36ts-based retro management.
+
+### Added
+
+- Initial release of ace-retro gem
+- RetroIdFormatter atom for raw b36ts ID generation
+- RetroFilePattern atom for `.retro.md` file patterns
+- RetroFrontmatterDefaults atom for retro frontmatter generation
+- Retro model with id, status, title, type, tags, content, task_ref, folder_contents
+- RetroConfigLoader molecule for configuration cascade
+- RetroScanner molecule wrapping DirectoryScanner for `.retro.md` files
+- RetroResolver molecule wrapping ShortcutResolver for ID resolution
+- RetroLoader molecule for loading retros from directories
+- RetroCreator molecule for full retro creation with b36ts ID
+- RetroMover molecule with cross-filesystem move support (Errno::EXDEV)
+- RetroDisplayFormatter molecule for terminal output
+- RetroManager organism orchestrating create, show, list, update, move operations
+- `.ace-defaults/retro/config.yml` with default configuration
+- CLI registry (RetroCLI) with dry-cli following ace-idea pattern
+- `create` command: `ace-retro create TITLE [--type TYPE] [--tags T] [--task-ref REF] [--move-to FOLDER] [--dry-run]`
+- `show` command: `ace-retro show REF [--path | --content]`
+- `list` command: `ace-retro list [--status S] [--type T] [--tags T] [--in FOLDER]`
+- `move` command: `ace-retro move REF --to FOLDER`
+- `update` command: `ace-retro update REF [--set K=V]... [--add K=V]... [--remove K=V]...`
+- `version` and `help` commands
+- Executable `exe/ace-retro` with SIGINT handling (exit 130) and error rescue
+- Handbook: workflow instructions (retro/create, retro/synthesize) moved from ace-taskflow
+- Handbook: templates (retro, synthesis-analytics, synthesize system prompt) moved from ace-taskflow
+- CLI integration tests for all 5 commands

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michal Czyz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,40 @@
+<div align="center">
+  <h1> ACE - Retro </h1>
+
+  Lightweight retrospective management — create, tag, and archive retros from the command line.
+
+  <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/ace-retro"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-retro.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)
+
+![ace-retro demo](docs/demo/ace-retro-getting-started.gif)
+
+`ace-retro` helps teams capture learning while context is still fresh and maintain a searchable archive for follow-up improvements. Use [`ace-retro create`](docs/usage.md) to start a retro from the CLI (or `/as-retro-create` from an interactive agent session), and `/as-retro-synthesize` to distill patterns across multiple retros.
+
+## How It Works
+
+1. Create a retrospective from type-aware templates (standard, conversation-analysis, or self-review) with [`ace-retro create`](docs/usage.md).
+2. Enrich metadata with tags and status updates.
+3. Archive completed retros to preserve history while keeping the active workspace clean.
+
+## Use Cases
+
+**Capture retros quickly after delivery** - use `/as-retro-create` or [`ace-retro create`](docs/usage.md) to initialize a retro from templates while the work is still fresh.
+
+**Synthesize patterns across retros** - use `/as-retro-synthesize` to distill recurring themes and improvement opportunities from multiple retrospectives.
+
+**Review and maintain retro metadata** - list, show, and update retros with tags and status, then archive completed entries without losing searchability.
+
+**Improve agent workflows over time** - use `/as-handbook-selfimprove` to feed retro insights back into handbook guidance for better future performance.
+
+---
+[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/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/docs/demo/ace-retro-getting-started.tape.yml

@@ -0,0 +1,33 @@
+---
+description: Showcase ace-retro creation, listing, show, and health checks
+tags:
+- ace-retro
+- docs
+- getting-started
+settings:
+  font_size: 16
+  width: 960
+  height: 540
+  format: gif
+scenes:
+- name: Create a retro and capture its ID
+  commands:
+  - type: RETRO_ID=$(ace-retro create "Sprint Review" --type standard --tags sprint,team | ruby -ne 'if $_ =~ /\b([a-z0-9]{6})-[a-z0-9-]+\.retro\.md\b/; puts $1; break; end') && echo "Created ${RETRO_ID}"
+    sleep: 4s
+- name: List active retros with tags
+  commands:
+  - type: ace-retro list
+    sleep: 6s
+- name: Show a retro with full content (learnings, action items)
+  commands:
+  - type: ace-retro show "$RETRO_ID"
+    sleep: 8s
+- name: Run health checks across all retros
+  commands:
+  - type: ace-retro doctor
+    sleep: 5s
+teardown:
+- cleanup
+setup:
+- sandbox
+- copy-fixtures

data/docs/demo/fixtures/README.md

@@ -0,0 +1,3 @@
+# Demo fixtures for ace-retro
+
+Seed data used by YAML demo setup.

data/docs/demo/fixtures/sample.txt

@@ -0,0 +1 @@
+sample fixture content

data/docs/getting-started.md

@@ -0,0 +1,77 @@
+---
+doc-type: user
+purpose: Quickstart guide for creating, reviewing, and archiving retros with ace-retro.
+ace-docs:
+  last-updated: '2026-03-22'
+---
+
+# Getting Started with ace-retro
+
+Create your first retrospective, connect it to task work, and keep your workspace tidy with archive moves.
+
+## Prerequisites
+
+- Ruby installed
+- `gem install ace-retro`
+
+## Installation
+
+```bash
+gem install ace-retro
+```
+
+## 1) Create your first retrospective
+
+```bash
+ace-retro create "Sprint Review" --type standard --tags sprint,team
+```
+
+Create other retro types when needed:
+
+```bash
+ace-retro create "Session Review" --type conversation-analysis
+ace-retro create "Weekly Self Review" --type self-review
+```
+
+## 2) View and list retros
+
+Every retro gets a short ID (last 3 characters of a timestamp-based identifier). Use the ID printed by `create` (e.g. `q7w`) to inspect a specific retro:
+
+```bash
+ace-retro show q7w          # replace q7w with the ID from step 1
+ace-retro list
+ace-retro list --in all
+```
+
+Use filters to focus your review queue:
+
+```bash
+ace-retro list --status active
+ace-retro list --type standard
+ace-retro list --tags sprint,team
+```
+
+## 3) Archive completed retros
+
+```bash
+ace-retro update q7w --set status=done --move-to archive   # replace q7w with your retro ID
+```
+
+Archive moves keep active retros in your main workspace while preserving historical records.
+
+## Common Commands
+
+| Command | What it does |
+|---------|-------------|
+| `ace-retro create "..." --type standard` | Create a new retrospective |
+| `ace-retro show <ref>` | Display one retro by ID or shortcut |
+| `ace-retro list --in all` | List active and archived retros |
+| `ace-retro update <ref> --set status=done` | Update retro metadata |
+| `ace-retro update <ref> --move-to archive` | Move retro to archive |
+| `ace-retro doctor` | Run retro health checks |
+
+## What to try next
+
+- Explore additional commands in [Usage Guide](usage.md)
+- Browse workflows and skills in [Handbook Reference](handbook.md)
+- Use runtime help: `ace-retro --help` and `ace-retro <command> --help`

data/docs/handbook.md

@@ -0,0 +1,60 @@
+---
+doc-type: user
+purpose: Handbook index for ace-retro skills, workflows, and templates.
+ace-docs:
+  last-updated: '2026-03-22'
+---
+
+# ace-retro Handbook Reference
+
+Complete catalog of skills, workflows, and templates shipped with `ace-retro`.
+
+The `handbook/` directory contains canonical skill definitions and workflow instructions used by provider integrations and assignment-driven execution.
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| `as-retro-create` | Capture a retrospective and move the idea file into the retro workspace |
+| `as-retro-synthesize` | Synthesize multiple retrospectives into recurring patterns and recommendations |
+| `as-handbook-selfimprove` | Analyze agent mistakes, update process guidance, and fix the immediate issue |
+
+## Workflow Instructions
+
+Load any workflow with `ace-bundle wfi://<namespace>/<action>`.
+
+| Protocol Path | Description | Invoked by |
+|--------------|-------------|------------|
+| `wfi://retro/create` | Create a retrospective artifact from a task or idea context | `as-retro-create` |
+| `wfi://retro/synthesize` | Aggregate retros into structured learnings | `as-retro-synthesize` |
+| `wfi://retro/selfimprove` | Guided self-improvement flow for agent quality issues | `as-handbook-selfimprove` |
+
+## Templates
+
+| Template Path | Protocol | Purpose |
+|---------------|----------|---------|
+| `handbook/templates/retro/retro.template.md` | `tmpl://retro/retro` | Base markdown structure for a retrospective entry |
+
+## Source Layout
+
+```text
+handbook/
+  skills/
+    as-retro-create/SKILL.md
+    as-retro-synthesize/SKILL.md
+    as-handbook-selfimprove/SKILL.md
+  workflow-instructions/retro/
+    create.wf.md
+    synthesize.wf.md
+    selfimprove.wf.md
+  templates/retro/
+    retro.template.md
+```
+
+## Runtime Discovery
+
+```bash
+ace-bundle wfi://retro/create
+ace-bundle wfi://retro/synthesize
+ace-bundle wfi://retro/selfimprove
+```