| name | project-analyzer |
| description | Analyze project structure, conventions, and patterns to generate a project profile. Use when /team-init is invoked or when team agents need to understand the codebase. Scans package.json, config files, source code patterns, and test setup to produce structured profiles in .claude/project-profile/. |
Project Analyzer
Scan the codebase and generate a structured project profile. Team workflow agents reference this profile to follow project conventions.
Output Location
.claude/project-profile/
├── index.md # Summary — always loaded by agents
├── stack.md # Tech stack, dependencies, build
├── structure.md # File/directory conventions
├── code-style.md # Naming, imports, formatting
├── api-layer.md # API patterns, type generation
├── state-management.md # Store patterns, reactivity
├── testing.md # Test framework, patterns
├── ui-components.md # Component library, design system
└── deployment.md # Build, CI/CD, env management
Workflow (MUST execute in order)
Templates for every file below live in resources/profile-templates.md. Read that file before filling any profile.
Step 1: Detect Tech Stack → stack.md
Follow template §1. Detect package manager via lockfile priority (bun.lockb → pnpm-lock.yaml → package-lock.json → default Bun).
Step 2: Analyze File Structure → structure.md
Follow template §2. Capture directory layout, routing pattern, module organization, naming conventions. If .gitmodules exists, also fill the Submodule Layout block (code submodules + superproject role + per-submodule worktree carry-list of gitignored env/config) — this is the SSOT the submodule-worktree skill reads; omit the block for non-submodule repos.
Step 3: Detect Code Style → code-style.md
Follow template §3. Read 5-10 source files to identify patterns. Skip if no consistent pattern emerges and mark N/A. (Seeded Mode: on a scaffold with <5 source files, derive style from the CLI's formatter config (eslint/prettier/biome) and mark provisional.)
Step 4: Analyze API Layer → api-layer.md
Follow template §4. Skip for projects without API integration and mark ⏭️ Skipped in index.md. (Seeded Mode: do NOT skip — inject the stack-decision doc's planned client/contract and mark 🌱 Seeded. See Seeded Mode.)
Step 5: Analyze State Management → state-management.md
Follow template §5. Skip for projects without state library and mark ⏭️ Skipped. (Seeded Mode: do NOT skip — inject the planned state library + store patterns and mark 🌱 Seeded. See Seeded Mode.)
Step 6: Analyze Testing → testing.md
Follow template §6. Default framework expectation: Vitest 4.x for unit, Playwright for E2E.
Also derive the Agentic Testing Adapter (template §6 block):
- Surface:
web if a browser UI (React/Vue/Svelte/Angular/Next…); backend if API-only (Spring/Express/FastAPI…); mobile if Flutter/React-Native.
- Driver / Emitter house-style / Concurrency / spec dir: fill per the Adapter table in the
agentic-testing skill.
- If Surface=mobile and no mobile driver (maestro/Patrol/mobile-MCP) is detectable, set
Driver: UNAVAILABLE and note it.
Step 7: Analyze UI Components → ui-components.md
Follow template §7. Skip for backend-only projects.
Step 8: Analyze Deployment → deployment.md
Follow template §8. Skip if no CI/CD found.
Step 9: Generate Index → index.md
Follow template §9. MUST include relevance + status for every profile file. Record Profile-Generated-At: <git rev-parse --short HEAD> so staleness can be detected later (/team-init --update).
Step 10: Bootstrap document buckets (if absent)
Follow template §10. Establish the three document buckets alongside _docs/:
_note/README.md — only if _note/ does not exist. MUST NOT create any other file under _note/, and MUST NOT modify an existing _note/ (agent read-only)..claude/wiki/{index.md, log.md, schema.md} — only the files that are absent (empty catalog / empty chronicle / conventions stub).
Never overwrite an existing file. On --update, re-run this step but only create what is missing.
Seeded Mode (greenfield — G5 of /team-new)
Called by the greenfield-bootstrap skill (G5) on a freshly-scaffolded project. A bare official-CLI scaffold has no API/state code yet, so Steps 4 & 5 would normally mark api-layer.md and state-management.md as ⏭️ Skipped — the OPPOSITE of what the first /team-run needs. Seeded Mode SCANS what exists and INJECTS the forward-looking decisions from the stack-decision doc.
Trigger: invoked with a path to the G2 stack-decision doc (_docs/.../project-bootstrap-stack-decision.md). Precondition: G4 scaffold + git first-commit already ran, so Step 9 Profile-Generated-At resolves to that SHA.
Two passes:
- SCAN-fill (real source on the scaffold):
stack.md (baseline = absolute 0 for greenfield), structure.md, code-style.md (formatter-config fallback if <5 files), testing.md (frameworks + agentic adapter, table-derived), ui-components.md (only if a UI lib was scaffolded), index.md. deployment.md → ⏭️ Skipped (no CI/CD in a scaffold) is correct.
- INJECT-fill (no scan source → from the decision doc), marked
🌱 Seeded:
api-layer.md — planned client + generated-vs-manual + generator/regen command + spec source + auth posture + base-URL env. (The single most valuable injected doc — Architect-BE and Designers read it on the first /team-run.)state-management.md — planned library + intended store-scope patterns.
INPUT CONTRACT — the stack-decision doc MUST carry: chosen framework + package manager; planned API client (generated-vs-manual, generator, regen command, auth, base-URL env); planned state library + store patterns; planned UI lib; planned test stack. (Same contract the greenfield-bootstrap G2 step produces.)
Provenance: every 🌱 Seeded doc gets the line > Source: injected from <stack-decision path>, not yet observed in code — re-verify on /team-init --update. The next --update re-scans seeded docs against now-real code and upgrades 🌱 → ✅.
Seeded Mode is purely additive override rules; the skill never hard-errors on an empty tree.
Update Mode (/team-init --update)
- Read existing
index.md to get current state
- Scan for changes (new dependencies, new directories, config changes)
- Only rewrite files that have changed
- Update
Last updated: [timestamp] in index.md
- Append changelog entry:
## Changelog
- [date]: [what changed]
How Agents Use the Profile
Loading Strategy (progressive)
- Always load:
index.md (summary + key conventions)
- Load on demand based on agent role:
| Agent | Files to load |
|---|
| Leader | index.md + structure.md |
| Architect FE | structure.md + code-style.md + ui-components.md + state-management.md |
| Architect BE | api-layer.md + structure.md |
| Architect Infra | deployment.md + api-layer.md |
| UI/UX Master | ui-components.md + code-style.md |
| Designer | code-style.md + state-management.md + testing.md |
| Tester | testing.md + structure.md |
Profile Files Are Best-Practice Defaults
The 8 profile files represent a best-practice template. Not every project has all sections:
- Pure frontend SPA may skip
deployment.md
- Utility library may skip
ui-components.md + state-management.md
- Backend-only project may skip
ui-components.md
Mark skipped files in index.md as ⏭️ Skipped (reason). Do not assume skipped files exist.
Status tokens (index.md): ✅ scanned-from-code · ⏭️ Skipped (reason) not applicable · 🌱 Seeded planned-and-injected-from-stack-decision-doc, not yet in code (greenfield Seeded Mode; upgrades to ✅ on the next --update re-scan).
Adaptation Rules (agents MUST)
- Read
index.md first (ONLY required file)
- Load additional profile files on-demand based on
index.md relevance column
- Skip files marked as
⏭️ Skipped
- Use the project's patterns (imports, naming, API calls, stores, tests, UI)
- If a profile file does not exist, fall back to general best practices
