create-sdd-project 0.1.1

package/template/.claude/skills/development-workflow/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: development-workflow
+description: "Orchestrates the complete development workflow for each task. Invoke with: 'start task B0.1', 'show sprint progress', 'next task', or 'init sprint N'."
+---
+
+# Development Workflow Skill
+
+## Quick Reference
+
+0. **Spec** — `spec-creator` drafts/updates specs → SPEC APPROVAL (Std/Cplx)
+1. **Setup** — Branch, ticket, sprint tracker → TICKET APPROVAL (Std/Cplx)
+2. **Plan** — Planner agent writes implementation plan → PLAN APPROVAL (Std/Cplx)
+3. **Implement** — Developer agent, TDD, real-time spec sync
+4. **Finalize** — Tests/lint/build, `production-code-validator` → COMMIT APPROVAL
+5. **Review** — PR, `code-review-specialist`, `qa-engineer` (Std/Cplx) → MERGE APPROVAL
+6. **Complete** — Clean up, update tracker
+
+**Step flow:** Simple: 1→3→4→5→6 | Standard: 0→1→2→3→4→5(+QA)→6 | Complex: 0→1(+ADR)→2→3→4→5(+QA)→6
+
+## Commands
+
+- `start task B0.1` — Begin working on a specific task
+- `next task` — Start the next pending task in current sprint
+- `show sprint progress` — View sprint completion status
+- `init sprint N` — Initialize a new sprint tracker
+
+---
+
+## On Skill Start
+
+1. Read the sprint tracker (`docs/project_notes/sprint-X-tracker.md`) → **Active Session** section for context recovery
+2. Read `CLAUDE.md` section 2 → **Autonomy Level**
+3. Read `docs/project_notes/key_facts.md` → **Branching Strategy**
+4. If resuming an active task → continue from the step recorded in the tracker's Active Session
+
+---
+
+## Autonomy & Checkpoints
+
+Read the **Autonomy Level** from `CLAUDE.md` section 2.
+
+| Checkpoint | L1 Full Control | L2 Trusted | L3 Autopilot | L4 Full Auto |
+|------------|:-:|:-:|:-:|:-:|
+| Spec Approval (Step 0) | Required | Auto | Auto | Auto |
+| Ticket Approval (Step 1) | Required | Auto | Auto | Auto |
+| Plan Approval (Step 2) | Required | Required | Auto | Auto |
+| Commit Approval (Step 4) | Required | Auto | Auto | Auto |
+| Merge Approval (Step 5) | Required | Required | Required | Auto |
+
+- **Auto** = proceed without asking; log in sprint tracker → "Auto-Approved Decisions" table
+- **Required** = ask user explicitly; do NOT continue without approval
+- **Quality gates always run** regardless of level (tests, lint, build, validators)
+
+---
+
+## Task Complexity
+
+Ask user to classify complexity before starting. See `references/complexity-guide.md`.
+
+| Tier | Spec | Ticket | Plan | QA |
+|------|:----:|:------:|:----:|:--:|
+| Simple | Skip | Skip | Skip | Skip |
+| Standard | Yes | Yes | Yes | Yes |
+| Complex | Yes | Yes + ADR | Yes | Yes |
+
+---
+
+## Step 0: Spec (Standard/Complex only)
+
+1. Use Task tool with `spec-creator` agent
+2. Agent updates global spec files (`api-spec.yaml`, `ui-components.md`) and Zod schemas in `shared/src/schemas/` if applicable
+3. Agent writes spec summary into the ticket's `## Spec` section
+
+**→ CHECKPOINT: Spec Approval** — Update tracker: step `0/6 (Spec)`
+
+---
+
+## Step 1: Setup
+
+**Determine base branch** from `key_facts.md` → `branching-strategy`:
+- **github-flow** → base from `main`
+- **gitflow** → base from `develop`
+
+See `references/branching-strategy.md` for details.
+
+1. Verify sprint tracker exists, no active task, dependencies met
+2. Create feature branch: `feature/sprint<N>-<task-id>-<short-description>`
+3. **Std/Cplx:** Generate ticket from `references/ticket-template.md` → fill `## Spec` section
+4. **Complex:** Also review `decisions.md` for related ADRs
+5. Update sprint tracker → Active Session: task, step `1/6 (Setup)`, branch, complexity
+
+**→ CHECKPOINT: Ticket Approval** (Std/Cplx only — Simple skips to Step 3)
+
+---
+
+## Step 2: Plan (Standard/Complex only)
+
+1. Use Task tool with planner agent (`backend-planner` for B*.*, `frontend-planner` for F*.*)
+2. Agent writes Implementation Plan into ticket's `## Implementation Plan`
+3. Update tracker: step `2/6 (Plan)`
+
+**→ CHECKPOINT: Plan Approval**
+
+---
+
+## Step 3: Implement
+
+**Simple:** Implement directly with TDD. **Std/Cplx:** Use developer agent (`backend-developer` / `frontend-developer`).
+
+**TDD Cycle:** Failing test → Minimum code to pass → Refactor → Repeat
+
+**Update specs IN REAL TIME (do not wait until Finalize):**
+- API endpoints → `docs/specs/api-spec.yaml` (MANDATORY)
+- DB schema → Zod schemas in `shared/src/schemas/` (MANDATORY)
+- UI components → `docs/specs/ui-components.md` (MANDATORY)
+- Env variables → `.env.example` | ADRs → `decisions.md`
+
+**Spec deviation** → document in sprint tracker Active Session and ask for approval.
+
+Update tracker: step `3/6 (Implement)`, context summary.
+
+---
+
+## Step 4: Finalize
+
+1. Run quality gates: `npm test` → `npm run lint` → `npm run build`
+2. **Std/Cplx:** Run `production-code-validator` via Task tool — **do NOT skip**
+3. Update ticket: mark acceptance criteria `[x]`, Definition of Done `[x]`
+4. Provide change summary: files created/modified, key review points
+
+**→ CHECKPOINT: Commit Approval**
+
+**Commit format:** `<type>(<scope>): <description>` + `Co-Authored-By: Claude <noreply@anthropic.com>`
+
+Update tracker: step `4/6 (Finalize)`
+
+---
+
+## Step 5: Review
+
+**Target branch** from `key_facts.md` → same as base branch (Step 1).
+
+1. Push branch, create PR (use `references/pr-template.md`)
+2. **Std/Cplx:** Run `code-review-specialist` via Task tool — **do NOT skip**
+3. **Std/Cplx:** Also run `qa-engineer` via Task tool
+4. **Merge:** Features/bugfixes → squash; Releases/hotfixes → merge commit
+
+**→ CHECKPOINT: Merge Approval**
+
+Update tracker: step `5/6 (Review)`
+
+---
+
+## Step 6: Complete
+
+1. Delete feature branch (local + remote)
+2. Update sprint tracker: task → Completed, add to Completion Log, update progress %
+3. Record bugs in `bugs.md`, decisions in `decisions.md`
+4. Clear Active Session → "No active work"
+
+---
+
+## Agents
+
+| Agent | Step | Scope |
+|-------|------|-------|
+| `spec-creator` | 0 | Draft/update specs |
+| `backend-planner` / `frontend-planner` | 2 | Implementation plan |
+| `backend-developer` / `frontend-developer` | 3 | TDD implementation |
+| `production-code-validator` | 4 | Pre-commit validation |
+| `code-review-specialist` | 5 | Pre-merge review |
+| `qa-engineer` | 5 | Edge cases, spec verification (Std/Cplx) |
+| `database-architect` | Any | Schema, migrations, queries |
+
+## References
+
+- `references/ticket-template.md` — Ticket format
+- `references/pr-template.md` — PR template
+- `references/branching-strategy.md` — Branching guide
+- `references/sprint-init-template.md` — New sprint initialization
+- `references/complexity-guide.md` — Complexity classification
+- `references/workflow-example.md` — Full worked example
+- `references/failure-handling.md` — Recovery & rollbacks
+
+## Constraints
+
+- **One task at a time** — never start a new task before completing current
+- **TDD mandatory** — all code needs tests
+- **Type safety** — fully typed, no `any`
+- **English only** — all technical artifacts
+- **Memory first** — check `project_notes/` before changes
+- **Sprint tracker** — keep Active Session updated at every step
+- **Correct agents** — Backend → `backend-planner` + `backend-developer`, Frontend → `frontend-planner` + `frontend-developer`
+- **Correct base branch** — check `key_facts.md` before creating branches

