---
title: Templates
description: The current Forge template and the quality contract behind generated projects.
---

# Templates



## Bar widget with popout [#bar-widget-with-popout]

The first and only shipped template creates an Omarchy bar widget backed by a
keyboard-accessible popout.

```bash
omaforge init my-widget \
  --template bar-widget \
  --id dev.example.my-widget \
  --author "Example Developer"
```

Generated projects include:

* A schema-v1 `manifest.json` with inline settings metadata.
* A theme-aware, orientation-aware `Panel.qml`.
* Loading, ready, empty, and error states.
* An asynchronous local command with argument-safe invocation and timeout.
* Runtime-only fictional demo states through Omarchy Shell IPC.
* README, MIT license, changelog, tests, and optional CI.

## Scaffolding controls [#scaffolding-controls]

| Option              | Purpose                                                      |
| ------------------- | ------------------------------------------------------------ |
| `--dry-run`         | Render and validate the plan without writing.                |
| `--force`           | Preview and overwrite only colliding generated files.        |
| `--git`             | Initialize a local Git repository without creating a remote. |
| `--agent-ready`     | Add a structured specification and agent safety guidance.    |
| `--no-ci`           | Omit the generated GitHub Actions workflow.                  |
| `--non-interactive` | Fail instead of prompting for missing required values.       |
| `--section`         | Choose `left`, `center`, or `right`.                         |

The same validated inputs always produce the same file contents and modes.
User-provided strings never determine generated filenames.
An existing target containing only a real `.git` directory is accepted without
`--force`, and normal generation leaves that repository metadata untouched.
Any other existing entry still requires the explicit collision workflow.

## Agent-ready projects [#agent-ready-projects]

Forge `v0.3.0` and later can create the same reviewed template for Omarchy's
configured coding agent:

```bash
omaforge init my-widget --git --agent-ready
cd my-widget
```

The opt-in flag adds `FORGE_SPEC.md` and `AGENTS.md`. Replace every placeholder
answer in the specification, review both files, and change its status from
`Draft` to `Ready for implementation` before involving an agent. The generated
guardrails restrict the agent to the project, preserve the manifest and runtime
contracts, allow static validation, and reserve QML execution and installation
for the user.

Forge does not choose a model, contact an AI service, collect a prompt, or
launch an agent. After reviewing the two files and committing the completed
specification as a rollback point, an Omarchy user may explicitly hand it to
their configured agent:

```bash
omarchy agent prompt \
  "Build the plugin described in FORGE_SPEC.md. Follow AGENTS.md exactly."
```

Omarchy may run prompt tasks unattended. Keep a Git rollback point and review
the resulting diff before trusting or executing plugin QML.

## Trusted runtime check [#trusted-runtime-check]

Generated projects include an opt-in Omarchy runtime smoke test:

```bash
./tests/runtime --trust-plugin-code
```

Run it only after reviewing the plugin's QML and local commands. It loads a
temporary copy of the entry point against the installed Omarchy QML contract,
checks lifecycle methods and geometry, and isolates HOME plus XDG state. It does
not install or enable the plugin, modify `shell.json`, or contact the live shell.
Static Forge checks and generated CI never execute this harness.

Additional templates remain roadmap items until this shape has proven reusable.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)