ACE - Support Nav

Protocol-aware navigation and resource discovery for ACE handbook content. ACE Logo

Gem Version Ruby License: MIT

Works with: Claude Code, Codex CLI, OpenCode, Gemini CLI, pi-agent, and more.

ace-support-nav powers the ace-nav CLI with cascade-aware URI resolution across project, user, and gem sources. It supports built-in protocols (wfi://, guide://, tmpl://, skill://, prompt://) and extensible command protocols like task:// for tool delegation, with override targeting, wildcard discovery, and fast cached lookups.

How It Works

  1. Accept a protocol URI (e.g., wfi://setup) and search project, user, and gem handbook sources in cascade order.
  2. Apply extension inference and override targeting (@project for repo .ace-handbook/, @user for ~/.ace-handbook/, @gem for a specific gem's bundled handbook) to locate the best match.
  3. Return the resolved path, content, or a list of candidates for wildcard and prefix patterns.

Use Cases

Resolve ACE resources without memorizing file paths - run ace-nav resolve wfi://setup or ace-nav resolve guide://configuration to locate workflows, guides, templates, and skills through protocol URLs instead of raw paths.

Target the right override layer explicitly - use @project, @user, or specific gem aliases (e.g., wfi://@ace-git/setup) to bypass cascade ambiguity when multiple sources provide the same resource.

Discover matching resources quickly - use wildcard and prefix patterns like ace-nav list 'wfi://*test*' or ace-nav resolve prompt://guidelines/ to browse available content across all handbook sources.

Navigate task specs through the same interface - use task:// references (e.g., ace-nav resolve task://083) so task lookup shares the same navigation workflow as handbook resources, delegating to ace-task under the hood.

Load resolved content into agent workflows - pair with ace-bundle to fetch and embed resources discovered through ace-nav into agent context for skills and workflows.

Quick Start

ace-nav resolve guide://markdown-style             # Resolve a guide path
ace-nav list 'wfi://*test*'                        # Browse candidate workflows
ace-nav sources                                    # List all registered sources
ace-nav create wfi://setup ./tmp/setup-copy.wf.md # Create from URI into a file

Expected user-facing success criteria for this journey:

  • resolve returns a usable path for the requested resource.
  • list and sources return actionable entries for follow-up commands.
  • create writes the requested file at the provided target path.

Testing

Use the restarted lane model for this package:

ace-test ace-support-nav       # fast deterministic lane (default)
ace-test ace-support-nav feat  # deterministic feature lane
ace-test ace-support-nav all   # fast + feat
ace-test-e2e ace-support-nav   # retained workflow-value scenarios only

Handbook | Part of ACE