ace-handbook 0.19.0

data/handbook/workflow-instructions/handbook/update-docs.wf.md

@@ -0,0 +1,338 @@
+---
+doc-type: workflow
+title: Update Handbook Documentation Workflow
+purpose: Documentation for ace-handbook/handbook/workflow-instructions/handbook/update-docs.wf.md
+ace-docs:
+  last-updated: 2026-03-12
+  last-checked: 2026-03-21
+---
+
+# Update Handbook Documentation Workflow
+
+## Goal
+
+Maintain accurate, comprehensive, and well-structured README documentation across ace-* packages
+to ensure all components are properly documented and discoverable.
+
+## Prerequisites
+
+* Understanding of handbook structure and component relationships
+* Access to ace-* package directories
+* Familiarity with handbook conventions and patterns
+* Knowledge of commands, guides, workflows, and provider-agent integrations
+
+## Project Context Loading
+
+### Load project context preset
+
+    ace-bundle project
+{: .language-bash}
+
+### Review target documentation files
+
+* README.md (main handbook documentation)
+* Provider integration READMEs when skills/projections are described
+* Related package READMEs under `ace-*/README.md`
+
+### Understand handbook standards
+
+* ace-handbook/handbook/guides/meta/guides-definition.g.md
+* ace-handbook/handbook/guides/meta/workflow-instructions-definition.g.md
+* ace-handbook/handbook/guides/meta/agents-definition.g.md
+
+## Process Steps
+
+### 1. Audit Current Documentation State
+
+**For each README file:**
+
+* Compare documented items against actual directory contents
+* Identify missing, outdated, or incorrect information
+* Check for broken links and invalid references
+* Note structural inconsistencies
+
+**Validation Commands:**
+
+    # Check for undocumented guides
+    for guide in guides/*.g.md; do
+      basename "$guide" | xargs -I {} grep -q {} README.md || echo "Missing: {}"
+    done
+    
+    # Check for undocumented workflows
+    for wf in workflow-instructions/*.wf.md; do
+      basename "$wf" | xargs -I {} grep -q {} README.md || echo "Missing workflow: {}"
+    done
+    
+    # Check for broken links
+    grep -o '\[.*\](.*.md)' README.md | grep -o '(.*\.md)' | tr -d '()' | while read link; do
+      [ -f "$link" ] || echo "Broken link: $link"
+    done
+{: .language-bash}
+
+### 2. Update Main Handbook README
+
+**Structure to maintain:**
+
+    # ACE Handbooks (ace-* packages)
+    
+    [Brief description and purpose]
+    
+    ## Quick Start
+    [Installation instructions]
+    
+    ## Structure
+    [Directory organization]
+    
+    ## Development Guides
+    ### [Category]
+    - [Guide links with descriptions]
+    
+    ## Workflow Instructions
+    [Key workflows listed]
+    
+    ## Templates
+    [Available templates]
+    
+    ## Integrations
+    [AI assistant integrations]
+    
+    ## Contributing
+    [How to contribute]
+{: .language-markdown}
+
+**Update Process:**
+
+* Scan `guides/` directory for all `.g.md` files
+* Group guides by category (Core Process, Technical Standards, Language-Specific, etc.)
+* Update guide links with consistent format: `[Guide Name](path) | [Related Guide](path)`
+* Include brief inline descriptions where helpful
+* Maintain alphabetical ordering within categories
+
+### 3. Update Meta Documentation README
+
+**Focus Areas:**
+
+* `/gds` - Guide Definition Standards listings
+* `/wfi` - Meta Workflow Instructions catalog
+* `/tpl` - Template inventory
+* Relationship diagrams showing how meta components interact
+* Quick reference table for finding the right meta resource
+
+**Structure Template:**
+
+    # Meta Documentation (`.meta`)
+    
+    [Purpose and overview]
+    
+    ## Structure
+    
+    ### `/gds` - Guide Definition Standards
+    [List all definition files with descriptions]
+    
+    ### `/wfi` - Meta Workflow Instructions
+    [Categorized workflow listings]
+    
+    ### `/tpl` - Templates
+    [Template inventory with use cases]
+    
+    ## Relationships
+    [ASCII diagram or structured explanation]
+    
+    ## Usage
+    [Common tasks and how to accomplish them]
+    
+    ## Quick Reference
+    [Table mapping needs to resources]
+{: .language-markdown}
+
+### 4. Update Integrations README
+
+**Key Sections to Maintain:**
+
+* Current integration status (Claude Code, others)
+* Directory structure with file counts
+* Agent catalog with descriptions and links
+* Command inventory (custom vs generated)
+* Installation instructions
+* Maintenance procedures
+* Relationship dependencies
+
+**Update Checklist:**
+
+    # Count agents
+    ls -1 .claude/agents/*.ag.md | wc -l
+    
+    # Count commands
+    ls -1 dev-tools/commands/_custom/*.md | wc -l
+    ls -1 dev-tools/commands/_generated/*.md | wc -l
+    
+    # Verify agent links
+    for agent in .claude/agents/*.ag.md; do
+      name=$(basename "$agent" .ag.md)
+      grep -q "$name" .integrations/README.md || echo "Missing agent doc: $name"
+    done
+{: .language-bash}
+
+### 5. Synchronize Cross-References
+
+**Ensure consistency across:**
+
+* Links between README files
+* References to guides, workflows, and templates
+* Agent and command documentation
+* Version numbers and counts
+* Directory structure descriptions
+
+**Cross-reference validation:**
+
+    # Check that all workflows mentioned in READMEs exist
+    grep -h "\.wf\.md" README.md .meta/README.md | 
+      grep -o '[a-z-]*\.wf\.md' | sort -u | while read wf; do
+        find . -name "$wf" | grep -q . || echo "Referenced but missing: $wf"
+    done
+{: .language-bash}
+
+### 6. Update Quick Reference Tables
+
+**For each README, maintain tables for:**
+
+* Component counts (guides, workflows, agents, commands)
+* Category mappings
+* Tool/workflow/guide relationships
+* Common task → resource mappings
+
+**Table Format:**
+
+    | Type | Count | Location | Definition |
+    |------|-------|----------|------------|
+    | Guides | XX | guides/ | .meta/gds/guides-definition.g.md |
+    | Workflows | XX | workflow-instructions/ | .meta/gds/workflow-instructions-definition.g.md |
+    | Agents | XX | .integrations/claude/agents/ | .meta/gds/agents-definition.g.md |
+{: .language-markdown}
+
+## Embedded Templates
+
+<templates>
+<template path="readme-section-template.md">
+## [Section Name]
+
+[Brief description of section purpose]
+
+### Available [Items]
+
+**[Category]:**
+- **[Item Name](./path/to/item.md)** - [One-line description]
+- **[Item Name](./path/to/item.md)** - [One-line description]
+
+**[Another Category]:**
+- **[Item Name](./path/to/item.md)** - [One-line description]
+
+### Usage
+
+```bash
+# Example command or workflow invocation
+```
+
+### Related Resources
+- [Related Section](#section-anchor)
+- [External Doc](./path/to/doc.md)
+</template>
+
+<template path="relationship-diagram-template.md">
+## Relationships
+
+```
+Component A provides [what] for →
+  └─ Component B (specific items)
+  └─ Component C (specific items)
+  
+Component B maintains →
+  └─ Component D via [mechanism]
+  └─ Component E via [mechanism]
+```
+
+### Dependencies
+- **[Component]** requires **[Other Component]** for [purpose]
+- **[Component]** generates **[Output]** used by **[Consumer]**
+</template>
+</templates>
+
+## Validation Checklist
+
+### Content Accuracy
+
+* All existing files are documented
+* No references to deleted files
+* Counts and statistics are current
+* Categories match actual content
+
+
+### Link Integrity
+
+* All internal links resolve correctly
+* Relative paths are accurate
+* No broken anchor links
+* Cross-references between READMEs work
+
+
+### Structure Consistency
+
+* Consistent heading hierarchy
+* Uniform list formatting
+* Table formatting matches standards
+* Code block syntax highlighting
+
+
+### Completeness
+
+* All directories have README files
+* New components are documented
+* Deprecated items are marked or removed
+* Examples and usage instructions included
+
+
+## Success Criteria
+
+* All README files accurately reflect current directory contents
+* No broken links or missing references
+* Consistent formatting and structure across all documentation
+* Clear navigation paths between related components
+* Quick reference sections enable fast discovery
+* Counts and statistics are accurate
+* Relationship diagrams correctly show dependencies
+
+## Error Handling
+
+**Missing Files:**
+
+* **Symptoms:** Documentation references non-existent files
+* **Solution:** Either remove reference or locate/recreate missing file
+
+**Inconsistent Information:**
+
+* **Symptoms:** Same item described differently in multiple places
+* **Solution:** Standardize description and update all references
+
+**Broken Links:**
+
+* **Symptoms:** Links return 404 or point to wrong location
+* **Solution:** Update paths or find correct targets
+
+**Outdated Counts:**
+
+* **Symptoms:** Documented counts don't match actual files
+* **Solution:** Recount and update all statistics
+
+## Usage Example
+
+> "Update the handbook documentation after adding new workflow instructions and agents"
+
+Following this workflow would:
+
+1.  Audit current state of all three README files
+2.  Update main README with new workflow listings
+3.  Update meta README if meta-workflows were added
+4.  Update integrations README with new agent information
+5.  Synchronize all cross-references
+6.  Update quick reference tables with new counts
+7.  Validate all changes for accuracy and completeness

data/lib/ace/handbook/atoms/provider_registry.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+module Ace
+  module Handbook
+    module Atoms
+      class ProviderRegistry
+        LOCAL_MANIFEST_GLOB = File.join(
+          "ace-handbook-integration-*",
+          ".ace-defaults",
+          "handbook",
+          "providers",
+          "*.yml"
+        ).freeze
+
+        attr_reader :project_root
+
+        def initialize(project_root: Ace::Handbook.project_root)
+          @project_root = project_root
+        end
+
+        def providers
+          manifests.keys.sort
+        end
+
+        def known?(provider)
+          manifests.key?(provider.to_s)
+        end
+
+        def manifest(provider)
+          manifests.fetch(provider.to_s)
+        end
+
+        def output_dir(provider)
+          manifest(provider).fetch("output_dir")
+        end
+
+        def manifests
+          @manifests ||= begin
+            all_paths = local_manifest_paths + installed_manifest_paths
+
+            all_paths.each_with_object({}) do |path, manifests|
+              data = YAML.safe_load_file(path, permitted_classes: [Date, Time], aliases: true) || {}
+              provider = (data["provider"] || File.basename(path, ".yml")).to_s
+              next if provider.empty?
+
+              manifests[provider] ||= data.merge("_manifest_path" => path)
+            end
+          end
+        end
+
+        private
+
+        def local_manifest_paths
+          Dir.glob(File.join(project_root, LOCAL_MANIFEST_GLOB)).sort
+        end
+
+        def installed_manifest_paths
+          Gem::Specification.find_all.filter_map do |spec|
+            next unless spec.name.start_with?("ace-handbook-integration-")
+
+            Dir.glob(File.join(spec.full_gem_path, ".ace-defaults", "handbook", "providers", "*.yml"))
+          end.flatten.sort
+        end
+      end
+    end
+  end
+end

data/lib/ace/handbook/cli/commands/status.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ace
+  module Handbook
+    module CLI
+      module Commands
+        class Status < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Show handbook provider integration status"
+
+          option :provider, aliases: ["-p"], desc: "Limit status to a single provider"
+          option :format, default: "table", desc: "Output format (table, json)"
+
+          def initialize(collector: nil)
+            super()
+            @collector = collector || Ace::Handbook::Organisms::StatusCollector.new
+          end
+
+          def call(provider: nil, format: "table", **)
+            snapshot = @collector.collect(provider: provider)
+
+            if format == "json"
+              puts JSON.pretty_generate(snapshot)
+              return
+            end
+
+            puts @collector.to_table(snapshot)
+          rescue => e
+            raise Ace::Support::Cli::Error.new(e.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/handbook/cli/commands/sync.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ace
+  module Handbook
+    module CLI
+      module Commands
+        class Sync < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          desc "Project canonical handbook skills into provider-native folders"
+
+          option :provider, aliases: ["-p"], desc: "Limit sync to a single provider"
+          option :quiet, aliases: ["-q"], type: :boolean, default: false, desc: "Suppress sync summary output"
+
+          def initialize(syncer: nil)
+            super()
+            @syncer = syncer || Ace::Handbook::Organisms::ProviderSyncer.new
+          end
+
+          def call(provider: nil, quiet: false, **)
+            results = @syncer.sync(provider: provider)
+            return if quiet
+
+            results.each do |result|
+              puts "synced #{result[:provider]} -> #{result[:relative_output_dir]} " \
+                   "(#{result[:projected_skills]} skills, #{result[:updated_files]} updated, " \
+                   "#{result[:removed_entries]} removed)"
+            end
+          rescue => e
+            raise Ace::Support::Cli::Error.new(e.message)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/handbook/cli.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+
+require_relative "../handbook"
+require_relative "cli/commands/sync"
+require_relative "cli/commands/status"
+
+module Ace
+  module Handbook
+    module CLI
+      extend Ace::Support::Cli::RegistryDsl
+
+      PROGRAM_NAME = "ace-handbook"
+
+      REGISTERED_COMMANDS = [
+        ["sync", "Project canonical skills into provider-native folders"],
+        ["status", "Show handbook provider integration status"]
+      ].freeze
+
+      HELP_EXAMPLES = [
+        "ace-handbook sync                    # Sync all enabled providers",
+        "ace-handbook sync --provider pi      # Sync only Pi",
+        "ace-handbook status                  # Show provider status",
+        "ace-handbook status --provider pi    # Show Pi status"
+      ].freeze
+
+      register "sync", Commands::Sync
+      register "status", Commands::Status
+
+      version_cmd = Ace::Support::Cli::VersionCommand.build(
+        gem_name: "ace-handbook",
+        version: Ace::Handbook::VERSION
+      )
+      register "version", version_cmd
+      register "--version", version_cmd
+
+      help_cmd = Ace::Support::Cli::HelpCommand.build(
+        program_name: PROGRAM_NAME,
+        version: Ace::Handbook::VERSION,
+        commands: REGISTERED_COMMANDS,
+        examples: HELP_EXAMPLES
+      )
+      register "help", help_cmd
+      register "--help", help_cmd
+      register "-h", help_cmd
+    end
+  end
+end

data/lib/ace/handbook/models/skill_document.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ace
+  module Handbook
+    module Models
+      class SkillDocument
+        attr_reader :source_path, :frontmatter, :body
+
+        def initialize(source_path:, frontmatter:, body:)
+          @source_path = source_path
+          @frontmatter = frontmatter
+          @body = body
+        end
+
+        def name
+          frontmatter.fetch("name")
+        end
+
+        def source
+          frontmatter.fetch("source", "unknown").to_s
+        end
+      end
+    end
+  end
+end

data/lib/ace/handbook/molecules/skill_projection.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ace
+  module Handbook
+    module Molecules
+      class SkillProjection
+        class << self
+          def projection_targets(frontmatter, registry:)
+            integration = frontmatter.fetch("integration", {})
+            targets = integration["targets"]
+            return registry.providers if targets.nil? || targets.empty?
+
+            Array(targets).map(&:to_s).select { |provider| registry.known?(provider) }
+          end
+
+          def projected_frontmatter(frontmatter, provider:)
+            merged = deep_copy(frontmatter)
+            integration = merged.delete("integration") || {}
+            provider_meta = integration.fetch("providers", {}).fetch(provider.to_s, {})
+            overrides = provider_meta["frontmatter"] || {}
+
+            deep_merge(merged, overrides)
+          end
+
+          def render(frontmatter, body)
+            yaml = YAML.dump(frontmatter).sub(/\A---\n/, "")
+            normalized_body = body.to_s.sub(/\A\n+/, "")
+            ["---\n", yaml, "---\n\n", normalized_body].join.rstrip + "\n"
+          end
+
+          private
+
+          def deep_copy(data)
+            Marshal.load(Marshal.dump(data))
+          end
+
+          def deep_merge(base, overrides)
+            return overrides unless base.is_a?(Hash) && overrides.is_a?(Hash)
+
+            base.merge(overrides) do |_key, old_value, new_value|
+              if old_value.is_a?(Hash) && new_value.is_a?(Hash)
+                deep_merge(old_value, new_value)
+              else
+                new_value
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end