Operation Customization

Operation Customization

Create or revise operation workflows for this repository without breaking the runtime-mediated contract.

When to Use

• Add a new operation under builtins/<lang>/operations/ or projects/<project-id>/operations/
• Extend or refactor an existing operation step flow
• Add or revise steps[].delegation for Noctis-owned autonomous flows
• Create or revise jobs, instructions, skills, policies, or output-contracts facets under builtin or project facet trees
• Diagnose operation prompt, routing, report transport, source-aware catalog, or instruction placeholder failures such as output(...), setting(...), or root(...)

Workflow

1. Confirm the target operation, source tree (builtins or projects/<project-id>), language or project id, and whether the task includes diagnostics.
2. Read the references that match the task:
   • For canonical YAML rules, runtime contracts, and parser constraints, read operation-authoring.md.
   • For facet-specific writing guidance, read facet-authoring.md. For skill facets, this bundled reference and template are the complete authoring guide.
   • For routing, prompt, or placeholder failures, read operation-diagnostics.md.
3. Inspect the closest existing operation and neighboring facet files before drafting.
4. When creating files from scratch, start from the matching templates in ./assets/. Use the dedicated autonomous delegation template for rules-less Noctis-owned parent steps.
5. Decide what should stay reusable in file-backed facets and what should remain step-local inline content.
6. Prefer file-backed instructions once a step procedure is long, uses multiple placeholders, or is followed by sibling fields such as output_contracts, policies, delegation, or rules.
7. Edit the operation YAML and the required facet files.
8. Run the bundled validator on every created or modified workflow YAML:
   • node .opencode/skills/operation-customization/scripts/validate-operation-yaml.mjs <path-to-operation.yaml>
   • You may pass multiple files or an operations directory.
9. Treat validator failures as blocking. Then verify runtime-facing placeholder behavior intentionally:
   • Confirm every {{ output("step", "selector", "file") }} references a declared output_contracts.report[].name on that step.
   • Confirm every {{ setting(...) }} and {{ root(...) }} uses a supported key/mode or scope.
   • If a worker step hands off to a Noctis step that consumes outputs, validate the next-step prompt path too, not just the current step.
10. Summarize created or changed files, workflow assumptions, validator results, and any unresolved ambiguity.

Critical Parser Trap

• For standard routed workflows, the initial_step may not route directly to ABORT or COMPLETE.
• If the initial step needs a failure or blocked branch, route it to a named non-initial step and let that later step choose ABORT or COMPLETE.
• Re-check copied template snippets against references/operation-authoring.md before finishing instead of trusting placeholder transitions verbatim.
• Treat multiline inline: | blocks as a YAML nesting hazard. After any such block, explicitly re-check that sibling step fields such as output_contracts, policies, delegation, and rules are still aligned with instruction: rather than nested inside it.
• A validator pass is necessary but not sufficient unless placeholder references and next-step prompt composition were also checked.

Bundled Assets

• Use operation-template.yaml for standard routed operations.
• Use autonomous-delegation-template.yaml for internal Noctis-owned autonomous flows that keep the parent step open while delegating child tasks.
• Use job-template.md for reusable step roles.
• Use instruction-template.md for file-backed instructions or inline content.
• Use skill-template.md for reusable file-backed skills under facets/skills/<skill-name>/SKILL.md. It includes the canonical description pattern, section layout, and split or script thresholds.
• Use policy-template.md for pass or fail criteria.
• Use output-contract-report-template.md for markdown report artifacts.
• Use output-contract-frontmatter-template.md for machine-readable frontmatter artifacts.

Bundled Script

• Use validate-operation-yaml.mjs after authoring or editing operation YAML.
• The validator checks YAML parseability, strict object shapes for workflow fields, file-backed facet paths, step ownership, next targets, the initial_step terminal-transition trap, and output(...) references against declared outputs.
• Treat validator failures as blocking until resolved.

Ask Only If Blocked

• Which operation should be created or changed?
• Is this a standard routed workflow or a rules-less autonomous delegation flow?
• Which step owners and transitions are expected?
• Are there required outputs or instruction placeholders that downstream steps will consume?
• Which facet content must be reusable across workflows?

Guardrails

• Keep this file lean. Put detailed rules and examples in references/.
• Default to the fewest steps that satisfy ownership, artifact boundaries, and required approvals.
• Do not add User-facing progress updates or Noctis relay steps unless checkpoints, approvals, or interactive monitoring were explicitly requested.
• Do not stretch the generic operation template into a rules-less delegation pattern; use the dedicated autonomous delegation template instead.
• Prefer adapting neighboring repository patterns over inventing new structures.
• Keep same-name builtin and project workflows as separate candidates; do not document or implement name-based collapsing.
• For facets/skills/<skill-name>/SKILL.md, keep frontmatter name in lowercase kebab-case and match the enclosing <skill-name> directory.
• Treat unresolved or unsupported instruction placeholders, legacy schema fields, and malformed output contracts as blocking.
• Do not skip the validator for "small" workflow edits. A one-line rule change can still break catalog loading for the whole language tree.
• When runtime behavior changes, inspect both live-path and debug-preview implications before finishing.
• If the workflow is internal-only, keep the internal operation name out of normal user-facing operation lists.

Completion Criteria

• Every step has a clear owner, job, instruction, and rules.
• A rules-less step is only used for an explicit Noctis-owned autonomous delegation flow.
• The initial_step points to a noctis step and that step does not route directly to ABORT or COMPLETE.
• The bundled validator passes for every created or modified operation YAML.
• New facet paths are relative to the operation YAML file.
• The workflow can be resolved unambiguously from its source tree and file path, even if another workflow shares the same visible name.
• Every output(...) placeholder resolves to a declared workflow output and every setting(...) / root(...) placeholder uses a supported contract.
• Any multiline inline instruction has been checked for accidental nesting of sibling step fields.
• The result preserves runtime-mediated dispatch, same-step return for delegated child tasks, and the canonical completion contract.