opencode-goopspec 0.1.0

package/skills/code-review/skill.md

@@ -0,0 +1,59 @@
+---
+name: code-review
+description: Provide thorough, constructive code reviews that improve code quality and share knowledge.
+category: review
+triggers:
+  - review
+  - feedback
+  - pull request
+  - quality
+version: 0.1.0
+---
+
+# Code Review Skill
+
+## Purpose
+Provide thorough, constructive code reviews that improve code quality and share knowledge.
+
+## Review Focus Areas
+
+### 1. Correctness
+- Does the code do what it claims?
+- Are edge cases handled?
+- Are there potential bugs?
+
+### 2. Design
+- Is the code well-structured?
+- Are abstractions appropriate?
+- Does it follow project patterns?
+
+### 3. Performance
+- Are there obvious performance issues?
+- Unnecessary loops or allocations?
+- Appropriate data structures?
+
+### 4. Security
+- Input validation present?
+- Secrets properly handled?
+- SQL injection, XSS risks?
+
+### 5. Maintainability
+- Is the code readable?
+- Are names meaningful?
+- Is complexity manageable?
+
+## Review Process
+
+1. Understand the context and goal
+2. Read the code thoroughly
+3. Run the code if possible
+4. Leave specific, actionable comments
+5. Distinguish between blocking issues and suggestions
+6. Acknowledge good code, not just problems
+
+## Comment Types
+
+- **Blocking** - Must be fixed before merge
+- **Suggestion** - Nice to have, not required
+- **Question** - Need clarification
+- **Nitpick** - Style preference (prefix with "nit:")

package/skills/codebase-mapping/skill.md

@@ -0,0 +1,54 @@
+---
+name: codebase-mapping
+description: Systematically explore and understand an unfamiliar codebase to build a mental model.
+category: code
+triggers:
+  - codebase
+  - architecture
+  - discovery
+  - mapping
+version: 0.1.0
+---
+
+# Codebase Mapping Skill
+
+## Purpose
+Systematically explore and understand an unfamiliar codebase to build a mental model.
+
+## Exploration Strategy
+
+### Phase 1: High-Level Overview
+1. Read README and documentation
+2. Examine directory structure
+3. Identify main entry points
+4. Review package.json/requirements.txt for dependencies
+
+### Phase 2: Architecture Discovery
+1. Find the main application entry point
+2. Trace the request/response flow
+3. Identify core abstractions and patterns
+4. Map module dependencies
+
+### Phase 3: Deep Dive
+1. Read key modules in detail
+2. Understand data models
+3. Map API endpoints to handlers
+4. Identify testing patterns
+
+## Key Questions
+
+- What framework/runtime is used?
+- How is the code organized (layers, features, hybrid)?
+- Where is configuration managed?
+- How is state managed?
+- What are the main data flows?
+- How are errors handled?
+- What testing approach is used?
+
+## Output Artifacts
+
+- Directory structure summary
+- Architecture diagram (text or visual)
+- Key file inventory
+- Pattern documentation
+- Convention notes for AI agents

package/skills/convention-detection/skill.md

@@ -0,0 +1,68 @@
+---
+name: convention-detection
+description: Identify and document coding conventions, patterns, and style guidelines used in a codebase.
+category: code
+triggers:
+  - conventions
+  - style
+  - patterns
+  - guidelines
+version: 0.1.0
+---
+
+# Convention Detection Skill
+
+## Purpose
+Identify and document coding conventions, patterns, and style guidelines used in a codebase.
+
+## Detection Areas
+
+### 1. Naming Conventions
+- File naming (kebab-case, camelCase, PascalCase)
+- Variable/function naming
+- Class/type naming
+- Constant naming
+- Database column naming
+
+### 2. Code Organization
+- Directory structure patterns
+- Module organization
+- Import ordering
+- Export patterns
+
+### 3. Style
+- Indentation (tabs vs spaces, size)
+- Quote style (single vs double)
+- Semicolons (yes/no)
+- Line length limits
+- Trailing commas
+
+### 4. Patterns
+- Error handling approach
+- Logging conventions
+- Testing patterns
+- Comment style
+- Documentation format
+
+## Detection Methods
+
+1. **Config files** - Read ESLint, Prettier, EditorConfig
+2. **Sample analysis** - Examine 5-10 representative files
+3. **Frequency analysis** - Count occurrences of patterns
+4. **Explicit docs** - Check CONTRIBUTING.md, STYLEGUIDE.md
+
+## Output Format
+
+```markdown
+## Detected Conventions
+
+### Naming
+- Files: kebab-case
+- Functions: camelCase
+- Classes: PascalCase
+
+### Style
+- Indent: 2 spaces
+- Quotes: single
+- Semicolons: no
+```

package/skills/debugging/skill.md

@@ -0,0 +1,59 @@
+---
+name: debugging
+description: Systematically diagnose and fix bugs using scientific method.
+category: code
+triggers:
+  - debug
+  - bug
+  - diagnose
+  - fix
+version: 0.1.0
+---
+
+# Debugging Skill
+
+## Purpose
+Systematically diagnose and fix bugs using scientific method.
+
+## The Scientific Method for Debugging
+
+1. **Observe** - Gather symptoms and error messages
+2. **Hypothesize** - Form theories about the cause
+3. **Predict** - What would you expect if hypothesis is true?
+4. **Experiment** - Test the hypothesis
+5. **Analyze** - Interpret results
+6. **Iterate** - Refine hypothesis or fix
+
+## Debugging Strategies
+
+### Binary Search
+Narrow down the problem space by eliminating half at each step.
+
+### Print/Log Debugging
+Add strategic logging to trace execution flow.
+
+### Rubber Duck Debugging
+Explain the problem out loud, step by step.
+
+### Minimal Reproduction
+Create the smallest test case that reproduces the bug.
+
+### Git Bisect
+Find the commit that introduced the bug.
+
+## Common Bug Categories
+
+- **Logic errors** - Wrong algorithm or condition
+- **State errors** - Unexpected state mutations
+- **Race conditions** - Timing-dependent failures
+- **Edge cases** - Unhandled boundary conditions
+- **Type errors** - Wrong types or null values
+- **Integration errors** - API contract mismatches
+
+## Debugging Checklist
+
+- [ ] Can I reproduce the bug consistently?
+- [ ] What changed recently?
+- [ ] What are the exact error messages?
+- [ ] What is the expected vs actual behavior?
+- [ ] What assumptions am I making?

package/skills/deviation-handling/skill.md

@@ -0,0 +1,187 @@
+---
+name: deviation-handling
+description: Handle deviations from plan using the 4-rule system
+category: core
+triggers:
+  - deviation
+  - unexpected
+  - bug
+  - blocker
+version: 0.1.0
+requires:
+  - goop-core
+---
+
+# Deviation Handling Skill
+
+## The 4-Rule System
+
+### Rule 1: Bug Fixes (Auto-Fix)
+
+**Triggers:**
+- Type errors, null pointer exceptions
+- Logic errors (off-by-one, wrong comparison)
+- Security vulnerabilities (injection, XSS)
+- Runtime crashes
+- Memory leaks
+
+**Action:** Fix immediately without asking.
+
+**Example:**
+```typescript
+// Bug found: missing null check
+if (user.email) {  // Was: if (user) - crashes on undefined
+  sendEmail(user.email);
+}
+```
+
+### Rule 2: Missing Critical Functionality (Auto-Fix)
+
+**Triggers:**
+- Missing error handling
+- Missing input validation
+- Missing auth checks
+- Missing rate limiting
+- Missing sanitization
+
+**Action:** Add immediately without asking.
+
+**Example:**
+```typescript
+// Missing: input validation
+export async function createUser(data: UserInput) {
+  // Added: validation
+  if (!isValidEmail(data.email)) {
+    throw new ValidationError('Invalid email');
+  }
+  // ... rest of implementation
+}
+```
+
+### Rule 3: Blocking Issues (Auto-Fix)
+
+**Triggers:**
+- Missing npm packages
+- Broken imports
+- Missing env variables
+- Config errors
+- Build failures
+
+**Action:** Fix to unblock without asking.
+
+**Example:**
+```bash
+# Missing package
+npm install zod  # Added to fix import error
+```
+
+### Rule 4: Architectural Decisions (STOP)
+
+**Triggers:**
+- Database schema changes
+- New tables or collections
+- Framework switches
+- Major dependency additions
+- API contract changes
+- Infrastructure changes
+
+**Action:** STOP and ask user.
+
+**Example:**
+```
+STOP: Architectural Decision Required
+
+The current implementation requires a new database table
+for session storage.
+
+Options:
+1. Add 'sessions' table (recommended)
+2. Use in-memory session store
+3. Use existing 'users' table with session fields
+
+Please choose an option to continue.
+```
+
+## Detection Flow
+
+```
+Issue Found
+    │
+    ▼
+Is it a bug/error? ──Yes──► Rule 1: Auto-fix
+    │
+    No
+    │
+    ▼
+Is critical feature missing? ──Yes──► Rule 2: Auto-add
+    │
+    No
+    │
+    ▼
+Is it blocking progress? ──Yes──► Rule 3: Auto-fix
+    │
+    No
+    │
+    ▼
+Is it architectural? ──Yes──► Rule 4: STOP and ask
+    │
+    No
+    │
+    ▼
+Continue without deviation
+```
+
+## Logging Deviations
+
+Always log to ADL:
+
+```markdown
+### AD-015
+
+**Type:** implementation
+**Date:** 2024-01-15T10:30:00Z
+**Status:** active
+
+**Context:**
+During implementation of login endpoint, discovered missing
+input validation on email field.
+
+**Decision:**
+Applied Rule 2: Auto-added email validation using zod schema.
+
+**Rationale:**
+Input validation is a critical security requirement that any
+professional implementation would include.
+
+**Related Files:**
+- `src/auth/login.ts`
+```
+
+## Confidence Handling
+
+If unsure which rule applies:
+- Default to Rule 4 (ask user)
+- Log uncertainty in ADL
+- Request clarification
+
+## Commit Messages
+
+```
+fix(auth): add missing email validation (Rule 2 deviation)
+
+- Added zod schema for email validation
+- Returns 400 on invalid input
+- Logged as AD-015 in ADL
+
+During: Implement login endpoint
+Issue: Missing input validation
+Rule: 2 (auto-add missing critical functionality)
+```
+
+## Best Practices
+
+1. **Document everything:** Every deviation goes in ADL
+2. **Atomic fixes:** One deviation = one commit
+3. **Stay in scope:** Deviations shouldn't expand spec scope
+4. **Confidence threshold:** When in doubt, ask (Rule 4)
+5. **Verify after fix:** Run tests to confirm fix works

package/skills/documentation/skill.md

@@ -0,0 +1,213 @@
+---
+name: documentation
+description: Write technical documentation and guides
+category: documentation
+triggers:
+  - document
+  - readme
+  - api
+  - guide
+version: 0.1.0
+requires:
+  - goop-core
+---
+
+# Documentation Skill
+
+## Documentation Types
+
+### README.md
+Project overview, quick start, basic usage.
+
+### API Documentation
+Endpoints, parameters, responses, examples.
+
+### Architecture Documentation
+System design, patterns, decisions.
+
+### User Guides
+How-to guides, tutorials, walkthroughs.
+
+### Developer Guides
+Setup, contribution, debugging.
+
+## README Structure
+
+```markdown
+# Project Name
+
+Brief description (1-2 sentences)
+
+## Features
+- Feature 1
+- Feature 2
+
+## Quick Start
+
+\`\`\`bash
+npm install project-name
+\`\`\`
+
+## Usage
+
+\`\`\`typescript
+import { thing } from 'project-name';
+\`\`\`
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| option | string | "default" | What it does |
+
+## API Reference
+
+### functionName(param)
+
+Description of function.
+
+**Parameters:**
+- `param` (type) - description
+
+**Returns:** type - description
+
+## Contributing
+See CONTRIBUTING.md
+
+## License
+MIT
+```
+
+## API Documentation
+
+### Endpoint Documentation
+```markdown
+## POST /api/users
+
+Create a new user.
+
+### Request
+
+**Headers:**
+| Header | Value | Required |
+|--------|-------|----------|
+| Authorization | Bearer {token} | Yes |
+
+**Body:**
+\`\`\`json
+{
+  "email": "user@example.com",
+  "name": "John Doe"
+}
+\`\`\`
+
+### Response
+
+**Success (201):**
+\`\`\`json
+{
+  "id": "123",
+  "email": "user@example.com",
+  "name": "John Doe"
+}
+\`\`\`
+
+**Error (400):**
+\`\`\`json
+{
+  "error": "Invalid email format"
+}
+\`\`\`
+```
+
+## Code Documentation
+
+### JSDoc/TSDoc
+```typescript
+/**
+ * Creates a new user in the system.
+ * 
+ * @param data - User creation data
+ * @param data.email - User's email address
+ * @param data.name - User's display name
+ * @returns The created user object
+ * @throws {ValidationError} If email is invalid
+ * 
+ * @example
+ * ```typescript
+ * const user = await createUser({
+ *   email: 'user@example.com',
+ *   name: 'John Doe'
+ * });
+ * ```
+ */
+export async function createUser(data: CreateUserInput): Promise<User> {
+  // ...
+}
+```
+
+## Architecture Decision Records
+
+```markdown
+# ADR-001: Use PostgreSQL for primary database
+
+## Status
+Accepted
+
+## Context
+Need a reliable database for user data and transactions.
+
+## Decision
+Use PostgreSQL with Prisma ORM.
+
+## Consequences
+- Pros: ACID compliance, rich feature set
+- Cons: Operational complexity, scaling limits
+```
+
+## Documentation Best Practices
+
+### Do
+- Write for your audience
+- Include examples
+- Keep it up to date
+- Use consistent formatting
+- Start with the most important info
+
+### Don't
+- Assume prior knowledge
+- Write walls of text
+- Document obvious things
+- Leave TODO comments
+- Duplicate information
+
+## Documentation Tools
+
+```bash
+# Generate API docs from JSDoc
+npx typedoc src/index.ts
+
+# Generate from OpenAPI spec
+npx @redocly/cli build-docs openapi.yaml
+
+# Markdown linting
+npx markdownlint "**/*.md"
+```
+
+## Documentation Review Checklist
+
+- [ ] Accurate and up to date
+- [ ] Clear and concise
+- [ ] Includes examples
+- [ ] Proper formatting
+- [ ] No broken links
+- [ ] Spell checked
+- [ ] Reviewed by someone unfamiliar
+
+## When to Document
+
+1. **New feature** - Add usage docs
+2. **API change** - Update API docs
+3. **Decision made** - Add ADR
+4. **Bug fixed** - Update troubleshooting
+5. **Process changed** - Update guides