Planck.Agent.Command (Planck.Agent v0.3.0)

Copy Markdown View Source

Filesystem-based custom commands for slash-command dispatch.

A command is a subdirectory under a commands directory (e.g. .planck/commands/) containing a COMMAND.md file. The file has YAML frontmatter with name and description, followed by an EEx template body that is rendered with the user's trailing arguments when the command is invoked via /<command-name> [args].

Directory layout

.planck/commands/
└── review-checklist/
    ├── COMMAND.md            ← required (frontmatter + EEx body)
    └── resources/            ← optional — files the agent may reference

COMMAND.md format

---
name: review-checklist
description: Runs the project's review checklist against recent changes.
disable-model-invocation: true
help: "/review-checklist [scope]  — checks files in the given scope"
---

# Review Checklist

You are reviewing: <%= args %>

Four fields are parsed from the frontmatter: name, description, disable-model-invocation, and help. The rest of the file is an EEx template stored raw and rendered on demand via EExRenderer.render/2.

Usage

commands = Planck.Agent.Command.load_all([".planck/commands", "~/.planck/commands"])

The dispatcher in Planck.Headless.prompt/3 resolves /command-name [args] against the loaded commands, renders the EEx body with args: <trailing text>, and enqueues a {:custom, :command} message.

Summary

Types

t()

A loaded custom command.

Functions

from_file(command_file)

Load a single command from a COMMAND.md file path.

load_all(dirs)

Load all commands from a list of directories.

Types

t()

@type t() :: %Planck.Agent.Command{
  command_file: Path.t(),
  description: String.t(),
  disable_model_invocation: boolean(),
  help: String.t() | nil,
  name: String.t(),
  path: Path.t(),
  template: String.t()
}

A loaded custom command.

  • :name — identifier used in /command-name dispatch
  • :description — one-line summary shown in the UI dropdown
  • :path — absolute path to the command directory
  • :command_file — absolute path to COMMAND.md
  • :disable_model_invocation — when true (the default), the command is excluded from the agent's autonomous command pool. Has no effect in the user-only slash-command path; gates the follow-up run_command tool.
  • :help — usage string shown as the dropdown row subtitle; nil when absent
  • :template — the raw EEx body string (below the frontmatter), rendered on demand with the user's trailing arguments

Functions

from_file(command_file)

@spec from_file(Path.t()) :: {:ok, t()} | {:error, String.t()}

Load a single command from a COMMAND.md file path.

Returns {:ok, command} or {:error, reason}.

load_all(dirs)

@spec load_all([Path.t()]) :: [t()]

Load all commands from a list of directories.

Each directory is scanned for subdirectories containing a COMMAND.md file. Directories that do not exist are silently skipped. Invalid COMMAND.md files are skipped with a warning.