pi-matt-pocock 0.2.2 → 0.3.0

package/src/catalog.json

@@ -35,6 +35,7 @@
     "kind": "workflow",
     "invocation": "user",
     "label": "Grill Me",
+    "description": "Interview the user relentlessly, one decision at a time, until you share one understanding. Use when the user says grill me.",
     "standalone": true,
     "requires": [
       "grilling"
@@ -324,6 +325,7 @@
     "kind": "workflow",
     "invocation": "user",
     "label": "Handoff",
+    "description": "Write a handoff document that another agent or person can pick up cold.",
     "standalone": true,
     "discloses": [
       "phase-boundaries"
@@ -337,6 +339,27 @@
       }
     ]
   },
+  {
+    "id": "pr",
+    "file": "pr.md",
+    "kind": "utility",
+    "invocation": "model",
+    "label": "Pull Request Body",
+    "description": "Write a PR body with summary, evidence, and merge risk.",
+    "standalone": true
+  },
+  {
+    "id": "retro",
+    "file": "retro.md",
+    "kind": "utility",
+    "invocation": "user",
+    "label": "Session Retrospective",
+    "description": "Review a coding session and propose improvements to the agent environment.",
+    "standalone": true,
+    "requires": [
+      "writing-for-agents"
+    ]
+  },
   {
     "id": "diagnosing-bugs",
     "file": "diagnosing-bugs.md",
@@ -349,6 +372,7 @@
     ],
     "standalone": true,
     "discloses": [
+      "hitl-loop.template.sh",
       "improve-codebase-architecture"
     ],
     "workflows": [
@@ -435,6 +459,7 @@
     "kind": "workflow",
     "invocation": "user",
     "label": "Improve Codebase Architecture",
+    "description": "Find and rank architecture deepening opportunities, then improve the strongest one.",
     "standalone": true,
     "requires": [
       "codebase-design"
@@ -593,10 +618,10 @@
     "kind": "utility",
     "invocation": "model",
     "label": "Domain Modeling",
-    "description": "Build or sharpen project terminology, CONTEXT.md, and architectural decisions.",
+    "description": "Build or sharpen project terminology, GLOSSARY.md, and architectural decisions.",
     "standalone": true,
     "discloses": [
-      "CONTEXT-FORMAT",
+      "GLOSSARY-FORMAT",
       "ADR-FORMAT"
     ]
   },
@@ -605,7 +630,7 @@
     "file": "tdd.md",
     "kind": "utility",
     "invocation": "model",
-    "label": "Tdd",
+    "label": "TDD",
     "description": "Run the BDD-driven red-green automation loop through public seams.",
     "standalone": true,
     "requires": [
@@ -623,21 +648,21 @@
     "file": "ADR-FORMAT.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "ADR FORMAT"
+    "label": "ADR Format"
   },
   {
     "id": "AGENT-BRIEF",
     "file": "AGENT-BRIEF.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "AGENT BRIEF"
+    "label": "Agent Brief"
   },
   {
     "id": "bdd-best-practices",
     "file": "bdd-best-practices.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "Bdd Best Practices",
+    "label": "BDD Best Practices",
     "discloses": [
       "gherkin-guide",
       "bdd",
@@ -651,26 +676,19 @@
     "file": "bdd.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "Bdd",
+    "label": "BDD",
     "discloses": [
       "bdd-best-practices",
       "tdd",
       "code-review"
     ]
   },
-  {
-    "id": "CONTEXT-FORMAT",
-    "file": "CONTEXT-FORMAT.md",
-    "kind": "reference",
-    "invocation": "internal",
-    "label": "CONTEXT FORMAT"
-  },
   {
     "id": "DEEPENING",
     "file": "DEEPENING.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "DEEPENING",
+    "label": "Deepening",
     "discloses": [
       "codebase-design"
     ]
@@ -680,7 +698,7 @@
     "file": "DESIGN-IT-TWICE.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "DESIGN IT TWICE",
+    "label": "Design It Twice",
     "discloses": [
       "codebase-design",
       "DEEPENING"
@@ -708,16 +726,19 @@
   {
     "id": "GLOSSARY-FORMAT",
     "file": "GLOSSARY-FORMAT.md",
+    "aliases": [
+      "CONTEXT-FORMAT"
+    ],
     "kind": "reference",
     "invocation": "internal",
-    "label": "GLOSSARY FORMAT"
+    "label": "Glossary Format"
   },
   {
     "id": "GLOSSARY",
     "file": "GLOSSARY.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "GLOSSARY",
+    "label": "Glossary",
     "discloses": [
       "writing-great-skills"
     ]
@@ -727,7 +748,7 @@
     "file": "HTML-REPORT.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "HTML REPORT",
+    "label": "HTML Report",
     "discloses": [
       "codebase-design"
     ]
@@ -737,7 +758,7 @@
     "file": "issue-tracker-github.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "Issue Tracker Github",
+    "label": "Issue Tracker GitHub",
     "discloses": [
       "triage",
       "wayfinder"
@@ -748,7 +769,7 @@
     "file": "issue-tracker-gitlab.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "Issue Tracker Gitlab",
+    "label": "Issue Tracker GitLab",
     "discloses": [
       "triage",
       "wayfinder"
@@ -769,7 +790,7 @@
     "file": "LEARNING-RECORD-FORMAT.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "LEARNING RECORD FORMAT",
+    "label": "Learning Record Format",
     "discloses": [
       "GLOSSARY-FORMAT"
     ]
@@ -779,7 +800,7 @@
     "file": "LOGIC.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "LOGIC",
+    "label": "Logic",
     "discloses": [
       "UI",
       "prototype"
@@ -790,7 +811,7 @@
     "file": "MISSION-FORMAT.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "MISSION FORMAT"
+    "label": "Mission Format"
   },
   {
     "id": "mocking",
@@ -804,7 +825,7 @@
     "file": "OUT-OF-SCOPE.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "OUT OF SCOPE"
+    "label": "Out of Scope"
   },
   {
     "id": "phase-boundaries",
@@ -821,7 +842,7 @@
     "file": "RESOURCES-FORMAT.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "RESOURCES FORMAT",
+    "label": "Resources Format",
     "discloses": [
       "teach"
     ]
@@ -831,7 +852,7 @@
     "file": "SKILL-MECHANICS.md",
     "kind": "reference",
     "invocation": "internal",
-    "label": "SKILL MECHANICS",
+    "label": "Skill Mechanics",
     "discloses": [
       "writing-for-agents"
     ]
@@ -883,7 +904,7 @@
     "file": "hitl-loop.template.sh",
     "kind": "asset",
     "invocation": "internal",
-    "label": "Hitl Loop.Template.Sh"
+    "label": "HITL Loop Template"
   },
   {
     "id": "template",

package/src/catalog.ts

@@ -28,12 +28,30 @@ export interface ProcedureDefinition {
   workflows?: WorkflowPlacement[];
 }
 
-const procedureDirectory = fileURLToPath(new URL("../procedures/", import.meta.url));
+/** The catalogue's own kinds decide where a resource lives; nothing else may. */
+const resourceDirectories: Record<ProcedureKind, string> = {
+  workflow: "procedures/",
+  utility: "procedures/",
+  reference: "references/",
+  asset: "assets/",
+};
+
+const packageDirectory = fileURLToPath(new URL("../", import.meta.url));
 const catalogPath = fileURLToPath(new URL("./catalog.json", import.meta.url));
 
 export const procedureCatalog = JSON.parse(readFileSync(catalogPath, "utf8")) as ProcedureDefinition[];
 const definitionsById = new Map(procedureCatalog.map((definition) => [definition.id, definition]));
 
+/** Absolute path of one catalogue resource, derived from its kind. */
+export function resourcePath(definition: ProcedureDefinition): string {
+  return `${packageDirectory}${resourceDirectories[definition.kind]}${definition.file}`;
+}
+
+/** Absolute directory holding every resource of one kind, so a reader can list them. */
+export function resourceDirectory(kind: ProcedureKind): string {
+  return `${packageDirectory}${resourceDirectories[kind]}`;
+}
+
 export function catalogFiles(): string[] {
   return procedureCatalog.map((definition) => definition.file);
 }
@@ -97,6 +115,13 @@ export function modelStandaloneCapabilities(): ProcedureDefinition[] {
   return standaloneCapabilities().filter((definition) => definition.invocation === "model");
 }
 
+/** Standalone capabilities the user starts by name. They stay out of capability mode
+ *  so the model never picks one on its own, but the gateway still exposes them so an
+ *  explicit request ("grill me") reaches the package instead of an improvised method. */
+export function userStandaloneCapabilities(): ProcedureDefinition[] {
+  return standaloneCapabilities().filter((definition) => definition.invocation === "user");
+}
+
 export function validateProcedureCatalog(): string[] {
   const errors: string[] = [];
   const ids = new Set<string>();
@@ -108,7 +133,7 @@ export function validateProcedureCatalog(): string[] {
     ids.add(definition.id);
     files.add(definition.file);
 
-    if (!existsSync(`${procedureDirectory}${definition.file}`)) {
+    if (!existsSync(resourcePath(definition))) {
       errors.push(`${definition.id}: file not found: ${definition.file}`);
     }
     for (const dependency of [...(definition.requires ?? []), ...(definition.discloses ?? [])]) {
@@ -124,6 +149,37 @@ export function validateProcedureCatalog(): string[] {
     }
   }
 
+  const aliases = new Map<string, string>();
+  for (const definition of procedureCatalog) {
+    for (const alias of definition.aliases ?? []) {
+      if (ids.has(alias) || aliases.has(alias)) errors.push(`${definition.id}: conflicting alias: ${alias}`);
+      aliases.set(alias, definition.id);
+    }
+    const placements = new Set<string>();
+    for (const placement of definition.workflows ?? []) {
+      if (placements.has(placement.route)) errors.push(`${definition.id}: duplicate placement for ${placement.route}`);
+      placements.add(placement.route);
+    }
+  }
+
+  const visiting = new Set<string>();
+  const visited = new Set<string>();
+  const visit = (definition: ProcedureDefinition): void => {
+    if (visiting.has(definition.id)) {
+      errors.push(`${definition.id}: required dependency cycle`);
+      return;
+    }
+    if (visited.has(definition.id)) return;
+    visiting.add(definition.id);
+    for (const id of definition.requires ?? []) {
+      const dependency = findProcedure(id);
+      if (dependency) visit(dependency);
+    }
+    visiting.delete(definition.id);
+    visited.add(definition.id);
+  };
+  for (const definition of procedureCatalog) visit(definition);
+
   const routes = new Map<string, WorkflowPlacement[]>();
   for (const definition of procedureCatalog) {
     for (const workflow of definition.workflows ?? []) {