pantheon-opencode 1.0.0

package/src/skills/spec-driven-development/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: spec-driven-development
+description: "Define requirements via spec-first before any code — PRD, edge cases, acceptance criteria"
+---
+
+# Spec-Driven Development
+
+**Não escreva código sem entender o problema primeiro.**
+
+## Workflow
+1. **Interview** — Extraia requisitos com perguntas iterativas (o usuário nunca sabe exatamente o que quer)
+2. **PRD** — Escreva um documento de requisitos: objetivo, personas, fluxos, regras de negócio, critérios de aceitação
+3. **Edge Cases** — Mapeie entradas inválidas, concorrência, falhas de API, estados vazios
+4. **Technical Spec** — Decisões de arquitetura: componentes, dados, API contracts, deploy
+5. **Approval** — Apresente ao usuário antes de codar. "É isso mesmo?"
+
+## Anti-patterns
+- ❌ Pular direto pra implementação
+- ❌ Assumir que entendeu sem confirmar
+- ❌ Spec muito detalhada (5+ páginas) — mantenha enxuta
+
+## Output
+`spec.md` no diretório raiz ou no `.pantheon/deepwork/<feature>/` — usado como input pro /plan.

package/src/skills/tdd-with-agents/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: tdd-with-agents
+description: "TDD enforcement with RED→GREEN→REFACTOR cycle and advanced testing patterns. Use for test-driven development across all layers."
+context: fork
+globs: []
+alwaysApply: false
+---
+
+# TDD with Agents
+
+Enforce RED → GREEN → REFACTOR cycle across all implementation agents. Includes advanced testing patterns for E2E, load, mutation, and contract testing.
+
+---
+
+## Core Principle
+
+> **Write the test FIRST. Watch it fail. Write minimal code to pass. Refactor with confidence.**
+
+---
+
+## TDD Cycle (RED → GREEN → REFACTOR)
+
+### RED — Write Failing Test
+- Write test for the behavior you want
+- Run it → **must fail** (confirms test works)
+- Test should be specific: one assertion per test
+
+### GREEN — Make It Pass
+- Write **minimal** code to pass the test
+- No extra features, no premature optimization
+- If it feels hard → design problem; refactor test
+
+### REFACTOR — Improve Without Breaking
+- Clean up code while tests stay green
+- Extract functions, rename, remove duplication
+- Tests are your safety net
+
+---
+
+## Testing by Layer
+
+### Backend (Hermes)
+```python
+# Unit: service logic
+def test_calculate_discount_applies_percentage():
+    result = calculate_discount(100, 10)
+    assert result == 90.0
+
+# Integration: API endpoint
+def test_get_user_returns_404_for_missing():
+    response = client.get("/users/nonexistent")
+    assert response.status_code == 404
+
+# Database: repository
+def test_user_repository_saves_and_retrieves():
+    repo.save(User(id="1", name="Test"))
+    assert repo.find("1").name == "Test"
+```
+
+### Frontend (Aphrodite)
+```typescript
+// Test behavior, not implementation
+test('shows error message on invalid form', async () => {
+  render(<LoginForm />)
+  await userEvent.click(screen.getByText('Submit'))
+  expect(screen.getByText('Email is required')).toBeInTheDocument()
+})
+```
+
+### Database (Demeter)
+```python
+def test_migration_creates_users_table():
+    alembic upgrade(head)
+    assert inspector.has_table('users')
+
+def test_migration_rollback_drops_table():
+    alembic upgrade(head)
+    alembic downgrade(-1)
+    assert not inspector.has_table('users')
+```
+
+---
+
+## Advanced Testing Patterns
+
+### E2E Testing (Playwright)
+```typescript
+test('user can complete full signup flow', async ({ page }) => {
+  await page.goto('/signup')
+  await page.fill('[name="email"]', 'test@example.com')
+  await page.fill('[name="password"]', 'secure123')
+  await page.click('button[type="submit"]')
+  await expect(page.locator('.welcome-banner')).toBeVisible()
+})
+```
+
+### Load Testing (k6/Locust)
+```javascript
+// k6 script
+export const options = { vus: 50, duration: '30s' }
+export default function () {
+  http.get('http://localhost:8000/api/users')
+}
+```
+
+### Contract Testing (Pact)
+```python
+# Provider verifies consumer contract
+@pact.verify_provider
+def test_provider_satisfies_consumer_contract():
+    # Verify all interactions from pact file
+    pass
+```
+
+### Mutation Testing
+- Mutate source code (change `>` to `<`, remove conditions)
+- Run tests → should fail (mutation killed)
+- If tests pass → test is weak; improve it
+
+### Visual Regression
+```typescript
+test('homepage looks the same', async ({ page }) => {
+  await page.goto('/')
+  await expect(page).toHaveScreenshot('homepage.png')
+})
+```
+
+---
+
+## Coverage Rules
+
+- **Minimum: 80%** for all code
+- **Critical paths: 100%** (auth, payments, data integrity)
+- **No snapshot testing** — test behavior, not output shape
+- **Test edge cases**: empty input, null, boundary values, errors
+
+---
+
+## Agent Responsibilities
+
+| Agent | Tests |
+|-------|-------|
+| **Hermes** | Unit + integration for FastAPI endpoints, services, middleware |
+| **Aphrodite** | Component behavior tests with React Testing Library |
+| **Demeter** | Migration upgrade/downgrade, query correctness |
+| **Themis** | Verifies coverage ≥80%, edge cases tested, error conditions |
+
+---
+
+## Workflow
+
+```
+1. Zeus/Athena defines feature with testable acceptance criteria
+2. Hermes writes failing test (RED)
+3. Hermes implements minimal code (GREEN)
+4. Hermes refactors (REFACTOR)
+5. Aphrodite writes frontend tests in parallel
+6. Themis reviews: coverage, edge cases, correctness
+7. If coverage <80% → NEEDS_REVISION
+```
+
+---
+
+## Anti-Patterns
+
+- ❌ Writing code before test
+- ❌ Testing implementation details (private methods, internal state)
+- ❌ Mocking everything (test real behavior where possible)
+- ❌ Skipping RED step (test must fail first)
+- ❌ Ignoring flaky tests (fix or delete)

