arey-pi 0.1.0 → 0.2.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,
@@ -27,6 +29,7 @@ Arey Pi is built around these guarantees:
 - 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,6 +38,7 @@ Arey Pi is built around these guarantees:
 
 ```txt
 agents/      # Arey Pi subagent role definitions for pi-subagents
+extensions/  # Slash commands for doctor, bootstrap, and workflows
 skills/      # On-demand Arey Pi workflows and instructions
 prompts/     # Reusable Pi prompt workflows
 rules/       # Arey Pi operating rules
@@ -71,8 +75,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 +99,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 +111,47 @@ 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   # install project-local Arey Pi agents
+/arey-bootstrap --agentsmd  # also create a starter AGENTS.md if missing
+/arey-bootstrap --force     # overwrite existing project-local Arey Pi agents
 /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 check
+```
+
+`bun run check` runs Biome linting and TypeScript type checking.
+
 ## Rule categories
 
 Arey Pi rules are organised as:
@@ -140,7 +162,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 +174,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.
@@ -46,7 +46,7 @@ Check:
 - whether tests assert behaviour and would catch plausible regressions;
 - 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
@@ -74,5 +74,6 @@ Engineering review:
 - 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.
@@ -76,6 +76,7 @@ Implementation handoff:
 - 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:

package/docs/commands.md

@@ -0,0 +1,278 @@
+# Arey Pi Commands
+
+Arey Pi ships a Pi extension that registers native slash commands.
+
+The commands are designed for two modes of use:
+
+- quick explicit workflows such as `/arey-feature` or `/arey-sync`;
+- natural-language work where the parent agent acts as the Arey Pi tech lead and uses the same workflow expectations.
+
+## Command overview
+
+```txt
+/arey-doctor
+/arey-bootstrap [--agentsmd] [--force]
+/arey-feature <feature request>
+/arey-bugfix <bug description>
+/arey-sync [scope]
+/arey-review [scope]
+/arey-assess [scope]
+```
+
+## `/arey-doctor`
+
+Checks whether Arey Pi is available and whether the current project is ready for subagent-backed workflows.
+
+It reports:
+
+- Arey Pi package version;
+- current project path;
+- whether packaged rules are present;
+- whether packaged agents are present;
+- whether `pi-subagents` appears to be installed;
+- whether project-local Arey Pi agents exist in `.pi/agents/arey-pi/`;
+- whether root `AGENTS.md` exists;
+- whether `.pi/settings.json` exists;
+- how many Arey Pi prompts and skills are discovered;
+- missing project-local agent files;
+- recommended next step.
+
+Usage:
+
+```txt
+/arey-doctor
+```
+
+Use this after installing Arey Pi,
+after running `/arey-bootstrap`,
+or when subagent workflows are not behaving as expected.
+
+## `/arey-bootstrap`
+
+Installs Arey Pi's packaged subagent definitions into the current project.
+
+Default target:
+
+```txt
+.pi/agents/arey-pi/
+```
+
+By default, existing project-local agent files are not overwritten.
+
+Usage:
+
+```txt
+/arey-bootstrap
+```
+
+Options:
+
+```txt
+/arey-bootstrap --agentsmd
+```
+
+Also creates a starter root `AGENTS.md` when one does not already exist.
+
+```txt
+/arey-bootstrap --force
+```
+
+Overwrites existing project-local Arey Pi agent files.
+It also creates a starter `AGENTS.md` when one does not already exist.
+
+Use this command after installing Arey Pi and `pi-subagents` in a repository where you want the Arey Pi agents to be discoverable by `pi-subagents`.
+
+## `/arey-feature`
+
+Starts the Arey Pi feature delivery workflow.
+
+Usage:
+
+```txt
+/arey-feature <feature request>
+```
+
+Example:
+
+```txt
+/arey-feature Add password reset with expiring email links
+```
+
+The command sends a structured request to the parent agent to act as the Arey Pi tech lead.
+The expected workflow is:
+
+```txt
+spec-author → tdd-implementer → spec-syncer → engineering-reviewer
+```
+
+The workflow should:
+
+- confirm or update canonical specs;
+- 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.
+
+## `/arey-bugfix`
+
+Starts the Arey Pi regression-test-first bugfix workflow.
+
+Usage:
+
+```txt
+/arey-bugfix <bug description>
+```
+
+Example:
+
+```txt
+/arey-bugfix Users can bypass email verification by refreshing the session
+```
+
+The workflow should:
+
+- reproduce the bug with a failing regression test;
+- implement the smallest high-quality fix;
+- keep TDD evidence visible;
+- update Gherkin, docs, DBML, ADRs, glossary, or architecture docs when affected;
+- run validation and report residual risks.
+
+## `/arey-sync`
+
+Runs Arey Pi sync review for the current repository or a specific scope.
+
+Usage:
+
+```txt
+/arey-sync
+/arey-sync <scope>
+```
+
+Examples:
+
+```txt
+/arey-sync
+/arey-sync authentication flow
+/arey-sync current diff
+```
+
+The command asks the parent agent to verify alignment across:
+
+- Gherkin specs;
+- tests;
+- code;
+- DBML;
+- ADRs;
+- glossary;
+- architecture docs;
+- README files;
+- `docs/`;
+- `AGENTS.md`;
+- skills, prompts, rules, agents, examples, templates;
+- command and tooling instructions.
+
+The final report should include both:
+
+```txt
+Specs updated
+```
+
+or:
+
+```txt
+Specs unaffected: <reason>
+```
+
+and:
+
+```txt
+Docs updated
+```
+
+or:
+
+```txt
+Docs unaffected: <reason>
+```
+
+## `/arey-review`
+
+Runs an adversarial Arey Pi engineering review.
+
+Usage:
+
+```txt
+/arey-review
+/arey-review <scope>
+```
+
+Examples:
+
+```txt
+/arey-review
+/arey-review current diff
+/arey-review persistence layer
+```
+
+The review should examine:
+
+- architecture and code quality;
+- test quality;
+- quality tooling and validation evidence;
+- security and privacy;
+- reliability and operability;
+- maintainability;
+- spec, ADR, DBML, glossary, and documentation sync concerns;
+- generated-code or agent-authored-code slop.
+
+Findings should be classified by severity.
+
+## `/arey-assess`
+
+Runs Arey Pi project readiness assessment.
+
+Usage:
+
+```txt
+/arey-assess
+/arey-assess <scope>
+```
+
+Examples:
+
+```txt
+/arey-assess
+/arey-assess backend package only
+```
+
+The assessment is read-only by default.
+It should score the repository against Arey Pi rules,
+provide evidence with file paths,
+identify blockers and quick wins,
+and propose a prioritised improvement plan.
+
+Use this when adopting Arey Pi in an existing repository or checking whether a project remains aligned.
+
+## Busy agent behaviour
+
+Workflow commands send a user message to the current Pi session.
+
+If the agent is idle,
+the workflow starts immediately.
+
+If the agent is already working,
+the workflow is queued as a follow-up message.
+
+## Relationship to natural language
+
+Commands are optional.
+
+Users can also work naturally:
+
+```txt
+Implement magic links following Arey Pi.
+```
+
+The commands exist to make common workflows explicit,
+repeatable,
+and easier to discover.

package/extensions/arey-pi.ts

