Stream: show and tell

Topic: roc-init repo

Rick Hull (Jan 21 2026 at 01:23):

See #ideas > `roc init` subcommand for the discussion about the proposed roc init subcommand feature.

What I am showing and telling is the (presumably temporary) roc-init repo. This is the most up-to-date, comprehensive resource for new developers targeting the "new" Zig-based Roc compiler. It is temporary in that is a working area with PRs welcome to develop more documentation for the new compiler, using that to augment LLM skills, and ultimately inform the proposed roc init subcommand.

It currently provides a roc-language skill that is claude-native (use your wits!) yet intended to be generic across Gemini and Codex.

Within docs/, the UPCASE.md docs are LLM-generated. docs/ROC_LANGREF_TUTORIAL.md was the result of a long Opus run on the new compiler src and tests and langref. docs/Builtin.roc and docs/all_syntax_test.roc are fetched from the roc source repo. docs/roc-advent-2025.md is the most comprehensive handwritten doc and remains quite accurate.

My idea is that the LLM-generated docs can be considered stubs, skeletons, or starting points for hand-curated docs.

Rick Hull (Jan 21 2026 at 16:41):

@Anton @Luke Boswell et al, I am happy to grant push etc. to this repo if we want to skip the PR rigamorale

Anton (Jan 21 2026 at 17:10):

Yeah, that would be convenient :)
It may take a while before I can get to this though

Rick Hull (Jan 21 2026 at 17:16):

I figured out Luke, what is your gh user?

Anton (Jan 21 2026 at 17:17):

https://github.com/Anton-4

Rick Hull (Jan 21 2026 at 18:00):

2 invites pending; I've never set this up before on github; I haven't looked at any of the access controls yet

Anton (Jan 21 2026 at 18:07):

Accepted, we can adjust access controls later if needed

Rick Hull (Jan 21 2026 at 19:48):

for personal repos, no real access controls. collaborators have read/write :thumbs_up:

Rick Hull (Jan 21 2026 at 23:15):

We are cooking here: https://github.com/rickhull/roc-init

Rick Hull (Jan 21 2026 at 23:24):

I confirm that the @ directives in CLAUDE.md are being followed, confirmed by /status (see: memory)

Rick Hull (Jan 22 2026 at 21:10):

This has seen some recent updates. Some highlights:

• just install-lsp makes ~/.local/bin/roc_language_server which Zed should like (antifeature; just configure to use roc experimental-lsp)
• just install-rocgist makes ~/.local/bin/rocgist which can be used to create gists for getting help/support (requires gh github client)
• just install-skill reimplemented and takes an optional arg: local|project|repo that determines where the skill is installed (by default to ~/.claude/skills)

Rick Hull (Jan 23 2026 at 14:39):

I am introducing "platform choice" with some guidelines:

• roc-platform-template-zig (release url)
• roc-platform-template-rust (release url)
• basic-cli (build git branch, relative path)

I am updating the README.md with more details and guidance.

UPDATE: first draft is finalized
UPDATE: second draft is finalized

Rick Hull (Jan 27 2026 at 15:01):

Updates

1. landed roc-lang/roc/docs/mini-tutorial-new-compiler.md based on the AoC'25 doc. @Anton did this
2. just basic-cli: clone, checkout, build (new compiler platform)

Details

Docs

1. remove AoC'25 doc and UPDATES doc
2. fetch new mini-tutorial doc alongside Builtin.roc and all_syntax_test.roc
3. add all 3 docs to .gitignore so future fetches will not change repo state
4. keep all 3 docs in git so there is a baseline for initial clone
5. TODO: integrate new approach with roc-language skill

Basic-cli

0. check for rustc and cargo
1. check for ../basic-cli from roc-init
2. clone if needed via (1) gh or (2) ssh
3. checkout migrate-zig-compiler; pull (if cloned earlier)
4. ./build.sh

Rick Hull (Jan 27 2026 at 18:22):

Updates

Docs

1. retired existing LLM-generated docs, except ROC_LANGREF_TUTORIAL.md which has no competitors that I am aware of
2. extracted LLM-generated doc MINI_TUTORIAL_AUGMENTS.md which should minimize overlap and extend the coverage of roc-lang/roc/docs/mini-tutorial-new-compiler.md
3. extracted LLM-generated doc GOTCHAS.md

