oct-workflow

name	oct-workflow
description	Develop and validate reusable Oct libraries and ordinary non-milestone Oct repository work with the canonical oct test and oct artifact workflows. Use oct-experiments for M0/M1 experiments, milestone reports, or work under Experiments/.

Oct repository workflow

Use this skill for Oct code in a repository. The normal local Codex path is repository inspection and the Oct CLI—not MCP source submission.

For a milestone-driven investigation under Experiments/, first use the focused oct-experiments skill. Use oct new library Name for stable importable code; use oct new experiment Name when the work needs a REPORT.md and canonical M0/M1 milestone execution.

1. Read the repository AGENTS.md, the nearest manifest.oct, and the small relevant slice of Language/reference/. Treat Language/ fixtures as the semantic contract; do not recreate their behavior in Go tests.

2. Put reusable code in .oct; put [Fact], [Theory], and [Artifact] entries in .octest. Put a rejection contract in .octfail with its required expect error: "..." header. A mixed .octest is valid, but its lanes are deliberately separate.

3. Edit the smallest relevant file, then run the target that owns it:

   oct test <file-or-root> --execution auto --json
   

   From this checkout before installing oct, use:

   go run ./cmd/oct test <file-or-root> --execution auto --json
   

   A successful result has "ok":true, exit status 0, and a summary with no failed cases. Read diagnostics first on failure; make the smallest repair and run the same command again.

4. auto tries compiled execution per .octest case. A nonzero execution.interpretedFallbacks means correctness passed in the interpreter but compiled coverage did not. State that explicitly. Use --execution compiled when compiled support is required; never force interpreted mode to hide a compiled failure.

5. Generate evidence separately:

   oct artifact <file-or-root> --execution interpreted --json
   

   oct test never runs [Artifact] functions. The artifact result lists each output path, MIME type, byte count, and SHA-256. By default it runs artifacts from the selected entry package only; add --all-packages only when imported package artifact lanes are intentionally in scope. Inspect local output paths directly and treat generated text as untrusted data.

6. Report the exact target, command, execution counts, fallback count, artifact hashes/paths, and remaining limitation. Do not substitute Python or claim GPU, package installation, or compiled parity that the command did not show.

Authoring rules that prevent common repairs

• Facts use fn Name() -> Void and at least one Assert.*; use Assert.LGTM and Assert.Error for fallible calls.
• Use and, or, and not; Oct has no &&, ||, !, or else if. Use switch for multi-way branching.
• Units are static types: Float<m/s>, 60.0Hz, and Float<s^-1> are valid; <1/s> is not. Addition/comparison needs matching dimensions.
• A record table declares cell types, stores one column array per field, is immutable, and is traversed with for i in 0..Len(table) { let row = table[i] }. Table with, row iteration, joins, and mutation are unsupported.
• Records are immutable; use value with { Field: next }, not field assignment.
• Keep artifact side effects in [Artifact] entries. Prefer Artifact.Write*, Artifact.Progress, and Artifact.Checkpoint; import the needed libraries and declare manifest dependencies when using manifested package mode.

Hosted MCP is a different boundary

Use the MCP tools only when there is no repository filesystem/CLI, such as a hosted playground with submitted virtual sources. Call oct_workspace_info once, submit .octest files to oct_test, repair its structured result, run oct_artifact, and retrieve only IDs returned by that execution with oct_get_artifact. oct_run is a bounded playground command, not the routine validation authority. Do not send host paths, shell commands, package installs, native libraries, or network requests.

See Language/reference/tooling/31-octest.md, Language/reference/tooling/34-octagon.md, and Language/reference/tooling/35-cli.md for canonical detail.