Eliteforge Codex Superpower

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 names from this skill.

One workspace represents one bounded feature only. Do not use one docs/features/<feature-slug>/ tree to hold an entire broad brainstorming spec or whole-product PRD that still contains several independent capabilities.

Before any behavior-changing execution, select the active git skill:

• eliteforge-git-feature-oriented-spec (full spec)
• eliteforge-git-feature-oriented-lite-spec (lite spec)
• If undeclared, stop and ask user

Use the chosen git skill as the only source for main branch, worktree path, multi-agent base, subagent branch, agentId, and subtaskName. Create or verify the selected-git-spec main/base branch before implementation, even when no worker is spawned. Record Codex runtime id separately in worktree-plan.md.

If files exist, preserve decisions and update in place.

Brainstorming And PRD Prerequisites

Before entering New Feature Delivery or Feature Evolution, activate eliteforge-brainstorming, then eliteforge-prd-generator.

• Use eliteforge-brainstorming to converge scope, alternatives, and design decisions before feature drafting or reopening.
• Use eliteforge-prd-generator to turn the approved brainstorming output into a searchable product definition. The PRD must carry feature requirements by module, page prototypes and interactions, business rules, exception/boundary cases, shared requirements, feature inventory, dependency map, recommended implementation order, and product-level acceptance.
• Keep the handoff non-duplicative: brainstorming owns why, alternatives, and decisions; PRD owns what must be built and how users, pages, rules, exceptions, and boundaries behave.
• Reuse is allowed only when an already approved brainstorming spec or approved PRD still matches the current request and repository state, and the user approves reuse.
• Do not let the lead agent carry brainstorming, PRD synthesis, and feature selection alone. Use read-only explorer subagents for repo/context scan before or during brainstorming, then again for PRD input synthesis and repo-aware feature selection.
• After the PRD is approved, the lead agent must select one bounded feature from PRD headings, confirm shared requirements, page/rule/exception sources, dependency relations, and implementation order against repository reality, then select or reopen one feature workspace.
• Do not start references/zero-one-delivery.md or references/feature-evolution.md until brainstorming and PRD are approved or the user explicitly approves reuse of existing approved upstream docs.

Workflow Selection

New Feature Delivery: after the brainstorming and PRD prerequisites pass, no existing feature workspace, starting new feature 0-1.

Feature Evolution: after the brainstorming and PRD prerequisites pass, changing, refactoring, extending, narrowing, or reopening existing workspace. Re-enter gates from earliest affected design point.

Both start from approved brainstorming output plus an approved PRD, then share the same feature-selection gate, AC-only documents, validators, git-spec constraints, context-index rule, and execution-mode rules.

Non-Negotiable Rules

1. Run brainstorming first. Start with eliteforge-brainstorming before any new feature 0-1 flow or feature evolution, unless the current request already has an approved brainstorming spec that the user approves for reuse. 2. Turn approved brainstorming into PRD. After brainstorming approval, activate eliteforge-prd-generator to write or refine the searchable product definition that superpower will use as its product-layer input. 3. Use subagents for brainstorming, PRD, and feature selection. Before or during brainstorming, dispatch read-only explorer subagents for repo/context scan. After brainstorming approval, dispatch read-only explorer subagents again for PRD input synthesis, then for repo-aware feature selection, heading search, and dependency validation. 4. Select one bounded feature before docs. After PRD approval, select one target feature from the approved product definition before creating or reopening docs/features/<feature-slug>/; capture only the relevant PRD heading references, not the whole PRD. 5. Make shared requirements explicit. Identify common capabilities across candidate features, decide whether they stay feature-local or become foundational work, and prioritize true shared dependencies before dependent features. 6. Make dependencies and order explicit. Record feature-to-feature dependencies, blocking relations, and recommended implementation order before Phase 4 drafting begins. 7. Draft before interrogation. Produce an opinionated draft first. Ask 3-5 blocking questions per round only after a draft exists. 8. Keep AC-only traceability. AC-* is the only global business ID across documents. 9. Keep feature spec clean. spec/feature-spec.md must not contain AC-*, TDD-*, commands, RED/GREEN, browser evidence, or execution logs. 10. Define ACs once. spec/acceptance.md owns all AC-*; each AC is one compact completion judgment line. 11. Use proof rows, not global TDD IDs. spec/test-plan.md proves ACs with case, red, green, optional interaction, and command_ref. 12. Centralize commands. CMD-* aliases live only in spec/test-plan.md#command-index; slow/browser commands require cost and rerun policy. 13. Spec interactions as AC fields. UI interactions are represented by interaction ACs and interaction: proof fields, not separate INT-* files or IDs. 14. Require concrete browser evidence. Browser evidence must list clicks, inputs, network assertions, visible feedback, and artifacts. smoke passed is not evidence. 15. Prefer bounded AC slices. Default phase: tdd task rows cover RED -> GREEN -> VERIFY for one AC slice. 16. Do not default to solo. Default execution is hybrid; solo requires explicit user approval or a recorded docs-only/trivial rationale. 17. Spawn for benefit, not ceremony. Use one tdd-slice-worker for behavior-changing AC slices when tool support is available; add more workers only for real parallelism, isolation, or long-running execution value. 18. Keep lead/worker roles explicit. Lead owns synthesis, gates, integration, review, and completion claims. Subagents own repository scan, PRD input, feature-selection input, and assigned AC slices only. 19. Respect command cost. REVIEW reuses slow/browser VERIFY evidence unless missing, failed, stale, or explicitly requested. 20. Treat external browser skills as tools. Do not edit external skills or inherit legacy EliteForge output contracts from them; the lead prompt must enforce this skill's AC-only browser evidence shape. 21. Separate git identity from Codex runtime. agentId and subtaskName come from the git skill; Codex runtime ids come from spawn_agent. 22. Create base branch before execution. orchestration/worktree-plan.md must record resolved main branch, main worktree path, and multi-agent base branch before implementation. 23. No worker edits lead/root worktree. Delegated workers use selected-git-spec worktrees; approved solo execution uses the selected-git-spec main/base branch and must be recorded in tasks/reports. 24. RED before GREEN. Every behavior-changing AC slice needs RED failure evidence before GREEN evidence. 25. Do not silently steal live worker scope. If a worker owns an AC slice, lead must not duplicate it without recording the decision. 26. Do not infer stalls from time. A running subagent remains in_progress unless platform failure, empty completion, user interruption, or approved timebox breach occurs. 27. Do not hide execution gaps. If subagents are unavailable, shared-file races appear, or evolution invalidates artifacts, record the blocker and stop for user decision.

Reference Index

Load references only when needed:

Completion Gate

Complete only when: active validation passes, reached gates have approved or approved-with-defaults decisions, every AC-* has proof rows, task rows, and final evidence rows, browser evidence is concrete when UI/browser is claimed, slow/browser reruns follow policy, and unresolved blockers are recorded.

Feature Evolution additionally requires: change classification, downstream impact analysis, affected-gate validation, stale artifact status, and old/new AC evidence migration.

Acceptance: {{FEATURE_NAME}}

Acceptance Index

Only this file defines global business traceability IDs. Use one compact line per AC.

Format: AC-<MODULE>-NN [must|should|could] [business|interaction|api|database|security|regression] Completion judgment; proof: pending.

• AC-MODULE-01 [must] [business] Business outcome is satisfied; proof: pending.

Rules:

• Do not restate the feature background.
• Do not describe implementation steps.
• Do not write test commands.
• Do not create INT-*, TDD-*, TASK-*, EV-*, or BVE-* IDs.
• Interaction ACs describe observable user behavior in one line; detailed proof belongs in spec/test-plan.md.

Valid types: business, interaction, api, database, security, regression.

Open Decisions

• None.

API Contract: {{FEATURE_NAME}}

API Overview

Summarize external and internal API behavior.

Endpoints

{{METHOD}} {{PATH}} - {{INTERFACE_NAME}}

• purpose: {{purpose}}
• auth: {{roles or permission rule}}
• acceptance_ids: AC-MODULE-01
• parameter_passing: {{path variables | query parameters | request headers | request body | multipart form data | mixed}}
• request: {{DTO name, key fields, validation}}
• response: {{DTO name, key fields, serialization}}
• client_impact: {{generated client method/types or none}}
• compatibility: {{breaking changes, migration path, deprecated fields, or none}}

Auth And Permissions

Allowed roles, denied roles, ownership checks, tenancy rules, audit requirements.

Error Contract

Format: condition -> status/code; response; AC id

• invalid request -> 400 / SERVICE_CODE; unified error response; AC-MODULE-01

Frontend Backend Boundary

Frontend responsibilities, backend responsibilities, shared types, route dependencies, generated client expectations.

Database And Transaction Boundary

Transaction boundaries, persistence responsibilities, locking behavior, consistency expectations, database error mapping.

Mock Or Adapter Expectations

Mocks, external adapters, service virtualization, test doubles, deterministic test seams.

Database Design: {{FEATURE_NAME}}

Database Decision

• status: draft
• impact: unknown
• approved_by: none
• approved_at: none

Use not_applicable when no database/persistence impact. Use approved only after user acceptance.

Existing Schema Impact

List affected tables, views, indexes, constraints, migrations, repositories, ORM entities, caches, reports, and downstream consumers.

Proposed Schema

{{object_name}}

• change_type: create|alter|drop|none
• fields: {{columns or fields}}
• constraints: {{constraints}}
• indexes: {{indexes}}
• notes: {{compatibility/migration notes}}

Relationships And Cardinality

Foreign keys, ownership, cascade, uniqueness, nullable relationships, domain invariants.

Migration Plan

Order, backward compatibility, migration names, backfills, defaults, lock risks, sequencing, rollback.

Query And Performance Plan

Primary query paths, pagination, sorting, filters, index coverage, cardinality, concurrency, locking, risks.

Data Governance

Tenancy, permissions, audit, soft delete, retention, privacy, encryption, regulatory, access logging.

Test Data And Fixtures

Seed data, factories, fixtures, containers/DB, cleanup, migration verification.

Validation Commands

• <command>: purpose; expect: evidence.

Feature Evolution Log: {{FEATURE_NAME}}

Summary

• feature_slug: {{FEATURE_SLUG}}
• total_changes: 0
• first_evolution: pending
• last_evolution: pending

Change History

Record every evolution event. spec/feature-spec.md remains current requirement; this log preserves historical trail.

#1

• change_id: 1
• timestamp: pending
• trigger: {{user_request|spec_correction|requirement_change|bug_discovery|scope_adjustment|documentation_only}}
• change_type: {{requirement_expansion|requirement_contraction|feature_model_change|database_change|api_contract_change|acceptance_change|proof_plan_change|task_execution_change|doc_correction_only}}
• gate_reopened: {{Phase 3|Phase 4A|Phase 4B|Phase 4C|Phase 4D|Phase 4E|Phase 5|Phase 6|none}}
• diff_summary: |

What changed vs before:

• {{before}}

+ {{after}}

• downstream_impact: {{feature-spec|database-design|api-contract|acceptance|test-plan|tasks|worktrees|reports|none}}
• old_evidence_status: {{retained|superseded|replaced|not_applicable|none}}
• user_approval: pending

Downstream Artifact Migration

Record how old tasks, report rows, and worktrees were handled. Do not overwrite old evidence.

• None yet.

Feature Spec: {{FEATURE_NAME}}

This file covers one bounded feature selected from the approved PRD-backed feature split. Do not use it to restate several independent features from one broad brainstorm spec or whole-product PRD.

Initial Agent Draft

• drafted_from_requirement: yes
• drafted_from_repository_findings: pending
• best_practice_defaults_applied: pending
• user_confirmation_status: waiting_human_decision

Summarize the first-pass interpretation, recommended defaults, assumptions, and at most 3 blocking confirmation questions. Do not define AC-*, test cases, commands, or evidence here.

Feature Identity And Context

• feature_slug: {{FEATURE_SLUG}}
• feature_name: {{FEATURE_NAME}}
• status: draft
• owner: {{OWNER}}
• source_request: {{SOURCE_REQUEST}}
• main_agent: first agent that activated this skill
• dependency_features: pending scan
• dependency_contracts: pending scan

Requirement

• user_story: {{USER_STORY_OR_NOT_APPLICABLE}}
• intent: {{PROBLEM_TO_SOLVE}}
• outcome: {{EXPECTED_USER_OR_BUSINESS_OUTCOME}}

Product Source Slices

Record only the upstream sections used to draft this bounded feature. Use exact PRD heading text so agents can search with rg and open the relevant section only.

• brainstorming_source: {{path and heading, or approved reuse note}}
• prd_feature_headings: {{Feature: module - feature name}}
• prd_page_headings: {{Page/Interaction headings or not applicable}}
• prd_rule_headings: {{Rule headings or not applicable}}
• prd_exception_headings: {{Exception headings or not applicable}}
• prd_acceptance_headings: {{Acceptance headings or not applicable}}

Scope Boundary

Assumptions

• {{ASSUMPTION}}

In Scope

• {{IN_SCOPE_ITEM}}

Out Of Scope

• {{OUT_OF_SCOPE_ITEM}}

Constraints

• {{CONSTRAINT}}

Feature Model

Describe only stable feature concepts: domain objects, state transitions, core business rules, permissions, tenancy, and invariants for this selected feature. Source the business rules from the PRD rule headings listed above, then rewrite them in repository-aware terms. Do not write acceptance criteria or test proof.

Page And Module Surface

List affected pages, routes, entry points, modules, APIs, database areas, shared libraries, generated clients, adapters, external services, and ownership boundaries.

When UI is in scope, describe the page/module surface enough for spec/acceptance.md to derive interaction ACs: entry, layout regions, controls, button behavior, form rules, visible states, navigation, and feedback. Source this from the PRD page and interaction headings listed above. Do not create interaction IDs.

If UI is not in scope, write exactly UI: Not applicable.

Repository Findings

Record only findings that affect design or execution: docs, modules, routes, migrations, tests, package manifests, CI commands, related feature folders, and strong dependencies.

For dependency scans, write either strong dependencies with feature names/contracts or:

Strong feature dependencies: none found after scanning <n> feature-spec.md files under <features-root>.

Open Decisions

Before writing None, identify whether this feature introduces reusable capability that may be needed by other features, bounded contexts, frontend pages, backend services, generated clients, adapters, or test utilities.

Use compact lines:

• {{capability}}; signal: {{reuse signal}}; modules: {{affected modules}}; target: {{shared module/path}}; recommendation: extract now / defer / keep feature-local; decision: waiting_human_decision.

