arey-pi 0.1.0

package/rules/workflow/agent-workflows.md

@@ -0,0 +1,70 @@
+# Agent Workflows
+
+## Purpose
+
+This policy defines how agents should collaborate without corrupting the worktree, bypassing specs, or hiding decisions.
+
+## Core Roles
+
+Arey Pi may define agents such as:
+
+- spec author;
+- test designer;
+- TDD implementer;
+- spec syncer;
+- acceptance reviewer;
+- rebuild planner;
+- tech lead/orchestrator.
+
+Roles should be focused. A role should not silently take over responsibilities that belong to another role when doing so weakens review or traceability.
+
+## Worktree Safety
+
+Only one agent should write to a worktree at a time unless writers are isolated in separate worktrees.
+
+Review, research, planning, and validation can run in parallel. Normal implementation should remain single-writer.
+
+## Role Boundaries
+
+- Spec authors write or refine canonical specs; they do not implement production code unless explicitly assigned.
+- Test designers derive tests from specs and risk; they do not weaken specs to fit code.
+- TDD implementers write tests and implementation through Red → Green → Refactor.
+- Spec syncers compare the final diff against canonical sources and update specs/docs when needed.
+- Reviewers validate alignment between specs, tests, code, and policies.
+- Tech leads choose change mode, scope, sequencing, and conflict escalation.
+
+## Review Behaviour
+
+Reviewers should be adversarial but practical.
+
+They should focus on:
+
+- spec drift;
+- missing or weak tests;
+- TDD violations;
+- behaviour/spec mismatches;
+- rebuildability gaps;
+- architecture memory gaps;
+- unnecessary scope expansion.
+
+## Completion Handoffs
+
+Implementation agents must report:
+
+- changed files;
+- tests added/updated;
+- Red/Green evidence;
+- validation commands;
+- spec sync status;
+- decisions made;
+- residual risks.
+
+## Escalation
+
+Agents must stop or ask for clarification when:
+
+- user intent conflicts with canonical specs;
+- product behaviour is ambiguous;
+- tests and specs disagree;
+- architecture decisions are required but not approved;
+- a direct change grows into SDD-level scope.

package/rules/workflow/ai-harness.md

