LightSpec

AI-native spec-driven development tool. Create, manage, and apply specifications with your agent.

Security Scan

The SKILL.md is internally consistent with a CLI-based spec tool: instructions (npm install, lightspec commands, reading .lightspec/config.json) match the described purpose, but installing CLI packages globally and running commands that modify a project carry the usual operational risks and should be done with user consent.

Purpose & Capability

Name/description (spec-driven CLI) align with the instructions: the doc instructs installing a Node.js-based CLI via npm and running lightspec commands. Required capabilities are limited to Node/npm and reading project files (e.g., .lightspec/config.json, AGENTS.md), which are appropriate for this purpose.

Instruction Scope

SKILL.md tells the agent to install the CLI, verify it, run commands (init, change, validate, apply, etc.), and read project files. It does not instruct reading unrelated system files, harvesting env vars, or exfiltrating data. It explicitly advises confirming with the user before running file-changing commands, which is appropriate.

Install Mechanism

This is an instruction-only skill (no install spec). It recommends 'npm install -g lightspec' which is a standard install path for a CLI but involves pulling code from the npm registry and may execute package install scripts and require elevated privileges on some systems. That is expected for a CLI but is a moderate operational risk to be aware of.

Credentials

The skill requests no environment variables or external credentials. It does reference local configuration (.lightspec/config.json) and project files (lightspec/changes/...), which is proportional to a project-scoped CLI tool.

Persistence & Privilege

always is false and autonomous invocation is allowed (platform default). The skill does not request persistent or cross-skill configuration changes in its instructions and does not ask to modify other skills or system-wide agent settings.

Assessment

This skill appears coherent for managing a Node-based CLI. Before installing or allowing the agent to run commands: 1) Verify the npm package and GitHub repository (publisher, recent commits, reputation). 2) Prefer non-global installs (npx or local project install) or run in a sandbox/container if you want to avoid global changes and privilege elevation. 3) Be cautious because 'npm install -g' can run install scripts from the package — inspect the package or its source before installing. 4) Require explicit user confirmation before the agent runs commands that change files (init, apply, uninstall). 5) If you want higher assurance, ask the agent to show the exact commands it will run and to display the lightspec package source or installation log before proceeding.

LightSpec Skill

LightSpec is a CLI tool that brings spec‑driven development to any AI‑assisted workflow. It helps you create feature specifications, track changes, and implement code based on those specs. This skill teaches your OpenClaw agent how to install, verify, update, uninstall, and use LightSpec effectively.

For more details on LightSpec, visit the Lightspec repository

Installation

LightSpec requires Node.js (v18 or later). The agent can install it globally via npm:

npm install -g lightspec

If Node.js is not present, the agent should first install Node.js (platform‑specific instructions can be provided if needed).

Verification

To confirm LightSpec is installed correctly, run:

lightspec --version

The agent should expect a version number like 1.2.3. If the command fails, installation should be retried or the user notified.

Updating

To update LightSpec to the latest version:

npm update -g lightspec

After updating, verify again with lightspec --version.

Uninstalling

To remove LightSpec completely:

npm uninstall -g lightspec

Basic Usage

All LightSpec commands follow the pattern:

lightspec [command] [options]

Initialize a Project

Run inside a project directory to set up LightSpec:

lightspec init

This creates a lightspec/ folder and injects instructions into AGENTS.md (if present). The agent can then use the generated structure.

Create a New Feature Spec

lightspec change "User authentication"

Or using the spec subcommand (depending on version). The agent should inspect the output to see where the spec file was created (usually lightspec/changes/<change-name>/spec.md).

List Existing Changes or Specs

lightspec list          # list active changes
lightspec list --specs  # list all specs

View Interactive Dashboard

lightspec view

The agent can run this to get a high‑level overview of all changes and specs.

Validate a Spec or Change

lightspec validate [change-name]

Checks for completeness and consistency.

Apply a Change (Implement)

After a spec is approved, the agent can apply it to the codebase:

lightspec apply [change-name]

This command generates code or updates files based on the spec (implementation details depend on the project’s configuration).

Show Details of a Change or Spec

lightspec show [change-name]

Workflow Example

1. Initialize project (if not already done)

lightspec init

2. Create a change proposal

lightspec change "Add profile search filters by role and team"

3. Read the generated spec The agent can use read_file to inspect lightspec/changes/add-profile-search-filters/spec.md.

4. Ask the user what’s missing The agent can summarise the spec and point out gaps (e.g., missing acceptance criteria).

5. Validate the spec

lightspec validate add-profile-search-filters

6. Implement after approval

lightspec apply add-profile-search-filters

Tips for the Agent

• Always confirm with the user before running commands that change files (e.g., apply, init in an existing project).
• Use lightspec --help or lightspec help [command] if you need more details about a subcommand.
• LightSpec respects .lightspec/config.json for custom paths – the agent can read that to understand project‑specific settings.
• Refer to the official LightSpec documentation for the most updated information, guidence and how to guide the user.

ClawHub Installation

To install this skill from ClawHub, the user can run:

openclaw install lightspec

Once installed, the agent will automatically load this skill and be able to assist with LightSpec tasks.