arey-pi 0.4.0 → 0.6.0

package/README.md

@@ -50,6 +50,12 @@ The rules are the policy layer.
 The skills and prompts make those policies usable inside Pi.
 The agents define the intended specialist roles for subagent-backed delivery.
 
+Arey Pi includes focused prompt templates and skills for feature specs,
+strict Red-Green-Refactor,
+spec drift repair,
+ADR assessment,
+and adversarial engineering review.
+
 ## Current subagent architecture
 
 Arey Pi is designed to work with `pi-subagents`.
@@ -113,7 +119,7 @@ Or load the readiness skill directly:
 /skill:project-readiness
 ```
 
-Arey Pi also ships an extension with native workflow commands.
+Arey Pi also ships an extension with native setup commands and automatic natural-language harness activation.
 
 When the Arey Pi agents are available to `pi-subagents`, the project evaluator runtime name is:
 
@@ -123,7 +129,7 @@ arey-pi.project-evaluator
 
 ## Extension-backed workflow
 
-Arey Pi includes a polished extension-backed workflow:
+Arey Pi includes a polished extension-backed setup and natural-language workflow harness:
 
 ```txt
 /arey-doctor      # check package, subagent, prompt, skill, and project readiness setup
@@ -133,19 +139,23 @@ Arey Pi includes a polished extension-backed workflow:
 /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
-/arey-review      # run adversarial engineering review
-/arey-assess      # assess project readiness against Arey Pi rules
+# Development workflows are natural-language first:
+# "Implementa password reset siguiendo Arey Pi"
+# "Corrige este bug con Arey Pi"
+# "Revisa el current diff contra Arey Pi"
 ```
 
-The goal is that users can either speak naturally or use explicit commands,
-while Arey Pi handles the disciplined workflow behind the scenes.
+The goal is that users work naturally without development commands.
+Requests such as `Implementa password reset siguiendo Arey Pi` automatically activate quiet harness context behind the scenes.
+Arey Pi lets the parent agent infer the work mode,
+act as orchestrator,
+use specialist subagents when available,
+inject the relevant delivery guidance,
+and apply simple event-based guardrails for protected paths.
 
 See:
 
-- `docs/commands.md` for detailed command behaviour, options, and examples;
+- `docs/commands.md` for setup commands and natural-language workflow behaviour;
 - `docs/adoption.md` for adopting Arey Pi in an existing repository;
 - `docs/workflows.md` for workflow expectations;
 - `docs/workflow-diagram.md` for the visual framework workflow;
@@ -189,8 +199,13 @@ The policy layer,
 readiness workflow,
 documentation sync rule,
 core subagent role definitions,
-and professional extension commands exist.
+and professional setup extension commands exist.
+
+Arey Pi now includes natural-language harness activation,
+focused prompts,
+TDD/spec-sync/review skills,
+and extension-core tests.
 
-Next milestones include richer templates,
-stronger bootstrap scaffolding,
-and deeper integration with `pi-subagents` discovery.
+Next improvements include stronger bootstrap scaffolding,
+custom Arey Pi tools,
+and deeper enforcement through Pi extension events.

package/docs/adoption.md

@@ -85,13 +85,13 @@ agents should be able to discover:
 
 ### 5. Assess readiness
 
-Run:
+Ask naturally:
 
 ```txt
-/arey-assess
+Evalúa este repo contra Arey Pi
 ```
 
-or:
+You can also use the focused prompt template if desired:
 
 ```txt
 /assess-project
@@ -155,7 +155,7 @@ Use this for active product repositories.
 - Add Gherkin specs for core behaviours.
 - Add DBML if persistence exists.
 - Add ADRs for significant decisions.
-- Require `/arey-sync` before completing non-trivial work.
+- Require natural Arey Pi sync review before completing non-trivial work.
 
 ### Strict adoption
 
@@ -202,11 +202,11 @@ Do not:
 ## Completion Standard
 
 After adoption work,
-run:
+run setup diagnostics and ask for a natural readiness assessment:
 
 ```txt
 /arey-doctor
-/arey-assess
+Evalúa este repo contra Arey Pi
 ```
 
 A good first adoption result is not perfection.

package/docs/commands.md

@@ -1,23 +1,14 @@
 # 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:
-
-- quick explicit workflows such as `/arey-feature` or `/arey-sync`;
-- natural-language work where the parent agent acts as the Arey Pi tech lead and uses the same workflow expectations.
+Arey Pi ships a Pi extension that registers native setup slash commands.
+Development workflows are intentionally natural-language first:
+the extension recognises explicit Arey Pi opt-in and injects quiet harness guidance automatically.
 
 ## Command overview
 
 ```txt
 /arey-doctor
 /arey-bootstrap [--agentsmd] [--specs] [--docs] [--full] [--force]
-/arey-feature <feature request>
-/arey-bugfix <bug description>
-/arey-sync [scope]
-/arey-review [scope]
-/arey-assess [scope]
 ```
 
 ## `/arey-doctor`