If no candidate exists, write Common capability extraction: no candidate found with a short rationale.

Integration Log: {{FEATURE_NAME}}

Summary

Integration result, highest-risk delta, unresolved blockers (1-2 lines).

Integration Events

#1

• event_id: 1
• worktree_ref: @ref:orchestration/worktree-plan.md#agent-worktrees
• ac_ref: AC-MODULE-01
• task_ref: @ref:tasks/{{TASK_FILE}}#task-rows
• action: merge|cherry-pick|patch-apply|validate|conflict-resolution
• command_ref: @ref:spec/test-plan.md#command-index
• result: pending
• evidence: pending

Conflict Log

• None.

Validation After Integration

• @ref:spec/test-plan.md#command-index: pending evidence.

Blockers

• None.

{{REPORT_KIND}} Report: {{FEATURE_NAME}}

Summary

Result, highest-risk delta, final status (1-2 lines). Do not restate feature requirements.

Evidence Rows

Use one compact row per AC. Do not create global evidence IDs.

Format: AC-<MODULE>-NN | red: <failure summary or not applicable> | green: <pass summary or not applicable> | command_ref: CMD-<ALIAS>|none | browser: clicks=<...>; inputs=<...>; network=<...>; feedback=<...>; artifacts=<...> | status: <pending|done|blocked|not_applicable>.

• AC-MODULE-01 | red: pending | green: pending | command_ref: CMD-BE-TEST | browser: not applicable | status: pending.

Changed Paths

• None yet.

Commands

• @ref:spec/test-plan.md#command-index: pending.

Blockers

• None.

{{TASK_KIND}} Task: {{FEATURE_NAME}}

Execution Contract

• feature_slug: {{FEATURE_SLUG}}
• status: draft
• execution_mode: solo|hybrid|parallel

TDD Contract

Default to one bounded tdd row per AC slice. A tdd row owns RED -> GREEN -> focused VERIFY for the AC inside one write scope.

Only split into multiple workers when contracts are stable, write scopes are disjoint, and splitting reduces wall-clock time.

Task Rows

Format: AC-<MODULE>-NN | phase: <tdd|docs|explore|support|verify|review|integrate|red|green|refactor> | owner: <lead|role> | scope: <paths/modules> | command_ref: CMD-<ALIAS>|none | status: <status>.

• AC-MODULE-01 | phase: tdd | owner: tdd-slice-worker | scope: tests/... src/... | command_ref: CMD-BE-TEST | status: draft.

Worktree Notes

Record whether each AC row runs in the lead worktree or a dedicated worker worktree, plus any split-worker rationale.

Integration Notes

Record cross-team contracts, shared DTOs, route dependencies, migration ordering, fixtures, generated clients, and handoff notes.

Open Decisions

• None.

Test Plan: {{FEATURE_NAME}}

Test Plan Decision

• status: waiting_human_decision
• approved_by: none
• approved_at: none

Valid statuses: waiting_human_decision, approved, approved_with_defaults.

Proof Rows

Each row proves one AC or one local case of an AC. Use multiple rows for multiple cases; do not create global TDD IDs.

Format: AC-<MODULE>-NN | layer: <unit|integration|api|database|frontend|browser|security|regression> | case: <local case description> | red: <expected failure before behavior> | green: <same proof passes> | interaction: <user action -> feedback -> network or not applicable> | command_ref: CMD-<ALIAS>.

• AC-MODULE-01 | layer: api | case: valid request returns expected result | red: proof fails before behavior | green: same proof passes | interaction: not applicable | command_ref: CMD-BE-TEST.

Command Index

CMD-* aliases are local to this file. They are command de-duplication labels, not business traceability IDs.

Format: - CMD-<ALIAS> | command: <command> | cost: <fast|medium|slow/browser> | when: <red|green|verify|final|review-if-stale> | rerun: <policy> | expect: <evidence>.

• CMD-BE-TEST | command: make be-test | cost: medium | when: red/green/verify | rerun: affected backend changes | expect: focused pass/fail output.
• CMD-FE-BROWSER | command: npm --prefix <frontend> exec playwright -- test <spec> | cost: slow/browser | when: verify | rerun: review-if-stale | expect: clicks, inputs, network assertions, visible feedback, artifacts.

Slow/browser commands: VERIFY runs once per relevant change; REVIEW reuses evidence unless missing, failed, stale, or user requests fresh run.

Evidence Rules

• Every AC-* from spec/acceptance.md must have at least one Proof Row.
• Browser or UI interaction proof must include concrete interaction text in the Proof Row.
• Final reports must record RED, GREEN, command output, and browser evidence fields when browser proof is claimed.
• If a layer is not applicable, state not applicable in the relevant field.

Worktree Plan: {{FEATURE_NAME}}

Main Agent

• feature_slug: {{FEATURE_SLUG}}
• main_agent: first agent that activated this skill
• main_codex_runtime_id: current-thread
• main_codex_runtime_name: lead-agent
• git_skill: eliteforge-git-feature-oriented-spec | eliteforge-git-feature-oriented-lite-spec
• execution_mode: hybrid
• main_branch: unknown
• main_worktree_path: unknown
• status: draft

Repository State

• root_worktree_path: unknown
• current_branch: unknown
• selected_git_skill_verified: false

Multi-Agent Base Branch

• branch: unknown
• base_ref: unknown
• merge_strategy: merge
• conflict_owner: Main Agent

Dispatch Decisions

One row per behavior-changing task row (phase: tdd|red|green|refactor). Default hybrid decision is spawn; use solo only with explicit approval or a genuinely trivial rationale.

Agent Worktrees

One block per delegated worker. Git identity from selected git skill. Codex runtime id/name filled after spawn. Hybrid execution may have zero worker rows only when solo fallback is explicitly approved and recorded.

WT-01

• git_agent_id: {{git-agent-id}}
• subtask_name: {{subtask-name}}
• runtime_agent_type: {{resolved-codex-runtime-agent-type}}
• codex_agent_id: pending-spawn
• codex_agent_name: pending-spawn
• ac_refs: AC-MODULE-01
• tdd_phase: tdd|red|green|verify|review
• branch: {{selected-git-skill-subagent-branch}}
• worktree_path: {{selected-git-skill-subagent-worktree-path}}
• base_ref: {{selected-git-skill-multi-agent-base-branch}}
• status: draft

Branch And Path Rules

• Git skill owns branch/worktree naming; Codex runtime id/name recorded after spawn, never used to derive git names.
• One worktree + one branch per delegated worker; workers write fragments to reports/agents/; Main Agent updates canonical reports.
• Selected-git-spec main/base branch is mandatory even when no worker is spawned.
• Each behavior-changing AC task row must have a dispatch decision before implementation.
• Solo fallback may have no worker row, but requires explicit approval or a recorded docs-only/trivial rationale.
• No worker edits main worktree.

Merge Strategy

• strategy: merge delegated worker branches into selected-git-spec main/base branch after evidence review.
• integration_owner: Main Agent

Conflict Rules

• conflict_owner: Main Agent
• worker_conflict_rule: stop and report; do not rewrite another worker's scope.

Cleanup Plan

• cleanup_after_merge: pending
• preserve_until_final_validation: true

Open Decisions

• None.

