@gajae-code/coding-agent 0.1.1

package/src/defaults/gjc/skills/ultragoal/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: ultragoal
+description: Create and execute durable repo-native multi-goal plans over GJC goal mode artifacts.
+
+source: "forked from upstream ultragoal skill and rebranded for GJC"
+---
+
+# Ultragoal Workflow
+
+Use when the user asks for `ultragoal`, `create-goals`, `complete-goals`, durable multi-goal planning, or sequential execution over GJC goal mode.
+
+## Purpose
+
+`ultragoal` turns a brief into repo-native artifacts and then drives a GJC goal safely through the named goal tools: `get_goal`, `create_goal`, and `update_goal`. New plans default to a stable pointer-style aggregate GJC goal for the whole durable plan in `.gjc/ultragoal/goals.json`, including later accepted/appended stories under the original brief constraints, while GJC tracks G001/G002 story progress in the ledger. Ultragoal does not call `/goal clear`; before multiple sequential ultragoal runs in one session/thread, manually run `/goal clear` in the UI so the previous completed aggregate goal does not block or confuse the next `create_goal`.
+
+- `.gjc/ultragoal/brief.md`
+- `.gjc/ultragoal/goals.json`
+- `.gjc/ultragoal/ledger.jsonl` (checkpoint and structured steering audit events)
+
+Existing aggregate plans with the legacy enumerated objective are migrated to the stable pointer objective on read, persisted to `goals.json`, retained in `gjcObjectiveAliases` for already-active hidden goal reconciliation, and audited with an `aggregate_objective_migrated` ledger entry.
+
+## Always-used command examples
+
+Use these exact `gjc ultragoal` commands before spending tool calls rediscovering syntax:
+
+```sh
+gjc ultragoal status
+gjc ultragoal status --json
+gjc ultragoal create-goals --brief "<brief>"
+gjc ultragoal create-goals --brief-file <path>
+gjc ultragoal complete-goals
+gjc ultragoal complete-goals --retry-failed
+gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --gjc-goal-json <get-goal-json-or-path>
+gjc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"
+gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve final review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --gjc-goal-json <active-get-goal-json-or-path>
+```
+
+Use these exact goal-tool calls for the inline goal state:
+
+```json
+get_goal({})
+create_goal({"objective":"<printed aggregate or per-story objective>"})
+update_goal({"status":"complete"})
+```
+
+`get_goal`, `create_goal`, and `update_goal` share the same session goal state as `/goal`; prefer these named tools inside Ultragoal because they produce JSON snapshots for ledger reconciliation.
+
+
+## Create goals
+
+1. Run one of:
+   - `gjc ultragoal create-goals --brief "<brief>"`
+   - `gjc ultragoal create-goals --brief-file <path>`
+   - `cat <brief> | gjc ultragoal create-goals --from-stdin`
+   - `gjc ultragoal create-goals --gjc-goal-mode per-story --brief "<brief>"` only when one GJC goal context per story is explicitly preferred
+2. Inspect `.gjc/ultragoal/goals.json` and refine if needed.
+
+## Complete goals
+
+Loop until `gjc ultragoal status` reports all goals complete:
+
+1. Run `gjc ultragoal complete-goals`.
+2. Read the printed handoff.
+3. Call `get_goal({})`.
+4. If no active GJC goal exists, call `create_goal({"objective":"<printed payload objective>"})` with the printed payload. In aggregate mode, if the same aggregate objective is already active, continue the current GJC story without creating a new GJC goal.
+5. Complete the current GJC story only.
+6. Run a completion audit against the story objective and real artifacts/tests.
+7. In aggregate mode, do **not** call `update_goal` for intermediate stories; checkpoint with a fresh `get_goal({})` snapshot whose aggregate objective is still `active`. On the final story only, first run the mandatory final cleanup/review gate below; call `update_goal({"status":"complete"})` only after that gate is clean, then call `get_goal({})` again for a fresh `complete` snapshot.
+8. Checkpoint the durable ledger with that snapshot. Intermediate aggregate checkpoints use only `--gjc-goal-json`; final clean checkpoints also require `--quality-gate-json`:
+   `gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<evidence>" --gjc-goal-json <get_goal-json-or-path> [--quality-gate-json <quality-gate-json-or-path>]`
+9. If blocked or failed, checkpoint failure:
+   `gjc ultragoal checkpoint --goal-id <id> --status failed --evidence "<blocker/evidence>"`
+10. For legacy per-story completed-goal blockers, preserve the non-terminal blocker with:
+   `gjc ultragoal checkpoint --goal-id <id> --status blocked --evidence "<completed legacy GJC goal blocks create_goal in this thread>" --gjc-goal-json <get_goal-json-or-path>`
+11. Resume failed goals with `gjc ultragoal complete-goals --retry-failed`.
+
+## Dynamic steering
+
+Use `gjc ultragoal steer` when real findings or blockers prove the current story decomposition should change while the aggregate objective and constraints stay fixed. Steering is explicit-only and evidence-backed; broad natural-language requests are rejected instead of guessed.
+
+Allowed mutation kinds are:
+
+- `add_subgoal`
+- `split_subgoal`
+- `reorder_pending`
+- `revise_pending_wording`
+- `annotate_ledger`
+- `mark_blocked_superseded`
+
+Examples:
+
+```sh
+gjc ultragoal steer --kind add_subgoal --title "Investigate blocker" --objective "Validate the blocker and report evidence." --evidence "log/test output" --rationale "The blocker changes the safe execution order." --json
+gjc ultragoal steer --directive-json ./steering.json --json
+```
+
+Steering invariants:
+
+- Do not edit the aggregate goal objective, original brief constraints, quality gates, or completion status. The aggregate objective is a stable pointer to `.gjc/ultragoal/goals.json` and `.gjc/ultragoal/ledger.jsonl`, not an enumeration of initial goal ids.
+- Do not hard-delete goals, auto-complete work, weaken verification, or silently mutate `.gjc/ultragoal`.
+- Accepted and rejected attempts append structured audit entries to `.gjc/ultragoal/ledger.jsonl`.
+- Superseded goals remain in `goals.json` with steering metadata and are skipped for scheduling.
+- Blocked goals without replacements are skipped for scheduling but still block final completion until later explicit steering replaces or supersedes them.
+
+UserPromptSubmit uses the same steering API only for structured directives such as `GJC_ULTRAGOAL_STEER: { ... }`, `gjc.ultragoal.steer: { ... }`, or `gjc ultragoal steer: { ... }`. Normal prose does not mutate state, and repeated prompt-submit directives dedupe by prompt signature or idempotency key.
+
+
+## Role-agent delegation guidance
+
+Ultragoal execution should use GJC's bundled role-agent roster when a durable story is large enough to benefit from delegation:
+
+- Use `executor` for bounded implementation, refactoring, and fix slices.
+- Use `planner` for story sequencing or handoff refinement when execution uncovers a missing plan branch.
+- Use `architect` for read-only architecture and code-review lanes, including `CLEAR` / `WATCH` / `BLOCK` status.
+- Use `critic` for read-only plan or handoff critique before execution proceeds.
+
+When delegating with native subagents, an await timeout only limits the leader's wait. It is not subagent failure evidence and must not be used as a cancellation reason; inspect or continue independent work, and cancel only when the subagent has actually failed, gone off-track, or become unrecoverably wrong.
+
+If an Ultragoal request has no approved plan or consensus artifact, run `ralplan` first and preserve its PRD, test spec, role roster, and verification guidance in the Ultragoal ledger. Do not silently substitute ad-hoc execution for missing planning.
+
+The Ultragoal leader owns `.gjc/ultragoal/goals.json` and `.gjc/ultragoal/ledger.jsonl`. Role agents return implementation/review evidence; they do not checkpoint Ultragoal or mutate goal state.
+
+## Use Ultragoal and Team together
+
+Use ultragoal and team together for a durable Ultragoal story that benefits from one visible tmux worker session. Ultragoal remains leader-owned: `.gjc/ultragoal/goals.json` stores the story plan and `.gjc/ultragoal/ledger.jsonl` stores checkpoints. Team is the single-worker tmux execution engine and returns task/evidence status to the leader.
+
+The leader checkpoints Ultragoal from Team evidence with a fresh `get_goal` snapshot:
+
+```sh
+gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evidence mentioning .gjc/ultragoal and <id>>" --gjc-goal-json <fresh-get_goal-json-or-path>
+```
+
+Workers do not own ultragoal goal state, do not create worker ultragoal ledgers, and do not checkpoint Ultragoal. Team launch remains explicit; Ultragoal does not auto-launch Team and performs no hidden goal mutation.
+
+## Mandatory final cleanup and review gate
+
+The final ultragoal story is not complete until the active agent has run the final quality gate:
+
+1. Run targeted verification for the story.
+2. Run a cleanup/refactor review pass on changed files only; if there are no relevant edits, the cleaner still runs and records a passed/no-op report.
+3. Rerun verification after the cleaner pass.
+4. Run a final code review pass. Clean means `codeReview.recommendation: "APPROVE"` and `codeReview.architectStatus: "CLEAR"`; `COMMENT`, `WATCH`, `REQUEST CHANGES`, and `BLOCK` are non-clean.
+5. If review is non-clean, do **not** call `update_goal`. Record durable blocker work instead:
+
+   ```sh
+   gjc ultragoal record-review-blockers --goal-id <id> --title "Resolve final review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --gjc-goal-json <active-get-goal-json-or-path>
+   ```
+
+   This marks the current story `review_blocked`, appends a pending blocker-resolution story, keeps the GJC goal active, and lets `gjc ultragoal complete-goals` start the blocker next. In legacy per-story mode, the blocker may need an available GJC goal context because the old per-story GJC goal remains active/incomplete.
+
+6. If review is clean, call `update_goal({"status":"complete"})`, call `get_goal({})`, and checkpoint with a structured final gate:
+
+   ```sh
+   gjc ultragoal checkpoint --goal-id <id> --status complete --evidence "<tests/files/review evidence>" --gjc-goal-json <fresh-complete-get-goal-json-or-path> --quality-gate-json <quality-gate-json-or-path>
+   ```
+
+`--quality-gate-json` must include:
+
+```json
+{
+  "aiSlopCleaner": { "status": "passed", "evidence": "cleaner report" },
+  "verification": { "status": "passed", "commands": ["npm test"], "evidence": "post-cleaner verification" },
+  "codeReview": { "recommendation": "APPROVE", "architectStatus": "CLEAR", "evidence": "final review synthesis" }
+}
+```
+
+## Constraints
+
+- The shell command cannot directly invoke interactive `/goal`; it emits a model-facing handoff for the active GJC agent.
+- Ultragoal intentionally does not invoke `/goal clear` or hidden `thread/goal/clear`; use only the named goal-tool surface: `get_goal`, `create_goal`, and `update_goal`.
+- After a completed aggregate ultragoal run, clear the goal manually with `/goal clear` before starting another ultragoal run in the same session/thread.
+- Never call `create_goal` when `get_goal` reports a different active goal.
+- Never call `update_goal` unless the aggregate run or legacy per-story goal is actually complete.
+- In aggregate mode, intermediate story checkpoints require a matching `active` GJC goal snapshot; final story completion requires a matching `complete` snapshot after `update_goal`.
+- Completion checkpoints require read-only goal snapshot reconciliation: pass fresh `get_goal` JSON/path with `--gjc-goal-json`; shell commands and hooks must not mutate goal state.
+- Treat `ledger.jsonl` as the durable audit trail; checkpoint after every success or failure.

package/src/defaults/gjc-defaults.ts

@@ -0,0 +1,151 @@
+import * as path from "node:path";
+import { getAgentDir, isEnoent, parseFrontmatter } from "@gajae-code/utils";
+import deepInterviewSkill from "./gjc/skills/deep-interview/SKILL.md" with { type: "text" };
+import ralplanSkill from "./gjc/skills/ralplan/SKILL.md" with { type: "text" };
+import teamSkill from "./gjc/skills/team/SKILL.md" with { type: "text" };
+import ultragoalSkill from "./gjc/skills/ultragoal/SKILL.md" with { type: "text" };
+
+export const DEFAULT_GJC_DEFINITION_NAMES = ["deep-interview", "ralplan", "team", "ultragoal"] as const;
+export type DefaultGjcDefinitionName = (typeof DEFAULT_GJC_DEFINITION_NAMES)[number];
+export type DefaultGjcDefinitionKind = "skill";
+export type EmbeddedDefaultGjcSkill = {
+	name: DefaultGjcDefinitionName;
+	description: string;
+	filePath: string;
+	baseDir: string;
+	source: "bundled:default";
+	hide?: boolean;
+	content: string;
+};
+export type DefaultGjcInstallStatus = "different" | "matching" | "missing" | "skipped" | "written";
+
+export interface DefaultGjcDefinition {
+	kind: DefaultGjcDefinitionKind;
+	name: DefaultGjcDefinitionName;
+	relativePath: string;
+	content: string;
+}
+
+export interface InstallDefaultGjcDefinitionsOptions {
+	check?: boolean;
+	force?: boolean;
+	targetRoot?: string;
+}
+
+export interface DefaultGjcDefinitionInstallFile {
+	kind: DefaultGjcDefinitionKind;
+	name: DefaultGjcDefinitionName;
+	path: string;
+	status: DefaultGjcInstallStatus;
+}
+
+export interface DefaultGjcDefinitionInstallResult {
+	targetRoot: string;
+	total: number;
+	written: number;
+	skipped: number;
+	matching: number;
+	missing: number;
+	different: number;
+	files: DefaultGjcDefinitionInstallFile[];
+}
+
+const DEFAULT_GJC_DEFINITIONS: readonly DefaultGjcDefinition[] = [
+	{
+		kind: "skill",
+		name: "deep-interview",
+		relativePath: "skills/deep-interview/SKILL.md",
+		content: deepInterviewSkill,
+	},
+	{ kind: "skill", name: "ralplan", relativePath: "skills/ralplan/SKILL.md", content: ralplanSkill },
+	{ kind: "skill", name: "team", relativePath: "skills/team/SKILL.md", content: teamSkill },
+	{ kind: "skill", name: "ultragoal", relativePath: "skills/ultragoal/SKILL.md", content: ultragoalSkill },
+];
+
+export function getDefaultGjcDefinitions(): readonly DefaultGjcDefinition[] {
+	return DEFAULT_GJC_DEFINITIONS;
+}
+
+export function getDefaultGjcAgentDefinitions(): readonly DefaultGjcDefinition[] {
+	return [];
+}
+
+export function getEmbeddedDefaultGjcSkills(): EmbeddedDefaultGjcSkill[] {
+	return DEFAULT_GJC_DEFINITIONS.filter(definition => definition.kind === "skill").map(definition => {
+		const { frontmatter } = parseFrontmatter(definition.content, {
+			source: `embedded:gjc/${definition.relativePath}`,
+			level: "warn",
+		});
+		const description =
+			typeof frontmatter.description === "string" ? frontmatter.description : `GJC ${definition.name} workflow`;
+		return {
+			name: definition.name,
+			description,
+			filePath: `embedded:gjc/${definition.relativePath}`,
+			baseDir: `embedded:gjc/skills/${definition.name}`,
+			source: "bundled:default",
+			hide: frontmatter.hide === true,
+			content: definition.content,
+		};
+	});
+}
+
+export async function installDefaultGjcDefinitions(
+	options: InstallDefaultGjcDefinitionsOptions = {},
+): Promise<DefaultGjcDefinitionInstallResult> {
+	const targetRoot = options.targetRoot ?? getAgentDir();
+	const files: DefaultGjcDefinitionInstallFile[] = [];
+
+	for (const definition of DEFAULT_GJC_DEFINITIONS) {
+		const destination = path.join(targetRoot, definition.relativePath);
+		const existing = await readExistingText(destination);
+		let status: DefaultGjcInstallStatus;
+
+		if (options.check) {
+			status = existing === undefined ? "missing" : existing === definition.content ? "matching" : "different";
+		} else if (existing !== undefined && !options.force) {
+			status = "skipped";
+		} else {
+			await Bun.write(destination, definition.content);
+			status = "written";
+		}
+
+		files.push({
+			kind: definition.kind,
+			name: definition.name,
+			path: destination,
+			status,
+		});
+	}
+
+	return summarizeInstallResult(targetRoot, files);
+}
+
+async function readExistingText(filePath: string): Promise<string | undefined> {
+	try {
+		return await Bun.file(filePath).text();
+	} catch (error) {
+		if (isEnoent(error)) return undefined;
+		throw error;
+	}
+}
+
+function summarizeInstallResult(
+	targetRoot: string,
+	files: DefaultGjcDefinitionInstallFile[],
+): DefaultGjcDefinitionInstallResult {
+	return {
+		targetRoot,
+		total: files.length,
+		written: countStatus(files, "written"),
+		skipped: countStatus(files, "skipped"),
+		matching: countStatus(files, "matching"),
+		missing: countStatus(files, "missing"),
+		different: countStatus(files, "different"),
+		files,
+	};
+}
+
+function countStatus(files: readonly DefaultGjcDefinitionInstallFile[], status: DefaultGjcInstallStatus): number {
+	return files.filter(file => file.status === status).length;
+}

package/src/discovery/agents-md.ts

@@ -0,0 +1,67 @@
+/**
+ * AGENTS.md Provider
+ *
+ * Discovers standalone AGENTS.md files by walking up from cwd.
+ * This handles AGENTS.md files that live in project root (not in config directories
+ * like .OpenAI code backend/ or .gemini/, which are handled by their respective providers).
+ */
+import * as path from "node:path";
+import { registerProvider } from "../capability";
+import { type ContextFile, contextFileCapability } from "../capability/context-file";
+import { readFile } from "../capability/fs";
+import type { LoadContext, LoadResult } from "../capability/types";
+import { calculateDepth, createSourceMeta } from "./helpers";
+
+const PROVIDER_ID = "agents-md";
+const DISPLAY_NAME = "AGENTS.md";
+
+/**
+ * Load standalone AGENTS.md files.
+ */
+async function loadAgentsMd(ctx: LoadContext): Promise<LoadResult<ContextFile>> {
+	const items: ContextFile[] = [];
+	const warnings: string[] = [];
+
+	// Walk up from cwd looking for AGENTS.md files
+	let current = ctx.cwd;
+
+	while (true) {
+		const candidate = path.join(current, "AGENTS.md");
+		const content = await readFile(candidate);
+
+		if (content !== null) {
+			const parent = path.dirname(candidate);
+			const baseName = parent.split(path.sep).pop() ?? "";
+
+			if (!baseName.startsWith(".")) {
+				const fileDir = path.dirname(candidate);
+				const calculatedDepth = calculateDepth(ctx.cwd, fileDir, path.sep);
+
+				items.push({
+					path: candidate,
+					content,
+					level: "project",
+					depth: calculatedDepth,
+					_source: createSourceMeta(PROVIDER_ID, candidate, "project"),
+				});
+			}
+		}
+
+		if (current === (ctx.repoRoot ?? ctx.home)) break; // scanned repo root or home, stop
+
+		// Move to parent directory
+		const parent = path.dirname(current);
+		if (parent === current) break; // Reached filesystem root
+		current = parent;
+	}
+
+	return { items, warnings };
+}
+
+registerProvider(contextFileCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Standalone AGENTS.md files (Codex/Gemini style)",
+	priority: 10,
+	load: loadAgentsMd,
+});

package/src/discovery/agents.ts

@@ -0,0 +1,230 @@
+/**
+ * Agents (standard) Provider
+ *
+ * Loads skills, rules, prompts, commands, context files, and system prompts
+ * from .agent/ and .agents/ directories at both user (~/) and project levels.
+ * Project-level discovery walks up from cwd to repoRoot.
+ */
+import * as path from "node:path";
+import { registerProvider } from "../capability";
+import { type ContextFile, contextFileCapability } from "../capability/context-file";
+import { readFile } from "../capability/fs";
+import { type Prompt, promptCapability } from "../capability/prompt";
+import { type Rule, ruleCapability } from "../capability/rule";
+import { type Skill, skillCapability } from "../capability/skill";
+import { type SlashCommand, slashCommandCapability } from "../capability/slash-command";
+import { type SystemPrompt, systemPromptCapability } from "../capability/system-prompt";
+import type { LoadContext, LoadResult } from "../capability/types";
+import {
+	buildRuleFromMarkdown,
+	calculateDepth,
+	createSourceMeta,
+	loadFilesFromDir,
+	scanSkillsFromDir,
+} from "./helpers";
+
+const PROVIDER_ID = "agents";
+const DISPLAY_NAME = "Agents (standard)";
+const PRIORITY = 70;
+const AGENT_DIR_CANDIDATES = [".agent", ".agents"] as const;
+
+/** User-level paths: ~/.agent/<segments> and ~/.agents/<segments>. */
+function getUserPathCandidates(ctx: LoadContext, ...segments: string[]): string[] {
+	return AGENT_DIR_CANDIDATES.map(baseDir => path.join(ctx.home, baseDir, ...segments));
+}
+
+/**
+ * Project-level paths: walk up from cwd to repoRoot, returning `.agent/<segments>`
+ * and `.agents/<segments>` at each ancestor.
+ *
+ * The user home directory is skipped: `~/.agent[s]/` is by definition
+ * user-level config and is already enumerated by {@link getUserPathCandidates}.
+ * Without this guard, any cwd under `$HOME` (with no closer git repoRoot) would
+ * walk up to home and yield duplicate project+user entries for the same
+ * directory — see https://github.com/can1357/gajae-code/issues/1116.
+ */
+export function getProjectPathCandidates(ctx: LoadContext, ...segments: string[]): string[] {
+	const paths: string[] = [];
+	let current = ctx.cwd;
+	while (true) {
+		if (current !== ctx.home) {
+			for (const baseDir of AGENT_DIR_CANDIDATES) {
+				paths.push(path.join(current, baseDir, ...segments));
+			}
+		}
+		if (current === (ctx.repoRoot ?? ctx.home)) break;
+		const parent = path.dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return paths;
+}
+
+// Skills
+async function loadSkills(ctx: LoadContext): Promise<LoadResult<Skill>> {
+	const projectScans = getProjectPathCandidates(ctx, "skills").map(dir =>
+		scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "project" }),
+	);
+	const userScans = getUserPathCandidates(ctx, "skills").map(dir =>
+		scanSkillsFromDir(ctx, { dir, providerId: PROVIDER_ID, level: "user" }),
+	);
+
+	const results = await Promise.all([...projectScans, ...userScans]);
+
+	return {
+		items: results.flatMap(r => r.items),
+		warnings: results.flatMap(r => r.warnings ?? []),
+	};
+}
+
+registerProvider<Skill>(skillCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load skills from .agent/skills and .agents/skills (project walk-up + user home)",
+	priority: PRIORITY,
+	load: loadSkills,
+});
+
+// Rules
+async function loadRules(ctx: LoadContext): Promise<LoadResult<Rule>> {
+	const load = (dir: string, level: "user" | "project") =>
+		loadFilesFromDir<Rule>(ctx, dir, PROVIDER_ID, level, {
+			extensions: ["md", "mdc"],
+			transform: (name, content, filePath, source) =>
+				buildRuleFromMarkdown(name, content, filePath, source, { stripNamePattern: /\.(md|mdc)$/ }),
+		});
+
+	const results = await Promise.all([
+		...getProjectPathCandidates(ctx, "rules").map(dir => load(dir, "project")),
+		...getUserPathCandidates(ctx, "rules").map(dir => load(dir, "user")),
+	]);
+
+	return {
+		items: results.flatMap(r => r.items),
+		warnings: results.flatMap(r => r.warnings ?? []),
+	};
+}
+
+registerProvider<Rule>(ruleCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load rules from .agent/rules and .agents/rules (project walk-up + user home)",
+	priority: PRIORITY,
+	load: loadRules,
+});
+
+// Prompts
+async function loadPrompts(ctx: LoadContext): Promise<LoadResult<Prompt>> {
+	const load = (dir: string, level: "user" | "project") =>
+		loadFilesFromDir<Prompt>(ctx, dir, PROVIDER_ID, level, {
+			extensions: ["md"],
+			transform: (name, content, filePath, source) => ({
+				name: name.replace(/\.md$/, ""),
+				path: filePath,
+				content,
+				_source: source,
+			}),
+		});
+
+	const results = await Promise.all([
+		...getProjectPathCandidates(ctx, "prompts").map(dir => load(dir, "project")),
+		...getUserPathCandidates(ctx, "prompts").map(dir => load(dir, "user")),
+	]);
+
+	return {
+		items: results.flatMap(r => r.items),
+		warnings: results.flatMap(r => r.warnings ?? []),
+	};
+}
+
+registerProvider<Prompt>(promptCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load prompts from .agent/prompts and .agents/prompts (project walk-up + user home)",
+	priority: PRIORITY,
+	load: loadPrompts,
+});
+
+// Slash Commands
+async function loadSlashCommands(ctx: LoadContext): Promise<LoadResult<SlashCommand>> {
+	const load = (dir: string, level: "user" | "project") =>
+		loadFilesFromDir<SlashCommand>(ctx, dir, PROVIDER_ID, level, {
+			extensions: ["md"],
+			transform: (name, content, filePath, source) => ({
+				name: name.replace(/\.md$/, ""),
+				path: filePath,
+				content,
+				level,
+				_source: source,
+			}),
+		});
+
+	const results = await Promise.all([
+		...getProjectPathCandidates(ctx, "commands").map(dir => load(dir, "project")),
+		...getUserPathCandidates(ctx, "commands").map(dir => load(dir, "user")),
+	]);
+
+	return {
+		items: results.flatMap(r => r.items),
+		warnings: results.flatMap(r => r.warnings ?? []),
+	};
+}
+
+registerProvider<SlashCommand>(slashCommandCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load commands from .agent/commands and .agents/commands (project walk-up + user home)",
+	priority: PRIORITY,
+	load: loadSlashCommands,
+});
+
+// Context Files (AGENTS.md)
+async function loadContextFiles(ctx: LoadContext): Promise<LoadResult<ContextFile>> {
+	const load = async (filePath: string, level: "user" | "project"): Promise<ContextFile | null> => {
+		const content = await readFile(filePath);
+		if (!content) return null;
+		// filePath is <ancestor>/.agent(s)/AGENTS.md — go up past the config dir to the ancestor
+		const ancestorDir = path.dirname(path.dirname(filePath));
+		const depth = level === "project" ? calculateDepth(ctx.cwd, ancestorDir, path.sep) : undefined;
+		return { path: filePath, content, level, depth, _source: createSourceMeta(PROVIDER_ID, filePath, level) };
+	};
+
+	const results = await Promise.all([
+		...getProjectPathCandidates(ctx, "AGENTS.md").map(p => load(p, "project")),
+		...getUserPathCandidates(ctx, "AGENTS.md").map(p => load(p, "user")),
+	]);
+
+	return { items: results.filter((r): r is ContextFile => r !== null), warnings: [] };
+}
+
+registerProvider<ContextFile>(contextFileCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load AGENTS.md from .agent and .agents (project walk-up + user home)",
+	priority: PRIORITY,
+	load: loadContextFiles,
+});
+
+// System Prompt (SYSTEM.md)
+async function loadSystemPrompt(ctx: LoadContext): Promise<LoadResult<SystemPrompt>> {
+	const load = async (filePath: string, level: "user" | "project"): Promise<SystemPrompt | null> => {
+		const content = await readFile(filePath);
+		if (!content) return null;
+		return { path: filePath, content, level, _source: createSourceMeta(PROVIDER_ID, filePath, level) };
+	};
+
+	const results = await Promise.all([
+		...getProjectPathCandidates(ctx, "SYSTEM.md").map(p => load(p, "project")),
+		...getUserPathCandidates(ctx, "SYSTEM.md").map(p => load(p, "user")),
+	]);
+
+	return { items: results.filter((r): r is SystemPrompt => r !== null), warnings: [] };
+}
+
+registerProvider<SystemPrompt>(systemPromptCapability.id, {
+	id: PROVIDER_ID,
+	displayName: DISPLAY_NAME,
+	description: "Load SYSTEM.md from .agent and .agents (project walk-up + user home)",
+	priority: PRIORITY,
+	load: loadSystemPrompt,
+});