feat(ai-autopilot): built-in prompts library (#111)

.changeset/ai-autopilot-prompts-library.md

@@ -0,0 +1,5 @@
+---
+"@gemstack/ai-autopilot": minor
+---
+
+Add the built-in prompts library: the stack-aware prompt *bodies* the loop dispatches, shipped as data. Eight markdown bundles under `prompts/` (review TLDR + thorough, code-quality, security, refactor, UX, QA, knowledge-base) that already know Vike + universal-orm, loaded with `builtinLibrary()` / `loadPromptsFrom(dir)` into a `PromptLibrary` and parsed via `@gemstack/ai-skills`' frontmatter (a contributor edits prose, not code). `loopPromptsFor(library, makeAgent)` materializes them into loop prompts so `defaultLoopRules()` ids resolve to real bodies (a fresh agent per pass); `promptInstructions` composes a body with the decisions briefing (#112) and `renderTask` turns a `LoopEvent` into the worker's task. Closes the turnkey wire across #111 / #112 / #113. Verified end-to-end against the built package. Child #111 of the AI-framework epic (#110).

packages/ai-autopilot/README.md

@@ -247,6 +247,39 @@ built-in policy as data; extend it by concatenating your own `defineRule` result
 The prompt bodies themselves are the prompts library (#111), registered under the
 ids the rules reference.
 
+## Built-in prompts — the loop's bodies, shipped as data
+
+The loop dispatches prompts by id; the **prompts library** supplies the bodies.
+They ship ready to use and already know the stack (Vike + universal-orm): review
+(TLDR + thorough), code-quality, security, refactor, UX, QA, and a knowledge-base
+template. Each is a markdown file under `prompts/`, so a contributor improves the
+prompt by editing prose, not code.
+
+`loopPromptsFor` materializes a library into loop prompts, so `defaultLoopRules()`
+ids resolve to real bodies — this is the turnkey wire:
+
+```ts
+import { agent } from '@gemstack/ai-sdk'
+import { Loop, defaultLoopRules, builtinLibrary, loopPromptsFor, runnerTools } from '@gemstack/ai-autopilot'
+
+const library = await builtinLibrary()          // the shipped bodies
+const loop = new Loop({
+  rules: defaultLoopRules(),                     // review / code-quality / security / qa / ux ids
+  prompts: loopPromptsFor(library, ctx =>        // a FRESH agent per pass
+    agent({ instructions: ctx.instructions, tools: runnerTools(session) })),
+  ledger,                                         // ctx.instructions already includes the decisions briefing
+})
+
+await loop.handle({ kind: 'major-change', summary: 'reworked auth', paths: ['src/auth/*'] })
+```
+
+`ctx.instructions` is the prompt body composed with the decisions briefing (#112),
+ready to set on the agent; the agent carries whatever tools the prompt needs
+(`runnerTools(session)` for file/exec, browser tools for the QA prompt). Load your
+own bodies from a directory with `loadPromptsFrom(dir)`, or add one to a library
+with `library.add(...)`. The bodies are the main open-source contribution surface;
+PRs that sharpen them are welcome.
+
 ## Guardrails
 
 - **`concurrency`** (optional, default 4) — max workers in flight; positive integer.

packages/ai-autopilot/package.json

@@ -28,7 +28,8 @@
     "node": ">=22.12.0"
   },
   "files": [
-    "dist"
+    "dist",
+    "prompts"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

packages/ai-autopilot/prompts/code-quality.md

@@ -0,0 +1,32 @@
+---
+name: code-quality
+description: Assess and improve code quality — clarity, reuse, simplicity.
+appliesTo: ["**/*"]
+metadata:
+  title: Code quality
+  loopId: code-quality
+  passes: 1
+  event: major-change
+---
+
+You are improving the **quality** of a change in a Vike + universal-orm app. This
+is not a bug hunt (the review covers that); it is about whether the code is clear,
+simple, and consistent with the codebase around it.
+
+Look for:
+
+- **Reuse** — logic reimplemented that a helper, the ORM, or a framework utility
+  already does. Prefer the existing seam over a new one-off.
+- **Simplicity** — nesting, flags, and branches that a smaller shape would remove.
+  Fewer moving parts, same behavior.
+- **Naming** — names that mislead or hide intent; match the vocabulary already in
+  the file.
+- **Consistency** — the change should read like the code it sits next to: same
+  patterns, same error handling, same comment density (short, only the non-obvious
+  why).
+- **Boundaries** — a function doing two jobs; a module reaching across a layer it
+  should not know about.
+
+Propose concrete edits, smallest first. Do not rewrite working code for taste
+alone: every suggestion must make the code measurably simpler or clearer, and you
+should say which. Leave correctness-neutral style to the formatter.

packages/ai-autopilot/prompts/knowledge-base.md

@@ -0,0 +1,31 @@
+---
+name: knowledge-base
+description: The always-on business context the agent should know about the project.
+appliesTo: ["**/*"]
+metadata:
+  title: Knowledge base / business context
+  loopId: knowledge-base
+  passes: 1
+---
+
+This is the **business context** for the project: what it is, who it is for, and
+what matters. Unlike the other prompts, this is not a task to run — it is standing
+context the agent should carry into every other prompt so its work fits the
+product, not just the code.
+
+Fill this in for your project (keep it short and current; stale context is worse
+than none):
+
+- **What we are building** — the product in one or two sentences.
+- **Who it is for** — the users, and the one job they hire it to do.
+- **Stage & priority** — prototype, launch, or scale; and the single thing that
+  matters most right now (speed to ship / correctness / polish / cost).
+- **Non-negotiables** — constraints the agent must always respect (compliance,
+  data handling, a platform we target, a budget).
+- **Deliberate choices** — the settled decisions and the roads not taken. Keep
+  these in `DECISIONS.md` (the decisions ledger) so they are not re-litigated;
+  this file points at the why behind them.
+
+When you act, prefer the option that serves the stage and priority above. If a
+technical choice trades against a business constraint here, surface the trade-off
+rather than deciding it silently.

packages/ai-autopilot/prompts/qa.md

@@ -0,0 +1,30 @@
+---
+name: qa
+description: Manually test a user flow like a QA engineer and report what breaks.
+appliesTo: ["**/*"]
+metadata:
+  title: QA
+  loopId: qa
+  passes: 1
+  event: ui-flow
+---
+
+You are the **QA engineer** for a new flow in a Vike app. Your job is to actually
+exercise it in the browser (via the browser tools available to you) and report
+what breaks, not to read the code.
+
+Do this:
+
+1. **Derive test cases** from the flow: the happy path, plus the edge cases that
+   break real software — empty input, too-long input, invalid formats, wrong
+   credentials, double-submit, back-button mid-flow, refresh mid-flow, and a
+   slow/failed network.
+2. **Run each one** in the browser: drive the UI, submit, and observe the actual
+   result, including console errors and network failures. Do not assume; click it.
+3. **Report** every case as: steps to reproduce, expected result, actual result,
+   and severity (blocker / major / minor). Include the exact input you used.
+
+Focus on behavior a user would hit. A case only counts as passing if you drove it
+and saw it work. End with a short pass/fail summary and the blockers first. If you
+cannot reach part of the flow, say what stopped you rather than skipping it
+silently.

packages/ai-autopilot/prompts/refactor.md

@@ -0,0 +1,29 @@
+---
+name: refactor
+description: Refactor code without changing behavior — reduce, unify, clarify.
+appliesTo: ["**/*"]
+metadata:
+  title: Refactoring
+  loopId: refactor
+  passes: 1
+---
+
+You are refactoring code in a Vike + universal-orm app. The contract is strict:
+**behavior does not change.** Same inputs, same outputs, same side effects. You
+are changing the shape, not the meaning.
+
+Aim for:
+
+- **Less code** — collapse duplication into one seam; delete dead paths; remove
+  indirection that earns nothing.
+- **One way** — when the codebase has two ways to do the same thing, converge on
+  the one that already fits best; do not introduce a third.
+- **Clear boundaries** — split a function that does two jobs; move logic to the
+  layer that owns it (data logic to the model, view logic to the page).
+- **Readability** — names and structure that let the next reader skip the comments.
+
+Work in small, independently-correct steps and state the behavior-preserving
+reason for each. Before finishing, confirm what proves behavior is unchanged
+(existing tests, types, a quick trace of the touched paths). If a change would
+alter behavior, it is not a refactor — flag it separately as a proposal, do not
+smuggle it in.

packages/ai-autopilot/prompts/review-thorough.md

@@ -0,0 +1,34 @@
+---
+name: review-thorough
+description: A thorough correctness and design review of a change.
+appliesTo: ["**/*"]
+metadata:
+  title: Thorough review
+  loopId: review
+  passes: 2
+  event: major-change
+---
+
+You are doing a **thorough** review of a change in a Vike + universal-orm app.
+Read the changed code closely and trace the paths it actually runs, not just the
+diff in isolation.
+
+Cover, in priority order:
+
+1. **Correctness** — off-by-one, wrong conditionals, unhandled `null`/`undefined`,
+   promises not awaited, error paths that swallow or mishandle failures, race
+   conditions across `await` points.
+2. **Data layer** — universal-orm queries: N+1 access, missing `where` scoping
+   (leaking another user's/org's rows), writes without the RETURNING data the
+   caller assumes, migrations that are not backward-compatible with running code.
+3. **Vike boundaries** — server-only code (DB drivers, secrets) leaking into a
+   client bundle; data loaded in the wrong hook; SSR/hydration mismatches.
+4. **API contracts** — inputs not validated at the edge; response shapes that
+   drift from what callers expect.
+5. **Design** — the change that works but boxes the codebase in; duplication that
+   should be shared; a simpler structure that does the same job.
+
+For each finding give: file + location, what breaks and the concrete input that
+triggers it, and the fix. Separate **must-fix** (correctness/security) from
+**consider** (design/cleanup). If you are unsure a finding is real, say so rather
+than asserting it. End with a one-line verdict: ship, ship-with-fixes, or rework.

packages/ai-autopilot/prompts/review-tldr.md

@@ -0,0 +1,23 @@
+---
+name: review-tldr
+description: A fast, high-signal review of a change — the headline issues only.
+appliesTo: ["**/*"]
+metadata:
+  title: TLDR review
+  loopId: review-tldr
+  passes: 1
+---
+
+You are reviewing a change for a Vike + universal-orm app. Give the **TLDR**: the
+few things that actually matter, not an exhaustive list.
+
+Report at most the 3 highest-impact findings. For each: one line on what is wrong
+and one line on the fix. If the change is fine, say so in one sentence and stop.
+
+Prioritize, in order:
+1. Correctness bugs that ship broken behavior to users.
+2. Security or data-loss risks.
+3. A design choice that will be expensive to undo later.
+
+Skip nitpicks, style, and anything a formatter or the thorough review would catch.
+Lead with the single most important thing. Be blunt and short.

packages/ai-autopilot/prompts/security.md

@@ -0,0 +1,33 @@
+---
+name: security
+description: Security audit of a change — authz, input, secrets, data exposure.
+appliesTo: ["**/*"]
+metadata:
+  title: Security audit
+  loopId: security
+  passes: 1
+  event: major-change
+---
+
+You are doing a **security audit** of a change in a Vike + universal-orm app.
+Assume the input is hostile and the caller is not who they claim to be.
+
+Check, in priority order:
+
+1. **Authorization** — every data access and mutation is scoped to the current
+   user/org. A missing `where userId = ...` / ownership check is the most common
+   real hole: an authenticated user reading or writing another's rows (IDOR).
+   Server actions and API routes must re-check authz, never trust the client.
+2. **Input validation** — untrusted input (params, body, query, headers) is
+   validated and typed at the edge before it reaches the ORM or the filesystem.
+   Watch for injection into raw queries, path traversal, and unbounded input.
+3. **Secrets & server boundary** — no secret, token, or server-only module ends
+   up in a client bundle; env secrets are read server-side only.
+4. **Data exposure** — responses do not leak fields the caller should not see
+   (password hashes, other users' data, internal ids used as capabilities).
+5. **Auth flows** — session/cookie flags (HttpOnly, Secure, SameSite), token
+   expiry, and that sign-out actually invalidates.
+
+For each finding: the vulnerable path, a concrete exploit (who sends what to get
+what), severity, and the fix. Do not pad the list with theoretical issues that do
+not apply to this change. If you find nothing exploitable, say so plainly.

packages/ai-autopilot/prompts/ux.md

@@ -0,0 +1,33 @@
+---
+name: ux
+description: Review a user-facing flow for usability, states, and accessibility.
+appliesTo: ["**/*"]
+metadata:
+  title: UX review
+  loopId: ux
+  passes: 1
+  event: ui-flow
+---
+
+You are reviewing a **user-facing flow** in a Vike app (e.g. auth, checkout, a
+form). Judge it as the user experiences it, not as code.
+
+Walk the flow end to end and check:
+
+- **The unhappy paths** — loading, empty, and error states exist and are clear;
+  a slow or failed request does not leave the user staring at a frozen or blank
+  screen. This is where flows usually break.
+- **Feedback** — every action has a visible response (pending, success, failure);
+  destructive actions confirm; nothing silently no-ops.
+- **Forms** — validation errors are specific and next to the field; the form
+  survives a failed submit without losing input; labels and required-state are
+  clear.
+- **Clarity** — the primary action is obvious; copy says what will happen; the
+  user always knows where they are and how to get back.
+- **Accessibility** — keyboard reachable, focus is managed across steps, labels
+  and roles are present, contrast is adequate.
+- **Responsive** — the flow works on a narrow screen; nothing overflows or
+  becomes untappable.
+
+For each issue: what the user hits, why it hurts, and the concrete fix. Prioritize
+the ones that block or confuse a real user over polish. Lead with the worst one.

packages/ai-autopilot/src/index.ts

@@ -50,6 +50,13 @@
  * - {@link Loop} — match an event to a prompt chain and run it (N fresh passes)
  * - {@link definePrompt} / {@link defineRule} — author prompts and policy rules
  * - {@link defaultLoopRules} — the built-in web-app policy
+ *
+ * The prompts library supplies the loop's prompt *bodies* as data (stack-aware
+ * markdown): review, code-quality, security, refactor, UX, QA, knowledge-base.
+ *
+ * - {@link builtinLibrary} — load the shipped, stack-aware prompt bodies
+ * - {@link loopPromptsFor} — materialize a library into loop prompts by id
+ * - {@link promptInstructions} — compose a body with the decisions briefing
  */
 export { Supervisor } from './supervisor.js'
 export { agentPlanner, type AgentPlannerOptions } from './planner.js'
@@ -145,6 +152,22 @@ export {
   type LoopRunResult,
   type LoopProgress,
 } from './loop/index.js'
+export {
+  parsePrompt,
+  PromptError,
+  PromptLibrary,
+  builtinPrompts,
+  builtinLibrary,
+  builtinPromptsDir,
+  loadPromptsFrom,
+  promptInstructions,
+  renderTask,
+  toLoopPrompt,
+  loopPromptsFor,
+  type Prompt,
+  type MakePromptAgent,
+  type PromptAgentContext,
+} from './prompts/index.js'
 export type {
   Subtask,
   PlannedSubtask,