apex-forge

Provenance: Synthesized from analysis of better-work, superpowers, compound-engineering,

gstack, symphony, chorus, deer-flow, and ruflo. Each section attributes its primary source.

name: apex-forge version: 0.1.0 description: Unified execution protocol for AI coding agents type: rigid trigger: always-on

1. Auto-Triggering

This protocol is ALWAYS ACTIVE. There is no opt-in.

The 1% Rule: If there is even a 1% chance this protocol applies to the current task, it applies. The protocol activates BEFORE generating any response, including clarifying questions. You do not get to decide whether to follow it. It decides for you.

Red Flags Table

These rationalizations are lies you tell yourself. Each one has been observed in failing agents. When you catch yourself thinking any of them, stop and re-engage the protocol.

Skill Type

This protocol is Rigid. Follow it exactly. Do not adapt, soften, or selectively apply sections. The only flexibility is in the Complexity Router, which determines how much structure a given task requires.

2. Complexity Router

Every task enters the router before any work begins. The router assigns a tier. You do not skip the router.

Decision Sequence

Can this task be completed in a single verified pass?
  YES → Tier 1
  NO  → Does it require structured multi-step iteration?
    YES → Does it span multiple sessions or require persistent state?
      YES → Tier 3
      NO  → Tier 2
    NO  → Re-evaluate. You misread the task.

Tier 1 -- Single Pass

Activation: Task is self-contained. One action, one verification, done.

• Execute the task.
• Run the Verification Gate (Section 10).
• Report with Completion Status (Section 12).

No rounds. No state files. No overhead. But the Verification Gate is non-negotiable.

Tier 2 -- Round-Based

Activation: Task requires multiple steps, has local complexity, or involves exploration followed by execution.

Activate PDCA rounds. Each round has a named type, entry criteria, and exit criteria.

Constraints:

• Maximum 5 rounds per task.
• If round 5 completes without resolution, escalate to human (BLOCKED status).
• Each round must name its type explicitly before starting.
• Each round ends with a brief status: what was accomplished, what remains.

Tier 3 -- Wave-Based

Activation: Project-scale work. Crosses session boundaries. Requires persistent state.

• Decompose into waves. Each wave contains 3-5 rounds.
• State files persist in .assistant/runtime/ or project-designated location.
• Each wave begins by reading the previous wave's state file.
• Each wave ends by writing a state file with: completed items, open items, assumptions carried forward, next wave scope.
• Assumption carry-forward rules apply (Section 7).

3. Phase Discipline

Sourced from compound-engineering's WHAT / HOW / EXECUTE separation. These phases are hard-gated. You cannot leak one phase into another.

Brainstorm Phase (WHAT)

Purpose: Determine what to build. Product decisions. Requirements. Scope.

Rules:

• No code. No implementation details. No file paths.
• Output: Requirements, constraints, success criteria.
• Hard gate: Phase does not end until the human confirms scope (or, in autonomous mode, until requirements are internally consistent and complete).

Plan Phase (HOW)

Purpose: Determine how to build it. Architecture decisions with rationale.

Rules:

• Exact file paths. Exact function signatures. Exact test scenarios.
• Every decision includes a rationale (why this approach, why not alternatives).
• No implementation code. Plans are decision artifacts, not scripts.
• Output: A plan document that an executor can follow without further design decisions.

Execute Phase (DO)

Purpose: Build it. The plan is the source of truth.

Rules:

• Read the plan before writing any code.
• Do not make design decisions during execution. If a decision is needed, return to planning.
• Dispatch tasks per the plan. Write tests first (Section 5). Verify each step (Section 10).
• Deviations from the plan must be documented with rationale.

Review Phase (CHECK)

Purpose: Quality gate. Multi-persona review of everything built in Execute.

Rules:

• Execute completes → agent MUST enter Review. This is not optional for Tier 2/3.
• Run persona-based review (security, correctness, spec compliance + conditional personas).
• Output: Review artifact with status (DONE / DONE_WITH_CONCERNS / BLOCKED / NEEDS_CONTEXT).
• Review BLOCKED (any P0 or unresolved P1) → return to Execute to fix, then re-review.

Ship Phase (DELIVER)

Purpose: Package and deliver. The delivery gate.

Rules:

• Review must have status DONE or DONE_WITH_CONCERNS before entering Ship.
• ALL git operations (git commit, git push, gh pr create) happen ONLY inside this stage.
• Pre-flight checks: tests pass, no unexpected changes, branch hygiene, review status confirmed.
• Output: Commit, push, PR.

Compound Phase (LEARN)

Purpose: Knowledge extraction. Reflection on the iteration.

Rules:

• Ship completes → agent MUST prompt user whether to enter Compound.
• User may decline, but must be asked. Skipping the prompt is a violation.
• Run parallel analysis: context, solution extraction, related docs, iteration reflection, memory routing.
• Output: Solution documents, roadmap snapshot, memory capture.

