Zeus - AI Project Evolution Operating System

Structured, version-aware AI delivery framework for long-running projects.

Zeus combines:

• deterministic planning artifacts (spec, prd, task, roadmap),
• wave-based execution with atomic commits,
• mandatory attribution loop from production feedback to roadmap evolution.

Language: English | 简体中文

Quick Start

# 1) Install the commit message hook (one-time)
cp .zeus/hooks/commit-msg .git/hooks/commit-msg

# 2) Initialize the Zeus project workspace
/zeus:init

# Optional for brownfield repositories: map the existing codebase first
/zeus:discover --depth auto

# 3) Build the first design spec
/zeus:brainstorm --full

# 4) Convert approved spec to executable artifacts
/zeus:plan

# 5) Run pending tasks in dependency waves
/zeus:execute

Workflow

English workflow diagram:

Chinese workflow diagram:

Skill Commands

| Command | Purpose | Main Output | |---|---|---| | /zeus:init | Initialize Zeus workspace and north star metrics | .zeus/main/config.json, evolution.md | | /zeus:discover [--version v2] [--depth quick\|auto\|full] | Map existing codebase and generate brownfield context artifacts | codebase-map.json, existing-modules.json, tech-inventory.md, architecture.md | | /zeus:brainstorm --full | Full-scope design dialogue and spec authoring | .zeus/main/specs/*.md | | /zeus:brainstorm --feature <name> | Single-feature design loop | feature spec | | /zeus:plan [--version v2] | Convert spec to user stories and tasks | prd.json, task.json, roadmap.json | | /zeus:execute [--version v2] | Execute pending tasks wave by wave | atomic commits, task pass states | | /zeus:test-gen [--version v2] [--platforms android,chrome,ios] | AI-generate platform test flows from task/prd artifacts | {version}/tests/*.test.json | | /zeus:feedback | Capture feedback and run attribution | feedback/*.json, evolution entry | | /zeus:evolve | Create a new version branch/folder model | .zeus/vN/* | | /zeus:status | Render global status report and next action | health snapshot + recommendation |

Repository Layout

.zeus/
  main/
    config.json
    prd.json
    task.json
    roadmap.json
    evolution.md
    feedback/
    ai-logs/
    specs/
    tests/
      android.test.json   ← AI-generated, do not edit manually
      chrome.test.json
      ios.test.json
  v2/ ... vN/
  schemas/
    config.schema.json
    codebase-map.schema.json
    existing-modules.schema.json
    prd.schema.json
    task.schema.json
    roadmap.schema.json
    spec.schema.json
    feedback.schema.json
    ai-log.schema.json
    test-flow.schema.json
  scripts/
    zeus-runner.sh
    generate-tests.sh
    collect-metrics.sh

## Brownfield Adoption

For existing repositories, run this path:

```bash
# 1) Build codebase context artifacts
/zeus:discover --version main --depth auto

# 2) Initialize config using discovered context
/zeus:init --import-existing --version main

# 3) Design and plan a scoped feature against existing modules
/zeus:brainstorm --feature <name> --version main
/zeus:plan --version main

# 4) Execute with wave gates
/zeus:execute --version main

This keeps Zeus backward-compatible for greenfield projects while adding safe brownfield onboarding. hooks/ commit-msg

.claude/ skills/zeus-/SKILL.md agents/.md

assets/ zeus-workflow.en.svg zeus-workflow.zh-CN.svg

## Agent Model

Zeus uses phase-specific agents under `.claude/agents`:

- `zeus-researcher`: context discovery and dependency checks
- `zeus-planner`: spec decomposition and artifact shaping
- `zeus-executor`: wave execution orchestration with quality gates
- `zeus-analyst`: attribution confidence and evolution decisions
- `zeus-docs`: bilingual consistency and docs quality checks
- `zeus-tester`: AI test case authoring for android / chrome / ios platforms

Skills should delegate intentionally:
- brainstorming -> researcher
- plan -> planner
- execute -> executor
- test generation -> tester (via `generate-tests.sh`)
- feedback/evolve -> analyst
- docs quality checks -> docs

## Testing

Zeus uses AI-generated test flows. **Do not write test cases manually.**

```bash
# Generate test flows for all platforms (after zeus:plan)
bash .zeus/scripts/generate-tests.sh --version main --platforms android,chrome,ios

# Or via skill
/zeus:test-gen

# Target a single platform
/zeus:test-gen --platforms chrome

# Regenerate (overwrite existing)
bash .zeus/scripts/generate-tests.sh --version main --force

Generated files live at .zeus/{version}/tests/{platform}.test.json and conform to .zeus/schemas/test-flow.schema.json.

Test execution uses the native platform toolchain directly:

| Platform | Toolchain | |---|---| | Android | adb shell | | Chrome | chrome-cli / Chrome DevTools Protocol | | iOS | xcrun simctl / libimobiledevice |

Test flows are regenerated automatically when /zeus:test-gen is invoked, and optionally after each execution wave completes.

AI Log Contract

Each skill execution must append one markdown log in ai-logs/:

## Decision Rationale
Why this approach was selected.

## Execution Summary
What changed and where.

## Target Impact
Expected impact on the north star metric.

Commit Convention

feat(T-003): implement user registration form
fix(T-007): correct session token expiry
docs(zeus): update prd from auth-design spec
chore(zeus): initialize v2 evolution

Troubleshooting

• If /zeus:* commands are not discovered, restart your AI runtime session.
• If execution stalls, verify .zeus/scripts/zeus-runner.sh is executable.
• If task updates fail, check JSON validity in .zeus/*/task.json.
• If commit hook fails, re-copy .zeus/hooks/commit-msg into .git/hooks/.

Contributing

1. Keep prompt specs deterministic and artifact-driven.
2. Keep shell snippets in English only.
3. Preserve backward compatibility for core .zeus schema files.
4. Add docs updates for any workflow changes.

Acknowledgements / 友链

• LINUX DO — 开源社区支持

Contact / 交流群

<p align="center"> <img src="assets/image.png" alt="交流群" width="300" /> </p>

License

MIT License — see LICENSE.