gsd-ag 1.0.0

package/.gsd/GSD-STYLE.md

@@ -0,0 +1,272 @@
+# GSD-STYLE.md
+
+> **Comprehensive reference.** Core rules auto-load from `.gemini/GEMINI.md`. This document provides deep explanations and examples for when you need the full picture.
+
+This document explains how GSD is written so future AI instances can contribute consistently.
+
+## Core Philosophy
+
+GSD is a **meta-prompting system** where every file is both implementation and specification. Files teach the AI how to build software systematically. The system optimizes for:
+
+- **Solo developer + AI workflow** (no enterprise patterns)
+- **Context engineering** (manage the context window deliberately)
+- **Plans as prompts** (PLAN.md files are executable, not documents to transform)
+
+---
+
+## File Structure Conventions
+
+### Workflows (`.agent/workflows/*.md`)
+
+Slash commands the user invokes. Each workflow:
+- Has YAML frontmatter with `description`
+- Contains XML-structured process blocks
+- Ends with "Next Steps" routing
+
+### Skills (`.agent/skills/*/SKILL.md`)
+
+Specialized agent behaviors. Each skill:
+- Has YAML frontmatter with `name` and `description`
+- Contains detailed methodology
+- Is referenced by parent workflows
+
+### Templates (`.gsd/templates/*.md`)
+
+Reusable document structures. Copy, don't reference.
+
+### References (`.gsd/examples/*.md`)
+
+Read-only documentation and examples.
+
+---
+
+## XML Tag Conventions
+
+### Semantic Containers Only
+
+Use XML tags for semantic meaning, not formatting:
+
+```markdown
+<role>
+You are a GSD executor...
+</role>
+
+<objective>
+Execute all plans in a phase...
+</objective>
+
+<process>
+## 1. First Step
+...
+</process>
+```
+
+### Task Structure
+
+```xml
+<task type="auto" effort="medium">
+  <name>Clear descriptive name</name>
+  <files>exact/path/to/file.ts</files>
+  <action>
+    Specific implementation instructions.
+    AVOID: common mistake (reason)
+    USE: preferred approach (reason)
+  </action>
+  <verify>executable command that proves completion</verify>
+  <done>measurable acceptance criteria</done>
+</task>
+```
+
+### Effort Attribute (Optional)
+
+The `effort` attribute hints at task complexity for model selection:
+
+| Value | Use Case | Model Hint |
+|-------|----------|------------|
+| `low` | Simple edits, formatting | Fast models |
+| `medium` | Standard implementation (default) | Standard models |
+| `high` | Complex logic, refactoring | Reasoning models |
+| `max` | Architecture, security-critical | Deep reasoning |
+
+**Default:** `medium` if omitted. No workflow should fail if this attribute is absent.
+
+See [docs/model-selection-playbook.md](docs/model-selection-playbook.md) for model selection guidance.
+
+
+### Checkpoint Structure
+
+```xml
+<task type="checkpoint:human-verify">
+  <name>Verify UI renders correctly</name>
+  <action>User reviews the rendered component</action>
+  <verify>User confirms visual correctness</verify>
+</task>
+```
+
+---
+
+## Language & Tone
+
+### Imperative Voice
+- ✅ "Create the file"
+- ❌ "You should create the file"
+- ❌ "We will create the file"
+
+### No Filler
+- ✅ "Run `npm test`"
+- ❌ "Now let's go ahead and run `npm test`"
+
+### No Sycophancy
+- ✅ "Phase complete."
+- ❌ "Great job! Phase complete!"
+
+### Brevity with Substance
+Every sentence should convey information. Remove words that don't add meaning.
+
+---
+
+## Context Engineering
+
+### Size Constraints
+
+| Context Usage | Quality |
+|---------------|---------|
+| 0-30% | PEAK — Thorough, comprehensive |
+| 30-50% | GOOD — Confident, solid work |
+| 50-70% | DEGRADING — Efficiency mode begins |
+| 70%+ | POOR — Rushed, minimal |
+
+**Rule:** Plans should complete within ~50% context.
+
+### Fresh Context Pattern
+
+When spawning subprocesses (plans, tasks), they get:
+- The specific plan being executed
+- Minimal necessary context from parent files
+- NO accumulated orchestrator state
+
+### State Preservation
+
+STATE.md exists because context windows are temporary.
+Everything important goes in STATE.md so the next session can continue.
+
+---
+
+## Anti-Patterns to Avoid
+
+### Enterprise Patterns (Banned)
+
+❌ Stakeholder communication
+❌ Team coordination
+❌ Sprint ceremonies
+❌ Multiple approval levels
+❌ Separate environments requiring explicit promotion
+
+### Temporal Language (Banned in Implementation Docs)
+
+❌ "First, we'll..."
+❌ "Next, we should..."
+❌ "Finally, we'll..."
+
+### Generic XML (Banned)
+
+```xml
+<!-- DON'T -->
+<section>
+  <title>Authentication</title>
+  <content>...</content>
+</section>
+
+<!-- DO -->
+<task type="auto">
+  <name>Create login endpoint</name>
+  ...
+</task>
+```
+
+### Vague Tasks (Banned)
+
+```xml
+<!-- DON'T -->
+<action>Implement authentication</action>
+
+<!-- DO -->
+<action>
+  Create POST /api/auth/login endpoint.
+  Accept {email, password} JSON body.
+  Query User by email, compare with bcrypt.
+  Return JWT in httpOnly cookie on success.
+  Return 401 on failure.
+</action>
+```
+
+---
+
+## Commit Conventions
+
+### Format
+```
+type(scope): description
+```
+
+### Types
+| Type | Use For |
+|------|---------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation |
+| `refactor` | Code restructure |
+| `test` | Add tests |
+| `chore` | Maintenance |
+
+### Rules
+- One task = one commit
+- Scope is phase number for phase work
+- No commit before verification passes
+
+---
+
+## UX Patterns
+
+### Banners
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ GSD ► STATUS MESSAGE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+### "Next Up" Format
+
+```
+───────────────────────────────────────────────────────
+
+▶ NEXT
+
+/command — description
+
+───────────────────────────────────────────────────────
+```
+
+### Decision Gates
+
+When user input needed:
+```
+⚠️ DECISION REQUIRED
+
+Option A: {description}
+Option B: {description}
+
+Which do you prefer?
+```
+
+---
+
+## Summary: Core Meta-Patterns
+
+1. **Plans are prompts** — PLAN.md is read and executed directly
+2. **Fresh context for execution** — Each plan runs in clean context
+3. **STATE.md is memory** — Everything important persists there
+4. **Verify before done** — No "trust me, it works"
+5. **Aggressive atomicity** — Small tasks, atomic commits
+6. **No enterprise theater** — Solo dev + AI workflow only

