diff --git a/.agents/skills/agent-instructions-authoring/SKILL.md b/.agents/skills/agent-instructions-authoring/SKILL.md index 87f798c..86d5811 100644 --- a/.agents/skills/agent-instructions-authoring/SKILL.md +++ b/.agents/skills/agent-instructions-authoring/SKILL.md @@ -1,32 +1,42 @@ --- name: agent-instructions-authoring description: Author, audit, and modify agent instructions and rule entrypoints — skills, AGENTS.md, CLAUDE.md, subagent/agent definitions, and any other file that instructs agent behavior. Use when creating, editing, renaming, or reviewing such files; when consolidating duplicated rules across them; or when validating skill metadata, discoverability, and structure. -user-invocable: true -disable-model-invocation: false --- # Agent Instructions Authoring -Use this skill for any task that creates, edits, audits, or restructures files that instruct agent behavior. This includes skills (`SKILL.md`), top-level instruction files (`AGENTS.md`, `CLAUDE.md`, repo-level agent docs), subagent and agent definitions, and any other rule/instruction entrypoint. +Use this skill for any task that creates, edits, audits, or restructures files that instruct agent behavior. This includes skills (`SKILL.md`), top-level instruction files (`AGENTS.md`, `CLAUDE.md`, repo-level agent docs), subagent and agent definitions, and any other rule/instruction entry point. -## Mandatory Spec Intake - -At the start of each task, load these references in this exact order: - -1. [Agent Skills specification](https://agentskills.io/specification) -2. The current harness documentation for skill, instruction, and agent-definition behavior and metadata. -3. Repository-specific instruction documentation for the active project (top-level instruction file, skill READMEs, related agent definitions). - -Use the loaded specs as the active source of truth for the task. Avoid static assumptions and derive requirements dynamically from the loaded references and current repository state. +Required upstream references are listed alongside the work they govern: see [Skill Authoring](#skill-authoring) for skill schema/structure references and [AGENTS.md Authoring](#agentsmd-authoring) for top-level instruction-file references. Load them when the task scope warrants; for small edits (description rewrites, wording tweaks, index updates, typo fixes), skip the load. ## Audit Scope - When auditing instruction files, analyze only the file's literal contents. Exclude system- and client-injected prompt content from the analysis. - Audit for duplicate or conflicting instructions across all repository instruction entrypoints (top-level instruction files, skills, agent/subagent definitions). - Prefer a single canonical source and cross-reference it rather than duplicating the same guidance — this applies equally to skills, `AGENTS.md`, `CLAUDE.md`, and agent definitions. -- For planning-phase completeness policy, use `planning` as canonical and keep related files as references. +- When multiple files could host the same policy, treat the most specific skill as canonical and have broader files cross-reference it. - Flag or remove drift-prone duplication that can diverge from real behavior over time. +## Validation + +- Validate skill metadata, structure, and behavior against the loaded specs. +- Validate and audit each skill `description` for discoverability quality, including clear invocation cues and relevant trigger keywords, and avoid "how it works" wording. +- When renaming or restructuring an instruction file or skill, search the repository for stale references and update them. +- Verify every `assets/…` (or equivalent referenced-resource) path resolves to an existing file and that the asset's current contents still match how the body cites them. +- Verify every concrete claim in the file before shipping: every command runs, every flag behaves as stated, every URL resolves, every directive, or syntax example matches current tool behavior. Inherited assumptions from a source skill or older docs do not count as verified. +- Run the Markdown linter required by the `markdown` skill against changed files. +- For changes that touch the `AGENTS.md` skill index or any skill directory under `.agents/skills/`, run `mise run lint-skills-index` to verify the index and on-disk skills stay in sync. + +## Critique + +The repository's general post-validation critique gate (defined in the top-level instruction file) applies to every change. This skill adds the following instruction-file-specific checks; apply them during that critique pass rather than as a separate cycle: + +- Does this rule conflict with another instruction entry point? +- Would a reasonable agent misread it? +- Does it over- or under-constrain compared to the user's actual intent? +- Is the canonical source still canonical after this edit? +- Does any rule contain authoring meta-commentary that belongs in the authoring skill? + ## Authoring Style - Write concise rules using imperative language optimized for accurate and efficient agentic execution. @@ -35,27 +45,88 @@ Use the loaded specs as the active source of truth for the task. Avoid static as - Instruct agents to choose execution approach based on efficiency, cost, capability, and task requirements instead of fixed named components. - Prefer clear, specific, and deterministic instructions that can be delegated to lower-cost but capable subagents. - Prefer delegating concrete execution work over delegating open-ended "thinking" work to subagents. -- Follow `coding-guidelines` skill markdown guidance. -- Use markdown links (`[text](url)`) instead of bare URLs so files pass markdownlint (`MD034/no-bare-urls`). +- Follow `coding-guidelines` skill Markdown guidance. +- Use Markdown links (`[text](url)`) instead of bare URLs. +- Keep behavioral guidance and authoring meta-commentary separate. Behavioral rules tell executing agents what to do; meta-commentary (labels like "this is the canonical X", directives about how other files should reference the rule, taxonomy notes, audience asides) tells skill authors how to treat the rule. Meta-commentary belongs in the authoring skill (`agent-instructions-authoring`), not embedded in the behavioral rule itself. +- When a skill has critique findings that apply only to its own domain, place them in a `## Critique` section that defers to the top-level critique gate and lists only the domain-specific checks. Do not restate the gate itself, and do not push domain-specific findings up into top-level instruction files (e.g., `AGENTS.md`). -## Validation +## Skill Authoring -- Validate skill metadata, structure, and behavior against the loaded specs. -- Validate and audit each skill `description` for discoverability quality, including clear invocation cues and relevant trigger keywords, and avoid "how it works" wording. -- When renaming or restructuring an instruction file or skill, grep the repository for stale references and update them. -- Run the configured markdown linter against changed files. +This section governs how to create, edit, and structure individual skills. -## Critique +### Required references for skill structural changes + +When creating a new skill, renaming a skill, or changing frontmatter or directory structure, load these references before editing: + +- [Agent Skills specification](https://agentskills.io/specification) — canonical `SKILL.md` frontmatter schema, directory layout, and loading model. +- Harness-specific skills documentation for each known conformant harness: + - **Claude Code** — [Skills](https://code.claude.com/docs/en/skills) + - **OpenCode** — [Skills](https://opencode.ai/docs/skills/) + - **GitHub Copilot CLI** — [Adding agent skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills) + +Compare each harness's frontmatter schema against the Agent Skills specification. Identify which fields are shared across harnesses, which are harness-specific extensions, and where any structural deviations exist. -- Treat critique and validation as separate gates: validation confirms the file parses, lints, and matches the spec; critique confirms the rule is the right rule. Both must pass. -- Before finalizing a change to an instruction entrypoint, critique it: does this rule conflict with another entrypoint? Would a reasonable agent misread it? Does it over- or under-constrain compared to the user's actual intent? Is the canonical source still canonical after this edit? -- For non-trivial rule changes (new skill, restructuring, broadened scope, renames), run a critique-capable sub-agent review before presenting the edit. Do not hard-code a single tool name; choose a capability appropriate to the active harness. -- Record how critique feedback changed the edit before presenting it. +When a harness requires a structural deviation that cannot be expressed within the `SKILL.md` format, surface the conflict to the user and present ordered alternatives — a harness-specific companion file or accepting a capability gap on that harness. -## Skill Description Authoring +Use the loaded specs as the active source of truth; derive requirements dynamically from the references and current repository state rather than static assumptions. For description rewrites, body wording changes, or other non-structural edits, skip the load. + +### Frontmatter and metadata + +- Set `name` to a kebab-case slug that matches the skill's directory name. +- Match every required frontmatter field to the Agent Skills specification; prefer spec fields over harness-specific extensions. +- The fields `name`, `description`, `license`, and `allowed-tools` are recognized across all known conformant harnesses. The optional spec fields `compatibility` and `metadata` are spec-defined but not documented by all harnesses — include them when useful and accept that they may be ignored. +- Harness-specific fields (e.g., Claude Code's `user-invocable`, `disable-model-invocation`) are additive — include them only when intentionally targeting that harness feature, and accept that other conformant harnesses will ignore them. + +### Scope and splitting + +- Author one skill per cohesive task domain, not per file or per tool. +- Split an existing skill when its body grows long enough that an agent will not load all of it, when two clearly separate triggers share unrelated guidance, or when sections of the body apply to disjoint user intents. +- Extend an existing skill instead of creating a new one when the new guidance shares both triggers and audience with the existing skill's scope. + +### Progressive disclosure + +- Keep `SKILL.md` to imperative behavior and rules. +- Move reference content (templates, exemplars, lookup tables, long enumerations) into an `assets/` subdirectory and reference it by relative path from the skill body. +- Reference assets explicitly by relative path; do not assume the harness autoloads them. + +### Description discoverability - Optimize every skill `description` for discoverability at skill-selection time. - Prioritize searchable task cues (domains, artifacts, user intents, aliases, and common trigger phrases) over implementation details. - Describe when to invoke the skill using concrete "use when" language and likely user wording. - Avoid descriptions that mostly explain what the skill does internally or how it works. -- Keep descriptions concise but keyword-rich so selection systems can reliably match relevant requests. +- Keep descriptions concise but keyword-rich so selection systems can reliably match relevant requests — some harnesses use keyword matching, others use semantic selection; concrete task cues work for both. +- Keep descriptions free of links, command examples, full path enumerations, and other content that belongs in the body. The `description` is a selector, not a summary. + +### Body authoring style + +- Write rules as positive, imperative directives. State what to do; describe the desired end state. Reserve "do not X" or "X is wrong" framings for cases where the antipattern is concrete, plausible, high-risk, and not already excluded by a positive rule — instruction-file authoring contains several such antipatterns (e.g., assuming the harness auto-loads referenced assets, restating canonical rules in multiple entrypoints), so negative framings appear in this skill where the exception is met. +- Negative rules carry two costs: they plant the anti-pattern in agent context (which can prompt the very behavior they forbid), and they can conflict with project-specific configuration (aliases, custom directories, custom commands) that legitimately uses the named token. +- Defer to upstream documentation as the durable source of truth. When the underlying system supports configuration (custom paths, directories, environment names, command aliases), reference the docs and the project's configuration; do not enumerate defaults inline as if they were invariant. +- Keep guidance language-, tool-, and version-agnostic where possible. State the rule generically and use language-specific or version-specific names only as examples, not as the rule itself. +- Prefer linking to canonical documentation over restating it; restated facts drift, links do not (and broken links are caught by validation). + +## AGENTS.md Authoring + +This section governs how to create, edit, and structure `AGENTS.md` files. + +### Required references for AGENTS.md structural changes + +When creating, restructuring, or pairing `AGENTS.md` with harness-specific instruction files, load these references before editing: + +- **Claude Code** — [Memory & CLAUDE.md](https://code.claude.com/docs/en/memory) +- **OpenCode** — [Rules](https://opencode.ai/docs/rules/) + +For small edits (rule wording tweaks, single-entry index updates), skip the load. + +### Authoring behavior + +- Keep `AGENTS.md` to rules that apply to all agents and all tasks, regardless of domain, language, or workflow, plus a skill index. Anything narrower belongs in a skill. +- Extract domain-, language-, or workflow-specific guidance into skills and reference them from the index. +- Update the index in the same change that adds, renames, or removes a skill. +- Pair every `AGENTS.md` with a `CLAUDE.md` at the same path whose entire contents are the literal string `@AGENTS.md` (and nothing else). Create, move, rename, and delete them in lockstep. This ensures Claude resolves to the same canonical entry point as other harnesses. + +### Required Skills section content + +- Use [`assets/agents-md-index-section.template.md`](assets/agents-md-index-section.template.md) as the canonical template for the `AGENTS.md` Skills section. Mirror its preamble verbatim, adapting only the skills-location reference to the active harness. +- Populate the index from the actual skill directory: one entry per skill, using the skill's frontmatter `name` and a one-line summary derived from its `description`. diff --git a/.agents/skills/agent-instructions-authoring/assets/agents-md-index-section.template.md b/.agents/skills/agent-instructions-authoring/assets/agents-md-index-section.template.md new file mode 100644 index 0000000..f6c890c --- /dev/null +++ b/.agents/skills/agent-instructions-authoring/assets/agents-md-index-section.template.md @@ -0,0 +1,11 @@ +## Skills + +The skills below are available under ``. + +- **MUST NOT** preload any skill in this index. Load a skill only when the current task matches its description or use-when criteria. +- Keep this index synchronized with the contents of ``; when adding, renaming, or removing a skill, update this section in the same change. Each entry must use the skill's frontmatter `name` and a one-line summary of its `description`. +- For changes to this file, any listed skill, subagent/agent definitions, or other rule entrypoints, use the `agent-instructions-authoring` skill as the canonical source. + +### Index + +- `` — diff --git a/.agents/skills/agentic-projects/SKILL.md b/.agents/skills/agentic-projects/SKILL.md index acf4916..cfbf12c 100644 --- a/.agents/skills/agentic-projects/SKILL.md +++ b/.agents/skills/agentic-projects/SKILL.md @@ -1,9 +1,6 @@ --- name: agentic-projects -description: Organize per-repo agentic project workspaces under .agents/projects/. Use when initializing or maintaining project prompt, plans, research, and temporary artifacts. -user-invocable: true -disable-model-invocation: true -argument-hint: --project --prompt "" [--force] +description: Organize per-repo agentic project workspaces under .agents/projects/. Use when initializing or maintaining project prompts, plans, research, and temporary artifacts. allowed-tools: Bash(bash ~/.agents/skills/agentic-projects/scripts/manage-agentic-project.sh) metadata: scripts: scripts/manage-agentic-project.sh diff --git a/.agents/skills/agentic-projects/scripts/manage-agentic-project.sh b/.agents/skills/agentic-projects/scripts/manage-agentic-project.sh old mode 100644 new mode 100755 diff --git a/.agents/skills/coding-guidelines/SKILL.md b/.agents/skills/coding-guidelines/SKILL.md index 2dd315e..8600d91 100644 --- a/.agents/skills/coding-guidelines/SKILL.md +++ b/.agents/skills/coding-guidelines/SKILL.md @@ -28,7 +28,7 @@ description: Apply repository coding standards for implementation and review tas - Only add comments if they match existing style or explain complex changes - Use existing libraries whenever possible - Only add new libraries or update versions if absolutely necessary -- **MUST ALWAYS** validate all rules were followed after completing changes +- Validate that all rules were followed after completing changes - Handle all errors - Validate all user inputs and system states - Run linters, builds, and tests before making changes to understand unrelated issues @@ -36,24 +36,17 @@ description: Apply repository coding standards for implementation and review tas - Use refactoring tools to automate changes - Use linters and formatters to fix code style and correctness - Use local variables to limit scope -- **ALWAYS** add and update type annotations +- Always add and update type annotations -## Critique Before Validation +## Critique Gate -- Treat critique and validation as separate gates: validation confirms the change passes tests, types, and lints; critique confirms the change is the right change. Both must pass. -- Before declaring an implementation done, run a critique pass that asks: should this exist at all? Is this the right abstraction? What breaks under realistic edge cases? Which assumptions does the surrounding code not actually guarantee? -- For non-trivial changes, run a critique-capable sub-agent review (or equivalent independent reviewer) before reporting completion, not after. Do not hard-code a single tool name; choose a capability appropriate to the active harness. -- Record how critique feedback changed the implementation before presenting it. +Follow the canonical critique-before-completion gate defined in `AGENTS.md`. Apply the universal gate to every change; layer domain-specific checks on top during the same pass when relevant. -## Lua (Neovim, Hammerspoon, WezTerm, Yazi) +## Language-Specific Guidance -- Organize `---@module` references at the top of the file, sorted alphabetically -- Use explicit module returns and clear structure - -## Shell Scripts (Zsh) - -- Use consistent logging functions -- Use `set -euo pipefail` for error safety +- Lua (Neovim, Hammerspoon, WezTerm, Yazi) — see the `lua` skill +- Zsh shell scripts — see the `zsh` skill +- Markdown — see the `markdown` skill ## Configuration Files @@ -61,14 +54,3 @@ description: Apply repository coding standards for implementation and review tas - Logical grouping with fallback values - Modular structure separating concerns - **MUST NOT** manually edit tool-generated lock files; they are managed by their respective tools - -## Markdown - -- Be clear and succinct -- **MUST NOT** write redundant or duplicate content, use link references -- Use standard `[text](url)` links, not wiki-style -- Validate all reference links after changes -- **MUST NOT** create table of contents unless explicitly requested - - If one exists, keep it synchronized with actual sections -- Analyze the whole file and suggest optimizations according to these rules -- Validate markdown files with the project's configured markdown linter when available diff --git a/.agents/skills/commit-guidelines/SKILL.md b/.agents/skills/commit-guidelines/SKILL.md index 2389178..58653e5 100644 --- a/.agents/skills/commit-guidelines/SKILL.md +++ b/.agents/skills/commit-guidelines/SKILL.md @@ -5,8 +5,7 @@ description: Create branches and commits from local diffs with correct commit me # Commit and Branch Guidelines -- **MUST NOT** skip hooks execution under any circumstances -- **MUST NEVER** use hook-bypass flags (for example: `git commit --no-verify`, `git merge --no-verify`, `git push --no-verify`) or any equivalent hook-disabling workaround +Follow the canonical hook-bypass policy in `AGENTS.md` (Tool Usage). For git specifically, this means commands such as `git commit --no-verify`, `git merge --no-verify`, and `git push --no-verify` are not used; failing hooks must be fixed at the root cause. ## Analyze Changes diff --git a/.agents/skills/github-cli/SKILL.md b/.agents/skills/github-cli/SKILL.md index bd364b8..2adb0a3 100644 --- a/.agents/skills/github-cli/SKILL.md +++ b/.agents/skills/github-cli/SKILL.md @@ -1,6 +1,6 @@ --- name: github-cli -description: Use gh CLI for GitHub operations. Invoke when working with pull requests, issues, workflow runs, releases, repository metadata, or file content on GitHub. +description: Use the `gh` CLI for pull requests, issues, workflow runs, releases, repository metadata, and file content on GitHub. Use when interacting with any GitHub resource from the terminal. --- # GitHub CLI Rules diff --git a/.agents/skills/hammerspoon/SKILL.md b/.agents/skills/hammerspoon/SKILL.md index dc263e8..c876d15 100644 --- a/.agents/skills/hammerspoon/SKILL.md +++ b/.agents/skills/hammerspoon/SKILL.md @@ -1,6 +1,6 @@ --- name: hammerspoon -description: AI rules and guidelines for Hammerspoon macOS automation and window management configuration using Lua scripting. Use when working with Hammerspoon scripts, Spoons, hotkeys, or window management code. +description: Apply Hammerspoon macOS automation and window management configuration rules. Use when working with Hammerspoon scripts, Spoons, hotkeys, or window management Lua code. --- # Hammerspoon Configuration - AI Rules and Guidelines @@ -43,3 +43,7 @@ description: AI rules and guidelines for Hammerspoon macOS automation and window - Test window movements across multiple displays - Validate modal states exit correctly - Monitor Hammerspoon console for errors + +## Cross-references + +- For general Lua authoring conventions (module structure, EmmyLua annotations) see the `lua` skill. diff --git a/.agents/skills/lua/SKILL.md b/.agents/skills/lua/SKILL.md new file mode 100644 index 0000000..e9ddb2e --- /dev/null +++ b/.agents/skills/lua/SKILL.md @@ -0,0 +1,22 @@ +--- +name: lua +description: Apply Lua authoring conventions for Neovim, Hammerspoon, WezTerm, and Yazi configurations. Use when writing, editing, or refactoring Lua modules, plugin configs, or scripts in this repository. +--- + +# Lua Authoring Conventions + +## Module Structure + +- Organize `---@module` references at the top of the file, sorted alphabetically. +- Use explicit module returns and clear structure. +- Keep one cohesive responsibility per module; split when a module grows two unrelated concerns. + +## Annotations + +- Use EmmyLua annotations for public functions, types, and module returns. +- Annotate parameters and return types so downstream tooling (LSP, type checkers) can reason about them. + +## Cross-references + +- For Neovim-specific patterns (LazyVim plugins, `which-key`, LSP integration) see the `nvim` skill. +- For Hammerspoon-specific patterns (Spoons, modifier keys, window management) see the `hammerspoon` skill. diff --git a/.agents/skills/markdown/SKILL.md b/.agents/skills/markdown/SKILL.md new file mode 100644 index 0000000..55bcf49 --- /dev/null +++ b/.agents/skills/markdown/SKILL.md @@ -0,0 +1,24 @@ +--- +name: markdown +description: Apply Markdown authoring conventions for clarity, link style, table-of-contents discipline, and linter validation. Use when writing or editing Markdown files, documentation, READMEs, or instruction files. +--- + +# Markdown Authoring Conventions + +## Style + +- Write clearly and succinctly. +- Use standard `[text](url)` links; do not use wiki-style links. +- Replace redundant or duplicated content with link references to a single canonical location. +- Prefer lists over tables. Use a table only when readers genuinely need to scan multiple parallel attributes across many rows; otherwise present the same content as a bulleted or definition list, which renders more reliably in narrow viewports, plain-text diff tools, and screen readers. + +## Table of Contents + +- Create a table of contents only when explicitly requested. +- When a table of contents exists, keep it synchronized with the actual section headings. + +## Validation + +- Validate all reference links after changes; fix dangling or moved targets. +- Analyze the whole file and apply these rules consistently; flag deviations. +- Validate Markdown files with the project's configured Markdown linter when available. diff --git a/.agents/skills/mise-tasks/SKILL.md b/.agents/skills/mise-tasks/SKILL.md new file mode 100644 index 0000000..5b35f8c --- /dev/null +++ b/.agents/skills/mise-tasks/SKILL.md @@ -0,0 +1,46 @@ +--- +name: mise-tasks +description: Add, modify, or invoke mise tasks (file tasks and TOML tasks); wire task help via usage directives; run tasks with mise run. Use when adding, modifying, running, or debugging tasks in a mise-managed project. +--- + +# Mise Tasks + +Use this skill when adding, modifying, or invoking [mise](https://mise.jdx.dev/) tasks in any project that adopts mise as its task runner. + +This skill complements the `scripts` skill (broader script authoring, testing, and integration workflow). When both apply, prefer the more specific rule here for task-runner specifics and defer to `scripts` for general script structure. + +## Discovery and Execution + +- List tasks with [`mise tasks`](https://mise.jdx.dev/cli/tasks.html) (alias `mise tasks ls`). +- Inspect a single task with `mise tasks info `. +- Render task help with `mise run --help` (or `-h`). See [`mise run`](https://mise.jdx.dev/cli/run.html) and [running tasks](https://mise.jdx.dev/tasks/running-tasks.html). + +## Authoring Conventions + +Mise supports two task styles. Detect the style the project already uses and match it; do not introduce a second style without a clear reason. + +### File tasks + +See [file tasks](https://mise.jdx.dev/tasks/file-tasks.html). + +- Place file tasks in the project's configured tasks directory; refer to the docs for the supported defaults and how `task_config.includes` overrides them. +- Make the file executable; mise auto-registers executable files in the tasks directory. +- Before authoring a file task, assess whether any of its logic should be reusable across other tasks or scripts. When it should, extract the reusable code into a directory outside the mise-detected tasks directory and import it from the task file. Keep the task namespace populated only by tasks; let shared logic live alongside the project's other source code for clearer separation of concerns. + +### TOML tasks + +See [TOML tasks](https://mise.jdx.dev/tasks/toml-tasks.html). + +- Define TOML tasks as `[tasks.]` tables (one table per task) in `mise.toml` or `.mise.toml`. +- Configure metadata (`description`, `depends`, `env`, `sources`, `outputs`, `dir`, `usage`, `quiet`, etc.) per [task configuration](https://mise.jdx.dev/tasks/task-configuration.html). + +## Usage and Help + +- Prefer mise's [usage](https://usage.jdx.dev/) feature for argument parsing, option configuration, defaults, validation, and help on file tasks. Let usage own the task's interface; keep in-script code focused on the task's behavior rather than reimplementing argument parsing. +- Define the task interface with mise's usage directives appropriate to the task's language. Examples: `#USAGE` for shell file tasks, `//USAGE` for TypeScript file tasks, and the `usage` field on TOML tasks. See the [Arguments section](https://mise.jdx.dev/tasks/file-tasks.html#arguments) of the file-tasks docs. +- Rely on mise's native help rendering; do not implement custom help printing inside task scripts. +- Treat unknown or incomplete options as explicit errors. + +## Output + +- Set tasks to `quiet` by default so mise does not prefix task output with `[task-name]`. Use `quiet = true` for TOML tasks and the equivalent `#MISE quiet=true` directive for file tasks (or whichever directive syntax the task's language uses, per [task configuration](https://mise.jdx.dev/tasks/task-configuration.html)). diff --git a/.agents/skills/nvim/SKILL.md b/.agents/skills/nvim/SKILL.md index 15bd404..006108e 100644 --- a/.agents/skills/nvim/SKILL.md +++ b/.agents/skills/nvim/SKILL.md @@ -1,6 +1,6 @@ --- name: nvim -description: AI rules and guidelines for the Neovim configuration built on LazyVim with Lua scripting, LSP integration, and plugin management. Use when working with Neovim configuration files, plugins, or Lua modules. +description: Apply LazyVim Neovim configuration rules for Lua scripting, LSP integration, and plugin management. Use when working with Neovim configuration files, plugins, or Lua modules. --- # Neovim Configuration - AI Rules and Guidelines @@ -38,3 +38,7 @@ description: AI rules and guidelines for the Neovim configuration built on LazyV - Monitor startup time and memory usage with `:Lazy profile` - Ensure compatibility with LazyVim updates before upgrading - Make small, testable, reversible changes + +## Cross-references + +- For general Lua authoring conventions (module structure, EmmyLua annotations) see the `lua` skill. diff --git a/.agents/skills/opencode-copilot-multipliers/scripts/sync-opencode-copilot-multipliers.ts b/.agents/skills/opencode-copilot-multipliers/scripts/sync-opencode-copilot-multipliers.ts old mode 100644 new mode 100755 diff --git a/.agents/skills/planning/SKILL.md b/.agents/skills/planning/SKILL.md index f3edc2c..8e51411 100644 --- a/.agents/skills/planning/SKILL.md +++ b/.agents/skills/planning/SKILL.md @@ -1,7 +1,6 @@ --- name: planning description: Produce execution-ready implementation plans for complex work. Use when tasks are multi-step, high-risk, ambiguous, or span multiple files/services. -user-invocable: false --- # Planning @@ -15,7 +14,7 @@ Before execution, confirm all of the following: 1. **Exploration complete**: relevant codepaths, docs, and constraints are identified. 2. **Unknowns handled**: unknowns are resolved or converted into explicit user questions. 3. **Conversational planning complete**: planning interaction challenges assumptions, pressure-tests risks, and avoids passive transcription. -4. **Critique pass complete**: every time the plan is updated, run a critique-capable sub-agent review before presenting the updated plan to the user. +4. **Critique pass complete**: every time the plan is updated, apply the canonical critique gate defined in `AGENTS.md` before presenting the updated plan to the user. 5. **Deterministic sequence**: execution steps are ordered, concrete, and testable. 6. **Failure protocol ready**: rollback/mitigation approach is clear for risky operations. @@ -27,12 +26,6 @@ Before execution, confirm all of the following: - Ask focused clarifying questions when requirements are ambiguous. - Keep the planning loop interactive until execution steps are unambiguous. -## Critique-Agent Requirement - -- The critique step must use a sub-agent with critique/review capability. -- Do not hard-code a single tool name as universally available across harnesses. -- Record how critique feedback changed the updated plan before presenting it. - ## Execution Guardrails - Do not start execution with unresolved decision branches. diff --git a/.agents/skills/rewrite-imports/SKILL.md b/.agents/skills/rewrite-imports/SKILL.md index 00a490e..be1e858 100644 --- a/.agents/skills/rewrite-imports/SKILL.md +++ b/.agents/skills/rewrite-imports/SKILL.md @@ -1,6 +1,6 @@ --- name: rewrite-imports -description: Migrate import paths safely across many files. Use when renaming modules/packages, moving files, or bulk-rewriting import statements after refactors. +description: Bulk-migrate import paths after module renames, file moves, or package refactors. Use when changing how modules are referenced across many files. --- # Rewrite Imports diff --git a/.agents/skills/scripts/SKILL.md b/.agents/skills/scripts/SKILL.md index a65cd6f..9191c83 100644 --- a/.agents/skills/scripts/SKILL.md +++ b/.agents/skills/scripts/SKILL.md @@ -72,3 +72,7 @@ When a task requires a script for execution: - Make new scripts generic and reusable. - Save new scripts in the project's reusable script location. - Write script documentation optimized for AI agents (see `coding-guidelines` skill). + +## Cross-references + +- For Zsh-specific conventions (error safety, logging helpers) see the `zsh` skill. diff --git a/.agents/skills/security/SKILL.md b/.agents/skills/security/SKILL.md index 3cf425a..3534088 100644 --- a/.agents/skills/security/SKILL.md +++ b/.agents/skills/security/SKILL.md @@ -1,6 +1,6 @@ --- name: security -description: Apply security checks and safeguards during implementation. Use when handling secrets, permissions, external network access, dependency risk, or security-sensitive configuration. +description: Apply security checks for secrets, credentials, permissions, external network access, dependency risk, and sensitive configuration. Use during implementation, code review, and security review passes. --- # Security Guidelines diff --git a/.agents/skills/task-orchestration/SKILL.md b/.agents/skills/task-orchestration/SKILL.md new file mode 100644 index 0000000..ce1ef66 --- /dev/null +++ b/.agents/skills/task-orchestration/SKILL.md @@ -0,0 +1,32 @@ +--- +name: task-orchestration +description: Decide when to parallelize tool calls, when to spawn, launch, or dispatch subagents instead of running directly, which model tier (higher- vs lower-capability) suits each sub-task, and how to coordinate multi-step work via shared scratch, temp, or orchestration directories. Use when fanning out concurrent tool calls, delegating scopes to subagents, picking a capability tier for sub-work, or sharing intermediate files across steps. +--- + +# Task Orchestration + +Use this skill when shaping how a task executes: whether to fan out tool calls in parallel, delegate scopes to subagents, pick a model tier per sub-task, or coordinate intermediate artifacts across steps. + +## Tools vs Subagents + +- Prefer direct tool calls for small, bounded, local operations. +- Use subagents when work is long-running, requires an isolated context window, benefits from model-tier selection, or would exhaust the parent's context budget. +- Do not dispatch a subagent for a task the parent can resolve directly in a few tool calls. + +## Subagent Discipline + +- Once a subagent owns a scope, do not redo that same scope in the parent. +- Keep each subagent prompt explicit about goals, constraints, inputs, and expected output format. +- Aggregate and reconcile outputs from multiple subagents before applying changes. + +## Model Selection + +- Choose the lowest-cost model that can reliably meet the task quality bar. +- Use faster/cheaper models for narrow, low-risk, repetitive, or format-constrained work. +- Use higher-capability models for ambiguous requirements, cross-file reasoning, architecture decisions, safety-critical changes, or failure recovery. +- When splitting work across subagents, match model capability to each sub-task instead of using one tier for everything. + +## Orchestration Artifacts + +- Coordinate multi-step or multi-agent work through a shared temporary directory; prefer a repository-scoped location (for example, `.agents/projects//tmp/` — see the `agentic-projects` skill for the path convention) when artifacts should be inspectable during the task, and a session-scoped location otherwise. +- Clean up temporary artifacts when the task is complete unless explicitly asked to persist them. diff --git a/.agents/skills/zsh/SKILL.md b/.agents/skills/zsh/SKILL.md new file mode 100644 index 0000000..c1a2a08 --- /dev/null +++ b/.agents/skills/zsh/SKILL.md @@ -0,0 +1,19 @@ +--- +name: zsh +description: Apply Zsh shell scripting conventions for error safety and logging. Use when authoring, modifying, or reviewing Zsh scripts, including mise file tasks and bootstrap scripts. +--- + +# Zsh Scripting Conventions + +## Error Safety + +- Use `set -euo pipefail` at the top of every Zsh script to fail fast on errors, undefined variables, and broken pipes. + +## Logging + +- Use consistent logging functions across scripts in the same project; detect and reuse existing helpers before introducing new ones. + +## Cross-references + +- For broader script-authoring guidance (project pattern detection, environment configuration, testing, integration) see the `scripts` skill. +- For mise-specific task authoring (file tasks, TOML tasks, usage directives) see the `mise-tasks` skill. diff --git a/.config/harper/dictionaries/user.txt b/.config/harper/dictionaries/user.txt index bcf25af..c70413d 100644 --- a/.config/harper/dictionaries/user.txt +++ b/.config/harper/dictionaries/user.txt @@ -2,6 +2,7 @@ ASCIIDoc Artifactory Autodesk BEM +CLAUDE CodeCompanion Contentful Crowdmark @@ -31,15 +32,18 @@ Wezterm automations bg cli +conformant darwin deduplication eslint fintech ish lua +md minusfive modularity param postambles schemas +subagents symlink diff --git a/.config/zsh/.p10k.zsh b/.config/zsh/.p10k.zsh index 19f7d6e..3b6d07c 100644 --- a/.config/zsh/.p10k.zsh +++ b/.config/zsh/.p10k.zsh @@ -417,6 +417,7 @@ # Styling for up-to-date Git status. local meta='%244F' # default foreground local clean='%002F' # green foreground + local staged='%002F' # green foreground local modified='%178F' # yellow foreground local untracked="%001F" # blue foreground local conflicted='%196F' # red foreground @@ -424,6 +425,7 @@ # Styling for incomplete and stale Git status. local meta='%244F' # grey foreground local clean='%244F' # grey foreground + local staged='%244F' # grey foreground local modified='%244F' # grey foreground local untracked='%244F' # grey foreground local conflicted='%244F' # grey foreground @@ -491,7 +493,7 @@ # ~42 if have merge conflicts. (( VCS_STATUS_NUM_CONFLICTED )) && res+=" ${conflicted}~${VCS_STATUS_NUM_CONFLICTED}" # +42 if have staged changes. - (( VCS_STATUS_NUM_STAGED )) && res+=" ${modified}+${VCS_STATUS_NUM_STAGED}" + (( VCS_STATUS_NUM_STAGED )) && res+=" ${staged}+${VCS_STATUS_NUM_STAGED}" # !42 if have unstaged changes. (( VCS_STATUS_NUM_UNSTAGED )) && res+=" ${modified}!${VCS_STATUS_NUM_UNSTAGED}" # ?42 if have untracked files. It's really a question mark, your font isn't broken. diff --git a/.harper-dictionary.txt b/.harper-dictionary.txt index eb0d8c6..de39806 100644 --- a/.harper-dictionary.txt +++ b/.harper-dictionary.txt @@ -9,6 +9,7 @@ HiDPI LazyVim Lazygit LuaDoc +OpenCode Podman Snyk Statusline @@ -20,6 +21,7 @@ XDG Zsh autocmds btop +entrypoints frontmatter fzf gh @@ -30,5 +32,6 @@ mise neovim nvim postinstall +subagent tmux wget diff --git a/AGENTS.md b/AGENTS.md index 97d8893..086f25e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,20 +7,25 @@ - Investigate uncertainty first rather than confirming assumptions. - Apply rigorous standards consistently to all ideas. - Critique plans and implementations; do not merely validate them. Surface blind spots, weak assumptions, edge cases, and sequencing risks even when the work appears correct. +- Treat critique as a discrete gate that runs AFTER the implementation passes validation (lint, tests, structural checks). Before declaring a task complete, run a fresh critique pass over the actual produced artifact. Do not treat any validation step as the stopping signal; the critique pass is. - Be concise and direct; focus output on the specific task and skip unnecessary preambles and postambles. - Ask for confirmation before destructive or irreversible operations. -- **MUST NOT** use emojis or icons unless explicitly requested. +- **MUST NOT** use emojis or icons unless explicitly requested. The verdict-glyph convention below is the only sanctioned exception. -## Planning +### Verdict output glyphs -- For planning behavior, gates, and transition-to-execution readiness, defer to the `planning` skill as the canonical source. -- When new unknowns emerge mid-execution: **STOP** the affected scope, **RETURN** to planning, **RESOLVE** the unknown or ask an explicit question before resuming. Do not guess, defer, or continue with unresolved decision points. +In critique, review, audit, and other verdict-style output (any structured report that classifies items as pass / fail / risk), label each classified item with the canonical Unicode status glyph below, rendered in the named semantic color. Apply only to verdict-bearing items; leave ordinary prose, headings, and unclassified bullet lists undecorated. The active harness chooses how to realize the color; do not hard-code escape sequences inline. + +- `✓` green — pass: claim verified, rule survives critique, no action needed. +- `✗` red — fail: claim falsified, rule rejected, change must not ship as-is. +- `⚠` yellow — risk: known unknown, residual edge case, or assumption deliberately accepted but worth surfacing. +- `ℹ` cyan — note: contextual remark that is neither a verdict nor a risk. ## Asking and Failing Gracefully ### When to ask -- When confidence is below 90%. +- When the correct approach is unclear after checking available context. - When security implications exist. - When requirements are ambiguous. - When multiple valid approaches materially change outcomes. @@ -30,43 +35,52 @@ ### How to present choices - When presenting multiple possible actions, configurations, or solutions, offer an ordered list of options. +- Place the recommended option first; order the remainder by likely preference. +- Use the active harness's structured ask capability (for example, a question-with-options tool) when it is available and the choices are mutually exclusive; otherwise present them as a numbered list in prose. +- Keep each option short and self-explanatory; reserve free-text input for divergent answers. + +### When tool calls are rejected or refused -### When operations are rejected or fail +This protocol applies to permission denials, policy refusals, and explicit user rejections of a tool call — not to ordinary task failures (failing tests, missing dependencies, transient errors), which follow normal debugging behavior. 1. **STOP** the current approach immediately. 2. **ASK** what changed and what outcome is preferred. 3. **WAIT** for instructions before proceeding. 4. **DO NOT** retry the same approach without new information. -## Parallelization and Subagents - -- Combine independent tool calls in parallel; sequence calls only when later parameters depend on earlier results. -- Prefer direct tool calls for small, bounded, local operations. Use subagents when work is long-running, requires an isolated context window, benefits from model-tier selection, or would exhaust the parent's context budget. -- Once a subagent owns a scope, do not redo that same scope in the parent. Keep each subagent prompt explicit about goals, constraints, and expected outputs. Aggregate and reconcile outputs before applying changes. - -## Model Selection - -- Choose the lowest-cost model that can reliably complete the task quality bar. -- Use faster/cheaper models for narrow, low-risk, repetitive, or format-constrained work. -- Use higher-capability models for ambiguous requirements, cross-file reasoning, architecture decisions, safety-critical changes, or failure recovery. -- When splitting work across subagents, match model capability to each sub-task instead of using one tier for everything. - -## Orchestration Artifacts - -- Coordinate multi-step or multi-agent work through a shared temporary directory; prefer a repository-scoped location (for example, `.agents/projects//tmp/`) when artifacts should be inspectable during the task, and a session-scoped location otherwise. -- Clean up temporary artifacts when the task is complete unless explicitly asked to persist them. - ## Tool Usage - Never bypass repository hooks (`--no-verify` or equivalent). - Prefer dedicated tools (linters, language servers, formatters, refactoring tools, file-discovery and edit tools) over ad-hoc shell commands. - Minimize command output using quiet/no-pager flags and targeted filtering supported by the active environment. -- Use the `project-overview` skill for project structure and configuration discovery before implementation in unfamiliar areas. - -## Skill Discovery - -- Look for skills in local project `.agents/` and global `~/.agents/` directories in addition to default locations. - -## Authoring this file and related entrypoints - -- For changes to this file, `CLAUDE.md`, skills, subagent/agent definitions, or any other rule entrypoint, use the `agent-instructions-authoring` skill as the canonical source. +- Combine independent tool calls in parallel; sequence calls only when later parameters depend on earlier results. Do not artificially serialize independent operations to "be safe" — parallelism is the default for independent work. + +## Skills + +The skills below are available under `.agents/skills/`. + +- **MUST NOT** preload any skill in this index. Load a skill only when the current task matches its description or use-when criteria. +- Keep this index synchronized with the contents of `.agents/skills/`; when adding, renaming, or removing a skill, update this section in the same change. Each entry must use the skill's frontmatter `name` and a one-line summary of its `description`. +- For changes to this file, any listed skill, subagent/agent definitions, or other rule entrypoints, use the `agent-instructions-authoring` skill as the canonical source. + +### Index + +- `agent-instructions-authoring` — Author, audit, and modify agent instruction files (skills, `AGENTS.md`, `CLAUDE.md`, subagent/agent definitions); consolidate duplicated rules; validate skill metadata and discoverability. +- `agentic-projects` — Organize per-repo agentic project workspaces under `.agents/projects//` (prompts, plans, research, temporary artifacts). +- `coding-guidelines` — Apply repository coding standards when adding features, fixing bugs, refactoring, updating tests, or resolving lint/type/build issues. +- `commit-guidelines` — Create branches and commits from local diffs using project commit-message conventions (Conventional Commits, commitlint). +- `github-cli` — Use the `gh` CLI for pull requests, issues, workflow runs, releases, repository metadata, and file content on GitHub; invoke when interacting with any GitHub resource from the terminal. +- `hammerspoon` — Apply Hammerspoon macOS automation and window management rules when working with scripts, Spoons, hotkeys, or Lua code. +- `lua` — Apply Lua authoring conventions for Neovim, Hammerspoon, WezTerm, and Yazi configurations (module structure, returns, EmmyLua annotations). +- `markdown` — Apply Markdown authoring conventions (clarity, link style, table-of-contents discipline, linter validation). +- `mise-tasks` — Add, modify, or invoke mise tasks (file tasks and TOML tasks); wire task help via usage directives; run tasks with mise run. +- `nvim` — Apply LazyVim Neovim configuration rules when working with config files, plugins, or Lua modules. +- `opencode-copilot-multipliers` — Sync GitHub Copilot model alias multiplier labels in the OpenCode config with current `github/docs` paid multipliers. +- `planning` — Produce execution-ready implementation plans for multi-step, high-risk, ambiguous, or multi-file/service work. +- `pr-guidelines` — Push branches and open pull requests using the project's title/body conventions and linked issues. +- `project-overview` — Discover project structure, architecture, and tooling before implementation in an unfamiliar area. +- `rewrite-imports` — Bulk-migrate import paths after module renames, file moves, or package refactors; use when changing how modules are referenced across many files. +- `scripts` — Author and maintain setup, automation, and bootstrap shell/task scripts and install flows. +- `security` — Apply security checks for secrets, credentials, permissions, external network access, dependency risk, and sensitive configuration; use during implementation and security review passes. +- `task-orchestration` — Decide when to parallelize tool calls, when to dispatch subagents, which model tier suits each sub-task, and how to coordinate multi-step work via shared temporary artifacts. +- `zsh` — Apply Zsh shell scripting conventions (error safety, logging helpers); use when authoring or modifying Zsh scripts. diff --git a/CLAUDE.md b/CLAUDE.md index feca6f6..43c994c 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1 @@ -See `AGENTS.md` for project instructions. +@AGENTS.md diff --git a/mise.toml b/mise.toml index 88a926c..c6119a5 100644 --- a/mise.toml +++ b/mise.toml @@ -5,6 +5,9 @@ lockfile = true HK_MISE = 1 HK_STAGE = 1 +[task_config] +includes = ["scripts/tasks"] + [tools] bun = "latest" betterleaks = "latest" @@ -14,19 +17,3 @@ hk = "latest" shellcheck = "latest" stylua = "latest" yamllint = "latest" - -[tasks.check] -description = "Run all checks" -run = "hk run check" - -[tasks.fix] -description = "Fix all (fixable) issues" -run = "hk run fix" - -[tasks.pre-commit] -description = "Run pre-commit hooks" -run = "hk run pre-commit" - -[tasks.setup] -description = "Set up the development environment" -run = ["bun install", "hk install"] diff --git a/scripts/tasks/check b/scripts/tasks/check new file mode 100755 index 0000000..44d547c --- /dev/null +++ b/scripts/tasks/check @@ -0,0 +1,7 @@ +#!/usr/bin/env zsh +#MISE description="Run all checks" +#MISE quiet=true + +set -euo pipefail + +hk run check "$@" diff --git a/scripts/tasks/fix b/scripts/tasks/fix new file mode 100755 index 0000000..306176e --- /dev/null +++ b/scripts/tasks/fix @@ -0,0 +1,7 @@ +#!/usr/bin/env zsh +#MISE description="Fix all (fixable) issues" +#MISE quiet=true + +set -euo pipefail + +hk run fix "$@" diff --git a/scripts/tasks/lint-skills-index b/scripts/tasks/lint-skills-index new file mode 100755 index 0000000..95eefae --- /dev/null +++ b/scripts/tasks/lint-skills-index @@ -0,0 +1,33 @@ +#!/usr/bin/env zsh +#MISE description="Verify AGENTS.md skill index is in sync with .agents/skills/" +#MISE quiet=true + +set -euo pipefail + +repo_root="${MISE_PROJECT_ROOT:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}" +agents_md="${repo_root}/AGENTS.md" +skills_dir="${repo_root}/.agents/skills" + +if [[ ! -f "$agents_md" ]]; then + print -u2 -- "error: ${agents_md} not found" + exit 2 +fi +if [[ ! -d "$skills_dir" ]]; then + print -u2 -- "error: ${skills_dir} not found" + exit 2 +fi + +on_disk=$(find "$skills_dir" -maxdepth 1 -mindepth 1 -type d -exec basename {} \; | sort) +in_index=$(grep -E '^- `[a-z][a-z0-9-]+` —' "$agents_md" | sed -E 's/^- `([^`]+)`.*$/\1/' | sort -u) + +if diff <(print -r -- "$on_disk") <(print -r -- "$in_index") >/dev/null; then + print -- "AGENTS.md skill index is in sync with .agents/skills/" + exit 0 +fi + +print -u2 -- "AGENTS.md skill index out of sync with .agents/skills/" +print -u2 -- "--- on-disk ---" +print -u2 -r -- "$on_disk" +print -u2 -- "--- in-index ---" +print -u2 -r -- "$in_index" +exit 1 diff --git a/scripts/tasks/pre-commit b/scripts/tasks/pre-commit new file mode 100755 index 0000000..a6b7a01 --- /dev/null +++ b/scripts/tasks/pre-commit @@ -0,0 +1,7 @@ +#!/usr/bin/env zsh +#MISE description="Run pre-commit hooks" +#MISE quiet=true + +set -euo pipefail + +hk run pre-commit "$@" diff --git a/scripts/tasks/setup b/scripts/tasks/setup new file mode 100755 index 0000000..532b6f9 --- /dev/null +++ b/scripts/tasks/setup @@ -0,0 +1,8 @@ +#!/usr/bin/env zsh +#MISE description="Set up the development environment" +#MISE quiet=true + +set -euo pipefail + +bun install +hk install