arey-pi 0.6.2 → 0.6.3

package/README.md

@@ -37,23 +37,28 @@ Arey Pi is built around these guarantees:
 ## Package contents
 
 ```txt
-agents/      # Arey Pi subagent role definitions for pi-subagents
-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
+agents/       # Arey Pi subagent role definitions for pi-subagents
+assets/       # Package assets, including the package image used by Pi
+docs/         # Package documentation
+extensions/   # Pi extension for doctor, bootstrap, workflow runtime, and guardrails
+prompts/      # Reusable Pi prompt workflows
+rules/        # Arey Pi operating rules
+skills/       # On-demand Arey Pi workflows and instructions
+templates/    # Bootstrap templates for AGENTS.md, specs, ADRs, DBML, glossary, and reports
 ```
 
 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,
+The extension turns the policy into project setup commands,
+always-on workflow context,
+and safe mutation guardrails.
+The skills and prompts provide focused entry points for targeted work.
+The agents define specialist roles for subagent-backed delivery.
+
+Arey Pi currently includes prompt templates and skills for project readiness,
+feature specs,
 strict Red-Green-Refactor,
 spec drift repair,
-ADR assessment,
+ADR review,
 and adversarial engineering review.
 
 ## Current subagent architecture
@@ -71,14 +76,12 @@ tech-lead
 └── project-evaluator
 ```
 
-The intended daily experience is natural language first:
-
-```txt
-Implement password reset.
-```
-
-The parent agent should act as the tech lead,
-then use specialist subagents when available for specs,
+The intended daily experience is conversational.
+Users describe the work they want done,
+and the parent agent acts as the tech lead behind the scenes.
+It classifies the request,
+selects the matching Arey Pi workflow,
+and uses specialist subagents when available for specs,
 TDD implementation,
 spec sync,
 and engineering review.
@@ -119,7 +122,9 @@ Or load the readiness skill directly:
 /skill:project-readiness
 ```
 
-Arey Pi also ships an extension with native setup commands and automatic natural-language harness activation.
+Arey Pi also ships an extension with native setup commands,
+always-on workflow context injection,
+and simple protected-file guardrails.
 
 When the Arey Pi agents are available to `pi-subagents`, the project evaluator runtime name is:
 
@@ -129,34 +134,30 @@ arey-pi.project-evaluator
 
 ## Extension-backed workflow
 
-Arey Pi includes a polished extension-backed setup and natural-language workflow harness:
+Arey Pi includes a polished extension-backed setup and runtime harness:
 
 ```txt
 /arey-doctor      # check package, subagent, prompt, skill, and project readiness setup
 /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 --agentsmd  # create a starter AGENTS.md if missing
 /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
-# Development workflows are natural-language first:
-# "Implementa password reset"
-# "Corrige este bug"
-# "Revisa el current diff"
+/arey-bootstrap --force     # overwrite selected project-local agents and scaffold files
 ```
 
-The goal is that users work naturally without development commands.
 When the package is installed,
 Arey Pi automatically injects quiet harness context behind the scenes on every agent turn.
 The parent agent infers the work mode,
 acts as orchestrator,
-use specialist subagents when available,
-inject the relevant delivery guidance,
-and apply simple event-based guardrails for protected paths.
+uses specialist subagents when available,
+applies the relevant delivery guidance,
+and enforces simple event-based guardrails for protected env files.
 
 See:
 
-- `docs/commands.md` for setup commands and natural-language workflow behaviour;
+- `docs/README.md` for the package documentation index;
+- `docs/commands.md` for setup commands, runtime harness behaviour, and guardrails;
 - `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;
@@ -200,13 +201,14 @@ The policy layer,
 readiness workflow,
 documentation sync rule,
 core subagent role definitions,
-and professional setup extension commands exist.
-
-Arey Pi now includes always-on natural-language harness injection,
+professional setup extension commands,
+bootstrap scaffolding,
+always-on workflow context injection,
 focused prompts,
 TDD/spec-sync/review skills,
-and extension-core tests.
+protected env-file guardrails,
+and extension-core tests exist.
 
-Next improvements include stronger bootstrap scaffolding,
-custom Arey Pi tools,
-and deeper enforcement through Pi extension events.
+Next improvements include custom Arey Pi tools,
+more granular workflow events,
+and deeper enforcement through Pi extension hooks.

package/docs/README.md

@@ -0,0 +1,51 @@
+# Arey Pi Documentation
+
+This directory documents the Arey Pi package as it exists today.
+
+## Start here
+
+- `commands.md` documents the Pi extension commands,
+  the always-on workflow runtime,
+  and protected env-file guardrails.
+- `adoption.md` explains how to introduce Arey Pi into an existing repository.
+- `workflows.md` describes the internal delivery workflows the runtime expects agents to follow.
+- `workflow-diagram.md` provides a visual workflow map.
+- `pi-subagents.md` explains how Arey Pi agents should be used with `pi-subagents`.
+- `templates.md` documents every bootstrap template and its project-local target.
+
+## Current package surface
+
+Arey Pi currently provides:
+
+- a Pi extension at `extensions/arey-pi/`;
+- setup commands `/arey-doctor` and `/arey-bootstrap`;
+- automatic hidden workflow context injection before agent turns;
+- env-file write/edit guardrails;
+- six Arey Pi subagent role definitions;
+- focused skills for readiness,
+  spec sync,
+  TDD,
+  and engineering review;
+- focused prompt templates for assessment,
+  ADR review,
+  feature specs,
+  Red-Green-Refactor,
+  drift sync,
+  and engineering review;
+- operating rules under `rules/`;
+- bootstrap templates for `AGENTS.md`,
+  specs,
+  DBML,
+  ADRs,
+  glossary,
+  and project docs.
+
+## Maintenance rule
+
+When package behaviour changes,
+update the relevant docs in the same change:
+
+- command or runtime changes: `commands.md`, `workflows.md`, and `README.md`;
+- bootstrap target changes: `templates.md`, `commands.md`, tests, and `README.md`;
+- subagent changes: `pi-subagents.md`, `agents/README.md`, and `README.md`;
+- policy changes: `rules/README.md` and affected workflow docs.

package/docs/commands.md

@@ -1,9 +1,8 @@
 # Arey Pi Commands
 
-Arey Pi ships a Pi extension that registers native setup slash commands.
-Development workflows are intentionally natural-language first:
-when the package is installed,
-the extension injects quiet harness guidance automatically on every agent turn.
+Arey Pi ships a Pi extension that registers native setup slash commands and a runtime harness.
+When the package is installed,
+the extension injects quiet workflow guidance automatically before every agent turn and blocks unsafe env-file mutations.
 
 ## Command overview
 
@@ -137,8 +136,10 @@ Explicitly runs the same combined bootstrap path as `/arey-bootstrap` with no fl
 ```
 
 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.
+When used alone,
+it applies to the default full bootstrap path.
+For `AGENTS.md`,
+Arey Pi remains conservative: it creates the starter file when missing but does not replace an existing root `AGENTS.md`.
 
 Examples:
 
@@ -150,49 +151,75 @@ 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`.
 
-## Natural-language development workflows
-
-Arey Pi is designed to work without development slash commands.
-When the package is installed,
-the extension injects quiet harness context automatically before every agent turn.
-Users can simply ask naturally:
-
-```txt
-Implementa password reset
-Corrige este bug
-Revisa el current diff
-Evalúa este repo
-```
-
-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.
-
-The injected harness guidance emphasises:
+## Runtime workflow harness
+
+Arey Pi is designed to work without separate development slash commands.
+The slash commands are for setup and diagnostics;
+delivery work is handled by the always-on runtime harness.
+
+On `before_agent_start`,
+the extension injects hidden Arey Pi context that asks the parent agent to:
+
+- infer whether the request is a feature,
+  bugfix,
+  sync,
+  review,
+  assessment,
+  or mixed task;
+- act as the parent Arey Pi orchestrator;
+- use canonical specs and strict Red → Green → Refactor for behaviour changes;
+- reproduce bugs with meaningful failing regression tests before production changes;
+- check drift across specs,
+  tests,
+  code,
+  DBML,
+  ADRs,
+  glossary,
+  README files,
+  docs,
+  `AGENTS.md`,
+  skills,
+  prompts,
+  rules,
+  agents,
+  commands,
+  templates,
+  and tooling instructions;
+- delegate bounded work to Arey Pi subagents when available;
+- use builtin `scout`,
+  `context-builder`,
+  `planner`,
+  `reviewer`,
+  and `oracle` agents when they fit discovery,
+  planning,
+  second-opinion,
+  or fresh-review needs;
+- keep one writer in the active worktree;
+- report final evidence and residual risks clearly.
+
+The injected harness guidance references these Arey Pi agents:
 
 - `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.
+- `arey-pi.project-evaluator` for readiness assessment.
+
+## Guardrails
 
-While Arey Pi is active,
-Arey Pi applies simple tool-call guardrails:
+The extension listens for `tool_call` events and blocks write/edit operations targeting env files such as:
 
-- writes or edits to env files such as `.env` and `.env.local` are blocked; `.git/` and `node_modules/` remain readable and writable when the task genuinely requires them.
+```txt
+.env
+.env.local
+.env.production
+```
 
+This protection is intentionally narrow.
+It prevents accidental secret or environment mutation while leaving normal repository files available for legitimate work.
 
 ## Prompt templates and skills
 
 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.
+The intended default is conversational work plus automatic runtime harness injection.

package/docs/workflows.md

@@ -2,18 +2,12 @@
 
 See `docs/workflow-diagram.md` for a visual overview of the framework workflow.
 
-Arey Pi development workflows are natural-language first.
+Arey Pi workflows are conversational at the user boundary and structured internally.
 When the package is installed,
 the extension injects quiet harness guidance automatically before every agent turn.
 
 ## Feature Workflow
 
-Example request:
-
-```txt
-Implementa password reset
-```
-
 Expected flow:
 
 ```txt
@@ -40,12 +34,6 @@ The workflow should:
 
 ## Bugfix Workflow
 
-Example request:
-
-```txt
-Corrige el bug de verificación de email
-```
-
 Use this when behaviour is wrong.
 
 Expected flow:
@@ -60,12 +48,6 @@ and it should live outside production source directories by default.
 
 ## Sync Workflow
 
-Example request:
-
-```txt
-Sincroniza specs y docs para el current diff
-```
-
 Use this before completing non-trivial work or when drift is suspected.
 
 The sync check covers:
@@ -100,12 +82,6 @@ or justified unaffected statuses.
 
 ## Review Workflow
 
-Example request:
-
-```txt
-Revisa el current diff
-```
-
 Use this for adversarial engineering review.
 
 Review should cover:
@@ -127,12 +103,6 @@ Findings should be classified by severity.
 
 ## Assessment Workflow
 
-Example request:
-
-```txt
-Evalúa este repo
-```
-
 Use this to assess project readiness.
 
 The assessment is read-only by default.
@@ -178,19 +148,21 @@ end the turn and wait for completion rather than polling repeatedly.
 
 See `docs/pi-subagents.md` for detailed guidance.
 
-## Natural Language Workflow
+## Conversational Workflow Runtime
 
-Users do not need to memorise commands.
+Users do not need to memorise development commands.
+The extension provides hidden workflow context before every agent turn,
+so the parent agent should act as tech lead,
+select the appropriate workflow,
+and use specialist subagents when available.
 
-This should work:
+The runtime is intentionally quiet:
+it should improve delivery quality without adding ceremony to normal conversation.
 
-```txt
-Implement password reset.
-```
+## Guardrails
 
-The parent agent should act as tech lead,
-select the appropriate workflow,
-and use specialist subagents when available.
+The workflow runtime blocks write/edit operations to env files such as `.env` and `.env.local`.
+This prevents accidental mutation of secrets or environment configuration while keeping the rest of the repository available for normal work.
 
 ## Evidence Standard
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arey-pi",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "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",