Metadata-Version: 2.5
Name: varchy
Version: 0.1.0
Summary: Your idea. Fully architected. Open-source AI software architect & development orchestrator.
Author-email: Varchy Core Team <dev@varchy.org>
License: MIT
License-File: LICENSE
Keywords: ai,cli,developer-tools,mcp,orchestrator,pydantic,software-architecture
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.3
Requires-Dist: keyring>=24.3.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0.0; extra == 'mcp'
Description-Content-Type: text/markdown

# VARCHY 🏛️
### *Your idea. Fully architected.*

<p align="center">
  <a href="https://github.com/varchy-org/varchy"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
  <a href="https://python.org"><img src="https://img.shields.io/badge/python-3.12%20%7C%203.13%20%7C%203.15-blue" alt="Python 3.12+"></a>
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Protocol%20Ready-purple" alt="MCP Ready"></a>
  <a href="#"><img src="https://img.shields.io/badge/Tests-24%2F24%20Passing-brightgreen" alt="Tests"></a>
  <a href="#"><img src="https://img.shields.io/badge/Readiness%20Engine-100%20pt%20Deterministic-emerald" alt="Readiness Engine"></a>
  <a href="#"><img src="https://img.shields.io/badge/BYOK-Zero%20Telemetry-orange" alt="Zero Telemetry"></a>
</p>

<p align="center">
  <strong>Varchy</strong> is the open-source software architect and planning orchestrator for the AI coding era.<br>
  It transforms a <strong>one-sentence idea</strong> into a complete, structured, mathematically validated, and implementation-ready engineering blueprint before a single line of application code is written.
</p>

---

## ⚡ The Problem: The "Vibe Coding" Hangover

AI coding assistants (Claude Code, Cursor, Copilot, Codex) write code in seconds. But without upfront architecture, developers face the same recurring disaster:

```
❌ Vibe Coding Without Architecture:
   Prompt: "Build me an Uber for dog walkers"
     ↳ Agent hallucinates database models on the fly
     ↳ Screen routes conflict with backend API contracts
     ↳ Edge cases and authentication are completely ignored
     ↳ Context window fills up -> Agent forgets earlier decisions
     ↳ Hours wasted debugging spaghetti code
```

```
✅ Vibe Coding With Varchy:
   Command: varchy generate --idea "Uber for dog walkers" --template saas
     ↳ Structured PRD with stable requirement IDs (REQ-001)
     ↳ Screen specs & interaction states (SCREEN-001)
     ↳ Relational schemas & API contracts (ENT-001, API-001)
     ↳ Phased task DAG with zero circular dependencies (TASK-001)
     ↳ 100-Point Deterministic Readiness Gate
     ↳ Exported AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, & Copilot rules
     ↳ Your coding agent implements tasks in perfect sequence!
```

---

## 🚀 30-Second Quickstart

### 1. Installation

```bash
pip install varchy
```

### 2. Browse Architectural Archetypes

```bash
varchy templates
```

```text
       🏛️ Varchy Architectural Templates & Archetypes
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Template ID  ┃ Name                      ┃ Category         ┃ Description                                    ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ saas         │ Multi-Tenant Web SaaS     │ saas             │ Scalable cloud web platform with billing & RBAC│
│ local_first  │ Local-First Encrypted App │ dev_tool         │ Zero-knowledge offline-first encrypted storage │
│ api_backend  │ High-Throughput API       │ api_backend      │ Headless scalable REST & RPC backend service   │
│ dev_tool     │ Developer CLI             │ dev_tool         │ Ergonomic terminal developer tool & state      │
│ mobile_app   │ Offline-Ready Mobile App  │ mobile_app       │ Cross-platform iOS/Android app with sync       │
└──────────────┴───────────────────────────┴──────────────────┴────────────────────────────────────────────────┘
```

### 3. Generate Complete Architecture Blueprint

```bash
# Autonomous generation with archetype
varchy generate --idea "A local-first encrypted collaborative workspace" --template local_first

# Interactive discovery interview
varchy generate --idea "A multi-tenant invoice automation tool" --mode interactive
```

