Skip to content
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions .agents/skills/architecture/references/code-map.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,19 @@

**Hub files (most depended-on):**
- `src/lib/runner.js` - 8 dependents
- `src/lib/scanner.js` - 8 dependents
- `src/lib/target.js` - 8 dependents
- `src/lib/errors.js` - 7 dependents
- `src/lib/scanner.js` - 7 dependents
- `src/lib/target.js` - 7 dependents
- `src/lib/skill-writer.js` - 6 dependents
- `src/lib/graph-builder.js` - 6 dependents

**Domain clusters:**

| Domain | Files | Top entries |
|--------|-------|-------------|
| src | 37 | `src/lib/runner.js`, `src/commands/doc-init.js`, `src/commands/doc-sync.js` |
| src | 40 | `src/lib/runner.js`, `src/commands/doc-init.js`, `src/lib/target.js` |

**High-churn hotspots:**
- `src/commands/doc-init.js` - 27 changes
- `src/commands/doc-sync.js` - 19 changes
- `src/commands/doc-init.js` - 28 changes
- `src/commands/doc-sync.js` - 20 changes
- `src/lib/runner.js` - 16 changes

15 changes: 9 additions & 6 deletions .agents/skills/base/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ This is a **base skill** that always loads when working in this repository.

---

You are working in **aspens** — a CLI tool that generates and maintains AI-ready documentation (skill files + AGENTS.md) for any codebase. Supports multiple output targets (Claude Code, Codex CLI).
You are working in **aspens** — a CLI that keeps coding-agent context accurate as your codebase changes. Scans repos, generates project-specific instructions and skills for Claude Code and Codex CLI, and keeps them fresh.

## Tech Stack
Node.js (ESM) | Commander | Vitest | es-module-lexer | @clack/prompts | picocolors
Expand All @@ -18,7 +18,8 @@ Node.js (ESM) | Commander | Vitest | es-module-lexer | @clack/prompts | picocolo
- `npm test` — Run vitest suite
- `npm start` / `node bin/cli.js` — Run CLI
- `aspens scan [path]` — Deterministic repo analysis (no LLM)
- `aspens doc init [path]` — Generate skills + hooks + AGENTS.md (supports `--target claude|codex|all`, `--backend claude|codex`)
- `aspens doc init [path]` — Generate skills + hooks + AGENTS.md (`--target claude|codex|all`, `--recommended` for smart defaults)
- `aspens doc impact [path]` — Show freshness, coverage, and drift of generated context
Comment thread
mvoutov marked this conversation as resolved.
Resolved
- `aspens doc sync [path]` — Incremental skill updates from git diffs
- `aspens doc graph [path]` — Rebuild import graph cache (`.claude/graph.json`)
- `aspens add <type> [name]` — Install templates (agents, commands, hooks)
Expand All @@ -35,8 +36,9 @@ CLI entry (`bin/cli.js`) → command handlers (`src/commands/`) → lib modules
- `src/lib/skill-writer.js` — Writes skill files and directory-scoped files, generates skill-rules.json, merges settings
- `src/lib/skill-reader.js` — Parses skill files, frontmatter, activation patterns, keywords
- `src/lib/diff-helpers.js` — Targeted file diffs and prioritized diff truncation for doc-sync
- `src/lib/git-helpers.js` — Git repo detection, diff retrieval, log formatting
- `src/lib/git-hook.js` — Post-commit git hook installation/removal for auto doc-sync
- `src/lib/git-helpers.js` — Git repo detection, git root resolution, diff retrieval, log formatting
- `src/lib/git-hook.js` — Post-commit git hook installation/removal for auto doc-sync (monorepo-aware)
- `src/lib/impact.js` — Context health analysis: domain coverage, hub surfacing, drift detection
- `src/lib/timeout.js` — Timeout resolution (`--timeout` flag > `ASPENS_TIMEOUT` env > default)
- `src/lib/errors.js` — `CliError` class (structured errors caught by CLI top-level handler)
- `src/lib/target.js` — Target definitions (claude/codex), config persistence (`.aspens.json`)
Expand All @@ -55,14 +57,15 @@ CLI entry (`bin/cli.js`) → command handlers (`src/commands/`) → lib modules
- **Target/Backend distinction** — Target = output format/location; Backend = which LLM CLI generates content. Config persisted in `.aspens.json`
- **Scanner is deterministic** — no LLM calls; pure filesystem analysis
- **CliError pattern** — command handlers throw `CliError` instead of calling `process.exit()`; caught at top level in `bin/cli.js`
- **Monorepo support** — `getGitRoot()` resolves the actual git root; hooks, sync, and impact scope to the subdirectory project path

