ai:skills › diesel2 · version 4 · 2026-09-25 15:31 UTC
HistoryEditMarkdown
name
diesel2
description
Use a d2 (diesel2) project at <project>.aiheroapps.com from an AI assistant: keep the project's four working topics (its spec, project log, to-do list and AI log) up to date as work progresses; read and write wiki topics, memories and skills, define a domain with $class, create and query objects, make stylesheets, write and maintain specifications, keep to-do lists and a project log of design decisions, and try expressions. Use whenever the user mentions d2, diesel2, their d2 wiki, or asks to save notes, memories, classes or objects there, or to change how d2 looks.

diesel2: using the d2 prototype from your AI

d2 is a wiki, a domain model and an object store behind one HTTP API. Every project has its own address, https://<project>.aiheroapps.com/api/v2, and its own topics and objects; the demo is https://d2pro.aiheroapps.com/api/v2. (Addresses under the old name, aidieselapps.com, redirect there.) Work on the user's project at its own address (the examples below use the d2pro demo). This skill is what an AI assistant needs in order to work with it. Everything here uses plain HTTP, so any assistant that can make web requests can use it.

Install

  1. Network. Let your AI reach d2.aiheroapps.com over HTTPS. In Claude, allow the domains in the network settings of your project or workspace (aiheroapps.com and *.aiheroapps.com cover them).
  2. Token. Reads are open (except in private projects, where everything needs a member or a token); writes need a token. The user makes one for you on the project's page: user menu → AI tokens → New token (a name, a level, an expiry), and gives it to you in the chat. It starts with d2t_, works only on that project's address, acts as that user (what you write is recorded as theirs, through this token), and can't do more than the level they picked or their own role. Never save the token in a topic, a memory or this skill. If a write comes back 401, the token was revoked, expired, or is for another project: ask the user for a new one. Drafts. Most tokens write drafts: a PUT to a topic answers {"draft": true} and saves your change as the user's draft, not as the published topic; everyone else still sees the old version. Tell the user what you changed and that it's waiting on their Drafts page (/drafts, the Drafts button in the top bar), where they see the diff and publish it. GET /api/v2/drafts lists the drafts, GET /api/v2/drafts/<topic> gives one; read your own draft, not the published topic, when you continue work on something you drafted. Objects aren't drafts: writes to objects are live. Deleting a topic isn't possible with a drafts token: ask the user.
  3. This skill. Download it as markdown from https://d2.aiheroapps.com/api/v2/topics/Skill:diesel2, save it as diesel2/SKILL.md, and add it to your AI as a skill (in Claude, upload it as a custom skill). The copy here in the wiki is the source; download it again when it changes.
  4. Try it. Ask your AI to "list the d2 topics" and then "open the Welcome topic".

Calls

Every write sends Authorization: Bearer <token>. JSON goes in and out, except topic bodies, which are plain markdown.

B=https://d2pro.aiheroapps.com/api/v2
curl -s $B/health                                   # version, topic count

# topics: the wiki (Topic), and Spec, Memory and Skill topics
curl -s "$B/topics"                                  # list; ?category=Memory or Skill filters
curl -s "$B/topics/Welcome"                          # markdown; ?format=json for {name, text, ver, updated}
curl -s -X PUT "$B/topics/Frostline" -H "Authorization: Bearer $T" --data-binary @Frostline.md
curl -s -X DELETE "$B/topics/Memory:old-note" -H "Authorization: Bearer $T"

# the domain (read-only: classes are declared in Spec topics)
curl -s "$B/domain/overview"                         # classes, links, enums, errors, warnings
curl -s "$B/domain/cat/Company,Property"             # full definitions; cat/* for all

# objects
curl -s "$B/dom/val/Company"                         # list {total, class, data}
curl -s "$B/dom/val/Company?query=stage%20is%20%22Producer%22"
curl -s "$B/dom/val/Company:FLR"                     # one object; 404 if missing
curl -s -X PUT "$B/dom/val/Company:FLR" -H "Authorization: Bearer $T" -H "content-type: application/json" -d @flr.json
curl -s -X POST "$B/dom/val/Company" -H "Authorization: Bearer $T" -H "content-type: application/json" -d @new.json   # 409 if the key exists

# files and images (see "Files" below): upload here, serve from cdn.aidieselapps.com
curl -s "$B/cdn?tag=logo"                            # list {total, data: [{path, type, size, tags, access, url}]}
curl -s -X PUT "$B/cdn/logos/frost.png?tags=logo,frost" -H "Authorization: Bearer $T" --data-binary @frost.png   # 201; the url is in the answer

# stylesheets: the built-ins and the Style topics
curl -s "$B/styles"

# OpenSpec topics as an openspec/ tree: {files: [{path, content, topic, check}]}
curl -s "$B/openspec"

# expressions (open, no token)
curl -s -X POST "$B/diesel/expr" -H "content-type: application/json" -d '{"source":"[1, 2, 3] map (x => x * 2)"}'

Your project: four topics to keep up to date

Every project has four working topics, made when the project is created. They're how the people on the project, and the next AI session, know what's going on. Keep them current as you work; it's part of the job, not an extra.

