--- 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. | | `--agent` | Unreleased guided specification, confirmation, baseline commit, and Omarchy-agent launch. | | `--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. ### Guided agent workflow (unreleased) [#guided-agent-workflow-unreleased] The next guided layer is available on the development branch as: ```bash omaforge init my-widget --agent ``` It shows the currently configured Omarchy agent, prompts for the bar, popout, data, command, network, persistence, and failure boundaries, and presents an editable final summary. Confirmation creates a complete `FORGE_SPEC.md`, `AGENTS.md`, and `AGENT_PROMPT.md`, initializes Git, commits a rollback baseline, and launches the configured agent from the project. Forge first offers `references` or `questionnaire`. Reference mode pauses for up to ten `.txt`, `.md`, PNG, JPEG, WebP, or SVG files and makes them the primary product brief. The generated agent contract requires an inventory of every visible or described function, control, value, state, action, and configuration hook, then requires implementation of every item within separately confirmed local-command, network, and persistence boundaries. Forge rejects symlinks and invalid or oversized files and records SHA-256 digests. Questionnaire mode retains the explicit bar, dashboard, button/action, data-source, and local-command questions for users who prefer to describe the product interactively. The confirmation warns that Omarchy agent tasks use unattended permissions. Generated instructions are not a sandbox. The agent may implement and commit locally but may not execute QML, install or publish the plugin, or push code. Its required final handoff separates static validation, isolated ready/empty/ error runtime tests, deliberate local installation, installed demos, removal, and optional remote publishing in that order. ### Verified end-to-end workflow [#verified-end-to-end-workflow] The released `v0.3.0` binary has completed a supervised agent-ready trial. Forge generated a disposable project, a human completed and committed its specification, and Omarchy's configured agent implemented a narrowly scoped local Git-status widget. The generated project tests, `omaforge check`, and the official Omarchy validator passed without executing QML, installing the plugin, or modifying live shell configuration. Human review remained essential: it caught and corrected an invalid NUL byte in generated agent code that the checks available during the trial initially missed. Forge `v0.4.0` includes the follow-up checker fix as error rule `OF305`; the earlier `v0.3.0` checker did not contain that rule. This evidence verifies the specification-to-static-validation workflow; it does not imply that arbitrary agent-written QML is safe to execute without review. ## 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)