Status: 🚫 NOT PRODUCTION READY - Early Stage Research Project

Kairos is an experimental framework exploring AI-driven collaborative development (also known as "vibe coding"). This project investigates how AI can effectively integrate into team-based software development workflows, not just individual developer-AI interactions.

The goal of Kairos is to:

1. Validate AI Integration: Test whether AI-driven development can produce production-grade code through collaborative workflows
2. Build a Production Framework: Create a Go-native, observable, and interoperable agent framework that could serve as a foundation for production systems
3. Democratize AI Development: Move beyond single-developer-with-AI setups to entire teams leveraging AI as part of their development process
4. Establish Best Practices: Define patterns, conventions, and architectural principles for team-based AI development

• A research and experimentation project for AI-assisted development
• A proof-of-concept for team-integrated AI workflows
• An architectural exploration of agent-based systems in Go
• A vibe coding experiment where most development is AI-driven with human oversight

• Production-ready software (APIs are unstable, behavior may change dramatically)
• A finished framework (core components are still being designed and refined)
• Suitable for critical systems (not battle-tested or security-hardened)
• A replacement for traditional development (it's an exploration of new possibilities)

This project operates under a unique development model:

• AI-Driven Development: The majority of code is generated and structured by AI
• Human Oversight: Humans provide direction, validation, and architectural decisions
• Team Integration: Designed to work with entire development teams, not solo developers
• Learning Loop: Each iteration improves both the framework and the AI collaboration process

The ultimate goal is to understand whether this approach can produce enterprise-grade software and to establish patterns that teams can adopt.

kairos/
├── cmd/                 # Command-line tools and entry points
├── pkg/                 # Core framework packages
├── examples/            # Example usage and integrations
├── docs/                # Technical documentation and ADRs
├── docs-site/           # MkDocs site for documentation
├── scripts/             # Build and utility scripts
├── tools/               # Development tooling
└── AGENTS.md            # Guidelines for AI agents working on this project

• Go 1.21+
• Make (optional but recommended)

go build ./...

go test ./...

go run ./examples/01-hello-agent

Production-Grade Components (Phases 1-3 Complete ✅):

• Error Handling: Typed errors, retry logic, circuit breaker
• Resilience Patterns: Health checks, timeouts, fallbacks
• Observability: 5 OTEL metrics, 6 alerts, 3 dashboards
• 62 tests, 100% pass rate | Zero compiler warnings

See Error Handling Guide for details and examples.

• 👨‍💻 Developers: Start with Error Handling Guide → Integration Guide for agents → Examples
• 👨‍💼 Operators: Go to Observability Guide (dashboards, alerts) → Metrics Export Guide (OTLP setup)
• 🏗️ Architects: Read Narrative Guide → ADR 0005

• Error Handling Guide - Production-grade error handling (All Phases ✅)

  • For agents: Integration Guide - How to use error handling in agent loops
  • Quick reference: Status | Roadmap | Index
  • For executives/architects: Narrative Guide

• Observability Guide - Dashboards, alerts, monitoring setup

  • For operators: Metrics Export Guide - OTLP configuration and where metrics go
  • 5 metrics, 6 alert rules, 3 dashboards, PromQL queries included

• Functional Specification - Complete feature specification (Spanish)

• Architecture Guide - System design and components

• API Reference - API documentation

• CLI Guide - Command-line interface

• Architecture Decision Records - Design decisions and rationale

• AGENTS.md - Contributing guidelines for AI-driven development

Kairos implements a reactive agent loop supporting:

• Tool integration (MCP protocol)
• Memory systems for context
• Observable metrics and logging
• Agent discovery and composition

• Agent Loop: ReAct-inspired architecture for agent reasoning
• Tool System: MCP-compatible tool definition and execution
• Memory Management: Persistent and ephemeral context storage
• Observability: Built-in metrics and tracing

See Architecture Documentation for details.

• 🔴 APIs are unstable and may change without warning
• 🔴 Tool ecosystem is minimal
• 🔴 No security hardening (use with caution)
• 🟡 Documentation is incomplete
• 🟡 Performance not optimized
• ✅ Production-grade error handling and observability (see docs and observability guide)

• Stabilize core APIs
• Production-grade error handling and recovery
• Comprehensive tool library
• Security audit and hardening
• Performance benchmarking and optimization
• Integration patterns for team workflows
• Formal validation and testing

This project welcomes contributions and experiments! However, please be aware:

• Architecture First: Before implementing, read AGENTS.md and existing documentation
• Consistency Matters: Follow established patterns in the codebase
• Backward Compatibility: Prefer non-breaking changes when possible
• Documentation: Document architectural decisions in docs/internal/adr/

See AGENTS.md for detailed contribution guidelines.

The core philosophy behind Kairos:

"Building production software through human-AI collaboration at the team level, where AI augments human judgment rather than replacing it."

Key principles:

• Transparency: All AI-generated code is human-reviewable
• Iterative: Short feedback loops between humans and AI
• Collaborative: Team-based decision making, not solo development
• Learning: Each iteration improves both code and process
• Ambitious: Aim for production-grade output despite experimental nature

[Add your license here]

For questions about the project:

• Check existing documentation
• Review Architecture Decision Records
• See AGENTS.md for AI development guidance

This codebase is actively evolving. Major changes may happen between commits:

• ✅ Learn from it
• ✅ Experiment with it
• ✅ Provide feedback
• ❌ Do NOT use in production systems
• ❌ Do NOT rely on API stability

The goal is eventual production readiness, but we're not there yet.

Made with AI-assisted development | Designed for team collaboration