
Apex Replatform
- 4 installs
- 2 repo stars
- Updated March 14, 2026
- othmanadi/apex
Implement a feature in a new architecture from a specification document, mapping spec concepts to target patterns and self-validating.
About
Implements a feature in a target architecture from a specification document, without needing the original source. A developer uses it to rebuild a decomposed feature in a new framework using the spec as the source of truth.
- Maps spec concepts to target architecture patterns with user confirmation
- Self-correcting loop runs lint, typecheck, tests, build until clean
Apex Replatform by the numbers
- 4 all-time installs (skills.sh)
- +1 installs in the week ending Aug 4, 2026 (Skillselion tracking)
- Ranked #3,711 of 4,347 Backend & APIs 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-replatformAdd 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
Implement a feature in a new architecture from a specification document, mapping spec concepts to target patterns and self-validating.
Files
APEX Replatform
Take a feature specification (from apex-decompose or manually written) and implement it in a target architecture. This is the "mapping problem" — translating what exists into what should exist.
When to Use
Use this skill after you have a specification document describing the feature's behavior. You should NOT need access to the original source code. The spec is your single source of truth.
Workflow
Replatforming a feature involves these steps:
1. Load and understand the specification 2. Map the spec to the target architecture 3. Implement the feature 4. Wire up self-correcting feedback loops 5. Validate against the spec's acceptance criteria
Step 1: Load the Specification
Read the spec file:
Read specs/{feature-name}.mdIdentify all [VERIFY] tags. Ask the user to resolve any ambiguities before proceeding. Do not guess on verified items.
Step 2: Map to Target Architecture
Create a mapping document that translates spec concepts to target patterns:
| Spec Concept | Target Implementation |
|---|---|
Database write to users table | Prisma user.create() call |
REST endpoint /api/v1/items | Next.js API route app/api/items/route.ts |
Event emission item.created | EventEmitter / message queue publish |
Ask the user to confirm the mapping before writing code. This is the architectural decision point.
Step 3: Implement the Feature
Write code following these rules:
1. One file at a time. Complete each file before moving to the next. 2. Match the spec exactly. Every input, output, and side effect in the spec must be implemented. 3. Preserve edge cases. If the spec says "returns 400 when empty," implement that exact behavior. 4. Add inline comments referencing the spec: // Spec: Edge Case #3 — concurrent request handling
Step 4: Self-Correcting Feedback Loop
After writing code, run the validation chain. Detect OS and use the appropriate script:
Linux/Mac:
bash "${CLAUDE_SKILL_DIR}/scripts/validate.sh" <target-dir>Windows:
powershell -File "${CLAUDE_SKILL_DIR}/scripts/validate.ps1" <target-dir>The validation script runs in order: linter, type checker, tests, build. If any step fails, read the error output, fix the issue, and re-run. Repeat until all four pass. Do NOT ask the user for help until you have attempted at least 3 fix cycles.
Step 5: Validate Against Spec
Walk through every section of the spec and confirm implementation coverage:
| Spec Section | Status | Notes |
|---|---|---|
| Inputs | PASS/FAIL | All parameters handled |
| Outputs | PASS/FAIL | Response shape matches |
| Side Effects | PASS/FAIL | All mutations implemented |
| Edge Cases | PASS/FAIL | Each case has a code path |
| Dependencies | PASS/FAIL | All packages installed |
Create a draft PR with this checklist in the description.
Output
A working implementation in the target architecture that matches the specification, with a passing validation chain and a draft PR ready for human review.
Example PR body:
## apex: Implement user-authentication from spec
### Spec Coverage
| Section | Status | Notes |
|---------|--------|-------|
| Inputs | ✅ PASS | All parameters handled |
| Outputs | ✅ PASS | JWT + cookie response |
| Side Effects | ✅ PASS | Session + event implemented |
| Edge Cases | ✅ PASS | 401/403 paths verified |
### Validation Results
- Lint: ✅ PASS
- Types: ✅ PASS
- Tests: ✅ PASS (12 new, 0 failing)
- Build: ✅ PASS
### Files Changed
- `src/auth/login.ts` (new)
- `src/auth/session.ts` (new)
- `src/events/user.ts` (modified)Feature: {Feature Name}
Overview
One paragraph describing what this feature does from the user's perspective.
Source Files
path/to/file1.ts— Role in the featurepath/to/file2.ts— Role in the feature
Behavior Contract
Inputs
| Name | Type | Source | Required | Description |
|---|---|---|---|---|
| param1 | string | request.body | yes | Description |
Outputs
| Name | Type | Destination | Description |
|---|---|---|---|
| result | object | response.json | Description |
Side Effects
1. Writes to table_name in database when condition X 2. Emits event event_name on success 3. Calls external-service/endpoint with payload Y
Edge Cases
1. When input is empty — Returns 400 with message "..." 2. When service is down — Retries 3 times, then falls back to cached value 3. When concurrent requests — Uses optimistic locking on field Z
Dependencies
| Dependency | Type | Version | Purpose |
|---|---|---|---|
| package-x | npm | ^2.0.0 | Used for Y |
| service-z | API | v3 | Called during Z |
Configuration
| Key | Default | Description |
|---|---|---|
| FEATURE_FLAG_X | false | Enables experimental behavior |
| TIMEOUT_MS | 5000 | Request timeout |
Migration Notes
- [VERIFY] Confirm whether the retry logic is still needed in the new architecture
- The hardcoded value
42on line 87 of file.ts is the max batch size from a 2023 incident - Order of operations in
processQueue()is critical — step 2 must complete before step 3
# 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