Worktree Report: {{FEATURE_NAME}}

Summary

Worktree/integration result, highest-risk delta, unresolved blockers (1-2 lines).

Evidence Rows

• AC-MODULE-01 | red: not applicable | green: not applicable | command_ref: none | browser: not applicable | status: pending.

Changed Paths

• None yet.

Commands

• @ref:spec/test-plan.md#command-index: pending.

Registry

• @ref:orchestration/worktree-plan.md#agent-worktrees: pending.
• Branch: @ref:orchestration/worktree-plan.md#multi-agent-base-branch: pending.

Blockers

• None.

Database Design Reference

Use when a feature touches persistence, migrations, data ownership, tenancy, permissions, reporting, search, audit, caching, or seed data.

Decision

spec/database-design.md must have status: waiting_human_decision | approved | not_applicable.

Implementation tasks cannot begin unless status is approved or not_applicable.

Design Checklist

• Affected bounded context/module
• Table names and ownership
• New/changed columns: type, nullability, default, semantics
• Keys (PK, UK, FK), check constraints, business constraints
• Indexes and expected query patterns
• Migration file naming and ordering
• Forward/backward compatibility
• Rollback strategy or irreversible warning
• Data backfill or seed strategy
• Transaction, locking, consistency
• Tenancy, authorization, data visibility
• Audit fields, soft delete, retention, privacy
• ORM/entity/repository changes
• Fixtures and test data strategy
• Migration validation commands

Compatibility Rule

Prefer expand-and-contract migrations: 1. Add compatible structures 2. Deploy code that reads/writes old and new shape 3. Backfill data 4. Enforce constraints after data is valid 5. Remove old structures after compatibility window closes

Destructive migrations require user confirmation.

Feature Decomposition Gate

Use after an approved brainstorming spec and approved PRD, and before selecting New Feature Delivery or Feature Evolution.

Purpose

eliteforge-brainstorming may approve a broad design that covers multiple business capabilities, admin surfaces, workflow stages, or existing workspaces. eliteforge-prd-generator may then turn that into a whole-product PRD with searchable feature, page, interaction, rule, exception, and acceptance headings. eliteforge-codex-superpower must not pour either upstream artifact into one docs/features/<feature-slug>/ workspace.

The lead agent must use the approved PRD as the primary product-layer input, then map it into bounded features that can each own one feature workspace, one feature model, and one AC inventory. Read only the matching PRD slices needed for the candidate feature.

Mandatory Explorer Support

The lead agent must not perform this analysis alone.

• Before or during brainstorming, dispatch at least one read-only explorer subagent to scan repository structure, existing feature workspaces, likely dependency surfaces, and hidden constraints.
• After brainstorming approval, dispatch at least one read-only explorer subagent to prepare PRD inputs such as shared requirements, feature inventory, dependency relations, and delivery order.
• After PRD approval, dispatch at least one read-only explorer subagent to validate that product split against repository constraints and propose the bounded feature selection.
• For broad specs, multi-domain designs, or multi-feature evolution, use 2 or more explorer subagents with non-overlapping scopes such as business capability, shared platform capability, and impacted existing features.
• If subagents are unavailable, record the blocker and stop before feature doc drafting or feature reopening.

Lead Agent Responsibilities

1. Read the approved brainstorming spec, approved PRD, and current repository context. 2. Search the PRD by module, feature, page, rule, exception, and acceptance headings; do not load the whole PRD when heading slices are enough. 3. Reuse the PRD's feature inventory, shared requirements, dependency map, and implementation order whenever they are already complete and current. 4. Add only repository-specific deltas needed for bounded feature selection, workspace reuse, and sequencing. 5. Split the design into bounded business capabilities, not technical layers. 6. Produce a compact decomposition summary before any feature doc drafting or reopening. 7. Select one target feature to enter the AC-only workflow unless the user explicitly approves batch orchestration.

Persist or restate four outputs. Reuse PRD content instead of duplicating it when possible:

1. Feature Inventory

For each candidate feature, record:

• feature_slug
• feature_name
• delivery_type: new_feature or feature_evolution
• target_workspace: existing docs/features/<feature-slug>/ or new workspace
• goal: one-sentence business outcome
• in_scope: stable capability slice only
• deferred_or_out_of_scope: adjacent capability deferred to another feature
• source_prd_headings: matching Feature/Page/Interaction/Rule/Exception/Acceptance headings
• dependency_features: upstream/downstream feature dependencies
• recommended_order

2. Shared Requirement Inventory

Record reusable or common needs across features:

• shared_requirement
• why_common
• consumer_features
• delivery_decision: foundational feature now | keep in owning feature | defer extraction
• priority_reason

True shared requirements that immediately block several features should be implemented first.

3. Dependency Map

Record at least:

• feature -> depends_on -> feature
• blocking shared requirements
• current repository constraints that force sequencing
• existing feature workspaces that must evolve before or alongside a new feature

If the PRD already includes these relations, append only repository-specific deltas instead of rewriting the whole graph.

4. Recommended Implementation Order

Produce a numbered sequence with rationale:

• foundational shared requirements first
• then blocking upstream features
• then dependent product features
• then follow-up admin/polish/reporting work

Split Rules

Split when the brainstorming spec combines any of these:

• distinct actor or permission surfaces such as admin, operator, end-user, or system automation
• distinct workflow stages such as ingestion, linking, publishing, notification, or audit
• distinct page/module surfaces that could ship or validate independently
• changes that belong to different existing feature workspaces
• one capability that can be implemented and accepted without waiting for the full rest of the design

Do not split by ceremony alone:

• not backend vs frontend vs database
• not one markdown file per subsystem
• not one worker role per feature by default

One feature workspace should represent one coherent acceptance surface. If the lead cannot explain the feature outcome in 1-2 sentences without listing several independent capabilities, the split is still too broad.

Shared Capability Rule

If a reusable capability appears during decomposition:

• keep it inside the owning feature when reuse is speculative or local
• record it as an open decision when extraction may be needed later
• create a standalone foundational feature only when it has its own acceptance surface or is an immediate dependency for multiple approved features
• prioritize the foundational feature before its dependents when the dependency is real and near-term

Execution Rule

• Do not create or reopen docs/features/<feature-slug>/ workspaces until the feature inventory, shared requirement inventory, dependency map, and implementation order exist.
• Do not create one feature workspace that restates the whole brainstorming spec or whole-product PRD.
• Do not paste the whole PRD into spec/feature-spec.md; carry compact source_prd_headings and rewrite only the selected feature model.
• Do not treat backend/frontend/database layering as feature decomposition.
• If multiple bounded features remain and defaults are not already authorized, ask the user to confirm the split, shared-requirement decisions, and recommended order.
• After approval, enter references/zero-one-delivery.md or references/feature-evolution.md for one selected feature at a time.

Multi-Feature Evolution Rule

If one brainstorming spec affects several existing features:

• map one row per impacted feature workspace
• classify each row as feature_evolution or new_feature
• reopen each feature from its own earliest affected gate
• do not mutate several feature workspaces under one blended gate flow without explicit user approval

Feature Evolution Workflow

Use when an existing docs/features/<feature-slug>/ workspace must change after drafting, task planning, active implementation, or delivery.

Brainstorming Gate

Before orientation or gate reopening, activate eliteforge-brainstorming for the current change request.