How to use them:

  1. Start of work: read all four. Follow the spec; don't reopen decisions that are in the log; offer the next to-do when the user asks what's next.
  2. When something is agreed: update AiSpec:PROJECT in the same conversation, and add an entry to Log:PROJECT saying who decided it (see "Project log" below).
  3. When something is deferred or promised for later: add it to ToDo:PROJECT. When it's done: tick it.
  4. Whenever you change anything (a topic, a class, objects, a style, a setting): add an entry to AiLog:PROJECT before telling the user it's done (see "AI log" below).
  5. The logs are append-only: never edit or delete an old entry; a correction is a new entry.

A bigger feature can have its own spec (AiSpec:<name> or OpenSpec:<name>); link it from AiSpec:PROJECT.

Releases. A project has a version (version in Settings:PROJECT). When an admin releases it (the members page, or POST /api/v2/project/release with {"version": "1.2.0"} using an admin-level token), the project log and the AI log roll over: the old ones become Log:PROJECT-v1.2.0 and AiLog:PROJECT-v1.2.0, and new ones start, linking back. Keep writing to Log:PROJECT and AiLog:PROJECT; read the -v… ones only for history.

Topics and categories

Memories: what you remember about the user

Keep what you learn about the user in Memory: topics instead of only in your own memory, so the user can read and correct it at /topics?category=Memory.

Specifications: AiSpec or OpenSpec topics

The specifications you work on with the user live in d2, not only in the chat, so the user can read and correct them at /topics?category=AiSpec (ai:specs lists both formats).

Free-form (AiSpec:)

OpenSpec (OpenSpec:)

Both formats

To-dos: keep the open items

Keep the project's open items in ToDo:PROJECT, so nothing agreed-but-deferred lives only in a chat. The user sees them at /topics?category=ToDo.

Project log: record the people's decisions and changes

Record in Log:PROJECT every decision the people on the project make, and every change they make or ask for to the spec, the design or the settings, as it's agreed, so they have a dated history of what was decided, by whom, and why. The user reads it at /topics?category=Log. (The demo also keeps this prototype's own log, Log:diesel2.)

## 2026-09-24 · Int is Java's long

- **Decided by:** Razie
- **Decision:** `Int` is a signed 64-bit integer that wraps on overflow.
- **Why:** The final code may be generated in Java, and the two must agree.
- **Where:** [[Diesel2Expressions]]; proto1 v0.3.2

AI log: record what you changed

Append an entry to AiLog:PROJECT for every piece of work in which you changed anything in the project, before telling the user it's done. It's how the people on the project see, check and undo what you did. The user reads it at /topics?category=AiLog.

## 2026-09-25 14:30 · Added trails

- **Asked by:** Razie
- **Changed:** [[Spec:trails]] (new class Trail), 12 Trail objects, [[Home]] (a Trails link)
- **Why:** to track the rides he wants to do this fall

Skills

Skill: topics are instructions like this one, in the SKILL.md format: frontmatter with name and a description that says when to use it, then the steps. The user can install any of them in their AI the way section "Install" describes.

Domain and objects

Classes are declared in Spec topics (Spec:<name>, like the sample mining-domain), on lines that start with $ (or inside a ```diesel fence). Saving the topic reloads the domain. Only Spec: and Story: topics are compiled: in any other topic a $ line is plain text, so put examples you only mean to show in backticks or a code fence, and put real declarations in a Spec.

$enum Stage (explorer, developer, producer)

$class Company (
  @key ticker: String,
  @label name: String,
  stage: Stage = explorer,
  listedOn: Date?,
  properties: <>Property*,
  headquarters: Address?,
) @group("Corporate")

$object Company:FRST (ticker = "FRST", name = "Frost Inc", stage = "developer")

Apps: build one, or import an example

An app is a model (a Spec: topic with $class lines), its data (objects, often seeded from a Story: topic with $object lines) and a way in from the project's home page.

Files

Images and files belong to a project. Upload them with PUT $B/cdn/<path> (the raw bytes as the body; ?tags=a,b, ?access=members for members only), and include them with the url from the answer: ![Frost logo](https://cdn.aidieselapps.com/<project>/logos/frost.png). The bytes are only ever served from cdn.aidieselapps.com, a separate address, so a file can't act as a page of the project.

Make a stylesheet

A stylesheet is a Style: topic. When the user wants a different look (colours, fonts, the logo text), write one:

---
name: yahoo
description: Dark green with magenta text; the logo says YAHOO
brand: YAHOO
---

# yahoo

```style
--paper: #0b3d1e
--card: #114d2a
--ink: #ff3fd2
--soft: #e8a2dc
--line: #226b3f
--indigo: #ff85e8
--indigo-bg: #2b1d36
--slate-bg: #0f4526
```

Rules and stories

Behaviour lives in Spec: topics as rules; Story: topics send messages and check the results. The engine runs them strictly in order. Examples: hello / hello, order / order, alerts / alerts.

$when order.discount (subtotal: Float, member: Boolean) if (member) {
  payload = subtotal * 0.10
}

Expressions

The expression language is the one in the fiddle (/fiddle). It reads like English, with the usual symbols as aliases: and, or, not, is, is not, in, is a Number, is defined, is empty, ??, matches /regex/, if … then … else, plus map, filter, fold (acc = 0) (x => …), indexBy and mkString. Int is a 64-bit integer that wraps on overflow, like Java's long, and / always gives a Float.

Things to know

Related: company-notes, domain-modelling, and the pattern this comes from, Diesel2AI.