ateschh-kit 1.0.0

package/templates/project/STATE.md

@@ -0,0 +1,94 @@
+# Project State — {Project Name}
+
+**Phase**: {1-6} / 6
+**Status**: {IN PROGRESS / COMPLETE / BLOCKED}
+**Last updated**: {YYYY-MM-DD}
+**Started**: {YYYY-MM-DD}
+
+---
+
+## Phase Progress
+
+| Phase | Name | Status |
+|-------|------|--------|
+| 1 | Idea & Research | ⬜ Not started |
+| 2 | Requirements | ⬜ Not started |
+| 3 | Design | ⬜ Not started |
+| 4 | Build | ⬜ Not started |
+| 5 | Test | ⬜ Not started |
+| 6 | Deploy | ⬜ Not started |
+
+---
+
+## Phase 1 — Idea & Research
+
+- [ ] Idea analysis complete (idea-analyst)
+- [ ] Market research complete (market-researcher)
+- [ ] Idea approved by user
+
+---
+
+## Phase 2 — Requirements
+
+- [ ] Tech stack proposed
+- [ ] Tech stack approved
+- [ ] REQUIREMENTS.md locked ✅
+
+---
+
+## Phase 3 — Design
+
+- [ ] App structure defined (STRUCTURE.md)
+- [ ] Design system created (DESIGN.md)
+- [ ] Both approved by user
+- [ ] PLAN.md created
+
+---
+
+## Phase 4 — Build
+
+<!-- Tasks from PLAN.md will be listed here as they are worked on -->
+
+- [ ] Project initialized
+- [ ] Dependencies installed
+
+---
+
+## Phase 5 — Test
+
+- [ ] L1 passed (build + types + lint)
+- [ ] L2 passed (feature functionality)
+- [ ] L3 passed (integration)
+- [ ] L4 passed (quality)
+
+---
+
+## Phase 6 — Deploy
+
+- [ ] Deployed to production
+- [ ] Live URL verified
+- [ ] Live URL: {url}
+
+---
+
+## Current Task
+
+**Next**: {describe the very next thing to do}
+
+---
+
+## Last Verification
+
+```
+Date: {date}
+L1: {✅ / ❌}
+L2: {✅ / ❌}
+L3: {✅ / ❌ / (not yet)}
+L4: {✅ / ❌ / (not yet)}
+```
+
+---
+
+## Blockers
+
+{None / describe any blocking issue}

package/templates/project/STRUCTURE.md

@@ -0,0 +1,89 @@
+# App Structure — {Project Name}
+
+**Status**: DRAFT 📝
+**Approved on**: (not yet approved)
+
+---
+
+## Golden Path
+
+{start screen} → {core action} → {success state}
+
+---
+
+## Auth Boundary
+
+**Public** (no login required):
+- {page}
+- {page}
+
+**Protected** (login required):
+- {page}
+- {page}
+
+---
+
+## Pages / Screens
+
+### {page-name}
+**Route**: `/{route}` (or Screen name for mobile)
+**Purpose**: {one sentence}
+
+**Must-have (MVP)**:
+- {feature}
+- {feature}
+
+**Nice-to-have (v2)**:
+- {feature}
+
+**Data**:
+- Reads: {data sources}
+- Writes: {what is created or modified}
+
+---
+
+### {page-name}
+**Route**: `/{route}`
+**Purpose**: {one sentence}
+
+**Must-have (MVP)**:
+- {feature}
+
+---
+
+## Navigation Map
+
+{Describe how pages connect — text or simple diagram}
+
+```
+Home → Login → Dashboard → {Feature}
+           ↓
+        Register
+```
+
+---
+
+## API Routes (if applicable)
+
+| Method | Route | Purpose |
+|--------|-------|---------|
+| GET | /api/{resource} | {purpose} |
+| POST | /api/{resource} | {purpose} |
+| PUT | /api/{resource}/{id} | {purpose} |
+| DELETE | /api/{resource}/{id} | {purpose} |
+
+---
+
+## Database Schema (high level)
+
+```
+{table_name}
+├── id: uuid
+├── {field}: {type}
+└── created_at: timestamp
+
+{table_name}
+├── id: uuid
+├── {field}: {type}
+└── updated_at: timestamp
+```

package/workflows/_TEMPLATE.md

@@ -0,0 +1,44 @@
+---
+command: "/_TEMPLATE"
+description: "Template for creating new workflows"
+---
+
+# /your-command — Short Description
+
+## When to Use
+
+{When should a user run this command?}
+
+## Prerequisites
+
+- {What must be true before this runs}
+
+## Steps
+
+### Step 1: {Step Name}
+
+{What to do}
+
+### Step 2: {Step Name}
+
+{What to do}
+
+### Step N: Confirm to User
+
+```
+✅ {What was done}
+
+{Result summary}
+
+Next: run /{next-command}
+```
+
+## State Updates
+
+After completion:
+- Update STATE.md: {what to update}
+- Log to SESSION-LOG.md: {yes/no}
+
+## Next Step
+
+`/{next-command}`

package/workflows/brainstorm.md

@@ -0,0 +1,69 @@
+---
+command: "/brainstorm"
+description: "Idea analysis + market research. Spawns idea-analyst and market-researcher agents."
+phase: "1"
+agents: ["idea-analyst", "market-researcher"]
+skills: ["idea-analysis", "market-research"]
+outputs: ["Updated STATE.md", "Research notes in sessions/"]
+---
+
+# /brainstorm — Idea Analysis & Market Research
+
+## When to Use
+
+After `/new-project`, when you have an idea and want to analyze it properly before committing to a tech stack.
+
+## Steps
+
+### Step 1: Read Project Context
+
+Read `projects/{name}/STATE.md` to confirm we're in Phase 1.
+
+### Step 2: Spawn Idea Analyst Agent
+
+Read `agents/idea-analyst.md` and spawn the agent with the user's idea.
+
+The idea-analyst uses the `idea-analysis` skill:
+- Asks 5 core questions using the Socratic method
+- Goal: understand the problem, target user, core value, and what success looks like
+- Output: structured idea summary
+
+Report findings to the user. Ask for confirmation before proceeding.
+
+### Step 3: Spawn Market Researcher Agent
+
+Read `agents/market-researcher.md` and spawn the agent.
+
+The market-researcher uses the `market-research` skill:
+- Identifies 3–5 direct competitors
+- Analyzes their strengths, weaknesses, pricing, and positioning
+- Identifies differentiation opportunities
+- Output: market research summary
+
+### Step 4: Synthesize & Present
+
+Combine both agent outputs into a single summary:
+
+```
+## Idea Summary
+{core idea in 3 bullet points}
+
+## Target User
+{who this is for, their pain point}
+
+## Market Opportunity
+{what competitors miss that we can win on}
+
+## Risks
+{top 2–3 risks to watch for}
+```
+
+Ask: "Does this capture your idea correctly? Ready to move to tech stack selection?"
+
+### Step 5: Update STATE.md
+
+Mark Phase 1 tasks complete. Set next task to `/requirements`.
+
+## Next Step
+
+`/requirements`

package/workflows/build.md

@@ -0,0 +1,92 @@
+---
+command: "/build"
+description: "Implements one task from PLAN.md. Repeatable — run for each task."
+phase: "4"
+agents: ["coder", "debugger"]
+skills: ["write-code"]
+outputs: ["Working code", "Updated STATE.md", "L1+L2 verification report"]
+---
+
+# /build — Build a Feature
+
+## When to Use
+
+After `/design` is complete. Run this command for each task in PLAN.md.
+This command is **repeatable** — run it once per task.
+
+## Steps
+
+### Step 1: Read Context
+
+Read in order:
+1. `projects/{name}/REQUIREMENTS.md` → tech stack and libraries
+2. `projects/{name}/DESIGN.md` → colors, fonts, style values
+3. `projects/{name}/STATE.md` → which task is next
+4. `projects/{name}/PLAN.md` → task details
+
+### Step 2: Confirm Task with User
+
+Show the current task in 3 lines:
+```
+🎯 Current task: {task name}
+📁 Files affected: {file list}
+⏱ Estimated time: {S=15min / M=30min / L=1hr}
+
+Shall I proceed?
+```
+
+### Step 3: Spawn Coder Agent
+
+Read `agents/coder.md` and spawn the agent.
+
+The coder:
+1. Reads REQUIREMENTS.md (library constraints)
+2. Reads DESIGN.md (style constraints)
+3. Implements exactly the task — nothing more
+4. Uses Context7 MCP to verify library APIs if needed
+5. Does NOT install unlisted dependencies
+
+### Step 4: L1 + L2 Verification
+
+After coding:
+
+```
+L1 Check:
+- [ ] npm run build passes
+- [ ] No TypeScript errors
+- [ ] No ESLint errors
+
+L2 Check:
+- [ ] Feature works as described
+- [ ] No console errors
+- [ ] Core user flow works
+```
+
+If L1 fails → spawn `debugger` agent to fix before proceeding.
+If L2 fails → spawn `debugger` agent to diagnose and fix.
+
+### Step 5: Show Result to User
+
+For web projects: use Claude Preview MCP if available to show a screenshot.
+Otherwise: describe what was built and where.
+
+### Step 6: Update STATE.md
+
+- Check off the completed task
+- Update "Next task" field
+- Log L1+L2 results in "Last Verification" section
+
+### Step 7: Confirm and Move On
+
+```
+✅ Task complete: {task name}
+
+L1: ✅ Build clean
+L2: ✅ Feature works
+
+Next task: {next task} — run `/build` again to continue.
+```
+
+## Next Step
+
+`/build` (repeat for next task) or `/test` when all tasks are done

package/workflows/deploy.md

@@ -0,0 +1,85 @@
+---
+command: "/deploy"
+description: "Deploys the application to production. Uses MCP tools."
+phase: "6"
+agents: ["deployer"]
+skills: ["publish"]
+outputs: ["Live URL", "Updated STATE.md", "Deployment log"]
+---
+
+# /deploy — Deploy to Production
+
+## When to Use
+
+After `/test` has passed L1–L4. The app is ready to go live.
+
+## Steps
+
+### Step 1: Pre-Deploy Checklist
+
+Before spawning the deployer, verify:
+
+- [ ] L1–L4 tests all pass
+- [ ] `.env` variables are set correctly (not test values)
+- [ ] REQUIREMENTS.md lists the deploy target (Vercel / Cloudflare / Firebase / Expo)
+- [ ] No hardcoded localhost URLs in code
+
+### Step 2: Read Requirements
+
+Read `projects/{name}/REQUIREMENTS.md` to identify the deploy target.
+
+### Step 3: Spawn Deployer Agent
+
+Read `agents/deployer.md` and spawn the agent.
+
+The deployer:
+
+**Web (Vercel/Next.js)**:
+- Runs `vercel --prod` or uses Vercel MCP
+- Sets environment variables in Vercel dashboard
+- Verifies deployment URL loads correctly
+
+**Backend (Cloudflare Workers)**:
+- Uses Cloudflare MCP to deploy Workers
+- Sets KV / D1 / R2 bindings
+- Verifies API endpoint responds
+
+**Mobile (Expo)**:
+- Runs `eas build` for production binary
+- Submits to App Store / Play Store if configured
+- Or creates OTA update via `eas update`
+
+**Database (Supabase)**:
+- Uses Supabase MCP to run migrations
+- Verifies RLS policies are active
+- Checks that anon key is restricted correctly
+
+**Firebase**:
+- Uses Firebase MCP to deploy hosting / functions
+- Verifies hosting URL is live
+
+### Step 4: Post-Deploy Verification
+
+After the deploy command succeeds:
+1. Open the live URL (or get a screenshot if Claude Preview available)
+2. Run a quick smoke test: core user flow end-to-end
+3. Confirm no 500 errors in logs
+
+### Step 5: Update STATE.md
+
+Mark Phase 6 complete. Add the live URL.
+
+### Step 6: Confirm to User
+
+```
+🚀 Deployed!
+
+🌐 Live URL: {url}
+📅 Deployed: {date}
+
+Run `/finish` to archive this project and close it out.
+```
+
+## Next Step
+
+`/finish`

package/workflows/design.md

