ArchLang

View saved version →

---
name: archlang
description: Use when the user wants to create, edit, or inspect an architectural floor plan / building layout as code — e.g. "draw a 2-bedroom apartment", "add a bathroom to this plan", "make the bedroom 1 m wider", "lay out an office floor". ArchLang is a tiny text language that compiles a .arch file to a professional floor-plan drawing (SVG/PNG/PDF/DXF). Drive it entirely through the `archlang` CLI; do not hand-render.
license: MIT
compatibility: Needs a shell with Node 18+ and the archlang CLI (npx -y @chanmeng666/archlang@1.60.0, or npm i -g @chanmeng666/archlang@1.60.0 for a global archlang).
---

# ArchLang — author floor plans as code

ArchLang turns a small `.arch` text file into a professional floor-plan drawing. It is built for
agents: deterministic, self-correcting (errors carry a machine code, a prose `fix`, and often a
**machine-applicable** fix `archlang fix` can apply), and verifiable without ever looking at an image
(`archlang describe`).

## What ArchLang can do

- Compile `.arch` to SVG, DXF, TXT, PDF, PNG or Plan JSON; it never reads images, so a plan from a photo is written by you.
- `validate --strict` and `lint` check soundness (doors on walls, reachability, clearances) and give a fix per finding.
- `describe` reports rooms, areas and adjacency; `takeoff` reports quantities as csv or md.
- `fix`, `repair` and `finish` rewrite the source; each takes `--dry-run` to preview first.
- `--expected-hash <source_hash>` on those refuses a stale file (exit 4).
- `impact --against old.arch --lock <ids>` exits 2 when a locked element moved: edit in place, never redraw.
- `impact --set NAME=value` shows what one top-level `let` would move.
- `keep` lines in the plan hold a relation through every edit and report a residual.
- `level` blocks give storeys; `axes` gives one grid; `keep stacked` aligns shafts.
- `validate --intent` checks a plan against a brief; `score` measures it.
- Plan JSON in (`compile --from-json`) and out (`-f json`).
- `link` prints a playground URL; `preview` renders a PNG.

## Setup (zero-install)

The CLI runs straight from npm — no clone, no build:

```bash
npx -y @chanmeng666/archlang@1.60.0 --help
```

Or `npm i -g @chanmeng666/archlang@1.60.0` for a global `archlang` command. Every call below is written
`archlang <cmd>`; without the global install, write `npx -y @chanmeng666/archlang@1.60.0 <cmd>`. Never run
a bare `arch`: the package installs it as an alias, but on Linux, macOS and Git Bash coreutils
owns that name, so the shell runs the wrong program.

## The loop (always follow this)

1. **Learn the language first.** Run `archlang spec` and read it — the entire language in one page.
   (`archlang context` prints *everything*: spec + this workflow + CLI reference + error catalog; a small model starts with `archlang context --level starter`, one screen.)
   Do this before writing any `.arch`.
2. **Write the plan** to a `.arch` file (or pipe via stdin with `-`), preferring the **placement
   sugar** below so you never hand-compute a coordinate.
3. **Render it:** `archlang compile plan.arch -o plan.svg --json`. The JSON is `{ ok, diagnostics,
   summary }`.
4. **Auto-fix the mechanical faults:** if `ok` is false, run `archlang fix plan.arch --dry-run --json`
   to preview the **machine-applicable** edits (off-wall opening → attachment form, out-of-range
   position clamped, …), then re-run without `--dry-run` to apply. Anything `fix` can't resolve stays
   in `diagnostics[].fix` for you to edit by hand. Exit code `2` means a deterministic user error —
   fix it, don't blindly retry (`1` = IO/internal, `3` = bad usage).
5. **See the plan without an image:** `archlang compile plan.arch -f txt` (or `archlang preview plan.arch
   --ascii`) prints a zero-dependency ASCII floor plan you can read straight from stdout.
6. **Verify intent:** `archlang describe plan.arch --json` returns the rooms (areas, adjacency), what each
   door connects, and totals. Confirm the room count, lab

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: archlang-brief-to-plan
description: Use when the user gives a written brief for a new floor plan (rooms, areas, how rooms connect, a plot size) and wants the drawing, e.g. "design a two-bedroom flat of about 75 m²" or "lay out a small office with four rooms". Writes an ArchLang .arch file from the brief, checks it against the brief with the archlang CLI, and finishes it as a sheet. Not for changing an existing plan (archlang-edit-plan) or for exporting one (archlang-export).
license: MIT
compatibility: Needs a shell with Node 18+ and the archlang CLI (npx -y @chanmeng666/archlang@1.60.0, or npm i -g @chanmeng666/archlang@1.60.0 for a global archlang).
---

# Brief to plan

