arey-pi 0.3.0 → 0.5.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`.
@@ -143,7 +149,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
 
@@ -184,6 +197,12 @@ documentation sync rule,
 core subagent role definitions,
 and professional extension commands exist.
 
-Next milestones include richer templates,
+Arey Pi now includes stronger workflow command contracts,
+focused prompts,
+TDD/spec-sync/review skills,
+and extension-core tests.
+
+Next improvements include guided interactive workflows,
 stronger bootstrap scaffolding,
-and deeper integration with `pi-subagents` discovery.
+custom Arey Pi tools,
+and deeper enforcement through Pi extension events.

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/commands.md

@@ -181,13 +181,16 @@ The expected workflow is:
 spec-author → tdd-implementer → spec-syncer → engineering-reviewer
 ```
 
+The command now sends a stronger execution contract.
 The workflow should:
 
-- confirm or update canonical specs;
+- identify scope, non-goals, risk, and unknowns;
+- confirm or update canonical specs before production behaviour changes;
 - 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.
+- 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.
 
 ## `/arey-bugfix`
 
@@ -205,12 +208,15 @@ Example:
 /arey-bugfix Users can bypass email verification by refreshing the session
 ```
 
+The command now sends a regression-test-first execution contract.
 The workflow should:
 
-- reproduce the bug with a failing regression test;
+- 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 TDD evidence visible;
+- 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`
@@ -247,6 +253,12 @@ The command asks the parent agent to verify alignment across:
 - 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
@@ -329,6 +341,32 @@ 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.