Orbit - AI Skill Orchestration Engine

English | 简体中文

 ██████╗ ██████╗ ██████╗ ██╗████████╗
██╔═══██╗██╔══██╗██╔══██╗██║╚══██╔══╝
██║   ██║██████╔╝██████╔╝██║   ██║
██║   ██║██╔══██╗██╔══██╗██║   ██║
╚██████╔╝██║  ██║██████╔╝██║   ██║
 ╚═════╝ ╚═╝  ╚═╝╚═════╝ ╚═╝   ╚═╝

Keep your AI development workflow in orbit

Complete development lifecycle automation through structured 5-phase workflow with script-based reliability.

Status

✅ v0.2.0 CLI - Complete

Core workflow implementation:

• ✅ Project structure
• ✅ Script-based automation
• ✅ State management with hash tracking
• ✅ 5-phase workflow skills
• ✅ Sync detection and recovery
• ✅ Independent skill invocation

Installation

Install Orbit globally:

npm install -g @leokon3/orbit@latest

Then navigate to your project directory and initialize:

cd your-project
orbit init

The initializer asks two questions:

1. Which agent you use:
   • Claude Code
   • Codex
2. Where to install Orbit:
   • Local project
   • Global user

| Agent | Local project | Global user | | --- | --- | --- | | Claude Code | .claude/skills/ | ~/.claude/skills/ | | Codex | .agents/skills/ | ~/.agents/skills/ |

CLI Commands

orbit init       # Install Orbit skills
orbit update     # Update installed Orbit skills
orbit uninstall  # Remove Orbit skills
orbit -version   # Show Orbit version

Manual Installation

If you do not want to install the global CLI, clone this repository and copy the skills to your target directory.

Claude Code

