john/claude-engineering-plugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add new onboarding skill to create onboarding guide for repo (#384)

Browse Source
This commit is contained in:
Trevin Chow
2026-03-25 21:30:09 -07:00
committed by GitHub
parent 355e7392b2
commit 27b9831084
8 changed files with 1553 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
docs/brainstorms/2026-03-25-vonboarding-skill-requirements.md Normal file
View File

@@ -0,0 +1,62 @@
---
date: 2026-03-25
topic: onboarding-skill
---
# Onboarding: Codebase Onboarding Document Generator
## Problem Frame
Onboarding is a general problem in software, but it is more acute in fast-moving codebases where code is written faster than documentation — whether through AI-assisted development, rapid prototyping, or simply a team that ships faster than it documents. The traditional assumption that the creator can explain the codebase breaks down when they didn't fully understand it to begin with, or when the codebase has evolved beyond any one person's mental model. New team members (and AI agents brought into the project) are left without the mental model they need to contribute effectively.
The primary audience is human developers. A document that works for human comprehension is also effective as agent context, but the inverse is not true.
## Requirements
- R1. A skill named `onboarding` that crawls a repository and generates `ONBOARDING.md` at the repo root
- R2. The skill always regenerates the full document from scratch — no surgical updates or diffing against a previous version
- R3. The document has a fixed filename (`ONBOARDING.md`) so the skill can detect whether one already exists; existence is the only state — no separate mode flag
- R4. The document contains exactly five sections, each earning its place by answering a question a new contributor will ask in their first hour:
- **What is this thing?** — Purpose, who it's for, what problem it solves
- **How is it organized?** — Architecture, key modules, how they connect, and what the system depends on externally (databases, APIs, services, env vars)
- **Key concepts and abstractions** — The vocabulary and architectural patterns needed to talk about and reason about this codebase
- **Primary flow** — One concrete path through the system showing how the pieces connect (the main thing the app does)
- **Where do I start?** — Dev setup, how to run it, where to make common types of changes
- R5. During the crawl, if `docs/solutions/` or other existing documentation is discovered and is directly relevant to a section's content, link to it inline within that section. Do not create a separate references/further-reading section. If no relevant docs exist, the document stands on its own without mentioning their absence.
- R6. The document is written for human comprehension first — clear prose, not agent-formatted structured data
- R7. Use visual aids — ASCII diagrams, markdown tables — where they improve readability over prose. Architecture overviews and flow traces especially benefit from diagrams.
- R8. Use proper markdown formatting throughout — backticks for file names, paths, commands, code references, and technical terms. Consistent styling maximizes legibility.
## Success Criteria
- A new contributor can read `ONBOARDING.md` and understand the codebase well enough to start making changes without needing the creator to explain it
- The document is useful even when the creator themselves doesn't fully understand the architecture
- Running the skill again on an evolved codebase produces an accurate, current document (no stale information carried over)
## Scope Boundaries
- Does not attempt to infer or fabricate design rationale ("why was X chosen over Y") — the creator may not know, and presenting guesses as fact is worse than saying nothing
- Does not assess fragility or risk areas — that requires judgment about production behavior the agent doesn't have
- Does not generate README.md, CLAUDE.md, AGENTS.md, or any other document — only `ONBOARDING.md`
- Does not preserve hand-edits from a previous version on regeneration — if users want durable authored context, it belongs in other docs (which the skill may discover and link to)
- No `ce:` prefix — this is a standalone utility skill, not part of the core workflow
## Key Decisions
- **Always regenerate, never update**: Reading the old document to update it means the agent does two jobs (understand the codebase + fact-check the old doc). That's slower and more error-prone than regenerating.
- **Five sections, no more**: Every section must earn its place by answering a question a new person will actually ask. No speculative sections "just in case."
- **Inline linking only**: Existing docs are surfaced within relevant sections, not collected in an appendix. This is opportunistic — works fine when nothing exists to link to.
- **Human-first writing**: The document targets human readers. Agent utility is a natural side effect of clear prose, not a separate design goal.
## Outstanding Questions
### Deferred to Planning
- [Affects R1][Technical] How should the skill orchestrate the crawl — single-pass or dispatch sub-agents for different sections?
- [Affects R4][Technical] What crawl strategy produces the best "Primary flow" section — entry point tracing, route analysis, or something else?
- [Affects R4][Needs research] What's the right depth/length target for each section to be useful without becoming a wall of text?
- [Affects R5][Technical] What heuristic determines whether a discovered doc is "directly relevant" to a section versus noise?
## Next Steps
-> `/ce:plan` for structured implementation planning

2
docs/plans/2026-03-01-feat-ce-command-aliases-backwards-compatible-deprecation-plan.md
View File

@@ -1,7 +1,7 @@
---
title: "feat: Add ce:* command aliases with backwards-compatible deprecation of workflows:*"
type: feat
status: active
status: complete
date: 2026-03-01
---

2
docs/plans/2026-03-16-001-feat-issue-grounded-ideation-plan.md
View File

@@ -1,7 +1,7 @@
---
title: "feat: Add issue-grounded ideation mode to ce:ideate"
type: feat
status: active
status: complete
date: 2026-03-16
origin: docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md
---

281
docs/plans/2026-03-25-001-feat-onboarding-skill-plan.md Normal file
View File

@@ -0,0 +1,281 @@
---
title: "feat: Add onboarding skill to generate ONBOARDING.md from repo crawl"
type: feat
status: complete
date: 2026-03-25
origin: docs/brainstorms/2026-03-25-vonboarding-skill-requirements.md
---
# feat: Add onboarding skill to generate ONBOARDING.md from repo crawl
## Overview
Add an `/onboarding` skill to the compound-engineering plugin that crawls a repository and generates `ONBOARDING.md` at the repo root. The skill uses a bundled inventory script for deterministic data gathering and model judgment for narrative synthesis, producing a document that helps new contributors understand the codebase without requiring the creator to explain it.
## Problem Frame
When a codebase is built through AI-assisted "vibe coding," the creator may not fully understand their own architecture. New team members are left without the mental model they need to contribute. The onboarding document reconstructs this mental model from the code itself.
The primary audience is human developers. A document that works for human comprehension is also effective as agent context, but the inverse is not true. (see origin: `docs/brainstorms/2026-03-25-vonboarding-skill-requirements.md`)
## Requirements Trace
- R1. A skill named `onboarding` that crawls a repository and generates `ONBOARDING.md` at the repo root
- R2. The skill always regenerates the full document from scratch -- no surgical updates or diffing
- R3. Fixed filename (`ONBOARDING.md`) is the only state -- exists means refresh, doesn't exist means create
- R4. Exactly five sections: What is this thing? / How is it organized? / Key concepts / Primary flow / Where do I start?
- R5. Inline-link existing docs when directly relevant to a section; no separate references section
- R6. Written for human comprehension first -- clear prose, not structured data
- R7. Use visual aids -- ASCII diagrams, markdown tables -- where they improve readability over prose
- R8. Proper markdown formatting throughout -- backticks for file names, paths, commands, code references, and technical terms
## Scope Boundaries
- Does not infer or fabricate design rationale
- Does not assess fragility or risk areas
- Does not generate README.md, CLAUDE.md, AGENTS.md, or any other document
- Does not preserve hand-edits from a previous version
- No `ce:` prefix -- standalone utility skill
- No new agents -- the skill uses a bundled script plus the model's own file-reading and writing capabilities
## Context & Research
### Relevant Code and Patterns
- Skills live in `plugins/compound-engineering/skills/<name>/SKILL.md` with optional `scripts/`, `references/`, `assets/` directories
- Skills are auto-discovered from directory structure -- no registration in `plugin.json`
- SKILL.md requires YAML frontmatter with `name` and `description` fields
- Arguments received via `#$ARGUMENTS` interpolation in an XML tag
- Platform-agnostic interaction: use capability-class tool descriptions with platform hints
- Reference files must be proper markdown links, not bare backtick paths
### Institutional Learnings
- **Script-first skill architecture** (`docs/solutions/skill-design/script-first-skill-architecture.md`): Move deterministic processing into bundled scripts; model does judgment work only. 60-75% token reduction. Applies here as a hybrid -- script gathers structural inventory, model reads key files and writes prose.
- **Compound-refresh skill improvements** (`docs/solutions/skill-design/compound-refresh-skill-improvements.md`): Triage before asking (don't ask users what to document); platform-agnostic tool references; subagents should use file tools not shell; no contradictory rules across phases.
- Skill compliance checklist in `plugins/compound-engineering/AGENTS.md`: imperative voice, no second person, cross-platform question tool patterns, markdown-linked references.
## Key Technical Decisions
- **Hybrid script-first architecture**: The inventory script handles deterministic work (file tree, manifest parsing, framework detection, entry point identification, doc discovery). The model handles judgment work (reading key files, understanding architecture, tracing flows, writing prose). This follows the institutional pattern and avoids burning tokens on mechanical directory traversal.
- **No sub-agent dispatch**: The five sections are interdependent -- understanding architecture informs the primary flow, domain terms appear across sections. A single model pass produces a more coherent document than independent sub-agents writing sections in isolation. The inventory script provides the structural grounding the model needs.
- **No `repo-research-analyst` dependency**: That agent produces research-formatted output for planning skills. Using it would add a layer of indirection (research output -> re-synthesis into human prose). A simpler inventory script gives the model raw facts and lets it write directly for the human audience.
- **Universal inventory script**: The script must work across any language/framework by detecting from manifests and conventional directory locations. It does not parse code ASTs or read file contents -- those are model tasks.
- **No explicit create/refresh mode**: The skill always regenerates. The SKILL.md need not branch on whether `ONBOARDING.md` exists -- the behavior is identical either way.
## Open Questions
### Resolved During Planning
- **Orchestration strategy**: Single-pass with bundled inventory script. Sub-agents per section would create overlapping crawls and lose cross-section coherence. The document is short enough for one model pass.
- **Primary flow strategy**: Entry point tracing guided by inventory. The script identifies entry points; the model reads the primary one and follows the main user-facing path through imports and calls.
- **Section depth/length**: No prescriptive line counts. Guiding principle: each section answers its question concisely enough that a new person reads the entire document. Total should be readable in under 10 minutes.
- **Doc relevance heuristic**: Model judgment during writing. The inventory lists existing docs; when the model writes about a topic and a discovered doc is relevant, it links inline. No programmatic relevance scoring.
### Deferred to Implementation
- Exact JSON schema for inventory script output -- the shape will be refined when writing the script against real repos
- Which conventional entry point locations to check per ecosystem -- will be enumerated during script implementation
- Precise wording of the section writing guidance in SKILL.md -- will iterate during implementation
## Implementation Units
- [ ] **Unit 1: Create the inventory script**
**Goal:** Build a Node.js script that produces a structured JSON inventory of any repository, giving the model a map to work from without burning tokens on directory traversal.
**Requirements:** R1 (crawl mechanism), R5 (doc discovery)
**Dependencies:** None
**Files:**
- Create: `plugins/compound-engineering/skills/onboarding/scripts/inventory.mjs`
- Test: `tests/onboarding-inventory.test.ts`
**Approach:**
The script accepts an optional `--root <path>` argument (defaults to cwd) and writes JSON to stdout. It gathers:
- **Project identity**: Name from the nearest manifest (package.json `name`, Cargo.toml `[package].name`, go.mod module path, etc.), falling back to directory name
- **Languages and frameworks**: Detected from manifest files using the same ecosystem mapping table as `repo-research-analyst` Phase 0.1. Extract language, major framework dependencies, and versions from each manifest found. Include package manager and test framework when detectable.
- **Directory structure**: Top-level directories plus one level into `src/`, `lib/`, `app/`, `pkg/`, `internal/` (or equivalent). Cap at 2 levels deep. Exclude `node_modules/`, `.git/`, `vendor/`, `target/`, `dist/`, `build/`, `__pycache__/`, `.next/`, `.cache/`, and other common build/dependency directories.
- **Entry points**: Check conventional locations per detected ecosystem:
- Node/TS: `src/index.*`, `src/main.*`, `src/app.*`, `index.*`, `server.*`, `app.*`, `pages/`, `app/` (Next.js)
- Python: `main.py`, `app.py`, `manage.py`, `src/<project>/`, `__main__.py`
- Ruby: `config/routes.rb`, `app/controllers/`, `bin/rails`, `config.ru`
- Go: `main.go`, `cmd/*/main.go`
- Rust: `src/main.rs`, `src/lib.rs`
- General: `Makefile`, `Procfile` targets
- **Scripts/commands**: Extract from `package.json` scripts, Makefile targets, or equivalent. Focus on dev, build, test, start, and lint commands.
- **Existing documentation**: Find markdown files in repo root and common doc directories (`docs/`, `doc/`, `documentation/`, `docs/solutions/`, `wiki/`). List paths only, don't read contents.
- **Test infrastructure**: Detect test directories and config files (`tests/`, `test/`, `spec/`, `__tests__/`, `jest.config.*`, `vitest.config.*`, `.rspec`, `pytest.ini`, `conftest.py`)
Output shape (directional -- exact fields will be refined during implementation):
```
{
"name": "...",
"languages": [...],
"frameworks": [...],
"packageManager": "...",
"testFramework": "...",
"structure": { "topLevel": [...], "srcLayout": [...] },
"entryPoints": [...],
"scripts": { ... },
"docs": [...],
"testInfra": { "dirs": [...], "config": [...] }
}
```
The script must:
- Use only Node.js built-in modules (`fs`, `path`, `child_process` for git-tracked file list if useful)
- Exit 0 and output valid JSON even when manifests are missing or unparseable
- Be fast -- no network calls, no AST parsing, bounded directory traversal
- Handle monorepos gracefully (list workspace structure without recursing into every package)
**Patterns to follow:**
- `skills/claude-permissions-optimizer/scripts/extract-commands.mjs` -- script-first pattern, JSON output, CLI flags, Node.js built-ins only
**Test scenarios:**
- Script produces valid JSON for a minimal repo (just a README)
- Script detects Node.js ecosystem from `package.json`
- Script detects multiple languages in a polyglot repo
- Script respects directory depth limits
- Script excludes common build/dependency directories
- Script exits 0 with empty/partial JSON when manifests are malformed
- Script finds entry points for at least Node, Python, and Ruby ecosystems
- Script discovers docs in standard locations
**Verification:**
- Running the script against the compound-engineering repo produces sensible output
- JSON output parses without error
- Script completes in under 5 seconds on a typical repo
- [ ] **Unit 2: Create the SKILL.md**
**Goal:** Write the skill definition that orchestrates the inventory script, guided file reading, and narrative synthesis into `ONBOARDING.md`.
**Requirements:** R1, R2, R3, R4, R5, R6, R7, R8
**Dependencies:** Unit 1
**Files:**
- Create: `plugins/compound-engineering/skills/onboarding/SKILL.md`
**Approach:**
The SKILL.md contains:
1. **Frontmatter**: `name: onboarding`, description that covers what it does and when to use it, `argument-hint` for optional scope/focus hints.
2. **Execution flow** with three phases:
**Phase 1: Gather inventory.** Run the bundled script. Parse the JSON output. This gives the model a structural map of the repo without reading every file.
**Phase 2: Read key files.** Guided by the inventory, read files that are essential for understanding the codebase:
- README.md (if exists) -- for project purpose and setup
- Primary entry points identified by the script
- Route/controller files (for understanding the primary flow)
- Configuration files that reveal architecture (e.g., docker-compose, database config)
- A sample of the discovered documentation files (for inline linking in Phase 3)
Cap the reading at a reasonable number of files (~10-15 key files) to avoid context bloat. Prioritize entry points and routes over config files. Use the native file-read tool, not shell commands.
**Phase 3: Write ONBOARDING.md.** Synthesize everything into the five sections. Guidance for each section:
- **What is this thing?** -- Draw from README, manifest descriptions, and entry point examination. State the purpose, who it's for, and what problem it solves. If this can't be determined, say so plainly rather than fabricating.
- **How is it organized?** -- Use the inventory structure plus what was learned from reading key files. Describe the architecture, key modules, and how they connect. Use an ASCII directory tree to show the high-level structure. Use a markdown table when listing modules with their responsibilities.
- **Key concepts / domain terms** -- Extract domain vocabulary from code (class names, module names, database tables, API endpoints) and explain each in one sentence. Present as a markdown table (`| Term | Definition |`) for scanability. These are the words someone needs to talk about this codebase.
- **Primary flow** -- Trace one concrete path from the user's perspective. Start with the main thing the app does (e.g., "when a user submits an order..."), then walk through the code path: which file handles the request, what services it calls, where data is stored. Use an ASCII flow diagram to visualize the path (e.g., `Request -> Router -> Controller -> Service -> DB`). Reference specific file paths at each step.
- **Where do I start?** -- Dev setup from README or scripts. How to run the app, how to run tests. Where to make common types of changes (e.g., "to add a new API endpoint, look at `src/routes/`"). List the 2-3 most common change patterns.
For each section: if a discovered documentation file is directly relevant to what the section is explaining, link to it inline (e.g., "authentication uses token-based middleware -- see `docs/solutions/auth-pattern.md` for details"). Do not create a separate references section. If no relevant docs exist, the section stands alone.
3. **Quality bar**: Before writing the file, verify:
- Every section answers its question without padding
- No fabricated design rationale or fragility assessments
- File paths referenced in the document actually exist in the inventory
- Prose is written for a human developer, not formatted as agent-consumable structured data
- Existing docs are linked inline only where directly relevant, not collected in an appendix
- All file names, paths, commands, code references, and technical terms use backtick formatting
- Markdown styling is consistent throughout (headers, bold, code blocks, tables)
4. **Post-generation options**: After writing, present options using the platform's blocking question tool:
- Open the file for review
- Commit the file
- Done
**Patterns to follow:**
- `skills/ce-plan/SKILL.md` -- research-then-write orchestration, platform-agnostic tool references
- `skills/claude-permissions-optimizer/SKILL.md` -- script-first execution pattern
- Skill compliance checklist in `plugins/compound-engineering/AGENTS.md`
**Test scenarios:**
- The skill description triggers on "generate onboarding", "onboard new contributor", "create ONBOARDING.md", "document this codebase for new developers"
- The skill runs the inventory script as its first action
- The skill reads key files identified by inventory, not arbitrary files
- The generated ONBOARDING.md contains exactly five sections
- The skill does not ask the user what to document -- it triages autonomously
- File paths referenced in ONBOARDING.md correspond to real files in the repo
**Verification:**
- SKILL.md passes the compliance checklist (no hardcoded tool names, imperative voice, markdown-linked scripts, platform-agnostic question patterns)
- Running the skill against a real repo produces a readable ONBOARDING.md with all five sections
- Re-running the skill regenerates the file from scratch (no diffing or updating behavior)
- [ ] **Unit 3: Update README and validate plugin**
**Goal:** Register the new skill in the plugin README and verify plugin consistency.
**Requirements:** R1
**Dependencies:** Unit 2
**Files:**
- Modify: `plugins/compound-engineering/README.md`
**Approach:**
Add `onboarding` to the **Workflow Utilities** table in README.md:
```
| `/onboarding` | Generate ONBOARDING.md to help new contributors understand the codebase |
```
Update the skill count in the Components table if it's now inaccurate (currently "40+").
**Patterns to follow:**
- Existing README skill table format and descriptions
**Test scenarios:**
- Skill appears in the correct category table
- Description is concise and matches SKILL.md description intent
- Component count is accurate
**Verification:**
- `bun run release:validate` passes
- README skill count matches actual skill count
## System-Wide Impact
- **Interaction graph:** The skill is standalone -- no callbacks, middleware, or cross-skill dependencies. Other skills do not invoke it.
- **Error propagation:** If the inventory script fails (malformed JSON, permission error), the skill should report the error and stop rather than attempting to write ONBOARDING.md from incomplete data.
- **API surface parity:** The skill outputs a file, not an API. No parity concerns.
- **Integration coverage:** Manual testing against a real repo is the primary integration check. The inventory script gets unit tests.
## Risks & Dependencies
- **Inventory script universality**: The script needs to handle repos in any language/framework. Risk: edge cases in ecosystem detection for less common stacks. Mitigation: start with the most common ecosystems (Node, Python, Ruby, Go, Rust) and degrade gracefully for others (still produce structure and docs, just skip framework-specific entry point detection).
- **Output quality variance**: The quality of ONBOARDING.md depends heavily on the model's synthesis ability, which varies by codebase complexity. Mitigation: the quality bar in SKILL.md sets clear expectations, and the five-section structure constrains scope.
- **Token budget**: Large codebases could produce large inventories or require reading many files. Mitigation: the inventory script caps directory depth, and the SKILL.md caps file reading at ~10-15 key files.
## Sources & References
- **Origin document:** [docs/brainstorms/2026-03-25-vonboarding-skill-requirements.md](../brainstorms/2026-03-25-vonboarding-skill-requirements.md)
- Script-first architecture: [docs/solutions/skill-design/script-first-skill-architecture.md](../solutions/skill-design/script-first-skill-architecture.md)
- Compound-refresh learnings: [docs/solutions/skill-design/compound-refresh-skill-improvements.md](../solutions/skill-design/compound-refresh-skill-improvements.md)
- Repo-research-analyst agent: `plugins/compound-engineering/agents/research/repo-research-analyst.md`
- Skill compliance checklist: `plugins/compound-engineering/AGENTS.md`