# Aperant Framework -- Plugin Template

A starting point for building a custom framework adapter for the [Aperant](https://aperant.dev) platform. Copy this directory, fill in your framework's artifact declarations and mapper logic, and Aperant will render your framework's output in its standard UI.

## Files

| File | Purpose |
| ---- | ------- |
| `manifest.json` | Declares your framework's identity, lifecycle stages, artifacts, and mapper paths. Conforms to the `FrameworkManifest` interface. |
| `mappers/context-mapper.ts` | Example mapper that translates your context-stage artifacts into `AperantContextView`. |
| `mappers/plan-mapper.ts` | Example mapper that translates your plan-stage artifacts into `AperantPlanView`. |

## Getting Started

1. **Copy this directory** into your own project:
   ```bash
   cp -r examples/plugin-template ~/my-framework-plugin
   cd ~/my-framework-plugin
   ```

2. **Install the framework package** as a dev dependency:
   ```bash
   npm install --save-dev @aperant/framework
   ```

3. **Edit `manifest.json`** with your framework's details:
   - Set `id` to a unique identifier for your framework (e.g., `"bmad"`, `"speckit"`)
   - Set `name` to a human-readable name
   - Update each stage's `artifacts` array with the filenames your framework produces
   - Point each stage's `mapper` field to the compiled JS path of your mapper

4. **Implement the mapper functions** for each stage. The two included mappers (`context-mapper.ts` and `plan-mapper.ts`) demonstrate the pattern:
   - Receive a `Map<filename, fileContent>` of native artifacts
   - Parse your native format
   - Return the normalized Aperant UI shape

   You will also need `progress-mapper.ts` (returns `AperantProgressView`) and `verify-mapper.ts` (returns `AperantVerificationView`).

5. **Replace inline types with imports** from `@aperant/framework/types`:
   ```typescript
   import type {
     AperantContextView,
     AperantPlanView,
     AperantProgressView,
     AperantVerificationView,
   } from "@aperant/framework/types";
   ```

6. **Build with TypeScript** and confirm your mappers compile cleanly:
   ```bash
   npx tsc
   ```

7. **Install for local testing** by copying the built output to the plugins directory:
   ```bash
   mkdir -p ~/.aperant/plugins/my-framework
   cp -r dist/ manifest.json ~/.aperant/plugins/my-framework/
   ```

## How It Works

1. When Aperant loads a framework plugin, it reads `manifest.json` to discover stages and mapper paths.
2. For each stage, Aperant collects the native artifact files declared in the manifest.
3. It passes them as a `Map<filename, fileContent>` to the corresponding mapper function.
4. The mapper parses the native format and returns the normalized UI shape.
5. Aperant renders the shape in its standard components (decisions table, Kanban board, progress bar, verification dashboard).

## Type Reference

For the complete API reference including all UI shape interfaces, provider capabilities, and mapper contracts, see [docs/api.md](../../docs/api.md).

## Key Interfaces

- **`FrameworkManifest`** -- Top-level plugin declaration (id, name, version, stages)
- **`StageManifest`** -- Per-stage artifact declarations and mapper path
- **`AperantContextView`** -- Normalized context (decisions, scope, deferred items)
- **`AperantPlanView`** -- Normalized plan (tasks, waves, dependencies)
- **`AperantProgressView`** -- Normalized progress (percent, activity feed)
- **`AperantVerificationView`** -- Normalized verification (score, dimensions, gaps)
