@cregis-dev/cckit 0.4.0 → 0.5.0

package/templates/ecc/agents/tdd-guide.md

@@ -1,80 +0,0 @@
----
-name: tdd-guide
-description: Test-Driven Development specialist enforcing write-tests-first methodology. Use PROACTIVELY when writing new features, fixing bugs, or refactoring code. Ensures 80%+ test coverage.
-tools: ["Read", "Write", "Edit", "Bash", "Grep"]
-model: sonnet
----
-
-You are a Test-Driven Development (TDD) specialist who ensures all code is developed test-first with comprehensive coverage.
-
-## Your Role
-
-- Enforce tests-before-code methodology
-- Guide through Red-Green-Refactor cycle
-- Ensure 80%+ test coverage
-- Write comprehensive test suites (unit, integration, E2E)
-- Catch edge cases before implementation
-
-## TDD Workflow
-
-### 1. Write Test First (RED)
-Write a failing test that describes the expected behavior.
-
-### 2. Run Test -- Verify it FAILS
-```bash
-npm test
-```
-
-### 3. Write Minimal Implementation (GREEN)
-Only enough code to make the test pass.
-
-### 4. Run Test -- Verify it PASSES
-
-### 5. Refactor (IMPROVE)
-Remove duplication, improve names, optimize -- tests must stay green.
-
-### 6. Verify Coverage
-```bash
-npm run test:coverage
-# Required: 80%+ branches, functions, lines, statements
-```
-
-## Test Types Required
-
-| Type | What to Test | When |
-|------|-------------|------|
-| **Unit** | Individual functions in isolation | Always |
-| **Integration** | API endpoints, database operations | Always |
-| **E2E** | Critical user flows (Playwright) | Critical paths |
-
-## Edge Cases You MUST Test
-
-1. **Null/Undefined** input
-2. **Empty** arrays/strings
-3. **Invalid types** passed
-4. **Boundary values** (min/max)
-5. **Error paths** (network failures, DB errors)
-6. **Race conditions** (concurrent operations)
-7. **Large data** (performance with 10k+ items)
-8. **Special characters** (Unicode, emojis, SQL chars)
-
-## Test Anti-Patterns to Avoid
-
-- Testing implementation details (internal state) instead of behavior
-- Tests depending on each other (shared state)
-- Asserting too little (passing tests that don't verify anything)
-- Not mocking external dependencies (Supabase, Redis, OpenAI, etc.)
-
-## Quality Checklist
-
-- [ ] All public functions have unit tests
-- [ ] All API endpoints have integration tests
-- [ ] Critical user flows have E2E tests
-- [ ] Edge cases covered (null, empty, invalid)
-- [ ] Error paths tested (not just happy path)
-- [ ] Mocks used for external dependencies
-- [ ] Tests are independent (no shared state)
-- [ ] Assertions are specific and meaningful
-- [ ] Coverage is 80%+
-
-For detailed mocking patterns and framework-specific examples, see `skill: tdd-workflow`.

package/templates/ecc/commands/build-fix.md

@@ -1,62 +0,0 @@
-# Build and Fix
-
-Incrementally fix build and type errors with minimal, safe changes.
-
-## Step 1: Detect Build System
-
-Identify the project's build tool and run the build:
-
-| Indicator | Build Command |
-|-----------|---------------|
-| `package.json` with `build` script | `npm run build` or `pnpm build` |
-| `tsconfig.json` (TypeScript only) | `npx tsc --noEmit` |
-| `Cargo.toml` | `cargo build 2>&1` |
-| `pom.xml` | `mvn compile` |
-| `build.gradle` | `./gradlew compileJava` |
-| `go.mod` | `go build ./...` |
-| `pyproject.toml` | `python -m py_compile` or `mypy .` |
-
-## Step 2: Parse and Group Errors
-
-1. Run the build command and capture stderr
-2. Group errors by file path
-3. Sort by dependency order (fix imports/types before logic errors)
-4. Count total errors for progress tracking
-
-## Step 3: Fix Loop (One Error at a Time)
-
-For each error:
-
-1. **Read the file** — Use Read tool to see error context (10 lines around the error)
-2. **Diagnose** — Identify root cause (missing import, wrong type, syntax error)
-3. **Fix minimally** — Use Edit tool for the smallest change that resolves the error
-4. **Re-run build** — Verify the error is gone and no new errors introduced
-5. **Move to next** — Continue with remaining errors
-
-## Step 4: Guardrails
-
-Stop and ask the user if:
-- A fix introduces **more errors than it resolves**
-- The **same error persists after 3 attempts** (likely a deeper issue)
-- The fix requires **architectural changes** (not just a build fix)
-- Build errors stem from **missing dependencies** (need `npm install`, `cargo add`, etc.)
-
-## Step 5: Summary
-
-Show results:
-- Errors fixed (with file paths)
-- Errors remaining (if any)
-- New errors introduced (should be zero)
-- Suggested next steps for unresolved issues
-
-## Recovery Strategies
-
-| Situation | Action |
-|-----------|--------|
-| Missing module/import | Check if package is installed; suggest install command |
-| Type mismatch | Read both type definitions; fix the narrower type |
-| Circular dependency | Identify cycle with import graph; suggest extraction |
-| Version conflict | Check `package.json` / `Cargo.toml` for version constraints |
-| Build tool misconfiguration | Read config file; compare with working defaults |
-
-Fix one error at a time for safety. Prefer minimal diffs over refactoring.

package/templates/ecc/commands/checkpoint.md

@@ -1,74 +0,0 @@
-# Checkpoint Command
-
-Create or verify a checkpoint in your workflow.
-
-## Usage
-
-`/checkpoint [create|verify|list] [name]`
-
-## Create Checkpoint
-
-When creating a checkpoint:
-
-1. Run `/verify quick` to ensure current state is clean
-2. Create a git stash or commit with checkpoint name
-3. Log checkpoint to `.claude/checkpoints.log`:
-
-```bash
-echo "$(date +%Y-%m-%d-%H:%M) | $CHECKPOINT_NAME | $(git rev-parse --short HEAD)" >> .claude/checkpoints.log
-```
-
-4. Report checkpoint created
-
-## Verify Checkpoint
-
-When verifying against a checkpoint:
-
-1. Read checkpoint from log
-2. Compare current state to checkpoint:
-   - Files added since checkpoint
-   - Files modified since checkpoint
-   - Test pass rate now vs then
-   - Coverage now vs then
-
-3. Report:
-```
-CHECKPOINT COMPARISON: $NAME
-============================
-Files changed: X
-Tests: +Y passed / -Z failed
-Coverage: +X% / -Y%
-Build: [PASS/FAIL]
-```
-
-## List Checkpoints
-
-Show all checkpoints with:
-- Name
-- Timestamp
-- Git SHA
-- Status (current, behind, ahead)
-
-## Workflow
-
-Typical checkpoint flow:
-
-```
-[Start] --> /checkpoint create "feature-start"
-   |
-[Implement] --> /checkpoint create "core-done"
-   |
-[Test] --> /checkpoint verify "core-done"
-   |
-[Refactor] --> /checkpoint create "refactor-done"
-   |
-[PR] --> /checkpoint verify "feature-start"
-```
-
-## Arguments
-
-$ARGUMENTS:
-- `create <name>` - Create named checkpoint
-- `verify <name>` - Verify against named checkpoint
-- `list` - Show all checkpoints
-- `clear` - Remove old checkpoints (keeps last 5)

package/templates/ecc/commands/claw.md

@@ -1,79 +0,0 @@
----
-description: Start the NanoClaw agent REPL — a persistent, session-aware AI assistant powered by the claude CLI.
----
-
-# Claw Command
-
-Start an interactive AI agent session that persists conversation history to disk and optionally loads ECC skill context.
-
-## Usage
-
-```bash
-node scripts/claw.js
-```
-
-Or via npm:
-
-```bash
-npm run claw
-```
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `CLAW_SESSION` | `default` | Session name (alphanumeric + hyphens) |
-| `CLAW_SKILLS` | *(empty)* | Comma-separated skill names to load as system context |
-
-## REPL Commands
-
-Inside the REPL, type these commands directly at the prompt:
-
-```
-/clear      Clear current session history
-/history    Print full conversation history
-/sessions   List all saved sessions
-/help       Show available commands
-exit        Quit the REPL
-```
-
-## How It Works
-
-1. Reads `CLAW_SESSION` env var to select a named session (default: `default`)
-2. Loads conversation history from `~/.claude/claw/{session}.md`
-3. Optionally loads ECC skill context from `CLAW_SKILLS` env var
-4. Enters a blocking prompt loop — each user message is sent to `claude -p` with full history
-5. Responses are appended to the session file for persistence across restarts
-
-## Session Storage
-
-Sessions are stored as Markdown files in `~/.claude/claw/`:
-
-```
-~/.claude/claw/default.md
-~/.claude/claw/my-project.md
-```
-
-Each turn is formatted as:
-
-```markdown
-### [2025-01-15T10:30:00.000Z] User
-What does this function do?
----
-### [2025-01-15T10:30:05.000Z] Assistant
-This function calculates...
----
-```
-
-## Examples
-
-```bash
-# Start default session
-node scripts/claw.js
-
-# Named session
-CLAW_SESSION=my-project node scripts/claw.js
-
-# With skill context
-CLAW_SKILLS=tdd-workflow,security-review node scripts/claw.js
-```

package/templates/ecc/commands/code-review.md

@@ -1,40 +0,0 @@
-# Code Review
-
-Comprehensive security and quality review of uncommitted changes:
-
-1. Get changed files: git diff --name-only HEAD
-
-2. For each changed file, check for:
-
-**Security Issues (CRITICAL):**
-- Hardcoded credentials, API keys, tokens
-- SQL injection vulnerabilities
-- XSS vulnerabilities  
-- Missing input validation
-- Insecure dependencies
-- Path traversal risks
-
-**Code Quality (HIGH):**
-- Functions > 50 lines
-- Files > 800 lines
-- Nesting depth > 4 levels
-- Missing error handling
-- console.log statements
-- TODO/FIXME comments
-- Missing JSDoc for public APIs
-
-**Best Practices (MEDIUM):**
-- Mutation patterns (use immutable instead)
-- Emoji usage in code/comments
-- Missing tests for new code
-- Accessibility issues (a11y)
-
-3. Generate report with:
-   - Severity: CRITICAL, HIGH, MEDIUM, LOW
-   - File location and line numbers
-   - Issue description
-   - Suggested fix
-
-4. Block commit if CRITICAL or HIGH issues found
-
-Never approve code with security vulnerabilities!

package/templates/ecc/commands/e2e.md

@@ -1,363 +0,0 @@
----
-description: Generate and run end-to-end tests with Playwright. Creates test journeys, runs tests, captures screenshots/videos/traces, and uploads artifacts.
----
-
-# E2E Command
-
-This command invokes the **e2e-runner** agent to generate, maintain, and execute end-to-end tests using Playwright.
-
-## What This Command Does
-
-1. **Generate Test Journeys** - Create Playwright tests for user flows
-2. **Run E2E Tests** - Execute tests across browsers
-3. **Capture Artifacts** - Screenshots, videos, traces on failures
-4. **Upload Results** - HTML reports and JUnit XML
-5. **Identify Flaky Tests** - Quarantine unstable tests
-
-## When to Use
-
-Use `/e2e` when:
-- Testing critical user journeys (login, trading, payments)
-- Verifying multi-step flows work end-to-end
-- Testing UI interactions and navigation
-- Validating integration between frontend and backend
-- Preparing for production deployment
-
-## How It Works
-
-The e2e-runner agent will:
-
-1. **Analyze user flow** and identify test scenarios
-2. **Generate Playwright test** using Page Object Model pattern
-3. **Run tests** across multiple browsers (Chrome, Firefox, Safari)
-4. **Capture failures** with screenshots, videos, and traces
-5. **Generate report** with results and artifacts
-6. **Identify flaky tests** and recommend fixes
-
-## Example Usage
-
-```
-User: /e2e Test the market search and view flow
-
-Agent (e2e-runner):
-# E2E Test Generation: Market Search and View Flow
-
-## Test Scenario Identified
-
-**User Journey:** Market Search → View Results → Click Market → View Details
-
-**Test Coverage:**
-1. Navigate to markets page
-2. Perform semantic search
-3. Verify search results
-4. Click on first result
-5. Verify market details page loads
-6. Verify chart renders
-
-## Generated Test Code
-
-```typescript
-// tests/e2e/markets/search-and-view.spec.ts
-import { test, expect } from '@playwright/test'
-import { MarketsPage } from '../../pages/MarketsPage'
-import { MarketDetailsPage } from '../../pages/MarketDetailsPage'
-
-test.describe('Market Search and View Flow', () => {
-  test('user can search markets and view details', async ({ page }) => {
-    // 1. Navigate to markets page
-    const marketsPage = new MarketsPage(page)
-    await marketsPage.goto()
-
-    // Verify page loaded
-    await expect(page).toHaveTitle(/Markets/)
-    await expect(page.locator('h1')).toContainText('Markets')
-
-    // 2. Perform semantic search
-    await marketsPage.searchMarkets('election')
-
-    // Wait for API response
-    await page.waitForResponse(resp =>
-      resp.url().includes('/api/markets/search') && resp.status() === 200
-    )
-
-    // 3. Verify search results
-    const marketCards = marketsPage.marketCards
-    await expect(marketCards.first()).toBeVisible()
-    const resultCount = await marketCards.count()
-    expect(resultCount).toBeGreaterThan(0)
-
-    // Take screenshot of search results
-    await page.screenshot({ path: 'artifacts/search-results.png' })
-
-    // 4. Click on first result
-    const firstMarketTitle = await marketCards.first().textContent()
-    await marketCards.first().click()
-
-    // 5. Verify market details page loads
-    await expect(page).toHaveURL(/\/markets\/[a-z0-9-]+/)
-
-    const detailsPage = new MarketDetailsPage(page)
-    await expect(detailsPage.marketName).toBeVisible()
-    await expect(detailsPage.marketDescription).toBeVisible()
-
-    // 6. Verify chart renders
-    await expect(detailsPage.priceChart).toBeVisible()
-
-    // Verify market name matches
-    const detailsTitle = await detailsPage.marketName.textContent()
-    expect(detailsTitle?.toLowerCase()).toContain(
-      firstMarketTitle?.toLowerCase().substring(0, 20) || ''
-    )
-
-    // Take screenshot of market details
-    await page.screenshot({ path: 'artifacts/market-details.png' })
-  })
-
-  test('search with no results shows empty state', async ({ page }) => {
-    const marketsPage = new MarketsPage(page)
-    await marketsPage.goto()
-
-    // Search for non-existent market
-    await marketsPage.searchMarkets('xyznonexistentmarket123456')
-
-    // Verify empty state
-    await expect(page.locator('[data-testid="no-results"]')).toBeVisible()
-    await expect(page.locator('[data-testid="no-results"]')).toContainText(
-      /no.*results|no.*markets/i
-    )
-
-    const marketCount = await marketsPage.marketCards.count()
-    expect(marketCount).toBe(0)
-  })
-
-  test('can clear search and see all markets again', async ({ page }) => {
-    const marketsPage = new MarketsPage(page)
-    await marketsPage.goto()
-
-    // Initial market count
-    const initialCount = await marketsPage.marketCards.count()
-
-    // Perform search
-    await marketsPage.searchMarkets('trump')
-    await page.waitForLoadState('networkidle')
-
-    // Verify filtered results
-    const filteredCount = await marketsPage.marketCards.count()
-    expect(filteredCount).toBeLessThan(initialCount)
-
-    // Clear search
-    await marketsPage.searchInput.clear()
-    await page.waitForLoadState('networkidle')
-
-    // Verify all markets shown again
-    const finalCount = await marketsPage.marketCards.count()
-    expect(finalCount).toBe(initialCount)
-  })
-})
-```
-
-## Running Tests
-
-```bash
-# Run the generated test
-npx playwright test tests/e2e/markets/search-and-view.spec.ts
-
-Running 3 tests using 3 workers
-
-  ✓  [chromium] › search-and-view.spec.ts:5:3 › user can search markets and view details (4.2s)
-  ✓  [chromium] › search-and-view.spec.ts:52:3 › search with no results shows empty state (1.8s)
-  ✓  [chromium] › search-and-view.spec.ts:67:3 › can clear search and see all markets again (2.9s)
-
-  3 passed (9.1s)
-
-Artifacts generated:
-- artifacts/search-results.png
-- artifacts/market-details.png
-- playwright-report/index.html
-```
-
-## Test Report
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║                    E2E Test Results                          ║
-╠══════════════════════════════════════════════════════════════╣
-║ Status:     ✅ ALL TESTS PASSED                              ║
-║ Total:      3 tests                                          ║
-║ Passed:     3 (100%)                                         ║
-║ Failed:     0                                                ║
-║ Flaky:      0                                                ║
-║ Duration:   9.1s                                             ║
-╚══════════════════════════════════════════════════════════════╝
-
-Artifacts:
-📸 Screenshots: 2 files
-📹 Videos: 0 files (only on failure)
-🔍 Traces: 0 files (only on failure)
-📊 HTML Report: playwright-report/index.html
-
-View report: npx playwright show-report
-```
-
-✅ E2E test suite ready for CI/CD integration!
-```
-
-## Test Artifacts
-
-When tests run, the following artifacts are captured:
-
-**On All Tests:**
-- HTML Report with timeline and results
-- JUnit XML for CI integration
-
-**On Failure Only:**
-- Screenshot of the failing state
-- Video recording of the test
-- Trace file for debugging (step-by-step replay)
-- Network logs
-- Console logs
-
-## Viewing Artifacts
-
-```bash
-# View HTML report in browser
-npx playwright show-report
-
-# View specific trace file
-npx playwright show-trace artifacts/trace-abc123.zip
-
-# Screenshots are saved in artifacts/ directory
-open artifacts/search-results.png
-```
-
-## Flaky Test Detection
-
-If a test fails intermittently:
-
-```
-⚠️  FLAKY TEST DETECTED: tests/e2e/markets/trade.spec.ts
-
-Test passed 7/10 runs (70% pass rate)
-
-Common failure:
-"Timeout waiting for element '[data-testid="confirm-btn"]'"
-
-Recommended fixes:
-1. Add explicit wait: await page.waitForSelector('[data-testid="confirm-btn"]')
-2. Increase timeout: { timeout: 10000 }
-3. Check for race conditions in component
-4. Verify element is not hidden by animation
-
-Quarantine recommendation: Mark as test.fixme() until fixed
-```
-
-## Browser Configuration
-
-Tests run on multiple browsers by default:
-- ✅ Chromium (Desktop Chrome)
-- ✅ Firefox (Desktop)
-- ✅ WebKit (Desktop Safari)
-- ✅ Mobile Chrome (optional)
-
-Configure in `playwright.config.ts` to adjust browsers.
-
-## CI/CD Integration
-
-Add to your CI pipeline:
-
-```yaml
-# .github/workflows/e2e.yml
-- name: Install Playwright
-  run: npx playwright install --with-deps
-
-- name: Run E2E tests
-  run: npx playwright test
-
-- name: Upload artifacts
-  if: always()
-  uses: actions/upload-artifact@v3
-  with:
-    name: playwright-report
-    path: playwright-report/
-```
-
-## PMX-Specific Critical Flows
-
-For PMX, prioritize these E2E tests:
-
-**🔴 CRITICAL (Must Always Pass):**
-1. User can connect wallet
-2. User can browse markets
-3. User can search markets (semantic search)
-4. User can view market details
-5. User can place trade (with test funds)
-6. Market resolves correctly
-7. User can withdraw funds
-
-**🟡 IMPORTANT:**
-1. Market creation flow
-2. User profile updates
-3. Real-time price updates
-4. Chart rendering
-5. Filter and sort markets
-6. Mobile responsive layout
-
-## Best Practices
-
-**DO:**
-- ✅ Use Page Object Model for maintainability
-- ✅ Use data-testid attributes for selectors
-- ✅ Wait for API responses, not arbitrary timeouts
-- ✅ Test critical user journeys end-to-end
-- ✅ Run tests before merging to main
-- ✅ Review artifacts when tests fail
-
-**DON'T:**
-- ❌ Use brittle selectors (CSS classes can change)
-- ❌ Test implementation details
-- ❌ Run tests against production
-- ❌ Ignore flaky tests
-- ❌ Skip artifact review on failures
-- ❌ Test every edge case with E2E (use unit tests)
-
-## Important Notes
-
-**CRITICAL for PMX:**
-- E2E tests involving real money MUST run on testnet/staging only
-- Never run trading tests against production
-- Set `test.skip(process.env.NODE_ENV === 'production')` for financial tests
-- Use test wallets with small test funds only
-
-## Integration with Other Commands
-
-- Use `/plan` to identify critical journeys to test
-- Use `/tdd` for unit tests (faster, more granular)
-- Use `/e2e` for integration and user journey tests
-- Use `/code-review` to verify test quality
-
-## Related Agents
-
-This command invokes the `e2e-runner` agent located at:
-`~/.claude/agents/e2e-runner.md`
-
-## Quick Commands
-
-```bash
-# Run all E2E tests
-npx playwright test
-
-# Run specific test file
-npx playwright test tests/e2e/markets/search.spec.ts
-
-# Run in headed mode (see browser)
-npx playwright test --headed
-
-# Debug test
-npx playwright test --debug
-
-# Generate test code
-npx playwright codegen http://localhost:3000
-
-# View report
-npx playwright show-report
-```