ace-handbook 0.19.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b0d7a79a21b2d55e4fd1a583f2825f10eff4e163629b49520c7aa50096e6472c
+  data.tar.gz: 38696630f7cad28c282e6904195c397d808d667f6fe5c9543b31aaba3bf0d97c
+SHA512:
+  metadata.gz: a6f780c0d782d95b6d9799e12b5d9f5787328b953d02dcd77720961a428bded1004793cf91928d321494feb1eb6c1582d48ede4667514b5a456ad3e91a2e9cc6
+  data.tar.gz: 2137a2d0924441c6f462f5bfa682b809f429d93ad1585a71ebdd82a09b2e8df8c217508a08c81b9a65b226ce788f1d1c83819cf5e7e2b0ad330e00db1e6a8f9b

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

@@ -0,0 +1,4 @@
+sync:
+  providers:
+    enabled: []
+    disabled: []

data/.ace-defaults/nav/protocols/guide-sources/ace-handbook.yml

@@ -0,0 +1,19 @@
+---
+# Guide Sources Protocol Configuration for ace-handbook gem
+# This enables guide discovery from the installed ace-handbook gem
+
+name: ace-handbook
+type: gem
+description: Handbook guides from ace-handbook gem
+priority: 10
+
+# Configuration for guide discovery within the gem
+config:
+  # Relative path within the gem
+  relative_path: handbook/guides
+
+  # Pattern for finding guide files
+  pattern: "*.g.md"
+
+  # Enable discovery
+  enabled: true

data/.ace-defaults/nav/protocols/tmpl-sources/ace-handbook.yml

@@ -0,0 +1,10 @@
+---
+# Template Sources Protocol Configuration for ace-handbook gem
+name: ace-handbook
+type: gem
+description: Templates from ace-handbook gem
+priority: 10
+config:
+  relative_path: handbook/templates
+  pattern: "**/*.template.md"
+  enabled: true

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

@@ -0,0 +1,19 @@
+---
+# WFI Sources Protocol Configuration for ace-handbook gem
+# This enables workflow discovery from the installed ace-handbook gem
+
+name: ace-handbook
+type: gem
+description: Workflow instructions from ace-handbook 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/CHANGELOG.md

