On this page
Plan AI features with a human path, then check the implemented behaviour. This
independent custom schema adds KLOD to OpenSpec's proposal, specs, design and tasks.
It includes the portable klod and klod-check guidance and their references.
Version: 0.1.0. Compatibility tested: OpenSpec 1.13.0, using its released CLI. This is a custom schema, not an official OpenSpec plugin or an accepted catalog entry.
Install
You need Python 3.10 or later for the installer and Node.js 20.19 or later for this OpenSpec release. In your project, install OpenSpec and initialise it if needed:
npm install -g @fission-ai/openspec@1.13.0
openspec init
Choose your coding assistant during OpenSpec setup. If the project is already initialised, keep its current setup.
Download the KLOD OpenSpec integration and extract it. From your project directory, run the installer from that extracted folder:
python3 /path/to/klod-openspec/install.py --project .
openspec schema validate klod
Or, from a checkout of the KLOD repository:
python3 /path/to/keepthelightson/integrations/openspec/install.py --project .
openspec schema validate klod
The installer puts the complete bundle in openspec/schemas/klod/. It leaves
openspec/config.yaml, other schemas, assistant configuration and existing changes
alone. Commit the installed schema with your project so your team has the same version.
Use it on a change
In your coding assistant, ask:
Use OpenSpec to propose add-support-drafting with the klod schema.
Include the human path when AI is unavailable or stopped.
Review the generated proposal, requirements, design and tasks. Then ask:
Apply the add-support-drafting change.
These are ordinary assistant prompts, not new slash commands. Use your installed OpenSpec workflows; they read the schema's instructions and bundled KLOD guidance. Installation alone does not generate a plan or change application code.
For a CLI-created scaffold, the equivalent schema selection is:
openspec new change add-support-drafting --schema klod
Then ask your assistant to continue that existing change using its klod schema.
Do not run both creation paths for the same name. If you want KLOD on every new
change, change the existing schema: value in openspec/config.yaml to klod;
preserve the rest of that file. Existing changes keep their selected schemas.
What the schema adds
- Proposal: identifies runtime AI, the work it serves and the people who need to complete the essential outcome. Unknown owners and operating targets stay explicit.
- Specs: describes observable unavailable-provider, operator-stop and human completion behaviour alongside the feature's normal behaviour.
- Design: traces usable data, permissions, controls, in-flight work and shared dependencies through both AI and human operation.
- Tasks and implementation: includes isolated execution checks and an honest
handover, with operating instructions and an updated
LIGHTS.mdentry where relevant.
The standard specs artifact and delta format remain in place for OpenSpec's sync
and archive workflows. Changes without runtime AI record that scope and continue
normally; using an AI coding assistant alone does not create a supplier-dependence level.
This version is tested with ordinary project-local OpenSpec changes. Standalone
stores, worksets and multi-repository planning are not yet supported by this adapter.
Use it from the project where openspec/schemas/klod/ is installed.
Check the implementation
The apply instructions point to the bundled verification guide. Run the change's authorised isolated tests and inspect actual state and effects. Record failures, unrun checks and the remaining limits. A document describing a test is not a test result.
For a separate repository audit, ask:
Read openspec/schemas/klod/skills/klod-check/SKILL.md and follow it to audit
this project. Write klod_report.md with file evidence and missing evidence.
That audit is read-only apart from its report. It does not run application tests, call providers or perform a live drill. It assesses the repository; a change-only inspection cannot claim complete coverage.
OpenSpec schema dependencies check file existence. They do not enforce successful tests or prove that people can operate the business. L2 requires a real-work drill with AI unavailable; L3 has further evidence gates. Live drills need authorisation, an agreed scope and recovery controls. Never invent participants, dates or measurements.
Update or customise
Download the new bundle and run its installer against the same project. An unchanged
installation can be updated repeatedly. Only previously managed, unchanged files may
be replaced or removed; unrelated files stay in place. The installer refuses local
edits, missing managed files, file collisions and symbolic links before making changes.
It records managed hashes in .klod-install.json inside the installed schema.
To check whether a bundle matches the installation without writing:
python3 /path/to/klod-openspec/install.py --project . --check
If you customise the installed schema, keep those changes in version control. Compare
the new bundle with your copy and merge deliberately; the installer does not have a
force-overwrite option. To maintain a separate custom workflow, copy the installed
folder under a different schema name and update its name and internal
openspec/schemas/klod/ references to match. Keep klod unchanged for managed updates.
OpenSpec's own openspec update does not update custom schema folders. To stop using
KLOD, select a different schema for new changes. Keep the installed folder while any
existing change still references it. Remove it only after preserving your own changes
and confirming it is no longer needed.
Verification and contribution
Compatibility checks cover installation, preservation and updates, schema validation, change creation, artifact dependencies, instruction generation and standard spec validation/archive behaviour with OpenSpec 1.13.0. They do not measure model quality, production readiness or real human takeover.
OpenSpec maintains a community schema catalog and invites repository links or documentation pull requests. A future KLOD submission can link this adapter, its example and compatibility results. No submission or acceptance is implied here. For upstream mechanics, see OpenSpec's schema documentation.
KLOD guidance and templates use CC BY 4.0; the installer uses MIT. The bundled skill copies come from KLOD's canonical skills and are checked for drift. Edit the canonical guidance when changing shared rules.