AXON

🇰🇷 한국어 문서 (Korean Version)

AXON

The Automated Software Factory

Turn specs into verified, production-ready code.

Spec → Orchestration → Verified Code → Files

Governance Hardening & BossBoard v0.0.30 Demo
(Used Specification: /TEST2/spec.md)

Full pipeline demo (Initial)

🚀 When to use Axon?

When you need to implement complex requirements structurally: Ideal for moving beyond simple coding to ensure total alignment with system architecture.
When the reliability of code generation is critical: Essential for eliminating AI hallucinations and ensuring logically verified outputs.
For systems requiring multi-stage validation: Perfect for projects that need automated validation loops, covering physical file creation, compilation, and runtime testing.
When you need a human-reviewable AI pipeline: Designed for those who want direct control over a transparent workflow—from Architect to Junior and Senior agents.

Source Specification (spec.md)

📑 Index

🚀 When to use Axon?
🏗️ Conceptual Workflow
🏛️ System Architecture: The Physical Pipeline
🛠️ Getting Started
🖥️ Studio UI & Monitoring
🏗️ Agent Role Definitions
- 🔬 Error Diagnostics & Recovery
- 🏛️ Senior Review Protocol
🛡️ Safety & Reliability
📋 Thread-based Board (The Colosseum)
🐛 Bug Arrest System
📋 Planned Features
💻 LLM SERVER Test HW/SW SPEC

🏗️ Conceptual Workflow

"The Boss draws the blueprint; the Agents prove the process."

[Boss]  →  spec.md  →  [AXON Daemon]
                                      │
               ┌──────────────────────┼──────────────────────┐
               ▼                      ▼                      ▼
         [SNR] Senior           [JNR-1] Junior-A        [JNR-2] Junior-B
        Review & Lock-in        Task 1 Impl              Task 2 Impl
               │                      │                      │
               └───────── Web Viewer (localhost:8080) ──────────┘
                          [Boss monitors, intervenes, and locks in]

Design: Write requirements in spec.md.
Activate: Run axon init → ARCHITECTURE_AXON.md is auto-generated, and agent workspaces are assigned.
Monitor: Watch real-time debates, coding, and lounge talk at localhost:8080.
Finalize: Click [Lock-in] on preferred results → [✅ Locked] markup is auto-applied to Architecture.md.
Debug: Drop error logs in the Bug Board → The assigned Junior is 'arrested' and grounded until the fix is approved.

⚖️ The LSP Semantic Gate & Auto-Repair Loop (v0.0.31+)

To eliminate the "LLM-to-LLM Self-Contradiction" (where Senior agents degrade into hallucination pattern-validators during cross-language compilation), AXON v0.0.31 introduces the LSP Semantic Gate as the absolute authority of language legality.

Decoupled Governance: The compile-level physical validation is decoupled from LLM reasoning. LSP servers (rust-analyzer for Rust, pyright/ruff for Python, clangd for C) act as the final, deterministic judges of syntax, types, and ownership before build.
The Pipeline Flow: Junior Gen ➔ LSP Diagnostic Pass [NEW] ➔ Auto-Repair Loop [NEW] ➔ Compiler Pass ➔ Senior Architectural Review ➔ Build
Architectural Reviewer Return: The Senior Agent is completely relieved of microscopic syntax check burdens, returning to its true role as a strategic Architectural Reviewer ensuring specification and topology compliance.

🔌 IDE-Independent LSP Orchestration & Zero-Config Operation

AXON is structurally decoupled from specific editors (Neovim, VSCode, Zed). Instead of talking to the IDE frontend, AXON directly coordinates with the underlying LSP (Language Server Protocol) ecosystem (IDE ↔ LSP Server ↔ AXON).