@@ -0,0 +1,268 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const agentSourceDir = join(packageRoot, "agents");
+const rulesDir = join(packageRoot, "rules");
+const requiredAgents = [
+  "tech-lead.md",
+  "spec-author.md",
+  "tdd-implementer.md",
+  "spec-syncer.md",
+  "engineering-reviewer.md",
+  "project-evaluator.md",
+];
+
+function cwdFrom(ctx: unknown): string {
+  const maybe = ctx as { cwd?: string };
+  return maybe.cwd ?? process.cwd();
+}
+
+function fileExists(path: string): boolean {
+  try {
+    return existsSync(path) && statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function dirExists(path: string): boolean {
+  try {
+    return existsSync(path) && statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function copyAgents(targetDir: string, force: boolean): { copied: string[]; skipped: string[]; missing: string[] } {
+  mkdirSync(targetDir, { recursive: true });
+
+  const copied: string[] = [];
+  const skipped: string[] = [];
+  const missing: string[] = [];
+
+  for (const agent of requiredAgents) {
+    const source = join(agentSourceDir, agent);
+    const target = join(targetDir, agent);
+
+    if (!fileExists(source)) {
+      missing.push(agent);
+      continue;
+    }
+
+    if (fileExists(target) && !force) {
+      skipped.push(agent);
+      continue;
+    }
+
+    copyFileSync(source, target);
+    copied.push(agent);
+  }
+
+  return { copied, skipped, missing };
+}
+
+function starterAgentsMd(): string {
+  return `# 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.
+- Keep specs, tests, code, DBML, ADRs, glossary, and architecture docs 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.
+
+## Subagents
+
+Project-local Arey Pi subagents live in:
+
+\`\`\`txt
+.pi/agents/arey-pi/
+\`\`\`
+
+Use them through pi-subagents when available.
+`;
+}
+
+function workflowMessage(kind: string, 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.`;
+
+  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.`;
+    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.`;
+    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.`;
+    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:
+      return `${common}\n\nWork on: ${target}`;
+  }
+}
+
+function sendWorkflow(
+  pi: ExtensionAPI,
+  args: string,
+  ctx: {
+    ui: { notify(message: string, level?: string): void };
+    isIdle(): boolean;
+  },
+  kind: string,
+  usage: string,
+) {
+  if (!args.trim()) {
+    ctx.ui.notify(usage, "warning");
+    return;
+  }
+
+  const message = workflowMessage(kind, args);
+  if (ctx.isIdle()) {
+    pi.sendUserMessage(message);
+  } else {
+    pi.sendUserMessage(message, { deliverAs: "followUp" });
+    ctx.ui.notify("Arey Pi workflow queued as follow-up", "info");
+  }
+}
+
+function packageVersion(): string {
+  try {
+    const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")) as { version?: string };
+    return pkg.version ?? "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+export default function areyPi(pi: ExtensionAPI) {
+  pi.registerCommand("arey-doctor", {
+    description: "Check Arey Pi package, project bootstrap, and subagent readiness",
+    handler: async (_args, ctx) => {
+      const cwd = cwdFrom(ctx);
+      const projectAgentDir = join(cwd, ".pi", "agents", "arey-pi");
+      const commands = pi.getCommands();
+      const hasSubagentsCommand = commands.some((command) => command.name.startsWith("subagents-doctor"));
+      const installedAgents = requiredAgents.filter((agent) => fileExists(join(projectAgentDir, agent)));
+      const missingAgents = requiredAgents.filter((agent) => !fileExists(join(projectAgentDir, agent)));
+      const packageAgents = requiredAgents.filter((agent) => fileExists(join(agentSourceDir, agent)));
+      const prompts = commands.filter(
+        (command) => command.source === "prompt" && command.sourceInfo?.source?.includes("arey-pi"),
+      );
+      const skills = commands.filter(
+        (command) => command.source === "skill" && command.sourceInfo?.source?.includes("arey-pi"),
+      );
+
+      const report = [
+        "# Arey Pi Doctor",
+        "",
+        `- Package: arey-pi@${packageVersion()}`,
+        `- Project: ${cwd}`,
+        `- Package rules present: ${dirExists(rulesDir) ? "yes" : "no"}`,
+        `- Package agents present: ${packageAgents.length}/${requiredAgents.length}`,
+        `- pi-subagents command detected: ${hasSubagentsCommand ? "yes" : "no"}`,
+        `- Project-local Arey Pi agents: ${installedAgents.length}/${requiredAgents.length}`,
+        `- Root AGENTS.md: ${fileExists(join(cwd, "AGENTS.md")) ? "yes" : "no"}`,
+        `- .pi/settings.json: ${fileExists(join(cwd, ".pi", "settings.json")) ? "yes" : "no"}`,
+        `- Arey Pi prompts discovered: ${prompts.length}`,
+        `- Arey Pi skills discovered: ${skills.length}`,
+        "",
+        "## Missing project agents",
+        missingAgents.length ? missingAgents.map((agent) => `- ${agent}`).join("\n") : "- none",
+        "",
+        "## Recommended next step",
+        installedAgents.length === requiredAgents.length
+          ? "- Project-local Arey Pi subagents are installed. Use `/arey-feature`, `/arey-bugfix`, `/arey-sync`, `/arey-review`, or natural language."
+          : "- Run `/arey-bootstrap` to install project-local Arey Pi subagents.",
+      ].join("\n");
+
+      pi.sendMessage({
+        customType: "arey-pi-doctor",
+        content: report,
+        display: true,
+        details: {},
+      });
+    },
+  });
+
+  pi.registerCommand("arey-bootstrap", {
+    description: "Install Arey Pi project-local subagents and optional starter AGENTS.md",
+    handler: async (args, ctx) => {
+      const cwd = cwdFrom(ctx);
+      const force = args.split(/\s+/).includes("--force");
+      const createAgentsMd = args.split(/\s+/).includes("--agentsmd");
+      const targetDir = join(cwd, ".pi", "agents", "arey-pi");
+      const result = copyAgents(targetDir, force);
+      const agentsMdPath = join(cwd, "AGENTS.md");
+      let agentsMdStatus = "unchanged";
+
+      if (!fileExists(agentsMdPath) && (createAgentsMd || force)) {
+        writeFileSync(agentsMdPath, starterAgentsMd());
+        agentsMdStatus = "created";
+      }
+
+      const report = [
+        "# Arey Pi Bootstrap",
+        "",
+        `- Target: ${relative(cwd, targetDir)}`,
+        `- Copied agents: ${result.copied.length}`,
+        `- Skipped existing agents: ${result.skipped.length}`,
+        `- Missing package agents: ${result.missing.length}`,
+        `- AGENTS.md: ${agentsMdStatus}`,
+        "",
+        "## Copied",
+        result.copied.length ? result.copied.map((agent) => `- ${agent}`).join("\n") : "- none",
+        "",
+        "## Skipped",
+        result.skipped.length ? result.skipped.map((agent) => `- ${agent}`).join("\n") : "- none",
+        "",
+        "Run `/arey-doctor` to verify setup.",
+      ].join("\n");
+
+      pi.sendMessage({
+        customType: "arey-pi-bootstrap",
+        content: report,
+        display: true,
+        details: result,
+      });
+    },
+  });
+
+  pi.registerCommand("arey-feature", {
+    description: "Run an Arey Pi spec-to-TDD feature workflow",
+    handler: async (args, ctx) => sendWorkflow(pi, args, ctx, "feature", "Usage: /arey-feature <feature request>"),
+  });
+
+  pi.registerCommand("arey-bugfix", {
+    description: "Run an Arey Pi regression-test-first bugfix workflow",
+    handler: async (args, ctx) => sendWorkflow(pi, args, ctx, "bugfix", "Usage: /arey-bugfix <bug description>"),
+  });
+
+  pi.registerCommand("arey-sync", {
+    description: "Run Arey Pi spec, test, code, DBML, ADR, and glossary sync",
+    handler: async (args, ctx) =>
+      sendWorkflow(pi, args || "the current repository", ctx, "sync", "Usage: /arey-sync [scope]"),
+  });
+
+  pi.registerCommand("arey-review", {
+    description: "Run an Arey Pi adversarial engineering review",
+    handler: async (args, ctx) =>
+      sendWorkflow(pi, args || "the current diff", ctx, "review", "Usage: /arey-review [scope]"),
+  });
+
+  pi.registerCommand("arey-assess", {
+    description: "Assess project readiness against Arey Pi rules",
+    handler: async (args, ctx) =>
+      sendWorkflow(pi, args || "the current repository", ctx, "assess", "Usage: /arey-assess [scope]"),
+  });
+}

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "arey-pi",
-  "version": "0.1.0",
+  "version": "0.2.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",
   "type": "module",
+  "packageManager": "bun@1.3.10",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/alereyleyva/arey-pi.git"
@@ -23,6 +24,8 @@
   ],
   "files": [
     "agents/",
+    "extensions/",
+    "docs/",
     "skills/",
     "prompts/",
     "rules/",
@@ -31,6 +34,9 @@
     "LICENSE"
   ],
   "pi": {
+    "extensions": [
+      "./extensions/arey-pi.ts"
+    ],
     "skills": [
       "./skills"
     ],
@@ -39,10 +45,27 @@
     ]
   },
   "scripts": {
-    "check": "node -e \"JSON.parse(require('fs').readFileSync('package.json', 'utf8'))\"",
-    "prepublishOnly": "npm run check && npm pack --dry-run"
+    "format": "biome format --write .",
+    "lint": "biome lint .",
+    "typecheck": "tsc --noEmit",
+    "check": "bun run lint && bun run typecheck",
+    "prepublishOnly": "bun run check && npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
   },
   "publishConfig": {
     "access": "public"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.16",
+    "@earendil-works/pi-coding-agent": "^0.78.1",
+    "@types/node": "^25.9.2",
+    "typescript": "^6.0.3"
   }
 }

package/prompts/assess-project.md

@@ -17,7 +17,7 @@ Evaluate alignment with Arey Pi rules:
 - test quality, coverage, mutation testing readiness
 - formatter/linter/static analysis/typecheck/dynamic validation
 - architecture and code quality signals
-- spec sync and Definition of Done
+- spec sync, documentation sync, and Definition of Done
 - DBML database specs when the project uses a database
 - rebuildability and architecture memory
 - Conventional Commits / incremental process
@@ -29,6 +29,7 @@ Read and apply these policies when present:
 
 - `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/test-quality.md`

package/rules/README.md

@@ -12,7 +12,7 @@ rules/
 ├── specs/         # canonical specs, Gherkin, DBML, spec sync, language style
 ├── engineering/   # TDD, test quality, code/architecture quality, tooling, rebuildability
 ├── architecture/  # architecture memory and ADR expectations
-├── workflow/      # agent workflows, AI harness, commits
+├── workflow/      # agent workflows, documentation sync, AI harness, commits
 └── assessment/    # project readiness evaluation
 ```
 
@@ -49,6 +49,7 @@ rules/
 ### Workflow
 
 - `workflow/agent-workflows.md`
+- `workflow/documentation-sync.md`
 - `workflow/incremental-commits.md`
 - `workflow/ai-harness.md`
 

package/rules/assessment/project-readiness.md

@@ -81,7 +81,7 @@ Check whether:
 - the implementation reflects senior engineering standards;
 - generated or agent-authored code has been reviewed for quality.
 
-### Spec Sync
+### Spec and Documentation Sync
 
 Check whether:
 
@@ -89,6 +89,7 @@ Check whether:
 - behaviour changes have corresponding Gherkin updates or no-impact reasoning;
 - database changes have precise DBML updates or no-impact reasoning;
 - architecture/ADR/glossary updates exist when durable knowledge changed;
+- README files, docs, AGENTS.md, skills, prompts, rules, agents, examples, templates, commands, and tooling instructions are updated when affected;
 - Definition of Done expectations are documented.
 
 ### Database Specs

package/rules/core/definition-of-done.md

@@ -24,6 +24,7 @@ A change is complete when:
 - architecture docs or high-quality ADRs are updated when durable decisions changed;
 - DBML database specs exist and are precisely synchronised when the project has a database and the change touches schema, migrations, ORM models, or persistence contracts;
 - glossary is updated when domain language changed;
+- README files, docs, AGENTS.md, skills, prompts, rules, agents, examples, templates, commands, and tooling instructions are updated when affected or explicitly confirmed unaffected;
 - code changes are scoped and minimal for the intended behaviour;
 - project-facing prose follows the configured language style, UK English by default;
 - specs use semantic line breaks, and touched documentation preserves or improves semantic line breaks;
@@ -45,6 +46,7 @@ A change is not done if:
 - the project lacks quality tooling and the gap has not been surfaced to the user;
 - significant technical decisions exist only in chat, implementation comments, or low-value ADRs that do not explain context, options, tradeoffs, and consequences;
 - project-facing prose mixes language styles without reason;
+- usage, setup, workflow, command, tooling, or agent documentation is stale after the change;
 - specs or touched docs ignore semantic line break conventions;
 - unrelated cleanup is mixed into the change without approval.
 
@@ -59,6 +61,7 @@ Done summary:
 - Validation:
 - Quality tooling:
 - Spec sync:
+- Documentation sync:
 - Architecture/code quality:
 - Architecture/ADR/glossary:
 - Database/DBML:

package/rules/specs/spec-sync.md

@@ -32,6 +32,7 @@ At task completion, agents must consider each canonical dimension:
 - **Database/DBML:** Did migrations, ORM models, SQL DDL, schema definitions, indexes, constraints, relationships, or persistence contracts change?
 - **ADRs:** Was a meaningful technical decision made that future agents/developers need to understand, and is it important enough for a high-quality ADR rather than process noise?
 - **Glossary:** Was a new domain term introduced or an existing meaning changed?
+- **Documentation:** Did README files, docs, AGENTS.md, skills, prompts, rules, agents, examples, templates, commands, or tooling instructions change or need to change?
 
 ## Required Behaviour
 
@@ -43,7 +44,9 @@ If database structure changed, update the canonical DBML spec precisely.
 
 If durable domain language changed, update the glossary.
 
-If only implementation changed and behaviour stayed the same, explain why specs are unaffected and name the coverage relied on where practical.
+If usage, setup, commands, agent instructions, tooling, or project workflow changed, update documentation or explicitly confirm docs are unaffected.
+
+If only implementation changed and behaviour stayed the same, explain why specs and docs are unaffected and name the coverage relied on where practical.
 
 ## Conflict Handling
 
@@ -66,5 +69,6 @@ Spec sync:
 - Architecture/ADR:
 - Database/DBML:
 - Glossary:
+- Documentation:
 - Status:
 ```

package/rules/workflow/documentation-sync.md

@@ -0,0 +1,88 @@
+# Documentation Sync
+
+## Purpose
+
+Documentation sync ensures that project-facing instructions and operational knowledge stay aligned with the change that was made.
+
+It complements spec sync.
+Specs preserve canonical product and system intent.
+Documentation sync preserves how humans and agents understand, use, operate, and extend the project.
+
+## Core Rule
+
+Every completed change must consider whether documentation needs to be updated.
+
+The final result must include one of:
+
+```txt
+Docs updated
+```
+
+or:
+
+```txt
+Docs unaffected: <reason>
+```
+
+Do not leave users, maintainers, or future agents with stale instructions.
+
+## Documentation Dimensions
+
+At task completion, agents must consider whether the change affects:
+
+- `README.md` files;
+- `docs/` content;
+- root or nested `AGENTS.md` files;
+- Pi prompts, skills, rules, agents, or extension docs;
+- developer setup, commands, package manager, tooling, or validation instructions;
+- public API, CLI, configuration, environment variables, or deployment instructions;
+- architecture overview docs;
+- ADR indexes or decision references;
+- troubleshooting, operational runbooks, or release notes;
+- examples, templates, or onboarding material.
+
+## Required Behaviour
+
+If user-facing usage changes, update README or docs.
+
+If agent behaviour, commands, safety rules, or project workflow changes, update `AGENTS.md`, skills, prompts, rules, or agent docs as appropriate.
+
+If development commands, package manager, tooling, validation, or release process changes, update developer documentation.
+
+If architecture or operational expectations change, update architecture docs, runbooks, or ADR references where appropriate.
+
+If docs are unaffected, explain why in the final report.
+
+## Quality Bar
+
+Documentation updates must be accurate, minimal, and useful.
+
+Agents must avoid:
+
+- stale command examples;
+- documenting features that do not exist;
+- copying policy text into multiple places when a link or reference is better;
+- broad doc rewrites unrelated to the change;
+- mixing language styles;
+- ignoring semantic line breaks in specs or touched docs.
+
+## Relationship to Spec Sync
+
+Spec sync answers whether canonical behaviour and durable project knowledge are aligned.
+
+Documentation sync answers whether users, maintainers, and agents have the correct operational instructions.
+
+Both checks are required before completion.
+
+## Final Report Format
+
+Agents should include documentation sync in final reports:
+
+```txt
+Documentation sync:
+- README/docs:
+- AGENTS.md/AI harness:
+- Skills/prompts/rules/agents:
+- Developer commands/tooling:
+- Status:
+```

package/skills/project-readiness/SKILL.md

@@ -68,6 +68,7 @@ Produce:
 - Quality Tooling
 - Engineering Quality
 - Spec Sync
+- Documentation Sync
 - Database Specs, when applicable
 - Rebuildability
 - Architecture Memory
@@ -90,6 +91,7 @@ Only after user approval, implement selected improvements such as:
 - adding spec directory skeletons;
 - adding initial DBML skeletons for database projects;
 - adding Arey Pi prompts or skills;
+- updating stale README/docs/AGENTS.md instructions;
 - documenting quality tooling;
 - adding ADR/glossary structure.