allye-pi 1.5.1 → 1.6.1

package/README.md

@@ -29,7 +29,7 @@ Your AI agent has **68+ tools** but no idea when to use them. Allye adds the met
 
 | | Feature | Description |
 |---|---------|-------------|
-| **Workflow** | Guided delivery | Sandbox → Product Planning → Technical Planning → Orchestrator → Executor → Reviewer (Standards + Spec axes), connected by handovers between fresh, lean-context chats |
+| **Workflow** | Adaptive toolkit | Intent-driven use of context, skills, optional planning/tasks, action, verification, and persistence; checkpoints can be skipped or repeated proportionally |
 | **Planning** | Discussion phase | Gray areas identified, options presented with trade-offs, decisions captured |
 | **Memory** | Cross-session continuity | Agent searches past context at start, saves session state at end |
 | **TDD** | Test-driven development | Red-Green-Refactor with automatic detection of when TDD applies |
@@ -81,8 +81,8 @@ Prefer the paste-into-agent or marketplace routes below? They still work — the
 After installing, you get:
 - **OAuth authentication** — browser-based login, no tokens to manage
 - **Bootstrap hook** — injects workflow methodology at session start
-- **5 dispatched subagents** — reviewer-standards, reviewer-spec, deep-search, code-analyzer, executor, delegated via the Agent tool for phases that don't need to pause and ask you anything (executor only runs this way if you opt into automatic mode — manual is the default)
-- **17 skills** — Sandbox, Planning, Technical Planning, Orchestrator, and Delivery run as skills loaded directly into your conversation, loaded on-demand by the bootstrap, so they can ask you questions when something's ambiguous
+- **Optional delegation** — bounded research, review, or execution subagents may be used when the runtime supports them and delegation is beneficial; local execution remains valid
+- **17 composable skills** — discovery, planning, execution, review, delivery, memory, verification, and delegation playbooks loaded as needed; no universal phase chain is required
 - **Parallel delivery, when a runtime is detected** — the Orchestrator can drive several independent stories at once, each in its own git worktree and its own watchable agent process; without a detected runtime, delivery degrades to the existing manual and automatic-subagent modes
 
 #### Multiple Allye accounts (multi-tenant)
@@ -113,7 +113,7 @@ The agent will configure the MCP server via OAuth and install the `allye-opencod
 
 After installing, you get:
 - **6 agents in the picker** — Allye, Allye Plan, Allye Orchestrator, Allye Build, Allye Review, Allye Deliver (Ctrl+T to switch)
-- **Auto-loaded context** — your profile and team info injected before every conversation
+- **Adaptive context** — profile, team info, and relevant memories loaded when Allye is available and useful
 - **Dynamic skill discovery** — agents search for your team's standards via MCP
 
 **To update:** Paste this into your agent:
@@ -263,7 +263,7 @@ How multi-phase workflow support is implemented differs by platform, because not
 - **OpenCode** ships 6 agent-picker personas (Ctrl+T to switch) — Allye, Allye Plan, Allye Orchestrator, Allye Build, Allye Review, Allye Deliver — OpenCode's agent model supports switching personas interactively within a session, so all 6 can be full agents. The automatic-Executor dispatch mode is Claude-Code-only for now; OpenCode always runs Executor (Allye Build) as an interactive agent.
 - **Cursor, Codex, Gemini CLI** — a single agent handles all phases with the same workflow knowledge (no multi-agent picker on these platforms).
 - **Hermes Agent** reads skills from a directory (`~/.hermes/skills/allye/`) rather than fetching them over MCP, and gets the `using-allye` bootstrap injected by a small Python plugin at session start instead of a hook — otherwise the same single-agent, same-workflow-knowledge shape as Cursor/Codex/Gemini CLI.
-- **Pi** loads the canonical repository skills through a native Pi package, injects Allye context through the configured MCP adapter, and supports explicit executor or orchestrator mode. Executor mode is the safe default for Hermes-led work; orchestrator mode can drive Herdr through the five-primitive runtime contract.
+- **Pi** loads the canonical repository skills through a native Pi package, reads `using-allye` into the first prompt, injects Allye context through the configured MCP adapter, and exposes an adaptive toolkit. Herdr delegation is optional and capability-detected; tasks are recommended rather than mandatory.
 
 Every phase, on every platform:
 - Responds in **your language** (detected from your messages, falling back to your profile only before you've said anything)

package/docs/install-pi.md

@@ -7,7 +7,7 @@ replace Pi's MCP configuration:
 - the adapter exposes that directory through Pi's `resources_discover` event;
 - Allye context and memory are loaded through the already configured `allye`
   MCP server via `pi-mcp-adapter`;
-- Herdr is exposed only in explicit Pi orchestrator mode.
+- Herdr is exposed as an optional capability when the Pi session provides `HERDR_ENV=1`.
 
 ## Official package sources
 
@@ -74,47 +74,21 @@ Both npm and Git packages use the root Pi manifest and let Pi install
 source, canonical `skills/` directory, and Pi documentation; it is not the full
 plugin checkout and is not the installer input.
 
-## Modes
+## Adaptive toolkit
 
-Pi is an executor by default, which is the safe mode when Hermes is the master.
-The mode can be selected before starting a session:
+Pi does not select an executor or orchestrator mode. Allye is available as an
+adaptive toolkit in the current session. Use `/allye-capabilities` to inspect
+Allye/MCP, filesystem, subagent, and Herdr capabilities.
 
-```text
-ALLYE_PI_MODE=executor pi
-ALLYE_PI_MODE=orchestrator pi
-```
+When `HERDR_ENV=1`, the optional `allye_herdr` tool provides bounded `detect`,
+`spawn`, `dispatch`, `wait`, and Allye-backed `collect` operations. Without it,
+Pi continues locally. Herdr and subagents are capabilities, not prerequisites.
+Tasks are recommended for meaningful, delegated, multi-step, or review-heavy
+work, but an explicitly approved no-task path is supported.
 
-`ALLYE_ORCHESTRATOR=hermes` always forces executor mode. Pi orchestrator mode
-also requires both `ALLYE_ORCHESTRATION_RUN_ID` and `ALLYE_WORK_ITEM_KEY`; an
-explicit local lock is acquired before `allye_runtime` becomes active. The claim
-contains run/work-item identity, PID, session identity when available, a nonce,
-and a 30-minute lease. Normal `session_shutdown` aborts waits and removes only
-the exact claim owned by that instance. If a process crashes, recovery is
-disabled by default; after confirming the recorded local PID is gone and the
-lease expired, set `ALLYE_PI_RECOVER_STALE_LOCK=1` to quarantine and replace the
-lock. Active, unreadable, changed, or inconclusive locks fail closed. In a
-session, `/allye-mode executor` and `/allye-mode orchestrator` change the active
-mode only when the same guard succeeds. Only orchestrator mode enables the
-`allye_runtime` tool.
-
-### Pi orchestrator
-
-With `ALLYE_PI_MODE=orchestrator`, Pi coordinates the canonical workflow and may
-use `allye_runtime` for Herdr's `detect`, `spawn`, `dispatch`, `wait`, and
-Allye-backed `collect` operations. Parallel stories require separate worktrees;
-the pane cwd remains the plugin-enabled repository root and absolute worktree
-paths are placed in each briefing. The adapter does not create work items or change statuses automatically.
-Status updates by an assigned executor remain allowed through the canonical
-`execution` skill; pane/dispatch ownership is separate from status ownership.
-
-### Pi executor / Hermes master
-
-In executor mode, Pi reads the handed-over story/tasks, implements only that
-scope, follows the canonical `execution` skill, and may advance its assigned
-tasks to `in_progress` and `review` when the work and verification are complete.
-It does not create or dispatch panes, assume orchestration, or change scope.
-Hermes can remain the master and dispatch Pi or another agent through Herdr; Pi
-and Hermes must not orchestrate the same work item simultaneously.
+The adapter does not create work items or change statuses automatically. When a
+work item exists, Allye remains the source of truth for scope, decisions, and
+evidence; otherwise the user can proceed with proportional verification.
 
 ## Existing Pi startup extension
 
@@ -122,8 +96,7 @@ This package includes its own Allye bootstrap. If a user already has a separate
 `allye-memory-startup.ts`, both can be loaded without changing global files, but
 startup context may be fetched twice. To keep the existing global bootstrap as
 the only startup fetcher, set `ALLYE_PI_NATIVE_BOOTSTRAP=0`; canonical skill
-loading, mode handling, team-selection guidance, and the Herdr guard remain
-available.
+loading, capability detection, and team-selection guidance remain available.
 
 When `initialize` reports multiple teams without an active team, the adapter does
 not choose one silently and skips team-scoped memory search. If initialization
@@ -150,25 +123,21 @@ The extension is at `packages/allye-pi/src/index.ts`. Test it without changing
 Pi's global settings with:
 
 ```text
-pi -e ./packages/allye-pi/src/index.ts -p "Report the active Allye mode"
+pi -e ./packages/allye-pi/src/index.ts -p "Report the available Allye capabilities"
 ```
 
-When `allye_runtime dispatch` registers a wait, the wait runs inside the Pi
+When `allye_herdr dispatch` registers a wait, the wait runs inside the Pi
 process through managed `pi.exec`. On settlement it persists a durable session
 entry, shows a UI notification/message when available, and queues a follow-up
-turn to the Pi orchestrator. That message is evidence only and explicitly tells
-the orchestrator to run `allye_runtime collect` and inspect Allye
-`work_children`, Review memories, and Implementation memories before declaring
-completion. Normal completion, timeout, error, and abort are distinguished.
+turn to the current Pi session. That message is evidence only and explicitly
+tells the agent to run `allye_herdr collect` when a managed work item exists and
+inspect Allye `work_children`, Review memories, and Implementation memories
+before declaring completion. Normal completion, timeout, error, and abort are
+distinguished.
 Manual `herdr agent wait` commands started outside this Pi session (for example
 with `nohup` or Bash) do not wake Pi and do not generate this notification.
 
 A real Herdr dispatch still requires `HERDR_ENV=1`, a compatible Herdr session,
-an existing isolated worktree, explicit orchestrator mode, and an orchestration
-run/work-item claim. Pi records workspace/tab/pane/agent ownership in memory for
-future safe teardown; it never adopts foreign panes, stops Herdr, closes panes,
-merges, pushes, or publishes. The lock is local to the Pi checkout/agent
-configuration and is **not** a distributed Allye lock: Hermes and Pi must still
-coordinate the run externally when operating on different machines/process
-homes. A stale lock can be manually investigated using its PID, lease, and owner
-token; automatic recovery is intentionally opt-in.
+and an existing isolated worktree. Pi records workspace/tab/pane/agent ownership
+for safe teardown; it never adopts foreign panes, stops Herdr, closes panes,
+merges, pushes, or publishes without explicit authorization.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "allye-pi",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "Pi package adapter for the canonical Allye workflow",
   "type": "module",
   "keywords": [

package/packages/allye-pi/src/index.ts

@@ -1,10 +1,8 @@
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 import { dirname, resolve } from "node:path";
-import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { homedir } from "node:os";
-import { randomUUID } from "node:crypto";
 import { Type } from "typebox";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
@@ -14,7 +12,13 @@ const MAX_CONTEXT_CHARS = 12_000;
 const RUNTIME_TIMEOUT_MS = 30_000;
 const AGENT_NAME = /^[a-z][a-z0-9_-]{0,31}$/;
 
-type PiMode = "orchestrator" | "executor";
+export type AllyeCapabilities = {
+  piSession: true;
+  allyeMcp: boolean;
+  filesystem: true;
+  subagents: boolean;
+  herdr: boolean;
+};
 type McpResult = { content?: Array<{ type?: string; text?: string }> };
 type StartupContext = {
   text: string;
@@ -57,32 +61,18 @@ export type WaitEventDeliveryResult = {
   sent: boolean;
   errors: string[];
 };
-export type OrchestrationMode = "pi" | "hermes";
-export type OrchestrationClaim = {
-  runId: string;
-  workItemKey: string;
-  master: OrchestrationMode;
-  pid: number;
-  sessionId?: string;
-  ownerToken: string;
-  claimedAt: string;
-  leaseExpiresAt: string;
-};
 export type OwnedPane = {
   workspaceId: string;
   tabId: string;
   paneId: string;
   agentName?: string;
 };
-export type OwnershipState = {
-  claim?: OrchestrationClaim;
+export type DelegationState = {
   panes: OwnedPane[];
   waits: Set<string>;
 };
-const RUNTIME_TOOL_NAME = "allye_runtime";
-const DEFAULT_LOCK_DIR = ".allye/pi-orchestration-locks";
-const DEFAULT_LEASE_MS = 30 * 60 * 1000;
 const WAIT_EVENT_TYPE = "allye-herdr-wait";
+const RUNTIME_TOOL_NAME = "allye_herdr";
 
 function resultText(result: unknown): string {
   const content = (result as McpResult | null)?.content;
@@ -97,15 +87,32 @@ function limitText(text: string, maxChars: number): string {
   return text.length <= maxChars ? text : `${text.slice(0, maxChars)}\n[context truncated]`;
 }
 
-function initialMode(): PiMode {
-  if (resolveOrchestrationMode(process.env) === "hermes") return "executor";
-  const explicit = process.env.ALLYE_PI_MODE?.toLowerCase();
-  if (explicit === "orchestrator"
-    && resolveOrchestrationMode(process.env) === "pi"
-    && process.env.ALLYE_ORCHESTRATION_RUN_ID
-    && process.env.ALLYE_WORK_ITEM_KEY) return explicit;
-  if (explicit === "executor") return explicit;
-  return "executor";
+export function describeCapabilities(env: NodeJS.ProcessEnv = process.env): AllyeCapabilities {
+  return {
+    piSession: true,
+    allyeMcp: env.ALLYE_PI_MCP !== "0",
+    filesystem: true,
+    subagents: env.ALLYE_PI_SUBAGENTS === "1",
+    herdr: env.HERDR_ENV === "1",
+  };
+}
+
+export function adaptiveInstructions(capabilities: AllyeCapabilities): string {
+  const available = [
+    capabilities.allyeMcp ? "Allye/MCP" : "no Allye/MCP",
+    capabilities.filesystem ? "filesystem" : "no filesystem",
+    capabilities.subagents ? "subagents" : "no subagents",
+    capabilities.herdr ? "Herdr" : "no Herdr",
+  ].join(", ");
+  return `Allye is an adaptive toolkit, not a mandatory workflow. Available capabilities: ${available}. Use each only when it helps; continue locally when an optional capability is absent. Recommend tasks when they add traceability, delegation, review, or coordination value; if the user explicitly approves working without a task, proceed and verify proportionally. Ask for consent before consequential mutations and keep Allye as the source of truth.`;
+}
+
+export function loadUsingAllyeSkill(): string {
+  try {
+    return readFileSync(resolve(canonicalSkillsPath(), "using-allye", "SKILL.md"), "utf8");
+  } catch {
+    return "";
+  }
 }
 
 function canonicalSkillsPath(): string {
@@ -189,8 +196,8 @@ export function formatWaitEvent(event: WaitEvent): string {
   const output = event.stdout?.trim() || "(no stdout)";
   const error = event.error || event.stderr?.trim() || "(none)";
   return `Herdr wait settled for agent ${event.name}. Outcome: ${event.outcome}. `
-    + `This is runtime evidence only, not a completion verdict. `
-    + `Use allye_runtime collect now: read work_children for the story and search Allye memories for Review and Implementation evidence before declaring completion.\n\n`
+    + `This is delegation evidence only, not a completion verdict. `
+    + `Use allye_herdr collect when a managed work item exists: read work_children for the story and search Allye memories for Review and Implementation evidence before declaring completion.\n\n`
     + `timeout_ms=${event.timeoutMs} code=${event.code ?? "n/a"} killed=${event.killed ?? false} timestamp=${event.timestamp}\n`
     + `stdout:\n${output}\nerror/stderr:\n${error}`;
 }
@@ -255,159 +262,10 @@ export function invalidStartupContext(message: string): StartupContext {
   };
 }
 
-export function resolveOrchestrationMode(env: NodeJS.ProcessEnv): OrchestrationMode {
-  if (env.ALLYE_ORCHESTRATOR?.toLowerCase() === "hermes") return "hermes";
-  return "pi";
-}
-
-export function orchestrationLockPath(cwd: string, runId: string): string {
-  const safeRunId = runId.replace(/[^a-zA-Z0-9._-]/g, "_");
-  return resolve(cwd, DEFAULT_LOCK_DIR, `${safeRunId}.json`);
-}
-
-export function canUseOwnedPane(state: OwnershipState, paneId: string): boolean {
+export function canUseOwnedPane(state: DelegationState, paneId: string): boolean {
   return state.panes.some((pane) => pane.paneId === paneId);
 }
 
-export function claimConflict(existing: OrchestrationClaim | undefined, requested: OrchestrationClaim): string | null {
-  if (!existing) return null;
-  if (existing.runId === requested.runId
-    && existing.workItemKey === requested.workItemKey
-    && existing.master === requested.master
-    && existing.pid === requested.pid
-    && existing.ownerToken === requested.ownerToken) return null;
-  return `orchestration ownership conflict: ${existing.master}/${existing.runId}/${existing.workItemKey} owns this lock`;
-}
-
-function lockRoot(): string {
-  return process.env.ALLYE_PI_LOCK_DIR
-    ?? process.env.PI_CODING_AGENT_DIR
-    ?? resolve(homedir(), ".pi", "agent");
-}
-
-function processState(pid: number): "alive" | "dead" | "unknown" {
-  try {
-    process.kill(pid, 0);
-    return "alive";
-  } catch (error) {
-    const code = (error as NodeJS.ErrnoException).code;
-    if (code === "ESRCH") return "dead";
-    return "unknown";
-  }
-}
-
-function claimFromEnvironment(sessionId?: string): OrchestrationClaim {
-  const runId = process.env.ALLYE_ORCHESTRATION_RUN_ID?.trim();
-  const workItemKey = process.env.ALLYE_WORK_ITEM_KEY?.trim();
-  if (!runId || !workItemKey) {
-    throw new Error("Pi orchestrator requires ALLYE_ORCHESTRATION_RUN_ID and ALLYE_WORK_ITEM_KEY");
-  }
-  if (resolveOrchestrationMode(process.env) === "hermes") {
-    throw new Error("Hermes owns orchestration for this process; Pi remains executor");
-  }
-  const claimedAt = new Date();
-  return {
-    runId,
-    workItemKey,
-    master: "pi",
-    pid: process.pid,
-    ...(sessionId ? { sessionId } : {}),
-    ownerToken: randomUUID(),
-    claimedAt: claimedAt.toISOString(),
-    leaseExpiresAt: new Date(claimedAt.getTime() + DEFAULT_LEASE_MS).toISOString(),
-  };
-}
-
-function readClaim(path: string): OrchestrationClaim {
-  try {
-    const claim = JSON.parse(readFileSync(path, "utf8")) as Partial<OrchestrationClaim>;
-    if (typeof claim.runId !== "string" || typeof claim.workItemKey !== "string"
-      || (claim.master !== "pi" && claim.master !== "hermes")
-      || typeof claim.pid !== "number" || typeof claim.ownerToken !== "string"
-      || typeof claim.leaseExpiresAt !== "string") {
-      throw new Error("missing required owner, PID, or lease fields");
-    }
-    return claim as OrchestrationClaim;
-  } catch (error) {
-    throw new Error(`orchestration lock ${path} is unreadable or invalid (${error instanceof Error ? error.message : String(error)}); refusing to take ownership`);
-  }
-}
-
-export function acquireLocalClaim(_cwd: string, requested: OrchestrationClaim): void {
-  const path = orchestrationLockPath(lockRoot(), requested.workItemKey);
-  mkdirSync(resolve(path, ".."), { recursive: true });
-  try {
-    writeFileSync(path, JSON.stringify(requested, null, 2), { encoding: "utf8", mode: 0o600, flag: "wx" });
-    return;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-  }
-
-  const existing = readClaim(path);
-  const conflict = claimConflict(existing, requested);
-  if (!conflict) return;
-
-  const leaseExpiresAt = Date.parse(existing.leaseExpiresAt);
-  const staleRecoveryEnabled = process.env.ALLYE_PI_RECOVER_STALE_LOCK === "1";
-  const ownerPidState = processState(existing.pid);
-  if (!staleRecoveryEnabled || !Number.isFinite(leaseExpiresAt) || Date.now() <= leaseExpiresAt || ownerPidState !== "dead") {
-    const reason = ownerPidState === "alive"
-      ? "owner process is active"
-      : ownerPidState === "unknown"
-        ? "owner process state is inconclusive"
-        : "stale recovery is disabled, lease is active, or required lease data is invalid";
-    throw new Error(`${conflict}; refusing stale-lock recovery (${reason}). Set ALLYE_PI_RECOVER_STALE_LOCK=1 only after confirming the local PID is gone and the lease expired.`);
-  }
-
-  const recoveryMarker = `${path}.recovering`;
-  try {
-    writeFileSync(recoveryMarker, JSON.stringify({ ownerToken: existing.ownerToken, pid: existing.pid }), { encoding: "utf8", mode: 0o600, flag: "wx" });
-  } catch {
-    throw new Error(`orchestration lock ${path} is already being recovered; refusing concurrent stale-lock recovery`);
-  }
-  try {
-    const current = readClaim(path);
-    if (current.ownerToken !== existing.ownerToken) {
-      throw new Error(`orchestration lock ${path} changed owner during stale recovery; refusing takeover`);
-    }
-    const quarantine = `${path}.stale-${existing.ownerToken}-${randomUUID()}`;
-    renameSync(path, quarantine);
-    try {
-      writeFileSync(path, JSON.stringify(requested, null, 2), { encoding: "utf8", mode: 0o600, flag: "wx" });
-    } catch (writeError) {
-      try { renameSync(quarantine, path); } catch { /* fail closed; quarantine remains for manual recovery */ }
-      throw writeError;
-    }
-    try { unlinkSync(quarantine); } catch { /* retained quarantine is safe for manual audit */ }
-  } finally {
-    try { unlinkSync(recoveryMarker); } catch { /* marker is advisory; stale recovery remains fail-closed */ }
-  }
-}
-
-export function releaseLocalClaim(claim: OrchestrationClaim): boolean {
-  const path = orchestrationLockPath(lockRoot(), claim.workItemKey);
-  if (!existsSync(path)) return false;
-  const existing = readClaim(path);
-  if (claimConflict(existing, claim) !== null) return false;
-  try {
-    unlinkSync(path);
-    return true;
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
-    throw error;
-  }
-}
-
-export function shutdownOwnership(ownership: OwnershipState, waits: Map<string, AbortController>): boolean {
-  for (const controller of waits.values()) controller.abort();
-  waits.clear();
-  ownership.waits.clear();
-  if (!ownership.claim) return false;
-  const released = releaseLocalClaim(ownership.claim);
-  if (released) ownership.claim = undefined;
-  return released;
-}
-
 async function loadStartupContext(): Promise<StartupContext> {
   const sections: string[] = [];
   try {
@@ -454,25 +312,14 @@ async function loadPromptContext(prompt: string): Promise<string> {
   }
 }
 
-function modeInstructions(mode: PiMode): string {
-  if (mode === "orchestrator") {
-    return `## Allye Pi role: orchestrator
-You are the explicitly selected Pi master for this work item.
-- Allye is the source of truth for work items, skills, memories, decisions, and review/delivery state.
-- Follow the canonical Allye workflow and gates; do not invent a second workflow.
-- Do not implement a story yourself when coordinating it. Dispatch exactly one story at a time to an isolated worktree and executor pane.
-- Use the allye_runtime tool only for the Herdr detect/spawn/dispatch/wait/collect contract. The pane cwd stays at the plugin-enabled repository root; absolute worktree paths belong in the briefing.
-- Never close panes you did not create, stop Herdr, merge, push, or publish without explicit user approval.
-- Hermes and Pi are alternative masters. Confirm that Hermes is not coordinating the same work item before taking control.`;
-  }
-  return `## Allye Pi role: executor
-You are the executor for this session (the safe default).
-- Read the canonical Allye skills and the exact story/tasks or handover before changing code.
-- Implement only the assigned story/task scope, with the execution skill's verification and reporting rules.
-- Follow the canonical execution skill's status protocol: the executor may use Allye to advance its assigned tasks to in_progress and review when the corresponding work and verification are actually complete.
-- Do not create or dispatch panes, assume orchestration, or change the assigned scope. Hermes and Pi may both manage status; being allowed to advance assigned task status does not make this session a master.
-- If Hermes is the master, follow Hermes' briefing and return a durable implementation/review trace through Allye; do not take control of the work item.
-- Stop and report when the scope or a locked decision is unclear; do not guess.`;
+function toolkitInstructions(): string {
+  return `## Allye Pi toolkit
+${adaptiveInstructions(describeCapabilities())}
+- Use canonical Allye skills as composable playbooks and choose the smallest useful next step for the user's intent.
+- Discovery and Product Planning may produce research, documents, memories, or proposed work items; do not create work items until the user approves the proposal.
+- Tasks are recommended for meaningful, delegated, multi-step, or review-heavy work, not universally required. If the user approves a no-task path, record the choice when useful and verify the result.
+- Use subagents when available and beneficial. Use Herdr only when available and beneficial; never require either one.
+- Use Allye for durable context, decisions, work items, and verification evidence. Ask before consequential mutations.`;
 }
 
 function sleep(ms: number): Promise<void> {
@@ -552,9 +399,9 @@ async function waitForInteractiveShell(pane: string): Promise<void> {
   throw new Error(`Herdr pane ${pane} did not reach an interactive shell within 30 seconds`);
 }
 
-export function activeToolsForMode(activeTools: string[], mode: PiMode): string[] {
+export function activeToolsForCapabilities(activeTools: string[], capabilities: AllyeCapabilities): string[] {
   const next = new Set(activeTools);
-  if (mode === "orchestrator") next.add(RUNTIME_TOOL_NAME);
+  if (capabilities.herdr) next.add(RUNTIME_TOOL_NAME);
   else next.delete(RUNTIME_TOOL_NAME);
   return [...next];
 }
@@ -564,10 +411,8 @@ export function dispatchStateIsAcceptable(stateText: string): boolean {
   return /working|idle|done/i.test(stateText);
 }
 
-function requireOrchestrator(mode: PiMode): void {
-  if (mode !== "orchestrator") {
-    throw new Error("Herdr orchestration is disabled in executor mode. Set ALLYE_PI_MODE=orchestrator explicitly for the Pi master.");
-  }
+function requireHerdr(capabilities: AllyeCapabilities): void {
+  if (!capabilities.herdr) throw new Error("Herdr is not available in this Pi session; use another available capability or continue locally.");
 }
 
 function requireAbsolutePath(value: unknown, name: string): string {
@@ -577,9 +422,7 @@ function requireAbsolutePath(value: unknown, name: string): string {
   return value;
 }
 
-async function runtimeOperation(mode: PiMode, params: Record<string, unknown>, registerWait: WaitRegistrar, cancelWait: WaitCanceller, ownership: OwnershipState): Promise<unknown> {
-  requireOrchestrator(mode);
-  if (!ownership.claim) throw new Error("Pi orchestrator has no explicit orchestration claim; provide ALLYE_ORCHESTRATION_RUN_ID and ALLYE_WORK_ITEM_KEY");
+async function runtimeOperation(capabilities: AllyeCapabilities, params: Record<string, unknown>, registerWait: WaitRegistrar, cancelWait: WaitCanceller, ownership: DelegationState): Promise<unknown> {
   const operation = params.operation;
   if (operation === "detect") {
     if (process.env.HERDR_ENV !== "1") return { available: false, reason: "HERDR_ENV is not 1" };
@@ -591,9 +434,7 @@ async function runtimeOperation(mode: PiMode, params: Record<string, unknown>, r
     }
   }
 
-  if (process.env.HERDR_ENV !== "1") {
-    throw new Error("Herdr runtime is not active in this Pi session (HERDR_ENV=1 is required).");
-  }
+  requireHerdr(capabilities);
 
   if (operation === "spawn") {
     const cwd = requireAbsolutePath(params.cwd, "cwd");
@@ -610,7 +451,10 @@ async function runtimeOperation(mode: PiMode, params: Record<string, unknown>, r
     const newPane = collectValues(afterLayout, "pane_id").find((id) => !beforePanes.has(id));
     if (!newPane) throw new Error("Herdr split completed but no new pane id was returned");
     const paneRecords = collectPaneRecords(afterLayout);
-    const record = paneRecords.find((candidate) => candidate.paneId === newPane && candidate.workspaceId === String((afterLayout as Record<string, unknown>).workspace_id ?? candidate.workspaceId) && candidate.tabId === String((afterLayout as Record<string, unknown>).tab_id ?? candidate.tabId));
+    const layoutMetadata = afterLayout as Record<string, unknown>;
+    const record = paneRecords.find((candidate) => candidate.paneId === newPane
+      && candidate.workspaceId === String(layoutMetadata.workspace_id ?? candidate.workspaceId)
+      && candidate.tabId === String(layoutMetadata.tab_id ?? candidate.tabId));
     if (!record) throw new Error("Herdr returned a pane without workspace/tab ownership metadata");
     ownership.panes.push(record);
     await waitForInteractiveShell(newPane);
@@ -690,11 +534,11 @@ async function runtimeOperation(mode: PiMode, params: Record<string, unknown>, r
   throw new Error(`Unknown runtime operation: ${String(operation)}`);
 }
 
-function registerRuntimeTool(pi: ExtensionAPI, getMode: () => PiMode, registerWait: WaitRegistrar, cancelWait: WaitCanceller, state: OwnershipState): void {
+function registerRuntimeTool(pi: ExtensionAPI, getCapabilities: () => AllyeCapabilities, registerWait: WaitRegistrar, cancelWait: WaitCanceller, state: DelegationState): void {
   pi.registerTool({
-    name: "allye_runtime",
+    name: RUNTIME_TOOL_NAME,
     label: "Allye Runtime",
-    description: "Drive Herdr from Pi orchestrator mode using detect, spawn, dispatch, wait, and Allye-backed collect.",
+    description: "Use optional Herdr capabilities for delegation, waiting, and collecting results when available.",
     parameters: Type.Object({
       operation: Type.String({ description: "detect | spawn | dispatch | wait | collect" }),
       cwd: Type.Optional(Type.String({ description: "Absolute plugin-enabled repository root for spawn" })),
@@ -711,7 +555,7 @@ function registerRuntimeTool(pi: ExtensionAPI, getMode: () => PiMode, registerWa
     }),
     async execute(_toolCallId, params) {
       try {
-        const result = await runtimeOperation(getMode(), params as Record<string, unknown>, registerWait, cancelWait, state);
+        const result = await runtimeOperation(getCapabilities(), params as Record<string, unknown>, registerWait, cancelWait, state);
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }], details: result };
       } catch (error) {
         const message = error instanceof Error ? error.message : String(error);
@@ -722,14 +566,15 @@ function registerRuntimeTool(pi: ExtensionAPI, getMode: () => PiMode, registerWa
 }
 
 export default function allyePiAdapter(pi: ExtensionAPI): void {
-  let mode = initialMode();
+  const capabilities = describeCapabilities();
   let startupContext: StartupContext = { text: "", teamSelectionRequired: false, allyeUnavailable: true, teams: [] };
   let firstPrompt = true;
+  let usingAllyeBootstrap = "";
   let shuttingDown = false;
   let activeContext: ExtensionContext | undefined;
   const waits = new Map<string, AbortController>();
   const settledWaits = new Set<string>();
-  const ownership: OwnershipState = { panes: [], waits: new Set() };
+  const ownership: DelegationState = { panes: [], waits: new Set() };
 
   const registerWait: WaitRegistrar = (name, timeoutMs) => {
     if (settledWaits.has(name)) return { registered: false, name, timeoutMs, duplicate: true, settled: true };
@@ -785,8 +630,8 @@ export default function allyePiAdapter(pi: ExtensionAPI): void {
     waits.delete(name);
   };
 
-  const syncModeTools = () => {
-    pi.setActiveTools(activeToolsForMode(pi.getActiveTools(), mode));
+  const syncCapabilityTools = () => {
+    pi.setActiveTools(activeToolsForCapabilities(pi.getActiveTools(), capabilities));
   };
 
   pi.registerMessageRenderer(WAIT_EVENT_TYPE, () => undefined);
@@ -796,49 +641,34 @@ export default function allyePiAdapter(pi: ExtensionAPI): void {
   pi.on("session_start", async (_event, ctx) => {
     shuttingDown = false;
     activeContext = ctx;
-    mode = initialMode();
     firstPrompt = true;
-    syncModeTools();
-    if (ctx.hasUI) ctx.ui.setStatus("allye-pi", `loading Allye context (${mode})…`);
+    usingAllyeBootstrap = loadUsingAllyeSkill();
+    syncCapabilityTools();
+    if (ctx.hasUI) ctx.ui.setStatus("allye-pi", "loading Allye context…");
     if (process.env.ALLYE_PI_NATIVE_BOOTSTRAP !== "0") startupContext = await loadStartupContext();
-    if (mode === "orchestrator") {
-      try {
-        const claim = claimFromEnvironment(ctx.sessionManager.getSessionId());
-        acquireLocalClaim(ctx.cwd, claim);
-        ownership.claim = claim;
-      } catch (error) {
-        mode = "executor";
-        syncModeTools();
-        startupContext = {
-          ...startupContext,
-          text: `${startupContext.text}\n## Pi orchestration blocked\n${error instanceof Error ? error.message : String(error)}\nPi remains executor; status management for assigned tasks remains allowed.`,
-        };
-        if (ctx.hasUI) ctx.ui.notify("Pi orchestration blocked; no compatible ownership claim was acquired. Executor mode remains active.", "warning");
-      }
-    }
     if (startupContext.teamSelectionRequired && ctx.hasUI) {
       ctx.ui.notify("Allye has multiple teams and no active team. Use /allye-team <name|prefix|id> before team-scoped work.", "warning");
     }
-    if (ctx.hasUI) ctx.ui.setStatus("allye-pi", `Allye ${mode} ready`);
+    if (ctx.hasUI) ctx.ui.setStatus("allye-pi", "Allye ready");
   });
 
   pi.on("session_shutdown", () => {
     shuttingDown = true;
     activeContext = undefined;
-    try {
-      shutdownOwnership(ownership, waits);
-    } catch (error) {
-      console.error(`Allye Pi: could not release orchestration lock safely: ${error instanceof Error ? error.message : String(error)}`);
-    }
+    for (const controller of waits.values()) controller.abort();
+    waits.clear();
+    ownership.waits.clear();
+    ownership.panes.length = 0;
   });
 
   pi.on("before_agent_start", async (event) => {
     const sections = [
-      `<allye-pi-adapter>\n${modeInstructions(mode)}\n\nCanonical Allye skills are loaded from ${canonicalSkillsPath()} — do not create copies.\n${startupContext.teamSelectionRequired ? "\n" + startupContext.text : ""}\n</allye-pi-adapter>`,
+      `<allye-pi-adapter>\n${toolkitInstructions()}\n\nCanonical Allye skills are loaded from ${canonicalSkillsPath()} — do not create copies.\n${startupContext.teamSelectionRequired ? "\n" + startupContext.text : ""}\n</allye-pi-adapter>`,
     ];
-    if (firstPrompt && process.env.ALLYE_PI_NATIVE_BOOTSTRAP !== "0") {
+    if (firstPrompt) {
       firstPrompt = false;
-      if (startupContext.text) sections.push(`<allye-pi-startup-context>\n${startupContext.text}\n</allye-pi-startup-context>`);
+      if (usingAllyeBootstrap) sections.push(`<allye-using-allye-bootstrap>\n${usingAllyeBootstrap}\n</allye-using-allye-bootstrap>`);
+      if (process.env.ALLYE_PI_NATIVE_BOOTSTRAP !== "0" && startupContext.text) sections.push(`<allye-pi-startup-context>\n${startupContext.text}\n</allye-pi-startup-context>`);
       if (!startupContext.teamSelectionRequired && !startupContext.allyeUnavailable) {
         const relevant = await loadPromptContext(event.prompt);
         if (relevant) sections.push(`<allye-pi-relevant-memory>\n${relevant}\n</allye-pi-relevant-memory>`);
@@ -847,45 +677,16 @@ export default function allyePiAdapter(pi: ExtensionAPI): void {
     return { systemPrompt: `${event.systemPrompt}\n\n${sections.join("\n\n")}` };
   });
 
-  pi.registerCommand("allye-mode", {
-    description: "Select executor or orchestrator mode for this Pi session",
-    getArgumentCompletions: (prefix) => ["executor", "orchestrator"]
-      .filter((value) => value.startsWith(prefix.trim()))
-      .map((value) => ({ value, label: value })),
-    handler: async (args, ctx) => {
-      const selected = args?.trim().toLowerCase();
-      if (selected !== "executor" && selected !== "orchestrator") {
-        ctx.ui.notify("Usage: /allye-mode executor|orchestrator", "error");
-        return;
-      }
-      if (selected === "orchestrator" && resolveOrchestrationMode(process.env) === "hermes") {
-        ctx.ui.notify("Hermes owns orchestration for this process; Pi remains executor.", "warning");
-        return;
-      }
-      if (selected === mode) {
-        ctx.ui.notify(`Allye mode is already ${mode} for this session`, "info");
-        return;
-      }
-      if (selected === "executor") {
-        // Downgrading must release the orchestration claim and abort waits so
-        // this session cannot keep coordinating after becoming an executor.
-        shutdownOwnership(ownership, waits);
-        ownership.panes.length = 0;
-      }
-      if (selected === "orchestrator" && !ownership.claim) {
-        try {
-          const claim = claimFromEnvironment(ctx.sessionManager.getSessionId());
-          acquireLocalClaim(ctx.cwd, claim);
-          ownership.claim = claim;
-        } catch (error) {
-          ctx.ui.notify(`Pi orchestration blocked: ${error instanceof Error ? error.message : String(error)}`, "error");
-          return;
-        }
-      }
-      mode = selected;
-      syncModeTools();
-      ctx.ui.setStatus("allye-pi", `Allye ${mode}`);
-      ctx.ui.notify(`Allye mode set to ${mode} for this session`, "info");
+  pi.registerCommand("allye-capabilities", {
+    description: "Show capabilities available to the Allye toolkit in this Pi session",
+    handler: async (_args, ctx) => {
+      const available = [
+        `Allye/MCP: ${capabilities.allyeMcp ? "available" : "unavailable"}`,
+        "filesystem: available",
+        `subagents: ${capabilities.subagents ? "available" : "unavailable"}`,
+        `Herdr: ${capabilities.herdr ? "available" : "unavailable"}`,
+      ].join("; ");
+      ctx.ui.notify(`${available}. Tasks are recommended, not mandatory.`, "info");
     },
   });
 
@@ -907,5 +708,5 @@ export default function allyePiAdapter(pi: ExtensionAPI): void {
     },
   });
 
-  registerRuntimeTool(pi, () => mode, registerWait, cancelWait, ownership);
+  registerRuntimeTool(pi, () => capabilities, registerWait, cancelWait, ownership);
 }

package/skills/agent-runtime/SKILL.md

@@ -11,8 +11,7 @@ An **agent runtime** owns real agent processes the human can watch, attach to, a
 over. This skill defines what the plugin needs from one, so the Orchestrator can drive
 any runtime that satisfies the contract rather than one specific tool.
 
-Load this only when the session hook reported a runtime. Without one, dispatch falls back
-to the manual handover and the dispatched-subagent modes, both of which work unchanged.
+Load this only when a compatible runtime is actually detected and the user benefits from delegation. Without one, continue locally or use another available subagent mechanism; never let the absence or degradation of a runtime block delivery.
 
 Concrete commands for the runtimes we implement live in `references/`. This file is the
 contract; the reference is the implementation.
@@ -105,19 +104,19 @@ through.
 
 ## The obligation on the dispatched side
 
-The contract closes only because the dispatched agent carries the other half:
+When a managed work item exists, the dispatched agent should leave a durable trace in
+Allye before settling: task statuses and an implementation/review memory as applicable.
+For an explicitly approved no-task path, return a durable result through the host session
+or another agreed channel and do not invent work items merely to satisfy this contract.
 
-> **Before settling, leave a durable trace in Allye.** Executor: task statuses advanced,
-> plus an implementation memory. Reviewer: a memory holding the findings.
-
-This is already what `execution` and `review` do. Here it becomes load-bearing rather than
-good practice — it is the entire result channel.
+This keeps Allye authoritative when it is in scope while allowing local, low-risk work
+to complete without a mandatory work-item workflow.
 
 ## Teardown
 
-Destroy only what you created, and only after the work it held is merged and verified.
-Never close a pane, tab, workspace, or session the plugin did not create. Never stop the
-runtime's server.
+Destroy only what you created, and only after the work it held is merged and verified or
+the user explicitly authorizes cleanup. Never close a pane, tab, workspace, or session the
+plugin did not create. Never stop the runtime's server.
 
 ## Implementations
 

package/skills/execution/SKILL.md

@@ -7,8 +7,8 @@ category: methodology
 
 # Technical Development Workflow
 
-Implements one task with discipline: read the existing code first, drive it with TDD,
-verify it actually works, and track progress in Allye.
+Implements a scoped change with discipline: read the existing code first, drive it with TDD when applicable,
+verify it actually works, and use Allye task tracking when a task exists or the user approves creating one. A small or explicitly approved no-task change still follows the same read, test, and verification discipline.
 
 **Scope, if you arrived via a `story-execution` or `correction` handover (see `handover-protocol`):** read only the one story and its tasks named in the handover — nothing else. A `correction` handover carries only the failed findings, not the whole story again; fix exactly what it lists.
 
@@ -24,6 +24,8 @@ Get task → Search context → Move to in_progress → Read code → TDD (Red
 
 ## Step 1: Get the Task and Context
 
+If a task or handover exists, fetch it and treat its acceptance criteria and locked decisions as authoritative. If no task exists, confirm that the user approved the no-task path, define the scope and verification command locally, and continue without inventing a work item.
+
 Fetch the task you're about to implement:
 
 ```
@@ -74,6 +76,8 @@ If there are multiple independent tasks (same wave), they can be done in any ord
 
 ## Step 3: Move Task to In Progress
 
+If a task exists, signal that work has started. If no task exists, record the local scope in the implementation plan and do not make a status call.
+
 Signal that work has started:
 
 ```
@@ -301,6 +305,8 @@ Examples of things that need human action:
 
 ## Step 7: Move Task to Review
 
+For a tracked task, advance it to review only after the verification evidence is green. For an approved no-task change, report the same evidence directly and do not create or advance a status.
+
 <!-- adapted from superpowers:verification-before-completion (MIT) — evidence before assertions -->
 **Evidence before assertions.** Don't advance a task because it looks right — run the tests, read the actual output, and confirm each acceptance criterion against that output before proceeding. "Should work" is not the same as "ran and passed."
 
@@ -308,13 +314,13 @@ The task's verification command is what supplies that evidence. Advancing a task
 `review` without having run it green — or without having recorded a `verification:
 manual` observation — is the assertion this rule exists to forbid.
 
-Once all acceptance criteria are verifiably met and tests pass:
+Once all acceptance criteria are verifiably met and tests pass for a tracked task:
 
 ```
 work_status_next(id: "{task uuid}")
 ```
 
-This advances the task forward to the "review" status. **Do NOT call `work_status_done` here** — passing its own tests makes a task ready for review, not done. "Done" only happens after the Reviewer returns ✅, and that final move (`review` → `done`) is the Orchestrator's, not yours (see the `orchestrator` skill §7).
+This advances the task forward to the "review" status. **Do NOT call `work_status_done` here** — passing its own tests makes a task ready for review, not done. For a no-task change, completion means the agreed scope and verification are reported; no status transition is implied.
 
 ---
 

package/skills/handover-protocol/SKILL.md

@@ -7,7 +7,7 @@ category: methodology
 
 # Handover Protocol
 
-A handover is how context moves between Allye workflow phases without carrying a chat's full history forward. Each phase runs in its own fresh, lean-context conversation; when it finishes, it emits a handover — a block of chat text the user reads, approves, and pastes as the first message of the next chat. The next chat's bootstrap detects the marker and loads the right skill automatically.
+A handover is one optional way context moves between Allye playbooks without carrying a chat's full history forward. Use it for meaningful, multi-step, delegated, or cross-session work where a durable briefing adds value. For short local work, stay in the current session rather than manufacturing phase boundaries. When a handover is used, the user reads, approves, and pastes the block as the first message of the next chat; the bootstrap detects the marker and loads the right skill automatically.
 
 **A handover is never saved as a memory or a file.** The Allye doc and work items it references are the durable record — the handover text itself is a disposable transport vehicle, copied by hand in both directions (including Orchestrator ↔ Executor's correction loop).
 
@@ -50,17 +50,17 @@ Six types. Each is a distinct handoff with its own objective and field set — n
 **Executor is reachable both ways.** In manual mode it receives `story-execution`/`correction` handovers as documented above. In automatic mode (Orchestrator's choice, offered per story) it's dispatched via the `Agent` tool instead, the same way the reviewer axes are — see `agents/executor.md`. Either way the content is the same; only the transport differs.
 <!-- opencode-exclude:end -->
 
-## 3. Writing a good handover (mandatory checklist)
+## 3. Writing a good handover checklist
 
 <!-- adapted from humanlayer/humanlayer create_handoff (Apache-2.0) and EveryInc/compound-engineering-plugin artifact_readiness contracts (MIT) -->
 
-Before emitting any handover, confirm:
+Before emitting a handover, confirm the following when applicable:
 
 - **Concrete keys, not vague pointers.** "The story we discussed" is not acceptable — write the actual `STORY-KEY`. The receiving chat has zero memory of this conversation.
 - **References carry an explicit read instruction, not just keys.** The handover must tell the receiver to actually fetch and read what it lists — work items via `work_get`/`work_children` (the entire subtree under the parent, when the handover is scoped to a parent item like a feature or epic), docs via `doc_get`. A key list without a "read all of this" instruction invites skimming, and the receiving chat has no other way to know reading is mandatory.
 - **Locked decisions are carried forward, verbatim.** If a decision was locked in this phase, restate it in the handover — don't make the next chat re-derive or, worse, re-litigate it.
 - **Scope matches the type.** `story-execution` carries exactly one story; `correction` carries only the failed findings, not the whole story again. Padding a handover with everything "just in case" defeats the purpose of a lean next chat.
-- **The reminder line is never dropped.** Every handover ends with the "stop and ask" line — it's the single most important sentence in this whole protocol.
+- **The reminder line is preserved.** A handover should end with the "stop and ask" line — it prevents guessed decisions in the next session.
 <!-- adapted from mattpocock/skills triage AGENT-BRIEF (MIT) — durability of handoff artifacts -->
 - **Name interfaces and contracts, not file paths and line numbers.** Write "the `SkillConfig`
   type gains an optional `schedule` field", never "open `src/types/skill.ts` and edit line 42."

package/skills/memory-protocol/SKILL.md

@@ -48,17 +48,15 @@ Every `memory_save` passes through conflict resolution: Allye checks for similar
 
 ## 2. When to search
 
-### Conversation start (mandatory)
+### Conversation start (proportional)
 
-<EXTREMELY_IMPORTANT>
-At the start of EVERY conversation, run at least these searches before doing anything else:
+For consequential, multi-step, resumed, or team-scoped work, search before acting:
 
 1. `memory_search(query: "Session State")` — find where the user left off
 2. `memory_search(query: "{topic of user's request}")` — find relevant context
 3. `memory_search(query: "{work item key}")` — if a specific item is mentioned (e.g., "PROJ-123")
-</EXTREMELY_IMPORTANT>
 
-React to what you find: session state → summarize it for the user ("Last time we were working on X, you completed Y, and the next step was Z"); decisions → keep them in mind and respect locked ones; nothing → proceed, noting this is a fresh context.
+For a short, low-risk, local request, the search may be skipped. Never claim a search was performed when the Allye memory capability is unavailable. React to what you find: session state → summarize it; decisions → respect locked ones; nothing → proceed with the available context.
 
 ### Before decisions and implementation
 
@@ -97,15 +95,13 @@ Save decisions and blockers immediately — not batched at session end. **Locked
 
 ### Session state — handled by the /save protocol
 
-<EXTREMELY_IMPORTANT>
-Before the conversation ends (or whenever /save is invoked), run the full /save protocol in §4. Session state is not a single ad hoc save — it's the first of four coordinated steps that also promote durable knowledge from the session into team sectors.
-</EXTREMELY_IMPORTANT>
+When the session is consequential, resumed, or contains durable decisions, use the full /save protocol in §4 before ending. For short, low-risk, local work, saving may be skipped. If Allye persistence is unavailable, report that continuity was not saved rather than implying it was.
 
 ---
 
 ## 4. The /save protocol
 
-`/save` is a 4-step protocol that turns a session's raw activity into (a) a personal continuity snapshot and (b) correctly-scoped, durable team knowledge. Run all four steps, in order, every time /save is invoked or a conversation is about to end.
+`/save` is a 4-step protocol that turns a session's raw activity into (a) a personal continuity snapshot and (b) correctly-scoped, durable team knowledge. Run all four steps, in order, whenever the user explicitly invokes `/save` or when a consequential session is being closed. Do not force it for trivial local work.
 
 ### Step 1 — Consolidate the session (sector: `sessions`, personal)
 
@@ -276,7 +272,7 @@ The relocation flow surfaces that backlog and offers to promote it — **once pe
 
 ### When to offer it
 
-Offer at most once per user, ever — not once per session. A good moment is early in a session, right after the mandatory memory searches (§2), at a natural pause before the actual task. Never interrupt an in-progress task to offer this; if the user is mid-implementation or mid-debugging, wait for a natural break or skip it for that session — it isn't urgent, and it'll still be there next time unless already offered.
+Offer at most once per user, ever — not once per session. A good moment is early in a consequential session, after any relevant memory searches (§2), at a natural pause before the actual task. Never interrupt an in-progress task to offer this; if the user is mid-implementation or mid-debugging, wait for a natural break or skip it for that session. If the relocation capability is unavailable, do not present the flow.
 
 ### Check the guard first
 

package/skills/orchestrator/SKILL.md

@@ -7,10 +7,12 @@ category: methodology
 
 # Orchestrator
 
-You drive delivery. You don't plan — that already happened in Technical Planning — and you don't implement — that's Executor's job, one fresh chat at a time. You coordinate: who owns what, what's in progress, whether a story is genuinely done, and when to bring in review.
+You coordinate delivery when the user chooses a durable, multi-step work-item workflow. You don't have to be invoked for every change, and you don't plan or implement when coordinating — Technical Planning and Executor playbooks remain available as needed. You coordinate: who owns what, what's in progress, whether a story is genuinely done, and when to bring in review. If the user chooses a local no-task path, stop coordinating rather than creating work items to justify this skill.
 
 ## 1. On start
 
+If no approved work item or handover exists, do not invent one. Explain the available lightweight local path or ask whether the user wants to opt into tracked delivery.
+
 If you arrived via a `technical-to-orchestration` handover (see `handover-protocol`), read it in full — it's your only context, there is no prior conversation to fall back on.
 
 Then load the actual work. **The handover's list is an index to verify against, not a substitute for reading:**

package/skills/product-planning/SKILL.md

@@ -16,9 +16,11 @@ Use this when the user talks about: requirements, business needs, product scope,
 ## Workflow Overview
 
 ```
-Understand context → Search memories → Define hierarchy → Create items → Save decisions
+Understand intent → Search context when useful → Propose hierarchy when traceability helps → Get approval → Create items → Save decisions
 ```
 
+Product Planning is recommended for durable product scope, not a mandatory prerequisite for every local implementation. Never create items without explicit approval.
+
 ---
 
 ## Step 0: Check for a Discovery Doc
@@ -29,7 +31,7 @@ If you arrived via a `discovery-to-planning` handover (see the `handover-protoco
 
 ## Step 1: Understand the Business Context
 
-Before creating anything, have a conversation with the user to understand:
+Before proposing or creating anything, have a conversation with the user to understand:
 
 1. **What problem are we solving?** — The business need or opportunity
 2. **Who is it for?** — Target users or stakeholders
@@ -114,7 +116,7 @@ Epic: User Authentication System
     └── Story: User can log out from all devices
 ```
 
-Wait for the user to approve, modify, or add to this structure before proceeding.
+Wait for the user to approve, modify, or add to this structure before proceeding. If the user explicitly chooses a no-work-item path for a small or local change, do not create a hierarchy; keep the scope and verification visible instead.
 
 ---
 

package/skills/sandbox/SKILL.md

@@ -11,7 +11,7 @@ This is the entry point for ideas that aren't ready to become work items yet. Us
 
 <!-- adapted from superpowers:brainstorming (MIT) -->
 <HARD-GATE>
-Do not create any Allye work item, and do not treat any direction as decided, until the user has explicitly approved it. This skill's only output is a Discovery Doc and a handover — never an Epic, Feature, or Story. If you catch yourself about to call `work_create`, stop: that's Product Planning's job, one conversation later.
+Do not create any Allye work item, and do not treat any direction as decided, until the user has explicitly approved it. This skill's default output is a Discovery Doc and a handover, but a user may explicitly choose an informal local research note or no persistence when that is sufficient. If you catch yourself about to call `work_create`, stop and ask for approval first.
 </HARD-GATE>
 
 ## 1. The core rule: ask, don't decide
@@ -59,4 +59,4 @@ When a direction is approved — explicitly, by the user, not inferred — synth
 
 ## 4. What this skill is not
 
-This is not Technical Planning — no stack decisions, no architecture, no tasks here. It is not Product Planning — no Epic/Feature/Story structure gets created here (see the HARD-GATE above). If the user arrives already knowing exactly what they want and just needs it turned into work items, route to `product-planning` directly instead — Sandbox isn't the right entry point for that.
+This is not Technical Planning — no stack decisions, no architecture, no tasks here. It is not Product Planning — no Epic/Feature/Story structure gets created here without approval. If the user arrives already knowing exactly what they want and just needs it turned into work items, recommend `product-planning`; if they only need a small local change, the adaptive toolkit may proceed without forcing a planning phase.

package/skills/technical-planning/SKILL.md

@@ -7,7 +7,7 @@ category: methodology
 
 # Technical Planning Workflow
 
-Turns a story into actionable tasks through a **Discussion Phase** — surfacing gray areas, capturing decisions, and writing tasks with verifiable acceptance criteria and a runnable verification command.
+Turns an approved, meaningful story into actionable tasks through a **Discussion Phase** — surfacing gray areas, capturing decisions, and writing tasks with verifiable acceptance criteria and a runnable verification command. It is recommended for durable, multi-step, shared, or review-heavy work, not mandatory for every local change.
 
 **Never assume — always ask.** The user knows the direction they want, sometimes only after researching further. Your job is to surface the gray areas and present real options, not to quietly pick one and present it as the plan.
 
@@ -23,6 +23,8 @@ Get story → Search context → Discussion Phase → Create tasks → Move stor
 
 ## 0. Scope: one feature, story by story
 
+If the user explicitly chooses a no-task path, do not enter this workflow or create tasks. State the local scope, assumptions, and verification plan instead.
+
 The steps below plan **one story at a time** — but the unit Technical Planning hands to the Orchestrator is the **feature**. When the target feature has multiple stories (a `planning-to-technical` handover usually lists several), work through every story under that feature in sequence, one at a time, running the full workflow (Steps 1–6) for each before starting the next.
 
 **Emit only ONE `technical-to-orchestration` handover, at the very end — after the last story in the feature is planned, never after each individual story.** That handover must cover every story and every task, grouped by wave, which is only honest once all of the feature's stories have actually been planned. If the session ends before all stories are planned, save session state (Step 6) and resume in a fresh chat — don't emit a partial feature-level handover.
@@ -73,9 +75,9 @@ If tasks already exist, review them instead of creating new ones. The user may w
 ## Step 3: Discussion Phase
 
 <EXTREMELY_IMPORTANT>
-Complete the discussion phase — surfacing ambiguity before committing to a plan —
-before creating any task. Skipping it leads to rework, wrong assumptions, and
-wasted effort.
+For tracked work, complete the discussion phase — surfacing ambiguity before committing
+to a plan — before creating any task. A user-approved no-task path may skip task creation,
+but must still surface scope-changing ambiguity and define proportional verification.
 </EXTREMELY_IMPORTANT>
 
 ### 3.1 Identify Gray Areas
@@ -90,7 +92,7 @@ Examples of gray areas:
 - Should we optimize for read speed or write speed?
 - How much backward compatibility do we need?
 
-**Mandatory:** whenever a story implies infrastructure, stack, or architecture choices, that is always a gray area to raise explicitly — never left to chance or agent discretion by default.
+Whenever tracked work implies infrastructure, stack, or architecture choices, raise them explicitly as gray areas. For a small no-task change, use established defaults only when the choice is low-risk and reversible; otherwise ask before acting.
 
 **Need more than a hunch to evaluate an option?** Dispatch the `deep-search` agent (web research) or the `code-analyzer` agent (analyze a public repo), both via the `Agent` tool — research is available here, not only in Sandbox. Bring findings back into the discussion before locking a decision.
 

package/skills/using-allye/SKILL.md

@@ -9,9 +9,9 @@ category: bootstrap
 
 You have access to the **Allye platform** — a project management and knowledge system with 12 MCP tools covering work items, documentation, sprints, boards, memories, skills, and more.
 
-This skill teaches you **when and how** to use those tools effectively. It does NOT replace the tools — it gives you methodology and workflow discipline on top of them.
+This skill teaches you **when and how** to use those tools effectively. It does NOT replace the tools — it gives you portable playbooks and proportional guardrails on top of them.
 
-**What you must do:** search memories at the start of every conversation, detect which workflow phase applies, load the matching skill for that phase, and save memories before the conversation ends.
+**Default posture:** Allye is an adaptive toolkit, not a mandatory phase chain. Use Allye MCP, filesystem, subagents, Herdr, work items, and memories when available and useful; degrade honestly when a capability is absent. Recommend traceable tasks for meaningful work, but support an explicitly approved no-task path.
 
 ---
 
@@ -23,51 +23,25 @@ These instructions are written in English, but every response, question, suggest
 
 ## Asking Questions
 
-<!-- adapted from superpowers:brainstorming (MIT) — "prefer multiple choice questions when possible" -->
-<HARD-GATE>
-This applies in every phase — Sandbox exploration, Technical Planning's gray-area discussion, Orchestrator's assignee/status calls, Product Planning's scope forks, anywhere you'd otherwise type a question in prose. Whenever a fork has a small set of nameable options — who owns something, which of two approaches, narrow vs. broad scope, yes/no confirmations — use the `AskUserQuestion` tool instead of typing the question out in prose. It's faster to answer by picking than by typing, and its free-text "Other" option means nothing is lost versus asking in prose.
+When a fork has a small set of nameable options — ownership, approach, scope, or confirmation — prefer the runtime's native structured-question mechanism when one exists. If the runtime has no such tool, ask one focused question in concise prose and make the options explicit. Never silently choose a consequential option.
 
-**Never bundle an open-ended sub-question with an enumerable one in the same message.** If a question has both parts — "what's driving this, and who's the audience?" — split them: ask the open part in prose, and the enumerable part (audience: internal/external/both) via `AskUserQuestion`, as two separate turns. Bundling them is what makes the whole thing read as "open-ended" and skip the tool entirely — don't let the open half smuggle the enumerable half out of a structured question.
+**Never bundle an open-ended sub-question with an enumerable one in the same message.** Split them into separate turns. Reserve plain conversational questions for genuinely open-ended forks where enumerating options would require guessing.
 
-Reserve plain conversational questions for forks that are genuinely open-ended on their own — where enumerating options would just be guessing at what the user might say (e.g. "what's driving this?", "describe the current process").
-</HARD-GATE>
+## 1. Context and Memory Protocol
 
-Note: `AskUserQuestion` inside skill-loaded contexts has known reliability issues in Claude Code itself (tracked upstream, e.g. anthropics/claude-code#29547, #30544) — it can silently return an empty answer or fall back to prose regardless of this instruction. Treat a prose fallback as a degraded but acceptable outcome, not a failure to correct mid-conversation; the underlying discipline (ask before deciding) still holds either way.
-
----
-
-## 1. Memory First Protocol
-
-<EXTREMELY_IMPORTANT>
-At the START of every conversation, you MUST search for relevant memories before doing anything else.
-At the END of every conversation, you MUST run the `memory-protocol` skill's /save process.
-</EXTREMELY_IMPORTANT>
+Use durable Allye context when the Allye MCP capability is available and the work benefits from continuity. Do not pretend a memory was searched or saved when the capability is unavailable.
 
 ### On conversation start
 
-**Step 1: Initialize Allye** — Call `initialize` (action: `init`) to load user context, team info, and core documents. This is mandatory and must happen before anything else.
-
-**Step 2: Check active team** — If the init response shows the user belongs to multiple teams and no team is active, ask the user which team they want to work with and call `team_switch` with the team name. Do not proceed until a team is selected — most tools require a team context.
-
-**Step 3: Search for memories** using `memory_search`:
-
-1. `"Session State"` — find where the user left off last time
-2. `"decision {topic}"` — find previous decisions about the current topic
-3. `"{work item key}"` — find context for the specific item being discussed (e.g., "PROJ-123")
-
-**Step 4: Greet the user** — Summarize what you know (from init + memories) before proceeding. If no memories are found, proceed normally with the context from init.
-
-**Step 5: Note the runtime, if one was reported.** The session hook may have injected a line beginning `Agent runtime: `. If it did, the `agent-runtime` skill is available and the Orchestrator will dispatch through it. Do not load that skill now — it loads when work is about to be dispatched, which is the whole point of it being a separate skill.
+1. Initialize when available. If it fails, state the limitation and continue with local context unless Allye is required.
+2. Resolve team context proportionally: ask before a team-scoped operation when multiple teams have no active selection; non-team-scoped work may continue.
+3. Search relevant memories when useful, especially for consequential, multi-step, or resumed work.
+4. Distinguish confirmed Allye context, local repository context, and assumptions.
+5. Use subagents or Herdr only when detected and beneficial; never make them prerequisites.
 
 ### On conversation end (and saving in general)
 
-Follow the `memory-protocol` skill's current save process — load it if you haven't already, and don't rely on an outdated inline copy of it here. That skill is the single source of truth for:
-
-- The **/save protocol** for session state (a 4-step process: consolidate the session into one `sector: "sessions"` memory, mine it for knowledge worth promoting to team sectors, react to each save's outcome, and promote any session todo that outlives the session)
-- **When to save mid-conversation** (decisions, trade-offs, blockers, non-obvious context — each in its correct sector)
-- **Tag conventions** and sector selection
-
-One rule worth internalizing before you even load it: **always pass `sector` explicitly** — it's optional and defaults to `knowledge`, which is rarely the sector you actually want.
+Follow the `memory-protocol` skill when Allye memory is available and the context is worth preserving. Save decisions, trade-offs, blockers, and durable session state; do not save trivial noise. Always pass `sector` explicitly. If persistence is unavailable, report the unsaved state rather than implying continuity.
 
 ---
 
@@ -94,7 +68,7 @@ If no handover marker is present, fall through to the decision table below as be
 | Define product requirements, create epics/features/stories | Product Planning | `allye-product-planning` |
 | Plan technical tasks for a story, discuss approach | Technical Planning | `allye-technical-planning` |
 | Coordinate delivery of an already-planned feature — assign work, track status, drive tasks through review | Orchestrator | `orchestrator` |
-| Implement code, write tests, develop features | Technical Development | `allye-technical-development` |
+| Implement code, write tests, develop features | Technical Development or a lightweight local implementation loop | `allye-technical-development` when a task/work item exists |
 | Review code, check implementation quality | Technical Review | `allye-technical-review` |
 | Finalize delivery, close story, update docs | Technical Delivery | `allye-technical-delivery` |
 
@@ -127,21 +101,27 @@ Then read the skill content and follow its instructions. The loaded skill takes
 
 If the user's request doesn't match any workflow phase (e.g., general questions, quick lookups, team management), use the Allye tools directly without loading a specific skill. The tools reference in section 4 gives you a quick overview.
 
----
+### Direct implementation path
+
+When the user asks for a small or low-risk local change and no task exists, recommend the lightweight execution loop: state scope, get explicit approval to bypass task creation, read first, test and verify, then report. Do not create a task merely because the execution skill exists.
 
-## 3. Workflow Gates
+---
 
-<HARD-GATE>
-These rules are non-negotiable. Do not proceed past a gate without meeting its condition.
+## 3. Adaptive Checkpoints and Guardrails
 
-1. **No implementation without tasks.** Do not write code for a story that has no tasks created. Run Technical Planning first.
+There is no universal phase gate. Choose the smallest useful loop for the user's intent:
 
-2. **No skipping the discussion phase.** When planning tasks for a story, always identify gray areas and present options to the user before creating tasks. Locked decisions must be captured as memories.
+`intent → context → research (optional) → decision/consent → action → verification → persistence (optional)`
 
-3. **No status changes without work.** Do not move a work item to "done" (`work_status_done`) unless the actual work is completed and verified.
+Checkpoints may be skipped or repeated. Use this policy:
 
-4. **TDD when applicable.** If you can write `expect(fn(input)).toBe(output)` before writing `fn`, you MUST write the test first (Red → Green → Refactor). If not (UI, infra, integration), test after implementation — but always test.
-</HARD-GATE>
+- **Low-risk, local, reversible work:** proceed with a concise plan and proportionate verification. Do not create work items merely to satisfy the toolkit.
+- **Meaningful, multi-step, delegated, shared, or review-heavy work:** recommend a task or work item for traceability. Explain the benefit and ask for approval before creating it.
+- **No-task path:** if the user explicitly approves bypassing task creation, record that choice when useful, keep scope explicit, and verify the result proportionally.
+- **Consequential mutations** (external systems, destructive operations, publication, deployment, status changes, or broad scope): obtain explicit consent unless the user already clearly authorized that exact action. Do not create or change work items/statuses without approval.
+- **Ambiguity that changes scope, risk, or architecture:** stop and ask. Minor implementation details may use established defaults, stated assumptions, and a reversible change.
+- **TDD:** use Red → Green → Refactor when the behavior can be specified as a deterministic example; otherwise test after implementation, but do not skip verification.
+- **Done claims:** only claim completion after reading actual verification output and distinguishing implementation evidence from review, deployment, or other pending gates.
 
 ---
 
@@ -172,11 +152,11 @@ If you catch yourself thinking any of these, STOP:
 
 | Rationalization | Why it's wrong |
 |-----------------|---------------|
-| "I don't need to search memories, this is a fresh conversation." | The user may have worked on this topic before. Context from past sessions prevents rework and contradictions. Always search. |
-| "I'll just start coding, tasks aren't necessary for something this small." | Tasks create accountability, enable progress tracking, and force you to think before acting. Planning first, always. |
+| "I don't need to search memories, this is a fresh conversation." | For consequential or resumed work, prior context may prevent rework; search when useful and available, but do not pretend an unavailable capability was used. |
+| "I'll just start coding, tasks aren't necessary for something this small." | For meaningful work, tasks improve accountability; for small work, use the approved no-task path with explicit scope and verification. |
 | "I'll skip the tests, the implementation is straightforward." | Straightforward code still breaks. TDD catches assumptions. Write the test. |
 | "I'll move the story to done, the tasks are mostly complete." | "Mostly" is not "done". Verify all tasks are complete first. |
-| "I don't need to save memories, I covered everything in the conversation." | Conversations are ephemeral. The next session starts from zero without memories. Always save state. |
+| "I don't need to save memories, I covered everything in the conversation." | Save durable decisions and consequential session state when persistence is available; skip trivial noise and report when persistence is unavailable. |
 | "I'll load all skills at once to be prepared." | Skills are loaded on-demand for a reason — loading everything bloats context and degrades quality. Load only what's needed. |
 
 ---