zaileys 2.2.7 → 3.0.0

package/.gsd/adapters/GEMINI.md

@@ -0,0 +1,92 @@
+# Gemini Adapter
+
+> **Everything in this file is optional.**
+> For canonical rules, see [PROJECT_RULES.md](../PROJECT_RULES.md).
+
+This adapter provides optional enhancements for Gemini models in Antigravity.
+
+---
+
+## Model Selection
+
+### Flash vs Pro
+
+| Model Type | Best For |
+|------------|----------|
+| **Flash** | Quick iterations, simple edits, high-volume tasks |
+| **Pro** | Complex planning, large refactors, deep analysis |
+
+**Default recommendation:** Start with Pro for planning, switch to Flash for implementation.
+
+---
+
+## Context Window Optimization
+
+Gemini models often have large context windows. Optimize usage:
+
+1. **Load full files strategically** — Large context allows it, but still prefer search-first
+2. **Batch related files** — Group related code in single context load
+3. **Clear separation** — Use XML tags to separate file contents
+
+### Context Loading Pattern
+
+```xml
+<file path="src/auth/login.ts">
+{file contents}
+</file>
+
+<file path="src/auth/types.ts">
+{file contents}
+</file>
+
+<task>
+{your task here}
+</task>
+```
+
+---
+
+## Grounding
+
+When available, use grounding for:
+
+- Checking latest documentation
+- Verifying API behaviors
+- Validating external service states
+
+**Not for:** Code implementation (use codebase content).
+
+---
+
+## Code Execution
+
+If code execution sandbox is available:
+
+- Use for verification commands
+- Use for testing snippets
+- Document outputs in SUMMARY.md
+
+---
+
+## Integration with .gemini/
+
+The `.gemini/GEMINI.md` file can reference this adapter:
+
+```markdown
+# In .gemini/GEMINI.md
+
+For canonical rules, see .gsd/PROJECT_RULES.md.
+For Gemini-specific tips, see .gsd/adapters/GEMINI.md.
+```
+
+---
+
+## Anti-Patterns
+
+❌ **Loading entire codebase** — Even with large context, quality degrades
+❌ **Ignoring context thresholds** — 50% is still the quality boundary
+❌ **Skipping STATE.md** — Context window size doesn't replace persistent state
+
+---
+
+*See PROJECT_RULES.md for canonical requirements.*

package/.gsd/adapters/GPT_OSS.md

@@ -0,0 +1,130 @@
+# GPT & Open Source Models Adapter
+
+> **Everything in this file is optional.**
+> For canonical rules, see [PROJECT_RULES.md](../PROJECT_RULES.md).
+
+This adapter provides guidance for GPT models and open-source alternatives.
+
+---
+
+## GPT Models
+
+### Model Selection
+
+| Model | Best For |
+|-------|----------|
+| **GPT-4o** | Balanced speed and quality, multimodal |
+| **GPT-4 Turbo** | Complex reasoning, large context |
+| **GPT-3.5** | Fast iterations, simple tasks |
+
+---
+
+### Function Calling
+
+When function calling is available:
+
+```json
+{
+  "name": "run_verification",
+  "description": "Execute a verification command",
+  "parameters": {
+    "command": "npm test",
+    "expected": "All tests pass"
+  }
+}
+```
+
+**Use for:**
+- Verification commands
+- File operations
+- External service checks
+
+---
+
+### Context Optimization
+
+GPT models may have smaller context than some alternatives:
+
+1. **Be selective** — Only load necessary files
+2. **Use search-first** — Critical for context efficiency
+3. **Summarize large files** — Extract relevant sections only
+
+---
+
+## Open Source Models
+
+### General Guidance
+
+Open source models vary widely. General tips:
+
+| Consideration | Guidance |
+|---------------|----------|
+| **Context length** | Verify model's limit; adjust file loading |
+| **Instruction following** | Use explicit, structured prompts |
+| **Code quality** | May need more verification steps |
+| **Speed** | Varies by hardware; plan accordingly |
+
+---
+
+### Local Deployment
+
+For locally-running models:
+
+1. **Resource planning** — Ensure adequate GPU/RAM
+2. **Latency expectations** — Adjust iteration speed assumptions
+3. **Fallback strategy** — Document when to switch to cloud models
+
+---
+
+### Recommended Patterns
+
+**Structured prompts work better:**
+
+```markdown
+## Task
+{clear task description}
+
+## Context
+{relevant code snippets}
+
+## Expected Output
+{what you need back}
+
+## Constraints
+{any limitations or requirements}
+```
+
+---
+
+## Shorter Context Strategies
+
+When working with limited context:
+
+1. **Aggressive search-first** — Never load full files blindly
+2. **Incremental loading** — Add context as needed, not upfront
+3. **State snapshots more frequently** — Prevent context overflow
+4. **Split large tasks** — Smaller plans, more waves
+
+---
+
+## Anti-Patterns
+
+❌ **Assuming GPT-4 context** — Verify actual model limits
+❌ **Complex nested prompts** — Keep structure flat and clear
+❌ **Ignoring model limits** — Quality crashes hard past context limit
+
+---
+
+## Model-Specific Files
+
+Not required, but if organizing:
+
+```
+.openai/           # For OpenAI API configuration
+.ollama/           # For Ollama local models
+.llm/              # Generic local LLM config
+```
+
+---
+
+*See PROJECT_RULES.md for canonical requirements.*

