@cratis/pi 3.3.0 → 3.4.0

package/README.md

@@ -14,6 +14,12 @@ Cratis quality hooks. When no `.cratis/ai.json` exists, it exposes the complete
 packaged skill set. It therefore gives Pi the complete single-harness Cratis
 experience without requiring the Cratis CLI.
 
+The `subagent` tool stands down for the session when another extension already
+provides a delegation tool named `Agent` (such as pi-subagents, which lists the
+same agents). It removes itself from the active tools at session start and
+shows one notice when Pi has a UI, so the model is not offered two delegation
+tools.
+
 The managed CLI path remains the choice when one repository must configure and
 synchronize several harnesses. It writes the resolved corpus to `.cratis/ai`,
 creates every harness integration, and records hashes for safe update and

package/package/corpus/agents/backend-developer.md

@@ -5,7 +5,6 @@ description: >
   Creates the single slice file containing all backend artifacts:
   commands, events, validators, constraints, read models, projections,
   and reactors — all in strict compliance with the vertical slice architecture.
-model: claude-sonnet-4-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/code-reviewer.md

@@ -4,7 +4,6 @@ description: >
   Quality gate agent for Cratis-based projects. Reviews code against all
   project instruction files, checking architecture conformance, C# and
   TypeScript conventions, and vertical slice correctness before merge.
-model: claude-sonnet-4-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/coordinator.md

@@ -8,7 +8,6 @@ description: >
   Use this agent when a request spans multiple concerns (backend + frontend,
   multiple slices, mixed C#/TypeScript work, or requires both implementation
   and review).
-model: claude-sonnet-4-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/frontend-developer.md

@@ -4,7 +4,6 @@ description: >
   Specialist for TypeScript/React frontend code within a vertical slice.
   Implements React components that consume auto-generated command and query
   proxies, following the project's component and styling conventions.
-model: claude-sonnet-4-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/orchestrator.md

@@ -8,7 +8,6 @@ description: >
   Use this agent as the entry point whenever multiple agents need to work together
   as a team: mixed implementation + documentation + review, multi-feature work,
   large refactors, or any goal that spans more than one concern.
-model: claude-sonnet-4-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/performance-reviewer.md

@@ -4,7 +4,6 @@ description: >
   Performance-focused review agent for Cratis-based projects. Analyzes changed
   files for projection efficiency, query patterns, unnecessary allocations,
   React render overhead, and Chronicle anti-patterns before merge.
-model: claude-sonnet-4-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/planner.md

@@ -5,7 +5,6 @@ description: >
   Breaks the work into ordered, parallelisable tasks, delegates each task
   to the right specialist agent, and ensures quality gates are met before
   the work is considered done.
-model: claude-sonnet-4-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/repository-investigation-reviewer.md

@@ -4,7 +4,6 @@ description: >
   Independent, read-only reviewer for typed Cratis repository investigations.
   Reviews evidence and repository-mode reasoning without applying application
   conventions to framework or client-library repositories.
-model: claude-opus-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/repository-investigator.md

@@ -4,7 +4,6 @@ description: >
   Read-only investigator for Cratis application and framework repositories.
   Produces typed, evidence-backed findings without changing source, invoking
   mutating Chronicle operations, or assuming an application architecture.
-model: claude-opus-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/security-reviewer.md

@@ -5,7 +5,6 @@ description: >
   security review of all changed files before merge, covering input validation,
   auth/authz, data exposure, secrets, event sourcing specifics, and frontend
   attack surface.
-model: claude-sonnet-4-5
 tools:
   - Read
   - Grep

package/package/corpus/agents/slice-implementer.md

@@ -4,7 +4,6 @@ description: >
   Implements a Cratis vertical slice end-to-end — all backend artifacts in one slice file, BDD specs
   in when_*/ folders, and the React surface (page and/or command dialog). Use for new slices and for
   non-trivial slice changes spanning backend and frontend.
-model: claude-opus-4-8
 tools:
   - Read
   - Grep

package/package/corpus/agents/spec-writer.md

@@ -4,7 +4,6 @@ description: >
   Specialist for writing C# specs (the in-process scenario family) and
   TypeScript/React specs for vertical slices. Ensures every slice has
   comprehensive behavior coverage following the project's BDD conventions.
