Julia Development

Julia Development Skill

Write idiomatic Julia code using Julian programming style (multiple dispatch, composition).

1. Julian vs OOP Style

Shift from class inheritance to multiple dispatch:

# Separate data from behavior
abstract type Animal end
struct Dog <: Animal name::String end
struct Cat <: Animal name::String end

# Multiple dispatch — behavior is external
speak(a::Dog) = "$(a.name) says Woof!"
speak(a::Cat) = "$(a.name) says Meow!"

2. Multiple Dispatch

Define behavior based on all argument types, not just the first:

# Generic fallback
collide(a, b) = "generic collision"

# Specific optimizations via type annotations
collide(a::Circle, b::Circle) = "circle-circle"
collide(a::Circle, b::Rectangle) = "circle-rect"
collide(a::Rectangle, b::Circle) = collide(b, a)  # symmetry

Method Ambiguity

When two methods are equally specific, define the intersection:

# AMBIGUOUS — neither is more specific
f(x::Any, y::String) = ...
f(x::String, y::Any) = ...
f("a", "b")  # Error!

# FIX: Define intersection
f(x::String, y::String) = ...

Parametric Methods

same_type(x::T, y::T) where {T} = true   # Diagonal dispatch
same_type(x, y) = false
process(x::T) where {T<:Number} = ...     # Type bounds

API Design With Dispatch

Prefer generic functions plus typed dispatch over public Symbol/String mode branches, Dict routing, or large mode switches when behavior actually changes. Prefer concrete marker or selector types—even zero-field types—for distinct behavior. Keep symbol keywords only as compatibility wrappers or user-facing convenience layers.

abstract type ProcessingMode end
struct FastMode <: ProcessingMode end
struct AccurateMode <: ProcessingMode end

process(data, ::FastMode) = fast_process(data)
process(data, ::AccurateMode) = accurate_process(data)

# Compatibility wrapper only when needed.
function process(data; mode::Symbol=:fast)
    selected = mode === :fast ? FastMode() :
               mode === :accurate ? AccurateMode() :
               throw(ArgumentError("unsupported mode: $mode"))
    return process(data, selected)
end

Use shallow abstract type hierarchies for open extension points, concrete immutable structs for data, and parametric fields for storage/scalar/backend types. Use traits when behavior depends on a capability rather than natural type identity.

Package Design Phase

When designing a package or changing its important verbs, noun types, or representative compositions, write the concept-only quoted Julia at <package-root>/docs/design/IdiomaticJulia.jl, where <package-root> means the package's actual root directory. Use native Julia notation: result = verb(...) for returned values, verb!(...) for mutating calls, and mutation assignments such as .= or += where those express the operation directly. Keep only the small package design surface there; do not record every function or method. Routine implementations under established verbs and nouns need no note update.

The note may use return type annotations, mixed typed and value arguments, keyword arguments, owned-field annotations such as owner.field::FieldNoun, tuple loop bindings, and dot access for noun values, callables, and type references. It may also contain long-form function ... end definitions for algorithms; their bodies are ordinary Julia rather than restricted verb–noun notation.

From the actual package root, run idiomatic-julia-check --semantic . docs/design/IdiomaticJulia.jl during design, before implementation. Typed standalone calls and long-form signatures declare the planned package surface. Assignments and value-only calls require a compatible planned signature; qualified dependency requirements are checked against the exact dependency source selected by Project.toml and Manifest.toml. The checker never treats the package's current src tree as the design authority. Treat planned, exact, and covered as confirmed; resolve every missing or unknown result. Then implement the design and align its generics, types, dependencies, public declarations, exports, and concrete restrictions. If the command is unavailable, read the notation and checker reference for its install command.

State Ownership and Operation Names

A field owns the state named by that field. Do not use Base.getproperty/Base.setproperty! forwarding to manufacture pseudo-fields: it hides ownership, weakens local reasoning, and often reintroduces symbol-based routing. Expose behavior through ordinary functions; keep implementation fields descriptive rather than allowing them to become an accidental public API.

Name operations for their actual direction and effect. A one-way update is not a synchronization; a validation is not a mutation. Avoid vague nouns such as family or capability when a concrete domain noun states what the operation owns or consumes. Do not encode visibility with leading underscores or retain compatibility aliases without a real compatibility requirement.

