From productivity-skills
Systematic implementation using APEX methodology (Analyze-Plan-Execute-eXamine) with parallel subagents and self-validation. Use when implementing features, fixing bugs, or making code changes that benefit from structured workflow.
How this skill is triggered — by the user, by Claude, or both
Slash command
/productivity-skills:apex [-a] [-s] [-e] [-b] [-i] [-g] [-f <context>] [-r <task-id>] <task description>When to use
When the task is non-trivial and benefits from analysis before coding. When multiple files are involved, the codebase is unfamiliar, or thoroughness matters more than speed. When the user says "implement", "build", "add feature" for anything beyond a quick fix. NOT for trivial single-file changes — use `/oneshot` for those. NOT for exploration or planning only — use `/forge`. On a Fable-class or newer frontier session, prefer `/ultrapex`; apex is the pick for step-gated checkpoints and resumable state.
[-a] [-s] [-e] [-b] [-i] [-g] [-f <context>] [-r <task-id>] <task description>The summary Claude sees in its skill listing — used to decide when to auto-load this skill
<!-- canonical:adversarial-verification:start -->
references/derivation-lens.mdscripts/resume_lookup.shscripts/setup-templates.shscripts/update-progress.shscripts/validate_state.shsteps/step-00-init.mdsteps/step-00b-branch.mdsteps/step-00b-economy.mdsteps/step-00b-interactive.mdsteps/step-01-analyze.mdsteps/step-02-plan.mdsteps/step-03-execute.mdsteps/step-04-examine.mdtemplates/00-context.mdtemplates/01-analyze.mdtemplates/02-plan.mdtemplates/03-execute.mdtemplates/04-examine.mdtemplates/README.mdtemplates/step-complete.mdThese rules govern how this skill trusts its own output — apply them whenever it verifies a claim, a defect, a source, or a decision before acting on it.
These rules govern how this skill changes code — apply them whenever it writes, edits, or proposes a fix.
Internal planning labels are author coordinates, not reader coordinates. Strip them from every shipped artifact this skill emits — code, comments, commit subjects/bodies, PR titles/descriptions, release notes, doc paragraphs, non-trivial comments.
WS-N, Phase-A, Step-3, issue or ticket numbers, plan phase names from the source spec, issue body, or planning artifact. Translate to the domain noun (Runs the battery script (WS-2) → Runs the battery script). <file>", "carried verbatim from", "the cleanup pass", "the audit", "spec AC" standalone. Replace with the concrete fact (carries the routing from the prior aggregation → routes via the merge keys in the synthesis module). Carve-outs — literal WS-N is legitimate where the skill IS the format authority (forge templates, apex rule documentation). Reviewer-facing dev docs (e.g. MIGRATION.md under tests/<skill>/) may reference deleted artifacts by their author-time names.
These rules govern every prose artifact this skill emits — READMEs, CHANGELOGs, commit messages, PR bodies, release notes, doc paragraphs, non-trivial comments. Apply them at draft time, verify before output.
NEVER commit secrets)./humanize-en if installed.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.
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/{project}/apex/-e (economy): No subagents, save tokensSee Parameters below for the complete flag list.
| Short | Long | Off | Long-off | Behavior |
|---|---|---|---|---|
-a | --auto | -A | --no-auto | Skip confirmations, auto-approve plans |
-s | --save | -S | --no-save | Save outputs to ~/.claude/output/{project}/apex/ |
-e | --economy | -E | --no-economy | No subagents, direct tools only |
-b | --branch | -B | --no-branch | Verify not on main; create branch if needed |
-i | --interactive | — | — | Configure flags via AskUserQuestion |
-g | --goal | -G | --no-goal | Wire /goal to loop step-04 until AC verified (v2.1.139+; auto-on when CLAUDE_NONINTERACTIVE is exported (set it in claude -p wrappers and CI)) |
-r | --resume | — | — | Continue from a previous task (takes <task-id>) |
-f | --from | — | — | Prior context: GitHub issue (#N, URL), forge plan (e.g. ~/.claude/output/{project}/forge/forge-{slug}.md), or any file as foundational input. Non-Markdown → pre-process via /markitdown -s |
Parsing algorithm, defaults, examples, and override semantics (lowercase enables, uppercase disables): steps/step-00-init.md.
-g (the /goal integration) requires Claude Code v2.1.139 or later. On older versions, Claude Code rejects the unknown slash command and the flag becomes a no-op without halting apex. If /goal is unavailable in your harness, skip the goal gate and proceed.
The /goal evaluator is transcript-only — it cannot run tools or read files independently. The emitted condition therefore forces command output into the transcript verbatim (e.g. npm test exits 0, not "tests pass") so the evaluator has a deterministic signal to judge.
-g is orthogonal to -a: -a skips per-tool prompts within a turn; -g skips per-turn prompts across turns. Recommended together for unattended claude -p "/apex …" runs.
Analyze can fetch third-party content into the workflow:
general-purpose subagents run web searches and WebFetch./find-docs or Context7 lookups pull current API references.-f #N ingests title, body, and comments verbatim.-f <path> — forge plan, RFC, design doc, markitdown output of a PDF — read literally.Fetched content feeds the analysis report that Plan and Execute work from. An adversarial document hosted at a fetched URL, or pasted into an issue body, can attempt indirect prompt injection — instructions disguised as data that the model could misread as directives.
User review is the trust boundary. Apex returns the analysis report and proposed plan for explicit approval before Execute begins (unless -a is set). Confirm the surfaced files, patterns, and acceptance criteria match intent before approving — anything fetched during Analyze passes through that review.
To remove the surface entirely, pass -e (economy mode): no subagents, no web fetches, direct tools only. Trade-off: less depth on unfamiliar libraries.
The output path is ~/.claude/output/{project}/apex/{task-id}/, where {project} is the repo basename and {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 single-file {skill}-{slug}.md shape (~/.claude/output/{project}/{skill}/{skill}-{slug}.md): apex is a multi-file task workspace and resume needs ordered task dirs, which one canonical file cannot carry.
When {save_mode} = true:
All outputs saved under ~/.claude/output/{project}/apex/{task-id}/, where {project} is the kebab-cased basename of the git toplevel (else the cwd outside a git repo):
~/.claude/output/{project}/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 mode (-r {task-id}):
$SKILL_DIR = this skill's folder — ${CLAUDE_SKILL_DIR} in Claude Code, the directory containing this SKILL.md elsewhere.
Resolve the partial ID deterministically, then auto-validate state before restoring:
bash "$SKILL_DIR"/scripts/resume_lookup.sh {partial_id}
# → resolves to {task_dir}
bash "$SKILL_DIR"/scripts/validate_state.sh {task_id} {step_num}
# → exit 0: state consistent, continue restoration
# → non-zero: halt with the script's stderr findings; do NOT restore
resume_lookup.sh:
validate_state.sh (auto-runs on every resume):
{step_num}.Step-00 reads {task_dir}/00-context.md to determine the next pending step, invokes validate_state.sh against that step, then restores state variables and continues.
For implementation details, see steps/step-00-init.md.
Step state persists across steps. Strings: {task_description} {feature_name} {task_id} {output_dir} {branch_name} {from_file} {resume_task}. Lists: {acceptance_criteria} {negative_acceptance} (must-NOT criteria, inferred or accepted verbatim from a spec via -f). Booleans: {auto_mode} {save_mode} {economy_mode} {branch_mode} {interactive_mode} {goal_mode}. Full definitions: steps/step-00-init.md.
FIRST ACTION: Load steps/step-00-init.md.
Step 00 handles:
-a, -s, -e, -b, -i, -g, -f, -r)save_mode)00-context.md creation (if save_mode)After initialization, step-00 loads step-01-analyze.md.
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 |
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). Type names are Claude Code's; other harnesses use their nearest equivalents.general-purpose — research library docs, web search, approaches, gotchasLaunch 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.
If your harness has no subagents, apply the economy-mode overrides (steps/step-00b-economy.md) — direct tools, run the explorations sequentially yourself.
When {save_mode} = true:
Step-00 runs scripts/setup-templates.sh to initialize all output files from the templates/ directory.
Each step then:
scripts/update-progress.sh {task_id} {step_num} {step_name} "in_progress"scripts/update-progress.sh {task_id} {step_num} {step_name} "complete"scripts/validate_state.sh auto-runs on every -r resume (see § Resume Workflow). It is also available manually for ad-hoc state verification — invoke it on demand against any task to confirm consistency.
Template system benefits:
templates/ directory (not inline in steps)templates/README.md for details-r resume with exit 3. scripts/validate_state.sh:66 requires the row in 00-context.md's ## Progress table to match the step filename exactly (| 01-analyze | ✓ Complete |). A hand-renamed step file or a half-applied update-progress.sh invocation leaves the table out of sync; tests/apex/test_validate_state.py:102-107 pins this. Fix: always run scripts/update-progress.sh after step completion; never rename step files post-creation.-f is an injection surface for indirect prompt attacks. A GitHub issue body, a WebFetch-pulled doc, or a -f file written by an upstream skill can embed instructions disguised as data. Trust model (§ above) requires user review of the analysis report before Execute. Auto-mode (-a) skips per-tool confirmations but does not skip plan approval. Drop the surface entirely for sensitive tasks: pass -e (no subagents, no fetches).-f mismatches resumed -r task ID. setup-templates.sh recreates 00-context.md on first setup; resuming with -r 01-foo but -f ~/.claude/output/{project}/forge/forge-bar.md mixes two intents: state variables get the -f content, progress table reads the resumed task. Always match the IDs: -r 01-foo pairs with -f ~/.claude/output/{project}/apex/01-foo/02-plan.md or a fresh forge plan for that task.{NN-feature}/ collisions across parallel worktrees. Two worktrees of the same repo share the same kebab-cased {project} basename → both write under ~/.claude/output/{project}/apex/. Auto-numbering scans the dir at script invocation, so two near-simultaneous setup-templates.sh calls can land on the same NN prefix. Fix: serialize apex setup across worktrees of the same repo, or rename one worktree's basename to differentiate.{save_mode} enabledGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub coroboros/agent-skills --plugin productivity-skills