Project Blueprint

Project Blueprint

Map a codebase by discovering its slices — repeated structural patterns that show up when a dev adds new work of the same kind. Output a written reference that captures what the project actually does, not what it should do.

This skill is descriptive, not prescriptive. It documents reality.

Core principles

1. Discovery over theory. Find patterns by reading structure, not by applying DDD/Hexagonal/Clean checklists.
2. Human-in-the-loop. Pause and ask whenever judgment is needed. Don't invent names. Don't classify ambiguous things.
3. Blueprint is the only persistent artifact. Audits and PR reviews are ephemeral outputs of running the blueprint against code — they don't get committed.
4. Evidence over assertions. Every claim points to a real path/file/line. If you can't point to evidence, mark with ⚠️ or move to open questions.
5. Respect conscious decisions. A choice documented in CLAUDE.md or a decision spec is not an anti-pattern. Only undocumented divergences are.

What this skill produces

Optional cross-cutting findings (UNIVERSAL_NOTES.md) are NOT generated by default — they're emitted to chat when the user explicitly asks for a universal sweep.

Workflow

Step 1 — Detect monorepo vs single project

Find every manifest file at top-level through depth 3:

find . -maxdepth 3 -type f \( \
  -name '*.csproj' -o -name '*.sln' \
  -o -name 'package.json' \
  -o -name 'pyproject.toml' -o -name 'requirements.txt' -o -name 'setup.py' -o -name 'Pipfile' \
  -o -name 'go.mod' \
  -o -name 'Cargo.toml' \
  -o -name 'pom.xml' -o -name 'build.gradle' -o -name 'build.gradle.kts' \
  -o -name 'composer.json' -o -name 'Gemfile' -o -name 'mix.exs' \
\) -not -path '*/node_modules/*' -not -path '*/.venv/*'

Group manifests by directory. Each top-level or depth-2 directory with a manifest is a sub-project candidate. Ignore dependency, build, cache, generated, and vendor folders.

⏸ Stop-and-ask checkpoint 1:

"Detected these N projects: [list]. Is this correct? Anything missing or wrongly included?"

Wait for confirmation. Don't proceed if uncertain.

Step 2 — Per project, Phase A: Stack and layers

For each confirmed project, read:

• Manifest file → language, framework version, key dependencies
• README.md, CLAUDE.md, docs/architecture* → declared conventions, prohibited libraries, migration notes
• .csproj references / package.json workspaces / go.mod modules → inter-module dependency graph

Map the layer structure if visible:

• For .NET: Api → Application → Domain ← Infrastructure / Persistence
• For Node/Python/Go: equivalent if it exists; otherwise note "flat structure"

Step 3 — Per project, Phase B: Vocabulary detection

Walk the directory tree (depth 3-4, excluding bin/obj/node_modules/.venv/dist/target/__pycache__).

For each building block, check if it's instantiated:

Reference references/patterns.md for the architectural pattern signatures (DDD, Hexagonal, Clean, Layered, CQRS, etc.) when needed to label what you found.

Step 4 — Per project, Phase C: Slice discovery

A slice is a repeated folder/file shape — the structural template a dev follows when adding new work of the same kind.

Detection method:

1. List directories at depth 2-3 from project root
2. For each, capture its child filenames
3. Cluster directories whose child filenames match the same regex/pattern
4. Clusters with N ≥ 2 instances → candidate slices
5. Clusters with N = 1 → singleton candidates (require human classification)

For each candidate slice with N ≥ 2:

• Shape: regex of filenames that define membership
• Instances: full list of paths, tagged by dimension if applicable (see Step 5)
• Canonical reference: pick using the heuristic below
• Co-created files: what else gets added in the same commit (DI registration, test mirror, controller endpoint, options class)
• Constraints: imports allowed/forbidden, naming, framework choices observed in the canonical
• Variants: instances deviating from the canonical shape; describe HOW they differ
• Status: active (preferred for new work) / frozen (legacy, do not extend) / deprecated (will be removed)

Canonical selection heuristic (priority order):

1. Exercises the full shape non-trivially (no empty files)
2. Has accompanying tests
3. Recently modified (≤ 6 months)
4. No findings against it in audit history
5. Descriptive name
6. Non-trivial Response/output

If two instances tie on the heuristic, use two-tier canonical: Primary (start here, simpler) + Advanced (richer example).

⏸ Stop-and-ask checkpoint 2 (if needed):

"Slice X has these two equally-strong canonicals: A and B. Which is Primary, which is Advanced? Or are they co-canonical?"

Step 5 — Detect dimensions (within a single project)

Look for folder/namespace patterns separating internal verticals:

• Channel-based: e.g. Voice* vs Whatsapp* markers in a project with multiple input channels
• Tenant-based: e.g. Internal* vs External* markers
• Module-based: explicitly named bounded contexts

If found, tag every slice instance with its dimension (voice | text | channel-agnostic | etc.).

⏸ Stop-and-ask checkpoint 3:

"Detected dimension X with markers [...]. Confirm or correct the dimension labels."

Step 6 — Classify N=1 candidates

Collect everything found with N=1 into a list. For each, ask one question:

⏸ Stop-and-ask checkpoint 4 (group all N=1 in one batch):

"Found N N=1 candidates. For each, classify:" • [path/name]: singleton (unique role, never replicated) | template (first of its kind, more coming) | smell (should have been split into multiple)?

Wait for batch answer before proceeding.

Step 7 — Cross-cutting conventions and asymmetries

Capture rules that span the project but aren't slices:

• Mappers — where they live by boundary
• Serialization — JSON case, BSON, etc.
• Validation — framework and registration
• Error model — envelope shape, code conventions
• Dependency direction — confirmed from manifest graph
• Logging / tracing — single source, conventions

Document known asymmetries explicitly — historic placements, naming exceptions, migration in flight. A reader needs to know "this is weird but intentional" so they don't try to "fix" it.

Step 8 — (Monorepo only) Build the SYSTEM_MAP

After per-project blueprints exist, build the system map covering:

• Project inventory with role of each
• Cross-project calls (caller → callee → protocol → contract)
• Cross-language boundaries explicit, with rules
• Same-language boundaries if any
• Shared external dependencies (databases, SaaS, queues)

For each cross-project boundary, note:

• Who owns the contract
• What kind of change needs coordination
• Mitigations in place

Step 9 — Pre-write summary

Before writing any file, present:

Summary
- Projects: [list]
- Slices per project: [count]
- N=1 classified as: [singletons | templates | smells]
- Dimensions: [if any]
- Files to be written: [list of paths]

⏸ Stop-and-ask checkpoint 5:

"Proceed to write the files above? Or adjust first?"

Step 10 — Write the files

Only after confirmation. Use assets/blueprint-template.md and assets/system-map-template.md as structure.

After writing, present each file path and offer: "Want me to commit these, or are you reviewing first?" Don't commit without explicit go-ahead.

Stop-and-ask checkpoints summary

Optional asks during the run when something genuinely ambiguous appears:

• Slice naming when the shape is clear but the name isn't obvious
• Variant classification (deliberate variant vs accidental divergence)
• Status of a slice (active / frozen / deprecated) when CLAUDE.md doesn't say

What the agent observes vs what the human decides

The agent observes (factual, no asking):

• Folder shapes and their repetition counts
• Imports between modules
• File sizes, method counts
• Default values in source
• Existence of tests/DI registrations
• Matches against architectural pattern signatures

Human decides (always ask):

• Singleton vs template vs smell for N=1
• Slice names when not obvious
• Primary vs advanced canonical when tied
• Whether a variant is deliberate
• Status (active/frozen/deprecated) when undocumented

This separation matters: if the agent guesses on the human's decisions, the blueprint becomes opinion-laden. If the human supplies the judgment, the blueprint stays grounded.

What this skill does NOT do

• Generate anti-pattern audits as persistent files (use pr-antipattern-review for diffs, or run a universal sweep ephemerally if asked)
• Recommend refactors
• Compare PRs against the blueprint (use pr-antipattern-review)
• Make architectural decisions for the team

See also

• references/slice-discovery.md — detailed heuristics for finding slices
• references/patterns.md — architectural pattern signatures (DDD, Hexagonal, Clean, etc.)
• references/universal-checks.md — project-independent observations (emitted on demand only)
• assets/blueprint-template.md — output template per project
• assets/system-map-template.md — output template for monorepos