agent-source-repository 0.1.0

Agent Source Repository local context registry for coding agents
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

# Agent Instructions

Use ASR first when a repository is registered. Use local shell search only as a
direct fallback for unregistered paths or one-off local searches.

Before broad source reads, run:

```bash
asr repo status <repo> --json
asr repo index <repo> --json
asr context "<task>" --repo <repo> --budget 4000 --json
```

Then read only returned file ranges:

```bash
asr read <repo> src/example.rs --lines 10:80 --json
```

If context is insufficient, narrow with ASR before any wider scan:

```bash
asr search "payment retry backoff" --repo <repo> --top-k 8 --json
asr deps <repo> src/payments/retry.ts --json
asr impact <repo> src/payments/retry.ts --json
asr diff <repo> --base HEAD~1 --head HEAD --json
asr verify <repo> --json
```

## Editing Contract

ASR owns the indexed source path for agent work. The agent must edit the same
checkout that ASR indexed.

If Forgejo stores the canonical repository, treat Forgejo as the code vault and
ASR as the checkout/index owner:

```txt
Forgejo bare repo -> ASR-selected checkout -> ASR index -> agent edits same checkout
```

Do not edit a different local copy after using ASR results from another path.
After source changes, run:

```bash
asr repo index <repo> --json
```

Bare repositories may be registered for source discovery, but editing requires a
checkout. See [docs/forgejo-workflow.md](docs/forgejo-workflow.md).

## Local Search Fallback

- Use `rg` only when ASR is unavailable or the target path is not registered.
- Prefer exact symbols, filenames, or domain terms before broad text scans.
- Broaden to full-file reads only after ASR or narrow `rg` results are
  insufficient.