arey-pi 0.2.0 → 0.4.0

package/README.md

@@ -25,7 +25,7 @@ Arey Pi is built around these guarantees:
 - behaviour is captured in canonical Gherkin specs;
 - database projects keep canonical DBML specs precisely synchronised;
 - TDD is mandatory for production behaviour changes;
-- tests must be meaningful, reviewed, and strengthened with coverage or mutation testing where risk warrants it;
+- tests must be meaningful, reviewed, kept outside production source directories, and strengthened with coverage or mutation testing where risk warrants it;
 - architecture and code must meet a senior engineering quality bar;
 - significant technical decisions are captured in high-quality ADRs;
 - specs, tests, code, DBML, ADRs, glossary, and architecture docs stay synchronised;
@@ -38,10 +38,12 @@ Arey Pi is built around these guarantees:
 
 ```txt
 agents/      # Arey Pi subagent role definitions for pi-subagents
-extensions/  # Slash commands for doctor, bootstrap, and workflows
+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
 ```
 
 The rules are the policy layer.
@@ -125,9 +127,12 @@ Arey Pi includes a polished extension-backed workflow:
 
 ```txt
 /arey-doctor      # check package, subagent, prompt, skill, and project readiness setup
-/arey-bootstrap   # install project-local Arey Pi agents
+/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 --force     # overwrite existing project-local Arey Pi agents
+/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
 /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
@@ -138,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
 
@@ -147,10 +159,11 @@ Arey Pi uses Bun as its package manager and Biome for extension formatting and l
 ```bash
 bun install
 bun run format
+bun run test
 bun run check
 ```
 
-`bun run check` runs Biome linting and TypeScript type checking.
+`bun run check` runs Biome linting, TypeScript type checking, and Bun tests.
 
 ## Rule categories
 

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/engineering-reviewer.md

@@ -44,6 +44,7 @@ Check:
 - whether domain concepts and contracts are explicit;
 - whether error handling, security, privacy, and edge cases are appropriate;
 - whether tests assert behaviour and would catch plausible regressions;
+- whether tests are kept in a dedicated test/spec directory rather than colocated with production source files without justification;
 - whether quality tooling ran and is sufficient for project risk;
 - whether durable decisions require ADRs;
 - whether DBML, Gherkin, glossary, architecture docs, README files, docs, AGENTS.md, skills, prompts, rules, agents, commands, or tooling instructions may need sync;
@@ -69,7 +70,7 @@ Return:
 Engineering review:
 - Blocking findings:
 - High/medium/low findings:
-- Test quality:
+- Test quality and location:
 - Tooling/validation:
 - Architecture/code quality:
 - Security/privacy/operability:

package/agents/tdd-implementer.md

@@ -22,6 +22,7 @@ Own:
 
 - deriving tests from accepted specs, bug reports, or explicit requirements;
 - writing failing tests before production behaviour;
+- placing tests in a dedicated test/spec directory outside production source trees by default;
 - implementing the smallest high-quality production change that satisfies the tests;
 - refactoring after tests pass;
 - keeping tests meaningful and behaviour-focused;
@@ -56,6 +57,9 @@ If you cannot demonstrate Red-Green-Refactor because of project constraints, sta
 Tests must constrain behaviour.
 They should cover important success paths, edge cases, failure paths, permissions, contracts, and regressions where relevant.
 
+Tests must not be colocated beside production files in `src/` or equivalent source directories unless an existing project convention, framework constraint, or user-approved exception requires it.
+Prefer mirroring production module structure under `tests/`, `test/`, `__tests__/`, or `spec/`.
+
 Weak tests are not acceptable evidence merely because they pass.
 Use mutation testing, coverage, or explicit test review where appropriate to risk.
 
@@ -71,7 +75,7 @@ Return:
 ```txt
 Implementation handoff:
 - Changed files:
-- Tests added/updated:
+- Tests added/updated and location:
 - Red-Green-Refactor evidence:
 - Validation commands:
 - Spec impact:

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

@@ -1,6 +1,7 @@
 # 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:
 
@@ -11,7 +12,7 @@ The commands are designed for two modes of use:
 
 ```txt
 /arey-doctor
-/arey-bootstrap [--agentsmd] [--force]
+/arey-bootstrap [--agentsmd] [--specs] [--docs] [--full] [--force]
 /arey-feature <feature request>
 /arey-bugfix <bug description>
 /arey-sync [scope]
@@ -28,6 +29,7 @@ It reports:
 - Arey Pi package version;
 - current project path;
 - whether packaged rules are present;
+- whether packaged templates are present;
 - whether packaged agents are present;
 - whether `pi-subagents` appears to be installed;
 - whether project-local Arey Pi agents exist in `.pi/agents/arey-pi/`;
@@ -49,15 +51,23 @@ or when subagent workflows are not behaving as expected.
 
 ## `/arey-bootstrap`
 
-Installs Arey Pi's packaged subagent definitions into the current project.
+Installs Arey Pi's packaged subagent definitions into the current project and performs a safe starter scaffold.
 
-Default target:
+With no flags, `/arey-bootstrap` runs the full bootstrap path:
+
+```txt
+--agentsmd --specs --docs
+```
+
+Default agent target:
 
 ```txt
 .pi/agents/arey-pi/
 ```
 
-By default, existing project-local agent files are not overwritten.
+By default, existing project-local agent files and scaffold files are not overwritten.
+Starter scaffold files are copied from the packaged `templates/` directory.
+Selective flags are available when you only want one part of the scaffold.
 
 Usage:
 
@@ -65,6 +75,24 @@ Usage:
 /arey-bootstrap
 ```
 
+This creates or installs, where missing:
+
+```txt
+.pi/agents/arey-pi/
+AGENTS.md
+specs/README.md
+specs/features/README.md
+specs/features/example.feature
+specs/database/README.md
+specs/database/schema.dbml
+specs/architecture/README.md
+specs/decisions/README.md
+specs/decisions/0001-record-architecture-decision.md
+specs/glossary.md
+docs/README.md
+docs/project-readiness-report.md
+```
+
 Options:
 
 ```txt
@@ -73,13 +101,61 @@ Options:
 
 Also creates a starter root `AGENTS.md` when one does not already exist.
 
+```txt
+/arey-bootstrap --specs
+```
+
+Creates starter Arey Pi spec structure when files do not already exist:
+
+```txt
+specs/README.md
+specs/features/README.md
+specs/features/example.feature
+specs/database/README.md
+specs/database/schema.dbml
+specs/architecture/README.md
+specs/decisions/README.md
+specs/decisions/0001-record-architecture-decision.md
+specs/glossary.md
+```
+
+```txt
+/arey-bootstrap --docs
+```
+
+Creates starter project documentation structure when files do not already exist:
+
+```txt
+docs/README.md
+docs/project-readiness-report.md
+```
+
+```txt
+/arey-bootstrap --full
+```
+
+Explicitly runs the same combined bootstrap path as `/arey-bootstrap` with no flags:
+
+```txt
+--agentsmd --specs --docs
+```
+
 ```txt
 /arey-bootstrap --force
 ```
 
-Overwrites existing project-local Arey Pi agent files.
+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.
 
+Examples:
+
+```txt
+/arey-bootstrap --specs --docs
+/arey-bootstrap --full
+/arey-bootstrap --full --force
+```
+
 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`