package/template/.claude/skills/development-workflow/references/branching-strategy.md

@@ -0,0 +1,59 @@
+# Branching Strategy — Extended Guide
+
+For branch tables and merge strategy, see `base-standards.mdc` § Git Conventions.
+
+## Visual Flows
+
+### GitHub Flow
+
+```
+main ────●────●────●────●────●──── (always deployable)
+          \  /      \  /
+           \/        \/
+        feature/   feature/
+        B1.1       B1.2
+                         tag: v0.1.0
+```
+
+### GitFlow
+
+```
+main ─────●──────────────────●──── (releases only)
+           \                /
+develop ────●──●──●──●──●──●───── (integration)
+             \  /  \  /
+              \/    \/
+           feature  feature
+                     \
+                   release/v1.0
+```
+
+## Decision Guide
+
+| Question | GitHub Flow | GitFlow |
+|----------|:-----------:|:-------:|
+| Solo dev or small team? | Yes | |
+| MVP / early stage? | Yes | |
+| Continuous deployment? | Yes | |
+| Multiple devs in parallel? | | Yes |
+| Formal release cycles? | | Yes |
+| Staging + QA environment? | | Yes |
+
+**Start with GitHub Flow. Switch to GitFlow when you need a `develop` branch.**
+
+## Migrating GitHub Flow → GitFlow
+
+1. Update `key_facts.md`: `branching-strategy: gitflow`
+2. Create develop: `git checkout main && git pull && git checkout -b develop && git push -u origin develop`
+3. Set develop as default branch in GitHub settings
+4. Protect both `main` and `develop`
+5. All new feature branches base from `develop`
+
+## Tag Convention
+
+`vMAJOR.MINOR.PATCH` — Breaking=MAJOR, Feature=MINOR, Fix=PATCH, Pre-release=`-beta.1`
+
+## Branch Protection (Recommended)
+
+- **GitHub Flow** — `main`: require PR, require status checks (tests/lint/build), require 1 approval
+- **GitFlow** — `main`: same + no direct push. `develop`: require PR + status checks