Turn a written brief into a checked `.arch` floor plan. Every step is a CLI call; never judge the
plan from the SVG markup.
If `archlang` is not on the path, write `npx -y @chanmeng666/archlang@1.60.0` in its place.
Never run a bare `arch`: on Linux, macOS and Git Bash that name is the coreutils command.

This skill is a workflow, not a language reference. The language is whatever `archlang spec` prints.

## Scope

- Run the `archlang` CLI commands below and no other program.
- Write one new plan file, `plan.arch` here or the name the user gives, in the user's working
  directory, plus the drawings the CLI renders beside it. If a file of that name already exists,
  ask the user before replacing it.
- The user's explicit instructions take priority over these steps.

## Steps

1. **Read the language.** Run `archlang spec` and read all of it before writing a line. For one
   command's flags and examples run `archlang <cmd> --help`, for example `archlang finish --help`.
2. **List what the brief asks for.** Write down each room, each stated area, each stated
   connection ("opens off the hall"), each stated window, and any outer size. Keep numbers exactly
   as the brief states them. If two requirements cannot both hold, stop and tell the user which
   ones; do not quietly change a number.
3. **Write `plan.arch`.** Give every room an `id`, a `label` and a `uses`. Attach doors and windows
   to walls and place furniture by anchor, as `archlang spec` shows, instead of computing coordinates.
   Give every room a door or an opening.
4. **Compile.** `archlang compile plan.arch -o plan.svg --json`. If `ok` is false, read each
   `diagnostics[].fix`. Preview the mechanical fixes with `archlang fix plan.arch --dry-run --json`,
   then apply them with `archlang fix plan.arch`. Fix the rest by hand and compile again.
5. **Check the plan against your list.** `archlang describe plan.arch --select rooms,doors,windows,totals --json`.
   Compare room count, labels, each area, what each door connects and which rooms have windows
   with the list from step 2. Edit and repeat from step 4 until they match. `area_m2` is measured on
   wall centrelines; `net_area_m2` is the floor no wall stands on.
6. **Check soundness.** `archlang lint plan.arch --json`. Fix each warning, or keep it on purpose and
   say why. If a room cannot be reached or a bedroom has no window, `archlang suggest plan.arch --json`
   returns door and window statements you can paste.
7. **Finish the drawing.** `archlang finish plan.arch --dry-run --json` shows the furniture and sheet
   statements it would add; `archlang finish plan.arch` applies them. Read `unresolved`: it names each
   room left empty and each statement left out, with the reason.
8. **Gate and show.** `archlang validate plan.arch --strict --json` must exit `0`, or you must be able
   to name each remaining warning as deliberate. Then `archlang preview plan.arch -o plan.png` to show
   the user.

## Report to the user

- The file you wrote and the drawing you rendered.
- Every requirement of the brief the plan does not meet, or "none".
- Which area you quote: `net_area_m2` is the floor no wall stands on, `area_m2` the larger
  centreline figure. If a room has no `net_area_m2`, say its net area could not be computed.
- Every lint warning 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: archlang-edit-plan
description: Use when the user wants to change an existing ArchLang .arch floor plan, e.g. "make the bedroom 1 m wider", "add a bathroom next to the hall", "move the front door to the south wall", "merge the kitchen into the living room". Reads the plan's facts with the archlang CLI, makes the smallest edit that does the job, and re-verifies. Not for writing a plan from a brief (archlang-brief-to-plan).
license: MIT
compatibility: Needs a shell with Node 18+ and the archlang CLI (npx -y @chanmeng666/archlang@1.60.0, or npm i -g @chanmeng666/archlang@1.60.0 for a global archlang).
---

# Edit an existing plan

Change a `.arch` file without breaking what already works.
If `archlang` is not on the path, write `npx -y @chanmeng666/archlang@1.60.0` in its place.
Never run a bare `arch`: on Linux, macOS and Git Bash that name is the coreutils command.

This skill is a workflow, not a language reference. Run `archlang spec` for the language and
`archlang <cmd> --help` for a command's flags.

## Scope

- Run the `archlang` CLI commands below and no other program.
- Change the one `.arch` file the user asked you to edit (`plan.arch` below). If the user has not
  named it, ask. Besides it, write only the drawing the CLI renders and the `.bak` copy that
  `--backup` keeps.
- The user's explicit instructions take priority over these steps.

## Steps

1. **Record the starting state.** Run `archlang validate plan.arch --json` and
   `archlang describe plan.arch --select rooms,totals --json`. Keep both results: they are what you
   compare against at the end. If the plan already has errors, tell the user before you edit.
