aria-knowledge

/index — Knowledge Index Builder

Scan all promoted knowledge files, normalize tags, detect issues, and regenerate {knowledge_folder}/index.md.

Runtime Gate (per ADR-094)

Canonical resolution: This is the Claude Code variant. When both plugin-claude-code and plugin-claude-cowork are loaded in the same session (most common in Claude Desktop), bare /index resolves to this skill — aria-knowledge (Code) is the canonical owner of all 24 dual-port skills per ADR-094 §Part 1. The Cowork variant is namespaced-only: /aria-cowork:index.

Before Step 0: Check that the Bash tool is available in this session. If Bash is NOT available (you are running in Claude Cowork or another non-Code runtime), surface the following notification and wait for explicit user confirmation:

⚠️ Runtime mismatch — you invoked aria-knowledge's /index from a non-Code runtime.

This variant supports projects_enabled / projects_shared_knowledge config keys not present in Cowork's aria-config.md. For the Cowork-native variant (simpler index, no shared-knowledge tier), use /aria-cowork:index.

Use /aria-cowork:index instead? (y / n)

Wait for an explicit reply:

• y / yes — Use the Skill tool to invoke aria-cowork:index with the same arguments the user provided to this invocation. Do not proceed with this skill's steps; the cowork variant takes over and runs to completion. This is the default-yes path — auto-redirect is the helpful action.
• n / no — Proceed with this (aria-knowledge) variant anyway despite the runtime mismatch. The user has explicitly opted in.
• No response / any other reply — Treat as "do not proceed" and exit cleanly without running either variant.

This gate applies even when mode = auto per ADR-094 §Part 3. Auto mode's "implicit-yes on all gates" rule is suspended for the runtime-mismatch check — auto trusts that the user invoked the correct variant, and this gate enforces that precondition. All other auto-mode gates remain bypassed. The friction cost is now low: on y, the auto-redirect runs the correct variant with the original args.

If Bash is available, proceed to Step 0.

Step 0: Resolve Config

Read ~/.claude/aria-knowledge.local.md and extract:

• knowledge_folder — base path for all operations
• freeform_promotion_threshold — minimum file count before suggesting promotion (default: 3)
• staleness_threshold_months — months before a file is flagged stale (default: 6)
• projects_enabled — default false; controls whether project tier is scanned and indexed
• projects_list — default empty; comma-separated tag:path pairs; only relevant if projects_enabled: true
• projects_promotion_threshold — default 2; minimum projects sharing a similar pattern to surface as a cross-project promotion candidate
• projects_shared_knowledge — default empty; comma-separated list of project tags enabled for shared knowledge. When non-empty, scan each listed project's _project-knowledge/ folder for team-shared knowledge. Tags not in this list are skipped (their _project-knowledge/ folders, if any exist on disk, are NOT indexed).

If the config file doesn't exist, stop: "aria-knowledge is not configured. Run /setup to get started."

Step 1: Scan Promoted Folders

Scan these directories for .md files (excluding directory README stubs that only contain a few lines of boilerplate):

• {knowledge_folder}/approaches/
• {knowledge_folder}/decisions/
• {knowledge_folder}/guides/ (recursive — includes subdirectories)
• {knowledge_folder}/references/ (recursive — includes sources/ and other subdirectories)

Do NOT scan: archive/, intake/, rules/, top-level logs/*.md (audit-log files like config-audit-log.md, knowledge-audit-log.md, hook-debug.log), or root-level files (README.md, LOCAL.md, OVERVIEW.md, index.md).

Carve-out for review reports: the two subfolders logs/prospect/ and logs/retrospect/ ARE scanned as a separate "reviews tier" — see the dedicated sub-step below. Review reports use the same frontmatter scanning convention as cross-project files (tags, Last updated, first heading).

For each .md file found:

1. Read the file
2. Extract YAML frontmatter (content between --- markers at the top of the file)
3. From frontmatter, extract:
4. tags: — array of tags (e.g., tags: [api, pagination, django]). If missing, record as untagged.
5. Last updated: — date string (YYYY-MM-DD). If missing, record as unknown.
6. semantic-hints: — array of free-form phrases (e.g., semantic-hints: [cursor pagination, keyset pagination]). Optional; if missing, treat as empty list. Added 2.16.0.
7. Extract the first # heading as the file's description
8. Store: {path, tags[], hints[], description, last_updated, source: "cross-project"}

Report: "Scanned N files in approaches/, decisions/, guides/, references/."

Reviews tier scan (always run if either review subfolder exists)

After the cross-project scan, scan logs/prospect/ and logs/retrospect/ for review reports written by the /prospect and /retrospect skills.

For each .md file found in either subfolder:

1. Read the file
2. Extract YAML frontmatter — review reports have a richer schema than cross-project files. Pull:
3. tags: — array of tags. Always includes prospect or retrospect plus the scope keyword. If missing (legacy reports written before the structured-frontmatter format), record as untagged and emit a soft warning (one-line) suggesting the file be re-run or hand-tagged.
4. Last updated: — fall back to date: if Last updated: is absent (review reports use date: for the report-creation date).
5. type: — prospect or retrospect. Used to bucket the file under "Retrospects" or "Prospects" in the ## Review Index section of index.md (see Step 9).
6. scope: — the scope keyword (e.g., release, deployment, commit, plan).
7. tickets: — for cross-reference enrichment (consumed by /context).
8. Extract the first # heading as the file's description (typically "/prospect — <goal>" or "/retrospect — <goal>").
9. Store: {path, tags[], description, last_updated, source: "review", review_type: <prospect|retrospect>, scope: <keyword>, tickets: [...]}

Report: "Scanned R review reports across logs/prospect/ and logs/retrospect/ (P prospect, Q retrospect)."

If neither subfolder exists yet on disk, skip this sub-step silently (first run before any /prospect or /retrospect has been invoked).

Project tier scan (only if projects_enabled: true and projects_list is non-empty)

After the cross-project scan, scan the project tier:

For each tag:path pair in projects_list:

1. Glob {knowledge_folder}/projects/{tag}/**/*.md recursively
2. Exclude projects/{tag}/README.md (per-project navigation, not knowledge content)
3. Exclude projects/README.md (the projects/ tier README, plugin-managed)
4. For each file found, perform the same frontmatter extraction as above.
5. Path-derived tag union (Decision #9): automatically add {tag} to the file's tag set even if not in YAML frontmatter. The union of YAML tags + path tag is what gets indexed. This means project files don't have to manually include the project tag in their frontmatter.
6. Store: {path, tags[], description, last_updated, source: "project-specific", project: tag}

Report: "Scanned M files across N project subdirectories: [project tags]."

If projects_enabled: false or projects_list is empty, skip this sub-step entirely. Project tier files (if any exist on disk) won't be indexed.

Team-shared scan (only if projects_shared_knowledge list is non-empty)

After the project tier scan, scan each enabled project's _project-knowledge/ folder. Only projects whose tags appear in projects_shared_knowledge are scanned — non-listed projects are skipped, even if their _project-knowledge/ folders exist on disk.

For each tag in `pro