ai-dev-setup 1.0.0

package/src/templates/claude-code/settings.json.tmpl

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Read(**)",
+      "Edit(**)",
+      "Bash(npm:*)",
+      "Bash(npx:*)",
+      "Bash(pnpm:*)",
+      "Bash(yarn:*)",
+      "Bash(node:*)"
+    ]
+  },
+  "meta": {
+    "projectName": "{{PROJECT_NAME}}",
+    "generatedBy": "ai-dev-setup"
+  }
+}

package/src/templates/cursor/cursorrules.tmpl

@@ -0,0 +1,36 @@
+# {{PROJECT_NAME}} — Cursor
+
+## Core stack (required)
+
+| System | Location | Role |
+|--------|----------|------|
+| Superpowers | `vendor/superpowers/`, `.cursor-plugin/plugin.json` | Workflow engine — use bundled skills for planning, TDD, review |
+| Agency Agents | `vendor/agency-agents/`, rules `agency-*.mdc` in `.cursor/rules/` | Specialist agents — select per `.ai/agents.md` |
+
+If `vendor/` or `.cursor-plugin/` is missing, run `npx ai-dev-setup init` without `--skip-vendor`.
+
+## Pointers (do not duplicate)
+
+| File | Purpose |
+|------|---------|
+| `.ai/rules.md` | Coding standards, anti-patterns, doc index |
+| `.ai/workflow.md` | Lifecycle, TDD, review checklist |
+| `.ai/agents.md` | Specialist activation |
+| `docs/*` | Deep references—load only when relevant |
+
+## Project facts
+
+- Language: {{LANGUAGE}} — Framework: {{FRAMEWORK}} — DB: {{DATABASE}}
+- Commands: `{{TEST_CMD}}` · `{{LINT_CMD}}` · `{{BUILD_CMD}}`
+
+## Behavior
+
+- Answer briefly; cite paths instead of pasting large files
+- Prefer existing patterns in-repo over generic tutorials
+- After architectural change, update `docs/ARCHITECTURE.md` in the same change when behavior crosses modules
+
+## Rules layout
+
+- `core-rules.mdc` — always on (keep lean)
+- `workflow.mdc`, `review.mdc`, `agents.mdc` — load when matching the task
+- `agency-*.mdc` — Agency specialist rules (on demand)

package/src/templates/cursor/rules/agents.mdc.tmpl

@@ -0,0 +1,12 @@
+---
+description: Specialist agent usage for {{PROJECT_NAME}} (Agency + .ai/agents.md)
+globs: ""
+alwaysApply: false
+---
+
+# Agents
+
+- Primary source: **Agency Agents** in `vendor/agency-agents/` — project rules under `.cursor/rules/agency-*.mdc`
+- Use `.ai/agents.md` tables to map task → specialist (planning, architecture, implementation, test, perf, review, security, docs)
+- Default: **one** primary agent per task; parallelize only independent workstreams
+- Superpowers (`vendor/superpowers/`) owns workflow phases; Agency owns role-specific execution

package/src/templates/cursor/rules/core-rules.mdc.tmpl

@@ -0,0 +1,14 @@
+---
+description: Core coding constraints for {{PROJECT_NAME}} (token-lean; details in .ai/rules.md)
+globs: "**/*"
+alwaysApply: true
+---
+
+# Core rules
+
+- Read `.ai/rules.md` for full standards; obey stack row for {{LANGUAGE}} / {{FRAMEWORK}}
+- Max **200** lines/file, **50** lines/function; early returns; no commented-out code in commits
+- Run `{{LINT_CMD}}` before hand-off; fix or explain waivers
+- Do not commit secrets or log tokens/PII
+- Touch tests when behavior changes (`{{TEST_CMD}}`) or document the gap
+- Use `docs/CONVENTIONS.md` for stack-specific style; load other `docs/*` only when needed

package/src/templates/cursor/rules/review.mdc.tmpl