• Use it to confirm why, scope boundaries, alternatives, trade-offs, and design intent before mutating existing feature docs, tasks, or reports.
• Reuse an existing approved brainstorming spec only when it still matches the requested change and current repository state.
• Do not reopen gates, rewrite docs, or change task/worktree decisions until brainstorming and PRD are approved or the user explicitly approves reuse of existing approved upstream docs.
• Before or during brainstorming, dispatch at least one read-only explorer subagent to scan impacted workspaces, sibling feature specs, shared capabilities, and likely hidden constraints.

PRD Gate

Activate eliteforge-prd-generator after the brainstorming gate passes.

• Confirm or update the searchable product definition for the current change, including background, goals, scope, feature requirements by module, page prototypes and interactions, business rules, exception/boundary cases, shared requirements, feature inventory, dependency map, recommended implementation order, and product-level acceptance.
• Keep the PRD different from brainstorming: PRD updates must add or change buildable facts under stable feature/page/rule/exception headings, not repeat option analysis.
• Reuse an existing approved PRD only when it still matches the requested change, the approved brainstorming output, and current repository reality.
• Do not reopen feature gates or rewrite downstream implementation artifacts during PRD drafting.
• After brainstorming approval, dispatch at least one read-only explorer subagent to convert brainstorming plus repository findings into PRD inputs.
• Enter Feature Impact Split only after the PRD is approved or the user explicitly approves reuse of an existing approved PRD.

Feature Impact Split

Before reopening any feature workspace, the lead agent must map the approved brainstorming spec plus approved PRD into bounded feature changes. Use references/feature-decomposition.md.

Dispatch at least one read-only explorer subagent for the decomposition pass. For broad or multi-domain changes, use 2 or more explorer subagents with non-overlapping scopes.

If the approved PRD already contains current feature inventory, shared requirement inventory, dependency map, and implementation order, reuse those sections and add only repository-specific deltas.

Search the PRD by module, feature, page, interaction, rule, exception, acceptance, shared-requirement, dependency, and order headings. Open only matching sections for each impacted feature; do not paste the whole PRD into any reopened feature workspace.

Produce a decomposition summary with one row per impacted feature:

• feature_slug
• delivery_type: feature_evolution or new_feature
• target_workspace: existing docs/features/<feature-slug>/ or new workspace
• goal
• change_surface
• dependency_features
• source_prd_headings
• recommended_order

Also produce:

• shared requirement inventory
• dependency map across affected features
• recommended implementation order with rationale

Rules:

• Do not reopen several unrelated feature workspaces as one blended evolution flow.
• If the brainstorm output covers a new capability plus several impacted existing features, split that into separate feature rows.
• Prioritize true shared requirements before dependent feature updates.
• Pause new dispatch and merges until the affected feature inventory is confirmed.
• Resume Feature Evolution for one selected feature at a time unless the user explicitly approves coordinated multi-feature execution.

Orientation And Freeze

Read orchestration/context-index.md first if present, then open only affected files, headings, and AC rows. Scan sibling feature-spec.md files for strong dependencies. If work is in progress, pause new dispatch and merges until impact analysis is confirmed. Preserve files and update in place.

Classify the change:

• requirement expansion, contraction, or clarification
• feature model or page/module surface change
• database or migration change
• API/DTO/permission/error contract change
• acceptance AC change
• proof row or command policy change
• task/worktree execution change
• documentation or evidence correction only

Record Evolution Entry

Before reopening any gate, create or append an entry in orchestration/feature-evolution-log.md:

• change_id: sequential number (1, 2, 3...)
• trigger: user_request | spec_correction | requirement_change | bug_discovery | scope_adjustment | documentation_only
• change_type: from the classification above
• gate_reopened: earliest affected New Feature Delivery phase
• diff_summary: before/after compact block
• downstream_impact: affected docs/tasks/reports
• old_evidence_status: retained | superseded | replaced | not_applicable
• user_approval: pending until confirmed

spec/feature-spec.md contains only the current feature model. Historical diffs belong in the evolution log.

Reopen Earliest Affected Gate

Run matching --spec-stage validation after each reopened gate. Run --complete-spec whenever acceptance or test plan changes. If test-plan.md changes, reset Test Plan Decision to waiting_human_decision.

AC And Evidence Migration

If an AC's meaning changes, do not silently reuse old evidence. Either keep the AC id and mark old evidence superseded when wording remains semantically compatible, or create a new AC id and mark the older AC/evidence retained, superseded, replaced, not applicable, or skipped with approval.

Task and report rows are AC-keyed. If work has not started, update rows directly. If in progress or complete, add replacement rows and keep old evidence auditable.

If active worker branches/worktrees exist, decide per worker: continue, rebase, narrow scope, replace AC scope, or mark superseded with explicit user approval. Never silently drop unintegrated changes.

Resume Delivery

If documentation-only and behavior unchanged, record why implementation/test tasks are not applicable, refresh context-index.md, then run affected validation. Otherwise resume from the earliest affected phase: task breakdown, mandatory base branch provisioning, selective worker worktree provisioning, AC TDD slice execution, verify, or final review.

Final review for evolution compares changed AC rows, proof rows, command policy, task rows, worker evidence, reports, and residual risks.

Git Worktree And Multi-Agent Orchestration

Use this reference before dispatching subagents. Read the selected eliteforge-git-feature-oriented-* skill first for branch/worktree naming rules.

Select The Git Skill

Select exactly one git skill based on project declaration:

• eliteforge-git-feature-oriented-spec (full spec)
• eliteforge-git-feature-oriented-lite-spec (lite spec)

If undeclared, stop and ask user. The selected skill provides: main agent branch/path, multi-agent base branch, subagent branch/path, agentId, subtask naming, merge direction, cleanup, commit, and MR/PR rules.

