cd ~/Documents/my-project-name
claude

Read the PRD at /docs/prd/prd.md.
Read AGENTS.md at the project root. This file currently contains placeholder sections that you will populate in Step 4. For now, review the structure to understand the template you will be filling in: file ownership table, architecture rules, code standards, and team coordination patterns.

Based on the requirements, recommend the technical architecture.
For each decision area below, give me 2-3 options with pros and cons.
Do NOT make final decisions -- present options for me to choose.

Decision areas:

1. **Frontend framework** (if applicable) -- What should the UI be built with?
2. **Backend framework** (if applicable) -- What should the server be built with?
3. **Database** (if applicable) -- What data store should we use?
4. **Hosting/deployment** -- Where will this run?
5. **Testing framework** -- What do we use for unit, integration, and e2e tests?
6. **CSS/styling approach** -- Tailwind, CSS modules, styled-components, etc.?
7. **State management** (if applicable) -- How do we manage client-side state?
8. **Authentication** (if applicable) -- How do users log in?
9. **API approach** -- REST, GraphQL, tRPC, or other?
10. **Project structure** -- How do we organise /src/?

For EACH option you recommend, use Context7 to verify the library/framework exists. Use Serena to explore the existing codebase structure and understand symbol relationships before recommending a project structure.

Do not guess. If Context7 cannot confirm something, say so explicitly.

For decision area 10 (Project structure), the recommendation must consider
agent team file ownership. Propose a /src/ structure where:
- Directories map cleanly to teammate roles (API, DB, frontend, shared/common)
- Shared code is isolated in a /src/shared/ or /src/common/ directory with clear ownership rules
- No two teammates need to regularly edit the same files
- Integration points between areas are handled through explicit interfaces, not shared files

Present everything in a clear comparison format so I can make quick decisions.

Here are my decisions: 1. Frontend: [your choice]
2. Backend: [your choice]
3. Database: [your choice]
4. Hosting: [your choice]
5. Testing: [your choice]
6. Styling: [your choice]
7. State management: [your choice]
8. Auth: [your choice]
9. API: [your choice]

For each architecture decision I just made, create an ADR in /docs/adr/
using the template at /docs/adr/template.md.

Number them sequentially:
- ADR-001: [first decision]
- ADR-002: [second decision]
- etc.

For each ADR:
- Set status to "Accepted"
- Include the alternatives I did NOT choose and explain why (based on our discussion)
- Include consequences (positive and negative)
- Reference the specific PRD requirements that drove this decision

Create an additional ADR for the project structure decision:
- ADR-[N]: Project Structure and Team File Ownership
- Document the /src/ layout and which directories map to which teammate roles
- Document the shared code policy and how integration points work
- This ADR is what teammates will reference when they need to understand boundaries

Also create /docs/adr/README.md that lists all ADRs as a table of contents with their status.

After creating the ADRs, update AGENTS.md:
- Fill in the "Architecture Rules" section with the actual decisions made
- Fill in the "Code Standards" section based on the chosen tech stack
- Update the "File Ownership" table to match the actual /src/ structure from the project structure ADR
- Add any stack-specific coordination rules (e.g. if using a monorepo, how do teammates avoid conflicts in shared config files?)

AGENTS.md must be accurate and complete after this step. It is the contract that every teammate reads.

Read:
- CLAUDE.md for project overview and tech stack
- The PRD at /docs/prd/prd.md for UI/UX requirements and key screens
- The Idea Pack at /docs/idea/idea-pack.md for product personality and target users
- The ADRs at /docs/adr/ for the chosen CSS/styling approach, frontend framework, and rendering strategy

Use the UI/UX Pro Max skill to generate a complete design system for this project. There is no existing branding to work from -- we are building the visual identity from scratch.

The design system must align with the architecture decisions already made:
- Use the CSS/styling approach from the ADRs (e.g. Tailwind, CSS modules, etc.)
- Respect the rendering strategy (SSR/SSG/hybrid) for any performance-sensitive design choices
- Component patterns should match the frontend framework conventions

Before creating the design system, ask me about:

1. Mood/personality -- Should this feel playful, corporate, minimal, bold, technical, warm?
2. Give me 3-4 pairs to choose between (e.g. "Friendly vs Professional", "Minimal vs Feature-rich")
3. Colour direction -- Any colours I'm drawn to or want to avoid? Light mode, dark mode, or both?
4. Typography feel -- Clean and geometric, humanist and approachable, or monospace/technical?
5. Density -- Spacious and breathing, or compact and information-dense?
6. Reference products -- Any existing apps or sites whose visual style I admire? (Not to copy, but to calibrate direction)

For public-facing landing pages and marketing content, also reference the frontend-design skill for bold creative direction. The UI/UX Pro Max skill design system provides consistency; the frontend-design skill provides distinctiveness on hero sections, CTAs, and first-impression surfaces.

After getting my answers:

- Use the UI/UX Pro Max skill to generate the full design system with frontend-design supporting the generation of the distinctive first-impression surfaces
- Setup the design system so it can be easily modified later, but feels modern
- Ensure /docs/design-system/MASTER.md exists and is complete
- Ensure /.claude/skills/ui-ux-pro-max/ exists and is up to date
- The design system should be informed by the PRD's UI/UX requirements and the Idea Pack's target users -- the visual design should match who this is for

Use this if you DO have existing branding guidelines

Read:
- CLAUDE.md for project overview and tech stack
- The PRD at /docs/prd/prd.md for UI/UX requirements and key screens
- The Idea Pack at /docs/idea/idea-pack.md for product personality and target users
- The ADRs at /docs/adr/ for the chosen CSS/styling approach, frontend framework, and rendering strategy

Use the UI/UX Pro Max skill to generate a complete design system for this project.

The design system must align with the architecture decisions already made:
- Use the CSS/styling approach from the ADRs (e.g. Tailwind, CSS modules, etc.)
- Respect the rendering strategy (SSR/SSG/hybrid) for any performance-sensitive design choices
- Component patterns should match the frontend framework conventions

We have existing branding to work from.
Attach any of the following you have (use clear file names):
- Brand guidelines PDF
- Link to existing website
- Tone of voice or personality notes (if not in the guidelines)

Step 1: Review and extract.
Go through all the branding inputs above and extract everything you can find:
- Colours: primary, secondary, accent, neutrals, any semantic colours
- Typography: font families, sizes, weights, line heights
- Spacing and layout patterns
- Component styles (buttons, inputs, cards, nav, etc.)
- Border radius, shadows, elevation
- Animation or motion patterns
- Responsive behaviour
- Overall personality, tone, and visual direction

Show me what you extracted in a summary. Organise it as:
- Extracted -- things you found definitive answers for
- Implied -- things you inferred from the visual style but weren't explicitly stated
- Missing -- things the branding doesn't cover that the design system needs

Step 2: Ask me questions only about the gaps.
Based on what's missing or ambiguous, ask me targeted questions to fill in the blanks.
Only ask about things you couldn't extract or confidently infer. This might include:
- Dark mode (if not addressed in the branding)
- Error/success/warning states (if no semantic colours defined)
- Mobile patterns (if branding is desktop-only)
- Component density and spacing (if not explicit)
- How closely to match vs room to modernise
- Anything about the current branding I want to evolve or move away from

Step 3: Generate the design system.
After getting my answers:
- Use the UI/UX Pro Max skill to generate the full design system, grounded in the extracted brand but extending it to cover everything the project needs
- Setup the design system so it can be easily modified later
- Ensure /docs/design-system/MASTER.md exists and is complete
- Ensure /.claude/skills/ui-ux-pro-max/ exists and is up to date
- The design system should bridge the existing brand identity with the PRD's UI/UX requirements
- Call out anywhere the existing branding conflicts with the project's needs and recommend how to resolve it

Now that architecture decisions are recorded, update both coordination files
before we create the implementation plan.

Update CLAUDE.md:
- Fill in the Tech Stack section with our chosen technologies and versions
- Add the test run command
- Add any build/dev server commands
- Update the "Agent Team Context" section:
  - Set "Current phase" to "Planning -- implementation plan next"
  - Fill in "Architecture" with a one-line summary of the stack
  - Fill in "API contracts" with a pointer to /docs/prd/prd.md (API Contracts section)
- Update the "File Ownership" table to match the actual project structure
- Keep it concise -- this is a quick reference card, not a full document

Review AGENTS.md and verify:
- "Architecture Rules" section is filled in and accurate
- "File Ownership" table matches the /src/ structure from the project structure ADR
- "Code Standards" section reflects the chosen stack
- "Team Coordination Rules" include any stack-specific rules

Both files must be complete and self-contained.
A freshly spawned teammate reading only CLAUDE.md and AGENTS.md should be able to:
- Understand what the project is
- Know the tech stack and conventions
- Know which files they own
- Know the API contracts they're building against
- Know how to run tests
- Know the coordination rules

If any of that is missing, add it now.
These files must be solid before we create the implementation plan,
because the plan will reference them as the source of truth for team compositions.

Read:
- CLAUDE.md at the project root (now fully populated)
- AGENTS.md at the project root (now fully populated)
- The PRD at /docs/prd/prd.md
- All ADRs in /docs/adr/
- The phased delivery plan from the PRD

CLAUDE.md and AGENTS.md are now the source of truth for tech stack,
file ownership, and coordination rules. Use them as the foundation for team compositions.

Create a detailed implementation plan at /docs/implementation-plan.md.
This plan is what we will follow during the build phase.

For EACH phase from the PRD:

### Phase [N]: [Name]

**Branch name:** feature/phase-[N]-[short-description]

**Execution mode:** Solo | Sub-agents | Agent Team
[Choose based on the phase. Use this logic:
- Solo: simple foundational setup, single-area work
- Sub-agents: independent parallel tasks that don't need inter-worker communication
- Agent Team: cross-layer work where teammates need to coordinate, share discoveries, or work against shared contracts]

**Team composition (if Agent Team):**
- Lead mode: Plan | Delegate (Delegate for 4+ teammates, Plan for 2-3)
- Teammate 1: [Role] -- owns [directories from AGENTS.md] -- [brief of what they build]
- Teammate 2: [Role] -- owns [directories from AGENTS.md] -- [brief of what they build]
- etc.
- File ownership must match the AGENTS.md table. If a phase needs ownership that differs from the default, note the override explicitly.

**Spawn context (if Agent Team):**
What each teammate needs in their spawn prompt beyond CLAUDE.md and AGENTS.md:
- Relevant API contracts from the PRD
- Specific interfaces or types they depend on
- What "done" looks like for their tasks

**Prerequisites:** What must be done before this phase starts?

**Steps (in order):**
1. [Specific step -- e.g., "Create the database schema for User and Project entities"]
2. [Next step]
3. [Next step]
...

**Files to create/modify:**
List every file that will be created or changed.
Group by teammate ownership if this is an Agent Team phase.

**Tests to write:**
- [Specific test -- e.g., "Test that user registration returns 201 with valid input"]
- [Specific test -- e.g., "Test that user registration returns 400 with missing email"]

**Acceptance criteria satisfied:**
List the AC numbers from the checklist that this phase covers.

**Definition of done:**
- [ ] All steps completed
- [ ] All tests written and passing
- [ ] Code reviewed
- [ ] AC items checked off
- [ ] Committed to feature branch
- [ ] If Agent Team: TeamDelete called, no orphaned sessions

Make the steps specific enough that someone (or Claude) could execute them
one at a time without additional context.

After creating the implementation plan:

1. Create /docs/interfaces.md:
   - Extract all integration points between feature areas from the plan
   - Document the interfaces/contracts that teammates will code against
   - This file is referenced in AGENTS.md and will be read by every teammate

2. Update CLAUDE.md:
   - Set "Current phase" to "Ready to build -- Phase 1"
   - Add a pointer to /docs/implementation-plan.md
   - Add a pointer to /docs/interfaces.md under "API contracts"

3. Update AGENTS.md team patterns section if any phase compositions
   differ from the default patterns already documented