package/src/skills/visual-review-pipeline/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: visual-review-pipeline
+description: "Automated visual review pipeline — Playwright screenshots, self-analysis, fix loop, escalation. Used by Aphrodite for UI verification."
+applyTo: "agents/{aphrodite,zeus}.agent.md"
+---
+
+# Visual Review Pipeline
+
+Automated visual review: Aphrodite captures screenshots via Playwright MCP → Self-analyzes for visual issues → Addresses findings in a loop.
+
+## Overview
+
+This pipeline establishes a formal workflow for detecting and resolving visual regressions and design issues. It enforces structured JSON output, iteration limits, and escalation criteria to prevent infinite fix loops.
+
+### Pipeline Flow
+
+```
+Aphrodite implements UI
+    ↓
+Playwright screenshot (browser/screenshotPage)
+    ↓
+Aphrodite self-analyzes (layout, contrast, responsive, accessibility)
+    ↓
+├─ verdict: pass → proceed to Themis review
+├─ verdict: fail + iteration < 3 → fix → re-capture
+└─ verdict: fail + iteration = 3 → Zeus escalation
+```
+
+## Workflow Steps
+
+### Step 1: Capture
+Aphrodite uses Playwright MCP to capture screenshots.
+- Navigate to target URL or render component
+- Capture full-page screenshot via `browser/screenshotPage`
+- Capture viewport-specific screenshots for responsive checks
+- Name files descriptively: `screenshot-iteration-N-component.png`
+
+### Step 2: Analyze
+Aphrodite self-analyzes screenshots visually.
+- Examine screenshot(s) for visual issues
+- Identify problems in layout, contrast, responsive behavior, and accessibility
+- Return findings in the structured JSON schema (below)
+- Include iteration number in findings
+- Mark issues with `pass_if_fixed` IDs
+
+### Step 3: Fix
+Aphrodite addresses each finding from self-analysis.
+- Triage findings by severity (critical → high → medium → low)
+- Fix each issue in component code
+- Commit changes with descriptive message
+- Re-capture screenshot for next iteration
+
+### Step 4: Loop
+Repeat Steps 1-3 for up to **3 iterations**.
+- Each iteration must fix at least one `pass_if_fixed` issue
+- Track iteration count in findings object
+- If no progress detected (zero fixes applied), escalate immediately
+- Compare before/after screenshots to verify fixes
+
+### Step 5: Escalate
+Zeus intervenes if issues persist after 3 iterations.
+- **Trigger:** 3 iterations exhausted or zero-progress detected
+- **Action:** Zeus coordinates manual review or architectural decision
+
+## JSON Schema
+
+Aphrodite must return findings in this exact structure:
+
+```json
+{
+  "verdict": "pass | fail | warn",
+  "iteration": 1,
+  "max_iterations": 3,
+  "issues": [
+    {
+      "id": "VIS-001",
+      "category": "layout",
+      "severity": "high",
+      "description": "Sidebar overflows on viewport width < 768px",
+      "screenshot_region": "left-panel at x:0,y:0 width:300px",
+      "recommendation": "Add responsive breakpoint to collapse sidebar below 768px"
+    }
+  ],
+  "summary": "One-line summary of overall visual state",
+  "pass_if_fixed": ["VIS-001", "VIS-002"]
+}
+```
+
+### Field Definitions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `verdict` | enum | `pass` = no issues, `fail` = blocking, `warn` = non-blocking |
+| `iteration` | int | Current iteration number (1-3) |
+| `max_iterations` | int | Always 3 |
+| `issues` | array | List of visual issues found |
+| `issues[].id` | string | Unique ID in format `VIS-NNN` |
+| `issues[].category` | enum | Issue category (see Categories) |
+| `issues[].severity` | enum | Severity level (see Severity) |
+| `issues[].description` | string | Clear description of the issue |
+| `issues[].screenshot_region` | string | Bounding box or region reference |
+| `issues[].recommendation` | string | Suggested fix |
+| `summary` | string | One-line overall assessment |
+| `pass_if_fixed` | string[] | Issue IDs that must be resolved to pass |
+
+## Categories
+
+| Category | Description | Examples |
+|----------|-------------|---------|
+| `layout` | Positioning, alignment, overflow | Element misplaced, container overflow, z-index issues |
+| `contrast` | Color contrast, visibility | Text hard to read, low contrast ratio |
+| `responsive` | Mobile/tablet behavior | Elements break at specific breakpoints |
+| `missing_element` | Expected element not rendered | Button not visible, icon missing |
+| `typography` | Font, size, weight, spacing | Wrong font family, text truncation |
+| `spacing` | Margins, padding, gaps | Uneven spacing, cramped elements |
+| `accessibility` | ARIA, focus states, keyboard nav | Missing alt text, no focus ring |
+
+## Severity Levels
+
+| Level | Description | Action Required |
+|-------|-------------|-----------------|
+| `critical` | Blocks user interaction or content | Must fix before merge |
+| `high` | Significant visual regression | Must fix before merge |
+| `medium` | Noticeable but not blocking | Fix in current sprint |
+| `low` | Minor polish item | Backlog, fix when convenient |
+
+## Iteration Rules
+
+1. **Minimum progress:** Each iteration fixes at least one `pass_if_fixed` issue
+2. **No regression:** Fixes must not introduce new issues
+3. **Track state:** Include iteration count in findings JSON
+4. **Early exit:** If `verdict` is `pass`, stop iterating
+5. **Immediate escalation:** If zero issues fixed in an iteration, escalate to Zeus
+
+### Progress Detection
+```
+Iteration N:
+  - Compare pass_if_fixed list to previous iteration
+  - If any ID removed from pass_if_fixed → progress detected
+  - If pass_if_fixed unchanged → zero progress → escalate
+```
+
+## Escalation Criteria
+
+Zeus must be invoked when:
+1. **3 iterations exhausted** — issues cannot be resolved within the pipeline
+2. **Backend/data dependency** — issue requires API changes, data model updates, or backend fixes
+3. **Architectural issue** — problem stems from component architecture, not CSS/styling
+4. **Zero progress** — no `pass_if_fixed` issues resolved in an iteration
+5. **Conflicting fixes** — resolving one issue introduces another
+
+**Escalation format:**
+```
+@zeus Visual review escalation: [component] failed after [N] iterations.
+Remaining issues: [list of unresolved pass_if_fixed IDs]
+Root cause: [backend | architectural | conflicting]
+```
+
+## MCP Requirements
+
+### Playwright MCP (Required)
+- Use `browser/screenshotPage` for full-page captures
+- Use `browser/snapshot` for accessibility tree context
+- Fallback: If Playwright MCP is unavailable, skip with warning:
+  ```
+  ⚠️ Playwright MCP unavailable — visual review skipped.
+  Install Playwright MCP server to enable visual review pipeline.
+  ```
+For UI implementation review, Aphrodite self-reviews.
+
+## Integration Points
+
+- **Code Review (Themis):** Visual review runs as part of frontend code review; findings feed into Themis's verdict.
+- **Artifact Protocol:** Visual review findings can attach to `IMPL-` artifacts. Escalation decisions documented in `_notes/`.
+- **Memory Bank:** Recurring visual issues documented in `01-active-context.md`. Architectural visual decisions recorded as `_notes/NOTE000X-*.md`.
+
+## Example Workflow
+
+```
+1. Aphrodite captures screenshot of LoginButton
+   → screenshot-iteration-1-login-button.png
+
+2. Self-analysis returns:
+   {
+     "verdict": "fail", "iteration": 1,
+     "issues": [{
+       "id": "VIS-001", "category": "contrast", "severity": "high",
+       "description": "White text on light blue bg, contrast ratio 2.1:1",
+       "recommendation": "Darken background to #1a56db"
+     }],
+     "pass_if_fixed": ["VIS-001"]
+   }
+
+3. Fix contrast, re-capture → screenshot-iteration-2-login-button.png
+
+4. Re-analysis: { "verdict": "pass", "iteration": 2, "issues": [],
+     "summary": "All visual issues resolved", "pass_if_fixed": [] }
+
+5. Pipeline complete — 2 iterations, all issues fixed.
+```