Brownfield Day-1 — Derive AI Layer From Scratch

You are executing the Brownfield Day-1 flow on a codebase. Goal: take a codebase with no AI Layer (no CLAUDE.md, no .claude/) and derive a working AI Layer — global rules + a customized command suite — in a single agent invocation.

Template path: $1 (a folder containing reference CLAUDE.md + .claude/commands/ to copy and customize from). If $1 is empty, use the default YourProduct template at .claude/skills/brownfield-day-1/templates/YourProduct/.

What you will do

1. Initial Scan — quick read of the codebase shape
2. Plan the subagent slicing — decide how many Explorer subagents and what each investigates
3. Dispatch Explorer subagents in parallel — N parallel sub-agents, one per slice
4. Converge their reports into tmp/brownfield-day-1/codebase-analysis.md
5. Dispatch 3 AI Layer Builders in parallel — derive CLAUDE.md + the command suite
6. Report the final state

You orchestrate. The user does not dispatch subagents — you do.

---

Precondition Check

Before starting, check if CLAUDE.md already exists in the target repo:

• If CLAUDE.md exists: STOP. Warn the user that this codebase already has an AI layer. Suggest updating the existing CLAUDE.md and commands directly, or running /vertical-slice-audit to score a specific feature.
• If CLAUDE.md does not exist: proceed with the full Day-1 flow below.

---

Step 0 — Initial Scan (≤3 minutes)

1. Read README.md if it exists. Capture: what is this product, tech stack at a glance.
2. Walk the top-level folder structure — ls -la and tree -L 2 (exclude node_modules, dist, build, .git, __pycache__, .venv).
3. Read root config files — whichever apply: package.json, pyproject.toml, Cargo.toml, go.mod, Gemfile, composer.json, tsconfig.json, etc.
4. Glance at 1-2 high-traffic files — the server entry point, main router, or primary CLI entrypoint.

