# Zeus Plan

> Zeus Plan - Spec to Executable Artifacts

- Skill: `huifer/zeus-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add huifer/zeus-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/huifer/zeus-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: huifer (https://skillmd.com/u/huifer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/huifer/zeus-plan

---


# Zeus Plan - Spec to Executable Artifacts

Convert an approved spec into version-scoped stories and tasks with deterministic IDs and dependency waves.

## Preconditions

- Target spec exists and is approved.
- `.zeus/{version}/config.json` exists.
- `.zeus/{version}/prd.json`, `task.json`, and `roadmap.json` are writable.

## Inputs

- `--spec <filename>` (optional, default latest spec)
- `--version vN` (optional, default `main`)

## Deterministic workflow

### 1) Load context and reserve IDs

Read:

- selected spec
- version config
- existing `prd.json`
- existing `task.json`

Reserve next IDs:

- `US-{NNN}` from `prd.json`
- `T-{NNN}` from `task.json`
- `M-{NNN}` from `roadmap.json` milestones

### 2) Create user stories

Extract from acceptance criteria and role/goal language in spec.

Required story shape:

```json
{
  "id": "US-001",
  "title": "One-line story title",
  "description": "As a <role>, I need <capability> so that <outcome>",
  "acceptance_criteria": ["Given/When/Then style criterion"],
  "priority": "high",
  "version_scope": "main",
  "passes": false,
  "created_from_spec": "2026-04-07-auth-design.md",
  "created_at": "2026-04-07T00:00:00.000Z"
}
```

Priority policy:

- high: direct north star impact
- medium: critical support path
- low: optimization or edge behavior

### 3) Create executable tasks

Generate small, independently executable units.

Task types:

- `infra`
- `api`
- `frontend`
- `docs`

Task schema:

```json
{
  "id": "T-001",
  "story_id": "US-001",
  "type": "api",
  "title": "Implement POST /api/auth/login",
  "description": "Include validation, error mapping, and audit logging.",
  "files": ["src/app/api/auth/login/route.ts"],
  "depends_on": [],
  "refactor_of": null,
  "depends_on_existing": [],
  "passes": false,
  "commit_sha": null,
  "ai_log_ref": null,
  "wave": null,
  "created_at": "2026-04-07T00:00:00.000Z"
}
```

Brownfield policy:

- If task modifies existing modules, fill `refactor_of` with a stable module path or identifier.
- If task depends on existing code not represented by Zeus task IDs, list those in `depends_on_existing`.
- Keep both fields optional for backward compatibility.

### 4) Compute wave plan

Build dependency DAG from `depends_on` and assign wave numbers:

- wave 1: no dependencies
- wave N: depends only on lower waves

Reject cyclic dependencies and force correction before write.

### 5) Update roadmap milestone

Add or update milestone with:

- title from spec
- `spec_ref`
- generated story/task ID lists
- `status: planned`

### 6) Persist artifacts

Write updated:

- `.zeus/{version}/prd.json`
- `.zeus/{version}/task.json`
- `.zeus/{version}/roadmap.json`

### 7) Commit planning artifacts

```bash
git add .zeus/{version}/prd.json .zeus/{version}/task.json .zeus/{version}/roadmap.json
git commit -m "docs(zeus): update prd and task from {spec-name}"
```

### 8) Write AI log

Create `.zeus/{version}/ai-logs/{ISO-ts}-plan.md` with the 3-section contract.

### 9) Report summary

Return:

- story count,
- task count,
- wave distribution,
- recommended next step: `/zeus:execute`.

### 10) Offer test generation

After printing the summary, prompt the user:

```
Generate test flows now? [yes/no]
(Platforms: android, chrome, ios — runs /zeus:test-gen automatically)
```

- If **yes**: invoke `/zeus:test-gen --version {version}` immediately.
- If **no**: remind the user they can run `/zeus:test-gen` at any time before executing.

## Quality gates

- no duplicate story/task IDs,
- no empty acceptance criteria,
- no task without a valid story link,
- no wave assignment with unresolved dependency.

## Agent collaboration

Use `zeus-planner` for decomposition quality checks and dependency sanity verification.