package/.gsd/docs/model-selection-playbook.md

@@ -0,0 +1,128 @@
+# Model Selection Playbook
+
+> Guidance for choosing models by phase and task type.
+> 
+> **No model is required.** These are recommendations, not requirements.
+
+---
+
+## Selection by Phase
+
+### Planning & Architecture
+
+**Recommended capabilities:**
+- Extended reasoning / thinking mode
+- Large context window (analyze multiple files)
+- Strong at structured output (specs, plans)
+
+**Why:** Planning requires understanding full system context and making architectural decisions.
+
+**Examples:** Models with "thinking" or "reasoning" modes, larger context variants.
+
+---
+
+### Code Implementation
+
+**Recommended capabilities:**
+- Fast iteration speed
+- Good at code completion
+- Tool/function calling (for verification commands)
+
+**Why:** Implementation involves many small changes with frequent verification cycles.
+
+**Examples:** Speed-tier models, code-specialized variants.
+
+---
+
+### Refactoring
+
+**Recommended capabilities:**
+- Large context window (see before/after)
+- Pattern recognition
+- Consistent style application
+
+**Why:** Refactoring requires maintaining consistency across large code changes.
+
+**Examples:** Standard or long-context variants.
+
+---
+
+### Debugging
+
+**Recommended capabilities:**
+- Extended reasoning (hypothesis generation)
+- Good at reading stack traces
+- Context for error patterns
+
+**Why:** Debugging requires hypothesis testing and pattern matching.
+
+**Examples:** Reasoning-focused models.
+
+---
+
+### Code Review
+
+**Recommended capabilities:**
+- Large context (review full PR diff)
+- Security pattern knowledge
+- Style consistency checking
+
+**Why:** Review requires seeing both code and context together.
+
+**Examples:** Long-context variants.
+
+---
+
+## Capability Tiers
+
+| Tier | Characteristics | Best For |
+|------|-----------------|----------|
+| **Fast** | Quick responses, lower cost | Implementation, iteration |
+| **Standard** | Balanced speed/quality | Most tasks |
+| **Reasoning** | Extended thinking, slower | Planning, debugging, architecture |
+| **Long-context** | >100k tokens | Review, refactoring |
+
+---
+
+## Anti-Patterns
+
+❌ **Using reasoning models for simple edits** — Overkill, slow, expensive
+
+❌ **Using fast models for architecture** — Insufficient depth for complex decisions
+
+❌ **Ignoring context limits** — Leads to quality degradation
+
+❌ **Forcing a specific model** — Breaks model-agnosticism
+
+---
+
+## Model Switching Mid-Session
+
+**When to switch:**
+- Context is getting polluted (approaching 50%)
+- Task type changes significantly (planning → implementation)
+- Current model struggling with task type
+
+**How to switch:**
+1. Create state snapshot
+2. Update STATE.md with current position
+3. Start fresh session with appropriate model
+4. Load STATE.md to resume
+
+---
+
+## GSD Model-Agnostic Principle
+
+GSD works with any capable LLM. The methodology compensates for model differences through:
+
+1. **Structured plans** — Reduce ambiguity
+2. **Explicit verification** — Catch errors regardless of model
+3. **State persistence** — Enable model switching
+4. **Fresh context** — Prevent accumulation issues
+
+Choose models based on task needs, not methodology requirements.
+
+---
+
+*See .gsd/PROJECT_RULES.md for canonical rules.*
+*See .gsd/docs/runbook.md for operational procedures.*

package/.gsd/docs/runbook.md

