pi-subagents-j0k3r 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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

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.1",
+  "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"
     ],
@@ -88,11 +91,11 @@ 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.
-- Prefer configuring subagent `model` and `effort` in global or project `subagents.json` under `model_profiles`, not in the subagent markdown frontmatter. Markdown definitions should usually contain identity, description, tool allowlist, and behavioral instructions only.
+- 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.
@@ -151,7 +154,7 @@ tools:
 Instructions...
 ```
 
-Configure routing separately in `subagents.json` when needed. If no profile/default is configured, the subagent inherits the current orchestrator model and thinking effort.
+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
 {
@@ -166,9 +169,9 @@ Configure routing separately in `subagents.json` when needed. If no profile/defa
 
 Model/effort resolution order:
 
-1. `model_profiles[agentName]` in `subagents.json`.
+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` in `subagents.json`.
+3. `default_model` / `default_effort` from effective `subagents.json` config.
 4. Current orchestrator model / effort.
 
 ## Decision Gates
@@ -176,16 +179,16 @@ Model/effort resolution order:
 - 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: 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.
-4. For new subagents, choose lowercase kebab-case names and clear trigger-focused descriptions.
+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`, `default_model`, and `default_effort` in `subagents.json` only when the user wants explicit routing; 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.
+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.
@@ -200,7 +203,7 @@ Model/effort resolution order:
 Return:
 
 - Skill applied: `subagents-configuration`.
-- Scope/path configured or reviewed.
+- 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`.

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); }