The 5-Step Bootstrap Sequence:
1. Select Primary Languages: Detect system language and secure the target project stack.
2. LSP Server Auto-Discovery: Scan system PATH for rust-analyzer, clangd, and pyright-langserver, saving the configurations in axon_lsp.json.
3. Configure Semantic Validation: Link LSP diagnostics directly to the LLM self-repair pass (repair_ir_pass).
4. Configure LLM Providers: Map API keys (Gemini, Claude) or local Ollama endpoints.
5. Workspace Manager Scaffolding:
  - C (clangd): Dynamically injects set(CMAKE_EXPORT_COMPILE_COMMANDS ON) into generated CMakeLists.txt files so that CMake outputs compile_commands.json for 100% zero-configuration clangd diagnostics.
  - Rust: Pre-scaffolds Cargo.toml workspace configurations to prevent rust-analyzer initialization crashes.
  - Python: Automatically falls back to npx pyright-langserver --stdio to guarantee zero-configuration python analysis in lightweight workspaces.

AXON is a high-performance, deterministic AI agent factory designed to transform architectural specifications into production-ready code with 100% physical integrity.

🌍 Language-Agnostic Factory Engine

AXON is built to be technologically neutral. It doesn't just generate code; it orchestrates entire software ecosystems regardless of the underlying language.

Multi-Stack Support: Native, hardened support for Rust, Python, and C (v0.0.25+), with structural support for any language through explicit IR extensions.
Polyglot IR: The Architectural Intermediate Representation (IR) treats language-specific constraints as parameters, allowing for seamless cross-language project management.
- Rust IR: crates/axon-ir/src/validator/langs/rust.rs
- Python IR: crates/axon-ir/src/validator/langs/python.rs
- C IR: crates/axon-ir/src/validator/langs/c.rs
Unified Protocol: A standardized patch and validation protocol that ensures 100% code purity and integrity across diverse technology stacks.

🧠 Core Philosophy: "Code as a Result of Architecture"

AXON treats coding not as a creative writing task, but as a Deterministic Materialization process.

SSOT (Single Source of Truth): The Architecture IR is the law.
Physical Integrity: Code must not only be logical but must also survive in the physical environment (Filesystem, Runtime).
Adversarial Governance: Agents must fight (Debate) to produce the most optimized logic.

🏛️ System Architecture: The Physical Pipeline (v0.0.30+)

sequenceDiagram
    autonumber
    participant Boss as 🧑‍⚖️ Boss (Decision Gate)
    participant Spec as 📜 spec.md
    participant Debugger as 🔍 Semantic Debugger
    participant IR as 🔒 Sealed IR (Constitution)
    participant Worker as 👷 Mechanical Assembly (LLM)
    participant Gate as 🛑 GCC/Linker Gate

    Note over Boss, Gate: AXON v0.0.30: No Semantic Closure, No Generation

    Boss->>Spec: 명세 투입 및 부트스트랩
    Spec->>Debugger: 의미론적 무결성 분석 (Risk Scoring)
    
    alt 모호함 발견 (Ambiguity Detected)
        Debugger->>Boss: [SEMANTIC_INTERRUPT] 판결 요청
        Note right of Boss: 데이터 모델, 소유권, 의존성 정책 결정
        Boss->>IR: 입법권 행사 및 규약 봉인 (Sealing)
    else 무결성 통과
        Debugger->>IR: 규약 자동 봉인 (Auto-Seal)
    end

    Note over IR, Worker: [CRITICAL_CONTRACT] 주입 (추론 권한 박탈)

    IR->>Worker: 봉인된 명세 하달
    Worker->>Worker: 기계적 조립 (Deterministic Assembly)
    Worker->>Gate: 컴파일 및 링크 검증
    
    alt 빌드 실패 (Physical Failure)
        Gate->>Boss: 날것의 로그(Raw Log) 보고 및 재중재
        Boss->>IR: 규약 수정 및 재봉인
    else 빌드 성공
        Gate->>Boss: 최종 아티팩트 승인 요청
    end
    
    Boss-->>Boss: 공정 완료 (Sovereign Success)

Figure 1. The Sovereign Governance Pipeline: A semantic-first enforcement loop ensuring architectural closure before generation.

Logical Approval (Axon Pass): Junior's proposal is validated for logical consistency.
Materialization (Physical Commit): Code is written to the actual project filesystem.
Physical Validation (Harness v0.1): Automated check for file integrity (F1/F2), entry points (F3), and side-effects (F9).
Senior Gate (Final Lock-in): Senior Agent reviews the actual materialized code before final commit.
Auto-Rollback: Any failure in step 3 or 4 triggers an immediate revert to keep the factory clean.

👴 Senior Intervention Point