package/template/.claude/skills/development-workflow/references/complexity-guide.md

@@ -0,0 +1,89 @@
+# Task Complexity Guide
+
+## How to Ask About Complexity
+
+Before starting any task, ask the user to classify its complexity using **context-aware options**:
+
+```
+"What complexity level for [TASK-ID] ([Task Name])?"
+
+1. Simple (Recommended if applicable)
+   [Specific description of what "simple" means for THIS task]
+
+2. Standard
+   [Specific description of what "standard" means for THIS task]
+
+3. Complex / Skip / Alternative
+   [Context-aware third option]
+```
+
+## Examples
+
+**Example 1 - Task might be already done:**
+```
+What complexity level for B1.5 (Implement refresh token rotation)?
+
+1. Simple (Recommended)
+   Verify existing implementation in B1.3, add tests if missing
+
+2. Standard
+   Add additional rotation logic or edge cases
+
+3. Skip B1.5
+   Already done in B1.3, move to B1.6 (auth controller)
+```
+
+**Example 2 - Standard new feature:**
+```
+What complexity level for B1.4 (Create auth middleware)?
+
+1. Simple
+   Straightforward middleware, minimal logic
+
+2. Standard (Recommended)
+   JWT verification, role checking, error handling
+
+3. Complex
+   Multiple middleware types, extensive edge cases
+```
+
+## Discussion Option
+
+The user always has the option to **discuss the task** instead of selecting a complexity level:
+
+- Clarifying doubts about what the task involves
+- Discussing if a task should be split or combined
+- Exploring alternative approaches
+- Understanding dependencies better
+
+When presenting complexity options, remind the user they can select "Chat about this" or type a custom response.
+
+## Why Context-Aware Options?
+
+- Helps user understand what each level means **for this specific task**
+- Allows suggesting "Skip" when a task might be redundant
+- Provides recommendations based on task analysis
+- Enables discussion via "Chat about this" option
+
+## Interaction with Autonomy Level
+
+Complexity and Autonomy Level combine to determine the effective workflow overhead:
+
+| Combination | Effect |
+|-------------|--------|
+| Simple + Any Level | Minimal overhead (branch → TDD → commit → PR) |
+| Standard + L1 | Maximum oversight (5 checkpoints) |
+| Standard + L2 | Balanced (Plan + Merge checkpoints only) |
+| Standard + L3-4 | Fast execution, quality gates + QA still enforced |
+| Complex + L1 | Full ceremony (all checkpoints + QA + ADR) |
+| Complex + L3-4 | Fast but with QA engineer + ADR |
+
+**Note:** The user can override the autonomy level per-task. E.g., "use level 1 for this task" forces all checkpoints regardless of the project-level setting.
+
+## Generic Fallback (only if no context available)
+
+```
+- Simple (install library, basic config, copy template)
+- Standard (new endpoint, component, small feature)
+- Complex (complete feature, significant refactor, external integration)
+```

