create-sdd-project 0.1.1

package/template/.claude/skills/development-workflow/references/ticket-template.md

@@ -0,0 +1,71 @@
+# [TASK-ID]: [Task Title]
+
+**Sprint:** [N] | **Type:** [Backend/Frontend]-[Feature/Bugfix/Refactor] | **Priority:** [High/Medium/Low]
+**Status:** In Progress | **Branch:** feature/sprint[N]-[TASK-ID]-[short-description]
+**Created:** [YYYY-MM-DD] | **Dependencies:** [List or "None"]
+
+---
+
+## Spec
+
+### Description
+
+[What needs to be implemented and WHY. Functional requirements and context about the feature/fix and its purpose in the system.]
+
+### API Changes (if applicable)
+
+[Endpoints to add/modify. Reference specific sections in `docs/specs/api-spec.yaml`.]
+
+### Data Model Changes (if applicable)
+
+[Schema changes needed. Update Zod schemas in `shared/src/schemas/` if applicable.]
+
+### UI Changes (if applicable)
+
+[Components to add/modify. Reference `docs/specs/ui-components.md`.]
+
+### Edge Cases & Error Handling
+
+[Known edge cases, error scenarios, and boundary conditions to handle.]
+
+---
+
+## Implementation Plan
+
+_Pending — to be generated by the planner agent in Step 2._
+
+---
+
+## Acceptance Criteria
+
+- [ ] [Criterion 1]
+- [ ] [Criterion 2]
+- [ ] [Criterion 3]
+- [ ] Unit tests for new functionality
+- [ ] All tests pass
+- [ ] Build succeeds
+- [ ] Specs updated (`api-spec.yaml` / `ui-components.md` / shared schemas)
+
+---
+
+## Definition of Done
+
+- [ ] All acceptance criteria met
+- [ ] Unit tests written and passing
+- [ ] E2E tests updated (if applicable)
+- [ ] Code follows project standards
+- [ ] No linting errors
+- [ ] Build succeeds
+- [ ] Specs reflect final implementation
+
+---
+
+## Completion Log
+
+| Date | Action | Notes |
+|------|--------|-------|
+| | | |
+
+---
+
+*Ticket created: [YYYY-MM-DD]*

package/template/.claude/skills/development-workflow/references/workflow-example.md

@@ -0,0 +1,87 @@
+# Workflow Example: Task B0.1 (Simple, L2 Trusted, github-flow)
+
+## On Skill Start
+
+1. Read sprint tracker → Active Session → No active task
+2. `CLAUDE.md` → Autonomy Level 2 (Trusted)
+3. `key_facts.md` → branching: github-flow (base: `main`)
+
+## Step 0: Spec — Skipped (Simple task)
+
+## Step 1: Setup
+
+```bash
+git checkout main && git pull
+git checkout -b feature/sprint0-B0.1-express-setup
+```
+
+Update sprint tracker → Active Session: B0.1, step `1/6`, branch, complexity: Simple.
+
+## Step 2: Plan — Skipped (Simple task)
+
+## Step 3: Implement (TDD)
+
+Update tracker: step `3/6 (Implement)`. Update `api-spec.yaml` in real time (e.g., health endpoint).
+
+**Cycle 1 — Express App:**
+
+```typescript
+// RED: backend/src/app.test.ts
+import app from './app';
+describe('Express App', () => {
+  it('should create an Express application', () => {
+    expect(app).toBeDefined();
+  });
+});
+// npm test → FAIL
+
+// GREEN: backend/src/app.ts
+import express from 'express';
+const app = express();
+export default app;
+// npm test → PASS
+```
+
+**Cycle 2 — Health Endpoint:**
+
+```typescript
+// RED
+describe('GET /health', () => {
+  it('should return 200 with status ok', async () => {
+    const res = await request(app).get('/health');
+    expect(res.status).toBe(200);
+    expect(res.body.status).toBe('ok');
+  });
+});
+
+// GREEN
+app.get('/health', (req, res) => res.json({ status: 'ok' }));
+```
+
+## Step 4: Finalize
+
+Update tracker: step `4/6`. Run validator → fix `console.log` → re-validate → PASS.
+
+L2 auto-approves commit for Simple tasks. Log in tracker.
+
+```bash
+git commit -m "feat(backend): initialize Express + TypeScript project
+..."
+```
+
+## Step 5: Review
+
+```bash
+git push -u origin feature/sprint0-B0.1-express-setup
+gh pr create --base main --title "feat(backend): initialize Express + TypeScript project" --body "..."
+gh pr merge --squash
+```
+
+## Step 6: Complete
+
+```bash
+git checkout main && git pull
+git branch -d feature/sprint0-B0.1-express-setup
+```
+
+Update sprint tracker: B0.1 → Completed, add to Completion Log, clear Active Session.