Do not use feature-skill-defined names such as eliteforge/integration/* or eliteforge/<unique-agent-id>/*.

Ownership

Main Agent: planning, gates, git-spec selection, worktree creation, dispatch, integration, conflict resolution, canonical reports, validation, user communication.

Each subagent: exactly one git worktree + one selected-git-spec branch. One branch = one worktree (no sharing).

Codex runtime identity is separate. After spawn_agent, update orchestration/worktree-plan.md with returned runtime id/name. Use runtime id for wait_agent/send_input; use selected-git-skill agentId/subtaskName for branches, paths, and report filenames.

Creation Commands

Scripts belong to the active skill directory. Set skill_dir to the absolute path of eliteforge-codex-superpower:

git switch -c "<selected-git-skill-multi-agent-base-branch>"  # only when no base exists
"$skill_dir/scripts/create_agent_worktree.sh" "<selected-git-skill-subagent-branch>" "<selected-git-skill-subagent-worktree-path>" "<base-ref>"

Dispatch Order

explore/support -> RED -> integrate RED into base -> GREEN -> integrate GREEN into base -> refactor/verify -> review

Do not run dependent GREEN before RED is integrated or legacy-coverage exception is documented.

After RED integration, dispatch backend + frontend GREEN as one parallel batch when:

• Both depend on same integrated RED base
• Write scopes are disjoint
• Shared API/DTO contracts are stable in base
• Neither depends on pending database/schema or generated-client output

If a frontend row depends on generated client or backend depends on frontend-visible contract changes, integrate shared artifact first, then dispatch independent rows in parallel.

Dispatch Rules

• Give every subagent: absolute worktree path (from git skill), branch name, task IDs.
• Tell every subagent: Codex runtime name may differ from agentId/subtaskName; do not edit main worktree; write only in assigned scope; write fragment to reports/agents/<task-id>-<agentId>-<subtaskName>.md.
• Do not dispatch GREEN until RED tests are in base branch.
• Do not dispatch VERIFY until GREEN branches are integrated.
• Avoid parallel workers that may edit same files or tightly coupled modules.

Integration

Inspect worker branch before integration:

git -C <worker-worktree> status --short
git -C <worker-worktree> diff --stat <base-ref>...HEAD
git -C <worker-worktree> diff --name-only <base-ref>...HEAD

Preferred merge:

git switch "<selected-git-skill-multi-agent-base-branch>"
git merge --no-ff "<selected-git-skill-subagent-branch>"

Patch apply (when merge unavailable):

git -C <worker-worktree> diff --binary <base-ref> > <patch-file>
git apply --index <patch-file>

After integration, rerun the validation command from the task row or approved test scope.

Conflict Rules

• Main Agent resolves conflicts; workers do not resolve other workers' conflicts.
• If two workers changed the same file unexpectedly, stop parallel dispatch for that file family and record in orchestration/integration-log.md.
• Never discard worker changes without recording reason.

Cleanup

Optional until final acceptance:

git worktree remove <worktree-path> && git branch -d "<selected-git-skill-subagent-branch>"

Do not delete branches/worktrees with unintegrated changes.

Subagent Orchestration Contract

Execution Modes

• solo: explicit fallback only. Lead owns docs, coding, validation, and final evidence for a small AC slice after the selected-git-spec main/base branch exists.
• hybrid: default. Lead owns docs and integration; one tdd-slice-worker handles behavior-changing AC slices unless the user approves solo or the slice is documentation-only/trivial.
• parallel: use multiple workers only after contracts are stable and write scopes are disjoint.

Default rule: selected-git-spec main/base branch is mandatory, then one bounded AC slice per worker. Split backend/frontend/database workers only when the same stable AC proof fans out into independent implementation scopes.

Dispatch Decision Tree

Record one orchestration/worktree-plan.md#Dispatch Decisions row for every behavior-changing task row (phase: tdd|red|green|refactor):

Behavior-changing AC task row → Is it docs-only/explore/support/review/verify-only?
    ├─ Yes → no implementation spawn
    │
    └─ No → Did user explicitly approve solo, or is the slice genuinely trivial?
        ├─ Yes → solo
        │        Lead executes on selected-git-spec main/base branch and records rationale
        │
        └─ No → Are subagents or selected-git worktrees unavailable?
            ├─ Yes → blocked
            │        Record blocker and stop for user decision
            │
            └─ No → Are contracts stable, write scopes isolated, and fan-out faster?
                ├─ Yes → parallel
                │        Spawn backend/frontend/database workers only for real fan-out
                │
                └─ No → spawn
                         Default hybrid path: one bounded AC implementation worker
                         owns RED -> GREEN -> focused VERIFY -> evidence

Grouping rule: one spawned worker may own multiple adjacent AC rows only when they share the same write scope, command aliases, and interaction surface. Otherwise keep one bounded AC slice per worker.

Coding Agent Selection

Default: worker agent type. Environment variables are Codex runtime spawn_agent.agent_type values, not workflow role names:

• ELITEFORGE_SKILL_SUPERPOWER_CODING_AGENT: overrides coding subagents such as backend/frontend/database workers.
• ELITEFORGE_SKILL_SUPERPOWER_TDD_AGENT: overrides specifically for bounded AC TDD slice workers.
• ELITEFORGE_SKILL_SUPERPOWER_REVIEWER_AGENT: overrides verify and review workers.

Resolution: 1. TDD slice workers: ELITEFORGE_SKILL_SUPERPOWER_TDD_AGENT -> worker 2. Backend/frontend/database: ELITEFORGE_SKILL_SUPERPOWER_CODING_AGENT -> worker 3. Verify/review: ELITEFORGE_SKILL_SUPERPOWER_REVIEWER_AGENT -> worker 4. Explorer: always explorer

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

Spawn call contract: before every non-explorer spawn, record runtime_agent_type in orchestration/worktree-plan.md, then pass that exact value as spawn_agent.agent_type. When a resolved value is coder-spark, spawn with agent_type: "coder-spark". Do not omit agent_type, do not rely on default spawn behavior, and do not use fork_context: true with explicit agent_type. Workflow roles such as tdd-slice-worker, backend-worker, frontend-worker, database-worker, and review-worker are prompt/report/worktree roles only; never pass them as spawn_agent.agent_type.

Main Agent

Owns: user communication, AC-only docs, execution-mode choice, git-spec resolution, mandatory base branch setup, selective worker worktree setup, dispatch, integration, final validation, completion claims.

The lead agent is a synthesizer, not the only reader. Use read-only explorer subagents to reduce context pressure before behavior-changing drafting starts.

• During brainstorming preparation, dispatch at least one explorer to scan repository structure, sibling feature workspaces, shared capabilities, and hidden constraints.
• After brainstorming approval, dispatch at least one explorer to prepare PRD inputs such as background, goals, scope, module-level features, page interactions, business rules, exception boundaries, shared requirements, feature inventory, dependency map, and recommended implementation order.
• After PRD approval, dispatch at least one explorer to validate the PRD against repository constraints, search relevant PRD headings, propose the bounded feature selection, and confirm dependency/order deltas.
• For broad specs or multi-feature impact, use 2 or more explorer subagents with disjoint scopes.
• If mandatory explorer support is unavailable, mark the workflow blocked before PRD drafting, feature doc drafting, or feature reopening.

• Generate or refresh orchestration/context-index.md before dispatch/review
• Read context index first, then only relevant AC rows and command aliases
• Create or verify the selected-git-spec main/base branch before behavior-changing execution
• Fill Dispatch Decisions before implementation; do not silently omit spawn for behavior-changing AC rows
• Dispatch one tdd-slice-worker for behavior-changing AC slices by default when tool support is available
• Use solo only with explicit user approval or a recorded docs-only/trivial rationale
• Create one worktree + one branch per delegated worker from the selected git skill
• Record each delegated worker runtime_agent_type before spawn
• After spawn, update orchestration/worktree-plan.md with runtime id and name
• Do not use fork_context: true when passing an explicit agent_type; provide a focused prompt with only required context
• Avoid parallel workers editing the same files or tightly coupled modules
• Preserve fresh VERIFY evidence during review

Worker Prompt Template

All delegated workers receive this identity header:

You are a <role> worker for feature <feature-slug>.
Worktree: <path> (resolved from selected git skill).
Branch: <branch>.
Agent id: <agentId>. Subtask name: <subtaskName> (from selected git skill).
Codex runtime name may differ from Agent id. Use Agent id and Subtask name for branches, paths, report filenames, and integration records.

Worker prompts must include:

• assigned AC rows from spec/acceptance.md
• matching proof rows and CMD-* aliases from spec/test-plan.md
• write scope and command expectations
• report row requirements
• TDD rules from references/tdd-workflow.md

Do not paste whole spec/, tasks/, or reports/.

External Browser Skill Use

When a browser/testing skill such as webapp-testing is used, treat it as a Playwright capability provider only. Do not edit the external skill and do not inherit any legacy EliteForge document contract from it.

Browser worker prompts must explicitly override the output contract:

• Use only assigned AC-* rows as traceability IDs.
• Use only CMD-* aliases from spec/test-plan.md.
• Write evidence into reports/*.md rows keyed by AC-*.
• Include clicks, inputs, network assertions, visible feedback, and artifacts.
• Do not create test-scope.md, TDD-*, TASK-*, INT-*, EV-*, or BVE-* outputs.

Command Cost Rules

• fast: unit, type, lint, focused parser. VERIFY and REVIEW may run.
• medium: build, integration, local service, database, container-light. VERIFY runs; REVIEW reruns only when evidence is missing or affected files changed.
• slow/browser: Playwright, Cypress, browser runtime, full E2E, container-heavy. VERIFY runs at most once per relevant change. REVIEW reuses evidence unless missing, failed, stale, or user requests fresh run.

Browser evidence must include clicks, inputs, network assertions, visible feedback, and artifacts. smoke passed is not evidence.

Running, Stalled, Or Empty Workers

Do not estimate stall from wall-clock alone. While running -> in_progress.

Observable stall conditions:

• Platform reports failed, cancelled, disconnected, or timed out
• Completes with no changed files, no report fragment, and no RED/GREEN/VERIFY evidence
• User asks to stop or replace
• Explicit recorded timebox reached and user approved interruption

After empty completion or approved interruption -> re-dispatch a narrower prompt once. If still no evidence -> mark blocked, record in reports/worktree-plan/integration-log, do not integrate the empty branch, and do not dispatch dependent rows.

Review

Review after reports exist. Cover database alignment, AC proof rows, command policy, worktree integration, changed paths, browser evidence detail, evidence freshness, and final status recommendation.

Review must not rerun slow/browser commands when passing VERIFY evidence is still fresh. Rerun only when:

• no passing VERIFY evidence exists
• prior evidence failed or was marked stale
• files changed in the covered route/page/component/auth flow/API fixture/browser setup
• user requested fresh run

When skipping rerun, record the reused evidence link and freshness rationale in the review report.

TDD Workflow Reference

Core Rule

For every automated acceptance criterion: RED (proof exists and fails for expected missing behavior) -> GREEN (smallest production change makes the same proof pass) -> VERIFY (integration/browser/regression evidence remains passing).

Manual-only criteria are allowed only when automation is impractical and approved in spec/test-plan.md.

AC Proof Granularity

AC-* is the only global business traceability ID. TDD cases are local proof rows under an AC, not global IDs.

Split proof rows when:

• one RED failure would prove multiple independent missing behaviors
• happy, error, boundary, permission, or integration branches are mixed
• browser interaction and API/database proof need separate commands
• GREEN would require unrelated write scopes

Use multiple proof rows for one AC when needed; keep each row compact with case, layer, red, green, optional interaction, and command_ref.

Layer Defaults

• domain rules: unit tests
• validation: unit + API/controller tests when externally visible
• persistence: integration tests with project-standard DB setup
• migrations: migration/schema validation or repository tests
• permissions: service/API tests for allowed + denied
• API contract: controller/API tests + DTO serialization checks
• frontend: component/page tests
• full journey: browser/runtime test when cross-layer behavior matters

Browser/runtime commands are expensive. Record as cost: slow/browser in test-plan.md#command-index. Run once per relevant change; REVIEW inspects evidence instead of rerunning.

RED Evidence Quality

Valid only when:

• command executes the proof row's test or browser proof
• failure is expected missing behavior, not syntax/dependency/environment noise
• maps to an AC id and command alias
• is recorded before dependent production implementation

GREEN Evidence Quality

Valid only when:

• same proof that produced RED now passes
• production changes stay inside assigned write scope
• tests are not weakened
• changed paths, branch/worktree or lead-local note, command alias, and AC id are recorded

Browser Evidence Quality

Browser evidence is valid only when the report row records:

• clicks
• inputs
• network assertions
• visible feedback
• artifacts such as trace, screenshot, or report path

smoke passed is never sufficient.

Database TDD Notes

Test before implementation when practical:

• migration/schema assertion fails before table/column/index exists
• repository/integration test fails before persistence behavior exists
• compatibility test fails before old/new behavior is supported
• fixture/seed-data test when deterministic data is required

If migration cannot be tested directly, record tooling output, schema inspection, or dry-run evidence.

0-1 Feature Delivery Workflow

Use this reference for new features with no existing docs/features/<feature-slug>/ workspace.

Phase 1: Brainstorming Gate

Activate eliteforge-brainstorming before any feature doc drafting.

• Use it to converge why, scope boundaries, alternatives, trade-offs, and design decisions before writing spec/*.md.
• Reuse an existing approved brainstorming spec only when it still matches the current request and repository state.
• Do not create tasks, worktree plans, or reports during brainstorming.
• Before or during brainstorming, dispatch at least one read-only explorer subagent to scan repository structure, sibling feature workspaces, likely shared capabilities, and hidden constraints.
• Enter Phase 2 only after brainstorming is approved or the user explicitly approves reuse of an existing approved brainstorming spec.

Phase 2: PRD Gate

Activate eliteforge-prd-generator after the brainstorming gate passes.

• Turn the approved brainstorming output into a searchable PRD with background, goals, scope, feature requirements by module, page prototypes and interactions, business rules, exception/boundary cases, shared requirements, feature inventory, dependency map, recommended implementation order, and product-level acceptance.
• Keep the PRD different from brainstorming: do not repeat alternative analysis except where it changes product scope; write buildable facts under stable headings such as Feature:, Page:, Interaction:, Rule:, Exception:, and Acceptance:.
• Reuse an existing approved PRD only when it still matches the current request, the approved brainstorming output, and repository reality.
• Do not create feature docs, tasks, worktree plans, or reports during PRD drafting.
• After brainstorming approval, dispatch at least one read-only explorer subagent to convert brainstorming plus repository findings into PRD inputs.
• For broad or multi-domain designs, use 2 or more explorer subagents with non-overlapping scopes such as user workflow, shared platform capability, and existing workspace impact.
• Enter Phase 3 only after the PRD is approved or the user explicitly approves reuse of an existing approved PRD.

Phase 3: Feature Decomposition And Selection

Before creating docs/features/<feature-slug>/, the lead agent must read the approved brainstorming spec and approved PRD, then select one bounded feature. Use references/feature-decomposition.md.

Dispatch at least one read-only explorer subagent for the selection pass. For broad or multi-domain designs, use 2 or more explorer subagents with non-overlapping scopes.

Search the PRD by heading keywords before reading details. Open only matching module, feature, page, interaction, rule, exception, acceptance, shared-requirement, dependency, and order sections for the selected feature. Do not load or paste the whole PRD into the feature workspace.

If the approved PRD already contains complete feature inventory, shared requirement inventory, dependency map, and implementation order, reuse those sections as the primary product input and add only repository-specific deltas needed for workspace selection.

Produce a compact decomposition summary that includes:

Feature Inventory

• feature_slug
• feature_name
• delivery_type: new_feature or feature_evolution
• goal
• in_scope
• deferred_or_out_of_scope
• dependency_features
• source_prd_headings
• recommended_order

Shared Requirement Inventory

• shared_requirement
• why_common
• consumer_features
• delivery_decision
• priority_reason

Dependency Map

• feature -> depends_on -> feature
• blocking shared requirements
• existing feature workspace dependencies

Recommended Implementation Order

• numbered implementation sequence
• rationale for why each item comes before the next

Rules:

• Do not create one feature workspace that restates the whole brainstorming spec.
• Do not create one feature workspace that restates the whole product PRD.
• Do not split only by backend/frontend/database implementation layers.
• Prioritize true shared requirements before dependent features.
• Create or reopen docs for one selected feature at a time unless the user explicitly approves batch orchestration.
• If multiple features remain and defaults are not already authorized, stop for user confirmation before entering Phase 4.

Phase 4: Repository Discovery And Feature Model

Draft from user requirement, repository findings, sibling feature specs, and best practices. Each gate creates or updates only its listed file(s), runs validation, and stops for user confirmation unless defaults are authorized.

Draft progressively:

1. spec/feature-spec.md 2. spec/database-design.md 3. spec/api-contract.md 4. spec/acceptance.md 5. spec/test-plan.md

Do not create tasks, worktree plans, or reports before the complete spec gate passes. orchestration/context-index.md is allowed as a generated navigation artifact after the selected feature workspace exists.

After each gated draft, ask at most 3-5 focused questions:

I drafted <current-file> with these assumptions:
1. ...
Confirm or correct these blocking decisions:
1. ...

Phase 5: Complete Spec Gate

spec/test-plan.md must have Test Plan Decision set to waiting_human_decision, approved, or approved_with_defaults. Task execution cannot begin until it is approved or approved_with_defaults.

Run:

"$skill_dir/scripts/validate_feature_docs.py" <feature-dir> --phase spec --complete-spec --no-downstream-artifacts

Stop for confirmation. Only begin task breakdown when the complete spec gate passes.

Phase 6: AC Task Breakdown

Create task files in tasks/. Each row is keyed by AC-*:

AC-<MODULE>-NN | phase: <tdd|docs|explore|support|verify|review|integrate|red|green|refactor> | owner: <role> | scope: <paths/modules> | command_ref: CMD-<ALIAS>|none | status: <status>.

Default planning:

• one bounded tdd row per AC slice
• split into backend/frontend/database workers only when contracts are stable, write scopes are disjoint, and splitting reduces wall-clock time
• verify/review rows after integration evidence exists
• task files do not define TASK-* ids and do not restate proof rows

Run:

"$skill_dir/scripts/validate_feature_docs.py" <feature-dir> --phase tasks

Set task status to waiting_human_decision and stop before implementation unless execution is approved.

Phase 7: Context Index And Mandatory Base Branch

Generate or refresh:

"$skill_dir/scripts/render_context_index.py" <feature-dir>

Read orchestration/context-index.md before dispatch. Open only relevant files, headings, and AC rows.

Read the selected eliteforge-git-feature-oriented-* skill, then references/git-worktree-orchestration.md. Create or verify the selected-git-spec main/base branch before any behavior-changing execution. This is mandatory for solo, hybrid, and parallel.

Worker worktrees are selective. If explicit solo fallback is approved, skip only the worker worktree rows, not the selected-git-spec main/base branch. Record the solo rationale in task rows, worktree-plan.md, integration log, and reports.

Agent selection:

• TDD slice workers: ELITEFORGE_SKILL_SUPERPOWER_TDD_AGENT if set, else worker
• Backend, frontend, database: ELITEFORGE_SKILL_SUPERPOWER_CODING_AGENT if set, else worker
• Verify, review: ELITEFORGE_SKILL_SUPERPOWER_REVIEWER_AGENT if set, else worker
• If a configured value is not a valid Codex runtime type such as worker, coder, coder-spark, or explorer, stop before spawning and record the invalid value; fallback to worker applies only when no configured value is set

Run after base branch/worktree-plan provisioning:

"$skill_dir/scripts/validate_feature_docs.py" <feature-dir> --phase worktrees

Phase 8: AC TDD Slice Execution

Default execution unit: one bounded AC slice.

Before implementation, fill orchestration/worktree-plan.md#Dispatch Decisions for every behavior-changing task row (phase: tdd|red|green|refactor):

Spawn call contract: before every non-explorer worker spawn, record runtime_agent_type in the worker block, then call spawn_agent with that exact value as agent_type. Do not omit agent_type, do not rely on default spawn behavior, and do not use fork_context: true with explicit agent_type.

AC task row → Is it docs-only/explore/support/review/verify-only?
    ├─ Yes → no implementation spawn
    │
    └─ No → Is solo explicitly approved or genuinely trivial?
        ├─ Yes → solo with recorded rationale
        │
        └─ No → Are subagents/worktrees unavailable?
            ├─ Yes → blocked and stop for user decision
            │
            └─ No → Can stable contracts + isolated write scopes reduce wall-clock?
                ├─ Yes → parallel fan-out
                └─ No → spawn one bounded AC implementation worker

Do not silently run behavior-changing hybrid work without a spawn decision row. One spawned worker may cover multiple adjacent AC rows only when they share the same write scope, command aliases, and interaction surface.

Valid AC slice evidence:

• AC id
• changed paths
• command alias and actual command output
• RED failure summary and why it proves missing behavior
• GREEN pass summary with the same proof
• focused VERIFY evidence when relevant
• browser evidence fields when browser proof is claimed
• worktree path or explicit lead-local execution note

If a browser/testing skill such as webapp-testing is used, use it only for Playwright technique, server lifecycle, selector discovery, screenshots, traces, and logs. The lead must still provide the AC-only prompt contract and require reports/*.md rows keyed by AC-*; do not follow any external legacy contract that asks for test-scope.md, global TDD-*, TASK-*, INT-*, EV-*, or BVE-* IDs.

Default hybrid behavior is to dispatch one tdd-slice-worker for behavior-changing AC slices when tool support is available. Lead may execute a bounded slice locally only when the user approves solo fallback or the task is documentation-only/trivial, and only from the selected-git-spec main/base branch.

Phase 9: Optional Parallel Fan-Out

Split into backend/frontend/database workers only when all are true:

• the AC and proof row are stable
• API/database contracts are stable enough to avoid repeated rework
• write scopes are disjoint
• splitting materially reduces wall-clock time

Lead integrates branches, resolves conflicts inside lead-owned scope, reruns affected validation, and updates reports by AC.

Phase 10: Verify, Review, And Final Evidence

Lead creates or updates reports:

"$skill_dir/scripts/render_reports.py" <feature-dir>
"$skill_dir/scripts/render_context_index.py" <feature-dir>

Reports keep only AC-keyed evidence rows, changed paths, commands, blockers, and conclusions. Final review compares implementation evidence against acceptance, proof rows, command policy, database design, and worktree evidence.

Final review is evidence review, not full regression. Spot checks with fast commands are fine. Do not rerun slow/browser commands when fresh VERIFY evidence already exists; reuse it unless stale, missing, failed, or explicitly requested.

Browser evidence must list actual clicks, inputs, network assertions, visible feedback, and artifacts. smoke passed is not acceptable.

Run:

"$skill_dir/scripts/validate_feature_docs.py" <feature-dir> --phase final

No completion while final validation fails, unresolved blockers remain, an AC lacks proof/task/evidence rows, or claimed UI behavior lacks concrete browser evidence.