@ennamjsc/agents-scaffold 1.1.0

package/templates/_shared/CLAUDE.md.partial.hbs

@@ -0,0 +1,286 @@
+<!-- ennam-agents-scaffold:begin v{{scaffoldVersion}} -->
+## Agents Workflow
+
+@AGENTS.md
+
+### Session Boot Protocol
+
+**Every agent MUST follow this exact sequence at session start.**
+DO NOT read source code, explore directories, or scan the codebase
+until you have completed steps 1-3. Source code is a last resort,
+not a starting point.
+
+1. **Read Serena** — `memories/INDEX.md` → relevant module memories → `comms/active/` → `backlog/`
+2. **Read checkpoint** — `.serena/checkpoint/` for the most recent checkpoint from your role
+3. **Understand the task** — you now have project context. Only NOW assess what source files you need.
+4. **Read ONLY the source files relevant to your task** — targeted reads, not bulk exploration.
+
+```mermaid
+flowchart TD
+    Start([Session Start]) --> S1
+
+    S1["1. Read Serena\nmemories/INDEX.md → modules → comms → backlog"]
+    S1 --> S2["2. Read Checkpoint\n.serena/checkpoint/ (latest for your role)"]
+    S2 --> S3["3. Understand the Task\nAssess what source files you need"]
+    S3 --> S4["4. Read ONLY Relevant Source Files\nTargeted reads, not bulk exploration"]
+
+    S1 -.- warn:::violation
+    warn["⛔ VIOLATION: Scanning src/ or running\nfind / ls -R before completing steps 1-3"]
+
+    classDef violation fill:#fee,stroke:#c00,color:#900,stroke-dasharray: 5 5
+```
+
+**Violations**: Scanning `src/`, or running `find` / `ls -R` at session start before completing steps 1-3 is a protocol violation. It wastes tokens and ignores existing knowledge.
+
+### Superpowers Workflow
+
+Every agent session follows this structured workflow.
+Phases may be skipped for trivial tasks (< 3 steps, single file, obvious fix).
+When skipping, state which phases you're skipping and why.
+
+#### Phase 1 — Understand
+**Skill**: `superpowers:brainstorming`
+**When**: Creating features, modifying behavior, adding functionality.
+**Skip if**: Bug fix with clear reproduction, typo, config change.
+**Output**: Approved design in `docs/superpowers/specs/`
+
+#### Phase 2 — Plan
+**Skill**: `superpowers:writing-plans`
+**When**: Task requires 3+ steps or touches multiple files/services.
+**Skip if**: Single-file change with obvious implementation.
+**Output**: Implementation plan with success criteria per step.
+
+#### Phase 3 — Isolate
+**Skill**: `superpowers:using-git-worktrees`
+**When**: Feature work that should not pollute the working branch.
+**Skip if**: Hotfix, docs-only change, or user requests in-place work.
+**Output**: Isolated worktree or branch ready for implementation.
+
+#### Phase 4 — Implement
+**Skills** (use as needed):
+- `superpowers:test-driven-development` — write tests first, then implementation
+- `superpowers:executing-plans` — execute the plan from Phase 2
+- `superpowers:dispatching-parallel-agents` — 2+ independent tasks
+- `superpowers:subagent-driven-development` — delegate to specialized agents
+- `superpowers:systematic-debugging` — when encountering failures during implementation
+**Output**: Working code with tests.
+
+#### Phase 5 — Verify
+**Skill**: `superpowers:verification-before-completion`
+**When**: ALWAYS. This phase is never skipped.
+**Output**: Evidence that success criteria are met (test output, build output).
+
+#### Phase 6 — Review
+**Skill**: `superpowers:requesting-code-review`
+**When**: Feature work, significant changes, anything touching shared code.
+**Skip if**: Docs-only, config-only, or user explicitly waives review.
+**Output**: Review feedback addressed.
+
+#### Phase 7 — Complete
+**Skill**: `superpowers:finishing-a-development-branch`
+**When**: Implementation verified and reviewed.
+**Output**: PR created, branch merged, or completion option presented to user.
+
+#### Workflow Diagram
+
+```mermaid
+flowchart LR
+    P1["Phase 1\nUnderstand\n<i>brainstorming</i>"]
+    P2["Phase 2\nPlan\n<i>writing-plans</i>"]
+    P3["Phase 3\nIsolate\n<i>git worktrees</i>"]
+    P4["Phase 4\nImplement\n<i>TDD / execute</i>"]
+    P5["Phase 5\nVerify\n<i>verification</i>"]:::mandatory
+    P6["Phase 6\nReview\n<i>code review</i>"]
+    P7["Phase 7\nComplete\n<i>finish branch</i>"]
+
+    P1 -->|"skip?"| P2
+    P2 -->|"skip?"| P3
+    P3 -->|"skip?"| P4
+    P4 --> P5
+    P5 -->|"NEVER SKIP"| P6
+    P6 -->|"skip?"| P7
+
+    classDef mandatory fill:#d4edda,stroke:#155724,stroke-width:3px,color:#155724
+```
+
+#### On-Demand Skills (any phase)
+- `superpowers:systematic-debugging` — when hitting unexpected failures
+- `superpowers:receiving-code-review` — when receiving feedback from others
+- `superpowers:writing-skills` — when creating/modifying workflow skills
+
+### Task Complexity Guide
+
+| Complexity | Example | Required Phases |
+|-----------|---------|-----------------|
+| **Trivial** | Fix typo, update config value | Implement → Verify |
+| **Simple** | Single-file bug fix, add field | Plan → Implement → Verify |
+| **Medium** | New endpoint, new component | Plan → Implement → Verify → Review |
+| **Complex** | New feature across services | ALL phases |
+
+### Knowledge Source Priority
+
+Agents MUST consult existing knowledge before exploring source code.
+
+#### Retrieval order (strict)
+
+```mermaid
+flowchart TD
+    Q["Need context or information?"]
+    Q --> C1{"Exists in\nSerena memories?"}
+    C1 -->|Yes| S1["1. Use Serena\ndecisions/ services/ backlog/"]
+    C1 -->|No| C2{"Need current\nimplementation?"}
+    C2 -->|Yes| S2["2. Source code\ntargeted file reads"]
+    C2 -->|No| C3{"Need history\nor blame?"}
+    C3 -->|Yes| S3["3. Git log / blame"]
+    C3 -->|No| S4["Ask the user"]
+
+    style S1 fill:#d4edda,stroke:#155724,color:#155724
+    style S4 fill:#fff3cd,stroke:#856404,color:#856404
+```
+
+1. **Serena memories** — primary source for decisions, architecture context, conventions, and inter-agent communication
+2. **Source code / git log** — when you need exact current implementation details
+
+#### When to read from Serena
+
+| Moment | Action |
+|--------|--------|
+| Session start | Read `memories/INDEX.md` — understand what's been decided, what's in progress |
+| Before coding a function | Check `services/<module>.md` — check related decisions and conventions |
+| Before making a design decision | Search `decisions/` — check for prior decisions on same topic |
+| When encountering unfamiliar code | Check memories — there may be a decision or discovery explaining it |
+
+#### When to write to Serena
+
+| Moment | Action |
+|--------|--------|
+| After making a design decision | Write to `memories/decisions/<topic>.md` |
+| After discovering something non-obvious | Write to `memories/decisions/<topic>.md` |
+| After completing a task | Update checkpoint + relevant service memory |
+| When identifying work for another agent | Write to `memories/backlog/<service>-<topic>.md` |
+
+### Serena MCP Protocol (canonical — defines *how*; overrides file-path wording below)
+
+**All `.serena/memories/` I/O goes through Serena MCP tools (`mcp__serena__*`). NEVER hand-edit memory files** with Read/Edit/Write — Serena indexes memories and resolves `` `mem:` `` links; hand-editing bypasses both.
+
+**Session start (before reading source):**
+1. `mcp__serena__activate_project` for this repo **by path** → `mcp__serena__initial_instructions` (loads the manual + lists available memories).
+2. `mcp__serena__read_memory`: `INDEX` → relevant `decisions/` / `services/` → `comms/active/` → `backlog/` → latest `checkpoint/`.
+
+**Writing:** `mcp__serena__write_memory(name, content)` — names use `/` topics (`decisions/…`, `services/…`, `backlog/…`, `comms/active/…`, `qa/…`, `checkpoint/…`); link memories as `` `mem:<name>` ``. Use `mcp__serena__edit_memory` for targeted edits and `mcp__serena__delete_memory` when an item is done.
+
+**Checkpoint (end of EVERY session):** `mcp__serena__write_memory("checkpoint/<agent-name>-<YYYY-MM-DD>", …)` → stored at `.serena/memories/checkpoint/<agent-name>-<YYYY-MM-DD>.md`.
+
+> The subsections below (Session Boot / Knowledge Source / Serena Memory Protocol / checkpoint) remain the reference for *what* to read/write and *where things go*; **this block is authoritative for *how*** — always via Serena MCP, checkpoints under `memories/checkpoint/`.
+
+### Mandatory Session Checkpoint
+
+**All AI agents MUST write a checkpoint at the end of every session — via Serena MCP** (`mcp__serena__write_memory`).
+
+**Format**: `mcp__serena__write_memory("checkpoint/<agent-name>-<YYYY-MM-DD>", …)` → stored at `.serena/memories/checkpoint/<agent-name>-<YYYY-MM-DD>.md`. Write through Serena MCP, **never** by hand-editing the file.
+
+**Required content**:
+
+```markdown
+# Checkpoint: <agent-name> — <date>
+
+## What was done
+- <bullet list of completed work>
+
+## Files changed
+- <list of files created/modified/deleted>
+
+## Current state
+- <what is working, what is broken, what is partially done>
+
+## Next steps
+- <what the next session should pick up>
+
+## Blockers / Risks
+- <anything that could block progress>
+```
+
+**Rules**:
+- Write checkpoint BEFORE ending the session — no exceptions
+- If the session was interrupted or failed, still write a checkpoint noting the failure
+- One file per agent per day; append if multiple sessions in the same day
+- Keep each checkpoint concise (under 50 lines)
+- This applies to ALL agents: any subagents, specialized agents, or the main session agent
+
+### Serena Memory Protocol
+
+Serena is the project's knowledge store for decisions, conventions, service state, and inter-agent communication.
+All agents MUST follow these rules when reading/writing to `.serena/memories/`.
+
+#### Read Protocol — Session Start
+
+```mermaid
+flowchart LR
+    R1["INDEX.md"] --> R2["services/\n&lt;module&gt;.md"]
+    R2 --> R3["comms/active/\nmessages for you"]
+    R3 --> R4["backlog/\npending items"]
+    R4 --> Ready(["Ready to work"])
+
+    style Ready fill:#d4edda,stroke:#155724,color:#155724
+```
+
+1. Read `memories/INDEX.md` first
+2. Read `services/<your-module>.md` for current state
+3. Check `comms/active/` for messages addressed to you
+4. Check `backlog/` for pending action items in your domain
+
+#### Write Protocol — What goes where
+
+```mermaid
+flowchart TD
+    W["What do you want to write?"]
+    W --> D{"Technical\ndecision?"}
+    W --> S{"Module\nstate update?"}
+    W --> B{"Work for\nanother agent?"}
+    W --> C{"Question for\nanother agent?"}
+    W --> QA{"QA results?"}
+
+    D -->|Yes| DF["decisions/&lt;topic&gt;.md"]
+    S -->|Yes| SF["services/&lt;module&gt;.md"]
+    B -->|Yes| BF["backlog/&lt;module&gt;-&lt;topic&gt;.md"]
+    C -->|Yes| CF["comms/active/&lt;you&gt;-to-&lt;them&gt;.md"]
+    QA -->|Yes| QAF["qa/latest-results.md"]
+
+    style DF fill:#e8f4fd,stroke:#0366d6
+    style SF fill:#e8f4fd,stroke:#0366d6
+    style BF fill:#fff3cd,stroke:#856404
+    style CF fill:#f0e8fd,stroke:#6f42c1
+    style QAF fill:#e8f4fd,stroke:#0366d6
+```
+
+| You want to... | Write to | Naming |
+|----------------|----------|--------|
+| Record a technical decision | `decisions/<topic>.md` | Descriptive topic name |
+| Update module/service state | `services/<module>.md` | Append or replace section |
+| Flag work for another agent | `backlog/<module>-<topic>.md` | Prefix with target module |
+| Ask another agent a question | `comms/active/<you>-to-<them>-<topic>.md` | |
+| Respond to a question | Append to the existing file in `comms/active/` | |
+| Close a resolved thread | Move both files to `comms/resolved/` | |
+| Report QA results | `qa/latest-results.md` (replace) | Keep only latest |
+| Store something historical | `archive/<category>/` | |
+
+#### Rules
+
+- **Never create new top-level directories** under `memories/`
+- **Never put files directly in `memories/`** — always in a subdirectory
+- **1 file per module** in `services/` — update, don't create siblings
+- **Backlog items**: delete the file when the work is done
+- **Comms**: respond within the SAME file (append), don't create
+  a separate response file. Move to `resolved/` when done.
+- **Decisions**: only for choices that affect future work. Don't store
+  implementation details — those belong in code comments.
+- **Update INDEX.md** when adding new files to `decisions/` or `services/`
+- **QA**: `latest-results.md` is overwritten each run. Archive old
+  results to `archive/qa-runs/<date>.md` before overwriting.
+{{#if profileSection}}
+
+### Profile: {{profile}}
+
+{{{profileSection}}}
+{{/if}}
+<!-- ennam-agents-scaffold:end -->

package/templates/_shared/docs/superpowers/plans/.gitkeep

@@ -0,0 +1 @@
+

package/templates/_shared/docs/superpowers/specs/.gitkeep

@@ -0,0 +1 @@
+

package/templates/flutter/.claude/agents/mobile-dev.md

@@ -0,0 +1,21 @@
+---
+name: mobile-dev
+description: Flutter 3 + Dart specialist — Riverpod/Bloc, dio HTTP, flutter_test. Implements features following AGENTS.md.
+---
+
+You are the mobile developer. Your stack is Flutter 3.x + Dart with sound null safety.
+
+Process:
+1. Run @superpowers:brainstorming if the task is new/creative.
+2. Read existing widget patterns in the touched directory before writing.
+3. Use the project's chosen state lib (Riverpod or Bloc) consistently. Don't introduce a second.
+4. Use dio with interceptors for HTTP; never roll a custom HTTP client.
+5. Add widget keys to test targets; cover with flutter_test (unit) or integration_test (flow).
+6. `flutter analyze` must report zero warnings before declaring done.
+7. Run @superpowers:verification-before-completion.
+8. Write a checkpoint when session ends.
+
+Boundaries:
+- Don't change `pubspec.yaml` dependencies without an explicit task.
+- Don't mix state libraries.
+- Never disable lints to "make it compile".

package/templates/flutter/.mcp.json.partial.hbs

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "figma": {
+      "command": "npx",
+      "args": ["-y", "@ennam/figma-mcp"],
+      "env": { "FIGMA_TOKEN": "${FIGMA_TOKEN}" }
+    }
+  }
+}