# Local project
mkdir -p .claude/skills
cp -r skills/* .claude/skills/

# Global user
mkdir -p ~/.claude/skills
cp -r skills/* ~/.claude/skills/

Codex

# Local project
mkdir -p .agents/skills
cp -r skills/* .agents/skills/

# Global user
mkdir -p ~/.agents/skills
cp -r skills/* ~/.agents/skills/

After installation, start using Orbit:

/orbit

Quick Start

As Claude Code Skills

# Automatic workflow (recommended)
/orbit

# Or call specific phases directly
/orbit-explore          # Phase 1: Requirements exploration
/orbit-brainstorming    # Phase 2: Technical design
/orbit-planning         # Phase 3.1: Implementation planning
/orbit-build            # Phase 3.2: Code implementation
/orbit-review           # Phase 4: Code review
/orbit-archive          # Phase 5: Archive and documentation
/orbit-sync             # Sync after spec changes

First Time Use

# 1. Start a new change
/orbit

# Claude will ask: "Tell me about what you're trying to build."
# Answer, then follow the conversation through each phase

# 2. Check status anytime
ls -la .orbit/
cat .orbit/state.yaml

# 3. Continue where you left off
/orbit

Five-Phase Workflow

Explore → Brainstorming → Build → Review → Archive
   ↓            ↓           ↓        ↓        ↓
proposal.md  brainstorming  plan.md  review.md  Archive
spec.md         .md         + code              + merge

Phase Details

| Phase | Skill | Creates | Key Activities | | -------------------- | ----------------------------------- | ------------------------------- | ----------------------------------------------------------------------------- | | 1. Explore | /orbit-explore | proposal.mdspec.md | Requirements conversationProblem/solution explorationFunctional specs | | 2. Brainstorming | /orbit-brainstorming | brainstorming.md | Technical designArchitecture diagrams (ASCII)Technology choices | | 3. Build | /orbit-planning/orbit-build | plan.mdCode + Tests | Implementation planningSubagent/inline executionTDD approach | | 4. Review | /orbit-review | review.md | Code quality reviewBug detectionPass/fail verification | | 5. Archive | /orbit-archive | Archive + IndexMerged specs | Move to archiveMerge to main specsClear state |

Core Mechanisms

1. Script-Based Automation

All critical logic is in cross-platform Node.js scripts (not agent promises):

skills/orbit/scripts/
├── orbit-check-state.js      # Detect current phase
├── orbit-phase-guard.js      # Validate transitions
├── orbit-update-hash.js      # Track document changes
├── orbit-sync-detect.js      # Detect stale documents
├── orbit-merge-spec.js       # Intelligent spec merging
└── orbit-archive-change.js   # Finalize archive and reset state

2. Hash-Based Document Tracking

SHA256 hash chain ensures consistency:

documents:
  spec:
    hash: bbb222...
  brainstorming:
    hash: ccc333...
    based_on_spec_hash: bbb222...  ✓ matches
  plan:
    hash: ddd444...
    based_on_brainstorming_hash: ccc333...  ✓ matches

If spec changes during build → automatic sync detection.

3. State Machine

.orbit/state.yaml tracks workflow:

workflow: full
phase: brainstorming
current_change: ops-platform

documents:
  proposal:
    path: .orbit/changes/ops-platform/proposal.md
    hash: aaa111...
  spec:
    path: .orbit/changes/ops-platform/spec.md
    hash: bbb222...
    based_on_proposal_hash: aaa111...

4. Phase Guards

Prevent invalid transitions:

# Can't skip phases
node skills/orbit/scripts/orbit-phase-guard.js archive
# ✗ Missing review.md. Run review phase first.

5. Automatic Sync

Spec changes trigger surgical updates:

# User edits spec.md during build
/orbit
# ⚠️  Spec changed since brainstorming was created
# 🔄 Running sync first...
# [Updates brainstorming.md and plan.md]
# ✓ Sync complete, continuing build...

Skills Structure

skills/
├── orbit/                    # Main dispatcher + shared scripts
│   ├── SKILL.md
│   └── scripts/
│       ├── orbit-check-state.js
│       ├── orbit-phase-guard.js
│       ├── orbit-update-hash.js
│       ├── orbit-sync-detect.js
│       ├── orbit-merge-spec.js
│       └── orbit-archive-change.js
│
├── orbit-explore/           # Phase 1: Requirements
├── orbit-brainstorming/     # Phase 2: Technical design
├── orbit-planning/          # Phase 3.1: Planning
├── orbit-build/             # Phase 3.2: Execution dispatcher
├── orbit-review/            # Phase 4: Code review
├── orbit-archive/           # Phase 5: Archive
├── orbit-sync/              # Sync handler
│
└── Execution skills (called by orbit-build):
    ├── orbit-executing/      # Simple tasks (≤2 tasks)
    ├── orbit-subagent-dev/   # Complex tasks (≥3 tasks)
    ├── orbit-tdd/            # Test-driven development
    ├── orbit-verify/         # Verification checks
    └── orbit-finishing/      # Branch cleanup

Usage Modes

Mode 1: Automatic Flow (Recommended)

/orbit  # Call repeatedly, it continues from current phase

Example session:

Turn 1: /orbit → Explore → Creates proposal.md + spec.md
Turn 2: /orbit → Brainstorming → Creates brainstorming.md
Turn 3: /orbit → Planning → Creates plan.md
Turn 4: /orbit → Build → Implements code
Turn 5: /orbit → Review → Creates review.md
Turn 6: /orbit → Archive → Archives change

Mode 2: Direct Phase Invocation (Advanced)

/orbit-brainstorming  # Jump to brainstorming (useful for quick design)
/orbit-review         # Quick code review
/orbit-sync           # Manual sync after spec edits

Project Directory Structure

myproject/
├── .orbit/
│   ├── state.yaml                      # Current workflow state
│   ├── changes/
│   │   └── my-feature/                 # Active change
│   │       ├── proposal.md
│   │       ├── spec.md
│   │       ├── brainstorming.md
│   │       ├── plan.md
│   │       └── review.md
│   ├── specs/
│   │   └── authentication.md           # Merged main specs
│   ├── archive/
│   │   ├── INDEX.md
│   │   └── 2026-06-18-my-feature/      # Completed changes
│   └── design-sessions/
│       └── brainstorm-2026-06-18.md
│
└── (your project code)

Hash Chain Example

Complete document lineage:

documents:
  proposal:
    hash: aaa111...

  spec:
    hash: bbb222...
    based_on_proposal_hash: aaa111...  ✓

  brainstorming:
    hash: ccc333...
    based_on_spec_hash: bbb222...      ✓

  plan:
    hash: ddd444...
    based_on_brainstorming_hash: ccc333...  ✓

  review:
    hash: eee555...
    based_on_plan_hash: ddd444...      ✓

If spec.md changes:

spec:
  hash: bbb999...  ← Changed!

brainstorming:
  based_on_spec_hash: bbb222...  ✗ MISMATCH

→ orbit-sync-detect.js catches this → Automatically triggers /orbit-sync → Updates brainstorming.md and plan.md → Rebuilds hash chain

Design Principles

1. Script-First - Critical logic in cross-platform Node.js scripts, not agent interpretation
2. Hash-Based Traceability - SHA256 tracks all document relationships
3. Automatic Sync - Spec changes trigger surgical updates, not full rewrites
4. Phase Guards - Prevent invalid workflow states
5. Incremental Specs - Changes merge into main docs, preserving history
6. Independent Skills - Can invoke any phase directly for flexibility

Comparison with Similar Tools

| Dimension | Comet | Orbit | | ------------------ | ------------------------------------- | --------------------------------------- | | Positioning | OpenSpec + Superpowers | Independent 5-phase workflow | | Dependencies | External CLIs (openspec, superpowers) | Self-contained skills + scripts | | Invocation | /comet, /comet-open, etc. | /orbit, /orbit-explore, etc. | | Phase 2 Name | design | brainstorming (exploration focus) | | Automation | State machine + scripts | State machine + scripts + hash tracking | | Build Strategy | Superpowers execution | Subagent-driven or inline | | Extensibility | Monolithic skill | Modular independent skills |

Documentation

• orbit-project-plan.md - Original project plan
• CLAUDE.md - Development guidelines

Credits

Inspired by:

• OpenSpec - Spec lifecycle
• Superpowers - Development methodology