@agentxm/workspace-state 0.28.4-bootstrap.0

package/dist/src/workspace/read-model/agents/index.js

@@ -0,0 +1,45 @@
+/**
+ * Catalog-derived agent projections and the scoped agent read-model API.
+ *
+ * All agents share the same declared, actual, and detected projectors. The
+ * canonical capability catalog carries genuine per-agent variance, so adding
+ * an agent does not require a placeholder module or registry edit here.
+ */
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { AGENTS } from "@agentxm/extension-model/unstable/agents/registry";
+import { AGENT_IDS, CONFIGURABLE_AGENT_IDS, isConfigurableAgentId, } from "@agentxm/extension-model/unstable/agents/types";
+import { defineAgentModule, } from "./types.js";
+export { defineAgentModule } from "./types.js";
+/** Every configurable catalog agent, in canonical order. */
+export const registeredAgentModules = CONFIGURABLE_AGENT_IDS.map((agentId) => defineAgentModule({ agentId, descriptor: AGENTS[agentId] }));
+/** Build the common projector module for one catalog agent. */
+export const getAgentModule = (id) => defineAgentModule({ agentId: id, descriptor: AGENTS[id] });
+const isAgentId = (id) => Object.hasOwn(AGENTS, id);
+/** Build the agent portion of a scoped workspace read model. */
+export const makeScopedAgentsApi = (deps) => {
+    const { scope, settings, presence, observations } = deps;
+    const declared = (id) => isConfigurableAgentId(id)
+        ? settings.pipe(Effect.map((decoded) => getAgentModule(id).declared(scope, decoded)))
+        : Effect.succeed(Option.none());
+    const actual = (id) => isConfigurableAgentId(id)
+        ? observations.pipe(Effect.map((obs) => getAgentModule(id).actual(scope, obs)))
+        : Effect.succeed(Option.none());
+    const detected = Effect.all([
+        Effect.result(settings).pipe(Effect.map((settingsResult) => settingsResult._tag === "Failure"
+            ? Option.none()
+            : settingsResult.success)),
+        presence,
+        observations,
+    ]).pipe(Effect.map(([decoded, presentAgentIds, obs]) => Array.getSomes(registeredAgentModules.map((module) => module.detected(scope, module.declared(scope, decoded), presentAgentIds.has(module.agentId), module.actual(scope, obs))))));
+    return {
+        list: Effect.succeed(AGENT_IDS),
+        known: Effect.succeed(AGENT_IDS.map((id) => AGENTS[id])),
+        byId: (id) => (isAgentId(id) ? Option.some(AGENTS[id]) : Option.none()),
+        declared,
+        actual,
+        detected,
+    };
+};
+//# sourceMappingURL=index.js.map

package/dist/src/workspace/read-model/agents/shared.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared default projectors used by every per-agent module.
+ *
+ * The default behavior captures the v1 contract:
+ *
+ * - `defaultDeclared(agentId, scope, settings)` — returns
+ *   `Option.some(DeclaredAgent)` iff the decoded settings list the agent in
+ *   its `agents` array. Pure function over already-decoded settings.
+ * - `defaultActual(agentId, scope, observations)` — returns
+ *   `Option.some(ActualAgent)` iff at least one scanner observation refers to
+ *   the agent. Combines agent-dir, agent-settings, and per-agent MCP-config
+ *   evidence.
+ * - `defaultDetected(agentId, scope, declared, actual)` — combines the two
+ *   into a `DetectedAgent` when at least one is present; returns
+ *   `Option.none()` when both are absent (no evidence either way).
+ *
+ * Per-agent modules override these only if their native config requires
+ * agent-specific evidence rules. v1 modules all reuse these defaults.
+ */
+import * as Option from "effect/Option";
+import type { AgentId } from "@agentxm/extension-model/unstable/agents/types";
+import type { Scope } from "../types.js";
+import type { ActualAgent, AgentScannerObservations, DeclaredAgent, DeclaredSettingsShape, DetectedAgent } from "./types.js";
+export declare const defaultDeclared: (agentId: AgentId, scope: Scope, settings: Option.Option<DeclaredSettingsShape>) => Option.Option<DeclaredAgent>;
+export declare const defaultActual: (agentId: AgentId, scope: Scope, observations: AgentScannerObservations) => Option.Option<ActualAgent>;
+export declare const defaultDetected: (agentId: AgentId, scope: Scope, declared: Option.Option<DeclaredAgent>, present: boolean, actual: Option.Option<ActualAgent>) => Option.Option<DetectedAgent>;
+//# sourceMappingURL=shared.d.ts.map

package/dist/src/workspace/read-model/agents/shared.js

@@ -0,0 +1,63 @@
+/**
+ * Shared default projectors used by every per-agent module.
+ *
+ * The default behavior captures the v1 contract:
+ *
+ * - `defaultDeclared(agentId, scope, settings)` — returns
+ *   `Option.some(DeclaredAgent)` iff the decoded settings list the agent in
+ *   its `agents` array. Pure function over already-decoded settings.
+ * - `defaultActual(agentId, scope, observations)` — returns
+ *   `Option.some(ActualAgent)` iff at least one scanner observation refers to
+ *   the agent. Combines agent-dir, agent-settings, and per-agent MCP-config
+ *   evidence.
+ * - `defaultDetected(agentId, scope, declared, actual)` — combines the two
+ *   into a `DetectedAgent` when at least one is present; returns
+ *   `Option.none()` when both are absent (no evidence either way).
+ *
+ * Per-agent modules override these only if their native config requires
+ * agent-specific evidence rules. v1 modules all reuse these defaults.
+ */
+import * as Option from "effect/Option";
+export const defaultDeclared = (agentId, scope, settings) => {
+    if (Option.isNone(settings))
+        return Option.none();
+    const declaredAgents = settings.value.agents ?? [];
+    if (!declaredAgents.includes(agentId))
+        return Option.none();
+    return Option.some({ scope, agentId });
+};
+export const defaultActual = (agentId, scope, observations) => {
+    const agentDir = observations.agentDir.filter((occ) => occ.agentId === agentId &&
+        (occ.readPathStatus === undefined || occ.readPathStatus === "primary"));
+    const agentSettings = observations.agentSettings.filter((occ) => occ.agentId === agentId);
+    const mcpConfig = observations.mcpConfig.filter((occ) => occ.surface._tag === "agent" && occ.surface.agentId === agentId);
+    if (agentDir.length === 0 && agentSettings.length === 0 && mcpConfig.length === 0) {
+        return Option.none();
+    }
+    return Option.some({
+        scope,
+        agentId,
+        agentDirOccurrences: agentDir,
+        agentSettingsOccurrences: agentSettings,
+        mcpConfigOccurrences: mcpConfig,
+    });
+};
+export const defaultDetected = (agentId, scope, declared, present, actual) => {
+    const isDeclared = Option.isSome(declared);
+    const status = isDeclared && present
+        ? Option.some("managed-and-present")
+        : isDeclared
+            ? Option.some("managed-not-present")
+            : present
+                ? Option.some("unmanaged-present")
+                : Option.none();
+    return Option.map(status, (s) => ({
+        scope,
+        agentId,
+        status: s,
+        present,
+        declared,
+        actual,
+    }));
+};
+//# sourceMappingURL=shared.js.map

package/dist/src/workspace/read-model/agents/types.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Shared agent projection types used by the generated module registry.
+ *
+ * Per Decision 3 (agents have declared + actual only; no resolved layer) and
+ * Decision 4 (per-subject modules carry the genuine variance) of the
+ * workspace read-model design:
+ *
+ * - `DeclaredAgent` / `ActualAgent` / `DetectedAgent` are the per-agent
+ *   payload shapes the projectors return through `Option`.
+ * - `AgentModule<TId>` is the common projector contract generated from the
+ *   canonical agent catalog.
+ * - `AgentScannerObservations` is the input projector helpers consume from the
+ *   live composition (Phase 9). It carries the agent-specific slice of scanner
+ *   outputs — directly observable evidence that this agent has any presence in
+ *   the workspace.
+ *
+ * `AgentSubjectType` mirrors `scanners/types.ts#AgentDirSubjectType` so the
+ * agent registry barrel does not need to import scanner types at runtime.
+ */
+import type * as Option from "effect/Option";
+import type { AgentDescriptor, AgentId } from "@agentxm/extension-model/unstable/agents/types";
+import type { AgentDirOccurrence, AgentSettingsOccurrence, McpConfigOccurrence } from "../scanners/types.js";
+import type { Scope } from "../types.js";
+/**
+ * Subject types renderable into per-agent directories. Mirrors the
+ * `AgentDirSubjectType` discriminator on the agent-dir scanner. Per-agent
+ * modules expose the subjects they support so the registry barrel can answer
+ * "which subjects does this agent render?" without re-scanning the agent
+ * registry.
+ */
+export type AgentSubjectType = "skill" | "subagent";
+/**
+ * Settings-derived declaration of an agent for a given scope. Produced by the
+ * per-agent `declared(scope, settings)` projector when the scope's
+ * `axm.json` lists the agent in its `agents` array.
+ */
+export interface DeclaredAgent {
+    readonly scope: Scope;
+    readonly agentId: AgentId;
+}
+/**
+ * Observable per-agent evidence collected from scanner outputs. An agent is
+ * "actual present" in a scope if at least one scanner observation refers to
+ * that agent — agent-dir occurrences for any subject, an agent-settings file,
+ * or an agent MCP config. The projector collects the underlying observations
+ * so consumers can render diagnostic detail.
+ *
+ * The actual layer NEVER fails (Decision 1).
+ */
+export interface ActualAgent {
+    readonly scope: Scope;
+    readonly agentId: AgentId;
+    readonly agentDirOccurrences: ReadonlyArray<AgentDirOccurrence>;
+    readonly agentSettingsOccurrences: ReadonlyArray<AgentSettingsOccurrence>;
+    readonly mcpConfigOccurrences: ReadonlyArray<McpConfigOccurrence>;
+}
+/**
+ * Classification of an agent by combining declared + actual evidence. The
+ * three values mirror today's "managed agent" / "unmanaged agent" / "missing"
+ * classifications used by `axm setup` and lint diagnostics.
+ *
+ * - `managed-and-present` — settings declares the agent AND scanners observed
+ *   evidence in the workspace.
+ * - `managed-not-present` — settings declares the agent BUT no scanners
+ *   observed evidence.
+ * - `unmanaged-present` — scanners observed evidence BUT settings does not
+ *   declare the agent.
+ *
+ * Agents that are neither declared nor present are NOT included in the
+ * `detected` projection — there is nothing to surface for an agent the user
+ * has not interacted with.
+ */
+export type DetectionStatus = "managed-and-present" | "managed-not-present" | "unmanaged-present";
+export interface DetectedAgent {
+    readonly scope: Scope;
+    readonly agentId: AgentId;
+    readonly status: DetectionStatus;
+    readonly present: boolean;
+    readonly declared: Option.Option<DeclaredAgent>;
+    readonly actual: Option.Option<ActualAgent>;
+}
+/**
+ * Pre-filtered scanner observations for one agent. Phase 9's live composition
+ * narrows scanner outputs by `agentId` once and threads the result into each
+ * per-agent module's `actual` projector.
+ *
+ * Each array is the (possibly empty) sequence of observations for this agent
+ * within the same scope. Per design Decision 5, the actual layer concatenates
+ * scanner outputs — duplicates of the same physical occurrence are collapsed
+ * upstream by the scanner-occurrence-identity helper.
+ */
+export interface AgentScannerObservations {
+    readonly agentDir: ReadonlyArray<AgentDirOccurrence>;
+    readonly agentSettings: ReadonlyArray<AgentSettingsOccurrence>;
+    readonly mcpConfig: ReadonlyArray<McpConfigOccurrence>;
+}
+/**
+ * Subset of decoded `axm.json` the agent `declared` projectors need.
+ * Phase 8 modules accept this narrowed shape so they can be unit-tested
+ * without depending on the full Settings schema.
+ */
+export interface DeclaredSettingsShape {
+    readonly agents?: ReadonlyArray<AgentId>;
+}
+/**
+ * Common projector contract for one catalog agent. Agent-specific native
+ * configuration belongs in the capability catalog, not phantom read-model
+ * types.
+ */
+export interface AgentModule<TId extends AgentId = AgentId> {
+    readonly agentId: TId;
+    readonly subjects: ReadonlyArray<AgentSubjectType>;
+    readonly declared: (scope: Scope, settings: Option.Option<DeclaredSettingsShape>) => Option.Option<DeclaredAgent>;
+    readonly actual: (scope: Scope, observations: AgentScannerObservations) => Option.Option<ActualAgent>;
+    readonly detected: (scope: Scope, declared: Option.Option<DeclaredAgent>, present: boolean, actual: Option.Option<ActualAgent>) => Option.Option<DetectedAgent>;
+}
+/**
+ * Inputs to `defineAgentModule`. The factory derives `subjects` from the
+ * descriptor so registration does not repeat scanner-relevant subject data.
+ */
+export interface DefineAgentModuleInput<TId extends AgentId> {
+    readonly agentId: TId;
+    readonly descriptor: AgentDescriptor;
+}
+/**
+ * Build a complete `AgentModule` for `agentId`. The projectors call the v1
+ * `defaultDeclared` / `defaultActual` / `defaultDetected` helpers from
+ * `shared.ts`. `subjects` is derived from `descriptor`.
+ *
+ * The registry creates these modules directly from the canonical catalog.
+ */
+export declare const defineAgentModule: <TId extends AgentId>(input: DefineAgentModuleInput<TId>) => AgentModule<TId>;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/workspace/read-model/agents/types.js

@@ -0,0 +1,51 @@
+/**
+ * Shared agent projection types used by the generated module registry.
+ *
+ * Per Decision 3 (agents have declared + actual only; no resolved layer) and
+ * Decision 4 (per-subject modules carry the genuine variance) of the
+ * workspace read-model design:
+ *
+ * - `DeclaredAgent` / `ActualAgent` / `DetectedAgent` are the per-agent
+ *   payload shapes the projectors return through `Option`.
+ * - `AgentModule<TId>` is the common projector contract generated from the
+ *   canonical agent catalog.
+ * - `AgentScannerObservations` is the input projector helpers consume from the
+ *   live composition (Phase 9). It carries the agent-specific slice of scanner
+ *   outputs — directly observable evidence that this agent has any presence in
+ *   the workspace.
+ *
+ * `AgentSubjectType` mirrors `scanners/types.ts#AgentDirSubjectType` so the
+ * agent registry barrel does not need to import scanner types at runtime.
+ */
+import { defaultActual, defaultDeclared, defaultDetected } from "./shared.js";
+/**
+ * Derive the subjects the agent renders into per-agent directories from its
+ * descriptor.
+ */
+const subjectsFromDescriptor = (descriptor) => {
+    const out = [];
+    if (descriptor.skills !== undefined)
+        out.push("skill");
+    if (descriptor.subagents !== undefined)
+        out.push("subagent");
+    return out;
+};
+/**
+ * Build a complete `AgentModule` for `agentId`. The projectors call the v1
+ * `defaultDeclared` / `defaultActual` / `defaultDetected` helpers from
+ * `shared.ts`. `subjects` is derived from `descriptor`.
+ *
+ * The registry creates these modules directly from the canonical catalog.
+ */
+export const defineAgentModule = (input) => {
+    const { agentId, descriptor } = input;
+    const subjects = subjectsFromDescriptor(descriptor);
+    return {
+        agentId,
+        subjects,
+        declared: (scope, settings) => defaultDeclared(agentId, scope, settings),
+        actual: (scope, observations) => defaultActual(agentId, scope, observations),
+        detected: (scope, declared, present, actual) => defaultDetected(agentId, scope, declared, present, actual),
+    };
+};
+//# sourceMappingURL=types.js.map

package/dist/src/workspace/read-model/diagnostics.d.ts

