gsd-ag 1.0.0

package/.agent/skills/codebase-mapper/SKILL.md

@@ -0,0 +1,226 @@
+---
+name: GSD Codebase Mapper
+description: Analyzes existing codebases to understand structure, patterns, and technical debt
+---
+
+# GSD Codebase Mapper Agent
+
+<role>
+You are a GSD codebase mapper. You analyze existing codebases to produce documentation that enables informed planning.
+
+**Core responsibilities:**
+- Scan and understand project structure
+- Identify patterns and conventions
+- Map dependencies and integrations
+- Surface technical debt
+- Produce ARCHITECTURE.md and STACK.md
+</role>
+
+## Analysis Domains
+
+### 1. Structure Analysis
+Understand how the project is organized:
+- Source directories and their purposes
+- Entry points (main files, index files)
+- Test locations and patterns
+- Configuration locations
+- Asset directories
+
+### 2. Dependency Analysis
+Map what the project depends on:
+- Runtime dependencies (production)
+- Development dependencies
+- Peer dependencies
+- Outdated packages
+- Security vulnerabilities
+
+### 3. Pattern Analysis
+Identify how code is written:
+- Naming conventions
+- File organization patterns
+- Error handling approaches
+- State management patterns
+- API patterns
+
+### 4. Integration Analysis
+Map external connections:
+- APIs consumed
+- Databases used
+- Third-party services
+- Environment dependencies
+
+### 5. Technical Debt Analysis
+Surface issues to address:
+- TODOs and FIXMEs
+- Deprecated code
+- Missing tests
+- Inconsistent patterns
+- Known vulnerabilities
+
+---
+
+## Scanning Process
+
+### Phase 1: Project Type Detection
+
+Identify project type from markers:
+```powershell
+# Node.js/JavaScript
+Test-Path "package.json"
+
+# Python
+Test-Path "requirements.txt" -or Test-Path "pyproject.toml"
+
+# Rust
+Test-Path "Cargo.toml"
+
+# Go
+Test-Path "go.mod"
+
+# .NET
+Get-ChildItem "*.csproj"
+```
+
+### Phase 2: Structure Scan
+
+```powershell
+# Get directory structure
+Get-ChildItem -Recurse -Directory | 
+    Where-Object { $_.Name -notmatch "node_modules|\.git|__pycache__|dist|build|\.next" } |
+    Select-Object FullName
+```
+
+### Phase 3: Dependency Extraction
+
+For each ecosystem:
+
+**Node.js:**
+```powershell
+$pkg = Get-Content "package.json" | ConvertFrom-Json
+$pkg.dependencies
+$pkg.devDependencies
+```
+
+**Python:**
+```powershell
+Get-Content "requirements.txt"
+```
+
+### Phase 4: Pattern Discovery
+
+Search for common patterns:
+```powershell
+# Components
+Get-ChildItem -Recurse -Include "*.tsx","*.jsx" | Select-Object Name
+
+# API routes
+Get-ChildItem -Recurse -Path "**/api/**" -Include "*.ts","*.js"
+
+# Models/schemas
+Select-String -Path "**/*.ts" -Pattern "interface|type|schema"
+```
+
+### Phase 5: Debt Discovery
+
+```powershell
+# TODOs
+Select-String -Path "src/**/*" -Pattern "TODO|FIXME|HACK|XXX"
+
+# Deprecated
+Select-String -Path "**/*" -Pattern "@deprecated|DEPRECATED"
+
+# Console statements (often debug leftovers)
+Select-String -Path "src/**/*" -Pattern "console\.(log|debug|warn)"
+```
+
+---
+
+## Output Format
+
+### ARCHITECTURE.md
+
+```markdown
+# Architecture
+
+> Generated by /map on {date}
+
+## Overview
+{High-level system description}
+
+## System Diagram
+```
+{ASCII or description of component relationships}
+```
+
+## Components
+
+### {Component Name}
+- **Purpose:** {what it does}
+- **Location:** `{path}`
+- **Dependencies:** {what it imports}
+- **Dependents:** {what imports it}
+
+## Data Flow
+{How data moves through the system}
+
+## Integration Points
+| External Service | Type | Purpose |
+|------------------|------|---------|
+| {service} | {API/DB/etc} | {purpose} |
+
+## Conventions
+- **Naming:** {patterns}
+- **Structure:** {organization}
+- **Testing:** {approach}
+
+## Technical Debt
+- [ ] {Debt item with location}
+```
+
+### STACK.md
+
+```markdown
+# Technology Stack
+
+> Generated by /map on {date}
+
+## Runtime
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| {tech} | {version} | {purpose} |
+
+## Production Dependencies
+| Package | Version | Purpose |
+|---------|---------|---------|
+| {pkg} | {version} | {purpose} |
+
+## Development Dependencies
+| Package | Version | Purpose |
+|---------|---------|---------|
+| {pkg} | {version} | {purpose} |
+
+## Infrastructure
+| Service | Provider | Purpose |
+|---------|----------|---------|
+| {svc} | {provider} | {purpose} |
+
+## Configuration
+| Variable | Purpose | Required |
+|----------|---------|----------|
+| {var} | {purpose} | {yes/no} |
+```
+
+---
+
+## Checklist
+
+Before Completing Map:
+- [ ] Project type identified
+- [ ] All source directories documented
+- [ ] Entry points found
+- [ ] Dependencies extracted and categorized
+- [ ] Key patterns identified
+- [ ] Integrations mapped
+- [ ] Technical debt surfaced
+- [ ] ARCHITECTURE.md created
+- [ ] STACK.md created