package/templates/flutter/CLAUDE.md.partial.hbs

@@ -0,0 +1,26 @@
+## Stack: Flutter 3.x + Dart
+
+| Layer | Tech |
+|---|---|
+| Framework | Flutter 3.x |
+| Language | Dart (sound null safety) |
+| State | Riverpod or Bloc (pick one — don't mix) |
+| HTTP | dio |
+| Testing | flutter_test + integration_test |
+
+### Conventions
+
+- **One state lib per project.** If using Riverpod, never import bloc; vice versa.
+- **dio interceptors** for auth + logging; do not roll a custom HTTP client.
+- **Widget keys** required on stateful test targets so integration_test can find them.
+- **Type-check before declaring done:** `flutter analyze` (zero warnings policy).
+
+### Common commands
+
+```bash
+flutter pub get
+flutter run               # debug on connected device
+flutter test
+flutter build apk         # or appbundle, ios, etc.
+flutter analyze
+```

package/templates/go/.claude/agents/backend-dev-go.md

@@ -0,0 +1,22 @@
+---
+name: backend-dev-go
+description: Go 1.24 specialist — stdlib net/http, pgx, slog. Implements features following AGENTS.md.
+---
+
+You are the backend (Go) developer. Your stack is Go 1.24+ with stdlib-first idioms.
+
+Process:
+1. Run @superpowers:brainstorming if the task is new/creative.
+2. Read existing handlers and packages in the touched directory before writing.
+3. Use stdlib net/http with the new ServeMux pattern (`http.HandleFunc("GET /users/{id}", …)`).
+4. Use pgx for Postgres; never database/sql.
+5. Use log/slog for all logging; never fmt.Println outside tests.
+6. Write/update tests as you go (TDD via @superpowers:test-driven-development).
+7. `go vet ./...` and `go test ./...` must pass before declaring done.
+8. Run @superpowers:verification-before-completion.
+9. Write a checkpoint when session ends.
+
+Boundaries:
+- Don't add a web framework (gin, echo, etc.) — stdlib is enough.
+- Don't panic in handlers; return errors via standard middleware.
+- Don't introduce new logging libraries.

package/templates/go/CLAUDE.md.partial.hbs

@@ -0,0 +1,28 @@
+## Stack: Go 1.24 + stdlib net/http
+
+| Layer | Tech |
+|---|---|
+| Language | Go 1.24+ |
+| HTTP | stdlib `net/http` (ServeMux from 1.22+) |
+| DB | pgx (PostgreSQL) |
+| Migrations | golang-migrate |
+| Logging | stdlib `log/slog` |
+| Testing | stdlib `testing` + `testify/assert` only for assertions |
+
+### Conventions
+
+- **No web frameworks.** stdlib net/http with the new ServeMux is enough.
+- **pgx for Postgres** — never database/sql.
+- **slog** for all logging — never fmt.Println in non-test code.
+- **Errors:** wrap with `fmt.Errorf("doing X: %w", err)`. No panic in handlers.
+- **Type-check before declaring done:** `go vet ./... && go test ./...`.
+
+### Common commands
+
+```bash
+go mod tidy
+go run ./cmd/server
+go test ./...
+go vet ./...
+go build -o bin/server ./cmd/server
+```

package/templates/local-root/CLAUDE.md.partial.hbs

@@ -0,0 +1,50 @@
+## Stack: Orchestration Root (Polyrepo Meta-Root)
+
+| Layer | Tech |
+|---|---|
+| Architecture | Polyrepo orchestrator — no build, no runtime; coordinates sub-platforms |
+| Memory coordination | Serena MCP (reads `.serena/` from each sub-platform) |
+| Sub-platform communication | Published interfaces (HTTP APIs, databases, MCPs) — never shared code |
+| Infrastructure coordination | Docker Compose / Kubernetes / custom (user-defined) |
+
+### The Orchestrator's Job
+
+This root orchestrates multiple independent platforms (sub-repositories or sub-folders). Each platform is autonomous — it has its own `CLAUDE.md`, `AGENTS.md`, `.serena/` memories, build, and deploy.
+
+The orchestrator's role is to:
+1. Read from `.serena/` stores across platforms via Serena MCP (by path-activating each platform)
+2. Collect signals — decisions (`decisions/`), service state (`services/`), comms (`comms/active/`), backlog items (`backlog/`), and checkpoints
+3. Present a cross-platform view — status, risk, dependencies, and work signals
+4. Direct work — write ecosystem-wide decisions to `global/ecosystem/*` (owned by this orchestrator)
+
+**Sub-platform `.serena/` locations the orchestrator reads:**
+
+<!-- TODO: Fill in your platforms. Example: -->
+| Platform folder | `.serena/` path | Purpose |
+|---|---|---|
+| `platform-a/` | `platform-a/.serena/` | (your first platform) |
+| `platform-b/` | `platform-b/.serena/` | (your second platform) |
+| `shared-infra/` | `shared-infra/.serena/` (if applicable) | (shared services) |
+
+(Remove or update this table to match your actual platform structure.)
+
+**Ecosystem (the orchestrator OWNS this):** the orchestrator **writes** Serena **`global/ecosystem/*`** — the shared contract + per-platform plans, the only Serena channel readable by every platform. Read each platform's own store by **path-activating** it; never reach into another platform's source. Keep THIS repo's project store to orchestrator-private items (INDEX + checkpoints).
+
+### Conventions
+
+- **No build at this root.** Each sub-platform builds and runs independently. This folder is pure coordination.
+- **No shared code.** Platforms interact only via published interfaces (HTTP APIs, databases, MCPs), never by importing code.
+- **Decisions in Serena.** Record cross-platform decisions in `.serena/memories/global/ecosystem/` so all platforms can read them.
+- **Respect platform autonomy.** Don't fork or duplicate a platform's logic — consume its published surface (API / MCP / DB).
+
+### Common commands
+
+```bash
+# (Fill in your orchestration commands. Examples:)
+# docker compose up                 # start shared infra
+# cd platform-a && npm run dev      # run platform A
+# cd platform-b && go run ./cmd/... # run platform B
+# kubectl apply -f k8s/             # apply Kubernetes manifests
+```
+
+(Edit this section to document how to start your platforms and shared infrastructure.)

package/templates/next/.claude/agents/web-dev.md

@@ -0,0 +1,23 @@
+---
+name: web-dev
+description: Next.js 16 + React 19 specialist — Server/Client components, TanStack Query, shadcn/ui, Tailwind 4. Implements features following AGENTS.md.
+---
+
+You are the web developer. Your stack is Next.js 16 + React 19 + TypeScript strict.
+
+Process:
+1. Run @superpowers:brainstorming if the task is new/creative.
+2. Read existing code patterns in the touched directory before writing. Match the project's style (Rule 11).
+3. Default to Server Components. Add `'use client'` only when needed.
+4. Use TanStack Query for client-side data fetching; use Server Components for server-side.
+5. Compose shadcn/ui primitives; don't reinvent.
+6. Write/update tests as you go (TDD via @superpowers:test-driven-development).
+7. Type-check with `npm run build` before declaring done.
+8. For interactive changes, verify with Chrome DevTools MCP (a11y, console errors, network).
+9. Run @superpowers:verification-before-completion.
+10. Write a checkpoint when session ends.
+
+Boundaries:
+- Don't touch `next.config.ts` or `eslint.config.mjs` without an explicit task.
+- Don't modify Server Component → Client Component boundary unless asked.
+- Never disable strict TypeScript checks to "make it compile".

package/templates/next/.mcp.json.partial.hbs

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/chrome-devtools-mcp"]
+    },
+    "figma": {
+      "command": "npx",
+      "args": ["-y", "@ennam/figma-mcp"],
+      "env": { "FIGMA_TOKEN": "${FIGMA_TOKEN}" }
+    }
+  }
+}

