compose-md-cli 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Johnston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# Compose-MD
+
+**These docs written by AI**
+
+Compose agent-facing markdown (`AGENTS.md`, `CLAUDE.md`, `SKILL.md`, and friends) from a pool of
+reusable fragments. Switch harness layouts and content placement by editing YAML approaches —
+not by rewriting the same prose in multiple files.
+
+**Docs:** [https://dwjohnston.github.io/compose-md/](https://dwjohnston.github.io/compose-md/)
+
+## Install
+
+```sh
+bun add -d compose-md
+```
+
+## Initialize
+
+From your project root:
+
+```sh
+bunx compose init
+```
+
+You'll be prompted for a docs root name (default `projectDocs`). `init` scaffolds the fragment
+pool, imports any existing agent prompt files, writes a `default` approach, and asks whether to
+run `compose apply` immediately.
+
+## Apply an approach
+
+```sh
+bunx compose apply default
+```
+
+Or run `bunx compose` for an interactive picker.

package/dist/cli.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { runInteractive } from './interactive.js';
+import { viewApproach } from './commands/view.js';
+import { applyApproach } from './commands/apply.js';
+import { runInit } from './commands/init.js';
+import { getDocsRoot } from './lib/config.js';
+const cwd = process.cwd();
+const docsRoot = getDocsRoot(cwd);
+const [, , command, ...args] = process.argv;
+switch (command) {
+    case 'apply': {
+        const name = args[0];
+        if (!name) {
+            console.error('Usage: compose apply <approach>');
+            process.exit(1);
+        }
+        await applyApproach(docsRoot, name, cwd);
+        break;
+    }
+    case 'view': {
+        const name = args[0];
+        if (!name) {
+            console.error('Usage: compose view <approach>');
+            process.exit(1);
+        }
+        viewApproach(docsRoot, name);
+        break;
+    }
+    case 'init':
+        await runInit(cwd);
+        break;
+    default:
+        await runInteractive(docsRoot, cwd);
+}

package/dist/commands/apply.js

@@ -0,0 +1,49 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { loadApproach } from '../lib/approaches.js';
+import { scanFragments } from '../lib/fragments.js';
+import { getActiveApproach, setActiveApproach } from '../lib/active.js';
+function resolveContent(fragmentIds, fragments) {
+    const parts = [];
+    for (const id of fragmentIds) {
+        if (!id.startsWith('@')) {
+            parts.push(id.trim());
+            continue;
+        }
+        const key = id.slice(1);
+        const fragment = fragments.get(key);
+        if (!fragment)
+            throw new Error(`Fragment not found: ${id}`);
+        parts.push(fragment.content.trim());
+    }
+    return parts.join('\n\n');
+}
+export async function applyApproach(docsRoot, name, cwd) {
+    const previousActive = getActiveApproach(cwd);
+    if (previousActive && previousActive !== name) {
+        try {
+            const prev = loadApproach(docsRoot, previousActive);
+            for (const outputPath of Object.keys(prev.outputs)) {
+                const fullPath = join(cwd, outputPath);
+                if (existsSync(fullPath)) {
+                    rmSync(fullPath);
+                    console.log(`Removed: ${outputPath}`);
+                }
+            }
+        }
+        catch {
+            // previous approach file missing — skip cleanup
+        }
+    }
+    const approach = loadApproach(docsRoot, name);
+    const fragments = scanFragments(docsRoot);
+    for (const [outputPath, fragmentIds] of Object.entries(approach.outputs)) {
+        const composed = resolveContent(fragmentIds, fragments);
+        const fullPath = join(cwd, outputPath);
+        mkdirSync(dirname(fullPath), { recursive: true });
+        writeFileSync(fullPath, composed + '\n');
+        console.log(`Written: ${outputPath}`);
+    }
+    setActiveApproach(cwd, name);
+    console.log(`\nApplied: ${name}`);
+}

package/dist/commands/init.js

@@ -0,0 +1,274 @@
+import { input, confirm } from '@inquirer/prompts';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, appendFileSync, readdirSync } from 'fs';
+import { join, relative, basename, dirname, sep } from 'path';
+import { fileURLToPath } from 'url';
+import { CONFIG_FILE, setDocsRootConfig } from '../lib/config.js';
+// Filenames recognized anywhere in the project tree.
+const AGENT_FILENAMES = new Set([
+    'AGENTS.md', // OpenAI Codex, generic
+    'CLAUDE.md', // Anthropic Claude
+    'SKILL.md', // Claude Code skills
+    'GEMINI.md', // Google Gemini
+]);
+// Exact relative paths recognized at that specific location only.
+const AGENT_PATHS = new Set([
+    '.github/copilot-instructions.md',
+]);
+const EXCLUDED_DIRS = new Set(['node_modules', '.git']);
+function toKebab(name) {
+    return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/, '');
+}
+function pathToId(p) {
+    return toKebab(p.replace(/\.[^.]+$/, '')); // e.g. src/commands/CLAUDE.md → src-commands-claude
+}
+function idToTitle(id) {
+    return id.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+// Plain .md files shipped with the package (src/startingPrompts/*.md) that
+// get copied into every new project as ready-made fragments.
+function startingPromptsSourceDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', 'startingPrompts');
+}
+// Starting prompts can reference the docs root by this placeholder; it's
+// swapped for the actual docsRootName (which is only known at init time).
+function substituteDocsRoot(content, docsRootName) {
+    return content.replace(/\$PROJECT_DOCS/g, docsRootName);
+}
+function copyStartingPrompts(docsRoot, docsRootName, created) {
+    const sourceDir = startingPromptsSourceDir();
+    if (!existsSync(sourceDir))
+        return [];
+    const files = readdirSync(sourceDir).filter(f => f.endsWith('.md'));
+    if (files.length === 0)
+        return [];
+    const destDir = join(docsRoot, 'starting');
+    mkdirSync(destDir, { recursive: true });
+    const prompts = [];
+    for (const file of files) {
+        const id = toKebab(file.replace(/\.md$/, ''));
+        const destFile = join(destDir, `${id}.md`);
+        if (!existsSync(destFile)) {
+            const content = readFileSync(join(sourceDir, file), 'utf-8');
+            writeFileSync(destFile, [
+                '---',
+                `name: ${id}`,
+                `description: ${idToTitle(id)}`,
+                '---',
+                '',
+                substituteDocsRoot(content, docsRootName).trim(),
+                '',
+            ].join('\n'));
+            created.push(`${docsRootName}/starting/${id}.md`);
+        }
+        prompts.push({ id, destRelPath: `starting/${id}.md` });
+    }
+    return prompts;
+}
+function copyStartingSkills(docsRoot, docsRootName, created) {
+    const sourceDir = join(startingPromptsSourceDir(), 'skills');
+    if (!existsSync(sourceDir))
+        return [];
+    const skillDirs = readdirSync(sourceDir, { withFileTypes: true }).filter(e => e.isDirectory());
+    if (skillDirs.length === 0)
+        return [];
+    const destDir = join(docsRoot, 'starting');
+    mkdirSync(destDir, { recursive: true });
+    const skills = [];
+    for (const { name: skillName } of skillDirs) {
+        const sourceFile = join(sourceDir, skillName, 'SKILL.md');
+        if (!existsSync(sourceFile))
+            continue;
+        const id = `${toKebab(skillName)}-skill`;
+        const destFile = join(destDir, `${id}.md`);
+        if (!existsSync(destFile)) {
+            const content = readFileSync(sourceFile, 'utf-8');
+            writeFileSync(destFile, [
+                '---',
+                `name: ${id}`,
+                `description: ${idToTitle(id)}`,
+                '---',
+                '',
+                substituteDocsRoot(content, docsRootName).trim(),
+                '',
+            ].join('\n'));
+            created.push(`${docsRootName}/starting/${id}.md`);
+        }
+        skills.push({ id, outputPath: `.agents/skills/${skillName}/SKILL.md` });
+    }
+    return skills;
+}
+function isAgentFile(relPath) {
+    if (AGENT_FILENAMES.has(basename(relPath)))
+        return true;
+    const posixPath = relPath.split(sep).join('/');
+    if (AGENT_PATHS.has(posixPath))
+        return true;
+    if (/^\.claude\/agents\/[^/]+\.md$/.test(posixPath))
+        return true;
+    return false;
+}
+function findAgentFiles(cwd, excludeDirs = []) {
+    const excluded = new Set(excludeDirs);
+    const results = [];
+    function walk(dir) {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            const rel = relative(cwd, full);
+            if (entry.isDirectory()) {
+                if (EXCLUDED_DIRS.has(entry.name) || excluded.has(rel))
+                    continue;
+                walk(full);
+            }
+            else if (entry.isFile() && isAgentFile(rel)) {
+                results.push({ sourcePath: rel.split(sep).join('/'), fragmentId: pathToId(rel) });
+            }
+        }
+    }
+    walk(cwd);
+    return results.sort((a, b) => a.sourcePath.localeCompare(b.sourcePath));
+}
+function buildDefaultYaml(agentFiles, startingPrompts, startingSkills) {
+    const startingIncludes = startingPrompts.map(({ id }) => `    - "@${id}"`);
+    // The "root file" is an agent file that lives at the project root (no
+    // directory component). Starting prompts (e.g. docs-workflow) only belong
+    // there, not in every nested agent file. Prefer an existing AGENTS.md;
+    // otherwise fall back to whichever root-level file was found first.
+    const rootFiles = agentFiles.filter(f => !f.sourcePath.includes('/'));
+    const otherFiles = agentFiles.filter(f => f.sourcePath.includes('/'));
+    const rootFile = rootFiles.find(f => f.sourcePath === 'AGENTS.md') ?? rootFiles[0];
+    const rootSourcePath = rootFile?.sourcePath ?? 'AGENTS.md';
+    const remainingRootFiles = rootFiles.filter(f => f !== rootFile);
+    const lines = [
+        'name: default',
+        'description: Initial approach',
+        '',
+        'outputs:',
+        `  ${rootSourcePath}:`,
+        ...startingIncludes,
+        '    - "@getting-started"',
+    ];
+    if (rootFile) {
+        lines.push(`    - "@${rootFile.fragmentId}"`);
+    }
+    for (const { sourcePath, fragmentId } of [...remainingRootFiles, ...otherFiles]) {
+        lines.push(`  ${sourcePath}:`);
+        lines.push(`    - "@${fragmentId}"`);
+    }
+    for (const { id, outputPath } of startingSkills) {
+        lines.push(`  ${outputPath}:`);
+        lines.push(`    - "@${id}"`);
+    }
+    return lines.join('\n') + '\n';
+}
+function ensureGitignore(cwd, docsRootName) {
+    const gitignorePath = join(cwd, '.gitignore');
+    const entries = [
+        '.compose-active',
+        CONFIG_FILE,
+        `${docsRootName}/_index.md`,
+    ];
+    const gitignoreExisted = existsSync(gitignorePath);
+    const existing = gitignoreExisted ? readFileSync(gitignorePath, 'utf-8') : '';
+    const toAdd = entries.filter(e => !existing.split('\n').some(line => line.trim() === e));
+    if (toAdd.length === 0)
+        return 'unchanged';
+    const prefix = existing.endsWith('\n') || existing === '' ? '' : '\n';
+    appendFileSync(gitignorePath, prefix + toAdd.join('\n') + '\n');
+    return gitignoreExisted ? 'updated' : 'created';
+}
+export function scaffoldProject(cwd, docsRootName) {
+    const docsRoot = join(cwd, docsRootName);
+    const created = [];
+    // Directories
+    mkdirSync(join(docsRoot, '_approaches'), { recursive: true });
+    created.push(`${docsRootName}/_approaches/`);
+    // Sample fragment
+    const sampleFragment = join(docsRoot, 'getting-started.md');
+    if (!existsSync(sampleFragment)) {
+        writeFileSync(sampleFragment, [
+            '---',
+            'name: getting-started',
+            'description: quick-start guide for new contributors',
+            '---',
+            '',
+            '# Getting Started',
+            '',
+            '<!-- Add your getting started content here -->',
+            '',
+        ].join('\n'));
+        created.push(`${docsRootName}/getting-started.md`);
+    }
+    // Curated starter fragments shipped with compose-md
+    const startingPrompts = copyStartingPrompts(docsRoot, docsRootName, created);
+    const startingSkills = copyStartingSkills(docsRoot, docsRootName, created);
+    // Scan for agent prompt files (excluding the docs root we just created)
+    const agentFiles = findAgentFiles(cwd, [docsRootName]);
+    if (agentFiles.length > 0) {
+        mkdirSync(join(docsRoot, 'existing'), { recursive: true });
+    }
+    for (const { sourcePath, fragmentId } of agentFiles) {
+        const content = readFileSync(join(cwd, sourcePath), 'utf-8');
+        const fragmentFile = join(docsRoot, 'existing', `${fragmentId}.md`);
+        if (!existsSync(fragmentFile)) {
+            writeFileSync(fragmentFile, [
+                '---',
+                `name: ${fragmentId}`,
+                `description: content of ${sourcePath}`,
+                '---',
+                '',
+                content.trim(),
+                '',
+            ].join('\n'));
+            created.push(`${docsRootName}/existing/${fragmentId}.md`);
+        }
+    }
+    // Default approach YAML
+    const defaultApproach = join(docsRoot, '_approaches', 'default.yaml');
+    if (!existsSync(defaultApproach)) {
+        writeFileSync(defaultApproach, buildDefaultYaml(agentFiles, startingPrompts, startingSkills));
+        created.push(`${docsRootName}/_approaches/default.yaml`);
+    }
+    // Empty _index.md
+    const indexFile = join(docsRoot, '_index.md');
+    if (!existsSync(indexFile)) {
+        writeFileSync(indexFile, '');
+        created.push(`${docsRootName}/_index.md`);
+    }
+    // Gitignore
+    const gitignoreResult = ensureGitignore(cwd, docsRootName);
+    if (gitignoreResult !== 'unchanged') {
+        created.push(`.gitignore (${gitignoreResult})`);
+    }
+    return created;
+}
+export async function runInit(cwd) {
+    const docsRootName = await input({
+        message: 'Docs root name:',
+        default: 'projectDocs',
+    });
+    const docsRoot = join(cwd, docsRootName);
+    if (existsSync(docsRoot)) {
+        const proceed = await confirm({
+            message: `${docsRootName}/ already exists. Continue?`,
+            default: false,
+        });
+        if (!proceed)
+            return;
+    }
+    const created = scaffoldProject(cwd, docsRootName);
+    setDocsRootConfig(cwd, docsRootName);
+    const agentFiles = findAgentFiles(cwd, [docsRootName]);
+    console.log('\nCreated:');
+    for (const path of created) {
+        console.log(`  ${path}`);
+    }
+    if (agentFiles.length > 0) {
+        console.log('\nRegistered agent files as fragments:');
+        for (const { sourcePath, fragmentId } of agentFiles) {
+            console.log(`  ${sourcePath} → @${fragmentId}`);
+        }
+    }
+    console.log('\nDone. Run `compose` to select and apply an approach.');
+}
+export { findAgentFiles };

