arey-pi 0.3.0 → 0.4.0

package/README.md

@@ -143,7 +143,14 @@ Arey Pi includes a polished extension-backed workflow:
 The goal is that users can either speak naturally or use explicit commands,
 while Arey Pi handles the disciplined workflow behind the scenes.
 
-See `docs/commands.md` for detailed command behaviour, options, and examples.
+See:
+
+- `docs/commands.md` for detailed command behaviour, options, and examples;
+- `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;
+- `docs/pi-subagents.md` for optimised `pi-subagents` usage;
+- `docs/templates.md` for bootstrap template details.
 
 ## Development
 

package/agents/README.md

@@ -5,6 +5,29 @@ Arey Pi uses subagents to turn Arey Pi rules into repeatable delivery workflows.
 Subagents are not independent product owners.
 They are specialised engineering roles with bounded responsibilities, explicit handoffs, and shared commitment to canonical specs, TDD, quality, and rebuildability.
 
+## Relationship to pi-subagents
+
+Arey Pi assumes the parent Pi session owns orchestration.
+
+Specialist children should receive concrete,
+bounded tasks and return evidence-backed handoffs.
+They should not launch their own subagent workflows unless explicitly assigned a bounded fanout job with the `subagent` tool.
+
+Use Arey Pi agents for framework-specific delivery.
+Use builtin `pi-subagents` agents for generic support:
+
+- `scout` for local codebase reconnaissance;
+- `context-builder` for planning handoff context;
+- `planner` for implementation plans;
+- `worker` for approved generic implementation;
+- `reviewer` for fresh independent review;
+- `oracle` for second opinions and risky decisions;
+- `researcher` for external evidence when web access is available.
+
+Prefer fresh-context reviewers for adversarial review.
+Use forked context for `oracle` when the parent conversation history matters.
+Keep one writer in the active worktree at a time.
+
 ## Core Principles
 
 ### Specs remain canonical
@@ -179,14 +202,20 @@ Does not own:
 For meaningful feature or bug-fix work, use this sequence:
 
 ```txt
