# Aperant Framework

[![npm](https://img.shields.io/npm/v/@aperant/framework)](https://www.npmjs.com/package/@aperant/framework)
[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg)](LICENSE)

> **Work in progress.** This is the foundation that will run the Aperant ecosystem — an agentic IDE covering the full software lifecycle. Join the waitlist at [aperant.com](https://aperant.com).

## Install

```bash
npx @aperant/framework init .
```

For non-interactive install or re-init across common runtimes:

```bash
npx @aperant/framework init . --claude --codex --pi --yes
```

## Usage

Just type `/apt` and describe what you want in natural language. The router classifies your input and dispatches to the right skill.

```
/apt add OAuth login with Google
/apt the chat scroll is jittery — debug it
/apt help me think through the new pricing model
/apt typo in the footer — wrong year
/apt review my PR
```

You can also call any skill directly (e.g. `/apt:plan ...`, `/apt:debug ...`).

Runtime command surfaces differ slightly:

- Claude: `/apt:plan`
- Codex: `/apt-plan`
- Pi: `/apt`, `/apt:plan` via `.pi/prompts/`

## Available commands

| Stage | Command | Purpose |
|---|---|---|
| **Route** | `/apt` | Smart router — natural-language dispatch to any skill |
| **Discovery** | `/apt:scan` | Build/refresh `.aperant/features/` registry |
| **Discovery** | `/apt:zoom-out` | One-page architectural orientation for an unfamiliar area |
| **Discovery** | `/apt:improve` | 3-lens scan for refactor opportunities (DEEPENING / INTERFACE-DESIGN / LANGUAGE) |
| **Discovery** | `/apt:debug` | Systematic debugging with persistent state across context resets |
| **Planning** | `/apt:discuss` | Brainstorm a vision or lock ambiguous decisions before planning |
| **Planning** | `/apt:design` | Pre-coding wireframe → critique → handoff to `/apt:plan` |
| **Planning** | `/apt:mockup` | Visual HTML+Tailwind mockup loop with parallel variants |
| **Planning** | `/apt:plan` | Investigate codebase, produce `spec.md` + `implementation_plan.json` |
| **Planning** | `/apt:roundtable` | 10-agent structured debate with supermajority voting |
| **Planning** | `/apt:spar` | Bidirectional adversarial sparring with a second CLI provider |
| **Planning** | `/apt:stress-test` | Scenario simulation to catch operational gaps before execution |
| **Planning** | `/apt:prototype` | Question-driven throwaway prototyping (LOGIC + UI branches) |
| **Build** | `/apt:quick` | Fast single-shot task — skip planning, go straight to implementation |
| **Build** | `/apt:execute` | Build code from a plan with atomic commits and progress tracking |
| **Build** | `/apt:run` | Full pipeline: plan → execute → verify → review in one command |
| **Verify** | `/apt:verify` | 4-dimension QA scoring (correctness / completeness / quality / coverage) |
| **Verify** | `/apt:verify-proof` | Visual proof verification — screenshots, video, HTML report |
| **Verify** | `/apt:review` | 6-pass inline code review with fix-all pipeline |
| **Verify** | `/apt:pr-review` | Multi-agent PR review — 6 parallel specialists + validator + fixer + self-reviewer |
| **Ship** | `/apt:ship` | Create PR with QA scores, decision traceability, commit-to-subtask mapping |
| **Ship** | `/apt:watch-ci` | Post-ship CI watcher — polls PR checks, auto-fixes red, pushes, reschedules |
| **Ship** | `/apt:close-task` | Post-merge closer — confirm merged, flip phase, GC state |
| **Session** | `/apt:pause` | Human-initiated handoff — save CONTINUE artifacts when you need to stop |
| **Session** | `/apt:resume` | Restore context from paused session and route to next action |
| **Docs** | `/apt:docs` | Generate/update documentation verified against the actual codebase |
| **Docs** | `/apt:create-docs` | Persona-first product docs from PROJECT.md + personas.json + features registry |
| **Docs** | `/apt:diagram` | Render a DiagramScene to `.excalidraw` file or live Excalidraw MCP canvas |
| **Project** | `/apt:bootstrap` | Generate/refresh PROJECT.md (product-context source of truth) |
| **Project** | `/apt:personas` | Discover 3–5 product personas grounded in code + PROJECT.md |
| **Project** | `/apt:roadmap` | Manage per-scope milestones, phases, owners, ROADMAP.md rendering |
| **Project** | `/apt:triage` | Move a task through the 5-state machine |
| **Framework** | `/apt:setup` | Change preferences (verification style, multi-model, parallelization, branching) |
| **Framework** | `/apt:update` | Refresh installed skills / agents / hooks across every runtime |

## License

AGPL-3.0-only. See [LICENSE](LICENSE).