package/dist/commands/view.js

@@ -0,0 +1,15 @@
+import { loadApproach } from '../lib/approaches.js';
+export function viewApproach(docsRoot, name) {
+    const approach = loadApproach(docsRoot, name);
+    console.log(`approach: ${approach.name}`);
+    if (approach.description)
+        console.log(`description: ${approach.description}`);
+    console.log();
+    for (const [outputPath, fragments] of Object.entries(approach.outputs)) {
+        console.log(outputPath);
+        for (const id of fragments) {
+            console.log(`        ${id}`);
+        }
+        console.log();
+    }
+}

package/dist/interactive.js

@@ -0,0 +1,37 @@
+import { select } from '@inquirer/prompts';
+import { listApproaches } from './lib/approaches.js';
+import { getActiveApproach } from './lib/active.js';
+import { viewApproach } from './commands/view.js';
+import { applyApproach } from './commands/apply.js';
+export async function runInteractive(docsRoot, cwd) {
+    const active = getActiveApproach(cwd);
+    const approaches = listApproaches(docsRoot);
+    if (approaches.length === 0) {
+        console.log('No approaches found in', docsRoot);
+        console.log('Run `compose init` to get started.');
+        return;
+    }
+    console.log(`Active approach: ${active ?? 'none'}\n`);
+    const chosen = await select({
+        message: 'Select an approach:',
+        choices: approaches.map(a => ({
+            name: `${a.name}${a.description ? ` — ${a.description}` : ''}`,
+            value: a.name,
+        })),
+    });
+    const action = await select({
+        message: `"${chosen}" —`,
+        choices: [
+            { name: 'View', value: 'view', description: 'Show composition without applying' },
+            { name: 'Apply', value: 'apply', description: 'Write output files' },
+        ],
+    });
+    if (action === 'view') {
+        console.log();
+        viewApproach(docsRoot, chosen);
+    }
+    else {
+        console.log();
+        await applyApproach(docsRoot, chosen, cwd);
+    }
+}