2. **Choose the locks, then check the edit.** Before you edit, list the ids the request does not
   name: those are the locks. For a change to one top-level `let`, ask first, with nothing written:
   `archlang impact plan.arch --set NAME=value --lock <ids> --json`. For any other edit, make it in a
   copy `new.arch` and check it after: `archlang impact new.arch --against plan.arch --lock <ids>
   --json`. Exit `2` with `E_LOCKED_ELEMENT_CHANGED` names a locked element the edit moves: change the
   edit, not the lock. A lock names elements by the `id=` written in the source (an unnamed one is
   refused with `E_LOCK_UNNAMED`).
3. **Read only what the change touches.** `archlang describe plan.arch --room <ids> --json` returns
   those rooms with the doors, windows and furniture that touch them.
   `archlang describe plan.arch --select freedom --json` says which positions the author typed
   (`absolute`) and which the compiler derives. Change a typed number; a derived one moves by
   itself when the thing it depends on moves.
4. **Read the language for the forms you will write.** `archlang spec`.
5. **Make the smallest edit.** Change the statements the request names and leave the rest as they
   are: same ids, same order, same comments. Do not reformat the file and do not rewrite
   statements you were not asked to change. When a room changes size, check the walls, doors,
   windows and neighbouring rooms that share its edges.
6. **Compile.** `archlang compile plan.arch -o plan.svg --json`. If `ok` is false, preview the
   mechanical fixes with `archlang fix plan.arch --dry-run --json` and read the diff before you apply
   them with `archlang fix plan.arch --backup`.
7. **Move furniture out of the way if needed.** If the edit pushed a piece into a wall, a doorway
   or a door swing, `archlang repair plan.arch -o plan.arch` moves it. Read `unresolved` for the pieces
   it could not move.
8. **Verify the change and nothing else.** Run the two commands from step 1 again, and
   the `impact` check from step 2 on the edited file. The rooms you meant to change differ as
   intended. Every other room has the same area and the same connections. No diagnostic is new unless the request causes it; if one is, tell the user.