*Runs with automatic stage checkpointing (`.varchy/checkpoints/`). If interrupted, re-running resumes from the last completed stage without burning tokens. Use `--force` to regenerate all stages.*

### 4. Run the 100-Point Deterministic Readiness Gate

```bash
varchy validate
```

```text
       🏛️ Blueprint Readiness Assessment (100-Point Deterministic Score)
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━┳━━━━━━━┳━━━━━━━━┓
┃ Category                    ┃ Max ┃ Score ┃ Status ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━╇━━━━━━━╇━━━━━━━━┩
│ Product Requirements        │  20 │  20.0 │  PASS  │
│ Technical Architecture      │  20 │  20.0 │  PASS  │
│ UI/UX Specifications        │  15 │  15.0 │  PASS  │
│ Development Planning        │  15 │  15.0 │  PASS  │
│ Database & API Contracts    │  10 │  10.0 │  PASS  │
│ Testing Strategy            │  10 │  10.0 │  PASS  │
│ Security & Deployment       │  10 │  10.0 │  PASS  │
└─────────────────────────────┴─────┴───────┴────────┘
Total Readiness Score: 100.0 / 100 — READY FOR IMPLEMENTATION
Critical Blockers: 0 | Warnings: 0 | Recommendations: 0
```

### 5. Step to the Next Actionable Task for Your Agent

```bash
varchy task next
```

```text
╭─ 🏛️ Varchy Task Handoff ────────────────────────────────────────────────────────╮
│ Next Actionable Implementation Task: [TASK-001]                                 │
│ Title: Repository Scaffolding & Configuration                                   │
│ Phase: PHASE-1 | Priority: critical                                             │
│ Description: Initialize package build configuration, virtual environment, and...│
│                                                                                 │
│ Associated Requirements:                                                        │
│   • [REQ-001] Core Domain Workflow Engine                                       │
│                                                                                 │
│ Completion Criteria:                                                            │
│   • Project installs cleanly in virtual environment.                            │
│   • Linting and formatting tools pass with zero warnings.                       │
╰─────────────────────────────────────────────────────────────────────────────────╯
```

---

## 🛠️ Complete CLI Command Reference

| Command | Description | Example |
|---|---|---|
| `varchy init` | Initialize project workspace & metadata | `varchy init --name "MyApp" --template saas` |
| `varchy templates` | List and inspect architectural project archetypes | `varchy templates inspect saas` |
| `varchy analyze` | Analyze idea, risks, and taxonomy before generation | `varchy analyze --idea "..."` |
| `varchy generate` | Execute 10-stage architecture DAG pipeline | `varchy generate --idea "..." --template saas` |
| `varchy task next` | Compute next actionable task in dependency DAG | `varchy task next` |
| `varchy task list` | Display all development tasks grouped by phase | `varchy task list` |
| `varchy update` | Incrementally update specific requirement without re-run | `varchy update --requirement REQ-001 ...` |
| `varchy validate` | Run 100-point deterministic readiness scoring | `varchy validate` |
| `varchy status` | Show current blueprint health, stages, and metrics | `varchy status` |
| `varchy export` | Re-compile documentation & agent instruction files | `varchy export` |
| `varchy doctor` | Diagnose environment, Keychain, and configured providers | `varchy doctor` |
| `varchy config set-key` | Securely store provider key in OS Keychain | `varchy config set-key openai sk-...` |
| `varchy mcp run` | Launch Model Context Protocol server over stdio | `varchy mcp run` |

---

## 🧠 Core Philosophy & Architecture

Varchy is **not** an AI wrapper that blindly outputs huge blobs of unstructured Markdown. It is built on six 100-level engineering invariants:

1. **Structured Data as the Single Source of Truth:**
   The source of truth is strictly typed, serialized Pydantic v2 schemas (`.varchy/blueprints/`). Markdown documentation (`docs/`) is a compiled, read-only projection.
2. **Unified Core Engine:**
   The CLI (`varchy`) and the MCP Server (`varchy mcp run`) share 100% of business logic through a single `VarchyEngine` orchestrator.