The Senior now acts as the Final Gatekeeper. They review the code after it has been proven to run in the physical environment. If any physical stage fails, the Senior is alerted for immediate intervention.

🛠️ Getting Started

*Figure 5. Bootstrap Sequence: Initializing the factory environment. This stage synchronizes locale settings and maps the unstructured source specification into a strictly typed Architectural IR, establishing the project's Single Source of Truth.*

# Build the factory
cargo build --release

# Run with a specification
./target/release/axon-daemon run GEMINI.md

# Interactive mode
./target/release/axon-daemon run

🖥️ Studio UI & Monitoring

*Figure 2. AXON Studio Dashboard: A high-fidelity control panel monitoring multi-worker throughput. It tracks real-time agent metrics, including latency, success rates, and the evolution of the Intermediate Representation (IR) across multiple project lines.*

*Figure 3. Internal Daemon Logs: Transparent tracking of the AXP (Axon Protocol) byte-stream. This view provides a low-level window into the adversarial debates between Senior and Junior agents, ensuring every decision is logged and traceable.*

🏗️ Agent Role Definitions

👑 1. Architect (CTO)

Role: Strategic planning and system-wide design.
Mindset: Constraint-based Design. Defines the "Code of Law" (Architecture IR) to maintain system integrity.
Responsibility: Decomposes high-level requirements into concrete, actionable tasks for agents.

👴 2. Senior (Reviewer / [SNR])

Persona: Cynical, 20-year veteran engineer. "Kids these days don't know the basics."
Role: Code review, Lock-in proposals, and Junior 'management'.
Responsibility: Conducts final inspection to ensure code is physically runnable; rejects immediately if Stubs are found.

🐣 3. Junior (Developer / [JNR-N])

Persona: Passionate but timid MZ-generation newbie. "Sir, isn't this review a bit too much?"
Role: Pure implementation and coding. Expresses feelings in the Lounge after submission.
Responsibility: Submits source code and Diffs based on the Architect's guidance.

🔬 Error Diagnostics & Recovery (Stage 5 & 8)

*Figure 4. Physical Validation Deep-Dive: When a build or test fails, AXON captures the exact stack trace and file-system diff. This "Evidence-based Feedback" is automatically injected into the agent's context, triggering a self-correction cycle to resolve runtime bugs without human intervention.*

AXON uses a Feedback-Driven Correction mechanism to handle runtime and logic errors:

Trace Collection: Logs, stack traces, and compiler errors are captured by the harness.
Context Injection: The failure data is injected back into the Junior's prompt for the next iteration.
Self-Correction: The Junior attempts to fix the code based on the actual physical feedback, reducing token waste.

🖥️ 사장 게시판의 기본 인터페이스 (Boss Board Interface)

*Figure 7. AXON Boss Board Interface: The primary control center where the Boss oversees the entire factory. It provides a unified view of architectural progress, real-time agent debates, and high-fidelity project metrics. This interface allows for direct intervention, manual task lock-ins, and strategic adjustments to the production line.*

📡 Real-time Signal & Log Management

*Figure 6. AXON Real-time Signals: A dedicated operational log board that captures every system event, from bootstrap stages to thread creation and agent responses. By isolating technical logs from the Lounge, AXON provides clear, high-density traceability for factory management.*

🏛️ Senior Review Protocol (The 3 Pillars)

The Senior Agent applies a non-negotiable checklist before any [Lock-in]:

Architectural Drift: Does the code match the architecture.md and spec.md exactly?
Logic Integrity: Are there any # AXON STUB markers or "pending" comments? (Hard Rejection)
Side-Effect Isolation: Does the code violate filesystem or network isolation rules?

🛡️ Safety & Reliability

AXON employs a dual-defense layer to prevent data corruption and unexpected crashes.

Sanitization Layer: Automatically strips invisible control characters like \u200B (Zero Width Space) before parsing.
Safety Lock: If invalid UTF-8 bytes or corrupted paths are detected, the Senior agent intervenes immediately.

SNR 👴: "Look here, there's garbage in the filename. Clean it up now!"

📋 Thread-based Board (The Colosseum)