Introduce a coordinating struct only when it owns durable state, invariants, or a meaningful lifecycle. Prefer an existing value, a constructor, a tuple, or direct dispatch for short-lived coordination.

For Julia >= 1.11 packages, declare every supported type and generic-function binding with public near the module header; a public generic function owns its supported methods. public records API intent without importing the name for using Package; use export only for names that users should receive unqualified. Do not encode visibility through _helper, PrivateType, InternalType, TypeImpl, or similar names when the distinction is merely public versus internal. Julia has no hard private bindings: use descriptive domain names, declare supported bindings public, and leave implementation details undeclared as public.

public Dataset, load, configure!
export load

abstract type StorageBackend end
struct InMemory <: StorageBackend end
struct OnDisk <: StorageBackend end

struct Dataset{T,B<:StorageBackend}
    values::Vector{T}
    backend::B
end

load(d::Dataset{T,InMemory}) where {T} = d.values
load(d::Dataset{T,OnDisk}) where {T} = read_from_disk(d)

3. Type System & Performance

→ See references/language-deep-dive.md for type annotations, type stability, broadcasting fusion, loop optimization, and Val types.

Key rules:

• Put performance-critical code inside functions; avoid top-level script logic for reusable package behavior
• Default to immutable struct; use mutable struct only when mutation is required
• Keep functions type-stable: return types should be inferable from input types, not from unpredictable runtime values
• Avoid abstract fields and abstract element containers in performance-sensitive data; prefer parametric fields such as Container{T}
• Type the fields read in hot loops, including storage, keys, and source collections; avoid Any and heterogeneous convenience vectors there. Do not over-engineer a type hierarchy merely to type opaque backend or UI handles that are outside the hot path.
• Traverse the owning typed collection directly in a hot path. Do not first allocate a generic accessor result or source-reference vector merely to recover dynamic dispatch.
• When cardinality is known from construction or a query, allocate exact destination storage and use indexed writes. Do not use push!, append!, resize!, repeated growth, shrinking, or compaction during a fixed-layout refresh.
• Use dotted calls or @. for fused broadcasting when it improves clarity and avoids unnecessary temporaries
• Annotate types for dispatch, invariants, or documentation; concrete argument annotations rarely improve performance by themselves
• Declare supported package bindings with public; use export only when unqualified using Package access is intended. Direct field access should be public API only when explicitly declared and documented.

Fixed Layouts, Batches, and Updates

Separate construction-time layout from refreshable state. Identities, topology, resource choices, and capacities are fixed facts; positions, values, styles, and other payloads are refreshable facts. An ordinary update overwrites compatible dynamic state. A layout mismatch uses an explicit reconstruction path—never silent reconciliation or resizing of a fixed object.

Batch by the concrete data/component/resource requirements consumed by an operation, not by the source object that produced a row. A source is often an owner rather than the unit of batched work.

Keep invalidation narrow: distinguish a layout or selection change from a content change, update only affected nonempty consumers, and publish coupled outputs together so observers cannot see mixed revisions.

4. Common Patterns

Bang Convention

Use ! only when a function mutates one of its arguments or other externally visible state. Validation, lookup, construction, and pure conversion do not take !.

• map(f, arr) → returns new array
• map!(f, dest, arr) → modifies dest
• push!(arr, x) → modifies arr

Duck Typing

# Works with any type supporting the required operations
magnitude(v) = sqrt(sum(x^2 for x in v))
# Works for: Vector, Tuple, SVector, custom types...

do-block Syntax

open("file.txt", "w") do io
    write(io, data)
end  # Auto-closed

map(collection) do x
    complex_transform(x)
end

Keyword Arguments

function process(data; normalize=true, scale=1.0)
    normalize && (data = data ./ maximum(data))
    return data .* scale
end

process([1,2,3])                    # defaults
process([1,2,3]; normalize=false)   # override

Constructors For Object Creation

Prefer constructors over extra constructor-like helper functions when the goal is to build an instance of a type. Use outer constructors for alternate input forms, defaults, conversion, and ergonomic APIs; use inner constructors only when every instance must enforce an invariant.

struct Config{T}
    threshold::T
    name::String

    function Config(threshold::T, name::AbstractString) where {T<:Real}
        @assert threshold >= zero(T) "threshold must be nonnegative"
        return new{T}(threshold, String(name))
    end
