arey-pi 0.2.0 → 0.3.0

package/README.md

@@ -25,7 +25,7 @@ Arey Pi is built around these guarantees:
 - behaviour is captured in canonical Gherkin specs;
 - database projects keep canonical DBML specs precisely synchronised;
 - TDD is mandatory for production behaviour changes;
-- tests must be meaningful, reviewed, and strengthened with coverage or mutation testing where risk warrants it;
+- tests must be meaningful, reviewed, kept outside production source directories, and strengthened with coverage or mutation testing where risk warrants it;
 - architecture and code must meet a senior engineering quality bar;
 - significant technical decisions are captured in high-quality ADRs;
 - specs, tests, code, DBML, ADRs, glossary, and architecture docs stay synchronised;
@@ -38,10 +38,12 @@ Arey Pi is built around these guarantees:
 
 ```txt
 agents/      # Arey Pi subagent role definitions for pi-subagents
-extensions/  # Slash commands for doctor, bootstrap, and workflows
+extensions/  # Directory-style Pi extension for doctor, bootstrap, and workflows
+docs/        # Package documentation
 skills/      # On-demand Arey Pi workflows and instructions
 prompts/     # Reusable Pi prompt workflows
 rules/       # Arey Pi operating rules
+templates/   # Bootstrap templates for AGENTS.md, specs, ADRs, DBML, glossary, and reports
 ```
 
 The rules are the policy layer.
@@ -125,9 +127,12 @@ Arey Pi includes a polished extension-backed workflow:
 
 ```txt
 /arey-doctor      # check package, subagent, prompt, skill, and project readiness setup
-/arey-bootstrap   # install project-local Arey Pi agents
+/arey-bootstrap   # full safe bootstrap: agents, AGENTS.md, specs, docs, and templates
 /arey-bootstrap --agentsmd  # also create a starter AGENTS.md if missing
-/arey-bootstrap --force     # overwrite existing project-local Arey Pi agents
+/arey-bootstrap --specs     # scaffold starter specs directories and glossary
+/arey-bootstrap --docs      # scaffold starter docs directory
+/arey-bootstrap --full      # explicit alias for the default full bootstrap
+/arey-bootstrap --force     # full bootstrap and overwrite selected project-local files
 /arey-feature     # run spec → TDD → sync → review for a feature
 /arey-bugfix      # run regression-test-first bug fixing
 /arey-sync        # verify specs, docs, tests, code, DBML, ADRs, and glossary alignment
@@ -147,10 +152,11 @@ Arey Pi uses Bun as its package manager and Biome for extension formatting and l
 ```bash
 bun install
 bun run format
+bun run test
 bun run check
 ```
 
-`bun run check` runs Biome linting and TypeScript type checking.
+`bun run check` runs Biome linting, TypeScript type checking, and Bun tests.
 
 ## Rule categories
 

package/agents/engineering-reviewer.md

@@ -44,6 +44,7 @@ Check:
 - whether domain concepts and contracts are explicit;
 - whether error handling, security, privacy, and edge cases are appropriate;
 - whether tests assert behaviour and would catch plausible regressions;
+- whether tests are kept in a dedicated test/spec directory rather than colocated with production source files without justification;
 - whether quality tooling ran and is sufficient for project risk;
 - whether durable decisions require ADRs;
 - whether DBML, Gherkin, glossary, architecture docs, README files, docs, AGENTS.md, skills, prompts, rules, agents, commands, or tooling instructions may need sync;
@@ -69,7 +70,7 @@ Return:
 Engineering review:
 - Blocking findings:
 - High/medium/low findings:
-- Test quality:
+- Test quality and location:
 - Tooling/validation:
 - Architecture/code quality:
 - Security/privacy/operability:

package/agents/tdd-implementer.md

@@ -22,6 +22,7 @@ Own:
 
 - deriving tests from accepted specs, bug reports, or explicit requirements;
 - writing failing tests before production behaviour;
+- placing tests in a dedicated test/spec directory outside production source trees by default;
 - implementing the smallest high-quality production change that satisfies the tests;
 - refactoring after tests pass;
 - keeping tests meaningful and behaviour-focused;
@@ -56,6 +57,9 @@ If you cannot demonstrate Red-Green-Refactor because of project constraints, sta
 Tests must constrain behaviour.
 They should cover important success paths, edge cases, failure paths, permissions, contracts, and regressions where relevant.
 
+Tests must not be colocated beside production files in `src/` or equivalent source directories unless an existing project convention, framework constraint, or user-approved exception requires it.
+Prefer mirroring production module structure under `tests/`, `test/`, `__tests__/`, or `spec/`.
+
 Weak tests are not acceptable evidence merely because they pass.
 Use mutation testing, coverage, or explicit test review where appropriate to risk.
 
@@ -71,7 +75,7 @@ Return:
 ```txt
 Implementation handoff:
 - Changed files:
-- Tests added/updated:
+- Tests added/updated and location:
 - Red-Green-Refactor evidence:
 - Validation commands:
 - Spec impact:

package/docs/commands.md

@@ -1,6 +1,7 @@
 # Arey Pi Commands
 
 Arey Pi ships a Pi extension that registers native slash commands.
+The extension uses Pi's documented directory style at `extensions/arey-pi/index.ts`.
 
 The commands are designed for two modes of use:
 
@@ -11,7 +12,7 @@ The commands are designed for two modes of use:
 
 ```txt
 /arey-doctor
-/arey-bootstrap [--agentsmd] [--force]
+/arey-bootstrap [--agentsmd] [--specs] [--docs] [--full] [--force]
 /arey-feature <feature request>
 /arey-bugfix <bug description>
 /arey-sync [scope]
@@ -28,6 +29,7 @@ It reports:
 - Arey Pi package version;
 - current project path;
 - whether packaged rules are present;
+- whether packaged templates are present;
 - whether packaged agents are present;
 - whether `pi-subagents` appears to be installed;
 - whether project-local Arey Pi agents exist in `.pi/agents/arey-pi/`;
@@ -49,15 +51,23 @@ or when subagent workflows are not behaving as expected.
 
 ## `/arey-bootstrap`
 
-Installs Arey Pi's packaged subagent definitions into the current project.
+Installs Arey Pi's packaged subagent definitions into the current project and performs a safe starter scaffold.
 
-Default target:
+With no flags, `/arey-bootstrap` runs the full bootstrap path:
+
+```txt
+--agentsmd --specs --docs
+```
+
+Default agent target:
 
 ```txt
 .pi/agents/arey-pi/
 ```
 
-By default, existing project-local agent files are not overwritten.
+By default, existing project-local agent files and scaffold files are not overwritten.
+Starter scaffold files are copied from the packaged `templates/` directory.
+Selective flags are available when you only want one part of the scaffold.
 
 Usage:
 
@@ -65,6 +75,24 @@ Usage:
 /arey-bootstrap
 ```
 
+This creates or installs, where missing:
+
+```txt
+.pi/agents/arey-pi/
+AGENTS.md
+specs/README.md
+specs/features/README.md
+specs/features/example.feature
+specs/database/README.md
+specs/database/schema.dbml
+specs/architecture/README.md
+specs/decisions/README.md
+specs/decisions/0001-record-architecture-decision.md
+specs/glossary.md
+docs/README.md
+docs/project-readiness-report.md
+```
+
 Options:
 
 ```txt
@@ -73,13 +101,61 @@ Options:
 
 Also creates a starter root `AGENTS.md` when one does not already exist.
 
+```txt
+/arey-bootstrap --specs
+```
+
+Creates starter Arey Pi spec structure when files do not already exist:
+
+```txt
+specs/README.md
+specs/features/README.md
+specs/features/example.feature
+specs/database/README.md
+specs/database/schema.dbml
+specs/architecture/README.md
+specs/decisions/README.md
+specs/decisions/0001-record-architecture-decision.md
+specs/glossary.md
+```
+
+```txt
+/arey-bootstrap --docs
+```
+
+Creates starter project documentation structure when files do not already exist:
+
+```txt
+docs/README.md
+docs/project-readiness-report.md
+```
+
+```txt
+/arey-bootstrap --full
+```
+
+Explicitly runs the same combined bootstrap path as `/arey-bootstrap` with no flags:
+
+```txt
+--agentsmd --specs --docs
+```
+
 ```txt
 /arey-bootstrap --force
 ```
 
-Overwrites existing project-local Arey Pi agent files.
+Overwrites existing project-local Arey Pi agent files and scaffold files selected by the other flags.
+When used alone, it applies to the default full bootstrap path.
 It also creates a starter `AGENTS.md` when one does not already exist.
 
+Examples:
+
+```txt
+/arey-bootstrap --specs --docs
+/arey-bootstrap --full
+/arey-bootstrap --full --force
+```
+
 Use this command after installing Arey Pi and `pi-subagents` in a repository where you want the Arey Pi agents to be discoverable by `pi-subagents`.
 
 ## `/arey-feature`

package/extensions/arey-pi/core.ts

@@ -0,0 +1,121 @@
+export const requiredAgents = [
+  "tech-lead.md",
+  "spec-author.md",
+  "tdd-implementer.md",
+  "spec-syncer.md",
+  "engineering-reviewer.md",
+  "project-evaluator.md",
+] as const;
+
+export type ScaffoldFile = { template: string; target: string };
+
+export const specScaffoldFiles: ScaffoldFile[] = [
+  { template: "specs-readme.md", target: "specs/README.md" },
+  { template: "features-readme.md", target: "specs/features/README.md" },
+  { template: "feature.feature", target: "specs/features/example.feature" },
+  { template: "database-readme.md", target: "specs/database/README.md" },
+  { template: "database.dbml", target: "specs/database/schema.dbml" },
+  { template: "architecture-readme.md", target: "specs/architecture/README.md" },
+  { template: "decisions-readme.md", target: "specs/decisions/README.md" },
+  { template: "adr.md", target: "specs/decisions/0001-record-architecture-decision.md" },
+  { template: "glossary.md", target: "specs/glossary.md" },
+];
+
+export const docsScaffoldFiles: ScaffoldFile[] = [
+  { template: "docs-readme.md", target: "docs/README.md" },
+  { template: "project-readiness-report.md", target: "docs/project-readiness-report.md" },
+];
+
+const selectiveBootstrapFlags = ["--agentsmd", "--specs", "--docs", "--full"];
+
+export type BootstrapPlan = {
+  flags: string[];
+  force: boolean;
+  full: boolean;
+  defaultFullBootstrap: boolean;
+  createAgentsMd: boolean;
+  createSpecs: boolean;
+  createDocs: boolean;
+};
+
+export function parseBootstrapFlags(args: string): BootstrapPlan {
+  const flags = args.split(/\s+/).filter(Boolean);
+  const force = flags.includes("--force");
+  const full = flags.includes("--full");
+  const hasSelectiveScaffoldFlag = flags.some((flag) => selectiveBootstrapFlags.includes(flag));
+  const defaultFullBootstrap = !hasSelectiveScaffoldFlag;
+
+  return {
+    flags,
+    force,
+    full,
+    defaultFullBootstrap,
+    createAgentsMd: defaultFullBootstrap || flags.includes("--agentsmd") || full,
+    createSpecs: defaultFullBootstrap || flags.includes("--specs") || full,
+    createDocs: defaultFullBootstrap || flags.includes("--docs") || full,
+  };
+}
+
+export type WorkflowKind = "feature" | "bugfix" | "sync" | "review" | "assess" | string;
+
+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. Follow Arey Pi rules, preserve TDD, and report evidence clearly.`;
+
+  switch (kind) {
+    case "feature":
+      return `${common}\n\nRun the Arey Pi feature workflow for: ${target}\n\nExpected flow: spec-author for canonical specs, tdd-implementer for Red-Green-Refactor, spec-syncer for final alignment, and engineering-reviewer for adversarial quality review when risk warrants it.`;
+    case "bugfix":
+      return `${common}\n\nRun the Arey Pi bugfix workflow for: ${target}\n\nStart with a regression test that fails for the bug, then implement the minimal high-quality fix, synchronise specs, 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\nReview architecture, code quality, test quality, quality tooling, security, privacy, operability, maintainability, and spec/ADR/DBML 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}`;
+  }
+}
+
+export type DoctorReportInput = {
+  packageVersion: string;
+  cwd: string;
+  packageRulesPresent: boolean;
+  packageTemplatesPresent: boolean;
+  packageAgentsCount: number;
+  requiredAgentsCount: number;
+  hasSubagentsCommand: boolean;
+  installedAgentsCount: number;
+  hasRootAgentsMd: boolean;
+  hasPiSettings: boolean;
+  promptsCount: number;
+  skillsCount: number;
+  missingAgents: string[];
+};
+
+export function buildDoctorReport(input: DoctorReportInput): string {
+  return [
+    "# Arey Pi Doctor",
+    "",
+    `- Package: arey-pi@${input.packageVersion}`,
+    `- Project: ${input.cwd}`,
+    `- Package rules present: ${input.packageRulesPresent ? "yes" : "no"}`,
+    `- Package templates present: ${input.packageTemplatesPresent ? "yes" : "no"}`,
+    `- Package agents present: ${input.packageAgentsCount}/${input.requiredAgentsCount}`,
+    `- pi-subagents command detected: ${input.hasSubagentsCommand ? "yes" : "no"}`,
+    `- Project-local Arey Pi agents: ${input.installedAgentsCount}/${input.requiredAgentsCount}`,
+    `- Root AGENTS.md: ${input.hasRootAgentsMd ? "yes" : "no"}`,
+    `- .pi/settings.json: ${input.hasPiSettings ? "yes" : "no"}`,
+    `- Arey Pi prompts discovered: ${input.promptsCount}`,
+    `- Arey Pi skills discovered: ${input.skillsCount}`,
+    "",
+    "## Missing project agents",
+    input.missingAgents.length ? input.missingAgents.map((agent) => `- ${agent}`).join("\n") : "- none",
+    "",
+    "## 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."
+      : "- Run `/arey-bootstrap` to install project-local Arey Pi subagents.",
+  ].join("\n");
+}

package/extensions/{arey-pi.ts → arey-pi/index.ts}

@@ -2,18 +2,20 @@ import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileS
 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";
 
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
 const agentSourceDir = join(packageRoot, "agents");
 const rulesDir = join(packageRoot, "rules");
-const requiredAgents = [
-  "tech-lead.md",
-  "spec-author.md",
-  "tdd-implementer.md",
-  "spec-syncer.md",
-  "engineering-reviewer.md",
-  "project-evaluator.md",
-];
+const templatesDir = join(packageRoot, "templates");
 
 function cwdFrom(ctx: unknown): string {
   const maybe = ctx as { cwd?: string };
@@ -64,52 +66,45 @@ function copyAgents(targetDir: string, force: boolean): { copied: string[]; skip
   return { copied, skipped, missing };
 }
 
-function starterAgentsMd(): string {
-  return `# Agent Instructions
+type ScaffoldResult = { created: string[]; skipped: string[] };
+
+function templateContent(name: string): string {
+  return readFileSync(join(templatesDir, name), "utf8");
+}
 
-This project uses Arey Pi.
+function writeTemplateIfMissing(file: ScaffoldFile, force: boolean, cwd: string, result: ScaffoldResult) {
+  const target = join(cwd, file.target);
+  mkdirSync(dirname(target), { recursive: true });
 
-## Delivery rules
+  if (fileExists(target) && !force) {
+    result.skipped.push(file.target);
+    return;
+  }
 
-- Treat canonical specs as the source of truth.
-- Use Gherkin for behaviour specs.
-- Use DBML for database specs when the project has persistence.
-- Follow TDD for production behaviour changes.
-- Keep specs, tests, code, DBML, ADRs, glossary, and architecture docs synchronised.
-- Capture significant technical decisions in high-quality ADRs.
-- Run formatter, lint/static analysis, typecheck, tests, and relevant dynamic analysis where available.
-- Use incremental Conventional Commits for meaningful steps.
+  writeFileSync(target, templateContent(file.template));
+  result.created.push(file.target);
+}
 
-## Subagents
+function scaffoldFiles(cwd: string, force: boolean, files: ScaffoldFile[]): ScaffoldResult {
+  const result: ScaffoldResult = { created: [], skipped: [] };
 
-Project-local Arey Pi subagents live in:
+  for (const file of files) {
+    writeTemplateIfMissing(file, force, cwd, result);
+  }
 
-\`\`\`txt
-.pi/agents/arey-pi/
-\`\`\`
+  return result;
+}
 
-Use them through pi-subagents when available.
-`;
+function scaffoldSpecs(cwd: string, force: boolean): ScaffoldResult {
+  return scaffoldFiles(cwd, force, specScaffoldFiles);
 }
 
-function workflowMessage(kind: string, 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. Follow Arey Pi rules, preserve TDD, and report evidence clearly.`;
-
-  switch (kind) {
-    case "feature":
-      return `${common}\n\nRun the Arey Pi feature workflow for: ${target}\n\nExpected flow: spec-author for canonical specs, tdd-implementer for Red-Green-Refactor, spec-syncer for final alignment, and engineering-reviewer for adversarial quality review when risk warrants it.`;
-    case "bugfix":
-      return `${common}\n\nRun the Arey Pi bugfix workflow for: ${target}\n\nStart with a regression test that fails for the bug, then implement the minimal high-quality fix, synchronise specs, 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\nReview architecture, code quality, test quality, quality tooling, security, privacy, operability, maintainability, and spec/ADR/DBML 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}`;
-  }
+function scaffoldDocs(cwd: string, force: boolean): ScaffoldResult {
+  return scaffoldFiles(cwd, force, docsScaffoldFiles);
+}
+
+function starterAgentsMd(): string {
+  return templateContent("AGENTS.md");
 }
 
 function sendWorkflow(
@@ -163,28 +158,21 @@ export default function areyPi(pi: ExtensionAPI) {
         (command) => command.source === "skill" && command.sourceInfo?.source?.includes("arey-pi"),
       );
 
-      const report = [
-        "# Arey Pi Doctor",
-        "",
-        `- Package: arey-pi@${packageVersion()}`,
-        `- Project: ${cwd}`,
-        `- Package rules present: ${dirExists(rulesDir) ? "yes" : "no"}`,
-        `- Package agents present: ${packageAgents.length}/${requiredAgents.length}`,
-        `- pi-subagents command detected: ${hasSubagentsCommand ? "yes" : "no"}`,
-        `- Project-local Arey Pi agents: ${installedAgents.length}/${requiredAgents.length}`,
-        `- Root AGENTS.md: ${fileExists(join(cwd, "AGENTS.md")) ? "yes" : "no"}`,
-        `- .pi/settings.json: ${fileExists(join(cwd, ".pi", "settings.json")) ? "yes" : "no"}`,
-        `- Arey Pi prompts discovered: ${prompts.length}`,
-        `- Arey Pi skills discovered: ${skills.length}`,
-        "",
-        "## Missing project agents",
-        missingAgents.length ? missingAgents.map((agent) => `- ${agent}`).join("\n") : "- none",
-        "",
-        "## Recommended next step",
-        installedAgents.length === requiredAgents.length
-          ? "- Project-local Arey Pi subagents are installed. Use `/arey-feature`, `/arey-bugfix`, `/arey-sync`, `/arey-review`, or natural language."
-          : "- Run `/arey-bootstrap` to install project-local Arey Pi subagents.",
-      ].join("\n");
+      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",
@@ -196,19 +184,22 @@ export default function areyPi(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("arey-bootstrap", {
-    description: "Install Arey Pi project-local subagents and optional starter AGENTS.md",
+    description: "Install Arey Pi subagents and optionally scaffold specs/docs",
     handler: async (args, ctx) => {
       const cwd = cwdFrom(ctx);
-      const force = args.split(/\s+/).includes("--force");
-      const createAgentsMd = args.split(/\s+/).includes("--agentsmd");
+      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 = [
@@ -219,13 +210,27 @@ export default function areyPi(pi: ExtensionAPI) {
         `- 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",
+        "## Copied agents",
         result.copied.length ? result.copied.map((agent) => `- ${agent}`).join("\n") : "- none",
         "",
-        "## Skipped",
+        "## 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");
 
@@ -233,7 +238,7 @@ export default function areyPi(pi: ExtensionAPI) {
         customType: "arey-pi-bootstrap",
         content: report,
         display: true,
-        details: result,
+        details: { agents: result, specs: specsResult, docs: docsResult, agentsMd: agentsMdStatus },
       });
     },
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arey-pi",
-  "version": "0.2.0",
+  "version": "0.3.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",
@@ -35,7 +35,7 @@
   ],
   "pi": {
     "extensions": [
-      "./extensions/arey-pi.ts"
+      "./extensions/arey-pi/index.ts"
     ],
     "skills": [
       "./skills"
@@ -48,7 +48,8 @@
     "format": "biome format --write .",
     "lint": "biome lint .",
     "typecheck": "tsc --noEmit",
-    "check": "bun run lint && bun run typecheck",
+    "test": "bun test",
+    "check": "bun run lint && bun run typecheck && bun run test",
     "prepublishOnly": "bun run check && npm pack --dry-run"
   },
   "peerDependencies": {
@@ -65,6 +66,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.16",
     "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@types/bun": "^1.3.14",
     "@types/node": "^25.9.2",
     "typescript": "^6.0.3"
   }

package/rules/assessment/project-readiness.md

@@ -54,6 +54,7 @@ Check whether:
 - coverage is available or intentionally absent;
 - mutation testing is configured for critical code or proposed as an improvement;
 - tests assert behaviour rather than implementation mechanics;
+- tests are organised in a dedicated test/spec directory rather than colocated with production source files without justification;
 - edge cases and failure paths are covered for important behaviour;
 - surviving mutants or weak assertions are triaged when evidence exists.
 

package/rules/core/definition-of-done.md

@@ -12,6 +12,7 @@ A change is complete when:
 
 - relevant Gherkin specs exist or are explicitly confirmed unaffected;
 - production behaviour is covered by meaningful tests;
+- tests are placed in a dedicated test/spec directory outside production source trees, unless an explicit project or framework constraint justifies an exception;
 - test quality has been assessed with mutation testing, coverage, or explicit review appropriate to risk;
 - TDD was followed for production behaviour;
 - bug fixes include regression tests;
@@ -37,6 +38,7 @@ A change is not done if:
 
 - behaviour changed but Gherkin was not updated or justified unaffected;
 - tests were skipped silently;
+- new tests are colocated inside production source directories without a documented convention or approved exception;
 - production code was written without TDD evidence;
 - failing tests remain unresolved without explicit blocker status;
 - code contradicts canonical specs;
@@ -57,7 +59,7 @@ Agents should close with:
 ```txt
 Done summary:
 - Behaviour/spec impact:
-- Tests/TDD:
+- Tests/TDD, including test location:
 - Validation:
 - Quality tooling:
 - Spec sync:

package/rules/engineering/tdd.md

@@ -16,13 +16,16 @@ Red → Green → Refactor
 
 This applies to features, bug fixes, behaviour changes, risky refactors, API/CLI behaviour, validation, permissions, persistence, and error handling.
 
+Tests must live outside production source directories by default.
+Do not colocate test files beside production files in `src/` or equivalent source trees unless an existing project convention explicitly requires it or the user approves an exception.
+
 ## Red
 
 Before implementation, create, update, or identify a test that fails for the intended reason.
 
 Valid Red evidence includes:
 
-- a newly added failing test;
+- a newly added failing test in the dedicated test directory;
 - an updated failing test;
 - an existing failing test that already captures the intended behaviour;
 - a documented inability to run the test, including the exact intended command and reason.
@@ -46,6 +49,32 @@ After Green, refactor only while tests remain green.
 
 Refactoring should improve clarity, structure, duplication, or maintainability without expanding scope or changing behaviour.
 
+## Test Location
+
+Use a dedicated test/spec directory for automated tests.
+
+Preferred locations include project conventions such as:
+
+```txt
+tests/
+test/
+__tests__/
+spec/
+```
+
+When adding tests for code under `src/`, mirror the production module structure under the chosen test directory instead of creating sibling test files inside `src/`.
+
+Example:
+
+```txt
+src/domain/accounts/password-reset.ts
+tests/domain/accounts/password-reset.test.ts
+```
+
+If a repository already has a clear separate test root, follow it.
+If it only has colocated tests, ask before continuing the pattern or migrating it.
+If a framework mandates colocated tests, document the constraint in the final evidence.
+
 ## Bug Fixes
 
 Every bug fix requires a regression test.
@@ -82,5 +111,6 @@ Completion must report:
 - Green evidence;
 - refactor status;
 - commands run;
+- test location and any exception to separate test directories;
 - tests not run and why;
 - residual risks.

package/rules/engineering/test-quality.md

@@ -23,6 +23,36 @@ Agents should assess test quality across these dimensions:
 5. **Minimal coupling:** the test avoids depending on private implementation details unless intentionally characterizing legacy code before refactor.
 6. **Maintainability:** the test is readable, focused, deterministic, and not overly broad.
 7. **Regression value:** for bug fixes, the test would have failed before the fix.
+8. **Source separation:** tests live in a dedicated test/spec directory rather than being colocated with production files, unless an explicit project or framework constraint justifies an exception.
+
+## Test Organisation
+
+Tests should be organised outside production source directories.
+
+Prefer a project-level test root such as:
+
+```txt
+tests/
+test/
+__tests__/
+spec/
+```
+
+Mirror production structure inside that test root when useful.
+
+Avoid creating files such as:
+
+```txt
+src/foo.test.ts
+src/foo.spec.ts
+src/foo.test.py
+```
+
+unless the repository has an established, user-approved, or framework-mandated colocated test convention.
+
+This keeps production source trees clean,
+makes generated tests easier to audit,
+and avoids mixing executable product code with validation artefacts.
 
 ## Coverage
 
@@ -101,7 +131,8 @@ Agents must reject or improve tests that:
 - over-mock collaborators so the real contract is not exercised;
 - assert private structure instead of observable behaviour;
 - pass even if important logic is removed;
-- lack a clear connection to a spec, bug, or requirement.
+- lack a clear connection to a spec, bug, or requirement;
+- are colocated with production source files without an explicit project convention or approved exception.
 
 ## Negative and Edge Cases
 
@@ -130,7 +161,7 @@ If the answer is no, the test is probably weak.
 
 For non-trivial production changes, agents should report:
 
-- tests added or modified;
+- tests added or modified, including their dedicated test directory location;
 - related Gherkin scenarios or requirements;
 - Red evidence;
 - Green evidence;

package/templates/AGENTS.md

@@ -0,0 +1,25 @@
+# Agent Instructions
+
+This project uses Arey Pi.
+
+## Delivery rules
+
+- Treat canonical specs as the source of truth.
+- Use Gherkin for behaviour specs.
+- Use DBML for database specs when the project has persistence.
+- Follow TDD for production behaviour changes.
+- Put tests in a dedicated test/spec directory outside production source trees unless a documented project or framework convention requires otherwise.
+- Keep specs, tests, code, DBML, ADRs, glossary, architecture docs, README files, docs, AGENTS.md, commands, and tooling instructions synchronised.
+- Capture significant technical decisions in high-quality ADRs.
+- Run formatter, lint/static analysis, typecheck, tests, and relevant dynamic analysis where available.
+- Use incremental Conventional Commits for meaningful steps.
+
+## Subagents
+
+Project-local Arey Pi subagents live in:
+
+```txt
+.pi/agents/arey-pi/
+```
+
+Use them through pi-subagents when available.

package/templates/adr.md

@@ -0,0 +1,60 @@
+# ADR-NNNN: Decision Title
+
+## Status
+
+Proposed
+
+## Context
+
+Describe the forces,
+constraints,
+requirements,
+and tradeoffs that make this decision necessary.
+
+## Decision
+
+State the decision clearly.
+
+## Options Considered
+
+### Option 1
+
+Summary.
+
+Pros:
+
+- ...
+
+Cons:
+
+- ...
+
+### Option 2
+
+Summary.
+
+Pros:
+
+- ...
+
+Cons:
+
+- ...
+
+## Consequences
+
+Describe expected consequences,
+including risks,
+costs,
+follow-up work,
+and operational impact.
+
+## Supersession and Relationships
+
+Record whether this ADR supersedes,
+is superseded by,
+or overlaps with other ADRs.
+
+## Revisit Conditions
+
+List conditions that should trigger review of this decision.

package/templates/architecture-readme.md

@@ -0,0 +1,9 @@
+# Architecture
+
+Use this directory for durable architecture memory.
+
+Document boundaries,
+integrations,
+ownership,
+constraints,
+and current system structure that future humans and agents need to preserve.

package/templates/database-readme.md

@@ -0,0 +1,10 @@
+# Database Specs
+
+Database projects must keep canonical DBML specs here or document the canonical DBML location.
+
+DBML must stay synchronised with migrations,
+ORM models,
+SQL DDL,
+constraints,
+indexes,
+and relationships.

package/templates/database.dbml

@@ -0,0 +1,14 @@
+// Canonical database specification.
+// Keep this DBML synchronised with migrations, ORM models, SQL DDL, constraints, indexes, and relationships.
+
+Project project_name {
+  database_type: 'PostgreSQL'
+  Note: 'Replace this starter DBML with the canonical project schema.'
+}
+
+Table example_entities {
+  id uuid [pk, note: 'Primary identifier']
+  name varchar [not null]
+  created_at timestamptz [not null]
+  updated_at timestamptz [not null]
+}

package/templates/decisions-readme.md

@@ -0,0 +1,11 @@
+# Decisions
+
+Use this directory for high-quality ADRs.
+
+ADRs should capture meaningful technical decisions,
+context,
+options,
+tradeoffs,
+consequences,
+revisit conditions,
+and supersession relationships.

package/templates/docs-readme.md

@@ -0,0 +1,9 @@
+# Documentation
+
+Use this directory for project-facing documentation that is not itself a canonical spec.
+
+Keep usage,
+setup,
+commands,
+operations,
+and workflow instructions synchronised with the implementation and Arey Pi rules.

package/templates/feature.feature

@@ -0,0 +1,17 @@
+Feature: Feature name
+  As a stakeholder
+  I want a capability
+  So that an outcome is achieved
+
+  Background:
+    Given relevant starting context
+
+  Scenario: Observable behaviour
+    Given preconditions
+    When an action occurs
+    Then the expected outcome is observable
+
+  Scenario: Important edge case
+    Given edge-case preconditions
+    When an action occurs
+    Then the system handles the case explicitly

package/templates/features-readme.md

@@ -0,0 +1,7 @@
+# Behaviour Specs
+
+Write behaviour specs in Gherkin.
+
+Use semantic line breaks in feature files and accompanying notes.
+Each feature should describe externally observable behaviour,
+not implementation details.

package/templates/glossary.md

@@ -0,0 +1,19 @@
+# Glossary
+
+Use this glossary for durable domain language.
+
+## Terms
+
+<!--
+Add terms as they become important.
+
+Example:
+
+### Account
+
+Definition.
+
+Related specs:
+
+- specs/features/example.feature
+-->

package/templates/project-readiness-report.md

@@ -0,0 +1,120 @@
+# Arey Pi Project Readiness Report
+
+## Overall
+
+- Overall Readiness: N/5
+- Lowest Rule Scores:
+- Highest Rule Scores:
+
+## Executive Summary
+
+Summarise the current readiness posture.
+
+## Blockers
+
+List issues that prevent reliable Arey Pi delivery.
+
+## Quick Wins
+
+List low-effort improvements with high leverage.
+
+## Rule Scores
+
+### Canonical Specs
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Gherkin Authoring
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Tests/TDD
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Test Quality
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Quality Tooling
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Engineering Quality
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Spec Sync
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Documentation Sync
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Database Specs
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Rebuildability
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Architecture Memory and ADRs
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Incremental Commits
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### AI Harness
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+## Recommended Plan
+
+1. ...
+
+## Residual Risks / Unknowns
+
+List what could not be verified.

package/templates/specs-readme.md

@@ -0,0 +1,6 @@
+# Specs
+
+This directory contains canonical Arey Pi project specifications.
+
+Specs are durable project knowledge.
+Keep them synchronised with tests, code, DBML, ADRs, glossary, architecture docs, and project documentation.