Instruction file imported from hijera/foxxy-agent (.cursor/rules/core-modules.mdc). Copyright stays with the author.

Core modules (sketch)

• internal/acp - ACP RPC server, session lifecycle from editors.
• internal/agent - tool loop and LLM turns.
• internal/session - session manager and mode (agent / plan / docs / ask / debug).
• internal/config - YAML and flags.
• internal/mcp - MCP clients and transports, the merged server list, and the workspace trust gate. A project-local <cwd>/.foxxycode/mcp.json arrives with the checkout, so TrustGate (gate.go) is the single decision point between that list and a spawn or an outbound connection; it re-checks immediately before the transport opens. Approvals live in <home>/mcp-trust.json keyed by canonical workspace and bound to a digest of the command-bearing declaration (trust.go). Never reach Connect / Probe around the gate for a configuration-derived server. See docs/features/mcp.md.
• internal/tools - filesystem, shell, todo, MCP merge, etc. Shell also owns the background task family (run_command background: true plus background_list / background_output / background_wait / background_stop / background_reap), backed by internal/bgtask. See docs/features/background-tasks.md.
• internal/bgtask - process-wide, session-scoped pool for work that outlives a tool call. A task is whatever a Runner starts (CommandRunner for shell commands) or whatever a LaunchFunc hands to Pool.Launch: that is how a subagent run becomes a KindAgent task, with Spec.Agent / Snapshot.Agent {name, session_id} naming the child session. One scheduling path (start) serves Start, Adopt and Launch; do not add a second scheduling mechanism or status surface.
• internal/subagents - subagent definitions (markdown + YAML frontmatter, definition.go: aliases, bounds, SHA-256 digest, EffectiveTools / NarrowPermissionMode / ResolveTimeoutSeconds), the loader (loader.go: subagents.dirs precedence, canonical scopes builtin / user / project, deny never reads project dirs), the trust receipts for project-scope files (trust.go: TrustStore at <home>/subagents-trust.json, Decide, keyed by canonical workspace + name + digest under subagents.project_trust), the process-wide Limiter (refuses, never queues), and the catalog (catalog.go: BuildCatalog, PromptBlock, WriteListing). Pure decisions only: no sessions, no loop. internal/agent/subagent.go applies them (spawn hook, permission relay, report) and internal/session/subagent.go owns child sessions (ordinary sess_ ids, bundles nested under <parent>/subagents/, ErrSubagentReadOnly, DeleteSessionTree). Approval surfaces: foxxycode agents list|trust|untrust, POST /foxxycode/subagents/{name}/trust|untrust. See docs/features/subagents.md. Pool.Adopt takes over a foreground command that outlived its timeout instead of killing it, sharing the single scheduling path with Start.
• internal/hooks - operator lifecycle hooks: commands that read one JSON document on stdin at a point of a session and answer with an exit code plus optional JSON (definition.go: Claude Code's file shape, handler fields, Parse; matcher.go: exact-list-or-regex matchers with tool-name aliases such as Bash -> run_command; loader.go: hooks.files, canonical scopes user / project, deny never reads project files, Source.Runnable; trust.go: TrustStore at <home>/hooks-trust.json, receipts keyed by canonical workspace + workspace-relative file + digest under hooks.project_trust, Loader.WithStore; catalog.go: BuildCatalog, FindSource, WriteListing; runner.go: payload, sequential execution, timeouts and process groups via internal/platform, the exit-code contract, Outcome merging with the most restrictive decision winning). Pure decisions only: no sessions, no loop. internal/agent/hooks.go applies them: PreToolUse before the permission gate and PostToolUse / PostToolUseFailure after the tool in executeToolCall, UserPromptSubmit (reject, or context into the ## Hook context prompt block) and Stop (follow-up submitted as a [Stop hook] user message, capped by hooks.stop_loop_limit) in the loop, PreCompact (veto) / PostCompact in CompactSession, SubagentStart (refuse, or context into the child's task) / SubagentStop in subagent.go, Notification (permission_prompt) before the permission prompt; internal/session/hooks.go fires SessionStart from the manager and persists its context as hookContext. Project-scope files follow hooks.project_trust like MCP declarations and subagent definitions; a held file is reported once per session as a notice-level UI log row. Approval surfaces: foxxycode hooks list|trust|untrust, GET /foxxycode/hooks, POST /foxxycode/hooks/trust|untrust. See docs/features/hooks.md.
• internal/skills - skill loading, enable/disable (loader.go, disabled.go), and remote install from repos / agents-standard marketplaces (remote.go, manifest.go, plugin.go: Sync/SyncSource (all or one source), AvailablePlugins/InstallPlugin (the Settings search and its per-skill install), AddSource, RemoveRemote/DeleteSkill (delete any on-disk skill; bundled = read-only via SkillReadonly), ListSources, RemoveSource, CheckUpdates, UpdateSkill; a shallow internal/gitws.Clone into a temp dir on every sync, http(s) clone and manifest URLs behind the webfetch SSRF guard, materialized into ${FOXXYCODE_HOME}/skills with a .remote.json lockfile that records each skill's installed version). Marketplace plugin version (and SKILL.md frontmatter version) are surfaced by InstalledVersion and drive update detection (compareVersions). Default dirs: ~/.agents/skills (global, shared with npx skills/npx skillsbd), ~/.foxxycode/skills (foxxycode-specific, also where synced skills land), ${CWD}/.foxxycode/skills (project-local; ${CWD} is the session workspace, which HTTP resolves through X-FoxxyCode-Session-ID). Remote sources are listed in skills.sources and fetched only on demand. Management parity across the CLI (foxxycode skills add|sync|remove, foxxycode plugin marketplace list|add|remove|sync, foxxycode plugin install|remove|enable|disable|list), the built-in /plugin chat command (internal/agent/plugin_command.go, deterministic like /compact; shared dispatcher skills.RunPluginCommand / MarketplaceStatus in plugin.go), HTTP (/foxxycode/skills/*), and the Settings → Skills UI. See docs/features/skills.md.
• internal/rules - rules catalog: one provider per root (factory.go: .foxxycode/rules, the shared .agents/rules as system agents-dir, .cursor/rules, .claude/rules, .codex/rules, the top-level .foxxyrules / .foxyrules roots as system foxxycode (foxxyrules.go: a single file or a directory), plus the operator's own ${FOXXYCODE_HOME}/rules as system user - DefaultFactory(home) adds it, and Discover accepts an absolute provider root for it; nested AGENTS.md files have no provider, agents.go reads them on demand through AgentsForPaths for the folders a tool enters and never walks the tree), dedupe by file name with precedence foxxycode > agents-dir > cursor > claude > codex > agents > user, the dialect picked by extension in markdown.go (.mdc = Cursor description/globs/alwaysApply, default manual; .md = Claude Code paths, unconditional without them; a header is read as YAML first, then by a lenient line reader because Cursor's own globs: **/*.go is not valid YAML), doublestar glob matching anchored at Rule.Root (MatchGlob), activation (select.go: MatchAuto for file:// context and SelectMentioned for @name; scope.go: MatchScoped for filesystem tool-call paths against globs and nested AGENTS.md subtrees) and the foxxycode rules list table (list.go: RenderCatalog). LoadProjectDocs(home, cwd) reads the agent home's AGENTS.md and DESIGN.md first, above the workspace's own pair, with nothing in config.yaml naming them, and AgentsForPaths reads the same pair (preambleFiles) for a folder a tool enters; RenderPrompt reports the paths it embedded, so internal/session/instructions_load.go (the instructions.files reader: ${FOXXYCODE_HOME}, ${CWD}, ~ and absolute entries) never sends the same file twice. See docs/features/rules.md.

Prefer extending these over growing cmd/ or duplicating logic in external/.

References

@architecture.mdc