ateschh-kit 1.0.0

package/agents/requirements-expert.md

@@ -0,0 +1,80 @@
+---
+name: "requirements-expert"
+description: "Selects and locks the optimal tech stack based on project requirements."
+triggered_by: ["/requirements"]
+skills: ["requirements-lock"]
+---
+
+# Requirements Expert Agent
+
+## Role
+
+You are a senior software architect with expertise in modern tech stacks.
+Your job is to select the most appropriate technologies for the project and lock them in REQUIREMENTS.md.
+
+**You recommend and lock. You do not implement.**
+
+## Decision Framework
+
+### Platform First
+
+| Target | Default Stack |
+|--------|--------------|
+| Web App (SaaS) | Next.js + Supabase + Vercel |
+| Mobile (iOS/Android) | Expo + Supabase |
+| Mobile (high performance) | React Native (bare) + Supabase |
+| Browser Extension | Plasmo + TypeScript |
+| Desktop | Electron or Tauri |
+| Game | Phaser.js (browser) or Unity (native) |
+| Backend / API only | Hono.js + Cloudflare Workers |
+| CLI tool | Node.js + Commander |
+
+### Selection Criteria
+
+For each decision, evaluate:
+1. **Ecosystem maturity** — Is it production-ready? Active community?
+2. **Team fit** — Does the user have preference or experience?
+3. **Scale fit** — Right tool for expected scale?
+4. **Cost fit** — Does the pricing model work for the project?
+5. **MCP support** — Can MCPs help with deployment, database, etc.?
+
+### Verify with Context7
+
+Before finalizing:
+- Check library versions are current and compatible
+- Verify known breaking changes between versions
+- Confirm selected libraries work together (no conflicts)
+
+## Output Format
+
+Propose the stack clearly:
+
+```markdown
+## Proposed Tech Stack — {project name}
+
+### Platform
+{Web / Mobile iOS+Android / Desktop / etc.}
+
+### Stack
+
+| Category | Technology | Version | Why |
+|----------|-----------|---------|-----|
+| Framework | Next.js | 14.x | Best for SEO + API routes built-in |
+| Database | Supabase | latest | Postgres + auth + realtime + storage |
+| Auth | Supabase Auth | latest | Included in Supabase, full OAuth support |
+| UI Components | shadcn/ui | latest | Headless, fully customizable |
+| Styling | Tailwind CSS | 3.x | Utility-first, pairs with shadcn |
+| State | Zustand | 4.x | Minimal, no boilerplate |
+| Deploy | Vercel | latest | One-click Next.js deploys |
+
+### Out of Scope (v1)
+- {feature or technology explicitly excluded}
+- {reason}
+
+### Known Constraints
+- {any version pins or compatibility notes}
+```
+
+Ask: "Does this stack work for you? Once confirmed, it goes into REQUIREMENTS.md and is locked."
+
+After approval, use the `requirements-lock` skill to write and lock REQUIREMENTS.md.

package/agents/tester.md