@@ -0,0 +1,84 @@
+---
+command: "/design"
+description: "Defines pages, features, and UI design system. Locks DESIGN.md."
+phase: "3"
+agents: ["architect", "designer"]
+skills: ["architecture-design"]
+outputs: ["Locked DESIGN.md", "STRUCTURE.md", "Updated STATE.md"]
+---
+
+# /design — Architecture & UI Design
+
+## When to Use
+
+After `/requirements` is locked. Defines what the app looks like and how it's structured.
+
+## Steps
+
+### Step 1: Verify Phase
+
+Read `projects/{name}/STATE.md`. Confirm Phase 2 is complete.
+
+### Step 2: Spawn Architect Agent
+
+Read `agents/architect.md` and spawn the agent.
+
+The architect:
+1. Reads REQUIREMENTS.md and the idea summary
+2. Defines the app's page structure and navigation
+3. Lists features per page with priority (must-have vs nice-to-have)
+4. Output: STRUCTURE.md draft
+
+Present to user. Ask for approval before proceeding.
+
+### Step 3: Spawn Designer Agent
+
+Read `agents/designer.md` and spawn the agent.
+
+The designer:
+1. Reads the idea summary and brand direction from the user
+2. Asks 3 quick questions:
+   - What mood/feeling? (e.g., professional, playful, minimal, bold)
+   - Any brand colors? (hex or description)
+   - Font preference or examples you like?
+3. Creates a full design system:
+   - Color palette (primary, secondary, accent, neutrals)
+   - Typography scale (font family, sizes, weights)
+   - Spacing system
+   - Component style (border radius, shadows)
+4. Output: DESIGN.md draft
+
+Present to user. Ask for approval.
+
+### Step 4: Lock Files
+
+Once both are approved:
+- Lock `projects/{name}/DESIGN.md` → status: **LOCKED ✅**
+- Save `projects/{name}/STRUCTURE.md`
+
+### Step 5: Generate PLAN.md
+
+Based on STRUCTURE.md, create the initial PLAN.md:
+- List all pages/features as tasks
+- Group into logical build order
+- Estimate complexity per task (S/M/L)
+
+### Step 6: Update STATE.md
+
+Mark Phase 3 complete. Set next task to `/build` (first task in PLAN.md).
+
+### Step 7: Confirm to User
+
+```
+✅ Design system locked!
+
+📐 Structure: {N} pages defined
+🎨 Design: colors, fonts, and components defined
+📋 Plan: {N} build tasks ready
+
+Next: `/build` — let's start building!
+```
+
+## Next Step
+
+`/build`

package/workflows/finish.md

@@ -0,0 +1,90 @@
+---
+command: "/finish"
+description: "Marks the project as complete, archives it, and closes it out."
+phase: "6"
+agents: []
+skills: ["context-management"]
+outputs: ["Archived project", "Updated ACTIVE-PROJECT.md", "Entry in archive/"]
+---
+
+# /finish — Complete & Archive Project
+
+## When to Use
+
+After `/deploy` is confirmed and the project is live.
+
+## Steps
+
+### Step 1: Verify Completion
+
+Read `projects/{name}/STATE.md`. Confirm:
+- [ ] All 6 phases complete
+- [ ] Deployed URL exists
+- [ ] No critical bugs remaining
+
+If not complete → ask: "Are you sure? Phase {N} isn't done yet. Continue?"
+
+### Step 2: Create Archive Entry
+
+Create `archive/{name}/`:
+- Copy all project files there
+- Add `COMPLETION-REPORT.md`:
+
+```markdown
+# {name} — Completion Report
+
+**Completed**: {date}
+**Duration**: {X} days
+**Live URL**: {url}
+
+## What was built
+{2-3 sentence summary}
+
+## Tech stack
+{from REQUIREMENTS.md}
+
+## Key decisions
+{from DECISIONS.md summary}
+
+## Lessons learned
+{what worked, what to do differently next time}
+
+## Backlog (carry forward)
+{items from BACKLOG.md to consider for v2}
+```
+
+### Step 3: Clear Active Project
+
+Update `.state/ACTIVE-PROJECT.md`:
+```markdown
+# Active Project
+
+(No active project)
+
+Last completed: {name} on {date}
+```
+
+### Step 4: Update SESSION-LOG.md
+
+Append:
+```
+## {date} — {name} COMPLETED
+- **Live URL**: {url}
+- **Duration**: {N} days
+- **Archive**: archive/{name}/
+```
+
+### Step 5: Confirm to User
+
+```
+🎉 Project "{name}" is complete!
+
+🌐 Live at: {url}
+📦 Archived to: archive/{name}/
+
+What's next? Use `/new-project` to start something new.
+```
+
+## Next Step
+
+`/new-project`