arey-pi 0.5.0 → 0.6.0

package/README.md

@@ -119,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:
 
@@ -129,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
@@ -139,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;
@@ -195,14 +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 stronger workflow command contracts,
+Arey Pi now includes natural-language harness activation,
 focused prompts,
 TDD/spec-sync/review skills,
 and extension-core tests.
 
-Next improvements include guided interactive workflows,
-stronger bootstrap scaffolding,
+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,235 +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`
+## Natural-language development workflows
 
-Starts the Arey Pi feature delivery workflow.
-
-Usage:
+Arey Pi is designed to work without development slash commands.
+When the user explicitly opts into Arey Pi in normal language,
+for example:
 
 ```txt
-/arey-feature <feature request>
+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
 ```
 
-Example:
+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.
 
-```txt
-/arey-feature Add password reset with expiring email links
-```
+The injected harness guidance emphasises:
 
-The command sends a structured request to the parent agent to act as the Arey Pi tech lead.
-The expected workflow is:
+- `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.
 
-```txt
-spec-author → tdd-implementer → spec-syncer → engineering-reviewer
-```
-
-The command now sends a stronger execution contract.
-The workflow should:
-
-- identify scope, non-goals, risk, and unknowns;
-- confirm or update canonical specs before production behaviour changes;
-- preserve TDD through Red → Green → Refactor;
-- keep tests outside production source directories by default;
-- synchronise specs, docs, tests, code, DBML, ADRs, glossary, README files, AGENTS.md, skills, prompts, rules, agents, commands, templates, and tooling instructions when affected;
-- run fresh-context engineering review when risk warrants it;
-- report validation evidence and residual risks using the Arey Pi final evidence format.
+While Arey Pi is active,
+Arey Pi applies simple tool-call guardrails:
 
-## `/arey-bugfix`
-
-Starts the Arey Pi regression-test-first bugfix workflow.
-
-Usage:
+- writes or edits to protected paths such as `.env`, `.git/`, and `node_modules/` are blocked.
 
-```txt
-/arey-bugfix <bug description>
-```
-
-Example:
-
-```txt
-/arey-bugfix Users can bypass email verification by refreshing the session
-```
-
-The command now sends a regression-test-first execution contract.
-The workflow should:
-
-- identify expected versus actual behaviour and affected scope;
-- reproduce the bug with a meaningful failing regression test before production changes;
-- implement the smallest high-quality fix;
-- keep Red → Green → Refactor evidence visible;
-- update Gherkin, docs, DBML, ADRs, glossary, or architecture docs when affected;
-- request fresh engineering review for security, data-loss, concurrency, auth, payment, migration, or public API bugs;
-- run validation and report residual risks.
-
-## `/arey-sync`
-
-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 sync contract asks the agent to classify drift as blocking,
-recommended,
-or unaffected.
-It may fix safe drift directly when canonical intent is clear,
-but it must ask before changing intent.
-
-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.
 
 ## Prompt templates and skills
 
-Arey Pi also ships focused prompt templates:
-
-```txt
-/feature-spec
-/red-green-refactor
-/sync-drift
-/engineering-review
-/adr-review
-/assess-project
-```
-
-And focused skills:
-
-```txt
-/skill:tdd-red-green-refactor
-/skill:spec-sync
-/skill:engineering-review
-/skill:project-readiness
-```
-
-Use slash commands for full workflow orchestration,
-prompts for targeted one-off work,
-and skills when you want the model to load specialised Arey Pi instructions on demand.
-
-## 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.
-```
-
-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();
+    },
+  });
+}

package/extensions/arey-pi/core.ts

@@ -56,96 +56,42 @@ 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:`;
 
-function commonWorkflowMessage(): string {
-  return [
-    "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.",
-    "Clarify blocking ambiguity before editing; otherwise proceed incrementally.",
-    "Follow Arey Pi rules, preserve TDD for behaviour changes, and report evidence clearly.",
-  ].join(" ");
-}
-
-function featureWorkflow(target: string): string {
-  return [
-    commonWorkflowMessage(),
-    "",
-    `Run the Arey Pi feature workflow for: ${target}`,
-    "",
-    "Execution contract:",
-    "1. Scope: identify behaviour, impacted users, non-goals, risk level, and unknowns.",
-    "2. Specs: confirm or update canonical Gherkin before production behaviour changes; use arey-pi.spec-author when available.",
-    "3. TDD: use arey-pi.tdd-implementer for Red → Green → Refactor; tests must live outside production source directories by default.",
-    "4. Implementation: make the smallest high-quality change; avoid speculative architecture.",
-    "5. Sync: use arey-pi.spec-syncer to align specs, tests, code, DBML, ADRs, glossary, README, docs, AGENTS.md, skills, prompts, rules, agents, commands, and tooling instructions when affected.",
-    "6. Review: use fresh-context arey-pi.engineering-reviewer or reviewers when risk warrants it.",
-    "",
-    "Use scout/context-builder/planner first if codebase context is not clear.",
-    evidenceSummary,
-  ].join("\n");
-}
+export function areyPiHarnessContext(prompt: string): string {
+  const target = prompt.trim() || "the current request";
 
-function bugfixWorkflow(target: string): string {
   return [
-    commonWorkflowMessage(),
-    "",
-    `Run the Arey Pi bugfix workflow for: ${target}`,
+    "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.",
     "",
-    "Execution contract:",
-    "1. Reproduce: identify expected vs actual behaviour and affected scope.",
-    "2. Regression test first: add or update a meaningful failing test that proves the bug before changing production code.",
-    "3. Fix: implement the smallest high-quality correction without broad rewrites unless necessary.",
-    "4. Refactor: improve design only while regression tests and existing tests remain green.",
-    "5. Sync: update Gherkin, docs, DBML, ADRs, glossary, or architecture docs when the intended behaviour or design contract changed.",
-    "6. Review: request fresh engineering review for security, data-loss, concurrency, auth, payment, migration, or public API bugs.",
+    `User request: ${target}`,
     "",
-    "If a failing regression test cannot be demonstrated, state the blocker explicitly and do not claim TDD evidence.",
     evidenceSummary,
   ].join("\n");
 }
 
-function syncWorkflow(target: string): string {
-  return [
-    commonWorkflowMessage(),
-    "",
-    `Run Arey Pi spec and documentation sync for: ${target}`,
-    "",
-    "Sync contract:",
-    "1. Inspect the requested scope and current diff before editing.",
-    "2. Verify alignment across canonical Gherkin, tests, production code, DBML, ADRs, glossary, architecture docs, README files, docs, AGENTS.md, skills, prompts, rules, agents, commands, templates, and tooling instructions.",
-    "3. Classify drift as blocking, recommended, or unaffected.",
-    "4. Fix safe drift directly when the intended behaviour is clear; otherwise ask for a decision.",
-    "5. Do not rewrite specs to hide implementation defects.",
-    "6. Run relevant validation after changes.",
-    "",
-    "End with both statuses exactly: `Specs updated` or `Specs unaffected`; `Docs updated` or `Docs unaffected`, with evidence.",
-    evidenceSummary,
-  ].join("\n");
-}
-
-export function workflowMessage(kind: WorkflowKind, args: string): string {
-  const target = args.trim() || "the current repository/task";
-
-  switch (kind) {
-    case "feature":
-      return featureWorkflow(target);
-    case "bugfix":
-      return bugfixWorkflow(target);
-    case "sync":
-      return syncWorkflow(target);
-    case "review":
-      return `${commonWorkflowMessage()}\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 `${commonWorkflowMessage()}\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 `${commonWorkflowMessage()}\n\nWork on: ${target}`;
-  }
-}
-
 export type DoctorReportInput = {
   packageVersion: string;
   cwd: string;
@@ -183,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.5.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",