arey-pi 0.3.0 → 0.4.0

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

package/docs/workflows.md

@@ -0,0 +1,213 @@
+# Arey Pi Workflows
+
+See `docs/workflow-diagram.md` for a visual overview of the framework workflow.
+
+Arey Pi workflows can be started with slash commands or natural language.
+
+The slash commands make the intended process explicit.
+Natural language should still follow the same rules when the user asks to work following Arey Pi.
+
+## Feature Workflow
+
+Command:
+
+```txt
+/arey-feature <feature request>
+```
+
+Expected flow:
+
+```txt
+parent tech lead → arey-pi.spec-author → arey-pi.tdd-implementer → arey-pi.spec-syncer → fresh reviewers → parent finalisation
+```
+
+For broad or risky changes,
+use builtin `scout`,
+`context-builder`,
+or `planner` before the Arey Pi delivery flow.
+
+Use this for new behaviour or meaningful behaviour changes.
+
+The workflow should:
+
+1. clarify scope and change mode;
+2. confirm or author canonical Gherkin specs;
+3. add a failing test in a dedicated test directory;
+4. implement the smallest high-quality production change;
+5. refactor while tests remain green;
+6. synchronise specs and documentation;
+7. review engineering quality when risk warrants it;
+8. report evidence and residual risks.
+
+## Bugfix Workflow
+
+Command:
+
+```txt
+/arey-bugfix <bug description>
+```
+
+Use this when behaviour is wrong.
+
+Expected flow:
+
+```txt
+reproduce with failing regression test → fix → validate → sync → review
+```
+
+Bug fixes require a regression test.
+The regression test should fail for the bug before the fix,
+and it should live outside production source directories by default.
+
+## Sync Workflow
+
+Command:
+
+```txt
+/arey-sync [scope]
+```
+
+Use this before completing non-trivial work or when drift is suspected.
+
+The sync check covers:
+
+- Gherkin specs;
+- tests;
+- code;
+- DBML;
+- ADRs;
+- glossary;
+- architecture docs;
+- README files;
+- `docs/`;
+- `AGENTS.md`;
+- skills,
+  prompts,
+  rules,
+  agents,
+  commands,
+  tooling instructions,
+  examples,
+  and templates.
+
+The final result should include both spec and documentation status:
+
+```txt
+Specs updated
+Docs updated
+```
+
+or justified unaffected statuses.
+
+## Review Workflow
+
+Command:
+
+```txt
+/arey-review [scope]
+```
+
+Use this for adversarial engineering review.
+
+Review should cover:
+
+- architecture and code quality;
+- test quality and test location;
+- tooling and validation evidence;
+- security and privacy;
+- reliability and operability;
+- maintainability;
+- generated-code quality;
+- spec,
+  ADR,
+  DBML,
+  glossary,
+  and documentation sync concerns.
+
+Findings should be classified by severity.
+
+## Assessment Workflow
+
+Command:
+
+```txt
+/arey-assess [scope]
+```
+
+Use this to assess project readiness.
+
+The assessment is read-only by default.
+It should produce scores,
+evidence,
+blockers,
+quick wins,
+and a prioritised improvement plan.
+
+## Bootstrap Workflow
+
+Command:
+
+```txt
+/arey-bootstrap
+```
+
+With no flags,
+bootstrap installs project-local Arey Pi agents and creates starter harness files where missing.
+
+Use selective flags only when needed:
+
+```txt
+/arey-bootstrap --agentsmd
+/arey-bootstrap --specs
+/arey-bootstrap --docs
+/arey-bootstrap --force
+```
+
+## Subagent Orchestration Pattern
+
+Keep orchestration in the parent Pi session.
+Child agents should receive bounded tasks and should not launch their own subagent workflows unless explicitly assigned a bounded fanout job.
+
+Use fresh-context reviewers for independent review.
+Use `oracle` when a decision needs a second opinion before implementation.
+Use one writer in the active worktree at a time.
+
+For long-running work,
+background subagents are appropriate.
+If the parent has no useful independent work,
+end the turn and wait for completion rather than polling repeatedly.
+
+See `docs/pi-subagents.md` for detailed guidance.
+
+## Natural Language Workflow
+
+Users do not need to memorise commands.
+
+This should work:
+
+```txt
+Implement password reset following Arey Pi.
+```
+
+The parent agent should act as tech lead,
+select the appropriate workflow,
+and use specialist subagents when available.
+
+## Evidence Standard
+
+Every non-trivial workflow should finish with:
+
+```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:
+```

package/extensions/arey-pi/core.ts

@@ -60,17 +60,17 @@ export type WorkflowKind = "feature" | "bugfix" | "sync" | "review" | "assess" |
 
 export function workflowMessage(kind: WorkflowKind, args: string): string {
   const target = args.trim() || "the current repository/task";
-  const common = `Act as the Arey Pi tech lead. Use pi-subagents when available and appropriate. Keep orchestration authority in the parent session. Follow Arey Pi rules, preserve TDD, and report evidence clearly.`;
+  const common = `Act as the Arey Pi tech lead. Use pi-subagents when available and appropriate. Keep orchestration authority in the parent session, give child agents bounded tasks, and keep one writer in the active worktree at a time. Follow Arey Pi rules, preserve TDD, and report evidence clearly.`;
 
   switch (kind) {
     case "feature":
-      return `${common}\n\nRun the Arey Pi feature workflow for: ${target}\n\nExpected flow: spec-author for canonical specs, tdd-implementer for Red-Green-Refactor, spec-syncer for final alignment, and engineering-reviewer for adversarial quality review when risk warrants it.`;
+      return `${common}\n\nRun the Arey Pi feature workflow for: ${target}\n\nExpected flow: arey-pi.spec-author for canonical specs, arey-pi.tdd-implementer for Red-Green-Refactor, arey-pi.spec-syncer for final alignment, and fresh reviewers or arey-pi.engineering-reviewer for adversarial quality review when risk warrants it. Use scout/context-builder/planner first if the codebase context is not clear.`;
     case "bugfix":
-      return `${common}\n\nRun the Arey Pi bugfix workflow for: ${target}\n\nStart with a regression test that fails for the bug, then implement the minimal high-quality fix, synchronise specs, and review engineering quality.`;
+      return `${common}\n\nRun the Arey Pi bugfix workflow for: ${target}\n\nStart with a regression test that fails for the bug, keep tests outside production source directories by default, implement the minimal high-quality fix, synchronise specs and docs, and review engineering quality.`;
     case "sync":
       return `${common}\n\nRun Arey Pi spec and documentation sync for: ${target}\n\nVerify Gherkin, tests, code, DBML, ADRs, glossary, architecture docs, README files, docs, AGENTS.md, skills, prompts, rules, agents, commands, and tooling instructions. End with both a spec status and a documentation status.`;
     case "review":
-      return `${common}\n\nRun an Arey Pi engineering review for: ${target}\n\nReview architecture, code quality, test quality, quality tooling, security, privacy, operability, maintainability, and spec/ADR/DBML concerns. Classify findings by severity.`;
+      return `${common}\n\nRun an Arey Pi engineering review for: ${target}\n\nPrefer fresh-context review. Review architecture, code quality, test quality and location, quality tooling, security, privacy, operability, maintainability, and spec/ADR/DBML/documentation concerns. Classify findings by severity.`;
     case "assess":
       return `${common}\n\nAssess this repository against Arey Pi Project Readiness. Audit only by default. Produce scores, evidence, blockers, quick wins, and a prioritised improvement plan.`;
     default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arey-pi",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "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",
@@ -24,6 +24,7 @@
   ],
   "files": [
     "agents/",
+    "assets/",
     "extensions/",
     "docs/",
     "skills/",
@@ -42,7 +43,8 @@
     ],
     "prompts": [
       "./prompts"
-    ]
+    ],
+    "image": "https://cdn.jsdelivr.net/gh/alereyleyva/arey-pi@main/assets/arey-pi-logo.png"
   },
   "scripts": {
     "format": "biome format --write .",

package/templates/AGENTS.md

@@ -2,7 +2,7 @@
 
 This project uses Arey Pi.
 
-## Delivery rules
+## Delivery Rules
 
 - Treat canonical specs as the source of truth.
 - Use Gherkin for behaviour specs.
@@ -14,8 +14,101 @@ This project uses Arey Pi.
 - Run formatter, lint/static analysis, typecheck, tests, and relevant dynamic analysis where available.
 - Use incremental Conventional Commits for meaningful steps.
 
+## Project Commands
+
+Document the project-specific commands here.
+Agents should run the narrowest relevant validation first,
+then the composed project check before completion.
+
+```bash
+# Install dependencies
+<package-manager> install
+
+# Format
+<package-manager> run format
+
+# Lint/static analysis
+<package-manager> run lint
+
+# Typecheck
+<package-manager> run typecheck
+
+# Test
+<package-manager> run test
+
+# Full validation
+<package-manager> run check
+```
+
+## Specs and Documentation
+
+Canonical specs should live under:
+
+```txt
+specs/features/
+specs/database/
+specs/architecture/
+specs/decisions/
+specs/glossary.md
+```
+
+Project-facing documentation should live under:
+
+```txt
+docs/
+README.md
+AGENTS.md
+```
+
+Every completed change should report:
+
+```txt
+Specs updated
+```
+
+or:
+
+```txt
+Specs unaffected: <reason>
+```
+
+and:
+
+```txt
+Docs updated
+```
+
+or:
+
+```txt
+Docs unaffected: <reason>
+```
+
+## Test Layout
+
+Keep tests outside production source directories by default.
+
+Preferred examples:
+
+```txt
+src/domain/accounts/password-reset.ts
+tests/domain/accounts/password-reset.test.ts
+```
+
+Avoid creating colocated tests such as:
+
+```txt
+src/domain/accounts/password-reset.test.ts
+```
+
+unless this repository documents that convention explicitly.
+
 ## Subagents
 
+Keep orchestration in the parent Pi session.
+Child agents should receive concrete,
+bounded tasks and should not launch their own subagent workflows unless explicitly assigned a bounded fanout job.
+
 Project-local Arey Pi subagents live in:
 
 ```txt
@@ -23,3 +116,36 @@ Project-local Arey Pi subagents live in:
 ```
 
 Use them through pi-subagents when available.
+Run `/subagents-doctor` if subagent discovery or async coordination looks wrong.
+
+Suggested Arey Pi roles:
+
+- `arey-pi.tech-lead` for orchestration;
+- `arey-pi.spec-author` for canonical specs;
+- `arey-pi.tdd-implementer` for Red-Green-Refactor;
+- `arey-pi.spec-syncer` for spec and documentation alignment;
+- `arey-pi.engineering-reviewer` for adversarial quality review;
+- `arey-pi.project-evaluator` for readiness assessment.
+
+Useful builtin `pi-subagents` roles:
+
+- `scout` for fast codebase reconnaissance;
+- `context-builder` for stronger planning handoff context;
+- `planner` for implementation plans;
+- `worker` for approved generic implementation;
+- `reviewer` for fresh-context reviews;
+- `oracle` for risky decisions and second opinions;
+- `researcher` for external evidence when web access is available.
+
+Prefer fresh reviewers for independent review.
+Use `oracle` when prior conversation context and decision drift matter.
+Keep one writer in the active worktree at a time.
+
+## Local Overrides
+
+Add repository-specific technology,
+architecture,
+safety,
+and validation instructions below.
+
+Nested `AGENTS.md` files may override or extend these instructions for specific subtrees.