opencode-goopspec 0.1.0

package/references/tdd.md

@@ -0,0 +1,231 @@
+# Test-Driven Development (TDD) Reference
+
+GoopSpec supports TDD-style planning and execution. This reference covers how to use TDD effectively within the GoopSpec workflow.
+
+## TDD Cycle
+
+```
+   ┌─────────────────┐
+   │   RED           │
+   │   Write a       │
+   │   failing test  │
+   └────────┬────────┘
+            │
+            ▼
+   ┌─────────────────┐
+   │   GREEN         │
+   │   Minimum code  │
+   │   to pass       │
+   └────────┬────────┘
+            │
+            ▼
+   ┌─────────────────┐
+   │   REFACTOR      │
+   │   Clean up      │
+   │   Keep green    │
+   └────────┬────────┘
+            │
+            └──────────► Repeat
+```
+
+## TDD in GoopSpec
+
+### Plan Configuration
+
+Enable TDD mode in plan frontmatter:
+
+```yaml
+---
+phase: 1
+plan: auth-feature
+type: tdd
+wave: 1
+autonomous: true
+---
+```
+
+### Task Structure
+
+```markdown
+<task type="auto" tdd="true">
+### Task 1: User Login
+
+**Test First:**
+```typescript
+// src/auth/__tests__/login.test.ts
+import { login } from '../login';
+
+describe('login', () => {
+  it('should return user on valid credentials', async () => {
+    const result = await login('test@example.com', 'password123');
+    expect(result.user).toBeDefined();
+    expect(result.user.email).toBe('test@example.com');
+  });
+
+  it('should throw on invalid credentials', async () => {
+    await expect(login('test@example.com', 'wrong'))
+      .rejects.toThrow('Invalid credentials');
+  });
+});
+```
+
+**Implementation:**
+```typescript
+// src/auth/login.ts
+export async function login(email: string, password: string) {
+  const user = await db.users.findByEmail(email);
+  if (!user || !await verifyPassword(password, user.passwordHash)) {
+    throw new Error('Invalid credentials');
+  }
+  return { user };
+}
+```
+
+**Refactor:**
+- Extract password verification to separate module
+- Add input validation
+- Add logging
+
+**Done:**
+- Tests pass: `npm test src/auth/__tests__/login.test.ts`
+- Coverage > 80%
+</task>
+```
+
+## TDD Execution Flow
+
+### Step 1: RED Phase
+
+1. Write the test file first
+2. Run tests to confirm they fail
+3. Commit the failing test
+
+```bash
+# Write test
+edit src/auth/__tests__/login.test.ts
+
+# Verify it fails
+npm test -- --testPathPattern=login
+
+# Commit
+git commit -m "test(auth): add login tests (red)"
+```
+
+### Step 2: GREEN Phase
+
+1. Write minimum code to pass
+2. Run tests to confirm they pass
+3. Commit the implementation
+
+```bash
+# Write implementation
+edit src/auth/login.ts
+
+# Verify it passes
+npm test -- --testPathPattern=login
+
+# Commit
+git commit -m "feat(auth): implement login (green)"
+```
+
+### Step 3: REFACTOR Phase
+
+1. Improve code quality
+2. Keep tests passing
+3. Commit refactoring
+
+```bash
+# Refactor
+edit src/auth/login.ts
+
+# Verify still passes
+npm test -- --testPathPattern=login
+
+# Commit
+git commit -m "refactor(auth): extract password verification"
+```
+
+## Context Budget for TDD
+
+TDD requires more context due to test code. Allocate accordingly:
+
+| Phase | Context Budget |
+|-------|---------------|
+| RED (tests) | 20% |
+| GREEN (impl) | 40% |
+| REFACTOR | 20% |
+| Buffer | 20% |
+
+**Total per TDD cycle:** ~40% context
+
+**Recommendation:** 2-3 TDD tasks per plan maximum.
+
+## Test Categories
+
+### Unit Tests
+
+Test individual functions/modules in isolation.
+
+```typescript
+describe('validateEmail', () => {
+  it('should accept valid emails', () => {
+    expect(validateEmail('user@example.com')).toBe(true);
+  });
+});
+```
+
+### Integration Tests
+
+Test module interactions.
+
+```typescript
+describe('auth flow', () => {
+  it('should login and create session', async () => {
+    const result = await login('user@example.com', 'pass');
+    const session = await getSession(result.sessionId);
+    expect(session.userId).toBe(result.user.id);
+  });
+});
+```
+
+### E2E Tests
+
+Test complete user flows (use sparingly, high cost).
+
+```typescript
+describe('login page', () => {
+  it('should redirect to dashboard on success', async () => {
+    await page.goto('/login');
+    await page.fill('#email', 'user@example.com');
+    await page.fill('#password', 'password');
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL('/dashboard');
+  });
+});
+```
+
+## Best Practices
+
+1. **One assertion per test:** Clear failure messages
+2. **Descriptive names:** `should_do_X_when_Y`
+3. **Arrange-Act-Assert:** Clear test structure
+4. **No test interdependence:** Each test isolated
+5. **Fast tests:** Mock external dependencies
+6. **Coverage targets:** Aim for 80%+ on critical paths
+
+## When NOT to Use TDD
+
+- Exploratory/prototyping work
+- UI/visual components (use snapshot tests instead)
+- Configuration/setup code
+- Third-party integrations (use integration tests)
+- Performance-critical inner loops (profile first)
+
+## TDD Tools
+
+| Language | Framework | Runner |
+|----------|-----------|--------|
+| TypeScript/JS | Jest, Vitest | npm test |
+| Python | pytest | pytest |
+| Go | testing | go test |
+| Rust | built-in | cargo test |

package/references/ui-brand.md

@@ -0,0 +1,261 @@
+# GoopSpec UI Brand Guide
+
+GoopSpec has a distinctive visual identity that differs from other AI development tools. Our aesthetic is **clean**, **organic**, and **professional**.
+
+## Brand Symbol
+
+The **hexagon** `⬢` represents GoopSpec - evoking molecules, honeycombs, and interconnected systems. It appears at the start of all GoopSpec UI elements.
+
+## Message Formats
+
+### Standard Header (Gates, Major Sections)
+
+```
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  SECTION TITLE                                     │
+│                                                    │
+╰────────────────────────────────────────────────────╯
+```
+
+### Compact Header (Status, Progress)
+
+```
+⬢ GoopSpec · Section Title
+──────────────────────────────────────────────────────
+```
+
+### Inline Indicator
+
+```
+⬢ message here
+```
+
+## Gate Messages
+
+### Contract Gate (Specify Phase)
+
+```
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  🔒 CONTRACT GATE                                  │
+│                                                    │
+│  The specification is ready to lock.               │
+│                                                    │
+│  MUST HAVES:                                       │
+│  • Requirement 1                                   │
+│  • Requirement 2                                   │
+│                                                    │
+│  OUT OF SCOPE:                                     │
+│  • Excluded item                                   │
+│                                                    │
+│  ─────────────────────────────────────────────     │
+│  Type "confirm" to lock and proceed.               │
+│                                                    │
+╰────────────────────────────────────────────────────╯
+```
+
+### Acceptance Gate (Accept Phase)
+
+```
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  ✓ ACCEPTANCE GATE                                 │
+│                                                    │
+│  Implementation complete. Verification:            │
+│                                                    │
+│  ☑ Requirement 1 - verified                        │
+│  ☑ Requirement 2 - verified                        │
+│                                                    │
+│  Tests: 24/24 passing                              │
+│  Build: Successful                                 │
+│                                                    │
+│  ─────────────────────────────────────────────     │
+│  Type "accept" to confirm completion.              │
+│                                                    │
+╰────────────────────────────────────────────────────╯
+```
+
+## Status Messages
+
+### Workflow Status
+
+```
+⬢ GoopSpec · Status
+──────────────────────────────────────────────────────
+
+Project: my-project
+Phase:   ⬢ execute (wave 2/4)
+Mode:    standard
+
+Progress: [████████░░░░] 67%
+
+Tasks:
+  ☑ Task 1.1 - complete
+  ☑ Task 1.2 - complete
+  ◉ Task 2.1 - in progress
+  ○ Task 2.2 - pending
+
+──────────────────────────────────────────────────────
+```
+
+### Phase Transition
+
+```
+⬢ GoopSpec · Phase Complete
+──────────────────────────────────────────────────────
+
+✓ Research phase complete
+
+Findings saved to RESEARCH.md
+3 recommendations identified
+2 risks documented
+
+Ready for: /goop-specify
+
+──────────────────────────────────────────────────────
+```
+
+## Progress Indicators
+
+### Task Status Icons
+
+| Icon | Meaning |
+|------|---------|
+| `○` | Pending |
+| `◉` | In Progress |
+| `☑` | Complete |
+| `☒` | Failed |
+| `◌` | Skipped |
+
+### Phase Icons
+
+| Icon | Phase |
+|------|-------|
+| `📝` | Plan |
+| `🔍` | Research |
+| `📋` | Specify |
+| `🔨` | Execute |
+| `✓` | Accept |
+
+### Mode Icons
+
+| Icon | Mode |
+|------|------|
+| `⚡` | Quick |
+| `📦` | Standard |
+| `🏗️` | Comprehensive |
+| `🎯` | Milestone |
+
+## Completion Messages
+
+### Task Complete
+
+```
+⬢ Task 2.1 complete (commit: abc123)
+```
+
+### Wave Complete
+
+```
+⬢ GoopSpec · Wave Complete
+──────────────────────────────────────────────────────
+
+Wave 2 of 4 complete
+
+Tasks: 3/3 ☑
+Commits: 3 atomic commits
+Time: 4m 32s
+
+Ready for Wave 3
+
+──────────────────────────────────────────────────────
+```
+
+### Milestone Complete
+
+```
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  🎯 MILESTONE COMPLETE                             │
+│                                                    │
+│  v1.0 Authentication System                        │
+│                                                    │
+│  Delivered:                                        │
+│  • User login/logout                               │
+│  • Session management                              │
+│  • OAuth integration                               │
+│                                                    │
+│  Archived: .goopspec/archive/v1.0-auth/            │
+│  Learnings: 5 patterns extracted                   │
+│                                                    │
+╰────────────────────────────────────────────────────╯
+```
+
+## Error & Warning Messages
+
+### Warning
+
+```
+⬢ Warning: High comment density (35%)
+  Consider reducing comments in src/auth/login.ts
+```
+
+### Error
+
+```
+⬢ Error: Phase transition blocked
+  Cannot skip from 'plan' to 'execute'
+  Required: Complete 'research' phase first
+```
+
+### Deviation
+
+```
+⬢ Deviation (Rule 2): Added missing error handling
+  File: src/api/users.ts
+  Logged to ADL
+```
+
+## Character Reference
+
+| Character | Use |
+|-----------|-----|
+| `⬢` | GoopSpec brand symbol |
+| `╭╮╰╯` | Rounded box corners |
+| `─` | Horizontal lines |
+| `│` | Vertical lines |
+| `·` | Separator dot |
+| `○◉☑☒◌` | Task status |
+| `►` | Action prompt |
+
+## Color Guidelines
+
+When color is available:
+- **Green** `#65f463` - GoopSpec brand, success
+- **Blue** - Information, links
+- **Yellow** - Warnings, attention
+- **Red** - Errors, failures
+- **Gray** - Secondary info, disabled
+
+## Anti-Patterns
+
+### Don't Use
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  GOOPSPEC > SECTION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+This heavy style with `━` characters and `>` separator is used by other tools.
+
+### Do Use
+
+```
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│  SECTION                                           │
+╰────────────────────────────────────────────────────╯
+```
+
+The rounded box with hexagon symbol is uniquely GoopSpec.