# AAPS Adapter

AgInTiFlow can use AAPS as a declarative control plane for large work. AAPS owns the top-down workflow script (`.aaps`), project manifest, validation contracts, compile reports, and run artifacts. AgInTiFlow remains the interactive agent runtime with model routing, file tools, shell policy, Docker mode, tmux, sessions, and canvas artifacts.

The integration is intentionally lightweight. AgInTiFlow does not vendor the AAPS parser or require AAPS as a hard dependency. It discovers AAPS at runtime in this order:

1. `AAPS_BIN` or `AGINTI_AAPS_BIN`.
2. `node_modules/.bin/aaps` in the current project.
3. `aaps` on `PATH`.
4. A sibling development checkout at `~/ProjectsLFS/AAPS/scripts/aaps.js` when present.

There are two useful bridge directions:

- `aginti aaps ...`: AgInTiFlow is the interactive runtime and calls the AAPS CLI to inspect, validate, compile, dry-run, or run project workflows.
- `aaps prompt "goal" --backend aginti`: AAPS writes a durable backend-agent handoff under `.aaps-work/prompts/` and invokes AgInTiFlow as the implementation agent for the goal.

## CLI

```bash
aginti aaps status
aginti aaps init "My AAPS Project"
aginti aaps files
aginti aaps validate
aginti aaps parse
aginti aaps compile check
aginti aaps check workflows/main.aaps
aginti aaps dry-run workflows/main.aaps
aginti aaps run workflows/main.aaps
```

Inside the interactive CLI, use the same commands with a slash:

```text
/aaps
/aaps on
/aaps init
/aaps validate
/aaps compile check
/aaps dry-run workflows/main.aaps
```

`/aaps on` switches the session to the AAPS task profile and raises the step budget for workflow work. `/aaps off` returns to the Auto profile.

## Safety

The adapter keeps paths project-relative and uses `execFile`, not shell interpolation. `status`, `files`, and `init` work without AAPS installed. Validation, parse, compile, check, and run require a discovered AAPS CLI.

`compile check` and `validate` are the recommended first checks. `run` can execute commands declared by the `.aaps` workflow, so treat it like any other project execution step and run only workflows you intend to execute.

Current lightweight adapter boundary: prompt-only AAPS tasks are recorded as handoffs. They do not automatically call an LLM/backend agent yet. When a workflow has prompt-only steps, `aginti aaps run` and `aginti aaps dry-run` print `promptOnly=<n>` plus warnings if no executable steps ran or a declared output was not produced.

`aginti aaps install` installs `@lazyingart/aaps` as a project dev dependency only when the current project has `package.json`. Use `aginti aaps install global` only when you intentionally want a global npm install.

If you want AAPS itself to hand a top-level goal to AgInTiFlow, use the AAPS CLI:

```bash
aaps prompt "Create and validate an executable workflow that writes reports/smoke.md" --project . --backend aginti
aaps "Create a small AAPS workflow and run it" --project . --backend aginti
aaps prompt "Prepare the backend prompt only" --project . --backend print --json
```

The generated AAPS handoff is sandbox-aware: it asks the backend to prefer installed `aaps`, use Docker-safe `npx -y @lazyingart/aaps@<version>` when package installs/network are approved, and use a source checkout only when that path is visible inside the active sandbox.

## Project Shape

`aginti aaps init` creates a starter project without overwriting existing files:

```text
aaps.project.json
workflows/main.aaps
reports/
runs/
artifacts/
```

The starter workflow is deliberately simple: it defines a planner agent and a `draft_plan` task whose declared output is `reports/aaps-plan.md`. With the current lightweight adapter this task is prompt-only, so `run` produces durable run metadata and a handoff warning rather than writing the plan itself. Use AgInTiFlow to act on that handoff, or expand the workflow with executable actions, validations, recovery steps, and review gates.

## When To Use AAPS

Use AAPS when a task is too large for a single chat-style loop and benefits from explicit phases:

- Multi-stage app development with review, tests, repair, screenshots, and release notes.
- Paper or book pipelines with outline, draft, figures, review, export, and publication checks.
- Data/research workflows with ingestion, cleaning, analysis, validation, and report artifacts.
- Recurring project maintenance with inspect, plan, patch, test, and commit stages.

For ordinary one-off coding or writing tasks, use normal AgInTiFlow prompts.