Multi-Tier Customization Discovery Engine (23 - Deprecating AGY and Unifying Workspace Plugins and CLI.md).
Discovers and resolves Rules (AGENTS.md, GEMINI.md, .agents/rules/*.md),
Skills (skills/<name>/SKILL.md, skills.json),
and Hooks (hooks.json) in strict precedence order:
- Workspace
.agents/(or.agent/,_agents/,_agent/) walking up fromcwdto the.gitroot. - Declared workspace JSON manifests (
skills.json,plugins.jsonwithentries,inherits,include_only,exclude). - Global configuration directory (see "Paths").
- Built-in application skills (
<app data dir>/builtin/skills/). - Global declared JSON manifests (
skills.json).
Paths
No path is hardcoded. Each directory resolves in this order:
| Directory | Option or app env | Environment variable | Default |
|---|---|---|---|
| Global config | :global_config_dir | SUPER_PI_CONFIG_DIR | :filename.basedir(:user_config, "super-pi") |
| App data | :app_data_dir | SUPER_PI_DATA_DIR | :filename.basedir(:user_data, "super-pi") |
| Extra global roots | :discovery_roots | SUPER_PI_DISCOVERY_ROOTS (path-separated) | none |
The defaults follow each operating system: XDG on Linux, ~/Library/Application Support on
macOS, and %APPDATA% on Windows. Extra roots are scanned like the global config directory,
after it. Use them to read a directory that another tool owns.
Summary
Functions
Walks up from start_dir to the repository root (directory containing .git).
If no .git boundary exists in any parent, returns [start_dir].
Returns all ancestor directories from highest priority (start_dir) to lowest (repo_root).
Application data directory (transcripts, built-in skills). See the module doc.
Global configuration directory. See the module doc for how it resolves.
Roots of a knowledge base: config :super_pi, :knowledge_paths, else default_workspace_paths/0.
Workspace roots for a conversation that names none: config :super_pi, :workspace_paths, else the
current working directory. This is the only place the server reads the working directory for it.
Discovers all hooks.json files across workspace .agents/hooks.json, active plugins, and <global config>/hooks.json.
Discovers all active rule files (GEMINI.md, AGENTS.md, .agents/rules/*.md) for workspace_dirs,
deduplicating by canonical resolved path (File.read_link / Path.expand) so a rule file is never
injected more than once.
Discovers all skills across the 5 priority tiers. Higher-priority skills override lower-priority
skills with the same name.
Returns [%{name: String.t(), description: String.t(), path: String.t(), tier: atom()}].
Extra global roots that are scanned like the global config directory.
Parses YAML frontmatter (name and description) from a SKILL.md file.
Resolves a skills.json or plugins.json manifest recursively (inherits + entries),
applying include_only and exclude regex/glob filters.
Functions
Walks up from start_dir to the repository root (directory containing .git).
If no .git boundary exists in any parent, returns [start_dir].
Returns all ancestor directories from highest priority (start_dir) to lowest (repo_root).
Application data directory (transcripts, built-in skills). See the module doc.
Global configuration directory. See the module doc for how it resolves.
@spec default_knowledge_paths() :: [String.t()]
Roots of a knowledge base: config :super_pi, :knowledge_paths, else default_workspace_paths/0.
@spec default_workspace_paths() :: [String.t()]
Workspace roots for a conversation that names none: config :super_pi, :workspace_paths, else the
current working directory. This is the only place the server reads the working directory for it.
Discovers all hooks.json files across workspace .agents/hooks.json, active plugins, and <global config>/hooks.json.
Discovers all active rule files (GEMINI.md, AGENTS.md, .agents/rules/*.md) for workspace_dirs,
deduplicating by canonical resolved path (File.read_link / Path.expand) so a rule file is never
injected more than once.
Discovers all skills across the 5 priority tiers. Higher-priority skills override lower-priority
skills with the same name.
Returns [%{name: String.t(), description: String.t(), path: String.t(), tier: atom()}].
Extra global roots that are scanned like the global config directory.
Parses YAML frontmatter (name and description) from a SKILL.md file.
Resolves a skills.json or plugins.json manifest recursively (inherits + entries),
applying include_only and exclude regex/glob filters.