end

Config(threshold::Real) = Config(threshold, "default")
Config(; threshold=1.0, name="default") = Config(threshold, name)

Avoid adding make_config(...), create_config(...), or build_config(...) when Config(...) is the natural API. Use a named function only when it performs a distinct operation, such as loading from disk, discovering environment state, mutating an existing object, or running a multi-step workflow.

Views and Published Storage

Use @view/@views for internal, non-owning slice operations when a view does not escape into an API with stricter storage expectations. Do not assume every downstream package, plotting backend, foreign-function boundary, or long-lived observable accepts a SubArray as a stable published value. Materialize an exact concrete container only at that unavoidable boundary; keep the fixed staging allocation and internal slice logic otherwise.

Common Macros

Use macros intentionally:

• @test, @testset, @test_throws: test behavior in test/, not package logic.
• @assert: check internal invariants during development; do not use it as the only user-facing validation for recoverable input errors.
• @views: avoid copies from slicing when a view is intended.
• @.: fuse broadcasts when it improves clarity and avoids temporaries.
• @time, @allocated, @code_warntype: quick diagnostics; use BenchmarkTools.@btime for serious benchmarking.

Do not introduce macros just to make ordinary function calls look clever. Prefer functions unless a macro is needed for syntax, generated code, source-location information, testing, diagnostics, or benchmarking support.

5. REPL & Package Management

REPL Modes

Essential Pkg Commands

pkg> st              # Status
pkg> add Package     # Install
pkg> dev Package     # Track local development version
pkg> rm Package      # Remove
pkg> up              # Update all
pkg> instantiate     # Restore from Manifest.toml

→ See references/testing-and-repl.md for Pkg API usage, Test.jl, TestEnv, aggregate test groups, and Revise.jl.

6. Common Mistakes (OOP → Julia)

→ See references/oop-migration.md for detailed examples of OOP→Julia pitfalls and their fixes.

Quick checklist:

• Don't put methods inside struct — use external functions with type annotations
• Don't write make_* or create_* helpers when an outer constructor is the natural object-building API
• Don't over-specify types (Int64) — let Julia specialize generically
• Don't encode real polymorphism as large public if mode == :foo branches; use typed selectors, traits, or separate methods
• Don't hide state ownership with getproperty/setproperty! forwarding or call a one-way update sync
• Don't encode visibility with _ prefixes or Private/Internal/Impl names; for Julia >= 1.11, declare supported bindings with public and use normal descriptive names
• Avoid type piracy: do not extend functions you don't own on types you don't own. Extending Base or package functions for your own types is normal Julia style.
• Default to struct (immutable) — use mutable struct only when needed
• Don't grow or resize a fixed-layout buffer during routine refresh; allocate known capacity and write by index
• Keep examples and skill guidance domain-neutral unless the user's current task is domain-specific; prefer examples from data processing, storage backends, plotting backends, parsers, optimizers, or numerical algorithms

7. Execution Tooling

Prefer repld for Julia execution when available. It gives long-lived named sessions, works well with Revise, survives ordinary code edits, and makes test iteration reproducible from shell commands. MCP servers are optional supplements for introspection or environments where repld is unavailable.

Import Placement and Review-Case Scripts

Classify the file by the module in which its code executes, then place its using and import statements accordingly:

For package code, an outer module's imports do not become bindings in a child module. Put an import in the child module even when the parent also uses that package.

# src/solver/step.jl, included by MyPackage.Solver
using LinearAlgebra
import StaticArrays: SVector

# Solver implementation that uses dot, norm, and SVector

When a temporary script defines a module, imports used by that defined module belong inside it; only imports used by the script runner remain in Main.

# temporary_script.jl, executed in Main
using MyPackage
import CairoMakie

# setup and one-off work

# review_cases/shell_preview.jl, executed in Main
using Revise
using MyPackage
import CairoMakie

# human-facing setup and review case

Revise is shared developer tooling, like JET. Do not add it to a reviewed case's Project.toml or to the package's dependencies solely for this script.

Environment Classes, Warming, and Hot Reload

Choose the workflow from the environment's role. A Julia process can only hot-reload files that it loaded after using Revise. Therefore, a no-Revise warm process may precompile or load MyPkg, but it must be separate from the later Revise session. Do not load the package, a test file, or a case definition before Revise in the process that is expected to reload it.

