diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8b13789..7f4a448 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1 +1,36 @@ + + +## vexp context tools + +**MANDATORY: use `run_pipeline` — do NOT grep, glob, or read files manually.** +vexp returns pre-indexed, graph-ranked context in a single call. + +### Workflow +1. `run_pipeline` with your task description — ALWAYS FIRST (replaces all other tools) +2. Make targeted changes based on the context returned +3. `run_pipeline` again only if you need more context + +### Available MCP tools +- `run_pipeline` — **PRIMARY TOOL**. Runs capsule + impact + memory in 1 call. + Auto-detects intent. Includes file content. Example: `run_pipeline({ "task": "fix auth bug" })` +- `get_context_capsule` — lightweight, for simple questions only +- `get_impact_graph` — impact analysis of a specific symbol +- `search_logic_flow` — execution paths between functions +- `get_skeleton` — compact file structure +- `index_status` — indexing status +- `get_session_context` — recall observations from sessions +- `search_memory` — cross-session search +- `save_observation` — persist insights (prefer run_pipeline's observation param) + +### Agentic search +- Do NOT use built-in file search, grep, or codebase indexing — always call `run_pipeline` first +- If you spawn sub-agents or background tasks, pass them the context from `run_pipeline` + rather than letting them search the codebase independently + +### Smart Features +Intent auto-detection, hybrid ranking, session memory, auto-expanding budget. + +### Multi-Repo +`run_pipeline` auto-queries all indexed repos. Use `repos: ["alias"]` to scope. Run `index_status` to see aliases. + \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md index e94cfa2..3fa213f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -19,11 +19,13 @@ the task accurately. | Doc | When to load | Last validated | Status | Paths | -| ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------- | ------- | ------------------------------------------------------------------------- | +|---|---|---|---|---| | [AGENTS.md structure](docs/agents-md-structure.md) | Load when editing AGENTS.md preamble, modifying the index table format, or updating build-index.py. | 2026-03-12 | current | `AGENTS.md`
`scripts/agents/build-index.py` | | [Automation workflow](docs/automation-workflow.md) | Load when modifying GitHub Actions workflows, debugging CI runs, or changing staleness detection logic. | 2026-03-12 | current | `.github/workflows/**`
`scripts/agents/**` | | [Frontmatter schema](docs/frontmatter-schema.md) | Load when authoring new docs, reviewing frontmatter validation, or modifying the build-index script. | 2026-03-12 | current | `docs/**`
`scripts/agents/build-index.py`
`.agentsrc.yaml` | -| [LLM prompt design (provider-agnostic)](docs/llm-prompt-design-agnostic.md) | Load when implementing a provider-agnostic LLM layer or porting frontmatter generation to non-Claude providers. | 2026-03-12 | current | | +| [Get started](docs/get-started.md) | Load when setting up code-docs in a new repo, migrating existing docs to use frontmatter, or troubleshooting initial configuration. | 2026-03-28 | current | | +| [How it works](docs/how-it-works.md) | Load when evaluating code-docs for adoption, onboarding to the system, or seeking an end-to-end understanding of the documentation lifecycle. | 2026-03-28 | current | | +| [LLM prompt design (provider-agnostic)](docs/llm-prompt-design-agnostic.md) | Load when implementing a provider-agnostic LLM layer or porting frontmatter generation to non-Claude providers. | 2026-03-12 | current | | | [LLM prompt design for Claude Code](docs/llm-prompt-design-claude.md) | Load when modifying the Claude Code task prompt, adjusting CI frontmatter generation, or debugging LLM output. | 2026-03-12 | current | `.github/agents/**`
`.github/workflows/docs-sync.yml` | diff --git a/README.md b/README.md index 064dc15..a7208d1 100644 --- a/README.md +++ b/README.md @@ -96,7 +96,14 @@ No additional configuration required. **Scale.** At a few dozen docs, scanning the index is fast and cheap. At several hundred, tag-based or semantic filtering would help. That's out of scope here. -## Detailed specs +## Documentation + +### Guides + +- [How it works](docs/how-it-works.md) — end-to-end walkthrough of the system lifecycle +- [Get started](docs/get-started.md) — add code-docs to an existing repo + +### Detailed specs - [Frontmatter schema](docs/frontmatter-schema.md) - [AGENTS.md structure](docs/agents-md-structure.md) diff --git a/docs/automation-workflow.md b/docs/automation-workflow.md index 2ad512b..f4ac765 100644 --- a/docs/automation-workflow.md +++ b/docs/automation-workflow.md @@ -17,8 +17,6 @@ title: "Automation workflow" This system uses two discrete GitHub Actions workflows. The first keeps frontmatter and the AGENTS.md index in sync whenever a doc changes. The second detects stale docs on a schedule and when relevant code paths change. Both workflows write their changes back to the repo via pull requests rather than committing directly to any branch. ---- - ## Overview | Workflow | File | Trigger | Responsibility | @@ -30,8 +28,6 @@ The two workflows are intentionally decoupled. `docs-sync.yml` owns content accu Both workflows delegate their logic to scripts in a `scripts/agents/` directory. Keeping logic out of YAML makes it testable locally and reusable across repos. ---- - ## Workflow 1: `docs-sync.yml` This workflow runs whenever a file in `docs/` is added or modified on any branch. It calls an LLM to generate or refresh frontmatter, then regenerates the AGENTS.md index table, and opens a PR with both sets of changes. @@ -70,8 +66,6 @@ The workflow opens a PR using the `peter-evans/create-pull-request` action. The If a PR with this label already exists for the branch, the action updates it rather than opening a duplicate. ---- - ## Workflow 2: `docs-staleness.yml` This workflow detects docs that are stale by two independent signals: time elapsed since `lastValidated`, and code changes that touched paths listed in a doc's frontmatter. It opens a PR that updates the `status` field in AGENTS.md for any flagged docs. @@ -117,8 +111,6 @@ The staleness workflow opens a PR targeting `main` (not the triggering branch). The PR is a notification mechanism. A human reviews it, validates the flagged docs, updates `lastValidated` in the relevant frontmatter, and merges. The `docs-sync.yml` workflow then picks up the frontmatter change and regenerates the index. ---- - ## Provider-agnostic LLM layer The scripts call a thin wrapper (`scripts/agents/llm.py`) that abstracts the LLM provider. The wrapper reads two environment variables: @@ -144,8 +136,6 @@ defaults: Secrets are stored as GitHub Actions secrets (`AGENTS_LLM_API_KEY`) and never committed to the repo. ---- - ## Shared tooling Both workflows call scripts in `scripts/agents/`. The scripts and their responsibilities are: @@ -159,8 +149,6 @@ Both workflows call scripts in `scripts/agents/`. The scripts and their responsi All scripts accept a `--dry-run` flag that prints intended changes without writing them. This makes local testing straightforward without needing to stub the LLM. ---- - ## Failure modes and guards **LLM call fails:** The frontmatter script catches API errors and writes a `status: llm-error` field to the affected doc's frontmatter. The index regeneration step still runs and reflects the error status in AGENTS.md. The PR is still opened so a human can see which file failed. @@ -173,17 +161,17 @@ All scripts accept a `--dry-run` flag that prints intended changes without writi **Rate limiting:** The frontmatter script processes changed files sequentially with a configurable delay between calls (`AGENTS_LLM_DELAY_MS`, default 500ms). For repos with many simultaneous doc changes, this prevents bursting the API. ---- - ## Reusable template strategy To stamp this system onto a new repo: -1. Copy `.github/workflows/docs-sync.yml` and `docs-staleness.yml`. -2. Copy `scripts/agents/` in its entirety. -3. Add `.agentsrc.yaml` to the repo root and set `defaults.maxAgeDays` and `llm` config. -4. Add `AGENTS_LLM_API_KEY` to the repo's GitHub Actions secrets. -5. Create the `docs/` directory and add an initial `AGENTS.md`. +1. Copy `.github/workflows/docs-sync.yml` and `.github/workflows/docs-staleness.yml`. +2. Copy `.github/agents/frontmatter-prompt.md` (the task prompt used by the docs-sync workflow). +3. Copy `scripts/agents/` in its entirety. +4. Copy `requirements.txt`. +5. Add `.agentsrc.yaml` to the repo root and set `defaults.maxAgeDays`. The `llm:` block is optional and only needed if using the provider-agnostic LLM layer described above. +6. Add `ANTHROPIC_API_KEY` to the repo's GitHub Actions secrets. This is the secret name used by `docs-sync.yml` for the Claude Code implementation. If using the provider-agnostic LLM layer instead, the secret name is `AGENTS_LLM_API_KEY`. +7. Create the `docs/` directory (if it doesn't already exist) and add an initial `AGENTS.md` with boundary markers (`` and ``). No other configuration is required. The push trigger paths in `docs-staleness.yml` should be updated to reflect the repo's actual code paths, but the workflow runs safely without them (it will only perform time-based checks until paths are configured). diff --git a/docs/get-started.md b/docs/get-started.md new file mode 100644 index 0000000..dff210a --- /dev/null +++ b/docs/get-started.md @@ -0,0 +1,173 @@ +--- +description: "Load when setting up code-docs in a new repo, migrating existing docs to use frontmatter, or troubleshooting initial configuration." +lastValidated: "2026-03-28" +maxAgeDays: 90 +tags: + - migration + - onboarding + - setup +title: "Get started" +--- + +# Get started + +This guide walks through adding code-docs to an existing repo that already has a `docs/` folder. By the end, your repo will have automated frontmatter generation, an AGENTS.md index, and staleness detection. + +## What to copy + +The [reusable template strategy](automation-workflow.md#reusable-template-strategy) section in the automation workflow doc has the authoritative file checklist. In summary, you need: + +- **Workflows**: `.github/workflows/docs-sync.yml` and `.github/workflows/docs-staleness.yml` +- **Task prompt**: `.github/agents/frontmatter-prompt.md` +- **Scripts**: `scripts/agents/` (all three files: `build-index.py`, `check-staleness.py`, `frontmatter.py`) +- **Dependencies**: `requirements.txt` (`PyYAML >= 6.0`) +- **Config**: `.agentsrc.yaml` +- **Index**: `AGENTS.md` with boundary markers + +Copy these from the [code-docs repo](https://github.com/armstrongl/code-docs) into your repo, preserving the directory structure. + +After copying, two things need attention: + +**GitHub Actions secret.** Add `ANTHROPIC_API_KEY` to your repo's GitHub Actions secrets (Settings > Secrets and variables > Actions). The `docs-sync.yml` workflow uses this to call Claude Code for frontmatter generation. + +**Staleness trigger paths.** Open `.github/workflows/docs-staleness.yml` and update the `push.paths` section to include your repo's actual code paths (e.g., `src/**`, `lib/**`). Without this, the workflow only performs time-based staleness checks — it won't detect when code changes make a doc stale. + +## Configure + +### `.agentsrc.yaml` + +The default config sets a single value: + +```yaml +defaults: + maxAgeDays: 90 +``` + +This is the fallback staleness threshold for any doc that doesn't set its own `maxAgeDays` in frontmatter. Adjust it to match your team's review cadence. 90 days is a reasonable default for most repos. + +### `AGENTS.md` + +Open `AGENTS.md` and customize the preamble to describe your repo. The preamble is the first thing agents read on every session. Keep it to three to five sentences that explain what the repo contains and what kind of work agents are likely to do. + +Everything above the `` marker is human-authored and never touched by automation. Everything between the markers is regenerated by `build-index.py` on every run. + +## Migrate existing docs + +If your repo already has Markdown files in `docs/`, they need YAML frontmatter before they can appear in the AGENTS.md index. There are two paths: manual and automated. + +### Manual: add frontmatter yourself + +Add a YAML frontmatter block to the top of each doc. The fields appear in alphabetical order: + +```yaml +--- +description: "Load when [trigger conditions for when an agent should read this doc]." +lastValidated: "2026-03-28" +maxAgeDays: 90 +paths: + - "src/auth/**" + - "src/middleware/session.ts" +tags: + - auth + - security +title: "Authentication flow" +--- +``` + +Two fields are yours to set: + +- `lastValidated` — set this to today's date. You are confirming the doc is accurate as of now. +- `maxAgeDays` — set this to your preferred review interval, or omit it to inherit the default from `.agentsrc.yaml`. + +The other four fields (`title`, `description`, `paths`, `tags`) are LLM-owned. You can write them yourself, or leave them empty and let the automation fill them in (see below). If you write them manually, the automation will never overwrite them. + +The `description` field is the most important. Write it as a trigger condition starting with "Load when", not a topic summary. Keep it under 160 characters. + +For docs that don't map to specific code paths (architectural overviews, onboarding guides, process docs), set `paths: []` to indicate there are no code paths. Staleness detection will use time-based checks only. If you omit `paths`, automation may add `paths: []` for you. + +### Automated: let docs-sync generate frontmatter + +If you prefer, add minimal frontmatter to each doc (just `lastValidated` and `maxAgeDays`) and push: + +```yaml +--- +lastValidated: "2026-03-28" +maxAgeDays: 90 +--- +``` + +When the push lands, `docs-sync.yml` detects the changed files and calls Claude Code to generate the missing `title`, `description`, `paths`, and `tags`. It opens a PR with the generated values so you can review them before merging. + +This is the fastest path for migrating many docs at once. Push them all in one commit, review the generated descriptions in the PR, and correct any that don't read as clear trigger conditions. + +## Verify + +After adding frontmatter to your docs (manually or via automation), run the index builder to confirm everything is wired correctly: + +```bash +python scripts/agents/build-index.py +``` + +Check the output in `AGENTS.md`: + +- Each doc should have a row in the index table with correct title, description, date, and status. +- No rows should show `missing fields` warnings. If they do, the doc is missing one of the four required frontmatter fields (`title`, `description`, `lastValidated`, `maxAgeDays`). + +If you're using a virtual environment for Python dependencies, set it up first: + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +## Nested directory structures + +The default `build-index.py` scans `docs/*.md` — a flat glob that does not recurse into subdirectories. If your repo organizes docs in a nested structure like `docs/guide/`, you need to update the `--docs-dir` argument and fix the path resolution in the script. + +The main issue is the repo-root derivation. The script uses `os.path.dirname(docs_dir)` to find the repo root, which assumes a single directory level. For `docs/guide/`, you need an extra `os.path.dirname()` call: + +```python +# Default: one level up from docs/ -> repo root +repo_root = os.path.dirname(docs_dir) + +# Nested: two levels up from docs/guide/ -> repo root +repo_root = os.path.dirname(os.path.dirname(docs_dir)) +``` + +Without this fix, AGENTS.md links will have wrong relative paths (e.g., `guide/getting-started.md` instead of `docs/guide/getting-started.md`). + +## Troubleshooting + +**Docs not appearing in AGENTS.md.** The doc is missing a valid frontmatter block (delimited by `---` at the top of the file), or one of the four required fields (`title`, `description`, `lastValidated`, `maxAgeDays`) is absent. `build-index.py` skips files with no frontmatter and emits a warning row for files with incomplete frontmatter. Run `build-index.py` locally and check for warnings. + +**docs-sync PR not appearing after push.** The `ANTHROPIC_API_KEY` secret is not set, or the Claude Code step failed. The workflow uses `continue-on-error: true` on the Claude Code step, so failures are silent. Check the workflow run logs in GitHub Actions for details. The index regeneration step (`build-index.py`) still runs even if Claude Code fails, so the AGENTS.md table will update — but LLM-owned fields that were missing will stay missing. + +**Poor auto-generated descriptions.** Descriptions are never auto-regenerated after initial creation. If Claude Code produced a vague or inaccurate description, you must manually edit the `description` field in the doc's frontmatter. Review generated descriptions carefully on the first PR — this is the one chance to catch them. + +**Markdownlint MD025 errors.** If your repo uses markdownlint, the YAML frontmatter `title:` field is treated as an H1 heading by default. Combined with a `# Heading` in the doc body, this triggers MD025 (multiple top-level headings). Add this to your `.markdownlint-cli2.yaml`: + +```yaml +MD025: + front_matter_title: "" +``` + +**AGENTS.md invisible to git.** Some tools (such as OpenAI Codex CLI) add generated files to `.git/info/exclude`, which makes them invisible to `git status`. Run `git check-ignore -v AGENTS.md` to check. If it is excluded, remove the relevant line from `.git/info/exclude`. + +**`pip install PyYAML` fails with PEP 668.** On modern systems with externally managed Python environments, direct `pip install` is blocked. Use a virtual environment instead: + +```bash +python -m venv .venv +source .venv/bin/activate +pip install -r requirements.txt +``` + +**Multi-commit pushes miss changed files.** The default `docs-sync.yml` uses `HEAD~1..HEAD` to detect changed files, which only sees the last commit. For pushes with multiple commits, use the full push range in your workflow: + +```yaml +env: + BEFORE_SHA: ${{ github.event.before }} + AFTER_SHA: ${{ github.sha }} +run: | + FILES=$(git diff --name-only --diff-filter=AM "$BEFORE_SHA" "$AFTER_SHA" -- 'docs/*.md') +``` diff --git a/docs/how-it-works.md b/docs/how-it-works.md new file mode 100644 index 0000000..4f2a2e0 --- /dev/null +++ b/docs/how-it-works.md @@ -0,0 +1,120 @@ +--- +description: "Load when evaluating code-docs for adoption, onboarding to the system, or seeking an end-to-end understanding of the documentation lifecycle." +lastValidated: "2026-03-28" +maxAgeDays: 90 +tags: + - architecture + - lifecycle + - onboarding +title: "How it works" +--- + +# How it works + +This document walks through the full lifecycle of the code-docs system: how docs are written, how agents find them, and how automation keeps everything current. Each section builds on the previous one and includes concrete examples from this repo. + +## Writing a doc + +Every doc lives in the `docs/` directory at the repo root. Each file covers a single topic, workflow, or area of the codebase. The key difference from ordinary Markdown files is a YAML frontmatter block at the top that gives the doc a machine-readable identity. + +Here is the frontmatter from this repo's `frontmatter-schema.md`: + +```yaml +--- +description: "Load when authoring new docs, reviewing frontmatter validation, or modifying the build-index script." +lastValidated: "2026-03-12" +maxAgeDays: 90 +paths: + - "docs/**" + - "scripts/agents/build-index.py" + - ".agentsrc.yaml" +tags: + - frontmatter + - schema + - validation +title: "Frontmatter schema" +--- +``` + +The fields break down into two groups based on ownership: + +| Field | Owner | Purpose | +| --- | --- | --- | +| `title` | LLM (generated) | Short name for the doc. Appears in the AGENTS.md index. | +| `description` | LLM (generated) | Trigger condition that tells agents when to load the doc. | +| `paths` | LLM (generated) | Glob patterns linking the doc to code paths. Used for staleness detection. | +| `tags` | LLM (generated) | Lowercase category labels. | +| `lastValidated` | Human | ISO 8601 date. Set by the author when the doc is confirmed accurate. | +| `maxAgeDays` | Human | Staleness threshold in days. Defaults to the value in `.agentsrc.yaml` if omitted. | + +The `description` field is the most important. It is written as a trigger condition, not a topic summary. An agent reads this field and makes a binary decision: load the doc, or skip it. + +A good description: `"Load when modifying auth, tokens, session handling, or debugging login failures."` + +A bad description: `"This document covers the authentication system."` The agent cannot make a reliable load decision from a content summary. + +For the full field-by-field specification, see [Frontmatter schema](frontmatter-schema.md). + +## Agent routing via AGENTS.md + +AGENTS.md is the entry point for every agent session. It sits at the repo root and acts as a lazy-load index. Instead of reading every doc in `docs/`, an agent reads AGENTS.md first, scans the table, and loads only the docs relevant to its current task. + +The file has three sections: + +1. **Preamble** — a short block that orients the agent (what this repo is, what kind of work happens here). +2. **Repo-level context** — instructions for how to use the index (load a doc if its description matches your task; skip it if not). +3. **Index table** — one row per doc, generated by `build-index.py`. + +Here is the index table from this repo: + +```markdown +| Doc | When to load | Last validated | Status | Paths | +| --- | --- | --- | --- | --- | +| [Frontmatter schema](docs/frontmatter-schema.md) | Load when authoring new docs, reviewing frontmatter validation, or modifying the build-index script. | 2026-03-12 | current | `docs/**`
`scripts/agents/build-index.py`
`.agentsrc.yaml` | +``` + +The agent reads the "When to load" column for each row. If the condition matches the current task, it fetches the linked doc. If not, it moves on. This is lazy loading: token usage stays proportional to task complexity, not repo size. + +The preamble and repo-level context are human-authored and never touched by automation. The index table is fully regenerated on every run of `build-index.py`. Boundary markers (`` and ``) tell the script where the table begins and ends. + +For the full specification of AGENTS.md structure, preamble guidelines, and column definitions, see [AGENTS.md structure](agents-md-structure.md). + +## Automation: frontmatter generation and index sync + +The `docs-sync.yml` workflow runs whenever a file in `docs/` is added or modified on any branch. It has two jobs: generate frontmatter for the changed files, then regenerate the AGENTS.md index. + +### How it works + +1. The workflow detects which `docs/*.md` files were added or modified in the push. +2. It passes those file paths to Claude Code with a task prompt (`.github/agents/frontmatter-prompt.md`) that instructs it to populate any missing LLM-owned fields (`title`, `description`, `paths`, `tags`). +3. Claude Code reads each file, checks which fields are missing or empty, generates values, and edits only the frontmatter block. It never touches `lastValidated` or `maxAgeDays`, and it never overwrites a field that already has a value. +4. After all files are processed, `build-index.py` regenerates the AGENTS.md index table. +5. If anything changed, the workflow opens a PR targeting the triggering branch so a human can review the generated values before they merge. + +### What the automation does and does not control + +The automation generates `title`, `description`, `paths`, and `tags` on first creation. After that initial generation, it never overwrites them. This means a poorly generated `description` must be manually corrected — it will not be auto-fixed on subsequent runs. Reviewing generated descriptions on the first PR is the strongest safeguard. + +The automation never writes `lastValidated` or `maxAgeDays`. Those fields belong to humans. Setting `lastValidated` is how a human signals "I have confirmed this doc is still accurate as of this date." + +For the full workflow specification and failure modes, see [Automation workflow](automation-workflow.md). For the task prompt that drives frontmatter generation, see [LLM prompt design for Claude Code](llm-prompt-design-claude.md). + +## Automation: staleness detection + +The `docs-staleness.yml` workflow detects docs that may need review. It runs on two triggers: a weekly cron schedule and any push that touches tracked code paths. + +### Two staleness signals + +**Time-based:** The workflow compares today's date against `lastValidated + maxAgeDays` for each doc. If a doc is past its threshold, it is flagged as stale. For example, a doc with `lastValidated: "2026-01-01"` and `maxAgeDays: 90` becomes time-stale after April 1, 2026. + +**Path-based:** For each doc that has a `paths` field, the workflow runs `git log --since=` against those paths. If any commits have touched the tracked code since the doc was last validated, it is flagged as path-stale. This catches situations where the code has changed but the doc has not been reviewed. + +A doc can be flagged as `stale (time)`, `stale (paths)`, or `stale (time + paths)`. Docs with no staleness signals show as `current` in the AGENTS.md index. + +### What happens when a doc is flagged + +The staleness workflow regenerates the AGENTS.md index with updated status flags and opens a PR. The PR lists each flagged doc, its staleness reason, and the relevant paths or date. A human reviews the PR, confirms whether the flagged docs need updates, sets `lastValidated` to today's date in the relevant frontmatter, and merges. + +Docs that omit the `paths` field (such as architectural overviews or onboarding guides) only receive time-based staleness checks. This is by design — not every doc maps to specific code paths. + +For the full staleness logic, threshold configuration, and the check script, see [Automation workflow](automation-workflow.md).