## Structure
- `bin/` — CLI entry point (commander setup, CliError handler)
- `src/commands/` — Command handlers (scan, doc-init, doc-sync, doc-graph, add, customize)
- `src/commands/` — Command handlers (scan, doc-init, doc-impact, doc-sync, doc-graph, add, customize)
- `src/lib/` — Core library modules
- `src/prompts/` — Prompt templates + partials
- `src/templates/` — Installable agents, commands, hooks, settings
- `tests/` — Vitest test files

---
**Last Updated:** 2026-04-02
**Last Updated:** 2026-04-08
47 changes: 47 additions & 0 deletions .agents/skills/doc-impact/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
---
name: doc-impact
description: Context health analysis — freshness, domain coverage, hub surfacing, drift detection for generated agent context
---

## Activation

This skill triggers when editing doc-impact files:
- `src/commands/doc-impact.js`
- `src/lib/impact.js`
- `tests/impact.test.js`

Keywords: impact, freshness, coverage, drift, health score, context health

---

You are working on **doc impact** — the command that shows whether generated agent context is keeping up with the codebase.

## Key Files
- `src/commands/doc-impact.js` — CLI command: calls `analyzeImpact()`, renders per-target report with health scores, coverage, drift, and recommended actions
- `src/lib/impact.js` — Core analysis: `analyzeImpact()` orchestrates scan + config + graph + per-target summarization
- `tests/impact.test.js` — Unit tests for coverage, drift, health score, status, and report summarization

## Key Concepts
- **`analyzeImpact(repoPath, options)`** — Main entry point. Runs `scanRepo()`, loads config from `.aspens.json`, infers targets if not configured, collects source file state, optionally builds import graph, then produces per-target reports.
- **Target inference:** If no `.aspens.json` config, infers targets from scan results (`.claude/` → claude, `.agents/` → codex). Falls back to `['claude']`.
- **`summarizeTarget()`** — Per-target analysis: finds skills, checks instruction file existence, computes domain coverage, hub coverage, drift, status, health score, and recommended actions.
- **Domain coverage:** `computeDomainCoverage()` matches scan-detected domains against installed skills by name match or activation pattern match. Returns covered/missing counts with reasons.
- **Hub coverage:** `computeHubCoverage()` checks if top 5 graph hub file paths appear in the instruction file + base skill text.
- **Drift detection:** `computeDrift()` finds source files modified after the latest generated context mtime. Maps changed files to affected domains via directory matching.
- **Health score:** `computeHealthScore()` starts at 100, deducts for: missing instructions (-35), no skills (-25), domain gaps (up to -25), missed hubs (-4 each), drift (-3 per file, max -20), missing hooks (-10 for Claude).
- **Source state collection:** `collectSourceState()` walks repo (depth 5, skips dotfiles/node_modules/dist/build/coverage), collects mtime for source extensions only (`SOURCE_EXTS` set).
- **Recommended actions:** `recommendActions()` suggests `aspens doc init --recommended` for missing context, `aspens doc sync` for stale context, `aspens doc init --hooks-only` for missing hooks.

## Critical Rules
- **No LLM calls** — impact analysis is fully deterministic (scan + filesystem + optional graph).
- **`--no-graph` flag** — skips import graph build; hub coverage section shows `n/a`.
- **Graph failure is non-fatal** — if `buildRepoGraph` throws, graph is set to null and analysis continues without hub data.
- **`SOURCE_EXTS` set** — only these extensions count as source files for drift detection. Adding a language requires updating this set.
- **Walk depth capped at 5** — deep nested source files won't appear in drift analysis.
- **Exported functions** — `computeDomainCoverage`, `computeHubCoverage`, `computeDrift`, `computeHealthScore`, `computeTargetStatus`, `recommendActions`, `summarizeReport` are all individually exported for testing.

## References
- **Patterns:** `src/lib/skill-reader.js` — `findSkillFiles()` used for skill discovery per target

