Scans the codebase to generate project-doc.md and AGENTS.md. Use when bootstrapping a new agent-driven repo, refreshing project documentation after architectural changes, or running a delta scan to detect drift. Runs a full scan on first use and a smart delta scan on subsequent
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/scan
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Scans the codebase to generate project-doc.md and AGENTS.md. Use when bootstrapping a new agent-driven repo, refreshing project documentation after architectural changes, or running a delta scan to detect drift. Runs a full scan on first use and a smart delta scan on subsequent
📊 Stats
Stars38,171
Forks4,092
LanguagePython
LicenseMIT
📦 Ships with wshobson-agents
</> SKILL.md
scan.SKILL.md
---name: scan
description: Scans the codebase to generate project-doc.md and AGENTS.md. Use when bootstrapping a new agent-driven repo, refreshing project documentation after architectural changes, or running a delta scan to detect drift. Runs a full scan on first use and a smart delta scan on subsequent runs. Uses understand-anything + context-mode when available, falls back to native tools otherwise. Only updates AGENTS.md on detected architectural changes with human confirmation.
---# Codebase Scanner
You are a technical analyst. Your job is to scan the project codebase and produce accurate, project-specific documentation used by all downstream agents.
## Step 1: Check Optional Plugin Dependencies
Check whether the two optional enhancement plugins are available:
```
understand-anything → /plugin list | grep understand-anything
context-mode → /plugin list | grep context-mode
```
These plugins are **optional**. They improve scan quality but are not required:
- **understand-anything** (Lum1104/Understand-Anything) — provides deeper semantic code analysis
- **context-mode** (mksglu/context-mode) — routes large outputs through a sandbox to protect the context window
If both are present, use them in Steps 3–4 as described below. If either or both are missing, proceed with the **native fallback** approach: use `find`, `grep`, `cat`, and `git` commands directly, routing large outputs through `ctx_execute` / `ctx_execute_file` if context-mode is available, otherwise summarise inline.
Check if `.claude/pipeline/project-doc.md` exists.
- **Does not exist** → FULL SCAN (first run)
- **Exists** → DELTA SCAN
## Step 3A: Full Scan
Use `understand-anything` to analyse the entire codebase. If **context-mode** is available (verified in Step 1), route ALL output through its tools (`ctx_batch_execute` / `ctx_execute_file`) — never dump raw file contents into the main context window. If context-mode is not available, summarise each file's findings inline and avoid printing raw file contents.
Produce `.claude/pipeline/project-doc.md` using the following structure (based on the architecture-blueprint-generator pattern):
[REST / GraphQL / event-driven — document what actually exists]
## Test Coverage
- Overall coverage: [X%]
- Testing framework: [e.g. Jest, Vitest, Pytest]
- Key untested areas: [list]
- Test patterns used: [unit / integration / e2e]
## Entry Points
[Main files, key config files, environment setup]
## Changed Files
[Only present in delta scans — list of files re-scanned]
## Last Scanned
[ISO timestamp]
```
After writing `project-doc.md`, proceed to **Step 4** to generate `AGENTS.md`.
## Step 3B: Delta Scan
1. Run `git diff HEAD~1 --name-only` to get changed files
2. If no changed files, report "No changes detected — project-doc.md is current" and exit
3. Use `understand-anything` to re-analyse only the changed files; route output through `ctx_execute_file` if context-mode is available, otherwise summarise inline
4. Patch only the affected sections of `.claude/pipeline/project-doc.md`
5. Update the `Last Scanned` and `Changed Files` fields
6. Proceed to **Step 4B** (architectural change detection)
## Step 4A: Generate AGENTS.md (First Run Only)
Write `AGENTS.md` to the repo root. This is NOT a copy of `project-doc.md` — it is rewritten as agent instructions, tailored to this specific project. Every agent reads this file first.
Structure:
```md
# AGENTS.md — [Project Name]
> Auto-generated by the dev pipeline scanner. Do not edit manually.
> Last updated: [timestamp]
> ⚠️ To update this file, architectural changes must be detected by the scanner and confirmed by a human.
## How to Read This File
Every agent in this pipeline reads this file before doing any work.
It defines the rules, patterns, and guardrails specific to this project.
[Written as DO/DON'T instructions inferred from actual codebase patterns]
Example:
- DO use named exports. Default exports are not used in this project.
- DON'T add business logic to API route handlers — delegate to /lib/services/
- DO use [naming convention] for [file type]
## Architecture Guardrails
[Rules derived from the actual architecture — not generic advice]
Example:
- This project uses the Repository pattern. Never query the DB directly from components.
- All API responses must go through the [ResponseWrapper] utility.
## Testing Requirements
[Coverage stat + specific rules for this project]
Example:
- Current coverage: 67%. All new code must include unit tests.
- QA agent: flag any feature with <80% coverage on new code.
- Integration tests use [real DB / mock DB] — do not change this.
## Modularity Conventions
[Specific rules about where code goes]
Example:
- Shared UI components → /components/ui
- Business logic → /lib/services/[domain]/
- Types → /types/[domain].ts
## Security Rules (All Agents)
- Never hardcode secrets, tokens, or credentials
- Use environment variables for all sensitive config
- Flag any auth-adjacent code changes immediately
## Agent-Specific Instructions
### Orchestrator
[Project-specific questions to always ask — e.g. "Does this touch the payment flow?"]
### Architect
[Known complexity areas, performance constraints, patterns to prefer]
[e.g. "This project has a known N+1 issue in /lib/services/orders — avoid adding more eager loading"]
### Developer
[Specific libraries to use, anti-patterns banned in this codebase]
[e.g. "Use dayjs — moment is banned", "Use React Query for all data fetching — no raw fetch()"]
### PR Reviewer
[What counts as 🔴 Critical vs 🟡 Should Fix in this project]
[e.g. "Any change to /lib/auth/ is automatically 🔴 Critical — requires human approval"]
### QA Agent
[Known edge cases for this domain, critical user paths to always test]
[e.g. "Always test empty state, loading state, and error state for every UI feature"]
```
If the project is MERN stack (MongoDB + Express + React + Node.js — detected from package.json / requirements), append a `### MERN Stack Notes` section to AGENTS.md covering: use Mongoose middleware over raw queries, handle async errors in Express with a central error handler, avoid storing JWT tokens in localStorage (use httpOnly cookies), and never expose Mongoose error objects directly in API responses.
