Stream: ideas

Topic: `roc init` subcommand

Anton (Jan 20 2026 at 15:47):

A new roc init subcommand would be pretty convenient, it would:

• produce main.roc containing:

app [main!] { pf: platform "https://github.com/lukewilliamboswell/roc-platform-template-zig/releases/download/0.6/2BfGn4M9uWJNhDVeMghGeXNVDFijMfPsmmVeo6M4QjKX.tar.zst" }

import pf.Stdout

main! = |_args| {
    Stdout.line!("Hello, World!")
    Ok({})
}

• create .claude/skills/roc-lang with @Rick Hull 's skill or perhaps a CLAUDE.md would be better instead of a hidden folder. We can also produce AGENTS.md. That would just be a symlink to CLAUDE.md.

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

this is specific for writing platform? we might want a more specific (sub)command. I have found that symlinking AGENT.md to CLAUDE.md is problematic, because claude treats CLAUDE.md as a read/write space. my solution is to put all my agent directives in AGENT.md, and then CLAUDE.md just has:

load @AGENT.md

Apparently the @ syntax forces a read/load. This has been working for me, and it lets claude write more stuff to CLAUDE.md. Without the @, claude will just have that chunk of text preloaded.

Anton (Jan 20 2026 at 16:08):

this is specific for writing platform?

No, for making a roc app

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

I see, very cool.

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

my assumption is that whatever I have currently for the "condensed tutorial" (target: under 500 lines) and the "full langref tutorial" (no size restrictions) will be superseded by actual docs within roc-language/roc

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

i think what I have now is a reasonable starting point, and could just be manually curated from here

Anton (Jan 20 2026 at 16:12):

I have found that symlinking AGENT.md to CLAUDE.md is problematic, because claude treats CLAUDE.md as a read/write space.

What is the specific problem here in this case? If claude writes project specific tips to CLAUDE.md that seems ok.

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

why not just use CLAUDE.md then? typically the goal of symlinking AGENT.md is to also symlink GEMINI.md and CODEX.md etc. but you don't want claude stomping on these files

Anton (Jan 20 2026 at 16:13):

why not just use CLAUDE.md then?

Codex searches for AGENTS.md but not CLAUDE.md I think

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

my point is that Codex should not be loading what claude has written. and yeah, not sure on AGENT vs AGENTS -- i think different tools look for either

Anton (Jan 20 2026 at 16:15):

Codex should not be loading what claude has written.

What does claude write in this case? Is it not something that should be useful for all agents working on the codebase?

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

my goal, when I originally symlinked AGENT.md to CLAUDE.md, was to also symlink AGENT.md to GEMINI.md and whatever codex looks for. but I didn't like this setup because claude writes to this file.

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

it could be, or it could be a memory of a troubleshooting session

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

I just don't like it from a hygiene perspective. it might be fine in practice. i think claude will maybe separate its "init" from its memory system in the future

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

I think I should make a temporary github repo, maybe named something like roc-init that will have all the relevant files I have generated. eventually most of these files could be promoted into roc-lang/roc; but we can do some curation in the temp repo

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

we could also do this within roc-lang/roc

Anton (Jan 20 2026 at 16:21):

temporary repo sounds good

Anton (Jan 20 2026 at 16:23):

I just don't like it from a hygiene perspective.

Uhu I get that. I do want it to work with claude out of the box for now, people will forget running load @AGENT.md once they come back to the project after a while.

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

no, there is nothing to remember. CLAUDE.md is: @AGENT.md (i don't think "load" is necessary but it doesn't hurt)

Anton (Jan 20 2026 at 16:24):

Oh I see, yeah that is great :)

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

the first line of CLAUDE.md is set to @AGENT.md. then claude can add memories at it sees fit. I My headcanon confirms that it loads my AGENT.md instructions automatically

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

rwh@ht nostr-platform (master *)$ cat CLAUDE.md
See @AGENT.md for workflow instructions
See @README.md for project overview.

the sentences are more for human consumption

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

i notice no memories. it may be that claude is already using something else for memories. maybe it was an old feature

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

i also like the separation of AGENT and README -- many projects sort of combine these

Anton (Jan 20 2026 at 16:28):

Yeah README should be targeting users of the project, AGENT is more for contributing

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

the way I see it, README is canonical for describing the project. AGENT is for LLM-specifics only, not project specifics. Here is my AGENT.md

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

@Anton about to create the repo. public or private?

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

public is easier and fine w/ me

Rick Hull (Jan 20 2026 at 17:27):

https://github.com/rickhull/roc-init PRs welcome

Rick Hull (Jan 20 2026 at 17:28):

you'll notice I used the @ syntax in SKILL.md this is not a supported feature but it seems to be working

Rick Hull (Jan 20 2026 at 17:33):

just fetch to get the two .roc files from github; already synched

Rick Hull (Jan 20 2026 at 18:06):

added the AoC 25 doc, and the LLM analysis

Rick Hull (Jan 20 2026 at 18:08):

I can incorporate your main.roc at the top of the topic. at project root?

Anton (Jan 20 2026 at 18:08):

Yes, project root sounds good

Rick Hull (Jan 20 2026 at 18:09):

pushed

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

justfile please skim; this is from my platform repo, but I think we would do well to port most of this to roc-init repo. i am definitely adding a task to create the claude skill, either within-repo or for the user at ~/.claude/skills

Richard Feldman (Jan 22 2026 at 02:15):

I haven't been following this super closely, but I'd honestly like to not implement a roc init subcommand (or #ideas > `roc gist` subcommand) until sometime after 0.1.0

Richard Feldman (Jan 22 2026 at 02:15):

I think it's kind of a can of worms around centralization and "blessed packages" and if we add it, it will be much harder to take it away

Richard Feldman (Jan 22 2026 at 02:16):

I'd rather these things just be third-party for now

Richard Feldman (Jan 22 2026 at 02:16):

I'm not saying we should never do it, just that now is not the right time to make a commitment that big in the official CLI

Rick Hull (Jan 22 2026 at 02:48):

This makes sense enough to me. I'd like to continue with the roc-init repo effort -- with the main thrust being "new dev experience" oriented towards the "new roc compiler", with an eye towards LLMs but not necessarily so. I have platform development in mind here, too.

Maybe a rename to roc-llm with a shift in focus? It's a little bit of a grab bag right now. I might just orient it towards the roc-language skill. Another angle is roc-template, similar to Luke's roc-platform-template-* repos. I have some strong opinions, weakly held, about things like direnv and justfile that belong 3rd-party.

Separately, I'm not super-happy with "start with someone's template, and go from there" on a repo basis. For one, licensing. I'm not going to say much more here on this, but it seems complicated to me. If there is an official rails generate:scaffolding, then there is less concern. This is not to push towards roc init! Just saying that Luke's templates have a license, and if you start there, you start with Luke's license.

I'm struggling to describe my exact concern, but as a practical example, I am about to publish schnorr-platform repo, but much of this repo is concerned with "new Roc" documentation, claude skills, etc. most of which I have transferred to roc-init. But how do I make my schnorr-platform nice and clean, yet my workflows can rely on roc-init? I have some ideas here, but also some uncertainty.

Rick Hull (Jan 22 2026 at 05:20):

One angle i'm imagining (it's late!) is roc-platform, that is, you install the "platform development environment", and you have all the tools an application developer needs as well. And where an application developer might want a basic-cli, it might provide a test harness or noop-platform or scriptable-platform or test-platform: accessible and programmable.

Conceptually adjacent to the roc-platform-template-*, just a slightly different angle, maybe.

Last updated: Jun 16 2026 at 16:19 UTC