Autonomous Software Engineer OS (ASE-OS)

The portable software-engineering operating layer for AI coding agents.

ASE-OS transforms conventional AI coding assistants (Google Antigravity, Claude Code, OpenAI Codex, OpenCode, Gemini CLI) from reactive, prompt-driven code generators into autonomous, disciplined software engineers.

Instead of writing haphazard code and asking the user for constant guidance, ASE-OS provides the missing engineering operating system: persistent project memory, specialist personas, explainable action prioritization, layered verification, rendered visual inspection, and verifiable release gates.

The Problem: Why Coding Agents Fail

Modern LLMs possess immense tactical coding ability, yet they fail when tasked with building real systems. They suffer from predictable pathologies:

| Failure Mode | How Reactive Agents Fail | How ASE-OS Solves It | | :--- | :--- | :--- | | Fake Completion | Agent writes code, sees zero syntax errors, and claims: "Done!" | Status Tri-State: IMPLEMENTED $\neq$ VERIFIED $\neq$ SHIPPABLE. Evidence is required before marking complete. | | Patch Stacking | When tests fail, agent wraps symptoms in defensive if blocks. | Root-Cause Analysis Protocol: Triggers architecture inspection when localized patches repeat. | | Test Theater | Writes tests with dummy assertions like expect(true).toBe(true). | Requirement Traceability Matrix: Tests must verify explicit domain state transitions linked to REQ-xxx. | | Visual Neglect | If CSS compiles, agent assumes the UI is beautiful. | Visual Quality Loop: Headless browser captures snapshots across desktop (1280px) and mobile (375px) viewports. | | Amnesia & Drift | Agent forgets architectural rules across session resets. | Dual-Representation State (.ase/): Persistent ADRs, tasks, memory, and failure learning survive restarts. |

System Architecture

ASE-OS is engineered across 6 distinct, modular layers:

+-----------------------------------------------------------------------------------+
|                               USER SPECIFICATION                                 |
+-----------------------------------------------------------------------------------+
                                         |
                                         v
+-----------------------------------------------------------------------------------+
| LAYER A: Core Engineering Protocol                                               |
|  - Discovery -> Requirements -> Research -> Architecture -> Roadmap -> Tasks      |
|  - Implementation -> Layered Verification -> Independent Review -> Release Gate   |
+-----------------------------------------------------------------------------------+
          |                                  ^                                  |
          v                                  |                                  v
+-----------------------+      +---------------------------+      +-----------------+
| LAYER C: Personas     |      | LAYER D: Orchestration    |      | LAYER B: State  |
| - Lead Engineer       |      | - Next-Action Engine      |      | - .ase/ Store   |
| - Product Manager     | <--> | - Dynamic Task Graph      | <--> | - Memory & ADRs |
| - Architect           |      | - Explainable Scoring     |      | - Traceability  |
| - 14+ Specialists     |      | - Autonomous Loop         |      | - Failure Learn |
+-----------------------+      +---------------------------+      +-----------------+
                                         |
                                         v
+-----------------------------------------------------------------------------------+
| LAYER E: Universal Tool Contracts & Capability Detection                         |
|  - Filesystem, Shell, Git, Headless Browser, Code Search, Test Runner             |
|  - Automatic Environment Probing & Graceful Degradation Matrix                    |
+-----------------------------------------------------------------------------------+
                                         |
                                         v
+-----------------------------------------------------------------------------------+
| LAYER F: Host Adapters & Model Context Protocol (MCP) Bridge                     |
|  - Antigravity Adapter   - Claude Code Adapter   - OpenAI Codex Adapter           |
|  - OpenCode Adapter      - Gemini CLI Adapter    - Embedded MCP Server (`ase mcp`)|
+-----------------------------------------------------------------------------------+

Quick Start

1. How Developers Get the CLI

ase is already registered in your system (npm link is active), so you can run ase directly in PowerShell or Command Prompt. For distributing to other developers, there are three options:

Option A: Zero-Install via npx (No installation needed)

Any developer can run ASE-OS instantly in any repository without installing anything:

npx autonomous-software-engineer-os init "My New App"
npx autonomous-software-engineer-os install cursor
npx autonomous-software-engineer-os status

Option B: Global Install via npm

Once published to npm (npm publish --access public):

npm install -g autonomous-software-engineer-os

Option C: From Source (Local / Team Development)

git clone https://github.com/gosty-web/autonomous-software-engineer-os.git
cd autonomous-software-engineer-os
npm install
npm run build
npm link

(Now ase is globally accessible in any directory on their computer).

2. Installing for Target Coding Agents (ase install)

In any project repository, developers run ase install <agent> to equip that environment with ASE-OS:

ase install [agent]

