ace-handbook 0.23.5 → 0.25.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ac7df9cd7a6a223a639a7cbc54f3669b81d33ce2e2a84ab6958117b7bf79041
-  data.tar.gz: 51256569bc2f4a4121a1aba33778e701e81a48e750c6887b2467e5bf21408dc2
+  metadata.gz: b30341cfc562a2ce2a4d1a41f4a8d2034e3b06d326493caf011b3bd14fbd04ba
+  data.tar.gz: 688554595c528ec149573e821bb9f9241b789ca220e3ab619c8948b0bbe1ad4d
 SHA512:
-  metadata.gz: a89bfa62563268247139b31d05fbc48fc508b0af6e18f249c82f9b3f5f8cf2486128bb013f711f718610fc4dd68d8ae8d0883ce9a417a2b299c55be8a5c7de15
-  data.tar.gz: 8879cb6414ae62d3648ac27cb91f2500e23799cf163a529bdb32b595b633c1791556cf883b5731769bc3a67e7e2aa4680412efc2aa9bb82edc7e7d26e531bd7f
+  metadata.gz: 44053a25c753be9c3c62353e5b1bdda32bb98eeba4b839fe8167021b8d11a17f03db0af7c36983125559eb37d9ed361d314140bb30b5b76661e5161b6fda1f52
+  data.tar.gz: f02655c8eeac3a7306ee1f4bb59474ce8e4551164c85c81e28b99d294cb441468111ada7098fb9c73644ddd4e6aa5d1219cd1678ff7192c21660aa0930a57545

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

@@ -0,0 +1,13 @@
+---
+# Cookbook Sources Protocol Configuration for ace-handbook gem
+# This enables cookbook discovery from handbook-owned cookbook assets
+
+name: ace-handbook
+type: gem
+description: Cookbooks from ace-handbook gem
+priority: 10
+
+config:
+  relative_path: handbook/cookbooks
+  pattern: "*.cookbook.md"
+  enabled: true

data/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.25.3] - 2026-04-05
+
+### Fixed
+- Scoped canonical skill inventory discovery to in-project defaults and explicitly registered external sources so status and sync no longer pick up ambient installed gems.
+
+## [0.25.2] - 2026-04-01
+
+### Changed
+- Updated cookbook management/review workflows to embed canonical cookbook standards and storage-path guidance directly, keeping the workflows self-contained.
+- Clarified cookbook path standards by explicitly distinguishing package-owned cookbooks (`ace-handbook/handbook/cookbooks/`) from project-local overlays (`.ace-handbook/cookbooks/`) in workflow/docs references.
+
+## [0.25.1] - 2026-04-01
+
+### Fixed
+- Corrected Astro cookbook setup commands to reference supported `ace-handbook` CLI behavior (`sync` / `status` flow), removing obsolete `ace-handbook init` guidance.
+
+### Changed
+- Added `.ace-handbook/cookbooks` to usage docs and standardized cookbook-review skill `argument-hint` metadata formatting.
+
+## [0.25.0] - 2026-04-01
+
+### Added
+- Added cookbook-first handbook surface with `wfi://handbook/manage-cookbooks` and `wfi://handbook/review-cookbooks` workflows plus canonical cookbook skills (`as-handbook-manage-cookbooks`, `as-handbook-review-cookbooks`) and provider projections.
+- Added canonical handbook-owned cookbook examples for Astro project setup and multi-ruby-gem monorepo setup, including explicit provenance and downstream propagation guidance.
+
+### Changed
+- Updated README, handbook/usage references, and cookbook template standards to treat `.cookbook.md` as a first-class handbook asset with explicit provenance and concise propagation guidance.
+
 ## [0.23.5] - 2026-03-31
 
 ### Changed

data/README.md

@@ -1,7 +1,7 @@
 <div align="center">
   <h1> ACE - Handbook </h1>
 
-  Standardized workflows for creating and managing guides, workflow instructions, and agent definitions.
+  Standardized workflows for creating and managing guides, cookbooks, workflow instructions, and agent definitions.
 
   <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
   <br><br>
@@ -18,7 +18,7 @@
 
 ![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`).
+`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`), cookbooks (`.cookbook.md`), workflow instructions (`.wf.md`), and agent definitions (`.ag.md`).
 
 ## How It Works
 
@@ -28,9 +28,9 @@
 
 ## 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.
+**Author handbook assets with consistent structure** - use `/as-handbook-manage-guides`, `/as-handbook-manage-cookbooks`, `/as-handbook-manage-workflows`, and `/as-handbook-manage-agents` to create and update guides, cookbooks, 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.
+**Review handbook content before publishing** - run `/as-handbook-review-guides`, `/as-handbook-review-cookbooks`, 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.
 
@@ -38,7 +38,7 @@
 
 **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.
 
-**Extend handbook content in normal projects** - put project-specific workflows, guides, templates, and skills under `.ace-handbook/` and discover them with protocol URLs (`wfi://`, `guide://`, `tmpl://`, `skill://`). See [Usage Guide](docs/usage.md) for path conventions.
+**Extend handbook content in normal projects** - put project-specific workflows, guides, cookbooks, templates, and skills under `.ace-handbook/` and discover them with protocol URLs (`wfi://`, `guide://`, `cookbook://`, `tmpl://`, `skill://`). See [Usage Guide](docs/usage.md) for path conventions.
 
 ---
 [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/cookbooks/setup-starting-a-multi-ruby-gem-monorepo-with-ace.cookbook.md

@@ -0,0 +1,151 @@
+# Setup Cookbook: Starting a Multi Ruby Gem Monorepo with ACE
+
+**Created**: 2026-04-01
+**Last Updated**: 2026-04-01
+**Category**: setup
+**Audience**: intermediate
+**Estimated Time**: 2-4 hours
+
+## Purpose
+
+Start a new Ruby multi-package monorepo using ACE patterns for package structure, shared defaults, handbook integration, and monorepo-level verification.
+
+## Overview
+
+This cookbook distills monorepo setup patterns from ACE package conventions and cross-cutting E2E quickstart verification work, then turns them into a reusable sequence for new repositories.
+
+## Source Provenance
+
+- Source workflows/guides/docs:
+  - `docs/ace-gems.g.md`
+  - `ace-monorepo-e2e/README.md`
+  - `.ace-retros/8quwjc-monorepo-e2e-quickstart-verification/8quwjc-monorepo-e2e-quickstart-verification.retro.md`
+- Validation evidence (commands, reports, or artifacts):
+  - `ace-test-e2e ace-monorepo-e2e --test-id TS-MONO-001`
+  - `ace-test-e2e ace-monorepo-e2e --test-id TS-MONO-002`
+  - `ace-nav resolve cookbook://setup-starting-a-multi-ruby-gem-monorepo-with-ace`
+- Last source verification date: 2026-04-01
+
+## Propagation Notes
+
+- Documentation updates to apply:
+  - Add one monorepo quickstart page that covers prerequisites, workspace bootstrap, and E2E smoke checks.
+  - Add a short troubleshooting section for permission and timeout pitfalls during E2E runs.
+- Agent guidance updates to apply:
+  - Add concise rules only: "use `ace-test` (not bundle exec)", "run `ace-config init` + `ace-handbook sync` before nav/bundle checks", and "scope E2E scenarios to monorepo-level concerns".
+- Summary-only propagation target notes (do not copy full cookbook body):
+  - `README.md`
+  - `docs/quick-start.md`
+  - `AGENTS.md`
+
+## Steps
+
+### Step 1: Scaffold monorepo package layout
+
+**Objective**: Establish consistent gem/package boundaries and shared conventions.
+
+**Commands/Actions:**
+
+1. Create packages with `ace-*`, `ace-support-*`, and integration naming patterns from `docs/ace-gems.g.md`.
+2. Include required defaults and handbook directories in each owned package.
+3. Use root-level dependency management for the repository.
+
+**Validation:**
+
+```bash
+rg --files | rg "\.ace-defaults/.*/config\.yml"
+rg --files | rg "handbook/"
+```
+
+### Step 2: Initialize local ACE configuration for repository tooling
+
+**Objective**: Ensure discovery and bundle protocols work in a fresh workspace.
+
+**Commands/Actions:**
+
+```bash
+ace-config init
+ace-handbook sync
+```
+
+**Validation:**
+
+```bash
+ace-nav list 'wfi://*'
+ace-bundle project
+```
+
+### Step 3: Add monorepo-level E2E scenario container
+
+**Objective**: Keep cross-package verification separate from any single gem package.
+
+**Commands/Actions:**
+
+1. Create `ace-monorepo-e2e/test/e2e/TS-*/scenario.yml` entries for repository-wide behaviors.
+2. Use one scenario for install verification and one for quickstart/docs validation.
+3. Keep per-package scenarios in their package folders; keep only cross-cutting cases here.
+
+**Validation:**
+
+```bash
+ace-test-e2e ace-monorepo-e2e
+```
+
+### Step 4: Verify quickstart and install paths under realistic conditions
+
+**Objective**: Confirm documented setup paths work in clean environments.
+
+**Commands/Actions:**
+
+```bash
+ace-test-e2e ace-monorepo-e2e --test-id TS-MONO-001
+ace-test-e2e ace-monorepo-e2e --test-id TS-MONO-002
+```
+
+If runs are network-heavy, raise timeout budgets deliberately and record the reason in scenario docs.
+
+**Validation:**
+
+```bash
+ace-test-e2e-suite --tags quickstart
+```
+
+### Step 5: Document guardrails learned from verification
+
+**Objective**: Prevent repeated setup failures for new contributors.
+
+**Commands/Actions:**
+
+Document these defaults in repo docs and concise agent guidance:
+
+- Use provider modes that include required permission handling for agent-run E2E.
+- Do not classify operational release steps as E2E scenarios; keep E2E focused on verification behavior.
+- Keep scenario scope tight; avoid adding unrelated package-specific tests without explicit need.
+
+**Validation:**
+
+```bash
+rg -n "ace-config init|ace-handbook sync|ace-test-e2e" README.md docs AGENTS.md
+```
+
+## Validation & Testing
+
+### Final Validation Steps
+
+1. Verify cookbook resolves through protocol:
+
+   ```bash
+   ace-nav resolve cookbook://setup-starting-a-multi-ruby-gem-monorepo-with-ace
+   ```
+
+2. Verify monorepo scenarios are runnable:
+
+   ```bash
+   ace-test-e2e ace-monorepo-e2e
+   ```
+
+### Success Criteria
+
+- [x] Monorepo setup sequence is reusable and action-first.
+- [x] Provenance references real project artifacts and verification evidence.
+- [x] Propagation guidance is concise and summary-only.

data/handbook/cookbooks/setup-starting-an-astro-project-with-ace.cookbook.md

@@ -0,0 +1,180 @@
+# Setup Cookbook: Starting an Astro Project with ACE
+
+**Created**: 2026-04-01
+**Last Updated**: 2026-04-01
+**Category**: setup
+**Audience**: intermediate
+**Estimated Time**: 45-90 minutes
+
+## Purpose
+
+Bootstrap a new Astro project with ACE workflow tooling and assignment sequencing that avoids common rework and deployment blockers.
+
+## Overview
+
+This cookbook captures the proven ordering and operating pattern from a completed Astro + Tailwind + Firebase project, then reframes it as reusable setup guidance.
+
+## Source Provenance
+
+- Source workflows/guides/docs:
+  - `.ace-tasks/8qs.t.x2b-migrate-cookbook-ownership-to-ace/2-seed-handbook-with-canonical-cookbook/astro-project-with-ace.input.md`
+  - `wfi://assign/create`
+  - `wfi://assign/drive`
+- Validation evidence (commands, reports, or artifacts):
+  - `ace-bundle wfi://assign/create`
+  - `ace-bundle wfi://assign/drive`
+  - `ace-nav resolve cookbook://setup-starting-an-astro-project-with-ace`
+- Last source verification date: 2026-04-01
+
+## Propagation Notes
+
+- Documentation updates to apply:
+  - Add a short project quickstart section for Astro prerequisites and deployment caveats.
+  - Add a mobile-browser gotchas section only if those issues were observed in that project.
+- Agent guidance updates to apply:
+  - Add concise rules only: "design tokens first", "mark interactive cloud auth tasks manual", "run 2 review cycles for static-site MVP work".
+- Summary-only propagation target notes (do not copy full cookbook body):
+  - `README.md`
+  - `CLAUDE.md`
+  - `AGENTS.md`
+
+## Steps
+
+### Step 1: Initialize Astro and styling baseline
+
+**Objective**: Create a clean Astro project with Tailwind wired into the build.
+
+**Commands/Actions:**
+
+```bash
+npm create astro@latest -- --template minimal
+npm install tailwindcss @tailwindcss/vite
+```
+
+Update `astro.config.mjs` and global styles:
+
+```js
+import { defineConfig } from 'astro/config';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  vite: { plugins: [tailwindcss()] }
+});
+```
+
+```css
+@import "tailwindcss";
+```
+
+**Validation:**
+
+```bash
+npm run build
+```
+
+### Step 2: Initialize ACE and project guidance
+
+**Objective**: Add handbook-aware workflow scaffolding before task execution.
+
+**Commands/Actions:**
+
+```bash
+ace-handbook sync
+ace-nav list 'wfi://handbook/*'
+```
+
+Create concise project-specific rules in `CLAUDE.md` and `AGENTS.md` for commit scope, design system references, and immutable project facts.
+
+**Validation:**
+
+```bash
+ace-bundle project
+```
+
+### Step 3: Plan task sequence with design tokens first
+
+**Objective**: Prevent styling drift and reduce component rework.
+
+**Commands/Actions:**
+
+1. Create the design-token task first.
+2. Add component/layout tasks after token decisions are fixed.
+3. Mark interactive authentication steps as manual and outside fork execution.
+
+Recommended sequence:
+
+1. Design tokens and global styles
+2. Header/navigation
+3. Hero section
+4. Content sections
+5. Contact/CTA
+6. Footer and floating CTA
+7. Image processing
+8. Hosting/deploy (manual)
+
+**Validation:**
+
+```bash
+ace-task list --status pending
+```
+
+### Step 4: Create and drive assignment
+
+**Objective**: Execute planned work with stable review depth and clear boundaries.
+
+**Commands/Actions:**
+
+```bash
+ace-assign create work-on-task --taskrefs <task-refs>
+ace-assign drive
+```
+
+Execution recommendations for Astro/static-site initial builds:
+
+- Use 2 review cycles (`valid`, `fit`), skip `shine`.
+- Run sequential fork execution unless sections are truly independent.
+- Keep deployment/auth tasks manual.
+
+**Validation:**
+
+```bash
+ace-assign status
+```
+
+### Step 5: Run post-build polish and release checks
+
+**Objective**: Catch real browser/device issues before release.
+
+**Commands/Actions:**
+
+- Verify mobile behavior, especially iOS Safari menu/scroll handling.
+- Verify social preview metadata and non-WebP OG image output.
+
+**Validation:**
+
+```bash
+npm run build
+```
+
+## Validation & Testing
+
+### Final Validation Steps
+
+1. Verify cookbook resolves through protocol:
+
+   ```bash
+   ace-nav resolve cookbook://setup-starting-an-astro-project-with-ace
+   ```
+
+2. Verify assignment workflows load:
+
+   ```bash
+   ace-bundle wfi://assign/create
+   ace-bundle wfi://assign/drive
+   ```
+
+### Success Criteria
+
+- [x] Setup flow is action-first and reusable.
+- [x] Provenance is explicit and traceable to real work artifacts.
+- [x] Propagation guidance is concise and summary-only.

data/handbook/skills/as-handbook-manage-cookbooks/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: as-handbook-manage-cookbooks
+description: Create, update, and maintain cookbook assets and standards
+# bundle: wfi://handbook/manage-cookbooks
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-handbook:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Write
+  - Edit
+  - MultiEdit
+  - Glob
+  - LS
+  - TodoWrite
+argument-hint: "[cookbook-name] [action: create|update|review]"
+last_modified: 2026-04-01
+source: ace-handbook
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+  providers: {}
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://handbook/manage-cookbooks
+---
+
+Load and run `ace-bundle wfi://handbook/manage-cookbooks` 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-handbook-review-cookbooks/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: as-handbook-review-cookbooks
+description: Review and validate cookbook assets for quality and consistency
+# bundle: wfi://handbook/review-cookbooks
+# context: no-fork
+# agent: general-purpose
+user-invocable: true
+allowed-tools:
+  - Bash(ace-handbook:*)
+  - Bash(ace-bundle:*)
+  - Read
+  - Glob
+  - LS
+  - TodoWrite
+argument-hint: "[cookbook-name]"
+last_modified: 2026-04-01
+source: ace-handbook
+integration:
+  targets:
+    - claude
+    - codex
+    - gemini
+    - opencode
+    - pi
+  providers: {}
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://handbook/review-cookbooks
+---
+
+Load and run `ace-bundle wfi://handbook/review-cookbooks` 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/cookbooks/cookbook.template.md

@@ -1,19 +1,19 @@
 ---
 doc-type: template
-title: "[Category] Cookbook: [Descriptive Name]"
+title: "{Category} Cookbook: {Descriptive Name}"
 purpose: Documentation for ace-handbook/handbook/templates/cookbooks/cookbook.template.md
 ace-docs:
   last-updated: 2026-01-08
   last-checked: 2026-03-21
 ---
 
-# [Category] Cookbook: [Descriptive Name]
+# {Category} Cookbook: {Descriptive Name}
 
 **Created**: YYYY-MM-DD
 **Last Updated**: YYYY-MM-DD
-**Category**: [integration | setup | migration | debugging | automation | pattern]
-**Audience**: [beginner | intermediate | advanced]
-**Estimated Time**: [X hours/minutes]
+**Category**: {integration | setup | migration | debugging | automation | pattern}
+**Audience**: {beginner | intermediate | advanced}
+**Estimated Time**: {X hours/minutes}
 
 ## Purpose
 
@@ -40,9 +40,25 @@ Brief description of what this cookbook accomplishes and why it's valuable.
 
 High-level summary of the approach and main steps involved.
 
+## Source Provenance
+
+Document the backward-derived sources used to build this cookbook.
+
+- Source workflows/guides/docs:
+- Validation evidence (commands, reports, or artifacts):
+- Last source verification date:
+
+## Propagation Notes
+
+Capture concise downstream updates required after applying this cookbook.
+
+- Documentation updates to apply:
+- Agent guidance updates to apply:
+- Summary-only propagation target notes (do not copy full cookbook body):
+
 ## Steps
 
-### Step 1: [Step Title]
+### Step 1: {Step Title}
 
 **Objective**: What this step accomplishes
 
@@ -71,7 +87,7 @@ verification-command
 - Common issue 1: Solution
 - Common issue 2: Solution
 
-### Step 2: [Step Title]
+### Step 2: {Step Title}
 
 **Objective**: What this step accomplishes
 
@@ -127,7 +143,7 @@ Expected results
 
 ## Examples
 
-### Example 1: [Scenario Name]
+### Example 1: {Scenario Name}
 
 **Context**: Specific use case or scenario
 
@@ -139,7 +155,7 @@ Expected results
 
 **Result**: What the outcome looks like
 
-### Example 2: [Another Scenario]
+### Example 2: {Another Scenario}
 
 **Context**: Different use case
 
@@ -175,13 +191,13 @@ end
 
 ## Common Patterns
 
-### Pattern 1: [Pattern Name]
+### Pattern 1: {Pattern Name}
 
 **When to use**: Specific conditions or scenarios
 **How to implement**: Brief implementation guide
 **Example**: Quick code or command example
 
-### Pattern 2: [Another Pattern]
+### Pattern 2: {Another Pattern}
 
 **When to use**: Different scenario
 **How to implement**: Implementation approach
@@ -189,14 +205,14 @@ end
 
 ## Troubleshooting
 
-### Error: [Common Error Message]
+### Error: {Common Error Message}
 
 **Symptoms**: How this error manifests
 **Cause**: Root cause of the issue
 **Solution**: Step-by-step fix
 **Prevention**: How to avoid in the future
 
-### Issue: [Common Problem]
+### Issue: {Common Problem}
 
 **Symptoms**: Observable behavior
 **Diagnosis**: How to confirm this is the issue

data/handbook/workflow-instructions/handbook/manage-cookbooks.wf.md

@@ -0,0 +1,117 @@
+---
+doc-type: workflow
+name: manage-cookbooks
+title: Manage Cookbooks
+description: Create and maintain handbook cookbook standards and assets
+purpose: Documentation for ace-handbook/handbook/workflow-instructions/handbook/manage-cookbooks.wf.md
+allowed-tools:
+  - Bash(ace-bundle:*)
+  - Bash(ace-handbook:*)
+  - Read
+  - Write
+ace-docs:
+  last-updated: 2026-04-01
+  last-checked: 2026-04-01
+---
+
+# Manage Cookbooks
+
+## Goal
+
+Create, update, and maintain cookbook assets as a handbook-owned capability. This workflow defines the canonical
+`.cookbook.md` model, provenance expectations, and downstream propagation requirements for project maintainers and agents.
+
+## Prerequisites
+
+- Understanding of handbook asset conventions
+- Clear source material for backward-derived cookbook guidance
+
+## Embedded Canonical Context
+
+### Canonical cookbook format
+
+Cookbooks must use `.cookbook.md` filenames and follow this required structure:
+
+```markdown
+# {Category} Cookbook: {Cookbook Name}
+
+## Purpose
+
+Brief description of what this cookbook accomplishes.
+
+## Source Provenance
+
+- Source workflows/guides/docs:
+- Validation evidence:
+
+## Steps
+
+### Step 1: {Step Title}
+
+    # command
+
+## Propagation Notes
+
+- Documentation updates to apply:
+- Agent guidance updates to apply:
+```
+
+### Canonical storage paths
+
+- Package-owned cookbooks (inside `ace-handbook`): `ace-handbook/handbook/cookbooks/`
+- Project-local cookbooks (outside package scope): `.ace-handbook/cookbooks/`
+
+## Process Steps
+
+1. **Define cookbook scope and audience:**
+   - Confirm cookbook category and intended audience.
+   - Ensure the cookbook solves a practical implementation problem.
+2. **Collect source evidence before authoring:**
+   - Gather primary source inputs (existing workflows, implementation docs, validated command behavior).
+   - Record where each instruction originated.
+3. **Author or update cookbook in canonical format:**
+   - Use `.cookbook.md` extension.
+   - Keep content action-oriented and operational.
+   - Store package-owned cookbooks under `ace-handbook/handbook/cookbooks/`.
+   - Store project-local cookbooks under `.ace-handbook/cookbooks/`.
+4. **Encode provenance and validation source:**
+   - Add explicit provenance and validation references in the cookbook content.
+   - Ensure each major section can be traced back to source material.
+5. **Add concise propagation guidance:**
+   - Include short downstream guidance for how cookbook outcomes should be reflected in docs and agent guidance.
+   - Do not duplicate full cookbook bodies into `CLAUDE.md` or `AGENTS.md`.
+6. **Cross-check handbook ownership boundaries:**
+   - Confirm cookbook instructions refer to handbook workflows/skills, not `ace-docs` ownership.
+   - Keep cookbook standards in `ace-handbook` surfaces.
+7. **Validate discovery readiness:**
+   - Confirm naming is protocol-friendly and resolves via `cookbook://`.
+   - Validate references and internal links.
+   - Verify the cookbook resides in the correct path:
+     - package-owned under `ace-handbook/handbook/cookbooks/`
+     - project-local under `.ace-handbook/cookbooks/`
+8. **Finalize and synchronize integrations:**
+   - Run `ace-handbook sync` when canonical handbook skills changed.
+   - Update usage docs if command examples changed.
+
+## Success Criteria
+
+- Cookbook guidance is defined as a handbook-owned asset model.
+- `.cookbook.md` remains the canonical format.
+- Provenance, validation source, and propagation guidance are explicit.
+- Content is discoverable through handbook cookbook protocol surfaces.
+- Documentation and workflow references remain aligned.
+
+## Validation Commands
+
+```bash
+ace-bundle wfi://handbook/manage-cookbooks
+ace-bundle wfi://handbook/review-cookbooks
+ace-nav list 'cookbook://*'
+ace-handbook sync
+```
+
+## Error Handling
+
+- **Missing provenance source:** stop authoring and collect source artifacts before finalizing.
+- **Ownership drift (`ace-docs` references):** rewrite guidance to point to handbook-owned workflows/skills.
+- **Discovery mismatch:** verify cookbook protocol registration and file naming/paths.

data/handbook/workflow-instructions/handbook/review-cookbooks.wf.md

@@ -0,0 +1,91 @@
+---
+doc-type: workflow
+name: review-cookbooks
+title: Review Cookbooks
+description: Review and validate cookbook assets and standards
+purpose: Documentation for ace-handbook/handbook/workflow-instructions/handbook/review-cookbooks.wf.md
+allowed-tools:
+  - Bash(ace-bundle:*)
+  - Bash(ace-handbook:*)
+  - Read
+ace-docs:
+  last-updated: 2026-04-01
+  last-checked: 2026-04-01
+---
+
+# Review Cookbooks
+
+## Goal
+
+Review cookbook assets for standards compliance, provenance quality, discovery compatibility, and concise downstream
+propagation guidance.
+
+## Prerequisites
+
+- Access to cookbook files under review
+- Understanding of handbook workflow/skill ownership boundaries
+
+## Embedded Review Standards
+
+### Required canonical structure
+
+Each cookbook under review must:
+
+- use `.cookbook.md` file naming
+- include `## Source Provenance` with explicit source references
+- include `## Propagation Notes` with concise downstream updates
+- keep workflow ownership guidance aligned to `ace-handbook`
+
+### Canonical storage paths to validate
+
+- Package-owned cookbooks (inside `ace-handbook`): `ace-handbook/handbook/cookbooks/`
+- Project-local cookbooks (outside package scope): `.ace-handbook/cookbooks/`
+
+## Process Steps
+
+1. **Define review scope:**
+   - Review one cookbook, a category, or all cookbook files.
+2. **Validate canonical format:**
+   - File naming uses `.cookbook.md`.
+   - Structure remains consistent with cookbook standards.
+3. **Validate provenance and source traceability:**
+   - Cookbook includes backward-derived source material references.
+   - Validation source for key procedures is explicit.
+4. **Validate propagation guidance quality:**
+   - Downstream propagation instructions are concise and actionable.
+   - No instructions suggest copying full cookbook text into `CLAUDE.md` or `AGENTS.md`.
+5. **Validate ownership and workflow linkage:**
+   - Cookbook lifecycle references `ace-handbook` workflows/skills.
+   - No wording implies cookbook ownership lives in `ace-docs`.
+6. **Validate discovery and command contracts:**
+   - Ensure cookbook names/locations are resolvable through `cookbook://`.
+   - Confirm package-owned vs project-local path placement is correct.
+   - Verify workflow commands referenced in cookbook guidance load correctly.
+7. **Report findings with severity:**
+   - Critical: ownership/provenance/discovery breaks.
+   - Major: incomplete propagation or validation guidance.
+   - Minor: wording/formatting consistency issues.
+
+## Review Checklist
+
+- [ ] Uses `.cookbook.md` canonical format
+- [ ] Includes provenance references
+- [ ] Includes validation source references
+- [ ] Includes concise propagation guidance
+- [ ] Avoids ownership drift to `ace-docs`
+- [ ] Respects `cookbook://` discovery requirements
+
+## Validation Commands
+
+```bash
+ace-bundle wfi://handbook/manage-cookbooks
+ace-bundle wfi://handbook/review-cookbooks
+ace-nav list 'cookbook://*'
+ace-nav resolve cookbook://setup-starting-an-astro-project-with-ace
+```
+
+## Success Criteria
+
+- Cookbook reviews consistently enforce handbook cookbook standards.
+- Findings clearly classify blocking vs non-blocking issues.
+- Discovery and workflow command contracts are validated as part of review.

data/lib/ace/handbook/organisms/skill_inventory.rb

@@ -3,6 +3,7 @@
 require "date"
 require "yaml"
 require "ace/support/nav"
+require "pathname"
 
 module Ace
   module Handbook
@@ -17,21 +18,80 @@ module Ace
         end
 
         def all
-          scanner.find_resources("skill").filter_map do |resource|
-            parse_skill(resource.fetch(:path))
-          end
+          skill_paths.filter_map { |path| parse_skill(path) }
         end
 
         private
 
-        def scanner
-          source_registry = Ace::Support::Nav::Molecules::SourceRegistry.new(start_path: project_root)
-          config_loader = Ace::Support::Nav::Molecules::ConfigLoader.new(
-            File.join(project_root, ".ace", "nav"),
-            source_registry: source_registry
-          )
+        def skill_paths
+          index = {}
+
+          source_directories.each do |directory|
+            Dir.glob(File.join(directory, "**", "SKILL.md")).sort.each do |path|
+              frontmatter = parse_frontmatter(File.read(path))
+              name = frontmatter["name"]&.to_s
+              next if name.nil? || name.empty? || index.key?(name)
+
+              index[name] = path
+            rescue
+              next
+            end
+          end
+
+          index.values
+        end
+
+        def source_directories
+          registry = Ace::Support::Nav::Molecules::SourceRegistry.new(start_path: project_root)
+          registry.sources_for_protocol("skill").filter_map do |source|
+            next if source.config.is_a?(Hash) && source.config["enabled"] == false
+
+            directory = resolve_source_directory(source)
+            next unless File.directory?(directory)
+            next if external_implicit_source?(source, directory)
+
+            directory
+          rescue
+            nil
+          end.uniq
+        end
+
+        def resolve_source_directory(source)
+          candidate = source.full_path
+          return candidate if File.directory?(candidate)
+
+          relative_path = source.config&.dig("relative_path")&.to_s&.strip
+          return nil if relative_path.nil? || relative_path.empty?
+
+          return nil unless source.config_file&.include?("/.ace-defaults/")
+
+          package_root = source.config_file.split("/.ace-defaults/").first
+          fallback = File.expand_path(relative_path, package_root)
+          File.directory?(fallback) ? fallback : nil
+        end
+
+        def external_implicit_source?(source, directory)
+          return false if path_within_project?(directory)
+          return false if explicit_registration?(source)
+
+          true
+        end
+
+        def explicit_registration?(source)
+          %w[project user].include?(source.origin.to_s)
+        end
+
+        def path_within_project?(path)
+          candidate = Pathname.new(File.expand_path(path))
+          root = Pathname.new(File.expand_path(project_root))
+          candidate == root || candidate.to_s.start_with?("#{root}/")
+        end
+
+        def parse_frontmatter(content)
+          match = content.match(FRONTMATTER_PATTERN)
+          return {} unless match
 
-          Ace::Support::Nav::Molecules::ProtocolScanner.new(config_loader: config_loader)
+          YAML.safe_load(match[1], permitted_classes: [Date, Time], aliases: true) || {}
         end
 
         def parse_skill(path)

data/lib/ace/handbook/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Handbook
-  VERSION = '0.23.5'
+  VERSION = '0.25.3'
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-handbook
 version: !ruby/object:Gem::Version
-  version: 0.23.5
+  version: 0.25.3
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-04-01 00:00:00.000000000 Z
+date: 2026-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -117,6 +117,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".ace-defaults/handbook/config.yml"
+- ".ace-defaults/nav/protocols/cookbook-sources/ace-handbook.yml"
 - ".ace-defaults/nav/protocols/guide-sources/ace-handbook.yml"
 - ".ace-defaults/nav/protocols/skill-sources/ace-handbook.yml"
 - ".ace-defaults/nav/protocols/tmpl-sources/ace-handbook.yml"
@@ -126,6 +127,8 @@ files:
 - README.md
 - Rakefile
 - exe/ace-handbook
+- handbook/cookbooks/setup-starting-a-multi-ruby-gem-monorepo-with-ace.cookbook.md
+- handbook/cookbooks/setup-starting-an-astro-project-with-ace.cookbook.md
 - handbook/guides/ai-agent-integration.g.md
 - handbook/guides/atom-pattern.g.md
 - handbook/guides/changelog.g.md
@@ -163,10 +166,12 @@ files:
 - handbook/guides/workflow-context-embedding.g.md
 - handbook/skills/as-handbook-init-project/SKILL.md
 - handbook/skills/as-handbook-manage-agents/SKILL.md
+- handbook/skills/as-handbook-manage-cookbooks/SKILL.md
 - handbook/skills/as-handbook-manage-guides/SKILL.md
 - handbook/skills/as-handbook-manage-workflows/SKILL.md
 - handbook/skills/as-handbook-parallel-research/SKILL.md
 - handbook/skills/as-handbook-perform-delivery/SKILL.md
+- handbook/skills/as-handbook-review-cookbooks/SKILL.md
 - handbook/skills/as-handbook-review-guides/SKILL.md
 - handbook/skills/as-handbook-review-workflows/SKILL.md
 - handbook/skills/as-handbook-synthesize-research/SKILL.md
@@ -180,11 +185,13 @@ files:
 - handbook/templates/research-comparison.template.md
 - handbook/workflow-instructions/handbook/init-project.wf.md
 - handbook/workflow-instructions/handbook/manage-agents.wf.md
+- handbook/workflow-instructions/handbook/manage-cookbooks.wf.md
 - handbook/workflow-instructions/handbook/manage-guides.wf.md
 - handbook/workflow-instructions/handbook/manage-workflows.wf.md
 - handbook/workflow-instructions/handbook/parallel-research.wf.md
 - handbook/workflow-instructions/handbook/perform-delivery.wf.md
 - handbook/workflow-instructions/handbook/research.wf.md
+- handbook/workflow-instructions/handbook/review-cookbooks.wf.md
 - handbook/workflow-instructions/handbook/review-guides.wf.md
 - handbook/workflow-instructions/handbook/review-workflows.wf.md
 - handbook/workflow-instructions/handbook/synthesize-research.wf.md