Apex

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.

Quick Start

Basic usage:

/apex add authentication middleware

Recommended workflow (autonomous with save):

/apex -a -s implement user registration

Flags:

• -a (auto): Skip confirmations
• -s (save): Save outputs to .claude/output/apex/
• -e (economy): No subagents, save tokens

See Parameters below for the complete flag list.

Parameters

Flags

Enable flags (turn ON):

Short	Long	Description
-a	--auto	Autonomous mode: skip confirmations, auto-approve plans
-s	--save	Save mode: output each step to .claude/output/apex/
-e	--economy	Economy mode: no subagents, save tokens (for limited plans)
-r	--resume	Resume mode: continue from a previous task
-b	--branch	Branch mode: verify not on main, create branch if needed
-i	--interactive	Interactive mode: configure flags via AskUserQuestion
-f	--from	Prior context: GitHub issue (#N, URL), spec, brainstorm report, or any file as foundational input for analysis. Non-Markdown sources (PDF, DOCX, PPTX, audio, YouTube) → pre-process with /markitdown -s and pass the saved path

Disable flags (turn OFF):

Short	Long	Description
-A	--no-auto	Disable auto mode
-S	--no-save	Disable save mode
-E	--no-economy	Disable economy mode
-B	--no-branch	Disable branch mode

Examples

# Basic
/apex add auth middleware

# Autonomous (skip confirmations)
/apex -a add auth middleware

# Save outputs
/apex -a -s add auth middleware

# Resume previous task
/apex -r 01-auth-middleware
/apex -r 01  # Partial match

# From a GitHub issue
/apex -f "#42" implement what issue 42 describes

# From prior analysis (spec, brainstorm report, RFC)
/apex -f .claude/output/spec/auth-system/spec.md implement WS-1
/apex -f .claude/output/brainstorm/neon-setup/brainstorm.md implement Neon database

# Economy mode (save tokens)
/apex -e add auth middleware

# Interactive flag config
/apex -i add auth middleware

# Disable flags (uppercase)
/apex -A add auth middleware  # Disable auto

Parsing Rules

1. Defaults loaded from steps/step-00-init.md ## Default Configuration 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 the detailed parsing algorithm, see steps/step-00-init.md.

Output Structure

The output path is .claude/output/apex/{task-id}/, where {task-id} is NN-feature-name (e.g., 01-add-auth). The numbered prefix is intentional — it preserves task ordering for the -r resume lookup. This is a deliberate divergence from the repo-wide .claude/output/{skill}/{slug}/ convention; resume needs ordering, plain slugs don't carry it.

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-examine.md  # Examination results

00-context.md structure — see templates/00-context.md for the canonical template (populated by scripts/setup-templates.sh).

Resume Workflow

Resume mode (-r {task-id}):

Resolve the partial ID deterministically, then restore state:

bash ${CLAUDE_SKILL_DIR}/scripts/resume_lookup.sh {partial_id}

• Exit 0 → absolute task path on stdout; continue.
• Exit 1 → ambiguous; candidates print on stderr. Show them to the user, ask which one.
• Exit 2 → no match; halt with a clear error.

Step-00 then restores state from {task_dir}/00-context.md and continues from the next pending step.

For implementation details, see steps/step-00-init.md.

Workflow

Standard flow:

1. Parse flags and task description
2. If -r: Execute resume workflow
3. If -s: Create output folder and 00-context.md
4. Load step-01-analyze.md → gather context
5. Load step-02-plan.md → create strategy
6. Load step-03-execute.md → implement
7. Load step-04-examine.md → verify and complete

State Variables

Persist throughout all steps:

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
{save_mode}	boolean	Save outputs to .claude/output/apex/
{economy_mode}	boolean	No subagents, direct tool usage only
{branch_mode}	boolean	Verify not on main, create branch if needed
{interactive_mode}	boolean	Configure flags interactively
{from_file}	string	Path to prior context file (if -f provided)
{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)

Entry Point

FIRST ACTION: Load steps/step-00-init.md.

Step 00 handles:

• Flag parsing (-a, -s, -e, -b, -i, -f, -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.

Step Files

Progressive loading — only load the current step:

Step	File	Purpose
00	steps/step-00-init.md	Parse flags, create output folder, initialize state
01	steps/step-01-analyze.md	Smart context gathering with 1-10 parallel agents based on complexity
02	steps/step-02-plan.md	File-by-file implementation strategy
03	steps/step-03-execute.md	Todo-driven implementation
04	steps/step-04-examine.md	Self-check, examination, and workflow completion

Execution Rules

• 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

Smart Agent Strategy in Analyze Phase

The analyze phase (step-01) uses adaptive agent launching (unless economy_mode):

Available subagent types (built-in):

• Explore — find existing patterns, files, utilities (read-only, fast)
• general-purpose — research library docs, web search, approaches, gotchas

Launch 0-10 agents based on task complexity:

Complexity	Agents	When
Trivial / pre-contextual	0	Target already known, or -f context covers it — use direct tools
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 spawn a subagent for work you can complete directly in a single response. Spawn multiple subagents in the same turn when fanning out across items or reading multiple files.

Save Output Pattern

When {save_mode} = true:

Step-00 runs scripts/setup-templates.sh to initialize all output files from the templates/ directory.

Each step then:

1. Run scripts/update-progress.sh {task_id} {step_num} {step_name} "in_progress"
2. Append findings/outputs to the pre-created step file
3. Run scripts/update-progress.sh {task_id} {step_num} {step_name} "complete"

scripts/validate_state.sh is shipped as a manual debugging utility — invoke it on demand to verify a task's state is consistent (e.g., when a resume looks suspicious). It is not part of the per-step workflow.

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.md for details

Success Criteria

• Each step loaded progressively
• All examination checks passing
• Outputs saved if {save_mode} enabled
• Clear completion summary provided