-1. tech-lead classifies change mode and scope
-2. spec-author writes or confirms canonical specs
-3. tdd-implementer performs Red → Green → Refactor
-4. spec-syncer verifies specs/tests/code and documentation alignment
-5. engineering-reviewer performs adversarial review
-6. tech-lead finalises evidence, risks, and commits
+1. parent tech lead classifies change mode and scope
+2. arey-pi.spec-author writes or confirms canonical specs
+3. arey-pi.tdd-implementer performs Red → Green → Refactor
+4. arey-pi.spec-syncer verifies specs/tests/code and documentation alignment
+5. fresh reviewers perform adversarial review when risk warrants it
+6. parent tech lead synthesises findings and finalises evidence, risks, and commits
 ```
 
+For broad or risky work,
+use builtin `scout`,
+`context-builder`,
+`planner`,
+or `oracle` before the Arey Pi delivery sequence.
+
 Small direct changes may skip specialised agents only when the tech lead can explicitly justify that specs, tests, architecture, DBML, ADRs, and documentation are unaffected.
 
 ## Handoff Contracts

package/agents/tech-lead.md

@@ -13,7 +13,10 @@ defaultReads: AGENTS.md, agents/README.md, rules/README.md, rules/core/principle
 You are the Arey Pi tech lead.
 Your job is to orchestrate high-quality software delivery under Arey Pi rules.
 
-You preserve scope, choose the correct change mode, coordinate specialist agents, and ensure final evidence satisfies Definition of Done.
+You preserve scope, choose the correct change mode, coordinate specialist work, and ensure final evidence satisfies Definition of Done.
+
+In normal Arey Pi use, the parent Pi session acts as the tech lead and calls specialist subagents.
+If this `arey-pi.tech-lead` agent is itself launched as a child, produce an orchestration plan and evidence checklist; do not attempt nested delegation unless the parent explicitly gave you the `subagent` tool for a bounded fanout task.
 
 ## Operating principles
 
@@ -30,7 +33,7 @@ Own:
 
 - classifying work as Spec-Driven Mode, Direct Change Mode, Rebuild Mode, Bootstrap Mode, or Assessment Mode;
 - decomposing work into spec, TDD, implementation, sync, review, and finalisation phases;
-- deciding when to use `spec-author`, `tdd-implementer`, `spec-syncer`, `engineering-reviewer`, or `project-evaluator`;
+- deciding when the parent should use `arey-pi.spec-author`, `arey-pi.tdd-implementer`, `arey-pi.spec-syncer`, `arey-pi.engineering-reviewer`, `arey-pi.project-evaluator`, or builtin `pi-subagents` roles such as `scout`, `planner`, `worker`, `reviewer`, and `oracle`;
 - making handoffs explicit and evidence-backed;
 - resolving conflicts only when the canonical source is clear;
 - asking the user when product intent or policy is ambiguous;
@@ -62,15 +65,20 @@ Small direct changes may skip specialist agents only when you can explicitly jus
 
 ## Delegation guidance
 
-Use `spec-author` when specs are missing, behaviour changes, DBML might change, ADRs may be warranted, or domain language changes.
+Use `arey-pi.spec-author` when specs are missing, behaviour changes, DBML might change, ADRs may be warranted, or domain language changes.
+
+Use `arey-pi.tdd-implementer` when accepted specs or bug reports need implementation through Red-Green-Refactor.
 
-Use `tdd-implementer` when accepted specs or bug reports need implementation through Red-Green-Refactor.
+Use `arey-pi.spec-syncer` near completion or whenever drift is suspected.
 
-Use `spec-syncer` near completion or whenever drift is suspected.
+Use `arey-pi.engineering-reviewer` for material implementation, generated code, high-risk tests, architecture concerns, security/privacy/operability risk, or missing quality-tooling evidence.
 
-Use `engineering-reviewer` for material implementation, generated code, high-risk tests, architecture concerns, security/privacy/operability risk, or missing quality-tooling evidence.
+Use `arey-pi.project-evaluator` for read-only repository readiness assessment.
 
-Use `project-evaluator` for read-only repository readiness assessment.
+Use builtin `scout`, `context-builder`, or `planner` before large changes when more context or planning is needed.
+Use builtin `oracle` for risky decisions and second opinions.
+Use fresh-context `reviewer` agents for independent adversarial review.
+Keep one writer in the active worktree at a time.
 
 ## Final response format
 

package/docs/adoption.md

@@ -0,0 +1,218 @@
+# Adopting Arey Pi
+
+This guide explains how to introduce Arey Pi into an existing repository.
+
+Arey Pi adoption should be incremental.
+Do not rewrite a project just to satisfy the framework.
+Start by making project intent,
+validation,
+and agent instructions discoverable.
+
+## Recommended Adoption Path
+
+### 1. Install the package
+
+Install Arey Pi in the project:
+
+```bash
+pi install -l npm:arey-pi
+```
+
+For subagent-backed workflows,
+install `pi-subagents` too:
+
+```bash
+pi install -l npm:pi-subagents
+```
+
+Optionally install `pi-intercom` when background subagents may need to ask the parent for blocking decisions:
+
+```bash
+pi install -l npm:pi-intercom
+```
+
+Reload Pi after installation:
+
+```txt
+/reload
+```
+
+### 2. Run doctor
+
+Check what Pi can discover:
+
+```txt
+/arey-doctor
+/subagents-doctor
+```
+
+Use these before and after bootstrap.
+
+### 3. Bootstrap safely
+
+Run:
+
+```txt
+/arey-bootstrap
+```
+
+With no flags,
+this creates a safe starter harness where files do not already exist:
+
+```txt
+.pi/agents/arey-pi/
+AGENTS.md
+specs/
+docs/
+```
+
+It does not overwrite existing files unless `--force` is used.
+
+### 4. Fill project-specific commands
+
+Edit `AGENTS.md` and replace command placeholders with real project commands.
+
+At minimum,
+agents should be able to discover:
+
+- dependency installation;
+- formatter;
+- lint/static analysis;
+- typecheck;
+- tests;
+- full validation command;
+- database validation or migration checks when applicable.
+
+### 5. Assess readiness
+
+Run:
+
+```txt
+/arey-assess
+```
+
+or:
+
+```txt
+/assess-project
+```
+
+Treat the report as a prioritised improvement plan,
+not as a reason to stop work.
+
+### 6. Adopt specs incrementally
+
+Start with high-value behaviour:
+
+- risky workflows;
+- customer-visible behaviour;
+- bug-prone areas;
+- persistence boundaries;
+- permissions and security-sensitive logic;
+- APIs and CLI contracts.
+
+Use Gherkin for behaviour specs.
+Use DBML for database specs when the project has persistence.
+
+### 7. Keep tests outside source trees
+
+Prefer dedicated test roots:
+
+```txt
+tests/
+test/
+__tests__/
+spec/
+```
+
+Mirror production module structure inside the test root where useful.
+
+Example:
+
+```txt
+src/domain/accounts/password-reset.ts
+tests/domain/accounts/password-reset.test.ts
+```
+
+Do not colocate new tests inside `src/` unless the project or framework requires it.
+
+## Adoption Modes
+
+### Light adoption
+
+Use this for small projects or early evaluation.
+
+- Install Arey Pi.
+- Run `/arey-bootstrap`.
+- Fill `AGENTS.md` commands.
+- Add specs only for new or risky changes.
+
+### Standard adoption
+
+Use this for active product repositories.
+
+- Complete light adoption.
+- Add Gherkin specs for core behaviours.
+- Add DBML if persistence exists.
+- Add ADRs for significant decisions.
+- Require `/arey-sync` before completing non-trivial work.
+
+### Strict adoption
+
+Use this for high-risk or agent-heavy projects.
+
+- Complete standard adoption.
+- Require TDD evidence for every production behaviour change.
+- Require separate test directories.
+- Require readiness assessment follow-ups.
+- Use engineering review for significant changes.
+- Consider coverage and mutation testing for critical behaviour.
+
+## Subagent Adoption Notes
+
+See `docs/pi-subagents.md` for deeper guidance.
+
+In short:
+
+- keep orchestration in the parent Pi session;
+- use Arey Pi agents for framework-specific delivery;
+- use builtin `scout`,
+  `planner`,
+  `worker`,
+  `reviewer`,
+  `oracle`,
+  `context-builder`,
+  and `researcher` for generic support;
+- prefer fresh reviewers for independent review;
+- use `oracle` when the decision itself is risky;
+- keep one writer in the active worktree at a time;
+- use `.pi/settings.json` `subagents.agentOverrides` for model/thinking tweaks instead of copying builtin agents.
+
+## What Not To Do
+
+Do not:
+
+- create low-value ADRs for trivial choices;
+- generate broad specs that nobody will maintain;
+- move all tests or docs in a single unrelated change;
+- accept shallow generated tests as proof of quality;
+- overwrite existing project conventions without review;
+- treat bootstrap as a substitute for project-specific instructions.
+
+## Completion Standard
+
+After adoption work,
+run:
+
+```txt
+/arey-doctor
+/arey-assess
+```
+
+A good first adoption result is not perfection.
+It is a repository where humans and agents can discover how to work safely,
+validate changes,
+and keep specs,
+docs,
+tests,
+and code aligned.

package/docs/pi-subagents.md

@@ -0,0 +1,292 @@
+# Using pi-subagents with Arey Pi
+
+Arey Pi is designed to work well with `pi-subagents`.
+
+`pi-subagents` gives the parent Pi session focused child agents for scouting,
+planning,
+implementation,
+review,
+and advisory second opinions.
+Arey Pi adds an opinionated delivery framework around specs,
+TDD,
+quality,
+and synchronisation.
+
+## Install
+
+Install both packages in the project:
+
+```bash
+pi install -l npm:arey-pi
+pi install -l npm:pi-subagents
+```
+
+Optional:
+
+```bash
+pi install -l npm:pi-intercom
+```
+
+`pi-intercom` is useful when background child agents may need to ask the parent for a blocking decision instead of guessing.
+It is not required for normal use.
+
+Reload Pi after installation:
+
+```txt
+/reload
+```
+
+Then check setup:
+
+```txt
+/arey-doctor
+/subagents-doctor
+```
+
+## Bootstrap
+
+Run:
+
+```txt
+/arey-bootstrap
+```
+
+This installs Arey Pi's project-local subagent definitions into:
+
+```txt
+.pi/agents/arey-pi/
+```
+
+The runtime names include the package prefix:
+
+```txt
+arey-pi.tech-lead
+arey-pi.spec-author
+arey-pi.tdd-implementer
+arey-pi.spec-syncer
+arey-pi.engineering-reviewer
+arey-pi.project-evaluator
+```
+
+## Parent Owns Orchestration
+
+The parent Pi session should own orchestration.
+
+Child agents should receive concrete,
+bounded tasks.
+They should not create their own subagent workflows unless explicitly launched with the `subagent` tool for a bounded fanout task.
+
+Good parent request:
+
+```txt
+Implement password reset following Arey Pi.
+Use specialist subagents where useful.
+```
+
+Good child handoff:
+
+```txt
+Use arey-pi.tdd-implementer to implement the accepted password-reset scenarios.
+Write tests under tests/,
+not beside production files.
+Report Red-Green-Refactor evidence and validation commands.
+```
+
+Poor child handoff:
+
+```txt
+Figure out everything and use more subagents if needed.
+```
+
+## Recommended Arey Pi Orchestration
+
+For meaningful feature work:
+
+```txt
+clarify → spec-author → tdd-implementer → fresh reviewers → sync/fix → finalise
+```
+
+For risky decisions:
+
+```txt
+oracle → parent decision → worker or Arey Pi implementer
+```
+
+For hard codebase discovery:
+
+```txt
+scout/context-builder → planner → Arey Pi implementation workflow
+```
+
+For review loops:
+
+```txt
+worker → fresh reviewers → parent synthesis → single fix worker
+```
+
+Keep one writer in the active worktree at a time.
+Use parallel agents for read-only scouting,
+planning,
+and review.
+
+## Context Choices
+
+Use fresh context for independent review:
+
+```txt
+fresh reviewers for correctness,
+tests,
+and simplicity
+```
+
+Fresh reviewers are less likely to inherit the parent agent's assumptions.
+
+Use forked context for decision review where conversation history matters:
+
+```txt
+oracle reviewing current plan and assumptions
+```
+
+Forked context is useful when the child should understand prior reasoning,
+but it is not a substitute for a focused task prompt.
+
+## Builtin Agents and Arey Pi Agents
+
+Use builtin `pi-subagents` agents for generic support:
+
+- `scout` for local codebase reconnaissance;
+- `context-builder` for implementation handoff context;
+- `planner` for implementation plans;
+- `worker` for generic approved implementation;
+- `reviewer` for generic review and small fixes;
+- `oracle` for second opinions and decision challenges;
+- `researcher` for external evidence when web access is available.
+
+Use Arey Pi agents for framework-specific delivery:
+
+- `arey-pi.spec-author` for Gherkin,
+  DBML,
+  ADR,
+  and glossary impact;
+- `arey-pi.tdd-implementer` for strict Red-Green-Refactor;
+- `arey-pi.spec-syncer` for spec and documentation sync;
+- `arey-pi.engineering-reviewer` for Arey Pi quality review;
+- `arey-pi.project-evaluator` for readiness audits.
+
+## Prompting Pattern
+
+A strong subagent task should include:
+
+- goal;
+- relevant files,
+  diffs,
+  specs,
+  plans,
+  or decisions;
+- success criteria;
+- hard constraints;
+- validation expectations;
+- expected output format;
+- stop rules.
+
+Example:
+
+```txt
+Review the current diff as arey-pi.engineering-reviewer.
+Focus on correctness,
+test quality and location,
+simplicity,
+security,
+and documentation sync.
+Do not modify files.
+Return blocking findings first with file references.
+```
+
+## Async and Background Work
+
+Use background subagents for long-running implementation,
+large reviews,
+or broad audits.
+
+If the parent has no useful independent work while a background child runs,
+end the turn and wait for completion rather than polling repeatedly.
+
+Use status checks when needed:
+
+```txt
+Show active async runs.
+```
+
+or:
+
+```txt
+/subagents-doctor
+```
+
+## Model Overrides
+
+Builtin `pi-subagents` agents inherit the current Pi default model.
+For normal tweaks,
+prefer `subagents.agentOverrides` in settings rather than copying builtin agents.
+
+Project-local example:
+
+```json
+{
+  "subagents": {
+    "agentOverrides": {
+      "reviewer": {
+        "thinking": "high",
+        "fallbackModels": ["openai/gpt-5-mini"]
+      }
+    }
+  }
+}
+```
+
+Use `.pi/settings.json` for project overrides.
+Use `~/.pi/agent/settings.json` for user-wide overrides.
+
+## Recommended Natural Language Requests
+
+```txt
+Ask oracle to challenge this plan before we edit.
+```
+
+```txt
+Use scout to map the auth flow,
+then ask me the clarification questions that matter.
+```
+
+```txt
+Run parallel reviewers on this diff:
+one for correctness,
+one for tests,
+and one for unnecessary complexity.
+```
+
+```txt
+Have a worker implement this approved plan,
+then run fresh reviewers and apply only fixes worth doing now.
+```
+
+```txt
+Run a review loop on this change with a max of 3 rounds.
+```
+
+## Arey Pi Completion Rule
+
+Subagents can contribute evidence,
+but the parent session finalises.
+
+The final response should still include:
+
+```txt
+- Specs:
+- Tests/TDD, including test location:
+- Validation:
+- Spec sync:
+- Documentation sync:
+- Quality review:
+- Residual risks:
+```