Prepared detailed implementation plan for GitHub issue

Summary

In Progress

Understand
Reviewed GitHub issue and project context.
Understand
Edit
Drafted consolidated comment with design decisions.
Edit
Edit
Expanded comment with detailed implementation instructions.
Edit

Analyze GitHub issue(s): https://github.com/badlogic/pi-mono/issues/645 this is an issue by me and you. we already went through all of this. i think its finally time to implement this garbage. analyze the issue and the codebase, tell me if you have any open questions so we can finalize the details, then go to town

For each issue:

Read the issue in full, including all comments and linked issues/PRs.
For bugs:
- Ignore any root cause analysis in the issue (likely wrong)
- Read all related code files in full (no truncation)
- Trace the code path and identify the actual root cause
- Propose a fix
For feature requests:
- Read all related code files in full (no truncation)
- Propose the most concise implementation approach
- List affected files and changes needed

Do NOT implement unless explicitly asked. Analyze and propose only.

Resolving large file read conflict

The file exceeds 50KB, so to retrieve it fully I’ll read the remaining part using offsets despite instructions against offsets for full reads, since the size requires chunked reading. I’ll continue from line 1521 to get the complete file.

Continuing file read with offset

Proceeding to read the remaining agent-session file starting at offset 1521 without a limit, expecting to fetch additional segments if needed due to size.

Analyzing package manager feature proposal

I'm outlining a design for a package manager with loader, reload, and watch features, identifying needed interface and main.ts changes plus runner reload support, while pinpointing open questions on settings storage, npm handling, and CLI integration. Next, I'll verify current extension loading and reload gaps by reviewing prompt templates and skills loading files.

Summarizing feature scope and open questions

I'm detailing #645 tasks covering package manager, loader, bootstrap flow, session reload, CLI commands, and watch mode, plus noting current extension/skill/prompt loading and absence of reload. I highlight unclear points on recursive skill discovery, compatibility with existing extension loading, settings merging semantics, npm install location, and theme loading, preparing precise questions for clarification.

Summarizing theme loading and extension management analysis

I've analyzed theme loading anchored by a custom themes directory and noted it would require new package-level loading support. The current extension loader focuses on local paths without package management. I'll outline the issue context, related tickets, current loader architecture, propose new PackageManager and Loader modules, and suggest CLI commands for package install/update/remove with options for organizing commands separately.

Detailing implementation approach and open questions

The current system lacks a unified loader abstraction, package manager, reload support, and CLI commands for package management. I propose creating a new core loader module to handle loading extensions, skills, prompts, themes, and context files from resolved paths with filtering, reusing existing extension loader logic where possible. A new PackageManager module would manage npm/git/local package sources and settings, handle installs/updates, and coordinate with SettingsManager for source persistence. Reload support would move initialization logic into AgentSession with a reload method triggering rebuilds of prompts, skills, and tools. Watch mode should gather relevant paths and run in interactive mode only.

Open questions include whether to install npm packages globally or in a local directory, how to migrate settings from paths to package sources, whether to retain automatic extension discovery alongside package manager resolution, how to handle overrides merging in SettingsManager, the scope of files and manifests the loader should handle (including SYSTEM.md and APPEND_SYSTEM.md), how and where to add CLI subcommands for install/remove/update, version pinning logic for git packages, and how to integrate new loaders with existing SDK/session runner initialization and event bus reuse. The response also notes affected files and the need for documentation updates.

Summary of issue #645 and linked items

#645 is a feature request that replaces #326 and #562. It defines a package manager, a unified loader for extensions, skills, prompts, themes, and context files, plus reload and watch.
#751 is a closed PR that added skills_discover. It is referenced in comments as a request for recursive skills discovery. It is superseded by #645.

Current code behavior

Extensions load via core/extensions/loader.ts. It discovers extensions from ~/.pi/agent/extensions and .pi/extensions, plus settings.json and -e paths. It supports package.json pi.extensions but only for extensions.
The SDK does all discovery. createAgentSession discovers skills, prompt templates, and context files separately. Extensions are loaded in sdk.ts or preloaded in main.ts to parse flags.
main.ts already does two pass parsing for extension flags, but it is tied to extension discovery and settings. There is no package manager or consolidated loader.
AgentSession has no reload mechanism. Modes manually initialize ExtensionRunner and emit session_start.
Skills, prompt templates, themes are loaded only from fixed global and project locations.
There is no CLI subcommand infrastructure. args.ts is flags only. No /reload command.

Concise implementation approach Phase 1: PackageManager

New PackageManager module under packages/coding-agent/src/core. It reads settings.json sources and resolves to paths, installs and updates npm or git sources, and handles local vs global.
Extend settings to store extension sources like npm: and git: instead of raw file paths. This likely requires a migration path or backward compatibility for current paths.
Implement install/remove/update commands in main.ts with a subcommand layer or early argument parsing before parseArgs.

Phase 2: Loader

New loader module that accepts resolved paths for extensions, skills, prompts, themes, and context files and applies filters. It should use existing logic in skills.ts, prompt-templates.ts, system-prompt.ts, and extensions/loader.ts without duplicating parsing.
Extend the pi manifest handling to include prompts and themes and maybe context file paths. Current PiManifest includes skills and themes but loader only uses extensions. Add prompts and context entries to the manifest shape.