package/template/.claude/skills/project-memory/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: project-memory
+description: "Set up and maintain a structured project memory system in docs/project_notes/ that tracks bugs with solutions, architectural decisions, key project facts, and work history. Use this skill when asked to 'set up project memory', 'track our decisions', 'log a bug fix', 'update project memory', or 'initialize memory system'."
+---
+
+# Project Memory
+
+## Overview
+
+Maintain institutional knowledge for projects by establishing a structured memory system in `docs/project_notes/`. This skill sets up three key memory files (bugs, decisions, key facts) plus sprint trackers, and configures the main AI instruction file to automatically reference and maintain them.
+
+## When to Use This Skill
+
+Invoke this skill when:
+
+- Starting a new project that will accumulate knowledge over time
+- The project already has recurring bugs or decisions that should be documented
+- The user asks to "set up project memory" or "track our decisions"
+- The user wants to log a bug fix, architectural decision, or completed work
+- Encountering a problem that feels familiar ("didn't we solve this before?")
+- Before proposing an architectural change (check existing decisions first)
+
+## Core Capabilities
+
+### 1. Initial Setup - Create Memory Infrastructure
+
+When invoked for the first time in a project, create the following structure:
+
+```
+docs/
+└── project_notes/
+    ├── bugs.md              # Bug log with solutions
+    ├── decisions.md         # Architectural Decision Records
+    ├── key_facts.md         # Project configuration and constants
+    └── sprint-X-tracker.md  # Sprint progress, active task, completion log
+```
+
+**Initial file content:** Copy templates from the `references/` directory in this skill:
+- Use `references/bugs_template.md` for initial `bugs.md`
+- Use `references/decisions_template.md` for initial `decisions.md`
+- Use `references/key_facts_template.md` for initial `key_facts.md`
+- Sprint tracker is created using the development-workflow skill
+
+### 2. Configure AI Instruction File - Memory-Aware Behavior
+
+Add or update a "Project Memory System" section in the project's main AI instruction file (e.g., `CLAUDE.md`):
+
+```markdown
+## Project Memory System
+
+This project maintains institutional knowledge in `docs/project_notes/`.
+
+### Memory Files
+- **sprint-X-tracker.md** - Sprint progress, active task, completion log
+- **bugs.md** - Bug log with dates, solutions, and prevention notes
+- **decisions.md** - Architectural Decision Records (ADRs)
+- **key_facts.md** - Project configuration, ports, important URLs
+
+### Memory-Aware Protocols
+
+**Before proposing architectural changes:**
+- Check `docs/project_notes/decisions.md` for existing decisions
+
+**When encountering errors or bugs:**
+- Search `docs/project_notes/bugs.md` for similar issues
+
+**When looking up project configuration:**
+- Check `docs/project_notes/key_facts.md`
+
+**When completing work:**
+- Update sprint tracker and add to Completion Log
+```
+
+### 3. Searching Memory Files
+
+When encountering problems or making decisions, proactively search memory files:
+
+- Search `bugs.md` for similar errors
+- Search `decisions.md` for related decisions
+- Search `key_facts.md` for configuration details
+
+### 4. Updating Memory Files
+
+**Adding a bug entry:**
+```markdown
+### YYYY-MM-DD - Brief Bug Description
+- **Issue**: What went wrong
+- **Root Cause**: Why it happened
+- **Solution**: How it was fixed
+- **Prevention**: How to avoid it in the future
+```
+
+**Adding a decision:**
+```markdown
+### ADR-XXX: Decision Title (YYYY-MM-DD)
+
+**Context:**
+- Why the decision was needed
+
+**Decision:**
+- What was chosen
+
+**Alternatives Considered:**
+- Option 1 → Why rejected
+
+**Consequences:**
+- Benefits and trade-offs
+```
+
+**Adding key facts:**
+- Organize by category
+- Use bullet lists for clarity
+- Include both production and development details
+
+### 5. Memory File Maintenance
+
+- User is responsible for manual cleanup
+- Remove very old bug entries (6+ months) that are no longer relevant
+- Archive old sprint trackers
+- Keep all decisions (they provide historical context)
+- Update key_facts.md when project configuration changes
+
+## Templates and References
+
+- **references/bugs_template.md** - Bug entry format with examples
+- **references/decisions_template.md** - ADR format with examples
+- **references/key_facts_template.md** - Key facts organization with examples
+
+Sprint trackers are created using the development-workflow skill.
+
+## Tips for Effective Memory Management
+
+1. **Be proactive**: Check memory files before proposing solutions
+2. **Be concise**: Keep entries brief (1-3 lines for descriptions)
+3. **Be dated**: Always include dates for temporal context
+4. **Be linked**: Include URLs to tickets, docs, dashboards
+5. **Be selective**: Focus on recurring or instructive issues, not every bug
+
+## Integration with Other Skills
+
+- **development-workflow**: Updates sprint tracker and memory files during task execution
+- **bug-workflow**: Documents bugs and solutions in bugs.md
+
+## Success Criteria
+
+This skill is successfully deployed when:
+
+- `docs/project_notes/` directory exists with memory files
+- Sprint tracker exists for active sprint
+- AI instruction file includes "Project Memory System" section
+- Memory files follow template format
+- AI assistant checks memory files before proposing changes