package/.gsd/PROJECT_RULES.md

@@ -0,0 +1,256 @@
+# PROJECT_RULES.md — GSD Canonical Rules
+
+> **Single Source of Truth** for the Get Shit Done methodology.
+> 
+> Model-agnostic. All adapters and extensions reference this file.
+
+---
+
+## Core Protocol
+
+**SPEC → PLAN → EXECUTE → VERIFY → COMMIT**
+
+1. **SPEC**: Define requirements in `.gsd/SPEC.md` until status is `FINALIZED`
+2. **PLAN**: Decompose into phases in `.gsd/ROADMAP.md`, then detailed plans
+3. **EXECUTE**: Implement with atomic commits per task
+4. **VERIFY**: Prove completion with empirical evidence
+5. **COMMIT**: One task = one commit, message format: `type(scope): description`
+
+**Planning Lock**: No implementation code until SPEC.md contains "Status: FINALIZED".
+
+---
+
+## Proof Requirements
+
+Every change requires verification evidence:
+
+| Change Type | Required Proof |
+|-------------|----------------|
+| API endpoint | curl/HTTP response |
+| UI change | Screenshot |
+| Build/compile | Command output |
+| Test | Test runner output |
+| Config | Verification command |
+
+**Never accept**: "It looks correct", "This should work", "I've done similar before".
+
+**Always require**: Captured output, screenshot, or test result.
+
+---
+
+## Search-First Discipline
+
+**Before reading any file completely:**
+
+1. **Search first** — Use grep, ripgrep, or IDE search to find relevant snippets
+2. **Evaluate snippets** — Determine if full file read is justified
+3. **Targeted reads** — Only read specific line ranges when needed
+
+**Benefits:**
+- Reduces context pollution
+- Faster understanding of large codebases
+- Prevents reading irrelevant code
+
+**Anti-pattern**: Reading entire files "to understand the context" without searching first.
+
+---
+
+## Wave Execution
+
+Plans are grouped into **waves** based on dependencies:
+
+| Wave | Characteristic | Execution |
+|------|----------------|-----------|
+| 1 | Foundation tasks, no dependencies | Run in parallel |
+| 2 | Depends on Wave 1 | Wait for Wave 1, then parallel |
+| 3 | Depends on Wave 2 | Wait for Wave 2, then parallel |
+
+**Wave Completion Protocol:**
+1. All tasks in wave verified
+2. State snapshot created
+3. Commit all wave work
+4. Update STATE.md with position
+
+---
+
+## State Snapshots
+
+At the end of each wave or significant work block, create a state snapshot:
+
+```markdown
+## Wave N Summary
+
+**Objective:** {what this wave aimed to accomplish}
+
+**Changes:**
+- {change 1}
+- {change 2}
+
+**Files Touched:**
+- {file1}
+- {file2}
+
+**Verification:**
+- {command}: {result}
+
+**Risks/Debt:**
+- {any concerns}
+
+**Next Wave TODO:**
+- {item 1}
+- {item 2}
+```
+
+---
+
+## Model Independence
+
+**Absolute Rule**: No rule, workflow, or skill may require a specific model provider.
+
+**Allowed:**
+- Optional adapters with provider-specific enhancements
+- Capability-based recommendations (e.g., "use a reasoning model for planning")
+- Examples mentioning specific models as illustrations
+
+**Forbidden:**
+- Hard dependencies on provider features
+- Breaking behavior when a specific model is unavailable
+- Duplicating canonical rules in adapters
+
+**Adapter Pattern:**
+```
+.gsd/adapters/
+├── CLAUDE.md    # Optional Claude enhancements
+├── GEMINI.md    # Optional Gemini enhancements
+└── GPT_OSS.md   # Optional GPT/OSS enhancements
+```
+
+Each adapter must begin with:
+> "Everything in this file is optional. For canonical rules, see PROJECT_RULES.md."
+
+---
+
+## Commit Conventions
+
+**Format:**
+```
+type(scope): description
+```
+
+**Types:**
+| Type | Usage |
+|------|-------|
+| `feat` | New feature |
+| `fix` | Bug fix |
+| `docs` | Documentation only |
+| `refactor` | Code restructure (no behavior change) |
+| `test` | Adding/updating tests |
+| `chore` | Maintenance, dependencies |
+
+**Rules:**
+- One task = one commit
+- Verify before commit
+- Scope = phase number for phase work (e.g., `feat(phase-1): ...`)
+
+---
+
+## Repository Structure
+
+```
+.agent/
+├── workflows/            # Slash commands (/plan, /execute, etc.)
+└── skills/               # Agent specializations
+
+.gemini/                  # Gemini-specific configuration
+.gsd/                     # Project state and artifacts
+├── PROJECT_RULES.md      # ← This file (canonical rules)
+├── GSD-STYLE.md          # Style and conventions
+├── SPEC.md               # Requirements (must be FINALIZED)
+├── ROADMAP.md            # Phases and progress
+├── STATE.md              # Session memory
+├── templates/            # Document templates
+├── examples/             # Usage examples
+├── adapters/             # Optional model-specific enhancements
+├── docs/                 # Operational documentation
+└── scripts/              # Utility scripts
+```
+
+---
+
+## Context Management
+
+**Context Quality Thresholds:**
+
+| Usage | Quality |
+|-------|---------|
+| 0-30% | **PEAK** — Comprehensive, thorough work |
+| 30-50% | **GOOD** — Solid, confident output |
+| 50-70% | **DEGRADING** — Efficiency mode |
+| 70%+ | **POOR** — Rushed, incomplete |
+
+**Context Hygiene Rules:**
+- Keep plans under 50% context usage
+- Fresh context for each plan execution
+- After 3 debugging failures → state dump → fresh session
+- STATE.md = memory across sessions
+
+---
+
+## Token Efficiency Rules
+
+**Goal:** Minimize token consumption while maintaining output quality.
+
+### Loading Rules
+
+| Action | Rule |
+|--------|------|
+| Before reading file | Search first (grep, ripgrep) |
+| File >200 lines | Use outline, not full file |
+| File already understood | Reference summary, don't reload |
+| >5 files needed | Stop, reconsider approach |
+
+### Budget Thresholds
+
+| Usage | Action Required |
+|-------|-----------------|
+| 0-50% | Proceed normally |
+| 50-70% | Switch to outline mode, compress context |
+| 70%+ | State dump required, recommend fresh session |
+
+### Compression Protocol
+
+After understanding a file:
+1. Create summary in STATE.md or task notes
+2. Reference summary instead of re-reading
+3. Only reload specific sections if needed
+
+### Per-Wave Efficiency
+
+- Start each wave with minimal context
+- Load files just-in-time (when task requires)
+- Compress/summarize before moving to next wave
+- Document token usage in state snapshots (optional)
+
+**Anti-patterns:**
+- Loading files "just in case"
+- Re-reading files already understood
+- Full file reads when snippets suffice
+- Ignoring budget warnings
+
+---
+
+## Quick Reference
+
+```
+Before coding    → SPEC.md must be FINALIZED
+Before file read → Search first, then targeted read
+After each task  → Commit + update STATE.md
+After each wave  → State snapshot
+After 3 failures → State dump + fresh session
+Before "Done"    → Empirical proof captured
+```
+
+---
+
+*GSD Methodology — Model-Agnostic Edition*
+*Reference implementation for multi-LLM environments*

