create-sdd-project 0.1.1

package/template/ai-specs/specs/documentation-standards.mdc

@@ -0,0 +1,68 @@
+---
+description: Standards for technical documentation and AI specification files. Covers documentation structure, update processes, language rules, and feedback integration.
+alwaysApply: true
+---
+
+# Documentation Standards
+
+## General Rules
+
+- **ALWAYS WRITE IN ENGLISH**, including comments and explanations. This applies to creating new documentation, updating existing documentation, and inline code comments.
+
+## Technical Documentation
+
+Before making any commit, review which technical documentation should be updated.
+
+### Update Process
+
+1. Review all recent changes in the codebase
+2. Identify which documentation files need updates:
+   - Data model changes → `docs/specs/api-spec.yaml`
+   - API changes → `docs/specs/api-spec.yaml`
+   - Library/migration changes → `ai-specs/specs/*-standards.mdc`
+   - UI component changes → `docs/specs/ui-components.md`
+   - Configuration changes → `docs/project_notes/key_facts.md`
+3. Update each affected documentation file in English
+4. Maintain consistency with existing documentation structure
+5. Verify all changes are accurately reflected
+
+### Documentation Files
+
+| File | Update When |
+|------|-------------|
+| `docs/specs/api-spec.yaml` | API endpoints or schemas change |
+| `docs/specs/ui-components.md` | Component hierarchy or props change |
+| `ai-specs/specs/backend-standards.mdc` | Backend patterns or deps change |
+| `ai-specs/specs/frontend-standards.mdc` | Frontend patterns or deps change |
+| `docs/project_notes/key_facts.md` | Configuration or infrastructure changes |
+| `docs/project_notes/decisions.md` | Architectural decisions are made |
+| `docs/project_notes/bugs.md` | Bugs are found and fixed |
+
+## AI Specifications
+
+AI specs are documents that instruct AI agents how to behave, plan, code, and document.
+
+### Learning from Feedback
+
+The AI should:
+- Learn from user feedback, guidance, and suggestions
+- Identify opportunities to improve existing development rules
+- Keep assistance aligned with evolving project needs
+- Incorporate feedback into the operational framework
+
+### Update Protocol
+
+When user feedback suggests a rule update:
+1. Identify the specific rule or section to modify
+2. Connect the proposed change to the user feedback
+3. Propose the change and wait for explicit approval
+4. Apply the modification only after approval
+5. Confirm the update was made
+
+### Anti-Patterns to Avoid
+
+- **Skipping Approval**: Never apply rule changes without user review
+- **Unlinked Proposals**: Always connect changes to specific feedback
+- **Scope Creep**: Update one rule at a time, matching feedback scope
+- **Unprompted Changes**: Only update rules when driven by feedback
+- **Missing Confirmation**: Always notify after successful updates

package/template/ai-specs/specs/frontend-standards.mdc

