pi-aia-asf 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+
+- Initial release of the Ai Applied Agentic Software Factory.
+- ASF skill with 8 gated phases: classify, intake, research, specs, adversarial analysis, plan (approval gate), test-first implementation, verification & delivery.
+- Per-phase reference guides (intake question bank, research playbook, adversarial checklist, PLAN.md template, implementation discipline, release workflow).
+- `/asf` commands: new, feature, bugfix, refactor, status, approve, abort.
+- Per-project phase state tracking in `~/.pi/agent/skills/aia-asf/projects/<project>/state.json`.
+- Dependency checks at startup and on `/asf` (pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser).
+- Specs shared with pi-vigilant via `capture_spec` / `get_task_specs` / `update_spec_status`.
+- Strict codebase isolation rule (project never touches other repos unless the user says so).
+- Mandatory pi-aia-browser testing for any web interface.
+- Release workflow: prepare version + CHANGELOG + tag + push; publishing always requires explicit user approval.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bruno Jakic, Ai Applied
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# 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 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` |
+
+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/`.
+- **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.
+
+## 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

package/index.ts

@@ -0,0 +1,232 @@
+/**
+ * pi-aia-asf — Ai Applied Agentic Software Factory.
+ *
+ * Small extension complementing the aia-asf skill:
+ *  - `/asf` commands (new, feature, bugfix, refactor, status, abort)
+ *  - per-project phase state (JSON in ~/.pi/agent/skills/aia-asf/projects/<project>/state.json)
+ *  - startup + first-run dependency check (pi-vigilant, web search/fetch, browser)
+ *
+ * The actual workflow lives in skills/aia-asf/SKILL.md — this extension only
+ * provides state and commands. Safe to load even when dependencies are missing:
+ * it warns instead of crashing.
+ */
+
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+// ─── Types ─────────────────────────────────────────────────────────────────
+
+type AsfPhase =
+  | "none"
+  | "classify"
+  | "intake"
+  | "research"
+  | "specs"
+  | "adversarial"
+  | "plan"
+  | "implementation"
+  | "verification";
+
+interface AsfState {
+  workType?: "new-project" | "feature" | "major-bugfix" | "refactor";
+  phase: AsfPhase;
+  planApproved?: boolean;
+  startedAt?: string;
+  updatedAt: string;
+}
+
+interface ProjectStateFile {
+  current: AsfState | null;
+  history: Array<{ workType: string; phase: AsfPhase; startedAt: string; endedAt: string }>;
+}
+
+// ─── Constants & helpers ───────────────────────────────────────────────────
+
+const SKILLS_DIR = join(homedir(), ".pi", "agent", "skills");
+const STATE_DIR = join(SKILLS_DIR, "aia-asf", "projects");
+
+function projectName(): string {
+  try {
+    return process.cwd().split(/[\\/]/).pop() || "default";
+  } catch {
+    return "default";
+  }
+}
+
+function stateFileFor(project: string): string {
+  return join(STATE_DIR, project, "state.json");
+}
+
+async function loadState(project: string): Promise<ProjectStateFile> {
+  const file = stateFileFor(project);
+  if (!existsSync(file)) {
+    return { current: null, history: [] };
+  }
+  try {
+    return JSON.parse(await readFile(file, "utf-8")) as ProjectStateFile;
+  } catch {
+    return { current: null, history: [] };
+  }
+}
+
+async function saveState(project: string, data: ProjectStateFile): Promise<void> {
+  const file = stateFileFor(project);
+  await mkdir(join(STATE_DIR, project), { recursive: true });
+  await writeFile(file, JSON.stringify(data, null, 2), "utf-8");
+}
+
+// ─── Dependency check ──────────────────────────────────────────────────────
+
+interface DependencyCheck {
+  name: string;
+  package: string;
+  present: boolean;
+  hint: string;
+}
+
+function checkDependencies(): DependencyCheck[] {
+  // Detect the tools by looking for the packages that register them.
+  // Tools are registered by extensions at runtime, so we check the
+  // installed packages in ~/.pi/agent/npm and the extensions dir.
+  const npmDir = join(homedir(), ".pi", "agent", "npm", "node_modules");
+  const extDir = join(homedir(), ".pi", "agent", "extensions");
+  const gitDir = join(homedir(), ".pi", "agent", "git");
+
+  const checks: DependencyCheck[] = [
+    {
+      name: "pi-vigilant (spec-memory: capture_spec / get_task_specs / update_spec_status)",
+      package: "pi-vigilant",
+      present: existsSync(join(npmDir, "pi-vigilant")) || existsSync(join(extDir, "pi-vigilant")) || existsSync(join(gitDir, "github.com", "brunoj", "pi-vigilant")),
+      hint: "pi install npm:pi-vigilant",
+    },
+    {
+      name: "pi-smart-web-search (web_search)",
+      package: "pi-smart-web-search",
+      present: existsSync(join(npmDir, "pi-smart-web-search")),
+      hint: "pi install npm:pi-smart-web-search",
+    },
+    {
+      name: "pi-smart-fetch (web_fetch / batch_web_fetch)",
+      package: "pi-smart-fetch",
+      present: existsSync(join(npmDir, "pi-smart-fetch")),
+      hint: "pi install npm:pi-smart-fetch",
+    },
+    {
+      name: "pi-aia-browser (browser_init / browser_navigate / …)",
+      package: "pi-aia-browser",
+      present:
+        existsSync(join(npmDir, "pi-aia-browser")) ||
+        existsSync(join(extDir, "pi-aia-browser")) ||
+        existsSync(join(extDir, "pi-browser")) ||
+        existsSync(join(gitDir, "github.com", "brunoj", "pi-aia-browser")),
+      hint: "pi install npm:pi-aia-browser (installs Playwright + Chromium)",
+    },
+  ];
+
+  return checks;
+}
+
+function dependencySummary(): string {
+  const checks = checkDependencies();
+  const missing = checks.filter((c) => !c.present);
+  if (missing.length === 0) {
+    return "All ASF dependencies present: pi-vigilant, pi-smart-web-search, pi-smart-fetch, pi-aia-browser ✓";
+  }
+  return (
+    "⚠️ ASF dependencies missing — install before starting a project:\n" +
+    missing.map((m) => `  - ${m.name}\n    → ${m.hint}`).join("\n")
+  );
+}
+
+// ─── Extension registration ────────────────────────────────────────────────
+
+export default function register(pi: ExtensionAPI): void {
+  // Startup check: warn once per session if deps are missing (unless disabled)
+  // The extension loads at startup; log to console so it surfaces in logs.
+
+  const setPhase = async (ctx: ExtensionCommandContext, phase: AsfPhase, workType?: AsfState["workType"]): Promise<string> => {
+    const project = projectName();
+    const state = await loadState(project);
+    const now = new Date().toISOString();
+
+    if (state.current && phase === "none") {
+      state.history.push({
+        workType: state.current.workType || "unknown",
+        phase: state.current.phase,
+        startedAt: state.current.startedAt || now,
+        endedAt: now,
+      });
+      state.current = null;
+    } else {
+      if (!state.current) {
+        state.current = {
+          workType,
+          phase: "classify",
+          startedAt: now,
+          updatedAt: now,
+        };
+      }
+      if (workType) state.current.workType = workType;
+      state.current.phase = phase;
+      state.current.updatedAt = now;
+    }
+
+    await saveState(project, state);
+    return state.current ? `ASF phase → ${phase}${workType ? ` (${workType})` : ""}` : "ASF session ended.";
+  };
+
+  pi.registerCommand("asf", async (args: string[], ctx: ExtensionCommandContext) => {
+    const sub = (args[0] || "").toLowerCase();
+
+    switch (sub) {
+      case "new":
+        return await setPhase(ctx, "intake", "new-project");
+      case "feature":
+        return await setPhase(ctx, "intake", "feature");
+      case "bugfix":
+        return await setPhase(ctx, "intake", "major-bugfix");
+      case "refactor":
+        return await setPhase(ctx, "intake", "refactor");
+      case "status": {
+        const project = projectName();
+        const state = await loadState(project);
+        if (!state.current) return "No active ASF session.";
+        return (
+          `ASF status (${project}):\n` +
+          `  work type: ${state.current.workType || "unset"}\n` +
+          `  phase: ${state.current.phase}\n` +
+          `  plan approved: ${state.current.planApproved ? "yes" : "no"}\n` +
+          `  started: ${state.current.startedAt || "?"}\n` +
+          `  history: ${state.history.length} completed session(s)`
+        );
+      }
+      case "abort":
+        return await setPhase(ctx, "none");
+      default:
+        return (
+          "ASF commands:\n" +
+          "  /asf new        — start a new software project\n" +
+          "  /asf feature    — add a feature to an existing project\n" +
+          "  /asf bugfix     — major bugfix\n" +
+          "  /asf refactor   — architectural refactor\n" +
+          "  /asf status     — show current phase\n" +
+          "  /asf abort      — end the current session\n\n" +
+          dependencySummary()
+        );
+    }
+  });
+
+  // Plan-approval helper: /asf approve marks the plan as approved (records Gate 5)
+  pi.registerCommand("asf-approve", async (_args: string[], ctx: ExtensionCommandContext) => {
+    const project = projectName();
+    const state = await loadState(project);
+    if (!state.current) return "No active ASF session — start one with /asf new|feature|bugfix|refactor.";
+    state.current.planApproved = true;
+    state.current.updatedAt = new Date().toISOString();
+    await saveState(project, state);
+    return "Plan approved ✓ — Gate 5 passed, implementation may begin.";
+  });
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "pi-aia-asf",
+  "version": "0.1.0",
+  "description": "Ai Applied Agentic Software Factory — codifies the full software development flow: intake, research, spec capture, adversarial analysis, planning with approval gates, test-first implementation, and release. Requires pi-vigilant, pi-smart-web-search, pi-smart-fetch, and pi-aia-browser.",
+  "keywords": [
+    "pi-package",
+    "software-factory",
+    "asf",
+    "specs",
+    "planning"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "author": "Bruno Jakic <bruno@ai-applied.nl>",
+  "homepage": "https://github.com/brunoj/pi-aia-asf#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/brunoj/pi-aia-asf.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brunoj/pi-aia-asf/issues"
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md",
+    "skills/"
+  ],
+  "scripts": {
+    "clean": "echo 'nothing to clean'",
+    "build": "echo 'nothing to build — pi loads .ts via jiti at runtime'",
+    "check": "tsc --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck --allowImportingTsExtensions --noCheck index.ts",
+    "test": "echo 'see https://github.com/brunoj/pi-aia-asf for test suites'",
+    "release": "./scripts/release.sh"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills/aia-asf"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": false
+    },
+    "@earendil-works/pi-agent-core": {
+      "optional": false
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": false
+    },
+    "typebox": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "0.83.0",
+    "@earendil-works/pi-ai": "0.83.0",
+    "@earendil-works/pi-coding-agent": "0.83.0",
+    "typebox": "1.1.38",
+    "typescript": "5.9.3"
+  }
+}

package/skills/aia-asf/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: aia-asf
+description: Agentic Software Factory — run a complete, disciplined software development cycle. Use when the user wants to start a NEW software project, add a SIGNIFICANT FEATURE to an existing project, perform a MAJOR BUGFIX, or do an ARCHITECTURAL REFACTOR. The flow is: classify the work, ask questions until the intent is clear, research SOTA and existing packages, capture hard specifications (via capture_spec, shared with pi-vigilant), run adversarial analysis, produce a PLAN.md and get explicit user approval, then implement test-first with strict codebase isolation and mandatory browser testing of any web interfaces (pi-aia-browser). Do NOT activate for simple Q&A, one-line fixes, casual conversation, content writing, or non-software tasks. When in doubt about whether work qualifies as a project/feature/bugfix/refactor, ask the user.
+---
+
+# AIA Agentic Software Factory (ASF)
+
+You are running the **Ai Applied Agentic Software Factory**. This skill codifies the full development flow used for real projects (conversense, betamaxx, mbee.me, pi-vigilant, and others). Follow the phases strictly, in order. Every phase has an explicit gate — never skip a gate.
+
+> **Dependencies** (verify at Phase 0, warn if missing, do not proceed without them):
+> - `pi-vigilant` — provides `capture_spec`, `get_task_specs`, `update_spec_status` and final-verification. If the tools are not available, tell the user: `pi install npm:pi-vigilant` and `/reload`.
+> - `pi-smart-web-search` / `pi-smart-fetch` — `web_search`, `web_fetch`, `batch_web_fetch` for research. If missing: `pi install npm:pi-smart-web-search npm:pi-smart-fetch`.
+> - `pi-aia-browser` — browser automation (`browser_init`, `browser_navigate`, …) for testing web interfaces. If missing: `pi install npm:pi-aia-browser` (installs Playwright + Chromium automatically).
+
+---
+
+## Phase 0 — Classify the work (gate)
+
+Determine the work type. If it is not ASF work, **do not run the factory** — just help normally.
+
+| Work type | ASF? |
+|---|---|
+| New software project | ✅ yes — full flow |
+| Significant feature in an existing project | ✅ yes — full flow (research: medium depth) |
+| Major bugfix (multi-file, behavior change, needs tests) | ✅ yes — lighter flow (research optional) |
+| Architectural refactor | ✅ yes — full flow (research: low depth) |
+| Simple Q&A, one-liner fix, casual talk, docs-only | ❌ no |
+| Non-software tasks (LinkedIn, research-only, writing) | ❌ no |
+
+If the user's request is ambiguous, **ask** before starting. State the classification explicitly:
+`ASF: <new-project|feature|major-bugfix|refactor> — starting Phase 1 (intake).`
+
+---
+
+## Phase 1 — Intake: ask until it's clear (gate)
+
+The factory **keeps asking until all is clear**. Never start planning or implementation on guesses.
+
+Minimum intake checklist (ask anything not yet known, one question at a time or a short batch):
+
+- **Goal** — what exactly is being built/changed? (one sentence)
+- **Context** — existing system? which repo? what's there today?
+- **Users / audience** — who uses this, and how?
+- **Success criteria** — how will we know it's done and correct? (be concrete)
+- **Constraints** — musts, must-nots, boundaries, budget, timeline
+- **Preferences** — stack, language, platform, style (only if the user has them)
+- **Definition of done** — tests? deploy? release? docs?
+
+For each answer, **capture hard requirements immediately with `capture_spec`** (requirement, area, priority). Specs are the shared contract with pi-vigilant — it will re-verify them at the end.
+
+**Gate 1**: You may only leave intake when the user has confirmed the summary of intent (restate it back in 3–5 bullet points and ask "is this correct?").
+
+---
+
+## Phase 2 — Research: SOTA and packages (adaptive depth)
+
+| Work type | Research depth |
+|---|---|
+| New project | **Mandatory, full** — SOTA approaches, frameworks, existing packages, reference implementations |
+| Significant feature | **Mandatory, medium** — existing packages/libraries, similar features in the wild |
+| Major bugfix | **Optional** — only if the fix changes scope or needs new tech |
+| Refactor | **Low** — best practices for the target architecture |
+
+Research method (use `web_search` + `web_fetch`/`batch_web_fetch`):
+1. Search for the topic + "best practices" / "comparison" / "2026"
+2. Search for existing npm/pip packages: `npm search <topic>` or web search
+3. Fetch the 2–3 most relevant results and extract concrete facts
+4. **Cite sources** in the research summary — every claim about a package/library gets a URL
+5. Summarize findings + a **recommendation** (which approach, which packages, with rationale)
+
+**Gate 2**: present the research summary + recommendation to the user. Ask: "proceed with this approach, or adjust?" Do not enter planning until the approach is agreed.
+
+---
+
+## Phase 3 — Specifications (gate)
+
+Turn the intake answers + research into the authoritative spec set.
+
+1. Run `get_task_specs` to see what's already captured.
+2. Fill gaps: for every requirement the user stated or approved, ensure a spec exists (`capture_spec`).
+3. Decompose broad specs with `parentId` (e.g. "must be secure" → auth + encryption sub-specs).
+4. Default priority is `must`; use `should` only when the user says "nice to have".
+5. Areas: functionality, ui-ux, performance, security, error-handling, testing, documentation, compatibility, constraints, format, data, deployment, other.
+
+**Gate 3**: show the full spec tree (`get_task_specs`) and get user sign-off: "specs correct — proceed to adversarial analysis?"
+
+---
+
+## Phase 4 — Adversarial analysis (gate)
+
+Challenge the plan like a hostile reviewer before committing to it. For each spec and the overall design, ask and resolve:
+
+- **Edge cases** — empty input, zero users, max load, missing data, concurrency
+- **Failure modes** — what breaks, and how do we detect/recover?
+- **Security** — auth, injection, data exposure, abuse
+- **Maintainability** — will this be understandable in 6 months? who maintains it?
+- **Dependencies** — are they maintained? license? size? alternatives?
+- **Scope** — is anything here actually unnecessary? (cut it)
+- **Feasibility** — is the SOTA research consistent with the specs?
+
+For each finding: either capture a new spec, refine an existing one (supersede), or record the decision to accept the risk. **Ask the user about anything that changes scope.**
+
+**Gate 4**: summarize adversarial findings + resolutions, get user confirmation.
+
+---
+
+## Phase 5 — Plan + approval gate
+
+Write `PLAN.md` in the project root (repo root, or cwd if no repo). Structure:
+
+```markdown
+# <Project> — Plan
+
+## Goal
+## Context
+## Approach (from research, cited)
+## Architecture / Design
+## Milestones (M1..Mn with exit criteria)
+## Task list (per milestone, checkboxes)
+## Dependencies (with licenses)
+## Risks & mitigations (from adversarial analysis)
+## Definition of done (tests, deploy, release)
+```
+
+Keep the plan **implementation-ready**: any competent engineer (or agent) can execute the task list without re-deriving decisions.
+
+**Gate 5 — MANDATORY user approval**: present the plan and ask explicitly:
+> "Plan ready. Do you approve starting implementation? (yes / changes needed)"
+
+**Never start implementing before Gate 5 passes.** If the user says "go" without reading, still show the plan and confirm.
+
+---
+
+## Phase 6 — Implementation (test-first, disciplined)
+
+Execute the task list milestone by milestone. Discipline rules:
+
+1. **Test-first**: write/update tests before or with implementation; run them; only commit green.
+2. **Codebase isolation**: work strictly inside the project's own codebase. Do NOT edit files in other repos, global config, or unrelated directories — **unless the user explicitly instructs otherwise**. If a change would touch another codebase, stop and ask.
+3. **No scope creep**: if something new is discovered that changes specs, capture it, ask the user, and update the plan before implementing.
+4. **Descriptive commits**: `git commit -m "type: specific description of what and why"` (e.g. `fix: verify specs before rotation`). No vague messages, no placeholders.
+5. **Browser testing — MANDATORY for any web interface**: if the deliverable has a UI/website/web app, test it through `pi-aia-browser` (`browser_init`, `browser_navigate`, `browser_click`, `browser_type`, `browser_screenshot`, `browser_dom`, …) to replicate the user's real experience — not just curl/API checks. Verify: loads, key user journeys, responsive behavior, console errors.
+6. **Let pi-vigilant do its job**: it will auto-continue after premature stops and verify specs at settle. When it asks for `update_spec_status` with evidence, do it.
+7. **CHANGELOG discipline**: every user-visible change gets a CHANGELOG entry describing exactly what changed (no placeholder text).
+
+---
+
+## Phase 7 — Verification & delivery (gate)
+
+1. Run the full test suite; fix failures; re-run until green.
+2. Run `get_task_specs` and verify **every spec** with `update_spec_status` + concrete evidence (test output, build result, code inspection). Unverifiable → `partial` + ask the user. Never self-certify.
+3. If the project is a library/package that the user publishes (npm, GitHub release): **offer** to run the release (see `references/07-release.md`): version bump, CHANGELOG, git tag, push. **Publishing is always the user's decision** — never publish without explicit approval. Optionally offer to set up a CI/CD pipeline for publishing.
+4. Present a completion summary: what was built, specs met, tests passing, how to use it.
+
+---
+
+## Anti-patterns
+
+- ❌ Starting implementation without Gate 5 approval
+- ❌ Planning on assumptions — always ask
+- ❌ Skipping research for new projects
+- ❌ Editing other codebases without explicit permission
+- ❌ Verifying a UI only via API/curl — browser testing is mandatory
+- ❌ Vague commits or CHANGELOG placeholders
+- ❌ Declaring done while specs are still `open`
+- ❌ Publishing anything without the user's explicit go-ahead
+
+## References
+
+- `references/01-intake.md` — question bank and probing techniques
+- `references/02-research.md` — research playbook with search templates
+- `references/04-adversarial.md` — adversarial checklist per area
+- `references/05-plan.md` — PLAN.md template with examples
+- `references/06-implementation.md` — coding discipline details
+- `references/07-release.md` — release workflow (versioning, CHANGELOG, tags, npm, CI/CD)

package/skills/aia-asf/references/01-intake.md

@@ -0,0 +1,34 @@
+# Phase 1 — Intake: Question Bank
+
+Keep asking until the user confirms. One question at a time is fine; short batches (3–5) are faster. Do not proceed on guesses.
+
+## Starter questions
+
+- "What are we building, in one sentence?"
+- "What problem does it solve, and for whom?"
+- "What exists today?" (blank slate / existing repo / replaces something)
+- "How will we know it's done and correct?" (concrete success criteria)
+- "Any hard constraints?" (stack, platform, budget, timeline, must-nots)
+
+## Probing techniques
+
+- **Five whys**: when the goal is vague, keep asking "why" until the real outcome surfaces.
+- **Concretize**: "what does 'fast' mean — under 200ms?" → convert adjectives to numbers → capture as spec.
+- **Boundary questions**: "what happens when there's no input / 10k users / the API is down?"
+- **Scope confirmation**: "is X in scope for this round, or later?" — write the answer down.
+
+## What to capture as specs (during intake)
+
+Every concrete requirement the user states → `capture_spec` immediately, before responding further. Examples:
+
+| User says | Capture |
+|---|---|
+| "must be in TypeScript" | constraints, must |
+| "handle empty input gracefully" | error-handling, must |
+| "needs to support Firefox and Chrome" | compatibility, must |
+| "should notify admins on failure" | functionality, should (if user says "should") |
+| "output JSON with id and name" | format, must |
+
+## Intake gate
+
+Restate intent in 3–5 bullets, then ask: **"Is this correct?"** Only proceed on an explicit yes.

package/skills/aia-asf/references/02-research.md

@@ -0,0 +1,44 @@
+# Phase 2 — Research Playbook
+
+Goal: decisions based on current facts, with sources. Never plan architecture on memory alone.
+
+## When research is mandatory
+
+- New project: full research
+- Significant feature: medium research (packages/libraries, similar implementations)
+- Major bugfix: only if scope/tech changes
+- Refactor: best practices for target architecture
+
+## Search templates (web_search)
+
+- `<topic> best practices 2026`
+- `<topic> vs <alternative> comparison`
+- `<topic> npm package` / `npm search <topic>` (via bash)
+- `how to implement <feature> <language>`
+- `<framework> <version> release notes`
+- `reference implementation <topic> open source`
+
+## Extraction (web_fetch / batch_web_fetch)
+
+- Fetch the 2–3 most relevant results (batch_web_fetch for parallel).
+- Extract: what it is, version, license, maintenance status, adoption, key trade-offs.
+- For npm packages: check `npm view <pkg>` (version, license, weekly downloads, dependencies) — fast and authoritative.
+
+## Decision criteria for packages
+
+1. License compatible (MIT/Apache preferred)
+2. Maintained (recent release, active issues)
+3. Mature enough (v1+ or widely adopted)
+4. Dependency footprint reasonable
+5. Fits the project's constraints (browser? node? size?)
+
+## Output
+
+Research summary with:
+- **Findings** (each with source URL)
+- **Recommendation** (approach + packages, with rationale)
+- **Alternatives considered** (one line each, why rejected)
+
+## Research gate
+
+Present summary + recommendation → ask: "proceed with this approach, or adjust?" → only proceed on agreement.

package/skills/aia-asf/references/04-adversarial.md

@@ -0,0 +1,31 @@
+# Phase 4 — Adversarial Analysis Checklist
+
+Challenge every spec and design decision like a hostile reviewer. For each item, determine: capture a new spec / supersede an existing one / accept the risk (recorded).
+
+## Per-spec questions
+
+- **Edge cases**: empty input, zero data, max load, missing fields, concurrent access, duplicate input, unicode, huge payloads
+- **Failure modes**: what breaks first? Is failure loud or silent? Can we recover automatically?
+- **Security**: authentication, authorization, injection (SQL/XSS), data exposure, secrets, abuse/rate-limiting, supply chain
+- **Maintainability**: will a new engineer understand this in 6 months? Is the design over-engineered or under-documented?
+- **Dependencies**: license, maintenance, size, security history, lockfile hygiene
+- **Scope**: does anything here NOT need to exist? Cut it (record the cut).
+- **Feasibility**: does the research support the spec? Is the plan's chosen stack proven for this use case?
+
+## Architecture questions
+
+- **Data flow**: what's the full path of a request/event? Where can it fail?
+- **State**: what state exists, where does it live, what happens on restart?
+- **Scaling**: what happens at 10× the expected load?
+- **Rollback**: if this ships and breaks, how do we revert?
+- **Observability**: logs, metrics, errors — can we see it working in production?
+
+## Resolution rules
+
+- Finding → **new spec** (capture_spec) or **spec change** (capture superseding spec; old one becomes obsolete)
+- Accepted risk → write it into the PLAN.md risks section with rationale
+- Scope change → **ask the user before proceeding**
+
+## Adversarial gate
+
+Summarize: findings found, specs added/changed, risks accepted → user confirmation.

package/skills/aia-asf/references/05-plan.md

@@ -0,0 +1,63 @@
+# Phase 5 — PLAN.md Template
+
+Write `PLAN.md` in the project root. It must be executable by any competent engineer without re-deriving decisions.
+
+```markdown
+# <Project> — Plan
+
+Status: DRAFT / APPROVED
+Date: YYYY-MM-DD
+
+## Goal
+One sentence. What are we building and why?
+
+## Context
+Existing system, repo layout, relevant prior work. Links to research sources.
+
+## Approach
+Decided approach with rationale. Cite the research (package names, URLs).
+
+## Architecture / Design
+- Components and their responsibilities
+- Data model / schema (if any)
+- Key flows (request lifecycle, event flow)
+- Interfaces / contracts between components
+
+## Milestones
+| # | Milestone | Exit criteria |
+|---|-----------|---------------|
+| M1 | Scaffold + CI | Repo builds, tests run |
+| M2 | Core feature | Feature works end-to-end (tests pass) |
+| ... | ... | ... |
+
+## Task list
+- [ ] M1: Initialize package (`npm init`, deps)
+- [ ] M1: Set up test runner
+- [ ] M2: Implement <feature> (tests first)
+- [ ] ...
+
+## Dependencies
+| Package | Version | License | Purpose |
+|---------|---------|---------|---------|
+
+## Risks & mitigations
+From adversarial analysis. Each risk: likelihood, impact, mitigation, owner.
+
+## Definition of done
+- [ ] All MUST specs met (pi-vigilant)
+- [ ] Test suite green
+- [ ] Browser-tested if UI involved
+- [ ] CHANGELOG updated
+- [ ] User approved delivery/release
+
+## Out of scope
+Explicitly cut items (so nobody re-adds them).
+```
+
+## Approval gate (MANDATORY)
+
+Present the plan and ask:
+
+> "Plan ready. Do you approve starting implementation? (yes / changes needed)"
+
+Do not implement before explicit approval. If the user says "go", record the plan as APPROVED.

package/skills/aia-asf/references/06-implementation.md

@@ -0,0 +1,56 @@
+# Phase 6 — Implementation Discipline
+
+## Test-first
+
+1. Write the failing test for the next behavior
+2. Implement the minimum to pass
+3. Run the suite; refactor; re-run
+4. Only commit green
+
+For web interfaces, browser tests via pi-aia-browser are part of the test suite, not an afterthought.
+
+## Codebase isolation (STRICT)
+
+- Work **only inside the project's codebase** (the repo the task belongs to).
+- Do NOT modify: other project repos, `~/.pi/agent/`, global config, unrelated directories.
+- If a legitimate need to touch another codebase arises (shared lib, dependency fix): **stop and ask the user**.
+- Exception: the user explicitly instructs otherwise — then note the instruction and proceed.
+
+## Browser testing (MANDATORY for web interfaces)
+
+Any deliverable with a UI/web surface must be verified through the browser to replicate the user's real experience:
+
+1. `browser_init` — start the browser
+2. `browser_navigate` to the app URL (local dev server or deployed)
+3. Walk the key user journeys: `browser_click`, `browser_type`, `browser_navigate`
+4. Verify: page loads, journeys work, console has no errors (`browser_js`), screenshots for record (`browser_screenshot`)
+5. Check responsiveness (desktop + mobile viewport)
+6. `browser_close` when done
+
+API-only verification is NOT sufficient for anything a human would see or click.
+
+## Commit messages
+
+`type: specific description of what and why`
+
+- `feat:` new capability
+- `fix:` bug fix
+- `refactor:` structural change, no behavior change
+- `docs:` documentation
+- `test:` tests
+- `chore:` tooling, deps, release
+
+Examples:
+- ✅ `fix: reset verification cooldown on new user task`
+- ✅ `feat: add rate limiting middleware with 429 responses`
+- ❌ `update stuff`, `fixes`, `wip`
+
+## CHANGELOG
+
+Every user-visible change gets an entry under `## [Unreleased]` or the released version, describing exactly what changed and why. No placeholder text.
+
+## Specs during implementation
+
+- New hard requirement discovered → `capture_spec` immediately
+- Requirement changed → capture superseding spec (old → obsolete)
+- When pi-vigilant injects its verification checklist → respond with `update_spec_status` + evidence

package/skills/aia-asf/references/07-release.md

@@ -0,0 +1,42 @@
+# Phase 7 — Release Workflow
+
+Publishing is **always the user's decision**. The factory prepares everything; the user gives the final go.
+
+## When release applies
+
+- npm packages (pi extensions, libraries)
+- GitHub releases
+- Deployed applications
+- NOT for internal-only experiments the user keeps local
+
+## Steps
+
+1. **Verify first** (mandatory, before any versioning):
+   - typecheck / build passes
+   - test suite green
+   - all MUST specs `met` in pi-vigilant
+2. **Version bump** — semantic versioning:
+   - `patch` (0.1.0 → 0.1.1): bug fixes
+   - `minor` (0.1.0 → 0.2.0): new features, backward compatible
+   - `major` (1.0.0): breaking changes
+3. **CHANGELOG** — move `[Unreleased]` entries into the new version section; describe each change specifically.
+4. **Tag** — `git tag vX.Y.Z`
+5. **Push** — `git push --follow-tags`
+6. **Publish** — only with explicit user approval:
+   - npm: `npm publish` (ensure 2FA token, `npm login` state)
+   - GitHub release: via web or `gh release create` if installed
+
+## CI/CD offer
+
+After a successful release (or for a new project), **offer** to set up a CI/CD pipeline for publishing:
+
+- GitHub Actions: test on push → version + publish on tag/release
+- Requires the user's secrets (npm token, etc.) — never invent credentials
+- Keep it minimal: test job + publish job, gated on tags
+
+## Hygiene rules
+
+- No auto-publish — always explicit user approval
+- Describe changes specifically in CHANGELOG (no placeholders)
+- The version in package.json, the git tag, and the npm release must match
+- If publishing fails partway, fix forward; never publish a second version with the same number