Output (internal — don't write to disk): a 5-bullet sketch of what the codebase is, its layout, and where the interesting parts live.

---

Step 1 — Plan the Subagent Slicing

Decide how many Explorer subagents you need. There is no fixed number. Choose what fits this codebase.

Slicing dimensions (use any combination that applies)

Dimension	When to include it
Backend / data layer	Server, API, or non-trivial data layer
Frontend / UI	Web, mobile, or desktop UI
Infrastructure / deploy	Dockerfile, CI/CD, deploy scripts, IaC
Tests	Substantial test suite
Domain / business logic	Almost always — what does this codebase DO
CLI / scripts	Meaningful CLI surface or scripts/ folder
Database / migrations	Non-trivial schema
Plugins / extensibility	Adapters, providers, hooks
Documentation	Substantial docs/ folder
Per-package (monorepo)	5+ packages → one subagent per cluster

Heuristics

• Small codebase (1-5K LOC) — 3 subagents
• Medium codebase (5-50K LOC) — 4-6 subagents
• Large monorepo (50K+ LOC) — 6-10 subagents, sliced by package cluster or subsystem

---

Step 2 — Dispatch Explorer Subagents in Parallel

Dispatch all N sub-agents in a single message so they run in parallel. Each writes a report to tmp/brownfield-day-1/0X-<slice-name>.md (~500-700 words).

Subagent prompt template

You are Explorer Subagent #X in a Brownfield Day-1 onboarding flow. The codebase
is at <REPO_PATH>. There is no AI Layer (no CLAUDE.md, no .claude/). Discover
everything from source.

Your remit: [slice description]

Cover specifically:
- [3-7 bullet points specific to this slice]
- Cite real file paths everywhere.
- Read enough source to be specific. Do NOT make recommendations — only describe what IS.

Output: write your findings to <REPO_PATH>/tmp/brownfield-day-1/0X-<slice-name>.md
(~500-700 words max).

Per-slice coverage

Backend: Primary language+version; framework+port; ORM/data-access; migration tool; auth pattern; API style; error handling; where routes live; top 5 substantial files; key interfaces.

Frontend: Framework+build tool; state management; styling; component organization; routing; type generation; real-time pattern.

Infrastructure: Package manager+lockfile; containerization; CI/CD workflows (list each); build pipeline; lint/format/type-check scripts; deployment; env/secrets management.

Tests: Test runner; naming+colocation convention; coverage tool; mocking convention; E2E vs unit split; top 3 test files; coverage gaps.

Domain: Elevator pitch; 3-5 core concepts (from schema/types/services); primary user flows; external integrations; non-obvious business rules; glossary.

---

Step 3 — Converge into codebase-analysis.md

Read all N subagent reports and produce <REPO_PATH>/tmp/brownfield-day-1/codebase-analysis.md:

# Codebase Analysis — <project-name>

## What this codebase does
<1-paragraph elevator pitch>

## Domain concepts
<3-8 bullet points>

## Stack at a glance
| Layer | Tool | Notes |
|-------|------|-------|

## Folder structure (annotated)
<tree of top 2 levels with 1-line annotations>

## Conventions
<bullet points: naming, imports, error handling, logging, tests>

## Most-substantial files
<top 5-10>

## External integrations
<bullet points>

## Non-obvious rules / gotchas
<bullet points>

## Seams — where new agentic work plugs in cleanly
<bullet points>

## Database schema (if applicable)
<table count + named list>

## Key files (cheat sheet)
<5-15 bullets pointing at entry-point files>

Critical rule: capture what IS, not what should be. Descriptive, no refactor proposals, cite real paths, no placeholders.

---

Step 4 — Dispatch 3 AI Layer Builders in Parallel

All 3 builders read codebase-analysis.md + the template at $1.

Builder A — Generate CLAUDE.md

Write <REPO_PATH>/CLAUDE.md with up to 10 sections:

1. Core Principles
2. Tech Stack
3. Architecture
4. Code Style
5. Logging
6. Testing
7. API Contracts (if applicable)
8. Development Commands
9. Common Patterns (2-3 real code examples from the analysis)
10. AI Coding Assistant Instructions (10 numbered bullets)

Rules: use ACTUAL paths from the analysis. 200-400 lines. Capture every gotcha. The template is structural reference; content comes from the analysis.

Builder B — Copy + customize the prime command family

1. Copy generic prime.md from template, customize with actual codebase paths.
2. Generate 2-4 codebase-specific prime-<slice>.md variants — one per major slice found in the analysis. Each explicitly lists the 5-10 key files for that slice.

Each prime command: YAML frontmatter with description, Objective, Process (exact files to read), Output (scannable summary template). 50-130 lines.

Builder C — Copy + customize PIV + workflow commands

1. Copy plan.md, implement.md, commit.md from template. Edit in place with this codebase's actual validation/test/lint commands.
2. Generate validate.md from scratch — wraps the codebase's full validation chain. Walk each step with per-step fix guidance. Tabular pass/fail report.

---

Step 5 — Final Report

Brownfield Day-1 Complete — <project-name>

Subagents dispatched: N (list them)

Generated AI Layer:
- CLAUDE.md (<line count> lines)
- .claude/commands/
  - prime.md (<lines>)
  - prime-<slice>.md x <count>
  - plan.md (<lines>)
  - implement.md (<lines>)
  - validate.md (<lines>)
  - commit.md (<lines>)

Total: 1 CLAUDE.md + <N> commands

Recommended next steps:
1. Review CLAUDE.md — edit anything the agent got wrong.
2. Try /prime in a fresh session to verify the orientation lands.
3. Pick a small ticket and run /plan then /implement to test the layer.
4. Update the AI layer manually when major features ship.

---

Critical Principles

1. Dynamic, not fixed. Subagent count adapts to the codebase. 3 for small, 10 for monorepo.
2. Capture what IS. Descriptive, not prescriptive. No refactor proposals.
3. Cite real paths. Every claim references a real file. No placeholders.
4. Copy + customize beats regenerate for template commands. Generate fresh for CLAUDE.md, validate.md, and codebase-specific prime variants.
5. One invocation does it all. The user sends one prompt. You orchestrate the rest.

Python Flat-Import Caveat

If the codebase uses flat sys.path imports (e.g., launchers put a directory on sys.path instead of packaging), note this in CLAUDE.md's Architecture section and in the generated prime commands. Static import resolvers will report false orphans — "dead code" verdicts inside such directories require grep confirmation, not just resolver output. This is a deliberate design choice, not a defect.

YourProduct Client-Onboarding Mode

This skill doubles as a YourProduct "Day-1 AI Enablement" deliverable. When used on a client repo:

• The template_path points at YourProduct's canonical AI-Layer template (or any reference template the operator chooses)
• The generated AI Layer is the deliverable — review, hand off to the client, or commit directly
• Follow-up maintenance: update the AI layer files directly when major features ship
• The assessment upsell is /vertical-slice-audit (score a feature, hand them a migration plan)

What This Skill Does NOT Cover

• Refactoring decisions. Day 1 is descriptive. Refactor decisions belong to a separate planning session.
• Skill creation. New skills come later, once you've seen the same workflow repeat 3+ times.
• Team rollout. Day 1 is for one engineer onboarding the agent.
• Type B Brownfield. This is Type A (no AI Layer yet). Once the layer exists, update the AI layer files directly when major features ship, or run /vertical-slice-audit to score a specific slice.