package/template/.claude/skills/project-memory/references/bugs_template.md

@@ -0,0 +1,41 @@
+# Bug Log Template
+
+This file demonstrates the format for logging bugs and their solutions. Keep entries brief and chronological.
+
+## Format
+
+Each bug entry should include:
+- Date (YYYY-MM-DD)
+- Brief description of the bug/issue
+- Solution or fix applied
+- Any prevention notes (optional)
+
+Use bullet lists for simplicity. Older entries can be manually removed when they become irrelevant.
+
+## Example Entries
+
+### 2025-01-15 - Docker Architecture Mismatch
+- **Issue**: Container failing to start with "exec format error"
+- **Root Cause**: Built on ARM64 Mac but deploying to AMD64 server
+- **Solution**: Added `--platform linux/amd64` to docker build command
+- **Prevention**: Always specify platform in Dockerfile and build scripts
+
+### 2025-01-20 - Database Connection Pool Exhaustion
+- **Issue**: API returning 500 errors under load
+- **Root Cause**: Connection pool size too small (default 5)
+- **Solution**: Increased pool size to 20 and max overflow to 10
+- **Prevention**: Load test APIs before production deployment
+
+### 2025-01-22 - CORS Headers Missing
+- **Issue**: Frontend getting CORS errors when calling API
+- **Root Cause**: CORS middleware not configured for frontend origin
+- **Solution**: Added frontend URL to allowed origins list
+- **Prevention**: Always configure CORS when setting up new API endpoints
+
+## Tips
+
+- Keep descriptions under 2-3 lines
+- Focus on what was learned, not exhaustive details
+- Include enough context for future reference
+- Date entries so you know how recent the issue is
+- Periodically clean out very old entries (6+ months)

package/template/.claude/skills/project-memory/references/decisions_template.md

@@ -0,0 +1,67 @@
+# Architectural Decisions Template
+
+This file demonstrates the format for logging architectural decisions (ADRs). Use bullet lists for clarity.
+
+## Format
+
+Each decision should include:
+- Date and ADR number
+- Context (why the decision was needed)
+- Decision (what was chosen)
+- Alternatives considered
+- Consequences (trade-offs, implications)
+
+## Example Entries
+
+### ADR-001: Use PostgreSQL as Primary Database (2025-01-10)
+
+**Context:**
+- Need relational database for structured data
+- Multiple entities with complex relationships
+- Need ACID transactions for order processing
+
+**Decision:**
+- Use PostgreSQL as the primary database
+- Use an ORM for type-safe database access
+
+**Alternatives Considered:**
+- MongoDB → Rejected: relational data model fits better
+- MySQL → Rejected: PostgreSQL has better JSON support and extensibility
+- SQLite → Rejected: not suitable for production multi-user workloads
+
+**Consequences:**
+- Better data integrity with foreign keys and constraints
+- Rich query capabilities including JSON operations
+- Requires managed database service for production
+- Team needs PostgreSQL knowledge
+
+### ADR-002: Use JWT for Authentication (2025-01-12)
+
+**Context:**
+- Need stateless authentication for API
+- Support multiple client types (web, mobile)
+- Want to avoid server-side session storage
+
+**Decision:**
+- Use JWT tokens with short-lived access tokens and refresh token rotation
+- Store tokens securely (httpOnly cookies for web)
+
+**Alternatives Considered:**
+- Session-based auth → Rejected: requires server-side state, harder to scale
+- OAuth2 only → Rejected: overkill for single-app auth, adds complexity
+- API keys → Rejected: not suitable for user-facing authentication
+
+**Consequences:**
+- Stateless: easy to scale horizontally
+- Self-contained: token carries user info
+- Must handle token refresh and rotation
+- Must protect against XSS/CSRF
+
+## Tips
+
+- Number decisions sequentially (ADR-001, ADR-002, etc.)
+- Always include date for context
+- Be honest about trade-offs (use pros and cons)
+- Keep alternatives brief but clear
+- Update decisions if they're revisited/changed
+- Focus on "why" not "how" (implementation details go elsewhere)

package/template/.claude/skills/project-memory/references/key_facts_template.md

@@ -0,0 +1,81 @@
+# Key Facts Template
+
+This file demonstrates the format for storing project constants, configuration, and frequently-needed **non-sensitive** information. Organize by category using bullet lists.
+
+## SECURITY WARNING: What NOT to Store Here
+
+**NEVER store passwords, API keys, or sensitive credentials in this file.** This file is typically committed to version control and should only contain non-sensitive reference information.
+
+**NEVER store:**
+- Passwords or passphrases
+- API keys or authentication tokens
+- Service account JSON keys or credentials
+- Database passwords
+- OAuth client secrets
+- Private keys or certificates
+
+**SAFE to store:**
+- Database hostnames, ports, and cluster names
+- Project identifiers and names
+- API endpoint URLs (public URLs only)
+- Service account email addresses (not the keys!)
+- Cloud project IDs and region names
+- Environment names and deployment targets
+- Local development ports
+
+**Where to store secrets:**
+- `.env` files (excluded via `.gitignore`)
+- Password managers
+- Secrets managers (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault)
+- CI/CD environment variables (GitHub Secrets, GitLab Variables)
+
+## Example Structure
+
+### Project Information
+
+- Project Name: `my-project`
+- Repository: `github.com/org/my-project`
+- Tech Stack: Node.js, Express, PostgreSQL, Next.js
+- Deployment: Vercel (frontend), Render (backend)
+
+### Database Configuration
+
+- Host: `db.example.com`
+- Port: `5432`
+- Database Name: `myproject`
+- Connection: Use connection string from `.env`
+
+### API Configuration
+
+- Production URL: `https://api.myproject.com`
+- Staging URL: `https://api-staging.myproject.com`
+- Local Development: `http://localhost:3010`
+
+### Local Development Ports
+
+- Backend API: `3010`
+- Frontend: `3000`
+- Database: `5432`
+- Redis: `6379`
+
+### Important URLs
+
+- API Documentation: `https://api.myproject.com/docs`
+- CI/CD Pipeline: `https://github.com/org/my-project/actions`
+- Monitoring: `https://dashboard.example.com`
+
+### Team & Access
+
+- GitHub Organization: `my-org`
+- CI/CD: GitHub Actions
+- Hosting: Vercel + Render
+
+## Tips
+
+- Keep entries current (update when things change)
+- Remove deprecated information after migration is complete
+- Include both production and development details
+- Add URLs to make navigation easier
+- Use consistent formatting
+- Group related information together
+- Mark deprecated items clearly with dates

package/template/.env.example

@@ -0,0 +1,17 @@
+# ===========================================
+# Environment Variables Template
+# ===========================================
+# Copy this file to .env and fill in real values.
+# NEVER commit .env to version control.
+
+# Backend
+NODE_ENV=development
+PORT=3010
+DATABASE_URL=postgresql://user:password@localhost:5432/dbname
+
+# Frontend
+NEXT_PUBLIC_API_URL=http://localhost:3010/api
+
+# Authentication (if applicable)
+# JWT_SECRET=your-secret-here
+# JWT_EXPIRES_IN=7d

package/template/.gemini/agents/backend-developer.md

@@ -0,0 +1,31 @@
+# Backend Developer
+
+**Role**: Backend TDD implementation (DDD architecture)
+**When to Use**: Implement backend tasks following the approved plan
+
+## Instructions
+
+Implement the task following the Implementation Plan in the ticket. Use strict TDD (Red-Green-Refactor). Follow DDD layer order: Domain > Application > Infrastructure > Presentation.
+
+## Before Implementing
+
+1. Read ticket (including Spec and Implementation Plan)
+2. Read `ai-specs/specs/backend-standards.mdc`
+3. Read `docs/specs/api-spec.yaml` for current API endpoints and schemas
+4. Read `shared/src/schemas/` (if exists) for current Zod data schemas
+5. Read `docs/project_notes/key_facts.md` and `bugs.md`
+
+## Documentation Updates (MANDATORY — in real time)
+
+- If adding/modifying an endpoint → update `docs/specs/api-spec.yaml` BEFORE continuing
+- If modifying a DB schema → update Zod schemas in `shared/src/schemas/` BEFORE continuing
+- New environment variables → `.env.example`
+
+## Rules
+
+- ALWAYS follow TDD — write tests before implementation
+- ALWAYS follow the Implementation Plan
+- ALWAYS use explicit types (no `any`)
+- ALWAYS handle errors with domain error classes
+- NEVER modify code outside the scope of the current ticket
+- ALWAYS verify implementation matches the approved spec. If deviation needed, document in sprint tracker's Active Session and ask for approval

package/template/.gemini/agents/backend-planner.md

@@ -0,0 +1,34 @@
+# Backend Planner
+
+**Role**: Backend implementation planner (DDD architecture)
+**When to Use**: Before implementing backend tasks — create implementation plan
+
+## Instructions
+
+Generate a detailed Implementation Plan and write it into the ticket's `## Implementation Plan` section. The plan must be detailed enough for the backend-developer to implement autonomously.
+
+## Before Planning
+
+1. Read `docs/project_notes/key_facts.md`
+2. Read the ticket file (including `## Spec` section)
+3. Read `docs/specs/api-spec.yaml` for current API endpoints and schemas
+4. Read `shared/src/schemas/` (if exists) for current Zod data schemas
+5. Explore existing domain entities, services, validators, repositories
+6. Read `ai-specs/specs/backend-standards.mdc`
+
+**Reuse over recreate.** Only propose new code when existing doesn't fit.
+
+## Output Sections
+
+- Existing Code to Reuse
+- Files to Create
+- Files to Modify
+- Implementation Order (Domain > Application > Infrastructure > Presentation > Tests)
+- Testing Strategy
+- Key Patterns
+
+## Rules
+
+- NEVER write implementation code — only the plan
+- ALWAYS check existing code before proposing new files
+- ALWAYS save the plan into the ticket

package/template/.gemini/agents/code-review-specialist.md

@@ -0,0 +1,44 @@
+# Code Review Specialist
+
+**Role**: Senior code reviewer
+**When to Use**: Before merging PRs — thorough code review
+
+## Instructions
+
+**Your focus vs QA Engineer:** You review code quality, patterns, and security. QA Engineer tests edge cases, spec compliance, and regressions.
+
+Perform a multi-layer code review covering:
+- **Correctness**: Logic errors, edge cases, async handling, race conditions
+- **Security**: Input validation, auth checks, injection vulnerabilities, secrets
+- **Code Quality**: DRY, SOLID, naming, complexity, type safety
+- **Performance**: N+1 queries, memory leaks, unnecessary computations
+- **Maintainability**: Readability, test coverage, pattern consistency
+
+## Output Format
+
+```
+## Code Review Summary
+[Overview and assessment]
+
+## Critical Issues
+[Must fix before merging]
+
+## Important Findings
+[Should fix]
+
+## Suggestions
+[Nice-to-have improvements]
+
+## What's Done Well
+[Positive patterns to highlight]
+
+## Final Recommendation
+[Approve / Approve with changes / Request changes]
+```
+
+## Rules
+
+- ALWAYS review against project standards (`backend-standards.mdc` / `frontend-standards.mdc`)
+- ALWAYS check for spec consistency (`api-spec.yaml`, `ui-components.md`)
+- NEVER approve code with CRITICAL issues
+- Be specific (line numbers), constructive, and balanced (praise good patterns)

package/template/.gemini/agents/database-architect.md

@@ -0,0 +1,35 @@
+# Database Architect
+
+**Role**: Database schema designer and query optimizer
+**When to Use**: Schema design, migrations, indexes, query optimization, scaling (invoke manually)
+
+## Instructions
+
+Design and optimize data systems with expertise in both relational (PostgreSQL, MySQL) and NoSQL (MongoDB, Redis) databases.
+
+## Before Designing
+
+1. Read `shared/src/schemas/` (if exists) for current Zod data schemas
+2. Read `docs/specs/api-spec.yaml` to understand data requirements
+3. Read `docs/project_notes/decisions.md` for related ADRs
+
+## Competencies
+
+- **Schema Design**: Normalization, strategic denormalization, constraints
+- **Indexing**: Composite indexes, partial indexes, GIN/GiST/BRIN
+- **Query Optimization**: N+1 detection, JOIN optimization, pagination
+- **Scalability**: Sharding, read replicas, partitioning
+
+## Output
+
+1. Summary of recommendations
+2. Schema/DDL statements
+3. Index definitions with rationale
+4. Migration notes and backward compatibility assessment
+
+## Rules
+
+- Never recommend changes without understanding full context
+- Always consider backward compatibility
+- Warn about data loss scenarios
+- If modifying schema → update Zod schemas in `shared/src/schemas/`