@wrongstack/core 0.9.4 → 0.9.19

package/skills/api-design/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: api-design
+description: |
+  Use this skill when designing, reviewing, or refactoring REST APIs in WrongStack.
+  Triggers: user says "API", "endpoint", "REST", "request", "response", "JSON",
+  "HTTP", "status code", "pagination", "query params", "request body".
+version: 1.0.0
+---
+
+# API Design — WrongStack
+
+## Overview
+
+Designs and reviews REST APIs for WrongStack services. WrongStack uses JSON over HTTPS, conventional HTTP status codes, and cursor-based pagination. APIs are consumed by the TUI, webui, and external integrations.
+
+## Rules
+
+1. Use conventional HTTP status codes: `200` (ok), `201` (created), `400` (bad request), `401` (unauthorized), `403` (forbidden), `404` (not found), `500` (server error).
+2. Always return consistent error shape: `{ "error": { "code": "ERROR_CODE", "message": "Human readable" } }`.
+3. Use plural nouns for resource names: `/sessions` not `/session`.
+4. Pagination: cursor-based for large datasets, not offset-based.
+5. Request validation: validate on server, return `400` with field-level errors.
+6. Idempotency: `POST` to `/resources` creates; `PUT` to `/resources/:id` replaces.
+7. No secrets in URLs — put auth in headers, not query params.
+8. Versioning: prefix with `/v1/` when breaking changes are inevitable.
+
+## Patterns
+
+### Do
+
+```typescript
+// ✅ Consistent error shape
+interface ErrorResponse {
+  error: {
+    code: string; // machine-readable: "VALIDATION_ERROR"
+    message: string;    // human-readable: "name is required"
+    details?: unknown;  // optional field-level errors
+  };
+}
+
+// ✅ Cursor-based pagination
+interface PaginatedResponse<T> {
+  data: T[];
+  nextCursor: string | null;  // null = last page
+  hasMore: boolean;
+}
+
+// GET /sessions?cursor=abc123&limit=20
+
+// ✅ Proper status codes
+if (!resource) return Response.json({ error: { code: 'NOT_FOUND', message: '...' } }, { status: 404 });
+if (!auth) return Response.json({ error: { code: 'UNAUTHORIZED', message: '...' } }, { status: 401 });
+```
+
+### Don't
+
+```typescript
+// ❌ Inconsistent error shape
+Response.json({ message: 'Not found' }); // no code, no standard shape
+
+// ❌ Secrets in URL
+GET /api/data?apiKey=sk-xxx  // ❌ put in Authorization header
+
+// ❌ Offset pagination (fragile on mutations)
+GET /users?offset=100&limit=20  // ❌ gaps after insert/delete
+
+// ❌ 200 for errors
+Response.json({ error: '...' }, { status: 200 }); // lies about outcome
+```
+
+## Request/response patterns
+
+### Create resource (POST)
+
+```
+POST /sessions
+Body: { "provider": "anthropic", "model": "claude-3-5-sonnet" }
+201: { "id": "sess_abc", "provider": "anthropic", ... }
+400: { "error": { "code": "VALIDATION_ERROR", "message": "model is required" } }
+```
+
+### Get resource (GET)
+
+```
+GET /sessions/sess_abc
+200: { "id": "sess_abc", "status": "running", ... }
+404: { "error": { "code": "NOT_FOUND", "message": "Session not found" } }
+```
+
+### List with pagination
+
+```
+GET /sessions?cursor=sess_xyz&limit=20
+200: {
+  "data": [...],
+  "nextCursor": "sess_aaa",
+  "hasMore": true
+}
+```
+
+### Update resource (PUT)
+
+```
+PUT /sessions/sess_abc
+Body: { "status": "paused" }
+200: { "id": "sess_abc", "status": "paused", ... }
+400: { "error": { "code": "INVALID_STATUS", "message": "Must be running or paused" } }
+```
+
+## Error codes
+
+| Code | HTTP | When |
+|------|------|------|
+| `VALIDATION_ERROR` | 400 | Request body/params invalid |
+| `UNAUTHORIZED` | 401 | Missing or invalid auth |
+| `FORBIDDEN` | 403 | Auth valid but no permission |
+| `NOT_FOUND` | 404 | Resource doesn't exist |
+| `CONFLICT` | 409 | Duplicate resource |
+| `RATE_LIMITED` | 429 | Too many requests |
+| `INTERNAL_ERROR` | 500 | Server-side failure |
+
+## Authentication
+
+- Bearer token in `Authorization` header: `Authorization: Bearer <token>`
+- API key in `X-API-Key` header for machine-to-machine
+- Never use query params for auth credentials
+
+## WrongStack-specific notes
+
+- **WrongStack CLI**: Most API calls go through the CLI's internal tool wrappers, not raw HTTP.
+- **Session management**: Sessions are created/managed via the CLI, not a public REST API.
+- **MCP tools**: MCP servers expose tools, not REST endpoints — this skill is for any HTTP APIs WrongStack exposes.
+
+## Skills in scope
+
+- `sdd` — for spec-driven API design with acceptance criteria
+- `typescript-strict` — for type-safe request/response types
+- `security-scanner` — for scanning API implementations for injection, auth, and secrets
+- `testing` — for writing integration tests against API endpoints