package/dist/lib/active.js

@@ -0,0 +1,12 @@
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+const ACTIVE_FILE = '.compose-active';
+export function getActiveApproach(cwd) {
+    const path = join(cwd, ACTIVE_FILE);
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, 'utf-8').trim() || null;
+}
+export function setActiveApproach(cwd, name) {
+    writeFileSync(join(cwd, ACTIVE_FILE), name);
+}

package/dist/lib/approaches.js

@@ -0,0 +1,23 @@
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { load } from 'js-yaml';
+export function approachesDir(docsRoot) {
+    return join(docsRoot, '_approaches');
+}
+export function listApproaches(docsRoot) {
+    const dir = approachesDir(docsRoot);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+        .map(f => {
+        const content = readFileSync(join(dir, f), 'utf-8');
+        return load(content);
+    });
+}
+export function loadApproach(docsRoot, name) {
+    const file = join(approachesDir(docsRoot), `${name}.yaml`);
+    if (!existsSync(file))
+        throw new Error(`Approach not found: ${name}`);
+    return load(readFileSync(file, 'utf-8'));
+}

package/dist/lib/config.js

@@ -0,0 +1,31 @@
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { join } from 'path';
+const CONFIG_FILE = '.compose-config.json';
+const DEFAULT_DOCS_ROOT = 'projectDocs';
+export function setDocsRootConfig(cwd, docsRoot) {
+    const config = { docsRoot };
+    writeFileSync(join(cwd, CONFIG_FILE), JSON.stringify(config, null, 2) + '\n');
+}
+// Reads the persisted docs-root name from .compose-config.json, falling
+// back to the default ('projectDocs') if the config file doesn't exist
+// (e.g. projects scaffolded before this config existed, or `compose init`
+// itself, which runs before the config is written).
+export function getDocsRootName(cwd) {
+    const path = join(cwd, CONFIG_FILE);
+    if (!existsSync(path))
+        return DEFAULT_DOCS_ROOT;
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        if (parsed && typeof parsed.docsRoot === 'string' && parsed.docsRoot.trim()) {
+            return parsed.docsRoot;
+        }
+    }
+    catch {
+        // Malformed config file; fall back to the default.
+    }
+    return DEFAULT_DOCS_ROOT;
+}
+export function getDocsRoot(cwd) {
+    return join(cwd, getDocsRootName(cwd));
+}
+export { CONFIG_FILE, DEFAULT_DOCS_ROOT };

