Kairos: A Cognitive Engineering System for Specification-First AI Development

Kairos is a cognitive engineering system that addresses a fundamental gap in the AI-powered software development ecosystem: the absence of a structured intent layer between human vision and machine execution.

Current AI coding tools operate downstream of user intent. They execute code, fix bugs, and generate features, but they lack a true understanding of why the software exists. Without structured specifications, these tools produce technically functional but conceptually misaligned systems. The result: rework, scope creep, and products that miss the mark.

Kairos solves this by capturing, structuring, and owning user intent through a specification-first approach. It conducts dynamic, persona-aware interviews to extract business requirements, generates detailed technical specifications, and produces adapter-ready outputs for downstream code generation tools like Claude Code, Lovable, or Kiro.

The core thesis: Engineering begins with intent, not code. AI tools require structured thinking to generate reliable systems. Kairos provides that thinking layer.

Key Innovations

• Dynamic Question Generation: Adaptive interview flows that respond to user answers in real-time
• Persona-Aware Adaptation: Questions calibrated to technical proficiency, with auto-answering for non-technical users
• Real-Time Ontology Building: Continuous entity extraction and relationship mapping as users describe their systems
• Universal Specification IR: A platform-agnostic intermediate representation that drives any downstream tool
• Modular Adapter Architecture: Extensible system for generating tool-specific outputs

1.1 The Rise of AI Coding Tools

The AI-assisted software development landscape has exploded. Tools like Cursor, Claude Code, Lovable, Replit, and GitHub Copilot have transformed how developers write code. These systems can generate entire applications from prompts, fix complex bugs, and refactor codebases with minimal human intervention.

However, a critical observation emerges from studying how these tools are used: they are execution engines, not thinking engines.

1.2 The Central Limitation

Consider the typical workflow with an AI coding assistant:

1. User provides a vague prompt: "Build me an e-commerce site"
2. AI generates code based on assumptions about what "e-commerce" means
3. User realizes the generated code doesn't match their vision
4. Cycle of clarification and regeneration begins
5. Eventually, the codebase becomes a patchwork of fixes

The root cause is clear: these tools lack structured intent. They operate on natural language prompts that are inherently ambiguous.

1.3 The Cost of Ambiguity

Problem	Impact
Scope Creep	Features evolve uncontrollably as AI makes assumptions
Rework Cycles	40-60% of AI-generated code requires revision
Technical Debt	Inconsistent architecture emerges from piecemeal generation
Misaligned Products	Working software that doesn't solve the actual problem
Communication Gaps	Non-technical stakeholders can't verify AI understanding

1.4 The Gap in the Market

No existing system captures, structures, or owns user intent in a way that can reliably drive AI code generation. The market has:

• Form builders (Typeform, JotForm): Static question flows, no intelligence
• Requirements tools (Jira, Linear): Issue tracking, not specification generation
• No-code platforms (Bubble, Retool): Implementation-focused, not intent-focused
• AI assistants (ChatGPT, Claude): Conversational, but no persistent spec structure

Kairos fills this gap by providing a persistent specification layer that sits above all downstream tools.

2.1 High-Level Architecture

                                ┌─────────────────────────────────┐
                                │         KAIROS SYSTEM           │
                                └─────────────────────────────────┘
                                                │
    ┌───────────────────────────────────────────┼───────────────────────────────────────────┐
    │                                           │                                           │
    ▼                                           ▼                                           ▼
┌───────────────────┐                   ┌───────────────────┐                   ┌───────────────────┐
│   INPUT LAYER     │                   │  PROCESSING CORE  │                   │   OUTPUT LAYER    │
│                   │                   │                   │                   │                   │
│ - Voice           │                   │ - Q&A Engine      │                   │ - Spec IR         │
│ - Text            │                   │ - Ontology System │                   │ - Adapters        │
│ - UI Events       │                   │ - Persona Matcher │                   │ - Tool Outputs    │
│ - Existing Code*  │                   │ - Completion Mgr  │                   │ - Documentation   │
└───────────────────┘                   └───────────────────┘                   └───────────────────┘

2.2 The Brain & Hands Paradigm

Kairos operates on a simple but powerful principle:

Kairos = the brain. It thinks, understands, and structures.
Code generation tools = the hands. They execute, implement, and build.

This separation provides several advantages:

• The brain can be upgraded independently of the hands
• Different hands can be attached for different tasks
• The brain maintains persistent knowledge across tool changes
• Quality control happens at the specification level, not the code level

2.3 Workflow Overview

1. User initiates a project with a high-level description
2. Persona detection identifies the user's technical proficiency
3. Dynamic Q&A engine asks contextually relevant questions
4. Real-time ontology builds a knowledge graph of entities and relationships
5. Completeness detection determines when enough information is gathered
6. Specification generation produces a structured IR
7. Adapters transform the IR into tool-specific outputs
8. Downstream tools execute against the specification

3.1 Question Flow Orchestrator

The QuestionFlowOrchestrator is the central coordinator for all specification gathering. It manages:

• Question ordering and priority
• Dynamic question injection based on user responses
• Pool activation when specific domains are detected
• Completion state evaluation

3.2 Dynamic Question Generation

The system employs four mechanisms for generating contextually relevant questions:

Mechanism 1: Gap-Filling (Ontology-Driven)

When the ontology detects missing critical information, questions are automatically injected:

User describes e-commerce → No user entity mentioned →
System injects: "Who will be using this platform? Tell me about your users."

Mechanism 2: Follow-Up Generation (AI-Powered)

Complex or ambiguous answers trigger AI-generated follow-ups using GPT-4o-mini for cost-effective generation with confidence scoring.

Mechanism 3: Pool Activation (Keyword-Triggered)

Specific technologies or domains activate specialized question sets. 22 pools are currently defined, covering authentication, payments, storage, AI/ML, analytics, and more.

Mechanism 4: Intelligent Completion Detection

const isComplete =
  meetsQuestionThreshold &&      // >= 12 questions answered
  meetsOntologyThreshold &&      // >= 70% completeness
  meetsCriticalThreshold &&      // >= 80% critical entities
  hasCoreEntities                // Has Project & User defined

3.3 Persona-Aware Adaptation

The system profiles users on a technical sophistication spectrum and adapts accordingly:

• Technical User: Full technical question text, detailed options with tradeoffs, no auto-answering
• Non-Technical User: Simplified language, contextual examples, auto-answers technical decisions using AI + best practices

3.4 Ontology System

The ontology layer extracts and tracks entities, attributes, and relationships in real-time:

Answer: "We sell handmade pottery to collectors worldwide"

Extracted Entities:
├── Business
│   ├── type: "ecommerce"
│   ├── products: ["handmade pottery"]
│   └── targetMarket: "collectors"
├── Website
│   ├── purpose: "sales"
│   └── ecommerceRequired: true
└── Users
    ├── type: "collectors"
    └── characteristics: ["specialized interest", "global reach"]

3.5 Specification Intermediate Representation (Spec IR)

The Spec IR is the universal output format that captures all gathered information. Design principles:

• Platform-agnostic: No tool-specific details
• Complete: Contains all information needed for implementation
• Reversible: Can reconstruct spec from generated code (V3)
• Versionable: Supports schema evolution
• Validatable: Zod schemas ensure correctness

3.6 Adapter Architecture

Adapters transform the universal Spec IR into platform-specific outputs. Current adapter targets:

• Claude Code (autonomous coding agent)
• Kiro (AWS-backed spec-driven development)
• Bubble (no-code platform)
• Retool (internal tools)
• Custom code generation

4.1 Real-time State Sync Under Changing Contexts

Problem: As users answer questions, the UI must reflect ontology changes, completion progress, and new dynamic questions simultaneously.

Solution: Server-Sent Events (SSE) with typed event payloads and batch emission for related updates.

// Event types
'AI.Thinking'              // Show loading state
'Question.Present'         // New question ready
'Ontology.Update'          // Entity/relationship changes
'Progress.Update'          // Completion percentage
'DynamicQuestion.Injected' // New question added mid-flow
'Flow.Complete'            // Gathering finished

4.2 Balancing Persona Simplification with Specification Quality

Problem: Non-technical users need simpler questions, but over-simplification leads to incomplete specifications.

Solution: Three-tier question handling with provenance tracking:

• Tier 1: Show simplified question with persona-adapted language
• Tier 2: Auto-answer with confirmation (user can override)
• Tier 3: Auto-answer silently for purely technical decisions

4.3 Determining Specification Completeness

Problem: How do you know when you've asked enough questions?

Solution: Multi-criteria scoring that balances completeness with pragmatism:

