verdict-ai 0.2.0

AI-powered meta-decision system with dual constrained agents

Verdict

AI-powered meta-decision system with dual constrained agents

Verdict helps you escape decision paralysis by making definitive "should I do this?" and "how should I do this?" decisions for you.

What is Verdict?

Verdict is a command-line tool that uses two AI agents to transform your fuzzy ideas into frozen decisions and actionable execution plans:

• Verdict Agent: Makes singular, decisive judgments (PROCEED/REJECT/ALTERNATIVE) - no "you could also..." suggestions
• Execution Agent: Designs minimal implementation plans based on the verdict

Unlike traditional AI assistants that offer endless possibilities, Verdict commits to ONE path and produces persistent artifacts you can execute.

Core Philosophy

• No vibe coding - Every decision traces back to structured reasoning
• Singular verdicts - Agent makes ONE decision, no alternatives
• Frozen decisions - Decisions are immutable (like Git tags)
• Persistent artifacts - Outputs are decision.json + todo.md, not chat logs
• Context-aware - Remembers your goals and past decisions

Quick Start (< 5 minutes)

从 PyPI 安装（推荐）⭐

所有平台统一安装：

# 使用 pipx (推荐)
pipx install verdict-ai

# 或使用 pip
pip install verdict-ai

# 配置 API key
verdict config

# 做第一个决策
verdict decide "I want to build a personal blog"

就这么简单！ 不需要克隆仓库 🎉

从源码安装（开发者）

# 克隆仓库
git clone https://github.com/1psychoQAQ/verdict.git
cd verdict

# 使用 Poetry
poetry install
poetry run verdict config
poetry run verdict decide "your idea"

Installation

推荐方式：从 PyPI 安装

macOS:

brew install pipx
pipx install verdict-ai

Windows:

pip install pipx
pipx install verdict-ai

Linux:

python3 -m pip install --user pipx
pipx install verdict-ai

其他安装方式

方式	命令	适用场景
PyPI (pipx)	pipx install verdict-ai	生产使用（推荐）⭐
PyPI (pip)	pip install verdict-ai	简单测试
源码 (Poetry)	poetry install	开发贡献
源码 (pip)	pip install -e .	本地开发

详细安装说明

查看 INSTALL.md 获取：

• Windows / macOS / Linux 详细步骤
• 常见问题解决方案
• 环境变量配置
• 故障排除指南

Requirements

• Python 3.10 or higher
• API key for at least one of the supported providers:
  • Claude (Anthropic) - Default
  • OpenAI (Platform)
  • Gemini (Google AI Studio)
• Internet connection for API calls

Usage Examples

Example 1: Side Project Decision

$ verdict decide "I want to build a habit tracking app"

╭────────────────── Verdict ──────────────────╮
│ Decision    PROCEED                         │
│ Summary     Build a minimal habit tracker   │
│ Confidence  82%                             │
│ Included    Daily tracking, Simple UI      │
│ Excluded    Social features, Analytics     │
╰─────────────────────────────────────────────╯

╭──────────────── Execution Plan ─────────────╮
│ Phase 1: Core tracking (3 days)            │
│ Phase 2: Basic UI (2 days)                 │
│ Total: 5 days                              │
╰─────────────────────────────────────────────╯

Example 2: Technical Architecture Choice

$ verdict decide "Should I use PostgreSQL or MongoDB for my app?"

╭────────────────── Verdict ──────────────────╮
│ Decision    ALTERNATIVE                     │
│ Summary     Use PostgreSQL with JSONB       │
│ Confidence  90%                             │
│ Reasoning   Get SQL reliability + JSON...  │
╰─────────────────────────────────────────────╯

Example 3: Learning Path Decision

$ verdict decide "Should I learn Rust or Go next?" \
  -c "I'm a Python developer working on backend services"

╭────────────────── Verdict ──────────────────╮
│ Decision    PROCEED                         │
│ Summary     Learn Go for backend work       │
│ Confidence  85%                             │
│ Reasoning   Go is easier to learn coming   │
│             from Python and more common     │
│             in backend services...          │
╰─────────────────────────────────────────────╯

Example 4: Feature Prioritization

$ verdict decide "Should I add dark mode to my app?"

╭────────────────── Verdict ──────────────────╮
│ Decision    REJECT                          │
│ Summary     Focus on core features first    │
│ Confidence  75%                             │
│ Reasoning   Dark mode is nice-to-have...   │
╰─────────────────────────────────────────────╯

Example 5: Career Decision with Context

# First, set your context
$ verdict context add-goal "Find remote work opportunities"
$ verdict context set-constraint location "prefer remote"
$ verdict context set-preference risk_tolerance "low"

# Then make the decision
$ verdict decide "Should I accept this startup job offer?"
# Verdict considers your goals, constraints, and preferences

How It Works

Agent Architecture

