arey-pi 0.4.0 → 0.6.0

package/extensions/arey-pi/core.ts

@@ -56,26 +56,40 @@ export function parseBootstrapFlags(args: string): BootstrapPlan {
   };
 }
 
-export type WorkflowKind = "feature" | "bugfix" | "sync" | "review" | "assess" | string;
+export function shouldActivateAreyPiHarness(prompt: string): boolean {
+  const normalized = prompt.toLowerCase();
+  if (normalized.includes("arey pi harness is active")) return false;
+  return /\barey(?:\s+pi)?\b/.test(normalized);
+}
+
+const evidenceSummary = `Final evidence format:\n- Behaviour/spec impact:\n- Tests/TDD, including test location:\n- Validation commands and results:\n- Quality tooling:\n- Spec sync:\n- Documentation sync:\n- Architecture/ADR/glossary impact:\n- Database/DBML impact:\n- Residual risks:`;
 
-export function workflowMessage(kind: WorkflowKind, args: string): string {
-  const target = args.trim() || "the current repository/task";
-  const common = `Act as the Arey Pi tech lead. Use pi-subagents when available and appropriate. Keep orchestration authority in the parent session, give child agents bounded tasks, and keep one writer in the active worktree at a time. Follow Arey Pi rules, preserve TDD, and report evidence clearly.`;
+export function areyPiHarnessContext(prompt: string): string {
+  const target = prompt.trim() || "the current request";
 
-  switch (kind) {
-    case "feature":
-      return `${common}\n\nRun the Arey Pi feature workflow for: ${target}\n\nExpected flow: arey-pi.spec-author for canonical specs, arey-pi.tdd-implementer for Red-Green-Refactor, arey-pi.spec-syncer for final alignment, and fresh reviewers or arey-pi.engineering-reviewer for adversarial quality review when risk warrants it. Use scout/context-builder/planner first if the codebase context is not clear.`;
-    case "bugfix":
-      return `${common}\n\nRun the Arey Pi bugfix workflow for: ${target}\n\nStart with a regression test that fails for the bug, keep tests outside production source directories by default, implement the minimal high-quality fix, synchronise specs and docs, and review engineering quality.`;
-    case "sync":
-      return `${common}\n\nRun Arey Pi spec and documentation sync for: ${target}\n\nVerify Gherkin, tests, code, DBML, ADRs, glossary, architecture docs, README files, docs, AGENTS.md, skills, prompts, rules, agents, commands, and tooling instructions. End with both a spec status and a documentation status.`;
-    case "review":
-      return `${common}\n\nRun an Arey Pi engineering review for: ${target}\n\nPrefer fresh-context review. Review architecture, code quality, test quality and location, quality tooling, security, privacy, operability, maintainability, and spec/ADR/DBML/documentation concerns. Classify findings by severity.`;
-    case "assess":
-      return `${common}\n\nAssess this repository against Arey Pi Project Readiness. Audit only by default. Produce scores, evidence, blockers, quick wins, and a prioritised improvement plan.`;
-    default:
-      return `${common}\n\nWork on: ${target}`;
-  }
+  return [
+    "Arey Pi harness is active for this request.",
+    "Act as the parent Arey Pi orchestrator: infer intent, choose the workflow, delegate bounded work to specialist subagents when available, then synthesise and finalise.",
+    "Work naturally; do not expose workflow ceremony unless it helps the user.",
+    "Infer the user's intent yourself. The work may be a feature, bugfix, sync, review, assessment, or a mixed task.",
+    "Use the workflow as an internal operating loop: clarify → spec/plan → TDD or audit → sync → review → evidence.",
+    "Select the matching Arey Pi posture:",
+    "- Feature or behaviour change: clarify scope, update/confirm canonical Gherkin first, then preserve Red → Green → Refactor.",
+    "- Bugfix: reproduce with a meaningful failing regression test before production changes.",
+    "- Sync: inspect drift across specs, tests, code, DBML, ADRs, glossary, README, docs, AGENTS.md, skills, prompts, rules, agents, commands, templates, and tooling instructions.",
+    "- Review: perform adversarial engineering review with severity-classified findings.",
+    "- Assessment: audit readiness with evidence, blockers, quick wins, and a prioritised improvement plan.",
+    "Subagents are a first-class part of Arey Pi when available: use arey-pi.spec-author for specs, arey-pi.tdd-implementer for Red → Green → Refactor, arey-pi.spec-syncer for alignment, arey-pi.engineering-reviewer for fresh review, and arey-pi.project-evaluator for readiness assessment.",
+    "Use builtin scout/context-builder/planner/reviewer/oracle agents when they fit the task, especially for discovery, planning, second opinions, and fresh review.",
+    "Keep orchestration in the parent session, give child agents concrete bounded tasks, and keep one writer in the active worktree.",
+    "Tests should live outside production source directories by default.",
+    "Do not rewrite specs to hide implementation defects.",
+    "Report evidence and residual risks clearly before finalising.",
+    "",
+    `User request: ${target}`,
+    "",
+    evidenceSummary,
+  ].join("\n");
 }
 
 export type DoctorReportInput = {
@@ -115,7 +129,7 @@ export function buildDoctorReport(input: DoctorReportInput): string {
     "",
     "## Recommended next step",
     input.installedAgentsCount === input.requiredAgentsCount
-      ? "- Project-local Arey Pi subagents are installed. Use `/arey-feature`, `/arey-bugfix`, `/arey-sync`, `/arey-review`, or natural language."
+      ? "- Project-local Arey Pi subagents are installed. Use natural language such as `Implementa password reset siguiendo Arey Pi`."
       : "- Run `/arey-bootstrap` to install project-local Arey Pi subagents.",
   ].join("\n");
 }

package/extensions/arey-pi/index.ts

@@ -1,273 +1,8 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { fileURLToPath } from "node:url";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import {
-  buildDoctorReport,
-  docsScaffoldFiles,
-  parseBootstrapFlags,
-  requiredAgents,
-  specScaffoldFiles,
-  workflowMessage,
-  type ScaffoldFile,
-} from "./core.ts";
+import { registerBootstrapCommands } from "./bootstrap.ts";
+import { registerWorkflowRuntime } from "./workflow-runtime.ts";
 
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-const agentSourceDir = join(packageRoot, "agents");
-const rulesDir = join(packageRoot, "rules");
-const templatesDir = join(packageRoot, "templates");
-
-function cwdFrom(ctx: unknown): string {
-  const maybe = ctx as { cwd?: string };
-  return maybe.cwd ?? process.cwd();
-}
-
-function fileExists(path: string): boolean {
-  try {
-    return existsSync(path) && statSync(path).isFile();
-  } catch {
-    return false;
-  }
-}
-
-function dirExists(path: string): boolean {
-  try {
-    return existsSync(path) && statSync(path).isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-function copyAgents(targetDir: string, force: boolean): { copied: string[]; skipped: string[]; missing: string[] } {
-  mkdirSync(targetDir, { recursive: true });
-
-  const copied: string[] = [];
-  const skipped: string[] = [];
-  const missing: string[] = [];
-
-  for (const agent of requiredAgents) {
-    const source = join(agentSourceDir, agent);
-    const target = join(targetDir, agent);
-
-    if (!fileExists(source)) {
-      missing.push(agent);
-      continue;
-    }
-
-    if (fileExists(target) && !force) {
-      skipped.push(agent);
-      continue;
-    }
-
-    copyFileSync(source, target);
-    copied.push(agent);
-  }
-
-  return { copied, skipped, missing };
-}
-
-type ScaffoldResult = { created: string[]; skipped: string[] };
-
-function templateContent(name: string): string {
-  return readFileSync(join(templatesDir, name), "utf8");
-}
-
-function writeTemplateIfMissing(file: ScaffoldFile, force: boolean, cwd: string, result: ScaffoldResult) {
-  const target = join(cwd, file.target);
-  mkdirSync(dirname(target), { recursive: true });
-
-  if (fileExists(target) && !force) {
-    result.skipped.push(file.target);
-    return;
-  }
-
-  writeFileSync(target, templateContent(file.template));
-  result.created.push(file.target);
-}
-
-function scaffoldFiles(cwd: string, force: boolean, files: ScaffoldFile[]): ScaffoldResult {
-  const result: ScaffoldResult = { created: [], skipped: [] };
-
-  for (const file of files) {
-    writeTemplateIfMissing(file, force, cwd, result);
-  }
-
-  return result;
-}
-
-function scaffoldSpecs(cwd: string, force: boolean): ScaffoldResult {
-  return scaffoldFiles(cwd, force, specScaffoldFiles);
-}
-
-function scaffoldDocs(cwd: string, force: boolean): ScaffoldResult {
-  return scaffoldFiles(cwd, force, docsScaffoldFiles);
-}
-
-function starterAgentsMd(): string {
-  return templateContent("AGENTS.md");
-}
-
-function sendWorkflow(
-  pi: ExtensionAPI,
-  args: string,
-  ctx: {
-    ui: { notify(message: string, level?: string): void };
-    isIdle(): boolean;
-  },
-  kind: string,
-  usage: string,
-) {
-  if (!args.trim()) {
-    ctx.ui.notify(usage, "warning");
-    return;
-  }
-
-  const message = workflowMessage(kind, args);
-  if (ctx.isIdle()) {
-    pi.sendUserMessage(message);
-  } else {
-    pi.sendUserMessage(message, { deliverAs: "followUp" });
-    ctx.ui.notify("Arey Pi workflow queued as follow-up", "info");
-  }
-}
-
-function packageVersion(): string {
-  try {
-    const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")) as { version?: string };
-    return pkg.version ?? "unknown";
-  } catch {
-    return "unknown";
-  }
-}
-
-export default function areyPi(pi: ExtensionAPI) {
-  pi.registerCommand("arey-doctor", {
-    description: "Check Arey Pi package, project bootstrap, and subagent readiness",
-    handler: async (_args, ctx) => {
-      const cwd = cwdFrom(ctx);
-      const projectAgentDir = join(cwd, ".pi", "agents", "arey-pi");
-      const commands = pi.getCommands();
-      const hasSubagentsCommand = commands.some((command) => command.name.startsWith("subagents-doctor"));
-      const installedAgents = requiredAgents.filter((agent) => fileExists(join(projectAgentDir, agent)));
-      const missingAgents = requiredAgents.filter((agent) => !fileExists(join(projectAgentDir, agent)));
-      const packageAgents = requiredAgents.filter((agent) => fileExists(join(agentSourceDir, agent)));
-      const prompts = commands.filter(
-        (command) => command.source === "prompt" && command.sourceInfo?.source?.includes("arey-pi"),
-      );
-      const skills = commands.filter(
-        (command) => command.source === "skill" && command.sourceInfo?.source?.includes("arey-pi"),
-      );
-
-      const report = buildDoctorReport({
-        packageVersion: packageVersion(),
-        cwd,
-        packageRulesPresent: dirExists(rulesDir),
-        packageTemplatesPresent: dirExists(templatesDir),
-        packageAgentsCount: packageAgents.length,
-        requiredAgentsCount: requiredAgents.length,
-        hasSubagentsCommand,
-        installedAgentsCount: installedAgents.length,
-        hasRootAgentsMd: fileExists(join(cwd, "AGENTS.md")),
-        hasPiSettings: fileExists(join(cwd, ".pi", "settings.json")),
-        promptsCount: prompts.length,
-        skillsCount: skills.length,
-        missingAgents,
-      });
-
-      pi.sendMessage({
-        customType: "arey-pi-doctor",
-        content: report,
-        display: true,
-        details: {},
-      });
-    },
-  });
-
-  pi.registerCommand("arey-bootstrap", {
-    description: "Install Arey Pi subagents and optionally scaffold specs/docs",
-    handler: async (args, ctx) => {
-      const cwd = cwdFrom(ctx);
-      const { force, createAgentsMd, createSpecs, createDocs } = parseBootstrapFlags(args);
-      const targetDir = join(cwd, ".pi", "agents", "arey-pi");
-      const result = copyAgents(targetDir, force);
-      const specsResult = createSpecs ? scaffoldSpecs(cwd, force) : { created: [], skipped: [] };
-      const docsResult = createDocs ? scaffoldDocs(cwd, force) : { created: [], skipped: [] };
-      const agentsMdPath = join(cwd, "AGENTS.md");
-      let agentsMdStatus = "unchanged";
-
-      if (!fileExists(agentsMdPath) && (createAgentsMd || force)) {
-        writeFileSync(agentsMdPath, starterAgentsMd());
-        agentsMdStatus = "created";
-      } else if (fileExists(agentsMdPath) && createAgentsMd && !force) {
-        agentsMdStatus = "skipped existing";
-      }
-
-      const report = [
-        "# Arey Pi Bootstrap",
-        "",
-        `- Target: ${relative(cwd, targetDir)}`,
-        `- Copied agents: ${result.copied.length}`,
-        `- Skipped existing agents: ${result.skipped.length}`,
-        `- Missing package agents: ${result.missing.length}`,
-        `- AGENTS.md: ${agentsMdStatus}`,
-        `- Spec scaffold created: ${specsResult.created.length}`,
-        `- Spec scaffold skipped: ${specsResult.skipped.length}`,
-        `- Docs scaffold created: ${docsResult.created.length}`,
-        `- Docs scaffold skipped: ${docsResult.skipped.length}`,
-        "",
-        "## Copied agents",
-        result.copied.length ? result.copied.map((agent) => `- ${agent}`).join("\n") : "- none",
-        "",
-        "## Skipped agents",
-        result.skipped.length ? result.skipped.map((agent) => `- ${agent}`).join("\n") : "- none",
-        "",
-        "## Created scaffold files",
-        [...specsResult.created, ...docsResult.created].length
-          ? [...specsResult.created, ...docsResult.created].map((path) => `- ${path}`).join("\n")
-          : "- none",
-        "",
-        "## Skipped scaffold files",
-        [...specsResult.skipped, ...docsResult.skipped].length
-          ? [...specsResult.skipped, ...docsResult.skipped].map((path) => `- ${path}`).join("\n")
-          : "- none",
-        "",
-        "Run `/arey-doctor` to verify setup.",
-      ].join("\n");
-
-      pi.sendMessage({
-        customType: "arey-pi-bootstrap",
-        content: report,
-        display: true,
-        details: { agents: result, specs: specsResult, docs: docsResult, agentsMd: agentsMdStatus },
-      });
-    },
-  });
-
-  pi.registerCommand("arey-feature", {
-    description: "Run an Arey Pi spec-to-TDD feature workflow",
-    handler: async (args, ctx) => sendWorkflow(pi, args, ctx, "feature", "Usage: /arey-feature <feature request>"),
-  });
-
-  pi.registerCommand("arey-bugfix", {
-    description: "Run an Arey Pi regression-test-first bugfix workflow",
-    handler: async (args, ctx) => sendWorkflow(pi, args, ctx, "bugfix", "Usage: /arey-bugfix <bug description>"),
-  });
-
-  pi.registerCommand("arey-sync", {
-    description: "Run Arey Pi spec, test, code, DBML, ADR, and glossary sync",
-    handler: async (args, ctx) =>
-      sendWorkflow(pi, args || "the current repository", ctx, "sync", "Usage: /arey-sync [scope]"),
-  });
-
-  pi.registerCommand("arey-review", {
-    description: "Run an Arey Pi adversarial engineering review",
-    handler: async (args, ctx) =>
-      sendWorkflow(pi, args || "the current diff", ctx, "review", "Usage: /arey-review [scope]"),
-  });
-
-  pi.registerCommand("arey-assess", {
-    description: "Assess project readiness against Arey Pi rules",
-    handler: async (args, ctx) =>
-      sendWorkflow(pi, args || "the current repository", ctx, "assess", "Usage: /arey-assess [scope]"),
-  });
+export default function areyPi(pi: ExtensionAPI): void {
+  registerBootstrapCommands(pi);
+  registerWorkflowRuntime(pi);
 }

package/extensions/arey-pi/paths.ts

@@ -0,0 +1,28 @@
+import { existsSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const packageRoot = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
+export const agentSourceDir = join(packageRoot, "agents");
+export const rulesDir = join(packageRoot, "rules");
+export const templatesDir = join(packageRoot, "templates");
+
+export function cwdFrom(ctx: { cwd: string }): string {
+  return ctx.cwd;
+}
+
+export function fileExists(path: string): boolean {
+  try {
+    return existsSync(path) && statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+export function dirExists(path: string): boolean {
+  try {
+    return existsSync(path) && statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/extensions/arey-pi/workflow-runtime.ts

@@ -0,0 +1,112 @@
+import {
+  isToolCallEventType,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ToolCallEvent,
+  type ToolCallEventResult,
+} from "@earendil-works/pi-coding-agent";
+import { areyPiHarnessContext, shouldActivateAreyPiHarness } from "./core.ts";
+
+const areyPiSessionEntryType = "arey-pi-session";
+
+type HarnessSessionData = { active: boolean };
+type HarnessStore = { active: boolean };
+type SessionEntry = ReturnType<ExtensionContext["sessionManager"]["getEntries"]>[number];
+type CustomSessionEntry = Extract<SessionEntry, { type: "custom" }>;
+type HarnessCustomEntry = CustomSessionEntry & { customType: typeof areyPiSessionEntryType };
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function isHarnessSessionData(value: unknown): value is HarnessSessionData {
+  return isObject(value) && typeof value.active === "boolean";
+}
+
+function isHarnessCustomEntry(value: unknown): value is HarnessCustomEntry {
+  return isObject(value) && value.type === "custom" && value.customType === areyPiSessionEntryType;
+}
+
+function latestHarnessSessionState(ctx: ExtensionContext): boolean {
+  const entry = ctx.sessionManager.getEntries().filter(isHarnessCustomEntry).at(-1);
+  return entry && isHarnessSessionData(entry.data) ? entry.data.active : false;
+}
+
+function persistHarnessState(pi: ExtensionAPI, active: boolean): void {
+  pi.appendEntry(areyPiSessionEntryType, { active } satisfies HarnessSessionData);
+}
+
+function updateHarnessUi(active: boolean, ctx: ExtensionContext): void {
+  ctx.ui.setStatus("arey-pi", active ? ctx.ui.theme.fg("accent", "Arey Pi") : undefined);
+  ctx.ui.setWidget(
+    "arey-pi-harness",
+    active
+      ? [
+          "Arey Pi active: natural-language harness guidance is injected.",
+          "The agent infers feature/bugfix/sync/review/assessment intent.",
+        ]
+      : undefined,
+  );
+}
+
+function activateHarness(pi: ExtensionAPI, store: HarnessStore, ctx: ExtensionContext): void {
+  store.active = true;
+  persistHarnessState(pi, true);
+  updateHarnessUi(true, ctx);
+}
+
+function isSensitivePath(path: string): boolean {
+  return [".env", ".git/", "node_modules/"].some((protectedPath) => path.includes(protectedPath));
+}
+
+function editedPath(event: ToolCallEvent): string | undefined {
+  if (isToolCallEventType("write", event) || isToolCallEventType("edit", event)) {
+    return event.input.path;
+  }
+
+  return undefined;
+}
+
+function handleMutationGuardrails(
+  store: HarnessStore,
+  event: ToolCallEvent,
+  ctx: ExtensionContext,
+): ToolCallEventResult | undefined {
+  const path = editedPath(event);
+  if (!path) return undefined;
+
+  if (isSensitivePath(path)) {
+    ctx.ui.notify(`Blocked write to protected path: ${path}`, "warning");
+    return { block: true, reason: `Arey Pi guardrail: path is protected: ${path}` };
+  }
+
+  if (!store.active) return undefined;
+
+  return undefined;
+}
+
+export function registerWorkflowRuntime(pi: ExtensionAPI): void {
+  const store: HarnessStore = { active: false };
+
+  pi.on("session_start", (_event, ctx) => {
+    store.active = latestHarnessSessionState(ctx);
+    updateHarnessUi(store.active, ctx);
+  });
+
+  pi.on("before_agent_start", (event, ctx) => {
+    const requestedAreyPi = shouldActivateAreyPiHarness(event.prompt);
+    if (!store.active && !requestedAreyPi) return undefined;
+    if (requestedAreyPi) activateHarness(pi, store, ctx);
+
+    return {
+      message: {
+        customType: "arey-pi-harness-context",
+        content: areyPiHarnessContext(event.prompt),
+        display: false,
+        details: { source: requestedAreyPi ? "natural-language" : "active-session" },
+      },
+    };
+  });
+
+  pi.on("tool_call", (event, ctx) => handleMutationGuardrails(store, event, ctx));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arey-pi",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "A Pi package for canonical Gherkin specs, non-negotiable TDD, spec synchronisation, AI harness readiness, and senior-quality software delivery.",
   "license": "MIT",
   "author": "Alejandro Rey Leyva",

package/prompts/adr-review.md

@@ -0,0 +1,33 @@
+---
+description: Decide whether a change needs an ADR and review ADR quality
+argument-hint: "[decision or change]"
+---
+
+Assess ADR impact for:
+
+$ARGUMENTS
+
+Inspect relevant specs, architecture docs, existing ADRs, README/docs, tests, and implementation context.
+
+Determine whether the change records a significant technical decision because it affects architecture, data model, security model, operability, public contracts, deployment, dependency strategy, or long-term maintainability.
+
+If an ADR is needed:
+
+- propose the ADR title and location under `specs/decisions/`;
+- capture context, decision, alternatives considered, consequences, risks, and follow-up work;
+- keep the decision durable and independent of transient implementation details;
+- update glossary, DBML, architecture docs, or README when affected.
+
+If no ADR is needed, explain why.
+
+Return:
+
+```txt
+ADR assessment:
+- Decision/change reviewed:
+- ADR required: yes/no
+- Evidence:
+- Proposed ADR changes:
+- Architecture/docs/glossary/DBML impact:
+- Open questions:
+```

package/prompts/engineering-review.md

@@ -0,0 +1,37 @@
+---
+description: Run an adversarial Arey Pi engineering review
+argument-hint: "[scope]"
+---
+
+Run an adversarial Arey Pi engineering review for:
+
+$ARGUMENTS
+
+Prefer fresh-context review and use `arey-pi.engineering-reviewer` when available.
+
+Review:
+
+- correctness and behavioural completeness;
+- architecture and code quality;
+- test quality, meaningful assertions, and test location;
+- TDD evidence where behaviour changed;
+- formatter/lint/static analysis/typecheck/test/coverage evidence;
+- security, privacy, reliability, operability, and maintainability;
+- generated-code risks;
+- spec, ADR, DBML, glossary, README, docs, AGENTS.md, skills, prompts, rules, agents, commands, and tooling sync.
+
+Do not modify files unless explicitly asked to fix findings.
+
+Return:
+
+```txt
+Engineering review:
+- Scope:
+- Blocking findings:
+- Major findings:
+- Minor findings:
+- Positive evidence:
+- Missing validation:
+- Sync concerns:
+- Recommended next actions:
+```

package/prompts/feature-spec.md

@@ -0,0 +1,35 @@
+---
+description: Draft or update canonical Arey Pi Gherkin specs for a feature
+argument-hint: "<feature request>"
+---
+
+Draft or update canonical Arey Pi feature specs for:
+
+$ARGUMENTS
+
+Work in spec-first mode.
+
+Requirements:
+
+- inspect existing `specs/features/`, glossary, ADRs, docs, tests, and related code before writing;
+- identify actors, business terms, rules, assumptions, non-goals, edge cases, and open questions;
+- write behaviour-focused Gherkin, not UI or implementation scripts;
+- prefer `Rule` sections and concrete examples where they clarify intent;
+- update glossary, ADR, DBML, architecture docs, or README only when affected;
+- do not change production code;
+- if requirements are ambiguous, ask focused questions instead of inventing policy.
+
+Prefer using `arey-pi.spec-author` when available.
+
+Return:
+
+```txt
+Spec handoff:
+- Feature scope:
+- Files read:
+- Specs added/updated:
+- Scenarios/rules covered:
+- Open questions:
+- Test implications:
+- ADR/DBML/glossary/docs impact:
+```

package/prompts/red-green-refactor.md

@@ -0,0 +1,34 @@
+---
+description: Implement accepted behaviour with strict Arey Pi Red-Green-Refactor
+argument-hint: "<accepted behaviour or spec>"
+---
+
+Implement the accepted behaviour through strict Arey Pi TDD:
+
+$ARGUMENTS
+
+Rules:
+
+- read applicable specs, tests, code, AGENTS.md, and quality tooling first;
+- add or update a meaningful failing test before production behaviour changes;
+- keep tests outside production source directories by default;
+- implement the smallest high-quality production change to pass;
+- refactor only while tests remain green;
+- run formatter, lint/static analysis, typecheck, tests, and coverage/mutation checks where relevant and available;
+- do not claim TDD if the Red phase cannot be demonstrated.
+
+Prefer using `arey-pi.tdd-implementer` when available.
+
+Return:
+
+```txt
+Red-Green-Refactor report:
+- Behaviour implemented:
+- Tests added/updated and location:
+- Red evidence:
+- Green evidence:
+- Refactor notes:
+- Validation commands and results:
+- Spec/docs/ADR/DBML/glossary impact:
+- Residual risks:
+```