eliteforge-codex-superpower

What this skill does

# EliteForge Codex Superpower

## Environment Variables

- `ELITEFORGE_SKILL_SUPERPOWER_TDD_AGENT` [optional] Codex runtime `spawn_agent.agent_type` for bounded AC TDD slice workers; defaults to `worker`.
- `ELITEFORGE_SKILL_SUPERPOWER_CODING_AGENT` [optional] Codex runtime `spawn_agent.agent_type` for coding subagents such as backend/frontend/database implementation workers; defaults to `worker`.
- `ELITEFORGE_SKILL_SUPERPOWER_REVIEWER_AGENT` [optional] Codex runtime `spawn_agent.agent_type` for verify and review workers; defaults to `worker`.

## Codex Runtime Agent Selection

Environment variable values are Codex runtime agent types passed to `spawn_agent.agent_type`, not workflow role names. Valid values must come from currently available Codex agent types such as `worker`, `explorer`, `coder`, or `coder-spark`.

Resolve runtime agent types before every `spawn_agent` call:

- TDD slice workers: `ELITEFORGE_SKILL_SUPERPOWER_TDD_AGENT` -> `worker`.
- Backend, frontend, database: `ELITEFORGE_SKILL_SUPERPOWER_CODING_AGENT` -> `worker`.
- Verify, review: `ELITEFORGE_SKILL_SUPERPOWER_REVIEWER_AGENT` -> `worker`.
- Explorer: always `explorer`.

If a configured environment variable is set to a value that is not an available Codex runtime agent type, stop before spawning and record the invalid value. Fall back to `worker` only when no configured variable in the resolution chain is set.

For every non-explorer worker spawn, pass the resolved value explicitly as `spawn_agent.agent_type`. If resolution returns `coder-spark`, call `spawn_agent` with `agent_type: "coder-spark"`. Do not omit `agent_type`, do not rely on default spawn behavior, do not replace it with a workflow role, and do not use `fork_context: true` with an explicit `agent_type`; pass a focused prompt with required AC rows, command aliases, write scope, and worktree context instead.

Workflow roles such as `tdd-slice-worker`, `backend-worker`, `frontend-worker`, `database-worker`, and `review-worker` belong only in task ownership, prompts, worktree plans, branches, and report filenames. They are never Codex runtime `agent_type` values.

## Workflow Nature

Default model:
```
lead agent + explorer subagents -> approved brainstorming design -> explorer-assisted PRD synthesis -> approved PRD -> repo-aware feature selection -> selected feature model -> AC index -> proof rows + command index -> AC task rows -> AC evidence rows
```

This skill is AC-only across documents. The only global business traceability ID is `AC-*`. Do not create global `INT-*`, `TDD-*`, `TASK-*`, `EV-*`, or `BVE-*` IDs. Page interactions, TDD cases, tasks, and browser evidence are fields under the owning AC row.

## Execution Modes

- `solo`: explicit fallback only. Lead handles docs, coding, validation, and evidence for a small bounded AC slice on the selected-git-spec main/base branch after recording the reason.
- `hybrid`: default. Lead owns docs, integration, and final judgment; behavior-changing AC slices should use one `tdd-slice-worker` unless the user explicitly approves solo or the slice is documentation-only/trivial.
- `parallel`: use multiple workers only when contracts are stable, write scopes are disjoint, and splitting reduces wall-clock time.

Default task unit: one bounded AC slice with `phase: tdd`, covering RED -> GREEN -> focused VERIFY. Do not split RED worker, GREEN worker, and review worker by ceremony. Split backend/frontend/database workers only for real fan-out.

Base branch rule: selected-git-spec main/base branch creation is mandatory before behavior-changing execution. `solo` means no delegated worker, not "work directly on the original checkout." Even solo execution must happen from the selected-git-spec main/base branch and be recorded in `orchestration/worktree-plan.md`.

Dispatch decision rule: every behavior-changing task row (`phase: tdd|red|green|refactor`) must have a row in `orchestration/worktree-plan.md#Dispatch Decisions`.

Decision order:
1. If the row is documentation-only, exploration, support, integration, review, or verify-only, do not spawn for implementation.
2. If the user explicitly approved solo or the row is genuinely trivial, choose `solo` and record the approval/trivial rationale.
3. If subagents are unavailable or git worktree setup is blocked, choose `blocked` and stop for user decision.
4. If contracts are stable, write scopes are isolated, and splitting reduces wall-clock, choose `parallel`.
5. Otherwise choose `spawn`; default `hybrid` means one bounded AC implementation worker owns RED -> GREEN -> focused VERIFY.

Before each `spawn` or `parallel` dispatch, resolve and record the delegated worker `runtime_agent_type` in `orchestration/worktree-plan.md`. User-facing dispatch summaries must name both the workflow owner and runtime type, for example `execution_owner=tdd-slice-worker` and `runtime_agent_type=coder-spark`.

Grouping: do not mechanically spawn one worker per AC when adjacent AC rows share the same files, command aliases, and interaction surface. One spawned worker may own multiple tightly coupled AC rows if the prompt remains bounded. Do not group AC rows that require disjoint backend/frontend/database fan-out, unrelated files, or independent browser flows.

## Single Source Of Truth

- Feature model and boundary: `spec/feature-spec.md`; no `AC-*`, commands, RED/GREEN, or evidence.
- Acceptance index: `spec/acceptance.md`; the only file that defines `AC-*`.
- Proof plan: `spec/test-plan.md`; proof rows by `AC-*` plus local `CMD-*` command aliases.
- Task rows: `tasks/*.md`; execution slices by `AC-*`, usually `phase: tdd`.
- Runtime/process state: `orchestration/*.md`; `worktree-plan.md` records the mandatory selected-git-spec main/base branch, and `context-index.md` provides navigation.
- Evidence ledgers: `reports/*.md`; RED/GREEN/VERIFY/browser evidence by `AC-*`.

All documents other than the owner file reference facts using `AC-*`, local `CMD-*`, or `@ref:<relative-file>#<anchor>`. Do not duplicate expanded facts across files.

## Context Budget

- Generate or refresh `orchestration/context-index.md` before dispatch, review, or final validation.
- Read `context-index.md` first, then open only the needed file, heading, and AC row.
- For approved brainstorming and PRD inputs, search by stable headings first. Use module, feature, page, rule, exception, and acceptance heading text from the PRD; open only matching sections. Do not paste a whole brainstorming spec or whole PRD into a feature draft or worker prompt.
- Worker prompts include only relevant AC rows, command aliases, write scope, and referenced sections. Do not paste whole `spec/`, `tasks/`, or `reports/`.
- Reports and worker fragments keep deltas and evidence only; they must not restate feature requirements, AC prose, or page design.

## External Browser Skill Compatibility

External browser/testing skills, including `webapp-testing`, are capability providers only. Do not edit or depend on their EliteForge document contract if it conflicts with this skill.

When delegating browser work, the lead prompt must provide the AC-only contract explicitly:
- Inputs: assigned `AC-*` rows, matching proof rows, `CMD-*` command aliases, route/surface references, and write scope.
- Output: `reports/*.md` evidence rows keyed by `AC-*`.
- Browser evidence fields: clicks, inputs, network assertions, visible feedback, and artifacts.
- Forbidden outputs: `test-scope.md`, global `TDD-*`, `TASK-*`, `INT-*`, `EV-*`, or `BVE-*` IDs.

Use external browser skills for Playwright technique, server lifecycle, selector discovery, screenshots, traces, and logs. This skill remains the source of truth for document names, IDs, report shape, and validation.

## Workspace Contract

Use `docs/features/<feature-slug>/` with `spec/`, `tasks/`, `orchestration/`, and `reports/`. Use `assets/` templates. Derive `<feature-slug>` from product feature name (lowercase kebab-case). Do not derive branch names, worktree paths, or agent