@clanker-ai/clanker

v0.0.1

Published

a month ago

Enterprise-scale, language-agnostic development harness framework with first-class OpenCode integration

0High
0Medium
0Low

superirale

harness framework scaffolding opencode enterprise development cli template boilerplate devops

Harness Engineering Framework

Enterprise-scale, specs-driven development framework with AI integration

A 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.

✨ Features

Core Capabilities

🚀 7 Language Templates: Node.js, TypeScript, Python, C++, Java, Go, Generic
📋 Specs-Driven Development: Built-in spec-pack workflow for structured feature development
🎛️ Harness Engineering: Complete feedforward + feedback control system (details)
🤖 OpenCode Native: First-class AI coding agent integration
🎯 Contract-First: OpenAPI/Swagger validation and test generation
📊 Web Dashboard: Visual spec-pack management interface
⚡ Standard Workflows: Consistent scripts across all projects
🔒 Production Ready: Full test coverage, CI/CD, and quality gates

Language Support

| Template | Language | Build System | Testing | Notable Features | | ------------ | ------------------ | ------------ | ------- | ------------------------------- | | nodejs | JavaScript/Node.js | npm | Jest | ESLint, Prettier, Docker | | typescript | TypeScript 5.x | tsc | ts-jest | Strict mode, full type coverage | | python | Python 3.8+ | pip | pytest | black, pylint, mypy | | cpp | C++20 | CMake | Catch2 | vcpkg, clang-format, sanitizers | | java | Java 11+ | Maven | JUnit | Checkstyle, google-java-format | | go | Go 1.18+ | go | testing | golangci-lint, gofmt | | generic | Any | Custom | Custom | Fully customizable |

🚀 Quick Start

New to Spec-Driven AI Development?

Start Here:

📖 30-Minute Tutorial - Build a complete REST API with AI
📚 Comprehensive Guide - Deep dive into spec-driven AI development (8,000+ lines)

Installation

npm install -g @clanker-ai/clanker

Create a New Project

# Node.js project
harness new my-api --template nodejs

# TypeScript project with strict mode
harness new my-ts-app --template typescript

# C++20 project with CMake + vcpkg
harness new my-cpp-lib --template cpp

cd my-project
./scripts/setup
npm test  # or appropriate command for your language

Start the Dashboard

# Launch web UI for spec-pack management
harness dashboard

Opens at http://localhost:3000

📋 Specs-Driven AI Development

Transform how you build software with AI agents using structured specifications and automated validation.

Learn the Workflow:

🎯 Quick Tutorial - 30 minutes to your first AI-built feature
📖 Complete Guide - Everything about spec-driven AI development

Create a Spec-Pack

# Interactive spec-pack creation
harness spec new

# Specify type directly
harness spec new user-auth --type api

Work with Spec-Packs

# List all spec-packs
harness spec list

# Validate a spec-pack
harness spec validate user-auth

# Show spec details
harness spec show user-auth

# Verify contracts
harness spec verify user-auth --generate-tests

Spec-Pack Types

API: REST API endpoints with OpenAPI contracts
Feature: Complete features with acceptance criteria
Service: Backend services with dependencies
Component: UI/UX components with examples
Refactor: Code refactoring specifications

🎯 Contract Verification

Automatically validate API contracts and generate tests:

# Verify OpenAPI specification
harness spec verify users-api

# Generate contract tests
harness spec verify users-api --generate-tests --language python

Validates:

OpenAPI/Swagger schema compliance
Breaking changes detection
Data model consistency
Acceptance example execution

🎛️ Harness Engineering

Transform spec-packs into executable control systems with feedforward guides, feedback sensors, retry logic, auto-fix, and continuous improvement.

Quick Example

# specs/user-api.spec.yml
harness:
  feedforward:
    architecture_constraints:
      - 'Use MVC pattern'
      - 'Controllers must be thin'
    few_shot_examples:
      - pattern: 'Error handling'
        example: |
          try {
            await operation();
          } catch (error) {
            logger.error('Failed', { error });
            throw new AppError('User message', 500);
          }

  feedback:
    sensors:
      - type: schema # Validate OpenAPI contract
        required: true
      - type: business_rules # Check domain logic
        required: true
      - type: security # Scan for vulnerabilities
        required: true

  operational:
    retry_strategy:
      enabled: true
      max_attempts: 3
    auto_fix:
      enabled: true
      deterministic_only: true # Safety first

