Commands and workflows

Commands are provider-specific shortcuts. They are not the canonical place to store project behavior. The canonical workflow belongs in a Fractal instruction, task, skill, or agent under .fractal/; a command adapter should only make that workflow easy to invoke.

This repository does not provide a dedicated workflow CLI for the current source-first contract. Use a provider's documented native command surface only after deriving it from .fractal/; otherwise invoke the canonical record in natural language.

Recommended flow

1. Define the behavior in .fractal/instructions/ or create a meaningful .fractal/tasks/<slug>/TASK.md using the Fractal schemas.
2. Add todos, comments, attachments, and validation evidence to the task when the workflow needs lifecycle tracking.
3. Convert the workflow to the provider's native command or prompt format.
4. Verify the provider discovers it and keep the adapter derived from the Fractal source.

Read the repository's references/code-agents.md before creating or synchronizing an adapter.

Native examples

Claude Code

Claude Code commands and skills are provider surfaces. Keep their prompt body short and delegate to the canonical instruction or task:

.fractal/instructions/workflows/onboarding.instruction.md
  -> .claude/commands/onboarding.md

The command may say “read the canonical onboarding instruction and follow its task lifecycle,” but it must not become a competing copy of the workflow.

Cursor

Cursor rules in .cursor/rules/*.mdc can provide a convenient workflow trigger when the installed version supports it. Map scope to globs and keep the actual workflow in .fractal/.

Copilot and other agents

Use the provider's documented prompt, command, or custom-agent directory. If a provider has no native command system, leave the workflow in Fractal and tell the user how to invoke it in natural language. Do not guess undocumented file formats.

When to use a task instead

Use a Fractal task when the work has an owner, multiple steps, a review gate, delegation, a durable decision, or evidence that must survive the current chat. Use a command only as an invocation convenience. Lia should suggest a new task template or workflow instruction when the same multi-step process repeats, and should suggest the appropriate specialist before delegating.

Manual exception

A provider adapter may contain metadata that Fractal cannot represent. Keep that exception minimal, document it, and expect the next source-first conversion to review it. Never edit a command adapter as the primary source.