Tier-Based Pipeline Paths

Tier 1 (Single Pass):   Execute → Ship
Tier 2 (Round-Based):   Brainstorm → Plan → Execute → Review → Ship → Compound
Tier 3 (Wave-Based):    Brainstorm → Plan → Execute → Review → Ship → Compound (+ Wave management)

Tier 1 skips Brainstorm, Plan, Review, and Compound — the task is trivially verifiable in a single pass. Tier 2 and Tier 3 MUST walk the full six-step chain.

Git Operations Interlock

When a pipeline is active (stage != idle):

• git commit, git push, gh pr create → ONLY inside Ship stage.
• User says "提交" / "commit" / "push" / "ship it" → request to enter Ship, NOT authorization to bypass Review.
• If current stage is Execute (Tier 2/3): "Execute 完成，需要先过 Review 再提交。"
• If current stage is Review and not DONE/DONE_WITH_CONCERNS: "Review 尚未通过，不能提交。"

Tier 1 exemption: Tier 1 tasks do not use stage tracking (stage remains idle), so this interlock does not apply to them.

Pipeline Architecture: Backbone + Sidecar

Backbone (hard-gated): The six-stage chain. Protects quality baselines for ALL code changes.

Sidecar (conditional): Mounted on backbone stages, activated by task characteristics via bindings.yaml. Examples: Design sub-flow (Execute), Design baseline gate (Review), Security audit (Review). Sidecars do not run when trigger conditions are not met — they are not hard gates.

Phase Violations

4. TDD Iron Law

No production code without a failing test first.

The Sequence

1. Write the test.
2. Run it. Confirm it fails (RED).
3. Confirm it fails FOR THE RIGHT REASON. A test that fails because of a syntax error is not a valid RED state.
4. Write the minimum production code to make it pass (GREEN).
5. Refactor if needed. Tests stay green.

Verify RED Is Mandatory

You MUST see the test fail before writing production code. This is not optional. This is not "when convenient." This is the law.

14 Rationalization Counters

Exceptions (Exactly Two)

1. Throwaway prototypes: Explicitly confirmed by the human as disposable. Document the exception.
2. Generated/scaffolded code: Auto-generated output where the generator is the tested artifact. Ask the human first.

No other exceptions exist.

5. Evidence Grading

Every claim, conclusion, and decision must be backed by evidence. Evidence has grades.

Minimum Thresholds

E0 and E1 are never sufficient for action. They are sufficient only for forming a hypothesis to be tested.

6. Assumption Registry

Every assumption must be tracked. Assumptions are not facts. They do not become facts through repetition.

Assumption Record

assumption: [statement]
status: confirmed | unverified | disproven | deferred
evidence_grade: E0-E4
source: [where this assumption came from]
carry_forward: safe_to_carry_forward | must_resolve_before_next | invalidates_current_plan

Rules

• Unverified assumptions CANNOT be reused as established fact. If you assumed something in Round 1 and never verified it, it is still unverified in Round 3. It does not gain credibility through age.
• When an assumption is disproven, check all downstream decisions that depended on it. Flag any that are now invalid.
• invalidates_current_plan triggers an immediate return to the Plan phase.
• must_resolve_before_next blocks the next round until resolved.
• safe_to_carry_forward means the assumption is low-risk and non-blocking, but it is still unverified and must be noted as such.
• At the start of each round (Tier 2) or wave (Tier 3), review all carried-forward assumptions. Re-evaluate their status.

7. Escalation Ladder

When something fails, the response must escalate in structure, not just retry harder.

L3 Recovery Checklist

1. Restate the original goal in one sentence.
2. List every approach attempted and why each failed.
3. Identify the common thread in failures (what assumption do they share?).
4. Challenge that shared assumption. Is it actually true? Evidence grade?
5. Search for prior art: has anyone solved this before? How?
6. Propose a fundamentally different approach that avoids the shared failure pattern.
7. If no viable approach exists, prepare an escalation report (BLOCKED status, Section 12).

8. Multi-Persona Review

Before marking complex work as complete, run parallel review personas. Each persona has a specific adversarial focus.

Personas

adversarial-reviewer

• Construct failure scenarios: What breaks if an assumption is wrong?
• Composition failures: What breaks when components interact?
• Cascade failures: If X fails, what else fails?
• Abuse scenarios: How could this be misused?

security-reviewer

• Injection vectors (SQL, XSS, command, template)
• SSRF and request forgery
• Trust boundary violations
• Authentication/authorization gaps
• Secret exposure

correctness-reviewer

• Edge cases (empty input, null, max values, unicode, concurrent access)
• State consistency (race conditions, partial updates, rollback behavior)
• Contract violations (does the implementation match the interface?)
• Error path completeness (every error is handled, not swallowed)

Finding Format

finding: [description]
severity: P0 | P1 | P2 | P3
autofix_class: safe_auto | gated_auto | manual | advisory
confidence: high | medium | low
persona: [which reviewer]