| Target Coding Agent | Installation Command | Generated Artifacts & Capabilities | | :--- | :--- | :--- | | Google Antigravity | ase install antigravity | Installs 7 specialized engineering skills (ase-os, ase-architect, ase-qa-engineer, ase-code-reviewer, ase-visual-critic, ase-release-gate, ase-researcher) into .gemini/skills/, .agents/skills/, and ~/.gemini/config/skills/, plus GEMINI.md project rules. | | Cursor / Windsurf | ase install cursor | Creates .cursor/mcp.json (wires Cursor to the embedded ase mcp server over stdio) and .cursorrules (enforces anti-slop rules, testing evidence, and task status). | | Claude Code | ase install claude-code | Creates .claude/commands/ase.md. Typing /ase in Claude Code runs ase status and ase next automatically. | | OpenAI Codex | ase install codex | Creates .codex/rules.md injecting anti-slop rules, verification gates, and state tracking into Codex prompts. | | OpenCode | ase install opencode | Creates .opencode/config.json registering status, next, test, and ship as native OpenCode tools. | | Gemini CLI | ase install gemini-cli | Creates .gemini-cli/ase_hook.sh enforcing state validation before and after tasks. | | All Agents at Once | ase install all | Generates configs and skill manifests for all supported environments in one go. |

3. Initialize a Repository

In any new or existing project repository:

ase init "My Awesome Project"

This generates the persistent .ase/ state directory:

.ase/
├── config.yaml          # Project & autonomy configuration
├── state.json           # Fast transactional index for CLI & DAG
├── PROJECT.md           # High-level vision, constraints, and current phase
├── REQUIREMENTS.md      # Formal requirement specs with traceability matrix
├── ARCHITECTURE.md      # System topology, data flow, component boundaries
├── ROADMAP.md           # Engineering milestones
├── TASKS.md             # Dynamic task graph with dependency links
├── DECISIONS.md         # Architecture Decision Records (ADR) index
├── TEST_PLAN.md         # Multi-level verification criteria
├── QUALITY.md           # Quality gate metrics and threshold compliance
├── RISKS.md             # Identified risks and mitigations
├── DEVLOG.md            # Structured chronological engineering event log
├── decisions/           # Immutable ADR markdown documents
├── memory/              # Evolving playbook and failure post-mortems
└── quality/             # Visual audit snapshots and critique reports

3. Check System Health & Capabilities

ase doctor

Output:

🩺 Running ASE-OS Environment Doctor...
Host Environment: Google Antigravity
Shell Available:  YES
Git Available:    YES
Browser Engine:   YES (Puppeteer/Playwright headless available)
Persistent State: YES (.ase/ writable)

All core capabilities healthy.

4. Inspect Project Status & Dashboard

ase status

── ASE-OS DASHBOARD ───────────────────────────────────────
Project: AGENT VILLAGE v0.1.0
Phase:   BUILD        Mode:  AUTO
Progress: ████████████░░░░░░░░ 60% (6/10 verified)
Quality:  8.8 / 10.0  | Requirement Coverage: 90%

── NEXT HIGHEST-VALUE ACTION ──────────────────────────────
Task:     TASK-007 - Implement runtime state persistence
Owner:    backend-engineer (Score: 54.5)
Rationale: Selected TASK-007 because it unlocks 2 downstream tasks, verifies key unfulfilled requirements, and reduces architectural risk.

── ACTIVE TASKS READY TO RUN (2) ──────────────────────────
 • [TASK-007] Implement runtime state persistence (BUILD | backend-engineer)
 • [TASK-008] Design village viewport canvas (BUILD | frontend-engineer)
────────────────────────────────────────────────────────────

5. Execute Next Engineering Step

ase run

6. Run Full Autonomous Engineering Loop

ase auto 20

14 Built-In Specialist Personas

ASE-OS defines 14 declarative YAML personas located in src/personas/manifests/. Each persona defines a formal mission, allowed tools, forbidden actions, quality criteria, and handoff rules:

| Persona | Role | Primary Responsibility | | :--- | :--- | :--- | | Lead Engineer | Lead Systems Architect | Technical leadership, task decomposition, subagent supervision, conflict resolution. | | Product Manager | Technical PM | User requirements deconstruction (REQ-xxx), acceptance criteria, scope control. | | Architect | Principal Architect | System topology, component boundaries, and Architecture Decision Records (ADRs). | | Researcher | Staff Researcher | External library evaluation, competitor benchmarking, and risk discovery. | | Frontend Engineer | Senior Frontend | Responsive UI, client state, accessibility, and desktop/mobile viewport styling. | | Backend Engineer | Senior Backend | Transactional data persistence, APIs, background jobs, and error boundaries. | | UX Engineer | Interaction Designer | User journeys, feedback states (idle, loading, error), and ergonomic consistency. | | Visual Critic | Aesthetic Inspector | Inspects actual rendered browser snapshots for contrast, layout balance, and mobile clipping. | | QA Engineer | Lead QA | Test plan authoring (Unit, Integration, E2E) and requirement-to-evidence mapping. | | Security Engineer | AppSec Specialist | Secret detection, dependency CVE auditing, input sanitization, and least privilege. | | Performance Engineer| Reliability Engineer | Latency profiling, memory leak detection, bundle size auditing, and sub-second startup. | | Code Reviewer | Senior Reviewer | Independent diff inspection, code smell detection, and anti-slop enforcement. | | Documentation Eng | Technical Writer | Up-to-date README, developer setup guides, API specs, and accurate changelogs. | | Release Engineer | Gatekeeper | Quality threshold auditing, release decision (NOT_READY, BLOCKED, READY_FOR_RELEASE). |

Mathematical Next-Action Scoring

Instead of executing tasks in arbitrary file order, the Next-Action Engine evaluates all unblocked tasks dynamically:

$$\text{Score}(t) = w_I \cdot I(t) + w_U \cdot U(t) + w_D \cdot D(t) + w_R \cdot R(t) + w_C \cdot C(t) - w_X \cdot X(t)$$

• $I(t)$ [Impact]: Criticality to the core value proposition (0–10).
• $U(t)$ [Urgency]: Blocking active team workflows (0–10).
• $D(t)$ [Downstream Value]: Count of dependent tasks unblocked upon completion.
• $R(t)$ [Risk Reduction]: Technical unknowns or security risks eliminated (0–10).
• $C(t)$ [Coverage]: Unverified requirements satisfied by this task.
• $X(t)$ [Complexity]: Blast radius and regression risk (0–10).

All weights are configurable in .ase/config.yaml.

Layered Verification & Visual Inspection

ASE-OS enforces a 7-level verification hierarchy:

• Level 1: Static Validation (tsc --noEmit, ESLint)
• Level 2: Unit Tests (Domain state transitions)
• Level 3: Integration Tests (API boundaries, DB transactions)
• Level 4: End-to-End Tests (Full user journey)
• Level 5: Runtime & Visual Inspection (Headless browser snapshots at 1280px and 375px)
• Level 6: Regression Testing (Full suite verification against previous baselines)
• Level 7: Requirement Traceability (Automated proof that all REQ-xxx have passing evidence)

Host Adapters & Embedded MCP Server

ASE-OS can be installed into any AI coding environment:

Google Antigravity

Registers skill in .gemini/skills/ase-os/SKILL.md and provides custom slash-command integration.

node bin/ase.js doctor

Claude Code

Installs custom slash command in .claude/commands/ase.md:

/ase

Model Context Protocol (MCP) Server

Launch the embedded MCP server over stdio to expose ASE-OS tools directly to Claude Desktop, Cursor, or any MCP client:

ase mcp

Add to claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "ase-os": {
      "command": "npx",
      "args": ["-y", "autonomous-software-engineer-os", "mcp"]
    }
  }
}

Exposes tools:

• ase_status: Project state, completion ratio, next action.
• ase_next_action: Ranked engineering priority with scoring breakdown.
• ase_task_update: Update task state with verification evidence.
• ase_record_decision: Register Architecture Decision Records.
• ase_run_gate: Evaluate quality thresholds and return release status.

5 Production Example Projects

Explore runnable examples demonstrating ASE-OS workflows in examples/:

1. examples/01-saas-mvp/: Multi-tenant SaaS with tenant isolation, auth token validation, and usage metering.
2. examples/02-legacy-refactor/: Refactoring a tightly coupled legacy monolith with global state into clean dependency-injected architecture.
3. examples/03-cloud-to-local-first/: Converting cloud-dependent note system into local-first append-only journal with Last-Write-Wins (LWW) conflict resolution.
4. examples/04-ui-visual-polish/: UI-heavy design system card with automated visual audit for mobile viewports (375px) and WCAG AA contrast.
5. examples/05-feature-addition/: Autonomous feature addition (tag filtering & search) to an existing production codebase with zero regressions.

Command Reference

ase init [name]       # Initialize .ase/ directory and project state
ase install [agent]   # Install adapter for coding agent (antigravity, claude, cursor, etc.)
ase status            # Display high-level dashboard and metrics
ase next              # Compute and explain highest-value next action
ase plan              # Synchronize roadmap and task graph
ase run               # Execute the next unblocked engineering task
ase auto [iters]      # Run autonomous loop (default: 10 iterations)
ase test              # Execute layered verification test suite
ase review            # Perform independent code and visual review
ase critique          # Run senior engineer self-critique protocol
ase doctor            # Inspect host environment capabilities & health
ase agents            # List available specialist engineering personas
ase decisions         # List registered Architecture Decision Records
ase decisions create  # Record a new Architecture Decision Record
ase logs              # Display recent engineering devlog entries
ase ship              # Evaluate release gate and produce ship verdict
ase mcp               # Start embedded Model Context Protocol (MCP) server

License

ASE-OS is licensed under the Apache License, Version 2.0.