/index

namespace: aiwg
name: index
platforms: [all]
description: Build, query, inspect dependencies, sync Fortemi Core cache, and report status for the searchable index of SDLC artifacts in .aiwg/

Artifact Index

You manage the AIWG artifact index — building or rebuilding the searchable index of all SDLC artifacts in `.aiwg/`, querying it by text, inspecting dependency graphs, and reporting index statistics.

> **Scope: the JSON artifact graph AND research-corpus markdown views.** This skill manages the JSON artifact graph under `.aiwg/.index/*` (nodes, edges, checksums). As of #1490, `aiwg index build` **also** renders research-corpus markdown views (`indices/by-topic.md`, `indices/by-year.md`, `indices/authors.md`, `citation-network`, …) natively, in the same process — one command produces both from one config (`.aiwg/aiwg.config` `index.graphs`, #1491). The former standalone `corpus-index-build` `build.py` is retired; that skill now points back to `aiwg index build`. Markdown views render only when the project has a `documentation/references/` corpus, so this is a no-op in ordinary SDLC projects.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "index my artifacts" → build
• "find requirements about authentication" → query "authentication"
• "what depends on UC-001" → deps .aiwg/requirements/UC-001.md
• "show neighboring artifacts" → neighbors --node <id>
• "compare related artifacts" → set --op intersection --node-a <id> --node-b <id>
• "how many artifacts are indexed" → stats
• "is the index healthy" → status
• "export the index for Fortemi" → export --format fortemi
• "sync the Fortemi cache" → sync
• "refresh the index" → build --force

Trigger Patterns Reference

| Pattern | Example | Action | |---------|---------|--------| | Build index | "build the artifact index" | Run `aiwg index build` | | Post-clone bootstrap | "I just cloned this, queries return nothing" / "the index is missing" | Run `aiwg index build --all` (the index is gitignored, not committed — see note below) | | Force rebuild | "rebuild the index from scratch" | Run `aiwg index build --force --verbose` | | Text search | "search artifacts for authentication" | Run `aiwg index query "authentication"` | | Dependency graph | "show dependencies for the SAD" | Run `aiwg index deps .aiwg/architecture/software-architecture-doc.md` | | Neighbor graph | "show related nodes for REF-001" | Run `aiwg index neighbors --graph <name> --node REF-001` | | Set operation | "what overlaps between these two nodes" | Run `aiwg index set --graph <name> --op intersection --node-a <id> --node-b <id>` | | Statistics | "how many artifacts are indexed?" | Run `aiwg index stats` | | Health/status | "is the index stale?" | Run `aiwg index status --json` | | JSON output | "get index stats as JSON" | Run `aiwg index stats --json` | | Fortemi export | "export this index for Fortemi" | Run `aiwg index export --format fortemi --schema-version v2` | | Fortemi cache | "sync the Fortemi Core index" | Run `aiwg index sync` |

> **`.aiwg/.index/` is a regenerable build artifact, not committed.** It is gitignored by default (`aiwg use` / `aiwg regenerate` / scaffolding add it to `.gitignore`), so a fresh clone has no index — `aiwg index build --all` is the standard bootstrap. `aiwg doctor` flags a missing index (`info`, when an `index` block is declared in `.aiwg/aiwg.config` — the canonical home as of #1491 — or legacy `.aiwg/config.yaml`) or a stale one (`warn`, when recorded source files changed) and points back to `aiwg index build`.

Behavior

When triggered:

1. **Identify the subcommand**:

• Is the user building, searching, inspecting dependencies, or checking stats?
• Is a specific artifact path or query mentioned?
• Is `--force`, `--verbose`, or `--json` appropriate?

2. **Run the appropriate command**:

   # Build or rebuild the index
   aiwg index build

   # Full rebuild with progress output
   aiwg index build --force --verbose

   # Semantic search across all artifacts
   aiwg index query "<text>"

   # Machine-readable search results
   aiwg index query "<text>" --json

   # default Fortemi Core static-cache query
   aiwg index query "<text>" --json

   # Fortemi static semantic and filtered hybrid query modes
   aiwg index query "<text>" --semantic --json
   aiwg index query "<text>" --hybrid --type adr --tags search --json

   # Show dependency graph for an artifact
   aiwg index deps <artifact-path>

   # Machine-readable dependency graph
   aiwg index deps <artifact-path> --json

   # Inspect neighbor traversal or set relationships
   aiwg index neighbors --graph <name> --node <node-id> --json
   aiwg index set --graph <name> --op intersection --node-a <node-id> --node-b <node-id> --json

   # Show index statistics
   aiwg index stats

   # Machine-readable statistics
   aiwg index stats --json

   # Health/status, including optional Fortemi Core cache state
   aiwg index status --json

   # Export and sync the default Fortemi Core static cache
   aiwg index export --format fortemi --schema-version v2
   aiwg index sync

3. **Report the result** — surface the relevant matches, dependencies, or counts.

Fortemi Core Backend

Fortemi Core is the default artifact search backend after `aiwg index sync`. Use `--backend local` only for the legacy local fallback during the phase-out window. If the Fortemi cache is missing or stale, run `aiwg index sync`. A valid synced Fortemi cache with zero items is not stale: query/fulltext return empty results, discover reports a Fortemi static-cache no-match hint, and show does not fall back to the local AIWG corpus when the Fortemi backend was explicit.

Examples

Example 1: Build the index

**User**: "Build the artifact index"

**Extraction**: Build subcommand, no flags

**Action**:

aiwg index build

**Response**: "Index built. Indexed 47 artifacts across 8