workflow-apex
Systematic implementation using APEX methodology (Analyze-Plan-Execute-eXamine) with parallel agents, self-validation, and optional adversarial review. Use when implementing features, fixing bugs, or
SKILL.mdskills/workflow-apex/SKILL.md
GitHub<objective>
Execute systematic implementation workflows using the APEX methodology. This skill uses progressive step loading to minimize context usage and supports saving outputs for review and resumption.
</objective>
<quick_start>
**Step-by-step mode (default):** Each step runs in its own session. Resume with `/apex -r`.
<examples>
```bash
# Basic
/apex add auth middleware
</state_variables>
<entry_point>
</step_files>
<execution_rules>
/apex add authentication middleware
# → Runs step-00 + step-01, stops with resume command
# → /apex -r 01-add-authentication-middleware (next session)
Autonomous mode: All steps chain in one session.
/apex -a implement user registration
With adversarial review:
/apex -a -x -s fix login bug
Flags:
-a(auto): Chain all steps in one session (skip confirmations)-s(save): Save outputs to.claude/output/apex/(auto-enabled when not-a)-x(examine): Include adversarial code review-t(test): Create and run tests-w(team): Use Agent Teams for parallel research, execution, review, and resolution-pr(pull-request): Create PR at end
See <parameters> for complete flag list.
</quick_start>
Disable flags (turn OFF):
| Short | Long | Description |
|---|---|---|
-A |
--no-auto |
Disable auto mode |
-X |
--no-examine |
Disable examine mode |
-S |
--no-save |
Disable save mode |
-T |
--no-test |
Disable test mode |
-E |
--no-economy |
Disable economy mode |
-W |
--no-team |
Disable team mode |
-B |
--no-branch |
Disable branch mode |
-PR |
--no-pull-request |
Disable PR mode |
-I |
--no-interactive |
Disable interactive mode |
| </flags> |
Autonomous (skip confirmations)
/apex -a add auth middleware
Save outputs + examine
/apex -a -x -s add auth middleware
Full workflow with tests
/apex -a -x -s -t add auth middleware
With PR creation
/apex -a -pr add auth middleware
Resume previous task
/apex -r 01-auth-middleware /apex -r 01 # Partial match
Resume with flag override (enable auto mode)
/apex -a -r 01
Resume with additional flags (add tests mid-workflow)
/apex -t -r 01
Economy mode (save tokens)
/apex -e add auth middleware
Team mode (parallel execution with Agent Teams)
/apex -w implement full-stack feature /apex -w -a -x implement dashboard with backend API
Interactive flag config
/apex -i add auth middleware
Disable flags (uppercase)
/apex -A add auth middleware # Disable auto
</examples>
<parsing_rules>
**Flag parsing:**
1. Defaults loaded from `steps/step-00-init.md` `<defaults>` section
2. Command-line flags override defaults (enable with lowercase `-x`, disable with uppercase `-X`)
3. Flags removed from input, remainder becomes `{task_description}`
4. Task ID generated as `NN-kebab-case-description`
For detailed parsing algorithm, see `steps/step-00-init.md`.
</parsing_rules>
</parameters>
<output_structure>
**When `{save_mode}` = true:**
All outputs saved to PROJECT directory (where Claude Code is running):
.claude/output/apex/{task-id}/ ├── 00-context.md # Params, user request, timestamp ├── 01-analyze.md # Analysis findings ├── 02-plan.md # Implementation plan ├── 03-execute.md # Execution log ├── 04-validate.md # Validation results ├── 05-examine.md # Review findings (if -x) ├── 06-resolve.md # Resolution log (if -x) ├── 07-tests.md # Test analysis and creation (if --test) ├── 08-run-tests.md # Test runner log (if --test) └── 09-finish.md # Workflow finish and PR creation (if --pull-request)
**00-context.md structure:**
```markdown
# APEX Task: {task_id}
**Created:** {timestamp}
**Task:** {task_description}
## Configuration
| Flag | Value |
|------|-------|
| Auto mode (`-a`) | {auto_mode} |
| Examine mode (`-x`) | {examine_mode} |
| Save mode (`-s`) | {save_mode} |
| Test mode (`-t`) | {test_mode} |
| Economy mode (`-e`) | {economy_mode} |
| Team mode (`-w`) | {team_mode} |
| Branch mode (`-b`) | {branch_mode} |
| PR mode (`-pr`) | {pr_mode} |
| Interactive mode (`-i`) | {interactive_mode} |
## User Request
{original user input}
## Progress
| Step | Status | Timestamp |
|------|--------|-----------|
| 00-init | ... | ... |
...
## State Snapshot
**feature_name:** ...
**next_step:** ...
### Acceptance Criteria
### Step Context
### Gotchas
When provided, step-00 will:
- Find task folder:
ls .claude/output/apex/ | grep {resume_task}(exact or partial match) - Restore state: Read
00-context.md→ all flags, task info, acceptance criteria, step context - Apply overrides: Any flags passed with
-roverride stored values (e.g.,/apex -a -r 01enables auto_mode) - Re-evaluate steps: If flags changed (e.g.,
-tadded), update Progress table Skip→Pending - Find resume target: Read
next_stepfrom State Snapshot (fallback: first non-Complete/non-Skip row in Progress table) - Handle crashes: "⏳ In Progress" status = crashed step → restart it
- Load target step: Each step has a Context Restoration block that reads its required prior outputs
Error handling:
/apex -rwithout prior-s: no output dir → clear error message- No match found → list available tasks, ask user to specify
Supports partial matching (e.g., -r 01 finds 01-add-auth-middleware).
</resume_workflow>
Session behavior:
auto_mode=false(default): Each step stops after completion with a resume command. Steps 00+01 run together as the first session.auto_mode=true(-a): All steps chain in a single session (no stops).</workflow>
When auto_mode is false (default), APEX runs one step per session:
- First session: step-00-init + step-01-analyze run together
save_modeis auto-enabled (required for resume)- After step-01 completes: saves state, shows resume command, STOPS
- Each subsequent session:
/apex -r {task_id}runs one step- Restores all state from
00-context.md+ previous step outputs - Executes the step
- Saves state, shows resume command, STOPS
- Restores all state from
Session boundary display:
═══════════════════════════════════════
STEP {NN} COMPLETE: {name}
═══════════════════════════════════════
{summary}
Resume: /apex -r {task_id}
Next: Step {NN} - {description}
═══════════════════════════════════════
Context restoration per step:
| Step | Reads on Resume |
|---|---|
| 01-analyze | 00-context.md only |
| 02-plan | 00-context.md + 01-analyze.md |
| 03-execute | 00-context.md + 02-plan.md (+ git diff for partial work) |
| 04-validate | 00-context.md + 03-execute.md |
| 05-examine | 00-context.md + 03-execute.md + 05-examine.md |
| 06-resolve | 00-context.md + 05-examine.md |
| 07-tests | 00-context.md + 03-execute.md |
| 08-run-tests | 00-context.md + 07-tests.md |
| 09-finish | 00-context.md only |
State Snapshot (in 00-context.md): tracks next_step, acceptance criteria, per-step context summaries, and gotchas (surprises, workarounds, deviations from plan) for reliable cross-session state transfer.
</stop_resume>
| Variable | Type | Description |
|---|---|---|
{task_description} |
string | What to implement (flags removed) |
{feature_name} |
string | Kebab-case name without number (e.g., add-auth-middleware) |
{task_id} |
string | Full identifier with number (e.g., 01-add-auth-middleware) |
{acceptance_criteria} |
list | Success criteria (inferred or explicit) |
{auto_mode} |
boolean | Skip confirmations, use recommended options |
{examine_mode} |
boolean | Auto-proceed to adversarial review |
{save_mode} |
boolean | Save outputs to .claude/output/apex/ |
{test_mode} |
boolean | Include test steps (07-08) |
{economy_mode} |
boolean | No subagents, direct tool usage only |
{team_mode} |
boolean | Use Agent Teams for parallel research (01), execution (03), review (05), and resolution (06) |
{branch_mode} |
boolean | Verify not on main, create branch if needed |
{pr_mode} |
boolean | Create pull request at end |
{interactive_mode} |
boolean | Configure flags interactively |
{next_step} |
string | Next step to execute (persisted in State Snapshot) |
{reference_files} |
string | Path(s) to reference documents (e.g., brainstorm output) |
{resume_task} |
string | Task ID to resume (if -r provided) |
{output_dir} |
string | Full path to output directory |
{branch_name} |
string | Created branch name (if branch_mode) |
FIRST ACTION: Load steps/step-00-init.md
Step 00 handles:
- Flag parsing (-a, -x, -s, -t, -e, -w, -b, -pr, -i, -r)
- Resume mode detection and task lookup
- Output folder creation (if save_mode)
- 00-context.md creation (if save_mode)
- State variable initialization
After initialization, step-00 loads step-01-analyze.md.
</entry_point> <step_files> **Progressive loading - only load current step:**| Step | File | Purpose |
|---|---|---|
| 00 | steps/step-00-init.md |
Parse flags, create output folder, initialize state |
| 00b | steps/step-00b-branch.md |
Branch verification and creation (if branch_mode) |
| 00b | steps/step-00b-interactive.md |
Interactive flag configuration via AskUserQuestion (if interactive_mode) |
| 00b | steps/step-00b-economy.md |
Economy mode adjustments (if economy_mode) |
| 01 | steps/step-01-analyze.md |
Smart context gathering with 1-10 parallel agents (built-in + custom) |
| 01b | steps/step-01b-team-analyze.md |
Agent Team parallel research (if team_mode) |
| 02 | steps/step-02-plan.md |
File-by-file implementation strategy |
| 03 | steps/step-03-execute.md |
Todo-driven implementation (solo) |
| 03b | steps/step-03b-team-execute.md |
Agent Team parallel implementation (if team_mode) |
| 04 | steps/step-04-validate.md |
Self-check and validation |
| 05 | steps/step-05-examine.md |
Adversarial code review (optional) |
| 05b | steps/step-05b-team-examine.md |
Agent Team parallel adversarial review (if team_mode) |
| 06 | steps/step-06-resolve.md |
Finding resolution (optional) |
| 06b | steps/step-06b-team-resolve.md |
Agent Team parallel finding resolution (if team_mode) |
| 07 | steps/step-07-tests.md |
Test analysis and creation (if --test) |
| 08 | steps/step-08-run-tests.md |
Test runner loop until green (if --test) |
| 09 | steps/step-09-finish.md |
Create pull request (if --pull-request) |
- Load one step at a time - Only load the current step file
- ULTRA THINK before major decisions
- Persist state variables across all steps
- Follow next_step directive at end of each step
- Save outputs if
{save_mode}= true (append to step file) - Use parallel agents for independent exploration tasks
- Session boundary: When
auto_mode=false, each step STOPS after completion and displays a resume command. Whenauto_mode=true, steps chain directly. See<stop_resume>for details. - Per-step commits: When
branch_mode=true, each code-modifying step (03, 04, 06, 07, 08) automatically commits changes with messageapex({task_id}): step NN - name. This gives PRs granular commit history. - Worktree isolation: For git worktree-based workspace isolation, use the
using-git-worktreesskill before running/apex. - Team mode: When
{team_mode}=true, Agent Teams parallelize four phases: research (step-01b-team-analyze.md), implementation (step-03b-team-execute.md), adversarial review (step-05b-team-examine.md), and finding resolution (step-06b-team-resolve.md). Researchers share findings cross-domain; reviewers challenge each other's findings; resolvers fix findings by file group. Incompatible with-e(economy mode).
🧠 Smart Agent Strategy in Analyze Phase
The analyze phase (step-01) uses adaptive agent launching (unless economy_mode):
Available agents:
Explore(built-in) - Find existing patterns, files, utilitiesexplore-docs(custom, requires.claude/agents/explore-docs.md) - Research library docs via Context7 (use when unfamiliar with API)websearch(built-in) - Find approaches, best practices, gotchas
Review agents (step-05):
Explore(built-in) - Adversarial review with focus areas (security, logic, clean-code) — read-only, fast
Launch 1-10 agents based on task complexity:
| Complexity | Agents | When |
|---|---|---|
| Simple | 1-2 | Bug fix, small tweak |
| Medium | 2-4 | New feature in familiar stack |
| Complex | 4-7 | Unfamiliar libraries, integrations |
| Major | 6-10 | Multiple systems, many unknowns |
BE SMART: Analyze what you actually need before launching. Don't over-launch for simple tasks, don't under-launch for complex ones.
</execution_rules> <save_output_pattern> **When `{save_mode}` = true:**Step-00 runs scripts/setup-templates.sh to initialize all output files from templates/ directory.
Each step then:
- Run
scripts/update-progress.sh {task_id} {step_num} {step_name} "in_progress" - Append findings/outputs to the pre-created step file
- Run
scripts/update-progress.sh {task_id} {step_num} {step_name} "complete"
Template system benefits:
- Reduces token usage by ~75% (1,350 tokens saved per workflow)
- Templates in
templates/directory (not inline in steps) - Scripts handle progress tracking automatically
- See
templates/README.mdfor details
- Each step loaded progressively
- All validation checks passing
- Outputs saved if
{save_mode}enabled - Tests passing if
{test_mode}enabled - Clear completion summary provided</success_criteria>