@@ -0,0 +1,226 @@
+---
+description: Frontend development standards, best practices, and conventions. Covers component architecture, state management, UI/UX guidelines, and testing practices.
+globs: ["frontend/**/*.{ts,tsx}", "frontend/tsconfig.json", "frontend/jest.config.*", "frontend/package.json"]
+alwaysApply: true
+---
+
+<!-- CONFIG: This file defaults to Next.js/React/Tailwind/Radix UI/Zustand. Adjust for your stack. -->
+
+# Frontend Standards
+
+## Technology Stack
+
+- **Framework**: Next.js (App Router) with React
+- **Language**: TypeScript (strict mode)
+- **Styling**: Tailwind CSS
+- **Components**: Radix UI primitives (shadcn/ui pattern)
+- **State Management**: Zustand (client-side state)
+- **Testing**: Jest + React Testing Library (unit), Playwright (e2e)
+
+## Project Structure
+
+```
+frontend/
+├── app/                   # Next.js App Router pages
+│   ├── layout.tsx         # Root layout
+│   ├── page.tsx           # Home page
+│   └── (routes)/          # Route groups
+├── components/            # UI components
+│   ├── ui/                # Primitive UI components (Button, Input, etc.)
+│   └── (features)/        # Feature-specific components
+├── lib/                   # Utilities and services
+│   ├── api/               # API client and types
+│   └── utils.ts           # General utilities
+├── stores/                # Zustand stores
+├── public/                # Static assets
+└── __tests__/             # Test utilities and fixtures
+```
+
+## Naming Conventions
+
+- **Components**: PascalCase (`UserCard.tsx`, `ProductList.tsx`)
+- **Variables/Functions**: camelCase (`handleSubmit`, `isLoading`)
+- **Constants**: UPPER_SNAKE_CASE (`API_BASE_URL`, `MAX_ITEMS`)
+- **Types/Interfaces**: PascalCase (`UserProps`, `CartItem`)
+- **Hooks**: camelCase with `use` prefix (`useAuth`, `useCartStore`)
+- **CSS classes**: kebab-case via Tailwind utilities
+- **Test files**: `ComponentName.test.tsx`
+
+## Component Conventions
+
+### Functional Components Only
+```typescript
+type UserCardProps = {
+  user: User;
+  onClick: (user: User) => void;
+};
+
+export function UserCard({ user, onClick }: UserCardProps) {
+  return (
+    <div className="rounded-lg border p-4" onClick={() => onClick(user)}>
+      <h3>{user.name}</h3>
+    </div>
+  );
+}
+```
+
+### Client vs. Server Components
+- Default to Server Components (no directive needed)
+- Add `'use client'` only when using hooks, event handlers, or browser APIs
+- Keep client components as small as possible
+
+### Props
+- Define TypeScript types for all props
+- Use destructuring
+- Include default values where appropriate
+
+## State Management
+
+### Zustand Stores
+```typescript
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+type CartStore = {
+  items: CartItem[];
+  addItem: (item: CartItem) => void;
+  removeItem: (id: string) => void;
+};
+
+export const useCartStore = create<CartStore>()(
+  persist(
+    (set) => ({
+      items: [],
+      addItem: (item) => set((s) => ({ items: [...s.items, item] })),
+      removeItem: (id) => set((s) => ({ items: s.items.filter((i) => i.id !== id) })),
+    }),
+    { name: 'cart-storage' }
+  )
+);
+```
+
+### Hydration Pattern
+When using `persist` with `skipHydration: true`, components must call `store.persist.rehydrate()` on mount.
+
+### Loading and Error States
+Always handle all three states for async operations:
+```typescript
+const [data, setData] = useState<Data | null>(null);
+const [isLoading, setIsLoading] = useState(true);
+const [error, setError] = useState<string | null>(null);
+```
+
+## Service Layer
+
+Centralize API calls in service files:
+
+```typescript
+// lib/api/userService.ts
+import { apiClient } from './apiClient';
+
+export const userService = {
+  async list(): Promise<User[]> {
+    const response = await apiClient.get('/users');
+    return response.data;
+  },
+
+  async getById(id: string): Promise<User> {
+    const response = await apiClient.get(`/users/${id}`);
+    return response.data;
+  },
+};
+```
+
+## API Types
+
+<!-- CONFIG: If using shared Zod schemas, import from @project/shared. If using OpenAPI code generation, uncomment the generate:api script below. -->
+
+Import shared types from the `shared/` workspace (see base-standards.mdc § Shared Types):
+
+```typescript
+import { UserSchema } from '@project/shared';
+import type { User } from '@project/shared';
+```
+
+If your project uses OpenAPI code generation instead, configure `npm run generate:api` in `package.json`.
+
+## UI Patterns
+
+### Radix UI Primitives
+Import from the `radix-ui` package (single package, not scoped):
+```typescript
+import { Select as SelectPrimitive } from "radix-ui";
+```
+
+### Form Handling
+- Use controlled components
+- Implement blur validation with touched tracking
+- Disable submit during loading
+- Show clear error messages
+
+### Success Feedback
+For mutating actions that don't redirect:
+```typescript
+const [successMessage, setSuccessMessage] = useState<string | null>(null);
+// After action: set message, auto-dismiss with setTimeout (5s)
+```
+
+### Admin Page Pattern
+Page (state management) → Table component (display) → Dialog (actions)
+
+## Testing Standards
+
+### React Testing Library
+```typescript
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+describe('UserCard', () => {
+  it('should display user name', () => {
+    render(<UserCard user={mockUser} onClick={jest.fn()} />);
+    expect(screen.getByText('John Doe')).toBeInTheDocument();
+  });
+
+  it('should call onClick when clicked', async () => {
+    const user = userEvent.setup();
+    const onClick = jest.fn();
+    render(<UserCard user={mockUser} onClick={onClick} />);
+
+    await user.click(screen.getByText('John Doe'));
+    expect(onClick).toHaveBeenCalledWith(mockUser);
+  });
+});
+```
+
+### Test Patterns
+- Test user interactions, NOT implementation details
+- Mock services and stores at the module level
+- Use `jest.mock()` with **relative paths** (not `@/` aliases)
+- Mock Radix UI portals (Select, Dialog, Sheet) with native HTML in tests
+- Test loading states, error states, and empty states
+- Use test fixtures for consistent mock data
+
+### Test Fixtures
+Create factory functions for test data:
+```typescript
+// testing/fixtures.ts
+export function createUser(overrides?: Partial<User>): User {
+  return { id: '1', name: 'Test User', email: 'test@example.com', ...overrides };
+}
+```
+
+## Performance
+
+- Lazy load components when appropriate
+- Memoize expensive calculations with `useMemo`
+- Use `useCallback` for stable function references
+- Optimize images with Next.js `<Image>` component
+- Code split at route level
+
+## Accessibility
+
+- Include `aria-label` for interactive elements
+- Use semantic HTML elements
+- Ensure keyboard navigation
+- Provide alt text for images
+- Test with screen reader basics

