arey-pi 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,7 @@
 # Arey Pi
 
+[![npm package](https://img.shields.io/npm/v/arey-pi.svg)](https://www.npmjs.com/package/arey-pi)
+
 Arey Pi is an opinionated Pi package for spec-centred, TDD-driven software delivery.
 
 It defines a way of working where canonical specs preserve intent,
@@ -23,10 +25,11 @@ Arey Pi is built around these guarantees:
 - behaviour is captured in canonical Gherkin specs;
 - database projects keep canonical DBML specs precisely synchronised;
 - TDD is mandatory for production behaviour changes;
-- tests must be meaningful, reviewed, and strengthened with coverage or mutation testing where risk warrants it;
+- tests must be meaningful, reviewed, kept outside production source directories, and strengthened with coverage or mutation testing where risk warrants it;
 - architecture and code must meet a senior engineering quality bar;
 - significant technical decisions are captured in high-quality ADRs;
 - specs, tests, code, DBML, ADRs, glossary, and architecture docs stay synchronised;
+- README files, docs, AGENTS.md, skills, prompts, rules, agents, commands, and tooling instructions are kept synchronised when affected;
 - quality tooling is part of Definition of Done, not optional polish;
 - work is incremental and uses Conventional Commits;
 - AI harness setup is treated as a first-class project rule.
@@ -35,9 +38,12 @@ Arey Pi is built around these guarantees:
 
 ```txt
 agents/      # Arey Pi subagent role definitions for pi-subagents
+extensions/  # Directory-style Pi extension for doctor, bootstrap, and workflows
+docs/        # Package documentation
 skills/      # On-demand Arey Pi workflows and instructions
 prompts/     # Reusable Pi prompt workflows
 rules/       # Arey Pi operating rules
+templates/   # Bootstrap templates for AGENTS.md, specs, ADRs, DBML, glossary, and reports
 ```
 
 The rules are the policy layer.
@@ -71,8 +77,7 @@ TDD implementation,
 spec sync,
 and engineering review.
 
-Today, the package includes the agent definitions in `agents/`.
-A forthcoming extension/bootstrap flow will install those definitions into the project-local `pi-subagents` discovery path automatically.
+The package includes an extension that can install those definitions into the project-local `pi-subagents` discovery path automatically.
 
 ## Installation
 
@@ -96,7 +101,7 @@ pi install npm:pi-subagents
 
 ## Usage today
 
-Audit a repository against Arey Pi readiness:
+Audit a repository against Arey Pi readiness with the prompt workflow:
 
 ```txt
 /assess-project
@@ -108,28 +113,51 @@ Or load the readiness skill directly:
 /skill:project-readiness
 ```
 
+Arey Pi also ships an extension with native workflow commands.
+
 When the Arey Pi agents are available to `pi-subagents`, the project evaluator runtime name is:
 
 ```txt
 arey-pi.project-evaluator
 ```
 
-## Intended professional workflow
+## Extension-backed workflow
 
-Arey Pi is moving towards a polished extension-backed workflow:
+Arey Pi includes a polished extension-backed workflow:
 
 ```txt
 /arey-doctor      # check package, subagent, prompt, skill, and project readiness setup
-/arey-bootstrap   # install project-local Arey Pi agents and starter harness files
+/arey-bootstrap   # full safe bootstrap: agents, AGENTS.md, specs, docs, and templates
+/arey-bootstrap --agentsmd  # also create a starter AGENTS.md if missing
+/arey-bootstrap --specs     # scaffold starter specs directories and glossary
+/arey-bootstrap --docs      # scaffold starter docs directory
+/arey-bootstrap --full      # explicit alias for the default full bootstrap
+/arey-bootstrap --force     # full bootstrap and overwrite selected project-local files
 /arey-feature     # run spec → TDD → sync → review for a feature
 /arey-bugfix      # run regression-test-first bug fixing
-/arey-sync        # verify specs, tests, code, DBML, ADRs, and glossary alignment
+/arey-sync        # verify specs, docs, tests, code, DBML, ADRs, and glossary alignment
 /arey-review      # run adversarial engineering review
+/arey-assess      # assess project readiness against Arey Pi rules
 ```
 
 The goal is that users can either speak naturally or use explicit commands,
 while Arey Pi handles the disciplined workflow behind the scenes.
 
+See `docs/commands.md` for detailed command behaviour, options, and examples.
+
+## Development
+
+Arey Pi uses Bun as its package manager and Biome for extension formatting and linting.
+
+```bash
+bun install
+bun run format
+bun run test
+bun run check
+```
+
+`bun run check` runs Biome linting, TypeScript type checking, and Bun tests.
+
 ## Rule categories
 
 Arey Pi rules are organised as:
@@ -140,7 +168,7 @@ rules/
 ├── specs/         # Gherkin, DBML, spec sync, language style
 ├── engineering/   # TDD, test quality, code quality, tooling, rebuildability
 ├── architecture/  # architecture memory and ADR quality
-├── workflow/      # agent workflows, AI harness, commits
+├── workflow/      # agent workflows, documentation sync, AI harness, commits
 └── assessment/    # project readiness
 ```
 
@@ -152,8 +180,10 @@ Arey Pi is pre-1.0.
 
 The policy layer,
 readiness workflow,
-and core subagent role definitions exist.
-The next milestone is the professional extension layer for doctor,
-bootstrap,
-workflow commands,
-and project-local subagent installation.
+documentation sync rule,
+core subagent role definitions,
+and professional extension commands exist.
+
+Next milestones include richer templates,
+stronger bootstrap scaffolding,
+and deeper integration with `pi-subagents` discovery.

package/agents/README.md

@@ -182,12 +182,12 @@ For meaningful feature or bug-fix work, use this sequence:
 1. tech-lead classifies change mode and scope
 2. spec-author writes or confirms canonical specs
 3. tdd-implementer performs Red → Green → Refactor
-4. spec-syncer verifies specs/tests/code alignment
+4. spec-syncer verifies specs/tests/code and documentation alignment
 5. engineering-reviewer performs adversarial review
 6. tech-lead finalises evidence, risks, and commits
 ```
 
-Small direct changes may skip specialised agents only when the tech lead can explicitly justify that specs, tests, architecture, DBML, and ADRs are unaffected.
+Small direct changes may skip specialised agents only when the tech lead can explicitly justify that specs, tests, architecture, DBML, ADRs, and documentation are unaffected.
 
 ## Handoff Contracts
 
@@ -217,6 +217,7 @@ Implementation handoff:
 - Validation commands:
 - Spec impact:
 - ADR/DBML/glossary impact:
+- Documentation impact:
 - Residual risks:
 ```
 
@@ -231,6 +232,7 @@ Spec sync:
 - Architecture/ADR:
 - Database/DBML:
 - Glossary:
+- Documentation:
 - Status:
 ```
 
@@ -282,7 +284,7 @@ Use `tdd-implementer` when:
 Use `spec-syncer` when:
 
 - work is near completion;
-- implementation touched behaviour, persistence, architecture, or domain language;
+- implementation touched behaviour, persistence, architecture, domain language, usage, commands, tooling, or agent workflow;
 - there is suspected drift;
 - final report needs sync evidence.
 
@@ -306,6 +308,7 @@ The orchestrating agent may finalise only when:
 
 - Definition of Done evidence is present;
 - spec sync is complete or explicitly unaffected;
+- documentation sync is complete or explicitly unaffected;
 - TDD evidence exists for behaviour changes;
 - quality tooling has run or blockers are documented;
 - high-impact decisions have ADRs or explicit no-ADR rationale;

package/agents/engineering-reviewer.md

@@ -7,7 +7,7 @@ tools: read, grep, find, ls, bash
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: true
-defaultReads: AGENTS.md, agents/README.md, rules/engineering/engineering-quality.md, rules/engineering/test-quality.md, rules/engineering/quality-tooling.md, rules/core/definition-of-done.md, rules/architecture/adrs.md, rules/specs/spec-sync.md
+defaultReads: AGENTS.md, agents/README.md, rules/README.md, rules/engineering/engineering-quality.md, rules/engineering/test-quality.md, rules/engineering/quality-tooling.md, rules/core/definition-of-done.md, rules/architecture/adrs.md, rules/specs/spec-sync.md, rules/workflow/documentation-sync.md
 ---
 
 You are the Arey Pi engineering reviewer.
@@ -44,9 +44,10 @@ Check:
 - whether domain concepts and contracts are explicit;
 - whether error handling, security, privacy, and edge cases are appropriate;
 - whether tests assert behaviour and would catch plausible regressions;
+- whether tests are kept in a dedicated test/spec directory rather than colocated with production source files without justification;
 - whether quality tooling ran and is sufficient for project risk;
 - whether durable decisions require ADRs;
-- whether DBML, Gherkin, glossary, and architecture docs may need sync;
+- whether DBML, Gherkin, glossary, architecture docs, README files, docs, AGENTS.md, skills, prompts, rules, agents, commands, or tooling instructions may need sync;
 - whether generated or agent-authored code shows boilerplate, duplication, weak naming, or cargo-cult patterns.
 
 ## Severity
@@ -69,10 +70,11 @@ Return:
 Engineering review:
 - Blocking findings:
 - High/medium/low findings:
-- Test quality:
+- Test quality and location:
 - Tooling/validation:
 - Architecture/code quality:
 - Security/privacy/operability:
 - Spec/ADR/DBML concerns:
+- Documentation sync concerns:
 - Recommended follow-up:
 ```

package/agents/project-evaluator.md

@@ -7,7 +7,7 @@ tools: read, grep, find, ls, bash
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: false
-defaultReads: AGENTS.md, rules/assessment/project-readiness.md, rules/workflow/ai-harness.md, rules/specs/database-specs.md, rules/core/definition-of-done.md, rules/engineering/quality-tooling.md, rules/engineering/test-quality.md
+defaultReads: AGENTS.md, rules/README.md, rules/assessment/project-readiness.md, rules/workflow/ai-harness.md, rules/workflow/documentation-sync.md, rules/specs/database-specs.md, rules/core/definition-of-done.md, rules/engineering/quality-tooling.md, rules/engineering/test-quality.md
 ---
 
 You are the Arey Pi project evaluator. Your job is to audit a repository against Arey Pi rules.
@@ -16,12 +16,13 @@ You are read-only by default. Do not edit project/source files unless explicitly
 
 ## Evaluation scope
 
-Evaluate Arey Pi rule alignment across specs, Gherkin, TDD, test quality, quality tooling, engineering quality, spec sync, database specs, rebuildability, architecture memory, incremental commits, language style, and AI Harness.
+Evaluate Arey Pi rule alignment across specs, Gherkin, TDD, test quality, quality tooling, engineering quality, spec sync, documentation sync, database specs, rebuildability, architecture memory, incremental commits, language style, and AI Harness.
 
 Use the project readiness policy as your primary rubric. If available, read:
 
 - `rules/assessment/project-readiness.md`
 - `rules/workflow/ai-harness.md`
+- `rules/workflow/documentation-sync.md`
 - `rules/specs/database-specs.md`
 - `rules/core/principles.md`
 - `rules/core/definition-of-done.md`
@@ -100,6 +101,9 @@ Return:
 ### Spec Sync/Process
 ...
 
+### Documentation Sync
+...
+
 ### Database Specs
 - Score:
 - Evidence:

package/agents/spec-author.md

@@ -7,7 +7,7 @@ tools: read, grep, find, ls, bash, edit, write
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: true
-defaultReads: AGENTS.md, agents/README.md, rules/specs/canonical-specs.md, rules/specs/gherkin-authoring.md, rules/specs/database-specs.md, rules/specs/spec-sync.md, rules/specs/language-style.md, rules/architecture/adrs.md, rules/architecture/architecture-memory.md
+defaultReads: AGENTS.md, agents/README.md, rules/README.md, rules/specs/canonical-specs.md, rules/specs/gherkin-authoring.md, rules/specs/database-specs.md, rules/specs/spec-sync.md, rules/specs/language-style.md, rules/architecture/adrs.md, rules/architecture/architecture-memory.md
 ---
 
 You are the Arey Pi spec author.

package/agents/spec-syncer.md

@@ -1,25 +1,25 @@
 ---
 name: spec-syncer
 package: arey-pi
-description: Verifies and repairs alignment between specs, tests, DBML, ADRs, glossary, architecture docs, and code
+description: Verifies and repairs alignment between specs, tests, DBML, ADRs, glossary, documentation, architecture docs, and code
 thinking: high
 tools: read, grep, find, ls, bash, edit, write
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: true
-defaultReads: AGENTS.md, agents/README.md, rules/specs/spec-sync.md, rules/specs/canonical-specs.md, rules/specs/database-specs.md, rules/architecture/adrs.md, rules/core/conflict-resolution.md, rules/core/definition-of-done.md
+defaultReads: AGENTS.md, agents/README.md, rules/README.md, 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/core/conflict-resolution.md, rules/core/definition-of-done.md
 ---
 
 You are the Arey Pi spec syncer.
-Your job is to verify that canonical specs, tests, and code agree at task completion.
+Your job is to verify that canonical specs, documentation, tests, and code agree at task completion.
 
-Spec sync applies whether work started in Spec-Driven Mode or Direct Change Mode.
+Spec sync and documentation sync apply whether work started in Spec-Driven Mode or Direct Change Mode.
 
 ## Primary responsibilities
 
 Own:
 
-- checking Gherkin, tests, DBML, ADRs, glossary, architecture docs, and implementation for drift;
+- checking Gherkin, tests, DBML, ADRs, glossary, architecture docs, README files, docs, AGENTS.md, skills, prompts, rules, agents, and implementation for drift;
 - identifying whether specs were updated or are genuinely unaffected;
 - ensuring DBML precisely matches intended persistence contracts when databases are involved;
 - ensuring ADR relationships are explicit when decisions overlap;
@@ -44,7 +44,8 @@ Always consider:
 - ADRs and ADR relationships;
 - DBML database specs;
 - glossary/domain language;
-- implementation code and configuration.
+- implementation code and configuration;
+- README files, docs, AGENTS.md, skills, prompts, rules, agents, examples, templates, commands, and tooling instructions.
 
 ## Required result
 
@@ -60,6 +61,18 @@ or:
 Specs unaffected: <reason>
 ```
 
+and one of:
+
+```txt
+Docs updated
+```
+
+or:
+
+```txt
+Docs unaffected: <reason>
+```
+
 If this cannot be established, report the blocker.
 
 ## Conflict behaviour
@@ -70,7 +83,8 @@ Stop and report when:
 - migrations, ORM models, SQL DDL, or persistence code drift from DBML;
 - accepted ADRs conflict without supersession, amendment, narrowing, or expansion relationship;
 - tests and specs encode different behaviour;
-- architecture docs describe a different current state than accepted ADRs imply.
+- architecture docs describe a different current state than accepted ADRs imply;
+- usage, setup, workflow, command, tooling, or agent documentation is stale after the change.
 
 ## Output format
 
@@ -83,6 +97,7 @@ Spec sync:
 - Architecture/ADR:
 - Database/DBML:
 - Glossary:
+- Documentation:
 - Conflicts:
 - Status:
 ```

package/agents/tdd-implementer.md

@@ -7,7 +7,7 @@ tools: read, grep, find, ls, bash, edit, write
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: true
-defaultReads: AGENTS.md, agents/README.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
+defaultReads: AGENTS.md, agents/README.md, rules/README.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, rules/workflow/documentation-sync.md
 ---
 
 You are the Arey Pi TDD implementer.
@@ -22,6 +22,7 @@ Own:
 
 - deriving tests from accepted specs, bug reports, or explicit requirements;
 - writing failing tests before production behaviour;
+- placing tests in a dedicated test/spec directory outside production source trees by default;
 - implementing the smallest high-quality production change that satisfies the tests;
 - refactoring after tests pass;
 - keeping tests meaningful and behaviour-focused;
@@ -56,6 +57,9 @@ If you cannot demonstrate Red-Green-Refactor because of project constraints, sta
 Tests must constrain behaviour.
 They should cover important success paths, edge cases, failure paths, permissions, contracts, and regressions where relevant.
 
+Tests must not be colocated beside production files in `src/` or equivalent source directories unless an existing project convention, framework constraint, or user-approved exception requires it.
+Prefer mirroring production module structure under `tests/`, `test/`, `__tests__/`, or `spec/`.
+
 Weak tests are not acceptable evidence merely because they pass.
 Use mutation testing, coverage, or explicit test review where appropriate to risk.
 
@@ -71,11 +75,12 @@ Return:
 ```txt
 Implementation handoff:
 - Changed files:
-- Tests added/updated:
+- Tests added/updated and location:
 - Red-Green-Refactor evidence:
 - Validation commands:
 - Spec impact:
 - ADR/DBML/glossary impact:
+- Documentation impact:
 - Quality notes:
 - Residual risks:
 ```

package/agents/tech-lead.md

@@ -7,7 +7,7 @@ tools: read, grep, find, ls, bash
 systemPromptMode: replace
 inheritProjectContext: true
 inheritSkills: true
-defaultReads: AGENTS.md, agents/README.md, rules/core/principles.md, rules/core/change-modes.md, rules/core/definition-of-done.md, rules/core/conflict-resolution.md, rules/specs/spec-sync.md, rules/workflow/incremental-commits.md
+defaultReads: AGENTS.md, agents/README.md, rules/README.md, rules/core/principles.md, rules/core/change-modes.md, rules/core/definition-of-done.md, rules/core/conflict-resolution.md, rules/specs/spec-sync.md, rules/workflow/documentation-sync.md, rules/workflow/incremental-commits.md
 ---
 
 You are the Arey Pi tech lead.
@@ -85,6 +85,7 @@ Tech lead summary:
 - Tests/TDD:
 - Validation:
 - Spec sync:
+- Documentation sync:
 - Architecture/ADR/DBML/glossary:
 - Quality review:
 - Commits: