arey-pi 0.4.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`.
@@ -191,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/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.

package/extensions/arey-pi/core.ts

@@ -58,23 +58,91 @@ export function parseBootstrapFlags(args: string): BootstrapPlan {
 
 export type WorkflowKind = "feature" | "bugfix" | "sync" | "review" | "assess" | string;
 
+const evidenceSummary = `Final evidence format:\n- Behaviour/spec impact:\n- Tests/TDD, including test location:\n- Validation commands and results:\n- Quality tooling:\n- Spec sync:\n- Documentation sync:\n- Architecture/ADR/glossary impact:\n- Database/DBML impact:\n- Residual risks:`;
+
+function commonWorkflowMessage(): string {
+  return [
+    "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.",
+    "Clarify blocking ambiguity before editing; otherwise proceed incrementally.",
+    "Follow Arey Pi rules, preserve TDD for behaviour changes, and report evidence clearly.",
+  ].join(" ");
+}
+
+function featureWorkflow(target: string): string {
+  return [
+    commonWorkflowMessage(),
+    "",
+    `Run the Arey Pi feature workflow for: ${target}`,
+    "",
+    "Execution contract:",
+    "1. Scope: identify behaviour, impacted users, non-goals, risk level, and unknowns.",
+    "2. Specs: confirm or update canonical Gherkin before production behaviour changes; use arey-pi.spec-author when available.",
+    "3. TDD: use arey-pi.tdd-implementer for Red → Green → Refactor; tests must live outside production source directories by default.",
+    "4. Implementation: make the smallest high-quality change; avoid speculative architecture.",
+    "5. Sync: use arey-pi.spec-syncer to align specs, tests, code, DBML, ADRs, glossary, README, docs, AGENTS.md, skills, prompts, rules, agents, commands, and tooling instructions when affected.",
+    "6. Review: use fresh-context arey-pi.engineering-reviewer or reviewers when risk warrants it.",
+    "",
+    "Use scout/context-builder/planner first if codebase context is not clear.",
+    evidenceSummary,
+  ].join("\n");
+}
+
+function bugfixWorkflow(target: string): string {
+  return [
+    commonWorkflowMessage(),
+    "",
+    `Run the Arey Pi bugfix workflow for: ${target}`,
+    "",
+    "Execution contract:",
+    "1. Reproduce: identify expected vs actual behaviour and affected scope.",
+    "2. Regression test first: add or update a meaningful failing test that proves the bug before changing production code.",
+    "3. Fix: implement the smallest high-quality correction without broad rewrites unless necessary.",
+    "4. Refactor: improve design only while regression tests and existing tests remain green.",
+    "5. Sync: update Gherkin, docs, DBML, ADRs, glossary, or architecture docs when the intended behaviour or design contract changed.",
+    "6. Review: request fresh engineering review for security, data-loss, concurrency, auth, payment, migration, or public API bugs.",
+    "",
+    "If a failing regression test cannot be demonstrated, state the blocker explicitly and do not claim TDD evidence.",
+    evidenceSummary,
+  ].join("\n");
+}
+
+function syncWorkflow(target: string): string {
+  return [
+    commonWorkflowMessage(),
+    "",
+    `Run Arey Pi spec and documentation sync for: ${target}`,
+    "",
+    "Sync contract:",
+    "1. Inspect the requested scope and current diff before editing.",
+    "2. Verify alignment across canonical Gherkin, tests, production code, DBML, ADRs, glossary, architecture docs, README files, docs, AGENTS.md, skills, prompts, rules, agents, commands, templates, and tooling instructions.",
+    "3. Classify drift as blocking, recommended, or unaffected.",
+    "4. Fix safe drift directly when the intended behaviour is clear; otherwise ask for a decision.",
+    "5. Do not rewrite specs to hide implementation defects.",
+    "6. Run relevant validation after changes.",
+    "",
+    "End with both statuses exactly: `Specs updated` or `Specs unaffected`; `Docs updated` or `Docs unaffected`, with evidence.",
+    evidenceSummary,
+  ].join("\n");
+}
+
 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, 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: 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.`;
+      return featureWorkflow(target);
     case "bugfix":
-      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.`;
+      return bugfixWorkflow(target);
     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.`;
+      return syncWorkflow(target);
     case "review":
-      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.`;
+      return `${commonWorkflowMessage()}\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.`;
+      return `${commonWorkflowMessage()}\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:
-      return `${common}\n\nWork on: ${target}`;
+      return `${commonWorkflowMessage()}\n\nWork on: ${target}`;
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arey-pi",
-  "version": "0.4.0",
+  "version": "0.5.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",

package/prompts/adr-review.md

@@ -0,0 +1,33 @@
+---
+description: Decide whether a change needs an ADR and review ADR quality
+argument-hint: "[decision or change]"
+---
+
+Assess ADR impact for:
+
+$ARGUMENTS
+
+Inspect relevant specs, architecture docs, existing ADRs, README/docs, tests, and implementation context.
+
+Determine whether the change records a significant technical decision because it affects architecture, data model, security model, operability, public contracts, deployment, dependency strategy, or long-term maintainability.
+
+If an ADR is needed:
+
+- propose the ADR title and location under `specs/decisions/`;
+- capture context, decision, alternatives considered, consequences, risks, and follow-up work;
+- keep the decision durable and independent of transient implementation details;
+- update glossary, DBML, architecture docs, or README when affected.
+
+If no ADR is needed, explain why.
+
+Return:
+
+```txt
+ADR assessment:
+- Decision/change reviewed:
+- ADR required: yes/no
+- Evidence:
+- Proposed ADR changes:
+- Architecture/docs/glossary/DBML impact:
+- Open questions:
+```

package/prompts/engineering-review.md

@@ -0,0 +1,37 @@
+---
+description: Run an adversarial Arey Pi engineering review
+argument-hint: "[scope]"
+---
+
+Run an adversarial Arey Pi engineering review for:
+
+$ARGUMENTS
+
+Prefer fresh-context review and use `arey-pi.engineering-reviewer` when available.
+
+Review:
+
+- correctness and behavioural completeness;
+- architecture and code quality;
+- test quality, meaningful assertions, and test location;
+- TDD evidence where behaviour changed;
+- formatter/lint/static analysis/typecheck/test/coverage evidence;
+- security, privacy, reliability, operability, and maintainability;
+- generated-code risks;
+- spec, ADR, DBML, glossary, README, docs, AGENTS.md, skills, prompts, rules, agents, commands, and tooling sync.
+
+Do not modify files unless explicitly asked to fix findings.
+
+Return:
+
+```txt
+Engineering review:
+- Scope:
+- Blocking findings:
+- Major findings:
+- Minor findings:
+- Positive evidence:
+- Missing validation:
+- Sync concerns:
+- Recommended next actions:
+```

package/prompts/feature-spec.md

@@ -0,0 +1,35 @@
+---
+description: Draft or update canonical Arey Pi Gherkin specs for a feature
+argument-hint: "<feature request>"
+---
+
+Draft or update canonical Arey Pi feature specs for:
+
+$ARGUMENTS
+
+Work in spec-first mode.
+
+Requirements:
+
+- inspect existing `specs/features/`, glossary, ADRs, docs, tests, and related code before writing;
+- identify actors, business terms, rules, assumptions, non-goals, edge cases, and open questions;
+- write behaviour-focused Gherkin, not UI or implementation scripts;
+- prefer `Rule` sections and concrete examples where they clarify intent;
+- update glossary, ADR, DBML, architecture docs, or README only when affected;
+- do not change production code;
+- if requirements are ambiguous, ask focused questions instead of inventing policy.
+
+Prefer using `arey-pi.spec-author` when available.
+
+Return:
+
+```txt
+Spec handoff:
+- Feature scope:
+- Files read:
+- Specs added/updated:
+- Scenarios/rules covered:
+- Open questions:
+- Test implications:
+- ADR/DBML/glossary/docs impact:
+```

package/prompts/red-green-refactor.md

@@ -0,0 +1,34 @@
+---
+description: Implement accepted behaviour with strict Arey Pi Red-Green-Refactor
+argument-hint: "<accepted behaviour or spec>"
+---
+
+Implement the accepted behaviour through strict Arey Pi TDD:
+
+$ARGUMENTS
+
+Rules:
+
+- read applicable specs, tests, code, AGENTS.md, and quality tooling first;
+- add or update a meaningful failing test before production behaviour changes;
+- keep tests outside production source directories by default;
+- implement the smallest high-quality production change to pass;
+- refactor only while tests remain green;
+- run formatter, lint/static analysis, typecheck, tests, and coverage/mutation checks where relevant and available;
+- do not claim TDD if the Red phase cannot be demonstrated.
+
+Prefer using `arey-pi.tdd-implementer` when available.
+
+Return:
+
+```txt
+Red-Green-Refactor report:
+- Behaviour implemented:
+- Tests added/updated and location:
+- Red evidence:
+- Green evidence:
+- Refactor notes:
+- Validation commands and results:
+- Spec/docs/ADR/DBML/glossary impact:
+- Residual risks:
+```

package/prompts/sync-drift.md

@@ -0,0 +1,44 @@
+---
+description: Find and fix Arey Pi spec, docs, tests, and implementation drift
+argument-hint: "[scope]"
+---
+
+Run Arey Pi sync review for:
+
+$ARGUMENTS
+
+If no scope is provided, inspect the current repository or current diff.
+
+Verify alignment across:
+
+- canonical Gherkin specs;
+- tests and production code;
+- DBML/database schema specs;
+- ADRs and architecture docs;
+- glossary/business terminology;
+- README files and `docs/`;
+- AGENTS.md, skills, prompts, rules, agents, commands, templates, and tooling instructions.
+
+Prefer using `arey-pi.spec-syncer` when available.
+
+Classify drift as:
+
+- blocking: must fix before completion;
+- recommended: should fix soon but does not invalidate current work;
+- unaffected: explicitly checked or not applicable.
+
+Fix safe drift when intent is clear. Ask before changing canonical intent.
+
+End with:
+
+```txt
+Sync report:
+- Scope:
+- Blocking drift:
+- Recommended drift:
+- Files changed:
+- Validation:
+- Specs updated/unaffected:
+- Docs updated/unaffected:
+- Residual risks:
+```

package/skills/engineering-review/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: engineering-review
+description: Perform an adversarial Arey Pi engineering review of a diff, feature, bugfix, plan, or repository area. Use to assess correctness, tests, quality tooling, security, maintainability, and spec/docs sync before completion.
+---
+
+# Engineering Review
+
+Use this skill for independent, adversarial review.
+
+Default mode is read-only. Do not edit files unless the user explicitly asks for fixes after findings are reported.
+
+Prefer fresh context when running as a subagent so the review does not inherit the implementer's assumptions.
+
+## Required Reading
+
+Read these files when available:
+
+- `rules/engineering/engineering-quality.md`
+- `rules/engineering/test-quality.md`
+- `rules/engineering/quality-tooling.md`
+- `rules/engineering/tdd.md`
+- `rules/core/definition-of-done.md`
+- `rules/specs/spec-sync.md`
+- `rules/workflow/documentation-sync.md`
+- `rules/architecture/adrs.md`
+- current diff, relevant specs, tests, code, and validation output
+
+## Review Checklist
+
+Assess:
+
+- behaviour correctness and edge cases;
+- simplicity and maintainability;
+- architecture boundaries and coupling;
+- security, privacy, data-loss, concurrency, auth, payments, migrations, and public API risks;
+- test quality, assertion strength, and test location;
+- whether TDD evidence exists for behaviour changes;
+- formatter, lint/static analysis, typecheck, tests, coverage, mutation, and dynamic validation evidence;
+- generated-code quality and hallucination risk;
+- spec, DBML, ADR, glossary, README, docs, AGENTS.md, skills, prompts, rules, agents, commands, templates, and tooling sync.
+
+## Severity
+
+- **Blocker**: must fix before completion.
+- **Major**: should fix before merge unless explicitly accepted.
+- **Minor**: improvement or maintainability concern.
+- **Question**: needs product/architecture/user decision.
+
+## Output
+
+Return:
+
+```txt
+Engineering review:
+- Scope:
+- Files inspected:
+- Blockers:
+- Major findings:
+- Minor findings:
+- Questions:
+- Positive evidence:
+- Missing validation:
+- Sync concerns:
+- Recommended next actions:
+```

package/skills/spec-sync/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: spec-sync
+description: Find and repair drift between Arey Pi specs, tests, code, DBML, ADRs, glossary, docs, prompts, skills, agents, and tooling instructions. Use before finalising non-trivial work or when drift is suspected.
+---
+
+# Spec Sync
+
+Use this skill to verify and restore alignment across Arey Pi project artefacts.
+
+The goal is not to make documentation match broken implementation. The goal is to preserve canonical intent and keep executable truth, production code, and docs aligned.
+
+## Required Reading
+
+Read these files when available:
+
+- `rules/specs/spec-sync.md`
+- `rules/workflow/documentation-sync.md`
+- `rules/specs/canonical-specs.md`
+- `rules/specs/database-specs.md`
+- `rules/architecture/adrs.md`
+- `rules/architecture/architecture-memory.md`
+- `rules/core/definition-of-done.md`
+- current diff and changed files
+
+## Inspect
+
+Check affected areas for drift across:
+
+- Gherkin specs under `specs/features/`;
+- tests and production code;
+- DBML/database schema specs;
+- ADRs and architecture docs;
+- glossary terms;
+- README files and `docs/`;
+- `AGENTS.md` and harness instructions;
+- skills, prompts, rules, agents, commands, templates, examples, and package metadata;
+- validation scripts and quality tooling instructions.
+
+## Classify Findings
+
+- **Blocking**: intent, tests, code, or docs conflict in a way that invalidates completion.
+- **Recommended**: useful improvement but not completion-blocking.
+- **Unaffected**: inspected or clearly not applicable.
+
+## Repair Rules
+
+- Fix safe mechanical drift when the intended behaviour is clear.
+- Ask for a decision before changing canonical intent.
+- Do not update specs merely to excuse defective implementation.
+- Preserve terminology consistency with the glossary.
+- Keep updates focused and incremental.
+
+## Output
+
+Return:
+
+```txt
+Spec sync report:
+- Scope:
+- Files inspected:
+- Blocking drift:
+- Recommended drift:
+- Files changed:
+- Validation commands and results:
+- Specs updated/unaffected:
+- Docs updated/unaffected:
+- ADR/DBML/glossary impact:
+- Residual risks:
+```

package/skills/tdd-red-green-refactor/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: tdd-red-green-refactor
+description: Implement behaviour changes with Arey Pi strict Red-Green-Refactor. Use when adding features, fixing bugs, or changing production behaviour where tests must drive implementation.
+---
+
+# TDD Red-Green-Refactor
+
+Use this skill for production behaviour changes under Arey Pi.
+
+TDD is mandatory unless the user explicitly chooses a non-behaviour mode or a project constraint blocks it. If blocked, report the blocker; do not claim TDD evidence.
+
+## Required Reading
+
+Read these files when available:
+
+- `AGENTS.md`
+- `rules/engineering/tdd.md`
+- `rules/engineering/test-quality.md`
+- `rules/engineering/engineering-quality.md`
+- `rules/engineering/quality-tooling.md`
+- `rules/core/definition-of-done.md`
+- `rules/specs/spec-sync.md`
+- affected Gherkin specs under `specs/features/`
+- existing tests and test runner configuration
+
+## Workflow
+
+1. **Understand accepted behaviour**
+   - Identify the canonical spec, bug report, or explicit user acceptance criteria.
+   - Ask focused questions if behaviour is ambiguous.
+
+2. **Red**
+   - Add or update meaningful tests before production code changes.
+   - Prefer `tests/`, `test/`, `spec/`, or equivalent dedicated test directories.
+   - Do not place tests inside production source directories by default.
+   - Run the narrowest relevant test command and capture failure evidence.
+
+3. **Green**
+   - Implement the smallest high-quality production change.
+   - Avoid speculative abstractions and broad rewrites.
+   - Run the failing test again and capture passing evidence.
+
+4. **Refactor**
+   - Improve clarity/design only while tests remain green.
+   - Keep behaviour unchanged during refactor.
+
+5. **Validate**
+   - Run available formatter, lint/static analysis, typecheck, tests, coverage, mutation testing, or dynamic checks appropriate to risk.
+   - Surface missing quality tooling as a gap.
+
+6. **Sync**
+   - Update specs, docs, DBML, ADRs, glossary, or architecture docs when the intended behaviour or contract changed.
+
+## Output
+
+Return:
+
+```txt
+TDD report:
+- Behaviour:
+- Tests added/updated and location:
+- Red evidence:
+- Green evidence:
+- Refactor evidence:
+- Validation commands and results:
+- Spec/docs/ADR/DBML/glossary impact:
+- Quality notes:
+- Residual risks:
+```