@smicolon/ai-kit 0.0.1 → 0.1.1

package/packs/dev-loop/scripts/setup-dev-loop.sh

@@ -0,0 +1,194 @@
+#!/bin/bash
+
+# Dev Loop Setup Script
+# Based on Ralph Wiggum pattern from official plugin
+# Creates state file for in-session dev loop
+
+set -euo pipefail
+
+# Parse arguments
+PROMPT_PARTS=()
+MAX_ITERATIONS=50        # Default: 50 iterations (different from Ralph's unlimited)
+COMPLETION_PROMISE="DONE" # Default: "DONE" (different from Ralph's null)
+FROM_PLAN=false
+PLAN_FILE=".claude/dev-plan.local.md"
+
+# Parse options and positional arguments
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    -h|--help)
+      cat << 'HELP_EOF'
+Dev Loop - Iterative development loop with sensible defaults
+
+USAGE:
+  /dev-loop [PROMPT...] [OPTIONS]
+  /dev-loop --from-plan [OPTIONS]
+
+ARGUMENTS:
+  PROMPT...    Initial prompt to start the loop (can be multiple words without quotes)
+
+OPTIONS:
+  --from-plan                    Use prompt from .claude/dev-plan.local.md
+  --max-iterations <n>           Maximum iterations (default: 50)
+  --promise '<text>'             Completion promise phrase (default: DONE)
+  -h, --help                     Show this help message
+
+DESCRIPTION:
+  Starts a development loop in your CURRENT session. The stop hook prevents
+  exit and feeds your output back as input until completion or iteration limit.
+
+  To signal completion, output: <promise>DONE</promise>
+  (or your custom --promise value)
+
+  Use this for:
+  - TDD development cycles (Red-Green-Refactor)
+  - Bug fixing with iterative debugging
+  - Feature implementation with self-correction
+
+DEFAULTS (different from Ralph Wiggum):
+  - Max iterations: 50 (Ralph: unlimited)
+  - Completion promise: DONE (Ralph: none)
+
+EXAMPLES:
+  /dev-loop Build a todo API
+  /dev-loop Fix the auth bug --max-iterations 20
+  /dev-loop --from-plan
+  /dev-loop Refactor cache layer --promise 'REFACTOR COMPLETE'
+
+STOPPING:
+  Output <promise>DONE</promise> or reach max iterations (50 by default).
+
+WORKFLOW:
+  1. /dev-plan "Your task"     # Generate structured TDD plan
+  2. Review .claude/dev-plan.local.md
+  3. /dev-loop --from-plan     # Execute with plan
+HELP_EOF
+      exit 0
+      ;;
+    --max-iterations)
+      if [[ -z "${2:-}" ]]; then
+        echo "❌ Error: --max-iterations requires a number argument" >&2
+        echo "" >&2
+        echo "   Valid examples:" >&2
+        echo "     --max-iterations 10" >&2
+        echo "     --max-iterations 50" >&2
+        echo "     --max-iterations 0  (unlimited)" >&2
+        echo "" >&2
+        echo "   You provided: --max-iterations (with no number)" >&2
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[0-9]+$ ]]; then
+        echo "❌ Error: --max-iterations must be a positive integer or 0, got: $2" >&2
+        echo "" >&2
+        echo "   Valid examples:" >&2
+        echo "     --max-iterations 10" >&2
+        echo "     --max-iterations 50" >&2
+        echo "     --max-iterations 0  (unlimited)" >&2
+        echo "" >&2
+        echo "   Invalid: decimals (10.5), negative numbers (-5), text" >&2
+        exit 1
+      fi
+      MAX_ITERATIONS="$2"
+      shift 2
+      ;;
+    --promise|--completion-promise)
+      if [[ -z "${2:-}" ]]; then
+        echo "❌ Error: --promise requires a text argument" >&2
+        echo "" >&2
+        echo "   Valid examples:" >&2
+        echo "     --promise 'DONE'" >&2
+        echo "     --promise 'TASK COMPLETE'" >&2
+        echo "     --promise 'All tests passing'" >&2
+        echo "" >&2
+        echo "   You provided: --promise (with no text)" >&2
+        echo "" >&2
+        echo "   Note: Multi-word promises must be quoted!" >&2
+        exit 1
+      fi
+      COMPLETION_PROMISE="$2"
+      shift 2
+      ;;
+    --from-plan)
+      FROM_PLAN=true
+      shift
+      ;;
+    *)
+      # Non-option argument - collect all as prompt parts
+      PROMPT_PARTS+=("$1")
+      shift
+      ;;
+  esac
+done
+
+# Handle --from-plan
+if [[ "$FROM_PLAN" == "true" ]]; then
+  if [[ ! -f "$PLAN_FILE" ]]; then
+    echo "❌ Error: Plan file not found at $PLAN_FILE" >&2
+    echo "" >&2
+    echo "   Run /dev-plan first to generate a plan, or provide a prompt directly." >&2
+    echo "" >&2
+    echo "   Examples:" >&2
+    echo "     /dev-plan Build a REST API for todos" >&2
+    echo "     /dev-loop --from-plan" >&2
+    exit 1
+  fi
+  PROMPT=$(cat "$PLAN_FILE")
+  echo "📋 Using plan from: $PLAN_FILE"
+else
+  # Join all prompt parts with spaces
+  PROMPT="${PROMPT_PARTS[*]}"
+fi
+
+# Validate prompt is non-empty
+if [[ -z "$PROMPT" ]]; then
+  echo "❌ Error: No prompt provided" >&2
+  echo "" >&2
+  echo "   Dev loop needs a task description to work on." >&2
+  echo "" >&2
+  echo "   Examples:" >&2
+  echo "     /dev-loop Build a REST API for todos" >&2
+  echo "     /dev-loop Fix the auth bug --max-iterations 20" >&2
+  echo "     /dev-loop --from-plan" >&2
+  echo "" >&2
+  echo "   For all options: /dev-loop --help" >&2
+  exit 1
+fi
+
+# Create state file for stop hook (markdown with YAML frontmatter)
+mkdir -p .claude
+
+# Quote completion promise for YAML
+COMPLETION_PROMISE_YAML="\"$COMPLETION_PROMISE\""
+
+cat > .claude/dev-loop.local.md <<EOF
+---
+active: true
+iteration: 1
+max_iterations: $MAX_ITERATIONS
+completion_promise: $COMPLETION_PROMISE_YAML
+started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+---
+
+$PROMPT
+EOF
+
+# Output setup message
+cat <<EOF
+🔄 Dev loop activated!
+
+Iteration: 1
+Max iterations: $(if [[ $MAX_ITERATIONS -gt 0 ]]; then echo $MAX_ITERATIONS; else echo "unlimited"; fi)
+Completion promise: $COMPLETION_PROMISE
+
+To complete: output <promise>$COMPLETION_PROMISE</promise>
+(ONLY when task is COMPLETE - do not lie to exit!)
+
+To monitor: head -10 .claude/dev-loop.local.md
+To cancel: /cancel-dev
+
+🔄
+EOF
+
+# Output the initial prompt
+echo ""
+echo "$PROMPT"