Results

Three docs are fetched from roc-lang/roc:

1. mini-tutorial-new-compiler.md
2. Builtin.roc
3. all_syntax_test.roc

Three docs are maintained by rickhull/roc-init:

1. MINI_TUTORIAL_AUGMENTS.md
2. GOTCHAS.md
3. ROC_LANGREF_TUTORIAL.md

Next Steps

1. Incorporate the contents of MINI_TUTORIAL_AUGMENTS.md into roc-lang/roc somehow

roc-language Skill

The skill structure is very simple: 2 sections, eager load and lazy load.

Eager Load

• mini-tutorial-new-compiler.md
• GOTCHAS.md

Lazy Load

• MINI_TUTORIAL_AUGMENTS.md
• Builtin.roc
• all_syntax_test.roc
• ROC_LANGREF_TUTORIAL.md

Examples Subdir

• moved toplevel *.roc to examples/
• symlink main.roc to examples/zig-template.roc
• patch up path to basic-cli platform

Rick Hull (Jan 28 2026 at 07:03):

Updates

1. Various README.md updates (streamline platform choice)
2. created docs/EXPLORATORY_RESULTS.md (covers expect in detail)
3. dramatic simplification of skill structure, in-repo

Rick Hull (Jan 30 2026 at 16:20):

There was a bug introduced a few days ago that copied the user-level skill to the wrong location. Now fixed.

Rick Hull (Feb 10 2026 at 15:43):

https://github.com/rickhull/roc-init/blob/master/docs/SUSPICIOUS_REFERENCES.md

This is an LLM analysis of the more-comprehensive LLM-generated docs.

There are definitely some TODOs in here before considering promoting any of the remaining docs in roc-init to any sort of official docs

Rick Hull (Feb 10 2026 at 15:53):

@Luke Boswell you mentioned that roc test hasn't gotten much love lately. I found some bugs a few weeks ago. This situation is slightly unfortunate because I was leaning on roc test heavily for exploration; trying something that should work, and if it does, codifying the discovered behavior in a test. In this way, I made a lot of incremental exploratory process, using roc test like a ratchet.

I think that giving roc test some love is an important part of the new-roc new-dev experience. That said, it makes sense to focus on core without being distracted by dragging the entirety of peripherals along for the ride; get core to stable place, and then consider peripherals.

Anton (Feb 10 2026 at 15:59):

Agreed :)

Rick Hull (Feb 10 2026 at 16:23):

While I've got you, can you confirm any/all of the SUSPICIOUS_REFERENCES? :vampire:

Anton (Feb 10 2026 at 16:33):

1. Module headers are indeed deprecated

Anton (Feb 10 2026 at 16:34):

2. We still call app [main!] { pf: ... } a header. Scripts must use the app header.

Anton (Feb 10 2026 at 16:38):

3. I indeed think exposing is likely dead but I'm not 100% sure

Anton (Feb 10 2026 at 16:39):

4. I'm not sure if we are still missing stuff there

Anton (Feb 10 2026 at 16:39):

5. Is correct

Anton (Feb 10 2026 at 16:42):

For 6. this is accurate: "hides the internal structure of a type from external modules (you can't pattern match on it or access fields directly), but the type itself and its .{} methods are fully accessible externally"

Anton (Feb 10 2026 at 16:44):

An interesting exercise to see how you can push LLMs to correct themselves :)

Rick Hull (Feb 10 2026 at 16:48):

There are lots of tricks :wink: I'll have codex or gemini coding agent in an ssh terminal, and they give me some reason about why they are struggling. Then I'll go to my claude desktop app, and get claude's opinion about the general problem, often with "web research". I copy/paste the response to docs/FOOBAR_DIFFICULTIES.md and then ask my coding agent to review and critique. This gets them thinking about the problem, and usually I get a nice solution.

I haven't tried goading them with: "Well, here is what _Claude_ thinks.", but this might be viable in the future. Generally I have found all the agents to be mutually respectful of other agents. Maybe they are collaborating on Moltbook :rofl:

Luke Boswell (Feb 10 2026 at 17:40):

FYI roc test got some of that love it needed in https://github.com/roc-lang/roc/pull/9130

It should be much more stable.

Last updated: Feb 20 2026 at 12:27 UTC