Ilmarinen

A reusable, versioned package that installs an agentic software-development workflow onto any machine and into any repo. Named for the master smith of the Kalevala; the theme runs through the whole vocabulary (see docs/VOCABULARY.md).

Ilmarinen is a methodology plus glue, not a platform. It adopts existing file formats and tools and adds only what none of them provide: the workflow itself, a small CLI, and a cross-repo knowledge index.

What it installs

• Per machine (ilmarinen setup, no input): a Claude Code plugin and an OpenCode layout generated from it (skills, hooks, MCP declarations), user-level instruction files, an empty personal memory project, and the cross-repo index.
• Per repo (ilmarinen init): a small, mostly declarative skeleton: AGENTS.md, a SpecScore spec/ tree, a justfile of gates, hook wiring, CI workflow, devcontainer, and a Beads task graph.

Read in this order

1. docs/ILMARINEN.md — the workflow: routing, gates, the loop.
2. docs/VOCABULARY.md — Blueprints, Runes, Forge, Sampo, Artifacts.
3. docs/TOOLING.md — every tool, its role, and what is deliberately excluded.
4. spec/decisions/ — why each choice was made (Runes, SpecScore format). Read before proposing changes.
5. docs/tool-notes.md — filled in during the build: doc URLs, config locations, contradictions found.

Repository layout

.claude-plugin/    marketplace.json (this repo is a one-plugin marketplace)
plugin/            Claude Code plugin: manifest, skills/, hooks/, .mcp.json
hosts/opencode/    generated by the converter; never hand-edited; linguist-generated
cli/               `ilmarinen`: setup | init | upgrade | doctor | off | on; `ilmarinen-sampo` (MCP);
                   `ilmarinen-convert` (dev only)
tests/             hook, trace and fixture tests (POSIX sh); the OpenCode plugin test
tools.toml         tool manifest: name, min version, detect command, install hint
mise.toml          pinned versions for tools mise can manage
templates/         per-repo skeleton rendered by `init`
fixtures/          one minimal repo per language plus one mixed; used by CI
docs/              this documentation
spec/              this repo's own Blueprints and Runes (SpecScore format)

Principles

1. Plain text in git is the source of truth. Everything generated is rebuildable.
2. The workflow is ours. Tools are adopted as formats and validators only.
3. Nothing auto-loads into agent context except a short map. Everything else is fetched on demand.
4. The CLI checks; it does not install. Installation is delegated to mise and only runs with explicit consent.
5. Every adopted tool must justify itself against the plain-text baseline, and must be replaceable without touching the workflow.
6. The package never handles identifying information. It does not seed, detect, derive, prompt for, store or transmit identity, usernames, hostnames, hardware, network addresses or ranges, paths under $HOME other than its own config and cache directories, accounts, deployment targets, or anything credential-adjacent; it keeps no infrastructure allow- or deny-lists, and no tool it manages sends telemetry. Where a session needs such a fact, the agent runs a command and does not persist the result.

License

Apache-2.0 (see spec/decisions/0009-license.md).