Phase 3: Bootstrap flow

Replace early extension load in main.ts with a loader provider callback that reads settings and resolves sources at load time.
Continue two pass parse by loading extensions first via loader.load() and collecting flags. Then parse args again and apply flag values to runtime.

Phase 4: Runner initializer and AgentSession reload

Add a runner initializer on AgentSession that modes register. AgentSession.reload should shut down old runner, create new runner, update skills, prompt templates, themes, and context files, rebuild system prompt, and emit session_start.
Move session_start emission into AgentSession logic so modes do not repeat it.

Phase 5: Reload and watch

Add /reload command in interactive mode that invokes loader.load() and session.reload(). Copy flag values from the old runtime to new runtime.
Add --watch flag that watches all resolved paths in loader config. Debounce and call reload. Reuse loader config provider on each change.

Phase 6: Package management CLI

Add pi install, remove, update with global vs local flags. Update args.ts and help output. Persist changes in settings.json.

Affected files and changes needed

packages/coding-agent/src/core/package-manager.ts (new)
packages/coding-agent/src/core/loader.ts or similar (new)
packages/coding-agent/src/core/sdk.ts: use loader and stop handling discovery here
packages/coding-agent/src/main.ts: new bootstrap flow, subcommands, --watch, /reload wiring
packages/coding-agent/src/core/agent-session.ts: add runner initializer and reload method
packages/coding-agent/src/modes/interactive/interactive-mode.ts: register initializer, add /reload command, apply themes
packages/coding-agent/src/modes/print-mode.ts and rpc-mode.ts: register initializer
packages/coding-agent/src/core/extensions/loader.ts: extend manifest handling for prompts, themes, skills, maybe context files
packages/coding-agent/src/core/skills.ts and prompt-templates.ts: add APIs to load from explicit paths, not just fixed directories
packages/coding-agent/src/core/system-prompt.ts: add loader to accept AGENTS.md and SYSTEM.md paths from loader
packages/coding-agent/src/cli/args.ts: new flags and subcommands
packages/coding-agent/docs/extensions.md and README.md: new extension package management and locations
packages/coding-agent/CHANGELOG.md: add entries when implemented

Open questions to finalize

Npm install strategy. The issue text uses npm root -g for global installs. Earlier #326 comments prefer unpacking into ~/.pi/agent/extensions to avoid polluting global node_modules. Which approach should we implement.
Settings merge behavior. Current SettingsManager deep merges objects but replaces arrays. Should local settings merge with global extensions sources or override them. The issue text says local overrides and merges with global.
Should we keep auto discovery of ~/.pi/agent/extensions and .pi/extensions or move to settings.json as the only source of truth. The issue text implies settings.json is the source of truth.
How to treat SYSTEM.md and APPEND_SYSTEM.md in the new loader. The ResolvedPaths sketch mentions agentsMd and systemMd. Do we add appendSystemMd or keep existing behavior in system-prompt.ts.
Watch and reload scope. Should --watch be interactive only or also work in rpc and print modes. Should /reload be interactive only.
Skills recursion ask from #751. Do you want to include recursive skills discovery beyond current behavior in this implementation or defer it.
Git update behavior. If source is git:...@commit or tag, should update skip it. If no version, should update pull latest default branch.

If these are confirmed, I can move to implementation.

npm root -g
give me an example
we should keep auto-discovery for extensions, themes, skills and prompt templates
i don't know. outline how this would look in practice compared to current
should work the same in all modes, i would assume watch just calls reload on agentsession
isn't that what we already implement? search SKILLS.md recursively in ~/.pi/agent/skills and /.pi/skills?
skip if @commit and tag and we already got latest, pull latest if no version

Extend the pi manifest handling to include prompts and themes and maybe context file paths. Current PiManifest includes skills and themes but loader only uses extensions. Add prompts and context entries to the manifest shape.

i think this also needs some talking about

Providing example and clarifications on settings and manifest

I'm preparing a concise example showing how local settings.json merges with system and appends for point 4. I'll outline that the manifest includes entries for prompts, themes, skills, and context, clarifying that the pi field controls priority or inclusion. I'll also confirm skill recursion is handled and raise an open question about default behavior for auto-discovery and settings merging, noting that watch mode applies in all cases.

Answers and details

Example for settings merge If global settings.json: { "extensions": ["npm:@foo/bar@1.0.0", "./global-local-ext"], "skills": { "enabled": true, "includeSkills": ["git-*"] } }

Project .pi/settings.json: { "extensions": ["./project-ext"], "skills": { "includeSkills": ["docker-*"] } }

With current deep merge behavior, arrays override, not merge. Effective: extensions: ["./project-ext"] skills.includeSkills: ["docker-*"]

If you want additive merge for extensions, we need custom handling so project extensions are appended to global instead of replacing. Same question applies to skills includeSkills and ignoredSkills. Do you want additive merge or override for each array.

SYSTEM.md and APPEND_SYSTEM.md options Current behavior:

discover SYSTEM.md or APPEND_SYSTEM.md only from global and project locations
system prompt build handles those and AGENTS.md context files, and skills
loader does not know about SYSTEM.md or APPEND_SYSTEM.md

If loader owns it: Option A. Keep current behavior