package/skills/audit-log/SKILL.md

@@ -11,6 +11,54 @@ version: 1.1.0
 
 Analyzes session logs, event streams, and system traces to surface patterns, anomalies, and actionable insights.
 
+## Overview
+
+Parses WrongStack session JSONL files to extract tool usage patterns, error distributions, cost trends, and context anomalies. Produces a structured report with prioritized findings.
+
+## Rules
+
+1. Always parse from the source JSONL — never summarize what you didn't read.
+2. Analyze one session at a time, or aggregate with clear labeling per session.
+3. Cite specific data in reports: iteration numbers, tool names, error messages.
+4. Flag repeated failures (same tool,5+ times) as a real issue, not noise.
+5. Report cost trends in context of iteration count — a spike means context growth.
+
+## Patterns
+
+### Do
+
+```json
+// ✅ Good — parse tool call counts from session JSONL
+{
+  "iterations": 23,
+  "toolCalls": [
+    { "tool": "read", "count": 142, "failures": 3 },
+    { "tool": "bash", "count": 89, "failures": 12 }
+  ],
+  "costPerIteration": [0.04, 0.04, 0.11, 0.18]
+}
+```
+
+```typescript
+// ✅ Extract error distribution
+const errorsByType = events
+  .filter(e => e.type === 'error')
+  .reduce((acc, e) => {
+    acc[e.error.type] = (acc[e.error.type] || 0) + 1;
+    return acc;
+  }, {});
+```
+
+### Don't
+
+```typescript
+// ❌ Bad — report without citing data
+"bash had some failures" // no count, no iteration, no error type
+
+// ❌ Bad — mix sessions without labeling
+// Analyzed 3 sessions together with no per-session breakdown
+```
+
 ## Workflow
 
 ```
@@ -23,24 +71,48 @@ Analyzes session logs, event streams, and system traces to surface patterns, ano
 ## What to look for
 
 ### Tool usage patterns
-- Over-used tools (100+ calls to the same tool = possibly a loop)
-- Tools that consistently fail (repeated failures = bug or misconfiguration)
-- Unusual tool sequences (e.g., 50 writes in a row with no reads)
+- **Over-used tools**: 100+ calls to the same tool = possibly a loop
+- **Consistent failures**: same tool failing 5x+ = bug or misconfiguration
+- **Unusual sequences**: 50 writes in a row with no reads = wrong approach
+- **Tool entropy**: too many different tools in one iteration = unfocused task
 
 ### Error patterns
-- Same error repeating across iterations
-- Error rate by type: what's most common?
-- Errors clustered in specific packages or tools
+- **Same error repeating**: `ToolExecutionError`47x across iterations = systemic issue
+- **Error clustering**: all errors in `bash` tool = command timeout pattern
+- **Error rate by type**: which error type is most common?
+- **Error distribution**: are errors clustered in specific packages or tools?
 
 ### Cost patterns
-- Tokens per iteration: is it growing?
-- Which provider/model combination is most expensive?
-- Any unexpected cost spikes?
+- **Token growth**: tokens/iteration trending up = context bloat
+- **Provider cost**: which model is most expensive per call?
+- **Cost spikes**: sudden3x increase = large file reads or excessive tool calls
+- **Iteration cost variance**: avg $0.04/iter → $0.11/iter = context growing
 
 ### Context management
-- Iterations with very high tool count (possible loop)
-- Context compaction triggered frequently
-- Session that keeps restarting
+- **High tool count per iteration**: >50 tool calls = possible loop or unfocused task
+- **Compaction events**: context compaction triggered 3x in one session = too much context
+- **Session restart**: same session restarting multiple times = crash loop
+- **Long iterations**: single iteration >5min = stuck or waiting on something
+
+## Session file structure
+
+WrongStack session logs are JSONL files. Each line is a JSON event. Key event types:
+
+```
+{"type": "iteration_start", "iteration": 1, "timestamp": "..."}
+{"type": "tool_call", "tool": "read", "input": {"path": "src/index.ts"}, "duration_ms": 12}
+{"type": "tool_result", "tool": "read", "output_lines": 45}
+{"type": "error", "error": {"type": "ToolExecutionError", "message": "...", "tool": "bash"}}
+{"type": "compaction", "reason": "context_near_limit", "tokens_removed": 1200}
+{"type": "cost", "input_tokens": 3400, "output_tokens": 890, "cost_usd": 0.11}
+{"type": "iteration_end", "iteration": 1, "stop_reason": "end_turn"}
+```
+
+When reading a session file:
+1. `grep` for event types you need (e.g., `grep '"type": "error"' session.jsonl`)
+2. `read` the full file for detailed analysis
+3. Track iteration boundaries via `iteration_start` / `iteration_end` events
+4. Sum `cost_usd` per iteration for cost trend analysis
 
 ## Input
 
@@ -64,7 +136,7 @@ Analyzes session logs, event streams, and system traces to surface patterns, ano
 - Cost: $X.XX
 
 ### Top Errors (by count)
-1. `ToolExecutionError` — 47x —集中在 `bash` tool, command timeout
+1. `ToolExecutionError` — 47x — concentrated in `bash` tool, command timeout
 2. `PermissionDenied` — 12x — `exec` tool, no trust file entry
 
 ### Tool Usage
@@ -93,4 +165,5 @@ Analyzes session logs, event streams, and system traces to surface patterns, ano
 ## Skills in scope
 
 - `bug-hunter` — for turning audit findings into concrete bugs to fix
-- `refactor-planner` — for addressing systemic issues found in logs
+- `refactor-planner` — for addressing systemic issues found in logs
+- `security-scanner` — for security-adjacent findings (leaked keys, injection patterns in logs)

package/skills/bug-hunter/SKILL.md

@@ -11,6 +11,19 @@ version: 1.1.0
 
 Scans code for bugs and code smells. Outputs a prioritized hit list with file:line references.
 
+## Overview
+
+Grep/read across target files to surface bugs, anti-patterns, and quality issues. Classifies by severity (critical/high/medium/low) and reports with file:line + fix suggestion.
+
+## Rules
+
+1. Always include `file:line` in every finding — no line reference = can't be fixed.
+2. Never scan `node_modules` — waste of time, false positives.
+3. Don't report style issues as bugs — those are lint findings.
+4. If >30% of findings are noise, note the false positive rate in the report.
+5. Don't flag deprecated APIs without severity — some deprecations are acceptable.
+6. Sort output: critical > high > medium > low.
+
 ## Workflow
 
 ```
