Skip to content

Commit ad29694

Browse files
SutuSebastianSutuSebastian
authored
chore: npm agent templates vs dev .agents, patch changeset (#6)
* chore: split npm agent templates from dev .agents, add patch changeset - templates/agents: npm-friendly codemap rule/skill; drop agents-first-convention template - .agents: dev-oriented CLI examples (bun src/index.ts) - docs: clarify templates vs repo .agents; templates README * docs: clarify consumer .agents in index; fix template rule doc links - docs/README.md: consumer vs dev .agents in index and single-source table - templates/agents/rules/codemap.mdc: ../../../docs/... from rules/ subdir
1 parent fa7d77d commit ad29694

9 files changed

Lines changed: 76 additions & 96 deletions

File tree

‎.agents/rules/codemap.mdc‎

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,18 @@ alwaysApply: true
88

99
A local database (default **`.codemap.db`**) indexes structure: symbols, imports, exports, components, dependencies, markers, CSS variables, CSS classes, CSS keyframes.
1010

11-
**Generic defaults:** This rule is **project-agnostic**. After you vendor or symlink it (or use a future `codemap` CLI that writes agent files), **edit your copy** to add app-specific triggers and SQL — upstream text is only a baseline.
11+
**This file** is for **developing Codemap** in this clone. **End users** of the published package get the agent rule from **`templates/agents/`** (via **`codemap agents init`**). **Generic defaults:** SQL and triggers stay project-agnostic — **edit** this rule for repo-specific paths and queries.
1212

13-
## CLI (this repo vs installed package)
13+
## CLI (this repository)
1414

1515
| Context | Incremental index | Query |
1616
| ------- | ----------------- | ----- |
17-
| Developing in this repo | `bun src/index.ts` | `bun src/index.ts query "<SQL>"` |
18-
| After `bun link` / global `codemap` | `codemap` | `codemap query "<SQL>"` |
19-
| Published package (when available) | `bunx @stainless-code/codemap` | `bunx @stainless-code/codemap query "<SQL>"` |
17+
| **Default** — from this clone | `bun src/index.ts` | `bun src/index.ts query "<SQL>"` |
18+
| Same entry | `bun run dev` | (same as first row) |
2019

21-
Index another project: **`--root /path/to/repo`**, or set **`CODEMAP_ROOT`** or **`CODEMAP_TEST_BENCH`** (e.g. in **`.env`** in this repo — see [docs/benchmark.md § Indexing another project](../../docs/benchmark.md#indexing-another-project)). Full rebuild: **`--full`**. Targeted re-index: **`--files path/to/a.ts path/to/b.tsx`**.
20+
After **`bun run build`**, **`node dist/index.mjs`** matches the published **`codemap`** binary (same flags). **`bun link`** / global **`codemap`** also work when testing the packaged CLI.
21+
22+
Index another project: **`--root /path/to/repo`**, or set **`CODEMAP_ROOT`** or **`CODEMAP_TEST_BENCH`** (e.g. in **`.env`** — see [docs/benchmark.md § Indexing another project](../../docs/benchmark.md#indexing-another-project)). Full rebuild: **`--full`**. Targeted re-index: **`--files path/to/a.ts path/to/b.tsx`**.
2223

2324
## Session start (do this ONCE per conversation)
2425

‎.agents/skills/codemap/SKILL.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,15 +6,15 @@ Query codebase structure via SQLite instead of scanning files. Use when explorin
66

77
Examples below use **placeholders** (`'...'`, `getConfig`, `~/lib/api`, etc.) — not a real product tree. **Shipped skill and rules stay generic** so they apply to any repo.
88

9-
**In your project:** copy or symlink these files into `.agents/` / `.cursor/` (see **`.github/CONTRIBUTING.md`**), or use a future **`codemap` CLI** that vendors agent files. Then **edit your copy** to add your team’s tsconfig aliases, directory conventions, and SQL snippets you reuse. Treat upstream updates as a reference; merge deliberately.
9+
**This repository:** run the CLI with **`bun src/index.ts`** (same as **`bun run dev`**). **Consumer / npm** copy of this skill lives under **`templates/agents/skills/codemap/`** (installed with **`codemap agents init`**). Edit **`.agents/`** here for Codemap development; **do not** treat it as the published package layout.
1010

11-
**Run queries**
11+
**Run queries:**
1212

1313
```bash
1414
bun src/index.ts query "<SQL>"
1515
```
1616

17-
When the package is installed globally or via `bunx`: `codemap query "<SQL>"` or `bunx @stainless-code/codemap query "<SQL>"`. Use **`--root`** to point at another project.
17+
After **`bun run build`**, **`node dist/index.mjs query …`** or a linked **`codemap`** binary matches the published CLI. Use **`--root`** / **`CODEMAP_ROOT`** to index another tree.
1818

1919
## Schema
2020

@@ -282,7 +282,7 @@ SELECT kind, COUNT(*) as count FROM markers GROUP BY kind;
282282

283283
## Maintenance
284284

285-
From this repository:
285+
From this repository (same flags as the published **`codemap`** binary):
286286

287287
```bash
288288
# Targeted — re-index only specific files you just modified
@@ -300,13 +300,13 @@ bun src/index.ts query "SELECT key, value FROM meta"
300300

301301
**Prefer `--files`** when you know which files you changed — it skips git diff and filesystem scanning for the rest of the tree. Deleted files passed to `--files` are auto-removed from the index.
302302

303-
When Codemap is installed as a package: `codemap`, `codemap --root /path/to/project`, or `bunx @stainless-code/codemap …` (same flags).
303+
**End-user / npm** commands: **`templates/agents/skills/codemap/SKILL.md`** ( **`npx @stainless-code/codemap`**, **`codemap`** on **`PATH`**, etc.).
304304

305305
## Troubleshooting
306306

307307
| Problem | Solution |
308308
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
309-
| Stale results after rebase | Run `bun src/index.ts --full` (or `codemap --full` when installed) |
309+
| Stale results after rebase | Run **`bun src/index.ts --full`** (or **`codemap --full`** when exercising the packaged CLI) |
310310
| Missing file in results | Check exclude / include globs in **`codemap.config.ts`**, **`codemap.config.json`**, or defaults in **`src/index.ts`** |
311311
| `resolved_path` is NULL | Import is an external package (not in project) |
312312
| Resolver errors | Verify `tsconfig.json` paths (or **`tsconfigPath`** in config) when resolving aliases |

‎.changeset/agent-templates-npm-dev-split.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
"@stainless-code/codemap": patch
3+
---
4+
5+
Align shipped agent templates with the published CLI (`codemap`, `npx @stainless-code/codemap`, …). Keep this repository’s `.agents/` rule and skill dev-oriented (`bun src/index.ts`). Remove the redundant `agents-first-convention` template. Document the dev vs `templates/agents/` split in `templates/agents/README.md` and `docs/agents.md`.

‎docs/README.md‎

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -4,24 +4,24 @@ Technical docs for **[@stainless-code/codemap](https://github.com/stainless-code
44

55
**Start here:** [../README.md](../README.md) (install, CLI, API, dev commands). **This folder** is deeper reference — pick a row below.
66

7-
| File | Topic |
8-
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9-
| [why-codemap.md](./why-codemap.md) | Why index + SQL for agents (speed, tokens, accuracy) — good first read after the readme |
10-
| [architecture.md](./architecture.md) | Schema, layering, CLI internals, API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files) |
11-
| [agents.md](./agents.md) | **`codemap agents init`** — granular **`templates/agents`** → **`.agents/`**, per-file IDE symlink/copy, **[pointer files](./agents.md#pointer-files)** (`codemap-pointer` markers), **`--interactive`**, **`.gitignore` / `.codemap.*`** |
12-
| [benchmark.md](./benchmark.md) | [**Indexing another project**](./benchmark.md#indexing-another-project) · [**Benchmark script**](./benchmark.md#the-benchmark-script) · [`fixtures/minimal/`](../fixtures/minimal/) |
13-
| [packaging.md](./packaging.md) | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets) |
14-
| [roadmap.md](./roadmap.md) | Forward-looking backlog (not a `src/` inventory) |
7+
| File | Topic |
8+
| ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9+
| [why-codemap.md](./why-codemap.md) | Why index + SQL for agents (speed, tokens, accuracy) — good first read after the readme |
10+
| [architecture.md](./architecture.md) | Schema, layering, CLI internals, API, [**User config**](./architecture.md#user-config) (Zod), parsers, [Key Files](./architecture.md#key-files) |
11+
| [agents.md](./agents.md) | **`codemap agents init`** — bundled **`templates/agents`** → **`.agents/`** in **consumer projects** (this repo’s **`.agents/`** is dev/maintainer — see [agents.md](./agents.md)); per-file IDE symlink/copy, **[pointer files](./agents.md#pointer-files)** (`codemap-pointer`), **`--interactive`**, **`.gitignore` / `.codemap.*`** |
12+
| [benchmark.md](./benchmark.md) | [**Indexing another project**](./benchmark.md#indexing-another-project) · [**Benchmark script**](./benchmark.md#the-benchmark-script) · [`fixtures/minimal/`](../fixtures/minimal/) |
13+
| [packaging.md](./packaging.md) | **`CHANGELOG.md` / `dist/` / `templates/`** on npm, **engines**, [**Node vs Bun**](./packaging.md#node-vs-bun), [**Releases**](./packaging.md#releases) (Changesets) |
14+
| [roadmap.md](./roadmap.md) | Forward-looking backlog (not a `src/` inventory) |
1515

1616
## Single source of truth (do not duplicate)
1717

18-
| Topic | Canonical doc | Elsewhere |
19-
| ------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
20-
| Runtime splits (SQLite, workers, globs, JSON config I/O) | [packaging § Node vs Bun](./packaging.md#node-vs-bun) — **the table lives here** | [architecture § Runtime](./architecture.md#runtime-and-database) links here; do not copy the table |
21-
| **`codemap.config.*`** shape / Zod validation | [architecture § User config](./architecture.md#user-config) | Root [README § Configuration](../README.md#configuration) points here |
22-
| **`codemap agents init`**: **`--force`** on **`.agents/`** (template file paths only), IDE matrix, per-file symlink/copy, **`templates/agents`** | [agents.md](./agents.md) | Link here; do not paste the integration table into README or packaging |
23-
| **`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / Copilot** — managed **`codemap-pointer`** sections, merge vs **`--force`** | [agents.md § Pointer files](./agents.md#pointer-files) | Link here; do not duplicate the situation table |
24-
| End-user CLI (index, query, agents, flags, env) | [../README.md § CLI](../README.md#cli) | [architecture § CLI usage](./architecture.md#cli-usage) summarizes and links back |
18+
| Topic | Canonical doc | Elsewhere |
19+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
20+
| Runtime splits (SQLite, workers, globs, JSON config I/O) | [packaging § Node vs Bun](./packaging.md#node-vs-bun) — **the table lives here** | [architecture § Runtime](./architecture.md#runtime-and-database) links here; do not copy the table |
21+
| **`codemap.config.*`** shape / Zod validation | [architecture § User config](./architecture.md#user-config) | Root [README § Configuration](../README.md#configuration) points here |
22+
| **`codemap agents init`**: **`--force`** on **`.agents/`** in **consumer projects** (template file paths only), IDE matrix, per-file symlink/copy, **`templates/agents`** | [agents.md](./agents.md) | Link here; do not paste the integration table into README or packaging |
23+
| **`CLAUDE.md` / `AGENTS.md` / `GEMINI.md` / Copilot** — managed **`codemap-pointer`** sections, merge vs **`--force`** | [agents.md § Pointer files](./agents.md#pointer-files) | Link here; do not duplicate the situation table |
24+
| End-user CLI (index, query, agents, flags, env) | [../README.md § CLI](../README.md#cli) | [architecture § CLI usage](./architecture.md#cli-usage) summarizes and links back |
2525

2626
## Conventions
2727

‎docs/agents.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44

55
## What it does
66

7-
The published package ships **`templates/agents/`** (rules + skills; mirrored in this repo under [`.agents/`](../.agents/)). The command **`codemap agents init`** writes each bundled file into **`<project>/.agents/`** with per-file copies (not a wholesale directory sync) — the **canonical** copy consumers edit (SQL, team conventions, paths).
7+
The published package ships **`templates/agents/`** (rules + skills). This repo also has [`.agents/`](../.agents/) for **Codemap development** (CLI from source); it is **not** identical to **`templates/agents/`** for every file (e.g. the **codemap** rule/skill). The command **`codemap agents init`** writes each bundled template file into **`<project>/.agents/`** with per-file copies (not a wholesale directory sync) — the **canonical** copy consumers edit (SQL, team conventions, paths).
88

99
```bash
1010
codemap agents init

‎templates/agents/README.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
# Bundled agent templates
22

3-
These files are **copies** of the upstream [`.agents/`](../../.agents/) rules and skills shipped with **`@stainless-code/codemap`** for **`codemap agents init`**.
3+
These files ship with **`@stainless-code/codemap`** for **`codemap agents init`** — written for **npm consumers** ( **`codemap`**, **`npx @stainless-code/codemap`**, etc.).
4+
5+
In **this** repository, **`.agents/`** (and **`.cursor/`** symlinks) are **maintainer / dev** copies: examples use **`bun src/index.ts`** where that matters. **`templates/agents/`** is the **published** agent surface and is **not** required to match **`.agents/`** byte-for-byte (the **codemap** rule and skill intentionally differ).
46

57
**Documentation:** [docs/agents.md](../../docs/agents.md) — interactive setup, **`.gitignore`**, and optional IDE wiring (Cursor, Copilot, …).
68

7-
After running the command, **edit** `.agents/` in your project (paths, SQL, team conventions). Treat updates here as a reference when refreshing your copy.
9+
After running the command in **your** project, **edit** **`.agents/`** there (paths, SQL, team conventions). Treat updates here as a reference when refreshing your copy.

‎templates/agents/rules/agents-first-convention.mdc‎

Lines changed: 0 additions & 37 deletions
This file was deleted.

0 commit comments

Comments
 (0)