package/.gsd/adapters/CLAUDE.md

@@ -0,0 +1,77 @@
+# Claude Adapter
+
+> **Everything in this file is optional.**
+> For canonical rules, see [PROJECT_RULES.md](../PROJECT_RULES.md).
+
+This adapter provides optional enhancements for Claude models in Antigravity.
+
+---
+
+## Extended Thinking Mode
+
+When available, activate extended thinking for:
+
+| Task Type | Recommended |
+|-----------|-------------|
+| Architecture planning | ✅ High effort |
+| Complex debugging | ✅ High effort |
+| Security analysis | ✅ High effort |
+| Simple edits | ❌ Not needed |
+| Quick iterations | ❌ Overhead too high |
+
+### Effort Levels
+
+If the model supports effort/budget levels:
+
+| Level | Use Case |
+|-------|----------|
+| `low` | Simple edits, formatting, comments |
+| `medium` | Standard implementation (default) |
+| `high` | Complex logic, refactoring, debugging |
+| `max` | Architecture, security, critical decisions |
+
+**Default:** `medium` if not specified.
+
+---
+
+## Artifacts Mode
+
+When artifacts are supported:
+
+- Use for code generation that needs preview
+- Use for documentation with formatting
+- Avoid for small inline edits
+
+---
+
+## Context Optimization
+
+Claude-specific context tips:
+
+1. **System prompt loading**: Core rules in system prompt, task details in user message
+2. **XML structure**: Claude parses XML well — use task XML format from GSD-STYLE.md
+3. **Conversation history**: Minimal history preferred; use STATE.md for continuity
+
+---
+
+## File Conventions
+
+Not required, but if organizing Claude-specific files:
+
+```
+.claude/
+├── CLAUDE.md      # This adapter (if using)
+└── settings.json  # IDE-specific settings
+```
+
+---
+
+## Anti-Patterns
+
+❌ **Using max effort for everything** — Slow and expensive
+❌ **Skipping verification** — Thinking mode doesn't guarantee correctness
+❌ **Depending on artifacts** — Not all Claude interfaces support them
+
+---
+
+*See PROJECT_RULES.md for canonical requirements.*

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.*