agentcrumbsinit

name	agentcrumbs/init
description	Initialize agentcrumbs in a repository. Discover systems, services, and modules to build a namespace catalog, then write the catalog to CLAUDE.md or AGENTS.md. Activate when setting up agentcrumbs in a new project, when asked to "init crumbs", "set up debug tracing", "add agentcrumbs", or when the project has agentcrumbs as a dependency but no namespace catalog in its agent config files.
type	lifecycle
library	agentcrumbs
library_version	0.2.0
requires	["agentcrumbs"]
sources	["triggerdotdev/trigger-labs:debug-mode/README.md","triggerdotdev/trigger-labs:debug-mode/src/types.ts"]

Initialize agentcrumbs in a Repository

You are setting up agentcrumbs debug tracing in a repository. Your job is to discover the project's systems and services, build a namespace catalog, and write it into the project's agent config file (CLAUDE.md or AGENTS.md) so all agents use consistent namespaces.

The output should be minimal — just the namespace catalog, a one-liner about the strip workflow, and essential CLI. The agentcrumbs skills already teach agents HOW to use the library. The config file only needs to teach agents WHICH namespaces to use in THIS repo.

---

Phase 1 — Discover project structure

Scan the repository to identify logical systems, services, and modules. These become the namespace catalog.

What to scan

Search for system boundaries using these strategies in order. Stop when you have a reasonable set (typically 3–15 namespaces):

Monorepo packages:

• apps/ directories — each app is a namespace
• packages/ directories — each package is a namespace
• internal-packages/ directories — each is a namespace
• services/ directories — each service is a namespace

Single-repo modules:

• src/ top-level directories — each major module is a namespace
• Route groups, feature folders, domain directories

Existing conventions:

• Look for existing logger namespaces, OpenTelemetry service names
• Check package.json name fields for naming conventions

Framework-specific:

• Next.js: app/api/* route groups, server actions, middleware
• Express/Fastify: router modules, middleware groups
• Worker/queue systems: each worker type

Naming rules

• Use lowercase kebab-case: auth-service, api-gateway, task-runner
• Keep names short but descriptive: webapp not main-web-application
• Match existing conventions in the repo if they exist
• Group related subsystems with prefixes: db-queries, db-migrations

Determine the app name

The app name identifies this project in crumb storage and CLI filtering. Read the root package.json name field (strip any @scope/ prefix). This is what gets stamped on every crumb as the app field.

If the repo is a monorepo, use the root package name (not individual workspace packages — those become namespaces, not apps).

Browser apps

If the project has browser-side code (React, Vue, Svelte, etc.), include browser-facing namespaces in the catalog. The same "agentcrumbs" import works in the browser — bundlers auto-resolve to the browser build. Note in the config that browser apps use configure() instead of the env var.

What to capture for each namespace

For each namespace, record:

• name: the trail namespace string
• description: one-line description of what this system does
• path: directory path relative to repo root (if applicable)

---

Phase 2 — Ask the maintainer

Present the app name and discovered namespaces to the maintainer and ask:

1. "The app name is <name> (from package.json). Is that correct?"
2. "Here are the namespaces I found. Should I add, remove, or rename any?"
3. "Are there any cross-cutting concerns I should add?" (e.g., cron, migrations, external-api, auth, billing)
4. "Which agent config file should I write to — CLAUDE.md or AGENTS.md?"

Wait for their response before proceeding.

If the maintainer asks to skip this phase, explain that the namespace catalog is the most important part — it ensures all agents use consistent names. Proceed only if they confirm a second time.

---

Phase 3 — Write the config

Write (or append to) the agent config file. Keep it short. The skills handle usage details — the config file only needs repo-specific context.

The output should look like this:

## agentcrumbs

App: `my-project`

Add crumbs as you write code — not just when debugging. Mark lines with
`// @crumbs` or wrap blocks in `// #region @crumbs`. They stay on the
branch throughout development and are stripped by `agentcrumbs strip`
before merge.

### Namespaces

| Namespace | Description | Path |
| --- | --- | --- |
| `webapp` | Main web application and API | `apps/webapp` |
| `supervisor` | Task execution supervisor | `apps/supervisor` |
| `core` | Shared types and utilities | `packages/core` |
| `billing` | Billing and subscription logic | `apps/webapp/app/services/billing` |

Do not invent new namespaces — pick from this table or ask first.

### For PR reviewers

Do not flag `// @crumbs` markers, `#region @crumbs` blocks, or agentcrumbs
imports in reviews. These are temporary debug instrumentation stripped
before merge. Data logged in crumbs (IDs, names, values) never reaches
production.

### CLI

```bash
AGENTCRUMBS=1 node app.js              # enable tracing (Node.js)
configure("*")                          # enable tracing (browser — call before trail())
agentcrumbs collect                     # start collector
agentcrumbs tail                        # live tail (scoped to this app)
agentcrumbs query --since 5m            # query recent crumbs (all namespaces)
agentcrumbs query --since 5m --cursor <id>  # paginate (cursor from output)
agentcrumbs clear                       # clear crumbs for this app
agentcrumbs strip                       # remove crumbs before merge
```

When querying, always start broad (all namespaces) and paginate with `--cursor`. Do not filter by `--ns` or `--match` — the value is in seeing the full cross-service picture.

Adapt the example above to the actual discovered namespaces and app name. Drop the Path column if namespaces don't have meaningful directory paths. Replace my-project with the actual app name detected from package.json.

---

Phase 4 — Verify

After writing the file:

1. Read it back and verify the namespace table rendered correctly
2. Check there are no duplicate ## agentcrumbs sections
3. Tell the maintainer what you wrote and where

---

Constraints

Rule	Detail
Never invent namespaces without discovery	Scan the repo first, always
Namespace catalog is mandatory	The whole point is consistent naming
Ask before writing	Confirm namespaces and target file
Append, don't overwrite	If the file exists, append to it
Skip if already configured	If the file contains ## agentcrumbs, tell the user and stop
Use repo conventions	Match existing naming style (kebab-case, camelCase, etc.)
Keep it short	No usage tutorial — the skills cover that. Just the catalog and 3-line CLI reference
No redundancy with skills	Don't repeat API docs, marker syntax details, env var schemas, or scope/session usage