You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(agents): align bundled rule + skill with Tier A flags + visibility column (#29)
## Summary
The recent merges to `main` shipped:
- **Tier A query flags** (PR #26): `--summary`, `--changed-since <ref>`, `--group-by owner|directory|package`, plus per-row recipe `actions`.
- **B.7 — `symbols.visibility` column** (PR #28).
But the bundled `templates/agents/` rule + skill (the surface installed by `codemap agents init`) didn't reference any of them. Agents installed downstream would have a stale view of the CLI surface and miss the structured-column path for visibility queries. This PR aligns four files in lockstep:
| File | Audience |
| --- | --- |
| `templates/agents/rules/codemap.md` | **Ships to npm** — installed by `codemap agents init` |
| `templates/agents/skills/codemap/SKILL.md` | **Ships to npm** |
| `.agents/rules/codemap.md` | This repo's dev mirror (so my own session view stays accurate) |
| `.agents/skills/codemap/SKILL.md` | Same |
## Per-rule edits
- New CLI table rows for `--summary`, `--changed-since`, `--group-by` (with example commands).
- One-liner about per-row recipe `actions` (json + recipe only; ad-hoc SQL never carries them).
- New trigger pattern row: questions about `@internal` / `@beta` / `@alpha` / `@private` route to **`symbols.visibility`** (the parsed JSDoc tag) rather than `doc_comment LIKE '%@beta%'`.
- New quick-reference query for visibility.
## Per-skill edits
- New `symbols.visibility` row in the schema table.
- Two new query examples in the **Basic lookups** block: `WHERE visibility IS NOT NULL` and `WHERE visibility = 'beta'`.
- New **Output flags** subsection covering `--summary` / `--changed-since` / `--group-by` / per-row `actions`.
- Recipe id list extended with `deprecated-symbols`, `visibility-tags`, `barrel-files`, `files-hashes` (already shipped via earlier PRs but never enumerated in the skill).
## Why patch (not minor)
`templates/agents/` is the only ship-affecting surface here. The column + flags themselves were released by their respective minor / patch changesets earlier on main. Per `.agents/lessons.md` "changesets bump policy (pre-v1)", docs / template churn defaults to patch.
## Test plan
- [x] `bun run check` passes locally (build, format:check, lint:ci, test, typecheck, test:golden — 19/19 golden scenarios green).
- [x] Diff between dev mirror (`.agents/`) and shipped templates (`templates/agents/`) confirmed to differ only on the CLI-prefix prose (`bun src/index.ts` vs `codemap`) — same content otherwise.
- [ ] CI green.
Copy file name to clipboardExpand all lines: .agents/lessons.md
+1Lines changed: 1 addition & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,3 +9,4 @@ Each entry is a single bullet: `- **<topic>** — <lesson>`. Newest entries at t
9
9
## Lessons
10
10
11
11
-**changesets bump policy (pre-v1)** — while in `0.x`, default to **patch** for everything (additive features, fixes, docs, internal refactors); reserve **minor** for schema-breaking changes that force a `.codemap.db` rebuild (matches 0.2.0 precedent: new tables/columns/`SCHEMA_VERSION` bump). Strict SemVer kicks in only after `1.0.0`. Don't propose `minor` just because new CLI commands or public types were added.
12
+
-**agent rule + skill maintenance** — when shipping a CLI flag, recipe id, recipe `actions` template, schema column, or any agent-queryable surface, update **both** copies of the codemap rule + skill in the **same PR** per [docs/README.md Rule 10](../docs/README.md): `templates/agents/rules/codemap.md` + `templates/agents/skills/codemap/SKILL.md` (ships to npm) **and**`.agents/rules/codemap.md` + `.agents/skills/codemap/SKILL.md` (this clone's mirror). Drift between the two pairs should be CLI-prefix-only (`codemap` vs `bun src/index.ts`). Forgetting this leaves installed agents with a stale view of the CLI — that's how `--summary` / `--changed-since` / `--group-by` / `actions` / `symbols.visibility` shipped without any `templates/agents/` mention until PR #29 retro-fixed it.
| Bucket by owner / dir / pkg | — |`bun src/index.ts query --json --group-by directory -r fan-in`|
25
+
26
+
**Recipe `actions`:** with **`--json`**, recipes that define an `actions` template append it to every row (kebab-case verb + description — e.g. `fan-out` → `review-coupling`). Inspect via **`--recipes-json`**. Ad-hoc SQL never carries actions.
22
27
23
28
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.
24
29
@@ -58,6 +63,7 @@ If the question looks like any of these → use the index:
Copy file name to clipboardExpand all lines: .agents/skills/codemap/SKILL.md
+31-16Lines changed: 31 additions & 16 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -34,7 +34,14 @@ After **`bun run build`**, **`node dist/index.mjs query …`** or a linked **`co
34
34
35
35
Replace placeholders (`'...'`) with your module path, file glob, or symbol name.
36
36
37
-
**CLI shortcuts:****`bun src/index.ts query --json --recipe <id>`** runs bundled SQL (preferred for agents). **`bun src/index.ts query --recipe <id>`** without **`--json`** prints a table. **`bun src/index.ts query --recipes-json`** prints every bundled recipe (**`id`**, **`description`**, **`sql`**) as JSON (no index / DB required). **`bun src/index.ts query --print-sql <id>`** prints one recipe’s SQL only. Ids include **`fan-out`**, **`fan-out-sample`** (**`GROUP_CONCAT`** samples), **`fan-out-sample-json`** (same, but **`json_group_array`** — needs SQLite JSON1), **`fan-in`**, **`index-summary`**, **`files-largest`**, **`components-by-hooks`**, **`markers-by-kind`** — see **`bun src/index.ts query --help`**.
37
+
**CLI shortcuts:****`bun src/index.ts query --json --recipe <id>`** runs bundled SQL (preferred for agents). **`bun src/index.ts query --recipe <id>`** without **`--json`** prints a table. **`bun src/index.ts query --recipes-json`** prints every bundled recipe (**`id`**, **`description`**, **`sql`**, optional **`actions`**) as JSON (no index / DB required). **`bun src/index.ts query --print-sql <id>`** prints one recipe’s SQL only. Ids include **`fan-out`**, **`fan-out-sample`** (**`GROUP_CONCAT`** samples), **`fan-out-sample-json`** (same, but **`json_group_array`** — needs SQLite JSON1), **`fan-in`**, **`index-summary`**, **`files-largest`**, **`components-by-hooks`**, **`markers-by-kind`**, **`deprecated-symbols`**, **`visibility-tags`**, **`barrel-files`**, **`files-hashes`** — see **`bun src/index.ts query --help`**.
38
+
39
+
**Output flags** (compose with **`--recipe`** or ad-hoc SQL):
40
+
41
+
-**`--summary`** — counts only. With **`--json`**: **`{"count": N}`**. With **`--group-by`**: **`{"group_by": "<mode>", "groups": [{key, count}]}`**.
42
+
-**`--changed-since <ref>`** — post-filter rows by **`path`** / **`file_path`** / **`from_path`** / **`to_path`** / **`resolved_path`** against **`git diff --name-only <ref>...HEAD ∪ git status --porcelain`**. Rows with no recognised path column pass through.
43
+
-**`--group-by owner|directory|package`** — partition into buckets and emit **`{"group_by", "groups": [{key, count, rows}]}`**. **`owner`** reads CODEOWNERS (last matching rule wins); **`directory`** is the first path segment; **`package`** uses **`package.json`****`workspaces`** or **`pnpm-workspace.yaml`**.
44
+
-**Per-row recipe `actions`** — recipes that define an **`actions: [{type, auto_fixable?, description?}]`** template append it to every row in **`--json`** output (recipe-only; ad-hoc SQL never carries actions). Inspect via **`--recipes-json`**.
38
45
39
46
**Determinism:** Bundled recipes use stable secondary **`ORDER BY`** tie-breakers (and ordered inner **`LIMIT`** samples where applicable). Prefer **`--recipe`** over pasting SQL when you need the maintained ordering. **Canonical SQL** is **`src/cli/query-recipes.ts`** (`QUERY_RECIPES`).
| kind | TEXT |`function`, `class`, `type`, `interface`, `enum`, `const`|
98
+
| line_start | INTEGER | Start line (1-based) |
99
+
| line_end | INTEGER | End line (1-based) |
100
+
| signature | TEXT | Reconstructed signature with generics and return types |
101
+
| is_exported | INTEGER | 1 if exported |
102
+
| is_default_export | INTEGER | 1 if default export |
103
+
| members | TEXT | JSON enum members (NULL for non-enums) |
104
+
| doc_comment | TEXT | Leading JSDoc text (cleaned), NULL when absent |
105
+
| value | TEXT | Literal value for consts (`"ok"`, `42`, `true`, `null`) |
106
+
| parent_name | TEXT | Enclosing symbol name (class/function), NULL = top-level |
107
+
| visibility | TEXT | Line-leading JSDoc tag: `public` / `private` / `internal` / `alpha` / `beta`; NULL when absent. First match in document order wins |
100
108
101
109
### `calls` — Function-scoped call edges (deduped per file)
102
110
@@ -233,6 +241,13 @@ WHERE symbol_name = 'UserSession';
233
241
SELECT name, kind, file_path, doc_comment FROM symbols
234
242
WHERE doc_comment LIKE'%@deprecated%';
235
243
244
+
-- Visibility-tagged symbols (parsed JSDoc tag — single column, no regex)
245
+
SELECT name, kind, visibility, file_path
246
+
FROM symbols WHERE visibility IS NOT NULLORDER BY visibility, file_path;
247
+
248
+
-- Just the @beta surface (filter on the parsed tag, not doc_comment LIKE)
249
+
SELECT name, kind, file_path FROM symbols WHERE visibility ='beta';
250
+
236
251
-- Symbol documentation
237
252
SELECT name, signature, doc_comment FROM symbols
238
253
WHERE name ='formatCurrency'AND doc_comment IS NOT NULL;
Update bundled `templates/agents/` rule and skill to cover the recent CLI surface — `codemap query --summary` / `--changed-since <ref>` / `--group-by owner|directory|package`, per-row recipe `actions`, and the new `symbols.visibility` column. The dev-side `.agents/` mirror is updated in lockstep so this clone stays self-consistent.
Copy file name to clipboardExpand all lines: docs/README.md
+4Lines changed: 4 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -39,6 +39,10 @@ These rules are normative — cite them by number in PR review. Ordered by how o
39
39
7.**No line-number references** — line numbers (e.g. `parser.ts:241`) rot on every edit. Reference by function name, section heading, or symbol from `codemap query` instead. Methodology tables in [benchmark.md](./benchmark.md) are exempt.
40
40
8.**Research notes get closed** — when a research scan's adopt items ship, slim the note to a "What shipped" appendix linking to canonical homes (see [research/competitive-scan-2026-04.md](./research/competitive-scan-2026-04.md) as the precedent). Rejected items keep a `Status: Rejected (date) — <one-line reason>` header.
41
41
9.**New term ⇒ update [glossary.md](./glossary.md) in the same PR** — when a PR introduces a new domain noun / verb / acronym (table name, recipe id, parser name, schema column), add or update its entry. Disambiguations (e.g. `FileRow` TS shape vs `files` SQLite table) take priority over single defs.
42
+
10.**Core surface change ⇒ update bundled agent rule + skill in the same PR** — when a PR adds / changes a CLI flag, recipe id, recipe `actions` template, schema column, or any other surface an agent would query, update **both** copies of the codemap rule + skill so installed agents and this clone stay in lockstep:
43
+
-**`templates/agents/rules/codemap.md`** + **`templates/agents/skills/codemap/SKILL.md`** (ships to npm via `codemap agents init`).
44
+
-**`.agents/rules/codemap.md`** + **`.agents/skills/codemap/SKILL.md`** (this clone's dev-side mirror — keeps my own session view of the CLI accurate).
45
+
Drift between the two pairs should be **CLI-prefix-only** (`codemap` vs `bun src/index.ts`) — anything else means content has diverged. Schema-version bumps and new recipes are the most common trigger; output flags (e.g. `--summary`, `--changed-since`, `--group-by`) come second. Patch changeset suffices when the underlying feature already shipped its own changeset (templates/agents/ is the only ship-affecting surface in such a PR).
Copy file name to clipboardExpand all lines: docs/agents.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -6,6 +6,8 @@
6
6
7
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).
8
8
9
+
**Maintenance discipline:** Core CLI / schema / recipe changes must update **both** copies of the codemap rule + skill in the same PR — see [README.md Rule 10](./README.md). Drift between `templates/agents/` and `.agents/` should be CLI-prefix-only (`codemap` vs `bun src/index.ts`).
10
+
9
11
**Query examples** in the bundled **codemap** rule and skill lead with **`codemap query --json`** (agents and automation). Omit **`--json`** when you want **`console.table`** in a terminal — see [README.md § CLI](../README.md#cli).
| Bucket by owner / dir / pkg |`codemap query --json --group-by directory -r fan-in`|
32
+
33
+
**Recipe `actions`:** with **`--json`**, recipes that define an `actions` template append it to every row (kebab-case verb + description — e.g. `fan-out` → `review-coupling`). Inspect via **`--recipes-json`**. Ad-hoc SQL never carries actions.
29
34
30
35
**Bundled rules/skills:****`codemap agents init`** writes **`.agents/`** from the package (see [docs/agents.md](../../../docs/agents.md)).
31
36
@@ -67,6 +72,7 @@ If the question looks like any of these → use the index:
0 commit comments