myco

Use when you need to know whether Myco's captured data is correct and complete, rather than why capture stopped — auditing capture fidelity across the Grove database and local symbiont transcripts, checking whether a symbiont's transcript format or hook contract has drifted from its manifest, investigating sessions that never closed or that never appeared at all, reconciling what is on disk against what is in the vault, chasing duplicate or missing prompt batches, NULL content_hash rows, missing response summaries, misclassified prompt origins, or suspected data loss after a coding agent updated. Applies to claude-code, codex, cursor, windsurf, copilot, antigravity, pi, opencode and cline. Use it proactively after any symbiont ships a new version, and before trusting vault contents for analysis. This skill is hand-managed — do NOT register it with the Myco skill pipeline.

Use when handing a coding session off to a new session or another symbiont — "hand this off", "prepare a handoff", "continue this in a new session", "pick up where I left off", "pass this to another agent", or when context is heavy / running low and the work will continue elsewhere, or work has drifted out of scope and should restart fresh. PREPARE compresses the current session's intention (why we're here, what we're doing, gotchas, dead ends, decisions) into a ≤1500-token digest saved on a Myco plan. RECEIVE takes a plan ID, rehydrates the context, reads and marks the referenced plans in progress, loads the suggested skills, and resumes the work.

Comprehensive lifecycle for authoring, registering, documenting, and maintaining MCP tools in packages/myco/src/tools/ — covering schema definition in TOOL_DEFINITIONS arrays, handler implementation with DaemonClient patterns, shared tool-runtime registration, documentation bundling, anti-drift testing patterns, and per-symbiont transport (mcp vs cli) decisions. Essential for maintaining the schema ↔ handler ↔ documentation triad that agents depend on for correct tool invocations, even when the user doesn't explicitly ask for MCP tool development.

Procedures for building, maintaining, and extending Myco's React daemon UI: the v7 component-composition system (AccentSurface/Panel primitives, page-wide selection state, master-detail and slideout layouts), the Grove-owned appearance system (6 themes, light/dark/system mode, three-role fonts, density), project-scoped request context, auth-gated attachments, and the Team Host degraded-presentation family for attached (hosted) projects. Use when building or troubleshooting UI components, extending the theme/appearance system, wiring project-scoped data, or presenting attached-project degradation, even if the user doesn't explicitly ask for UI development guidance.

Use this skill when installing Myco for the first time, initializing Myco in a new project, or troubleshooting a broken installation. Activate even if the user just asks "how do I get started with Myco" or "how do I add Myco to my project" without explicitly saying "install." Covers the full lifecycle: bootstrapping the CLI via the install script, verifying health with `myco doctor`, and managing updates and removal.

Use this skill when adding or evolving Myco's SQLite vault database schema — even if the user doesn't explicitly ask for "schema work." Covers: authoring versioned migration scripts with correct error guards (IF NOT EXISTS, user_version bumps), evolving existing tables with ALTER TABLE in a backfill-safe sequence, creating and populating FTS5 full-text search indexes with auto-sync triggers, keeping the dormant team-sync worker's D1 mirror parity-test-clean for any table in its synced-table set (team sync itself is retired — there is no live D1 deployment), selecting the right query patterns (WHERE IN with json_each for dynamic ID sets, hydration joins instead of N+1 selects, cursor-based pagination instead of OFFSET), Grove multi-tenant database design for global daemon architecture, and updating the constants and query modules that complete the data layer surface. Every new Myco feature that stores data touches this domain.

Use this skill whenever you need to add, modify, or remove tables, columns, or indexes in the Myco vault SQLite schema — even if the user just asks to "add a column" or "create a new table." The vault uses a versioned createSchema migration chain where each schema version is a numbered step that builds on the previous one. Because user vaults accumulate real data across machines, any schema change that breaks the migration chain can corrupt or destroy vault data. This skill covers how to add a new version to the chain, write safe migration SQL, handle backfill steps, bump the schema version constant, keep the dormant team-sync worker's D1 mirror parity-test-clean if your table is in the synced-table set, and verify the migration works end-to-end before shipping.

Use this skill when authoring, configuring, or debugging Myco agent pipeline tasks. It covers task YAML anatomy, scheduling, parameter injection, timeout and concurrency behavior, audit-log interpretation, turn-budget failures, skill-lifecycle task constraints, and hardening patterns for new tasks and MCP tools. Apply it whenever work touches `src/agent/tasks/`, `src/agent/executor.ts`, `src/daemon/task-scheduler.ts`, or `src/mcp/tools/`, even if the user does not explicitly mention task authoring.

Comprehensive procedures for building and extending Myco's Canopy code intelligence system. Covers agent harness task standardization, three-layer file exclusion models, context injection and attribution pipelines, hook response shape compatibility, local-only aggregation architecture, and scanner configuration workflows. Apply when developing file indexing capabilities, extending intelligence features, or integrating code analysis workflows, even if the user doesn't explicitly ask for canopy system development.

Deploy, maintain, and operate Myco's Collective worker (packages/myco-collective) — the cross-project admin layer built on Cloudflare Workers, D1, and KV. Covers the worker's package structure, the `myco-collective` operator CLI (install/upgrade/status/add-project/ rotate-tokens/destroy), D1/KV bindings, and the general Wrangler-upgrade failure modes that apply to any Cloudflare Worker package in this repo. Use this when touching packages/myco-collective/worker, running wrangler against it, or debugging its deploy/D1/KV behavior.

Comprehensive procedures for implementing and managing Myco's Grove multi-tenant architecture with request context management. Covers request context threading through transport boundaries, project identity binding via .myco/project.toml, multi-tenant database schema design, context enforcement across six layers, MCP transport unification, Grove registry management, and comprehensive importer architecture. Use when implementing multi-tenant features, setting up Grove projects, debugging context propagation issues, or ensuring request context isolation.

Apply this skill whenever you need to write, update, or modify Myco configuration — whether from a React settings form, a CLI command, a task, or any other code path. This covers the two linked invariants that prevent silent data loss: (1) all YAML writes must flow through updateConfig() in packages/myco/src/config/loader.ts, and (2) all React settings forms must spread the original config before overlaying form values in their formToConfig() function. Also covers the complete procedure for adding new configurable settings to Myco's three-tier scoped config system (machine/grove/project/personal) including scope assignment decisions, Zod schema extension, API endpoint integration, useScopedConfig hook wiring, and ScopedField component wrapping. Use this skill even if the user hasn't explicitly asked about config safety — any time you touch myco.yaml, add a settings field, modify a settings page, or add new configurable fields, these patterns apply.

Use this skill when writing, reviewing, or editing user-facing Myco documentation — README sections, feature docs, onboarding guides, CLI reference pages, docs site SEO/crawler files, or any content intended for people who use Myco (not people who build it). Activate this skill even if the user doesn't explicitly ask for a documentation review — if you're finishing a feature implementation and documentation is the next step, invoke this skill before writing or committing any docs. This skill enforces the Myco doc-voice contract: user guides rather than user manuals, capability-first language, zero internal mechanics leakage, crawler-friendly public docs, and user-vocabulary only.

Use when making design decisions, debugging non-obvious issues, encountering gotchas, wondering why code is structured a certain way, delegating work to another agent, or when you need context about prior work on the same feature or component. Myco captures the reasoning, trade-offs, and lessons behind the codebase — things the code itself doesn't show. Also use when the user mentions vault, spores, sessions, team knowledge, institutional memory, or prior decisions.

Use this skill whenever the Myco daemon is misbehaving — even if the user doesn't explicitly ask for a debugging procedure. Activates for: daemon process crashes, uncaught exceptions, FK constraint violations, PowerManager jobs not firing, scheduler starvation, outbox drain loops, duplicate or phantom sessions, executor tasks that silently succeed or stall, and any log output from the daemon's core subsystems (PowerManager, SQLite, outbox, session lifecycle, phased executor). This is the cross-cutting playbook for investigating, tracing, and surgically solutioning daemon-layer bugs — distinct from debugging agent task YAML, schema migrations, or outbox architecture design.

Use this skill when adding a new symbiont (agent integration) to Myco's SymbiontInstaller — the component that manages agent lifecycle operations (init, update, remove, doctor) for all registered agents. Activates whenever you need to onboard a new AI agent (Claude Code, Cursor, Windsurf, a custom agent, etc.) so that `myco init`, `myco update`, and `myco doctor` manage its installation. Apply this skill even if the user doesn't explicitly mention SymbiontInstaller — any time you're adding a new agent type, creating a symbiont manifest, wiring new hook templates, or extending the supported agents list, this skill applies. Also relevant when a new symbiont needs the cross-platform hook guard or environment variable injection.

Use this skill when a Myco session, prompt, tool use, or attachment appears to have gone missing — the agent says "I sent that" but it isn't in the dashboard, a session shows zero batches, MCP tool calls hang or silently no-op, hooks aren't firing in a worktree, the buffer file isn't growing, FK constraint errors appear in the daemon log, or the symptom is "capture went silent." Also use when investigating any reported capture regression in the Myco repo. Walks the capture lifecycle top-down — agent → hook → daemon HTTP → buffer → registry → SQLite → transcript miner — and tells you which layer to look at, in what order, with the exact command to run. Replaces the "investigate capture loss from scratch" antipattern that produced repeated one-off patches.

Quality engineering procedures for Myco's npm workspace: build orchestration (make vs npm), cross-platform artifact validation, workspace dependency management, release workflow hardening, and CI/CD pipeline robustness. Use when setting up quality gates, debugging build failures, hardening release workflows, or managing workspace dependencies.

Apply this skill when working on native binary installation, upgrade pipelines, daemon binary path management, or dev/prod daemon coexistence for the Myco native installer. Covers: the steady-state binary path model (e.g., issues with code-signing on macOS have now been addressed and should be reflected in plist self-heal), the looksLikeDevBuildExecutable() service-mutation guard, managedBinaryPath() usage, the MYCO_HOME physical boundary model (prod ~/.myco vs dogfood ~/.myco-dev) that replaced the deprecated detectDevBuild() pattern, upgrade-path validation (confirm plist self-heal before testing), beta rollout sequencing for install-path changes, and the self-propagation trap requiring GA-gating any upgrade-path fix. Use this skill whenever code touches binary paths, service install/uninstall, upgrade exemption, plist config, or daemon coexistence.

Apply this skill when validating, testing, or releasing any version-to-version upgrade, addressing critical missing paths and suspected fabrications. Covers five orthogonal procedures: (1) clean-state revert methodology before upgrade testing to simulate real-world conditions; (2) CI-as-primary-gate discipline when local tests are flaky or environment-contaminated; (3) merge→publish→test release sequencing to avoid blocking on local reliability; (4) detecting and handling the self-propagation trap, where a bug disables the auto-adopt mechanism that would deliver its own fix; (5) dev environment routing via pattern extension (runtime.command + runtime.home + manual channel) instead of bespoke knobs.

Create or maintain an OKF-conformant project wiki — a portable, git-committed markdown knowledge base that lives in the repo, not the vault. Use when asked to create a wiki, build or generate a project wiki, document this codebase as a wiki, maintain/update/sync the wiki with the code, or when the request mentions OKF, "Open Knowledge Format", or knowledge catalog. Also use when asked to turn Myco's captured intelligence (Canopy map, digest, spores, sessions, skills) into human-readable documentation that ships with the repo. Any symbiont can run this procedure — it needs no daemon machinery beyond the ordinary Myco tools.

Comprehensive procedures for analyzing, optimizing, and monitoring LLM costs and performance in Myco's agent harness system. Covers cost leak identification, performance bottleneck analysis, resource allocation optimization, SDK execution telemetry, and budget calibration patterns. Use when investigating cost spikes, optimizing agent task efficiency, calibrating turn budgets, or implementing cost control measures, even if the user doesn't explicitly ask for cost optimization analysis.

Use this skill when designing, writing, configuring, or debugging a new phased executor task for the Myco agent harness — even if the user doesn't explicitly ask for a "task authoring" guide. Applies when adding a new intelligence task, modifying phase structure, tuning turn budgets or model routing, adjusting scheduling triggers or session-gating, designing a tool surface, or debugging silent phase failures or budget exhaustion. Covers: YAML task anatomy and registration; phase decomposition and the judgment/recipe gradient; model selection via the advisor pattern; turn budget calibration including local-model multipliers; scheduling triggers and session-gating; tool surface design and readOnly enforcement; Grove scope iteration patterns; per-project lifecycle management; session lifecycle orchestration and agent runtime coordination; and observability via the agent_runs audit table.

Apply this skill whenever you encounter logic, values, or transformations duplicated across multiple files in the Myco codebase — even if the user doesn't explicitly ask for a refactor. Covers five recurring SSoT patterns: (1) extracting shared read projections to the shared read-projections module, (2) centralizing provider capabilities in the shared context-window module, (3) replacing magic strings with named constants in the shared constants module, (4) creating semantic wrapper functions in the config loader and settings-merge modules, and (5) adding path properties to service state objects (DaemonServiceState). Also covers two critical violation classes to detect during code review: parallel ownership predicates (is-this-mine? checks duplicated across files) and database query locality (direct DB calls in tool files that bypass the shared data access layer). The root discipline is: name the thing, own it in one place, let consumers reference it.

Implement and maintain Git-based release provenance tracking with reconciliation for squash-merge workflows. Covers Git snapshot capture, two-tier reconciliation strategy (ancestry + patch-ID matching), knowledge graph propagation, performance optimization, and privacy-aware sync design. Use this for setting up release provenance systems, troubleshooting reconciliation issues, or maintaining Git lineage tracking even if the user doesn't explicitly ask for release provenance configuration.

Comprehensive procedures for authoring, configuring, and maintaining Myco's PowerManager infrastructure and scheduled task system. Covers PowerManager job registration and lifecycle, task scheduler architecture and configuration, per-project power state tracking implementation, scheduled task fan-out across Groves, cold-project gating and threshold management, and fire-and-forget dispatch patterns for long-running tasks.

Use when prompt/response capture stops working, a Claude Code hook reports a silent non-blocking error, or you're modifying anything in packages/myco/src/hooks/, the global launcher, or the EventBuffer/ reconciliation path. Stop hooks are the most fragile point in Myco's capture chain — covers three distinct, independently-diagnosable failure modes: (1) hook path wiring breaking when ~/.myco/runtime/ is deleted even though the native daemon is active, (2) capture-critical hooks needing an EventBuffer fallback so daemon restarts mid-turn don't permanently drop the assistant response, and (3) the global launcher's catch-all masking real errors as a silent "non-blocking status code, no stderr" failure. Apply this even if the user just says "capture isn't working" or "hook is erroring" without naming a root cause — the procedure here is how you tell the three apart and fix or recover from each.

Use this skill when delivering a non-trivial Myco feature that spans multiple files and needs clean PR history. It applies whenever you need git worktrees for isolated implementation, the `code-review high` quality pass (multi-agent fan-out; `/simplify` is deprecated), `make build` as the full quality gate, or a single clean squash-merge commit for the final PR.

Apply this skill when working on global symbiont installation, extending the global install model, adding new symbionts for global deployment, or debugging issues that touch multiple projects simultaneously — even if the user doesn't explicitly ask about the install model or its constraints. Covers six repeatable procedures: (1) eliminating legacy fallback code during migration, (2) scoping the Symbiont page UI to auto-detect plus per-project override only, (3) scheduling symbiont health checks against PowerManager state, (4) previewing blast radius before any global write, (5) enforcing walker grove-ownership filtering to prevent cross-grove mutations, and (6) running a dry-run validation before committing global installs. Also covers the invariant that the global model is canonical — fallbacks are traps, per-project config is the escape hatch. Includes the managed skills architecture (binary-embedded, agent-standard install) and three known failure modes for global skill symlinks.

Implement manifest-driven tool resolution for Canopy read-tool detection across symbionts. Covers adding canopyReadTools discriminated union declarations to symbiont manifests (structured vs shell-pattern modes), implementing symbiont-agnostic resolvers, unifying pre/post tool-use hooks, and updating database queries to respect manifest declarations. Use when adding new symbionts that need Canopy integration, extending tool resolution capabilities, or debugging read-tool detection issues, even if the user doesn't explicitly ask for manifest-driven architecture.

Comprehensive procedures for managing Myco daemon process lifecycle including startup robustness, unified eviction and restart workflows, process identity management, multi-instance coordination, health checking, update application, npm package upgrade handling, daemon binary version mismatch detection, event-loop safety patterns, lag monitoring, yield points, and resource cleanup. Covers operational daemon management patterns from auto-spawn and migration tasks through SIGTERM/SIGKILL sequences to port release verification, cross-runtime coordination, and event loop responsiveness protection. Use when starting, restarting, updating, or coordinating daemon processes, even if the user doesn't explicitly ask for daemon lifecycle management.

Procedures for managing binary dispatch, runtime environment resolution, and machine-scoped coordination in Myco deployments. Covers layered runtime command resolution (~/.myco/runtime.command pins, project overrides, fallback chains), machine-scoped runtime architecture, binary masquerade detection and prevention, update coordination protocols, Bun compilation deployment patterns, dogfood routing via dev-build detection, and beta channel global replacement strategy. Use when setting up environments, troubleshooting binary dispatch issues, managing machine-scoped coordination, or implementing system updates, even if the user doesn't explicitly ask for runtime environment management.

Implement capture pipeline resilience patterns and detect silent failure modes in the Myco daemon. Covers identifying when capture hooks fail silently while the daemon appears healthy, diagnosing liveness vs readiness issues, implementing service-manager-aware recovery patterns with capturePost(), and debugging capture ingestion delays. Essential for maintaining reliable session/prompt/event capture even when the daemon process is alive but routed endpoints are wedged.

Apply when deciding WHERE to record knowledge, instructions, or context in the Myco project — even if the user hasn't explicitly asked about documentation strategy. Covers five surfaces: AGENTS.md (durable agent operating rules and architectural invariants only), SKILL.md files (codified project procedures with steps and examples), inline code comments (behavioral invariants and HOW the code works — never historical narrative), the Myco vault (decisions, rationale, incidents, tradeoffs), and user-facing docs (README, CHANGELOG, docs/, marketing site — user mental model only, never internal mechanics). The wrong surface creates knowledge rot: implementation details in user docs confuse users, historical narrative in code comments becomes lies as code evolves, behavioral invariants buried only in the vault leave developers guessing at the point of action. Use this skill when writing any new knowledge, reviewing a PR for doc discipline, or auditing existing content for surface violations.

Activate this skill when working on the Myco backup/restore subsystem — including restore UX changes, async job architecture, daemon thread safety, or concurrency correctness in restore operations — even if the user doesn't explicitly ask about reliability or async patterns. Covers four major procedures: (1) restructuring the restore UI around a modal-based guided flow, (2) offloading long-running DB operations to a child process + async job registry, (3) parsing dump header metadata for preview without SQL execution, and (4) hardening the job registry against temp-path collisions and memory leaks.

Apply this skill when writing, modifying, or reviewing any code that touches Myco's intent-file-mediated daemon communication protocol — even if the user doesn't explicitly ask about correctness. The protocol (write intent file → reconciler reads → acts) has four documented failure modes: (1) concurrent writers silently dropping each other's intent via shared-file merge logic, (2) intent cleared before the async action it triggers is confirmed complete, (3) intent written but never consumed when the daemon is in deep_sleep state (SELF_RECONCILE excludes deep_sleep), and (4) reconciler re-entrancy where a handler raises a new intent for the very action the reconciler is executing, producing a perpetual no-op loop. Covers diagnosis, fix patterns, and required test coverage for all four gaps.

Procedure for dogfooding Myco changes inside a git worktree so capture, MCP, and CLI route to the worktree's own build instead of the production binary. Use when developing Myco in a git worktree, when capture/MCP in a worktree behaves like production or points at the wrong build, or when wiring up `make dev-link-worktree` / `make dev-unlink-worktree`. Covers why `.myco/runtime.command` does not travel with `git worktree add`, why a build must happen first, the direct-CLI `MYCO_HOME` gotcha, the shared-vault schema rollup hazard across worktrees, and the vendor-asset build gotcha.

Apply this skill when working on the myco.sh documentation site — including adding or updating guides, modifying the build pipeline, maintaining the GitHub Actions Pages deploy workflow, auditing SEO/AI-crawler discovery, or fixing rendering bugs in the static HTML output — even if the user doesn't explicitly ask about build infrastructure or deployment. Covers four interlocking procedures: (1) dual-surface architecture — keeping raw .md files for AI crawlers while generating parallel .html in docs/_site via docs/build.mjs; (2) build pipeline configuration using markdown-it + Shiki with the linkify fuzzyLink guard in docs/lib/render.mjs; (3) discovery layer maintenance — robots.txt, sitemap.xml, llms.txt, JSON-LD, and canonical tags; and (4) GitHub Pages workflow — matching upload-pages-artifact and deploy-pages version pairs to prevent silent deploy failures.

Use this skill when running or debugging the Myco skill lifecycle end to end: identifying candidates from vault knowledge, curating them through approval, generating `SKILL.md` files, and evolving existing skills as the vault grows. It applies to `skill-survey`, `skill-generate`, `skill-evolve`, and any work on the Skills dashboard, including cases where candidates appear but no skills materialize, surveys return zero results, or generated skills need refreshes.

Use this skill when working with Myco's skill lifecycle system — whether generating a new skill from an approved candidate, reviewing the candidate queue, updating a stale skill, retiring an outdated one, or debugging why a skill wasn't triggered. Activates whenever you touch vault_skill_candidates, vault_skill_records, or vault_write_skill — or whenever the user asks about skills, the Skills dashboard, skill generation tasks, or the .agents/skills/ directory. Apply this skill even if the user doesn't explicitly say "skill lifecycle" — any time a task involves producing or updating a SKILL.md file, evaluating candidates, or managing skill status, this procedure applies.