pi-subagents-j0k3r 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 1.1.0 - 2026-06-27
+
+### Added
+- Added support for loading markdown-defined subagents from both `agents` and `subagents` directories globally and project-locally.
+- Added startup warnings when duplicate names exist in `agents` and `subagents` at the same scope, while preserving `subagents` as the winning source.
+- Enabled project Skill Registry configuration and ignored generated registry cache outputs.
+
+### Fixed
+- Made `model_profiles` global-only so project-local `.pi/subagents.json` cannot override per-agent model/effort routing.
+
+### Documentation
+- Updated README and Subagents configuration skill guidance for `agents`/`subagents` source precedence and global-only model profiles.
+
+## 1.0.1 - 2026-06-27
+
+### Fixed
+- Expanded Subagents configuration guidance so agents can explain npm installation/update setup, model/effort inheritance, and task/background runtime behavior.
+- Clarified that subagent model and effort routing should live in `subagents.json` `model_profiles` by default, with unconfigured agents inheriting the orchestrator model and effort.
+
 ## 1.0.0 - 2026-06-27
 
 ### Added

package/README.md

@@ -67,10 +67,12 @@ Subagents are markdown files with optional YAML-like frontmatter.
 
 Load order:
 
-1. Global user subagents from `$PI_CODING_AGENT_DIR/subagents/*.md`.
-2. Project subagents from `.pi/subagents/*.md`.
+1. Global user agents from `$PI_CODING_AGENT_DIR/agents/*.md`.
+2. Global user subagents from `$PI_CODING_AGENT_DIR/subagents/*.md`.
+3. Project agents from `.pi/agents/*.md`.
+4. Project subagents from `.pi/subagents/*.md`.
 
-Project definitions override global definitions with the same normalized name.
+Project definitions override global definitions with the same normalized name. Within the same scope, `subagents` definitions override `agents` definitions with the same normalized name and Pi shows a startup warning so the duplicate can be cleaned up.
 
 Default global agent directory:
 
@@ -127,7 +129,7 @@ Config files:
 .pi/subagents.json              # project
 ```
 
-Config resolves as a cascade: project `.pi/subagents.json` overrides global `~/.pi/agent/subagents.json`; missing project fields fall back to global config; fields missing from both fall back to built-in defaults. Model profiles are merged by normalized lowercase agent name, with project profile fields overriding global profile fields.
+Config resolves as a cascade: project `.pi/subagents.json` overrides global `~/.pi/agent/subagents.json`; missing project fields fall back to global config; fields missing from both fall back to built-in defaults. `model_profiles` are the explicit exception: per-agent model/effort routing is read only from the global `~/.pi/agent/subagents.json` or `$PI_CODING_AGENT_DIR/subagents.json`, and project-local `model_profiles` are ignored.
 
 Example:
 
@@ -168,7 +170,7 @@ Example:
 |---|---:|---|
 | `default_model` | current orchestrator model | Fallback model for all subagents. Format: `provider/model-id`. |
 | `default_effort` | current orchestrator effort | Fallback thinking effort. Also accepts `default_thinking_level` or `thinkingLevel`. |
-| `model_profiles` | `{}` | Per-agent model/effort overrides. |
+| `model_profiles` | `{}` | Global-only per-agent model/effort overrides. Project-local `.pi/subagents.json` `model_profiles` are ignored. |
 | `timeout_ms` | `600000` | Total timeout per subagent task. |
 | `stall_timeout_ms` | `120000` | Inactivity timeout for a subagent session. |
 | `max_concurrency` | `5` | Max concurrent subagent tasks per cwd/config pair. |
@@ -392,7 +394,7 @@ This package bundles:
 - `index.ts` and `src/**` — the Pi extension runtime.
 - `skills/subagents-configuration/SKILL.md` — configuration guidance for agents that need to create or edit subagent definitions.
 
-Subagent definitions are intentionally user/project configuration, not hard-coded package behavior. Add them globally in `$PI_CODING_AGENT_DIR/subagents/*.md` or project-locally in `.pi/subagents/*.md`.
+Subagent definitions are intentionally user/project configuration, not hard-coded package behavior. Add them globally in `$PI_CODING_AGENT_DIR/agents/*.md` or `$PI_CODING_AGENT_DIR/subagents/*.md`, or project-locally in `.pi/agents/*.md` or `.pi/subagents/*.md`.
 
 ## Development
 

package/index.ts

@@ -1,5 +1,5 @@
 import { SubagentManager } from './src/manager.js';
-import { readSubagentsConfig } from './src/config.js';
+import { readSubagentsConfig, subagentSourceWarnings } from './src/config.js';
 import { registerSubagentTools, triggerClaudeBackgroundHandoff } from './src/tools.js';
 import { runSubagentModelsCommand } from './src/model-profiles-ui.js';
 import { SubagentsHistoryPanel } from './src/ui.js';
@@ -412,6 +412,8 @@ export default function subagentsExtension(pi: any): void {
 
   pi.on?.('session_start', (_event: unknown, ctx: any) => {
     clearClaudeBackgroundWidget();
+    const cwd = ctx?.cwd ?? process.cwd();
+    for (const warning of subagentSourceWarnings(cwd)) ctx?.ui?.notify?.(warning, 'warning');
     if (typeof ctx?.ui?.setWidget !== 'function') return;
     widgetCtx = ctx;
     if (!installClaudeBackgroundWidget(ctx)) return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-j0k3r",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Installable Pi package that adds markdown-defined subagents, delegated task tools, history, and model profiles.",
   "type": "module",
   "license": "MIT",

package/skills/subagents-configuration/SKILL.md

@@ -19,10 +19,13 @@ Use this block as the machine-readable source for `.pi/skill-registry.json` gene
   "domains": ["subagents-configuration", "subagent-config", "model-profile-config", "tool-allowlist-config", "subagent-history-config", "subagent-shortcut-config"],
   "triggers": {
     "paths": [
+      ".pi/agents/**/*.md",
       ".pi/subagents/**/*.md",
       ".pi/subagents.json",
+      "agents/**/*.md",
       "subagents/**/*.md",
       "subagents.json",
+      "~/.pi/agent/agents/**/*.md",
       "~/.pi/agent/subagents/**/*.md",
       "~/.pi/agent/subagents.json"
     ],
@@ -77,7 +80,7 @@ Field conventions:
 
 ## Activation Contract
 
-Use this skill only when the user asks how to configure Pi Subagents or when editing/reviewing subagent configuration files: markdown subagent definitions and project/global `subagents.json`. Cover model profiles, allowed tools, history settings, background task config, background handoff shortcuts, lean resources, and generic interaction handoff as configuration topics only.
+Use this skill only when the user asks how to configure Pi Subagents or when editing/reviewing subagent configuration files: package installation/update settings, markdown subagent definitions, project/global `subagents.json`, model profiles, allowed tools, history settings, background task config, background handoff shortcuts, lean resources, runtime task/background behavior, and generic interaction handoff as configuration topics only.
 
 Do not load this skill for ordinary subagent delegation/use (`subagent_run`, task status/result polling), extension implementation work, task history browsing, or editing this skill file; those are not configuration questions.
 
@@ -88,15 +91,28 @@ Do not load this skill for ordinary subagent delegation/use (`subagent_run`, tas
 - Prefer narrow tool allowlists per subagent. Do not grant write/bash tools unless the subagent purpose requires them.
 - For SDD/PRD phase agents, prefer deterministic active-flow memory tools only: `memory_search`, `memory_get`, `memory_add`, and `memory_update`; avoid `memory_context` and `memory_recall` in subagent allowlists unless there is a specific reviewed need.
 - For SDD phase agents, memory write tools may be allowed only for active SDD flow memory/artifacts according to `sdd-workflow`.
-- Project subagents live in `.pi/subagents/*.md`; global user subagents live in `$PI_CODING_AGENT_DIR/subagents/*.md` or `~/.pi/agent/subagents/*.md`.
-- Project definitions override global definitions with the same normalized name.
-- Subagents config resolves as a cascade: project `.pi/subagents.json` overrides global `$PI_CODING_AGENT_DIR/subagents.json` or `~/.pi/agent/subagents.json`; missing project fields fall back to global config; fields missing from both fall back to built-in defaults. Communicate this precedence to users when explaining config behavior.
-- `model_profiles` are deep-merged by agent name with project-local profile fields taking precedence over global profile fields.
+- Project subagent definitions live in `.pi/agents/*.md` and `.pi/subagents/*.md`; global user definitions live in `$PI_CODING_AGENT_DIR/agents/*.md`, `$PI_CODING_AGENT_DIR/subagents/*.md`, `~/.pi/agent/agents/*.md`, or `~/.pi/agent/subagents/*.md`.
+- Project definitions override global definitions with the same normalized name. Within the same scope, definitions in `subagents` override definitions in `agents` with the same normalized name, and Pi should warn at session startup so users can clean up the duplicate.
+- Subagents config resolves as a cascade: project `.pi/subagents.json` overrides global `$PI_CODING_AGENT_DIR/subagents.json` or `~/.pi/agent/subagents.json`; missing project fields fall back to global config; fields missing from both fall back to built-in defaults. Communicate this precedence to users when explaining config behavior, with the explicit exception that `model_profiles` are global-only.
+- `model_profiles` are read only from global `$PI_CODING_AGENT_DIR/subagents.json` or `~/.pi/agent/subagents.json`; project-local `.pi/subagents.json` must not set or override subagent model/effort routing.
+- Prefer configuring subagent `model` and `effort` in global `subagents.json` under `model_profiles`, not in project-local config or in the subagent markdown frontmatter. Markdown definitions should usually contain identity, description, tool allowlist, and behavioral instructions only.
 - Nested subagent sessions should use `session_resources: "lean"` by default so the subagent markdown body becomes the nested session system prompt, the delegated user prompt contains only orchestrator context/task, and workflow skills, prompt templates, themes, context files, and startup context injections are not auto-loaded.
 - In lean mode, extensions are loaded for allowlisted tools and tool-safety hooks only; prompt/context lifecycle hooks such as `before_agent_start` and `context` must not inject hidden messages into subagent turns.
 - Subagent task history is stored globally under data storage, but rows remain project-scoped by `cwd`; history stores delegated prompt and subagent system prompt separately.
 - Debug logging is disabled by default with `debug: false`; when enabled in global or project `subagents.json`, logs are written to the executing project's `cwd/.pi/subagents-debug.log`.
-- After changing subagent markdown/config or extension code, tell the user to `/reload` or restart Pi.
+- To install the published package globally, prefer `pi install npm:pi-subagents-j0k3r`. If the user wants future `pi update --extensions` / `pi update --all` to move to newer releases, keep the package source unpinned as `npm:pi-subagents-j0k3r` in `~/.pi/agent/settings.json`. Use `npm:pi-subagents-j0k3r@x.y.z` only when the user explicitly wants a fixed version.
+- Runtime behavior to explain: `mode=task` waits and returns the full subagent response to the orchestrator; `mode=background` frees the chat, should not be polled just to wait, and sends an automatic completion/failure notification. `/subagents` opens the session history/detail panel; `ctrl+o` expands/collapses rendered tool output and responses; `subagent_result` reads a stored result when explicitly needed.
+- After changing subagent markdown/config, package settings, or extension code, tell the user to `/reload` or restart Pi.
+
+Recommended global package setting in `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": [
+    "npm:pi-subagents-j0k3r"
+  ]
+}
+```
 
 Recommended `subagents.json` starter:
 
@@ -131,8 +147,6 @@ description: investigates isolated ideas, code, documentation, and context7 befo
 tools:
   - read
   - memory_search
-model: anthropic/claude-sonnet-4-5
-effort: low
 ---
 
 # Discovery Subagent
@@ -140,36 +154,59 @@ effort: low
 Instructions...
 ```
 
+Configure model/effort routing separately in the global `subagents.json` when needed. If no global profile/default is configured, the subagent inherits the current orchestrator model and thinking effort.
+
+```json
+{
+  "model_profiles": {
+    "discovery": {
+      "model": "anthropic/claude-sonnet-4-5",
+      "effort": "low"
+    }
+  }
+}
+```
+
+Model/effort resolution order:
+
+1. Global `model_profiles[agentName]` in `$PI_CODING_AGENT_DIR/subagents.json` or `~/.pi/agent/subagents.json`.
+2. Markdown frontmatter `model` / `effort` only for explicit per-file overrides.
+3. `default_model` / `default_effort` from effective `subagents.json` config.
+4. Current orchestrator model / effort.
+
 ## Decision Gates
 
 - If the subagent will modify files, run bash, or write memory, ask whether a full SDD workflow or stricter review is required.
 - If the subagent needs human input, require a structured `interaction_required` request with enough prompt, payload, and expected-response data for the parent to answer.
 - If a project wants many subagents or broad tools, recommend starting with read-only discovery agents and expanding deliberately.
-- If model profiles are global, confirm the user wants global behavior rather than project-only config.
+- If the user asks for project-local model profiles, explain that `model_profiles` are global-only and ask whether they want to update the global config instead.
 
 ## Execution Steps
 
-1. Identify target scope: global subagent, project subagent, global config, or project config, and explain the cascade when relevant: project-local config first, then global config for missing fields, then built-in defaults.
-2. Read existing subagent markdown/config before editing.
-3. For new subagents, choose lowercase kebab-case names and clear trigger-focused descriptions.
-4. Set minimal tool allowlists; remove any `subagent_*` entries.
-5. Configure `model_profiles`, `default_model`, and `default_effort` only when the user wants explicit routing.
-6. Configure `debug: true` only for temporary diagnostics; keep `debug: false` by default and remember logs are written under the executing project's `.pi` directory.
-7. Validate JSON syntax for `subagents.json` and frontmatter/body structure for markdown agents.
-8. When configuring OpenCode-mode history opening, prefer `history_panel_shortcut` with `ctrl+<letter>` or `ctrl+,` values and document any built-in shortcut conflicts.
-9. When configuring history/detail cancellation, prefer `detail_cancel_shortcut` with `x` by default; it supports `ctrl+<letter>`, `ctrl+shift+<letter>`, `ctrl+,`, or one lowercase letter. It only cancels the selected queued/running task while the detail panel is active.
-10. When configuring Claude-mode background handoff, prefer `background_handoff_shortcut` with `ctrl+<letter>` values and document any built-in shortcut conflicts.
-11. Tell the user to `/reload` or restart Pi.
-12. If validating configuration after reload, use `subagent_list_agents` only when the user asks for runtime verification; do not run delegated tasks just to validate configuration.
+1. Identify target scope: npm package install/update, global subagent, project subagent, global config, or project config, and explain the cascade when relevant: project-local config first, then global config for missing fields, then built-in defaults.
+2. For package setup, inspect settings before editing; use `pi install npm:pi-subagents-j0k3r` when possible, or edit `~/.pi/agent/settings.json` only when the CLI is unavailable/broken. Prefer unpinned `npm:pi-subagents-j0k3r` unless the user asks for a fixed version.
+3. Read existing subagent markdown/config before editing, checking both `agents` and `subagents` directories for the requested scope.
+4. For new subagents, choose lowercase kebab-case names and clear trigger-focused descriptions. Prefer `subagents` for new definitions unless the user explicitly needs compatibility with an `agents` harness.
+5. Set minimal tool allowlists; remove any `subagent_*` entries.
+6. Configure `model_profiles` only in global `subagents.json` when the user wants explicit per-agent routing; project-local `model_profiles` are ignored. Configure `default_model` and `default_effort` in effective `subagents.json` only when the user wants defaults. Do not put model routing in subagent markdown unless the user explicitly asks for per-file overrides. Explain that unconfigured fields inherit from the orchestrator.
+7. Configure `debug: true` only for temporary diagnostics; keep `debug: false` by default and remember logs are written under the executing project's `.pi` directory.
+8. Validate JSON syntax for settings/subagents config and frontmatter/body structure for markdown agents.
+9. When configuring OpenCode-mode history opening, prefer `history_panel_shortcut` with `ctrl+<letter>` or `ctrl+,` values and document any built-in shortcut conflicts.
+10. When configuring history/detail cancellation, prefer `detail_cancel_shortcut` with `x` by default; it supports `ctrl+<letter>`, `ctrl+shift+<letter>`, `ctrl+,`, or one lowercase letter. It only cancels the selected queued/running task while the detail panel is active.
+11. When configuring Claude-mode background handoff, prefer `background_handoff_shortcut` with `ctrl+<letter>` values and document any built-in shortcut conflicts.
+12. Explain runtime behavior when relevant: use `mode=task` to wait; use `mode=background` to keep chat usable and wait for automatic notification; use `/subagents` and `ctrl+o` for detail/expanded rendering.
+13. Tell the user to `/reload` or restart Pi.
+14. If validating configuration after reload, use `subagent_list_agents` only when the user asks for runtime verification; do not run delegated tasks just to validate configuration.
 
 ## Output Contract
 
 Return:
 
 - Skill applied: `subagents-configuration`.
-- Scope/path configured or reviewed.
-- Subagents/config fields added, changed, or preserved.
-- Tool allowlist, system-prompt isolation, Context7 scope, memory-tool scope, debug logging, and model/effort decisions.
+- Scope/path configured or reviewed, including whether definitions came from `agents` or `subagents`.
+- Package settings and subagents/config fields added, changed, or preserved.
+- Tool allowlist, system-prompt isolation, Context7 scope, memory-tool scope, debug logging, model/effort decisions, and inheritance behavior.
+- Runtime behavior explained when relevant: task vs background, automatic notifications, `/subagents`, `ctrl+o`, and `subagent_result`.
 - Related configuration skills considered or loaded.
 - Validation executed, or the concrete reason it was not run.
 - Required reload/restart note and open risks.

package/src/config.ts

@@ -163,16 +163,6 @@ function parseModelProfiles(value: unknown): SubagentModelProfiles {
   return profiles;
 }
 
-function mergeModelProfiles(globalRaw: unknown, projectRaw: unknown): SubagentModelProfiles {
-  const globalProfiles = parseModelProfiles(globalRaw);
-  const projectProfiles = parseModelProfiles(projectRaw);
-  const merged: SubagentModelProfiles = { ...globalProfiles };
-  for (const [name, projectProfile] of Object.entries(projectProfiles)) {
-    merged[name] = { ...(merged[name] ?? {}), ...projectProfile };
-  }
-  return merged;
-}
-
 function serializeModelRef(model: ModelRef): string {
   return `${model.provider}/${model.id}`;
 }
@@ -191,7 +181,7 @@ export function readSubagentsConfig(cwd: string): SubagentsConfig {
   return {
     default_model: parseModel(raw.default_model),
     default_effort: parseEffort(raw.default_effort ?? raw.default_thinking_level ?? raw.thinkingLevel),
-    model_profiles: mergeModelProfiles(globalRaw.model_profiles, projectRaw.model_profiles),
+    model_profiles: parseModelProfiles(globalRaw.model_profiles),
     timeout_ms: positiveInteger(raw.timeout_ms, DEFAULT_TIMEOUT_MS),
     stall_timeout_ms: positiveInteger(raw.stall_timeout_ms, DEFAULT_STALL_TIMEOUT_MS),
     max_concurrency: positiveInteger(raw.max_concurrency, DEFAULT_MAX_CONCURRENCY),
@@ -250,10 +240,37 @@ function loadSubagentsFromDir(dir: string): SubagentDefinition[] {
     });
 }
 
+function agentsDirSources(cwd: string): Array<{ scope: 'global' | 'project'; kind: 'agents' | 'subagents'; dir: string }> {
+  const globalAgentDir = agentDir();
+  return [
+    { scope: 'global', kind: 'agents', dir: path.join(globalAgentDir, 'agents') },
+    { scope: 'global', kind: 'subagents', dir: path.join(globalAgentDir, 'subagents') },
+    { scope: 'project', kind: 'agents', dir: path.join(cwd, '.pi', 'agents') },
+    { scope: 'project', kind: 'subagents', dir: path.join(cwd, '.pi', 'subagents') },
+  ];
+}
+
+export function subagentSourceWarnings(cwd: string): string[] {
+  const warnings: string[] = [];
+  for (const scope of ['global', 'project'] as const) {
+    const sources = agentsDirSources(cwd).filter((source) => source.scope === scope);
+    const agents = loadSubagentsFromDir(sources.find((source) => source.kind === 'agents')!.dir);
+    const subagents = loadSubagentsFromDir(sources.find((source) => source.kind === 'subagents')!.dir);
+    const subagentNames = new Map(subagents.map((definition) => [definition.name, definition]));
+    for (const agent of agents) {
+      const subagent = subagentNames.get(agent.name);
+      if (!subagent) continue;
+      warnings.push(`Duplicate subagent name "${agent.name}" found in ${scope} agents and subagents directories; using subagents definition (${subagent.filePath}).`);
+    }
+  }
+  return warnings;
+}
+
 export function loadSubagents(cwd: string): SubagentDefinition[] {
   const byName = new Map<string, SubagentDefinition>();
-  for (const agent of loadSubagentsFromDir(path.join(agentDir(), 'subagents'))) byName.set(agent.name, agent);
-  for (const agent of loadSubagentsFromDir(path.join(cwd, '.pi', 'subagents'))) byName.set(agent.name, agent);
+  for (const source of agentsDirSources(cwd)) {
+    for (const agent of loadSubagentsFromDir(source.dir)) byName.set(agent.name, agent);
+  }
   return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 

package/src/tools.ts

@@ -299,7 +299,7 @@ export function registerSubagentTools(pi: any, manager: SubagentManager): void {
     name: 'subagent_list_agents',
     label: 'Subagent List Agents',
     description: 'List available markdown-defined subagents for delegation.',
-    promptSnippet: 'List available subagents loaded from .pi/subagents/*.md.',
+    promptSnippet: 'List available subagents loaded from global/project agents and subagents markdown directories.',
     parameters: Type.Object({}),
     async execute(_id: string, _params: any, _signal: any, _onUpdate: any, ctx: any) {
       try { const agents = manager.listAgents(ctx?.cwd ?? process.cwd()); return ok(`Found ${agents.length} subagent(s).`, { agents }); } catch (e) { return fail(e); }