@smicolon/ai-kit 0.0.1 → 0.1.1

package/packs/dev-loop/commands/dev-loop.md

@@ -0,0 +1,72 @@
+---
+name: dev-loop
+description: "Start dev loop for iterative development"
+argument-hint: '"Your prompt here" [--from-plan] [--max-iterations N] [--promise TEXT]'
+allowed-tools: ["Bash(${CLAUDE_PLUGIN_ROOT}/scripts/setup-dev-loop.sh:*)"]
+---
+
+```!
+"${CLAUDE_PLUGIN_ROOT}/scripts/setup-dev-loop.sh" $ARGUMENTS
+```
+
+# Dev Loop Started
+
+You are now in a development loop. The loop will continue until you output `<promise>DONE</promise>` or reach the maximum iterations (default: 50).
+
+## How It Works
+
+1. **You receive a prompt** - Work on the task iteratively
+2. **Complete work** - When done, output `<promise>DONE</promise>`
+3. **Loop continues** - If you don't output the promise, you'll get the prompt again
+4. **Max safety** - After 50 iterations, the loop stops automatically
+
+## Completion
+
+When your work is complete, output:
+
+```
+<promise>DONE</promise>
+```
+
+This ends the loop successfully.
+
+## Flags
+
+```bash
+# Use existing plan from /dev-plan command
+/dev-loop --from-plan
+
+# Override max iterations (default: 50)
+/dev-loop "Build feature X" --max-iterations 30
+
+# Custom completion promise (default: DONE)
+/dev-loop "Refactor module Y" --promise "REFACTOR_COMPLETE"
+```
+
+## Recommended Workflow
+
+For best results, use the planning phase first:
+
+```bash
+# 1. Generate structured TDD plan
+/dev-plan "Build user authentication"
+
+# 2. Review and edit .claude/dev-plan.local.md if needed
+
+# 3. Execute with structured plan
+/dev-loop --from-plan
+```
+
+This creates a plan with:
+- TDD phases (Red-Green-Refactor)
+- Clear verification commands
+- Self-correction rules
+- Stuck handling
+
+## Tips
+
+- Use `/dev-plan` first for complex tasks
+- Break complex tasks into smaller steps
+- Test your work before declaring completion
+- Use `<promise>DONE</promise>` only when truly finished
+- If stuck, the loop will eventually timeout at max iterations

package/packs/dev-loop/commands/dev-plan.md

@@ -0,0 +1,351 @@
+---
+name: dev-plan
+description: Generate a structured TDD plan for dev-loop execution
+argument-hint: '"Your goal" [--framework NAME] [--test-cmd "cmd"] [--lint-cmd "cmd"] [--interactive]'
+allowed-tools: ["Read", "Write", "Glob", "Grep", "Bash", "AskUserQuestion"]
+---
+
+# Create Development Plan
+
+Generate a high-quality, structured TDD plan for use with `/dev-loop --from-plan`.
+
+**Quality Standard:** See `references/good-example.md` for the expected output quality.
+
+---
+
+## Steps
+
+### 1. Parse Arguments
+
+Extract from user input:
+- **Goal**: The main objective (required)
+- **--framework**: Override auto-detection (optional, any framework name)
+- **--test-cmd**: Custom test command (optional, overrides auto-detect)
+- **--lint-cmd**: Custom lint command (optional, overrides auto-detect)
+- **--interactive**: Ask clarifying questions (optional)
+
+### 2. Detect Framework
+
+**Priority order:**
+1. Use `--test-cmd` and `--lint-cmd` if provided (custom stack)
+2. Use `--framework` if specified
+3. Auto-detect from project files
+
+**Auto-detection (first match wins):**
+
+```bash
+# Mobile
+[ -f "pubspec.yaml" ] && grep -q "flutter:" pubspec.yaml && echo "flutter"
+[ -f "package.json" ] && grep -q "react-native" package.json && echo "react-native"
+
+# Python
+[ -f "manage.py" ] && echo "django"
+[ -f "pyproject.toml" ] && grep -q "fastapi" pyproject.toml && echo "fastapi"
+[ -f "pyproject.toml" ] && grep -q "flask" pyproject.toml && echo "flask"
+
+# Node.js
+grep -q "@nestjs/core" package.json 2>/dev/null && echo "nestjs"
+grep -q '"next"' package.json 2>/dev/null && echo "nextjs"
+grep -q '"nuxt"' package.json 2>/dev/null && echo "nuxtjs"
+grep -q '"hono"' package.json 2>/dev/null && echo "hono"
+grep -q '"express"' package.json 2>/dev/null && echo "express"
+grep -q '"@tanstack/react-router"' package.json 2>/dev/null && echo "tanstack"
+
+# Go
+[ -f "go.mod" ] && echo "go"
+
+# Rust
+[ -f "Cargo.toml" ] && echo "rust"
+
+# Ruby
+[ -f "Gemfile" ] && grep -q "rails" Gemfile && echo "rails"
+
+# PHP
+[ -f "composer.json" ] && grep -q "laravel" composer.json && echo "laravel"
+
+# Generic fallbacks
+[ -f "pyproject.toml" ] || [ -f "requirements.txt" ] && echo "python"
+[ -f "package.json" ] && echo "node"
+```
+
+**Package Manager Detection (for Node.js projects):**
+
+```bash
+# Detect package manager (first match wins)
+[ -f "bun.lockb" ] && PM="bun"
+[ -f "pnpm-lock.yaml" ] && PM="pnpm"
+[ -f "yarn.lock" ] && PM="yarn"
+[ -f "package-lock.json" ] && PM="npm"
+# Default to bun if no lockfile
+[ -z "$PM" ] && PM="bun"
+```
+
+**Framework Commands Table:**
+
+Use `${PM}` for the detected package manager (defaults to `bun`).
+
+| Framework | Test Command | Lint Command |
+|-----------|--------------|--------------|
+| **Mobile** | | |
+| Flutter | `flutter test` | `flutter analyze` |
+| React Native | `${PM} test` | `${PM} run lint` |
+| **Python** | | |
+| Django | `pytest --tb=short` | `ruff check .` |
+| FastAPI | `pytest --tb=short` | `ruff check .` |
+| Flask | `pytest --tb=short` | `ruff check .` |
+| Python (generic) | `pytest` | `ruff check .` |
+| **Node.js** | | |
+| NestJS | `${PM} test` | `${PM} run lint` |
+| Next.js | `${PM} test` | `${PM} run lint` |
+| Nuxt.js | `${PM} test` | `${PM} run lint` |
+| Hono | `bun test` | `bun run lint` |
+| Express | `${PM} test` | `${PM} run lint` |
+| TanStack | `bun test` | `bun run lint` |
+| Node (generic) | `${PM} test` | `${PM} run lint` |
+| **Systems** | | |
+| Go | `go test ./...` | `golangci-lint run` |
+| Rust | `cargo test` | `cargo clippy` |
+| **Web Frameworks** | | |
+| Rails | `bundle exec rspec` | `bundle exec rubocop` |
+| Laravel | `php artisan test` | `./vendor/bin/pint` |
+
+**Unknown Framework Handling:**
+
+If framework is unknown or not detected:
+1. Check for common test files (`*_test.go`, `*_spec.rb`, `*.test.ts`)
+2. Check package.json/pyproject.toml for test scripts
+3. If `--interactive`, ask user for test/lint commands
+4. Default: prompt user to specify `--test-cmd` and `--lint-cmd`
+
+### 3. Deep Codebase Analysis
+
+**CRITICAL:** Analyze the codebase thoroughly before planning.
+
+Read and understand:
+- [ ] Existing test files (understand testing patterns)
+- [ ] Related modules/components (understand current structure)
+- [ ] Configuration files (package.json, pubspec.yaml, etc.)
+- [ ] Similar implementations (reuse patterns)
+- [ ] Documentation (CLAUDE.md, README.md)
+
+Identify specifically:
+- **Current State**: What exists now that relates to the goal?
+- **Work Items**: List each specific item to create/modify
+- **Files to Modify**: Which existing files need changes?
+- **New Files**: Which files need to be created?
+- **Dependencies**: What packages/imports are needed?
+
+### 4. Generate File Tables
+
+**REQUIRED:** Every plan must include these tables.
+
+#### Files to Modify
+
+| File | Action |
+|------|--------|
+| `path/to/file.ext` | Description of changes |
+
+#### New Files to Create
+
+| File | Purpose |
+|------|---------|
+| `path/to/new/file.ext` | What this file does |
+
+### 5. Create TDD Phases
+
+For each component, create Red-Green-Refactor phases:
+
+#### Phase Structure
+
+```markdown
+### Phase N: {{TYPE}} - {{COMPONENT}}
+
+**Goal:** {{SPECIFIC_GOAL}}
+
+**Tasks:**
+- [ ] {{TASK}} in `{{FILE_PATH}}`:
+  - {{DETAIL_1}}
+  - {{DETAIL_2}}
+
+**Implementation Structure:**
+```{{language}}
+// Show actual code structure expected
+```
+
+**Verification:**
+```bash
+{{COMMAND}}
+```
+**Expected:** {{OUTCOME}} (e.g., "should FAIL - tests don't exist yet")
+
+**Self-correction:**
+- {{PHASE_SPECIFIC_TIP}}
+```
+
+#### Phase Types
+
+**Red Phase:**
+- Write failing tests first
+- Expected: Tests FAIL (implementation doesn't exist)
+- Self-correction: "If tests pass, they're not testing the right thing"
+
+**Green Phase:**
+- Implement minimum code to pass tests
+- Include code snippet showing structure
+- Expected: Tests PASS
+- Self-correction: "If tests fail, read error, fix implementation (not test)"
+
+**Refactor Phase:**
+- Clean up code, add types, documentation
+- Expected: Tests still PASS, lint clean
+- Self-correction: "If tests fail, refactoring broke something - revert"
+
+### 6. Define Success Criteria
+
+Measurable criteria with specifics:
+
+```markdown
+## Success Criteria
+
+- [ ] {{SPECIFIC_BEHAVIOR}} (e.g., "Login returns JWT token")
+- [ ] {{QUANTITATIVE}} (e.g., "81+ tests pass")
+- [ ] {{NEGATIVE_CASE}} (e.g., "Invalid credentials return 401")
+- [ ] All tests pass (`{{TEST_COMMAND}}`)
+- [ ] Linter clean (`{{LINT_COMMAND}}`)
+```
+
+### 7. Add Acceptance Criteria (Optional)
+
+For user-facing features, add Given/When/Then:
+
+```markdown
+## Acceptance Criteria
+
+### 1. User can login with valid credentials
+- **Given**: Valid email and password
+- **When**: POST /api/auth/login
+- **Then**: Returns 200 + JWT token
+
+### 2. Invalid credentials rejected
+- **Given**: Wrong password
+- **When**: POST /api/auth/login
+- **Then**: Returns 401 + error message
+```
+
+### 8. Add Stuck Handling
+
+**REQUIRED:** Framework-specific stuck handling, not generic.
+
+```markdown
+## Stuck Handling
+
+### If same test keeps failing:
+1. Read the exact error message (not just "test failed")
+2. Check if {{FRAMEWORK_SPECIFIC_THING}} is configured correctly
+3. Verify {{COMMON_MISTAKE_FOR_THIS_FRAMEWORK}}
+4. Check ProviderScope/dependency injection/imports
+
+### If app/server won't start:
+1. Check {{ENTRY_POINT_FILE}}
+2. Verify {{INITIALIZATION_ORDER}}
+3. Look for circular dependencies
+
+### Alternative approaches if blocked:
+1. {{SIMPLER_APPROACH}}
+2. {{INCREMENTAL_APPROACH}}
+3. {{FALLBACK_APPROACH}}
+```
+
+### 9. Quality Checklist
+
+Before saving, verify the plan meets quality standards:
+
+- [ ] Context lists **specific items** to work on
+- [ ] Success criteria are **measurable**
+- [ ] **Every task** has a file path
+- [ ] **Code snippets** show implementation structure
+- [ ] Verification has **expected output** with reasoning
+- [ ] Self-correction is **phase-specific**
+- [ ] **Files to Modify** table exists
+- [ ] **New Files to Create** table exists
+- [ ] Stuck handling is **framework-specific**
+
+### 10. Save Plan
+
+Save to `.claude/dev-plan.local.md`:
+
+```markdown
+# Dev Loop Plan: {{GOAL}}
+
+Generated: {{TIMESTAMP}}
+
+---
+
+## Context
+[Framework, test/lint commands, work items...]
+
+## Success Criteria
+[Measurable outcomes...]
+
+## Acceptance Criteria (if applicable)
+[Given/When/Then...]
+
+## Files to Modify
+[Table...]
+
+## New Files to Create
+[Table...]
+
+## Progress Tracking
+[Instructions...]
+
+## Phases
+[Red/Green/Refactor phases with code snippets...]
+
+## Final Verification
+[Combined verification command...]
+
+## Completion
+When ALL criteria met: <promise>DONE</promise>
+
+## Stuck Handling
+[Framework-specific tips...]
+```
+
+### 11. Confirm with User
+
+After generating:
+- Show plan summary
+- Ask: "Plan saved to `.claude/dev-plan.local.md`. Start with `/dev-loop --from-plan`?"
+
+---
+
+## Interactive Mode (--interactive)
+
+When `--interactive` flag is present:
+
+1. "What's the current state of this feature?" (understand starting point)
+2. "Which specific components need to be created?" (scope)
+3. "Are there existing patterns I should follow?" (consistency)
+4. "What's the most important acceptance criterion?" (priority)
+5. "Any known edge cases or risks?" (robustness)
+
+---
+
+## Anti-Patterns to Avoid
+
+| Don't | Do Instead |
+|-------|------------|
+| "Implement the feature" | "Create `lib/auth/login.dart` with ConsumerWidget" |
+| "If it fails, fix it" | "If tests pass in Red phase, tests aren't specific enough" |
+| Missing code snippets | Show actual structure with types and patterns |
+| No file tables | Always list files to modify/create |
+| "App works" | "Login returns JWT, logout invalidates token" |
+
+---
+
+## References
+
+- `references/plan-template.md` - Full template with variables
+- `references/good-example.md` - High-quality example plan
+- `references/framework-patterns.md` - Framework-specific patterns

package/packs/dev-loop/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "description": "Dev loop Stop hook for autonomous iterative development",
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/stop-hook.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/packs/dev-loop/hooks/stop-hook.sh

@@ -0,0 +1,178 @@
+#!/bin/bash
+
+# Dev Loop Stop Hook
+# Based on Ralph Wiggum pattern from official plugin
+# Prevents session exit when a dev-loop is active
+# Feeds Claude's output back as input to continue the loop
+
+set -euo pipefail
+
+# Read hook input from stdin (advanced stop hook API)
+HOOK_INPUT=$(cat)
+
+# Check if dev-loop is active
+STATE_FILE=".claude/dev-loop.local.md"
+
+if [[ ! -f "$STATE_FILE" ]]; then
+  # No active loop - allow exit
+  exit 0
+fi
+
+# Parse markdown frontmatter (YAML between ---) and extract values
+FRONTMATTER=$(sed -n '/^---$/,/^---$/{ /^---$/d; p; }' "$STATE_FILE")
+ITERATION=$(echo "$FRONTMATTER" | grep '^iteration:' | sed 's/iteration: *//')
+MAX_ITERATIONS=$(echo "$FRONTMATTER" | grep '^max_iterations:' | sed 's/max_iterations: *//')
+# Extract completion_promise and strip surrounding quotes if present
+COMPLETION_PROMISE=$(echo "$FRONTMATTER" | grep '^completion_promise:' | sed 's/completion_promise: *//' | sed 's/^"\(.*\)"$/\1/')
+
+# Validate numeric fields before arithmetic operations
+if [[ ! "$ITERATION" =~ ^[0-9]+$ ]]; then
+  echo "⚠️  Dev loop: State file corrupted" >&2
+  echo "   File: $STATE_FILE" >&2
+  echo "   Problem: 'iteration' field is not a valid number (got: '$ITERATION')" >&2
+  echo "" >&2
+  echo "   This usually means the state file was manually edited or corrupted." >&2
+  echo "   Dev loop is stopping. Run /dev-loop again to start fresh." >&2
+  rm "$STATE_FILE"
+  exit 0
+fi
+
+if [[ ! "$MAX_ITERATIONS" =~ ^[0-9]+$ ]]; then
+  echo "⚠️  Dev loop: State file corrupted" >&2
+  echo "   File: $STATE_FILE" >&2
+  echo "   Problem: 'max_iterations' field is not a valid number (got: '$MAX_ITERATIONS')" >&2
+  echo "" >&2
+  echo "   This usually means the state file was manually edited or corrupted." >&2
+  echo "   Dev loop is stopping. Run /dev-loop again to start fresh." >&2
+  rm "$STATE_FILE"
+  exit 0
+fi
+
+# Check if max iterations reached
+if [[ $MAX_ITERATIONS -gt 0 ]] && [[ $ITERATION -ge $MAX_ITERATIONS ]]; then
+  echo "🛑 Dev loop: Max iterations ($MAX_ITERATIONS) reached."
+  rm "$STATE_FILE"
+  exit 0
+fi
+
+# Get transcript path from hook input
+TRANSCRIPT_PATH=$(echo "$HOOK_INPUT" | jq -r '.transcript_path')
+
+if [[ ! -f "$TRANSCRIPT_PATH" ]]; then
+  echo "⚠️  Dev loop: Transcript file not found" >&2
+  echo "   Expected: $TRANSCRIPT_PATH" >&2
+  echo "   This is unusual and may indicate a Claude Code internal issue." >&2
+  echo "   Dev loop is stopping." >&2
+  rm "$STATE_FILE"
+  exit 0
+fi
+
+# Read last assistant message from transcript (JSONL format - one JSON per line)
+# First check if there are any assistant messages
+if ! grep -q '"role":"assistant"' "$TRANSCRIPT_PATH"; then
+  echo "⚠️  Dev loop: No assistant messages found in transcript" >&2
+  echo "   Transcript: $TRANSCRIPT_PATH" >&2
+  echo "   This is unusual and may indicate a transcript format issue" >&2
+  echo "   Dev loop is stopping." >&2
+  rm "$STATE_FILE"
+  exit 0
+fi
+
+# Extract last assistant message with explicit error handling
+LAST_LINE=$(grep '"role":"assistant"' "$TRANSCRIPT_PATH" | tail -1)
+if [[ -z "$LAST_LINE" ]]; then
+  echo "⚠️  Dev loop: Failed to extract last assistant message" >&2
+  echo "   Dev loop is stopping." >&2
+  rm "$STATE_FILE"
+  exit 0
+fi
+
+# Parse JSON with error handling
+LAST_OUTPUT=$(echo "$LAST_LINE" | jq -r '
+  .message.content |
+  map(select(.type == "text")) |
+  map(.text) |
+  join("\n")
+' 2>&1)
+
+# Check if jq succeeded
+if [[ $? -ne 0 ]]; then
+  echo "⚠️  Dev loop: Failed to parse assistant message JSON" >&2
+  echo "   Error: $LAST_OUTPUT" >&2
+  echo "   This may indicate a transcript format issue" >&2
+  echo "   Dev loop is stopping." >&2
+  rm "$STATE_FILE"
+  exit 0
+fi
+
+if [[ -z "$LAST_OUTPUT" ]]; then
+  echo "⚠️  Dev loop: Assistant message contained no text content" >&2
+  echo "   Dev loop is stopping." >&2
+  rm "$STATE_FILE"
+  exit 0
+fi
+
+# Check for completion promise (only if set)
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  # Extract text from <promise> tags using Perl for multiline support
+  # -0777 slurps entire input, s flag makes . match newlines
+  # .*? is non-greedy (takes FIRST tag), whitespace normalized
+  PROMISE_TEXT=$(echo "$LAST_OUTPUT" | perl -0777 -pe 's/.*?<promise>(.*?)<\/promise>.*/$1/s; s/^\s+|\s+$//g; s/\s+/ /g' 2>/dev/null || echo "")
+
+  # Use = for literal string comparison (not pattern matching)
+  # == in [[ ]] does glob pattern matching which breaks with *, ?, [ characters
+  if [[ -n "$PROMISE_TEXT" ]] && [[ "$PROMISE_TEXT" = "$COMPLETION_PROMISE" ]]; then
+    echo "✅ Dev loop: Detected <promise>$COMPLETION_PROMISE</promise>"
+    rm "$STATE_FILE"
+    exit 0
+  fi
+fi
+
+# Not complete - continue loop with SAME PROMPT
+NEXT_ITERATION=$((ITERATION + 1))
+
+# Extract prompt (everything after the closing ---)
+# Skip first --- line, skip until second --- line, then print everything after
+# Use i>=2 instead of i==2 to handle --- in prompt content
+PROMPT_TEXT=$(awk '/^---$/{i++; next} i>=2' "$STATE_FILE")
+
+if [[ -z "$PROMPT_TEXT" ]]; then
+  echo "⚠️  Dev loop: State file corrupted or incomplete" >&2
+  echo "   File: $STATE_FILE" >&2
+  echo "   Problem: No prompt text found" >&2
+  echo "" >&2
+  echo "   This usually means:" >&2
+  echo "     • State file was manually edited" >&2
+  echo "     • File was corrupted during writing" >&2
+  echo "" >&2
+  echo "   Dev loop is stopping. Run /dev-loop again to start fresh." >&2
+  rm "$STATE_FILE"
+  exit 0
+fi
+
+# Update iteration in frontmatter (portable across macOS and Linux)
+# Create temp file, then atomically replace
+TEMP_FILE="${STATE_FILE}.tmp.$$"
+sed "s/^iteration: .*/iteration: $NEXT_ITERATION/" "$STATE_FILE" > "$TEMP_FILE"
+mv "$TEMP_FILE" "$STATE_FILE"
+
+# Build system message with iteration count and completion promise info
+if [[ "$COMPLETION_PROMISE" != "null" ]] && [[ -n "$COMPLETION_PROMISE" ]]; then
+  SYSTEM_MSG="🔄 Dev loop iteration $NEXT_ITERATION of $MAX_ITERATIONS | To stop: output <promise>$COMPLETION_PROMISE</promise> (ONLY when task is COMPLETE - do not lie to exit!)"
+else
+  SYSTEM_MSG="🔄 Dev loop iteration $NEXT_ITERATION | No completion promise set - loop runs until max iterations"
+fi
+
+# Output JSON to block the stop and feed prompt back
+# The "reason" field contains the prompt that will be sent back to Claude
+jq -n \
+  --arg prompt "$PROMPT_TEXT" \
+  --arg msg "$SYSTEM_MSG" \
+  '{
+    "decision": "block",
+    "reason": $prompt,
+    "systemMessage": $msg
+  }'
+
+# Exit 0 for successful hook execution
+exit 0