@@ -0,0 +1,362 @@
+# 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.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.19.0] - 2026-03-23
+
+### Added
+- New use case in README documenting `ace-handbook sync` and `ace-handbook status` CLI commands.
+- Added `as-release`, `as-release-bump-version`, `as-release-rubygems-publish`, and `as-release-update-changelog` to the handbook skills reference table.
+- Re-recorded getting-started demo GIF showcasing provider status and sync workflows.
+
+### Fixed
+- Fixed broken `[ace-nav](../ace-nav)` cross-link in README — corrected to `[ace-nav](../ace-support-nav)`.
+- Fixed incorrect `ace-integration-*` package reference in README — corrected to `ace-handbook-integration-*`.
+
+### Changed
+- Aligned gemspec description wording with summary for consistency.
+- Removed stale `mise` prerequisite from `docs/getting-started.md`.
+- Rewrote demo tape to focus on `ace-handbook status` and `ace-handbook sync --provider pi`.
+
+## [0.18.3] - 2026-03-23
+
+### Changed
+- Refreshed `README.md` to the current package layout pattern with quick-link navigation, use-case framing, and normalized section order.
+
+## [0.18.2] - 2026-03-22
+
+### Changed
+- Updated `docs/getting-started.md` to remove contradictory `mise exec --` prose and align onboarding guidance with direct `ace-*` command usage.
+- Documented intentional retirement of projected provider `as-idea-capture` and `as-idea-capture-features` skill files after canonical source removal.
+
+## [0.18.1] - 2026-03-22
+
+### Changed
+- Remove `mise exec --` wrapper from test fixture strings and canonical skill docs.
+- Document intentional retirement of projected provider `as-idea-capture` and `as-idea-capture-features` skill files after canonical source removal.
+
+## [0.18.0] - 2026-03-22
+
+### Changed
+- Reworked `ace-handbook` documentation into a landing-page README with package-focused messaging and links to dedicated docs.
+- Added `docs/getting-started.md`, `docs/usage.md`, and `docs/handbook.md` with tutorial and workflow/skill reference coverage.
+- Added demo assets under `docs/demo/` and aligned examples to the current `ace-nav resolve/list` command pattern.
+- Updated gem metadata summary/description to match the new README tagline and documentation positioning.
+
+## [0.17.1] - 2026-03-21
+
+### Added
+- Add RubyGems publish workflow (`wfi://release/rubygems-publish`) for publishing ACE gems in dependency order with credential verification, conflict detection, and dry-run support.
+- Add `as-release-rubygems-publish` skill for invoking the RubyGems publish workflow.
+
+## [0.17.0] - 2026-03-21
+
+### Changed
+- Added initial `TS-HANDBOOK-001` value-gated smoke E2E coverage for `ace-handbook` CLI help and status command contracts.
+
+## [0.16.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.16.0] - 2026-03-18
+
+### Changed
+- Removed legacy backward-compatibility behavior as part of the 0.10 cleanup release.
+
+
+## [0.15.9] - 2026-03-18
+
+### Fixed
+- Updated `cli-support-cli.g.md` guide to remove stale `DryCli::` namespace prefix from `VersionCommand` and `HelpCommand` class references.
+
+## [0.15.8] - 2026-03-17
+
+### Changed
+- Updated `cli-support-cli.g.md` examples to the current `ace-support-cli` API (`RegistryDsl`, `Runner`, and `coerce_types`).
+- Updated review workflow docs to reflect 15-minute timeout guidance for long PR review runs.
+
+## [0.15.7] - 2026-03-15
+
+### Changed
+- Migrated CLI framework from dry-cli to ace-support-cli
+
+## [0.15.6] - 2026-03-13
+
+### Changed
+- Updated handbook-owned canonical skills to explicitly run bundled workflows in the current project and execute them end-to-end.
+
+### Technical
+- Refreshed provider sync and status collector regression coverage for the new compact canonical skill execution template.
+
+## [0.15.5] - 2026-03-13
+
+### Changed
+- Removed provider-specific skill body rendering so projected provider skills once again apply frontmatter overrides while preserving the canonical skill body unchanged.
+- Updated the canonical `as-release` skill to use the unified arguments / variables / execution structure with explicit workflow-execution guidance.
+- Limited provider-specific forking for `as-release` to Claude frontmatter only.
+
+### Technical
+- Simplified handbook projection coverage to validate frontmatter override projection and canonical body preservation instead of provider-specific body rendering.
+
+## [0.15.4] - 2026-03-13
+
+### Changed
+- Strengthened projected workflow skill instructions for Codex delegated execution and forked provider contexts so generated provider skills explicitly load and execute workflows in the current project instead of only reading or summarizing them.
+
+### Technical
+- Added projection regression coverage for strong workflow-execution rendering in both Codex `context: ace-llm` mode and provider `context: fork` mode.
+
+## [0.15.3] - 2026-03-13
+
+### Changed
+- Render Codex `ace-llm` skills from canonical frontmatter by deriving uppercase variables from `argument-hint` and generating `## Variables` / `## Instructions` sections for projected Codex skills.
+
+### Technical
+- Added projection regression coverage for `context: ace-llm` rendering and argument-hint-derived Codex variable generation.
+
+## [0.15.2] - 2026-03-12
+
+### Fixed
+- Preserved conditional `--sandbox` workflow routing in provider-synced skill projections so generated Claude and Codex skills keep the canonical E2E execute path.
+
+### Technical
+- Added provider-sync regression coverage for conditional workflow bodies in projected skills.
+
+## [0.15.1] - 2026-03-12
+
+### Changed
+- Updated handbook README, workflow docs, and guidance to document bundle-first workflow usage and the current handbook structure.
+
+## [0.15.0] - 2026-03-12
+
+### Added
+- Added Codex-specific delegated execution metadata to the canonical `as-release-bump-version` and `as-release-update-changelog` skills so the generated Codex skills run in fork context on `gpt-5.3-codex-spark`.
+
+## [0.14.1] - 2026-03-12
+
+### Technical
+- Updated provider sync regression coverage to verify provider-specific `context` and `model` overrides on projected git-commit skills and to keep generated provider output free of canonical `integration` metadata.
+
+## [0.14.0] - 2026-03-12
+
+### Changed
+- Changed canonical handbook skill inventory to load from registered `skill://` sources via `ace-support-nav` instead of scanning monorepo package directories directly.
+
+### Technical
+- Added nav-backed inventory regression coverage and explicit skill-source registration fixtures for handbook sync/status tests.
+
+## [0.13.1] - 2026-03-12
+
+### Technical
+- Added regression coverage for the `.agent/skills` retirement so handbook sync/status changes are exercised against provider-native skill trees only.
+
+## [0.13.0] - 2026-03-12
+
+### Added
+- Added canonical skill inventory counts by `source` to `ace-handbook status` output and JSON responses.
+
+### Changed
+- Expanded provider status reporting to show expected, installed, in-sync, outdated, missing, and extra skill counts, including comparisons through symlinked provider directories.
+
+## [0.12.0] - 2026-03-10
+
+### Added
+- Added a public `ace-handbook` CLI with `sync` and `status` commands for projecting canonical package skills into provider-native folders.
+- Added provider manifest discovery and sync/status coverage for handbook integrations, including replacement of legacy provider skill symlinks with real provider directories.
+
+### Changed
+- Moved handbook integration execution to `ace-handbook` while provider packages now supply thin provider manifests for projection targets.
+
+## [0.11.0] - 2026-03-10
+
+### Added
+- Added canonical handbook-owned skills for handbook management, release workflows, and research/delivery orchestration.
+
+
+## [0.10.0] - 2026-03-08
+
+### Added
+- New `release/publish` workflow for coordinated multi-package releases that auto-detect modified packages, update package and root changelogs, and finish with one release commit.
+
+### Changed
+- `/as-release` now loads `wfi://release/publish`, and release documentation now points to the canonical workflow path.
+
+## [0.9.9] - 2026-03-04
+
+### Changed
+- Update `perform-delivery` workflow PR skill references from `/ace-git-create-pr` to `/ace-github-pr-create`
+
+## [0.9.8] - 2026-02-25
+
+### Changed
+- Update `perform-delivery` workflow task lookup guidance to use `ace-task show <ref>` for explicit task selection.
+
+## [0.9.7] - 2026-02-22
+
+### Technical
+- Update `ace-bundle project` → `ace-bundle load project` in update-docs workflow
+
+## [0.9.6] - 2026-02-22
+
+### Changed
+- Migrate skill naming and invocation references to hyphenated `ace-*` format (no underscores).
+
+## [0.9.5] - 2026-02-21
+
+### Added
+- "Redundant computation" root cause category in selfimprove workflow with fix template showing compute-once-pass-explicitly pattern
+
+## [0.9.4] - 2026-02-20
+
+### Technical
+- Update /ace:create-pr to /ace:git-create-pr in perform-delivery workflow
+
+## [0.9.3] - 2026-02-20
+
+### Technical
+- Update stale wfi:// references in workflow definition guide
+
+## [0.9.2] - 2026-02-19
+
+### Technical
+- Namespace workflow instructions into handbook/ subdirectory with updated wfi:// URIs
+- Update skill name references to use namespaced ace:handbook-action format
+
+## [0.9.1] - 2026-02-04
+
+### Added
+
+- Preference hierarchy for search targets in selfimprove workflow (workflows/guides preferred over skills)
+
+## [0.9.0] - 2026-02-03
+
+### Added
+- Self-improve workflow (`selfimprove.wf.md`) for transforming agent mistakes into system improvements
+
+## [0.8.0] - 2026-01-31
+
+### Added
+- Multi-agent research synthesis capabilities (Task 254):
+  - `multi-agent-research.g.md` guide explaining when/how to use parallel agents
+  - `research-comparison.template.md` for structured synthesis comparison
+  - `parallel-research.wf.md` workflow for setting up parallel agent research
+  - `synthesize-research.wf.md` workflow for combining agent outputs
+  - `research.wf.md` with single/multi-agent decision criteria
+- Template protocol source configuration for ace-handbook templates
+
+## [0.7.1] - 2026-01-29
+
+### Fixed
+- Refine exit code handling documentation for dry-cli framework with exception-based pattern
+
+## [0.7.0] - 2026-01-22
+
+### Added
+- New guides extracted from ace-gems.g.md for better discoverability:
+  - `prompt-caching.g.md` - PromptCacheManager patterns for LLM prompt generation
+  - `cli-dry-cli.g.md` - Complete dry-cli framework reference
+  - `mono-repo-patterns.g.md` - Mono-repo development patterns and binstubs
+- Document IO isolation and testing pyramid patterns
+
+### Technical
+- Lower Ruby version requirement to >= 3.2.0
+
+## [0.6.0] - 2026-01-18
+
+### Added
+- Add perform-delivery workflow for multi-step delivery tracking with automatic TodoWrite externalization
+
+### Technical
+- Update guides for bundle terminology
+
+## [0.5.2] - 2026-01-16
+
+### Changed
+- Rename context: to bundle: keys in configuration files
+
+## [0.5.1] - 2026-01-08
+
+### Fixed
+- Fixed `guide://` protocol links in ace-test-runner guides (added `.g` suffix for `.g.md` files)
+- Cross-gem guide:// links now properly resolve to resources with `.g` extension
+
+## [0.5.0] - 2026-01-08
+
+### Added
+- Migrated 10 generic guides from dev-handbook to handbook/guides/
+  - ai-agent-integration.g.md, atom-pattern.g.md, changelog.g.md
+  - coding-standards.g.md, debug-troubleshooting.g.md, error-handling.g.md
+  - performance.g.md, quality-assurance.g.md, strategic-planning.g.md
+- Migrated 5 meta-guides to handbook/guides/meta/
+  - agents-definition.g.md, guides-definition.g.md, markdown-definition.g.md
+  - tools-definition.g.md, workflow-instructions-definition.g.md
+- Guide subdirectories with language-specific content (ruby, rust, typescript)
+- initialize-project-structure.wf.md workflow for project setup
+- Templates: cookbooks/cookbook.template.md, completed-work-documentation.md
+- Template discovery protocol (.ace-defaults/nav/protocols/tmpl-sources/)
+
+### Changed
+- Consolidates dev-handbook content into ace-handbook gem
+- All development guides now distributed with gem installation
+
+## [0.4.0] - 2026-01-03
+
+### Added
+- Guides support with handbook/guides/ directory
+- workflow-context-embedding.g.md guide for embed_document_source pattern
+- Guide discovery protocol (.ace-defaults/nav/protocols/guide-sources/ace-handbook.yml)
+
+## [0.3.0] - 2026-01-03
+
+### Changed
+- **BREAKING**: Minimum Ruby version raised to 3.3.0 (was 3.1.0)
+- Standardized gemspec file patterns with deterministic Dir.glob
+- Added MIT LICENSE file
+
+## [0.2.0] - 2025-12-30
+
+### Changed
+
+* Rename `.ace.example/` to `.ace-defaults/` for gem defaults directory
+
+## [0.1.0] - 2025-11-05
+
+### Added
+- Initial release of ace-handbook gem as pure workflow package
+- 6 handbook management workflows accessible via wfi:// protocol:
+  - `wfi://manage-guides` - Create and update development guides
+  - `wfi://review-guides` - Review guides for quality and consistency
+  - `wfi://manage-workflow-instructions` - Create and validate workflow files
+  - `wfi://review-workflows` - Review workflow instructions
+  - `wfi://manage-agents` - Create and update agent definitions
+  - `wfi://update-handbook-docs` - Update handbook README and structure
+- Path references updated for project-relative usage
+- Complete gem structure following ACE patterns
+- Comprehensive documentation and usage examples
+- Auto-discovery support through ace-nav gem
+
+### Changed
+- Migrated workflows from dev-handbook/.meta/wfi/ to installable gem
+- Updated path references to be project-root relative
+- Removed dev-handbook specific dependencies
+
+### Removed
+- Moved `update-tools-docs.wf.md` to ace-docs package (tools documentation management)
+- Moved `update-integration-claude.wf.md` to ace-integration-claude package (Claude Code integration)
+
+### Fixed
+- Added ace-nav protocol registration (.ace.example/nav/protocols/wfi-sources/ace-handbook.yml)
+- Updated gemspec to include protocol registration files for proper discovery
+
+### Technical Details
+- Pure workflow package with no Ruby runtime dependencies
+- Auto-discovery via ace-nav through handbook/workflow-instructions/ directory
+- Protocol registration enables ace-nav to discover workflows from installed gem
+- Template embedding framework ready for ADR-002 compliance
+- Standard ACE gem structure with lib/, handbook/, gemspec, README, CHANGELOG

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 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,42 @@
+<div align="center">
+  <h1> ACE - Handbook </h1>
+
+  Standardized workflows for creating and managing guides, workflow instructions, and agent definitions.
+
+  <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-handbook"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-handbook.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-handbook demo](docs/demo/ace-handbook-getting-started.gif)
+
+`ace-handbook` gives ACE teams a shared way to author, review, and maintain handbook assets with consistent quality gates and repeatable delivery workflows. It covers guides (`.g.md`), workflow instructions (`.wf.md`), and agent definitions (`.ag.md`).
+
+## How It Works
+
+1. Author handbook assets using standardized templates and structure conventions for guides, workflows, and agents.
+2. Review content through quality-gate workflows that check clarity, formatting, and process compliance.
+3. Coordinate multi-step documentation changes through orchestration and research workflows.
+
+## Use Cases
+
+**Author handbook assets with consistent structure** - use `/as-handbook-manage-guides`, `/as-handbook-manage-workflows`, and `/as-handbook-manage-agents` to create and update guides, workflow instructions, and agent definitions with package workflows.
+
+**Review handbook content before publishing** - run `/as-handbook-review-guides` and `/as-handbook-review-workflows` to catch clarity, formatting, and process issues before updates propagate to integrations.
+
+**Coordinate larger handbook deliveries** - use `/as-handbook-update-docs` to plan, execute, and synthesize multi-step documentation changes across package handbook assets.
+
+**Integrate with resource discovery and context loading** - pair with [ace-nav](../ace-support-nav) for workflow and resource discovery, [ace-bundle](../ace-bundle) for loading complete workflow instructions, and provider integrations (`ace-handbook-integration-*`) that project canonical handbook skills into provider-native folders.
+
+**Sync and inspect provider integrations** - run `ace-handbook sync` to project canonical skills into provider-native folders and `ace-handbook status` to check integration health across all configured providers.
+
+---
+[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,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test" << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+task spec: :test
+task default: :test

data/exe/ace-handbook

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "ace/handbook/cli"
+
+Ace::Support::Cli::Runner.new(Ace::Handbook::CLI).call