9. **Refresh the sheet if the drawing grew.** `archlang finish plan.arch --dry-run --jso

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: archlang-export
description: Use when the user wants an ArchLang .arch floor plan delivered as files, e.g. "export this plan as PDF", "give me a DXF for CAD", "a PNG I can paste into a document", "one sheet per floor", "print it at 1:50 on A3". Covers SVG, PNG, PDF and DXF output, paper size and scale, multi-storey plans and batches, through the archlang CLI, or through the ArchLang MCP tools and the Playground where the CLI cannot run. Not for writing or changing the plan itself.
license: MIT
compatibility: Needs a shell with Node 18+ and the archlang CLI (npx -y @chanmeng666/archlang@1.60.0, or npm i -g @chanmeng666/archlang@1.60.0 for a global archlang). PNG and PDF need optional packages that the CLI can install with --install. Without them, the ArchLang MCP tools and a browser.
---

# Export a plan

Produce drawing files from a `.arch` plan.
If `archlang` is not on the path, write `npx -y @chanmeng666/archlang@1.60.0` in its place.
Never run a bare `arch`: on Linux, macOS and Git Bash that name is the coreutils command.

This skill is a workflow, not a language reference. `archlang compile --help` lists every format and
flag; `archlang spec` describes the `paper` and `scale` statements.

## Steps

1. **Check the plan compiles.** `archlang compile plan.arch --json` writes nothing and reports `ok`
   and the diagnostics. Do not export a plan with errors; fix it first.
2. **Make sure it is a sheet.** A plan with no `paper` statement has no physical size.
   `archlang finish plan.arch --only sheet --dry-run --json` shows the sheet statements the plan lacks
   (paper, scale, dimensions, title block, room schedule, legend). `archlang finish plan.arch --only sheet`
   adds them on the smallest sheet the drawing fits.
3. **If the user names a paper size or a scale,** edit the plan's `paper` and `scale` statements
   to those values and compile again. If the drawing does not fit the sheet the plan declares,
   `archlang finish plan.arch --reissue -o issued.arch` writes a copy in which only `paper` and `scale`
   are replaced by ones that fit. Tell the user when the sheet they asked for cannot hold the
   drawing at that scale.
4. **Export.** Pick the format by what the file is for:
   - SVG, for the web or further editing: `archlang compile plan.arch -o plan.svg --json`
   - PDF, for print at true size: `archlang compile plan.arch -f pdf -o plan.pdf --install --json`
   - PNG, for a document or a chat: `archlang compile plan.arch -f png -o plan.png --install --json`
     (`-s 2` doubles the raster scale)
   - DXF, for CAD: `archlang compile plan.arch -f dxf -o plan.dxf --json`
5. **Multi-storey plans.** A plan written with `level` blocks compiles to one file per storey,
   named `<stem>.L<level>.<ext>`, and the JSON result lists them in `outputs[]`. To write one
   storey to one named file, add `--level <n>`.
6. **Many plans at once.** Create the output directory first; `batch` does not create it. Then
   `archlang batch a.arch b.arch -f pdf -o out/ --json` renders each input into it and returns one
   result row per input.
7. **Confirm what was written.** Read `output` (or `outputs[]` for a multi-storey plan) and
   `bytes` in the JSON result and list the files for the user. For a PNG you can look at it; for the other formats report the
   path, the sheet size and the scale.

## Report to the user

- Each file written, with its format.
- The paper size and scale of the sheet, and whether you or `finish` chose them.
- Any storey or input that failed, with its diagnostic.

## When the CLI cannot run

Some hosts have no shell, or a shell that cannot reach npm: in ChatGPT's sandbox `npx` only times
out, and a retry ends in `ENOTCACHED`. Stop after the first such failure and do not substitute
another PDF tool. With the ArchLang MCP tools:

1. Set the plan's `paper` and `scale`, then check it with the `validate` tool and render it with
   the `compile` tool. `W_SCALE_OVERFLOW` means the sheet cannot hold the drawing at that s

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: archlang-review-plan
description: Use when the user wants an existing ArchLang .arch floor plan checked rather than changed, e.g. "review this plan", "does this layout meet the brief?", "is every room reachable?", "check it for accessibility", "why does lint complain?". Reads the plan's facts, runs the lint profiles and the intent gate through the archlang CLI, and reports findings with suggested fixes. It edits nothing unless asked.
license: MIT
compatibility: Needs a shell with Node 18+ and the archlang CLI (npx -y @chanmeng666/archlang@1.60.0, or npm i -g @chanmeng666/archlang@1.60.0 for a global archlang).
---

# Review a plan

Report what is true of a `.arch` plan and what is wrong with it, from the compiler's own facts.
If `archlang` is not on the path, write `npx -y @chanmeng666/archlang@1.60.0` in its place.
Never run a bare `arch`: on Linux, macOS and Git Bash that name is the coreutils command.

This skill is a workflow, not a language reference. Run `archlang spec` for the language,
`archlang context --section errors` for the diagnostic catalog, and `archlang <cmd> --help` for flags.

The checks are drafting heuristics. They do not establish that a plan meets a building code, and
your report must not say that it does.

## Steps

1. **Does it compile?** `archlang validate plan.arch --json`. Errors come first in the report; a plan
   with errors has no facts to review until they are fixed.
2. **Read the facts.** `archlang describe plan.arch --json` gives rooms with areas and uses, what each
   door and window connects, the access graph and the totals. On a large plan narrow it:
   `archlang describe plan.arch --select rooms,access,totals --json`. `area_m2` is measured on wall
   centrelines, so it counts the wall bands that stand on the room; `net_area_m2` subtracts them.
   Say which one you quote.
3. **Run the default lint.** `archlang lint plan.arch --json`. Each warning has a code, a place in the
   source and a `fix` in prose. `archlang explain <CODE> --json` explains a code you do not know.
4. **Run the accessibility profile when the user asks about access,** or when the brief mentions
   a wheelchair, step-free access or ageing in place:
   `archlang lint plan.arch --profile accessibility-advisory --json`.
5. **Check against the brief, if there is one.** Write the brief's checkable requirements as an
   intent file: room count only if the brief lists the rooms, an area band only where the brief
   gives a number. The format is the JSON Schema at <https://archlang.uk/intent.schema.json>,
   explained at <https://archlang.uk/intent>; a malformed file is refused with exit `3` and the
   path of the bad field. Then run
   `archlang validate plan.arch --intent intent.json --feedback --json`. A failed gating assertion
   exits `2` and comes with a correction prompt for each violation.
   `archlang score plan.arch --brief intent.json --json` gives the same comparison as a number that
   never fails.
6. **Ask for candidate fixes.** For an unreachable room, a building with no entrance, a bathroom
   reached only through a bedroom, or a bedroom with no window, `archlang suggest plan.arch --json`
   returns door and window statements with a reason for each. Put them in the report as options.
   Do not apply them.
7. **Look at it, if that helps.** `archlang preview plan.arch --ascii` prints a text plan;
   `archlang preview plan.arch -o plan.png` renders an image. `archlang compile plan.arch --overlay circulation -o walk.svg`
   draws the walking routes and their narrow points.

## Report to the user

Order the findings so the user can act on them:

1. Errors: the plan does not compile, with each diagnostic.
2. Brief: each requirement the plan misses, with the measured value beside the asked value.
3. Soundness: each lint warning, grouped by room, with the fix the diagnostic proposes.
4. What you did not check, for example "no brief was given, so nothing was compared to one".

State which lint profile produced ea

Preview of the first 4,000 characters. Read full instructions →