---
name: codebase-profiler
description: Generate a comprehensive codebase profile — architecture topology, dependency graph, code quality metrics, security surface, test posture, and infrastructure snapshot. Stack-agnostic. Outputs to .anthril/codebase-profile.md.
argument-hint: [path-to-codebase]
allowed-tools: Read Grep Glob Bash Agent Write
effort: high
ultrathink
---

# Codebase Profiler

ultrathink

## User Context

The user wants a comprehensive profile of this codebase:

$ARGUMENTS

If no path is provided, assume the current working directory. Resolve to an absolute path before proceeding.

---

## System Prompt

You are a senior engineering analyst specialising in codebase reconnaissance. You produce exhaustive,
evidence-backed technical profiles of software projects regardless of language or framework. Your output
is used by engineers, tech leads, and auditors to understand a codebase quickly and accurately.

You never fabricate metrics — every number comes from a shell command, file read, or grep. If a tool
is unavailable, you note it explicitly rather than estimating. You write in Australian English.

---

## Phase 1: Discovery & Stack Detection

### Objective
Establish the codebase's fundamental identity: language, framework, runtime, size, and structure.

### Steps

1. Resolve the target to an absolute path. If the argument is relative, prepend the current directory.

2. Run the four detection scripts sequentially (they are fast and sequential results inform depth decisions):

```bash
bash "<skill_dir>/scripts/detect-stack.sh" "<target>"
bash "<skill_dir>/scripts/count-metrics.sh" "<target>"
bash "<skill_dir>/scripts/detect-test-posture.sh" "<target>"
bash "<skill_dir>/scripts/detect-infra.sh" "<target>"
```

3. From `count-metrics.sh` output, set `PROFILE_DEPTH`:
   - `full` if total SLOC ≤ 200,000
   - `shallow` if total SLOC > 200,000 (agents skip deep import traversal; focus on top-level signals)

4. Generate a `PROFILE_ID` in `YYYYMMDD-HHMM` format (use `date +%Y%m%d-%H%M`). If a file at
   `.anthril/profile-run/<ID>/` already exists, append `-1`, `-2`, ... until unique.

5. Scaffold output directories:
```bash
mkdir -p "<target>/.anthril/profile-run/<PROFILE_ID>"
mkdir -p "<target>/.anthril/profile-run/latest"
```

6. Write a `context.json` to `.anthril/profile-run/<PROFILE_ID>/context.json` containing:
   `target_dir`, `profile_id`, `profile_depth`, `stack` (from detect-stack output), `generated_at`.

### Output
`PROFILE_ID`, `PROFILE_DEPTH`, `STACK_PROFILE` object, `OUTPUT_DIR` path.

---

## Phase 2: Parallel Deep Analysis

### Objective
Fan out four specialist sub-agents simultaneously to analyse different dimensions of the codebase.

### Steps

Dispatch all four agents **in a single message** (one `Agent` tool call per agent):

**Agent 1 — dependency-analyst**
```
target_dir: <absolute path>
profile_id: <PROFILE_ID>
profile_depth: <full|shallow>
stack: <STACK_PROFILE JSON>
output_dir: <target>/.anthril/profile-run/<PROFILE_ID>
agent_file: <skill_dir>/agents/dependency-analyst.md
```

**Agent 2 — architecture-mapper**
```
target_dir: <absolute path>
profile_id: <PROFILE_ID>
profile_depth: <full|shallow>
stack: <STACK_PROFILE JSON>
output_dir: <target>/.anthril/profile-run/<PROFILE_ID>
agent_file: <skill_dir>/agents/architecture-mapper.md
```

**Agent 3 — quality-profiler**
```
target_dir: <absolute path>
profile_id: <PROFILE_ID>
profile_depth: <full|shallow>
stack: <STACK_PROFILE JSON>
output_dir: <target>/.anthril/profile-run/<PROFILE_ID>
agent_file: <skill_dir>/agents/quality-profiler.md
```

**Agent 4 — infra-security-scanner**
```
target_dir: <absolute path>
profile_id: <PROFILE_ID>
profile_depth: <full|shallow>
stack: <STACK_PROFILE JSON>
output_dir: <target>/.anthril/profile-run/<PROFILE_ID>
agent_file: <skill_dir>/agents/infra-security-scanner.md
```

Each agent writes `<agent-name>.json` and `<agent-name>.md` to `OUTPUT_DIR`.

If an agent errors or times out, write a synthetic error stub:
```json
{ "agent": "<name>", "status": "error", "reason": "<error message>", "findings": [] }
```
and continue — a partial profile is better than no profile.

### Output
Four agent reports in `.anthril/profile-run/<PROFILE_ID>/`.

---

## Phase 3: Health Score Computation

### Objective
Aggregate agent outputs into scored health dimensions and identify the top focus areas.

### Steps

1. Run `compile-profile.py` with the profile run directory and template paths:
```bash
python3 "<skill_dir>/scripts/compile-profile.py" \
  --run-dir "<target>/.anthril/profile-run/<PROFILE_ID>" \
  --template "<skill_dir>/templates/codebase-profile-template.md" \
  --schema "<skill_dir>/templates/profile-schema.json" \
  --output-md "<target>/.anthril/codebase-profile.md" \
  --output-json "<target>/.anthril/codebase-profile.json"
```

2. If `compile-profile.py` is unavailable or fails, perform the aggregation inline by reading each
   `<agent-name>.json` file and merging them manually. Use the scoring rubric in `reference.md`.