package/.agent/skills/context-compressor/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: Context Compressor
+description: Strategies for compressing context to maximize token efficiency
+---
+
+# Context Compressor Skill
+
+<role>
+You are a context compression specialist. Your job is to maintain rich understanding while using minimal tokens.
+
+**Core principle:** Compress aggressively, decompress only when needed.
+</role>
+
+---
+
+## Compression Strategies
+
+### Strategy 1: Summary Mode
+
+**When:** You've fully understood a file and may need to reference it later.
+
+**How:**
+```markdown
+## File Summary: src/auth/login.ts
+
+**Purpose:** Handles user login via email/password
+**Key functions:**
+- handleLogin(req, res) → Validates credentials, returns JWT
+- validateCredentials(email, password) → Checks against DB
+**Dependencies:** bcrypt, jose, database
+**Tokens saved:** ~400 (95 lines not reloaded)
+```
+
+**Use instead of:** Re-reading the full file
+
+---
+
+### Strategy 2: Outline Mode
+
+**When:** You need to understand a file's structure but not implementation details.
+
+**How:**
+```markdown
+## Outline: src/services/payment.ts (127 lines)
+
+- L1-15: Imports and types
+- L17-35: PaymentService class
+  - L20: constructor(config)
+  - L25: processPayment(amount, method)
+  - L45: refund(transactionId)
+  - L67: getHistory(userId)
+- L90-127: Helper functions
+```
+
+**Tokens:** ~50 vs ~500 for full file
+
+---
+
+### Strategy 3: Diff-Only Mode
+
+**When:** You've already seen a file and need to understand changes.
+
+**How:**
+```markdown
+## Changes to: src/config.ts
+
+Added:
+- L45: TOKEN_BUDGET_THRESHOLD = 0.5
+- L46: COMPRESSION_ENABLED = true
+
+Modified:
+- L12: MAX_CONTEXT → increased from 100000 to 150000
+```
+
+**Use for:** Reviewing modifications, understanding updates
+
+---
+
+### Strategy 4: Reference Mode
+
+**When:** You need to track a file without loading it.
+
+**How:**
+```markdown
+## References
+
+| File | Last Seen | Summary | Load If |
+|------|-----------|---------|---------|
+| auth.ts | Task 2 | Login handling | Auth bugs |
+| db.ts | Task 1 | Postgres client | DB errors |
+| utils.ts | Never | Utility funcs | Helper needed |
+```
+
+**Cost:** ~10 tokens vs ~200+ per file
+
+---
+
+### Strategy 5: Progressive Disclosure
+
+**When:** Unsure how much detail is needed.
+
+**Process:**
+1. Start with outline (Level 1)
+2. If insufficient, load key functions (Level 2)
+3. If still stuck, load related code (Level 3)
+4. Full file only as last resort (Level 4)
+
+```
+L1: Outline → "I see handleLogin at L25"
+L2: Function → "handleLogin validates then calls createToken"
+L3: Related → "createToken uses jose.sign with HS256"
+L4: Full → Only for complex debugging
+```
+
+---
+
+## Compression Triggers
+
+### Automatic Compression Points
+
+| Trigger | Action |
+|---------|--------|
+| After understanding a file | Create summary |
+| Switching tasks | Compress previous context |
+| Budget at 50% | Aggressive outline mode |
+| Budget at 70% | Summary-only mode |
+| End of wave | Full compression pass |
+
+---
+
+## Decompression Protocol
+
+When you need details from compressed context:
+
+1. **Check summary first** — Often sufficient
+2. **Load specific section** — If summary incomplete
+3. **Full load as last resort** — And re-compress after
+
+```markdown
+## Decompression Log
+
+| File | Reason | Level | Tokens |
+|------|--------|-------|--------|
+| auth.ts | Debug login | L2 (func) | +150 |
+| db.ts | Check query | L3 (snippet) | +50 |
+```
+
+---
+
+## Compression Format Templates
+
+### Summary Template
+
+```markdown
+## 📦 [filename]
+**Purpose:** [one line]
+**Key exports:** [list]
+**Dependencies:** [list]
+**Patterns:** [notable patterns used]
+**Watch for:** [gotchas or edge cases]
+```
+
+### Outline Template
+
+```markdown
+## 📋 [filename] (N lines)
+- L[start]-[end]: [section name]
+  - L[n]: [key item]
+  - L[n]: [key item]
+```
+
+### Diff Template
+
+```markdown
+## Δ [filename]
+**+** [additions]
+**-** [removals]
+**~** [modifications]
+```
+
+---
+
+## Integration
+
+Works with:
+- `token-budget` — Triggers compression at thresholds
+- `context-fetch` — Provides input for compression
+- `context-health-monitor` — Monitors compression effectiveness
+
+---
+
+## Anti-Patterns
+
+❌ **Keeping full files in mental context** — Compress after understanding
+❌ **Re-reading instead of referencing** — Use summaries
+❌ **Loading full file for one function** — Use outline + target
+❌ **Skipping compression "to save time"** — Costs more later
+
+---
+
+*Part of GSD v1.6 Token Optimization. See docs/token-optimization-guide.md for examples.*