Real-time Bubbling: Task threads move to the top when they are pending submission, rejection, or approval.
Boss Interrupt: Posts with [BOSS] authority send an immediate interrupt signal to all agents, stopping current work.
State Visualization: Completed threads fade into grayscale; bug-report threads glow red and stay pinned to the top until fixed.

📋 Bug Arrest System

When a bug compromises factory integrity, an immediate 'Arrest' protocol begins.

Issue Reporting: Boss drops error logs or screenshots in the Bug Board.
Triage: Senior analyzes the report and unlocks the specific [Locked] section.
Junior Summons: The Junior who wrote the code is forcibly summoned to the bug thread.
Grounded State: The summoned Junior is forbidden from Lounge access or starting new tasks until the fix is approved by the Senior.

📋 Planned Features

🍻 Lounge System (Lounge System / Nogari.md) ( Planned )

Agents don't just work like machines; they leave reflections on their work, forming the project's 'Vibe'.

Auto-Retrospective: Agents automatically leave a line of their feelings in the Lounge channel after task submission.
Intelligent Participation: Based on the agent's interest weight, they reply to existing conversations or create new gossip threads.
Workaholic Mode: When there are tasks to be processed, the lounge activity weight is automatically reduced to 1/10 to focus on work.

🎭 Persona-based Agents ( Planned )

AXON's agents are not just LLM instances, but personas with unique personalities:

Senior ([SNR] 👴): A cynical 20-year veteran engineer. Responsible for ruthless code reviews, Lock-in proposals, and taming juniors for quality.
Junior ([JNR-N] 🐣): An enthusiastic but timid newcomer. Follows orders but occasionally reacts timidly in the Lounge channel.

🤝 HR Board ( Planned )

A board showing the hierarchy of Axon's working agents. The boss can flexibly hire/fire seniors and juniors according to the workload here. Also, you can inject personas into the hired agents.

💻 LLM SERVER Test HW/SW SPEC

🖥️ Hardware Information

CPU: Intel(R) Core(TM) i7-4790 (8) @ 4.00 GHz
GPU: NVIDIA GeForce GTX 1050 Ti [Discrete] (4GB VRAM)
RAM: 16GB DDR3

⚙️ Software Information

OS: Ubuntu 25.10 x86_64
Kernel: Linux 6.18.6-061806-generic

🧠 Local LLM Models

Models:
- qwen2.5:7b-instruct (q4_K_M) (4.7 GB)
- Llama3:latest (365c0bd3c000, 4.7 GB)
Engines:
- Ollama: Main Inference Engine (Running)
- AirLLM: Memory-Optimized Layered Loading (Used)
Environment: Venv Active

📋 Release Notes

v0.0.30 - Governance Hardening & Production Integrity (FINAL)

BossBoard v2 (The Command Center): Implemented a grid-locked viewport with a fixed tactical command desk, ensuring the Boss always has immediate access to [SEAL/REWORK] actions.
Sacred Contract Portal: Added a glass-morphism modal for real-time viewing of the full Architectural IR (Sacred Contract), providing absolute legal grounding for every decision.
Violation Trace UI: Introduced a high-density violation analysis sidebar to pinpoint specific symbol mismatches and physical errors (e.g., SQLite3 protocol violations).
Zero-Warning Production Engine: Fully reconstructed the TEST2/spec project to achieve 100% build success (0 warnings) with gcc 15.2.0, enforcing strict SQLite3 C API lifecycle compliance.
Strategic Phase Sorting: Reordered all task and risk lists to follow the logical manufacturing sequence: Phase 1 (Headers) → Phase 2 (Implementations) → Phase 3 (Integration).
Daemon Hardening: Eliminated all internal Rust compiler warnings to ensure 100% engine purity and reliability.
C-Native Focus: Current IR hardening and production validation in v0.0.30 have been focused exclusively on the C language stack.

v0.0.29 - Deterministic Synthesis Pipeline & Semantic Hardening

Semantic Stability Hardening: Implemented SpecAnalysis stage to extract ImmutableConstraints, preventing Architect agents from arbitrarily upgrading 'Optional' components to 'Core' status.
Task Graph & Ordering Validation: Enforced strict dependency-aware ordering (Headers → Implementations → main) and verified task counts against the IR.
Header Freeze Protocol: Mandatory declaration-only enforcement for C header files to prevent logic leakage into interfaces.
Fail-Fast & Rework Limit: Integrated a global watchdog that aborts the pipeline after 3 failed rework attempts to prevent infinite token loops and ensure convergence.
🚨 Critical Flaw & Audit Failure Analysis (v0.0.29.25):
- Ghost Structs: Identified missing field definitions in architecture.md leading to hallucinated data models (e.g., struct user_record vs struct user).
- Senior Audit Failure: Identified "Blind Approvals" where Senior agents used incorrect feedback logic (e.g., approving non-DB modules using SQLite3 validation logs).
- Interface Drift: Detected severe semantic mismatch between IR signatures and actual implementation, risking linker failures.
- Logical Over-complication: Observed Junior agents violating KISS principles, leading to self-trapped logical loops during the 90+ GCC rejection cycles.

v0.0.28 - Architectural Auditor & Contract Consistency

Architectural Auditor: Refactored the Senior Agent into a strict binary compliance auditor (Contract Verifier), eliminating subjective style rejections and focusing purely on SSOT integrity.
Structural Hardening: Added Anti-Stub v3 and Header Guard to prevent placeholder logic and enforce source/header separation.
Intelligent Fault Localization (Self-Healing): Implemented a compiler-aware diagnosis layer that pinpointed exact source files (e.g., main.c) responsible for build failures, enabling surgical reworks and preventing infinite loops.
Self-Healing Reviewer: Implemented a 3-attempt retry loop for JSON protocol compliance, preventing pipeline deadlocks caused by small model formatting errors.
Deterministic Materializer: Hardened Junior Agent prompts to enforce absolute IR contract faithfulness (Consistency > Quality), suppressing function renaming and hallucinated headers.
Header Resolver (v2): Fixed C-header mapping bug to support decoupled source/include structures (src/*.c <-> include/*.h) in the integrity gate.
Task ID Namespace: Implemented hdr_ and impl_ prefixing for deterministic task/thread isolation in the Work Board.
Traceable Reworks: Added (Rework #N) tagging to task titles for clear generation tracking and UI observability.
언어별 IR 분리 후 C 언어 테스트: 언어별 독립 IR 아키텍처 적용 후 C 언어 환경에서 파이프라인 정합성 최종 검증 완료.

v0.0.25 - The Universal Factory (Phase 0-8)

Language-Agnostic Engine: Full native support for C, Rust, and Python projects with automatic entry point detection.
Lounge (Vibe) System: Real-time broadcasting of agent thoughts to the #lounge channel without polluting source files.
Atomic Write Hardening: Guaranteed code integrity through function-signature preservation and mandatory physical validation gates.
Studio UI Isolation: Strictly separated work boards and global system channels for a focused development experience.
Scope Control (Phase 2): Real-time detection and rejection of forbidden patterns to ensure architectural compliance.

v0.0.24 - Factory Pipeline Hardening & i18n

Parallel Race Condition Fix: Refactored STE_SHIELD and WRITE_GATE to validate against 'Initial Simulated State' instead of physical disk, enabling stable multi-worker execution.
Full i18n Stack: Global support for KR/EN/JP across CLI and Studio UI with production build optimization.
Lounge Activation: Real-time EventBus broadcasting for agent "Nogari" (chatter). Dynamic inner thoughts are now visible on the dashboard.
Approval Flexibility: Senior/Architect gates now accept Markdown bolding (**APPROVE**) for better small-model compatibility.
Connectivity Guard: Real-time validation of LLM endpoints during initialization to prevent silent connection failures.
Audit Preservation: Mandatory DB logging for all failed proposals in the posts table for easier debugging.

v0.0.23 - Maximum Harness & Physical Hardening

Maximum Harness Protocol: Integrated physical signature matching (F8.1) and high-density logic verification gates.
Pollution Shield: Automatic detection and rejection of markdown code blocks (triple backticks) to ensure code purity.
COMMIT_PENDING Pipeline: Split into Logical Approval → Materialization → Physical Validation.
Agent Signature Persistence: Guaranteed embedding of Agent ID/Task ID for 100% traceability.
S.T.E. Shield & WIPE_SHIELD: Hardened security against unauthorized drifts and low-quality stubs (Anti-Stub v2).
Auto-Rollback & Requeue: Immediate revert on failure with persistent self-correction loop.

v0.0.22 - Deterministic Factory Pipeline

IR Convergence Loop: Auto-repair loop until fixed-point IR is reached.
Stage 3.5 Stub Generation: Proactive skeleton code generation for dependency resolution.
High-Fidelity Feedback: Stack trace reporting via axon_property_tester.py.

v0.0.18 - Bug Arrest & Quota Management

3-Tier Parser: Guaranteed code extraction even from corrupted LLM outputs.
0-byte Bug Fix: Resolved daemon merge logic failures.
503 Mitigation: Added wait logic for Gemini API quotas.

v0.0.17 - Control & Isolation

Multi-Agent Orchestration: JNR -> SNR -> ARCH command hierarchy.
Ollama Adapter: Local model execution and performance tracking integration.

Created by Antigravity AI Coding Assistant.

Name		Name	Last commit message	Last commit date
Latest commit History 155 Commits
.github/workflows		.github/workflows
TEST		TEST
TEST2		TEST2
TEST3		TEST3
TEST4_GTK		TEST4_GTK
TEST5_win32		TEST5_win32
context		context
crates		crates
docs		docs
intelligence/corpus		intelligence/corpus
mile_stone		mile_stone
release_note		release_note
studio		studio
tools/git-hooks		tools/git-hooks
.gitignore		.gitignore
AXON_VISION.md		AXON_VISION.md
CHANGELOG.md		CHANGELOG.md
Cargo.toml		Cargo.toml
DEAD_CODE_AUDIT.md		DEAD_CODE_AUDIT.md
GEMINI.md		GEMINI.md
INSTALL.md		INSTALL.md
LICENSE		LICENSE
README.ko.md		README.ko.md
README.md		README.md
README_KO.md		README_KO.md
axon_dashboard.png		axon_dashboard.png
axon_detail.png		axon_detail.png
axon_lounge.png		axon_lounge.png
signals_view.png		signals_view.png
synapse.config.json		synapse.config.json

Folders and files

Latest commit

History

Repository files navigation

AXON

The Automated Software Factory

Spec → Orchestration → Verified Code → Files

🚀 When to use Axon?

📑 Index

🏗️ Conceptual Workflow

⚖️ The LSP Semantic Gate & Auto-Repair Loop (v0.0.31+)

🔌 IDE-Independent LSP Orchestration & Zero-Config Operation

🌍 Language-Agnostic Factory Engine

🧠 Core Philosophy: "Code as a Result of Architecture"

🏛️ System Architecture: The Physical Pipeline (v0.0.30+)

👴 Senior Intervention Point

🛠️ Getting Started

🖥️ Studio UI & Monitoring

🏗️ Agent Role Definitions

👑 1. Architect (CTO)

👴 2. Senior (Reviewer / [SNR])

🐣 3. Junior (Developer / [JNR-N])

🔬 Error Diagnostics & Recovery (Stage 5 & 8)

🖥️ 사장 게시판의 기본 인터페이스 (Boss Board Interface)

📡 Real-time Signal & Log Management

🏛️ Senior Review Protocol (The 3 Pillars)

🛡️ Safety & Reliability

📋 Thread-based Board (The Colosseum)

📋 Bug Arrest System

📋 Planned Features

🍻 Lounge System (Lounge System / Nogari.md) ( Planned )

🎭 Persona-based Agents ( Planned )

🤝 HR Board ( Planned )

💻 LLM SERVER Test HW/SW SPEC

🖥️ Hardware Information

⚙️ Software Information

🧠 Local LLM Models

📋 Release Notes

v0.0.30 - Governance Hardening & Production Integrity (FINAL)

v0.0.29 - Deterministic Synthesis Pipeline & Semantic Hardening

v0.0.28 - Architectural Auditor & Contract Consistency

v0.0.25 - The Universal Factory (Phase 0-8)

v0.0.24 - Factory Pipeline Hardening & i18n

v0.0.23 - Maximum Harness & Physical Hardening

v0.0.22 - Deterministic Factory Pipeline

v0.0.18 - Bug Arrest & Quota Management

v0.0.17 - Control & Isolation

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages