Polaris#

Polaris is a Go CLI that creates agent-friendly full-stack Gleam projects.

It scaffolds a small, working Gleam app with clear runtime boundaries, project intent docs, and agent guidance files so human-agent pairs can build without losing track of why the project exists or where code belongs.

Why it exists#

Full-stack Gleam projects often need to coordinate Erlang-targeted server code, JavaScript-targeted client code, shared domain logic, docs, and tooling. Polaris makes those boundaries explicit from the start.

Generated projects include a stable, fairly realistic starter app plus the control-plane files agents need to work safely across sessions: WHY.md, CONTEXT.md, AGENTS.md, .agents/, docs/, and polaris.toml.

Polaris is not a Gleam runtime framework. Generated apps do not import Polaris runtime code. Once generated, the starter is ordinary project-owned Gleam code that you can inspect, change, delete, or replace.

What gets generated#

The current starter is a small greeting app: the browser fetches a greeting, submits a name, and the Erlang-targeted server keeps the current name in memory while it runs.

The project shape is intentionally opinionated:

my-app/
  polaris.toml
  WHY.md
  CONTEXT.md
  AGENTS.md
  .agents/skills/using-polaris/
  apps/server/
  apps/client/
  packages/domain/
  docs/

The generated app is meant to be a showcase of tools available to full-stack Gleam developers:

shared domain code
typed route contracts
JSON encoding/decoding
Erlang-targeted server code
JavaScript-targeted client code
static asset handling
small FFI boundaries.

This is overkill for something so simple, but useful as a tour of the stack.

Try it locally#

Prerequisites: Go, Gleam, and Git.

mkdir polaris-sandbox
cd polaris-sandbox

git clone git@knot.h14h.com:did:plc:zn5k2enfurucv33qiak5ibeb polaris
cd polaris

go build -o ../polaris-bin ./cmd/polaris

cd ..
./polaris-bin init hello-polaris
cd hello-polaris
../polaris-bin check
../polaris-bin dev

Working on Polaris#

This repository is the scaffolding project that builds the polaris CLI.

Useful commands:

go test ./...
go run ./cmd/polaris --version
go run ./cmd/polaris init ../scratch-app

Status#

Polaris is pre-v0 experiment, but the generated starter code is stable and potentially useful as a starting point for your Gleam projects.

Most active development will come in the form of tuning the agentic workflow, and the CLI may see significant behavioral changes as well.

Here is a short list of some feature ideas I have for the future:

Agent Skills for migrating from the scaffold to the MVP of your idea
Skills for helping agents determine when new features warrant new deployment targets
Happy-path deployment config (e.g. a Dockerfile or fly launch support)
A "Dependency Catalog" to help agents find and install the right dependencies for the job across the BEAM ecosystem
Reliable documentation/spec practices to keep your agents on the rails as your project grows/evolves

But to be clear, these ideas are all quite fresh, and should not be treated as a roadmap. There may be features not listed I choose to implement instead, and some of the items in this may never get implemented.

For this project to graduate from pre-v0, I intend it to have the following at minimum:

A clear release/versioning strategy
An explicit roadmap
Stability guarantees
A decision made around licensing

Configure Feed