┌─────────────────────────────────────────────────┐
│                   User Input                    │
│        "I want to build a blog platform"        │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│              Verdict Agent                      │
│  • Analyzes idea against goals & context       │
│  • Makes singular decision (PROCEED/REJECT)     │
│  • Defines scope (included/excluded)            │
│  • Provides reasoning & confidence              │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
         ┌───────────────────────┐
         │    decision.json      │
         │  (Frozen verdict)     │
         └───────────┬───────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│            Execution Agent                      │
│  • Accepts verdict without questioning          │
│  • Designs minimal viable path                  │
│  • Breaks down into phases & tasks              │
│  • Estimates effort & identifies risks          │
└────────────────────┬────────────────────────────┘
                     │
                     ▼
         ┌───────────────────────┐
         │      todo.md          │
         │  (Action plan)        │
         └───────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────┐
│              Artifact Storage                   │
│         ~/.verdict/                             │
│         ├── decisions/  (decision.json)         │
│         ├── plans/      (todo.md)               │
│         └── state/      (state.json)            │
└─────────────────────────────────────────────────┘

Decision Pipeline

1. Context Loading: Loads your goals, preferences, and past decisions
2. Verdict Phase: AI agent makes a singular decision with reasoning
3. Validation: Ensures output matches JSON schema
4. Execution Phase: AI agent creates implementation plan
5. Validation: Ensures plan is actionable and complete
6. Artifact Generation: Creates JSON and Markdown files
7. Storage: Saves to ~/.verdict/ with timestamps
8. Context Update: Records decision in your history

Retry Logic

• Each phase has 3 retry attempts on failure
• Exponential backoff between retries
• Validation errors trigger automatic retry
• Clear error messages on final failure

Configuration

API Key Setup

Verdict supports multiple LLM providers. Configure the one you want to use:

# Claude (default)
$ verdict config --provider claude
API Key: [hidden]
✓ Configuration saved

# OpenAI
$ verdict config --provider openai
API Key: [hidden]
✓ Configuration saved

# Gemini
$ verdict config --provider gemini
API Key: [hidden]
✓ Configuration saved

# Or set environment variables
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export GOOGLE_API_KEY="AI..."

Configuration File

Location: ~/.verdict/config.yaml

# Configure one or more providers
anthropic_api_key: sk-ant-...
openai_api_key: sk-...
google_api_key: AI...

Selecting a Provider

Use the --provider flag to choose which LLM to use:

# Use Claude (default)
$ verdict decide "Build a blog" --provider claude

# Use OpenAI GPT-4
$ verdict decide "Build a blog" --provider openai

# Use Google Gemini
$ verdict decide "Build a blog" --provider gemini

# Specify a specific model
$ verdict decide "Build a blog" --provider openai --model gpt-4o
$ verdict decide "Build a blog" --provider gemini --model gemini-1.5-pro

Available Models:

• Claude: claude-3-5-sonnet-20241022 (default), claude-3-opus-20240229, claude-3-haiku-20240307
• OpenAI: gpt-4o (default), gpt-4-turbo, gpt-4, gpt-3.5-turbo
• Gemini: gemini-1.5-pro (default), gemini-1.5-flash, gemini-pro

Installing Provider Support:

By default, only Claude is included. To use OpenAI or Gemini:

# Install with all providers
pipx install verdict-ai[all]

# Or install specific providers
pipx install verdict-ai[openai]
pipx install verdict-ai[gemini]

Context Management

Verdict maintains context across sessions to make better decisions:

# View current context
$ verdict context show

# Add goals
$ verdict context add-goal "Ship MVP in 2 weeks"
$ verdict context add-goal "Learn by building"

# Set constraints
$ verdict context set-constraint time_budget "weekends only"
$ verdict context set-constraint skill_level "intermediate"

# Set preferences
$ verdict context set-preference risk_tolerance "low"
$ verdict context set-preference innovation_vs_proven "proven"

# Remove a goal
$ verdict context remove-goal "Old goal"

# Clear all context
$ verdict context clear

Output Files

decision.json

Immutable record of the verdict:

{
  "decision": "proceed",
  "verdict_summary": "Build a minimal CLI tool",
  "reasoning": "This is achievable and valuable...",
  "confidence": 0.85,
  "scope": {
    "included": ["Core CLI", "Basic logic"],
    "excluded": ["Web UI", "Database"],
    "constraints": ["Keep it simple", "CLI only"]
  },
  "timestamp": "2025-12-20T10:00:00Z"
}

todo.md

Actionable execution plan:

# Execution Plan: Build a minimal CLI tool

**Decision:** PROCEED
**Estimated Effort:** 6 hours

---

## Phases

### Phase 1: Setup
**Goal:** Initialize project structure
**Tasks:**
- [ ] Create project with Poetry
- [ ] Setup dependencies
- [ ] Configure CLI framework

**Done Criteria:** Project runs with --help
**Estimated Effort:** 2 hours

state.json

Progress tracking snapshot:

{
  "decision_id": "abc123def456",
  "status": "planned",
  "verdict": {
    "decision": "proceed",
    "summary": "Build a minimal CLI tool"
  },
  "execution": {
    "phases_count": 2,
    "total_estimated_effort": "6 hours"
  }
}

Advanced Features

Decision History

All decisions are stored with timestamps:

# List recent decisions
ls ~/.verdict/decisions/

# View a specific decision
cat ~/.verdict/decisions/20251220-155518-abc123-decision.json

# Find your latest plan
cat $(ls -t ~/.verdict/plans/*.md | head -1)

Combining with Other Tools

# Use with task managers
verdict decide "Feature X" && todoist add "$(cat ~/.verdict/plans/*.md | head -1)"

# Use with Git
verdict decide "Refactor auth" && git checkout -b feature/auth-refactor

# Use with project management
verdict decide "New API" && gh issue create --title "Implement API" --body-file ~/.verdict/plans/*.md

Agent Design Rationale

Why Singular Verdicts?

Traditional AI assistants hedge with multiple options:

"You could use React, or Vue, or Svelte. Each has pros and cons..."

Verdict makes ONE decision:

"Use React. Vue and Svelte are excluded from scope."

Reasoning:

• Decision paralysis comes from too many options
• Analysis without commitment wastes time
• You can always iterate after shipping

Why Two Separate Agents?

Verdict Agent (What to do)

• Must be critical and skeptical
• Can say "don't do this"
• Considers opportunity cost

Execution Agent (How to do it)

• Must be optimistic and constructive
• Cannot question the verdict
• Focuses on minimal path

Reasoning:

• Separation prevents "but you could also..." hedging
• Forces commitment at decision boundary
• Execution agent can't re-litigate the verdict

Why Persistent Artifacts?

Chat logs disappear. Files persist.

Reasoning:

• Decisions should be reviewable months later
• Plans should integrate with Git workflow
• State tracking enables project management tools

Development

Running Tests

# Run all tests
poetry run pytest tests/

# Run with coverage
poetry run pytest tests/ --cov=verdict --cov-report=html

# Run specific test file
poetry run pytest tests/test_integration.py -v

Project Structure

verdict/
├── src/verdict/          # Source code
│   ├── agents.py         # AI agent implementations
│   ├── artifacts.py      # Artifact generation
│   ├── cli.py           # Command-line interface
│   ├── config.py        # Configuration management
│   ├── context.py       # User context management
│   ├── pipeline.py      # Decision pipeline
│   ├── storage.py       # File storage
│   └── validator.py     # JSON schema validation
├── templates/           # Jinja2 templates
│   ├── verdict_agent.j2     # Verdict agent prompt
│   ├── execution_agent.j2   # Execution agent prompt
│   ├── decision.json.j2     # Decision artifact
│   ├── todo.md.j2          # Plan artifact
│   └── state.json.j2       # State artifact
├── schemas/             # JSON schemas
│   ├── verdict.json     # Verdict validation
│   └── execution.json   # Execution plan validation
├── tests/              # Test suite
└── docs/              # Documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Areas for Contribution

• Additional agent prompt templates
• New artifact formats (e.g., GitHub Issues, Linear tasks)
• Integration with project management tools
• Alternative LLM providers
• Improved error handling
• Documentation improvements

Troubleshooting

"Authentication error: invalid x-api-key"

Solution: Verify your API key:

verdict config  # Re-enter your API key
# Or check environment variable
echo $ANTHROPIC_API_KEY

"Pipeline failed after 3 attempts"

Possible causes:

• Network connectivity issues
• API rate limits
• Invalid input format

Solution: Check Anthropic API status and try again.

"Files not saving to ~/.verdict/"

Solution: Check permissions:

ls -la ~/.verdict/
# If directory doesn't exist, Verdict will create it on first run

Roadmap

• MVP: Core decision pipeline
• Context management
• Integration tests
• Rich terminal output
• Documentation
• PyPI package distribution
• Alternative LLM providers (Claude, OpenAI, Gemini)
• GitHub Actions integration
• Decision review/update workflow
• Team collaboration features
• Additional LLM providers (Cohere, Mistral, etc.)

Philosophy

Verdict is inspired by:

• Getting Things Done (GTD): Reduce open loops, make definitive commitments
• Shape Up: Fixed scope, flexible time approach
• Unix Philosophy: Do one thing well, compose with other tools
• Git: Immutable history, branching possibilities

License

MIT License - see LICENSE file for details.

Acknowledgments

• Supports multiple LLM providers:
  • Anthropic Claude (default)
  • OpenAI GPT
  • Google Gemini
• Uses Rich for beautiful terminal output
• Follows CCPM workflow for development

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation: See docs/ directory

---

Made with Claude Code 🤖