Read:
- The implementation plan at /docs/implementation-plan.md for the full list of pages and which phase each belongs to
- The PRD at /docs/prd/prd.md for functional requirements, user stories, and API contracts per page
- The design system at /docs/design-system/MASTER.md for available components, colour tokens, typography, and spacing
- AGENTS.md for file ownership boundaries

Use the UI/UX Pro Max skill to generate a page spec for every page/screen
listed in the implementation plan.

Create each spec at /docs/design-system/pages/[page-name].md

Each page spec must include:

1. **Purpose** -- One sentence on what this page does and which user stories it satisfies (reference US numbers)
2. **Layout** -- Describe the page structure: header, sidebar, main content area, footer, etc. Include a simple ASCII wireframe or describe the grid/layout approach
3. **Components used** -- List every component from the design system this page uses (buttons, inputs, cards, tables, modals, etc.) and how they're configured (e.g. "Primary button -- full width", "Data table -- sortable, paginated")
4. **Data sources** -- What API endpoints or data does this page consume? Reference the API contracts from the PRD. What loading, empty, and error states need handling?
5. **User interactions** -- What can the user do on this page? Map each interaction to its outcome (e.g. "Click 'Save' -- POST to /api/projects -- show success toast or inline error")
6. **Responsive behaviour** -- How does this page adapt at each breakpoint? What stacks, collapses, or hides on mobile?
7. **Phase** -- Which implementation phase delivers this page

After creating all page specs, create /docs/design-system/pages/README.md
with a table listing every page, its phase, and its primary user stories.

Update the implementation plan:
- For each phase that includes frontend work, add a reference to the relevant page specs
  under the "Spawn context" section so frontend teammates get pointed to them

Read all project documentation:
- CLAUDE.md
- AGENTS.md
- /docs/idea/idea-pack.md
- /docs/prd/prd.md
- /docs/prd/acceptance-checklist.md
- /docs/adr/ (all ADRs and README.md)
- /docs/design-system/MASTER.md
- /docs/design-system/pages/ (all page specs)
- /docs/implementation-plan.md
- /docs/interfaces.md

Step 1: Pre-flight check.
Before creating any issues, verify everything is consistent and complete:

- [ ] Every user story in the PRD has acceptance criteria
- [ ] Every AC in the PRD appears in the acceptance checklist
- [ ] Every phase in the implementation plan maps to user stories in the PRD
- [ ] Every ADR references the PRD requirements that drove it
- [ ] CLAUDE.md has the tech stack, test command, and build commands filled in
- [ ] AGENTS.md has architecture rules, file ownership, and code standards filled in
- [ ] The file ownership table in AGENTS.md matches the /src/ structure in the project structure ADR
- [ ] Every frontend phase has corresponding page specs in /docs/design-system/pages/
- [ ] API contracts in the PRD are detailed enough for separate teammates to build against
- [ ] /docs/interfaces.md exists and documents integration points between feature areas
- [ ] Phase prerequisites in the implementation plan form a valid dependency chain (no circular deps, no missing prereqs)

If anything fails, list what's missing or inconsistent and fix it before proceeding.
Do not create Beads issues until everything passes.

Step 2: Create Beads issues.
Once the pre-flight check passes, create a Beads issue for each phase using `bd create`.

Each issue should include:
- Title: Phase [N] -- [Phase name]
- Branch name from the implementation plan
- Execution mode: Solo, Sub-agents, or Agent Team
- Team composition and lead mode (if Agent Team)
- User stories it delivers (US numbers)
- Acceptance criteria it must satisfy (AC numbers from the checklist)
- Page specs to reference (if the phase includes frontend work)
- Prerequisites: which phases must be complete before this one starts
- Definition of done from the implementation plan

Order the issues so that prerequisite phases come first.
If any phases can run in parallel (no dependency between them), note that in both issues.

After creating all issues, run `bd list` and show me the full list so I can verify.

Commit all new files (ADRs, implementation plan, updated CLAUDE.md, Agents) with message: "docs: architecture decisions and implementation plan"