Copilot instructions

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