package/template/docs/project_notes/bugs.md

@@ -0,0 +1,18 @@
+# Bug Log
+
+Track bugs with their solutions for future reference. Focus on recurring issues, tricky bugs, and lessons learned.
+
+## Format
+
+```markdown
+### YYYY-MM-DD — Brief Bug Description
+
+- **Issue**: What went wrong (symptoms, error messages)
+- **Root Cause**: Why it happened
+- **Solution**: How it was fixed
+- **Prevention**: How to avoid in future
+```
+
+---
+
+<!-- Add bug entries below this line -->

package/template/docs/project_notes/decisions.md

@@ -0,0 +1,18 @@
+# Architectural Decisions
+
+Track important technical decisions with context, so future sessions understand WHY things are the way they are.
+
+## Format
+
+```markdown
+### ADR-XXX: Decision Title (YYYY-MM-DD)
+
+**Context:** Why the decision was needed
+**Decision:** What was chosen
+**Alternatives Considered:** Options and why rejected
+**Consequences:** Benefits and trade-offs
+```
+
+---
+
+<!-- Add ADR entries below this line -->

package/template/docs/project_notes/key_facts.md

@@ -0,0 +1,52 @@
+# Key Project Facts
+
+Quick reference for project configuration, infrastructure details, and important URLs.
+
+## Security Warning
+
+**DO NOT store in this file:** Passwords, API keys, secret tokens, private keys.
+**SAFE to store:** Hostnames, ports, project IDs, public URLs, architecture notes.
+
+---
+
+## Project Configuration
+
+- **Project Name**: [Your project name]
+- **Repository**: [URL]
+- **Primary Language**: TypeScript
+- **Branching Strategy**: github-flow <!-- Options: github-flow | gitflow — See .claude/skills/development-workflow/references/branching-strategy.md -->
+
+## Technology Stack
+
+- **Backend**: [Framework, runtime, version]
+- **Frontend**: [Framework, version]
+- **Database**: [Type, host, port]
+- **ORM**: [Name, version]
+
+## Local Development
+
+- **Backend Port**: [e.g., 3010]
+- **Frontend Port**: [e.g., 3000]
+- **Database Port**: [e.g., 5432]
+- **API Base URL**: [e.g., http://localhost:3010/api]
+
+## Infrastructure
+
+- **CI/CD**: [e.g., GitHub Actions]
+- **Frontend Hosting**: [e.g., Vercel]
+- **Backend Hosting**: [e.g., Render]
+- **Database Hosting**: [e.g., Neon, Supabase, RDS]
+
+## Important URLs
+
+- **Production**: [URL]
+- **Staging**: [URL]
+- **API Docs**: [URL]
+
+## Reusable Components
+
+### Backend
+- [List key services, middleware, validators as you build them]
+
+### Frontend
+- [List key components, hooks, stores as you build them]

package/template/docs/project_notes/pending-improvements.md

@@ -0,0 +1,50 @@
+# Pending Template Improvements
+
+Documented on 2026-02-23 for future sessions.
+
+---
+
+## P1: Agent Teams Readiness (Impact: HIGH, Effort: MEDIUM)
+
+**What**: Prepare the template to leverage Claude Code's Agent Teams feature (experimental) — a lead agent coordinates multiple teammate agents working in parallel on isolated worktrees.
+
+**Why**: Currently, all work is sequential (one agent at a time). Agent Teams would enable parallel execution of independent tasks (e.g., backend + frontend of the same feature simultaneously).
+
+**What to do**:
+1. **Isolation guide**: Document how to use `git worktree` so each teammate works in an isolated copy
+2. **Parallelism guide**: Add a section to `base-standards.mdc` or a new reference file defining which tasks can safely run in parallel (e.g., backend + frontend of same ticket) vs which must be sequential (e.g., shared types → then backend/frontend)
+3. **Coordination protocol**: Define how the lead agent splits work, assigns to teammates, and merges results
+4. **Skill updates**: Modify `development-workflow/SKILL.md` to support a "parallel mode" for Standard/Complex tasks where Step 4 (Implement) can fork into parallel teammates
+
+**Prerequisites**: Agent Teams must be stable (currently experimental). Test with a real project first.
+
+---
+
+## ~~P2: Quality Gate Hooks~~ — DONE (2026-02-23)
+
+Implemented as:
+- `.claude/settings.json` — Quick scan hook (SubagentStop) + compaction recovery hook (SessionStart)
+- `.claude/hooks/quick-scan.sh` — Fast grep-based scan (no API calls, ~2s)
+- `.claude/settings.local.json` — Notification hooks (permission_prompt, idle_prompt, Stop)
+- Documented in `AGENTS.md` § Automated Hooks
+
+---
+
+## P3: PM Agent + L5 Autonomous (Impact: HIGH, Effort: HIGH)
+
+**What**: Create a `project-manager` agent that can substitute the human in most workflow decisions, enabling a new "L5 Fully Autonomous" level where the AI drives the entire sprint.
+
+**Why**: Currently, autonomy levels top out at L4 (all checkpoints auto-approved). But the human still decides WHAT to build and in what order. A PM agent could read the sprint tracker, prioritize tasks, and orchestrate the full workflow autonomously.
+
+**What to do**:
+1. **Create `pm-agent.md`**: Reads sprint tracker, selects next task, invokes the workflow skill, reviews results, and decides whether to proceed or flag for human review
+2. **Add L5 Autonomous**: New autonomy level where the PM agent drives. Human only reviews at sprint boundaries (sprint planning + sprint review)
+3. **Guard rails**: Define what the PM agent CANNOT do autonomously (e.g., delete data, change architecture, skip tests)
+4. **Sprint planning integration**: PM agent proposes sprint backlog from a product backlog, human approves
+5. **Escalation protocol**: When the PM agent encounters ambiguity or risk, it pauses and asks the human
+
+**Prerequisites**: Template must be battle-tested at L3-L4 first. Agent Teams (P1) would multiply the PM agent's effectiveness.
+
+---
+
+*Delete entries from this file as they are implemented.*

package/template/docs/project_notes/sprint-0-tracker.md

@@ -0,0 +1,66 @@
+# Sprint 0 Tracker
+
+**Period:** [YYYY-MM-DD] to [YYYY-MM-DD]
+**Goal:** Project setup and infrastructure
+**Progress:** 0/0 tasks (0%)
+
+---
+
+## Active Session
+
+> **Read this section first** when starting a new session or after context compaction. Provides instant context recovery.
+
+**Last Updated:** —
+
+| Field | Value |
+|-------|-------|
+| **Current Task** | None |
+| **Step** | — |
+| **Branch** | — |
+| **Complexity** | — |
+| **Ticket** | — |
+
+**Context:** _No active work._
+
+**Next Actions:**
+1. —
+
+**Open Questions:** _None._
+
+**Auto-Approved Decisions (this session):**
+
+| Step | Decision | Rationale |
+|------|----------|-----------|
+| — | — | — |
+
+---
+
+## Tasks
+
+### Backend
+
+| # | Task | Status | Notes |
+|---|------|--------|-------|
+| B0.1 | [Task description] | ⬚ | |
+
+### Frontend
+
+| # | Task | Status | Notes |
+|---|------|--------|-------|
+| F0.1 | [Task description] | ⬚ | |
+
+**Status Legend:** ⬚ Pending | 🔄 In Progress | ✅ Complete | ⏸️ Blocked | ❌ Cancelled
+
+---
+
+## Completion Log
+
+| Date | Task | Commit | Notes |
+|------|------|--------|-------|
+| | | | |
+
+---
+
+## Sprint Notes
+
+- Sprint initialized. Replace tasks above with your actual Sprint 0 backlog.

package/template/docs/specs/api-spec.yaml

@@ -0,0 +1,114 @@
+openapi: 3.0.3
+info:
+  title: Project API
+  description: |
+    API specification for the project.
+    Update this file BEFORE implementing new endpoints.
+  version: 0.1.0
+
+servers:
+  - url: http://localhost:3010/api
+    description: Local development
+
+# CONFIG: Add your API paths below
+
+paths:
+  /health:
+    get:
+      summary: Health check
+      operationId: healthCheck
+      tags:
+        - System
+      responses:
+        '200':
+          description: Service is healthy
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    example: ok
+                  timestamp:
+                    type: string
+                    format: date-time
+
+components:
+  schemas:
+    # CONFIG: Add your schemas below
+
+    ErrorResponse:
+      type: object
+      required:
+        - success
+        - error
+      properties:
+        success:
+          type: boolean
+          example: false
+        error:
+          type: object
+          required:
+            - message
+            - code
+          properties:
+            message:
+              type: string
+            code:
+              type: string
+            details:
+              type: array
+              items:
+                type: object
+
+    SuccessResponse:
+      type: object
+      required:
+        - success
+        - data
+      properties:
+        success:
+          type: boolean
+          example: true
+        data:
+          type: object
+        message:
+          type: string
+
+    PaginatedResponse:
+      type: object
+      required:
+        - success
+        - data
+        - pagination
+      properties:
+        success:
+          type: boolean
+          example: true
+        data:
+          type: array
+          items:
+            type: object
+        pagination:
+          type: object
+          required:
+            - page
+            - pageSize
+            - totalItems
+            - totalPages
+          properties:
+            page:
+              type: integer
+            pageSize:
+              type: integer
+            totalItems:
+              type: integer
+            totalPages:
+              type: integer
+
+  securitySchemes:
+    BearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT

package/template/docs/specs/ui-components.md

@@ -0,0 +1,77 @@
+# UI Component Specification
+
+Define component hierarchies, props, state, and interactions BEFORE implementing.
+
+<!-- CONFIG: Adjust component library references to match your stack -->
+
+## Format
+
+For each component, specify:
+
+```markdown
+### ComponentName
+
+**Type**: Page | Layout | Feature | Primitive
+**Client**: Yes/No (needs 'use client')
+
+**Props:**
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| name | string | Yes | — | User display name |
+
+**State:**
+- `isLoading: boolean` — Loading state for async operations
+- `error: string | null` — Error message
+
+**Interactions:**
+- Click submit → calls `onSubmit(formData)`
+- Form validation → on blur + on submit
+
+**Loading/Error/Empty States:**
+- Loading: Skeleton placeholder
+- Error: Alert with retry button
+- Empty: Message with CTA
+```
+
+---
+
+## Component Hierarchy
+
+<!-- Add your component tree here as you design the UI -->
+
+```
+App
+├── Layout
+│   ├── Header
+│   │   ├── Logo
+│   │   └── Navigation
+│   ├── Main (page content)
+│   └── Footer
+└── Pages
+    └── [Define pages as you plan them]
+```
+
+---
+
+## Shared UI Primitives
+
+List the primitive components available in your project (e.g., from shadcn/ui):
+
+- **Button** — Primary, secondary, outline, ghost variants
+- **Input** — Text input with label and error state
+- **Card** — Container with header, content, footer
+- **Dialog** — Modal overlay
+- **Table** — Data table with sorting and pagination
+- **Select** — Dropdown selection
+- **Badge** — Status indicators
+- **Alert** — Feedback messages (success, error, warning, info)
+
+---
+
+## Pages
+
+<!-- Define each page's component composition as you design them -->
+
+---
+
+*Update this file BEFORE implementing new components or pages.*