---
**Last Updated:** 2026-04-08
12 changes: 7 additions & 5 deletions .agents/skills/doc-sync/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,18 +23,19 @@ You are working on **doc-sync**, the incremental skill update command (`aspens d
- `src/commands/doc-sync.js` — Main command: git diff → graph rebuild → skill mapping → LLM update → publish for targets → write. Also contains refresh mode and `skillToDomain()` export.
- `src/prompts/doc-sync.md` — System prompt for diff-based sync (uses `{{skill-format}}` partial, target-specific path variables)
- `src/prompts/doc-sync-refresh.md` — System prompt for `--refresh` mode (full skill review)
- `src/lib/git-helpers.js` — `isGitRepo()`, `getGitDiff()`, `getGitLog()`, `getChangedFiles()` — git primitives
- `src/lib/git-helpers.js` — `getGitRoot()`, `isGitRepo()`, `getGitDiff()`, `getGitLog()`, `getChangedFiles()` — git primitives
- `src/lib/diff-helpers.js` — `getSelectedFilesDiff()`, `buildPrioritizedDiff()`, `truncateDiff()`, `truncate()` — diff budgeting
- `src/lib/git-hook.js` — `installGitHook()` / `removeGitHook()` for post-commit auto-sync
- `src/lib/git-hook.js` — `installGitHook()` / `removeGitHook()` for post-commit auto-sync (monorepo-aware)
- `src/lib/context-builder.js` — `buildDomainContext()`, `buildBaseContext()` used by refresh mode
- `src/lib/runner.js` — `runLLM()`, `loadPrompt()`, `parseFileOutput()` shared across commands
- `src/lib/skill-writer.js` — `writeSkillFiles()`, `writeTransformedFiles()`, `extractRulesFromSkills()` for output
- `src/lib/target-transform.js` — `projectCodexDomainDocs()`, `transformForTarget()` for multi-target publish

## Key Concepts
- **Monorepo-aware:** `getGitRoot(repoPath)` resolves the actual git root. `projectPrefix` (`toGitRelative`) computes the subdirectory offset. `scopeProjectFiles()` filters changed files to the project subdirectory. Diffs are fetched from `gitRoot` but file paths are project-relative.
- **Multi-target publish:** `configuredTargets()` reads `.aspens.json` for all configured targets. `chooseSyncSourceTarget()` picks the best source (prefers Claude if both exist). LLM generates for the source target; `publishFilesForTargets()` transforms output for all other configured targets. `graphSerialized` is passed through to control conditional architecture references.
- **Backend routing:** `runLLM()` from `runner.js` dispatches to `runClaude()` or `runCodex()` based on `config.backend` (defaults to source target's id).
- **Diff-based flow:** Gets `git diff HEAD~N..HEAD` and `git log`, feeds them plus existing skill contents and graph context to the selected backend.
- **Diff-based flow:** Gets `git diff HEAD~N..HEAD` from git root, scopes changed files to project prefix, then feeds diff plus existing skill contents and graph context to the selected backend.
- **Prompt path variables:** Passes `{ skillsDir, skillFilename, instructionsFile, configDir }` from source target to `loadPrompt()` for path substitution in prompts.
- **Refresh mode (`--refresh`):** Skips diff entirely. Reviews every skill against the current codebase. Base skill refreshed first, then domain skills in parallel batches of `PARALLEL_LIMIT` (3). Also refreshes instructions file and reports uncovered domains.
- **Graph rebuild on every sync:** Calls `buildRepoGraph` + `persistGraphArtifacts` (with source target) to keep graph fresh. `graphSerialized` return value is captured and forwarded to `publishFilesForTargets` for conditional Codex architecture refs. Graph failure is non-fatal.
Expand All @@ -46,7 +47,7 @@ You are working on **doc-sync**, the incremental skill update command (`aspens d
- **Split writes:** Direct-write files (`.claude/`, `AGENTS.md`, root `AGENTS.md`) use `writeSkillFiles()`. Directory-scoped `AGENTS.md` files (e.g. `src/AGENTS.md`) use `writeTransformedFiles()`.
- **Skill-rules regeneration:** After writing, regenerates `skill-rules.json` via `extractRulesFromSkills()` — only for targets with `supportsHooks: true` (Claude). Uses `hookTarget` from publish targets list.
- **`findExistingSkills` is target-aware:** Uses `target.skillsDir` and `target.skillFilename` to locate skills for any target.
- **Git hook:** `installGitHook()` creates a `post-commit` hook with 5-minute cooldown lock file. Hook skips aspens-only commits (filters `.claude/`, `.codex/`, `.agents/`, `AGENTS.md`, `AGENTS.md`, `.aspens.json`). Works for all configured targets.
- **Git hook (monorepo-aware):** `installGitHook()` installs at the git root with per-project scoping. Hook uses `PROJECT_PATH` derived from project-relative offset. Each subproject gets its own labeled hook block (`# >>> aspens doc-sync hook (label) >>>`) with a unique function name (`__aspens_doc_sync_<slug>`). Multiple subprojects can coexist in one post-commit hook. Hook skips aspens-only commits scoped to the project prefix.
- **Force writes:** doc-sync always calls `writeSkillFiles` with `force: true`.

## Critical Rules
Expand All @@ -57,9 +58,10 @@ You are working on **doc-sync**, the incremental skill update command (`aspens d
- The command exits early with `CliError` if the source target's skills directory doesn't exist.
- `checkMissingHooks()` in `bin/cli.js` only checks for Claude skills (not Codex — Codex doesn't use hooks).
- `dedupeFiles()` ensures no duplicate paths when publishing across multiple targets.
- **Git operations use `gitRoot`** — diffs, logs, and changed files are fetched from git root, not `repoPath`. File paths are then scoped via `projectPrefix`.

## References
- **Patterns:** `src/lib/skill-reader.js` — `GENERIC_PATH_SEGMENTS`, `fileMatchesActivation()`, `getActivationBlock()`

---
**Last Updated:** 2026-04-07
**Last Updated:** 2026-04-08
Loading
Loading