Claude/nextjs spec kit setup pre xu#2620
Closed
Satcomx00-x00 wants to merge 5 commits into
Closed
Conversation
Introduces a presets/nextjs/ preset that specializes Spec-Driven Development for full-stack Next.js web applications. Encodes behaviors (not a tech stack) across Frontend, Backend, Security, Performance, TypeScript & Code Quality, and Infrastructure & Operations. Every directive is tagged with a Phase (P1 Foundation, P2 MVP, P3 Hardening, P4 Scale) and Criticality (Critical, High, Medium, Low) so enforcement scales with the project's maturity. Ships two artifacts: - constitution-template.md: project directive with principles, phase framework, and the full behavior matrix; replaces the core template. - agent-context.md: compressed always-on rules for the AI agent, ready to mirror into AGENTS.md / CLAUDE.md / copilot-instructions.md.
Introduces a sibling to /speckit.constitution that scans the repository for evidence and exports a properly-structured constitution to .specify/memory/constitution.md with a Sync Impact Report mapping findings to every Critical directive. Scanners (bash + PowerShell) walk the repo and emit a JSON inventory: - Markdown files: path, size, head excerpt, and extracted headings. - package.json: name/version, scripts, engines, deps/devdeps counts, framework/tooling/security signals (Next.js, React, TypeScript, validation libs, hash libs, OTel/Sentry, etc.). - tsconfig.json: strict-flag posture (parses JSON-with-comments). - Next.js structure: App vs Pages router, middleware presence, Route Handler count, "use client"/"use server" file counts, and server-only/client-only import counts (both side-effect-only and named-import forms). - Tooling: ESLint, Prettier, Biome, Husky, CI workflow files. - Environment: .env example files, pinned Node version (.nvmrc / .node-version / .tool-versions / package.json engines). - Git metadata, existing constitution detection. Schema is documented in scripts/SCHEMA.md (schema_version: "1.0") as the stable contract between script and command. The command file (commands/speckit.constitution.scan.md) runs the scan, reads relevant .md docs, infers the operating phase (P1-P4) from evidence, fills the Next.js constitution template without rewriting the behavior matrix, and prepends a Sync Impact Report with per-directive status (MET / NOT MET / PARTIAL / UNVERIFIED).
Replaces the prior "TypeScript & Code Quality Behaviors" section with a comprehensive "TypeScript Engineering Behaviors" section. Introduces a third tag — Scope (FE / BE / Both) — that applies specifically to TypeScript directives, since the same code-quality rules can carry different weight or scope on frontend versus backend. New subsections: - Compiler & Project Config — strict flags from day one; tsc errors block CI; @ts-ignore replaced by justified @ts-expect-error. - Type System Discipline — unknown over any; satisfies / as const over casts; discriminated unions; branded IDs; user-defined type predicates; readonly inputs; constrained generics. - SOLID — SRP/OCP for both layers; DIP/DI for backend; ISP/LSP for both; composition over inheritance. - Clean Code & Functional Discipline — pure functions, immutability, Rule of Three, KISS/YAGNI, Law of Demeter, low complexity, early returns, no boolean-param soup, args <=3. - Runtime Boundaries — parse don't validate; schema-validated input at every boundary; env validation at startup; DTOs decoupled from internal models; types generated from the source of truth; Result<T, E> for expected failures. - Frontend Patterns — typed props/events/refs; discriminated-union variants; generic components; no leaked server-only types. - Backend Patterns — server-only marking; typed service signatures; typed domain error unions; exhaustive switches with never; opaque IDs; domain / persistence / API types kept separate. - Project Hygiene & DX — one linter + one formatter on pre-commit and CI; banned circular imports; naming conventions; co-located types; at most one barrel per public boundary; tests on the type contract; tsc performance budgeted; TSDoc on non-obvious types. Updates the operating framework intro to declare the new Scope tag, refreshes agent-context with the expanded discipline (do / don't), and updates the /speckit.constitution.scan compliance mapping so the Sync Impact Report distinguishes Compiler, Type System, and runtime directives instead of one rolled-up TypeScript bucket.
Introduces a behavioral audit that challenges the codebase against the TypeScript and Next.js directives in the constitution. Rule engine (scripts/bash/audit-codebase.sh + powershell mirror): - 23 high-signal rules across six sections (TS, FE, BE, SEC, PERF, INFRA). - TS / Compiler & Project Config: strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes (Critical) plus noImplicitOverride, noFallthroughCasesInSwitch, noImplicitReturns, forceConsistentCasingInFileNames (High). - TS / Type System: any usage, @ts-ignore, unchecked `as` casts (with const/unknown exemption), untyped catch. - BE: DAL modules missing `import 'server-only'`; process.env reads outside the env validator module. - FE: `"use client"` at page/layout/template roots; raw <img> in TSX; raw <a href="/..."> in app routes; pages missing metadata exports. - SEC: localStorage session/token writes; dangerouslySetInnerHTML; NEXT_PUBLIC_*SECRET/TOKEN/KEY/PASSWORD; SQL template literals with ${...} interpolation. - PERF: console.log in production source. - INFRA: CI workflows missing tsc/typecheck step. Each finding carries rule_id, severity, section, phase, scope, directive, remediation, file:line, and a snippet. Designed for big codebases: single file enumeration; parallel grep via xargs -P (bash) and per-file Select-String (PowerShell); --paths / --rules / --sections filters; --max-findings-per-rule cap; --list-rules for catalog introspection; --severity floor. Commands: - /speckit.audit — runs the rule engine, persists JSON under .specify/audits/, produces a human-readable report grouped by severity and section with prioritized actions. - /speckit.audit.deep — same plus four additional layers: tsc --noEmit (treats diagnostics as TS.COMPILER.tsc-diagnostic), eslint (TS.LINT.<rule>), npm audit (SEC.DEPS.cve-<pkg>), and LLM file-level confirmation that reads flagged files in full, marks false positives, correlates cross-file patterns, and inspects every "use server" file for the parse -> authorize -> ownership -> DTO recipe (BE.ACTION.recipe-violation). Schema (scripts/SCHEMA.md, schema_version: 1.0) is the stable contract between the scripts and the commands. Severity maps 1:1 to constitution criticality so audit reports plug into the same waiver and exception model.
…scaffold.dal, /speckit.docs.sync commands
Adds five Next.js-specific workflow commands to the preset:
- /speckit.plan: decomposes a feature into routes, RSC/client boundaries,
Server Actions, DAL methods, schemas, caching strategy, prerendering,
metadata, accessibility, error handling, and a security checklist — all
tagged with Phase and Criticality.
- /speckit.tasks: generates dependency-ordered implementation tasks from a
plan (schema → DAL → actions → route scaffold → RSC → client islands →
route handlers → metadata → skeletons → tests), each with Next.js-idiomatic
titles, acceptance criteria, and constitution directive references.
- /speckit.scaffold.route: scaffolds page.tsx (RSC + generateMetadata),
layout.tsx, loading.tsx (accessible skeleton), error.tsx ("use client"
boundary), not-found.tsx — with --auth, --no-layout, --title flags.
- /speckit.scaffold.dal: scaffolds lib/dal/<entity>.ts with
import 'server-only', typed Result<T> envelope, schema-validated inputs,
CRUD method stubs, and a DTO mapper. Supports --db (prisma/drizzle/kysely/pg),
--methods, --schema, --no-result-envelope.
- /speckit.docs.sync: syncs AGENTS.md / CLAUDE.md /
.github/copilot-instructions.md / GEMINI.md from agent-context.md template.
Conflict detection for custom additions; --dry-run, --force, --targets flags.
Also updates preset.yml (v0.1.0 → v0.2.0) and README.md with a command
reference section and typical workflow.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Testing
uv run specify --helpuv sync && uv run pytestAI Disclosure