-
-
Notifications
You must be signed in to change notification settings - Fork 3
docs: ground GitHub topics in rankable agent-memory niches #268
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
tonyketcham
wants to merge
1
commit into
main
Choose a base branch
from
toeknee/github-topics-positioning-8777
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
9 changes: 9 additions & 0 deletions
9
...itations/cit-github-search-api-topic-counts-24-august-2026--m9s9pj2v1d5fad3p.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| id: cit-github-search-api-topic-counts-24-august-2026--m9s9pj2v1d5fad3p | ||
| effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz | ||
| title: 'GitHub Search API topic counts, 24 August 2026' | ||
| role: evidence | ||
| created_at: '2026-08-24T01:46:44.637Z' | ||
| --- | ||
|
|
||
| https://docs.github.com/en/rest/search/search#search-repositories — GET /search/repositories?q=topic:<name>&sort=stars. Counts and top-starred repos captured 2026-08-24 from this cloud-agent run against public GitHub. |
43 changes: 43 additions & 0 deletions
43
...sions/dec-use-twelve-github-topics-that-mix-demand-with-ra--67c632y486se7a9b.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| --- | ||
| id: dec-use-twelve-github-topics-that-mix-demand-with-ra--67c632y486se7a9b | ||
| effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz | ||
| title: Use twelve GitHub topics that mix demand with rankable niches | ||
| state: accepted | ||
| created_at: '2026-08-24T01:46:47.307Z' | ||
| derives_from: | ||
| - fnd-github-topic-pages-only-rank-flatbread-in-small--0p910vppn6z2nd3m | ||
| --- | ||
|
|
||
| Keep the GitHub About blurb **Context alignment, version controlled.** Put that same line on the README. Cut the live topic list from 20 implementation labels to 12 niches where Flatbread either already ranks, would rank at 64 stars, or is an honest demand filter for agent memory and file-based content. | ||
|
|
||
| Canonical list, About-sidebar order, stored in `.github/topics.json`: | ||
|
|
||
| 1. `agent-memory` | ||
| 2. `coding-agents` | ||
| 3. `context-engineering` | ||
| 4. `project-memory` | ||
| 5. `context-management` | ||
| 6. `agent-context` | ||
| 7. `llm-memory` | ||
| 8. `git-native` | ||
| 9. `markdown-cms` | ||
| 10. `git-cms` | ||
| 11. `file-based-cms` | ||
| 12. `docs-as-code` | ||
|
|
||
| Lead seven name the fragmented-context problem for coding agents. Trailing five name the Git/file publishing path (`markdown-cms` is already 1st of 13; `git-cms` is already 4th of 17; `file-based-cms` would be 2nd of 14). | ||
|
|
||
| Drop `ai-agents`, `markdown`, `javascript`, `typescript`, `nodejs`, `nextjs`, `yaml` (oceans), `graphql` / `graphql-codegen` (one read interface), `headless-cms` and `knowledge-graph` (true phrases, unwinnable pages), `agent-skills` (a skill is a channel, not the product), `local-first` / `knowledge-base` / `static-content` (wrong communities), and `mcp` / `rag` / `claude-code` (untrue). | ||
|
|
||
| GitHub does not read `.github/topics.json`. A repo admin applies it with `gh api -X PUT repos/FlatbreadLabs/flatbread/topics --input .github/topics.json`. npm `keywords` on the public `flatbread` package mirror the twelve, plus `markdown` and `knowledge-graph` for npm search. | ||
|
|
||
| ## Alternatives considered | ||
|
|
||
| - **Handoff ten:** `ai-agents`, `agent-memory`, `agent-context`, `coding-agents`, `knowledge-graph`, `context-management`, `git-native`, `markdown`, `git-cms`, `headless-cms`. Rejected as-is: it drops `markdown-cms` (already 1st), skips `context-engineering` and `project-memory` / `file-based-cms` (rankable or high-demand), and keeps oceans `ai-agents` / `markdown` plus unwinnable `headless-cms` / `knowledge-graph`. | ||
| - **Keep all 20 current topics.** Rejected: GitHub caps at 20, so every ocean crowds out a niche we can actually win. | ||
| - **Only rankable tags** (`markdown-cms`, `git-cms`, `git-native`, `file-based-cms`, `agent-context`, `project-memory`). Rejected: people searching `agent-memory` never see the repo. | ||
| - **Change the tagline** to a longer two-path slogan. Rejected: the short line already names the problem; the README table explains the two paths. | ||
|
|
||
| ## Reversal criteria | ||
|
|
||
| Revisit when stars cross a few hundred (demand-topic pages become reachable), when a new surface ships and a tag becomes true (MCP, hosted search), or when `markdown-cms` / `git-cms` stop matching how searchers name the publishing path. |
43 changes: 43 additions & 0 deletions
43
...ndings/fnd-github-topic-pages-only-rank-flatbread-in-small--0p910vppn6z2nd3m.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,43 @@ | ||
| --- | ||
| id: fnd-github-topic-pages-only-rank-flatbread-in-small--0p910vppn6z2nd3m | ||
| effort: eff-flatbread-product-branding--zt7b35sa05kyvhdz | ||
| title: GitHub topic pages only rank Flatbread in small niches | ||
| kind: measurement | ||
| created_at: '2026-08-24T01:46:46.012Z' | ||
| cites: | ||
| - cit-github-search-api-topic-counts-24-august-2026--m9s9pj2v1d5fad3p | ||
| --- | ||
|
|
||
| GitHub topic pages sort by stars. FlatbreadLabs/flatbread had 64 stars on 24 August 2026. The live repo had 20 topics, many of them implementation labels (javascript, nodejs, graphql, nextjs). | ||
|
|
||
| Search method: GitHub REST `GET /search/repositories?q=topic:<name>&sort=stars`. | ||
|
|
||
| Current ranks where Flatbread is already tagged: | ||
|
|
||
| - markdown-cms: 13 repos, Flatbread is 1st (next is 50 stars). | ||
| - git-cms: 17 repos, Flatbread is 4th after nuxt/content (3661), plentico/plenti (1076), sitepins/sitepins (154). | ||
| - git-native: 59 repos, Flatbread is 6th. | ||
|
|
||
| Niches not currently tagged where 64 stars would still show: | ||
|
|
||
| - file-based-cms: 14 repos; current 2nd has 35 stars, so Flatbread would be 2nd. | ||
| - project-memory: 154 repos; top repo has 497 stars; 64 stars should make the first page. | ||
| - agent-context: 77 repos; after pingcap/tidb (a 40k-star noise tag) the next repos are 1370, 469, 188, 107, 83, 72, 59. 64 stars should show. | ||
|
|
||
| Demand topics people search, but we will not rank yet: | ||
|
|
||
| - agent-memory: 2958 repos, top ~71k stars. | ||
| - coding-agents: 3244 repos, top ~90k stars. | ||
| - context-engineering: 2773 repos, top is a Java guide wearing the tag (~158k). | ||
| - context-management: 1321 repos, top ~89k stars. | ||
| - llm-memory: 451 repos, top ~15k stars. | ||
| - docs-as-code: 368 repos, top ~3.7k stars. | ||
| - headless-cms: 1667 repos, Strapi 73k. Real CMS traffic, no rank chance at 64 stars. | ||
|
|
||
| Oceans that hide a 64-star repo: ai-agents 77078, markdown 37339, javascript 670087, typescript 413824, nodejs 333467, nextjs 178931. | ||
|
|
||
| Empty vanity tags (single-digit repo counts, no searchers): context-alignment, durable-memory, markdown-database. | ||
|
|
||
| Dishonest until we ship the surface: mcp (65155), rag (42198), graph-rag (349), claude-code (63170). | ||
|
|
||
| This is a measurement of discovery supply and current rank, not of product fit alone. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| { | ||
| "names": [ | ||
| "agent-memory", | ||
| "coding-agents", | ||
| "context-engineering", | ||
| "project-memory", | ||
| "context-management", | ||
| "agent-context", | ||
| "llm-memory", | ||
| "git-native", | ||
| "markdown-cms", | ||
| "git-cms", | ||
| "file-based-cms", | ||
| "docs-as-code" | ||
| ] | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,46 @@ | ||
| import test from 'ava'; | ||
| import { readFileSync } from 'node:fs'; | ||
| import path from 'node:path'; | ||
| import { fileURLToPath } from 'node:url'; | ||
|
|
||
| const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..'); | ||
|
|
||
| function readRepo(rel) { | ||
| return readFileSync(path.join(root, rel), 'utf8'); | ||
| } | ||
|
|
||
| const TOPIC_NAME = /^[a-z0-9](?:[a-z0-9-]{0,48}[a-z0-9])?$/; | ||
| const APPLY_PAYLOAD = JSON.parse(readRepo('.github/topics.json')); | ||
|
|
||
| test('GitHub topics payload is a names list GitHub will accept', (t) => { | ||
| t.deepEqual(Object.keys(APPLY_PAYLOAD).sort(), ['names']); | ||
| t.true(Array.isArray(APPLY_PAYLOAD.names)); | ||
| t.true(APPLY_PAYLOAD.names.length >= 8); | ||
| t.true(APPLY_PAYLOAD.names.length <= 20); | ||
| t.is(new Set(APPLY_PAYLOAD.names).size, APPLY_PAYLOAD.names.length); | ||
|
|
||
| for (const name of APPLY_PAYLOAD.names) { | ||
| t.regex(name, TOPIC_NAME); | ||
| t.false(name.includes('--')); | ||
| } | ||
| }); | ||
|
|
||
| test('positioning docs, README tagline, and npm keywords use the same topic set', (t) => { | ||
| const positioning = readRepo('docs/positioning.md'); | ||
| const readme = readRepo('packages/flatbread/README.md'); | ||
| const pkg = JSON.parse(readRepo('packages/flatbread/package.json')); | ||
|
|
||
| t.true(readme.includes('Context alignment, version controlled.')); | ||
| t.true(Array.isArray(pkg.keywords)); | ||
|
|
||
| for (const name of APPLY_PAYLOAD.names) { | ||
| t.true( | ||
| positioning.includes('`' + name + '`'), | ||
| `docs/positioning.md must name ${name}` | ||
| ); | ||
| t.true( | ||
| pkg.keywords.includes(name), | ||
| `flatbread keywords must include ${name}` | ||
| ); | ||
| } | ||
| }); | ||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Topic sync test false positives
Low Severity
The positioning sync check only looks for a backticked topic name anywhere in
docs/positioning.md. The dropped-topics table already repeats several live niche names in backticks, so a topic can vanish from the canonical table—or a rejected topic can be added to.github/topics.json—and the test still passes.Additional Locations (1)
docs/positioning.md#L89-L98Reviewed by Cursor Bugbot for commit b0d27ed. Configure here.