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

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)

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