vibe-architect

name

vibe-architect

description

Architecture planning workflow for establishing code structure, patterns, and principles before any code is written. Runs after brainstorm: and before new: on every project. Triggers on "architect:" prefix, "plan the architecture", "architect this", "how should we structure this", "what patterns should we use". Always runs on every project — no exceptions, no shortcuts. Reads BRIEF.md stack decisions and confirms them explicitly before asking any questions — prevents scaffolding with wrong framework (e.g. Next.js when React+Vite is specified). Produces ARCHITECTURE.md from canonical template — structurally consistent so review:, fix-bug:, and add-feature: can parse it reliably every session. review: uses ARCHITECTURE.md as its primary reference for drift detection. Handles gracefully if BRIEF.md is missing. Detects existing ARCHITECTURE.md before overwriting.

Vibe Architect Skill

Establishes the architectural foundation before a single line of spec or code is written. Every pattern, convention, and structural decision made here becomes the law for the entire build.

Always run in Plan Mode (Shift+Tab). No code. No project files.

---

The O'Reilly principle this enforces

Spec before code — and architecture before spec. Without deliberate architecture decisions, agents make reasonable but unconsidered defaults. Folder structure, naming conventions, state management, error handling — these just happen, inconsistently.

ARCHITECTURE.md is the agent's constitution for the project. Not what gets built (SPEC.md does that) — how everything gets built. Every task from Phase 1 through Phase 3 is measured against it. review: detects drift from it at every phase gate.

Good architecture on a small project costs 20 minutes. Bad architecture on a small project costs days of refactoring.

---

Step 0 — Read BRIEF.md, confirm stack, classify project type

Check for existing ARCHITECTURE.md first: If ARCHITECTURE.md already exists at the project root:

"An ARCHITECTURE.md already exists for this project. Do you want to update it (add new decisions) or start fresh (replace it entirely)?" Wait for answer before proceeding.

Check for BRIEF.md: If BRIEF.md does not exist:

"BRIEF.md not found. Ideally run brainstorm: first — it captures the problem, user, stack preferences, and constraints that make architecture decisions meaningful.

I can proceed without it by asking those questions now, or you can run brainstorm: first. Which do you prefer?"

• If proceeding without: ask for app name, core purpose, platform, and rough stack preference before Step 1.
• If running brainstorm first: stop here and tell user to run brainstorm: then return.

If BRIEF.md exists: read it fully. Extract:

• Core problem and user
• Platform (mobile-first, desktop, both)
• v1 feature set and complexity
• Tech stack preferences or mandates ← CRITICAL
• Compliance requirements (affects architecture choices)
• Known risks
• Agentic flag (if true — agent: should have run before this)

Stack confirmation — mandatory before asking any questions:

After reading BRIEF.md, immediately confirm the stack out loud:

"Stack from BRIEF.md: Frontend: [exact value from brief] Backend: [exact value from brief] Database: [exact value from brief] Auth: [exact value from brief]

Proceeding with this stack. I will NOT suggest alternatives unless a technical constraint discovered during this session requires it."

This one explicit confirmation step prevents the most common architect: failure: silently defaulting to a popular framework (Next.js, Create React App) instead of the stack already decided in brainstorm:.

If the stack seems mismatched for the requirements (e.g. brief says "mobile app" but stack says "Next.js") — flag it now:

"I notice the brief specifies [requirement] but the stack is [choice]. This may cause [issue]. Recommend [alternative]. Proceed with brief's choice or switch?"

Wait for answer before continuing.

Classify project type:

• Web app — frontend (React/Vue/Svelte/Next.js etc) + optional backend
• Mobile app — React Native / Expo / Flutter
• API service — backend only, no UI
• CLI tool — command line
• Static site — HTML/CSS/JS, minimal interactivity
• Library / package — reusable code

Tell the user: "This is a [type] project. I'll ask about [relevant areas]."

Branch questions:

• Web app / Mobile app → Steps 1, 2 (if backend), 3, 4, 5
• API service → Steps 2, 3, 4, 5
• CLI / Library → Steps 3, 4, 5
• Static site → Step 1 (light), 4, 5

---

Step 1 — Frontend architecture (web/mobile only)

Present as recommendations. User says "sounds good" or overrides.

Frontend structure — my recommendations:

1. Folder approach: [Feature-based / Type-based] — I recommend [choice] because [one sentence reason based on BRIEF.md size and complexity]. Sound good, or do you have a preference?

2. State management: For [app name], data is [describe from brief]. I recommend [Context+localStorage / Zustand / Redux / other] because [one sentence reason]. Sound good?

3. TypeScript: Strict mode, no any — the O'Reilly framework requires this. Any reason to deviate?

4. Component library: [Recommend based on design direction — Tailwind only / shadcn/ui / Radix / none / existing if mandated]. Does this fit?

Lock in recommendations if user agrees. Note any overrides.

---

Step 2 — Backend architecture (if project has backend)

Skip entirely if client-only with no API.

Backend structure — my recommendations:

1. API style: REST with clear resource naming. Reason to use tRPC or GraphQL instead?

2. Business logic: [Route handlers / Service layer] — I recommend [choice] because [reason based on complexity].

3. Input validation: [Zod / Joi / yup] at route entry before any logic. For this stack, [Zod] is the best fit. Agree?

4. Error responses: Consistent envelope — { success: false, error: { code, message } }. This is what review: checks for. Agree?

---

Step 3 — Testing philosophy

Testing approach:

My recommended approach for [app name]:

• Unit: pure functions, utilities, calculations — always
• Component: user interactions, state changes, conditional rendering — always
• Integration: [if backend] API endpoints with real DB — always
• E2E: skip for v1 unless a flow is genuinely high-risk

The O'Reilly framework requires tests for every task — what gets tested matters more than coverage numbers. Stricter or lighter than this?

Lock the testing philosophy.

---

Step 4 — Code quality and git conventions

Code quality:

1. Linter: ESLint strict — no-any, no-unused-vars, react-hooks/exhaustive-deps. Existing config to follow?

2. Formatter: Prettier — single quotes, semicolons, 2-space indent, 100 char line length. Standard?

3. Dependencies: Pin exact versions, npm audit before every commit, prefer packages >1M weekly downloads. Sound reasonable?

4. Git commits: Conventional format — feat(scope), fix(scope), docs(scope), design(scope). Doc commits always separate from code. This is what the framework uses throughout. Agree?

5. Pre-commit hooks: Linter + tests before every commit?

---

Step 5 — Synthesise and confirm

Architecture summary for [App Name]:

Project type: [type] Frontend: [structure] · [state] · TypeScript strict · [component library] Backend: [API style] · [logic layer] · [validation] · [error format] (if applicable) Testing: [philosophy summary] Quality: ESLint strict + Prettier + conventional commits + pre-commit hooks Dependencies: pinned, npm audit before commit

Does this look right? Any changes before I write ARCHITECTURE.md?

Wait for confirmation.

---

Step 6 — Generate ARCHITECTURE.md

Read references/ARCHITECTURE_MD.md for the full canonical template.

Generate ARCHITECTURE.md by filling every section of the template:

• Project type section: Copy stack from BRIEF.md verbatim. Include the "Do NOT scaffold with alternatives" warning with the specific stack chosen.
• Folder structure: Generate the actual project tree, not a generic example. Match what PLAN.md will define in the next step.
• Never list: Always include the 6 universal P0 items plus 2 project-specific ones derived from the conversation (e.g. "no direct Supabase calls outside repositories").
• Testing table: Adjust for project complexity (S/M/L from BRIEF.md).
• Architecture decisions log: Fill with the decisions made in Steps 1-5.
• Delete inapplicable sections: Backend section for client-only projects, database section if no DB, etc.

If updating existing ARCHITECTURE.md: add changelog entry and update affected sections only. Never overwrite the Never list or decisions log.

Save as ARCHITECTURE.md at project root. (Moved to vibe/ARCHITECTURE.md when new: runs.)

---

Step 7 — Update BRIEF.md

Append to BRIEF.md:

---
## Architecture decisions
> Decided during architect: — [date]
> Full detail in ARCHITECTURE.md

- Project type: [type]
- Frontend structure: [choice] — [reason]
- State management: [choice] — [reason]
- TypeScript: strict mode, no any
- Testing: [philosophy summary]
- Backend: [choice if applicable]
- Code quality: ESLint strict + Prettier + conventional commits
- Dependencies: pinned, npm audit before commit

---

Step 8 — Tell the user

---

✅ Architecture locked.

Decisions made: [N] O'Reilly principles: enforced in every session via ARCHITECTURE.md

Every task Phase 1 through Phase 3 follows these patterns. No agent defaults. No inconsistent conventions. No architectural drift. review: uses ARCHITECTURE.md as primary reference — drift caught at every gate.

To generate your project kit:

new: [your app description]

---

---

How the agent uses ARCHITECTURE.md every session

Session startup order:

1. Read CLAUDE.md
2. Read vibe/CODEBASE.md
3. Read vibe/ARCHITECTURE.md — check patterns for today's task
4. Read vibe/SPEC_INDEX.md
5. Read vibe/TASKS.md

Before writing code: does this follow ARCHITECTURE.md patterns? After writing code: did I introduce a new pattern not in ARCHITECTURE.md? → Yes: update ARCHITECTURE.md before marking task done. → Yes, and it was a necessary deviation: log in DECISIONS.md, update ARCHITECTURE.md.

Document update rules

Document	Updated when
ARCHITECTURE.md	New pattern, library added, tech decision changed
BRIEF.md	Scope changes, core value refined, stack changed
SPEC.md + SPEC_INDEX.md	Always together — any scope change
PLAN.md	Architecture changes, phase structure changes
TASKS.md	After every single task — no exceptions
CODEBASE.md	New file, route, schema, or pattern added
DECISIONS.md	Every drift, scope change, tech choice mid-build
FEATURE_TASKS.md	Task done, decisions filled, checklist ticked
CLAUDE.md	Conventions change, active feature changes

The rule: if something changed in the codebase, something changed in the docs. If the docs aren't updated, the task isn't done.