-model: claude-sonnet-4-5
 tools:
   - Read
   - Grep

package/package/corpus/harnesses/pi/extensions/subagent/agents.ts

@@ -4,7 +4,8 @@
  * The agent definitions are the SINGLE-SOURCE corpus files under `.cratis/ai/agents/*.md`,
  * surfaced to Pi through symlink adapters in `.pi/agents/*.md`. Those files are written
  * in the Claude/Copilot shape (Title-Case `name`, a YAML-list `tools:` using Claude tool
- * names such as `Read`/`Glob`/`Bash`, and a `model:` id). Pi's built-in tools are the
+ * names such as `Read`/`Glob`/`Bash`). Agents without a `model:` inherit the dispatching
+ * session's model. Pi's built-in tools are the
  * lowercase set `read, write, edit, bash, grep, find, ls`, so this module NORMALIZES the
  * shared shape to Pi semantics — the adapter layer absorbs the tool difference, exactly
  * like every other adapter in this corpus, so `.pi/agents/*.md` can stay pure symlinks.

package/package/corpus/harnesses/pi/extensions/subagent/delegation.ts

@@ -0,0 +1,40 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Deciding whether the Cratis `subagent` tool stands down for a session.
+ *
+ * Widely used delegation extensions already read `.pi/agents/*.md` — pi-subagents registers a tool named
+ * `Agent` that lists every Cratis corpus agent. Offering that tool and `subagent` side by side makes the
+ * model guess which to call and pay for both descriptions, so the Cratis tool yields to the one the user
+ * installed deliberately.
+ *
+ * The match is on the exact tool name, not a substring: `agent` is a common word in unrelated tool names,
+ * and silently withdrawing delegation against one of those would be a bug nobody could see.
+ *
+ * Kept free of host calls so the policy is testable from the tool list alone; the extension owns
+ * `getAllTools`, `setActiveTools` and the notice.
+ */
+
+import type { ToolInfo } from "@earendil-works/pi-coding-agent";
+
+/** The name the Cratis delegation tool registers under. */
+export const SUBAGENT_TOOL_NAME = "subagent";
+
+/** Tool names that mean "another extension already delegates to agents". */
+export const FOREIGN_DELEGATION_TOOL_NAMES: ReadonlySet<string> = new Set(["Agent"]);
+
+/** The registered delegation tool the Cratis tool yields to, or `undefined` when there is none. */
+export function foreignDelegationTool<T extends Pick<ToolInfo, "name">>(tools: readonly T[]): T | undefined {
+	return tools.find((tool) => FOREIGN_DELEGATION_TOOL_NAMES.has(tool.name));
+}
+
+/** The one informational notice shown when the Cratis tool stands down. */
+export function standDownNotice(tool: Pick<ToolInfo, "name"> & { sourceInfo?: Partial<ToolInfo["sourceInfo"]> }): string {
+	const source = tool.sourceInfo?.source ?? "another extension";
+	return (
+		`The "${tool.name}" tool from ${source} already delegates to agents, so the Cratis ` +
+		`"${SUBAGENT_TOOL_NAME}" tool is disabled for this session to avoid offering two delegation tools. ` +
+		`Remove that extension to use "${SUBAGENT_TOOL_NAME}" instead.`
+	);
+}

package/package/corpus/harnesses/pi/extensions/subagent/index.ts

@@ -12,6 +12,10 @@
  *   - single:   { agent, task }
  *   - parallel: { tasks: [{ agent, task }, ...] }   (max 8, 4 concurrent)
  *   - chain:    { chain: [{ agent, task }, ...] }    (sequential, {previous} placeholder)
+ *
+ * Stand-down: when another extension already provides a delegation tool named `Agent` (pi-subagents,
+ * which reads the same `.pi/agents/*.md`), this tool removes itself from the session's active tools at
+ * session start and says so once — see `./delegation.ts`. Without such a tool it behaves unchanged.
  */
 
 import { spawn } from "node:child_process";
@@ -23,6 +27,7 @@ import { CONFIG_DIR_NAME, type ExtensionAPI, getAgentDir } from "@earendil-works
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { type AgentConfig, type AgentScope, discoverAgents } from "./agents.ts";
+import { foreignDelegationTool, standDownNotice, SUBAGENT_TOOL_NAME } from "./delegation.ts";
 
 const extensionPath = fileURLToPath(import.meta.url);
 const isPackagedExtension = extensionPath.includes(`${path.sep}package${path.sep}corpus${path.sep}`);
@@ -257,8 +262,28 @@ export default function (pi: ExtensionAPI) {
 	} catch {
 		knownAgents = "";
 	}
+	// Yield to another extension's delegation tool. This can only happen at session start: getAllTools
+	// cannot be called while extensions load, and an extension loaded after this one is not visible yet.
+	// setActiveTools rebuilds the system prompt before the first turn, so the model never sees this tool.
+	let standDownNoticeShown = false;
+	pi.on("session_start", (_event, ctx) => {
+		try {
+			const foreign = foreignDelegationTool(pi.getAllTools());
+			if (!foreign) return;
+			const active = pi.getActiveTools();
+			if (!active.includes(SUBAGENT_TOOL_NAME)) return;
+			pi.setActiveTools(active.filter((name) => name !== SUBAGENT_TOOL_NAME));
+			if (ctx.hasUI && !standDownNoticeShown) {
+				standDownNoticeShown = true;
+				ctx.ui.notify(standDownNotice(foreign), "info");
+			}
+		} catch {
+			// Some hosts cannot list or switch tools; being unable to check is no reason to fail the session.
+		}
+	});
+
 	pi.registerTool({
-		name: "subagent",
+		name: SUBAGENT_TOOL_NAME,
 		label: "Subagent",
 		description: [
 			"Delegate a task to a specialized Cratis agent in an isolated context (separate pi process).",

package/package/corpus/skills/cratis-social-feed-post/SKILL.md

@@ -42,6 +42,38 @@ a trade rather than a free improvement.
 Check the opening by reading only the first three lines and asking whether they are worth
 expanding. If the answer depends on the fourth line, the opening is wrong.
 
+## Sound like a person talking
+
+A post that reads as generated gets scrolled past as generated, however accurate it is. The
+fix is not a smoother sentence. It is writing the way someone who built the thing would
+explain it to a colleague over coffee.
+
+- **Open with something that happened.** What shipped, a real number, what you found this
+  week. A concrete, checkable event reads as a person reporting. An aphorism about the domain
+  ("A skill is just text…") reads as a slogan, however clever it is.
+- **Talk, don't announce.** Contractions, a sentence that starts with "So" or "And", a
+  parenthetical aside, a question answered straight away ("Why bother? Because…"). Use them
+  the way speech does, now and then, not as a new pattern on every line.
+- **Show the default, then the better way.** Name what the reader, or their coding agent,
+  writes today in concrete terms, then the shape you are offering, with real identifiers. A
+  before-and-after persuades; adjectives do not.
+- **Sell with specifics.** Enthusiasm is welcome and a list of real capabilities is
+  persuasive. What persuades is the command, the count, and the thing the reader can do
+  tomorrow, not "powerful", "seamless" or "game-changing".
+- **Say why in the words you would use out loud.** A reason with a stake ("we don't want the
+  good version of that to be a paid add-on") beats a principle stated in the abstract.
+- **Put a limit where it applies.** "On macOS and Linux, the installer…" carries the limit
+  inside the claim. A closing paragraph labeled "One honest limit:" reads as a disclaimer a
+  reviewer bolted on.
+- **Keep the review out of the copy.** Evidence, verification and approval language belongs
+  in the review record. A qualifier that protects the writer instead of informing the reader
+  makes the post read as noncommittal. Keep every qualification that is true and would
+  change what the reader does; drop the rest.
+- **Stop when you are done.** A plain next step ("Links in the comments") ends a post better
+  than a tidy closing maxim.
+
+The tells to remove in review are listed in the **cratis-writing-voice-and-cadence** skill.
+
 ## Never use Unicode pseudo-formatting
 
 Third-party tools offer pseudo-bold and pseudo-italic built from Mathematical Alphanumeric
@@ -66,7 +98,9 @@ said first. A point that needs visual weight belongs in an image with its own al
 
 ## Structure that survives a phone
 
-- One idea per post. A feed reader will not assemble two.
+- One thread per post. A feed reader will not assemble two arguments. An announcement may
+  still list what shipped as a plain list of short fragments inside that thread, with no
+  bolded labels and no slogan per item.
 - Short paragraphs, one to three sentences, and visibly different from each other in length.
   A column of identically sized blocks reads as a generated template before it reads as an
   argument.

package/package/corpus/skills/cratis-social-feed-post/verification.json

@@ -9,6 +9,10 @@
     { "kind": "skill-contains", "value": "A brief opening sentence is a hook doing its job" },
     { "kind": "skill-contains", "value": "No external link in the body" },
     { "kind": "skill-contains", "value": "No engagement bait" },
-    { "kind": "skill-contains", "value": "unofficial approximations" }
+    { "kind": "skill-contains", "value": "unofficial approximations" },
+    { "kind": "skill-contains", "value": "Sound like a person talking" },
+    { "kind": "skill-contains", "value": "Open with something that happened" },
+    { "kind": "skill-contains", "value": "Put a limit where it applies" },
+    { "kind": "skill-contains", "value": "Keep the review out of the copy" }
   ]
 }

package/package/corpus/skills/cratis-writing-voice-and-cadence/SKILL.md

@@ -27,6 +27,11 @@ recurrence.
 | **"rather than"** | The same correction carried by a different connective |
 | **Em-dash pivot** | The dash used to swing into a closing clause |
 | **"That is what X is for"** | A pointer sentence standing in for an explanation |
+| **Punchline fragment** | A two- or three-word sentence landing a slogan: "They run." |
+| **Signpost pair** | "That's the X. Here's the Y." Announcing the structure instead of having one |
+| **Labeled caveat** | "One honest limit:" A limitation parked in its own closing paragraph |
+| **Aphoristic close** | A tidy maxim as the last line, restating what the piece already said |
+| **Reflexive triplet** | Three parallel items where the thought had one or two |
 
 To measure rather than guess, count them. Searching for `, not a`, `; ` between two clauses,
 `rather than`, and an em-dash followed by a short closing clause takes a few minutes across a
@@ -48,9 +53,23 @@ Look at ten pieces together, not one at a time:
   assertion — "A screen that needs…", "A registration test can…" — is one move. Alternate it
   with a question, a direct address, a concrete moment, or a number.
 
+## Hedging that protects the writer
+
+The other common complaint is "wishy-washy": copy so qualified that it never commits to
+anything. It usually comes from review language leaking into the material: evidence,
+verification and approval wording that belongs in the review record, and qualifiers that
+protect the writer without informing the reader.
+
+The rule below protects every hedge that is true and would change what the reader does. It
+does not protect review residue. Move the evidence to the review record, state the capability
+plainly, and put a real limit inside the sentence it limits ("on macOS and Linux, …") instead
+of in a separate disclaimer.
+
 ## Address somebody
 
 - **Say "you".** Material that tells a reader what to do should address that reader.
+- **A company account is a team talking.** Write "we", the way the people who built it would
+  say it, not the company name in the third person.
 - **Attributed writing should sound attributed.** Prose published under a person's name and
   written entirely in the impersonal third person reads as documentation wearing a byline.
   Opinion, judgement and preference belong to the named author and are theirs to give.

package/package/corpus/skills/cratis-writing-voice-and-cadence/verification.json

@@ -8,6 +8,10 @@
     { "kind": "skill-contains", "value": "every hedging word" },
     { "kind": "skill-contains", "value": "First person is not a licence to invent" },
     { "kind": "skill-contains", "value": "Structural sameness is the more damaging half" },
-    { "kind": "skill-contains", "value": "Rewrite a tranche, read it, and only then continue" }
+    { "kind": "skill-contains", "value": "Rewrite a tranche, read it, and only then continue" },
+    { "kind": "skill-contains", "value": "Punchline fragment" },
+    { "kind": "skill-contains", "value": "Labeled caveat" },
+    { "kind": "skill-contains", "value": "Hedging that protects the writer" },
+    { "kind": "skill-contains", "value": "A company account is a team talking" }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cratis/pi",
-  "version": "3.3.0",
+  "version": "3.4.0",
   "description": "Configuration-aware Cratis AI integration for Pi",
   "type": "module",
   "files": [