|
| 1 | +--- |
| 2 | +description: "Load when setting up code-docs in a new repo, migrating existing docs to use frontmatter, or troubleshooting initial configuration." |
| 3 | +lastValidated: "2026-03-28" |
| 4 | +maxAgeDays: 90 |
| 5 | +tags: |
| 6 | + - migration |
| 7 | + - onboarding |
| 8 | + - setup |
| 9 | +title: "Get started" |
| 10 | +--- |
| 11 | + |
| 12 | +# Get started |
| 13 | + |
| 14 | +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. |
| 15 | + |
| 16 | +## What to copy |
| 17 | + |
| 18 | +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: |
| 19 | + |
| 20 | +- **Workflows**: `.github/workflows/docs-sync.yml` and `.github/workflows/docs-staleness.yml` |
| 21 | +- **Task prompt**: `.github/agents/frontmatter-prompt.md` |
| 22 | +- **Scripts**: `scripts/agents/` (all three files: `build-index.py`, `check-staleness.py`, `frontmatter.py`) |
| 23 | +- **Dependencies**: `requirements.txt` (`PyYAML >= 6.0`) |
| 24 | +- **Config**: `.agentsrc.yaml` |
| 25 | +- **Index**: `AGENTS.md` with boundary markers |
| 26 | + |
| 27 | +Copy these from the [code-docs repo](https://github.com/armstrongl/code-docs) into your repo, preserving the directory structure. |
| 28 | + |
| 29 | +After copying, two things need attention: |
| 30 | + |
| 31 | +**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. |
| 32 | + |
| 33 | +**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. |
| 34 | + |
| 35 | +## Configure |
| 36 | + |
| 37 | +### `.agentsrc.yaml` |
| 38 | + |
| 39 | +The default config sets a single value: |
| 40 | + |
| 41 | +```yaml |
| 42 | +defaults: |
| 43 | + maxAgeDays: 90 |
| 44 | +``` |
| 45 | +
|
| 46 | +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. |
| 47 | + |
| 48 | +### `AGENTS.md` |
| 49 | + |
| 50 | +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. |
| 51 | + |
| 52 | +Everything above the `<!-- AGENTS-INDEX-START -->` marker is human-authored and never touched by automation. Everything between the markers is regenerated by `build-index.py` on every run. |
| 53 | + |
| 54 | +## Migrate existing docs |
| 55 | + |
| 56 | +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. |
| 57 | + |
| 58 | +### Manual: add frontmatter yourself |
| 59 | + |
| 60 | +Add a YAML frontmatter block to the top of each doc. The fields appear in alphabetical order: |
| 61 | + |
| 62 | +```yaml |
| 63 | +--- |
| 64 | +description: "Load when [trigger conditions for when an agent should read this doc]." |
| 65 | +lastValidated: "2026-03-28" |
| 66 | +maxAgeDays: 90 |
| 67 | +paths: |
| 68 | + - "src/auth/**" |
| 69 | + - "src/middleware/session.ts" |
| 70 | +tags: |
| 71 | + - auth |
| 72 | + - security |
| 73 | +title: "Authentication flow" |
| 74 | +--- |
| 75 | +``` |
| 76 | + |
| 77 | +Two fields are yours to set: |
| 78 | + |
| 79 | +- `lastValidated` — set this to today's date. You are confirming the doc is accurate as of now. |
| 80 | +- `maxAgeDays` — set this to your preferred review interval, or omit it to inherit the default from `.agentsrc.yaml`. |
| 81 | + |
| 82 | +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. |
| 83 | + |
| 84 | +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. |
| 85 | + |
| 86 | +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. |
| 87 | + |
| 88 | +### Automated: let docs-sync generate frontmatter |
| 89 | + |
| 90 | +If you prefer, add minimal frontmatter to each doc (just `lastValidated` and `maxAgeDays`) and push: |
| 91 | + |
| 92 | +```yaml |
| 93 | +--- |
| 94 | +lastValidated: "2026-03-28" |
| 95 | +maxAgeDays: 90 |
| 96 | +--- |
| 97 | +``` |
| 98 | + |
| 99 | +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. |
| 100 | + |
| 101 | +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. |
| 102 | + |
| 103 | +## Verify |
| 104 | + |
| 105 | +After adding frontmatter to your docs (manually or via automation), run the index builder to confirm everything is wired correctly: |
| 106 | + |
| 107 | +```bash |
| 108 | +python scripts/agents/build-index.py |
| 109 | +``` |
| 110 | + |
| 111 | +Check the output in `AGENTS.md`: |
| 112 | + |
| 113 | +- Each doc should have a row in the index table with correct title, description, date, and status. |
| 114 | +- 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`). |
| 115 | + |
| 116 | +If you're using a virtual environment for Python dependencies, set it up first: |
| 117 | + |
| 118 | +```bash |
| 119 | +python -m venv .venv |
| 120 | +source .venv/bin/activate |
| 121 | +pip install -r requirements.txt |
| 122 | +``` |
| 123 | + |
| 124 | +## Nested directory structures |
| 125 | + |
| 126 | +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. |
| 127 | + |
| 128 | +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: |
| 129 | + |
| 130 | +```python |
| 131 | +# Default: one level up from docs/ -> repo root |
| 132 | +repo_root = os.path.dirname(docs_dir) |
| 133 | +
|
| 134 | +# Nested: two levels up from docs/guide/ -> repo root |
| 135 | +repo_root = os.path.dirname(os.path.dirname(docs_dir)) |
| 136 | +``` |
| 137 | + |
| 138 | +Without this fix, AGENTS.md links will have wrong relative paths (e.g., `guide/getting-started.md` instead of `docs/guide/getting-started.md`). |
| 139 | + |
| 140 | +## Troubleshooting |
| 141 | + |
| 142 | +**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. |
| 143 | + |
| 144 | +**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. |
| 145 | + |
| 146 | +**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. |
| 147 | + |
| 148 | +**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`: |
| 149 | + |
| 150 | +```yaml |
| 151 | +MD025: |
| 152 | + front_matter_title: "" |
| 153 | +``` |
| 154 | + |
| 155 | +**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`. |
| 156 | + |
| 157 | +**`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: |
| 158 | + |
| 159 | +```bash |
| 160 | +python -m venv .venv |
| 161 | +source .venv/bin/activate |
| 162 | +pip install -r requirements.txt |
| 163 | +``` |
| 164 | + |
| 165 | +**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: |
| 166 | + |
| 167 | +```yaml |
| 168 | +env: |
| 169 | + BEFORE_SHA: ${{ github.event.before }} |
| 170 | + AFTER_SHA: ${{ github.sha }} |
| 171 | +run: | |
| 172 | + FILES=$(git diff --name-only --diff-filter=AM "$BEFORE_SHA" "$AFTER_SHA" -- 'docs/*.md') |
| 173 | +``` |
0 commit comments