audit-stack

# Audit Project Stack Scan a project's source code, classify technologies into Logic/Interface/Data layers, research each technology online, recommend architecture improvements, and generate template and stack.json recommendations. Read reference files before starting: - [technology-signatures.md](references/technology-signatures.md) — detection signatures for 80+ technologies - [layer-classification.md](references/layer-classification.md) — canonical tech-to-layer mapping <!-- SYNC NOTE: Phases 1-4 started as a copy of plugin-creator/skills/audit-stack/SKILL.md; the two copies have drifted (reference links, newer signatures), so port a change by hand when it applies to both --> --- ## Phase 1: Source Code Scan Scan the target project directory. Do NOT modify any files — this is read-only. ### Step 1.1 — Package Manifests Read all package manifests found in the project root (and monorepo packages if applicable): - `package.json` (Node.js) — extract `dependencies` and `devDependencies` - `requirements.txt` / `pyproject.toml` / `Pipfile` (Python) - `go.mod` (Go) - `Cargo.toml` (Rust) - `Gemfile` (Ruby) - `composer.json` (PHP) - `pom.xml` / `build.gradle` (Java/Kotlin) - Lockfiles name the package manager: `pnpm-lock.yaml` (pnpm), `bun.lock` / `bun.lockb` (Bun), `uv.lock` (uv), `package-lock.json` (npm), `yarn.lock` (Yarn), `poetry.lock` (Poetry) — record it as tooling, not a layer technology For each dependency found, match against the package manifest tables in `references/technology-signatures.md`. ### Step 1.2 — Configuration Files Use Glob to detect configuration files. Check for: ``` **/next.config.* , **/nuxt.config.* , **/svelte.config.* , **/angular.json , **/tailwind.config.* , **/vite.config.* , **/webpack.config.* , **/tsconfig.json , **/prisma/schema.prisma , **/drizzle.config.* , **/trigger.config.* , **/docker-compose.yml , **/docker-compose.yaml , **/Dockerfile* , **/.github/workflows/*.yml , **/vercel.json , **/terraform/*.tf , **/k8s/** , **/.storybook/** , **/jest.config.* , **/vitest.config.* , **/playwright.config.* , **/sentry.*.config.* , **/payload.config.* , **/.infisical.json , **/pnpm-lock.yaml , **/bun.lock , **/bun.lockb , **/uv.lock ``` Match each against the configuration file table in `references/technology-signatures.md`. ### Step 1.3 — Docker Compose Services If `docker-compose.yml` or `docker-compose.yaml` exists, read it and extract all `image:` values; also check `networks:` for `dokploy-network` (a Dokploy deployment). Match against the Docker Compose service table in `references/technology-signatures.md`. ### Step 1.4 — Import Pattern Scanning Use Grep to search source files for distinctive import patterns. Focus on `src/` and root-level source files: ``` Glob: src/**/*.{ts,tsx,js,jsx,py,go,rs} ``` Search for the import patterns listed in `references/technology-signatures.md` Section 4. ### Step 1.5 — Directory Structure Signals Check for directory patterns that signal specific technologies (see Section 5 of technology-signatures.md): - `src/app/` + `layout.tsx` = Next.js App Router - `components/ui/` = shadcn/ui - `prisma/` directory = Prisma - `supabase/` directory = Supabase - `trigger/` or `src/trigger/` = Trigger.dev ### Step 1.6 — Compile Technology List Deduplicate all findings into a single list. For each technology, record: - **Name** — canonical technology name - **Version** — from package manifest if available, otherwise "detected" - **Detection source** — which scan step found it (package.json, config file, docker-compose, import, directory) Group minor packages under their parent ecosystem: - `@radix-ui/react-dialog`, `@radix-ui/react-popover` -> just "Radix UI" - `@sentry/node`, `@sentry/nextjs` -> just "Sentry" - Multiple `@aws-sdk/*` packages -> just "AWS SDK" Cap the list at the 30-40 most significant technologies. Minor utilities (linters, formatters, type checkers) can be mentioned briefly but don't need individual analysis. --- ## Phase 2: Layer Classification Using `references/layer-classification.md`, classify each technology into layers. **Critical rule:** Full-stack frameworks (Next.js, Nuxt, SvelteKit, Remix, Rails, Django, Laravel) MUST appear in BOTH `logic` AND `interface`. **Output as a table:** ```markdown ## Stack Audit Report ### Detected Technologies | # | Technology | Version | Layer | Detection Source | |---|-----------|---------|-------|-----------------| | 1 | Next.js | 15.2.x | Logic, Interface | package.json, next.config.ts | | 2 | PostgreSQL | 16 | Data | docker-compose.yml | | 3 | Prisma | 6.x | Data | package.json, prisma/schema.prisma | | 4 | Tailwind CSS | 4.x | Interface | package.json, tailwind.config.ts | | 5 | Redis | 7.x | Data | docker-compose.yml | | ... | | | | | ### Layer Summary **Logic:** Next.js, Better Auth, Trigger.dev, tRPC, Stripe **Interface:** Next.js, React, Tailwind CSS, shadcn/ui, Radix UI **Data:** PostgreSQL, Prisma, Redis, Supabase **Infrastructure:** Docker Compose, GitHub Actions, Vercel ``` --- ## Phase 3: Technology Research For each significant technology (or batched by related group), research its ecosystem online to gather information for template and plugin recommendations. ### Search Tool Fallback Chain Try tools in this order. Move to the next only if the previous is unavailable, denied, or returns nothing useful. Reference tools by service name — find the matching tool in your available session tools: | Priority | Service | Best for | |----------|---------|----------| | 1 | **Firecrawl Search** | Most powerful — supports `site:` operators, JS rendering | | 2 | **Exa Web Search** | Code-focused, technical search | | 3 | **Perplexity Search** | Synthesized answers about ecosystem health | | 4 | **Jina Web Search** | Broad web search, parallel queries | | 5 | **Context7 Query Docs** | Library documentation lookup | | 6 | **WebSearch / WebFetch** | Always available — built-in fallback | If an MCP search tool is denied after 1-2 attempts, immediately fall back to WebSearch/WebFetch. Do not keep retrying denied tools. ### What to Research For each technology (batch related ones together to save queries): 1. **MCP server existence** — Search: `"{technology} MCP server"` — does an MCP server exist for this technology? 2. **Existing Claude Code plugin** — Search: `"{technology} claude code plugin agents store"` — is there already a plugin? 3. **Ecosystem health** — Is the technology actively maintained? Major version? Community size? 4. **Integration patterns** — How does this technology typically integrate with the others found in this project? ### Research Output Record findings per technology: ```markdown ### Technology Research | Technology | MCP Server? | Existing Plugin? | Ecosystem Status | Notes | |-----------|-------------|-----------------|-----------------|-------| | Next.js | No official | nextjs-dev (exists) | Active, v15 | Major framework | | Prisma | Yes (community) | None | Active, v6 | Popular ORM | | Redis | Yes (official) | None | Active, v7 | Standard cache | ``` --- ## Phase 4: Architecture Recommendation Based on the classified stack and research findings, provide architecture recommendations. ### Analysis Categories 1. **Consolidation opportunities** — Technologies serving the same purpose that could be unified - Example: "Both raw SQL queries and Prisma found — consider consolidating on Prisma" - Example: "Both Axios and native fetch used — standardize on one" 2. **Layer gaps** — Missing capabilities in any layer - Example: "No caching layer detected — consider Redis for frequently accessed data" - Example: "No authentication solution found — consider Better Auth or Clerk" - Example: "No job processing — consider Trigger.dev for background tasks" - Example: "No monitoring — consider Sentry for error tracking" 3. **Modern alternatives** — Technologies that have better modern replacements - Example: "Webpack detected — consider migrating to Vite for faster builds" - Example: "Express detected — consider Hono or Fastify for better performance" - Example: "Moment.js detected — consider date-fns or dayjs (Moment is in maintenance mode)" 4. **Integration patterns** — How the discovered technologies should work together - Example: "Next.js + Directus: use Directus SDK with server components for type-safe data fetching" - Example: "Supabase + Next.js: use Supabase Auth helpers with middleware for session management" ### Output Format ```markdown ## Architecture Recommendation ### Current Architecture - **Logic:** [list technologies] - **Interface:** [list technologies] - **Data:** [list technologies] - **Infrastructure:** [list technologies] ### Strengths 1. [what's working well about this stack] 2. [good technology choices] ### Recommended Improvements | # | Category | Recommendation | Rationale | |---|----------|---------------|-----------| | 1 | Layer Gap | Add Redis for caching | Frequently accessed data without cache layer | | 2 | Consolidation | Standardize on Prisma | Raw SQL and Prisma both used for same DB | | 3 | Modern Alt | Migrate Webpack → Vite | 10x faster builds, native ESM | | 4 | Integration | Use Directus SDK in server components | Type safety, automatic caching | ``` <!-- END SHARED PHASES — Phase 5 below is the Template Recommendation variant --> --- ## Phase 5: Template Recommendation Based on discovered technologies and layer classification, generate template recommendations and a draft `stack.json`. Reference these files for proper schema and level rules: - `${CLAUDE_PLUGIN_ROOT}/skills/template-reference/SKILL.md` — template hierarchy rules - `${CLAUDE_PLUGIN_ROOT}/skills/create/references/stack-json-schema.md` — stack.json schema - `${CLAUDE_PLUGIN_ROOT}/skills/create/references/level-checklist.md` — required content per level ### Step 5.1 — Determine Template Level Assess the project's maturity to determine the appropriate template level: | Signal | Level | |--------|-------| | Just technologies, no application code | Level 1 (Stack Template) | | Working application with sample/demo data | Level 1.5 (Demo Template) | | Real client project with production credentials and custom business logic | Level 2 (Client Project) | Maturity signals to check: - Does `src/` contain substantial application code? (Level 1.5+) - Are there seed scripts or sample data? (Level 1.5+) - Does `.env` / `.env.local` contain real (non-example) credentials? (Level 2) - Is there custom business logic specific to a client? (Level 2) - Does `stack.json` already exist? (existing template — report current level) ### Step 5.2 — Generate Template Name Follow the naming convention `project-{data}-{interface}`: - Identify the primary **data** technology (e.g., directus, supabase, nocodb, postgresql) - Identify the primary **interface** technology (e.g., nextjs, nuxt, svelte) - Combine: `project-directus-nextjs`, `project-supabase-nuxt`, `project-nocodb-nuxt` If no clear data+interface pair, use the dominant technology: `project-{dominant-tech}` ### Step 5.3 — Generate Draft stack.json Using the layer classification from Phase 2, generate a complete `stack.json`: ```json { "stack": "{data}-{interface}", "version": "1.0.0", "level": 1, "parent": "project-template", "description": "Stack template for {Data Technology} + {Interface Technology} projects", "layers": { "data": ["lowercase-tech-names"], "logic": ["lowercase-tech-names"], "interface": ["lowercase-tech-names"] }, "plugins": { "technology": ["matching-dev-plugins"], "process": [], "stack": ["matching-stack-plugins"] } } ``` Rules for `layers` values — use lowercase kebab-case identifiers: - `nextjs` (not `Next.js`), `tailwindcss`, `trigger-dev`, `better-auth` - Database drivers collapse to DB name: `pg` -> `postgresql` - UI libraries use short form: `@radix-ui/*` -> `radix-ui` Rules for `plugins` values: - List technology plugins that exist or should be created: `{tool}-dev`, `{tool}-ops`, `{tool}-provision` - List stack plugins if integration plugins exist: `stack-{name}` (no process suffix) - Leave `process` empty unless the project uses specific business process plugins