https://github.com/huifer/zeus
Structured, version-aware AI delivery framework for long-running projects. Deterministic planning (Spec/PRD/Task/Roadmap) + wave-based atomic execution + Git-hook enforcement + zero-manual multi-platform testing (Android/iOS/Chrome) + closed-loop evolution from real production feedback.
https://github.com/huifer/zeus
ai-agents claude-code llm skills
Last synced: about 24 hours ago
JSON representation
Structured, version-aware AI delivery framework for long-running projects. Deterministic planning (Spec/PRD/Task/Roadmap) + wave-based atomic execution + Git-hook enforcement + zero-manual multi-platform testing (Android/iOS/Chrome) + closed-loop evolution from real production feedback.
- Host: GitHub
- URL: https://github.com/huifer/zeus
- Owner: huifer
- License: mit
- Created: 2026-04-07T13:24:57.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-07T15:27:22.000Z (3 months ago)
- Last Synced: 2026-04-07T15:32:47.539Z (3 months ago)
- Topics: ai-agents, claude-code, llm, skills
- Language: Shell
- Homepage:
- Size: 621 KB
- Stars: 12
- Watchers: 0
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Zeus - AI Project Evolution Operating System
[](README.zh-CN.md)
[](#workflow)
[](#)
[](#license)
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](README.md) | [简体中文](README.zh-CN.md)
## Quick Start
```bash
# 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 ` | 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
```text
.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 --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/`:
```markdown
## Decision Rationale
Why this approach was selected.
## Execution Summary
What changed and where.
## Target Impact
Expected impact on the north star metric.
```
## Commit Convention
```text
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](https://linux.do/) — 开源社区支持
## Contact / 交流群
## License
MIT License — see [LICENSE](LICENSE).