@@ -0,0 +1,102 @@
+---
+name: "tester"
+description: "Runs L1-L4 quality checks across the full application before deployment."
+triggered_by: ["/test"]
+skills: ["run-tests"]
+---
+
+# Tester Agent
+
+## Role
+
+You are a QA engineer and quality assurance specialist.
+Your job is to find and document every defect before the application goes live.
+
+**You test. You do not deploy (unless you're also the deployer).**
+
+## Testing Methodology
+
+### L1 — Syntax & Build
+Primary check: nothing broken statically.
+
+```bash
+# Run these (adapt to the project's package manager):
+npm run build
+npm run typecheck  # or tsc --noEmit
+npm run lint
+```
+
+Pass criteria:
+- [ ] Build exits with code 0
+- [ ] Zero TypeScript errors
+- [ ] Zero ESLint errors (warnings OK)
+
+### L2 — Feature Functionality
+Test each feature in STRUCTURE.md.
+
+For each feature:
+1. Describe what "working" means
+2. Try the happy path
+3. Try the failure path (bad input, network error, empty state)
+4. Check edge cases
+
+Common failures to look for:
+- Empty state not handled (shows blank or crashes instead of "no data" message)
+- Form submits with invalid data
+- Navigation doesn't update correctly
+- Auth check missing on protected route
+
+### L3 — Integration
+Test features working together as a system.
+
+Scenarios to test:
+1. **New user flow**: Sign up → verify → first action → see expected result
+2. **Returning user flow**: Sign in → pick up where they left off
+3. **Data flow**: Create → list → update → delete (full CRUD if applicable)
+4. **Auth gates**: Try accessing protected routes without being signed in
+5. **API error handling**: What happens when the server is slow or returns an error?
+
+### L4 — Quality
+Final polish checks before deploy.
+
+- [ ] Mobile responsive (test at 375px, 768px, 1280px if web)
+- [ ] Loading states visible during async operations
+- [ ] Error messages are user-friendly (not stack traces)
+- [ ] No `console.log` in production code
+- [ ] Environment variables use `.env` (not hardcoded)
+- [ ] No credentials in code
+- [ ] Images have alt text
+- [ ] Buttons have accessible labels
+
+## Defect Reporting
+
+For each issue found:
+
+```
+[{Level}] {Short description}
+
+File: {file path}:{line number}
+Steps to reproduce:
+1. {step}
+2. {step}
+
+Expected: {what should happen}
+Actual: {what happened}
+
+Severity: Critical / High / Medium / Low
+Fix: {suggested fix if obvious}
+```
+
+## Test Report
+
+After all levels complete, generate a full test report (see `/test` workflow for format).
+
+## Working with Debugger
+
+When a bug needs fixing:
+1. Write the defect report
+2. Spawn the `debugger` agent with the full defect report
+3. Wait for fix
+4. Re-test the specific issue to confirm fix
+
+Do not fix bugs yourself — that's the debugger's domain.

package/bin/install.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+/**
+ * ateschh-kit installer
+ * Usage: npx ateschh-kit [target-directory]
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { execSync } = require('child_process')
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function log(msg) { console.log(msg) }
+function success(msg) { console.log(`\x1b[32m✅ ${msg}\x1b[0m`) }
+function info(msg) { console.log(`\x1b[36mℹ  ${msg}\x1b[0m`) }
+function warn(msg) { console.log(`\x1b[33m⚠  ${msg}\x1b[0m`) }
+function error(msg) { console.error(`\x1b[31m✗  ${msg}\x1b[0m`) }
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true })
+  }
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath)
+    } else {
+      fs.copyFileSync(srcPath, destPath)
+    }
+  }
+}
+
+function copyFile(src, dest) {
+  const destDir = path.dirname(dest)
+  if (!fs.existsSync(destDir)) {
+    fs.mkdirSync(destDir, { recursive: true })
+  }
+  fs.copyFileSync(src, dest)
+}
+
+// ── Main ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2)
+  const targetDir = args[0] ? path.resolve(args[0]) : process.cwd()
+  const kitDir = path.resolve(__dirname, '..')
+
+  log('')
+  log('\x1b[1m🚀 ateschh-kit installer\x1b[0m')
+  log('━━━━━━━━━━━━━━━━━━━━━━━━━')
+  log(`Installing to: ${targetDir}`)
+  log('')
+
+  // Check if already installed
+  if (fs.existsSync(path.join(targetDir, 'CLAUDE.md'))) {
+    warn('CLAUDE.md already exists in this directory.')
+    warn('Use --force to overwrite.')
+    if (!args.includes('--force')) {
+      process.exit(0)
+    }
+  }
+
+  try {
+    // Copy core files
+    info('Copying CLAUDE.md...')
+    copyFile(path.join(kitDir, 'CLAUDE.md'), path.join(targetDir, 'CLAUDE.md'))
+
+    info('Copying .claude/rules/ ...')
+    copyDir(path.join(kitDir, '.claude'), path.join(targetDir, '.claude'))
+
+    info('Copying workflows/ ...')
+    copyDir(path.join(kitDir, 'workflows'), path.join(targetDir, 'workflows'))
+
+    info('Copying agents/ ...')
+    copyDir(path.join(kitDir, 'agents'), path.join(targetDir, 'agents'))
+
+    info('Copying skills/ ...')
+    copyDir(path.join(kitDir, 'skills'), path.join(targetDir, 'skills'))
+
+    info('Copying templates/ ...')
+    copyDir(path.join(kitDir, 'templates'), path.join(targetDir, 'templates'))
+
+    // Create runtime directories
+    const dirs = ['.state', 'projects', 'archive']
+    for (const dir of dirs) {
+      const dirPath = path.join(targetDir, dir)
+      if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true })
+        info(`Created ${dir}/`)
+      }
+    }
+
+    // Create .gitignore additions
+    const gitignorePath = path.join(targetDir, '.gitignore')
+    const gitignoreAdditions = `
+# ateschh-kit runtime files
+.state/
+projects/
+archive/
+`
+    if (fs.existsSync(gitignorePath)) {
+      const existing = fs.readFileSync(gitignorePath, 'utf8')
+      if (!existing.includes('.state/')) {
+        fs.appendFileSync(gitignorePath, gitignoreAdditions)
+        info('Updated .gitignore')
+      }
+    } else {
+      fs.writeFileSync(gitignorePath, gitignoreAdditions.trim() + '\n')
+      info('Created .gitignore')
+    }
+
+    // Create initial ACTIVE-PROJECT.md
+    const activeProjectPath = path.join(targetDir, '.state', 'ACTIVE-PROJECT.md')
+    if (!fs.existsSync(activeProjectPath)) {
+      fs.writeFileSync(activeProjectPath, `# Active Project\n\n(No active project)\n\nRun \`/new-project\` to get started.\n`)
+    }
+
+    log('')
+    log('━━━━━━━━━━━━━━━━━━━━━━━━━')
+    success('ateschh-kit installed!')
+    log('')
+    log('Next steps:')
+    log('  1. Open this directory in Claude Code or Antigravity')
+    log('  2. Type: /new-project')
+    log('  3. Describe your idea')
+    log('')
+    log('Available commands:')
+    log('  /new-project  /brainstorm  /requirements')
+    log('  /design  /build  /test  /deploy')
+    log('  /next  /quick  /status  /map-codebase')
+    log('')
+
+  } catch (err) {
+    error(`Installation failed: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+main()

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "ateschh-kit",
+  "version": "1.0.0",
+  "description": "A structured AI development system for Claude Code and Antigravity",
+  "keywords": [
+    "claude",
+    "claude-code",
+    "antigravity",
+    "ai",
+    "development",
+    "workflow",
+    "agents",
+    "cursor",
+    "windsurf"
+  ],
+  "homepage": "https://github.com/ateschh/ateschh-kit",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ateschh/ateschh-kit.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "ateschh-kit": "bin/install.js"
+  },
+  "scripts": {
+    "test": "echo \"No automated tests yet\""
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "agents/",
+    "skills/",
+    "workflows/",
+    "templates/",
+    ".claude/",
+    "CLAUDE.md",
+    "ARCHITECTURE.md",
+    "README.md",
+    "README.tr.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE"
+  ]
+}

package/skills/architecture-design/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: "architecture-design"
+description: "Creates STRUCTURE.md (pages/features) and DESIGN.md (visual system), and PLAN.md (task list)"
+used_by: ["architect", "designer"]
+---
+
+# Skill: Architecture & Design
+
+## Purpose
+
+Produce three locked documents that define what will be built and how it will look.
+
+## Outputs
+
+1. **STRUCTURE.md** — App structure, pages, features, navigation (architect produces this)
+2. **DESIGN.md** — Colors, typography, spacing, component style (designer produces this)
+3. **PLAN.md** — Ordered task list derived from STRUCTURE.md (architect produces this)
+
+## STRUCTURE.md Template
+
+```markdown
+# App Structure — {project name}
+
+**Status**: APPROVED ✅
+**Approved on**: {date}
+
+## Golden Path
+{start screen} → {core action} → {success state}
+
+## Auth Boundary
+- **Public**: {list of public pages}
+- **Protected**: {list of protected pages}
+
+## Pages
+
+### {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/modified}
+
+---
+{repeat for each page}
+
+## Navigation
+{Describe how pages connect — list or diagram}
+
+## API Routes (if applicable)
+- `GET /api/{resource}` — {purpose}
+- `POST /api/{resource}` — {purpose}
+```
+
+## PLAN.md Template
+
+```markdown
+# Build Plan — {project name}
+
+**Status**: APPROVED ✅
+**Approved on**: {date}
+
+## Phase 4 — Build Tasks
+
+### 🛠 Setup
+- [ ] Initialize {framework} project
+- [ ] Install all dependencies from REQUIREMENTS.md
+- [ ] Configure environment variables
+- [ ] Set up database schema
+
+### 📄 {Page/Feature Name} — {S/M/L}
+- [ ] {specific task}
+- [ ] {specific task}
+
+### 📄 {Page/Feature Name}
+- [ ] {specific task}
+
+### 🔗 Integration
+- [ ] End-to-end auth flow
+- [ ] API connections tested
+- [ ] Final responsive pass
+
+## Sizing Guide
+S = ~15 min | M = ~30 min | L = ~1 hour
+```

package/skills/context-management/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: "context-management"
+description: "Save and restore project context across sessions and platforms"
+used_by: ["orchestrator (main session)"]
+---
+
+# Skill: Context Management
+
+## Purpose
+
+Prevent context rot and enable seamless continuation across sessions or platforms.
+
+## Save Protocol
+
+### When to Save
+
+- Before ending a session
+- When context > 50% full (DEGRADING zone)
+- Before switching to another AI platform
+
+### What to Save
+
+1. **Session file** (`projects/{name}/sessions/session-NNN.md`):
+   - What was done this session
+   - Current phase and task
+   - Files changed
+   - Decisions made
+   - Blockers or open questions
+
+2. **Active context** (`.state/ACTIVE_CONTEXT.md`):
+   - 1-page summary of current project state
+   - Written for a fresh session to pick up immediately
+
+3. **Session log** (`.state/SESSION-LOG.md`):
+   - One-line entry per session
+   - Running history of all work
+
+### ACTIVE_CONTEXT.md Format
+
+```markdown
+# Active Context — {date} {time}
+
+**Project**: {name}
+**Phase**: {N}/6 — {phase name}
+
+## Status in 3 lines
+- Done: {last completed task}
+- Next: {very next task}
+- Blocked: {blocker or "None"}
+
+## What's been built
+{bullet list of completed features}
+
+## Key decisions (don't re-discuss)
+- {decision}: {why}
+
+## Important file locations
+- Requirements: projects/{name}/REQUIREMENTS.md
+- Design: projects/{name}/DESIGN.md
+- Plan: projects/{name}/PLAN.md
+```
+
+## Restore Protocol
+
+### On `/resume`
+
+1. Read `.state/ACTIVE_CONTEXT.md` (primary source)
+2. Read `projects/{name}/STATE.md` (current progress)
+3. Read latest session file (recent decisions)
+4. Summarize to user in 3 lines
+5. Ask: "Continue with {next task}?"
+
+### Cross-Platform (Claude Code ↔ Antigravity)
+
+Both platforms read the same file system.
+The only difference is `MEMORY.md` behavior:
+- **Claude Code**: add `MEMORY.md` path to Claude's memory
+- **Antigravity**: the context-agent handles memory automatically
+
+Either way, `/save` + `/resume` handles the transition.
+
+## Context Health Monitoring
+
+| Zone | Token Usage | Action |
+|------|------------|--------|
+| PEAK | 0–30% | Normal |
+| GOOD | 30–50% | Prefer delegation |
+| DEGRADING | 50–70% | Warn user, checkpoint |
+| POOR | 70%+ | `/save` immediately |
+
+At DEGRADING: "Context window is getting full — I recommend running `/save` soon."
+At POOR: Stop, run `/save`, ask user to start new session.

package/skills/fix-bugs/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: "fix-bugs"
+description: "Root cause diagnosis and minimal targeted fix for reported defects"
+used_by: ["debugger"]
+---
+
+# Skill: Fix Bugs
+
+## Process
+
+### 1. Reproduce
+
+Follow the exact steps from the defect report.
+If you can't reproduce: ask for more context. Never fix what you can't see.
+
+### 2. Isolate
+
+| Question | Why it matters |
+|----------|---------------|
+| Frontend or backend? | Narrows search space |
+| Every time or sometimes? | Suggests race condition or state issue |
+| After what action? | Points to the trigger |
+| Only for certain users? | Suggests auth/permission problem |
+
+### 3. Diagnose
+
+Common patterns:
+
+| Symptom | Root cause |
+|---------|-----------|
+| `undefined is not an object` | Missing null check or async race |
+| `401 Unauthorized` | Token expired or header wrong |
+| Infinite re-render | `useEffect` dependency instability |
+| Data doesn't update | Cache stale, state not invalidated |
+| CORS error | Server missing CORS header |
+| Build fails | Env var missing, version conflict |
+| Hydration mismatch | Server vs client render difference |
+
+### 4. Fix
+
+Minimal and targeted:
+- Fix the root cause (not a workaround)
+- Touch as few files as possible
+- Don't add features or refactor while fixing
+
+### 5. Verify
+
+- Re-run reproduction steps → bug gone
+- Run L1 → build still clean
+- Check adjacent code for same pattern
+
+### 6. Escalate if Stuck
+
+After 2 attempts with no fix:
+```
+I've tried:
+1. {attempt}: {result}
+2. {attempt}: {result}
+
+The issue appears to be: {hypothesis}
+
+Options:
+A. {option}: {tradeoff}
+B. {option}: {tradeoff}
+
+Which should I try?
+```

package/skills/idea-analysis/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: "idea-analysis"
+description: "5-question Socratic analysis to validate an idea before building"
+used_by: ["idea-analyst"]
+---
+
+# Skill: Idea Analysis
+
+## Purpose
+
+Deeply understand an idea before committing to any technology or design decisions.
+
+## The 5 Questions
+
+Ask one at a time. Read the answer carefully before asking the next.
+
+```
+Q1 — PROBLEM
+"What specific problem does this solve? Who experiences this daily?"
+
+Q2 — ROOT CAUSE
+"Why does this problem exist? Why hasn't someone already fixed it?"
+
+Q3 — SOLUTION
+"Why is your approach better than current alternatives?"
+
+Q4 — TARGET USER
+"Who is the exact person who would use this? Describe them specifically."
+
+Q5 — SUCCESS
+"What does success look like in 6 months? How would you measure it?"
+```
+
+## Evaluation Criteria
+
+After all 5 answers:
+
+| Signal | Green | Red |
+|--------|-------|-----|
+| Problem clarity | Specific, real pain | Vague, hypothetical |
+| Market | Users exist now | "Everyone would want this" |
+| Differentiation | Clear advantage | "Like X but better" |
+| Success | Measurable metric | "Lots of users" |
+| Scope | Achievable v1 | Requires everything at once |
+
+## Output Template
+
+```markdown
+## Idea Analysis — {date}
+
+**Verdict**: ✅ Strong / ⚠️ Needs clarity / ❌ Fundamental issue
+
+### Core Problem
+{1-2 sentences}
+
+### Target User
+{specific persona with pain point}
+
+### Solution
+{what this does differently}
+
+### Value Proposition
+{why users will choose this}
+
+### Success Metrics
+{measurable outcomes}
+
+### Key Risks
+1. {risk}
+2. {risk}
+```