// Implement features in a new architecture using specifications from apex-decompose. Use when replatforming, migrating codebases, rebuilding features in a new framework, or translating specs into working code. Triggers on keywords like replatform, migrate, rebuild, implement spec, new architecture.
Trigger the self-improvement loop after completing a task. Analyzes friction, extracts learnings, and updates AGENTS.md with new rules and preferences. Use after any task that involved struggle, correction, or discovery of a new pattern. Triggers on keywords like learn, self-improve, update rules, what did I learn, retrospective, post-mortem.
Decompose features from an existing codebase into detailed, agent-ready specifications for replatforming or migration. Use when analyzing legacy code, extracting feature behavior, mapping old architecture to new, or preparing migration specs. Triggers on keywords like decompose, analyze features, extract behavior, migration spec, map codebase.
Execute well-defined tasks autonomously with zero human intervention. Fire-and-forget mode for straightforward work like adding tests, fixing lint errors, writing docs, or implementing simple features. Use when the task is clear, low-risk, and has objective pass/fail criteria. Triggers on keywords like fire and forget, autonomous task, simple fix, add tests, fix lint.
Execute complex tasks with periodic human checkpoints. Background work with steering — the agent works autonomously but pauses at defined decision points for human input. Use for medium-complexity tasks like feature implementation, refactoring, or multi-file changes. Triggers on keywords like guided task, checkpoint, background with review, implement feature, refactor module.
Real-time pair programming mode for complex architectural work. The agent and human collaborate interactively on design decisions, complex debugging, or exploratory work. Use for high-stakes tasks, new architecture design, critical bug investigation, or when every step needs discussion. Triggers on keywords like pair, collaborate, design together, debug with me, architect, explore.
| name | apex-replatform |
| description | Implement features in a new architecture using specifications from apex-decompose. Use when replatforming, migrating codebases, rebuilding features in a new framework, or translating specs into working code. Triggers on keywords like replatform, migrate, rebuild, implement spec, new architecture. |
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.
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.
Replatforming a feature involves these steps:
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.
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.
Write code following these rules:
// Spec: Edge Case #3 — concurrent request handlingAfter 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.
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.
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)