source-bundle

source-bundle

Turn a whole project into a small set of readable Markdown bundles under .source/, so an AI system that only accepts Markdown can ingest the code. Verbatim — nothing is rewritten or summarized.

When to use

• Prepping a repo for a Markdown-only AI ingestion / RAG pipeline.
• "Export/bundle the source as Markdown", "consolidate the codebase into docs", "generate .source".

When NOT to use

• Generating prose docs (architecture / API / manual) → use the document skill.
• Codebase maps / symbol indexes → use codemap.

Output contract

.source/                         # hidden, git-ignored
├── index.source.md              # explanation + included tree + bundle table + skip report
├── <folder>.source.md           # one bundle per meaningful folder
└── <folder>.part-01.source.md   # large folders split into parts

Each <folder>.source.md contains, in order:

1. Title with the original folder path.
2. Generated folder introduction (what the folder appears to contain).
3. Folder summary — list of files included in this part.
4. Per file: heading with the relative path → one-line generated note → full file contents in a fenced code block with the correct language tag.

Procedure

The deterministic generator is shipped with the plugin. Run it against the target project (defaults to the current working directory):

node ${CLAUDE_PLUGIN_ROOT}/scripts/generate-source-md.mjs $ARGUMENTS

• $ARGUMENTS (optional) = target project directory. Omit to bundle the CWD.
• Safe to rerun: it wipes and regenerates .source/ every run and idempotently adds .source/ to .gitignore.
• No model call — introductions are extracted from the files themselves (Markdown frontmatter description: / first # H1; leading JS/TS comment), so output is reproducible.

If the script is missing (e.g. running outside the plugin), recreate it in the target repo at scripts/generate-source-md.mjs from the rules below, then run it.

Behavior the generator guarantees

Grouping (reasonable file count, not one file per source file):

• One bundle per meaningful folder; whole subtree rolled into that bundle.
• Descend into subfolders only when a subtree exceeds ~40 files (so large trees like skills/ or src/ split by subsystem; small ones stay single).
• Split a bundle into .part-NN.source.md when embedded source exceeds ~350 KB.
• Safe readable names preserve nesting: src/memory/web → src-memory-web.source.md.

Exclusions (never embedded):

• Dirs: .git, .source, node_modules, coverage, build output (dist/build/ out — root-level only, so a /build skill folder is kept), .sfdx, .sf, caches, virtualenvs.
• Files: lock files (package-lock.json, yarn.lock, …), binaries / images / archives / media (by extension), OS cruft (.DS_Store), and anything that looks like a secret/key/credential (.env*, *.pem, *.key, id_rsa, .npmrc, …).
• Per-project scratch (e.g. IDEAS.md) when git-ignored as personal.

Correctness:

• Code fences auto-size: the outer fence is one backtick longer than the longest backtick run inside the file, so Markdown sources (which contain their own ``` fences) nest correctly.
• File contents are copied byte-for-byte (only a single trailing newline trimmed).

Verify before reporting

1. node --check the script (if (re)created), then run it.
2. Confirm .source/ exists with the expected bundles + index.source.md.
3. Confirm .gitignore contains .source/ and nothing outside .source/ was modified except .gitignore.
4. Optional integrity spot-check: extract a fenced block and diff against the original file.

Report

State: files created/changed, source folders converted, Markdown files generated, folders/files skipped (with reasons), and the regenerate command (/siftcoder:source-bundle or node scripts/generate-source-md.mjs).