@@ -0,0 +1,177 @@
+# AI Harness
+
+## Purpose
+
+The AI harness is the project infrastructure that lets agents work reliably, safely, and consistently under Arey Pi.
+
+It is a first-class Arey Pi rule, not an optional convenience and not an external concern. If agents are expected to contribute to a project, the project must expose enough context, commands, skills, prompts, and safety rails for them to do high-quality work.
+
+## Core Rule
+
+A project using Arey Pi must maintain an explicit AI harness appropriate to its complexity, stack, and risk.
+
+The AI harness should make it easy for agents to discover:
+
+- what the project is;
+- how it is structured;
+- which Arey Pi rules apply;
+- where canonical specs live;
+- how to run validation;
+- which tooling is required;
+- which technologies require special guidance;
+- what agents must not do.
+
+## Required Harness Components
+
+### AGENTS.md
+
+Projects should provide an `AGENTS.md` file with:
+
+- project overview;
+- Arey Pi instructions;
+- links to relevant rules/specs;
+- common setup and validation commands;
+- Definition of Done expectations;
+- quality tooling commands;
+- commit conventions;
+- safety constraints;
+- project structure notes;
+- known pitfalls and non-obvious conventions.
+
+`AGENTS.md` is the bootstrap context for agents. It should be concise enough to read at startup and specific enough to prevent repeated rediscovery.
+
+### Nested AGENTS.md
+
+Large or multi-domain repositories may use nested `AGENTS.md` files to provide local instructions for a subtree.
+
+Use nested files when different areas have meaningfully different:
+
+- technology stacks;
+- validation commands;
+- architecture boundaries;
+- domain language;
+- safety constraints;
+- generated file rules;
+- ownership or review expectations.
+
+Nested `AGENTS.md` files should refine or specialize the root instructions, not contradict them. If local instructions conflict with root Arey Pi rules, the conflict must be explicit and resolved by the user or project maintainers.
+
+Because Pi loads context files from parent directories and the current working directory at startup, nested `AGENTS.md` works best when agents are launched from the relevant subtree or when the root `AGENTS.md` tells agents which nested files to read for specific areas.
+
+### Pi Configuration
+
+Projects should document or configure how Arey Pi is loaded, for example through:
+
+- `.pi/settings.json`;
+- package installation instructions;
+- local package references;
+- project README instructions;
+- explicit prompts or skills.
+
+Agents should be able to tell whether Arey Pi is installed, vendored, or expected as external context.
+
+### Skills
+
+Projects should provide or reference skills when agents need specialized guidance for:
+
+- project-specific workflows;
+- important frameworks or libraries;
+- domain concepts;
+- testing strategy;
+- quality tooling;
+- deployment or operations;
+- security-sensitive areas.
+
+Technology-specific skills are especially valuable when correct work depends on ecosystem details that agents may otherwise hallucinate or rediscover.
+
+### Prompts
+
+Projects should provide reusable prompts for common workflows when useful, such as:
+
+- feature delivery;
+- bug fix;
+- spec sync;
+- project assessment;
+- architecture review;
+- release validation;
+- migration work.
+
+Prompts should apply Arey Pi rules instead of duplicating stale instructions.
+
+### Subagents
+
+When `pi-subagents` is used, projects may define role agents for recurring responsibilities such as:
+
+- planning;
+- implementation;
+- review;
+- spec sync;
+- test quality review;
+- project evaluation;
+- domain-specific analysis.
+
+Subagents must respect Arey Pi role boundaries and worktree safety rules.
+
+### Command Discoverability
+
+Validation and setup commands should be discoverable from one or more of:
+
+- `AGENTS.md`;
+- README;
+- package/build scripts;
+- Makefile;
+- Justfile;
+- CI configuration;
+- project docs.
+
+Agents should not need to guess how to format, lint, typecheck, test, run coverage, or perform mutation testing.
+
+### Safety Rails
+
+The AI harness should document restrictions for:
+
+- secrets;
+- environment variables;
+- destructive commands;
+- database operations;
+- migrations;
+- generated files;
+- external services;
+- deployment;
+- ownership or human review requirements.
+
+## Missing Harness
+
+If a project lacks an adequate AI harness, agents must surface the gap.
+
+They should propose improvements and ask for approval before adding or changing harness infrastructure.
+
+For non-trivial projects, missing `AGENTS.md`, undiscoverable validation commands, or absent safety rules are Arey Pi readiness issues.
+
+## Harness Quality
+
+A good AI harness is:
+
+- concise;
+- current;
+- specific to the project;
+- connected to canonical rules and specs;
+- easy to update;
+- safe by default;
+- useful for both humans and agents.
+
+A weak AI harness is:
+
+- generic;
+- stale;
+- disconnected from real commands;
+- missing safety constraints;
+- missing technology-specific guidance;
+- too verbose to be reliably followed;
+- dependent on chat history.
+
+## Acceptance Rule
+
+A project is not fully aligned with Arey Pi unless its AI harness is adequate for the level of agent work expected in that project.
+
+AI harness gaps should be evaluated and prioritised like any other Arey Pi rule gap.

package/rules/workflow/incremental-commits.md

