Skip to content

Latest commit

 

History

History
175 lines (142 loc) · 6.63 KB

VISION.md

File metadata and controls

175 lines (142 loc) · 6.63 KB

Agent-Driven Development Vision

The goal: 1000 imperfect agents working in parallel, safely producing high-quality software.

The Problem

Today's AI coding agents are "entropy generators":

  • They drift from specifications over time
  • They introduce subtle bugs without understanding context
  • They conflict with each other when working in parallel
  • They lack the guardrails needed for production use

Result: Agents work great for demos, fail at scale.

The Solution: Production Control Layer

Agent-Ready provides the production control layer that makes AI-written software safe:

┌─────────────────────────────────────────────────────────────────┐
│                    AGENT-DRIVEN DEVELOPMENT                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
│  │  SPEC    │ -> │  TASKS   │ -> │  AGENTS  │ -> │  VERIFY  │  │
│  │  .md     │    │  Queue   │    │  Execute │    │  Gates   │  │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘  │
│       │               │               │               │         │
│       v               v               v               v         │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │              FROZEN CONTRACTS (types, schemas)            │  │
│  └──────────────────────────────────────────────────────────┘  │
│       │               │               │               │         │
│       v               v               v               v         │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │                    CI GATEKEEPING                         │  │
│  │              (tests, lint, security, coverage)            │  │
│  └──────────────────────────────────────────────────────────┘  │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

The 5 Maturity Levels (Redefined)

L1: Agent-Readable

  • Agents can understand the codebase
  • CLAUDE.md / AGENTS.md explains structure
  • Basic documentation exists

L2: Agent-Configurable

  • Agents have tool configurations
  • .claude/settings.json, .cursorrules, etc.
  • Permission boundaries defined

L3: Agent-Executable

  • Agents can run tasks
  • MCP servers for extended capabilities
  • Slash commands for common operations
  • Hooks for workflow integration

L4: Agent-Coordinated

  • Multiple agents can work together
  • Task ownership and boundaries
  • Context injection for shared knowledge
  • Conflict detection mechanisms

L5: Agent-Autonomous

  • Agents can self-improve
  • Feedback loops from CI/reviews
  • Learning from past mistakes
  • Autonomous workflow execution

Key Mechanisms

1. Specification-First

SPEC.md → TASKS.md → Agent Work → Verification

Agents work FROM specifications, not just context.

2. Frozen Contracts

// These types are FROZEN - agents cannot modify
export interface ScanResult {
  level: number;
  score: number;
  // ...
}

Contract tests verify agents don't break interfaces.

3. Task Discovery

# TASKS.md or GitHub Issues
- [ ] Implement user authentication (owner: agent-auth)
- [ ] Add rate limiting (owner: agent-api)
- [ ] Write integration tests (owner: agent-test)

Agents claim tasks, avoiding conflicts.

4. Verification Gates

# CI blocks merge unless ALL pass:
- Type checking
- Unit tests
- Contract tests
- Security scan
- Coverage threshold

No agent change reaches main without verification.

5. Agent Boundaries

// .claude/settings.json
{
  "permissions": {
    "allowedPaths": ["src/**/*"],
    "deniedPaths": ["src/core/types.ts"],  // Frozen
    "allowedCommands": ["npm test", "npm run build"]
  }
}

Agents can only modify what they're allowed to.

Metrics That Matter

Metric What It Measures Target
Contract Coverage % of interfaces with contract tests > 90%
Spec Alignment Code traces back to SPEC.md 100%
Agent Boundary Coverage % of code with ownership defined > 80%
CI Gate Strictness All PRs must pass all checks 100%
Verification Freshness How recent is last full verification < 24h

The "1000 Idiots" Test

A codebase is truly agent-ready when:

1000 imperfect AI agents can work on it in parallel without destroying it.

This requires:

  1. Clear specifications (what to build)
  2. Frozen contracts (what not to break)
  3. Strict CI gates (catch all mistakes)
  4. Agent boundaries (who owns what)
  5. Verification loops (continuous checking)

Roadmap

Phase 1: Foundation (Current)

  • Basic checks for file existence
  • Project type detection
  • Spec-kit integration (SPEC.md, contracts)

Phase 2: Agent Control Surface

  • Agent boundary definitions (.claude/boundaries.json)
  • Task discovery checks (TASKS.md, issues integration)
  • Ownership mapping (CODEOWNERS for agents)

Phase 3: Multi-Agent Coordination

  • Agent workflow definitions
  • Conflict detection mechanisms
  • Shared context protocols

Phase 4: Autonomous Operations

  • Self-improvement feedback loops
  • Automatic task generation from specs
  • Agent performance metrics

Agent-Ready is the missing production control layer for AI-written software.

Without it: chaos. With it: scalable, safe, autonomous development.