@@ -0,0 +1,13 @@
+---
+description: Pre-merge review checklist for {{PROJECT_NAME}}
+globs: ""
+alwaysApply: false
+---
+
+# Review
+
+- Acceptance checks satisfied; no accidental scope creep
+- Lint/test/build scripts clean (`{{LINT_CMD}}`, `{{TEST_CMD}}`, `{{BUILD_CMD}}`)
+- Security: input validation, authz, secrets, injection risks per `docs/SECURITY.md`
+- Docs updated when public behavior or architecture changes
+- Merge risks + rollback noted for risky changes

package/src/templates/cursor/rules/workflow.mdc.tmpl

@@ -0,0 +1,12 @@
+---
+description: Feature workflow and TDD expectations for {{PROJECT_NAME}}
+globs: ""
+alwaysApply: false
+---
+
+# Workflow
+
+- Follow `.ai/workflow.md` phases: understand → design → plan → implement → review → ship
+- TDD when harness exists: red → green → refactor; add minimal harness if missing and user agrees
+- Each plan task lists **path**, **intent**, and **verification** (command or observable outcome)
+- Map errors per `docs/ERROR-HANDLING.md`; API shape per `docs/API-PATTERNS.md` when touching HTTP

package/src/templates/ignore/claudeignore.tmpl

@@ -0,0 +1,25 @@
+# Generated by ai-dev-setup — Claude Code ignore
+node_modules/
+.git/
+dist/
+build/
+coverage/
+*.lock
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+*.map
+.env
+.env.*
+*.log
+__pycache__/
+.venv/
+vendor/superpowers/tests/
+vendor/agency-agents/.git/
+.next/
+.nuxt/
+.output/
+*.min.js
+*.min.css
+.cursor/
+.cursorrules

package/src/templates/ignore/cursorignore.tmpl

@@ -0,0 +1,25 @@
+# Generated by ai-dev-setup — Cursor ignore
+node_modules/
+.git/
+dist/
+build/
+coverage/
+*.lock
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+*.map
+.env
+.env.*
+*.log
+__pycache__/
+.venv/
+vendor/superpowers/tests/
+vendor/agency-agents/.git/
+.next/
+.nuxt/
+.output/
+*.min.js
+*.min.css
+.claude/
+CLAUDE.md

package/src/templates/shared/agents.md.tmpl

@@ -0,0 +1,41 @@
+# Agent activation — {{PROJECT_NAME}}
+
+**Agency Agents** (vendored in `vendor/agency-agents/`) are the default specialist system. **Superpowers** (vendored in `vendor/superpowers/`) is the default workflow engine. Use both together: Superpowers for phase discipline, Agency for role fit.
+
+## Layout
+
+| Piece | Claude Code | Cursor |
+|-------|-------------|--------|
+| Agency | `.claude/agents/*.md` | `.cursor/rules/agency-*.mdc` |
+| Superpowers skills | `.claude/skills/` | `.cursor-plugin` → `vendor/superpowers` |
+
+## Engineering agents
+
+| Task focus | Agent role |
+|------------|------------|
+| Requirements → plan | Product/planning: clarify scope, acceptance, risks |
+| Architecture / structure | System design: boundaries, modules, data flow |
+| Implementation | Feature dev: code changes following `.ai/rules.md` |
+| Tests | QA test: coverage gaps, edge cases, fixtures |
+| Performance | Perf: hot paths, allocations, I/O, caching |
+| Tooling / CI | Platform: scripts, pipelines, developer ergonomics |
+
+## Quality agents
+
+| Task focus | Agent role |
+|------------|------------|
+| Review | Code review: correctness, safety, maintainability |
+| Security review | Threats: authz, input validation, secrets, supply chain |
+| Docs | Technical writing: clarity, examples, diagrams |
+
+## Claude Code
+
+- Invoke slash commands from `.claude/commands/` when they match the phase (`/kickoff`, `/review`, `/ship`)
+- Load Agency agent definitions from `.claude/agents/`; match filename/topic to task
+- Keep long guidance in `docs/`; keep messages short with pointers
+
+## Cursor
+
+- Load `.cursor/rules/workflow.mdc`, `review.mdc`, `agents.mdc` when the task matches
+- Load relevant `agency-*.mdc` when using a named Agency specialist
+- Keep `.cursorrules` as the index; do not duplicate `.ai/rules.md`

package/src/templates/shared/docs/api-patterns.md.tmpl

@@ -0,0 +1,39 @@
+# API patterns — {{PROJECT_NAME}}
+
+## REST shape
+
+| Concern | Rule |
+|---------|------|
+| URLs | Plural nouns; stable versioning (`/v1/...`) |
+| Methods | `GET` safe/idempotent; `POST` create; `PUT`/`PATCH` update; `DELETE` remove |
+| Status | Use correct 2xx/4xx/5xx; avoid 200 with error payloads |
+
+## Request validation
+
+- Reject unknown fields when schema is strict
+- Normalize types at the boundary; domain receives validated models
+
+## Pagination
+
+| Style | When |
+|-------|------|
+| Cursor-based | Large, stable feeds |
+| Offset/limit | Admin tools with small datasets |
+
+Include `next_cursor` or `page`/`page_size` consistently.
+
+## Errors
+
+| Field | Purpose |
+|-------|---------|
+| `code` | Machine-stable identifier |
+| `message` | Human readable, safe for clients |
+| `details` | Optional structured context (no secrets) |
+
+## Idempotency
+
+- Use idempotency keys for `POST` that create billable or side-effectful resources
+
+## Versioning
+
+- Breaking changes: new major version path or explicit deprecation window documented

package/src/templates/shared/docs/architecture.md.tmpl

@@ -0,0 +1,41 @@
+# Architecture — {{PROJECT_NAME}}
+
+## Purpose
+
+Describe what the system does for users and the main runtime boundaries.
+
+## Context diagram
+
+- **Actors**: (users, admins, other services)
+- **External systems**: (payments, email, identity)
+- **This repo**: (apps, packages, workers)
+
+## Logical structure
+
+| Area | Responsibility | Key modules |
+|------|------------------|-------------|
+| UI / API edge | Transport, validation at boundary | _TBD_ |
+| Application | Use cases, orchestration | _TBD_ |
+| Domain | Entities, invariants, policies | _TBD_ |
+| Infrastructure | DB, queues, object storage, 3rd-party SDKs | _TBD_ |
+
+## Data flow
+
+1. Request/event enters at: _TBD_
+2. Authoritative state lives in: _TBD_
+3. Async work is handled by: _TBD_
+
+## Key decisions
+
+| Decision | Why | Tradeoff |
+|----------|-----|----------|
+| _TBD_ | _TBD_ | _TBD_ |
+
+## Non-goals
+
+- _List explicit out-of-scope items to prevent accidental coupling_
+
+## Evolution
+
+- Next likely split: _TBD_
+- Deprecations: _TBD_

package/src/templates/shared/docs/conventions.md.tmpl

@@ -0,0 +1,50 @@
+# Conventions — {{PROJECT_NAME}}
+
+{{#IF_TYPESCRIPT}}
+## TypeScript
+
+- Enable `strict`; avoid `any`; prefer `unknown` + narrowing
+- Explicit return types on exported functions and public class methods
+- Use discriminated unions for variant results instead of loose strings
+- Prefer `import type` for type-only imports
+- Co-locate tests as `*.test.ts` or `__tests__/` per repo standard
+{{/IF_TYPESCRIPT}}
+
+{{#IF_JAVASCRIPT}}
+## JavaScript
+
+- Prefer ES modules; avoid default exports for shared utilities
+- Add JSDoc types where the codebase has not migrated to TypeScript
+- Run the project's formatter and linter before PR
+{{/IF_JAVASCRIPT}}
+
+{{#IF_PYTHON}}
+## Python
+
+- Follow PEP 8; use a formatter (e.g. Ruff) consistently
+- Type hints on public functions; avoid mutable default arguments
+- Prefer `pathlib` over string paths
+- Tests alongside `tests/` layout already in repo
+{{/IF_PYTHON}}
+
+{{#IF_GO}}
+## Go
+
+- Handle `error` values explicitly; wrap with `%w` for traceability
+- Keep `context.Context` on I/O boundaries
+- Prefer small packages; avoid `util` catch-alls
+- Run `go fmt` and `go vet` before PR
+{{/IF_GO}}
+
+{{#IF_FLUTTER}}
+## Flutter / Dart
+
+- Keep widgets small; extract `StatelessWidget` for reusable UI
+- Avoid logic in `build`; use controllers/notifiers per project pattern
+- Prefer immutable models; document serialization boundaries
+{{/IF_FLUTTER}}
+
+## Cross-cutting
+
+- One logical change per commit when possible
+- Update public docs when behavior visible to users changes

package/src/templates/shared/docs/error-handling.md.tmpl

@@ -0,0 +1,32 @@
+# Error handling — {{PROJECT_NAME}}
+
+## Philosophy
+
+- Fail loudly at boundaries; convert to stable user-facing errors at the edge
+- Preserve cause chain for operators; strip internals for clients
+
+## Custom errors
+
+| Field | Use |
+|-------|-----|
+| `name` / `code` | Stable identifier for logs and metrics |
+| `message` | Operator-safe detail |
+| `cause` | Wrapped lower-level error |
+
+## Boundaries
+
+| Layer | Behavior |
+|-------|----------|
+| HTTP/API | Map domain failures to status + error body per `docs/API-PATTERNS.md` |
+| UI | Show actionable copy; log correlation id |
+| Jobs/queues | Retry only transient failures; dead-letter poison messages |
+
+## Logging
+
+- Structured logs: include request/job id, feature, outcome
+- Never log secrets, tokens, full payloads with PII
+
+## Assertions vs errors
+
+- Use assertions for programmer mistakes in dev/test
+- Use typed errors for expected business failures (e.g. not found, conflict)

package/src/templates/shared/docs/security.md.tmpl

@@ -0,0 +1,37 @@
+# Security — {{PROJECT_NAME}}
+
+## Input
+
+- Validate all untrusted input at the boundary with explicit schemas
+- Enforce size limits on payloads and uploads
+
+## AuthN / AuthZ
+
+- Authenticate callers before authorization checks
+- Default deny; document each public route's required role/scope
+- Re-verify authorization on every request—do not trust client-side flags alone
+
+## Secrets
+
+- Load from environment or a secret manager—never commit secrets
+- Rotate credentials with a documented process
+
+## Web (if applicable)
+
+- Set secure cookie flags; prefer HttpOnly for session tokens
+- Encode output contextually to mitigate XSS
+- Use CSRF protections for cookie-based sessions on mutating routes
+
+## Injection
+
+- Parameterize SQL; avoid string-concatenated queries
+- Sanitize or allow-list any dynamic file paths
+
+## Dependencies
+
+- Pin versions; review changelogs for security fixes
+- Run `npm audit` / ecosystem equivalent in CI where practical
+
+## Data
+
+- Minimize PII collection; define retention and deletion expectations

package/src/templates/shared/docs/testing.md.tmpl

@@ -0,0 +1,34 @@
+# Testing strategy — {{PROJECT_NAME}}
+
+## Goals
+
+- Prove behavior the team relies on—not implementation trivia
+- Fail fast in CI on regressions touching covered behavior
+
+## Layout
+
+| Layer | Where | Notes |
+|-------|-------|-------|
+| Unit | Colocated or `tests/unit` | Pure logic, fast |
+| Integration | `tests/integration` | DB, HTTP, queues with test doubles where needed |
+| E2E | `tests/e2e` | Few, high-value user paths |
+
+## Coverage expectations
+
+- New bug fixes include a regression test unless truly impossible—then document why
+- Critical domain rules: aim for direct unit tests on invariants
+
+## Do not test
+
+- Third-party library internals
+- Generated code without business rules
+- Exact log message wording unless contractually required
+
+## Mocking
+
+- Mock I/O boundaries (HTTP, DB client, clock), not domain logic
+- Prefer fakes over deep mocks when behavior matters
+
+## Commands
+
+- Default test entry: `{{TEST_CMD}}`

package/src/templates/shared/rules.md.tmpl

@@ -0,0 +1,65 @@
+# Coding rules — {{PROJECT_NAME}}
+
+## Stack
+
+| Field | Value |
+|-------|-------|
+| Language | {{LANGUAGE}} |
+| Framework | {{FRAMEWORK}} |
+| Database | {{DATABASE}} |
+| Test | `{{TEST_CMD}}` |
+| Lint | `{{LINT_CMD}}` |
+| Build | `{{BUILD_CMD}}` |
+
+## Token efficiency (assistant)
+
+| # | Rule |
+|---|------|
+| 1 | Read only files needed for the current task; prefer ripgrep over opening whole trees |
+| 2 | Summarize long outputs; paste minimal excerpts with path:line |
+| 3 | Do not repeat `.ai/` or `docs/` content in chat—cite paths |
+| 4 | Propose edits in small batches; one concern per patch where possible |
+| 5 | Stop when success criteria are met; avoid scope creep |
+| 6 | Ask one clarifying question only when blocked |
+
+## Style
+
+- Prefer pure functions, early returns, shallow nesting (max 3 levels)
+- Max **200** lines per file; split when exceeded
+- Max **50** lines per function; extract helpers
+- Name booleans `is/has/should`; avoid `data`/`info` without context
+- No commented-out code in commits
+
+## Architecture
+
+- Feature-based folders: `features/<name>/{api,ui,lib,types}`
+- Dependencies point inward: UI → application → domain → infrastructure
+- Keep framework adapters at the edges; core logic framework-agnostic
+
+## Load these docs on demand
+
+| Topic | File |
+|-------|------|
+| System shape | `docs/ARCHITECTURE.md` |
+| Stack conventions | `docs/CONVENTIONS.md` |
+| Tests | `docs/TESTING-STRATEGY.md` |
+| HTTP API | `docs/API-PATTERNS.md` |
+| Errors | `docs/ERROR-HANDLING.md` |
+| Security | `docs/SECURITY.md` |
+
+## Git
+
+- Conventional commits: `type(scope): summary` (types: feat, fix, docs, refactor, test, chore)
+- Branch names: `type/short-description` or `issue-123-short-description`
+- PRs: purpose, risk, test plan, rollback
+
+## Anti-patterns
+
+1. Do not add global mutable singletons for domain state
+2. Do not catch errors without handling or rethrow with context
+3. Do not commit secrets, tokens, or `.env*` contents
+4. Do not skip tests for new behavior unless explicitly out of scope
+5. Do not widen public API surface without a documented need
+6. Do not mix formatting-only changes with functional changes
+7. Do not depend on unspecified order where the domain requires stability
+8. Do not silence linter rules project-wide to land a change

package/src/templates/shared/workflow.md.tmpl

@@ -0,0 +1,42 @@
+# Development workflow — {{PROJECT_NAME}}
+
+## Lifecycle
+
+1. **Understand** — restate goal, constraints, acceptance checks (3–7 bullets)
+2. **Design** — data flow, boundaries, failure modes; link to `docs/ARCHITECTURE.md` updates if structure changes
+3. **Plan** — ordered tasks with file paths and verification per task
+4. **Implement** — smallest vertical slice first; keep diffs reviewable
+5. **Review** — run `{{LINT_CMD}}` and `{{TEST_CMD}}`; fix or document exceptions
+6. **Ship** — conventional commit; PR notes include risk + rollback
+
+## TDD (when tests exist)
+
+- **Red** — write a failing test that encodes the requirement
+- **Green** — minimal code to pass
+- **Refactor** — structure and names; keep tests green
+
+Skip TDD only when user explicitly opts out or project has no harness yet—then add the smallest harness first.
+
+## Planning standards
+
+| Rule | Target |
+|------|--------|
+| Task size | Completable in one focused session |
+| Task description | Verb + object + location (path or module) |
+| Verification | Command or observable outcome per task |
+
+## Review checklist (self)
+
+- [ ] Behavior matches acceptance checks
+- [ ] Errors surfaced with actionable messages
+- [ ] New logic covered by tests or documented gap
+- [ ] No new secrets or sensitive logs
+- [ ] Docs updated when public behavior or architecture changed
+
+## Commands (local)
+
+| Step | Command |
+|------|---------|
+| Lint | `{{LINT_CMD}}` |
+| Test | `{{TEST_CMD}}` |
+| Build | `{{BUILD_CMD}}` |