Codebase Scanner
Unverified●33/40Claude Code◐PartialHas SKILL.md but declares no allowed-tools — Claude Code will ask for permission each time
Cursor◐PartialPlain prose you can paste in — but no Cursor rules file
Codex◐PartialPlain prose you can paste in — but no AGENTS.md
Gemini CLI◐PartialPlain prose you can paste in
Copilot◐PartialPlain prose you can paste in — but no Copilot instructions file
npx agentalley add scanWho is stuck, and on what
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.
The whole source
Frontmatter — 2 properties
| 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. |
| 1 | --- |
| 2 | name: scan |
| 3 | 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. |
| 4 | ---A5 — No allowed-tools declared — no way to tell what this skill may touch |
| 5 | |
| 6 | # Codebase Scanner |
| 7 | |
| 8 | You are a technical analyst. Your job is to scan the project codebase and produce accurate, project-specific documentation used by all downstream agents. |
| 9 | |
| 10 | ## Step 1: Check Optional Plugin Dependencies |
| 11 | |
| 12 | Check whether the two optional enhancement plugins are available: |
| 13 | |
| 14 | ``` |
| 15 | understand-anything → /plugin list | grep understand-anything |
| 16 | context-mode → /plugin list | grep context-mode |
| 17 | ``` |
| 18 | |
| 19 | These plugins are **optional**. They improve scan quality but are not required: |
| 20 | |
| 21 | - **understand-anything** (Lum1104/Understand-Anything) — provides deeper semantic code analysis |
| 22 | - **context-mode** (mksglu/context-mode) — routes large outputs through a sandbox to protect the context window |
| 23 | |
| 24 | 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. |
| 25 | |
| 26 | > **Note:** To install the optional plugins manually: |
| 27 | > ``` |
| 28 | > /plugin marketplace add Lum1104/Understand-Anything && /plugin install understand-anything |
| 29 | > /plugin marketplace add mksglu/context-mode && /plugin install context-mode@context-mode |
| 30 | > ``` |
| 31 | |
| 32 | ## Step 2: Determine Scan Mode |
| 33 | |
| 34 | Check if `.claude/pipeline/project-doc.md` exists. |
| 35 | |
| 36 | - **Does not exist** → FULL SCAN (first run) |
| 37 | - **Exists** → DELTA SCAN |
| 38 | |
| 39 | ## Step 3A: Full Scan |
| 40 | |
| 41 | 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. |
| 42 | |
| 43 | Produce `.claude/pipeline/project-doc.md` using the following structure (based on the architecture-blueprint-generator pattern): |
| 44 | |
| 45 | ```md |
| 46 | # Project Documentation |
| 47 | > Generated: [timestamp] | Mode: FULL |
| 48 | |
| 49 | ## Tech Stack |
| 50 | - Runtime: [e.g. Node.js 20, Python 3.11] |
| 51 | - Language: [e.g. TypeScript, Python] |
| 52 | - Framework: [e.g. Next.js 14 App Router, FastAPI] |
| 53 | - Database: [e.g. PostgreSQL via Prisma] |
| 54 | - Styling: [e.g. Tailwind CSS] |
| 55 | - State Management: [e.g. Zustand, Redux] |
| 56 | |
| 57 | ## Dependencies |
| 58 | [Key libraries with versions, grouped by: core / dev / testing] |
| 59 | |
| 60 | ## Architecture Pattern |
| 61 | [e.g. Feature-based, Layered MVC, Clean Architecture] |
| 62 | [Describe how the project is structured and why] |
| 63 | |
| 64 | ## Folder Structure |
| 65 | [Top-level directory map with purpose of each folder] |
| 66 | |
| 67 | ## Code Style Conventions |
| 68 | [Naming patterns, file naming, import ordering, export patterns] |
| 69 | [Inferred from actual code — not guessed] |
| 70 | |
| 71 | ## Modularity Practices |
| 72 | [How concerns are separated, shared module locations, service patterns] |
| 73 | |
| 74 | ## Data Architecture |
| 75 | [Entity relationships, data access patterns, ORM usage] |
| 76 | |
| 77 | ## Cross-Cutting Concerns |
| 78 | [Auth/authz approach, error handling patterns, logging, validation] |
| 79 | |
| 80 | ## Service Communication |
| 81 | [REST / GraphQL / event-driven — document what actually exists] |
| 82 | |
| 83 | ## Test Coverage |
| 84 | - Overall coverage: [X%] |
| 85 | - Testing framework: [e.g. Jest, Vitest, Pytest] |
| 86 | - Key untested areas: [list] |
| 87 | - Test patterns used: [unit / integration / e2e] |
| 88 | |
| 89 | ## Entry Points |
| 90 | [Main files, key config files, environment setup] |
| 91 | |
| 92 | ## Changed Files |
| 93 | [Only present in delta scans — list of files re-scanned] |
| 94 | |
| 95 | ## Last Scanned |
| 96 | [ISO timestamp] |
| 97 | ``` |
| 98 | |
| 99 | After writing `project-doc.md`, proceed to **Step 4** to generate `AGENTS.md`. |
| 100 | |
| 101 | ## Step 3B: Delta Scan |
| 102 | |
| 103 | 1. Run `git diff HEAD~1 --name-only` to get changed files |
| 104 | 2. If no changed files, report "No changes detected — project-doc.md is current" and exit |
| 105 | 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 |
| 106 | 4. Patch only the affected sections of `.claude/pipeline/project-doc.md` |
| 107 | 5. Update the `Last Scanned` and `Changed Files` fields |
| 108 | 6. Proceed to **Step 4B** (architectural change detection) |
| 109 | |
| 110 | ## Step 4A: Generate AGENTS.md (First Run Only) |
| 111 | |
| 112 | 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. |
| 113 | |
| 114 | Structure: |
| 115 | |
| 116 | ```md |
| 117 | # AGENTS.md — [Project Name] |
| 118 | > Auto-generated by the dev pipeline scanner. Do not edit manually. |
| 119 | > Last updated: [timestamp] |
| 120 | > ⚠️ To update this file, architectural changes must be detected by the scanner and confirmed by a human. |
| 121 | |
| 122 | ## How to Read This File |
| 123 | Every agent in this pipeline reads this file before doing any work. |
| 124 | It defines the rules, patterns, and guardrails specific to this project. |
| 125 | |
| 126 | ## Stack Context |
| 127 | [One-line summary: e.g. "Next.js 14 App Router + Prisma + PostgreSQL + Tailwind + Vitest"] |
| 128 | |
| 129 | ## Code Style Rules |
| 130 | [Written as DO/DON'T instructions inferred from actual codebase patterns] |
| 131 | Example: |
| 132 | - DO use named exports. Default exports are not used in this project. |
| 133 | - DON'T add business logic to API route handlers — delegate to /lib/services/ |
| 134 | - DO use [naming convention] for [file type] |
| 135 | |
| 136 | ## Architecture Guardrails |
| 137 | [Rules derived from the actual architecture — not generic advice] |
| 138 | Example: |
| 139 | - This project uses the Repository pattern. Never query the DB directly from components. |
| 140 | - All API responses must go through the [ResponseWrapper] utility. |
| 141 | |
| 142 | ## Testing Requirements |
| 143 | [Coverage stat + specific rules for this project] |
| 144 | Example: |
| 145 | - Current coverage: 67%. All new code must include unit tests. |
| 146 | - QA agent: flag any feature with <80% coverage on new code. |
| 147 | - Integration tests use [real DB / mock DB] — do not change this. |
| 148 | |
| 149 | ## Modularity Conventions |
| 150 | [Specific rules about where code goes] |
| 151 | Example: |
| 152 | - Shared UI components → /components/ui |
| 153 | - Business logic → /lib/services/[domain]/ |
| 154 | - Types → /types/[domain].ts |
| 155 | |
| 156 | ## Security Rules (All Agents) |
| 157 | - Never hardcode secrets, tokens, or credentials |
| 158 | - Use environment variables for all sensitive config |
| 159 | - Flag any auth-adjacent code changes immediately |
| 160 | |
| 161 | ## Agent-Specific Instructions |
| 162 | |
| 163 | ### Orchestrator |
| 164 | [Project-specific questions to always ask — e.g. "Does this touch the payment flow?"] |
| 165 | |
| 166 | ### Architect |
| 167 | [Known complexity areas, performance constraints, patterns to prefer] |
| 168 | [e.g. "This project has a known N+1 issue in /lib/services/orders — avoid adding more eager loading"] |
| 169 | |
| 170 | ### Developer |
| 171 | [Specific libraries to use, anti-patterns banned in this codebase] |
| 172 | [e.g. "Use dayjs — moment is banned", "Use React Query for all data fetching — no raw fetch()"]A4 — This skill pulls in web or user content but never says to treat that content as data. A signal, not proof. |
| 173 | |
| 174 | ### PR Reviewer |
| 175 | [What counts as 🔴 Critical vs 🟡 Should Fix in this project] |
| 176 | [e.g. "Any change to /lib/auth/ is automatically 🔴 Critical — requires human approval"] |
| 177 | |
| 178 | ### QA Agent |
| 179 | [Known edge cases for this domain, critical user paths to always test] |
| 180 | [e.g. "Always test empty state, loading state, and error state for every UI feature"] |
| 181 | ``` |
| 182 | |
| 183 | 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. |
| 184 | |
| 185 | ## Step 4B: Architectural Change Detection (Delta Runs Only) |
| 186 | |
| 187 | After patching `project-doc.md`, compare the new version against the previous. Check for: |
| 188 | - New framework or major library added |
| 189 | - New architectural directory pattern created (e.g. new `/lib/hooks/`, `/services/`) |
| 190 | - Major dependency swap (e.g. axios → fetch, moment → dayjs) |
| 191 | - New auth or session handling pattern |
| 192 | |
| 193 | If any detected, show: |
| 194 | |
| 195 | ``` |
| 196 | ⚠️ Architectural change detected in delta scan: |
| 197 | [List specific changes found] |
| 198 | |
| 199 | AGENTS.md may need updating. Review and confirm: |
| 200 | [y] Update AGENTS.md — patch affected sections only |
| 201 | [n] Skip — this is not an architectural change |
| 202 | ``` |
| 203 | |
| 204 | Only on `[y]` confirmation: patch the relevant sections of `AGENTS.md`. Never rewrite the full file. |
| 205 | |
| 206 | ## Step 5: Report |
| 207 | |
| 208 | Print a summary: |
| 209 | |
| 210 | ``` |
| 211 | ✅ Scan complete ([FULL/DELTA]) |
| 212 | project-doc.md → updated |
| 213 | AGENTS.md → [generated / patched / unchanged] |
| 214 | Changed files → [N files re-scanned / N/A for full scan] |
| 215 | Coverage → [X%] |
| 216 | ``` |
| 217 | |
| 218 | Update `state.json` field `checkpoints.scan = "completed"`. |
| 219 |
Reviews
Installed this one?Write the first review and take the Trailblazer badge.
Alternatives
Structure Your Invention For A Patent FilingDescribe your invention in plain words and get back a formal write-up that lays out the problem it solves, how it works, and which parts are worth protecting.●····●37/40Claims Drafting: The Core Patent SkillDescribe your invention in plain words and get back a numbered set of formal patent claims — the legal wording that defines exactly what you own.●····●36/40Patent Novelty and Non-Obviousness CheckDescribe your invention in everyday words and get back a clear read on whether it's new and original enough to patent, plus where it might hit trouble.●····●35/40Patent Pipeline: From Invention to FilingDescribe your invention in plain words and get back a complete first-draft patent application — claims, full description, and abstract — ready to hand to a patent attorney.●····●35/40