Foreword¶

The most common problem with agents writing code is “finishing everything in one breath without knowing what to trust.” If the steps of requirements, implementation, verification, release, and review aren’t separated, agents often conflate the spec and build in their minds, causing ‘check’ to become a mere formality. Existing approaches either provide agents with a pile of structured document templates or rely on manual human oversight at workflow nodes. These methods either fail to constrain the agent’s stage jumping or shift the burden onto humans.

Galadon, introduced below, takes a different path: it doesn’t attempt to make the agent smarter, but limits it to proceed one stage at a time, leaving artifacts at each step and setting gates. Galadon is maintained by Lumos-789. It uses existing plugins found on open-source directory pages as reference; it does not exaggerate its status but merely explains what it can do, how to use it, and its limitations.

What is this¶

One-sentence positioning: Galadon is an engineering cycle plugin for agents building projects. It breaks the project workflow from “spec” to “learn” into five stages and provides scaffolding and gates.

It solves the problem: when agents are responsible for writing code, running tests, and releasing, there is often a lack of stable stage boundaries and artifact checking mechanisms. Galadon initializes a small engineering workspace, allowing the agent to handle only one stage at a time. The core layer only recognizes three things—phases, artifacts, and gates. Other capabilities are exposed via “port” interfaces, allowing implementations to be swapped without changing the five-stage loop.

Categorically, it belongs to the “workflow” category. The repository is at https://github.com/Lumos-789/galadon and the directory page is at https://www.skillhub.cn/plugins/Lumos-789/galadon.

Core Features¶

The Five-Stage Loop¶

The backbone of Galadon is a fixed-sequenced loop:

Spec -> Build -> Verify -> Ship -> Learn

This corresponds to the five stages of requirements, implementation, verification, release, and learning. The agent reads galadon.yaml, executes the current stage, and repeatedly runs galadon check until the loop advances to “learn”. The purpose of the gates is to fail immediately on unqualified artifacts rather than letting the agent continue blindly downstream.

Port Interface¶

Galadon abstracts three things—‘who does it’, ‘what skeleton to use’, and ‘how to deploy’—into three ports:

The built-in implementations are merely examples. A project can replace any of these ports without having to modify the five-stage loop itself. This is what distinguishes it from a “large template pack”: the process is fixed, while surrounding capabilities are pluggable.

Layouts and Stacks¶

init --layout adds internal layering common in production projects. The default none keeps the basic template without layering contracts:

Except for none, each layout includes a layer of “spec truth” under spec/: INDEX.md (active feature index), domains/README.md (behavioral contract for each domain), TESTING.md (trigger matrix for changes to checks), and CONSTITUTION.md (hard rules). These four files are placed in templates/layouts/_shared/ and are rendered before the layout’s own common/ layer. This allows a layout to override a file, while none remains unchanged.

--stack selects the code skeleton and real check commands:

When using the python or node stack with a non-none layout, there is at least one real test after initialization, so galadon check turns green immediately. With --stack none, there are no check commands, so it will explicitly error out rather than passing silently. The build will compile or perform syntax checks on each source root in the layout, and run bash -n on the plugin’s bash wrapper. Therefore, a broken entry point will cause the gate to fail directly.

The gate also enforces layout contracts: AGENTS.md, openspec/config.yaml, spec/INDEX.md, spec/domains/, spec/TESTING.md, spec/CONSTITUTION.md, three wiki/ directories, six .agents/ slots, non-empty checks, and out/ and .agents/ in .gitignore. If any are missing, the gate will fail and identify them. .agents/ in repository templates is stored as __agents__/ because the repository itself ignores .agents/, and it is mapped back during rendering.

Deployment¶

For remote deployment, use deploy.adapter: ssh. This uploads the directory to a host running systemd and a reverse proxy. It supports releases, atomic current/previous switching, deployment locks, and JSON probing based on commit version numbers:

deploy:
  adapter: ssh
  env: test
  build: "mkdir -p dist && cp server.py dist/ && git rev-parse --short HEAD > dist/commit.txt"
  probe_url: "https://demo.example.com/health.json"
  probe_expect: "{{COMMIT}}"
  artifact: "dist"
  options:
    host: 203.0.113.10
    user: root
    remote_root: /srv/demo
    service: demo
    domain: demo.example.com
    listen: 127.0.0.1:18790
    exec_start: "/usr/bin/python3 /srv/demo/current/server.py"
    caddy_block: demo

bootstrap creates a system user, a release directory tree, a systemd unit, and a marked reverse proxy configuration (it backs up the proxy configuration first and only reloads after validation). teardown --yes only deletes the root that still has the bootstrap mark.

deploy.adapter: local uses the same release directory tree under deploy.options.root (default .galadon/deploy): releases/<timestamp>-<version>, atomic current switching, preserving previous, and shared/deploy.lock. It refuses to ship when a lock is held. If probing fails, it restores current to previous, probes that release again, exits with a non-zero status, and identifies the actual effective release.

Installation and Activation¶

The plugin publishes both the skill and CLI together, requiring no extra installation steps. For DeepSeek Harness, the official command is (path or repository placeholders need to be filled with actual values):

dsh plugin --profile headless add <path-or-repo>

For the other two hosts, respectively:

zcode plugins install galadon@<marketplace>
codex plugin add galadon@<marketplace>

Inside the workspace, the agent will call the built-in bin/galadon. If you want to use the CLI yourself, you can call bin/galadon directly in the plugin directory, or install it:

pip install <plugin-dir>   # or: pipx install <plugin-dir>

It depends on Python 3.10+ and PyYAML. These commands are taken directly from the plugin’s README. When installing, please replace <path-or-repo>, <marketplace>, and <plugin-dir> with actual paths or repository names; do not concatenate github:owner/repo yourself.

Typical Usage¶

Initialize a directory and then let the agent advance the loop:

galadon init --template api --role solo   # empty directory; use --force if files exist
galadon next                              # give only the next action for one stage at a time

Then hand it over to the agent: it reads galadon.yaml, performs the current stage, and repeatedly runs galadon check until the loop reaches “learn”. Under the default none layout, the first gate is spec: init will write a spec/spec.md stub full of TODOs, so check will report “spec/spec.md still contains TODO” until you finish it. init also deliberately leaves checks.build and checks.test empty, so after the spec is complete, check will explicitly report “no checks configured — declare checks.build/checks.test” until you declare real commands.

Common full commands:

galadon init --template web --role solo
galadon init --layout webapp --stack python --template web
galadon next
galadon check
galadon new
galadon bootstrap --env test
galadon ship --env test
galadon teardown --env test --yes

galadon init --list-layouts outputs stable text listing available layouts and stacks.

Without real probing, ship will not report success; a production release requires adding --yes-prod in the current session.

Suitable Scenarios and Notes¶

Suitable scenarios: projects where you want agents to advance through a project in fixed stages, and require that every step has checkable artifacts and gates. If you need external release processes, CI orchestration, or team collaboration permission systems, Galadon only provides the basic loop and two types of deploy adapters and cannot cover these.

Runtime permissions need attention: the plugin runs with the permissions of the current DSH process. Before installing, you should check the source code and license yourself—the license information is based on the repository and plugin metadata. In this material, package.json is recorded as MIT, and the repository is at https://github.com/Lumos-789/galadon.

Do not concatenate install commands based on the plugin name; prefer the commands and placeholders given in the README. Additionally, bootstrap and ship write files and restart services on remote hosts, while teardown --yes deletes directories. Before pointing at important machines, you should first read the “Side effects” section of the README.

Conclusion¶

The value of Galadon lies not in how many templates it comes with, but in fixing the most missing stage boundaries and gates for agent projects, leaving other capabilities to be swapped via ports. Directory page: https://www.skillhub.cn/plugins/Lumos-789/galadon , Repository: https://github.com/Lumos-789/galadon .