Use --startup-file=no in these commands so a personal startup file cannot silently load Revise in a no-Revise warm or in a fresh verification gate. Run Pkg.resolve() only after an explicit project/dependency edit or a manifest conflict; it is not routine warming.

Package src/ and test/ changes

Use this for a package such as MyPkg or a package extension. All processes use the package project. The first warm process intentionally loads MyPkg without TestEnv or Revise; close it before starting the hot loop. The second warm process activates TestEnv and precompiles test dependencies, but does not load MyPkg, tests, or editable source files.

# Runtime warm: package only, no TestEnv and no Revise.
repld --fresh --session mypkg-runtime-warm julia --startup-file=no --project=MyPkg -e 'import Pkg; Pkg.instantiate(); using MyPkg'
repld close --session mypkg-runtime-warm

# Test-dependency warm: TestEnv is active, but MyPkg and tests stay unloaded.
repld --fresh --session mypkg-test-warm julia --startup-file=no --project=MyPkg -e 'import Pkg, TestEnv; TestEnv.activate(); Pkg.instantiate(); Pkg.precompile()'
repld close --session mypkg-test-warm

# Hot focused-test loop: TestEnv first, then Revise, then the package.
repld --fresh --session mypkg-test-dev julia --startup-file=no --project=MyPkg -e 'import TestEnv; TestEnv.activate(); using Revise; using MyPkg'
repld --session mypkg-test-dev julia -e 'Revise.revise(); include("test/unit/foo.jl")'

Repeat the last command for ordinary src/ or selected test/ edits. The package-loaded src/ files are revised, and explicitly included tests rerun in the active TestEnv environment. Package precompilation does not transfer every JIT specialization into this separate hot process, so the first focused include may still compile substantially. Measure the second include in the same mypkg-test-dev session when judging re-test speed; do not promise a fast first execution.

For a package whose test runner selects a group through an environment variable, set that selector inside the Julia evaluation. Do not prefix a repld client command with GROUP=UNIT: a persistent daemon session does not inherit per-client shell environment assignments.

# Hot aggregate loop with the package-defined UNIT selector.
repld --session mypkg-test-dev julia -e 'ENV["GROUP"] = "UNIT"; Revise.revise(); Base.include(Main, joinpath(pkgdir(MyPkg), "test", "runtests.jl"))'

Use one aggregate selector per hot session, and prefer a documented standalone leaf test for the tightest loop. See references/testing-and-repl.md for selector-caching behavior.

A project-selected Pkg.test() gate is a separate fresh process: it creates and owns its own test environment and must not run from the TestEnv/Revise loop.

repld --fresh --session mypkg-pkgtest julia --startup-file=no --project=MyPkg -e 'import Pkg; Pkg.test(; coverage=false)'
repld close --session mypkg-pkgtest

# Selector-driven fresh gate: the Pkg.test subprocess inherits this Julia ENV.
repld --fresh --session mypkg-unit-pkgtest julia --startup-file=no --project=MyPkg -e 'ENV["GROUP"] = "UNIT"; import Pkg; Pkg.test(; coverage=false)'
repld close --session mypkg-unit-pkgtest

Docs, review cases, and other non-package environments

Docs and human-facing cases are executable workflows, not package test targets. Do not activate TestEnv for them. Give each durable review case its own anonymous Project.toml (no package name or uuid) with local packages in [sources], then retain the project directory as the environment identity.

# Docs: no Revise warm in one process; hot work in a fresh process.
repld --fresh --session docs-warm julia --startup-file=no --project=docs -e 'import Pkg; Pkg.instantiate(); Pkg.precompile()'
repld close --session docs-warm
repld --fresh --session docs-dev julia --startup-file=no --project=docs -e 'using Revise; using MyPkg'
repld --session docs-dev julia -e 'Revise.revise(); include("docs/make.jl")'

# Review case: its project stays separate from the package and has no TestEnv.
repld --fresh --session case1-warm julia --startup-file=no --project=examples/cases/case1 -e 'import Pkg; Pkg.instantiate(); Pkg.precompile()'
repld close --session case1-warm
repld --fresh --session case1-dev julia --startup-file=no --project=examples/cases/case1 -e 'using Revise; using MyPkg; includet("examples/cases/case1/definitions.jl")'
repld --session case1-dev julia -e 'Revise.revise(); include("examples/cases/case1/run.jl")'

Use includet once for a case definitions file whose changes should revise; use ordinary include for the deliberate rerun of a build or human-facing case.

--project=@temp is a special case: Julia creates that temporary environment inside its process, so a separate hot session would be a different empty environment. Keep the preparation and hot phases in one named repld session, with no TestEnv. Do all Pkg work before loading Revise or the editable package.

# Replace MyPkg with the package to inspect; this creates a process-local temp env.
repld --fresh --session scratch-dev julia --startup-file=no --project=@temp -e 'import Pkg; Pkg.develop(path="MyPkg"); Pkg.instantiate(); Pkg.precompile()'
repld --session scratch-dev julia -e 'using Revise; using MyPkg; includet("scratch/definitions.jl")'
repld --session scratch-dev julia -e 'Revise.revise(); include("scratch/run.jl")'

For a fresh @temp session after dependency, type-layout, or module-structure changes, recreate its Pkg setup before the Revise phase. Use a durable docs or case project instead when the environment itself must survive a fresh process.

Executable Workflow Fixture

When changing this protocol or validating a Julia/repld installation, run the minimal local package fixture. It proves the package runtime warm, the TestEnv test-dependency warm and hot loop, the isolated Pkg.test() gate, docs and case loops without TestEnv, and the process-local @temp loop. It copies the fixture to a temporary directory, changes a package function and two includet definition files, calls Revise.revise(), and asserts each changed result before closing every named session.

bash scripts/verify-warm-revise-workflow.sh

The fixture is fixtures/warm-revise-workflow/. Its package-owned test target uses only the Test standard library from root [extras]/[targets]. It needs julia, repld, Revise, and TestEnv available as shared developer tools; it does not install or update those shared tools.

Sessions created from Codex or Claude Code automatically attach to the agent harness and close when that harness exits. Do not pass --owner-pid manually for ordinary agent work. Autoclose is a fallback for interrupted or abandoned work, not a replacement for explicitly closing a completed task session. Use repld free <id | --session=NAME> only when a session must intentionally outlive the agent; it removes that ownership lease.

Use --fresh when starting a task, after module reorganization, dependency changes, thread-count or Julia-channel assumptions, or repeated Revise/world-age symptoms. Revise can usually hot-reload ordinary function-body edits, many method additions, and many changes in dev'd packages. Treat a struct/type redefinition as a fresh-session trigger by default: Julia 1.12+ can revise structs only when Revise's revise_structs preference is deliberately enabled, and that does not make pre-existing values or stale runtime state valid. Adding a new using NewPkg inside a module when NewPkg was absent from the project when the session started also requires a fresh session.

For a non-package definitions script, call includet("path/to/definitions.jl") once in the warm session rather than using include; its default :evalmeth mode tracks method definitions without rerunning arbitrary top-level work. Keep side-effecting computations in a separate script and use ordinary include only when deliberately rerunning those computations. Set __revise_mode__ = :eval only when full top-level re-evaluation is wanted and safe.

Use --trace smart by default for user/project frames plus nearby boundary frames. Use --trace full when package internals, generated code, or Julia runtime frames matter. repld trace --trace smart --session NAME shows the last saved traceback without rerunning the failing command; repld sessions also exposes short session IDs accepted by trace, interrupt, and close.

Use TestEnv.activate only for interactive, focused test-file execution when tests need [extras], [targets], or test/Project.toml dependencies that are not available in the plain package environment. This applies to package-owned test infrastructure such as Aqua and SafeTestsets, not analyzers or formatters. For aggregate selectors, run the package test entry point through TestEnv.activate during the warm loop and confirm with a fresh project-selected Pkg.test() gate. Use Pkg.test() only in a fresh package-project session; it may include functional tests, Aqua, and SafeTestsets, but it must never invoke JET, ExplicitImports, Runic, JuliaFormatter, or other shared QA tooling. Do not add TestEnv as a package dependency; treat it as a developer tool available from the global/dev environment. See references/testing-and-repl.md and references/package-quality-gates.md.

ReTest is optional and conditional, not a default dependency. On Julia 1.12.x, ReTest 0.3.x is compatible and can be useful for regex-filtered testsets, deferred tests, shuffling, or parallel test execution when the package already uses or explicitly wants that style. ReTest 0.4.x requires Julia 1.13, so do not recommend it for the current Julia 1.12 fleet. Prefer plain Test, focused project test selection, and TestEnv.activate unless ReTest's filtering/deferred-test model materially improves the task.

repld Session Lifecycle

Close task-scoped repld sessions at the end of each implementation or testing phase, after recording any needed trace output and final command result. This prevents stale Julia processes, old Revise state, loaded manifests, and package images from leaking into the next Comet/OpenSpec phase or unrelated task. Codex-created sessions also auto-close when the Codex harness exits; retain explicit closure for normal completion and use autoclose as interruption protection.

Close only after the evaluation has returned success or its explicit completion marker. A host shell tool can yield while a long Pkg evaluation is still running; poll or wait for the evaluation instead of closing the named session. A warm interrupted by cleanup is not valid evidence.

Use:

repld sessions
repld close --session mypkg

Keep sessions open only while they are actively useful for a tight edit/test loop. Prefer repld close --session NAME for task cleanup; reserve daemon-wide repld stop for explicit all-session cleanup or when the user asks to stop the daemon.

Optional MCP Servers

Kaimon.jl and julia-mcp can still be useful, especially for live introspection, method lookup, profiling, or environments where shell-backed repld is not available.

→ See references/mcp-servers.md for setup, full tool parameters, GateTool registration, and integration patterns.

Decision: repld available → use it for execution. Kaimon available → use it for introspection/debugging in addition to repld. julia-mcp available → fallback for quick eval or bootstrapping. JETLS is complementary — use alongside any execution path.

Tool quick reference:

• repld: --fresh --session NAME julia --project=... -e '...', --session NAME julia -e '...', trace, interrupt.
• Kaimon: kaimon_ex(e="code"), kaimon_run_tests(pattern="..."), kaimon_type_info(), kaimon_search_methods(), kaimon_code_typed(), kaimon_goto_definition().
• julia-mcp: julia_eval(code, env_path?, timeout?), julia_restart(env_path?), julia_list_sessions().
• JETLS: diagnostics, hover, go-to-definition, find-references, rename, code actions, inlay hints, formatting.

8. Tool Sanity Probe

On skill activation for nontrivial work, run a lightweight sanity probe for the execution path. Prefer repld; do not require julia-mcp, Kaimon, or JETLS.

Quick Probe

Run shell probes in parallel when possible:

command -v repld
repld --fresh --session julia-sanity julia --startup-file=no --project=. -e 'println("repld+julia ready: ", VERSION)'
repld close --session julia-sanity

Pass condition for ordinary Julia package work: repld is available and can run the one-line Julia command in the current project. If this passes, proceed with the task; do not install or update tools.

Optional probes, only when the task needs that capability:

9. Julian Review Checklist

Before finishing nontrivial Julia changes, check:

• Does reusable behavior live in functions rather than top-level scripts?
• Does polymorphism use dispatch, typed selectors, or traits instead of large mode branches?
• Are public selectors typed when behavior changes, with Symbol wrappers only for compatibility?
• Are supported types and functions declared with public, with export reserved for intended unqualified imports rather than used as the only visibility signal?
• Are object-building APIs expressed as constructors instead of redundant make_* functions?
• Are structs immutable unless mutation is required?
• Are fields concrete or parametrically typed where performance matters?
• Does each struct expose actual ownership through fields rather than pseudo-fields forwarded through getproperty/setproperty!?
• Are ! suffixes reserved for actual mutation, and do operation names state their real direction and effect?
• Does a fixed-layout object separate construction data from refreshable data and reject incompatible layout changes explicitly?
• Does each hot path traverse native typed collections and avoid Any, abstract fields, and heterogeneous temporary source vectors?
• Where cardinality is known, are buffers exact-sized and filled by indexed writes rather than grown, shrunk, or compacted during routine refresh?
• Are views confined to internal slice operations, with concrete containers materialized only at downstream publication boundaries that require them?
• Are batches grouped by compatible consumed data rather than by source ownership, and are selection/layout invalidation and content invalidation updated independently?
• Are signatures generic enough for Real, AbstractVector, StaticArrays, AD numbers, and unitful values when applicable?
• Are public APIs exposed through functions rather than undocumented field access?
• Are macros limited to appropriate roles such as tests, assertions, views, diagnostics, or benchmarking?
• Do performance-oriented tests verify durable semantics such as identity preservation, exact row counts, fixed-layout rejection, and active-only work rather than brittle global allocation ceilings?
• Are package-owned functional and test-only checks runnable through a selected Pkg.test() gate and, for focused iteration, through TestEnv.activate, with shared analyzers kept out of both test paths?
• Was Revise.revise() used before warm-session checks, and was a fresh session used after type/module/dependency changes?

If the preferred probe fails but plain julia works, continue with shell Julia or MCP fallback and mention the limitation once. Open install/update recipes only when a required tool is missing, a requested optional tool is missing, or a tool failure points to a known setup issue. For package-level QA gates, read references/package-quality-gates.md; PkgTemplates belongs only to new package/app scaffolding, not quality checks.

Capability Matrix

Install and Update Recipes

Keep install details out of the main workflow. Use them only after a sanity probe fails or the user explicitly asks to configure a tool:

• repld, julia-mcp, Kaimon, and JETLS: see references/mcp-servers.md.
• Revise/TestEnv and package testing: see references/testing-and-repl.md.

When Tools Are Missing — Guidance

Report missing required tools, or optional tools that were attempted and unavailable, once per session. Do not repeat on every turn.

10. Environment & Dependency Workflow

Before executing Julia code, determine the correct env_path and dependency permissions.

Classification

Rules

1. Use Pkg APIs for dependency graph changes. Prefer Pkg.add() / Pkg.rm() / Pkg.dev() over hand-editing dependency entries or Manifest.toml. Manual Project.toml edits are acceptable for package metadata and explicit user-requested fields.
2. Separate test dependencies from analyzers. A package-owned test suite may declare Aqua and SafeTestsets in [extras] and the test target; they are test-only dependencies and may run under Pkg.test(). Do not add ExplicitImports, JET, JETLS, Runic, JuliaFormatter, BenchmarkTools, or Documenter to the target package solely for agent QA. Install and run those tools from the active Julia version's default shared environment or a temporary environment, with approval for dependency changes.
3. Ephemeral tasks → temp env (env_path=nothing). Don't pollute a pkg's deps for one-off work.
4. Keep analyzers outside Pkg.test(). Pkg.test() runs package-owned tests and test-only dependencies. Run JET/JETLS diagnostics, ExplicitImports, Runic/JuliaFormatter, Documenter draft builds, and benchmarks as separate shared-tooling commands; do not hide them in a broad test invocation.

Detecting Execution Backend

1. repld present → preferred execution path.
2. kaimon_ tools present → optional introspection/debugging.
3. julia_eval present → MCP fallback.
4. Plain julia in PATH → acceptable shell fallback when repld/MCP are absent.

11. Revise.jl and Session Lifecycle

Use Revise in warm sessions, especially with repld. Trust Revise for normal function-body edits, tests, examples, documentation, and many new method definitions. Do not restart automatically just because a core function changed.

Restart with repld --fresh when:

• struct fields, type parameters, constants, or generated-function assumptions change;
• module includes/exports are reorganized;
• dependencies or Project/Manifest state changes;
• Revise reports failures or repeated world-age/stale-method behavior appears;
• a large API refactor changes many call paths and the cost of stale state exceeds restart cost.

→ See references/mcp-servers.md for the full Revise limits table and restart commands per server.

12. Visualization & User Verification

Large Julia projects follow an agent-generate → inspect what is inspectable → user-verify workflow. Live interactive plots often need user inspection, while saved images or screenshots can sometimes be checked directly by the agent when local visual tools are available.

Rule: Inspect or Hand Off Visual Output

When code produces plots, figures, or visualizations:

1. Generate the output (run the plotting code via repld or MCP).
2. Inspect saved artifacts when possible — use local image/browser/screenshot tools for static files or served HTML when available.
3. Tell the user what remains visual — describe what was generated, where it is, and what still needs human inspection.
4. Never claim success for visual properties that were not actually inspected.

WGLMakie for Agent-Accessible Visualization

Use WGLMakie (web-based Makie backend) wh

…(truncated)