Development
AI Collaboration
Rule ownership, nine repo skills, layered implementation, and verification.
Rules and Documentation
AGENTS.md: source of truth for architecture, boundaries, routing, and verification defaults.README.md: human-facing positioning, setup, commands, and deployment entry points..agents/skills/*/SKILL.md: task workflows, real entry points, and done criteria..claude/skills/is a generated copy for Claude Code (pnpm skills:sync);pnpm skills:checkverifies every referenced path in CI.docs/getting-started.en.md: the buyer's path from clone to production, with every human-only step and the recommended MCP servers.CLAUDE.md: tool/runtime preferences, not another copy of architecture rules.tests/README.mdandtests/e2e/SCENARIOS.md: test setup and browser acceptance map.
Task Routing
| Skill | Scope |
|---|---|
musemvp-setup | Run locally with muse:init, read muse:doctor, fix setup |
musemvp-connect-services | Payments (Dodo through its MCP), mail, OAuth, Turnstile, uploads; separates human-only steps |
musemvp-new-feature | Behavior, data, auth, billing, API |
musemvp-customize-site | Public copy, pages, navigation, pricing presentation, content |
musemvp-customize-app | Signed-in shell, navigation, and the /app home |
musemvp-testing | Test layers, helpers, and running suites |
musemvp-review | Merge and launch risk review |
musemvp-deploy | Cloudflare Workers, Vercel, or Docker |
musemvp-changelog | Bilingual changelog from commits |
Claude Code loads .claude/skills; Codex and other tools that support the Agent Skills format read .agents/skills. Broad requests follow the order in AGENTS.md: setup, site, app, first feature, services, review, deploy.
Delivery Loop
- Run
pnpm muse:doctor --json, then inspect the owning route/module/config/query andAGENTS.md. - Define acceptance; update
SCENARIOS.mdfor browser journeys. - Write failing tests first for package behavior, schemas, and bug fixes.
- Implement
queries → modules/lib → routes → api-client → UI. Drivers belong in appsrc/server; auth/API wiring stays insrc/backend. - Manually verify the real app before fixing automated assertions, then run the narrowest useful tests.
- Report passed, failed, unrun, and deferred paths. Types/rendering alone are not acceptance.
Packages cannot use app @/; modules do not access DB directly. Derivative messages go only into packages/i18n/src/translations/{en,zh}/mvp.json. Check pnpm apps:parity for page/content changes. Before Next.js 16 edits, read the relevant installed node_modules/next/dist/docs/ guide rather than relying on old API assumptions.
Reusable Prompt
Goal: implement concrete behavior in src/modules/<feature>.
Inspect AGENTS.md, the owning entry points, and the relevant Skill first.
Define acceptance and write a failing test for new behavior or a bug.
Preserve package/app boundaries and synchronize en/zh mvp.json and page copies.
Manually verify errors, empty states, and permissions, then add minimal unit/API/E2E coverage.
Run relevant checks and report actual results and unverified paths.See Testing and Acceptance and Release Checklist. Fast-moving tool tips/community content does not replace repository rules.