{"_id":"@clanker-ai/clanker","name":"@clanker-ai/clanker","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"@clanker-ai/clanker","version":"0.0.1","description":"Enterprise-scale, language-agnostic development harness framework with first-class OpenCode integration","type":"module","main":"src/index.js","bin":{"harness":"src/index.js"},"scripts":{"dev":"node src/index.js","test":"NODE_OPTIONS=--experimental-vm-modules jest","test:watch":"NODE_OPTIONS=--experimental-vm-modules jest --watch","test:coverage":"NODE_OPTIONS=--experimental-vm-modules jest --coverage","test:ci":"NODE_OPTIONS=--experimental-vm-modules jest --ci --coverage --maxWorkers=2","lint":"eslint src/","lint:fix":"eslint src/ --fix","format":"prettier --write src/ templates/ docs/","format:check":"prettier --check src/ templates/ docs/","prepare":"husky install","lint-staged":"lint-staged","prepublishOnly":"npm run lint && npm run test:ci"},"keywords":["harness","framework","scaffolding","opencode","enterprise","development","cli","template","boilerplate","devops"],"author":{"name":"superirale"},"license":"MIT","engines":{"node":">=18.0.0"},"dependencies":{"ajv":"^8.12.0","ajv-formats":"^2.1.1","chalk":"^5.3.0","commander":"^11.1.0","fs-extra":"^11.2.0","glob":"^10.3.10","handlebars":"^4.7.8","inquirer":"^9.2.12","openapi-validator-middleware":"^3.2.2","ora":"^7.0.1","swagger-parser":"^10.0.3","validate-npm-package-name":"^5.0.0","yaml":"^2.3.4"},"devDependencies":{"@types/jest":"^29.5.11","eslint":"^8.55.0","husky":"^8.0.3","jest":"^29.7.0","lint-staged":"^15.2.0","mock-fs":"^5.2.0","prettier":"^3.1.1","strip-ansi":"^7.1.0","supertest":"^6.3.3","tmp":"^0.2.1"},"repository":{"type":"git","url":"git+https://github.com/clanker-ai/clanker.git"},"bugs":{"url":"https://github.com/clanker-ai/clanker/issues"},"homepage":"https://github.com/clanker-ai/clanker#readme","gitHead":"84ece133481d1fa3f1b14291715df18a06d49f23","_id":"@clanker-ai/clanker@0.0.1","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-tMCB4UZQ2s6Ge0RRqE/mo1snuAOwt+GczaCCtGY0fyyphUht1Tn91NUNheS3SabeJfw8h/ZHw7Y1tUIoTpcYMw==","shasum":"deddc44803744b22cf8015a4b6cc1db94aa1646b","tarball":"https://registry.npmjs.org/@clanker-ai/clanker/-/clanker-0.0.1.tgz","fileCount":183,"unpackedSize":974090,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIEPTgFX6oG0w3w2CdVuQJc6ec8ncBUrU3/7DbAc7aGY1AiBIO0A4grfAxD8Z7kgT8C4UvUN4wImUEdgGHu8XCeyWCg=="}]},"_npmUser":{"name":"superirale","email":"superirale@gmail.com"},"directories":{},"maintainers":[{"name":"superirale","email":"superirale@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/clanker_0.0.1_1776444249372_0.35500321292453996"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-17T16:44:09.243Z","0.0.1":"2026-04-17T16:44:09.564Z","modified":"2026-04-17T16:44:09.842Z"},"maintainers":[{"name":"superirale","email":"superirale@gmail.com"}],"description":"Enterprise-scale, language-agnostic development harness framework with first-class OpenCode integration","homepage":"https://github.com/clanker-ai/clanker#readme","keywords":["harness","framework","scaffolding","opencode","enterprise","development","cli","template","boilerplate","devops"],"repository":{"type":"git","url":"git+https://github.com/clanker-ai/clanker.git"},"author":{"name":"superirale"},"bugs":{"url":"https://github.com/clanker-ai/clanker/issues"},"license":"MIT","readme":"# Harness Engineering Framework\n\n[![CI](https://github.com/clanker-ai/clanker/actions/workflows/ci.yml/badge.svg)](https://github.com/clanker-ai/clanker/actions/workflows/ci.yml)\n[![npm version](https://badge.fury.io/js/@clanker-ai%2Fclanker.svg)](https://www.npmjs.com/package/@clanker-ai/clanker)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n\n> **Enterprise-scale, specs-driven development framework with AI integration**\n\nA comprehensive framework for scaffolding, building, and managing software projects with consistent workflows, quality gates, and AI-powered development assistance. Built for modern software engineering with TypeScript, C++, and more.\n\n## ✨ Features\n\n### Core Capabilities\n\n- 🚀 **7 Language Templates**: Node.js, TypeScript, Python, C++, Java, Go, Generic\n- 📋 **Specs-Driven Development**: Built-in spec-pack workflow for structured feature development\n- 🎛️ **Harness Engineering**: Complete feedforward + feedback control system ([details](HARNESS_COMPLETE.md))\n- 🤖 **OpenCode Native**: First-class AI coding agent integration\n- 🎯 **Contract-First**: OpenAPI/Swagger validation and test generation\n- 📊 **Web Dashboard**: Visual spec-pack management interface\n- ⚡ **Standard Workflows**: Consistent scripts across all projects\n- 🔒 **Production Ready**: Full test coverage, CI/CD, and quality gates\n\n### Language Support\n\n| Template     | Language           | Build System | Testing | Notable Features                |\n| ------------ | ------------------ | ------------ | ------- | ------------------------------- |\n| `nodejs`     | JavaScript/Node.js | npm          | Jest    | ESLint, Prettier, Docker        |\n| `typescript` | TypeScript 5.x     | tsc          | ts-jest | Strict mode, full type coverage |\n| `python`     | Python 3.8+        | pip          | pytest  | black, pylint, mypy             |\n| `cpp`        | C++20              | CMake        | Catch2  | vcpkg, clang-format, sanitizers |\n| `java`       | Java 11+           | Maven        | JUnit   | Checkstyle, google-java-format  |\n| `go`         | Go 1.18+           | go           | testing | golangci-lint, gofmt            |\n| `generic`    | Any                | Custom       | Custom  | Fully customizable              |\n\n## 🚀 Quick Start\n\n### New to Spec-Driven AI Development?\n\n**Start Here:**\n\n- 📖 **[30-Minute Tutorial](docs/ai-development-tutorial.md)** - Build a complete REST API with AI\n- 📚 **[Comprehensive Guide](docs/spec-driven-ai-guide.md)** - Deep dive into spec-driven AI development (8,000+ lines)\n\n### Installation\n\n```bash\nnpm install -g @clanker-ai/clanker\n```\n\n### Create a New Project\n\n```bash\n# Node.js project\nharness new my-api --template nodejs\n\n# TypeScript project with strict mode\nharness new my-ts-app --template typescript\n\n# C++20 project with CMake + vcpkg\nharness new my-cpp-lib --template cpp\n\ncd my-project\n./scripts/setup\nnpm test  # or appropriate command for your language\n```\n\n### Start the Dashboard\n\n```bash\n# Launch web UI for spec-pack management\nharness dashboard\n```\n\nOpens at http://localhost:3000\n\n## 📋 Specs-Driven AI Development\n\nTransform how you build software with AI agents using structured specifications and automated validation.\n\n**Learn the Workflow:**\n\n- 🎯 **[Quick Tutorial](docs/ai-development-tutorial.md)** - 30 minutes to your first AI-built feature\n- 📖 **[Complete Guide](docs/spec-driven-ai-guide.md)** - Everything about spec-driven AI development\n\n### Create a Spec-Pack\n\n```bash\n# Interactive spec-pack creation\nharness spec new\n\n# Specify type directly\nharness spec new user-auth --type api\n```\n\n### Work with Spec-Packs\n\n```bash\n# List all spec-packs\nharness spec list\n\n# Validate a spec-pack\nharness spec validate user-auth\n\n# Show spec details\nharness spec show user-auth\n\n# Verify contracts\nharness spec verify user-auth --generate-tests\n```\n\n### Spec-Pack Types\n\n- **API**: REST API endpoints with OpenAPI contracts\n- **Feature**: Complete features with acceptance criteria\n- **Service**: Backend services with dependencies\n- **Component**: UI/UX components with examples\n- **Refactor**: Code refactoring specifications\n\n## 🎯 Contract Verification\n\nAutomatically validate API contracts and generate tests:\n\n```bash\n# Verify OpenAPI specification\nharness spec verify users-api\n\n# Generate contract tests\nharness spec verify users-api --generate-tests --language python\n```\n\n**Validates**:\n\n- OpenAPI/Swagger schema compliance\n- Breaking changes detection\n- Data model consistency\n- Acceptance example execution\n\n## 🎛️ Harness Engineering\n\nTransform spec-packs into **executable control systems** with feedforward guides, feedback sensors, retry logic, auto-fix, and continuous improvement.\n\n### Quick Example\n\n```yaml\n# specs/user-api.spec.yml\nharness:\n  feedforward:\n    architecture_constraints:\n      - 'Use MVC pattern'\n      - 'Controllers must be thin'\n    few_shot_examples:\n      - pattern: 'Error handling'\n        example: |\n          try {\n            await operation();\n          } catch (error) {\n            logger.error('Failed', { error });\n            throw new AppError('User message', 500);\n          }\n\n  feedback:\n    sensors:\n      - type: schema # Validate OpenAPI contract\n        required: true\n      - type: business_rules # Check domain logic\n        required: true\n      - type: security # Scan for vulnerabilities\n        required: true\n\n  operational:\n    retry_strategy:\n      enabled: true\n      max_attempts: 3\n    auto_fix:\n      enabled: true\n      deterministic_only: true # Safety first\n```\n\n### Run Harness Verification\n\n```bash\n# Basic verification\nharness harness verify user-api\n\n# With options\nharness harness verify user-api \\\n  --max-retries 5 \\\n  --no-auto-fix \\\n  --verbose\n\n# Check improvements\nharness harness improve user-api\n\n# View statistics\nharness harness stats user-api\n```\n\n### Features\n\n- **Feedforward System**: Architecture constraints, few-shot examples, non-goals\n- **Feedback Sensors**: Schema, business rules, performance, security, LLM judge\n- **Runtime Orchestration**: Automatic retry with exponential backoff\n- **Auto-Fix**: Deterministic fixes applied automatically\n- **Escalation**: Smart escalation on critical failures\n- **Steering Loop**: Learn from failures, suggest improvements\n- **Dashboard Integration**: Real-time monitoring and history\n\n### Learn More\n\n- **[Complete Guide](docs/harness-guide.md)** - Comprehensive harness documentation\n- **[Custom Sensors](docs/custom-sensors.md)** - Create your own validators\n- **[Steering Loop](docs/steering-loop.md)** - Continuous improvement deep-dive\n- **[Migration Guide](docs/migration-guide.md)** - Upgrade existing specs\n- **[Implementation Details](HARNESS_COMPLETE.md)** - Technical architecture\n\n## 🔧 CLI Commands\n\n### Project Management\n\n```bash\nharness new <name>           # Create new project\nharness init                 # Initialize in existing project\nharness validate             # Validate project structure\nharness run <script>         # Run standard script\nharness upgrade              # Upgrade framework version\n```\n\n### Spec-Pack Management\n\n```bash\nharness spec new [name]      # Create new spec-pack\nharness spec list            # List all spec-packs\nharness spec validate <name> # Validate spec-pack\nharness spec show <name>     # Display spec details\nharness spec verify <name>   # Verify contracts\n```\n\n### Harness Engineering\n\n```bash\nharness harness verify <spec>   # Full harness verification\nharness harness improve <spec>  # Show improvement suggestions\nharness harness stats [spec]    # Display statistics\n\n# With options\nharness harness verify my-feature \\\n  --max-retries 5 \\\n  --no-auto-fix \\\n  --verbose\n```\n\n### Dashboard\n\n```bash\nharness dashboard            # Start web dashboard\n```\n\n## 🏗️ Project Structure\n\n```\nmy-project/\n├── src/                 # Source code\n├── tests/               # Test files\n├── specs/               # Spec-pack files\n├── contracts/           # API contracts (OpenAPI, etc.)\n├── scripts/             # Standard scripts\n│   ├── setup           # Environment setup\n│   ├── build           # Build project\n│   ├── test            # Run tests\n│   ├── lint            # Code linting\n│   ├── format          # Code formatting\n│   ├── clean           # Clean build artifacts\n│   └── deploy          # Deployment\n├── .opencode/           # OpenCode integration\n│   ├── commands/       # Custom OpenCode commands\n│   └── skills/         # OpenCode skills\n├── harness.yaml         # Project configuration\n├── opencode.json        # OpenCode config\n└── AGENTS.md            # AI agent instructions\n```\n\n## 🤖 OpenCode Integration\n\n### Built-in Commands\n\nEvery project includes OpenCode commands:\n\n```\n/setup       - Setup development environment\n/build       - Build the project\n/test        - Run test suite with coverage\n/lint        - Run code quality checks\n/format      - Format code\n/deploy      - Deploy the project\n\n/spec new    - Create new spec-pack\n/spec list   - List spec-packs\n/spec show   - Show spec details\n/spec implement - Implement a spec-pack\n```\n\n### Custom Skills\n\n- **harness-core**: Project-specific workflows\n- **spec-pack**: Specs-driven development workflow\n\n## 📦 Template Features\n\n### TypeScript Template\n\n```bash\nharness new my-ts-app --template typescript\n```\n\n**Includes**:\n\n- TypeScript 5.x with strict mode\n- ts-jest for testing\n- ESLint + @typescript-eslint\n- Full type coverage\n- Build optimization\n\n### C++ Template\n\n```bash\nharness new my-cpp-lib --template cpp\n```\n\n**Includes**:\n\n- Modern C++20 features\n- CMake 3.21+ build system\n- vcpkg dependency management\n- Catch2 v3 testing\n- clang-format, clang-tidy\n- Sanitizers (ASan, UBSan)\n- Coverage support\n\n## 🧪 Testing\n\nAll templates include comprehensive testing setup:\n\n```bash\n# Run tests\n./scripts/test\n\n# Run with coverage\nnpm run test:coverage  # or language equivalent\n\n# Watch mode\nnpm run test:watch\n```\n\n**Coverage Targets**: 80% across all metrics\n\n## 🎨 Code Quality\n\n### Linting\n\n```bash\n./scripts/lint\n\n# Auto-fix\nnpm run lint:fix  # or language equivalent\n```\n\n### Formatting\n\n```bash\n./scripts/format\n\n# Check only\nnpm run format:check\n```\n\n### Pre-commit Hooks\n\nHusky + lint-staged automatically:\n\n- Lint staged files\n- Format code\n- Run relevant tests\n\n## 🐳 Docker Support\n\nAll templates include:\n\n- Multi-stage Dockerfile\n- docker-compose.yml\n- Optimized for production\n- Non-root user\n- Health checks\n\n```bash\ndocker build -t my-app .\ndocker run -p 3000:3000 my-app\n```\n\n## 🔄 CI/CD Integration\n\n### GitHub Actions\n\n```yaml\n# Generated automatically in .github/workflows/ci.yml\n- Runs on: Ubuntu, macOS, Windows\n- Node versions: 18, 20, 22\n- Parallel test execution\n- Coverage reporting\n```\n\n### Custom CI/CD\n\nTemplates included for:\n\n- GitHub Actions\n- GitLab CI\n- Generic/portable pipelines\n\n## 🌐 Web Dashboard\n\nVisual interface for spec-pack management:\n\n```bash\nharness dashboard\n```\n\n**Features**:\n\n- List all spec-packs\n- View spec details\n- Validate spec-packs\n- Verify contracts\n- Real-time status updates\n\n**Ports**:\n\n- Frontend: http://localhost:3000\n- Backend API: http://localhost:3001\n\n## 📚 Documentation\n\n### Getting Started\n\n- **[30-Minute AI Development Tutorial](docs/ai-development-tutorial.md)** ⭐ Start here!\n- [Getting Started Guide](docs/getting-started.md)\n- [Quick Start](QUICKSTART.md)\n\n### Spec-Driven AI Development\n\n- **[Complete Spec-Driven AI Guide](docs/spec-driven-ai-guide.md)** - Comprehensive 8,000+ line guide\n- [Spec-Pack Guide](docs/spec-pack-guide.md) - Writing effective specs\n- [OpenCode Integration](docs/opencode-integration.md) - AI agent integration\n\n### Harness Engineering\n\n- [Harness Complete Guide](docs/harness-guide.md) - Full harness configuration\n- [Custom Sensors](docs/custom-sensors.md) - Create custom validators\n- [Steering Loop Deep-Dive](docs/steering-loop.md) - Continuous improvement\n- [Migration Guide](docs/migration-guide.md) - Upgrade existing specs\n- [Harness Implementation](HARNESS_COMPLETE.md) - Technical details\n\n### Advanced Topics\n\n- [Contract Verification](docs/contract-verification.md) - OpenAPI validation\n- [Contributing](CONTRIBUTING.md) - Contribution guidelines\n- [Security](SECURITY.md) - Security policy\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n### Development Setup\n\n```bash\ngit clone https://github.com/clanker-ai/clanker.git\ncd harness-engineering\nnpm install\nnpm link\nnpm test\n```\n\n### Running Tests\n\n```bash\nnpm test                # All tests\nnpm run test:coverage   # With coverage\nnpm run test:watch      # Watch mode\n```\n\n## 🔒 Security\n\nPlease report security vulnerabilities to security@clanker.ai. See [SECURITY.md](SECURITY.md) for details.\n\n## 📊 Project Stats\n\n- **Templates**: 7 languages\n- **Test Coverage**: 80%+\n- **CLI Commands**: 12\n- **OpenCode Commands**: 11\n- **Total Tests**: 76+\n- **Lines of Code**: 10,000+\n\n## 🗺️ Roadmap\n\n- [ ] Additional language templates (Rust, Kotlin)\n- [ ] Enhanced dashboard with analytics\n- [ ] Spec-pack versioning and migration\n- [ ] Plugin system for custom generators\n- [ ] Cloud deployment integrations\n- [ ] Team collaboration features\n\n## 📄 License\n\nMIT © [superirale](https://github.com/superirale)\n\n## 🙏 Acknowledgments\n\n- Inspired by specs-driven development principles\n- Built with modern developer experience in mind\n- Powered by the OpenCode AI coding agent\n\n## 💬 Support\n\n- **Issues**: [GitHub Issues](https://github.com/clanker-ai/clanker/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/clanker-ai/clanker/discussions)\n- **Email**: support@superirale.com\n\n---\n\nMade with ❤️ for developers who care about quality, consistency, and productivity.\n[Opencode session](opencode -s ses_26e1e3048ffeuVsBXNMBW4uF7n)\n","readmeFilename":"README.md","_rev":"1-dca97beadd81ad9e30589239d1c620a3"}