package/template/.claude/skills/development-workflow/references/failure-handling.md

@@ -0,0 +1,174 @@
+# Failure Handling & Rollback Guide
+
+## Types of Failures
+
+| Failure Type | When It Happens | Severity |
+|--------------|-----------------|----------|
+| Test Failure | Tests don't pass | Medium |
+| Validation Failure | production-code-validator finds issues | Medium |
+| Build Failure | Code doesn't compile | High |
+| Dependency Block | Waiting on another task | Low |
+| External Block | Waiting on external resource | Medium |
+| Critical Bug | Discovered during development | High |
+| Scope Creep | Task is bigger than expected | Medium |
+
+---
+
+## Failure Recovery Procedures
+
+### Test Failure
+
+**Recovery:**
+1. **Identify** failing tests
+2. **Analyze** root cause
+3. **Fix** the code (not the test, unless test is wrong)
+4. **Re-run** all tests
+5. **Continue** workflow
+
+**Do NOT:**
+- Skip failing tests
+- Delete tests to make them pass
+- Disable tests temporarily
+
+---
+
+### Validation Failure (production-code-validator)
+
+**Recovery:**
+1. **Review** all issues reported
+2. **Prioritize** by severity (CRITICAL first)
+3. **Fix** each issue
+4. **Re-run** validator
+5. **Continue** only when clean
+
+**Common Fixes:**
+
+| Issue | Fix |
+|-------|-----|
+| console.log | Remove or use proper logger |
+| TODO/FIXME | Complete the task or create new ticket |
+| Hardcoded URL | Use environment variable |
+| Hardcoded secret | Use secrets manager |
+| Empty catch block | Add proper error handling |
+
+---
+
+### Build/Compile Failure
+
+**Recovery:**
+1. **Read** error messages carefully
+2. **Fix** type errors first
+3. **Check** imports and paths
+4. **Rebuild** incrementally
+5. **Run** tests after fix
+
+---
+
+### Dependency Block
+
+**Recovery:**
+1. **Identify** the blocking task/resource
+2. **Document** the block in sprint tracker "Active Task" section
+3. **Options:**
+   - Wait for blocker to resolve
+   - Switch to different task
+   - Create mock/stub to continue
+
+**Update sprint tracker:**
+- Change task status to Blocked
+
+---
+
+### Critical Bug Discovered
+
+**Recovery:**
+1. **Document** the bug immediately
+2. **Assess** impact and priority
+3. **Decide:**
+   - Fix now (if blocking current task)
+   - Create ticket for later (if not blocking)
+4. **If fixing:** Complete fix before continuing task
+
+**Update bugs.md** with the new bug entry.
+
+---
+
+### Scope Creep
+
+**Recovery:**
+1. **Stop** expanding scope
+2. **Document** what was discovered
+3. **Options:**
+   - Complete minimal viable task
+   - Split into multiple tasks
+   - Discuss with team
+
+---
+
+## Rollback Procedures
+
+### When to Rollback
+
+- Breaking changes merged to main
+- Critical bug in production
+- Failed deployment
+- Data corruption
+
+### Git Rollback
+
+**Undo last commit (not pushed):**
+```bash
+git reset --soft HEAD~1  # Keep changes staged
+git reset --hard HEAD~1  # Discard changes
+```
+
+**Revert pushed commit:**
+```bash
+git revert <commit-hash>
+git push
+```
+
+### Database Rollback
+
+<!-- CONFIG: Adjust for your ORM -->
+```bash
+npx prisma migrate reset  # Reset to initial state
+npx prisma migrate deploy # Reapply migrations
+```
+
+---
+
+## Status Codes Reference
+
+| Status | Meaning | Action |
+|--------|---------|--------|
+| In Progress | Normal work | Continue |
+| Paused | Temporarily stopped | Can resume |
+| Blocked | Waiting on dependency | Resolve block |
+| Failed | Critical failure | Rollback/fix |
+| Abandoned | No longer needed | Clean up |
+| Completed | Successfully done | Next task |
+
+---
+
+## Prevention Strategies
+
+### Avoid Test Failures
+- Write tests first (TDD)
+- Run tests frequently
+- Use watch mode during development
+
+### Avoid Validation Failures
+- Use linter during development
+- Check code before commit
+- Follow code standards from start
+
+### Avoid Blocks
+- Check dependencies before starting
+- Communicate with team early
+- Use mocks when possible
+
+### Avoid Scope Creep
+- Understand requirements fully before starting
+- Ask questions early
+- Timebox exploration

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

