# Context Index And Packs

Open Orchestra can build a local, offline context index so future runtime
prompts can reference compact project facts instead of asking agents to scan the
whole repository.

```bash
orchestra context-index build --json
orchestra context-index status --json
orchestra context-index search --query "runtime lifecycle" --role developer --json
orchestra context-index pack --query "runtime lifecycle" --task STORY-001 --json
```

The build command writes:

- `.agent-workflow/context-index/manifest.json`
- `.agent-workflow/context-index/files.jsonl`

The index stores relative paths, file size, modified time, extension, depth, and
compact search signals such as Markdown headings, imports, exported symbols, and
test hints.
It intentionally excludes generated, dependency, cache, binary-output, workflow,
and secret-sensitive paths such as `node_modules`, `dist`, `build`,
`.agent-workflow`, `.env*`, key files, credentials, tokens, and secrets.

`context-index status` rescans the workspace and reports whether the index is
fresh. It marks the index stale when the schema changes, exclusion rules drift,
files are added or removed, indexed file size or modified time changes, or the
manifest is corrupted.

`context-index search` reads only the local index, not the full source tree. It
returns deterministic ranked results with matched signals, inclusion reasons,
and omission reasons when results are below the requested limit. Ranking uses
query terms, task ownership paths, phase, role, paths, headings, imports,
symbols, and test hints.

`context-index pack` builds bounded JSON and Markdown artifacts under
`.agent-workflow/context-packs/`. Defaults are conservative:

- target budget: 30,000 characters
- hard cap: 40,000 characters
- max files: 20
- max snippets: 60
- per-snippet cap: 1,200 characters

Packs fail closed when the index is missing or stale. Snippets are selected from
ranked files, each item records an inclusion reason, and obvious secret-like
values are redacted before persistence.

Runtime-native spawn prompts consume context packs automatically when a fresh
index exists. The prompt and spawn request include the pack artifact path and
budget summary. If the index is missing or stale, the prompt records the fallback
reason and keeps the existing required context manifest behavior.

## Benchmark Evidence

Use the deterministic local benchmark when validating context-pack behavior for
large repositories:

```bash
npm run context:pack:bench
```

The benchmark seeds a temporary repository, builds a context index, creates a
bounded task-scoped pack, verifies stale-index failure behavior, and writes JSON
and Markdown reports under `docs/reports/`. The report includes selected files,
inclusion reasons, redaction count, target and hard-cap budgets, packed size,
source-size reduction ratio, stale-index diagnostics, and runtime spawn pack
metadata. It does not require network access, remote embeddings, or a SaaS
index.