| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 20 | 0% |
| Commands | 0 | 5 | 2 | 0% |
| Section tags | 2 | 1 | 7 | 20% |
What each file covers
Sections
0 shared · 6 only in A · 20 only in B- − aspens
- − Skills
- − Commands
- − Release
- − Conventions
- − Behavior
- + Copilot Instructions
- + What This Project Does
- + Project Setup
- + Architecture
- + `doc init` Pipeline
- + `doc sync` Pipeline
- + Key Conventions
- + ES Modules
- + Path Handling
- + Output Parsing
- + Prompt Templates
- + Claude CLI Invocation
- + Interactive UI
- + Error Handling
- + Skill File Format
- + Activation
- + Key Files
- + Key Concepts
- + Critical Rules
- + Phase Status
Commands
0 shared · 5 only in A · 2 only in B- − npm test
- − vitest run
- − npm start
- − node bin/cli.js
- − npm run lint
- + npm install
- + npm link
Section tags
2 shared · 1 only in A · 7 only in B- − test
- + setup
- + lint-format
- + architecture
- + ui
- + do-not
- + agent-behaviour
- + docs
- code-style
- deployment
Line diff
aspenkit/aspens · CLAUDE.md
@@ −1 @@
1# aspens
2
3## Skills
4
5- `.claude/skills/base/skill.md` — Base repo skill; load whenever working in this repo.
6- `.claude/skills/agent-customization/skill.md` — LLM-powered injection of project context into installed agent templates via `aspens customize agents`
7- `.claude/skills/claude-runner/skill.md` — Claude/Codex CLI execution layer — prompt loading, stream-json parsing, file output extraction, path sanitization, skill file writing, and skill rule generation
8- `.claude/skills/cli-shell/skill.md` — Top-level Commander wiring, welcome screen, missing-hook warning, CliError exit handling, and the public programmatic API surface
9- `.claude/skills/codex-support/skill.md` — Multi-target output system — target abstraction, backend routing, content transforms for Codex CLI and future targets
10- `.claude/skills/doc-impact/skill.md` — Context health analysis — freshness, domain coverage, hub surfacing, drift detection, LLM-powered interpretation, and auto-repair for generated agent context
11- `.claude/skills/doc-sync/skill.md` — Incremental skill updater that maps git diffs to affected skills and optionally auto-syncs via a post-commit hook
12- `.claude/skills/import-graph/skill.md` — Static import analysis that builds dependency graphs, domain clusters, hub files, git churn hotspots, and file priority rankings
13- `.claude/skills/repo-scanning/skill.md` — Deterministic repo analysis — language/framework detection, structure mapping, domain discovery, health checks, and import graph integration
14- `.claude/skills/save-tokens/skill.md` — Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code
15- `.claude/skills/skill-generation/skill.md` — LLM-powered generation pipeline for Claude Code skills and CLAUDE.md — doc-init command, prompt system, context building, and output parsing
16- `.claude/skills/template-library/skill.md` — Bundled agents, commands, hooks, and settings that users install via `aspens add`, `aspens doc init`, and `aspens save-tokens` into their .claude/ directories
17
18## Commands
19
20- `npm test` — run Vitest (`vitest run`)
21- `npm start` — run the CLI (`node bin/cli.js`)
22- `npm run lint` — no-op check (`echo 'No linter configured yet' && exit 0`)
23- `aspens scan [path]` — deterministic repo scan
24- `aspens doc init [path]` — generate skills, hooks, and instructions file (`--target claude|codex|all`, `--recommended` for full recommended setup including save-tokens, agents, and doc-sync hook)
25- `aspens doc impact [path]` — show freshness, coverage, drift, and LLM interpretation of generated context (interactive apply for repairs)
26- `aspens doc sync [path]` — update docs from recent diffs
27- `aspens doc graph [path]` — rebuild `.claude/graph.json`
28- `aspens add <type> [name]` — install bundled templates
29- `aspens customize agents` — inject project context into installed agents
30- `aspens save-tokens [path]` — install token-saving session settings (`--recommended`, `--remove`)
31
32## Release
33
34- Release workflow: `../dev/release.md`
35
36## Conventions
37
38- ESM only: use `import`/`export`; never `require()`.
39- Prefer `CliError` from command handlers; top-level handling lives in `bin/cli.js`.
40- `es-module-lexer` must be initialized before `parse()`.
41- Keep target/backend semantics straight: target is output format/location; backend is the generating CLI. Persist config in `.aspens.json`.
42- Do not duplicate base-skill guidance here; consult `.claude/skills/base/skill.md` for deeper repo context.
43
44## Behavior
45
46- **Verify before claiming** — Never state that something is configured, running, scheduled, or complete without confirming it first. If you haven't verified it in this session, say so rather than assuming.
47- **Make sure code is running** — If you suggest code changes, ensure the code is running and tested before claiming the task is done.
48- **Ask clarifying questions** — If the task is ambiguous, ask for clarification rather than making assumptions. Don't imply or guess at requirements or constraints that aren't explicitly stated.
49- **Simplicity first** — Write the minimum code that solves the problem. No speculative features, abstractions for single-use code, or error handling for impossible scenarios.
50- **Surgical changes** — Touch only what the task requires. Don't refactor adjacent code, fix unrelated formatting, or "improve" things that aren't broken.
51
aspenkit/aspens · .github/copilot-instructions.md
@@ +1 @@
1# Copilot Instructions
2
3## What This Project Does
4
5`aspens` is a CLI tool that generates and maintains AI-ready documentation (skills and guidelines) for any codebase. It scans a repo's tech stack, then uses Claude to produce structured markdown "skill files" that Claude Code loads automatically when working in that codebase.
6
7```bash
8aspens scan # detect tech stack (current dir)
9aspens doc init --dry-run # preview generated skills
10aspens doc init --mode chunked # generate one domain at a time
11aspens doc sync --commits 3 # update skills from last 3 commits
12aspens doc sync --install-hook # auto-sync on every commit
13```
14
15## Project Setup
16
17```bash
18npm install # installs commander, @clack/prompts, picocolors
19npm link # makes `aspens` available globally for testing
20```
21
22No build step. No test runner configured yet — `tests/` is empty.
23
24## Architecture
25
26```
27bin/cli.js # entrypoint — welcome screen + subcommands via commander
28src/
29 index.js # barrel exports
30 commands/
31 scan.js # pretty/JSON output of scanner results
32 doc-init.js # full pipeline: scan → mode select → Claude → write
33 doc-sync.js # diff-based skill updates + git hook installer
34 add.js # placeholder (Phase 4)
35 lib/
36 scanner.js # deterministic tech stack detection (no LLM)
37 context-builder.js # assembles repo context (used by doc-sync, available for API mode)
38 runner.js # wraps `claude -p` CLI; prompt loading; output parsing; path sanitization
39 skill-writer.js # writes parsed {path, content} files to disk
40 prompts/
41 doc-init.md # all-at-once init prompt (tool-first: "read before writing")
42 doc-init-domain.md # single domain skill prompt (for chunked mode)
43 doc-init-claudemd.md # CLAUDE.md generation prompt
44 doc-sync.md # sync prompt (diff → skill updates)
45 partials/ # skill-format.md, guideline-format.md, examples.md
46```
47
48### `doc init` Pipeline
49
501. `scanRepo()` — detect languages, frameworks, structure, domains, entry points
512. User picks mode: all-at-once / chunked / pick domains / base-only
523. User picks strategy for existing docs: improve / rewrite / skip
534. `loadPrompt()` — resolve `{{partial-name}}` and `{{varName}}` in the template
545. `runClaude()` — spawn `claude -p` with `--allowedTools Read,Glob,Grep` — Claude explores the repo itself
556. `parseFileOutput()` — extract `<file path="...">content</file>` blocks from Claude's response
567. `writeSkillFiles()` — mkdir + write, respecting `--force` / `--dry-run`
57
58### `doc sync` Pipeline
59
601. Check prerequisites (git repo, .claude/skills/ exists)
612. Get git diff for last N commits
623. Map changed files → affected skills (via activation pattern matching, generic segments filtered)
634. Send diff + existing skills to Claude with Read/Glob/Grep tools
645. Claude updates only affected skills, outputs nothing if no changes needed
656. Write updated files (force mode — sync is meant to be automated)
66
67## Key Conventions
68
69### ES Modules
70The project uses `"type": "module"` — all files use `import`/`export`, no `require()`.
71
72### Path Handling
73Always resolve to absolute paths with `path.resolve()` / `path.join()`. Use `path.relative()` for display and stored paths. Never pass raw user-provided paths without resolving first.
74
75### Output Parsing
76Claude emits files as `<file path="...">content</file>`. `parseFileOutput()` handles this (primary) and an HTML comment fallback. Paths are validated by `sanitizePath()`: no `..`, no leading `/`, must be exactly `CLAUDE.md` or start with `.claude/`.
77
78### Prompt Templates
79Templates live in `src/prompts/`. `{{skill-format}}` in a template resolves to the full content of `src/prompts/partials/skill-format.md`. Other `{{varName}}` tokens are substituted from the `vars` object passed to `loadPrompt()`. Partials are resolved before variables.
80
81### Claude CLI Invocation
82`runner.js` spawns `claude -p` with `--allowedTools Read,Glob,Grep` — read-only tools so Claude can explore the codebase. For `--verbose` mode, uses `--output-format stream-json` to show real-time activity. Handles timeout (manual timer + SIGTERM), rate-limit detection, and non-zero exits.
83
84### Interactive UI
85Use `@clack/prompts` for all user-facing interaction (spinners, confirms, selects, multiselects). Use `picocolors` for inline color. `--mode` and `--strategy` flags allow non-interactive/CI usage.
86
87### Error Handling
88Throw descriptive errors with remediation hints. Commands call `process.exit(1)` on unrecoverable failures. File reads use try/catch and return `null` on failure. Doc init falls back to chunked mode on timeout.
89
90## Skill File Format
91
92Generated skills use YAML frontmatter followed by structured markdown:
93
94```markdown
95---
96name: domain-name
97description: One-line description
98---
99
100## Activation
101Triggers when editing these files:
102- `**/pattern*.js`
103
104---
105
106You are working on **description**.
107
108## Key Files
109## Key Concepts
110## Critical Rules
111```
112
113Skills are written to `.claude/skills/<name>/skill.md` in the target repo. The full spec is in `src/prompts/partials/skill-format.md`.
114
115## Phase Status
116
117| Phase | Status |
118|-------|--------|
119| 1: Scanner + Skill Format | Done |
120| 2: Doc Init (3 modes, improve/rewrite/skip, verbose, chunked) | Done |
121| 3: Doc Sync (git diff, skill mapping, hook installer) | Done |
122| 4: À La Carte Components | Planned |
123| 5: API Mode (Anthropic SDK) | Planned |
124| 6: Docs Site (Astro Starlight) | Planned |
125| 7: Launch (npm publish) | Planned |
126
@@ −1 +1 @@
1−# aspens
1+# Copilot Instructions
22
3−## Skills
3+## What This Project Does
44
5−- `.claude/skills/base/skill.md` — Base repo skill; load whenever working in this repo.
6−- `.claude/skills/agent-customization/skill.md` — LLM-powered injection of project context into installed agent templates via `aspens customize agents`
7−- `.claude/skills/claude-runner/skill.md` — Claude/Codex CLI execution layer — prompt loading, stream-json parsing, file output extraction, path sanitization, skill file writing, and skill rule generation
8−- `.claude/skills/cli-shell/skill.md` — Top-level Commander wiring, welcome screen, missing-hook warning, CliError exit handling, and the public programmatic API surface
9−- `.claude/skills/codex-support/skill.md` — Multi-target output system — target abstraction, backend routing, content transforms for Codex CLI and future targets
10−- `.claude/skills/doc-impact/skill.md` — Context health analysis — freshness, domain coverage, hub surfacing, drift detection, LLM-powered interpretation, and auto-repair for generated agent context
11−- `.claude/skills/doc-sync/skill.md` — Incremental skill updater that maps git diffs to affected skills and optionally auto-syncs via a post-commit hook
12−- `.claude/skills/import-graph/skill.md` — Static import analysis that builds dependency graphs, domain clusters, hub files, git churn hotspots, and file priority rankings
13−- `.claude/skills/repo-scanning/skill.md` — Deterministic repo analysis — language/framework detection, structure mapping, domain discovery, health checks, and import graph integration
14−- `.claude/skills/save-tokens/skill.md` — Token-saving session automation — statusline, prompt guard, precompact handoffs, session rotation, and handoff commands for Claude Code
15−- `.claude/skills/skill-generation/skill.md` — LLM-powered generation pipeline for Claude Code skills and CLAUDE.md — doc-init command, prompt system, context building, and output parsing
16−- `.claude/skills/template-library/skill.md` — Bundled agents, commands, hooks, and settings that users install via `aspens add`, `aspens doc init`, and `aspens save-tokens` into their .claude/ directories
5+`aspens` is a CLI tool that generates and maintains AI-ready documentation (skills and guidelines) for any codebase. It scans a repo's tech stack, then uses Claude to produce structured markdown "skill files" that Claude Code loads automatically when working in that codebase.
176
18−## Commands
7+```bash
8+aspens scan # detect tech stack (current dir)
9+aspens doc init --dry-run # preview generated skills
10+aspens doc init --mode chunked # generate one domain at a time
11+aspens doc sync --commits 3 # update skills from last 3 commits
12+aspens doc sync --install-hook # auto-sync on every commit
13+```
1914
20−- `npm test` — run Vitest (`vitest run`)
21−- `npm start` — run the CLI (`node bin/cli.js`)
22−- `npm run lint` — no-op check (`echo 'No linter configured yet' && exit 0`)
23−- `aspens scan [path]` — deterministic repo scan
24−- `aspens doc init [path]` — generate skills, hooks, and instructions file (`--target claude|codex|all`, `--recommended` for full recommended setup including save-tokens, agents, and doc-sync hook)
25−- `aspens doc impact [path]` — show freshness, coverage, drift, and LLM interpretation of generated context (interactive apply for repairs)
26−- `aspens doc sync [path]` — update docs from recent diffs
27−- `aspens doc graph [path]` — rebuild `.claude/graph.json`
28−- `aspens add <type> [name]` — install bundled templates
29−- `aspens customize agents` — inject project context into installed agents
30−- `aspens save-tokens [path]` — install token-saving session settings (`--recommended`, `--remove`)
15+## Project Setup
3116
32−## Release
17+```bash
18+npm install # installs commander, @clack/prompts, picocolors
19+npm link # makes `aspens` available globally for testing
20+```
3321
34−- Release workflow: `../dev/release.md`
22+No build step. No test runner configured yet — `tests/` is empty.
3523
36−## Conventions
24+## Architecture
3725
38−- ESM only: use `import`/`export`; never `require()`.
39−- Prefer `CliError` from command handlers; top-level handling lives in `bin/cli.js`.
40−- `es-module-lexer` must be initialized before `parse()`.
41−- Keep target/backend semantics straight: target is output format/location; backend is the generating CLI. Persist config in `.aspens.json`.
42−- Do not duplicate base-skill guidance here; consult `.claude/skills/base/skill.md` for deeper repo context.
26+```
27+bin/cli.js # entrypoint — welcome screen + subcommands via commander
28+src/
29+ index.js # barrel exports
30+ commands/
31+ scan.js # pretty/JSON output of scanner results
32+ doc-init.js # full pipeline: scan → mode select → Claude → write
33+ doc-sync.js # diff-based skill updates + git hook installer
34+ add.js # placeholder (Phase 4)
35+ lib/
36+ scanner.js # deterministic tech stack detection (no LLM)
37+ context-builder.js # assembles repo context (used by doc-sync, available for API mode)
38+ runner.js # wraps `claude -p` CLI; prompt loading; output parsing; path sanitization
39+ skill-writer.js # writes parsed {path, content} files to disk
40+ prompts/
41+ doc-init.md # all-at-once init prompt (tool-first: "read before writing")
42+ doc-init-domain.md # single domain skill prompt (for chunked mode)
43+ doc-init-claudemd.md # CLAUDE.md generation prompt
44+ doc-sync.md # sync prompt (diff → skill updates)
45+ partials/ # skill-format.md, guideline-format.md, examples.md
46+```
4347
44−## Behavior
48+### `doc init` Pipeline
4549
46−- **Verify before claiming** — Never state that something is configured, running, scheduled, or complete without confirming it first. If you haven't verified it in this session, say so rather than assuming.
47−- **Make sure code is running** — If you suggest code changes, ensure the code is running and tested before claiming the task is done.
48−- **Ask clarifying questions** — If the task is ambiguous, ask for clarification rather than making assumptions. Don't imply or guess at requirements or constraints that aren't explicitly stated.
49−- **Simplicity first** — Write the minimum code that solves the problem. No speculative features, abstractions for single-use code, or error handling for impossible scenarios.
50−- **Surgical changes** — Touch only what the task requires. Don't refactor adjacent code, fix unrelated formatting, or "improve" things that aren't broken.
50+1. `scanRepo()` — detect languages, frameworks, structure, domains, entry points
51+2. User picks mode: all-at-once / chunked / pick domains / base-only
52+3. User picks strategy for existing docs: improve / rewrite / skip
53+4. `loadPrompt()` — resolve `{{partial-name}}` and `{{varName}}` in the template
54+5. `runClaude()` — spawn `claude -p` with `--allowedTools Read,Glob,Grep` — Claude explores the repo itself
55+6. `parseFileOutput()` — extract `<file path="...">content</file>` blocks from Claude's response
56+7. `writeSkillFiles()` — mkdir + write, respecting `--force` / `--dry-run`
57+
58+### `doc sync` Pipeline
59+
60+1. Check prerequisites (git repo, .claude/skills/ exists)
61+2. Get git diff for last N commits
62+3. Map changed files → affected skills (via activation pattern matching, generic segments filtered)
63+4. Send diff + existing skills to Claude with Read/Glob/Grep tools
64+5. Claude updates only affected skills, outputs nothing if no changes needed
65+6. Write updated files (force mode — sync is meant to be automated)
66+
67+## Key Conventions
68+
69+### ES Modules
70+The project uses `"type": "module"` — all files use `import`/`export`, no `require()`.
71+
72+### Path Handling
73+Always resolve to absolute paths with `path.resolve()` / `path.join()`. Use `path.relative()` for display and stored paths. Never pass raw user-provided paths without resolving first.
74+
75+### Output Parsing
76+Claude emits files as `<file path="...">content</file>`. `parseFileOutput()` handles this (primary) and an HTML comment fallback. Paths are validated by `sanitizePath()`: no `..`, no leading `/`, must be exactly `CLAUDE.md` or start with `.claude/`.
77+
78+### Prompt Templates
79+Templates live in `src/prompts/`. `{{skill-format}}` in a template resolves to the full content of `src/prompts/partials/skill-format.md`. Other `{{varName}}` tokens are substituted from the `vars` object passed to `loadPrompt()`. Partials are resolved before variables.
80+
81+### Claude CLI Invocation
82+`runner.js` spawns `claude -p` with `--allowedTools Read,Glob,Grep` — read-only tools so Claude can explore the codebase. For `--verbose` mode, uses `--output-format stream-json` to show real-time activity. Handles timeout (manual timer + SIGTERM), rate-limit detection, and non-zero exits.
83+
84+### Interactive UI
85+Use `@clack/prompts` for all user-facing interaction (spinners, confirms, selects, multiselects). Use `picocolors` for inline color. `--mode` and `--strategy` flags allow non-interactive/CI usage.
86+
87+### Error Handling
88+Throw descriptive errors with remediation hints. Commands call `process.exit(1)` on unrecoverable failures. File reads use try/catch and return `null` on failure. Doc init falls back to chunked mode on timeout.
89+
90+## Skill File Format
91+
92+Generated skills use YAML frontmatter followed by structured markdown:
93+
94+```markdown
95+---
96+name: domain-name
97+description: One-line description
98+---
99+
100+## Activation
101+Triggers when editing these files:
102+- `**/pattern*.js`
103+
104+---
105+
106+You are working on **description**.
107+
108+## Key Files
109+## Key Concepts
110+## Critical Rules
111+```
112+
113+Skills are written to `.claude/skills/<name>/skill.md` in the target repo. The full spec is in `src/prompts/partials/skill-format.md`.
114+
115+## Phase Status
116+
117+| Phase | Status |
118+|-------|--------|
119+| 1: Scanner + Skill Format | Done |
120+| 2: Doc Init (3 modes, improve/rewrite/skip, verbose, chunked) | Done |
121+| 3: Doc Sync (git diff, skill mapping, hook installer) | Done |
122+| 4: À La Carte Components | Planned |
123+| 5: API Mode (Anthropic SDK) | Planned |
124+| 6: Docs Site (Astro Starlight) | Planned |
125+| 7: Launch (npm publish) | Planned |
51126