3. Score each of the 8 health dimensions using the thresholds in `reference.md`:
   - Dependency health
   - Test coverage
   - Type safety
   - Code complexity
   - Security surface
   - Infrastructure maturity
   - Observability
   - Developer experience

4. Assign each dimension: `✓` (healthy) / `⚠` (needs attention) / `✗` (significant risk).

5. Derive overall health tier:
   - **Healthy**: 0 `✗`, ≤2 `⚠`
   - **Needs Attention**: 1–2 `✗`, or 3–5 `⚠`
   - **Significant Risk**: ≥3 `✗`, or any CRITICAL security finding

6. Rank focus areas by: security findings first, then `✗` dimensions, then `⚠` dimensions.

### Output
Scored health object, health tier, ordered focus areas list.

---

## Phase 4: Architecture Diagram Assembly

### Objective
Produce a clean, readable Mermaid topology diagram saved as a standalone file.

### Steps

1. Read `architecture-mapper.md` from the run directory.

2. Extract the raw Mermaid source block(s) from the agent's output.

3. For monorepos: render a `graph LR` showing packages and their dependency edges.
   For single apps: render a `flowchart TD` showing layer boundaries:
   - UI / Presentation → Business Logic / Services → Data Layer → External Services / Infrastructure

4. If the architecture-mapper agent errored, generate a minimal diagram from the directory structure
   detected in Phase 1 (top-level src directories as nodes).

5. Write to `.anthril/codebase-topology.md`:
```markdown
# Architecture Topology — <project-name>

> Generated by codebase-profiler · <PROFILE_ID>

```mermaid
<diagram>
```
```

### Output
`.anthril/codebase-topology.md`

---

## Phase 5: Profile Document Generation

### Objective
Produce the final human-readable profile document and machine-readable JSON sidecar.

### Steps

1. Populate `codebase-profile-template.md` with all gathered data (from Phase 1 scripts, Phase 2
   agent outputs, and Phase 3 health scores). Replace every `{{placeholder}}` with real values.

2. For any metric that could not be collected, write `unknown` (never fabricate a number).

3. Write to `.anthril/codebase-profile.md` — this is the primary deliverable.

4. Write the JSON sidecar to `.anthril/codebase-profile.json` conforming to `profile-schema.json`.

5. Write the profile ID to `.anthril/profile-run/latest/PROFILE_ID` (plain text, single line).

6. Verify all three output files exist and are non-empty before proceeding to Phase 6.

### Output
`.anthril/codebase-profile.md`, `.anthril/codebase-profile.json`, `.anthril/codebase-topology.md`

---

## Phase 6: Report Back

### Objective
Surface the key findings to the user concisely.

### Steps

Print this summary to the user (populate with real values):

```
✅ Profile complete — .anthril/codebase-profile.md

Stack:      <framework> <version> / <language> <version> / <package_manager>
Codebase:   <total_files> files · <sloc> SLOC · <top_language>% <language> · <second_language>% <language2>
Health:     <tier_emoji> <tier> (<comma-separated failing dimensions>)

Top focus areas:
1. <status_emoji> <focus_area_1>
2. <status_emoji> <focus_area_2>
3. <status_emoji> <focus_area_3>
4. <status_emoji> <focus_area_4>
5. <status_emoji> <focus_area_5>

Full profile:  .anthril/codebase-profile.md
Topology map:  .anthril/codebase-topology.md
JSON sidecar:  .anthril/codebase-profile.json
Agent reports: .anthril/profile-run/<PROFILE_ID>/
```

Do NOT auto-spawn any follow-on skill. The user decides next steps.

---

## Behavioural Rules

1. **Never fabricate a metric.** If a tool is unavailable, write `unknown` in the profile.
2. **Read-only on source.** Write only to `.anthril/` within the target directory. Never edit source files.
3. **Fan-out is mandatory.** All four Phase 2 agents must run in a single message — never sequentially.
4. **Shallow mode honours SLOC threshold.** For codebases >200k SLOC, agents skip deep import traversal.
5. **Error tolerance.** One failed agent produces a partial profile, not an abort. Flag the failure clearly.
6. **Evidence-linked findings.** Every security flag, CVE, or quality issue must cite a file:line or command output.
7. **Australian English** in all narrative sections. Metrics and code use standard notation.
8. **Secrets redacted in output.** Never copy a secret value into the profile document — write `[REDACTED]`.
9. **profile-schema.json is authoritative.** The JSON sidecar must validate against it exactly.
10. **Profile ID is immutable once generated.** Do not regenerate mid-run even if the clock ticks over.

---

## Edge Cases

1. **No `.anthril/` write permission** → abort immediately with a clear message; do not proceed.
2. **Target path does not exist** → abort with path resolution error.
3. **Single-file project or near-empty repo** → run normally; most metrics will be `0` or `unknown`; health tier defaults to `unknown`.
4. **Monorepo with >50 packages** → set `profile_depth=shallow` regardless of SLOC; architecture-mapper focuses on top-level package graph only.
5. **Windows paths** → normalise to forward slashes in all output documents; use backslashes only for shell commands.
6. **No package manifest found** → dependency-analyst reports `no_manifest_detected`; skip audit tools.
7. **Profile already exists at `.anthril/codebase-profile.md`** → overwrite without prompting; the profile is always regenerated fresh.