Run Harness Verification

# Basic verification
harness harness verify user-api

# With options
harness harness verify user-api \
  --max-retries 5 \
  --no-auto-fix \
  --verbose

# Check improvements
harness harness improve user-api

# View statistics
harness harness stats user-api

Features

Feedforward System: Architecture constraints, few-shot examples, non-goals
Feedback Sensors: Schema, business rules, performance, security, LLM judge
Runtime Orchestration: Automatic retry with exponential backoff
Auto-Fix: Deterministic fixes applied automatically
Escalation: Smart escalation on critical failures
Steering Loop: Learn from failures, suggest improvements
Dashboard Integration: Real-time monitoring and history

Learn More

Complete Guide - Comprehensive harness documentation
Custom Sensors - Create your own validators
Steering Loop - Continuous improvement deep-dive
Migration Guide - Upgrade existing specs
Implementation Details - Technical architecture

🔧 CLI Commands

Project Management

harness new <name>           # Create new project
harness init                 # Initialize in existing project
harness validate             # Validate project structure
harness run <script>         # Run standard script
harness upgrade              # Upgrade framework version

Spec-Pack Management

harness spec new [name]      # Create new spec-pack
harness spec list            # List all spec-packs
harness spec validate <name> # Validate spec-pack
harness spec show <name>     # Display spec details
harness spec verify <name>   # Verify contracts

Harness Engineering

harness harness verify <spec>   # Full harness verification
harness harness improve <spec>  # Show improvement suggestions
harness harness stats [spec]    # Display statistics

# With options
harness harness verify my-feature \
  --max-retries 5 \
  --no-auto-fix \
  --verbose

Dashboard

harness dashboard            # Start web dashboard

🏗️ Project Structure

my-project/
├── src/                 # Source code
├── tests/               # Test files
├── specs/               # Spec-pack files
├── contracts/           # API contracts (OpenAPI, etc.)
├── scripts/             # Standard scripts
│   ├── setup           # Environment setup
│   ├── build           # Build project
│   ├── test            # Run tests
│   ├── lint            # Code linting
│   ├── format          # Code formatting
│   ├── clean           # Clean build artifacts
│   └── deploy          # Deployment
├── .opencode/           # OpenCode integration
│   ├── commands/       # Custom OpenCode commands
│   └── skills/         # OpenCode skills
├── harness.yaml         # Project configuration
├── opencode.json        # OpenCode config
└── AGENTS.md            # AI agent instructions

🤖 OpenCode Integration

Built-in Commands

Every project includes OpenCode commands:

/setup       - Setup development environment
/build       - Build the project
/test        - Run test suite with coverage
/lint        - Run code quality checks
/format      - Format code
/deploy      - Deploy the project

/spec new    - Create new spec-pack
/spec list   - List spec-packs
/spec show   - Show spec details
/spec implement - Implement a spec-pack

Custom Skills

harness-core: Project-specific workflows
spec-pack: Specs-driven development workflow

📦 Template Features

TypeScript Template

harness new my-ts-app --template typescript

Includes:

TypeScript 5.x with strict mode
ts-jest for testing
ESLint + @typescript-eslint
Full type coverage
Build optimization

C++ Template

harness new my-cpp-lib --template cpp

Includes:

Modern C++20 features
CMake 3.21+ build system
vcpkg dependency management
Catch2 v3 testing
clang-format, clang-tidy
Sanitizers (ASan, UBSan)
Coverage support

🧪 Testing

All templates include comprehensive testing setup:

# Run tests
./scripts/test

# Run with coverage
npm run test:coverage  # or language equivalent

# Watch mode
npm run test:watch

Coverage Targets: 80% across all metrics

🎨 Code Quality

Linting

./scripts/lint