interface CompletionCriteria {
  minQuestionsAnswered: 12        // Floor for any project
  minOntologyCompleteness: 70     // Percentage of expected entities
  minCriticalEntitiesComplete: 80 // Core entities must be detailed
  requireCoreEntities: ['Project', 'User']
}

4.4 Ontology Extraction Accuracy

Problem: Natural language answers contain implicit entities and relationships that must be explicitly extracted.

Solution: Hybrid extraction pipeline combining keyword detection, pattern matching, LLM extraction, and validation/deduplication.

Version 1: Specification Engine (Completed)

Status: Production-ready

Capabilities: Dynamic persona-aware interviews, domain-specific question flows, real-time ontology building, structured specification generation, adapter outputs for Claude Code and Kiro.

Metric	Value
Question completion rate	78%
Ontology extraction accuracy	85%
Spec generation time	< 30 seconds

Version 2: Spec IR Hardening (Current Focus)

Enhancing the IR for long-term maintainability: structured entrypoints, flow-level steps, acceptance tests, stable IDs, and reversible spec elements.

Version 3: Codebase Ingestion Engine (Future Flagship)

Parse existing codebases and reconstruct Kairos specifications. This enables refactors with preserved intent, modernization with understanding, migrations to new stacks, and documentation generation from code.

Market Opportunity: Enterprise brownfield modernization is a multi-billion dollar market.

Version 10: The Engineering Brain (Long-term Vision)

Kairos becomes the authoritative source of system intent. The spec is the source of truth, codebases are implementations, changes begin at the spec layer, and AI QA agents validate correctness.

Greenfield Application Design

Persona: Non-technical founder building first product

1. Founder describes idea in plain English
2. Kairos asks clarifying questions in non-technical language
3. Technical decisions are auto-answered with sensible defaults
4. Specification is generated with full implementation details
5. Claude Code receives spec and generates working application

Outcome: Founder has working MVP in days, not weeks.

Team Alignment

Persona: PM, designer, and engineers need shared understanding

1. PM runs Kairos session with stakeholders
2. Each person's input is captured and reconciled
3. Conflicts are surfaced (designer wants X, engineer says Y)
4. Final spec represents agreed-upon scope
5. Engineers receive implementation-ready specification

Outcome: Alignment achieved before code is written.

Codebase Modernization (V3)

Persona: Enterprise architect with legacy system

1. Existing codebase is ingested by Kairos
2. Specification is reconstructed from code analysis
3. Architect reviews and approves extracted intent
4. Modifications are made at the spec level
5. New implementation is generated in modern stack

Outcome: Legacy system modernized with preserved business logic.

Not Competitors - Complements

Kairos does not compete with AI coding tools. It powers them.

Tool	What It Does	How Kairos Helps
Lovable	Generates full-stack apps	Receives structured specs instead of vague prompts
Cursor	AI-powered code editing	Operates against Kairos-generated codebase
Claude Code	Autonomous coding agent	Executes against detailed specification
Replit	Full-stack dev environment	Benefits from pre-defined project structure

Kairos' Differentiator

Kairos sits before execution. It resolves ambiguity before code is written.

Traditional Flow:
  Vague Prompt → AI Coding Tool → Code → Clarification → More Code → ...

Kairos Flow:
  Structured Interview → Complete Spec → AI Coding Tool → Code → Done

Current Metrics

Metric	Target	Achieved
Question completion rate	80%+	78%
Ontology extraction accuracy	85%+	85%
Spec generation time	< 60s	28s
Auto-answer acceptance rate	90%+	92%
Dynamic question relevance	75%+	81%

Qualitative Results

User Feedback:

• "It asked questions I didn't know I needed to answer"
• "The spec was more detailed than my PRD"
• "Claude Code just... worked, no clarifications needed"

Developer Feedback:

• "The spec had edge cases I would have missed"
• "Entity relationships were already defined"
• "I could start implementing immediately"

Kairos represents a fundamental shift in how AI-assisted software development should work. By capturing and structuring user intent before code generation, it transforms the relationship between humans and AI coding tools.

The current implementation (V1) demonstrates the viability of specification-first development for greenfield projects. The roadmap to V3 extends this capability to brownfield modernization, addressing the massive enterprise market for legacy system evolution.

As AI coding tools become more powerful, the bottleneck will increasingly be the quality of their inputs. Kairos is positioned to be the essential layer that ensures those inputs are complete, consistent, and correct.