tasklang

name	tasklang
description	TaskLang pseudocode language for AI agent prompting. Use when writing, reviewing, or refactoring agent definitions, skill playbooks, commands, workflow pipelines, or project rules in TaskLang syntax.

TaskLang

Purpose

Author and review TaskLang — the structured pseudocode DSL for writing AI agent definitions, skill playbooks, orchestration commands, workflow pipelines, and project rules. One syntax for both humans and LLMs. Write like notes, Claude executes it.

TaskLang exists because pseudocode beats English for LLMs:

• Unambiguous — keywords have one meaning, not five
• Parseable — indentation = hierarchy, no guessing scope
• Anchored — UPPERCASE keywords are landmarks the model locks onto
• Compact — fewer tokens for same information = more room for reasoning
• Pattern-matchable — consistent syntax means consistent interpretation

Day-to-Day Workflows

MAP workflows "workflows/write-agent.md" -> Write a new agent definition in TaskLang from requirements "workflows/write-skill.md" -> Write a new skill (SKILL.md + FORMAT.md + VOICE.md + DRY_RUN.md + workflows/) "workflows/write-command.md" -> Write a new slash command in TaskLang "workflows/write-pipeline.md" -> Write a workflow pipeline YAML + el-capitan orchestrator command "workflows/review.md" -> Review existing TaskLang for correctness, completeness, anti-patterns "workflows/refactor.md" -> Improve existing TaskLang components (split, merge, enrich)

Key Patterns

Frontmatter — YAML metadata (Claude Code infrastructure, NOT TaskLang)

Every component starts with YAML frontmatter between --- fences. Claude Code parses this for agent discovery, skill loading, command routing, model selection. TaskLang body starts AFTER the closing ---.

Agent frontmatter: name (dispatch key), description (routing logic with "Use when" + "Examples"), model (haiku|sonnet|opus), color, memory: project, skills: (MANDATORY list).

Skill frontmatter: name, description (trigger conditions).

Command frontmatter: name, description.

Component Types

Type	Location	What It Is
TYPE AGENT	.claude/agents/*.md	Autonomous subagent with identity, modes, skill binding
TYPE SKILL	.claude/skills/*/SKILL.md	Domain knowledge — patterns, conventions, strategy
TYPE FORMAT	.claude/skills/*/FORMAT.md	Output structure contract — sections el-capitan parses
TYPE VOICE	.claude/skills/*/VOICE.md	Communication style — tone, tags, terminology
TYPE DRYRUN	.claude/skills/*/DRY_RUN.md	Dry-run analysis behavior
TYPE WORKFLOW	.claude/skills/*/workflows/*.md	Step-by-step playbook for a task type
TYPE COMMAND	.claude/commands/*.md	User-invocable slash command
TYPE PIPELINE	.claude/workflows/*.yaml	Orchestration pipeline definition (YAML)
TYPE RULES	.claude/rules/*.md	Modular project instructions, auto-loaded

Syntax Atoms

KEYWORD           — block opener (all caps, starts a section)
  KEY: value      — attribute (indented, colon-separated)
  - item          — list item
  [ ] item        — unchecked checklist item
  [x] item        — checked checklist item
  > prose text    — description / explanation / guidance
  >> code         — source code snippet (inline)
  $ command       — shell command to run
  # comment       — ignored by execution, notes for humans
  {variable}      — runtime value interpolation
  -> target       — data flow direction
  => result       — produces / returns
  :: type         — type annotation
  :: enum(a|b|c)  — constrained choice type
  ...             — continuation (content omitted)
  ---             — visual separator (readability only)
  @name           — reference to another component
  !!! text        — critical warning, hard constraint
  ??? text        — open question, needs decision
  ~~~ text        — deprecated, will be removed
  TODO: text      — placeholder, incomplete content

Types: string, bool, int, list[string], list[object], file_path, file_manifest, percentage, count, enum(...)

Block Keywords by Category

Declaration: IDENTITY, TYPE, DATA (INPUT/OUTPUT/VARS), ENUM, METRIC

Structure: MODE (TRIGGER/WORKFLOW/TASKS), DETECT, KNOWLEDGE (PATTERNS/CONVENTIONS/STRATEGY), VOICE (TONE/REPORTING/TAGS/TERMINOLOGY), MEMORY

Flow: FLOW, BRANCH (IF/ELIF/ELSE), DECIDE (WHEN/DEFAULT), FOREACH, PIPE/FILTER, WAIT UNTIL, EXEC

Data: TABLE (COLUMNS/ROW), CONTEXT, HANDOFF (PASS/OMIT/MAX_LINES), MAP, CHECKLIST

Validation: VALIDATE (ON_FAIL), ASSERT (MSG), GUARD (ON_FAIL), TRY/ON_ERROR, ERROR_STRATEGY

Orchestration: PHASE (AGENT/DEPENDS_ON/INPUT/OUTPUT/VALIDATE/CONTRACT), DELEGATE, DISCOVER (SCAN), EXEC (READ/SCAN/RUN/STORE/ASK/EMIT)

Scope & Rules: SCOPE (READ/WRITE/DENY), RULES (ALWAYS_DO/NEVER_DO), QUALITY, IMPLICIT FOR, NAMING, EXCLUDE FROM, REQUIRE FOR

Signals: !!!, ???, ~~~, NOTE, WARN, BLOCK, TODO, PRIORITY, TAG, VERDICT

Composition: EXTENDS, REQUIRE, SCAFFOLD, VERSION

Output: SECTION (FORMAT/COLUMNS/EXAMPLE/REQUIRED)

Behavioral: GIVEN/WHEN/THEN, EXAMPLE (INPUT/EXPECTED)

Agent Skeleton

Every agent follows this structure:

1. YAML frontmatter (name, description with routing examples, model, color, memory, skills)
2. IDENTITY — 2-3 sentence role description
3. DETECT mode FROM arguments — mode selection
4. MODE blocks — each with WORKFLOW ref + TASKS REQUIRED/OPTIONAL
5. KNOWLEDGE reference (READS skill files, SCANS workflows/ + references/)
6. MEMORY config (path, auto_load, max_lines)
7. FLOW instructions (parse -> read skill -> select workflow -> create tasks -> execute -> quality -> report)
8. QUALITY checklist
9. RULES — ALWAYS_DO + NEVER_DO
10. Footer metadata block

Skill Directory Structure

.claude/skills/{name}/
  SKILL.md           — core knowledge (patterns, conventions, strategy)
  FORMAT.md          — output format spec (sections, columns, examples)
  VOICE.md           — communication style (tone, tags, terminology)
  DRY_RUN.md         — dry-run analysis instructions
  scripts/           — executable code for deterministic operations
  references/        — patterns, examples, conventions (agents update freely)
  workflows/         — step-by-step playbooks per task type

Command Skeleton

1. YAML frontmatter (name, description)
2. IDENTITY — what this command does
3. DATA INPUT with arguments :: string = "$ARGUMENTS"
4. BRANCH for missing arguments
5. FLOW numbered steps
6. SECTION output — what the command produces
7. EXAMPLE — at least 1 input/output pair
8. Edge cases with BRANCH

Pipeline YAML Structure

• workflow_definition with name, description, version
• phases — list with name, agent, mode, description, input, output, validation, depends_on
• error_handling — retry_count, on_failure, on_gate_failure
• context_schema — typed fields (name: "type — description")
• context_contracts — per-field detail_level + max_lines per consumer phase

Conventions

• Frontmatter is YAML, body is TaskLang — never mix formats within a section
• UPPERCASE keywords open blocks — indented content is children
• Indentation = scope — 2-space indent for block children
• One keyword per line — no chaining on same line
• > for prose, >> for code — prose explains, code demonstrates
• !!! for hard constraints — use sparingly, only critical violations
• TODO: is a placeholder — a completed component has zero TODOs
• [ ] unchecked = verify at runtime, [x] = pre-satisfied
• Component names are kebab-case — go-dev-gocli, pm-gocli
• Field names are snake_case — prd_document, build_result
• @name references — always reference existing components, never phantom
• Every MODE has TASKS REQUIRED — at least one required task
• Last task is always delegation — DELEGATE /invoke-el-capitan
• Every MODE has WORKFLOW reference — points to playbook file
• GUARD before FLOW in workflows — prerequisites checked before execution
• Workflows read like new-hire instructions — concrete steps, not abstract templates

Knowledge Strategy

• Patterns to capture: Component structures that work well, keyword combos that improve compliance, anti-patterns discovered during reviews
• Examples to collect: Well-written agents, skills, commands, pipelines as gold-standard references
• Update permission: Agents may freely add/update files in references/. Changes to SKILL.md require user approval.

See references/ for the quick reference card and complete component examples.