buildcrew 1.0.0 → 1.1.1

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "buildcrew",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "11 AI agents for Claude Code — auto-orchestrated dev team with 9 operating modes",
+  "homepage": "https://buildcrew-landing.vercel.app",
   "author": "z1nun",
   "license": "MIT",
   "type": "module",
@@ -11,6 +12,7 @@
   "files": [
     "bin/",
     "agents/",
+    "templates/",
     "README.md",
     "LICENSE"
   ],

package/templates/api-spec.md

@@ -0,0 +1,52 @@
+# API Specification
+
+## Base URL
+- **Development**: `http://localhost:3000/api`
+- **Production**: `https://[your-domain]/api`
+
+## Authentication
+- **Method**: [Bearer token / Cookie / API key]
+- **Header**: `Authorization: Bearer <token>`
+
+## Endpoints
+
+### [Resource Name]
+
+#### `GET /api/[resource]`
+- **Auth**: Required / Public
+- **Description**: [what it does]
+- **Query Params**: `?page=1&limit=20`
+- **Response 200**:
+```json
+{
+  "data": [],
+  "total": 0
+}
+```
+- **Response 401**: Unauthorized
+
+#### `POST /api/[resource]`
+- **Auth**: Required
+- **Body**:
+```json
+{
+  "field": "value"
+}
+```
+- **Response 201**: Created
+- **Response 400**: Validation error
+
+## Error Format
+```json
+{
+  "error": "Error message",
+  "code": "ERROR_CODE"
+}
+```
+
+## Rate Limits
+- [e.g., "100 requests per minute per user"]
+- [e.g., "AI endpoints: 10 requests per minute"]
+
+---
+*Agents use this to implement correct API calls, validate endpoints during review, and test during QA.*

package/templates/architecture.md

@@ -0,0 +1,49 @@
+# Architecture
+
+## System Overview
+
+```
+[Client] → [Frontend] → [API Layer] → [Database]
+                ↓              ↓
+           [Auth]         [External APIs]
+```
+
+## Frontend
+- **Framework**: [Next.js / React / Vue / etc.]
+- **Routing**: [App Router / Pages Router / file-based]
+- **State Management**: [React Context / Zustand / Redux / etc.]
+- **Styling**: [TailwindCSS / CSS Modules / styled-components]
+
+## Backend / API
+- **Type**: [Next.js API Routes / Express / serverless]
+- **Authentication**: [Supabase Auth / NextAuth / custom]
+- **Database**: [Supabase / PostgreSQL / MongoDB]
+- **ORM**: [Prisma / Drizzle / Supabase client]
+
+## External Services
+| Service | Purpose | Auth Method |
+|---------|---------|-------------|
+| [e.g., OpenAI] | [AI generation] | [API key] |
+| [e.g., Stripe] | [Payments] | [API key + webhook] |
+
+## Directory Structure
+```
+src/
+├── app/          [pages and API routes]
+├── components/   [React components]
+├── lib/          [utilities and helpers]
+└── [other dirs]
+```
+
+## Key Patterns
+- [e.g., "Server components by default, 'use client' only when needed"]
+- [e.g., "All DB access through lib/supabase/ helpers"]
+- [e.g., "API routes validate input with zod"]
+
+## Deploy
+- **Platform**: [Vercel / AWS / etc.]
+- **CI/CD**: [GitHub Actions / Vercel auto-deploy]
+- **Environments**: [dev, staging, prod]
+
+---
+*Agents use this to understand system boundaries, make architecture-consistent decisions, and avoid breaking existing patterns.*

package/templates/design-system.md

@@ -0,0 +1,66 @@
+# Design System
+
+## Colors
+
+### Brand
+| Token | Value | Usage |
+|-------|-------|-------|
+| `primary` | [#hex] | CTAs, links, active states |
+| `secondary` | [#hex] | Secondary buttons, borders |
+| `accent` | [#hex] | Highlights, badges |
+
+### Semantic
+| Token | Value | Usage |
+|-------|-------|-------|
+| `success` | [#hex] | Success messages, confirmations |
+| `error` | [#hex] | Error messages, destructive actions |
+| `warning` | [#hex] | Warnings, caution states |
+| `info` | [#hex] | Informational messages |
+
+### Neutral
+| Token | Value | Usage |
+|-------|-------|-------|
+| `bg` | [#hex] | Page background |
+| `surface` | [#hex] | Card/modal backgrounds |
+| `border` | [#hex] | Borders, dividers |
+| `text` | [#hex] | Primary text |
+| `text-muted` | [#hex] | Secondary text, labels |
+
+## Typography
+
+| Level | Size | Weight | Line Height | Usage |
+|-------|------|--------|-------------|-------|
+| H1 | [rem] | [weight] | [lh] | Page titles |
+| H2 | [rem] | [weight] | [lh] | Section titles |
+| H3 | [rem] | [weight] | [lh] | Card titles |
+| Body | [rem] | [weight] | [lh] | Default text |
+| Small | [rem] | [weight] | [lh] | Captions, labels |
+
+## Spacing
+- **Base unit**: [4px / 8px]
+- **Scale**: 4, 8, 12, 16, 24, 32, 48, 64
+
+## Border Radius
+- **Small**: [4px] — inputs, small cards
+- **Medium**: [8px] — cards, modals
+- **Large**: [16px] — large containers
+- **Full**: [9999px] — pills, avatars
+
+## Shadows
+- **Small**: [shadow] — hover states
+- **Medium**: [shadow] — cards, dropdowns
+- **Large**: [shadow] — modals, popovers
+
+## Components
+| Component | Variants | Location |
+|-----------|----------|----------|
+| Button | primary, secondary, ghost, destructive | `src/components/Button` |
+| [Component] | [variants] | [path] |
+
+## Animation
+- **Duration**: fast (150ms), normal (300ms), slow (500ms)
+- **Easing**: ease-out for enter, ease-in for exit
+- **Library**: [Framer Motion / CSS transitions / etc.]
+
+---
+*Agents use this to create visually consistent components, pick correct tokens, and follow established patterns.*

package/templates/env-vars.md

@@ -0,0 +1,36 @@
+# Environment Variables
+
+## Required (app won't work without these)
+
+| Variable | Description | Where to Get |
+|----------|-------------|-------------|
+| `DATABASE_URL` | [Database connection string] | [Supabase dashboard / provider] |
+| `NEXT_PUBLIC_SUPABASE_URL` | [Supabase project URL] | [Supabase dashboard] |
+| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | [Supabase public key] | [Supabase dashboard] |
+| | | |
+
+## Optional (features degrade gracefully)
+
+| Variable | Description | Feature Affected |
+|----------|-------------|-----------------|
+| `OPENAI_API_KEY` | [AI API access] | [AI features disabled] |
+| `STRIPE_SECRET_KEY` | [Payment processing] | [Payments disabled] |
+| | | |
+
+## Server-Only (never expose to client)
+
+| Variable | Why Server-Only |
+|----------|----------------|
+| `SUPABASE_SERVICE_ROLE_KEY` | Bypasses RLS |
+| `[API]_SECRET_KEY` | Payment/API secrets |
+
+## Environments
+
+| Env | .env file | Notes |
+|-----|-----------|-------|
+| Local | `.env.local` | Never committed |
+| Preview | Vercel env vars | Auto from branch |
+| Production | Vercel env vars | Manual setup |
+
+---
+*Agents use this to avoid exposing secrets, configure features correctly, and debug environment issues.*

package/templates/erd.md

@@ -0,0 +1,32 @@
+# ERD (Entity Relationship Diagram)
+
+## Tables
+
+### users
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | uuid | PK | |
+| email | text | unique, not null | |
+| created_at | timestamp | default now() | |
+
+### [table_name]
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+
+## Relationships
+
+```
+users 1──* orders      (one user has many orders)
+orders *──1 products   (many orders reference one product)
+```
+
+## Indexes
+- `users.email` — unique index for login lookup
+- [add your indexes]
+
+## RLS Policies (if using Supabase)
+- `users`: users can only read/update their own row
+- [add your policies]
+
+---
+*Agents use this to understand your data model when planning features, writing queries, and reviewing security.*

package/templates/glossary.md

@@ -0,0 +1,27 @@
+# Glossary
+
+Domain terms and their definitions. All agents use consistent terminology.
+
+| Term | Definition | In Code As |
+|------|-----------|------------|
+| [e.g., reading] | [e.g., A tarot card reading session] | `Reading` type |
+| [e.g., spread] | [e.g., The layout pattern for cards] | `SpreadType` enum |
+| [e.g., interpretation] | [e.g., AI-generated meaning of cards] | `Interpretation` type |
+| | | |
+| | | |
+
+## User Roles
+| Role | Permissions | In Code As |
+|------|------------|------------|
+| [e.g., free user] | [e.g., 3 readings per day] | `role: "free"` |
+| [e.g., premium] | [e.g., unlimited readings + chat] | `role: "premium"` |
+| [e.g., admin] | [e.g., all access + user management] | `role: "admin"` |
+
+## Status Flows
+```
+[e.g., Order: draft → pending → paid → fulfilled → completed]
+[e.g., User: anonymous → registered → verified → premium]
+```
+
+---
+*Agents use this to write code with correct naming, understand business logic, and communicate clearly in docs.*

package/templates/user-flow.md

@@ -0,0 +1,40 @@
+# User Flows
+
+## Core Flows
+
+### [Flow Name, e.g., "Purchase Flow"]
+```
+[Entry Point] → [Step 1] → [Step 2] → [Step 3] → [Success]
+                    ↓           ↓           ↓
+                [Error A]   [Error B]   [Error C]
+```
+
+**Happy Path**:
+1. User [action]
+2. System [response]
+3. User [action]
+4. System [response] → Success
+
+**Error Paths**:
+- Step 1 fails: [what happens, where user goes]
+- Step 2 fails: [what happens]
+- Network error: [retry? fallback?]
+
+**Edge Cases**:
+- [e.g., user refreshes mid-flow]
+- [e.g., session expires during checkout]
+- [e.g., concurrent access from two devices]
+
+### [Next Flow...]
+
+## Page Map
+```
+/                 → Home (landing)
+/login            → Auth
+/dashboard        → Main dashboard (auth required)
+/dashboard/[id]   → Detail page
+/settings         → User settings
+```
+
+---
+*Agents use this to implement correct navigation, handle all error states, and test edge cases during QA.*