@@ -0,0 +1,18 @@
+/** Per-scope append-only diagnostics buffer for settings/lockfile/scanner warnings. */
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+/** A degraded-state observation surfaced through a scoped diagnostics buffer. */
+export interface Warning {
+    readonly source: "settings" | "lockfile" | "scanner";
+    readonly message: string;
+    readonly path?: string;
+    readonly code?: string;
+}
+/** Append-only, snapshot-readable warning buffer for one scoped workspace read model. */
+export interface Diagnostics {
+    readonly append: (warning: Warning) => Effect.Effect<void>;
+    readonly snapshot: Effect.Effect<ReadonlyArray<Warning>>;
+}
+/** Build a `Diagnostics` helper around a caller-owned `Ref<ReadonlyArray<Warning>>`. */
+export declare const makeDiagnostics: (ref: Ref.Ref<ReadonlyArray<Warning>>) => Diagnostics;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/src/workspace/read-model/diagnostics.js

@@ -0,0 +1,14 @@
+/** Per-scope append-only diagnostics buffer for settings/lockfile/scanner warnings. */
+import * as Effect from "effect/Effect";
+import * as Ref from "effect/Ref";
+/** Build a `Diagnostics` helper around a caller-owned `Ref<ReadonlyArray<Warning>>`. */
+export const makeDiagnostics = (ref) => ({
+    append: Effect.fn("workspace.read-model.diagnostics.append")(function* (warning) {
+        yield* Ref.update(ref, (current) => [...current, warning]);
+    }),
+    snapshot: Effect.gen(function* () {
+        const current = yield* Ref.get(ref);
+        return current;
+    }).pipe(Effect.withSpan("workspace.read-model.diagnostics.snapshot")),
+});
+//# sourceMappingURL=diagnostics.js.map

package/dist/src/workspace/read-model/discovery/index.d.ts

@@ -0,0 +1,5 @@
+/** Discovery helpers that operate on arbitrary source directories. */
+export { getPriorityDirectories, skillsInDir, type DiscoveredSkill, type DiscoveryOptions, } from "./skills.js";
+export { parsePluginManifests } from "./plugin-manifests.js";
+export { scanAgentSubagentFiles, scanAllSubagentFiles, type AgentSubagentSummary, type DetectedSubagentFile, } from "./subagents.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/src/workspace/read-model/discovery/index.js

@@ -0,0 +1,5 @@
+/** Discovery helpers that operate on arbitrary source directories. */
+export { getPriorityDirectories, skillsInDir, } from "./skills.js";
+export { parsePluginManifests } from "./plugin-manifests.js";
+export { scanAgentSubagentFiles, scanAllSubagentFiles, } from "./subagents.js";
+//# sourceMappingURL=index.js.map

package/dist/src/workspace/read-model/discovery/plugin-manifests.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Plugin manifest parsing for skill discovery.
+ *
+ * Parses .claude-plugin/marketplace.json and .claude-plugin/plugin.json
+ * to discover explicitly declared skill directories.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Effect from "effect/Effect";
+/**
+ * Parse plugin manifests and return validated skill parent directories.
+ * All paths are validated to be within basePath.
+ * Errors are silently skipped (returns empty array on failure).
+ */
+export declare const parsePluginManifests: (basePath: string) => Effect.Effect<ReadonlyArray<string>, never, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=plugin-manifests.d.ts.map

package/dist/src/workspace/read-model/discovery/plugin-manifests.js

@@ -0,0 +1,168 @@
+/**
+ * Plugin manifest parsing for skill discovery.
+ *
+ * Parses .claude-plugin/marketplace.json and .claude-plugin/plugin.json
+ * to discover explicitly declared skill directories.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import * as Array from "effect/Array";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import * as Result from "effect/Result";
+import * as Schema from "effect/Schema";
+// -----------------------------------------------------------------------------
+// Path Validation
+// -----------------------------------------------------------------------------
+const RelativeManifestPathSchema = Schema.String.pipe(Schema.check(Schema.makeFilter((input) => {
+    if (!input.startsWith("./"))
+        return "Expected a relative manifest path starting with ./";
+    if (input.includes(".."))
+        return "Manifest paths must not contain .. segments";
+    return undefined;
+})));
+const decodeRelativeManifestPath = Schema.decodeUnknownResult(RelativeManifestPathSchema);
+/**
+ * Validate a raw skill path from a manifest.
+ * Must start with `./`, must not contain `..`, and must resolve within basePath.
+ * Returns the parent directory of the skill path on success.
+ */
+const validatePath = (rawPath, basePath, path) => {
+    if (Result.isFailure(decodeRelativeManifestPath(rawPath)))
+        return Option.none();
+    // Resolve and check within basePath
+    const resolved = path.resolve(basePath, rawPath);
+    const normalizedBase = path.resolve(basePath);
+    if (!resolved.startsWith(normalizedBase + path.sep) && resolved !== normalizedBase) {
+        return Option.none();
+    }
+    // Return parent directory of the skill path
+    return Option.some(path.dirname(resolved));
+};
+// -----------------------------------------------------------------------------
+// Manifest Parsers
+// -----------------------------------------------------------------------------
+const MarketplacePlugin = Schema.Struct({
+    source: Schema.optional(Schema.Unknown),
+    skills: Schema.optional(Schema.Array(Schema.String)),
+});
+const MarketplaceManifest = Schema.Struct({
+    metadata: Schema.optional(Schema.Struct({ pluginRoot: Schema.optional(Schema.String) })),
+    plugins: Schema.Array(MarketplacePlugin),
+});
+const PluginManifest = Schema.Struct({
+    skills: Schema.Array(Schema.String),
+});
+/**
+ * Read a file and parse as JSON, returning None on any failure.
+ */
+const readDecodedJsonFile = (filePath, schema) => Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const content = yield* fs.readFileString(filePath).pipe(Effect.option);
+    if (Option.isNone(content))
+        return Option.none();
+    const decode = Schema.decodeUnknownSync(Schema.fromJsonString(schema));
+    return yield* Effect.sync(() => {
+        try {
+            return Option.some(decode(content.value));
+        }
+        catch {
+            return Option.none();
+        }
+    });
+});
+/**
+ * Validate a directory path from a manifest (not a skill path — no dirname).
+ * Must start with `./`, must not contain `..`, and must resolve within basePath.
+ * Returns the resolved directory path on success.
+ */
+const validateDirPath = (rawPath, basePath, path) => {
+    if (Result.isFailure(decodeRelativeManifestPath(rawPath)))
+        return Option.none();
+    const resolved = path.resolve(basePath, rawPath);
+    const normalizedBase = path.resolve(basePath);
+    if (!resolved.startsWith(normalizedBase + path.sep) && resolved !== normalizedBase) {
+        return Option.none();
+    }
+    return Option.some(resolved);
+};
+/**
+ * Resolve a plugin's base directory from its source field and pluginRoot.
+ * - string source: must start with `./`, resolve relative to basePath + pluginRoot
+ * - omitted source: resolve to basePath + pluginRoot (or basePath if no pluginRoot)
+ * - object source: skip (remote plugin)
+ */
+const resolvePluginBase = (source, basePath, pluginRoot, path) => {
+    const rootBase = pluginRoot ? path.resolve(basePath, pluginRoot) : path.resolve(basePath);
+    // Object source → skip plugin
+    if (typeof source === "object" && source !== null)
+        return Option.none();
+    if (typeof source === "string") {
+        return validateDirPath(source, rootBase, path);
+    }
+    // Omitted source → root-level plugin
+    return Option.some(rootBase);
+};
+/**
+ * Parse .claude-plugin/marketplace.json and return validated skill parent directories.
+ *
+ * Supports metadata.pluginRoot, per-plugin source (string/omitted/object),
+ * per-plugin skills array, and conventional {pluginBase}/skills/ directory.
+ */
+const parseMarketplaceJson = (basePath) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const manifestPath = path.join(basePath, ".claude-plugin", "marketplace.json");
+    const data = yield* readDecodedJsonFile(manifestPath, MarketplaceManifest);
+    if (Option.isNone(data))
+        return [];
+    const pluginRoot = data.value.metadata?.pluginRoot;
+    if (pluginRoot !== undefined && Result.isFailure(decodeRelativeManifestPath(pluginRoot))) {
+        return [];
+    }
+    return data.value.plugins.flatMap((plugin) => {
+        const pluginBase = resolvePluginBase(plugin.source, basePath, pluginRoot, path);
+        if (Option.isNone(pluginBase))
+            return [];
+        // Conventional {pluginBase}/skills/ always added
+        const conventional = [path.join(pluginBase.value, "skills")];
+        // Explicit skill paths transformed via dirname
+        const explicit = (plugin.skills ?? []).flatMap((skillPath) => {
+            const validated = validatePath(skillPath, pluginBase.value, path);
+            return Option.isSome(validated) ? [validated.value] : [];
+        });
+        return [...conventional, ...explicit];
+    });
+});
+/**
+ * Parse .claude-plugin/plugin.json and return validated skill parent directories.
+ *
+ * Expected shape: { skills: string[] }
+ */
+const parsePluginJson = (basePath) => Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const manifestPath = path.join(basePath, ".claude-plugin", "plugin.json");
+    const data = yield* readDecodedJsonFile(manifestPath, PluginManifest);
+    if (Option.isNone(data))
+        return [];
+    const validatedPaths = [];
+    for (const skillPath of data.value.skills) {
+        const validated = validatePath(skillPath, basePath, path);
+        if (Option.isSome(validated)) {
+            validatedPaths.push(validated.value);
+        }
+    }
+    return validatedPaths;
+});
+// -----------------------------------------------------------------------------
+// Public API
+// -----------------------------------------------------------------------------
+/**
+ * Parse plugin manifests and return validated skill parent directories.
+ * All paths are validated to be within basePath.
+ * Errors are silently skipped (returns empty array on failure).
+ */
+export const parsePluginManifests = (basePath) => Effect.gen(function* () {
+    const [marketplaceDirs, pluginDirs] = yield* Effect.all([parseMarketplaceJson(basePath), parsePluginJson(basePath)], { concurrency: "unbounded" });
+    return Array.dedupe([...marketplaceDirs, ...pluginDirs]);
+});
+//# sourceMappingURL=plugin-manifests.js.map

package/dist/src/workspace/read-model/discovery/skills.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Skill discovery algorithm (3-phase: direct match, priority scan, recursive fallback).
+ *
+ * The `skillsInDir` function is used by source providers (local, git-hosting)
+ * to discover skills within a directory structure.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+import * as FileSystem from "effect/FileSystem";
+import * as Path from "effect/Path";
+import type { Skill } from "@agentxm/registry-protocol/unstable/content/skill-types";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
+import { SkillDiscoveryRootInvalid } from "../errors.js";
+/**
+ * A discovered skill — intermediate result from directory scanning.
+ *
+ * Does not carry source, version, or gitTreeSha — the caller (provider)
+ * enriches with those after discovery.
+ */
+export interface DiscoveredSkill {
+    readonly type: "skill";
+    readonly skill: Skill;
+    /** file:// URL to the skill directory */
+    readonly location: string;
+}
+/**
+ * Options controlling discovery behavior.
+ */
+export interface DiscoveryOptions {
+    /** Exhaustive recursive search even if root skill found */
+    readonly fullDepth: boolean;
+    /** Include skills with metadata.internal: "true" */
+    readonly includeInternal: boolean;
+}
+/**
+ * Derive the full Phase 2 priority directory list.
+ *
+ * Composition:
+ * 1. `.` (searchPath root) — always first, highest priority
+ * 2. Non-agent static dirs: skills, skills/.curated, skills/.experimental, skills/.system
+ * 3. Agent dirs: unique primary and additional read paths from the AgentDescriptor registry
+ */
+export declare const getPriorityDirectories: () => ReadonlyArray<string>;
+/**
+ * Discover skills in a directory using a 3-phase algorithm:
+ *
+ * Phase 1 — Direct match: check if search root itself contains SKILL.md
+ * Phase 2 — Priority directory scan: scan well-known directories one level deep
+ * Phase 3 — Recursive fallback: bounded DFS when prior phases find nothing or fullDepth is true
+ *
+ * Skills are deduplicated by name (first-found wins). Internal skills are
+ * filtered unless opted in.
+ *
+ * @experimental This API is unstable and may change without notice.
+ */
+export declare const skillsInDir: (basePath: string, subPath: Option.Option<string>, options: DiscoveryOptions) => Effect.Effect<ReadonlyArray<DiscoveredSkill>, SkillDiscoveryRootInvalid, FileSystem.FileSystem | Path.Path>;
+//# sourceMappingURL=skills.d.ts.map