package/templates/next/CLAUDE.md.partial.hbs

@@ -0,0 +1,35 @@
+## Stack: Next.js 16 + React 19 + TypeScript
+
+| Layer | Tech |
+|---|---|
+| Framework | Next.js 16 (App Router) |
+| UI runtime | React 19 (Server Components by default) |
+| Language | TypeScript strict mode |
+| Data fetching | TanStack Query for client-side; Server Components for server-side |
+| UI primitives | shadcn/ui + Tailwind CSS 4 |
+| Session | iron-session (cookie-based) |
+| Linter | ESLint (next/core-web-vitals) |
+| Build | `npm run build` (Turbopack) |
+
+### Conventions
+
+- **Default to Server Components.** Add `'use client'` only when the component uses state, effects, or browser APIs.
+- **Tailwind 4 syntax.** Avoid `@apply` where utility classes work; lean on theme tokens.
+- **Don't reinvent shadcn primitives.** Compose them; if you need a new one, copy from the shadcn registry rather than write from scratch.
+- **Type-check before declaring done:** `npm run build` (catches type errors that `tsc --noEmit` may miss in App Router).
+- **Use Chrome DevTools MCP** for runtime debugging when changes touch interactivity (a11y, network, console errors, LCP).
+
+### Common commands
+
+```bash
+npm run dev          # local dev server (port 3000)
+npm run build        # production build + type-check
+npm run start        # serve the production build
+npm run lint         # eslint
+```
+
+<!-- BEGIN:nextjs-agent-rules -->
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` before writing any code. Heed deprecation notices.
+<!-- END:nextjs-agent-rules -->

package/templates/python/.claude/agents/backend-dev-python.md

@@ -0,0 +1,21 @@
+---
+name: backend-dev-python
+description: Python 3.12 + FastAPI specialist — uv, Pydantic v2, pytest, ruff. Implements features following AGENTS.md.
+---
+
+You are the backend (Python) developer. Your stack is Python 3.12 + FastAPI with uv package management.
+
+Process:
+1. Run @superpowers:brainstorming if the task is new/creative.
+2. Read existing route handlers and schemas in the touched directory before writing.
+3. Use Pydantic v2 syntax (no v1 patterns like `class Config:`).
+4. Manage deps with `uv add` / `uv remove` — never edit pyproject.toml by hand.
+5. Write/update tests as you go (TDD via @superpowers:test-driven-development).
+6. `uv run ruff check .` and `uv run pytest` must pass before declaring done.
+7. Run @superpowers:verification-before-completion.
+8. Write a checkpoint when session ends.
+
+Boundaries:
+- Don't touch `pyproject.toml` directly — use uv commands.
+- Don't disable ruff rules to "make it lint".
+- Don't mix sync and async route handlers carelessly.

package/templates/python/CLAUDE.md.partial.hbs

@@ -0,0 +1,27 @@
+## Stack: Python 3.12 + FastAPI
+
+| Layer | Tech |
+|---|---|
+| Framework | FastAPI |
+| Package manager | uv |
+| Lint/format | ruff |
+| Testing | pytest |
+| Schemas | Pydantic v2 |
+
+### Conventions
+
+- **uv only.** No `pip install` outside `uv add`. No `requirements.txt` editing by hand.
+- **Pydantic v2 syntax** (`model_config`, `Annotated`, etc.) — not v1.
+- **Type hints required** on public functions; ruff checks this.
+- **Pytest fixtures** in `conftest.py`; one feature per test file.
+- **Type-check before declaring done:** `uv run ruff check . && uv run pytest`.
+
+### Common commands
+
+```bash
+uv sync                     # install deps
+uv run uvicorn app:app      # dev server
+uv run pytest               # tests
+uv run ruff check .         # lint
+uv add <pkg>                # add a dep
+```

package/templates/qa/.claude/agents/qa-tester.md

@@ -0,0 +1,23 @@
+---
+name: qa-tester
+description: QA workflow agent — executes test cases, captures evidence, never edits application code.
+---
+
+You are the QA tester. Your scope is strictly verification; you do NOT modify application code.
+
+Process:
+1. Read `test-cases/README.md` for the suite overview.
+2. Pick cases by priority (P0 first).
+3. For each case:
+   a. Read the case file.
+   b. Set up preconditions.
+   c. Execute steps using Chrome DevTools MCP (or manual instruction to user if non-browser).
+   d. Capture evidence under `evidence/<case-id>/`.
+   e. Record pass/fail in `qa/latest-results.md`.
+4. On failure: `/escalate` to the dev agent responsible; do NOT fix.
+5. Write a checkpoint when session ends.
+
+Boundaries:
+- Never edit files outside `test-cases/`, `evidence/`, `qa/`.
+- Never modify application source.
+- Never declare "all passing" if any case was skipped — surface skips loudly (Rule 12).

package/templates/qa/.claude/commands/qa-report.md

@@ -0,0 +1,13 @@
+---
+description: Summarize the latest QA run from qa/latest-results.md.
+---
+
+Read `qa/latest-results.md` and print a summary:
+
+- Total cases run, by priority (P0/P1/P2)
+- Pass count, fail count, skipped count
+- List of failed case ids with one-line reason
+- Time range (first → last entry timestamp)
+- Action items: which cases need escalation, which need re-run after fix
+
+Do not modify `latest-results.md`. Do not re-execute cases.

package/templates/qa/.claude/commands/qa-run.md

@@ -0,0 +1,13 @@
+---
+description: Execute a single test case from test-cases/ by id.
+---
+
+Usage: `/qa-run <case-id>`
+
+Steps:
+1. Read `test-cases/<case-id>.md`.
+2. Validate preconditions (warn if not met).
+3. Execute each step. For browser-based steps, use Chrome DevTools MCP.
+4. Capture evidence to `evidence/<case-id>/` (timestamped screenshots, console snapshots, network HARs).
+5. Record outcome in `qa/latest-results.md` (append row: id, status, evidence path, notes).
+6. On fail: `/escalate` to the responsible dev agent.

package/templates/qa/.mcp.json.partial.hbs

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "chrome-devtools": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/chrome-devtools-mcp"]
+    }
+  }
+}

package/templates/qa/CLAUDE.md.partial.hbs

@@ -0,0 +1,20 @@
+## Role: QA tester
+
+You verify behavior; you do NOT modify application code.
+
+### Workflow
+
+1. Pick test cases from `test-cases/` (priority order: P0 → P1 → P2).
+2. Execute steps; capture evidence (screenshots, console logs) under `evidence/<case-id>/`.
+3. Record pass/fail in `qa/latest-results.md`.
+4. Surface failures to dev agents via `/escalate` — don't fix them yourself.
+
+### Test case structure
+
+Each `test-cases/<case-id>.md` has: priority, Jira link, target URL/screen, preconditions, steps, expected outcome, pass criteria. Use `TEMPLATE.md` as starting point.
+
+### Common commands
+
+```bash
+# nothing app-specific — use Chrome DevTools MCP for browser inspection
+```

package/templates/qa/evidence/.gitkeep

@@ -0,0 +1 @@
+