# pi-aia-asf — Ai Applied Agentic Software Factory

Codifies the full, disciplined software development flow used on real projects (conversense, betamaxx, mbee.me, pi-vigilant): **classify → intake → research → specs → adversarial analysis → plan with approval gate → test-first implementation → verification & delivery**.

It turns "let's build something" into a gated pipeline where nothing is implemented on assumptions, every hard requirement is captured as a verifiable spec, and nothing ships without evidence.

## What it does

| Phase | Gate | What happens |
|---|---|---|
| 0. Classify | must be ASF work | New project / feature / major bugfix / refactor — or *not* ASF (skill stays quiet) |
| 1. Intake | user confirms intent | Ask until goal, success criteria, constraints are all clear |
| 2. Research | approach agreed | SOTA + existing packages via `web_search`/`web_fetch`, cited |
| 3. Specs | user signs off | Every hard requirement → `capture_spec` (shared with pi-vigilant) |
| 4. Adversarial | findings confirmed | Edge cases, failure modes, security, maintainability challenged |
| 5. Plan | **explicit approval** | `PLAN.md` in repo root — no implementation before approval |
| 6. Implement | tests green | Test-first, strict codebase isolation, browser-tested UIs |
| 7. Verify & deliver | specs met | Every spec verified with evidence; release offered, never auto-published |

## Activation

The skill activates when the user's request is a **new software project, significant feature, major bugfix, or architectural refactor**. It does **not** activate for Q&A, one-liners, casual conversation, or non-software tasks. When in doubt, it asks.

You can also force/start a session explicitly:

```
/asf new          — start a new software project
/asf feature      — add a feature
/asf bugfix       — major bugfix
/asf refactor     — architectural refactor
/asf status       — show current phase + state
/asf health       — run the code health gate (function/module/architecture)
/asf approve      — mark PLAN.md as approved (Gate 5)
/asf abort        — end the session
```

## Dependencies (required)

| Package | Provides | Install |
|---|---|---|
| **pi-vigilant** | `capture_spec`, `get_task_specs`, `update_spec_status`, final verification | `pi install npm:pi-vigilant` |
| **pi-smart-web-search** | `web_search` | `pi install npm:pi-smart-web-search` |
| **pi-smart-fetch** | `web_fetch`, `batch_web_fetch` | `pi install npm:pi-smart-fetch` |
| **pi-aia-browser** | `browser_init`, `browser_navigate`, … (Playwright + Chromium, auto-installed) | `pi install npm:pi-aia-browser` |

**Optional:** `pi-intercom` (`intercom` — message other live pi sessions directly) is **not** a dependency; ASF works without it. Install it only if you want delegation between sessions: `pi install npm:pi-intercom`.

The extension warns at startup (and on `/asf` with no args) when any dependency is missing.

## Install

```bash
pi install npm:pi-aia-asf
```

Then `/reload`.

## How it works

- **Skill** (`skills/aia-asf/SKILL.md`) — the workflow itself, with per-phase reference guides in `references/`. The skill uses **progressive disclosure**: only SKILL.md (the phase flow + gates + a reference index) loads by default; each reference is a small single-concern doc the agent reads on demand when its phase needs it (the index's "Read when" column tells it which). Small work reads at most the testing + code-quality standards; large work reads the ones its phase calls for.
- **Extension** (`index.ts`) — `/asf` commands, per-project phase state (`~/.pi/agent/skills/aia-asf/projects/<project>/state.json`), dependency checks.
- **Specs shared with pi-vigilant** — ASF drives `capture_spec` during intake; pi-vigilant re-verifies every spec at task end and blocks "done" while MUST specs are open. One spec file, two systems.

## Code Health Gate

`/asf health` measures convolution **objectively** at three levels — function
(complexity, cognitive complexity, lines, depth, params), module (file lines,
duplication, circular imports) and architecture (optional dependency rules) —
and fails the gate when a threshold is crossed. It is **on by default** with
conservative thresholds; configure via `.asf-code-health.json` at the project
root (every level/metric can be disabled independently). For large work it is
**Gate 8** in `/asf verify`. See `skills/aia-asf/references/06e-code-health.md`.

```json
{
  "enabled": true,
  "gate": { "mode": "block", "scope": "large" },
  "missingTool": "warn",
  "function": { "complexity": { "max": 20 }, "maxDepth": { "max": 4 } },
  "module": { "duplication": { "thresholdPercent": 5 } }
}
```

Flags: `--diff` (compare vs committed `.asf-code-health-baseline.json`),
`--update-baseline`, `--json`. Tools are invoked via `npx --no-install` — they
must be project devDependencies (eslint, eslint-plugin-sonarjs, jscpd, madge,
dependency-cruiser); the gate never installs anything.

## Release policy (configurable)

Publishing is the user's decision **by default** — the factory prepares the
release and gets explicit approval. A project can define its own release
policy in `.asf-release.json` at the project root (optional):

```json
{
  "when": "when the full suite is green and the bump is patch/minor → publish automatically; when the bump is major → send for final review; when the suite is not green → fix first, never publish",
  "how": "To publish: connect with npm using the credentials in ~/.npmrc (2FA token; verify with `npm whoami`), sync git (`git pull --rebase`), run `npm run release <level>`, then verify the published version from the registry in a clean install..."
}
```

- **`when`** — user-stated conditional rules the ASF evaluates against the
  current state (suite green, bump scope, credentials) and acts on.
- **`how`** — user-stated instructions with all technical details; the ASF
  drives the release with judgment, not as a deterministic command list.
- No file → default: always send for final review; standard workflow in
  `references/07-release.md`.
- **Always test on publish / in production, if applicable** — verify the
  shipped artifact from the registry (clean-room install) or smoke-test prod.

## Hygiene rules enforced

- Test-first; only green commits
- **Strict codebase isolation** — the project never touches other repos unless the user explicitly says so
- **Mandatory browser testing** of any web interface (real user experience, not just curl)
- Descriptive commits + CHANGELOG entries (no placeholders)
- **Publishing is always the user's decision** — ASF prepares the release (version + CHANGELOG + tag), optionally offers CI/CD setup, but never auto-publishes

## Development

```bash
npm run check   # typecheck
npm test        # see repo for test suites
npm run release patch|minor|major   # test → version → CHANGELOG → tag → push
```

## License

MIT © Bruno Jakic, Ai Applied