@c0x12c/spartan-ai-toolkit 1.0.1

package/commands/spartan/next-app.md

@@ -0,0 +1,317 @@
+---
+name: spartan:next-app
+description: Scaffold a complete new Next.js application from scratch — App Router, TypeScript, Tailwind, testing setup, API client layer, auth scaffolding, and CI config.
+argument-hint: "[app name] [brief description]"
+---
+
+# New Next.js App: {{ args[0] }}
+Description: {{ args[1] }}
+
+Scaffolding a **production-ready** Next.js application. This is more complete than
+`/spartan:next-feature` — use this for a brand-new frontend project.
+
+---
+
+## Step 1: Clarify before building
+
+Ask:
+1. **Auth**: None / NextAuth.js / custom JWT / Clerk / Auth0?
+2. **State management**: Server-only (preferred) / Zustand / React Query for client state?
+3. **Connects to which BE service(s)?** (Kotlin service names/URLs)
+4. **Deploy target**: Railway / Vercel / AWS / Docker+K8s?
+5. **Database** (if any — for full-stack Next.js with Prisma): Yes / No, using separate BE
+
+**Auto mode on?** → Use defaults: No auth, Server-only state, Railway deploy, no DB (separate BE). Proceed immediately.
+**Auto mode off?** → Wait for answers.
+
+---
+
+## Step 2: Bootstrap with create-next-app
+
+```bash
+npx create-next-app@latest {{ args[0] }} \
+  --typescript \
+  --tailwind \
+  --app \
+  --src-dir \
+  --import-alias "@/*" \
+  --no-eslint   # we configure this ourselves
+
+cd {{ args[0] }}
+```
+
+---
+
+## Step 3: Install core dependencies
+
+```bash
+# Testing
+npm install -D vitest @vitejs/plugin-react jsdom
+npm install -D @testing-library/react @testing-library/user-event @testing-library/jest-dom
+
+# API + validation
+npm install zod
+
+# Auth (if NextAuth chosen)
+npm install next-auth@beta    # v5 for App Router
+
+# Dev tooling
+npm install -D eslint-config-next @typescript-eslint/eslint-plugin prettier
+```
+
+---
+
+## Step 4: Configure project structure
+
+```
+src/
+├── app/                        # App Router
+│   ├── (auth)/                 # Route group — auth pages
+│   │   ├── login/page.tsx
+│   │   └── layout.tsx
+│   ├── (dashboard)/            # Route group — protected pages
+│   │   ├── layout.tsx          # ← auth check here
+│   │   └── [feature]/
+│   ├── api/                    # API routes (only when server actions aren't enough)
+│   ├── globals.css
+│   └── layout.tsx              # Root layout
+├── components/
+│   ├── ui/                     # Shared primitives (Button, Input, Card...)
+│   └── [feature]/              # Feature-specific components
+├── lib/
+│   ├── api/                    # BE API client functions
+│   │   ├── client.ts           # Base fetch wrapper
+│   │   └── [service].api.ts    # Per-service functions
+│   ├── auth/                   # Auth utilities
+│   └── utils.ts                # cn(), formatDate(), etc.
+├── hooks/                      # Custom React hooks (client-side)
+├── types/                      # Shared TypeScript types
+│   └── api.types.ts            # Mirror Kotlin DTOs here
+└── middleware.ts               # Auth + route protection
+```
+
+---
+
+## Step 5: Create base API client
+
+```typescript
+// src/lib/api/client.ts
+const BASE_URL = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:8080'
+
+type ApiError = {
+  message: string
+  code: string
+  status: number
+}
+
+export class ApiClient {
+  private static async request<T>(
+    path: string,
+    options?: RequestInit & { tags?: string[] }
+  ): Promise<T> {
+    const res = await fetch(`${BASE_URL}${path}`, {
+      ...options,
+      headers: {
+        'Content-Type': 'application/json',
+        ...options?.headers,
+      },
+      next: options?.tags ? { tags: options.tags } : undefined,
+    })
+
+    if (!res.ok) {
+      const error: ApiError = await res.json().catch(() => ({
+        message: 'Unknown error',
+        code: 'UNKNOWN',
+        status: res.status,
+      }))
+      throw new Error(error.message)
+    }
+
+    return res.json()
+  }
+
+  static get<T>(path: string, tags?: string[]) {
+    return this.request<T>(path, { tags })
+  }
+
+  static post<T>(path: string, body: unknown) {
+    return this.request<T>(path, {
+      method: 'POST',
+      body: JSON.stringify(body),
+    })
+  }
+
+  static put<T>(path: string, body: unknown) {
+    return this.request<T>(path, {
+      method: 'PUT',
+      body: JSON.stringify(body),
+    })
+  }
+
+  static delete<T>(path: string) {
+    return this.request<T>(path, { method: 'DELETE' })
+  }
+}
+```
+
+---
+
+## Step 6: Configure Vitest
+
+```typescript
+// vitest.config.ts
+import { defineConfig } from 'vitest/config'
+import react from '@vitejs/plugin-react'
+import path from 'path'
+
+export default defineConfig({
+  plugins: [react()],
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['./src/test/setup.ts'],
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+    },
+  },
+})
+```
+
+```typescript
+// src/test/setup.ts
+import '@testing-library/jest-dom'
+import { vi } from 'vitest'
+
+// Mock Next.js navigation
+vi.mock('next/navigation', () => ({
+  useRouter: () => ({ push: vi.fn(), replace: vi.fn(), back: vi.fn() }),
+  usePathname: () => '/',
+  useSearchParams: () => new URLSearchParams(),
+}))
+```
+
+Add to `package.json`:
+```json
+{
+  "scripts": {
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage"
+  }
+}
+```
+
+---
+
+## Step 7: Environment variables
+
+Create `.env.local`:
+```bash
+NEXT_PUBLIC_API_URL=http://localhost:8080
+# NEXTAUTH_URL=http://localhost:3000
+# NEXTAUTH_SECRET=   # generate: openssl rand -base64 32
+```
+
+Create `.env.example` (commit this):
+```bash
+NEXT_PUBLIC_API_URL=http://localhost:8080
+# NEXTAUTH_URL=https://your-domain.com
+# NEXTAUTH_SECRET=your-secret-here
+```
+
+---
+
+## Step 8: Deploy configuration
+
+**Railway** (`railway.toml`):
+```toml
+[build]
+builder = "nixpacks"
+
+[deploy]
+startCommand = "npm start"
+healthcheckPath = "/api/health"
+healthcheckTimeout = 30
+```
+
+Create `src/app/api/health/route.ts`:
+```typescript
+export function GET() {
+  return Response.json({ status: 'ok', timestamp: new Date().toISOString() })
+}
+```
+
+**Docker** (`Dockerfile`):
+```dockerfile
+FROM node:20-alpine AS deps
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+
+FROM node:20-alpine AS builder
+WORKDIR /app
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+ENV NODE_ENV=production
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+EXPOSE 3000
+CMD ["node", "server.js"]
+```
+
+Add to `next.config.ts`: `output: 'standalone'`
+
+---
+
+## Step 9: First test — smoke test
+
+```typescript
+// src/app/page.test.tsx
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect } from 'vitest'
+import Home from './page'
+
+describe('Home page', () => {
+  it('renders without crashing', () => {
+    render(<Home />)
+    expect(document.body).toBeDefined()
+  })
+})
+```
+
+Run: `npm test` — must be green before moving on.
+
+---
+
+## Step 10: GitHub Actions CI
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run test:run
+      - run: npm run build
+```
+
+After scaffolding complete:
+"✅ App scaffolded. Run `npm run dev` to start. First test is green.
+Use `/spartan:next-feature [name]` to build individual features."

package/commands/spartan/next-feature.md

@@ -0,0 +1,197 @@
+---
+name: spartan:next-feature
+description: Scaffold a new Next.js feature following App Router conventions — pages, components, server actions, types, and tests.
+argument-hint: "[feature name] [brief description]"
+---
+
+# Next.js Feature: {{ args[0] }}
+Description: {{ args[1] }}
+
+You are scaffolding a new Next.js feature following **App Router** conventions for the Spartan frontend.
+
+---
+
+## Step 1: Clarify before building
+
+Ask the user:
+1. Is this a **page** (new route), a **component** (reusable UI), or a **feature** (page + components + logic)?
+2. Does it need **data fetching** from the Kotlin BE? If yes, which API endpoints?
+3. Is any part **interactive** (needs `'use client'`)? What interactions?
+4. Any **auth/access control** requirements?
+
+**Auto mode on?** → Infer answers from the feature name and codebase context. Assume "feature" type, check existing API patterns, proceed immediately.
+**Auto mode off?** → Wait for answers, then proceed.
+
+---
+
+## Step 2: Map the directory structure
+
+Based on answers, propose this structure under `app/` or `components/`:
+
+```
+# For a new PAGE feature:
+app/[feature-name]/
+  page.tsx              ← Server Component (data fetching here)
+  page.test.tsx         ← Tests
+  layout.tsx            ← Only if needs own layout
+  loading.tsx           ← Loading UI (Suspense boundary)
+  error.tsx             ← Error boundary
+  _components/          ← Feature-local components
+    FeatureCard.tsx
+    FeatureCard.test.tsx
+  _actions/             ← Server Actions for mutations
+    createFeature.ts
+    updateFeature.ts
+  _types/               ← TypeScript types
+    feature.types.ts
+
+# For a reusable COMPONENT:
+components/[ComponentName]/
+  [ComponentName].tsx
+  [ComponentName].test.tsx
+  [ComponentName].stories.tsx   ← If using Storybook
+  index.ts                      ← Re-export
+```
+
+---
+
+## Step 3: Create types first
+
+In `_types/feature.types.ts`:
+
+```typescript
+// Mirror the Kotlin DTO structure from BE
+export interface FeatureDto {
+  id: string
+  // ... fields from BE response
+  createdAt: string // ISO string from BE
+}
+
+// For API responses — always typed
+export interface ApiResponse<T> {
+  data: T
+  message?: string
+}
+
+// For form/mutation input
+export interface CreateFeatureInput {
+  // ...
+}
+```
+
+---
+
+## Step 4: Create API client
+
+```typescript
+// lib/api/feature.api.ts
+
+import { FeatureDto, CreateFeatureInput } from '@/app/[feature]/_types/feature.types'
+
+export async function getFeature(id: string): Promise<FeatureDto> {
+  const res = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/v1/features/${id}`, {
+    next: { revalidate: 60 }, // ISR: revalidate every 60s
+  })
+  
+  if (!res.ok) {
+    throw new Error(`Failed to fetch feature: ${res.status}`)
+  }
+  
+  return res.json()
+}
+
+export async function createFeature(input: CreateFeatureInput): Promise<FeatureDto> {
+  const res = await fetch(`${process.env.NEXT_PUBLIC_API_URL}/api/v1/features`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(input),
+  })
+  
+  if (!res.ok) {
+    const error = await res.json()
+    throw new Error(error.message || 'Failed to create feature')
+  }
+  
+  return res.json()
+}
+```
+
+---
+
+## Step 5: Create Server Component page
+
+```typescript
+// app/[feature-name]/page.tsx
+import { getFeature } from '@/lib/api/feature.api'
+import { FeatureCard } from './_components/FeatureCard'
+
+// Metadata for SEO
+export const metadata = {
+  title: '[Feature Name] | Spartan',
+}
+
+interface PageProps {
+  params: { id: string }
+  searchParams: { [key: string]: string | undefined }
+}
+
+export default async function FeaturePage({ params }: PageProps) {
+  // Data fetching directly in Server Component
+  const feature = await getFeature(params.id)
+  
+  return (
+    <main>
+      <FeatureCard feature={feature} />
+    </main>
+  )
+}
+```
+
+---
+
+## Step 6: Write tests FIRST (TDD)
+
+```typescript
+// page.test.tsx — Server Component test
+import { render, screen } from '@testing-library/react'
+import { describe, it, expect, vi } from 'vitest'
+import FeaturePage from './page'
+
+// Mock the API call
+vi.mock('@/lib/api/feature.api', () => ({
+  getFeature: vi.fn()
+}))
+
+describe('FeaturePage', () => {
+  it('renders feature data when loaded', async () => {
+    // given
+    const mockFeature = { id: '1', name: 'Test Feature' }
+    vi.mocked(getFeature).mockResolvedValue(mockFeature)
+    
+    // when
+    const page = await FeaturePage({ params: { id: '1' }, searchParams: {} })
+    render(page)
+    
+    // then
+    expect(screen.getByText('Test Feature')).toBeInTheDocument()
+  })
+})
+```
+
+---
+
+## Step 7: Environment variables check
+
+Ensure these are set in `.env.local` (and in Railway env vars):
+```
+NEXT_PUBLIC_API_URL=http://localhost:8080   # local
+# Railway: set to production BE service URL
+```
+
+After scaffolding, run:
+```bash
+npm run dev
+npm test -- --watch [feature-name]
+```
+
+Say: "Feature scaffolded. First failing test written. Say **'go'** to implement."

package/commands/spartan/outreach.md

@@ -0,0 +1,16 @@
+---
+name: spartan:outreach
+description: Draft personalized investor outreach emails — cold, warm intro, and follow-up
+argument-hint: "[investor name or context]"
+---
+
+# Outreach: {{ args[0] | default: "investor email" }}
+
+Draft investor communication.
+
+## Steps
+
+1. Use the `investor-outreach` skill
+2. If investor name is given, search for their thesis, portfolio, recent activity
+3. Personalize the email based on real data
+4. If no investor info is available, create a template and flag what needs personalizing

package/commands/spartan/phase.md

@@ -0,0 +1,119 @@
+---
+name: spartan:phase
+description: Manage project phases — discuss requirements, plan tasks, execute work, verify results. This is the Spartan wrapper for GSD phase commands. Use after /spartan:project new.
+argument-hint: "[discuss | plan | execute | verify] [phase number]"
+---
+
+# Phase {{ args[1] | default: "?" }}: {{ args[0] | default: "discuss" }}
+
+You are managing a phase in the current GSD project.
+The user does NOT need to know about `/gsd:*` commands — everything runs through `/spartan:*`.
+
+---
+
+{% if args[0] == "discuss" %}
+## Discuss Phase {{ args[1] | default: "N" }}
+
+Gathering requirements for this phase. But first — Office Hours.
+
+**MANDATORY: Ask these 3 forcing questions BEFORE gathering requirements:**
+
+1. **"What pain are we actually solving?"** (not the feature — the underlying pain)
+2. **"What's the narrowest version we can ship to learn?"** (force MVP thinking)
+3. **"What assumption are we making that could be wrong?"** (surface hidden risks)
+
+**Auto mode on?** → Still ask these 3 questions. They prevent building the wrong thing.
+
+Only after the user answers all 3 → proceed:
+
+**Run:** `/gsd:discuss-phase {{ args[1] | default: "N" }}`
+
+After discussion, decompose requirements into work units (WUs) per GSD v5:
+- Each WU: max 3 files, max half-day, one commit
+- Group into waves by dependency
+
+Then tell the user:
+"Requirements gathered and decomposed into [N] work units across [N] waves. Next step: `/spartan:phase plan {{ args[1] | default: "N" }}`"
+
+{% elif args[0] == "plan" %}
+## Plan Phase {{ args[1] | default: "N" }}
+
+Generating the execution plan with wave-parallel tasks.
+
+**Before planning, check `.memory/index.md`** for relevant patterns, decisions, and knowledge from previous phases.
+
+**Run:** `/gsd:plan-phase {{ args[1] | default: "N" }}`
+
+The plan should include:
+- Work units grouped into waves
+- Wave 1 = independent tasks (can run in parallel tabs)
+- Wave 2+ = depends on previous wave
+- Each task has: files to touch, test to write first, commit message
+
+Then tell the user:
+"Plan ready with [N] waves. Next step: `/spartan:phase execute {{ args[1] | default: "N" }}`"
+
+If the user has multiple Claude Code tabs available, suggest:
+"Wave 1 has [N] independent tasks — you can run them in parallel tabs for speed."
+
+{% elif args[0] == "execute" %}
+## Execute Phase {{ args[1] | default: "N" }}
+
+Running the planned tasks wave by wave.
+
+**Run:** `/gsd:execute-phase {{ args[1] | default: "N" }}`
+
+During execution:
+- Follow TDD: test first → implement → verify
+- Respect safety guardrails if active (careful/freeze/guard)
+- After each wave, verify all tests pass before starting next wave
+- Capture new knowledge to `.memory/` as you go
+
+After execution, tell the user:
+"Phase {{ args[1] | default: "N" }} executed. [N] commits made. Next step: `/spartan:phase verify {{ args[1] | default: "N" }}`"
+
+{% elif args[0] == "verify" %}
+## Verify Phase {{ args[1] | default: "N" }}
+
+Running acceptance criteria checks and UAT.
+
+**Run:** `/gsd:verify-work {{ args[1] | default: "N" }}`
+
+After verification:
+1. Check all acceptance criteria from the discuss phase
+2. Run full test suite
+3. Extract decisions made → `.memory/decisions/`
+4. Extract patterns discovered → `.memory/patterns/`
+5. Update `.memory/index.md`
+
+Then tell the user:
+- If passed: "Phase {{ args[1] | default: "N" }} verified ✅. Next: `/spartan:phase discuss [N+1]` for the next phase, or `/spartan:project milestone-complete` if milestone is done."
+- If failed: "Phase {{ args[1] | default: "N" }} has [N] issues. Fix them, then re-run `/spartan:phase verify {{ args[1] | default: "N" }}`."
+
+{% else %}
+## Unknown action: {{ args[0] }}
+
+Available actions:
+- `/spartan:phase discuss N` — Gather requirements (starts with Office Hours)
+- `/spartan:phase plan N` — Generate wave-parallel execution plan
+- `/spartan:phase execute N` — Execute tasks wave by wave
+- `/spartan:phase verify N` — Run acceptance criteria + UAT
+
+Example: `/spartan:phase discuss 1`
+{% endif %}
+
+---
+
+## Phase Lifecycle (for reference)
+
+```
+/spartan:phase discuss N     ← Office Hours → requirements → decompose
+       ↓
+/spartan:phase plan N        ← Wave-parallel plan from .memory/ context
+       ↓
+/spartan:phase execute N     ← TDD, wave by wave, safety guardrails
+       ↓
+/spartan:phase verify N      ← UAT + capture knowledge to .memory/
+       ↓
+  [next phase or milestone complete]
+```

package/commands/spartan/pitch.md

@@ -0,0 +1,18 @@
+---
+name: spartan:pitch
+description: Create investor-facing materials — deck outline, one-pager, memo, or financial model
+argument-hint: "[what you need: deck, one-pager, memo, model]"
+---
+
+# Pitch: {{ args[0] | default: "deck outline" }}
+
+Create investor materials.
+
+## Steps
+
+1. Use the `investor-materials` skill
+2. Check for existing research in the project's `02-research/` and `03-validation/` folders
+3. Use that data as the source of truth
+4. Save to the project's `04-build/` folder
+
+If there's no prior research, warn that the materials will be weaker without data.