loader deals with extensions, skills, prompts, themes, AGENTS.md only
system prompt remains in system-prompt.ts, still auto-discovers SYSTEM.md and APPEND_SYSTEM.md
reload would re-run system prompt build, which already rereads those files

Option B. Loader returns explicit prompt overrides

loader resolves systemMd and appendSystemMd paths, maybe context files
AgentSession.reload uses those paths when rebuilding the system prompt, so discovery is centralized
removes the implicit discovery of SYSTEM.md and APPEND_SYSTEM.md from system-prompt.ts

Option C. Hybrid

loader resolves AGENTS.md and skills, but SYSTEM.md and APPEND_SYSTEM.md remain in system-prompt.ts
reload calls system prompt build which still discovers SYSTEM and APPEND files

Given your note, Option A or C is minimal. Option B is a more complete centralization but adds more decisions to loader.

Skills recursion Yes. Current loadSkills searches ~/.pi/agent/skills and /.pi/skills recursively already. It also loads Codex and Claude locations with their specific formats.
Git update I will implement: if source has tag or commit, skip update when already at that ref. If no version, update to latest.

Manifest handling discussion Today PiManifest in extensions/loader.ts only checks pi.extensions, but the interface already includes themes and skills. It does not include prompts or context files.

We need to decide what pi field means for non extensions. Proposed options:

Option 1. pi field means explicit paths only, no auto discovery inside the package

pi.extensions, pi.skills, pi.prompts, pi.themes, pi.contextFiles
PackageManager resolves source to a directory and loader consumes the explicit paths
If pi field is missing, loader defaults to auto discovery rules inside the package folder

Option 2. pi field is an augmentation, not a replacement

auto discovery always runs in the package directory
pi.extensions etc adds additional paths

Option 3. pi field only for extensions, other types always use auto discovery

simplest but inconsistent

Given your earlier issue text, it sounds like Option 1 is intended. If no pi field, fall back to default discovery for extensions, skills, prompts, themes. If pi field exists, use only those entries.

Also need to decide path formats:

Files or directories for skills and prompts
For themes, probably files only
For context files, maybe explicit paths to AGENTS.md or SYSTEM.md

Open questions

Settings merge for extensions and other array settings. Additive or override. This impacts local overrides. I need your preference.
SYSTEM.md and APPEND_SYSTEM.md. Which of the three options above.
Manifest semantics for prompts, themes, skills, context. Which option above, and whether to allow directories in each list.

Once you confirm, I will proceed to implementation.

i think we should get rid of ignore skills and include skills. if people want filtering, they should filter shit on their own by deleting skills they don't want.

as for merging extensions arrays, yeah that makes sense, merge local and global, warn on conflicts (same extension different version via npm or git for example).

what about themes and prompt templates?

that can stay as is, packaged extensions won't ship SYSTEM.md or AGENTS.md or APPEND_SYSTEM.md. that said, wouldn't it make sense to construct the system in such a way that the loader is responsible for ingesting and providing all the dynamic parts? extensions, skills, themes, prompt templates, AGENTS.md, APPEND_SYSTEM.md, SYSTEM.md? the default loader would just implement the current behaviour of looking in the default locations. A custom loader can provide those things whichever way it likes, no? Then main uses the default loader and passes that to createAgentSession in the SDK?
So i think that's also part of what the default loader will do. resolve skills in known locations, resolve skills from extension packages, provide them all as a nice list of SKILL.md files to load to createAgentSession?
approved

manifest handling i don't think we should include context files in manifests, but we must include prompts.

pi field means explicit paths only (either folders to which parts of auto-disocvery applies, or concrete files), full auto-discovery (like we do in ~/.pi/agent) only for extension packages without a pi field. those must then follow the folder and file layouts expected in ~/.pi/agent

path formats:

extension entry points: paths to .ts or .js files each containing an extension factory
themes: folder (assumes each .json file in the folder is a theme, no recursion) or file paths (assumes each file path is a theme)
prompts: folder (assumes each .md file in the folder is a prompt, no recursion) or file paths (assumes each file path is a prompt)
skills: folder (recursively searches for SKILLS.md), or file paths (assumes each file path is a SKILLS.md file)

Is this consistent? got a better proposal?

open questions:

which settings do we still need to think about wrt to merging given the above?
see above

let's keep discussing based on the above, possibly give feedback and a proposal of the full thing

Proposing SDK loader and settings changes

I’ll clarify the SKILL.md vs SKILLS.md mismatch by standardizing on SKILL.md as the code uses that. For settings, only extension arrays merge with conflict warnings; themes and prompts don’t have array settings currently. Skills settings will remove include/ignored filters. I propose a new Loader interface returning a load result that includes discovered extensions, skills, prompts, themes, context files, and system prompt files, used as input to createAgentSession via options for preloaded data. The default loader will handle discovery as now. SettingsManager and the settings schema need updates to reflect skill settings removing include/ignored. For merging, extensions arrays merge locally and globally with warnings on conflicts; we should consider merging extension sources from the CLI with similar warnings. Custom skill directories remain and should merge additively with warnings on duplicates since filtering is removed. This balanced approach avoids ambiguous merges and improves extensibility.

Confirming manifest support and naming consistency

I’ll note that prompts and themes support manifests as files or directories with rules, with themes and prompts loaded globally and non-recursively for listing and application. I’ll confirm consistently using SKILL.md (not SKILLS.md) and suggest minor settings tweaks to align with these standards.