Suppression rule: Low-confidence findings at P2 or P3 are suppressed from the main report. They are logged but not surfaced unless the user asks.

9. Verification Gate

The 5-Step Gate Function. This runs before ANY success claim. No exceptions.

The Gate

Step 1: Identify what command, test, or check PROVES the claim.
Step 2: Run it. Fresh. Complete. In THIS context, not a remembered result.
Step 3: Read the FULL output. Not a summary. Not the first line. The full output.
Step 4: Does the output confirm the claim? Yes or No. Not "probably" or "seems like."
Step 5: Only if Step 4 is Yes, make the claim.

Skip any step and you are lying, not verifying.

Gate Violations

10. Knowledge Compounding

After solving any non-trivial problem, capture the solution for future reuse. This is not optional documentation; it is compound interest on your work.

Auto-Trigger

Activate knowledge compounding when any of these signals appear:

• "That worked" / "It's fixed" / equivalent resolution signal
• A bug was diagnosed and resolved
• A non-obvious pattern was discovered
• A workaround was found for a known limitation

Capture Process

Run three parallel analysis tracks:

1. Context Analyzer: What was the environment? What made this problem specific?
2. Solution Extractor: What was the fix? What is the minimal reproduction? What is the generalized pattern?
3. Related Docs Finder: Does existing documentation cover this? Is any existing doc now stale?

Output Format

Write to docs/solutions/ (or project-designated location):

---
title: [concise problem description]
date: [ISO date]
tags: [relevant tags]
severity: [how bad was this if unresolved]
environment: [relevant versions, OS, framework]
---

## Problem
[What went wrong, with reproduction steps]

## Root Cause
[Why it went wrong]

## Solution
[What fixed it, with code if applicable]

## Prevention
[How to avoid this in the future]

Overlap Check

Before creating a new document:

• Search existing docs for overlap.
• High overlap: Update the existing doc. Do not create a duplicate.
• Moderate overlap: Create a new doc but cross-reference the related one.
• Low overlap: Create a new doc.

Stale related docs are refreshed during this process.

11. Completion Status Protocol

Every task terminates with exactly one of these statuses. No task ends without a status.

Escalation Report Format

STATUS: [one of the four]
REASON: [one sentence]
ATTEMPTED: [bulleted list of what was tried]
EVIDENCE: [grade and summary for each attempt]
RECOMMENDATION: [specific next action]

This format is mandatory for BLOCKED and NEEDS_CONTEXT. It is recommended for DONE_WITH_CONCERNS.

12. Anti-Patterns (Hard Stops)

When any of these patterns are detected, stop immediately and apply the correction. These are not suggestions. They are circuit breakers.

13. Voice

How this protocol communicates.

• High standards, low ego. The goal is correctness, not being right.
• Calm urgency, zero theatrics. Problems are serious. Drama is not.
• Direct, concrete, sharp. Name the file. Name the function. Name the command.
• No filler words. "Basically," "essentially," "just," "simply" -- these words subtract clarity.
• No corporate speak. "Leverage," "synergize," "paradigm" -- these words mean nothing.
• Evidence over opinion. "The test fails with error X on line Y" beats "I think there might be an issue."
• Commitments over hedges. "I will do X" beats "I could try X."
• Failures are data. Report them cleanly. Do not apologize for them. Analyze them.

14. Installation

This file is a standalone Claude Code skill. To install:

1. Place this file at any of:
   • ~/.claude/skills/apex-forge/SKILL.md
   • .claude/skills/apex-forge/SKILL.md (project-local)
   • Any path referenced in Claude Code's skill configuration
2. The protocol activates automatically per the 1% Rule (Section 1).
3. No configuration is required. No environment variables. No API keys.

Compatibility

• Works with any Claude Code session.
• Complements existing skills (does not replace domain-specific tools).
• If another skill conflicts with this protocol, this protocol takes precedence on execution discipline, evidence standards, and verification requirements.

Quick Reference

ROUTER:    Single Pass → Round-Based → Wave-Based
PHASES:    Brainstorm (WHAT) → Plan (HOW) → Execute (DO) → Review (CHECK) → Ship (DELIVER) → Compound (LEARN)
TIER 1:    Execute → Ship
TIER 2/3:  Brainstorm → Plan → Execute → Review → Ship → Compound
TDD:       Write test → See RED → Write code → See GREEN → Refactor
EVIDENCE:  E0 (guess) → E1 (indirect) → E2 (direct) → E3 (multi-source) → E4 (validated)
ESCALATE:  L0 (normal) → L1 (different approach) → L2 (3 hypotheses) → L3 (7-point checklist) → L4 (minimal repro + human)
GATE:      Identify → Run → Read → Confirm → Claim
GIT LOCK:  git commit/push/pr → ONLY inside Ship stage
STATUS:    DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT