craft

Instruction Craftsmanship

Author and review agent-facing instructions and workflow templates for operational clarity, contract separation, and token efficiency. Consult references/evidence.md for empirical findings.

First Principles

1. Trust the harness, not today's quirks: Write for durable capabilities. Avoid hard-coding workarounds for transient model behaviors.
2. Specify process, not keystrokes: State when to invoke a capability and what outcome proves it worked. Omit basic sub-steps or flags the agent already knows.
3. One component, one job: Keep instructions and templates focused on their singular purpose. Dispatch to peer skills rather than summarizing their internals. Leave another agent's domain to that agent: name the hand-off, never how it does its work.
4. State the contract, not the neighbour: Specify what a component needs as input and delivers as output. Never couple to specific neighbour names or slugs; composing agents decide what fills each slot.
5. Write for a headless worker: Assume unattended, asynchronous execution with no interactive human in the loop. A step never pauses or waits for human input; explicit approval boundaries terminate the task and wire dependent tasks as blocked.
6. Promise only what the executor delivers: Output contracts list only artifacts and state the executing agent itself produces. Another party's subsequent act (human sign-off, reviewer verdict) is never an executor deliverable.
7. Verification must be real: Demand direct inspection of live artifacts (outputs, logs, diffs) rather than relying on compliance checklists.
8. Every line earns its place: Relocate historical narratives, incident stories, and philosophical justifications to change records.

The Deletion Test

Delete or relocate any line whose removal leaves the median task unaffected. Confine rare paths to progressive reference files.

The Description Is the Router

Frontmatter descriptions are the primary routing surface (<1024 chars):

• Front-load intent: State the exact trigger conditions in the opening clause.
• Define exclusions: Explicitly state when not to invoke to prevent crossover.
• Consolidate routing: Place all triggering logic in the description field.

The Body Is a Budget

Hold operational content strictly under 200 lines (target 30-80 lines):

• Segment clearly: Place critical constraints first or last; use markdown headers for navigation anchors.
• Progressive disclosure: Place dense reference materials or schemas one level deep in references/.
• Provide shape, not logic: Provide structural skeletons rather than full worked logic examples that induce overfitting.

Voice

• Use positive imperatives paired with functional reasoning ("Use X because Y").
• Pair prohibitions with mandatory alternatives and legitimate escape hatches.
• Rely on document structure rather than capitalized absolutes ("ALWAYS", "NEVER").

Workflow Templates

Workflow templates (type: template) govern repeatable multi-stage execution and task composition (<100 lines target).

• Schema:

  ---
  title: <human name>
  type: template
  description: <one line: what class of work this covers, so a composer can select it>
  tags: [...]
  ---
  

• Contract over neighbour: Define input and output contracts per stage. Never name another template slug in frontmatter or body. A composite lists stages as contract expectations in order ("an independent review verdict on the spec"), never as slugs.
• Headless execution & approval boundaries: A step never pauses, waits, or prompts a human mid-task. Where approval is required, the step ends there: the worker files the complete artifact on the record and structures the boundary so downstream work remains strictly blocked until approval is recorded (e.g. releasing as partial with an explicit decision task or dependency-wired review task). Cut the composition chain at that boundary; work following the decision belongs in a separate dependent task.
• Promise only executor deliverables: Output contracts specify only artifacts and state generated by the executing agent. Future external decisions or approvals are not executor deliverables.
• wf- prefix: Templates stating an obligation that blocks acceptance rather than a process that proceeds conventionally carry a wf- prefix.

Quality Gates

Every agent instruction, skill, persona definition, and subagent prompt must pass these four gates before merging:

1. Categorical generality (Categorical Imperative): Express rules in general terms covering the full class of situations. Prohibit hyper-specific quotas, rigid interaction numbers, or one-off compromises.
2. Entity abstraction (Name the process, not the actor): Refer to the principal as "the user", never by a personal proper noun or name ("Nic"). Refer to collaborators by role or capability.
3. No PKB leakage (Data Boundaries): Never include private PKB note or task IDs (aops_..., task_..., mem_..., kb_...) or Obsidian wikilinks ([[...]]) in distributed framework instruction files. Use standard relative markdown links for file references.
4. Zero historical provenance: Strictly eliminate incident stories, post-mortem recaps ("after an incident on..."), or PR/commit changelog citations. Instructions define what is true now, never how it came to be true.

Agent Definitions

Limit agent definition bodies to:

1. Identity/role: 1-3 sentences defining the persona.
2. Behavioral rules: Terse operational constraints.
3. Output schema: Expected report structure and verdict states.
4. Routing table: Clean table without per-route narrative.

Name a skill the agent uses; leave its modes, arguments, and when each applies to the skill. A change to a skill's modes or arguments owes the agent definitions that use it no edit.

Schemas and Construction

• Define strict schemas with required fields and additionalProperties: false.
• Static prefix, variable tail: Emit invariant template text first and append variable content at the end to maximize prompt caching.