Notes and proposal based on your latest guidance

Clarification needed

You wrote SKILLS.md in a few places. Current code uses SKILL.md. I will stick to SKILL.md unless you want to rename the format.

Settings merge and removal of skill filters

If we remove includeSkills and ignoredSkills from SkillsSettings, then the only remaining skills settings are enabled, per source flags, and customDirectories.
We should decide how to merge skills.customDirectories between global and project. I suggest additive merge with dedupe, similar to extensions, because users are likely to want both.
I propose we remove includeSkills and ignoredSkills from SettingsManager and Settings types, and ignore them if present in existing settings files. That is a breaking change but aligned with your intent.

Extensions array merging and conflicts

Merge global and project extensions arrays. Dedupe by normalized source string or by resolved package identity.
Warn on conflicts when the same package name appears with different sources or versions. For example npm:@foo/bar@1.0.0 and npm:@foo/bar@2.0.0.
For git sources, warn on the same repo with different refs.

Themes and prompt templates in settings

There are no settings arrays today for themes or prompt templates, so no merge logic needed unless we introduce them.
I suggest we do not add settings for these. Keep default loader discovery plus extension package contributions.

Loader ownership of all dynamic parts This fits well. I suggest we formalize a Loader result that includes:

extensions: extension entry points and runtime
skills: list of SKILL.md files or preloaded Skill objects
prompt templates: list of prompt files or PromptTemplate objects
themes: list of theme files or preloaded Theme objects
contextFiles: AGENTS.md content list
systemPromptSource: optional SYSTEM.md or override string
appendSystemPromptSource: optional APPEND_SYSTEM.md or override string

Default loader behavior

This default loader reproduces current behavior using existing discovery functions.
It returns concrete files and parsed objects. createAgentSession consumes those directly and does no additional discovery.

Custom loader behavior

A custom loader can override any part. It can hand a list of skill files, or preloaded Skill objects, or a custom system prompt string.
It can use a different root for discovery without changing SDK internals.

SDK changes

createAgentSession options should accept a LoadResult. If provided, SDK should not do discovery.
If no LoadResult is provided, SDK can use the default loader. This keeps existing programmatic usage stable.

Manifest handling proposal

pi field means explicit entries only. If pi field exists, only those are loaded. If pi field is absent, full auto discovery runs in that package root.
Add prompts to PiManifest.
No context files in manifest, per your request.

Path formats based on your list This is consistent, with one change for naming.

extensions: files to .ts or .js factories
themes: directory or file paths. Directory is non recursive and loads all .json
prompts: directory or file paths. Directory is non recursive and loads all .md
skills: directory or file paths. Directory is recursive and finds SKILL.md. File path must be SKILL.md

If you want prompts or themes to be recursive within package manifests, say so. Otherwise I will keep non recursive to match the folder rules.

Open questions to finalize

Confirm SKILL.md, not SKILLS.md.
Confirm additive merge for skills.customDirectories in settings.
Confirm whether custom loader should be a new public SDK surface or internal to CLI only. My suggestion is to expose Loader and LoadResult through SDK so programmatic users can plug in.
Confirm non recursive prompts and themes in manifest directories.

Once these are locked, I can proceed to implementation.

A yes, SKILL.md
I want to get rid of the source flags. if people want to use skills from another harness, they should symlink or use customDirectories. i'm ok with this breaking change. Merging of global and project customDirectories with dedup is fine too. I have a feeling we won't need enabled. it's not used anywhere either afaikt! i.e. SettingsManager.getSkillsEnabled(). so that means skills can become a simple array like extensions as well? which references local files SKILL.md or folders (recursively find SKILL.mds), in addition to discovery in ~/.pi/agent/skills
themes and prompt templates, yes makes sense, tho i feel we should harmonize this with extensions and skills above? I kind of feel there's a general theme here we can apply to all 4 things: extensions, skills, prompts themes?

we auto-discovery in ~/.pi/agent and /.pi/

skills/ any direct .md child in that folder plus recursively find SKILL.md files
prompts/ any direct .md child in that folder
themes/ any direct .json child in that folder
extensions/ any direct .ts or .js file in that folder, or one subfolder deep index.ts/.js or package.json?

Then in addition to that auto discovery, settings.json can have

skills: ["folder", "file"] prompts: ["folder", "file"] themes: ["folder", "file"] extensions: ["folder", "file", "npm", "git"]

and the same rules as for auto-disovery apply? any skill, theme or prompt declared in an extension package (either by folder layout or via pi field in packages.json)

if people want to disable skills or extensions loading, they can use --no-skills and --no-extensions, no need to make the config super complicated

I think the loader should have getters to get the currently loaded extension runtimes, skill objects, prompttemplate objects, theme objects, contextFiles, systemPromptSource, and appendPromptSources

Loader then also has a reload() method that reloads all the things it was configured to load, subsequent getXXX() calls return the new objects. does that make sense?

the sdk then does ... nothing much. it just takes a loader instance which it binds to the AgentSession is creates, so the agent session can reload things at any time

so the loader really loads everything, including context files, system.md, etc. does that make sense? tui can also get access to the loader to set things up

new proposal

Proposal aligned with your updated direction

Summary of behavior

Remove SkillsSettings and source flags. Skills settings become a list of paths only.
Auto discovery always runs for all four types in ~/.pi/agent and /.pi/.
settings.json can add extra paths for skills, prompts, themes, extensions.
--no-skills and --no-extensions still disable those subsystems.

Auto discovery rules

extensions: direct .ts or .js files, one level deep index.ts or index.js, or package.json with pi field
skills: direct .md children of skills/ plus recursive SKILL.md under subfolders
prompts: direct .md children of prompts/
themes: direct .json children of themes/

Paths listed in settings.json

Same rules as above based on path type.
Directory path means apply that type’s discovery rules.
File path means load that file directly.
For extensions, also accept npm: and git: sources via PackageManager.

Extension packages

If package.json has pi field, use only the explicit paths in pi for extensions, skills, prompts, themes.
If no pi field, apply the same discovery rules as the ~/.pi/agent layout.
No context files in pi manifest.

Loader shape I propose a Loader interface like:

type LoaderConfig = { cwd: string; agentDir: string; settingsManager: SettingsManager; packageManager: PackageManager; filters?: { extensions?: { enabled?: boolean; include?: string[]; exclude?: string[] }; skills?: { enabled?: boolean }; prompts?: { enabled?: boolean }; themes?: { enabled?: boolean }; }; };

type LoadResult = { extensions: LoadExtensionsResult; skills: Skill[]; skillWarnings: SkillWarning[]; promptTemplates: PromptTemplate[]; themes: ThemeInfo[] | Theme[]; contextFiles: Array<{ path: string; content: string }>; systemPromptSource?: string; appendSystemPromptSource?: string; };

interface Loader { load(): Promise; getResult(): LoadResult | undefined; }

Notes

I prefer load returns a full LoadResult and getResult just returns the last loaded one. This avoids extra getters per type.
Reload just calls load again.
For themes, we can return file paths or Theme objects. I suggest returning Theme objects loaded from paths so the TUI can apply them directly.

SDK changes

createAgentSession should accept a Loader instance or a LoadResult.
If Loader is provided, createAgentSession does no discovery. It reads from the LoadResult.
AgentSession.reload takes a LoadResult and refreshes skills, prompts, themes, context, system prompt, extensions.

Questions to confirm

Should skills, prompts, themes arrays in settings.json be merged between global and project like extensions, with dedupe.
Should include and exclude filters in loader be kept or removed entirely. You already removed skills include ignore. Should we keep extension include and exclude.
Loader should resolve themes to Theme objects or just file paths.

If this matches, I will proceed to implement exactly this shape.

that loader interface is fucking garbage.

i think what we need is something more like Resources interface

interface ResourceLoader { getExtensions(): ExtensionLoaderResult (prev LoadExtensionsResult) getSkills(): { skills: Skill[], warnings: SkillWarning[] } getPrompts(): { prompts: PromptTemplate[], warnings PromptTemplateWarning[] } getThemes(): { themes: Theme[], warnings: ThemeWarnings[] } getAgentsFiles(): { agentsFiles: { path: string, content: string }[] } getSystemPrompt(): string? getAppendSystemPrompt(): string[]? async reload(): ?? }

then we have a DefaultResourceLoader that implemnents our default semantics, people can subclass it, or wrap it?

and createAgentSession takes a ResourceLoader, and AgentSession exposes the ResourceLoader and has a reload() method that rewires everything, and possibly emits an event to tui or other parties when reloading has finished?

I want this to be as simple and clean as possible

Understood. Here is a cleaner proposal aligned with your ResourceLoader shape.

Proposed interfaces

