70 lines
6.5 KiB
Markdown
70 lines
6.5 KiB
Markdown
|
|
# Spec Kit
|
||
|
|
|
||
|
|
Projects use [Spec Kit](https://github.com/github/spec-kit) for spec-driven development. In Claude Code it installs as the `speckit-*` skills (`specify init` with `--integration claude` puts them in `.claude/skills/`), invoked as `/speckit-*`.
|
||
|
|
|
||
|
|
- Constitution: `.specify/memory/constitution.md`.
|
||
|
|
- Feature artifacts: `specs/<###-feature>/`, holding `spec.md`, `plan.md`, `research.md`, `data-model.md`, `contracts/`, `quickstart.md`, `tasks.md`, and `checklists/`.
|
||
|
|
- The active feature is recorded in `.specify/feature.json`.
|
||
|
|
|
||
|
|
The speckit skills run the process; this skill supplies the front-end architecture inside each artifact. If `.specify/` is missing, suggest initializing Spec Kit before a large feature. For a small change, follow the workflow in SKILL.md and put the plan in the PR description.
|
||
|
|
|
||
|
|
## Constitution (once per repo)
|
||
|
|
|
||
|
|
Propose these principles, adapted to the repo's project type:
|
||
|
|
|
||
|
|
```text
|
||
|
|
/speckit-constitution Front-end principles for this Nx monorepo (<B2C/B2B | admin panel>):
|
||
|
|
1. Structure: follow the front-end-architect skill's project structure. Code lives in src/. Files and folders are kebab-case; component files are PascalCase.
|
||
|
|
2. Layers: features are DDD (entities, repositories, caches on B2C/B2B, actions, models). Actions emit their event when they succeed. Each feature has its own HTTP client in http.ts, extended from the root client, and repositories send requests only through it. Repositories have no client-side dependencies. UI and stores use *Payload types only. No upward or cross-product imports; ESLint boundaries must pass.
|
||
|
|
3. Exports: tree-shakeable named re-exports, never export *. Every module is importable by subpath. B2C/B2B projects expose server-only code through server.ts.
|
||
|
|
4. UX: every screen has loading, empty, error, and in-progress states. Every completed action shows feedback. Every error says how to fix it. All text is translatable. WCAG 2.1 AA.
|
||
|
|
5. Performance: B2C/B2B routes meet p75 LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1 and their JS budgets. Admin screens never flicker, lazy-load routes and heavy widgets, and virtualize long lists.
|
||
|
|
6. Rendering (B2C/B2B): every request renders a fresh page; the Next.js server keeps no cache between requests.
|
||
|
|
7. Access (admin): every page, action, and navigation item declares its permission.
|
||
|
|
8. Testing: every feature ships Playwright specs for the happy path, validation error, and server error, plus inspected screenshots.
|
||
|
|
9. Stack: no dependency outside the agreed stack without an approved justification.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Per feature
|
||
|
|
|
||
|
|
| Step | What you add |
|
||
|
|
|---|---|
|
||
|
|
| `/speckit-specify` | Keep the spec free of technology. Make sure it states who uses the feature and how often, and every state (empty, loading, error, in progress). B2C/B2B: device views, SEO needs, signed-in versus signed-out behavior, expected traffic. Admin: roles and permissions per page and action, the business domains involved, and which actions need help text. |
|
||
|
|
| `/speckit-clarify` | Focus on permissions, error cases, pagination and filters, mobile versus desktop differences, how fresh data must be, and SEO. |
|
||
|
|
| `/speckit-plan` | Pass the project type, stack, and affected projects (template below), then check that `plan.md` contains everything listed under Plan contents. |
|
||
|
|
| `/speckit-checklist` | Focus on "UX states and copy", plus "access levels" (admin) or "performance and SEO" (B2C/B2B). |
|
||
|
|
| `/speckit-tasks` | Check that the tasks follow the Task order below. |
|
||
|
|
| `/speckit-analyze` | Check that plan paths match project-structure.md, that every requirement has its states and tests, that no task breaks a boundary, and that no task uses a pattern from the "Not used here" list in design-patterns.md. |
|
||
|
|
| `/speckit-implement` | Follow SKILL.md and code-patterns.md. Read design-patterns.md before you add a pattern the plan names or a task calls for. When code resists a task, refactor it first, in its own commit (refactoring.md). After each user story, run lint, type-check, and tests for the affected projects. |
|
||
|
|
| `/speckit-converge` | Run the Definition of Done from SKILL.md and the playbook, and repeat implement and converge until it reports Converged. |
|
||
|
|
|
||
|
|
Plan argument template:
|
||
|
|
|
||
|
|
```text
|
||
|
|
/speckit-plan Project type: <B2C/B2B | admin panel>. Stack: Nx, <Next.js App Router | React + TanStack Router>, Tailwind CSS v4 with cva, valibot, react-hook-form, zustand + immer, TanStack Query, i18next, sonner, Playwright. Follow the front-end-architect skill for structure, layers, exports, and budgets. Affected projects: <apps/..., platforms/..., packages/...>.
|
||
|
|
```
|
||
|
|
|
||
|
|
## Plan contents
|
||
|
|
|
||
|
|
- Technical Context: the project type and stack.
|
||
|
|
- Constitution Check: each principle, marked as passing or as a justified violation.
|
||
|
|
- Project Structure: exact paths in this skill's layout, covering routes or screens, templates and organisms, feature layers (entities, repositories, caches on B2C/B2B, actions, page and part models), stores, validations, and the island components to add or extend.
|
||
|
|
- `research.md`: decisions and their trade-offs, such as each route's streamed parts and how each client part gets its server data (B2C/B2B), lazy-loading boundaries and what triggers each deferred part ([rendering-patterns.md](rendering-patterns.md)), each new non-obvious pattern with its signal and the simpler option you rejected ([design-patterns.md](design-patterns.md)), and any new dependency.
|
||
|
|
- `data-model.md`: entities, the `*Args`, `*Dto`, `*ResponseDto`, and `*Payload` types for each endpoint, stores, and query keys.
|
||
|
|
- `contracts/`: each endpoint's method, path, DTOs, error codes, and pagination and filter parameters.
|
||
|
|
- `quickstart.md`: the Playwright scenarios that prove the feature works.
|
||
|
|
- B2C/B2B: the JS budget and web-vitals targets for each route. Admin: the permission matrix of roles against pages and actions.
|
||
|
|
|
||
|
|
## Task order
|
||
|
|
|
||
|
|
1. Setup: Nx projects, tags, subpath exports, and new env variables (the app's env schemas and each project's env type).
|
||
|
|
2. Foundational: entities, repositories with mappers and query keys, caches (B2C/B2B), island components or variants.
|
||
|
|
3. Each user story: actions, then models, then templates and organisms, then the route or screen entry, then its Playwright spec.
|
||
|
|
4. Polish: screenshot inspection at every viewport, accessibility, the bundle and web-vitals check (B2C/B2B), and help content (admin).
|
||
|
|
|
||
|
|
Mark tasks that touch separate files with `[P]` so they can run in parallel.
|
||
|
|
|
||
|
|
## Bugs
|
||
|
|
|
||
|
|
If the repo has Spec Kit's bug extension, run `/speckit-bug-assess`, then `/speckit-bug-fix`, then `/speckit-bug-test`. Fix the fault in the layer that owns it (repository, mapper, action, model, or component) instead of patching the symptom in the UI.
|