
Apex Tier3
- 4 installs
- 2 repo stars
- Updated March 14, 2026
- othmanadi/apex
Pair-program in real time with a propose-confirm loop and decision log for high-stakes architecture, debugging, or exploratory work.
About
Runs a real-time pair-programming mode where the agent proposes and the human confirms every significant decision. A developer uses it for high-stakes architecture design, critical debugging, or exploratory work needing discussion at each step.
- Propose-confirm loop: never write >50 lines without checking in
- Maintains a running decision log with rationale and alternatives
Apex Tier3 by the numbers
- 4 all-time installs (skills.sh)
- +1 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #2,331 of 3,282 Productivity & Planning skills by installs in the Skillselion catalog
- Data as of Aug 4, 2026 (Skillselion catalog sync)
npx skills add https://github.com/othmanadi/apex --skill apex-tier3Add your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 4 |
|---|---|
| repo stars | ★ 2 |
| Last updated | March 14, 2026 |
| Repository | othmanadi/apex ↗ |
What it does
Pair-program in real time with a propose-confirm loop and decision log for high-stakes architecture, debugging, or exploratory work.
Files
APEX Tier 3 — Pair Mode
Work side-by-side with the human in real-time. Every significant decision is discussed. The agent proposes, the human approves or redirects.
When to Use
Use Tier 3 when:
- Designing new architecture from scratch
- Debugging a critical production issue
- The problem space is ambiguous or exploratory
- The human wants to learn from the process
- Stakes are high and mistakes are expensive
Interaction Protocol
The Propose-Confirm Loop
Every action follows this pattern:
1. Agent proposes — "I think we should do X because Y. Here's what that looks like..." 2. Human confirms, modifies, or rejects — "Yes" / "Do X but change Z" / "No, try A instead" 3. Agent executes — Implements the confirmed approach 4. Agent reports — "Done. Here's what changed. Ready for next step."
Rules of Engagement
- Never write more than 50 lines without checking in
- Always explain WHY before proposing WHAT
- Show alternatives when there's a genuine trade-off: "Option A gives us X but costs Y. Option B gives us Z but costs W."
- Admit uncertainty — "I'm not confident about this approach because..." is always better than guessing
- No yes-man behavior — If the human's suggestion has a flaw, say so respectfully with evidence
Workflow
Opening
Start by understanding the problem space:
Before we start, I need to understand:
1. What are we trying to achieve?
2. What constraints exist (time, tech, compatibility)?
3. What have you already tried or considered?
4. What does success look like?During the Session
Maintain a running decision log:
## Decision Log
| # | Decision | Rationale | Alternatives Considered |
|---|----------|-----------|------------------------|
| 1 | Use Prisma over Drizzle | Team familiarity | Drizzle (faster), raw SQL (flexible) |
| 2 | REST over GraphQL | Simpler for this scope | GraphQL (flexible queries) |After every significant block of work, run validation:
Linux/Mac:
bash "${CLAUDE_SKILL_DIR}/scripts/validate.sh" <target-dir>Windows:
powershell -File "${CLAUDE_SKILL_DIR}/scripts/validate.ps1" <target-dir>Closing
At the end of the session:
1. Summarize all decisions made 2. List any open questions or TODOs 3. Identify learnings that should be added to AGENTS.md 4. Commit work with a descriptive message referencing the decision log
Output
Working code with a complete decision log. Any recurring patterns or preferences discovered during the session are candidates for AGENTS.md updates via apex-learn.
Example decision log:
## Decision Log — Event System Architecture
| # | Decision | Rationale | Alternatives Considered |
|---|----------|-----------|------------------------|
| 1 | Use EventEmitter over message queue | Simpler for current scale, can migrate later | RabbitMQ, Redis pub/sub |
| 2 | Typed events with Zod schemas | Runtime validation + TypeScript inference | io-ts, manual types |
| 3 | Async handlers by default | Non-blocking, better throughput | Sync handlers |
| 4 | Dead letter queue for failures | Debugging + replay capability | Log and drop |
## Open Questions
- [ ] Should we add event versioning now or later?
- [ ] Rate limiting for high-frequency events?
## Learnings for AGENTS.md
- Always use typed events (add to Architecture Rules)
- Prefer async handlers unless order matters (add to Preferences)# APEX — Self-Correcting Validation Chain (Windows)
# Runs linter, type checker, tests, and build in sequence.
# Usage: powershell -File validate.ps1 <project-dir>
param(
[Parameter(Position=0)]
[string]$ProjectDir = "."
)
$ErrorActionPreference = "Continue"
Set-Location $ProjectDir
Write-Host "=== APEX Validation Chain ==="
Write-Host "Project: $ProjectDir"
Write-Host "Date: $((Get-Date).ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ'))"
Write-Host ""
$Pass = 0
$Fail = 0
$Results = @()
function Run-Step {
param([string]$StepName, [string]$Command)
Write-Host "--- Step: $StepName ---"
try {
$output = Invoke-Expression $Command 2>&1
$output | ForEach-Object { Write-Host $_ }
if ($LASTEXITCODE -eq 0 -or $null -eq $LASTEXITCODE) {
Write-Host "PASS: $StepName"
$script:Pass++
$script:Results += [PSCustomObject]@{Step=$StepName; Status="PASS"; Notes="—"}
} else {
Write-Host "FAIL: $StepName"
$script:Fail++
$script:Results += [PSCustomObject]@{Step=$StepName; Status="FAIL"; Notes="See output above"}
}
} catch {
Write-Host "FAIL: $StepName — $($_.Exception.Message)"
$script:Fail++
$script:Results += [PSCustomObject]@{Step=$StepName; Status="FAIL"; Notes=$_.Exception.Message}
}
Write-Host ""
}
# Detect project type
$packageJson = Join-Path $ProjectDir "package.json"
$pyproject = Join-Path $ProjectDir "pyproject.toml"
$requirements = Join-Path $ProjectDir "requirements.txt"
$goMod = Join-Path $ProjectDir "go.mod"
$cargoToml = Join-Path $ProjectDir "Cargo.toml"
if (Test-Path $packageJson) {
# Node.js project
$pkg = Get-Content $packageJson -Raw | ConvertFrom-Json
# Lint
if ($pkg.scripts.PSObject.Properties.Name -contains "lint") {
Run-Step "Lint" "npm run lint"
} elseif (Test-Path "eslint.config.*" -ErrorAction SilentlyContinue) {
Run-Step "Lint" "npx eslint . --max-warnings 0"
} else {
Write-Host "SKIP: No linter configured"
$Results += [PSCustomObject]@{Step="Lint"; Status="SKIP"; Notes="No config found"}
}
# Type check
if (Test-Path (Join-Path $ProjectDir "tsconfig.json")) {
Run-Step "Type Check" "npx tsc --noEmit"
} else {
Write-Host "SKIP: No TypeScript config"
$Results += [PSCustomObject]@{Step="Type Check"; Status="SKIP"; Notes="No tsconfig.json"}
}
# Tests
if ($pkg.scripts.PSObject.Properties.Name -contains "test") {
Run-Step "Tests" "npm run test -- --passWithNoTests"
} else {
Write-Host "SKIP: No test script"
$Results += [PSCustomObject]@{Step="Tests"; Status="SKIP"; Notes="No test script"}
}
# Build
if ($pkg.scripts.PSObject.Properties.Name -contains "build") {
Run-Step "Build" "npm run build"
} else {
Write-Host "SKIP: No build script"
$Results += [PSCustomObject]@{Step="Build"; Status="SKIP"; Notes="No build script"}
}
} elseif ((Test-Path $pyproject) -or (Test-Path $requirements)) {
# Python project
if (Get-Command ruff -ErrorAction SilentlyContinue) {
Run-Step "Lint (ruff)" "ruff check ."
} elseif (Get-Command flake8 -ErrorAction SilentlyContinue) {
Run-Step "Lint (flake8)" "flake8 ."
} else {
Write-Host "SKIP: No Python linter found"
$Results += [PSCustomObject]@{Step="Lint"; Status="SKIP"; Notes="Install ruff or flake8"}
}
if (Get-Command mypy -ErrorAction SilentlyContinue) {
Run-Step "Type Check (mypy)" "mypy ."
}
if (Get-Command pytest -ErrorAction SilentlyContinue) {
Run-Step "Tests (pytest)" "pytest -v"
}
} elseif (Test-Path $goMod) {
Run-Step "Lint (go vet)" "go vet ./..."
Run-Step "Build" "go build ./..."
Run-Step "Tests" "go test ./..."
} elseif (Test-Path $cargoToml) {
Run-Step "Lint (clippy)" "cargo clippy -- -D warnings"
Run-Step "Build" "cargo build"
Run-Step "Tests" "cargo test"
} else {
Write-Host "WARNING: Could not detect project type."
$Fail++
$Results += [PSCustomObject]@{Step="Detection"; Status="FAIL"; Notes="Unknown project type"}
}
Write-Host ""
Write-Host "=== Validation Summary ==="
$Results | Format-Table -AutoSize
Write-Host "Passed: $Pass | Failed: $Fail"
if ($Fail -gt 0) {
Write-Host ""
Write-Host "ACTION: Fix the failures above and re-run this script."
exit 1
} else {
Write-Host ""
Write-Host "All checks passed. Ready to commit."
exit 0
}
#!/usr/bin/env bash
# APEX — Self-Correcting Validation Chain (Linux/Mac)
# Runs linter, type checker, tests, and build in sequence.
# Exits with the first failure so the agent can fix and re-run.
# Usage: bash validate.sh <project-dir>
set -euo pipefail
PROJECT_DIR="${1:-.}"
cd "$PROJECT_DIR"
echo "=== APEX Validation Chain ==="
echo "Project: $PROJECT_DIR"
echo "Date: $(date -u +"%Y-%m-%dT%H:%M:%SZ")"
echo ""
PASS=0
FAIL=0
RESULTS=""
run_step() {
local step_name="$1"
local cmd="$2"
echo "--- Step: $step_name ---"
if eval "$cmd" 2>&1; then
echo "PASS: $step_name"
PASS=$((PASS + 1))
RESULTS="$RESULTS\n| $step_name | PASS | — |"
else
echo "FAIL: $step_name"
FAIL=$((FAIL + 1))
RESULTS="$RESULTS\n| $step_name | FAIL | See output above |"
return 1
fi
echo ""
}
# Detect project type and run appropriate tools
if [ -f "package.json" ]; then
# Node.js project
PM="npx"
[ -f "pnpm-lock.yaml" ] && PM="pnpm exec"
[ -f "yarn.lock" ] && PM="yarn"
# Step 1: Lint
if grep -q '"lint"' package.json 2>/dev/null; then
run_step "Lint" "$PM run lint 2>&1" || true
elif [ -f ".eslintrc.js" ] || [ -f ".eslintrc.json" ] || [ -f "eslint.config.js" ] || [ -f "eslint.config.mjs" ]; then
run_step "Lint" "npx eslint . --max-warnings 0 2>&1" || true
else
echo "SKIP: No linter configured"
RESULTS="$RESULTS\n| Lint | SKIP | No config found |"
fi
# Step 2: Type check
if [ -f "tsconfig.json" ]; then
run_step "Type Check" "npx tsc --noEmit 2>&1" || true
else
echo "SKIP: No TypeScript config"
RESULTS="$RESULTS\n| Type Check | SKIP | No tsconfig.json |"
fi
# Step 3: Tests
if grep -q '"test"' package.json 2>/dev/null; then
run_step "Tests" "$PM run test -- --passWithNoTests 2>&1" || true
else
echo "SKIP: No test script"
RESULTS="$RESULTS\n| Tests | SKIP | No test script |"
fi
# Step 4: Build
if grep -q '"build"' package.json 2>/dev/null; then
run_step "Build" "$PM run build 2>&1" || true
else
echo "SKIP: No build script"
RESULTS="$RESULTS\n| Build | SKIP | No build script |"
fi
elif [ -f "pyproject.toml" ] || [ -f "requirements.txt" ] || [ -f "setup.py" ]; then
# Python project
# Step 1: Lint
if command -v ruff &>/dev/null; then
run_step "Lint (ruff)" "ruff check . 2>&1" || true
elif command -v flake8 &>/dev/null; then
run_step "Lint (flake8)" "flake8 . 2>&1" || true
else
echo "SKIP: No Python linter found"
RESULTS="$RESULTS\n| Lint | SKIP | Install ruff or flake8 |"
fi
# Step 2: Type check
if command -v mypy &>/dev/null; then
run_step "Type Check (mypy)" "mypy . 2>&1" || true
else
echo "SKIP: mypy not installed"
RESULTS="$RESULTS\n| Type Check | SKIP | Install mypy |"
fi
# Step 3: Tests
if command -v pytest &>/dev/null; then
run_step "Tests (pytest)" "pytest -v 2>&1" || true
else
echo "SKIP: pytest not installed"
RESULTS="$RESULTS\n| Tests | SKIP | Install pytest |"
fi
# Step 4: Build
run_step "Build (syntax check)" "python -m py_compile *.py 2>&1 || true" || true
elif [ -f "go.mod" ]; then
# Go project
run_step "Lint (go vet)" "go vet ./... 2>&1" || true
run_step "Build" "go build ./... 2>&1" || true
run_step "Tests" "go test ./... 2>&1" || true
elif [ -f "Cargo.toml" ]; then
# Rust project
run_step "Lint (clippy)" "cargo clippy -- -D warnings 2>&1" || true
run_step "Build" "cargo build 2>&1" || true
run_step "Tests" "cargo test 2>&1" || true
else
echo "WARNING: Could not detect project type. No validation run."
RESULTS="$RESULTS\n| Detection | FAIL | Unknown project type |"
FAIL=$((FAIL + 1))
fi
echo ""
echo "=== Validation Summary ==="
echo "| Step | Status | Notes |"
echo "|------|--------|-------|"
echo -e "$RESULTS"
echo ""
echo "Passed: $PASS | Failed: $FAIL"
if [ "$FAIL" -gt 0 ]; then
echo ""
echo "ACTION: Fix the failures above and re-run this script."
exit 1
else
echo ""
echo "All checks passed. Ready to commit."
exit 0
fi