othmanadi 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:
- Load and understand the specification
- Map the spec to the target architecture
- Implement the feature
- Wire up self-correcting feedback loops
- Validate against the spec's acceptance criteria
Step 1: Load the Specification
Read the spec file:
Read specs/{feature-name}.md
Identify 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:
- One file at a time. Complete each file before moving to the next.
- Match the spec exactly. Every input, output, and side effect in the spec must be implemented.
- Preserve edge cases. If the spec says "returns 400 when empty," implement that exact behavior.
- 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)