@@ -0,0 +1,296 @@
+# GSD Runbook
+
+> Operational procedures for debugging, validation, and recovery.
+
+---
+
+## Quick Commands
+
+### Status Check
+
+**PowerShell:**
+```powershell
+# Current git status
+git status
+
+# Recent commits
+git log --oneline -10
+
+# Current branch
+git branch --show-current
+```
+
+**Bash:**
+```bash
+# Current git status
+git status
+
+# Recent commits
+git log --oneline -10
+
+# Current branch
+git branch --show-current
+```
+
+---
+
+## Wave Validation
+
+### Verify Wave Completion
+
+**Before marking a wave complete:**
+
+1. All tasks have commits:
+   ```powershell
+   git log --oneline -N  # N = number of tasks in wave
+   ```
+
+2. All verifications passed (documented in SUMMARY.md)
+
+3. STATE.md updated with current position
+
+4. State snapshot created
+
+### Wave Rollback
+
+**If a wave needs to be reverted:**
+
+```powershell
+# Find commit before wave started
+git log --oneline -20
+
+# Reset to that commit (keeps changes staged)
+git reset --soft <commit-hash>
+
+# Or hard reset (discards changes)
+git reset --hard <commit-hash>
+```
+
+---
+
+## Debugging Procedures
+
+### 3-Strike Rule
+
+After 3 consecutive failed debug attempts:
+
+1. **Stop** — Don't try a 4th approach in same session
+
+2. **Document** in STATE.md:
+   ```markdown
+   ## Debug Session
+   
+   **Problem:** {description}
+   
+   **Attempts:**
+   1. {approach 1} → {result}
+   2. {approach 2} → {result}
+   3. {approach 3} → {result}
+   
+   **Hypothesis:** {current theory}
+   
+   **Recommended next:** {suggested approach}
+   ```
+
+3. **Fresh session** — Start new conversation with documented context
+
+### Log Inspection
+
+**Find relevant logs:**
+
+```powershell
+# Search for error patterns
+Select-String -Path "*.log" -Pattern "error|exception|failed" -CaseSensitive:$false
+```
+
+```bash
+# Search for error patterns
+grep -ri "error\|exception\|failed" *.log
+```
+
+---
+
+## Verification Commands
+
+### Build Verification
+
+```powershell
+# Node.js
+npm run build
+if ($LASTEXITCODE -eq 0) { Write-Host "✅ Build passed" }
+
+# Python
+python -m py_compile src/**/*.py
+```
+
+### Test Verification
+
+```powershell
+# Node.js
+npm test
+
+# Python
+pytest -v
+
+# Go
+go test ./...
+```
+
+### Lint Verification
+
+```powershell
+# Node.js
+npm run lint
+
+# Python
+ruff check .
+
+# Go
+golangci-lint run
+```
+
+---
+
+## State Recovery
+
+### From STATE.md
+
+When resuming work:
+
+1. Read STATE.md for current position
+2. Check "Last Action" for context
+3. Follow "Next Steps" to continue
+4. Verify recent commits match documented progress
+
+### From Git History
+
+If STATE.md is outdated:
+
+```powershell
+# See recent work
+git log --oneline -20
+
+# Check specific commit details
+git show <commit-hash> --stat
+
+# View file at specific commit
+git show <commit-hash>:path/to/file
+```
+
+### Context Pollution Recovery
+
+If quality is degrading mid-session:
+
+1. Create state snapshot immediately
+2. Update STATE.md with full context
+3. Commit any pending work
+4. Start fresh session
+5. Run `/resume` to reload context
+
+---
+
+## Search Commands
+
+### Find in Codebase
+
+**PowerShell:**
+```powershell
+# Find pattern in files
+Select-String -Path "src/**/*.ts" -Pattern "TODO" -Recurse
+
+# Find files by name
+Get-ChildItem -Recurse -Filter "*.config.*"
+```
+
+**Bash:**
+```bash
+# Find pattern in files (with ripgrep)
+rg "TODO" --type ts
+
+# Find pattern in files (with grep)
+grep -r "TODO" src/
+
+# Find files by name
+find . -name "*.config.*"
+```
+
+### Search-First Workflow
+
+Before reading any file:
+
+1. Search for relevant terms:
+   ```powershell
+   Select-String -Path "**/*.md" -Pattern "architecture" -Recurse
+   ```
+
+2. Identify candidate files from results
+
+3. Read only relevant sections:
+   ```powershell
+   Get-Content file.md | Select-Object -Skip 49 -First 20  # Lines 50-70
+   ```
+
+---
+
+## Common Issues
+
+### "SPEC.md not FINALIZED"
+
+**Cause:** Planning lock prevents implementation
+
+**Fix:**
+1. Open `.gsd/SPEC.md`
+2. Complete all required sections
+3. Change status to `Status: FINALIZED`
+4. Retry command
+
+### "Context degrading"
+
+**Symptoms:** Shorter responses, skipped steps, inconsistency
+
+**Fix:**
+1. Create state snapshot
+2. Commit current work
+3. Start fresh session
+4. Run `/resume`
+
+### "Commit failed"
+
+**Causes:** Staged conflicts, hook failures
+
+**Debug:**
+```powershell
+git status
+git diff --staged
+```
+
+---
+
+## Checklist Templates
+
+### Pre-Execution Checklist
+
+- [ ] SPEC.md is FINALIZED
+- [ ] ROADMAP.md has current phase
+- [ ] STATE.md loaded and understood
+- [ ] Previous wave verified complete
+
+### Post-Wave Checklist
+
+- [ ] All tasks committed
+- [ ] Verifications documented
+- [ ] STATE.md updated
+- [ ] State snapshot created
+- [ ] No uncommitted changes
+
+### Session End Checklist
+
+- [ ] Current work committed
+- [ ] STATE.md has "Next Steps"
+- [ ] JOURNAL.md updated (if milestone)
+- [ ] No loose ends
+
+---
+
+*See .gsd/PROJECT_RULES.md for canonical rules.*
+*See .gsd/docs/model-selection-playbook.md for model guidance.*