arey-pi 0.2.0 → 0.4.0

package/rules/engineering/tdd.md

@@ -16,13 +16,16 @@ Red → Green → Refactor
 
 This applies to features, bug fixes, behaviour changes, risky refactors, API/CLI behaviour, validation, permissions, persistence, and error handling.
 
+Tests must live outside production source directories by default.
+Do not colocate test files beside production files in `src/` or equivalent source trees unless an existing project convention explicitly requires it or the user approves an exception.
+
 ## Red
 
 Before implementation, create, update, or identify a test that fails for the intended reason.
 
 Valid Red evidence includes:
 
-- a newly added failing test;
+- a newly added failing test in the dedicated test directory;
 - an updated failing test;
 - an existing failing test that already captures the intended behaviour;
 - a documented inability to run the test, including the exact intended command and reason.
@@ -46,6 +49,32 @@ After Green, refactor only while tests remain green.
 
 Refactoring should improve clarity, structure, duplication, or maintainability without expanding scope or changing behaviour.
 
+## Test Location
+
+Use a dedicated test/spec directory for automated tests.
+
+Preferred locations include project conventions such as:
+
+```txt
+tests/
+test/
+__tests__/
+spec/
+```
+
+When adding tests for code under `src/`, mirror the production module structure under the chosen test directory instead of creating sibling test files inside `src/`.
+
+Example:
+
+```txt
+src/domain/accounts/password-reset.ts
+tests/domain/accounts/password-reset.test.ts
+```
+
+If a repository already has a clear separate test root, follow it.
+If it only has colocated tests, ask before continuing the pattern or migrating it.
+If a framework mandates colocated tests, document the constraint in the final evidence.
+
 ## Bug Fixes
 
 Every bug fix requires a regression test.
@@ -82,5 +111,6 @@ Completion must report:
 - Green evidence;
 - refactor status;
 - commands run;
+- test location and any exception to separate test directories;
 - tests not run and why;
 - residual risks.

package/rules/engineering/test-quality.md

@@ -23,6 +23,36 @@ Agents should assess test quality across these dimensions:
 5. **Minimal coupling:** the test avoids depending on private implementation details unless intentionally characterizing legacy code before refactor.
 6. **Maintainability:** the test is readable, focused, deterministic, and not overly broad.
 7. **Regression value:** for bug fixes, the test would have failed before the fix.
+8. **Source separation:** tests live in a dedicated test/spec directory rather than being colocated with production files, unless an explicit project or framework constraint justifies an exception.
+
+## Test Organisation
+
+Tests should be organised outside production source directories.
+
+Prefer a project-level test root such as:
+
+```txt
+tests/
+test/
+__tests__/
+spec/
+```
+
+Mirror production structure inside that test root when useful.
+
+Avoid creating files such as:
+
+```txt
+src/foo.test.ts
+src/foo.spec.ts
+src/foo.test.py
+```
+
+unless the repository has an established, user-approved, or framework-mandated colocated test convention.
+
+This keeps production source trees clean,
+makes generated tests easier to audit,
+and avoids mixing executable product code with validation artefacts.
 
 ## Coverage
 
@@ -101,7 +131,8 @@ Agents must reject or improve tests that:
 - over-mock collaborators so the real contract is not exercised;
 - assert private structure instead of observable behaviour;
 - pass even if important logic is removed;
-- lack a clear connection to a spec, bug, or requirement.
+- lack a clear connection to a spec, bug, or requirement;
+- are colocated with production source files without an explicit project convention or approved exception.
 
 ## Negative and Edge Cases
 
@@ -130,7 +161,7 @@ If the answer is no, the test is probably weak.
 
 For non-trivial production changes, agents should report:
 
-- tests added or modified;
+- tests added or modified, including their dedicated test directory location;
 - related Gherkin scenarios or requirements;
 - Red evidence;
 - Green evidence;

package/templates/AGENTS.md

@@ -0,0 +1,151 @@
+# Agent Instructions
+
+This project uses Arey Pi.
+
+## Delivery Rules
+
+- Treat canonical specs as the source of truth.
+- Use Gherkin for behaviour specs.
+- Use DBML for database specs when the project has persistence.
+- Follow TDD for production behaviour changes.
+- Put tests in a dedicated test/spec directory outside production source trees unless a documented project or framework convention requires otherwise.
+- Keep specs, tests, code, DBML, ADRs, glossary, architecture docs, README files, docs, AGENTS.md, commands, and tooling instructions synchronised.
+- Capture significant technical decisions in high-quality ADRs.
+- 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
+.pi/agents/arey-pi/
+```
+
+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.

package/templates/adr.md

@@ -0,0 +1,129 @@
+# ADR-NNNN: Decision Title
+
+## Status
+
+Proposed
+
+Accepted values:
+Proposed,
+Accepted,
+Superseded,
+Deprecated.
+
+## Date
+
+YYYY-MM-DD
+
+## Context
+
+Describe the forces,
+constraints,
+requirements,
+and tradeoffs that make this decision necessary.
+
+Include:
+
+- the problem being solved;
+- relevant canonical specs or ADRs;
+- operational constraints;
+- security,
+  privacy,
+  performance,
+  reliability,
+  or maintainability concerns;
+- what happens if no decision is made.
+
+## Decision Drivers
+
+- Driver 1
+- Driver 2
+- Driver 3
+
+## Options Considered
+
+### Option 1: Name
+
+Summary.
+
+Pros:
+
+- ...
+
+Cons:
+
+- ...
+
+### Option 2: Name
+
+Summary.
+
+Pros:
+
+- ...
+
+Cons:
+
+- ...
+
+## Decision
+
+State the chosen option clearly.
+
+Explain why it best satisfies the decision drivers.
+
+## Consequences
+
+Expected positive consequences:
+
+- ...
+
+Expected negative consequences or costs:
+
+- ...
+
+Operational impact:
+
+- ...
+
+Follow-up work:
+
+- ...
+
+## Validation
+
+Describe how the decision will be validated.
+
+Examples:
+
+- tests;
+- operational metrics;
+- migration checks;
+- architecture review;
+- project readiness assessment.
+
+## Supersession and Relationships
+
+Supersedes:
+
+- None
+
+Superseded by:
+
+- None
+
+Related ADRs:
+
+- None
+
+Overlapping decisions:
+
+- None
+
+## Revisit Conditions
+
+Revisit this decision if:
+
+- a listed constraint changes;
+- implementation cost differs materially from expectations;
+- operational evidence contradicts assumptions;
+- a simpler option becomes viable.

package/templates/architecture-readme.md

@@ -0,0 +1,9 @@
+# Architecture
+
+Use this directory for durable architecture memory.
+
+Document boundaries,
+integrations,
+ownership,
+constraints,
+and current system structure that future humans and agents need to preserve.

package/templates/database-readme.md

@@ -0,0 +1,10 @@
+# Database Specs
+
+Database projects must keep canonical DBML specs here or document the canonical DBML location.
+
+DBML must stay synchronised with migrations,
+ORM models,
+SQL DDL,
+constraints,
+indexes,
+and relationships.

package/templates/database.dbml

@@ -0,0 +1,57 @@
+// Canonical database specification.
+// Keep this DBML synchronised with migrations,
+// ORM models,
+// SQL DDL,
+// constraints,
+// indexes,
+// relationships,
+// and persistence tests.
+
+Project project_name {
+  database_type: 'PostgreSQL'
+  Note: '''
+    Replace this starter DBML with the canonical project schema.
+    Document the database engine,
+    important extensions,
+    ownership boundaries,
+    and migration constraints here.
+  '''
+}
+
+Enum example_status {
+  active
+  archived
+}
+
+Table example_entities {
+  id uuid [pk, note: 'Primary identifier']
+  name varchar [not null, unique, note: 'Human-readable unique name']
+  status example_status [not null, default: 'active']
+  created_at timestamptz [not null]
+  updated_at timestamptz [not null]
+
+  indexes {
+    name [unique, name: 'idx_example_entities_name_unique']
+    status [name: 'idx_example_entities_status']
+  }
+
+  Note: '''
+    Replace this example table with canonical project tables.
+    Include constraints,
+    indexes,
+    relationship intent,
+    and relevant domain notes.
+  '''
+}
+
+Table example_events {
+  id uuid [pk]
+  entity_id uuid [not null, ref: > example_entities.id]
+  event_type varchar [not null]
+  occurred_at timestamptz [not null]
+  payload jsonb [not null, default: '{}']
+
+  indexes {
+    (entity_id, occurred_at) [name: 'idx_example_events_entity_time']
+  }
+}

package/templates/decisions-readme.md

@@ -0,0 +1,11 @@
+# Decisions
+
+Use this directory for high-quality ADRs.
+
+ADRs should capture meaningful technical decisions,
+context,
+options,
+tradeoffs,
+consequences,
+revisit conditions,
+and supersession relationships.

package/templates/docs-readme.md

@@ -0,0 +1,9 @@
+# Documentation
+
+Use this directory for project-facing documentation that is not itself a canonical spec.
+
+Keep usage,
+setup,
+commands,
+operations,
+and workflow instructions synchronised with the implementation and Arey Pi rules.

package/templates/feature.feature

@@ -0,0 +1,38 @@
+@arey-pi @replace-me
+Feature: Replace with capability name
+  This feature is a canonical behaviour spec.
+  It should describe externally observable behaviour,
+  not implementation details.
+
+  As a named actor or stakeholder
+  I want a concrete capability
+  So that a valuable outcome is achieved
+
+  Rule: Replace with the business rule being protected
+
+    Background:
+      Given relevant starting context
+      And any shared preconditions that every scenario needs
+
+    @happy-path
+    Scenario: Primary successful behaviour
+      Given a meaningful initial state
+      When the actor performs the behaviour
+      Then the expected outcome is observable
+      And important side effects are visible
+
+    @validation @edge-case
+    Scenario Outline: Important validation or boundary behaviour
+      Given <precondition>
+      When the actor performs the behaviour with <input>
+      Then <outcome> is reported
+
+      Examples:
+        | precondition | input | outcome |
+        | valid setup   | value | result  |
+
+    @regression
+    Scenario: Regression behaviour
+      Given the historical failure condition
+      When the triggering action occurs
+      Then the regression is prevented

package/templates/features-readme.md

@@ -0,0 +1,7 @@
+# Behaviour Specs
+
+Write behaviour specs in Gherkin.
+
+Use semantic line breaks in feature files and accompanying notes.
+Each feature should describe externally observable behaviour,
+not implementation details.

package/templates/glossary.md

@@ -0,0 +1,19 @@
+# Glossary
+
+Use this glossary for durable domain language.
+
+## Terms
+
+<!--
+Add terms as they become important.
+
+Example:
+
+### Account
+
+Definition.
+
+Related specs:
+
+- specs/features/example.feature
+-->

package/templates/project-readiness-report.md

@@ -0,0 +1,120 @@
+# Arey Pi Project Readiness Report
+
+## Overall
+
+- Overall Readiness: N/5
+- Lowest Rule Scores:
+- Highest Rule Scores:
+
+## Executive Summary
+
+Summarise the current readiness posture.
+
+## Blockers
+
+List issues that prevent reliable Arey Pi delivery.
+
+## Quick Wins
+
+List low-effort improvements with high leverage.
+
+## Rule Scores
+
+### Canonical Specs
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Gherkin Authoring
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Tests/TDD
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Test Quality
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Quality Tooling
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Engineering Quality
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Spec Sync
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Documentation Sync
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Database Specs
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Rebuildability
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Architecture Memory and ADRs
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### Incremental Commits
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+### AI Harness
+
+- Score:
+- Evidence:
+- Findings:
+- Recommendations:
+
+## Recommended Plan
+
+1. ...
+
+## Residual Risks / Unknowns
+
+List what could not be verified.

package/templates/specs-readme.md

@@ -0,0 +1,6 @@
+# Specs
+
+This directory contains canonical Arey Pi project specifications.
+
+Specs are durable project knowledge.
+Keep them synchronised with tests, code, DBML, ADRs, glossary, architecture docs, and project documentation.