@@ -158,197 +149,49 @@ Examples:
 
 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`
-
-Starts the Arey Pi feature delivery workflow.
-
-Usage:
-
-```txt
-/arey-feature <feature request>
-```
-
-Example:
-
-```txt
-/arey-feature Add password reset with expiring email links
-```
+## Natural-language development workflows
 
-The command sends a structured request to the parent agent to act as the Arey Pi tech lead.
-The expected workflow is:
+Arey Pi is designed to work without development slash commands.
+When the user explicitly opts into Arey Pi in normal language,
+for example:
 
 ```txt
-spec-author → tdd-implementer → spec-syncer → engineering-reviewer
+Implementa password reset siguiendo Arey Pi
+Corrige este bug con Arey Pi
+Revisa el current diff contra Arey Pi
+Evalúa este repo contra Arey Pi
 ```
 
-The workflow should:
+The extension injects quiet harness context automatically before the agent turn.
+The harness is not meant to add ceremony for the user.
+It asks the agent to infer whether the request is a feature,
+bugfix,
+sync,
+review,
+assessment,
+or mixed task,
+then apply the corresponding Arey Pi posture.
+The parent agent should act as orchestrator,
+use specialist Arey Pi subagents when available,
+and continue conversationally while reporting evidence naturally.
 
-- confirm or update canonical specs;
-- preserve TDD through Red → Green → Refactor;
-- synchronise specs, docs, tests, code, DBML, ADRs, glossary, and architecture docs;
-- run engineering review when risk warrants it;
-- report validation evidence and residual risks.
-
-## `/arey-bugfix`
-
-Starts the Arey Pi regression-test-first bugfix workflow.
-
-Usage:
-
-```txt
-/arey-bugfix <bug description>
-```
-
-Example:
-
-```txt
-/arey-bugfix Users can bypass email verification by refreshing the session
-```
+The injected harness guidance emphasises:
 
-The workflow should:
+- `arey-pi.spec-author` for canonical specs;
+- `arey-pi.tdd-implementer` for Red → Green → Refactor;
+- `arey-pi.spec-syncer` for alignment;
+- `arey-pi.engineering-reviewer` for fresh review;
+- `arey-pi.project-evaluator` for readiness assessment;
+- builtin scout/planner/reviewer/oracle-style agents for discovery, planning, and second opinions.
 
-- reproduce the bug with a failing regression test;
-- implement the smallest high-quality fix;
-- keep TDD evidence visible;
-- update Gherkin, docs, DBML, ADRs, glossary, or architecture docs when affected;
-- run validation and report residual risks.
+While Arey Pi is active,
+Arey Pi applies simple tool-call guardrails:
 
-## `/arey-sync`
+- writes or edits to protected paths such as `.env`, `.git/`, and `node_modules/` are blocked.
 
-Runs Arey Pi sync review for the current repository or a specific scope.
 
-Usage:
-
-```txt
-/arey-sync
-/arey-sync <scope>
-```
-
-Examples:
-
-```txt
-/arey-sync
-/arey-sync authentication flow
-/arey-sync current diff
-```
-
-The command asks the parent agent to verify alignment across:
-
-- Gherkin specs;
-- tests;
-- code;
-- DBML;
-- ADRs;
-- glossary;
-- architecture docs;
-- README files;
-- `docs/`;
-- `AGENTS.md`;
-- skills, prompts, rules, agents, examples, templates;
-- command and tooling instructions.
-
-The final report should include both:
-
-```txt
-Specs updated
-```
-
-or:
-
-```txt
-Specs unaffected: <reason>
-```
-
-and:
-
-```txt
-Docs updated
-```
-
-or:
-
-```txt
-Docs unaffected: <reason>
-```
-
-## `/arey-review`
-
-Runs an adversarial Arey Pi engineering review.
-
-Usage:
-
-```txt
-/arey-review
-/arey-review <scope>
-```
-
-Examples:
-
-```txt
-/arey-review
-/arey-review current diff
-/arey-review persistence layer
-```
-
-The review should examine:
-
-- architecture and code quality;
-- test quality;
-- quality tooling and validation evidence;
-- security and privacy;
-- reliability and operability;
-- maintainability;
-- spec, ADR, DBML, glossary, and documentation sync concerns;
-- generated-code or agent-authored-code slop.
-
-Findings should be classified by severity.
-
-## `/arey-assess`
-
-Runs Arey Pi project readiness assessment.
-
-Usage:
-
-```txt
-/arey-assess
-/arey-assess <scope>
-```
-
-Examples:
-
-```txt
-/arey-assess
-/arey-assess backend package only
-```
-
-The assessment is read-only by default.
-It should score the repository against Arey Pi rules,
-provide evidence with file paths,
-identify blockers and quick wins,
-and propose a prioritised improvement plan.
-
-Use this when adopting Arey Pi in an existing repository or checking whether a project remains aligned.
-
-## Busy agent behaviour
-
-Workflow commands send a user message to the current Pi session.
-
-If the agent is idle,
-the workflow starts immediately.
-
-If the agent is already working,
-the workflow is queued as a follow-up message.
-
-## Relationship to natural language
-
-Commands are optional.
-
-Users can also work naturally:
-
-```txt
-Implement magic links following Arey Pi.
-```
+## Prompt templates and skills
 
-The commands exist to make common workflows explicit,
-repeatable,
-and easier to discover.
+Arey Pi still ships focused prompt templates and skills for targeted use,
+but they are optional.
+The intended default is natural language plus automatic harness injection.

package/docs/templates.md

@@ -133,7 +133,7 @@ The readiness report template captures Arey Pi assessment output.
 
 Use it when you want a persistent audit snapshot under `docs/`.
 For routine checks,
-`/arey-assess` can report directly in the session.
+ask naturally: `Evalúa este repo contra Arey Pi`.
 
 ## Template Maintenance
 

package/docs/workflows.md

@@ -2,17 +2,16 @@
 
 See `docs/workflow-diagram.md` for a visual overview of the framework workflow.
 
-Arey Pi workflows can be started with slash commands or natural language.
-
-The slash commands make the intended process explicit.
-Natural language should still follow the same rules when the user asks to work following Arey Pi.
+Arey Pi development workflows are natural-language first.
+When the user asks to work following Arey Pi,
+the extension injects quiet harness guidance automatically before the agent turn.
 
 ## Feature Workflow
 
-Command:
+Example request:
 
 ```txt
-/arey-feature <feature request>
+Implementa password reset siguiendo Arey Pi
 ```
 
 Expected flow:
@@ -41,10 +40,10 @@ The workflow should:
 
 ## Bugfix Workflow
 
-Command:
+Example request:
 
 ```txt
-/arey-bugfix <bug description>
+Corrige el bug de verificación de email con Arey Pi
 ```
 
 Use this when behaviour is wrong.
@@ -61,10 +60,10 @@ and it should live outside production source directories by default.
 
 ## Sync Workflow
 
-Command:
+Example request:
 
 ```txt
-/arey-sync [scope]
+Sincroniza specs y docs con Arey Pi para el current diff
 ```
 
 Use this before completing non-trivial work or when drift is suspected.
@@ -101,10 +100,10 @@ or justified unaffected statuses.
 
 ## Review Workflow
 
-Command:
+Example request:
 
 ```txt
-/arey-review [scope]
+Revisa el current diff contra Arey Pi
 ```
 
 Use this for adversarial engineering review.
@@ -128,10 +127,10 @@ Findings should be classified by severity.
 
 ## Assessment Workflow
 
-Command:
+Example request:
 
 ```txt
-/arey-assess [scope]
+Evalúa este repo contra Arey Pi
 ```
 
 Use this to assess project readiness.

package/extensions/arey-pi/bootstrap.ts

@@ -0,0 +1,198 @@
+import { copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import {
+  buildDoctorReport,
+  docsScaffoldFiles,
+  parseBootstrapFlags,
+  requiredAgents,
+  specScaffoldFiles,
+  type ScaffoldFile,
+} from "./core.ts";
+import { agentSourceDir, cwdFrom, dirExists, fileExists, packageRoot, rulesDir, templatesDir } from "./paths.ts";
+
+type AgentCopyResult = { copied: string[]; skipped: string[]; missing: string[] };
+type ScaffoldResult = { created: string[]; skipped: string[] };
+
+function copyAgents(targetDir: string, force: boolean): AgentCopyResult {
+  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 };
+}
+
+function templateContent(name: string): string {
+  return readFileSync(join(templatesDir, name), "utf8");
+}
+
+function writeTemplateIfMissing(file: ScaffoldFile, force: boolean, cwd: string, result: ScaffoldResult): void {
+  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 packageVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")) as { version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+function buildBootstrapReport(input: {
+  cwd: string;
+  targetDir: string;
+  agents: AgentCopyResult;
+  specs: ScaffoldResult;
+  docs: ScaffoldResult;
+  agentsMd: string;
+}): string {
+  const createdScaffold = [...input.specs.created, ...input.docs.created];
+  const skippedScaffold = [...input.specs.skipped, ...input.docs.skipped];
+
+  return [
+    "# Arey Pi Bootstrap",
+    "",
+    `- Target: ${relative(input.cwd, input.targetDir)}`,
+    `- Copied agents: ${input.agents.copied.length}`,
+    `- Skipped existing agents: ${input.agents.skipped.length}`,
+    `- Missing package agents: ${input.agents.missing.length}`,
+    `- AGENTS.md: ${input.agentsMd}`,
+    `- Spec scaffold created: ${input.specs.created.length}`,
+    `- Spec scaffold skipped: ${input.specs.skipped.length}`,
+    `- Docs scaffold created: ${input.docs.created.length}`,
+    `- Docs scaffold skipped: ${input.docs.skipped.length}`,
+    "",
+    "## Copied agents",
+    input.agents.copied.length ? input.agents.copied.map((agent) => `- ${agent}`).join("\n") : "- none",
+    "",
+    "## Skipped agents",
+    input.agents.skipped.length ? input.agents.skipped.map((agent) => `- ${agent}`).join("\n") : "- none",
+    "",
+    "## Created scaffold files",
+    createdScaffold.length ? createdScaffold.map((path) => `- ${path}`).join("\n") : "- none",
+    "",
+    "## Skipped scaffold files",
+    skippedScaffold.length ? skippedScaffold.map((path) => `- ${path}`).join("\n") : "- none",
+    "",
+    "Run `/arey-doctor` to verify setup.",
+  ].join("\n");
+}
+
+function handleDoctor(pi: ExtensionAPI, ctx: ExtensionCommandContext): void {
+  const cwd = cwdFrom(ctx);
+  const projectAgentDir = join(cwd, ".pi", "agents", "arey-pi");
+  const commands = pi.getCommands();
+  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"),
+  );
+
+  pi.sendMessage({
+    customType: "arey-pi-doctor",
+    content: buildDoctorReport({
+      packageVersion: packageVersion(),
+      cwd,
+      packageRulesPresent: dirExists(rulesDir),
+      packageTemplatesPresent: dirExists(templatesDir),
+      packageAgentsCount: packageAgents.length,
+      requiredAgentsCount: requiredAgents.length,
+      hasSubagentsCommand: commands.some((command) => command.name.startsWith("subagents-doctor")),
+      installedAgentsCount: installedAgents.length,
+      hasRootAgentsMd: fileExists(join(cwd, "AGENTS.md")),
+      hasPiSettings: fileExists(join(cwd, ".pi", "settings.json")),
+      promptsCount: prompts.length,
+      skillsCount: skills.length,
+      missingAgents,
+    }),
+    display: true,
+    details: {},
+  });
+}
+
+function handleBootstrap(pi: ExtensionAPI, args: string, ctx: ExtensionCommandContext): void {
+  const cwd = cwdFrom(ctx);
+  const { force, createAgentsMd, createSpecs, createDocs } = parseBootstrapFlags(args);
+  const targetDir = join(cwd, ".pi", "agents", "arey-pi");
+  const agents = copyAgents(targetDir, force);
+  const specs = createSpecs ? scaffoldFiles(cwd, force, specScaffoldFiles) : { created: [], skipped: [] };
+  const docs = createDocs ? scaffoldFiles(cwd, force, docsScaffoldFiles) : { created: [], skipped: [] };
+  const agentsMdPath = join(cwd, "AGENTS.md");
+  let agentsMd = "unchanged";
+
+  if (!fileExists(agentsMdPath) && (createAgentsMd || force)) {
+    writeFileSync(agentsMdPath, templateContent("AGENTS.md"));
+    agentsMd = "created";
+  } else if (fileExists(agentsMdPath) && createAgentsMd && !force) {
+    agentsMd = "skipped existing";
+  }
+
+  pi.sendMessage({
+    customType: "arey-pi-bootstrap",
+    content: buildBootstrapReport({ cwd, targetDir, agents, specs, docs, agentsMd }),
+    display: true,
+    details: { agents, specs, docs, agentsMd },
+  });
+}
+
+export function registerBootstrapCommands(pi: ExtensionAPI): void {
+  pi.registerCommand("arey-doctor", {
+    description: "Check Arey Pi package, project bootstrap, and subagent readiness",
+    handler: (_args, ctx) => {
+      handleDoctor(pi, ctx);
+      return Promise.resolve();
+    },
+  });
+
+  pi.registerCommand("arey-bootstrap", {
+    description: "Install Arey Pi subagents and optionally scaffold specs/docs",
+    handler: (args, ctx) => {
+      handleBootstrap(pi, args, ctx);
+      return Promise.resolve();
+    },
+  });
+}