# Auto-fix
npm run lint:fix  # or language equivalent

Formatting

./scripts/format

# Check only
npm run format:check

Pre-commit Hooks

Husky + lint-staged automatically:

Lint staged files
Format code
Run relevant tests

🐳 Docker Support

All templates include:

Multi-stage Dockerfile
docker-compose.yml
Optimized for production
Non-root user
Health checks

docker build -t my-app .
docker run -p 3000:3000 my-app

🔄 CI/CD Integration

GitHub Actions

# Generated automatically in .github/workflows/ci.yml
- Runs on: Ubuntu, macOS, Windows
- Node versions: 18, 20, 22
- Parallel test execution
- Coverage reporting

Custom CI/CD

Templates included for:

GitHub Actions
GitLab CI
Generic/portable pipelines

🌐 Web Dashboard

Visual interface for spec-pack management:

harness dashboard

Features:

List all spec-packs
View spec details
Validate spec-packs
Verify contracts
Real-time status updates

Ports:

Frontend: http://localhost:3000
Backend API: http://localhost:3001

📚 Documentation

Getting Started

30-Minute AI Development Tutorial ⭐ Start here!
Getting Started Guide
Quick Start

Spec-Driven AI Development

Complete Spec-Driven AI Guide - Comprehensive 8,000+ line guide
Spec-Pack Guide - Writing effective specs
OpenCode Integration - AI agent integration

Harness Engineering

Harness Complete Guide - Full harness configuration
Custom Sensors - Create custom validators
Steering Loop Deep-Dive - Continuous improvement
Migration Guide - Upgrade existing specs
Harness Implementation - Technical details

Advanced Topics

Contract Verification - OpenAPI validation
Contributing - Contribution guidelines
Security - Security policy

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Development Setup

git clone https://github.com/clanker-ai/clanker.git
cd harness-engineering
npm install
npm link
npm test

Running Tests

npm test                # All tests
npm run test:coverage   # With coverage
npm run test:watch      # Watch mode

🔒 Security

Please report security vulnerabilities to [email protected]. See SECURITY.md for details.

📊 Project Stats

Templates: 7 languages
Test Coverage: 80%+
CLI Commands: 12
OpenCode Commands: 11
Total Tests: 76+
Lines of Code: 10,000+

🗺️ Roadmap

[ ] Additional language templates (Rust, Kotlin)
[ ] Enhanced dashboard with analytics
[ ] Spec-pack versioning and migration
[ ] Plugin system for custom generators
[ ] Cloud deployment integrations
[ ] Team collaboration features

📄 License

🙏 Acknowledgments

Inspired by specs-driven development principles
Built with modern developer experience in mind
Powered by the OpenCode AI coding agent

💬 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: [email protected]

Made with ❤️ for developers who care about quality, consistency, and productivity. [Opencode session](opencode -s ses_26e1e3048ffeuVsBXNMBW4uF7n)

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Harness Engineering Framework

✨ Features

Core Capabilities

Language Support

🚀 Quick Start

New to Spec-Driven AI Development?

Installation

Create a New Project

Start the Dashboard

📋 Specs-Driven AI Development

Create a Spec-Pack

Work with Spec-Packs

Spec-Pack Types

🎯 Contract Verification

🎛️ Harness Engineering

Quick Example

Run Harness Verification

Features

Learn More

🔧 CLI Commands

Project Management

Spec-Pack Management

Harness Engineering

Dashboard

🏗️ Project Structure

🤖 OpenCode Integration

Built-in Commands

Custom Skills

📦 Template Features

TypeScript Template

C++ Template

🧪 Testing

🎨 Code Quality

Linting

Formatting

Pre-commit Hooks

🐳 Docker Support

🔄 CI/CD Integration

GitHub Actions

Custom CI/CD

🌐 Web Dashboard

📚 Documentation

Getting Started

Spec-Driven AI Development

Harness Engineering

Advanced Topics

🤝 Contributing

Development Setup

Running Tests

🔒 Security

📊 Project Stats

🗺️ Roadmap

📄 License

🙏 Acknowledgments

💬 Support