CLAUDE.md

1# Claude Code Repos Index - Repository Instructions
2 
3## Purpose
4 
5This repository serves as a curated index of agent workspace blueprints and Claude Code-related resources shared on GitHub. It provides organized, categorized listings with descriptions to help users discover relevant tools, templates, and configurations for agentic AI workflows.
6 
7Many of the repositories in this index are **agent workspaces** — pre-configured repository environments designed for structured, domain-specific agentic AI workflows. This pattern, which I originally called "Claude Spaces," uses repository structure, context files, and Claude Code's built-in features to create effective AI work environments that go far beyond traditional codebases.
8 
9## Repository Structure
10 
11- **`README.md`**: Main index displaying all repositories (auto-generated from category files)
12- **`categories/`**: Individual category files that are concatenated to build README.md
13- **`scratchpad.md`**: Staging area for new repositories to be added to the index
14- **`scripts/build_readme.py`**: Script to regenerate README.md from category files
15- **`scripts/build_site.py`**: Unified build pipeline (README + repos.json + tagged_repos.json + site state tracking)
16- **`scripts/update_repo_tracking.py`**: Script to update repo counts and repos.json
17- **`data/repos.json`**: Programmatic representation of the index (category-based)
18- **`data/tag_rules.json`**: Auto-tagging rules mapping categories and keywords to tags
19- **`data/site_state.json`**: Tracks what has been deployed to the site (repo manifest, change history)
20- **`docs/`**: Astro build output (deployed via GitHub Pages)
21- **`images/`**: Category banner images
22 
23## Astro Site Architecture
24 
25The deployed site is built with **Astro** (static site generator). Source files live in `src/`:
26 
27- **`src/layouts/BaseLayout.astro`**: Shared HTML shell (head, fonts, CSS import)
28- **`src/components/Nav.astro`**: Shared top navigation (single source of truth)
29- **`src/components/Footer.astro`**: Shared footer
30- **`src/styles/global.css`**: All site styles
31- **`src/data/categoryIcons.ts`**: Shared category icon SVGs
32- **`src/pages/`**: All page templates (Astro generates `docs/` from these)
33  - `index.astro` — Main index with search/filter/pagination
34  - `about/index.astro` — About page
35  - `plugins/index.astro` — Plugins Marketplace page
36  - `ideas/claude-spaces/` — Claude Spaces landing + subpages
37  - `ideas/non-code/` — Non-Code Uses landing + subpages
38  - `repos/[...slug].astro` — Dynamic route generating all repo detail pages from `tagged_repos.json`
39- **`public/`**: Static assets copied to build output (images, JSON data files)
40- **`astro.config.mjs`**: Astro config (outputs to `docs/`)
41 
42**To add/edit nav links, footer, or layout**: Edit the component in `src/components/` — changes apply to all 135+ pages automatically.
43 
44**To add a new static page**: Create a `.astro` file in `src/pages/` using `BaseLayout`.
45 
46## Modular Category System
47 
48The index is built from individual category files stored in the `categories/` directory. This modular approach allows for:
49- Easier maintenance of individual sections
50- Clear ownership of category content
51- Simpler diffs when reviewing changes
52- Parallel editing of different categories
53 
54### Category Files
55 
56Files are named with numeric prefixes to control concatenation order:
57 
58```
59categories/
60  00-header.md              # Banner, intro, understanding section
61  01-systems-administration.md
62  02-productivity.md        # Productivity & Planning
63  02a-legal.md              # Legal
64  02b-health.md             # Health & Wellbeing
65  02c-communications.md     # Communications & Writing
66  02d-financial.md          # Financial Planning
67  02e-career.md             # Career
68  02f-business.md           # Business
69  02g-privacy.md            # Privacy & Anonymity
70  03-research.md
71  04-argument-perspective.md
72  05-context-personalization.md
73  06-multi-agent-tooling.md
74  07-mcp.md
75  08-plugins.md             # GENERATED — see below, do not hand-edit
76  09-slash-commands.md
77  10-misc.md
78```
79 
80### `08-plugins.md` is generated, not authored
81 
82`scripts/sync_marketplace.py` fetches `.claude-plugin/marketplace.json` from
83`danielrosehill/Claude-Code-Plugins` and regenerates `categories/08-plugins.md`
84wholesale. Hand-written entries there are silently destroyed on the next sync or
85build.
86 
87To get a plugin into the index, register it in the **marketplace repo** — it then
88flows here automatically. A plugin repo that is not in the marketplace has no
89route into the Plugins category; file it under its topical category instead, or
90add it to the marketplace first.
91 
92### Building the Site
93 
94After editing category files, run the full build pipeline:
95 
96```bash
97npm run build
98```
99 
100This runs two steps:
1011. **`npm run build:data`** (`python3 scripts/build_site.py`): Builds README.md, repos.json, tagged_repos.json, copies data to `public/`
1022. **`npm run build:site`** (`astro build`): Generates all HTML pages from Astro templates into `docs/`
103 
104For development with hot reload: `npm run dev`
105 
106To run just the data pipeline (no site rebuild): `python3 scripts/build_site.py`
107 
108## Workflow for Adding New Repositories
109 
110### 1. New Repository Collection
111 
112When Daniel adds repository URLs to `scratchpad.md`, follow this workflow:
113 
1141. **Read the scratchpad** to identify new repositories
1152. **Check for duplicates**: Verify each repository isn't already in the index
1163. **Fetch repository information**: Use WebFetch to retrieve the README.md for each repository
1174. **Extract key information**:
118   - Repository name
119   - Primary purpose/functionality
120   - Key features (if notable)
121   - Category classification
122 
123### 2. Categorization
124 
125**Important**: Each repository should belong to **one primary category only**. While some repositories may touch multiple domains, choose the most appropriate single category to avoid duplication and maintenance complexity.
126 
127When adding new repositories, consider whether they fit an existing category or whether a new category/subcategory should be created. The goal is to group repositories that explore Claude Code or the agent workspace model for similar purposes.
128 
129### 3. Editing the Correct Category File
130 
131**Always edit the specific category file**, not README.md directly:
132 
1331. Identify the correct category file in `categories/`
1342. Add the repository entry in alphabetical order within that file
1353. Run `npm run build` to rebuild README, site data, and Astro site
136 
137### 4. Entry Format
138 
139Each repository entry should follow this format:
140 
141```markdown
142### Repository Name
143[![View Repo](https://img.shields.io/badge/View%20Repo-blue?style=flat-square&logo=github)](https://github.com/danielrosehill/Repository-Name)
144 
145Brief description of the repository's purpose and key features (1-2 sentences).
146 
147---
148```
149 
150### 5. Alphabetical Ordering
151 
152Within each category file, maintain **strict alphabetical order by repository name**. When adding new entries:
153 
1541. Find the alphabetical position within the category file
1552. Insert the entry in the correct location
1563. Verify ordering after insertion
157 
158### 6. Description Guidelines
159 
160Descriptions should be:
161- **Concise**: 1-2 sentences maximum
162- **Informative**: Clearly state what the repository does
163- **Actionable**: Help users understand if this resource is relevant to their needs
164- **Professional**: Use clear, technical language without marketing fluff
165 
166### 7. Duplicate Handling
167 
168When processing scratchpad.md:
169- If a repository is already in any category file, skip it silently
170- Do not remove it from scratchpad.md (Daniel manages scratchpad clearing)
171- Note duplicates in your response to Daniel for awareness
172 
173## Quality Standards
174 
175### Repository Descriptions
176 
177- Begin with the primary function/purpose
178- Include key differentiating features
179- Avoid redundant phrases like "A tool for..." or "This repository contains..."
180- Be specific about what the tool does
181 
182### Category Assignment
183 
184- Assign repositories to the **single most appropriate category**
185- If a repository spans multiple categories, choose the primary focus
186- Suggest new categories/subcategories if multiple repositories don't fit existing ones
187 
188### Consistency
189 
190- Use consistent terminology across similar repositories
191- Match the tone and style of existing descriptions
192- Maintain parallel structure in descriptions within the same category
193 
194## WebFetch Usage
195 
196When gathering information about new repositories:
197 
198```
199WebFetch URL: https://github.com/danielrosehill/[repo-name]
200Prompt: "Summarize the purpose and key features of this repository in 1-2 concise sentences suitable for an index listing."
201```
202 
203## Git Operations
204 
205After updating category files:
206 
2071. Run `npm run build` to regenerate README.md and rebuild the Astro site
2082. Review changes to ensure accuracy
2093. Commit with descriptive message: "Add [repository names] to index"
2104. Push changes to GitHub (pre-push hooks will update tracking data)
211 
212## Common Tasks
213 
214### Adding a Single Repository
215 
2161. Read scratchpad.md
2172. WebFetch the repository README
2183. Identify the correct category file
2194. Insert entry in alphabetical order within that file
2205. Run `npm run build`
2216. Commit and push
222 
223### Batch Adding Multiple Repositories
224 
2251. Read scratchpad.md
2262. WebFetch all repository READMEs in parallel
2273. Categorize all repositories
2284. Edit appropriate category files, maintaining alphabetical order
2295. Run `npm run build`
2306. Commit with list of added repositories
231 
232### Reorganizing Categories
233 
234If Daniel requests category restructuring:
2351. Document the new category structure
2362. Create new category files or rename existing ones (maintain numeric prefixes)
2373. Move repositories between category files as needed
2384. Maintain alphabetical ordering within each category
2395. Run `npm run build`
2406. Update this CLAUDE.md if the structure changes significantly
2417. Commit with descriptive reorganization message
242 
243### Creating a New Category
244 
2451. Create a new file in `categories/` with appropriate numeric prefix
2462. Add category header with title and optional image reference
2473. Add repository entries in alphabetical order
2484. Run `npm run build`
249 
250## JSON Data Files
251 
252- `data/repos.json` - Category-based index (generated by `build_site.py`)
253- `docs/tagged_repos.json` - Tag-based index for the site (generated by `build_site.py`)
254- `data/site_state.json` - Deployment state tracking with change history
255- `data/tag_rules.json` - Configurable rules for auto-tagging repos
256 
257To regenerate all data and rebuild the site: `npm run build`
258 
259## Badge System
260 
261Repositories can have multiple badges to indicate their type and purpose:
262 
263| Badge | Color | Purpose |
264|-------|-------|---------|
265| `Agent Workspace` | Purple | Pre-configured agent workspaces for domain-specific workflows |
266| `Agent Config` | Orange | Multi-agent configurations and orchestration |
267| `Slash Commands` | Cyan | Slash command collections |
268| `Non-Code` | Teal | Non-development use cases |
269| `Light Touch` | Light gray | Minimal configuration/simple utilities |
270| `Template` | Green | Forkable templates |
271| `LAN Manager` | Blue | Network/LAN management |
272| `Diary` | Pink | Diary/planning workspaces |
273| `Health` | Red | Health-related workspaces |
274| `Job Search` | Gold | Career/job search tools |
275| `Rig` | Gray | Hardware planning |
276| `Therapy` | Lavender | Therapy tracking |
277| `Budget` | Gold | Budget/financial workspaces |
278| `Legal` | Navy | Legal research and case management |
279| `Forensics` | Dark red | Digital forensics and evidence handling |
280 
281Badge format example:
282```markdown
283![Agent Workspace](https://img.shields.io/badge/Agent-Workspace-purple?style=flat-square)
284```
285 
286## Repository Discovery
287 
288In addition to the scratchpad workflow, run the discovery script to find public
289repos that are not yet in the index:
290 
291```bash
292python3 scripts/discover_new_repos.py          # names matching /claude/
293python3 scripts/discover_new_repos.py --all    # every public repo
294```
295 
296Results are written to `data/unindexed_repos.json`.
297 
298Two traps this script has already fallen into, both fixed — do not reintroduce
299either:
300 
301- **`gh repo list --limit` must exceed the account's total public repo count**
302  (>1050 as of Aug 2026). `gh` truncates silently, so a limit of 500 returned a
303  plausible-looking list while hiding every older candidate.
304- **The default pattern only matches `claude` in the repo *name*.** Genuinely
305  Claude Code-related repos named otherwise — `Document-As-You-Go`,
306  `Aliexpress-Shopper`, `Android-Media-Importer`, `Israel-Phonebook-Manager` —
307  are invisible to it. Periodically re-run with `--all`, or grep descriptions for
308  `claude|agentic|slash command|subagent|agent workspace`, and triage by hand.
309 
310Compare results against the category files before adding anything; the script
311does not know which repos were deliberately excluded.
312 
313## The deployed site
314 
315Live at **https://claude.danielrosehill.com**, deployed by **Vercel** on push to
316`main` (`vercel.json` sets `outputDirectory: docs`). `docs/` is the committed
317Astro build output — so **run `npm run build` and commit the result**; this repo
318is not one where the build can be left to CI.
319 
320`npm run build` is three steps: `build:data` (the Python pipeline that regenerates
321`README.md`, the split markdown pages and `data/*.json`), `build:site` (Astro), and
322`check:links`, which fails the build on a broken internal link.
323 
324**Repo detail pages come from Astro, not Python.** `src/pages/repos/[...slug].astro`
325owns `/repos/<slug>/`. `build_site.py` used to render those pages too — 237 of them,
326from a duplicate HTML template — and `astro build` then overwrote every one. The
327Python copies still carried the pre-rename slug and none of the SEO metadata, and
328editing that template had no visible effect whatsoever. Removed 2026-08-10. If you
329need to change how a repo page looks, the `.astro` file is the only place.
330 
331### SEO and machine-readable surfaces
332 
333`astro.config.mjs` sets `site:` — this is load-bearing. Without it canonical URLs,
334Open Graph URLs and `@astrojs/sitemap` all silently produce nothing.
335 
336`BaseLayout.astro` takes `description`, `image`, `isHome` and `schema` props and
337emits the canonical link, Open Graph and Twitter tags, and JSON-LD. **Pass a
338`description` on every new page** — the fallback is the site-wide one, which is
339fine for a stray page but poor if it ends up on many.
340 
341| Surface | Source | Notes |
342| --- | --- | --- |
343| `/sitemap-index.xml` | `@astrojs/sitemap` | every page, generated |
344| `/robots.txt` | `public/robots.txt` | static; points at the sitemap |
345| `/llms.txt` | `src/pages/llms.txt.ts` | generated from `tagged_repos.json`, cannot drift |
346| `/browse/` | `src/pages/browse/index.astro` | static listing of every repo |
347| `/og-image.png` | `public/` | 1200×630 |
348 
349**Why `/browse/` exists:** the home page renders its repo list client-side from
350`tagged_repos.json`, so a crawler that does not run JS sees only "Loading
351repositories…" and finds no repo links at all. `/browse/` is the static
352counterpart that puts all 236 in the initial HTML. Keep it working; do not fold it
353into the client-rendered index.
354 
355### Dates: both are persisted, deliberately
356 
357`created_date` (real GitHub creation date, `data/repo_created_dates.json`, filled
358by `scripts/fetch_created_dates.py`) drives the site's default "Newest" sort.
359`added_date` (`data/repo_added_dates.json`) is when the repo entered this index.
360 
361Both files exist because both values used to be recomputed as *today* on every
362build whenever a lookup missed — `site_state.json` history is capped at 50 entries,
363so older repos fell off and got restamped. On 2026-08-10 that had left 125 of 236
364repos claiming they were created that day, which made the default sort meaningless.
365Never reintroduce a `datetime.now()` fallback that is not written back to disk.
366 
367After adding repos, run `python3 scripts/fetch_created_dates.py` before building,
368or the new entries sort to the top with a fabricated date.
369 
370## This repo's own name
371 
372Canonical slug: **`danielrosehill/Claude-Code-Projects-Index`**. It has been
373renamed twice, and both former slugs still resolve via GitHub's rename redirect:
374 
375| Former slug | Status |
376| --- | --- |
377| `Claude-Code-Repos-Index` | redirects |
378| `Claude-Agent-Blueprints` | redirects |
379 
380The redirects make staleness invisible — a clone whose `origin` points at an old
381slug fetches and pushes perfectly well, and `gh api repos/<old-slug>` returns
382`200`. Resolve `.full_name` before trusting any slug. Consequences already hit:
383the local checkout sat 130 commits behind on a stale remote URL, and `10-misc.md`
384carried an entry for "Claude Agent Blueprints" — this repo listing *itself* under
385a dead name, with a description that had drifted. All three former names are in
386`SKIP_REPOS` in `scripts/discover_new_repos.py`.
387 
388The local working copy's directory name may also lag the repo name; it is not
389authoritative.
390 
391## Notes
392 
393- All repositories indexed here are public GitHub repositories
394- This index focuses specifically on Claude Code-related projects
395- Daniel maintains a separate master index for all GitHub projects (linked in README.md)
396- The index serves both as documentation and as a discovery tool for the community
397- **Always edit category files, never README.md directly** (it is auto-generated)
398