3. **Multi-Stage DAG with Checkpoint Resumability:**
   Execution passes through 10 discrete stages (`Discovery` → `Clarification` → `Product` → `UX` → `Architecture` → `Data & APIs` → `Planning` → `QA` → `Validation` → `Compilation`). Checkpoints are persisted atomically after every stage.
4. **Stable Traceability Matrix:**
   Every structural node maintains an immutable, human-readable stable ID:
   `REQ-###` ⟷ `SCREEN-###` ⟷ `API-###` ⟷ `ENT-###` ⟷ `TASK-###` ⟷ `TEST-###`
5. **Deterministic Readiness Scoring:**
   Readiness is calculated via AST and graph traversal algorithms (including cycle detection for tasks), not subjective LLM opinion.
6. **Zero-Leak Bring-Your-Own-Key (BYOK):**
   Keys are securely stored in your hardware-backed OS Keychain (`keyring`) or local environment variables. Secrets never touch disk, logs, or git.

---

## 🔌 Supported AI Providers

| Provider | Integration | Structured Mode | Configuration |
|---|---|---|---|
| **OpenAI** | API (`gpt-4o`, `gpt-4o-mini`, `o3-mini`) | Native JSON Schema (`strict: true`) | `varchy config set-key openai sk-...` |
| **Google Gemini** | API (`gemini-2.5-pro`, `gemini-2.5-flash`) | Native `responseSchema` | `varchy config set-key gemini AIza...` |
| **Ollama** | Local REST (`http://localhost:11434`) | Native JSON Schema Format | Run `ollama serve` (zero key required) |
| **Mock Provider** | Offline Deterministic Blueprint Engine | Built-in | Used in tests or with `--provider mock` |

---

## 🤖 Model Context Protocol (MCP) Integration

Connect Varchy directly to **Cursor**, **Claude Desktop**, or **Claude Code** as a native MCP server:

### Cursor Configuration (`~/.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "varchy": {
      "command": "varchy",
      "args": ["mcp", "run"]
    }
  }
}
```

### Claude Desktop Configuration (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "varchy": {
      "command": "varchy",
      "args": ["mcp", "run"]
    }
  }
}
```

### Available MCP Capabilities:
- **Tools:** `varchy_initialize_project`, `varchy_generate_blueprint`, `varchy_validate_blueprint`, `varchy_get_context`
- **Live Resources:**
  - `varchy://project/overview`
  - `varchy://project/prd`
  - `varchy://project/architecture`
  - `varchy://project/database`
  - `varchy://project/tasks`
  - `varchy://project/validation`
- **Reusable Prompts:**
  - `review_architecture`: Live readiness assessment & critical blocker checks.
  - `prepare_task_implementation`: Context pack for implementing a specific `TASK-###`.

---

## 📁 Generated Project Layout

```text
my-project/
├── .varchy/                       # Machine System of Record (Git-ignored)
│   ├── project.json               # Metadata & configuration
│   ├── checkpoints/               # Atomic stage transaction snapshots
│   └── blueprints/current.json    # Master Pydantic domain models
│
├── docs/                          # Compiled Engineering Specifications (Git-ignored)
│   ├── 01-product/                # PRD, requirements, personas
│   ├── 02-design/                 # Design system, screen specs, IA
│   ├── 03-engineering/            # Architecture, DB schema (with Mermaid ER diagrams), API contracts
│   ├── 04-development/            # Phased roadmap & tasks (with dependencies)
│   └── 05-quality/                # Test strategies, unit/integration test cases
│
├── AGENTS.md                      # Universal Coding Agent Guidelines
├── CLAUDE.md                      # Claude Code instructions
├── GEMINI.md                      # Gemini CLI instructions
├── .cursorrules                   # Cursor IDE Composer / Agent rules
├── .github/copilot-instructions.md # GitHub Copilot guidelines
└── README.md                      # Project architectural summary
```

---

## 🧪 Testing & Verification

Varchy is engineered with a comprehensive automated test harness:

```bash
pytest -v
```

```text
tests/test_cli.py::test_cli_version PASSED                               [  4%]
tests/test_cli.py::test_cli_doctor PASSED                                [  8%]
tests/test_cli.py::test_cli_init_and_generate_workflow PASSED            [ 12%]
tests/test_cli_advanced.py::test_cli_analyze_command PASSED              [ 16%]
tests/test_cli_advanced.py::test_cli_status_uninitialized PASSED         [ 20%]
tests/test_cli_advanced.py::test_cli_status_initialized_and_generated PASSED [ 25%]
tests/test_cli_advanced.py::test_cli_config_set_key PASSED               [ 29%]
tests/test_cli_tasks_and_ide.py::test_cursor_and_copilot_files_generated PASSED [ 33%]
tests/test_cli_tasks_and_ide.py::test_cli_task_list_and_task_next PASSED [ 37%]
tests/test_engine_unified.py::test_engine_init_and_generate PASSED       [ 41%]
tests/test_mcp_extended.py::test_mcp_resources_and_prompts PASSED        [ 45%]
tests/test_pipeline_stages.py::test_all_pipeline_stages_execute_in_sequence PASSED [ 50%]
tests/test_pipeline_stages.py::test_pipeline_orchestrator_checkpointing_and_resumption PASSED [ 54%]
tests/test_schemas.py::test_project_metadata_serialization PASSED        [ 58%]
tests/test_schemas.py::test_requirement_model_validation PASSED          [ 62%]
tests/test_schemas.py::test_mock_blueprint_schema_conformance PASSED     [ 66%]
tests/test_templates_and_updates.py::test_templates_registry_contains_archetypes PASSED [ 70%]
tests/test_templates_and_updates.py::test_cli_templates_list_and_inspect PASSED [ 75%]
tests/test_templates_and_updates.py::test_interactive_discovery_interview_callback PASSED [ 79%]
tests/test_templates_and_updates.py::test_cli_update_requirement_incremental PASSED [ 83%]
tests/test_templates_and_updates.py::test_doc_compiler_generates_mermaid_diagrams PASSED [ 87%]
tests/test_validation_engine.py::test_complete_blueprint_passes_validation PASSED [ 91%]
tests/test_validation_engine.py::test_circular_dependency_triggers_critical_blocker PASSED [ 95%]
tests/test_validation_engine.py::test_unconfirmed_high_risk_assumption_blocks_blueprint PASSED [100%]

============================= 24 passed in 12.22s ==============================
```

---

## 🗺️ Roadmap & Implementation Progress

- [x] **v0.1.0:** Core Pydantic schemas, Deterministic 100-pt validation engine, Typer CLI, Mock provider, Agent instruction generator (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`).
- [x] **v0.2.0:** Multi-Stage DAG Orchestrator with Checkpoint Resumability, UX (`SCREEN-###`), Architecture, Data & API (`ENT-###`, `API-###`), Planning (`TASK-###`), and QA (`TEST-###`) stages.
- [x] **v0.3.0:** Live BYOK AI Providers: OpenAI (`gpt-4o`, `o3-mini`), Google Gemini (`2.5/3 Pro`), and Ollama local inference adapter.
- [x] **v0.4.0:** Interactive discovery interview mode (`varchy generate --mode interactive`) and Mermaid visual architecture & ER diagrams.
- [x] **v0.5.0:** Architectural templates (`varchy templates`), Incremental blueprint updates (`varchy update`), and Task handoff (`varchy task next`, `varchy task list`).
- [x] **v0.6.0:** Complete MCP Resources (`varchy://project/*`) & Prompts API + Cursor (`.cursorrules`) & GitHub Copilot instruction exporters.
- [ ] **v1.0.0:** Varchy Build — Coding agent execution orchestration & drift detection.

---

## 🤝 Contributing

Contributions are warmly welcomed! Please read [CONTRIBUTING.md](CONTRIBUTING.md) to get started.

---

## ⚖️ License

Distributed under the MIT License. See [LICENSE](LICENSE) for more information.