export interface ResourceLoader {  getExtensions(): LoadExtensionsResult;  getSkills(): { skills: Skill[]; warnings: SkillWarning[] };  getPrompts(): { prompts: PromptTemplate[]; warnings: PromptTemplateWarning[] };  getThemes(): { themes: Theme[]; warnings: ThemeWarning[] };  getAgentsFiles(): { agentsFiles: Array<{ path: string; content: string }> };  getSystemPrompt(): string | undefined;  getAppendSystemPrompt(): string[]; // one or more fragments  reload(): Promise<void>;}

export interface ResourceLoader {  getExtensions(): LoadExtensionsResult;  getSkills(): { skills: Skill[]; warnings: SkillWarning[] };  getPrompts(): { prompts: PromptTemplate[]; warnings: PromptTemplateWarning[] };  getThemes(): { themes: Theme[]; warnings: ThemeWarning[] };  getAgentsFiles(): { agentsFiles: Array<{ path: string; content: string }> };  getSystemPrompt(): string | undefined;  getAppendSystemPrompt(): string[]; // one or more fragments  reload(): Promise<void>;}

Notes

LoadExtensionsResult is already part of core. We keep it.
PromptTemplateWarning and ThemeWarning do not exist. I can add them or return warnings: string[].
getAppendSystemPrompt returns string[] so multiple sources can contribute. Default loader will return zero or one entries based on APPEND_SYSTEM.md or CLI.
getSystemPrompt returns a resolved string or undefined.

DefaultResourceLoader behavior

On construction, receives cwd, agentDir, settingsManager, packageManager, and optional filters for --no-extensions and --no-skills.
reload recomputes all internal cached resources.
The getters return cached data from the last reload.
It follows your discovery rules for ~/.pi/agent and /.pi/ and merges with settings.json path arrays.

SDK and AgentSession changes

createAgentSession takes a ResourceLoader and calls reload once at startup, unless caller already did it.
AgentSession stores the loader and exposes it.
AgentSession.reload calls loader.reload, then rebuilds the session based on loader getters, emits session_start, and notifies listeners with a new event like resource_reload_end.

Open questions

Should ResourceLoader getters be sync as above or async. I prefer sync with cached state to keep mode code simple.
Should getAppendSystemPrompt return string[] or string. I prefer string[] for multiple sources.
Do you want a resource reload event type. If yes, name preference. I can add agent_session event like "resource_reload_end" or keep it as a method result.

If this is good, I will proceed and adjust the analysis for warnings types.

errors: Array<{ path: string; error: string }>

i think this shape is what we want for warnings/errors in general? maybe we just have warningsAndErrors, and add a type field "warning" | "error", an optional path (in case the resource wasn't laoded from disk), and a text: string?

Proposed unified diagnostics shape

export interface ResourceDiagnostic {  type: "warning" | "error";  message: string;  path?: string;}

export interface ResourceDiagnostic {  type: "warning" | "error";  message: string;  path?: string;}

ResourceLoader getters return { data, diagnostics } for each resource type, or we add a single getDiagnostics that aggregates them.

Example per resource:

This replaces skillWarnings and any future prompt or theme warnings.

Confirm if you want per resource diagnostics or one aggregated list.

DefaultResourceLoader behavior

On construction, receives cwd, agentDir, settingsManager, packageManager, and optional filters for --no-extensions and --no-skills.

note that we also have --extension and other cli flags that may add additional resources, no?

Yes. DefaultResourceLoader should take CLI overrides too.

Proposal

DefaultResourceLoader constructor accepts optional overrides:
- extensionSources: string[] for -e/--extension
- skillSources: string[] for --skills if we keep it
- promptSources: string[] if we add a flag later
- themeSources: string[] if we add a flag later
- systemPromptSource: string | undefined
- appendSystemPromptSources: string[]
- disableExtensions: boolean
- disableSkills: boolean

For now only extensionSources and disable flags are used by CLI. This keeps it extensible without more CLI flags.

Confirm if you want CLI to also accept explicit prompt, theme, skill sources.

does shouldn't be overrides though, should they be? the string[] at least, no? those are in addition to the auto discovery shit?

Agree. CLI lists should be additive.

Updated behavior

extensionSources, skillSources, promptSources, themeSources are appended to auto discovery and settings lists, with dedupe and conflict warnings.
disable flags still short circuit their respective resource type.

Confirm if you want --skills and --themes and --prompts flags to exist, or only extensions for now.

no aggreation, each getter returns diagnostics just for that resource tpe.

read @packages/coding-agent/src/cli/args.ts to see if we forgot something?

CLI args we need to update or remove

--skills currently exists and means glob filters. You want to drop include and ignore filters, so --skills should be repurposed or removed. I suggest removing it to avoid confusion, and keep only --no-skills. If you want --skills to mean explicit paths, we can repurpose it.
--extension remains as additive sources.
There are no flags for prompts or themes. If you want explicit CLI injection for those, we would add flags.

Proposal update for ResourceLoader + CLI

Remove --skills filtering flag. Update help.
Keep --no-skills and --no-extensions.
Keep --extension as additive source.

If you want to repurpose --skills to accept explicit paths, confirm and I will adjust parseArgs and help accordingly.

so, we already have --extension, i think we should have --skill (takes a SKILL.md) --theme (takes a theme.json) --prompt-template (takes a prompt template .md).

then we have --no-skills, --no-extensions --no-theme and --no-prompt-templates, and if we also specify --skill, --theme, --prompt-template, --extension, those get added back.

is that consistent?

Yes, consistent.

I will add:

--skill (repeatable)
--theme (repeatable)
--prompt-template (repeatable)

Disable flags:

--no-skills
--no-extensions
--no-themes
--no-prompt-templates

Behavior:

Disabled means skip auto discovery and settings sources for that type.
Explicit CLI sources are still added even when disabled, same as extensions.

If this is final, I will proceed to implementation.

not yet, we now still need to figure out how package manager factors into all of this.

in settings, or via --extension, what if a user specifics npm: or git:? what should happen?

We need to define how source specs are handled in two contexts: settings.json and CLI flags.

Proposed behavior

settings.json entries

Accept npm: and git: sources in extensions, skills, prompts, themes arrays.
PackageManager resolves those to local install paths.
Loader uses those resolved paths.

CLI flags

For --extension, --skill, --theme, --prompt-template:
- If path is a normal file or directory, use directly.
- If npm: or git:, we need to decide whether to auto install and where.

Open decisions A. Should CLI npm or git sources be auto installed into global locations, without touching settings.json.

This is consistent with using flags as temporary overrides.

B. Should CLI npm or git sources trigger a settings change, same as pi install.

This is consistent if you consider CLI flags as package management requests.

I suggest A for flags, B for install command. That keeps flags ephemeral and install explicit.

Please confirm:

For npm or git in settings.json, use PackageManager to install and resolve.
For npm or git in CLI flags, install into global or local cache without writing settings.json.

Also decide whether --skill, --prompt-template, --theme should accept npm or git or only filesystem paths. If we allow npm or git, the package must include pi field or follow auto discovery rules.

npm: and git: are only for extensions, which themselves then can contain extension entry points, skills, prompts, and themes

Understood.

Behavior update

npm: and git: sources are only valid for extensions.
Those packages can provide extension entry points, skills, prompts, and themes via pi field or auto discovery if no pi field.

This means --skill, --theme, --prompt-template only accept filesystem paths. Same for settings.json entries in skills, prompts, themes.

Anything else to finalize before implementation.

For npm or git in CLI flags, install into global or local cache without writing settings.json.

i think they should go into a /tmp folder just for that run?

the bigger question is: is package manager auto-invoked at any point? or is the user supposed to use the additional cli args to manually trigger pulling in an extension specified in settings.json?

Proposal

CLI npm or git

For --extension npm: or git:, install into a temp directory scoped to the process, for example /tmp/pi-extensions/.
No settings changes.

Auto invocation of PackageManager

Yes. When extensions in settings.json are npm: or git:, the default loader should ask PackageManager to resolve them. If missing, it installs automatically.
This mirrors current behavior where settings.json is the source of truth for what gets loaded, and pi should make it happen without extra commands.

Optional behavior

If install fails, surface a diagnostic and skip loading that source.
The install command exists for explicit management and updates.

Confirm if auto install on startup is acceptable, or if you want a prompt or a flag to opt out.

well, installing via package manager may take a while, so whoever constructs the default loader may also want to show visual feedback in the tui ... so we need a kind of progress thing.

We can add progress callbacks to PackageManager and ResourceLoader.

Proposal

PackageManager methods accept an optional progress callback:

type PackageProgress = { source: string; phase: "resolve" | "install" | "update" | "done"; message?: string };

type PackageProgress = { source: string; phase: "resolve" | "install" | "update" | "done"; message?: string };

DefaultResourceLoader accepts an optional onProgress callback. It passes that down to PackageManager and also emits its own phases for non package work.

Interactive mode can pass a handler that updates a loader or status line.

If you want, I can add a lightweight interface like:

interface ResourceLoaderProgress {  phase: "extensions" | "skills" | "prompts" | "themes" | "context" | "system" | "package";  message: string;}

interface ResourceLoaderProgress {  phase: "extensions" | "skills" | "prompts" | "themes" | "context" | "system" | "package";  message: string;}

Confirm which shape you want.

what does package manager do concretely? where does it put the things?

Concrete PackageManager behavior proposal

Global install locations

npm: use npm root -g to find global node_modules. If source is npm:@scope/pkg@1.2.3, install via npm install -g @scope/pkg@1.2.3, then resolve path via node_modules/@scope/pkg.
git: clone into ~/.pi/agent/git/<host>/<path>/<ref?> or similar. Use ~/.pi/agent/git/github.com/user/repo/ and checkout ref. If no ref, track default branch and update via fetch + reset.

Local install locations

Only used when explicitly requested by a future -l flag or via project settings. But you asked for npm root -g, so global is fine.

Temp installs for CLI flags

npm or git with --extension installs to /tmp/pi-extensions/ to avoid modifying settings.

Actions

resolve(source) returns local path and metadata. If missing, installs.
update(source) refreshes unpinned packages.

Pinning

npm: if @version, treat as pinned and update is no-op. If no version, update pulls latest.
git: if @tag or @commit, pinned. If no ref, update pulls latest default branch.

If this matches, I will proceed.

what does package manager return to the loader then? would it itself be a resource loader?

PackageManager is not a ResourceLoader. It is a dependency of DefaultResourceLoader.

PackageManager returns resolved paths for extension sources:

Given a source like npm:@foo/bar@1.2.3, it returns the absolute path to the installed package directory and metadata like version, pinned, source type.
Given git:github.com/user/repo@v1, it returns the checkout directory.
For local paths, it just returns the resolved path.

DefaultResourceLoader then applies extension discovery rules inside those directories, or uses pi field if present.

So the chain is: settings.json or CLI sources -> DefaultResourceLoader -> PackageManager.resolve -> resolved directories -> extension discovery -> ExtensionLoaderResult, skills, prompts, themes.

If you want PackageManager to expose a higher level helper like resolveExtensionSources to return arrays of paths, I can add that, but it still is not a ResourceLoader.

ok. what if the project local settings.json has npm in it? will that also be installed to the global npm modules?

With the current decision to use npm root -g, yes. Any npm: source in project settings would still install into the global npm modules directory.

If you want project settings to install into a project local cache instead, I can add a local mode. That would need a rule like: project settings use /.pi/npm/node_modules while global settings use npm root -g.

what did the original issue say about that?

Issue #645 specifies:

Global npm sources install to global node_modules via npm root -g.
Local (-l) installs go to <cwd>/.pi/npm/node_modules/.

So if we follow the issue, project settings would be local only when using the -l flag in install. Otherwise global.

ignore the -l flag and other shit we might add as an interface to the lci later. all that will do is modify the settings.json, either global or local. the rest will then be handled by the default "pipeline". no?

Yes. The CLI install or other management commands only mutate settings.json, either global or local. After that, the default loader pipeline handles resolve and install on startup or reload. With npm root -g, both global and project settings will install into the global node_modules path unless we introduce a separate local install location later.

soo, can we install to ./pi/npm/node_modules easily? in case we find a npm: extension in the project local settings.json?

Yes. Use npm install --prefix <cwd>/.pi/npm <pkg> and resolve path from <cwd>/.pi/npm/node_modules/<pkg>. We can detect origin of the source. If it comes from project settings, use local install dir. If it comes from global settings, use npm root -g.

Confirm if you want this split behavior now.

confirmed.

so back to when package-manager is triggered. read @packages/coding-agent/src/main.ts where in this flow would we do that? in the defaultresourceloader? which i guess we construct on startup to get extension cli flags?

Yes. The default ResourceLoader owns PackageManager and should be used in both passes.

Flow in main.ts:

First pass parse for --no-extensions and CLI extension sources.
Construct DefaultResourceLoader with settingsManager, packageManager, disable flags, and CLI sources.
Call loader.reload() to load extensions and collect flags.
Parse args again with extension flags.
Call loader.reload() again if the second pass changes anything relevant, or just update runtime flag values on the existing extensions result.
Pass the loader into createAgentSession.

This keeps the package manager inside the default loader and ensures it runs during the early extension flag discovery.

Confirm if you want step 5 to reuse the same loaded result or to reload after setting flags.

well, flags can't modify anything wrt to resources, can theyß

Extension flags do not affect resource loading. We can load once in the first pass, then only apply flag values to the runtime before creating the session. No second reload needed unless you want to re-read settings.json after parsing non extension flags.

ok, and a user of DefaultResourceLoader would not have to cnstruct their own package manager, correct?

Correct. DefaultResourceLoader should create and own its PackageManager internally. We can still accept an optional PackageManager for tests, but callers should not need to construct one.

alright. what about models.json? and keybindings.json? do we have more .json files that could live in ~/.pi/agent or /.pi? what do we have atm? i think resourceloader should handle all those things, no?

Clarifying resource loading scope

The ResourceLoader should focus on runtime session-related resources like extensions, skills, prompts, themes, agents, and system prompts, excluding models, keybindings, and auth config since they're outside session-loaded resources. Keybindings likely live in the keybindings manager and can be read there if needed, so checking keybindings.json with a read tool in that context makes sense for safety.

Clarifying ResourceLoader scope and config files

ResourceLoader should only handle session-visible resources like extensions, skills, prompts, themes, context, and system prompts. Core config files such as models.json, auth.json, keybindings.json, and settings.json belong elsewhere and are not managed by ResourceLoader.

Defining ownership of core config files

Models.json, auth.json, and keybindings.json are managed respectively by ModelRegistry, AuthStorage, and KeybindingsManager; ResourceLoader should not handle them.

Current config and data files

Global (~/.pi/agent):

settings.json
auth.json
models.json
keybindings.json
themes/*.json
prompts/*.md
skills/**/SKILL.md
extensions/*.ts or */index.ts or package.json with pi field
SYSTEM.md
APPEND_SYSTEM.md
AGENTS.md or CLAUDE.md
sessions/
bin/ (managed tools like fd, rg)
tools/ (custom tools storage)

Project (/.pi):

settings.json
extensions/
skills/
prompts/
themes/
SYSTEM.md
APPEND_SYSTEM.md

Project context files outside .pi:

AGENTS.md or CLAUDE.md in ancestor directories

Recommendation ResourceLoader should only handle runtime resources that affect the session prompt and extension system:

extensions
skills
prompts
themes
AGENTS.md context files
SYSTEM.md
APPEND_SYSTEM.md

It should not handle:

models.json and auth.json. Those are owned by ModelRegistry and AuthStorage.
keybindings.json. That is owned by KeybindingsManager.
sessions, bin, tools. Those are owned by SessionManager and tool management.

If you want ResourceLoader to handle settings.json too, that is a larger refactor. My suggestion is to keep settings in SettingsManager and let DefaultResourceLoader read from it.

no, that sounds good to me. alright, does it make sense to encode ALL our decisions above into a new comment on the issue 645 that describes everything in detail?

Yes. A single comment on #645 that consolidates the final design and decisions will prevent drift. If you want, I can post it as a structured checklist covering ResourceLoader API, DefaultResourceLoader behavior, package manager rules, settings layout, CLI flags, and reload flow.

do that please. i suggest you first write to a local file, then upload that as a comment via gh cli

Drafting concise issue comment

I'm preparing a clear technical comment listing key decisions: ResourceLoader interface, diagnostic updates, default discovery changes, merged settings arrays with conflict checks, new CLI flags replacing --skills filter, npm root and local install behavior, temp use for CLI npm/git in extensions, and the two-pass reload flow. I'll avoid em dashes and ornate language for clarity before saving and posting the comment via GitHub CLI.

Comment posted: https://github.com/badlogic/pi-mono/issues/645#issuecomment-3770700174

If you want any edits to the comment, say which parts to adjust.

could you implement this based on just that comment? i HIGHLY doubt that ... add all the detalis needed, so the comment is self-conatined, contains all shapes, all files you need to read and modify, etc.

Posted expanded comment: https://github.com/badlogic/pi-mono/issues/645#issuecomment-3770703260

If you want any adjustments, list them and I will update with a follow-up comment.