arey-pi 0.1.0 → 0.3.0

package/docs/commands.md

@@ -0,0 +1,354 @@
+# Arey Pi Commands
+
+Arey Pi ships a Pi extension that registers native slash commands.
+The extension uses Pi's documented directory style at `extensions/arey-pi/index.ts`.
+
+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] [--specs] [--docs] [--full] [--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 templates 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 and performs a safe starter scaffold.
+
+With no flags, `/arey-bootstrap` runs the full bootstrap path:
+
+```txt
+--agentsmd --specs --docs
+```
+
+Default agent target:
+
+```txt
+.pi/agents/arey-pi/
+```
+
+By default, existing project-local agent files and scaffold files are not overwritten.
+Starter scaffold files are copied from the packaged `templates/` directory.
+Selective flags are available when you only want one part of the scaffold.
+
+Usage:
+
+```txt
+/arey-bootstrap
+```
+
+This creates or installs, where missing:
+
+```txt
+.pi/agents/arey-pi/
+AGENTS.md
+specs/README.md
+specs/features/README.md
+specs/features/example.feature
+specs/database/README.md
+specs/database/schema.dbml
+specs/architecture/README.md
+specs/decisions/README.md
+specs/decisions/0001-record-architecture-decision.md
+specs/glossary.md
+docs/README.md
+docs/project-readiness-report.md
+```
+
+Options:
+
+```txt
+/arey-bootstrap --agentsmd
+```
+
+Also creates a starter root `AGENTS.md` when one does not already exist.
+
+```txt
+/arey-bootstrap --specs
+```
+
+Creates starter Arey Pi spec structure when files do not already exist:
+
+```txt
+specs/README.md
+specs/features/README.md
+specs/features/example.feature
+specs/database/README.md
+specs/database/schema.dbml
+specs/architecture/README.md
+specs/decisions/README.md
+specs/decisions/0001-record-architecture-decision.md
+specs/glossary.md
+```
+
+```txt
+/arey-bootstrap --docs
+```
+
+Creates starter project documentation structure when files do not already exist:
+
+```txt
+docs/README.md
+docs/project-readiness-report.md
+```
+
+```txt
+/arey-bootstrap --full
+```
+
+Explicitly runs the same combined bootstrap path as `/arey-bootstrap` with no flags:
+
+```txt
+--agentsmd --specs --docs
+```
+
+```txt
+/arey-bootstrap --force
+```
+
+Overwrites existing project-local Arey Pi agent files and scaffold files selected by the other flags.
+When used alone, it applies to the default full bootstrap path.
+It also creates a starter `AGENTS.md` when one does not already exist.
+
+Examples:
+
+```txt
+/arey-bootstrap --specs --docs
+/arey-bootstrap --full
+/arey-bootstrap --full --force
+```
+
+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/core.ts

@@ -0,0 +1,121 @@
+export const requiredAgents = [
+  "tech-lead.md",
+  "spec-author.md",
+  "tdd-implementer.md",
+  "spec-syncer.md",
+  "engineering-reviewer.md",
+  "project-evaluator.md",
+] as const;
+
+export type ScaffoldFile = { template: string; target: string };
+
+export const specScaffoldFiles: ScaffoldFile[] = [
+  { template: "specs-readme.md", target: "specs/README.md" },
+  { template: "features-readme.md", target: "specs/features/README.md" },
+  { template: "feature.feature", target: "specs/features/example.feature" },
+  { template: "database-readme.md", target: "specs/database/README.md" },
+  { template: "database.dbml", target: "specs/database/schema.dbml" },
+  { template: "architecture-readme.md", target: "specs/architecture/README.md" },
+  { template: "decisions-readme.md", target: "specs/decisions/README.md" },
+  { template: "adr.md", target: "specs/decisions/0001-record-architecture-decision.md" },
+  { template: "glossary.md", target: "specs/glossary.md" },
+];
+
+export const docsScaffoldFiles: ScaffoldFile[] = [
+  { template: "docs-readme.md", target: "docs/README.md" },
+  { template: "project-readiness-report.md", target: "docs/project-readiness-report.md" },
+];
+
+const selectiveBootstrapFlags = ["--agentsmd", "--specs", "--docs", "--full"];
+
+export type BootstrapPlan = {
+  flags: string[];
+  force: boolean;
+  full: boolean;
+  defaultFullBootstrap: boolean;
+  createAgentsMd: boolean;
+  createSpecs: boolean;
+  createDocs: boolean;
+};
+
+export function parseBootstrapFlags(args: string): BootstrapPlan {
+  const flags = args.split(/\s+/).filter(Boolean);
+  const force = flags.includes("--force");
+  const full = flags.includes("--full");
+  const hasSelectiveScaffoldFlag = flags.some((flag) => selectiveBootstrapFlags.includes(flag));
+  const defaultFullBootstrap = !hasSelectiveScaffoldFlag;
+
+  return {
+    flags,
+    force,
+    full,
+    defaultFullBootstrap,
+    createAgentsMd: defaultFullBootstrap || flags.includes("--agentsmd") || full,
+    createSpecs: defaultFullBootstrap || flags.includes("--specs") || full,
+    createDocs: defaultFullBootstrap || flags.includes("--docs") || full,
+  };
+}
+
+export type WorkflowKind = "feature" | "bugfix" | "sync" | "review" | "assess" | string;
+
+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. 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}`;
+  }
+}
+
+export type DoctorReportInput = {
+  packageVersion: string;
+  cwd: string;
+  packageRulesPresent: boolean;
+  packageTemplatesPresent: boolean;
+  packageAgentsCount: number;
+  requiredAgentsCount: number;
+  hasSubagentsCommand: boolean;
+  installedAgentsCount: number;
+  hasRootAgentsMd: boolean;
+  hasPiSettings: boolean;
+  promptsCount: number;
+  skillsCount: number;
+  missingAgents: string[];
+};
+
+export function buildDoctorReport(input: DoctorReportInput): string {
+  return [
+    "# Arey Pi Doctor",
+    "",
+    `- Package: arey-pi@${input.packageVersion}`,
+    `- Project: ${input.cwd}`,
+    `- Package rules present: ${input.packageRulesPresent ? "yes" : "no"}`,
+    `- Package templates present: ${input.packageTemplatesPresent ? "yes" : "no"}`,
+    `- Package agents present: ${input.packageAgentsCount}/${input.requiredAgentsCount}`,
+    `- pi-subagents command detected: ${input.hasSubagentsCommand ? "yes" : "no"}`,
+    `- Project-local Arey Pi agents: ${input.installedAgentsCount}/${input.requiredAgentsCount}`,
+    `- Root AGENTS.md: ${input.hasRootAgentsMd ? "yes" : "no"}`,
+    `- .pi/settings.json: ${input.hasPiSettings ? "yes" : "no"}`,
+    `- Arey Pi prompts discovered: ${input.promptsCount}`,
+    `- Arey Pi skills discovered: ${input.skillsCount}`,
+    "",
+    "## Missing project agents",
+    input.missingAgents.length ? input.missingAgents.map((agent) => `- ${agent}`).join("\n") : "- none",
+    "",
+    "## Recommended next step",
+    input.installedAgentsCount === input.requiredAgentsCount
+      ? "- 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");
+}