@@ -0,0 +1,80 @@
+# Pull Request Template
+
+## Target Branch
+
+Read `key_facts.md` → `branching-strategy`:
+- **github-flow** → `--base main`
+- **gitflow** → `--base develop` (features/bugfixes), `--base main` (releases/hotfixes)
+
+## Create PR
+
+```bash
+gh pr create --base main --title "<type>(<scope>): <description>" --body "$(cat <<'EOF'
+## Summary
+
+[One paragraph: what this PR does and why]
+
+## Task Reference
+
+- **Task:** [B0.1] | **Sprint:** [0]
+- **Ticket:** [docs/tickets/task-id.md]
+
+## Changes
+
+- [Change 1]
+- [Change 2]
+
+## Testing
+
+- [x] Unit tests passing
+- [x] Integration tests passing (if applicable)
+- [x] Validated with production-code-validator
+
+## Checklist
+
+- [ ] Code follows project standards
+- [ ] No console.log or debug statements
+- [ ] No hardcoded values
+- [ ] Types are complete (no `any`)
+- [ ] Specs updated (api-spec.yaml / ui-components.md / shared schemas)
+- [ ] Documentation updated (if applicable)
+
+## Related Issues
+
+Closes #issue_number (if applicable)
+
+---
+Generated with Claude Code
+EOF
+)"
+```
+
+## Merge Strategy
+
+| Branch type | Strategy | Command |
+|-------------|----------|---------|
+| Features / Bugfixes | Squash and merge | `gh pr merge --squash` |
+| Releases / Hotfixes | Merge commit | `gh pr merge --merge` |
+
+## After Merge
+
+```bash
+# Delete branch and return to base
+gh pr close --delete-branch
+# github-flow → git checkout main && git pull
+# gitflow → git checkout develop && git pull
+```
+
+## Commit Types
+
+feat, fix, docs, style, refactor, test, chore
+
+## Merge Conflicts
+
+```bash
+git checkout main && git pull
+git checkout <feature-branch>
+git rebase main
+# Resolve conflicts → git add <file> → git rebase --continue
+git push --force-with-lease  # Only on your own feature branches
+```

package/template/.claude/skills/development-workflow/references/sprint-init-template.md

@@ -0,0 +1,82 @@
+# Sprint Initialization Template
+
+Use this template when running `init sprint N`.
+
+## How to Initialize
+
+1. Copy template below to `docs/project_notes/sprint-{N}-tracker.md`
+2. Read the sprint section from your project plan — extract goal, backend tasks (B*.*), frontend tasks (F*.*)
+3. Set dates (start + 2 weeks)
+4. Use `start task B0.1` to begin
+
+---
+
+## Template
+
+```markdown
+# Sprint {N}: {Sprint Title}
+
+**Period:** YYYY-MM-DD to YYYY-MM-DD
+**Goal:** {Sprint goal}
+**Progress:** 0/{total} tasks (0%)
+
+---
+
+## Active Session
+
+> **Read this section first** when starting a new session or after context compaction.
+
+**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 |
+|---|------|--------|-------|
+{backend_tasks}
+
+### Frontend
+
+| # | Task | Status | Notes |
+|---|------|--------|-------|
+{frontend_tasks}
+
+**Status Legend:** ⬚ Pending | 🔄 In Progress | ✅ Complete | ⏸️ Blocked | ❌ Cancelled
+
+---
+
+## Completion Log
+
+| Date | Task | Commit | Notes |
+|------|------|--------|-------|
+
+---
+
+## Sprint Notes
+
+_Key learnings, issues, or observations._
+```