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

Activation

ASF is always on when software is being changed. The extension watches tool calls: the first change to a source file (an edit/write, a bash heredoc / sed -i / scripted write into source, or a pi -p --no-extensions worker with write tools) opens a small run automatically. Docs, assets and loose /tmp scratch never activate it, and nothing activates for Q&A or research.

An automatic run is held to a floor, not a ceremony: it cannot settle until a passing test run that started after the last source change is recorded (a lint or typecheck does not count), and any spec marked met during the run must carry trace.outcome + trace.codePath. Missing evidence is steered, never stopped: each gap is raised once, an identical steer never repeats, and an unclosable gap is reported as unverified. The run only parks for input ASF cannot obtain itself (plan approval, an irreversible step with no safe path, a credential, a deliverable-shaping choice).

Three refusals always hold, including in passive mode: a secret written into a tracked file, a push/publish without a recorded full-suite green, and a destructive git command on a dirty tree. A repeated identical refusal escalates from refuse, to refuse with the rule text, to parking for the PO.

Run state is stored per git work-tree root (or absolute path outside git), so cd into a subdirectory keeps the run. Deleting the state file does not end a run — it is restored and the deletion is recorded.

Large work (new project, significant feature, major bugfix, architectural refactor) runs the full gated flow above. You can also 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 (the legitimate way to end a run)
/asf passive      — silence steering for THIS run only (the three refusals stay)

Dependencies (required)

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

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.

{
  "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):

{
  "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

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