| name | zig-workflows |
| description | ZeroLight-Framework (Zig 0.16, SDL3, SDL_GPU) specialist routing: design, implement, debug, PR/diff review, and multi-phase review passes. Use when the user asks for zig-design-specialist, zig-specialist, zig-debug-specialist, or zig-review-specialist; when zig build, zig test, or shader compile fails; when reviewing a PR or branch diff; when planning ECS, DataSystem, SimulationPipeline, pathfinding, collision, AI, or threading changes; or when assessing emergent-gameplay architecture readiness. Slash: /zig-workflows. |
Zig Workflows (Grok-native)
Canonical guardrails: root AGENTS.md / Agents.md and docs/coding-standards.md.
Agents: .grok/agents/zig-*.md (Grok-native source of truth).
Presets: references/module-presets.md.
Multi-phase skills: /pathfinder-review, /architecture-assessment,
/zig-best-practices-review, /zig-deep-correctness-review.
Do not restate full guardrails in spawn_subagent prompts — agents load agents_md.
Inline vs delegate
Work inline (no subagent) when ALL are true:
- One or two files, localized change
- No architecture, pipeline-order, or DataSystem contract change
- User did not ask for a specialist or review pass
- Examples: typo, comment, single test fix, rename, fmt-only
Delegate when ANY are true:
| Signal | Workflow |
|---|
| Non-trivial feature or slice | Design → Implement |
| User names a specialist | Matching workflow below |
zig build / test / shader / runtime failure | Debug |
| PR, diff, or standards review | Review |
| Module-wide pathfinder pass | /pathfinder-review skill |
| ECS extensibility / roadmap assessment | /architecture-assessment skill |
| Large-subsystem best-practice pass | /zig-best-practices-review skill |
| Deep correctness / concurrency / algorithm pass | /zig-deep-correctness-review skill |
| Touches hot paths, threading, or pipeline stages | Implement (or Design first if unclear) |
When unsure: Implement for coding tasks, Review after substantive diffs,
Debug for any failing command output.
Shared spawn conventions
Use the spawn_subagent tool. Only the parent session may spawn (depth limit 1).
| Subagent | capability_mode | Typical next step |
|---|
zig-design-specialist | read-only (or omit; agent is permission_mode: plan) | Implement |
zig-specialist | omit / all | Review if risky |
zig-debug-specialist | omit / all | Review if hot-path fix |
zig-review-specialist | read-only (or omit; agent is permission_mode: plan) | Debug or Design |
- Prefer
background: true for parallel multi-unit work; collect with
get_command_or_subagent_output.
- One subagent per logical unit unless a multi-phase skill says otherwise.
- Do not run Design + Implement in parallel on the same feature unless the user asks.
- Model pins (Grok 4.5 vs Composer 2.5) live in user
~/.grok/config.toml
[subagents.models] — do not invent model overrides in skills.
Invocation examples
User says → do:
- "Review my branch" → Review, scope
branch changes
- "Review only uncommitted" → Review, scope
uncommitted changes
- "Fix this test failure" + error output → Debug
- "Design the arbitration system before we code" → Design
- "Implement slice X" → Design first if contracts unclear, else Implement
- "Review the pathfinder module" → run
/pathfinder-review skill steps
- "Best-practices review of hot subsystems" →
/zig-best-practices-review
- "Deep correctness pass on threading/pathfinding" →
/zig-deep-correctness-review
- "How ready is this for emergent gameplay?" →
/architecture-assessment
Design
subagent_type: zig-design-specialist
capability_mode: read-only
Prompt: goal, in/out of scope, owning slice, files/areas, constraints.
Implement
subagent_type: zig-specialist
Prompt: owning module(s), success criteria, validation commands, prior design if any.
Debug
subagent_type: zig-debug-specialist
Prompt: failing command + full first error block (verbatim), recent changes, display
available for zig build gpu-smoke?
Skip zig build verify until the targeted command is green.
Review
subagent_type: zig-review-specialist
capability_mode: read-only
Full Repository Path: <abs path>
Review scope: branch changes | uncommitted changes | <file list>
Base Branch: <only if non-default base>
Custom Instructions: <optional>
Summarize as a severity-sorted table; do not fix unless asked.
Multi-phase workflows
For module / architecture / best-practices / deep-correctness passes, load the
dedicated skill (slash or auto-invoke) rather than inlining here. Those skills
own unit tables, verify phases, and synthesis prompts.
Presets shared across skills: references/module-presets.md.
