From 6cef7347a20c06c55397ef170e951e8e4018bef5 Mon Sep 17 00:00:00 2001 From: b0berman Date: Thu, 9 Apr 2026 10:19:08 +0200 Subject: [PATCH 1/7] feat: add onboard skill --- CLAUDE.md | 3 + agents/analysis/onboard-analysis-agent.md | 165 ++++++++ skills/onboard/SKILL.md | 129 ++++++ skills/onboard/references/html-template.html | 394 +++++++++++++++++++ skills/onboard/references/section-prompts.md | 126 ++++++ 5 files changed, 817 insertions(+) create mode 100644 agents/analysis/onboard-analysis-agent.md create mode 100644 skills/onboard/SKILL.md create mode 100644 skills/onboard/references/html-template.html create mode 100644 skills/onboard/references/section-prompts.md diff --git a/CLAUDE.md b/CLAUDE.md index 79ced7e..1bc8dd3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,6 +26,8 @@ Standalone Skills: - **`/debrief`** — Produce a structured, blameless debrief document after an incident, failed release, or significant bug. +- **`/onboard`** — Generate a self-contained HTML site explaining the repository's structure, architecture, and key abstractions. + Each phase persists its output to `docs/` so the next phase can discover it from a cold start. **Fast path:** **`/hotfix`** — Streamlined workflow for emergency fixes. Skips brainstorm and planning but enforces review and testing. Use when speed matters but quality is still non-negotiable. @@ -57,6 +59,7 @@ Quality-review agents: - `docs/hotfix-review/` — Review reports from `/hotfix` (ephemeral, cleaned up by hotfix) - `docs/code-review/` — Review reports from `/review` (standalone, user-managed) - `docs/debriefs/` — Debrief documents from `/debrief` +- `docs/onboard/` — Onboarding HTML sites from `/onboard` ## Hooks diff --git a/agents/analysis/onboard-analysis-agent.md b/agents/analysis/onboard-analysis-agent.md new file mode 100644 index 0000000..dae8c0a --- /dev/null +++ b/agents/analysis/onboard-analysis-agent.md @@ -0,0 +1,165 @@ +--- +name: onboard-analysis-agent +description: | + Analyzes a codebase for onboarding comprehension — maps architecture, modules, + dependencies, entry points, data flow, key abstractions, and test coverage. + Focused on understanding, not quality review or best practices. +model: sonnet +effort: high +--- + +# Onboard analysis agent + +You are an expert at reading unfamiliar codebases and explaining them clearly. Your job is to walk a repository and produce a structured analysis that helps a newcomer understand how the project is organized, how data flows, and where to start reading. + +You are **not** reviewing code quality, enforcing best practices, or suggesting improvements. You are building a map. + +## Scope + +Analyze the codebase at the path provided in your prompt. If no path is provided, analyze the entire repository from the root. + +## Analysis process + +Work through these steps in order. Be thorough but concise — favor clarity over completeness. + +### 1. Read high-level documentation + +Look for and read (if they exist): +- README, README.md +- CLAUDE.md +- ARCHITECTURE.md, DESIGN.md +- CONTRIBUTING.md +- Package manifests (package.json, pubspec.yaml, Cargo.toml, go.mod, Gemfile, pyproject.toml, build.gradle, pom.xml, etc.) +- Monorepo config (lerna.json, pnpm-workspace.yaml, melos.yaml, etc.) + +### 2. Map the directory structure + +Use Glob to map the top 2-3 levels of the directory tree. Identify: +- Source directories vs config vs docs vs tests +- Package/module boundaries (each independently buildable or importable unit) +- Generated or vendored directories to skip + +### 3. Identify the tech stack + +From package manifests, file extensions, and build files determine: +- Primary language(s) +- Frameworks and major libraries +- Build tools and task runners +- Runtime requirements + +### 4. Analyze each module + +For each module or top-level package identified in step 2: +- Read its entry point (index file, main file, lib file) +- Read its own README if present +- Determine its responsibility in one sentence +- Note its public API surface (key exports) + +### 5. Trace dependency relationships + +Scan imports and dependency declarations to build a dependency graph: +- Which modules import from which other modules? +- What are the external dependencies per module? +- Are there circular dependencies? +- Which modules are "leaf" modules (depended on by many, depend on few)? + +### 6. Identify entry points + +Find where execution begins: +- Main files, CLI entry points +- HTTP/API route definitions +- Exported public APIs +- Event handlers or job runners +- Configuration entry points (app setup, DI containers) + +### 7. Trace data and state flow + +Follow the primary user-facing paths through the codebase: +- How does a request/event enter the system? +- What layers does it pass through? +- Where is state stored and managed? +- How do side effects (DB, network, file I/O) happen? + +### 8. Find key abstractions + +Identify the types, interfaces, and classes that shape how you think about the codebase: +- Types that appear in many function signatures +- Base classes or interfaces that define contracts +- Domain models and DTOs +- Configuration types +- The abstractions a newcomer must understand to read any module + +### 9. Assess the test landscape + +Compare test directories against source directories: +- What testing frameworks are used? +- Which modules have tests? Which don't? +- What's the ratio of test files to source files per module? +- Are there integration tests, E2E tests, or only unit tests? +- Note any areas with notably thin coverage + +### 10. Extract build and run instructions + +From READMEs, Makefiles, package.json scripts, Justfiles, docker-compose files, etc.: +- How to install dependencies +- How to build the project +- How to run it locally +- How to run tests +- Any required environment setup (env vars, databases, services) + +### 11. Produce a suggested reading order + +Based on everything above, recommend an order for a newcomer to read the code: +1. Start with entry points +2. Then core abstractions and shared types +3. Then modules in dependency order (leaves first) +4. Note any "start here" files or particularly well-documented areas + +## Output format + +You MUST structure your output using exactly these section headers. Each section maps to a section in the final HTML output. Use markdown within each section. + +``` +## Project Overview & Tech Stack + +[content] + +## Architecture Map + +[content — use nested lists to show module hierarchy and boundaries] + +## Dependency Graph + +[content — use a list or table showing module → depends on relationships] + +## Entry Points + +[content — list each entry point with its file path and what it does] + +## Data & State Flow + +[content — describe the primary flows through the system] + +## Key Abstractions + +[content — list each key type/interface with its file path and why it matters] + +## Test Landscape + +[content — summary table or list of coverage per module] + +## Build & Run Instructions + +[content — step-by-step commands] + +## Suggested Reading Order + +[content — numbered list with file paths and brief rationale] +``` + +## Important + +- Reference specific file paths (e.g., `src/auth/middleware.ts:42`) wherever possible. +- Use relative paths from the repository root. +- If a section has no relevant content (e.g., no tests exist), say so explicitly rather than omitting the section. +- Keep each section focused. If you find something interesting that doesn't fit a section, skip it — this is a map, not an encyclopedia. diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md new file mode 100644 index 0000000..8c197bd --- /dev/null +++ b/skills/onboard/SKILL.md @@ -0,0 +1,129 @@ +--- +name: onboard +user-invocable: true +description: "Walks a repository and generates a self-contained HTML site summarizing its structure, architecture, and key abstractions. Use when user says \"onboard\", \"explain this repo\", \"codebase overview\", \"help me understand this codebase\", or \"map this codebase\"." +argument-hint: "[path/to/scope (optional, defaults to repo root)]" +effort: high +compatibility: Designed for Claude Code (or similar products with agent support) +--- + +# Generate a codebase onboarding site + +Walk a repository and generate a self-contained HTML page that explains its structure, architecture, and key abstractions. Focused on understanding — not best practices or framework guidance. + +## Scope + +$ARGUMENTS + +## Phase 0 — Parse scope and detect repo + +1. **Parse the scope above.** If empty, default to the repository root (`.`). If a path is provided, validate it exists. + +2. **Detect the repository name** for the output filename: + + ```bash + basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" + ``` + +3. **Check for existing onboard files:** + + ```bash + ls docs/onboard/*.html 2>/dev/null + ``` + + If files exist, inform the user: "Found existing onboard site(s) at `docs/onboard/`. Generating a new one will not overwrite existing files (filenames are date-prefixed)." + +## Phase 1 — Analyze + +Run the **@onboard-analysis-agent** to gather structured codebase analysis. The agent's prompt must include: + +1. The scope constraint (repo root or specific path) +2. Instructions to follow the section format defined in [section-prompts.md](references/section-prompts.md) + +The agent returns structured markdown with exactly 9 section headers. Capture the full output. + +**If the agent fails:** Report the error to the user and stop. Do not generate a partial HTML file. + +## Phase 2 — Generate HTML + +### 2.1 Read the template + +Read the HTML template from [html-template.html](references/html-template.html). + +### 2.2 Prepare metadata + +Determine values for the metadata placeholders: + +| Placeholder | Value | +|-------------|-------| +| `` | Repository name from Phase 0 | +| `` | Today's date in `YYYY-MM-DD` format | +| `` | The analysis scope (`.` for full repo, or the provided path) | + +### 2.3 Map agent output to HTML sections + +Parse the agent's markdown output by splitting on `## ` headers. Convert each section's markdown content to HTML: + +| Agent Section Header | HTML Placeholder | +|----------------------|-----------------| +| `## Project Overview & Tech Stack` | `` | +| `## Architecture Map` | `` | +| `## Dependency Graph` | `` | +| `## Entry Points` | `` | +| `## Data & State Flow` | `` | +| `## Key Abstractions` | `` | +| `## Test Landscape` | `` | +| `## Build & Run Instructions` | `` | +| `## Suggested Reading Order` | `` | + +**Markdown to HTML conversion rules:** + +- `### Heading` → `

Heading

` +- `#### Heading` → `

Heading

` +- Paragraphs → `

...

` +- `- item` → `` +- `1. item` → `
  1. item
` +- `` `code` `` → `code` +- Code blocks → `
...
` +- `**bold**` → `bold` +- `→` in dependency graphs → `→` +- Tables → `` with `
` and `` + +### 2.4 Assemble and write + +1. Replace all `` placeholders with their values +2. Replace all `` placeholders with the converted HTML +3. Ensure `docs/onboard/` directory exists: + + ```bash + mkdir -p docs/onboard + ``` + +4. Write the assembled HTML to: + + ``` + docs/onboard/YYYY-MM-DD--onboard.html + ``` + +## Phase 3 — Handoff + +Announce completion: + +```md +Onboard site generated! + +File: docs/onboard/.html + +Open it in any browser — the file is fully self-contained with no external dependencies. +``` + +## Gotchas + +- The HTML file must be self-contained: all CSS and JS inline, no external fonts, no CDN scripts. It must work from `file://` with no network. +- The agent output must use the exact section headers listed above. If a header is missing, leave the corresponding HTML placeholder empty with a `

No data available for this section.

` fallback. +- Large monorepos: the agent should focus on the top-level structure and the most significant modules, not exhaustively document every package. Depth over breadth for the most important areas. +- The generated file is an untracked working file. The user decides whether to commit it. + +## Important + +This skill generates a static HTML document. It does NOT make any changes to the codebase, run tests, or modify project configuration. diff --git a/skills/onboard/references/html-template.html b/skills/onboard/references/html-template.html new file mode 100644 index 0000000..6768274 --- /dev/null +++ b/skills/onboard/references/html-template.html @@ -0,0 +1,394 @@ + + + + + + <!-- META:repo-name --> — Onboard + + + + + +
+

+

Generated · Scope:

+ +
+
+ Project Overview & Tech Stack +
+ +
+
+
+ +
+
+ Architecture Map +
+ +
+
+
+ +
+
+ Dependency Graph +
+ +
+
+
+ +
+
+ Entry Points +
+ +
+
+
+ +
+
+ Data & State Flow +
+ +
+
+
+ +
+
+ Key Abstractions +
+ +
+
+
+ +
+
+ Test Landscape +
+ +
+
+
+ +
+
+ Build & Run Instructions +
+ +
+
+
+ +
+
+ Suggested Reading Order +
+ +
+
+
+
+ +
+ Generated by Wingspan /onboard on · Scope: +
+ + + + diff --git a/skills/onboard/references/section-prompts.md b/skills/onboard/references/section-prompts.md new file mode 100644 index 0000000..7a67d08 --- /dev/null +++ b/skills/onboard/references/section-prompts.md @@ -0,0 +1,126 @@ +# Section Prompts for Onboard Analysis + +This document defines the 9 required sections the `onboard-analysis-agent` must produce. Each section header maps directly to a placeholder in the HTML template. + +The agent's output must use **exactly** these markdown headers. The skill parses them to inject content into the HTML template. + +--- + +## Section 1: Project Overview & Tech Stack + +**Header:** `## Project Overview & Tech Stack` + +**Must include:** +- What the project is (one paragraph) +- Primary language(s) and versions +- Frameworks and major libraries with versions +- Build tools and task runners +- Runtime requirements (Node, JVM, Docker, etc.) +- Repository type (monorepo, single package, workspace) + +--- + +## Section 2: Architecture Map + +**Header:** `## Architecture Map` + +**Must include:** +- Top-level directory layout with purpose of each directory +- Module/package boundaries — each independently buildable or importable unit +- Responsibility of each module in one sentence +- Layer structure if present (data, domain, presentation, etc.) +- Boundary rules — what's allowed to import what + +**Format:** Use nested markdown lists to show hierarchy. + +--- + +## Section 3: Dependency Graph + +**Header:** `## Dependency Graph` + +**Must include:** +- Module-to-module dependency relationships +- Leaf modules (depended on by many, depend on few) +- Circular dependencies (if any) +- Key external dependencies per module + +**Format:** Use a markdown table or arrow notation (`module-a → module-b`). + +--- + +## Section 4: Entry Points + +**Header:** `## Entry Points` + +**Must include:** +- Every place where execution begins +- File path and line number for each +- What each entry point does (one sentence) +- Types: main files, CLI commands, HTTP routes, exported APIs, event handlers, job runners + +--- + +## Section 5: Data & State Flow + +**Header:** `## Data & State Flow` + +**Must include:** +- Primary user-facing flows (e.g., "request comes in at X, passes through Y, hits DB at Z") +- Where state is stored (in-memory, database, cache, global store) +- How side effects are managed +- State management pattern if applicable + +--- + +## Section 6: Key Abstractions + +**Header:** `## Key Abstractions` + +**Must include:** +- Types, interfaces, and classes that shape how you think about the codebase +- File path for each +- Why each matters (one sentence) +- Domain models, DTOs, configuration types +- Base classes or interfaces that define contracts + +--- + +## Section 7: Test Landscape + +**Header:** `## Test Landscape` + +**Must include:** +- Testing framework(s) used +- Coverage by module (which have tests, which don't) +- Types of tests present (unit, integration, E2E, visual) +- Areas with notably thin or absent coverage +- Test patterns used (mocks, fixtures, factories) + +--- + +## Section 8: Build & Run Instructions + +**Header:** `## Build & Run Instructions` + +**Must include:** +- Prerequisites (tools, runtimes, env vars) +- Install dependencies +- Build the project +- Run locally +- Run tests +- Any other common tasks (lint, format, generate) + +**Format:** Use code blocks for commands. + +--- + +## Section 9: Suggested Reading Order + +**Header:** `## Suggested Reading Order` + +**Must include:** +- Numbered list of files/directories to read +- File path for each item +- Brief rationale for why to read it at that position +- Start with entry points, then core abstractions, then modules in dependency order From 3be00c0c75e58965998d8a668752e309d9810476 Mon Sep 17 00:00:00 2001 From: b0berman Date: Thu, 9 Apr 2026 16:13:18 +0200 Subject: [PATCH 2/7] feat: improve fact check --- agents/analysis/onboard-analysis-agent.md | 98 +++++++++++++++++--- skills/onboard/SKILL.md | 9 +- skills/onboard/references/html-template.html | 16 ++-- 3 files changed, 98 insertions(+), 25 deletions(-) diff --git a/agents/analysis/onboard-analysis-agent.md b/agents/analysis/onboard-analysis-agent.md index dae8c0a..d1c096f 100644 --- a/agents/analysis/onboard-analysis-agent.md +++ b/agents/analysis/onboard-analysis-agent.md @@ -32,6 +32,8 @@ Look for and read (if they exist): - Package manifests (package.json, pubspec.yaml, Cargo.toml, go.mod, Gemfile, pyproject.toml, build.gradle, pom.xml, etc.) - Monorepo config (lerna.json, pnpm-workspace.yaml, melos.yaml, etc.) +**Workspace manifests are the source of truth for member counts.** If a workspace file (e.g., `Cargo.toml` `[workspace]`, `pnpm-workspace.yaml`, `melos.yaml`) lists members, count them directly from that list. Do not estimate or round — use the exact number. + ### 2. Map the directory structure Use Glob to map the top 2-3 levels of the directory tree. Identify: @@ -41,7 +43,18 @@ Use Glob to map the top 2-3 levels of the directory tree. Identify: ### 3. Identify the tech stack -From package manifests, file extensions, and build files determine: +For **every** directory that looks like a module or package, determine its language by checking for build/manifest files first: +- `Cargo.toml` → Rust +- `package.json` → JavaScript/TypeScript +- `pubspec.yaml` → Dart +- `go.mod` → Go +- `pyproject.toml` / `setup.py` / `requirements.txt` → Python +- `build.gradle` / `pom.xml` → JVM +- `Gemfile` → Ruby + +**Never infer language from directory names, README prose, or surrounding context.** Always verify by checking for a manifest file and source file extensions (`*.rs`, `*.py`, `*.ts`, etc.) inside the directory. If a directory named `cloud_replay` contains `Cargo.toml` and `*.rs` files, it is Rust — not Python. + +From these determinations, summarize: - Primary language(s) - Frameworks and major libraries - Build tools and task runners @@ -54,32 +67,49 @@ For each module or top-level package identified in step 2: - Read its own README if present - Determine its responsibility in one sentence - Note its public API surface (key exports) +- Note which app or top-level binary consumes this module (if it's only used by one app, say so — this distinction matters for onboarding) + +**Check for sibling or related directories** that might serve different environments or platforms (e.g., `cloud_functions/` and `azure_functions/`, or `web/` and `mobile/`). Note these relationships explicitly. ### 5. Trace dependency relationships -Scan imports and dependency declarations to build a dependency graph: -- Which modules import from which other modules? -- What are the external dependencies per module? +**Read each module's manifest file directly** to determine its dependencies. Do not infer dependencies from module names, directory proximity, or conceptual relationships. + +For each module: +1. Open its dependency manifest (`Cargo.toml` `[dependencies]`, `package.json` `dependencies`, `pubspec.yaml` `dependencies`, etc.) +2. List only the internal (workspace/monorepo) dependencies that actually appear in the manifest +3. A module with zero internal dependencies is a leaf — report it as such + +Build the dependency graph from these verified relationships: +- Which modules depend on which other modules? (from manifests only) +- What are the key external dependencies per module? - Are there circular dependencies? -- Which modules are "leaf" modules (depended on by many, depend on few)? +- Which modules are leaf modules (depended on by many, depend on few)? ### 6. Identify entry points -Find where execution begins: +Find where execution begins. **Verify each entry point path exists** — do not assume conventional paths like `lib/main.dart`; check the actual file system. + - Main files, CLI entry points - HTTP/API route definitions - Exported public APIs - Event handlers or job runners - Configuration entry points (app setup, DI containers) +**Group entry points by technology** (e.g., "Rust Binaries", "Flutter Apps", "Python Services", "Scripts") rather than listing them in a flat table. This makes it easier to scan. + ### 7. Trace data and state flow -Follow the primary user-facing paths through the codebase: +**Start with a 2-3 sentence summary** of the overall data flow before diving into detailed step-by-step walkthroughs. A newcomer should be able to read just the summary and understand the high-level picture. + +Then follow the primary user-facing paths through the codebase: - How does a request/event enter the system? - What layers does it pass through? - Where is state stored and managed? - How do side effects (DB, network, file I/O) happen? +Keep this section proportional to the rest of the document. If the system has many flows, cover the 2-3 most important ones in detail and list the rest briefly. + ### 8. Find key abstractions Identify the types, interfaces, and classes that shape how you think about the codebase: @@ -91,14 +121,39 @@ Identify the types, interfaces, and classes that shape how you think about the c ### 9. Assess the test landscape -Compare test directories against source directories: -- What testing frameworks are used? -- Which modules have tests? Which don't? -- What's the ratio of test files to source files per module? -- Are there integration tests, E2E tests, or only unit tests? -- Note any areas with notably thin coverage +**Check every module for tests — do not skip any.** For each module identified in step 4: -### 10. Extract build and run instructions +1. Search for test directories: `tests/`, `test/`, `spec/`, `__tests__/`, and inline `#[cfg(test)]` blocks +2. Use Glob to count test files with precise patterns per language: + - Dart: `**/*_test.dart` (only files ending in `_test.dart`) + - Rust: `tests/**/*.rs` (files in `tests/` directory) + - JavaScript/TypeScript: `**/*.test.{ts,tsx,js,jsx}` or `**/*.spec.{ts,tsx,js,jsx}` + - Python: `**/test_*.py` or `**/*_test.py` +3. **Report the exact count returned by the Glob tool.** Do not estimate, round, or adjust. If Glob returns 179 files, write "179" — not "about 180" or "187". + +Report per module: +- Testing framework(s) used +- Exact number of test files (from Glob) +- Types of tests present (unit, integration, E2E, visual) +- Areas with notably thin or absent coverage + +**Do not report "None detected" without actually searching the module's directory.** If you find zero test files after searching, say "No test files found in ``" so it's clear you looked. + +### 10. Identify operational and tooling context + +Look for tooling, services, and operational details that a newcomer would need to know but that aren't obvious from source code alone: + +- **Version managers**: `.fvm/`, `.nvmrc`, `.tool-versions`, `.python-version` — note which versions and why multiple versions may coexist +- **Code generation**: `build_runner`, `protobuf`/`prost`, `openapi-generator`, `graphql-codegen` — note what's generated and how to regenerate it +- **Third-party services**: Firebase, AWS, GCP, Azure, Stripe, etc. — check manifests and config files for SDKs +- **Deployment config**: systemd units, Docker/docker-compose, Kubernetes manifests, serverless config, CI/CD pipelines +- **Credentials/config directories**: `creds/`, `config/`, `.env.example` — note the structure without exposing secrets +- **Proto/schema files**: `.proto`, `.graphql`, database migration files — note what they define and where they're used +- **Project conventions**: VGV CLI, monorepo tools (melos, turborepo, nx), linting/formatting configs that shape how code is written + +Include these findings in the relevant sections (tech stack, build instructions, architecture map) rather than creating a separate section. + +### 11. Extract build and run instructions From READMEs, Makefiles, package.json scripts, Justfiles, docker-compose files, etc.: - How to install dependencies @@ -106,8 +161,9 @@ From READMEs, Makefiles, package.json scripts, Justfiles, docker-compose files, - How to run it locally - How to run tests - Any required environment setup (env vars, databases, services) +- **Codegen steps** — if the project uses code generation, include the commands to regenerate (e.g., `dart run build_runner build`, `cargo build` for prost). Newcomers who skip this step get confusing "type not found" errors. -### 11. Produce a suggested reading order +### 12. Produce a suggested reading order Based on everything above, recommend an order for a newcomer to read the code: 1. Start with entry points @@ -157,6 +213,18 @@ You MUST structure your output using exactly these section headers. Each section [content — numbered list with file paths and brief rationale] ``` +## Accuracy rules + +These rules exist because inference-based errors are the most common failure mode. Follow them strictly. + +1. **Counts must match source data.** If the workspace manifest lists 15 members, write "15" — not "13" or "about 15". Count from the file, not from memory. +2. **Dependencies come from manifests, not inference.** If `blob-loader/Cargo.toml` has zero internal `[dependencies]`, it is a leaf crate. Do not add dependencies because the name suggests a relationship. +3. **Language comes from files, not names.** Check for `Cargo.toml`/`*.rs`, `package.json`/`*.ts`, etc. A directory called `cloud_replay` is Rust if it contains Rust source files. +4. **Test presence comes from searching, not assuming.** Glob for test files in every module. Report what you find, not what you expect. +5. **When prose references a number, verify it matches the data.** If the dependency graph table has 14 rows, the prose should say "14", not "13". +6. **Entry point paths must be verified.** Do not assume `lib/main.dart` or `src/main.rs` — Glob for the actual file. If the entry point is at `lib/main/main.dart`, report that exact path. +7. **Test counts come from Glob, not estimation.** Use the exact number the Glob tool returns. Inflated counts undermine trust in the entire document. + ## Important - Reference specific file paths (e.g., `src/auth/middleware.ts:42`) wherever possible. diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index 8c197bd..1b2a600 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -89,17 +89,20 @@ Parse the agent's markdown output by splitting on `## ` headers. Convert each se - `→` in dependency graphs → `→` - Tables → `` with `
` and `` -### 2.4 Assemble and write +**Cross-linking:** When a section references a concept covered in another section (e.g., a type name in Data & State Flow that's defined in Key Abstractions), add an HTML anchor link: `Key Abstractions`. This helps readers navigate between related sections. + +### 2.4 Assemble, validate, and write 1. Replace all `` placeholders with their values 2. Replace all `` placeholders with the converted HTML -3. Ensure `docs/onboard/` directory exists: +3. **Validate:** Check that no `
-
+
Dependency Graph
@@ -289,7 +289,7 @@

-
+
Entry Points
@@ -298,7 +298,7 @@

-
+
Data & State Flow
@@ -307,7 +307,7 @@

-
+
Key Abstractions
@@ -316,7 +316,7 @@

-
+
Test Landscape
@@ -325,7 +325,7 @@

-
+
Build & Run Instructions
@@ -334,7 +334,7 @@

-
+
Suggested Reading Order
@@ -372,6 +372,8 @@

e.preventDefault(); var target = document.querySelector(this.getAttribute('href')); if (target) { + var details = target.querySelector('details'); + if (details && !details.open) details.open = true; target.scrollIntoView({ behavior: 'smooth' }); history.pushState(null, '', this.getAttribute('href')); } From f1676a583cd84214831ca85660caf76bd9e42429 Mon Sep 17 00:00:00 2001 From: b0berman Date: Fri, 10 Apr 2026 16:12:52 +0200 Subject: [PATCH 3/7] fix: recalibrate to focus on actual value info --- agents/analysis/onboard-analysis-agent.md | 84 +++++++++----------- skills/onboard/references/section-prompts.md | 33 ++++---- 2 files changed, 55 insertions(+), 62 deletions(-) diff --git a/agents/analysis/onboard-analysis-agent.md b/agents/analysis/onboard-analysis-agent.md index d1c096f..8043eac 100644 --- a/agents/analysis/onboard-analysis-agent.md +++ b/agents/analysis/onboard-analysis-agent.md @@ -14,6 +14,8 @@ You are an expert at reading unfamiliar codebases and explaining them clearly. Y You are **not** reviewing code quality, enforcing best practices, or suggesting improvements. You are building a map. +**Guiding principle: understand the system, don't operate it.** Write for someone who needs to build a mental model of the codebase — not someone who needs to deploy, configure, or administer it. Operational details (exact env vars, port numbers, deployment commands, IP addresses) belong in runbooks, not onboarding docs. If operational knowledge exists, mention where to find it and move on. + ## Scope Analyze the codebase at the path provided in your prompt. If no path is provided, analyze the entire repository from the root. @@ -75,16 +77,15 @@ For each module or top-level package identified in step 2: **Read each module's manifest file directly** to determine its dependencies. Do not infer dependencies from module names, directory proximity, or conceptual relationships. -For each module: -1. Open its dependency manifest (`Cargo.toml` `[dependencies]`, `package.json` `dependencies`, `pubspec.yaml` `dependencies`, etc.) -2. List only the internal (workspace/monorepo) dependencies that actually appear in the manifest -3. A module with zero internal dependencies is a leaf — report it as such +For each module, open its dependency manifest (`Cargo.toml` `[dependencies]`, `package.json` `dependencies`, `pubspec.yaml` `dependencies`, etc.) and note internal (workspace/monorepo) dependencies. + +**Focus on the shape of the graph, not the full matrix.** A newcomer needs to understand: +- What is the hub module that everything depends on? +- Which modules are leaves (depended on by many, depend on few)? +- Are there circular dependencies or surprising relationships? +- What are the 3-5 most important external dependencies and what role they play? -Build the dependency graph from these verified relationships: -- Which modules depend on which other modules? (from manifests only) -- What are the key external dependencies per module? -- Are there circular dependencies? -- Which modules are leaf modules (depended on by many, depend on few)? +If the repo has 15+ modules, don't produce a 15-row table. Describe the pattern (e.g., "hub-and-spoke: `common` is the hub, all feature packages depend on it") and call out only the noteworthy relationships. ### 6. Identify entry points @@ -121,47 +122,42 @@ Identify the types, interfaces, and classes that shape how you think about the c ### 9. Assess the test landscape -**Check every module for tests — do not skip any.** For each module identified in step 4: +**Check every module for tests — do not skip any.** Search for test directories (`tests/`, `test/`, `spec/`, `__tests__/`, inline `#[cfg(test)]` blocks) and use Glob to verify test presence. -1. Search for test directories: `tests/`, `test/`, `spec/`, `__tests__/`, and inline `#[cfg(test)]` blocks -2. Use Glob to count test files with precise patterns per language: - - Dart: `**/*_test.dart` (only files ending in `_test.dart`) - - Rust: `tests/**/*.rs` (files in `tests/` directory) - - JavaScript/TypeScript: `**/*.test.{ts,tsx,js,jsx}` or `**/*.spec.{ts,tsx,js,jsx}` - - Python: `**/test_*.py` or `**/*_test.py` -3. **Report the exact count returned by the Glob tool.** Do not estimate, round, or adjust. If Glob returns 179 files, write "179" — not "about 180" or "187". +**Write a qualitative narrative, not a file-count audit.** A newcomer needs to know: +- Testing framework(s) and conventions used (e.g., "uses mocktail for mocking, pump for widget tests") +- Which areas have strong coverage and which are thin — described in relative terms (e.g., "solver and common have thorough unit tests; binary crates have minimal coverage") +- Types of tests present (unit, integration, E2E, visual) and where each type lives +- How to run the tests (pointer to the Build & Run section) -Report per module: -- Testing framework(s) used -- Exact number of test files (from Glob) -- Types of tests present (unit, integration, E2E, visual) -- Areas with notably thin or absent coverage +**Do not** enumerate exact file counts per module. "The api package has strong unit test coverage" is more useful for onboarding than "The api package has 179 test files." **Do not report "None detected" without actually searching the module's directory.** If you find zero test files after searching, say "No test files found in ``" so it's clear you looked. ### 10. Identify operational and tooling context -Look for tooling, services, and operational details that a newcomer would need to know but that aren't obvious from source code alone: +Look for tooling and services that shape how the code is written and built. **Focus on what affects a newcomer's ability to read and build the code, not to deploy or administer it.** -- **Version managers**: `.fvm/`, `.nvmrc`, `.tool-versions`, `.python-version` — note which versions and why multiple versions may coexist -- **Code generation**: `build_runner`, `protobuf`/`prost`, `openapi-generator`, `graphql-codegen` — note what's generated and how to regenerate it -- **Third-party services**: Firebase, AWS, GCP, Azure, Stripe, etc. — check manifests and config files for SDKs -- **Deployment config**: systemd units, Docker/docker-compose, Kubernetes manifests, serverless config, CI/CD pipelines -- **Credentials/config directories**: `creds/`, `config/`, `.env.example` — note the structure without exposing secrets -- **Proto/schema files**: `.proto`, `.graphql`, database migration files — note what they define and where they're used -- **Project conventions**: VGV CLI, monorepo tools (melos, turborepo, nx), linting/formatting configs that shape how code is written +Include in relevant sections: +- **Version managers** (`.fvm/`, `.nvmrc`, `.tool-versions`) — mention that multiple versions may coexist and where to check, not the exact version strings (these go stale quickly) +- **Code generation** (`build_runner`, `protobuf`/`prost`, `openapi-generator`) — note what's generated and that regeneration is needed after certain changes +- **Third-party services** — mention which services the system depends on (Firebase, AWS, etc.) at the architectural level +- **Proto/schema files** — note what they define and which modules consume them +- **Project conventions** — monorepo tools, linting/formatting configs that shape how code is written -Include these findings in the relevant sections (tech stack, build instructions, architecture map) rather than creating a separate section. +**Do not inline operational details.** Deployment commands, IP addresses, port numbers, systemd units, exact env var names, and infrastructure tuning knobs belong in runbooks. If these exist, mention where to find them (e.g., "deployment is documented in `ops/README.md`") and move on. ### 11. Extract build and run instructions -From READMEs, Makefiles, package.json scripts, Justfiles, docker-compose files, etc.: -- How to install dependencies -- How to build the project -- How to run it locally -- How to run tests -- Any required environment setup (env vars, databases, services) -- **Codegen steps** — if the project uses code generation, include the commands to regenerate (e.g., `dart run build_runner build`, `cargo build` for prost). Newcomers who skip this step get confusing "type not found" errors. +Describe what a newcomer needs to get the project running locally. **Focus on the conceptual setup, not a copy-paste recipe** — exact commands go stale and are better maintained in READMEs or Makefiles. + +Cover: +- Prerequisites (tools, runtimes, services that must be running) +- General workflow: install deps → build → run → test +- **Gotchas** — things that will trip up a newcomer if they don't know (e.g., "you must run codegen before building or you'll get 'type not found' errors", "the app and the competition_app use different Flutter versions — check `.fvmrc`") +- Where to find the detailed commands (e.g., "see the Makefile", "see `package.json` scripts", "see the root README") + +**Do not reproduce full command sequences** that already exist in project files. Point to the source of truth instead. ### 12. Produce a suggested reading order @@ -217,13 +213,11 @@ You MUST structure your output using exactly these section headers. Each section These rules exist because inference-based errors are the most common failure mode. Follow them strictly. -1. **Counts must match source data.** If the workspace manifest lists 15 members, write "15" — not "13" or "about 15". Count from the file, not from memory. -2. **Dependencies come from manifests, not inference.** If `blob-loader/Cargo.toml` has zero internal `[dependencies]`, it is a leaf crate. Do not add dependencies because the name suggests a relationship. -3. **Language comes from files, not names.** Check for `Cargo.toml`/`*.rs`, `package.json`/`*.ts`, etc. A directory called `cloud_replay` is Rust if it contains Rust source files. -4. **Test presence comes from searching, not assuming.** Glob for test files in every module. Report what you find, not what you expect. -5. **When prose references a number, verify it matches the data.** If the dependency graph table has 14 rows, the prose should say "14", not "13". -6. **Entry point paths must be verified.** Do not assume `lib/main.dart` or `src/main.rs` — Glob for the actual file. If the entry point is at `lib/main/main.dart`, report that exact path. -7. **Test counts come from Glob, not estimation.** Use the exact number the Glob tool returns. Inflated counts undermine trust in the entire document. +1. **Facts come from files, not inference.** Dependencies come from manifests. Languages come from source files and build configs. Test presence comes from Glob searches. Entry point paths must be verified. Never infer from directory names, README prose, or conceptual relationships. +2. **Counts must match source data.** If the workspace manifest lists 15 members, write "15" — not "13" or "about 15". Count from the file, not from memory. +3. **Entry point paths must be verified.** Do not assume `lib/main.dart` or `src/main.rs` — Glob for the actual file. If the entry point is at `lib/main/main.dart`, report that exact path. +4. **Prefer patterns over enumerations.** When a full list would create a wall of text a newcomer scans past, describe the shape instead (e.g., "hub-and-spoke with `common` at the center" vs a 14-row dependency table). Call out only the noteworthy items. +5. **Separate understanding from operating.** If a detail helps a newcomer build a mental model of the system, include it. If it's a value they'd look up when debugging or deploying (port numbers, env var names, IP addresses, exact SDK versions), point to where it lives and move on. ## Important diff --git a/skills/onboard/references/section-prompts.md b/skills/onboard/references/section-prompts.md index 7a67d08..b077e44 100644 --- a/skills/onboard/references/section-prompts.md +++ b/skills/onboard/references/section-prompts.md @@ -40,12 +40,12 @@ The agent's output must use **exactly** these markdown headers. The skill parses **Header:** `## Dependency Graph` **Must include:** -- Module-to-module dependency relationships -- Leaf modules (depended on by many, depend on few) -- Circular dependencies (if any) -- Key external dependencies per module +- The shape of the dependency graph (e.g., hub-and-spoke, layered, flat) +- Hub modules and leaf modules — what role they play +- Circular dependencies or surprising relationships (if any) +- 3-5 most important external dependencies and what role they play -**Format:** Use a markdown table or arrow notation (`module-a → module-b`). +**Format:** Use arrow notation (`module-a → module-b`) or a simplified diagram. For repos with many modules, describe the pattern rather than listing every relationship — a 15-row table is less useful than a clear description of the graph's shape. --- @@ -91,12 +91,13 @@ The agent's output must use **exactly** these markdown headers. The skill parses **Header:** `## Test Landscape` **Must include:** -- Testing framework(s) used -- Coverage by module (which have tests, which don't) -- Types of tests present (unit, integration, E2E, visual) -- Areas with notably thin or absent coverage +- Testing framework(s) and conventions (e.g., "uses mocktail for mocking, pump for widget tests") +- Qualitative coverage narrative — which areas are well-tested, which are thin +- Types of tests present (unit, integration, E2E, visual) and where each type lives - Test patterns used (mocks, fixtures, factories) +**Do not** enumerate exact file counts per module. Describe coverage in relative terms ("strong", "minimal", "none found"). + --- ## Section 8: Build & Run Instructions @@ -104,14 +105,12 @@ The agent's output must use **exactly** these markdown headers. The skill parses **Header:** `## Build & Run Instructions` **Must include:** -- Prerequisites (tools, runtimes, env vars) -- Install dependencies -- Build the project -- Run locally -- Run tests -- Any other common tasks (lint, format, generate) - -**Format:** Use code blocks for commands. +- Prerequisites (tools, runtimes, services that must be running) +- General workflow: install deps → build → run → test +- Gotchas that will trip up a newcomer (e.g., codegen must run first, multiple SDK versions coexist) +- Where to find detailed commands (Makefile, package.json scripts, root README) + +**Do not** reproduce full command sequences that already exist in project files. Point to the source of truth. Focus on what a newcomer needs to know that isn't obvious from the project files themselves. --- From 75e76e9dfa4617d1091e3bf1cbee01617b6a4179 Mon Sep 17 00:00:00 2001 From: b0berman Date: Wed, 15 Apr 2026 14:54:35 +0200 Subject: [PATCH 4/7] fix: update validate section --- skills/onboard/SKILL.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/skills/onboard/SKILL.md b/skills/onboard/SKILL.md index 1b2a600..5e3ce83 100644 --- a/skills/onboard/SKILL.md +++ b/skills/onboard/SKILL.md @@ -95,14 +95,14 @@ Parse the agent's markdown output by splitting on `## ` headers. Convert each se 1. Replace all `` placeholders with their values 2. Replace all `` placeholders with the converted HTML -3. **Validate:** Check that no `` | Repository name from Phase 0 | -| `` | Today's date in `YYYY-MM-DD` format | -| `` | The analysis scope (`.` for full repo, or the provided path) | +Write the agent's markdown output to a temporary file: -### 2.3 Map agent output to HTML sections +```bash +# Write agent output to a temp file for the conversion script +cat > /tmp/onboard-agent-output.md << 'AGENT_EOF' + +AGENT_EOF +``` -Parse the agent's markdown output by splitting on `##` headers. Convert each section's markdown content to HTML: +### 2.2 Run the conversion script -| Agent Section Header | HTML Placeholder | -|----------------------|-----------------| -| `## Project Overview & Tech Stack` | `` | -| `## Architecture Map` | `` | -| `## Dependency Graph` | `` | -| `## Entry Points` | `` | -| `## Data & State Flow` | `` | -| `## Key Abstractions` | `` | -| `## Test Landscape` | `` | -| `## Build & Run Instructions` | `` | -| `## Suggested Reading Order` | `` | +Use [convert-md-to-html.py](scripts/convert-md-to-html.py) to assemble the final HTML: -**Markdown to HTML conversion rules:** +```bash +python3 skills/onboard/scripts/convert-md-to-html.py \ + --template skills/onboard/references/html-template.html \ + --input /tmp/onboard-agent-output.md \ + --repo-name "" \ + --date "YYYY-MM-DD" \ + --scope "" \ + --output docs/onboard/YYYY-MM-DD--onboard.html +``` -- `### Heading` → `

Heading

` -- `#### Heading` → `

Heading

` -- Paragraphs → `

...

` -- `- item` → `
  • item
` -- `1. item` → `
  1. item
` -- `` `code` `` → `code` -- Code blocks → `
...
` -- `**bold**` → `bold` -- `→` in dependency graphs → `→` -- Tables → `` with `
` and `` +The script handles: +- Parsing agent markdown by `## ` headers +- Converting markdown to HTML (headings, lists, code blocks, tables, bold, dep-arrows) +- Replacing all `` and `` placeholders +- Creating the output directory if needed +- Cross-linking between sections -**Cross-linking:** When a section references a concept covered in another section (e.g., a type name in Data & State Flow that's defined in Key Abstractions), add an HTML anchor link: `Key Abstractions`. This helps readers navigate between related sections. +### 2.3 Validate -### 2.4 Assemble, validate, and write +Run the validation loop to verify the generated HTML: -1. Replace all `` placeholders with their values -2. Replace all `` placeholders with the converted HTML -3. **Validate:** Scan the assembled HTML for any remaining `", html.escape(repo_name)) + result = result.replace("", html.escape(date)) + result = result.replace("", html.escape(scope)) + + # Content placeholders + for section_header, placeholder_name in SECTION_MAP.items(): + placeholder = f"" + md_content = sections.get(section_header, "") + if md_content: + html_content = convert_markdown_to_html(md_content) + else: + html_content = FALLBACK_CONTENT + result = result.replace(placeholder, html_content) + + # Fill any remaining placeholders + result = re.sub( + r"", + FALLBACK_CONTENT, + result, + ) + result = re.sub( + r"", + "unknown", + result, + ) + + return result + + +def validate(assembled_html: str) -> list[str]: + """Check the assembled HTML for common issues. Returns a list of errors.""" + errors: list[str] = [] + + if not assembled_html.strip(): + errors.append("Output HTML is empty") + return errors + + if "` and `` placeholders - Creating the output directory if needed