arey-pi 0.2.0 → 0.4.0

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:
+```

package/docs/templates.md

@@ -0,0 +1,146 @@
+# Arey Pi Templates
+
+Arey Pi ships starter templates used by `/arey-bootstrap`.
+
+Templates are intentionally useful but generic.
+They should be edited after bootstrap to reflect the real project.
+
+## Template List
+
+```txt
+templates/AGENTS.md
+templates/adr.md
+templates/feature.feature
+templates/database.dbml
+templates/glossary.md
+templates/project-readiness-report.md
+templates/specs-readme.md
+templates/features-readme.md
+templates/database-readme.md
+templates/architecture-readme.md
+templates/decisions-readme.md
+templates/docs-readme.md
+```
+
+## Bootstrap Targets
+
+`/arey-bootstrap` maps templates to project files:
+
+```txt
+templates/AGENTS.md                         → AGENTS.md
+templates/specs-readme.md                   → specs/README.md
+templates/features-readme.md                → specs/features/README.md
+templates/feature.feature                   → specs/features/example.feature
+templates/database-readme.md                → specs/database/README.md
+templates/database.dbml                     → specs/database/schema.dbml
+templates/architecture-readme.md            → specs/architecture/README.md
+templates/decisions-readme.md               → specs/decisions/README.md
+templates/adr.md                            → specs/decisions/0001-record-architecture-decision.md
+templates/glossary.md                       → specs/glossary.md
+templates/docs-readme.md                    → docs/README.md
+templates/project-readiness-report.md       → docs/project-readiness-report.md
+```
+
+Existing files are not overwritten unless `--force` is used.
+
+## `AGENTS.md`
+
+The `AGENTS.md` template provides project-level AI harness instructions.
+
+After bootstrap,
+replace placeholders with real project commands:
+
+- dependency installation;
+- formatting;
+- lint/static analysis;
+- typecheck;
+- tests;
+- full validation;
+- database validation when applicable.
+
+Add local architecture,
+safety,
+and operational constraints.
+
+Use nested `AGENTS.md` files for subtrees that need local instructions.
+
+## `feature.feature`
+
+The Gherkin template includes:
+
+- tags;
+- a feature description;
+- actor/outcome framing;
+- a rule section;
+- background context;
+- happy path;
+- scenario outline for validation or boundary cases;
+- regression scenario.
+
+Delete sections that are not useful for the real behaviour.
+Do not keep placeholder scenarios as fake coverage.
+
+## `database.dbml`
+
+The DBML template demonstrates:
+
+- project metadata;
+- enum modelling;
+- primary keys;
+- unique constraints;
+- indexes;
+- foreign-key relationships;
+- JSON payload notes;
+- table notes.
+
+Replace the example schema with the canonical project schema.
+Do not leave example tables in a real project unless they are clearly marked as placeholders and not used as canonical truth.
+
+## `adr.md`
+
+The ADR template is decision-focused.
+
+Use it for significant technical decisions,
+not routine implementation details.
+
+A good ADR should include:
+
+- status;
+- date;
+- context;
+- decision drivers;
+- options considered;
+- the chosen decision;
+- consequences;
+- validation;
+- supersession and relationship metadata;
+- revisit conditions.
+
+## `glossary.md`
+
+The glossary template is for durable domain language.
+
+Add terms when names or meanings matter to behaviour,
+specs,
+architecture,
+or user-facing concepts.
+
+Do not use it as a dumping ground for obvious technical vocabulary.
+
+## `project-readiness-report.md`
+
+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.
+
+## Template Maintenance
+
+When templates change,
+update:
+
+- `docs/templates.md`;
+- `docs/commands.md` if bootstrap behaviour changes;
+- `README.md` if user-facing package behaviour changes;
+- extension tests if scaffold targets change.

package/docs/workflow-diagram.md

@@ -0,0 +1,92 @@
+# Arey Pi Workflow Diagram
+
+This diagram shows the intended Arey Pi delivery workflow.
+
+The parent Pi session owns orchestration.
+Specialist subagents contribute bounded evidence,
+but the parent decides when to continue,
+ask the user,
+repair,
+or finalise.
+
+```mermaid
+graph TD
+  A["User request"] --> B["Parent acts as Arey Pi tech lead"]
+  B --> C{"Classify change mode"}
+
+  C -->|"Assessment"| EVAL["Project evaluator"]
+  EVAL --> EVALREPORT["Readiness report and improvement plan"]
+
+  C -->|"Bootstrap"| BOOT["arey-bootstrap"]
+  BOOT --> HARNESS["AGENTS.md, specs, docs, templates, project agents"]
+  HARNESS --> DOCTOR["arey-doctor and subagents-doctor"]
+
+  C -->|"Direct change"| DIRECT{"Specs, tests, docs unaffected?"}
+  DIRECT -->|"No or unclear"| SPEC
+  DIRECT -->|"Yes, justified"| IMPL
+
+  C -->|"Feature, bugfix, rebuild, risky change"| CONTEXT{"Enough context?"}
+  CONTEXT -->|"No"| RECON["Scout, context-builder, or planner"]
+  RECON --> SPEC["Spec author"]
+  CONTEXT -->|"Yes"| SPEC
+
+  SPEC --> SPECCHECK{"Canonical intent clear?"}
+  SPECCHECK -->|"No"| ASK["Ask user or resolve conflict"]
+  ASK --> SPEC
+  SPECCHECK -->|"Yes"| IMPL["TDD implementer"]
+
+  IMPL --> RED["Red: failing behaviour or regression test"]
+  RED --> GREEN["Green: minimal high-quality implementation"]
+  GREEN --> REFACTOR["Refactor while tests stay green"]
+  REFACTOR --> VALIDATE["Run validation and quality tooling"]
+
+  VALIDATE --> SYNC["Spec syncer"]
+  SYNC --> SYNCCHECK{"Specs and docs aligned?"}
+  SYNCCHECK -->|"No"| REPAIR["Repair sync gaps"]
+  REPAIR --> VALIDATE
+  SYNCCHECK -->|"Yes"| REVIEWGATE{"Risk warrants review?"}
+
+  REVIEWGATE -->|"Yes"| REVIEW["Fresh reviewers or engineering reviewer"]
+  REVIEW --> FINDINGS{"Blocking findings?"}
+  FINDINGS -->|"Yes"| FIX["Single writer applies accepted fixes"]
+  FIX --> VALIDATE
+  FINDINGS -->|"No"| DONE
+
+  REVIEWGATE -->|"No"| DONE["Parent finalises"]
+
+  DONE --> REPORT["Done summary with specs, TDD, validation, sync, quality, commits, and risks"]
+
+  ORACLE["Oracle second opinion"] -.-> B
+```
+
+## Safety Rules
+
+- The parent session owns orchestration.
+- Use fresh reviewers for independent adversarial review.
+- Use `oracle` when the decision itself is risky.
+- Use `scout`,
+  `context-builder`,
+  or `planner` before large changes when context is weak.
+- Keep one writer in the active worktree at a time.
+- Parallel subagents are best for read-only review,
+  planning,
+  scouting,
+  and audits.
+- Chains are best for repeatable sequential workflows where one step's output feeds the next.
+
+## Required Completion Evidence
+
+```txt
+Done summary:
+- Behaviour/spec impact:
+- Tests/TDD, including test location:
+- Validation:
+- Quality tooling:
+- Spec sync:
+- Documentation sync:
+- Architecture/code quality:
+- Architecture/ADR/glossary:
+- Database/DBML:
+- Commits:
+- Residual risks:
+```