package/.agent/skills/context-fetch/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: Context Fetch
+description: Search-first skill to reduce unnecessary file reads by searching before loading
+---
+
+# Context Fetch Skill
+
+<role>
+You are a context-efficient agent. Your job is to find relevant code with minimal file reads.
+
+**Core principle:** Search first, read targeted sections, never load full files blindly.
+</role>
+
+---
+
+## When to Use
+
+Activate this skill **before**:
+- Starting any coding task
+- Beginning a refactor
+- Investigating a bug
+- Understanding unfamiliar code
+
+---
+
+## Process
+
+### Step 1: Define the Question
+
+What are you trying to find or understand?
+
+Examples:
+- "Where is the login endpoint defined?"
+- "How does the caching layer work?"
+- "What calls the `processPayment` function?"
+
+### Step 2: Identify Keywords
+
+Extract searchable terms:
+
+| Question | Keywords |
+|----------|----------|
+| Login endpoint | `login`, `auth`, `POST.*login` |
+| Caching layer | `cache`, `redis`, `memoize` |
+| Payment calls | `processPayment`, `payment` |
+
+### Step 3: Search Before Reading
+
+**PowerShell:**
+```powershell
+# Simple pattern search
+Select-String -Path "src/**/*.ts" -Pattern "login" -Recurse
+
+# With ripgrep (if available)
+rg "login" --type ts
+```
+
+**Bash:**
+```bash
+# With ripgrep (recommended)
+rg "login" --type ts
+
+# With grep
+grep -r "login" src/ --include="*.ts"
+```
+
+### Step 4: Evaluate Results
+
+From search results, identify:
+
+1. **Primary candidates** — Files directly matching your question
+2. **Secondary candidates** — Files that reference primary candidates
+3. **Ignore list** — Files with keyword but unrelated context
+
+### Step 5: Targeted Reading
+
+Only read what's justified:
+
+```powershell
+# Read specific line range (PowerShell)
+Get-Content "src/auth/login.ts" | Select-Object -Skip 49 -First 30
+
+# Read specific function (with view_code_item tool)
+# view_code_item: src/auth/login.ts -> handleLogin
+```
+
+---
+
+## Inputs
+
+When invoking this skill, provide:
+
+| Input | Description | Example |
+|-------|-------------|---------|
+| **Question** | What you're trying to find | "Where is user validation?" |
+| **Scope** | Directory or file pattern | `src/`, `*.service.ts` |
+| **Keywords** | Terms to search for | `validate`, `user`, `schema` |
+
+---
+
+## Outputs
+
+After executing this skill, report:
+
+1. **Candidate files** — Ranked by relevance
+2. **Relevant extracts** — Key snippets found
+3. **Next reads** — Specific files/line-ranges to read next
+4. **Skip list** — Files searched but not relevant
+
+---
+
+## Anti-Patterns
+
+### ❌ Loading Everything First
+
+```
+# BAD: Reading 5 full files to "understand context"
+Read: src/auth/login.ts (500 lines)
+Read: src/auth/register.ts (400 lines)
+Read: src/auth/types.ts (200 lines)
+```
+
+### ✅ Search Then Target
+
+```
+# GOOD: Search first, read only what's needed
+Search: "validatePassword" in src/auth/
+Found: login.ts:45, register.ts:78
+Read: login.ts lines 40-60
+```
+
+### ❌ Broad Searches
+
+```
+# BAD: Searching for common terms
+Search: "function" → 10,000 results
+```
+
+### ✅ Specific Searches
+
+```
+# GOOD: Searching for specific identifiers
+Search: "validateUserCredentials" → 3 results
+```
+
+---
+
+## Context Efficiency Metrics
+
+Track your efficiency:
+
+| Metric | Good | Poor |
+|--------|------|------|
+| Files searched | 10+ | <5 |
+| Files fully read | <3 | 10+ |
+| Lines read | <200 | 1000+ |
+| Targeted sections | Yes | No |
+
+---
+
+## Integration with GSD
+
+This skill supports GSD's context management:
+
+- **Prevents context pollution** — Less irrelevant code loaded
+- **Supports wave execution** — Each wave starts with minimal context
+- **Enables model switching** — Less context = easier handoff
+
+---
+
+## Quick Reference
+
+```
+1. Define question     → What am I looking for?
+2. Extract keywords    → What terms to search?
+3. Search codebase     → rg/grep/Select-String
+4. Evaluate results    → Which files matter?
+5. Read targeted       → Specific lines only
+6. Report findings     → Candidates + extracts
+```
+
+---
+
+*Part of GSD methodology. See PROJECT_RULES.md for search-first discipline rules.*

package/.agent/skills/context-health-monitor/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: Context Health Monitor
+description: Monitors context complexity and triggers state dumps before quality degrades
+---
+
+# Context Health Monitor
+
+## Purpose
+
+Prevent "Context Rot" — the quality degradation that occurs as the agent processes more information in a single session.
+
+## When This Skill Activates
+
+The agent should self-monitor for these warning signs:
+
+### Warning Signs
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| Repeated debugging | 3+ failed attempts | Trigger state dump |
+| Going in circles | Same approach tried twice | Stop and reassess |
+| Confusion indicators | "I'm not sure", backtracking | Document uncertainty |
+| Session length | Extended back-and-forth | Recommend `/pause` |
+
+## Behavior Rules
+
+### Rule 1: The 3-Strike Rule
+
+If debugging the same issue fails 3 times:
+
+1. **STOP** attempting fixes
+2. **Document** in `.gsd/STATE.md`:
+   - What was tried
+   - What errors occurred
+   - Current hypothesis
+3. **Recommend** user start fresh session
+4. **Do NOT** continue with more attempts
+
+### Rule 2: Circular Detection
+
+If the same approach is being tried again:
+
+1. **Acknowledge** the repetition
+2. **List** what has already been tried
+3. **Propose** a fundamentally different approach
+4. **Or** recommend `/pause` for fresh perspective
+
+### Rule 3: Uncertainty Logging
+
+When uncertain about an approach:
+
+1. **State** the uncertainty clearly
+2. **Document** in `.gsd/DECISIONS.md`:
+   - The uncertain decision
+   - Why it's uncertain
+   - Alternatives considered
+3. **Ask** user for guidance rather than guessing
+
+## State Dump Format
+
+When triggered, write to `.gsd/STATE.md`:
+
+```markdown
+## Context Health: State Dump
+
+**Triggered**: [date/time]
+**Reason**: [3 failures / circular / uncertainty]
+
+### What Was Attempted
+1. [Approach 1] — Result: [outcome]
+2. [Approach 2] — Result: [outcome]
+3. [Approach 3] — Result: [outcome]
+
+### Current Hypothesis
+[Best guess at root cause]
+
+### Recommended Next Steps
+1. [Fresh perspective action]
+2. [Alternative approach to try]
+
+### Files Involved
+- [file1.ext] — [what state it's in]
+- [file2.ext] — [what state it's in]
+```
+
+## Auto-Save Protocol
+
+**Critical:** When any warning signal triggers, the agent must save state BEFORE recommending `/pause` to the user. This ensures state persists even if the session hard-terminates.
+
+### Steps
+
+1. **Write** a state snapshot to `.gsd/STATE.md` immediately when a threshold is hit
+2. **Include** at minimum: current phase, current task, last action, next step
+3. **Then** inform the user of the situation and recommend `/pause`
+
+### Why
+
+Sessions can terminate abruptly (usage limits, context limits, network errors). If the agent waits for the user to type `/pause`, it may never get the chance. By saving first and recommending second, state is always preserved.
+
+## Integration
+
+This skill integrates with:
+- `/pause` — Triggers proper session handoff (includes proactive auto-save)
+- `/resume` — Loads the state dump context
+- Rule 3 in `GEMINI.md` — Context Hygiene enforcement