@covibes/zeroshot 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,167 @@
+## [1.0.1](https://github.com/covibes/zeroshot/compare/v1.0.0...v1.0.1) (2025-12-27)
+
+
+### Bug Fixes
+
+* **ci:** checkout latest main to prevent stale SHA race condition ([dd302ba](https://github.com/covibes/zeroshot/commit/dd302ba8e0755cea6835cfae3286b3aa51e2f92a))
+* trigger npm publish ([6aa6708](https://github.com/covibes/zeroshot/commit/6aa6708dca0e55299ba5d1be9eb54410731a7da0))
+
+# 1.0.0 (2025-12-27)
+
+
+### Bug Fixes
+
+* **ci:** update codecov to v5 and add continue-on-error ([53de603](https://github.com/covibes/zeroshot/commit/53de603d008764c31dc158a3f2702128d6cf8bc4))
+* **ci:** use Node.js 22 for semantic-release compatibility ([#9](https://github.com/covibes/zeroshot/issues/9)) ([0387c7d](https://github.com/covibes/zeroshot/commit/0387c7dcf5211b8632cf5c19a5516ad119c69a59))
+* disable checkJs to fix CI typecheck failures ([cabe14c](https://github.com/covibes/zeroshot/commit/cabe14c21e8827b26423aa1b5339cb4056f0f8a5))
+* **lint:** add missing eslint-config-prettier + fix no-control-regex ([d26e1ba](https://github.com/covibes/zeroshot/commit/d26e1ba404a85c96519d2945501dfa4b09505190))
+* mark task-lib as ES module for Node 18 compatibility ([44fea80](https://github.com/covibes/zeroshot/commit/44fea80bd4d28877786eb140d9a9d63ac9f609ee))
+* prevent agents from asking questions in non-interactive mode ([#8](https://github.com/covibes/zeroshot/issues/8)) ([458ed29](https://github.com/covibes/zeroshot/commit/458ed299aefa2790fcc951dd0efcd9d347c485ce))
+* **resume:** find last workflow trigger instead of arbitrary last 5 messages ([497c24f](https://github.com/covibes/zeroshot/commit/497c24f4bd0b8c0be168167965520600b82a3f2a))
+* **test:** correct npm install retry timing assertion ([36222d6](https://github.com/covibes/zeroshot/commit/36222d69920fc1aed012002c3846cf9f7d9e6392))
+
+
+### Features
+
+* **validator:** make validator-tester repo-calibrated and intelligent ([#5](https://github.com/covibes/zeroshot/issues/5)) ([3bccad2](https://github.com/covibes/zeroshot/commit/3bccad2ab32130efb897864de2a31d10c1f1842c))
+* **validators:** enforce test quality with antipattern detection ([#2](https://github.com/covibes/zeroshot/issues/2)) ([9b4f912](https://github.com/covibes/zeroshot/commit/9b4f91200f4429acbce300f2c049d1d23191e768))
+
+# 1.0.0 (2025-12-27)
+
+
+### Bug Fixes
+
+* **ci:** update codecov to v5 and add continue-on-error ([53de603](https://github.com/covibes/zeroshot/commit/53de603d008764c31dc158a3f2702128d6cf8bc4))
+* **ci:** use Node.js 22 for semantic-release compatibility ([#9](https://github.com/covibes/zeroshot/issues/9)) ([0387c7d](https://github.com/covibes/zeroshot/commit/0387c7dcf5211b8632cf5c19a5516ad119c69a59))
+* disable checkJs to fix CI typecheck failures ([cabe14c](https://github.com/covibes/zeroshot/commit/cabe14c21e8827b26423aa1b5339cb4056f0f8a5))
+* **lint:** add missing eslint-config-prettier + fix no-control-regex ([d26e1ba](https://github.com/covibes/zeroshot/commit/d26e1ba404a85c96519d2945501dfa4b09505190))
+* mark task-lib as ES module for Node 18 compatibility ([44fea80](https://github.com/covibes/zeroshot/commit/44fea80bd4d28877786eb140d9a9d63ac9f609ee))
+* prevent agents from asking questions in non-interactive mode ([#8](https://github.com/covibes/zeroshot/issues/8)) ([458ed29](https://github.com/covibes/zeroshot/commit/458ed299aefa2790fcc951dd0efcd9d347c485ce))
+* **resume:** find last workflow trigger instead of arbitrary last 5 messages ([497c24f](https://github.com/covibes/zeroshot/commit/497c24f4bd0b8c0be168167965520600b82a3f2a))
+* **test:** correct npm install retry timing assertion ([36222d6](https://github.com/covibes/zeroshot/commit/36222d69920fc1aed012002c3846cf9f7d9e6392))
+
+
+### Features
+
+* **validator:** make validator-tester repo-calibrated and intelligent ([#5](https://github.com/covibes/zeroshot/issues/5)) ([3bccad2](https://github.com/covibes/zeroshot/commit/3bccad2ab32130efb897864de2a31d10c1f1842c))
+* **validators:** enforce test quality with antipattern detection ([#2](https://github.com/covibes/zeroshot/issues/2)) ([9b4f912](https://github.com/covibes/zeroshot/commit/9b4f91200f4429acbce300f2c049d1d23191e768))
+
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2025-12-25
+
+### Added
+
+#### Core Architecture
+
+- Multi-agent coordination engine with message-passing primitives
+- SQLite-backed immutable ledger for crash recovery and state persistence
+- Pub/sub message bus with topic-based routing and WebSocket support
+- JavaScript-based logic engine for trigger evaluation with sandboxed execution
+- Agent lifecycle management with state machine (idle → evaluating → executing)
+- Dynamic agent spawning via CLUSTER_OPERATIONS messages
+
+#### Agent System
+
+- AgentWrapper for managing Claude CLI process lifecycle
+- Context building from ledger with configurable strategies
+- Hook system for onComplete, onError, and onStart actions
+- Output streaming via message bus with real-time updates
+- Liveness detection to identify stuck agents
+- Resume capability for failed tasks with error context
+- Dynamic model selection based on iteration count and complexity
+- Support for both static and parameterized model configurations
+
+#### CLI Commands
+
+- `zeroshot run` - Start multi-agent cluster from GitHub issue or text
+- `zeroshot auto` - Full automation with Docker isolation and auto-merge PR
+- `zeroshot list` - View all running clusters and tasks
+- `zeroshot status` - Get detailed cluster status with zombie detection
+- `zeroshot logs` - Follow cluster output in real-time
+- `zeroshot resume` - Continue from crashed or stopped clusters
+- `zeroshot stop` - Graceful cluster shutdown
+- `zeroshot kill` - Force stop running cluster
+- `zeroshot clear` - Remove all stopped clusters
+- `zeroshot export` - Export conversation as JSON or Markdown
+- `zeroshot watch` - Interactive TUI dashboard (htop-style)
+- `zeroshot agents` - View available agent definitions
+- `zeroshot settings` - Manage global settings
+- Shell completion support via omelette
+
+#### Docker Isolation
+
+- IsolationManager for container lifecycle management
+- Fresh git repository initialization in isolated containers
+- Credential mounting for Claude CLI, AWS, GitHub, Kubernetes
+- Docker-in-Docker support for e2e tests
+- Automatic npm dependency installation in containers
+- Terraform state preservation across container cleanup
+- Git worktree support (alternative to full copy)
+
+#### Workflow Templates
+
+- Conductor system with 2D classification (Complexity × TaskType)
+- Four base templates: single-worker, worker-validator, debug-workflow, full-workflow
+- Parameterized template resolution with TemplateResolver
+- Dynamic agent spawning based on task analysis
+- Model tier selection: Haiku (TRIVIAL), Sonnet (SIMPLE/STANDARD), Opus (CRITICAL)
+- Validator scaling: 0-5 validators based on complexity
+- Adversarial tester for STANDARD/CRITICAL tasks
+
+#### GitHub Integration
+
+- Issue fetching with automatic URL parsing
+- GitHub CLI (gh) integration for PR creation
+- Auto-merge support via git-pusher agent
+- Token authentication with hosts.yml fallback
+
+#### TUI Dashboard
+
+- Real-time cluster monitoring with blessed/blessed-contrib
+- Cluster list with state, agent count, and message count
+- Message viewer with topic filtering
+- Agent status display with iteration tracking
+- Log viewer with search and navigation
+- System resource monitoring (CPU, memory)
+- Responsive layout with keyboard navigation
+
+#### Developer Tools
+
+- Config validator with strict mode and warning detection
+- ESLint configuration with unused imports detection
+- TypeScript type checking with JSDoc annotations
+- Mocha test framework with comprehensive test coverage
+- Dead code detection with ts-prune, unimported, depcheck
+- Proper lockfile support for concurrent file access
+
+#### Safety Features
+
+- PreToolUse hook to block AskUserQuestion in non-interactive mode
+- Explicit prompts for autonomous decision-making
+- Git safety enforcement (no destructive operations)
+- Zombie cluster detection for orphaned processes
+- Retry logic with exponential backoff for network operations
+- File locking for concurrent orchestrator instances
+
+### Security
+
+- Sandboxed JavaScript execution for trigger logic
+- Frozen prototypes in VM context to prevent pollution
+- Read-only mounts for credentials in Docker containers
+- Docker group GID detection for socket access control
+- Timeout enforcement for logic scripts (1 second limit)
+
+## [0.0.0] - Development
+
+Initial development phase before first release.
+
+[Unreleased]: https://github.com/covibes/zeroshot/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/covibes/zeroshot/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Covibes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,364 @@
+# zeroshot CLI
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node 18+](https://img.shields.io/badge/node-18%2B-brightgreen.svg)](https://nodejs.org/)
+[![Platform: Linux | macOS](https://img.shields.io/badge/platform-Linux%20%7C%20macOS-blue.svg)]()
+
+**Multi-agent coding CLI built on Claude Code.**
+
+You know the problem. Your AI agent:
+
+- Says "tests pass" (never ran them)
+- Says "done!" (nothing works)
+- Implements 60% of what you asked
+- Ignores your coding guidelines
+- Introduces antipatterns like a junior dev
+- Gets sloppy on long tasks
+
+**AI is extremely capable. But not when one agent does everything in one session.**
+
+Context degrades. Attention drifts. Shortcuts get taken.
+
+Zeroshot fixes this with **multiple isolated agents** that check each other's work. The validator didn't write the code, so it can't lie about tests. Fail? Fix and retry until it works.
+
+```bash
+zeroshot 123
+```
+
+Point at a GitHub issue, walk away, come back to working code.
+
+### Demo
+
+```bash
+zeroshot "Add rate limiting middleware: sliding window algorithm (not fixed window),
+per-IP tracking with in-memory store and automatic TTL cleanup to prevent memory leaks,
+configurable limits per endpoint. Return 429 Too Many Requests with Retry-After header
+(seconds until reset) and X-RateLimit-Remaining header on ALL responses.
+Must handle both IPv4 and IPv6, normalizing IPv6 to consistent format."
+```
+
+<p align="center">
+  <img src="./docs/assets/zeroshot-demo.gif" alt="Demo" width="700">
+  <br>
+  <em>Sped up — original recording: 32 minutes</em>
+</p>
+
+---
+
+## Install
+
+**Platforms**: Linux, macOS
+
+```bash
+npm install -g @covibes/zeroshot
+```
+
+**Requires**: Node 18+, [Claude Code CLI](https://claude.com/product/claude-code), [GitHub CLI](https://cli.github.com/)
+
+```bash
+npm i -g @anthropic-ai/claude-code && claude auth login
+gh auth login
+```
+
+---
+
+## Commands
+
+```bash
+zeroshot 123                   # Run on GitHub issue
+zeroshot "Add dark mode"       # Run from description
+
+# Full automation (isolated container + PR + merge)
+zeroshot auto 123
+zeroshot auto 123 -d           # Background
+
+# Control
+zeroshot list                  # See all running
+zeroshot logs <id> -f          # Follow output
+zeroshot resume <id>           # Continue after crash
+zeroshot kill <id>             # Stop
+zeroshot watch                 # TUI dashboard
+```
+
+---
+
+## FAQ
+
+**Q: Why Claude-only?**
+
+Claude Code is the most capable agentic coding tool available. We wrap it directly - same tools, same reliability, no custom implementations to break.
+
+**Q: Why do single-agent coding sessions get sloppy?**
+
+Three failure modes compound when one agent does everything in one session:
+
+- **Context Dilution**: Your initial guidelines compete with thousands of tokens of code, errors, and edits. Instructions from 50 messages ago get buried.
+- **Success Bias**: LLMs optimize for "Task Complete" - even if that means skipping steps to get there.
+- **Error Snowball**: When fixing mistakes repeatedly, the context fills with broken code. The model starts copying its own bad patterns.
+
+Zeroshot fixes this with **isolated agents** where validators check work they didn't write - no self-grading, no shortcuts.
+
+**Q: Can I customize the team?**
+
+Yes, see CLAUDE.md. But most people never need to.
+
+**Q: Why does the CLI appear frozen?**
+
+Zeroshot agents use strict JSON schema outputs to ensure reliable parsing and hook execution. This is incompatible with live streaming - agents can't stream partial JSON.
+
+During heavy tasks (large refactors, complex analysis), the CLI may appear frozen for several minutes while the agent works. This is normal - the agent is actively running, just not streaming output.
+
+**Q: Why is it called "zeroshot"?**
+
+In machine learning, "zero-shot" means solving tasks the model has never seen before - using only the task description, no prior examples needed.
+
+Same idea here: give zeroshot a well-defined task, get back a result. No examples. No iterative feedback. No hand-holding.
+
+The multi-agent architecture handles planning, implementation, and validation internally. You provide a clear problem statement. Zeroshot handles the rest.
+
+---
+
+## How It Works
+
+Zeroshot is a **multi-agent coordination framework** with smart defaults.
+
+### Zero Config
+
+```bash
+zeroshot 123  # Analyzes task → picks team → done
+```
+
+The conductor classifies your task (complexity × type) and routes to a pre-built workflow.
+
+### Default Workflows (Out of the Box)
+
+```
+                                ┌─────────────────┐
+                                │      TASK       │
+                                └────────┬────────┘
+                                         │
+                                         ▼
+                ┌────────────────────────────────────────────┐
+                │                 CONDUCTOR                  │
+                │     Complexity × TaskType → Workflow       │
+                └────────────────────────┬───────────────────┘
+                                         │
+           ┌─────────────────────────────┼─────────────────────────────┐
+           │                             │                             │
+           ▼                             ▼                             ▼
+     ┌───────────┐                ┌───────────┐                ┌───────────┐
+     │  TRIVIAL  │                │  SIMPLE   │                │ STANDARD+ │
+     │  1 agent  │──────────▶     │  worker   │                │ planner   │
+     │  (haiku)  │  COMPLETE      │ + 1 valid.│                │ + worker  │
+     │ no valid. │                └─────┬─────┘                │ + 3-5 val.│
+     └───────────┘                      │                      └─────┬─────┘
+                                        ▼                            │
+                                 ┌─────────────┐                     ▼
+                             ┌──▶│   WORKER    │             ┌─────────────┐
+                             │   └──────┬──────┘             │   PLANNER   │
+                             │          │                    └──────┬──────┘
+                             │          ▼                           │
+                             │   ┌─────────────────────┐            ▼
+                             │   │ ✓ validator         │     ┌─────────────┐
+                             │   │   (generic check)   │ ┌──▶│   WORKER    │
+                             │   └──────────┬──────────┘ │   └──────┬──────┘
+                             │       REJECT │ ALL OK     │          │
+                             └──────────────┘     │      │          ▼
+                                                  │      │   ┌──────────────────────┐
+                                                  │      │   │ ✓ requirements       │
+                                                  │      │   │ ✓ code (STANDARD+)   │
+                                                  │      │   │ ✓ security (CRIT)    │
+                                                  │      │   │ ✓ tester (CRIT)      │
+                                                  │      │   │ ✓ adversarial        │
+                                                  │      │   │   (curl + browser)   │
+                                                  │      │   └──────────┬───────────┘
+                                                  │      │       REJECT │ ALL OK
+                                                  │      └──────────────┘     │
+                                                  ▼                           ▼
+     ┌─────────────────────────────────────────────────────────────────────────────┐
+     │                                COMPLETE                                     │
+     └─────────────────────────────────────────────────────────────────────────────┘
+```
+
+These are **templates**. The conductor picks based on what you're building.
+
+| Task                   | Complexity | Agents | Validators                                        |
+| ---------------------- | ---------- | ------ | ------------------------------------------------- |
+| Fix typo in README     | TRIVIAL    | 1      | None                                              |
+| Add dark mode toggle   | SIMPLE     | 2      | generic validator                                 |
+| Refactor auth system   | STANDARD   | 5      | requirements, code, adversarial                   |
+| Implement payment flow | CRITICAL   | 7      | requirements, code, security, tester, adversarial |
+
+## End-to-End Flow
+
+**This is how zeroshot processes a task from start to finish:**
+
+```
+                              ╔═════════════════════════════════════════════════════╗
+                              ║            ZEROSHOT ORCHESTRATION ENGINE            ║
+                              ╚═════════════════════════════════════════════════════╝
+
+                                              ┌─────────────────┐
+                                              │   "Add auth     │
+                                              │   to the API"   │
+                                              └────────┬────────┘
+                                                       │
+                                                       ▼
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│                              CONDUCTOR (2D Classification)                                    │
+│  ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
+│  │  Junior (Haiku)                                     Senior (Sonnet)                     │ │
+│  │  ─────────────                                      ───────────────                     │ │
+│  │  Fast classification on 2 dimensions:        ───▶   Handles UNCERTAIN cases             │ │
+│  │  • Complexity: TRIVIAL | SIMPLE | STANDARD   (if    with deeper analysis                │ │
+│  │  • TaskType: INQUIRY | TASK | DEBUG          Junior                                     │ │
+│  │                                              unsure)                                    │ │
+│  └─────────────────────────────────────────────────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+                                                       │
+                                                       │ Classification: STANDARD × TASK
+                                                       ▼
+                              ┌─────────────────────────────────────────┐
+                              │            CONFIG ROUTER                │
+                              │  ─────────────────────────────────────  │
+                              │  TRIVIAL        → single-worker         │
+                              │  SIMPLE         → worker-validator      │
+                              │  DEBUG (non-trivial) → debug-workflow   │
+                              │  STANDARD/CRITICAL  → full-workflow  ◀──│
+                              └─────────────────────────────────────────┘
+                                                       │
+                                                       │ Spawns full-workflow agents
+                                                       ▼
+┌──────────────────────────────────────────────────────────────────────────────────────────────┐
+│                                    FULL WORKFLOW                                             │
+│  ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │
+│  │                                                                                         │ │
+│  │   ┌──────────────┐                                                                      │ │
+│  │   │   PLANNER    │  Creates implementation plan                                         │ │
+│  │   │ (opus/sonnet)│  • Analyzes requirements                                             │ │
+│  │   └──────┬───────┘  • Identifies files to change                                        │ │
+│  │          │          • Breaks into actionable steps                                      │ │
+│  │          │ PLAN_READY                                                                   │ │
+│  │          ▼                                                                              │ │
+│  │   ┌──────────────┐                                                                      │ │
+│  │   │    WORKER    │◀─────────────────────────────────────────────┐                       │ │
+│  │   │   (sonnet)   │  Implements the plan                         │                       │ │
+│  │   └──────┬───────┘  • Writes/modifies code                      │                       │ │
+│  │          │          • Handles rejections                        │                       │ │
+│  │          │ IMPLEMENTATION_READY                                 │                       │ │
+│  │          ▼                                                      │                       │ │
+│  │   ┌─────────────────────────────────────────────────────┐       │                       │ │
+│  │   │              VALIDATORS (parallel)                  │       │                       │ │
+│  │   │                                                     │       │                       │ │
+│  │   │  ┌────────────┐ ┌────────────┐ ┌─────────────────┐  │       │ REJECTED              │ │
+│  │   │  │Requirements│ │Code Review │ │  Adversarial    │  │       │                       │ │
+│  │   │  │  Validator │ │  (reviewer)│ │    Tester       │  │───────┘                       │ │
+│  │   │  │ (validator)│ │            │ │ EXECUTES tests  │  │                               │ │
+│  │   │  └────────────┘ └────────────┘ └─────────────────┘  │                               │ │
+│  │   │                                                     │                               │ │
+│  │   └──────────────────────┬──────────────────────────────┘                               │ │
+│  │                          │                                                              │ │
+│  │                          │ ALL APPROVED                                                 │ │
+│  │                          ▼                                                              │ │
+│  │                   ┌──────────────┐                                                      │ │
+│  │                   │   COMPLETE   │                                                      │ │
+│  │                   │  ──────────  │                                                      │ │
+│  │                   │  PR Created  │  (with --pr flag)                                    │ │
+│  │                   │  Auto-merged │  (with --merge flag)                                 │ │
+│  │                   └──────────────┘                                                      │ │
+│  │                                                                                         │ │
+│  └─────────────────────────────────────────────────────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+### Model Selection by Complexity
+
+| Complexity | Planner | Worker | Validators |
+| ---------- | ------- | ------ | ---------- |
+| TRIVIAL    | -       | haiku  | 0          |
+| SIMPLE     | -       | sonnet | 1 (sonnet) |
+| STANDARD   | sonnet  | sonnet | 3 (sonnet) |
+| CRITICAL   | opus    | sonnet | 5 (sonnet) |
+
+---
+
+### Custom Workflows (Framework Mode)
+
+Zeroshot is **message-driven** - define any agent topology:
+
+- **Expert panels**: Parallel specialists → aggregator → decision
+- **Staged gates**: Sequential validators, each with veto power
+- **Hierarchical**: Supervisor dynamically spawns workers
+- **Dynamic**: Conductor adds agents mid-execution
+
+**Coordination primitives:**
+
+- Message bus (pub/sub topics)
+- Triggers (wake agents on conditions)
+- Ledger (SQLite, crash recovery)
+- Dynamic spawning (CLUSTER_OPERATIONS)
+
+See [CLAUDE.md](./CLAUDE.md) for custom cluster configs.
+
+You don't configure defaults. But you **can** when needed.
+
+---
+
+## Crash Recovery
+
+Everything saves to SQLite. If your 2-hour run crashes at 1:59:
+
+```bash
+zeroshot resume cluster-bold-panther
+# Continues from exact point
+```
+
+---
+
+## Docker Isolation
+
+```bash
+zeroshot 123 --isolation
+```
+
+Runs in a fresh container. Your workspace stays untouched. Good for risky experiments.
+
+---
+
+## More
+
+- **Debug**: `sqlite3 ~/.zeroshot/cluster-abc.db "SELECT * FROM messages;"`
+- **Export**: `zeroshot export <id> --format markdown`
+- **Architecture**: See [CLAUDE.md](./CLAUDE.md)
+
+---
+
+## Troubleshooting
+
+| Issue                         | Fix                                                                  |
+| ----------------------------- | -------------------------------------------------------------------- |
+| `claude: command not found`   | `npm i -g @anthropic-ai/claude-code && claude auth login`            |
+| `gh: command not found`       | [Install GitHub CLI](https://cli.github.com/)                        |
+| CLI frozen for minutes        | Normal - agents use JSON schema output, can't stream partial results |
+| `--isolation` fails           | Docker must be running: `docker ps` to verify                        |
+| Cluster stuck                 | `zeroshot resume <id>` to continue with guidance                     |
+| Agent keeps failing           | Check `zeroshot logs <id>` for actual error                          |
+| `zeroshot: command not found` | `npm install -g @covibes/zeroshot`                                   |
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and guidelines.
+
+Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
+
+For security issues, see [SECURITY.md](SECURITY.md).
+
+---
+
+MIT — [Covibes](https://github.com/covibes)
+
+Built on [Claude Code](https://claude.com/product/claude-code) by Anthropic.
+
+