Locque Repo Orientation Skill

Locque Repo Orientation

Use this skill when starting work in the locque repo or when you need a reference for project conventions, tooling, and the "definition of done."

What Locque is

Locque is a dependently typed, keyword-led language with a strict CBPV split (values vs computations), a 1:1 M-expr ↔ S-expr mapping, explicit effects, and no implicit coercions. It is built almost entirely by LLMs.

Project layout

| Path | Purpose | |------|---------| | grammar.md | Canonical surface syntax and S-expr mapping — source of truth | | AGENTS.md | Project conventions, tooling, working agreements | | lib/ | Standard library (.lq M-expr files) | | test/ | Tests — one rollup per lib/** module | | interpreter/ | Haskell interpreter — polecats normally do not touch this | | Smythfile.lq | Project config (error-tests list) | | skills/ | Skill files for agents (including this one) |

Tooling

The primary tool is smyth (installed at ~/.local/bin/smyth):

smyth test              # Run full test suite (entry: test/main.lq)
smyth test <file>       # Run one test file
smyth test --slow       # Show slowest test suites
smyth bench             # Run benchmarks (test/bench.lq)
smyth run <file>        # Type-check and run a .lq file
smyth dump core <file>  # Inspect elaborated output

Always run smyth test after any change — it is the gate for "done."

File conventions

Source: .lq (M-expr, human-authored). Do NOT handwrite .lqs.
Paths: lowercase only — lib/some/module.lq, test/some/module.lq
Every lib/**/*.lq must have a matching test/**/*.lq
Module name Some::Module maps to file lib/some/module.lq
Test module Test::Some::Module maps to test/some/module.lq

Syntax quick-reference

# Definition
define transparent name as <Value>
define opaque       name as <Value>

# Function
define transparent inc as
  function x Natural returns Natural value
    Ar::add x 1
  end

# Computation value (effect-bearing)
define transparent main as compute
  perform (IO::print "hello")
end

# Data type
define transparent Option as data A Type0 in Type0
  case Option::none of-type Option A
  case Option::some of-type for-all x as A to Option A
end

# Match
match opt of-type (Option A) as ignored returns A
  case Option::none as fallback
  case Option::some with x A as x
end

# Import and qualify
import string as S   # Use S::concat, S::eq, etc.
open S exposing concat end  # Then use concat directly

Key rules:

Qualification uses :: only (never .)
Application is prefix, left-associative
end closes every block (function, compute, match, data, module, open, bind, typeclass, instance, pack, unpack)
List literals: [] and [a, b] (commas required); empty lists need of-type [] (List A) when no type is in scope
Use ignored instead of _ for unused binders
Effects are explicit: computation T type, bridged by perform; sequences via bind name from comp then ... end

Writing tests

import assert as A

module test::my_module contains
  define transparent run-tests as compute
    bind ignored from
      A::assert-eq Natural (Ar::add 1 2) 3
    then
      perform (IO::print "tests passed")
    end
  end
end

Use A::assert-eq with an explicit type argument
Add your test module to test/main.lq imports and the runner

What polecats do (and do not) change

Typical polecat work (library .lq files):

New library functions in lib/
New or updated tests in test/
Syntax fixes, refactors within .lq files
Adding/fixing data types, typeclasses, instances

Off-limits for polecats (interpreter):

interpreter/ — Haskell source. Do NOT modify unless the bead explicitly asks for interpreter changes. The interpreter is a separate build (GHC required) and is rarely the right place to fix library-level issues.
Do not add new primitives without explicit instruction from the bead.

Definition of done (checklist)

[ ] smyth test — all tests pass (no deletions to make tests pass)
[ ] New lib file has a matching test file
[ ] Paths are lowercase
[ ] No handwritten .lqs files
[ ] No changes to interpreter/ (unless bead explicitly requires it)
[ ] git status clean
[ ] gt done

Related skills

locque-authoring — detailed authoring rules: data/match forms, module syntax, CBPV rules, templates

Agent Skills: Locque Repo Orientation

Install this agent skill to your local

Skill Files