invowk

Invowk type-system and goplint guidance for value types across cmd/*, internal/*, and pkg/*, including Validate() contracts, primitive-wrapper value objects, aliases/re-exports, sentinel errors, Invalid*Error wrappers, check-types/check-types-all findings, DDD compliance, and baseline updates. Use when adding, reviewing, refactoring, or documenting value types.

Comprehensive documentation review and audit for invowk. Checks README, website docs (next version only), MDX snippets, CUE schema alignment, i18n parity, architecture diagrams, container image policy, security/audit docs, LLM authoring docs, and agent workflow docs against the actual codebase. Use this when reviewing documentation accuracy, when code changes may have caused doc drift, after significant feature work, or before releases. Always use this skill for any documentation review task, even if the user doesn't explicitly say "review docs" — any mention of checking docs, verifying documentation accuracy, or ensuring docs match code should trigger this skill.

Maintain and troubleshoot Invowk's Bencher benchmark infrastructure. Use when working on Bencher, BMF benchmark output, benchmark GitHub Actions, PGO benchstat comparisons, dedicated/bare-metal runner handoff, benchmark image packaging, Bencher thresholds, "No thresholds found" dashboard warnings, benchmark alerts, or files such as `.github/workflows/benchmarks*.yml`, `.github/workflows/pgo-benchstat.yml`, `scripts/bench-bmf.mjs`, `scripts/bencher-threshold-args.sh`, `scripts/bencher-registry-login.sh`, and `build/bencher/Dockerfile`.

Platform-aware bug diagnosis and fix workflow with parallel subagents. Auto-triggers when the user mentions fixing bugs, test failures, CI failures, flaky tests, error messages, race conditions, or debugging any issue. Also user-invocable as /fixer with an issue description, error output, PR number, or CI run URL. Spawns up to 3 parallel diagnostic subagents based on failure type: platform investigator (consults windows-testing, macos-testing, linux-testing), code path tracer, and pattern matcher. Produces a structured diagnosis report with root cause, fix, and prevention. Use this skill whenever you encounter test failures, CI failures, runtime errors, race detector reports, or any situation that requires diagnosing and fixing a bug — even if the user doesn't explicitly say "fix" or "debug".

Audit Go dependencies for vulnerabilities, stale modules, deprecated/retracted modules, and available updates across the root module and nested Go modules. Use before releases, for periodic dependency health checks, or when evaluating dependency upgrades.

Audit and update CI workflow versions, tool installs, MCP servers, Dependabot-covered action pins, inline binary installs, pre-commit hooks, Node.js LTS pins, and CI-created commit mechanisms. Use when preparing a release, doing monthly CI maintenance, investigating version-related CI failures, or reviewing workflow/tooling pin drift.

Publish new Invowk releases through GitHub Releases and every supported release channel. Use when preparing, dry-running, tagging, publishing, monitoring, troubleshooting, rolling back, or repairing a release; drafting release notes; validating Homebrew, WinGet, install-script, Go install, docs-versioning, Cosign, Bencher, or GoReleaser release behavior; or investigating release workflow failures.

Go coding and lint guardrails for Invowk. Use whenever Codex creates, edits, reviews, refactors, or tests Go code (*.go), changes Go linters or formatters, fixes golangci-lint/goplint/staticcheck/revive/decorder/funcorder/gocritic/modernize/perfsprint/wrapcheck/errcheck errors, or touches Go package architecture.

Testing patterns for *_test.go files, testscript CLI tests (.txtar), race conditions, TUI component testing, container test timeouts. Use when writing tests, debugging flaky tests, or setting up testscript.

Windows testing guidance for Invowk Go code. Use for Windows process lifecycle, os/exec, NTFS/MAX_PATH/sharing issues, PATH/PATHEXT, timer resolution, race detector overhead, windows-latest CI, proactive path-touching refactors (`filepath.IsAbs`, `filepath.FromSlash`, `filepath.Join`, `filepath.ToSlash`), CUE-fed path value types, volume mounts, and platform-split testscript coverage.

Draft commit-derived release notes from conventional commits since the latest semantic version tag. Use for pre-release summaries, reviewing changes since the last release, or preparing text to compare with GitHub-native GoReleaser notes.

CLI command structure, Cobra patterns, execution flow, hidden internal commands, command service adapters, and CLI-facing dependency/runtime validation. Use when working on cmd/invowk/, internal/app/commandsvc/, internal/app/deps/, internal/app/execute/, or internal/app/commandadapters/, adding commands, modifying Cobra trees, or changing CLI error/output behavior.

Container engine abstraction, Docker/Podman patterns, persistent container lifecycle, provisioning, containerfile validation, path handling, transient retry behavior, and Linux-only policy. Use when working on internal/container/, internal/containerplan/, internal/provision/, internal/runtime/container*.go, pkg/invowkfile container runtime fields, or container-related tests/docs.

CUE schema patterns for *.cue files, schema sync and behavioral sync tests, Go struct JSON tag alignment, parser/decode helpers, and error formatting. Use when editing invowkfile_schema.cue, invowkmod_schema.cue, config_schema.cue, pkg/cueutil, CUE-backed Go types, or CUE parsing/validation behavior.

Agent-optimized D2 diagram generation and maintenance for Invowk architecture docs. Use for `.d2` files, C4 architecture diagrams, sequence diagrams, flowcharts, diagram render validation, or user requests that explicitly ask for a diagram. D2 is the default for new repo diagrams.

Module/command discovery, precedence order, collision detection, source tracking, vendored module namespace policy, diagnostics, and command-scope discovery inputs. Use when working on internal/discovery/, discovery adapters, command dependency scope checks, or how invowkfiles/modules are found, namespaced, locked, and aggregated.

Documentation editing workflow for website/, Docusaurus, MDX snippets, i18n localization, architecture/diagram docs that feed the site, and versioning. Use when creating pages, updating snippets/translations/assets, or running version-docs. For documentation accuracy audits, use /review-docs instead.

Hexagonal Architecture and Domain-Driven Design guidance for Invowk's Go codebase. Use when Codex designs, reviews, refactors, or implements Go package boundaries, application services, ports/adapters, aggregates, value objects, repositories, domain services, module/discovery/runtime architecture, or when explicitly invoked for a full codebase architecture review with deterministic subagent passes and high-confidence design findings.

Comprehensive Go 1.22+ testing knowledge. Covers all go test flags and their interactions, execution model (compilation, caching, parallel scheduling), race detector internals and platform-specific overhead, go vet analyzers, context patterns decision tree, parallelism safety framework, testing package API, benchmark/fuzz APIs, gotestsum integration, and coverage tooling. Primary entry point for testing — references platform skills (windows-testing, macos-testing, linux-testing) for OS-level issues. Use this whenever working on test code, debugging test failures, or optimizing CI performance.

Schema guidelines for invowkfile.cue, invowkmod.cue, pkg/invowkfile/invowkfile_schema.cue, pkg/invowkmod/invowkmod_schema.cue, root invowkfile.cue examples, samples/invowkmods/**/*.cue, command structures, script sources/interpreters, dependency declarations, cross-platform runtime examples, capability checks, and environment variables.

Learning workflow for after substantive Invowk repo work, especially architecture changes, refactors, feature work, bug fixes, CI repairs, or explicit `/learn` requests. Use to keep `AGENTS.md`, rules, skills, hooks, and allowed memory notes up to date with durable lessons.

Invowk Linux and Ubuntu CI testing knowledge for Go. Covers process lifecycle (clone/fork+exec, process groups via setpgid, PDEATHSIG), full POSIX signal handling (SIGKILL/SIGTERM/SIGINT), exec.CommandContext signal delivery and cmd.Cancel customization, ext4/XFS case-sensitivity, inotify watch limits (ENOSPC/EMFILE/ENFILE), file descriptor limits, cgroups and namespace isolation for container tests, OOM killer risks with -race (10x memory), and the full container test infrastructure (testscript deadlines, ContainerTestContext, AcquireContainerSemaphore, flock-based cross-binary serialization). Use when debugging Linux-only failures, exit code 137, ping_group_range races, context deadline exceeded, `[!container-available]`, container test hangs, inotify errors, or the container timeout strategy.

Deep macOS-specific testing knowledge for Go. Covers APFS case-insensitivity (case-preserving), /tmp → /private/tmp symlink pitfalls, kqueue vs inotify behavior (more aggressive event coalescing), timer coalescing (100ms sleep may take 200ms), file descriptor limits (soft 256 vs Linux 1024), flock inheritance across fork, code signing edge cases, and ARM64 memory ordering on Apple Silicon. Use when debugging macOS-only or Darwin-only test failures, virtual path resolver assertion drift, watcher test flakiness, CLI testscript `[darwin]` branches, or timing failures on macos-15 CI runners.