package/dist/lib/fragments.js

@@ -0,0 +1,40 @@
+import { readdirSync, readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+function parseFrontmatter(raw) {
+    const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/);
+    if (!match)
+        return { data: {}, body: raw };
+    const data = {};
+    for (const line of (match[1] ?? '').split('\n')) {
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1)
+            continue;
+        const key = line.slice(0, colonIdx).trim();
+        const value = line.slice(colonIdx + 1).trim().replace(/^["']|["']$/g, '');
+        data[key] = value;
+    }
+    return { data, body: match[2] ?? '' };
+}
+export function scanFragments(docsRoot) {
+    const fragments = new Map();
+    function scan(dir) {
+        if (!existsSync(dir))
+            return;
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+            if (entry.isDirectory()) {
+                if (entry.name === '_approaches')
+                    continue;
+                scan(join(dir, entry.name));
+            }
+            else if (entry.name.endsWith('.md') && entry.name !== '_index.md') {
+                const filePath = join(dir, entry.name);
+                const { data, body } = parseFrontmatter(readFileSync(filePath, 'utf-8'));
+                if (data.name) {
+                    fragments.set(data.name, { name: data.name, description: data.description, content: body, filePath });
+                }
+            }
+        }
+    }
+    scan(docsRoot);
+    return fragments;
+}

package/dist/startingPrompts/docs-workflow.md

@@ -0,0 +1,9 @@
+# This project uses compose-md
+
+The coding agent prompts (AGENTS.md, CLAUDE.md, SKILL.md etc) in this project are .gitignored. Do not edit them directly. 
+
+Instead, edit the files in $PROJECT_DOCS
+
+Invoke the /compose-docs skill to assist.
+
+If your memory system would normally have you write something durable directly into one of these files, write it into the corresponding fragment in $PROJECT_DOCS instead, then run `compose apply` to regenerate the file.

package/dist/startingPrompts/skills/compose-docs/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: compose-docs
+description: Edit and regenerate this project's agent instruction files (AGENTS.md, CLAUDE.md, SKILL.md, etc.), which are generated by compose-md from fragments and approaches. Use this whenever you would normally write durable memory directly into one of those files.
+---
+
+# compose-docs
+
+This project's coding-agent instruction files (AGENTS.md, CLAUDE.md, SKILL.md, etc.) are generated by compose-md and are gitignored. Do not edit them directly — your changes will be overwritten the next time `compose apply` runs.
+
+## Where the real content lives
+
+- **Fragments** — `.md` files anywhere under `$PROJECT_DOCS/` (except `_approaches/`), each with a `name:` field in its frontmatter.
+- **Approaches** — `.yaml` files in `$PROJECT_DOCS/_approaches/`. Each approach maps an output path (e.g. `AGENTS.md`) to a list of `@fragment-name` references and/or inline literal text (YAML block scalars, e.g. `- |`, work for multiline bespoke content like frontmatter headers).
+
+## Workflow
+
+1. Find the fragment behind the content you want to change — search `$PROJECT_DOCS/` for the relevant `name:` frontmatter, or look up the output path in the active approach's YAML.
+2. Edit the fragment's markdown content.
+3. Run `compose apply <approach>` to regenerate the output files from the fragments.
+4. To add a new generated file, add an entry under `outputs:` in the approach YAML.
+5. If your memory mechanism would normally write directly into AGENTS.md, CLAUDE.md, or a SKILL.md (e.g. to persist something durable you've learned), write it into the corresponding fragment instead, then run `compose apply`. Never write memory straight into a generated file — it will be overwritten.
+
+Never hand-edit a generated file — always change the source fragment (or approach YAML) and re-run `compose apply`.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "compose-md-cli",
+  "module": "index.ts",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "compose": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "compose": "bun run src/cli.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp -R src/startingPrompts dist/startingPrompts && chmod +x dist/cli.js",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf projectDocs && git checkout -- .gitignore",
+    "docs:dev": "vitepress dev",
+    "docs:build": "vitepress build",
+    "docs:preview": "vitepress preview"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/js-yaml": "^4.0.9",
+    "typescript": "^5",
+    "vitepress": "^2.0.0-alpha.18"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "js-yaml": "^5.2.0"
+  },
+  "version": "0.0.0"
+}