Project Architecture Flow

This skill turns a project idea into a right-sized architecture: it gathers the scope and PRD, analyzes them to decide how much structure the project actually needs, and produces the docs and AGENT.md context files that keep that structure legible to future agents (and humans) working on it.

Why this exists

The single biggest architecture mistake in either direction is picking the wrong amount of structure: over-engineering a small tool into a multi-module system nobody needs, or letting a genuinely multi-domain product sprawl inside one undifferentiated codebase where an agent has to read everything to change anything. The scope/PRD analysis below exists to make that call deliberately, with reasoning the user can see and override, instead of defaulting to whatever's fastest to type.

The other recurring failure mode this skill addresses is context loss across a growing codebase. A single AGENT.md file works fine until a project has real module boundaries — at that point an agent working inside one module needs local context without having to re-read the whole system, but it also needs to know when something it just changed reaches outside its module. That's why the modular tier uses a root AGENT.md plus one per module, with an explicit escalation path between them (see "Cross-Module Impact Log" below) — the module-local file is the fast path for day-to-day work, the root file is what stops modules from silently drifting apart.

The workflow

Follow these steps in order. Don't skip the scope/PRD gathering step even if the user jumps straight to "make me a modular monolith" — you need the content to fill in the docs, and a quick gut-check is often useful even when the user's already decided.

Step 1: Gather scope and PRD

Ask the user for (or help them draft, if they don't have one yet):

• What the project does and who it's for
• The core feature areas (this is the main signal for the scaling decision)
• Expected scale (users, traffic, team size) if known
• Whether it's full-stack, backend-only, frontend-only, etc.
• Any constraints already decided (stack, must-integrate-with-X, compliance)

If the user pastes an existing PRD or describes it in prose, that's sufficient — don't force them into a rigid Q&A if they've already given you the substance. Use templates/PROJECT_OVERVIEW.md as the shape to fill in either way.

Step 2: Analyze and propose a scope tier

Infer the tier from the PRD content, then say so explicitly and let the user confirm or override — don't silently commit to a tier.

Signals that point toward monolith (single service, single root AGENT.md):

• One or two feature areas that share the same data and rules
• Small expected team (a handful of people or fewer)
• No clearly separable domains — features are tightly interdependent

Signals that point toward modular monolith (root AGENT.md + per-module AGENT.md):

• Several feature areas that are each coherent enough to describe in one or two sentences and could plausibly be worked on independently
• Distinct data ownership per feature area (e.g. billing vs. content vs. auth)
• A team large enough that multiple people/agents will work in different parts concurrently
• The user explicitly expects the project to grow into multiple independently-evolving domains

State your reasoning plainly, e.g. "This looks like a monolith to me — the PRD describes one core workflow with a couple of supporting screens, no clearly separable domains. Want me to proceed with that, or do you already know this needs to be modular?" Then proceed with whichever tier the user confirms.

Step 3: Design the architecture for that tier

First, determine which of three project shapes this is, from the PRD's stack section — this decides which layout below applies:

• Full-stack — both a frontend and a backend/API exist in this project.
• Backend-only — an API/service with no frontend at all.
• Frontend-only — a client that calls someone else's API, with no backend of its own.

There is no standalone /ui layer in any shape or tier. Never create empty placeholder folders for a side that doesn't exist in the project (e.g. don't add business/data to a frontend-only project, and don't add ui/components to a backend-only one).

Don't tie the skill's guidance to any one framework beyond the examples below; use whatever fits the user's stated stack, and fall back to generic language when the stack isn't decided yet.

Full-stack

Frontend and backend get separate structuring patterns within the same project — don't force both into one generic /ui /business /data triad.

• Backend: business logic and data access stay separate — route handlers / API endpoints stay thin and call into a business layer, which is the only thing that talks to the data layer.
• Frontend: organized by the framework's own conventions (e.g. Next.js app/ routing, feature-scoped components/hooks) — route/page components stay thin and call into shared hooks or a client-side data layer. No /ui folder.

Monolith layout:

/app or /pages         (frontend: routes/pages, framework convention)
/components            (frontend: shared/feature components)
/hooks or /lib/client   (frontend: client-side data access, e.g. query hooks)
/server or /backend
  /business
  /data
/docs
  PROJECT_OVERVIEW.md
  ARCHITECTURE.md
  QUICK_REFERENCE.md
AGENT.md

Modular monolith layout:

/app or /pages                 (frontend routes, framework convention — cross-module)
/modules
  /<module-a>
    /components              (frontend: module-scoped components/hooks)
    /business                (backend: module-scoped logic)
    /data                    (backend: module-scoped data access)
    AGENT.md
  /<module-b>
    ...
/docs
  PROJECT_OVERVIEW.md
  ARCHITECTURE.md
  QUICK_REFERENCE.md
AGENT.md

Backend-only

No frontend folders of any kind — just business logic and data access, regardless of language/framework (Python, Node, Go, etc.).

Monolith layout:

/business               (rules/logic; route or API handlers stay thin and call in here)
/data                    (queries/persistence; only layer that talks to the DB)
/docs
  PROJECT_OVERVIEW.md
  ARCHITECTURE.md
  QUICK_REFERENCE.md
AGENT.md

Modular monolith layout:

/modules
  /<module-a>
    /business
    /data
    AGENT.md
  /<module-b>
    ...
/docs
  PROJECT_OVERVIEW.md
  ARCHITECTURE.md
  QUICK_REFERENCE.md
AGENT.md

Frontend-only

No backend folders of any kind — organized entirely by the framework's own conventions, calling an external API.

Monolith layout:

/app or /pages          (routes/pages, framework convention)
/components             (shared/feature components)
/hooks or /lib/client    (client-side data access, e.g. calls to the external API)
/docs
  PROJECT_OVERVIEW.md
  ARCHITECTURE.md
  QUICK_REFERENCE.md
AGENT.md

Modular monolith layout:

/app or /pages                 (routes, framework convention — cross-module)
/modules
  /<module-a>
    /components              (module-scoped components/hooks)
    AGENT.md
  /<module-b>
    ...
/docs
  PROJECT_OVERVIEW.md
  ARCHITECTURE.md
  QUICK_REFERENCE.md
AGENT.md

Propose the module breakdown based on the feature areas from Step 1 — each module should map to something a person could describe as one coherent responsibility. If a "module" would just be a single CRUD screen with no real independent logic, it's probably not a module; fold it into a related one or reconsider the tier. Within a module, keep the frontend/backend split above rather than collapsing them into one undifferentiated folder.

Step 4: Present the plan before creating anything

Show the user the proposed folder tree, the module list (if applicable), and a short summary of the reasoning from Step 2. This is a plan for approval, not a fait accompli — the user said they want to see it described first and confirm before files get created. Ask directly: "Want me to create these files and folders now?"

This is a hard gate, not a formality. Do not run Step 5 (scaffolding) until the user has explicitly said yes. If the user's reply is ambiguous, a change to the plan, or anything other than a clear go-ahead, treat it as "not yet" — show the revised plan and ask again rather than proceeding.

Step 5: Scaffold the files

Once confirmed, create the actual folders and files using the templates in templates/:

• templates/PROJECT_OVERVIEW.md → /docs/PROJECT_OVERVIEW.md, filled in with what was gathered in Step 1
• templates/ARCHITECTURE.md → /docs/ARCHITECTURE.md, filled in with the tier, reasoning, layout, and module boundaries/data ownership if modular
• templates/QUICK_REFERENCE.md → /docs/QUICK_REFERENCE.md, the one-page quick reference — keep this short, it's meant to be skimmable
• templates/AGENT_ROOT.md → root /AGENT.md
• For each module (modular tier only): templates/AGENT_MODULE.md → /modules/<name>/AGENT.md

Fill in every template placeholder — don't leave <Project Name> or table headers unfilled. Empty tables (like the Cross-Module Impact Log) are fine to leave as empty tables; they're meant to be filled in as the project evolves, not up front.

Create the actual empty folders too — only the ones that match the project's shape from Step 3 (full-stack, backend-only, or frontend-only), with a .gitkeep or similar if the tooling needs it — not just the docs. The point is a working scaffold the user can start building into immediately, without placeholder folders for a side the project doesn't have.

Step 6: Note the Agile/SDLC framing

Mention to the user that these docs are meant to be living documents under an Agile approach, not written once and abandoned — the PRD, ARCHITECTURE.md, and AGENT.md files should get updated as scope evolves across iterations. This is already noted inside the templates themselves, but it's worth saying out loud so the user doesn't treat the initial scaffold as final.

Ongoing use: adding a module or feature later

If the user comes back later asking "where should this new feature live," that's a mid-project rerun of Step 2's analysis, scoped to just the new feature:

• Does it fit inside an existing module/layer, or does it need its own module?
• If it's a monolith that's now accumulating enough distinct domains to justify going modular, say so — this is exactly the kind of re-evaluation the tier decision should get as a project grows, not a one-time call.
• Root vs. local logging is not optional — check dependency direction before writing anywhere:
  • If the change stays entirely inside one module (no other module depends on it, no shared interface/data touched) → log it only in that module's own AGENT.md under "Local Context Log". Do not touch the root AGENT.md at all.
  • If the change affects another module's interface, shared data, or a cross-cutting concern → log it in both the root AGENT.md's Cross-Module Impact Log and the affected modules' own "Local Context Log" — see "Escalate to Root When..." inside templates/AGENT_MODULE.md for the exact triggers.
  • When unsure which case applies, ask the user rather than guessing — don't default to logging at root "just in case."

A note on AGENT.md vs other agent-context filenames

This skill uses AGENT.md as the filename, matching the user's own convention. If the user's project already uses a different convention (e.g. CLAUDE.md), match theirs instead — the content and structure matter more than the exact filename.