Module system security auditing and supply-chain hardening for invowk. Use when reviewing module vulnerabilities, implementing `invowk audit`, improving `internal/audit/`, or changing module discovery, vendoring, lock files, script resolution, command scope enforcement, or related docs. Runs `invowk audit --format json` first, then adds interpretive review only for threat model drift, supply-chain code review, or documentation consistency.

Generate, update, or audit native_*.txtar mirror tests from virtual_*.txtar tests with platform-split CUE patterns and runtime mirror exemption rules. Use when creating or reviewing testscript CLI tests that need native runtime mirrors.

Comprehensive test suite review and audit for invowk. Evaluates 102 checklist items across 8 surfaces — structural hygiene, parallelism/context, test patterns/assertions, integration gating, testscript quality, virtual/native mirrors, coverage guardrails, and TUI/domain-specific testing. Detects both coverage gaps (missing branches, error paths, untested exports) and low-value tests (circular assertions, excessive mocking, dead tests). Use this skill whenever reviewing test quality, checking test coverage, auditing the test suite, preparing for releases, or evaluating whether tests adequately cover recent code changes. Always use this skill for any test review task, even if the user doesn't explicitly say "review tests" — any mention of checking test quality, verifying test coverage, or ensuring tests are comprehensive should trigger this skill.

Validate CUE schema sync after editing schemas, Go structs with JSON tags, value-type Validate() methods, enum/disjunction constraints, config defaults, or schema-owned decode behavior. Runs targeted structural and behavioral sync tests and reports mismatches.

Server state machine pattern for sshserver/, tuiserver/, core/serverbase/, and new long-running server components. Covers serverbase.Base lifecycle states (Created→Starting→Running→Stopping→Stopped/Failed), readiness, async errors, terminal states, idempotent stop, and race-safe shutdown.

Shell runtime rules for mvdan/sh virtual-sh runtime, hidden exec-sh adapters, shared virtual-shell interactive plumbing, and repository bash scripts. Covers positional arguments gotcha (prepend "--"), bash strict mode, and arithmetic increment pitfalls.

tmux-based TUI testing for durable CI coverage of interactive `invowk tui` commands, keyboard flows, TTY behavior, ANSI/text verification, coverage exemptions, and TUI flake hardening. Use testscript instead for pipe-based `tui format`/`tui style` helpers.

VHS-based visual debugging workflow for Invowk TUI demos, screenshots, demo GIFs, VHS tapes, and visual TUI regressions. Use tmux-testing for durable CI TUI tests.

u-root utility implementation patterns for internal/uroot/, virtual runtime built-in registry changes, virtual filesystem path policy, streaming I/O, error format, symlinks, and tests/cli/testdata/virtual_uroot*.txtar coverage. Use when implementing or reviewing built-in utilities for virtual-sh or virtual-lua.

Virtual-lua runtime and golua integration guidance for Invowk. Use when editing internal/runtime/lua*.go, hidden exec-virtual-lua adapters, internal/app/commandadapters Lua interactive plumbing, virtual-lua bridge APIs, golua library loading, Lua stdlib/require behavior, virtual-lua tests, virtual.utilities.enabled behavior for Lua, Lua audit discovery/checks, or docs/examples for the virtual-lua runtime.

Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.

Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.

Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.

Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.

Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.

Generate a custom checklist for the current feature based on user requirements.

Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.