# Repository Guidelines

Astro frontend + Payload CMS backend monorepo for website migration.

## Quick Reference

| Command | Purpose |
|---------|---------|
| `pnpm install` | Sync dependencies |
| `pnpm dev` | Start dev server (Astro at :4321) |
| `pnpm test:unit` | Run Vitest tests |
| `pnpm test:e2e` | Run Playwright tests |
| `pnpm build` | Production build |

## Module Locations

| Type | Location |
|------|----------|
| Frontend components | `frontend/src/components` |
| Frontend routes | `frontend/src/pages` |
| Frontend shared | `frontend/src/services` or `frontend/src/lib` |
| Backend collections | `backend/src/collections` |
| Backend auth/integrations | `backend/src` |
| Contract tests | `backend/tests` |
| Specs | `specs/001-users-pukpuk-dev/` |

## Coding Conventions

- **Frontend**: TypeScript/TSX with strict typing. `PascalCase` for Astro components, `camelCase` for variables/functions, `kebab-case` for file names.
- **Backend**: Payload collections use singular `PascalCase` with `kebab-case` slugs.
- **Testing**: Vitest suites beside modules (`*.spec.ts`), Playwright specs in `frontend/tests/e2e/`.

## Git Workflow

- **Conventional Commits**: `feat:`, `fix:`, `chore:`, etc.
- **PRs**: Include test results, screenshots for UX changes, schema updates.

## Security

- Store secrets in `.env` (never commit)
- Required: `PAYLOAD_CMS_URL`, `PAYLOAD_CMS_API_KEY`

## BMAD Agents & Tasks

This project uses BMAD-METHOD for structured development. Agent and task definitions
are managed in `.bmad-core/` and auto-generated into this file.

**Useful commands:**
- `npx bmad-method list:agents` - List available agents
- `npx bmad-method install -f -i codex` - Regenerate Codex section
- `npx bmad-method install -f -i opencode` - Regenerate OpenCode section

For agent/task details, see:
- `.bmad-core/agents/` - Agent definitions
- `.bmad-core/tasks/` - Task definitions
- `.bmad-core/user-guide.md` - Full BMAD documentation

---

<!-- BEGIN: BMAD-AGENTS -->
<!-- Auto-generated by: npx bmad-method install -f -i codex -->
<!-- To regenerate: npx bmad-method install -f -i codex -->

# BMAD-METHOD Agents and Tasks

This section is auto-generated by BMAD-METHOD for Codex. Codex merges this AGENTS.md into context.

## How To Use With Codex

- Codex CLI: run `codex` in this project. Reference an agent naturally, e.g., "As dev, implement ...".
- Codex Web: open this repo and reference roles the same way; Codex reads `AGENTS.md`.
- Commit `.bmad-core` and this `AGENTS.md` file to your repo so Codex (Web/CLI) can read full agent definitions.
- Refresh this section after agent updates: `npx bmad-method install -f -i codex`.

### Helpful Commands

- List agents: `npx bmad-method list:agents`
- Reinstall BMAD core and regenerate AGENTS.md: `npx bmad-method install -f -i codex`
- Validate configuration: `npx bmad-method validate`

## Agents

### Directory

| Title | ID | When To Use |
|---|---|---|
| UX Expert | ux-expert | Use for UI/UX design, wireframes, prototypes, front-end specifications, and user experience optimization |
| Scrum Master | sm | Use for story creation, epic management, retrospectives in party-mode, and agile process guidance |
| Test Architect & Quality Advisor | qa | Use for comprehensive test architecture review, quality gate decisions, and code improvement. Provides thorough analysis including requirements traceability, risk assessment, and test strategy. Advisory only - teams choose their quality bar. |
| Product Owner | po | Use for backlog management, story refinement, acceptance criteria, sprint planning, and prioritization decisions |
| Product Manager | pm | Use for creating PRDs, product strategy, feature prioritization, roadmap planning, and stakeholder communication |
| Full Stack Developer | dev | 'Use for code implementation, debugging, refactoring, and development best practices' |
| BMad Master Orchestrator | bmad-orchestrator | Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult |
| BMad Master Task Executor | bmad-master | Use when you need comprehensive expertise across all domains, running 1 off tasks that do not require a persona, or just wanting to use the same agent for many things. |
| Architect | architect | Use for system design, architecture documents, technology selection, API design, and infrastructure planning |
| Business Analyst | analyst | Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield) |
| Web Vitals Optimizer | web-vitals-optimizer | Core Web Vitals optimization specialist |
| Unused Code Cleaner | unused-code-cleaner | Detects and removes unused code across multiple languages |
| Ui Ux Designer | ui-ux-designer | UI/UX design specialist for user-centered design |
| Prompt Engineer | prompt-engineer | Expert prompt optimization for LLMs and AI systems |
| Frontend Developer | frontend-developer | Frontend development specialist for React applications |
| Devops Engineer | devops-engineer | DevOps and infrastructure specialist |
| Context Manager | context-manager | Context management specialist for multi-agent workflows |
| Code Reviewer | code-reviewer | Expert code review specialist for quality and security |
| Backend Architect | backend-architect | Backend system architecture and API design specialist |
| Setting & Universe Designer | world-builder | Use for creating consistent worlds, magic systems, cultures |
| Story Structure Specialist | plot-architect | Use for story structure, plot development, and narrative arc design |
| Interactive Narrative Architect | narrative-designer | Use for branching narratives and interactive storytelling |
| Genre Convention Expert | genre-specialist | Use for genre requirements and market expectations |
| Style & Structure Editor | editor | Use for line editing and style consistency |
| Conversation & Voice Expert | dialog-specialist | Use for dialog refinement and conversation flow |
| Book Cover Designer & KDP Specialist | cover-designer | Use to generate AI-ready cover art prompts |
| Character Development Expert | character-psychologist | Use for character creation and motivation analysis |
| Renowned Literary Critic | book-critic | Professional review of manuscripts |
| Reader Experience Simulator | beta-reader | Use for reader perspective and engagement analysis |

> **Note:** Full agent definitions are in `.bmad-core/agents/`. Use `npx bmad-method list:agents` for details.

## Tasks

For task definitions, see `.bmad-core/tasks/`. Key tasks include:
- `create-next-story` - Prepare user stories for implementation
- `review-story` - Comprehensive test architecture review
- `test-design` - Design test scenarios and coverage
- `trace-requirements` - Requirements to tests traceability
- `risk-profile` - Risk assessment and mitigation

<!-- END: BMAD-AGENTS -->

<!-- BEGIN: BMAD-AGENTS-OPENCODE -->
<!-- Auto-generated by: npx bmad-method install -f -i opencode -->
<!-- To regenerate: npx bmad-method install -f -i opencode -->

# BMAD-METHOD Agents and Tasks (OpenCode)

OpenCode reads AGENTS.md during initialization. Run `npx bmad-method install -f -i opencode` to regenerate this section.

> **Note:** Same agents and tasks as Codex section above. See `.bmad-core/` for full definitions.

<!-- END: BMAD-AGENTS-OPENCODE -->

---

## Progressive Disclosure Memory

Use `agent-swarm` skill when executing multiple independent stories in parallel via Task tool with run_in_background.