@@ -30,23 +43,25 @@ Scans code for bugs and code smells. Outputs a prioritized hit list with file:li
 | **Medium** | Error handling gap, type unsafety | Fix soon |
 | **Low** | Style, minor code smell | Consider fixing |
 
-## Bug patterns to find
+## Patterns
 
-```
-| Pattern | Regex hint | Severity |
-|---------|------------|----------|
-| Uncaught promise | /\.then\([^]*\.catch/ but missing catch | high |
-| Event listener leak | `on(` without `off/removeListener` | high |
-| Hardcoded secret | `[A-Za-z0-9/+=]{40}` in config or code | critical |
-| unsafe any | `: any\b` or `as any` | medium |
-| innerHTML assignment | `innerHTML\s*=` | high |
-| Missing await | `await` not used on async call | high |
-| Unhandled rejection | `process.on('unhandledRejection'` | medium |
-| SQL concatenation | `"SELECT * FROM " + table` | critical |
-| Shell injection | `exec(\`cmd ${input}\`)` | critical |
+### Do
+
+```typescript
+// ✅ FIXED — use textContent instead of innerHTML
+element.textContent = userInput;
+
+// ✅ FIXED — parameterized query
+db.query("SELECT * FROM users WHERE id = $1", [userId]);
+
+// ✅ FIXED — proper await with catch
+await fetchData().catch(err => console.error(err));
+
+// ✅ FIXED — execFile with args array
+execFile('echo', [userInput], { signal: AbortSignal.timeout(5000) });
 ```
 
-## Real examples
+### Don't
 
 ```typescript
 // ❌ CRITICAL — hardcoded API key
@@ -63,13 +78,21 @@ exec(`echo ${userInput}`);
 
 // ❌ HIGH — unsafe any
 const data: any = response.json();
+```
 
-// ✅ FIXED — use textContent
-element.textContent = userInput;
+### Bug patterns to find
 
-// ✅ FIXED — parameterized query
-db.query("SELECT * FROM users WHERE id = $1", [userId]);
-```
+| Pattern | Regex hint | Severity |
+|---------|------------|----------|
+| Uncaught promise | `\.then\(` without `.catch` | high |
+| Event listener leak | `on(` without `off/removeListener` | high |
+| Hardcoded secret | `[A-Za-z0-9/+=]{40}` in config or code | critical |
+| unsafe any | `: any\b` or `as any` | medium |
+| innerHTML assignment | `innerHTML\s*=` | high |
+| Missing await | `await` not used on async call | high |
+| Unhandled rejection | `process.on('unhandledRejection'` | medium |
+| SQL concatenation | `"SELECT * FROM " + table` | critical |
+| Shell injection | `exec(\`cmd ${input}\`)` | critical |
 
 ## Anti-patterns
 

package/skills/docker-deploy/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: docker-deploy
+description: |
+  Use this skill when building, containerizing, or deploying WrongStack
+  with Docker. Triggers: user says "docker", "container", "dockerfile",
+  "image", "docker-compose", "deploy", "containerize", "registry",
+  "multi-stage", "distroless".
+version: 1.0.0
+---
+
+# Docker Deploy — WrongStack
+
+## Overview
+
+Containerizes and deploys WrongStack with Docker. WrongStack is a Node.js CLI tool — containerize it for CI/CD, cloud deployment, or self-hosted setups. Use multi-stage builds to keep images small and distroless base images for security.
+
+## Rules
+
+1. Multi-stage build: build stage (with dev deps) + runtime stage (production deps only).
+2. Use `node:*` base image with pinned version — not `node:latest`.
+3. Never run as root in the container — use a non-root user.
+4. Pass secrets via environment variables, not baked into the image.
+5. Health check: `docker healthcheck` pointing to the CLI's self-check command.
+6. Tag images with git SHA: `wrongstack:$GIT_SHA` — never `latest` in production.
+7. Scan images for vulnerabilities: `trivy image` or `docker scout` before push.
+8. Use `.dockerignore` to exclude `node_modules`, `dist`, `.git`, `*.test.ts`.
+
+## Patterns
+
+### Do
+
+```dockerfile
+# ✅ Multi-stage build — small production image
+FROM node:22-alpine AS builder
+WORKDIR /app
+COPY package.json pnpm-lock.yaml .pnpmfile.cjs ./
+RUN corepack enable && pnpm install --frozen-lockfile
+COPY . .
+RUN pnpm build
+
+FROM node:22-alpine AS runtime
+WORKDIR /app
+# Copy only what's needed
+COPY --from=builder /app/packages/cli/dist ./dist/
+COPY --from=builder /app/node_modules ./node_modules/
+COPY --from=builder /app/packages/cli/package.json ./
+
+# Non-root user
+RUN addgroup -S wrongstack && adduser -S wrongstack -G wrongstack
+USER wrongstack
+
+ENTRYPOINT ["node", "dist/index.js"]
+```
+
+```yaml
+# ✅ docker-compose.yml — development
+version: '3.9'
+services:
+  wrongstack:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    environment:
+      - WRONGSTACK_CONFIG_DIR=/app/.wrongstack
+      - WRONGSTACK_SESSION_ROOT=/app/sessions
+    volumes:
+      - .:/app
+      - wrongstack-data:/app/.wrongstack
+    stdin_open: true
+    tty: true
+
+volumes:
+  wrongstack-data:
+```
+
+```bash
+# ✅ Build with git SHA tag
+IMAGE_TAG="wrongstack:$(git rev-parse --short HEAD)"
+docker build -t "$IMAGE_TAG" .
+docker tag "$IMAGE_TAG" "registry.example.com/wrongstack:$IMAGE_TAG"
+docker push "registry.example.com/wrongstack:$IMAGE_TAG"
+```
+
+### Don't
+
+```dockerfile
+# ❌ Running as root
+FROM node:22
+WORKDIR /app
+COPY . .
+RUN npm install && npm run build
+ENTRYPOINT ["npm", "start"]
+
+# ❌ No .dockerignore — copies everything
+# node_modules, .git, dist/ end up in the image
+
+# ❌ Secrets baked into image
+ARG API_KEY
+RUN echo $API_KEY > /app/config.key  # ❌
+```
+
+## Dockerfile best practices
+
+| Practice | Why |
+|----------|-----|
+| Pin base image version | `node:22-alpine` not `node:latest` |
+| Multi-stage build | 1GB → ~150MB image size |
+| Non-root user | Security: container compromise ≠ host root |
+| `.dockerignore` | Smaller image, faster builds |
+| No `latest` tag | Reproducibility — you always know which SHA |
+| Health check | Kubernetes/docker-compose health monitoring |
+
+## Environment variables
+
+```bash
+# Required at runtime
+WRONGSTACK_CONFIG_DIR=/app/.wrongstack
+WRONGSTACK_SESSION_ROOT=/app/sessions
+
+# Optional
+WRONGSTACK_PROVIDER=anthropic
+WRONGSTACK_MODEL=claude-3-5-sonnet-20241022
+WRONGSTACK_API_KEY=${ANTHROPIC_API_KEY}  # from secrets manager
+```
+
+## Health check
+
+```dockerfile
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD node dist/index.js diag-doctor || exit 1
+```
+
+## Image scanning
+
+```bash
+# Scan before push
+trivy image wrongstack:$GIT_SHA
+
+# Block critical vulnerabilities
+trivy image --exit-code 1 --ignore-unfixed --severity HIGH,CRITICAL wrongstack:$GIT_SHA
+```
+
+## WrongStack-specific notes
+
+- **WrongStack CLI entry point**: `packages/cli/dist/index.js` after build.
+- **pnpm workspaces**: Build from repo root — `pnpm -r build` before `docker build`.
+- **Session storage**: Sessions are stored at `WRONGSTACK_SESSION_ROOT` — mount a volume for persistence.
+- **Config**: Config is at `WRONGSTACK_CONFIG_DIR` — mount for config persistence across restarts.
+
+## Skills in scope
+
+- `security-scanner` — for scanning Dockerfiles and container configs for vulnerabilities
+- `git-flow` — for tagging releases and managing Docker image versions
+- `node-modern` — for Node.js-specific containerization patterns
+- `observability` — for logging and tracing in containerized environments

package/skills/git-flow/SKILL.md

@@ -9,6 +9,57 @@ version: 1.1.0
 
 # Git Workflow — WrongStack
 
+## Overview
+
+Guides commit messages, branch hygiene, PR strategy, and merge decisions. WrongStack uses pnpm workspaces — use `pnpm -r` for recursive commands across packages.
+
+## Rules
+
+1. One concern per commit — never mix logic changes with lockfile updates.
+2. Never force-push shared branches — use `--force-with-lease` on own branches only.
+3. Always branch from `main` or a stable release tag.
+4. Small, frequent commits with clear messages beat large, vague ones.
+5. Rebase onto `main` before PR when safe for cleaner history.
+6. Delete branches after merge unless shared or releasing.
+
+## Patterns
+
+### Do
+
+```bash
+# ✅ Good commit — what and why
+fix: correct race condition in token refresh
+
+Retry logic now respects backoff multiplier. Without this,
+repeated failures would hammer the provider instead of backing off.
+
+Fix #123
+
+# ✅ Topic branch naming
+feat/login
+fix/session-leak
+refactor/auth-layer
+
+# ✅ Feature branch → rebase → fast-forward merge
+git rebase main && git merge --ff-only feature
+```
+
+### Don't
+
+```bash
+# ❌ Bad — what, not why
+git commit -m "fix: fixed bug"
+
+# ❌ Bad — WIP commit left in main
+git commit -m "WIP"
+
+# ❌ Bad — force-push to shared branch
+git push --force origin main
+
+# ❌ Bad — mega-commit across 15 packages
+git commit -m "Update stuff"
+```
+
 ## Commit messages
 
 Format: `type: short description`
@@ -84,4 +135,5 @@ git rebase main && git merge --ff-only feature
 ## Skills in scope
 
 - `refactor-planner` — when a refactor involves multiple git-managed changes
-- `multi-agent` — for fleet-wide version audits across packages
+- `multi-agent` — for fleet-wide version audits across packages
+- `bug-hunter` — for spotting bugs at commit time before they reach main

package/skills/multi-agent/SKILL.md

@@ -9,6 +9,48 @@ version: 1.1.0
 
 # Multi-Agent Coordination — WrongStack
 
+## Overview
+
+Coordinates parallel AI agent execution for tasks that benefit from fanning out. Leader delegates narrow subtasks to workers, collects structured results, and synthesizes a unified output.
+
+## Rules
+
+1. Subagents share nothing — no memory, no session state, no variable scope.
+2. Leader must aggregate results — don't let worker output go unprocessed.
+3. Narrow task scope per subagent — broad tasks cause `budget_exhausted`.
+4. Role must match task — don't use `bug-hunter` to write docs.
+5. Check `stopReason` on every result: `end_turn` (clean), `budget_exhausted` (retry), `error` (surface), `aborted` (don't retry).
+6. Don't fan out single atomic tasks under 5 tool calls — overhead exceeds benefit.
+
+## Patterns
+
+### Do
+
+```typescript
+// ✅ Good — narrow, focused task per subagent
+batch_tool_use([
+  { tool: "delegate", input: { task: "Audit auth/session.ts for null-deref bugs", role: "bug-hunter" }},
+  { tool: "delegate", input: { task: "Audit auth/token.ts for null-deref bugs", role: "bug-hunter" }},
+  { tool: "delegate", input: { task: "Audit auth/refresh.ts for null-deref bugs", role: "bug-hunter" }},
+])
+
+// ✅ Leader passes artifact explicitly
+// Subagent B gets subagent A's output as part of the task description
+```
+
+### Don't
+
+```typescript
+// ❌ Bad — too broad, will exhaust budget
+{ task: "Audit all packages for bugs" }
+
+// ❌ Bad — no aggregation
+// Subagents return results, leader pastes raw output without synthesis
+
+// ❌ Bad — role mismatch
+{ task: "Write documentation for the API", role: "bug-hunter" }
+```
+
 ## When to fan out
 
 ✅ Good fits: