Authoring conventions

Toolang favors concise, readable source that both humans and models can write and maintain.

Naming

Use lowercase snake_case for runnable and local agent names. Prefer descriptive, action-oriented names such as review_change or rewrite_section.

Use an agic for model-driven work and a flow for explicitly controlled execution.

Runnable signatures

Keep signatures concise when default types are sufficient:

Primary input _ defaults to Part[].
Named arguments default to Text.
Output defaults to Text.
() declares no inputs.
? marks optional arguments or fields.

Specify types when a runnable requires a different input or output contract.

agic rewrite(_, tone):
  Rewrite {{_}} in a {{tone}} tone.

Use {{_}} to reference the primary input and {{name}} for named arguments.

In flows, results normally replace _. Bind the original input to a named local if later stages still need it.

Agic messages

A single user message can be written directly in an agic without a user: prefix. Use explicit roles for multiple messages:

agic revise:
  user: Review the current conclusion.
  assistant: The conclusion needs stronger evidence.
  user: Revise it using {{_}}.

Keep messages focused and omit unnecessary role declarations.

Flow statements

Write implicit runs as ordinary prose, using natural capitalization and punctuation. Separate prose from explicit statements with a blank line.

flow brief:
  run -> Text[]:
    Extract findings from {{_}} as a list.
  keep if:
    Return true when {{_}} is actionable.
  map in 4 lanes:
    Explain {{_}} in one sentence.
 
  Combine the findings in {{_}} into a short brief.

Reference {{_}} in inline operations that depend on the current value.

Use run for a single invocation, even when it returns an array. Use generate N for independent invocations and in N lanes to limit concurrency.

Place in N lanes before using, if, or by when combining clauses.

Instructs and contexts

Use module-level instruct and context declarations for reusable instructions and information. Keep task-specific instructions in the agic body.

instruct review_guidance:
  Distinguish verified defects from open questions.
 
agic review:
  instruct = review_guidance
 
  Review {{_}} and return prioritized findings.

Omitting a selector inherits its value. Use default to select the module default or none to disable that layer.

Declare resource restrictions only when intentionally narrowing the available resources.

Comments

Keep source code clear and readable on its own. Prefer descriptive names and straightforward structure over comments, and add comments only when they provide useful information that the code cannot express.

Use documentation comments (##) to describe runnables and flow stages for CLI help and execution progress. Place them immediately above the declaration. Use ## @param to document parameters and #@ for module-level descriptions.

#@ Text rewriting helpers.
 
## Rewrite text for the intended audience.
## @param _ Source text to rewrite.
## @param audience Intended readers.
agic rewrite(_, audience):
  Rewrite {{_}} for {{audience}}.

Use ordinary comments (#) sparingly to explain non-obvious decisions or intent, rather than repeating what the code does.

Avoid comments inside text blocks introduced by user: or run:, where lines beginning with # are treated as literal content.

Formatting

Use too fmt to keep .too files consistently formatted:

too fmt helpers.too

Check formatting without modifying the file, or preview the formatted output:

too fmt --check helpers.too
too fmt --stdout helpers.too

The formatter uses two-space structural indentation by default and preserves source order within groups. It does not rewrite prose, names, or capability selections.