converge-tool 0.2.3

# Converge: Semantic Governance & Alignment

> Converge is a vision for **semantic governance**. We move from fragmented intent to unified, converged states through a deterministic alignment engine. Our mission is to provide a stable foundation for complex decision-making where human authority and AI agency coexist in a transparent, explainable ecosystem.

## Converge Tool 🛠️

Standalone developer tools for the [Converge](https://converge.zone) ecosystem. High-performance, LLM-powered validation, and generation of Gherkin specifications.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Website](https://img.shields.io/badge/Website-converge.zone-blue)](https://converge.zone)

---

## 🚀 Overview

`converge-tool` is designed to bridge the gap between business requirements and technical implementation. It focuses on the "Truth" behind your specifications—ensuring they are not just syntax-valid, but provide real business value and are realistically automatable.

### ✨ Key Features

- **Multi-Dimensional Validation**: Evaluates specs for convention compliance, business sense, and technical compilability.
- **AI Spec Generation**: Transform free-text requirements into valid `Truth` (Gherkin) files instantly.
- **Truth Syntax Support**: Native support for Converge's `Truth:` keyword, maintaining full Gherkin compatibility.
- **LLM Integration**: Seamlessly connects with Anthropic, OpenAI, and other providers via `converge-core` traits.
- **Scoring & Feedback**: Receive detailed validation reports with confidence scores and actionable suggestions.

---

## 🛠️ Components

### 📐 Gherkin Validation

Validate your feature files against three rigorous dimensions:

1. **Convention Compliance**: Enforces Given/When/Then structure and naming standards.
2. **Compilability**: Analyzes if steps can be automated or if they rely on hidden human inputs/externalities.
3. **Business Sense**: Ensures scenarios are testable, deterministic, and describe meaningful business outcomes.

### ✍️ Spec Generation (New!)

Convert natural language descriptions into professional specifications.

```bash
# Try it out with the included example
ANTHROPIC_API_KEY=your_key cargo run --example generate_spec
```

---

## 💻 Installation

Add this to your `Cargo.toml`:

```toml
[dependencies]
converge-tool = "0.2"
```

---

## ⚡ Quick Start

### Validation Example

```rust
use converge_tool::gherkin::{GherkinValidator, ValidationConfig};
use converge_provider::AnthropicProvider;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Setup LLM Provider
    let provider = Arc::new(AnthropicProvider::from_env("claude-3-5-haiku-20241022")?);

    // 2. Initialize Validator
    let validator = GherkinValidator::new(provider, ValidationConfig::default());

    // 3. Validate Content
    let result = validator.validate(feature_text, "my_feature.truth")?;

    println!("Validation Score: {:.2}", result.confidence);
    Ok(())
}
```

---

## 🗺️ Roadmap & Architecture

See [converge-business/knowledgebase/tool-ARCHITECTURE.md](../converge-business/knowledgebase/tool-ARCHITECTURE.md) for a detailed look at the internal components and workflows.

- **Knowledgebase:** See [converge-business/knowledgebase/](../converge-business/knowledgebase/)
- **Collaboration:** See [COLLABORATION.md](COLLABORATION.md)
- **For LLMs:** See [AGENTS.md](AGENTS.md)

- [x] Standalone Tool Extraction
- [x] AI Spec Generation
- [x] Validation Scoring
- [ ] VS Code Extension Integration
- [ ] Custom Domain Lexicons

---

## 📄 License & Conduct

This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.

We expect all contributors to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md).

---

© 2024-2026 Aprio One AB, Sweden.

## Development Tools

This project is built with the help of modern AI-assisted development tools:

### Agent Tooling (Examples)

This project supports a **tool-agnostic agent workflow**. Claude, Codex, Gemini, Cursor, and similar tools are optional frontends; the shared contract is visible task state, scoped changes, validation, and explicit handoffs.

- **[Claude Code](https://claude.ai/claude-code)** - Example interactive coding agent
- **[Cursor](https://cursor.com)** - Example AI-powered IDE workflow
- **[Antigravity](https://antigravity.dev)** - Example AI pair-programming tool
- **Frontier models (Claude / Gemini / others)** - Use any provider that fits the task and team policy

### Version Control & Task Tracking

- **[Jujutsu (jj)](https://github.com/martinvonz/jj)** - Use jj on top of Git for day-to-day version control (commit/diff/rebase/undo)
- **Task tracking (tool-agnostic)** - Use GitHub Issues, Jira, Linear, or a repo-local `TASKS.md`

```bash
# Quick workflow (agent-friendly)
jj status                 # See changes
jj diff                   # Review changes
jj commit -m "message"    # Commit
jj git push               # Push via git remote
# Update tracker or TASKS.md with status + handoff
```

### Key Rust Crates

| Crate | Purpose |
|-------|---------|
| `tokio` | Async runtime |
| `axum` | HTTP framework |
| `serde` / `serde_json` | Serialization |
| `thiserror` | Error handling |
| `tracing` | Structured logging |
| `rayon` | Parallel computation |
| `proptest` | Property-based testing |
| `burn` | ML/deep learning (converge-llm) |
| `tonic` / `prost` | gRPC support |