@@ -0,0 +1,88 @@
+# Incremental Commits
+
+## Purpose
+
+Work should be committed incrementally so the project history reflects coherent steps, not one large opaque dump.
+
+All commits must use Conventional Commits.
+
+## Core Rule
+
+When a task spans multiple meaningful steps, commit after each coherent unit of work.
+
+A coherent unit may be:
+
+- specs added or updated;
+- tests added or updated;
+- implementation of a focused behaviour;
+- refactor after green tests;
+- spec sync updates;
+- architecture/ADR updates;
+- Arey Pi policy or agent definition changes.
+
+## Conventional Commits
+
+Use Conventional Commits format:
+
+```txt
+<type>(optional-scope): <description>
+```
+
+Common types:
+
+- `feat`: new behaviour or capability;
+- `fix`: bug fix;
+- `test`: tests only;
+- `docs`: specs, rules, architecture docs, ADRs, glossary;
+- `refactor`: behaviour-preserving code change;
+- `chore`: package/config/maintenance;
+- `ci`: CI or automation;
+- `build`: build system or dependencies.
+
+Examples:
+
+```txt
+docs(rules): define canonical spec policy
+test(auth): add login regression scenario
+feat(auth): implement successful login flow
+docs(specs): sync login Gherkin scenarios
+refactor(auth): simplify session creation
+```
+
+## Commit Hygiene
+
+Each commit should be:
+
+- focused;
+- reviewable;
+- buildable where practical;
+- aligned with the TDD/spec workflow;
+- free from unrelated cleanup.
+
+## Agent Behaviour
+
+Agents should commit incrementally when asked to perform repository work and the current environment allows commits.
+
+Before committing, agents should inspect the diff and avoid committing unrelated user changes.
+
+If there are pre-existing uncommitted changes not made by the agent, stop and ask before mixing them into a commit.
+
+## Suggested Commit Flow
+
+For SDD/TDD work:
+
+```txt
+docs(specs): add or update Gherkin behaviour
+test(scope): add failing behaviour/regression tests
+feat/fix(scope): implement behaviour
+refactor(scope): improve implementation after green tests
+docs(specs): synchronize canonical specs and decisions
+```
+
+For direct small work:
+
+```txt
+test(scope): cover direct change
+fix/feat/refactor(scope): apply direct change
+docs(specs): record spec sync if files changed
+```

package/skills/project-readiness/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: project-readiness
+description: Evaluate whether a repository is aligned with Arey Pi rules. Use when assessing specs, tests, quality tooling, AGENTS.md, skills, prompts, subagents, or project readiness.
+---
+
+# Project Readiness
+
+Use this skill to assess whether a project is ready to operate under Arey Pi.
+
+Project readiness evaluates alignment with Arey Pi rules.
+
+Project readiness covers all applicable Arey Pi rules, including specs, TDD, database specs, quality tooling, architecture/code quality, spec sync, AI harness, DoD, and commits.
+
+## Required Reading
+
+Read these policy files when available in the Arey Pi package or project:
+
+- `rules/assessment/project-readiness.md`
+- `rules/workflow/ai-harness.md`
+- `rules/specs/database-specs.md`
+- `rules/core/principles.md`
+- `rules/core/definition-of-done.md`
+- `rules/engineering/test-quality.md`
+- `rules/engineering/quality-tooling.md`
+- `rules/engineering/engineering-quality.md`
+
+If the files are missing from the target project, report that as part of the assessment rather than assuming compliance.
+
+## Default Mode: Audit
+
+Audit mode is read-only.
+
+Inspect the repository and produce a readiness report. Do not modify files, install dependencies, or change configuration unless the user explicitly asks for Bootstrap Mode.
+
+## What to Inspect
+
+Look for:
+
+- root and nested `AGENTS.md`, `CLAUDE.md`, `.pi/settings.json`, `.pi/`, `.agents/`
+- `specs/features/`, `specs/database/`, `specs/architecture/`, `specs/decisions/`, glossary
+- test directories and test runner config
+- quality tooling config: formatter, linter, typecheck, coverage, mutation testing
+- project scripts: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, Makefile, Justfile, CI
+- README/developer docs
+- git history conventions when useful
+
+## Output
+
+Produce:
+
+```md
+# Arey Pi Project Readiness Report
+
+## Overall
+- Overall Readiness: N/5
+- Lowest Rule Scores:
+- Highest Rule Scores:
+
+## Blockers
+
+## Quick Wins
+
+## Rule Scores
+- Canonical Specs
+- Gherkin Authoring
+- Tests/TDD
+- Test Quality
+- Quality Tooling
+- Engineering Quality
+- Spec Sync
+- Database Specs, when applicable
+- Rebuildability
+- Architecture Memory
+- Incremental Commits
+- AI Harness
+
+## Recommended Plan
+
+## Residual Risks / Unknowns
+```
+
+For every score, include evidence with file paths or explicit missing-file observations.
+
+## Bootstrap Mode
+
+Only after user approval, implement selected improvements such as:
+
+- creating or updating `AGENTS.md`;
+- adding missing validation scripts;
+- adding spec directory skeletons;
+- adding initial DBML skeletons for database projects;
+- adding Arey Pi prompts or skills;
+- documenting quality tooling;
+- adding ADR/glossary structure.
+
+Bootstrap Mode must follow Arey Pi policies, including quality tooling, DoD, and incremental Conventional Commits.