package/packs/dev-loop/skills/tdd-planner/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: tdd-planner
+description: This skill should be used when the user asks to "plan a feature", "prepare for dev loop", "structure TDD approach", "break down this task", "create development plan", or when generating structured prompts for iterative development. Creates dev-loop-ready plans with TDD phases, file tables, code snippets, and framework-specific guidance.
+---
+
+# TDD Planner
+
+Generate high-quality, structured development plans following Test-Driven Development principles for use with the dev-loop command.
+
+## Quality Standard
+
+Every plan must meet this checklist before saving:
+
+- [ ] Context lists **specific items** to work on (not just "the feature")
+- [ ] Success criteria are **measurable** (numbers, specific behaviors)
+- [ ] **Every task** has a file path
+- [ ] **Code snippets** show implementation structure
+- [ ] Verification has **expected output** (PASS/FAIL + why)
+- [ ] Self-correction is **phase-specific**, not generic
+- [ ] **Files to Modify** table exists
+- [ ] **New Files to Create** table exists
+- [ ] Stuck handling is **framework/task-specific**
+
+**Reference:** See `references/good-example.md` for expected quality.
+
+## Activation Triggers
+
+This skill activates when:
+- Planning a feature for iterative development
+- Preparing prompts for dev-loop execution
+- Breaking down complex tasks into TDD phases
+- Creating structured development workflows
+
+## Core Principles
+
+1. **Specificity Over Vagueness** - File paths, code snippets, measurable outcomes
+2. **Iteration Over Perfection** - Expect multiple passes, not first-draft solutions
+3. **Failures as Data** - Red phase tests MUST fail first
+4. **Framework Awareness** - Use correct patterns for detected framework
+
+## Required Plan Sections
+
+### 1. Context
+
+```markdown
+## Context
+
+- **Framework**: Flutter / Django / Next.js / etc.
+- **Current State**: What exists now
+- **Test Command**: `flutter test` / `pytest` / etc.
+- **Lint Command**: `flutter analyze` / `ruff check .` / etc.
+- **Items to Work On**:
+  - `ComponentA` (description)
+  - `ComponentB` (description)
+```
+
+### 2. Success Criteria (Measurable)
+
+```markdown
+## Success Criteria
+
+- [ ] Login returns JWT token (specific behavior)
+- [ ] 81+ tests pass (quantitative)
+- [ ] Invalid credentials return 401 (negative case)
+- [ ] All tests pass (`flutter test`)
+- [ ] Linter clean (`flutter analyze`)
+```
+
+### 3. File Tables (Required)
+
+```markdown
+## Files to Modify
+
+| File | Action |
+|------|--------|
+| `lib/main.dart` | Replace MultiProvider with ProviderScope |
+| `pubspec.yaml` | Add flutter_riverpod dependency |
+
+## New Files to Create
+
+| File | Purpose |
+|------|---------|
+| `lib/providers/auth_provider.dart` | Riverpod auth state |
+| `test/providers/auth_test.dart` | Auth provider tests |
+```
+
+### 4. Phases with Code Snippets
+
+```markdown
+### Phase 2: Green - Implement Auth Provider
+
+**Goal:** Create Riverpod provider that passes tests
+
+**Tasks:**
+- [ ] Create `lib/providers/auth_provider.dart`:
+  - StateNotifierProvider with AuthNotifier
+  - Methods: login(), logout(), checkAuth()
+  - State: AuthState (authenticated, user, token)
+
+**Implementation Structure:**
+```dart
+final authProvider = StateNotifierProvider<AuthNotifier, AuthState>((ref) {
+  return AuthNotifier();
+});
+
+class AuthNotifier extends StateNotifier<AuthState> {
+  AuthNotifier() : super(AuthState.initial());
+
+  Future<void> login(String email, String password) async {
+    // Implementation
+  }
+}
+```
+
+**Verification:**
+```bash
+flutter test test/providers/auth_test.dart
+```
+**Expected:** Tests should PASS
+
+**Self-correction:**
+- If tests fail, check state class matches test expectations
+- Verify StateNotifier lifecycle is correct
+```
+
+### 5. Stuck Handling (Framework-Specific)
+
+```markdown
+## Stuck Handling
+
+### If same test keeps failing:
+1. Read the exact error message
+2. Check if ProviderScope wraps the widget tree
+3. Verify ref.watch vs ref.read usage
+4. Check state class matches expected structure
+
+### If app won't start:
+1. Check ProviderScope is at app root
+2. Verify no circular provider dependencies
+3. Check async initialization is handled
+
+### Alternative approaches if blocked:
+1. Keep hybrid approach temporarily (both Provider and Riverpod)
+2. Migrate one screen at a time
+3. Use ChangeNotifierProvider adapter for gradual migration
+```
+
+## Framework Detection
+
+**Package manager auto-detection** (defaults to `bun`):
+- `bun.lockb` → bun
+- `pnpm-lock.yaml` → pnpm
+- `yarn.lock` → yarn
+- `package-lock.json` → npm
+- No lockfile → bun (default)
+
+**Auto-detected frameworks (17+):**
+
+| Category | Framework | Detection | Test | Lint |
+|----------|-----------|-----------|------|------|
+| **Mobile** | Flutter | `pubspec.yaml` | `flutter test` | `flutter analyze` |
+| | React Native | `react-native` in package.json | `${PM} test` | `${PM} run lint` |
+| **Python** | Django | `manage.py` | `pytest` | `ruff check .` |
+| | FastAPI | `fastapi` in pyproject.toml | `pytest` | `ruff check .` |
+| | Flask | `flask` in pyproject.toml | `pytest` | `ruff check .` |
+| **Node.js** | NestJS | `@nestjs/core` | `${PM} test` | `${PM} run lint` |
+| | Next.js | `next` | `${PM} test` | `${PM} run lint` |
+| | Nuxt.js | `nuxt` | `${PM} test` | `${PM} run lint` |
+| | Hono | `hono` | `bun test` | `bun run lint` |
+| | Express | `express` | `${PM} test` | `${PM} run lint` |
+| | TanStack | `@tanstack/react-router` | `bun test` | `bun run lint` |
+| **Systems** | Go | `go.mod` | `go test ./...` | `golangci-lint run` |
+| | Rust | `Cargo.toml` | `cargo test` | `cargo clippy` |
+| **Web** | Rails | `rails` in Gemfile | `bundle exec rspec` | `bundle exec rubocop` |
+| | Laravel | `laravel` in composer.json | `php artisan test` | `./vendor/bin/pint` |
+
+`${PM}` = detected package manager (bun/pnpm/yarn/npm)
+
+**Custom frameworks:**
+
+```bash
+/dev-plan "Build API" --framework elixir --test-cmd "mix test" --lint-cmd "mix credo"
+/dev-plan "Add feature" --test-cmd "make test" --lint-cmd "make lint"
+```
+
+## Phase Generation Rules
+
+### For New Features
+1. **Red**: Write tests for the feature interface (expect FAIL)
+2. **Green**: Implement minimum code to pass (include code snippet)
+3. **Refactor**: Clean up, add types, documentation
+
+### For Bug Fixes
+1. **Red**: Write test that reproduces the bug (should fail)
+2. **Green**: Fix the bug (test passes)
+3. **Refactor**: Ensure no regression, clean up
+
+### For Refactoring/Migration
+1. **Red**: Ensure existing tests pass (baseline)
+2. **Green**: Apply changes incrementally
+3. **Refactor**: Verify tests still pass after each change
+
+## Task Detail Pattern
+
+**Bad Task:**
+```markdown
+- [ ] Create login view
+```
+
+**Good Task:**
+```markdown
+- [ ] Create `lib/screens/login_screen.dart`:
+  - ConsumerStatefulWidget
+  - Form with email/password TextFormFields
+  - Calls `ref.read(authProvider.notifier).login()`
+  - Shows loading state during auth
+  - Navigates to home on success
+  - Shows error snackbar on failure
+```
+
+## Anti-Patterns to Avoid
+
+| Don't | Do Instead |
+|-------|------------|
+| "Implement the feature" | "Create `lib/auth/login.dart` with ConsumerWidget" |
+| "If it fails, try again" | "If tests pass in Red, they're too weak - add assertions" |
+| Missing code snippets | Show actual structure with types and patterns |
+| No file tables | Always list files to modify/create |
+| "App works well" | "Login returns JWT, logout invalidates token, 401 on bad creds" |
+| Generic stuck handling | Framework-specific: "Check ProviderScope wraps app" |
+
+## Usage
+
+### Generate Plan
+```bash
+/dev-plan "Migrate to Riverpod" --framework flutter
+/dev-plan "Add user authentication" --interactive
+```
+
+### Execute Plan
+```bash
+/dev-loop --from-plan
+```
+
+## References
+
+- `references/plan-template.md` - Full template with all variables
+- `references/good-example.md` - High-quality Flutter migration example
+- `references/framework-patterns.md` - Framework-specific patterns