lightspec 0.2.1 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +32 -57
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
<p align="center">
|
|
2
2
|
<a href="https://github.com/augmenter-dev/lightspec">
|
|
3
3
|
<picture>
|
|
4
|
-
<img src="assets/augmenter-lightspec.svg" alt="LightSpec logo" height="
|
|
4
|
+
<img src="assets/augmenter-lightspec.svg" alt="LightSpec logo" height="156">
|
|
5
5
|
</picture>
|
|
6
6
|
</a>
|
|
7
7
|
|
|
@@ -20,13 +20,9 @@
|
|
|
20
20
|
<img src="assets/openspec_dashboard.png" alt="LightSpec dashboard preview" width="90%">
|
|
21
21
|
</p>
|
|
22
22
|
|
|
23
|
-
<p align="center">
|
|
24
|
-
Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">LightSpec Discord</a> for help and questions.
|
|
25
|
-
</p>
|
|
26
|
-
|
|
27
23
|
# LightSpec
|
|
28
24
|
|
|
29
|
-
A fork of [
|
|
25
|
+
A fork of [OpenSpec](https://github.com/Fission-AI/OpenSpec), focused on simplicity and skill-based agents.
|
|
30
26
|
|
|
31
27
|
LightSpec aligns humans and AI coding assistants with spec-driven development so you agree on what to build before any code is written. **No API keys required.**
|
|
32
28
|
|
|
@@ -38,13 +34,14 @@ Key outcomes:
|
|
|
38
34
|
- Human and AI stakeholders agree on specs before work begins.
|
|
39
35
|
- Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable.
|
|
40
36
|
- Shared visibility into what's proposed, active, or archived.
|
|
41
|
-
- Works with the AI tools you already use
|
|
37
|
+
- Works with the AI tools you already use via [agent skills](https://agentskills.io/).
|
|
42
38
|
|
|
43
39
|
## How LightSpec compares (at a glance)
|
|
44
40
|
|
|
45
41
|
- **Lightweight**: simple workflow, no API keys, minimal setup.
|
|
46
42
|
- **Brownfield-first**: works great beyond 0→1. LightSpec separates the source of truth from proposals: `lightspec/specs/` (current truth) and `lightspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features.
|
|
47
43
|
- **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs.
|
|
44
|
+
- **Compared to OpenSpec**: LightSpec is a streamlined alternative to OpenSpec, focused on simplicity and ease of adoption. It has fewer commands and a more opinionated workflow, which can reduce cognitive overhead for teams new to spec-driven development.
|
|
48
45
|
- **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). LightSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs.
|
|
49
46
|
|
|
50
47
|
See the full comparison in [How LightSpec Compares](#how-lightspec-compares).
|
|
@@ -85,49 +82,29 @@ See the full comparison in [How LightSpec Compares](#how-lightspec-compares).
|
|
|
85
82
|
|
|
86
83
|
### Supported AI Tools
|
|
87
84
|
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
| **OpenCode** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` |
|
|
112
|
-
| **Qoder (CLI)** | `/lightspec:proposal`, `/lightspec:apply`, `/lightspec:archive` (`.qoder/commands/lightspec/`) — see [docs](https://qoder.com/cli) |
|
|
113
|
-
| **Qwen Code** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.qwen/commands/`) |
|
|
114
|
-
| **RooCode** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.roo/commands/`) |
|
|
115
|
-
| **Windsurf** | `/lightspec-proposal`, `/lightspec-apply`, `/lightspec-archive` (`.windsurf/workflows/`) |
|
|
116
|
-
|
|
117
|
-
Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/lightspec-proposal.md`, `/lightspec-apply.md`, or `/lightspec-archive.md`.
|
|
118
|
-
|
|
119
|
-
</details>
|
|
120
|
-
|
|
121
|
-
<details>
|
|
122
|
-
<summary><strong>AGENTS.md Compatible</strong> (click to expand)</summary>
|
|
123
|
-
|
|
124
|
-
These tools automatically read workflow instructions from `lightspec/AGENTS.md`. Ask them to follow the LightSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/).
|
|
125
|
-
|
|
126
|
-
| Tools |
|
|
127
|
-
|-------|
|
|
128
|
-
| Amp • Jules • Others |
|
|
129
|
-
|
|
130
|
-
</details>
|
|
85
|
+
- Amazon Q Developer
|
|
86
|
+
- Antigravity
|
|
87
|
+
- Auggie (Augment CLI)
|
|
88
|
+
- Claude Code
|
|
89
|
+
- Cline
|
|
90
|
+
- Codex
|
|
91
|
+
- CodeBuddy Code (CLI)
|
|
92
|
+
- Continue (VS Code / JetBrains / CLI)
|
|
93
|
+
- CoStrict
|
|
94
|
+
- Crush
|
|
95
|
+
- Cursor
|
|
96
|
+
- Factory Droid
|
|
97
|
+
- Gemini CLI
|
|
98
|
+
- GitHub Copilot
|
|
99
|
+
- iFlow
|
|
100
|
+
- Kilo Code
|
|
101
|
+
- Mistral Vibe
|
|
102
|
+
- OpenCode
|
|
103
|
+
- Qoder (CLI)
|
|
104
|
+
- Qwen Code
|
|
105
|
+
- RooCode
|
|
106
|
+
- Windsurf
|
|
107
|
+
- Any AGENTS.md-compatible assistant (via Universal `AGENTS.md`)
|
|
131
108
|
|
|
132
109
|
### Install & Initialize
|
|
133
110
|
|
|
@@ -194,14 +171,14 @@ lightspec init
|
|
|
194
171
|
|
|
195
172
|
**What happens during initialization:**
|
|
196
173
|
- You'll be prompted to pick any natively supported AI tools (Claude Code, CodeBuddy, Cursor, OpenCode, Qoder,etc.); other assistants always rely on the shared `AGENTS.md` stub
|
|
197
|
-
- LightSpec automatically configures
|
|
174
|
+
- LightSpec automatically configures skills for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root
|
|
198
175
|
- A new `lightspec/` directory structure is created in your project
|
|
199
176
|
|
|
200
177
|
**After setup:**
|
|
201
178
|
- Primary AI tools can trigger `/lightspec` workflows without additional configuration
|
|
202
179
|
- Run `lightspec list` to verify the setup and view any active changes
|
|
203
|
-
- If your coding assistant doesn't surface the new
|
|
204
|
-
|
|
180
|
+
- If your coding assistant doesn't surface the new skills right away, restart it. Skills are loaded at startup, so a fresh launch ensures they appear
|
|
181
|
+
- Depending on your AI tool, you'll need to invoke the lightspec skills with either slash commands (e.g. `/lightspec:proposal`) or dollar commands (e.g. `$lightspec-proposal`) to create change proposals, apply changes, or archive completed work
|
|
205
182
|
|
|
206
183
|
### Optional: Populate Project Context
|
|
207
184
|
|
|
@@ -216,7 +193,7 @@ Use the `/lightspec:context-check` skill to validate that your agent instruction
|
|
|
216
193
|
|
|
217
194
|
### Create Your First Change
|
|
218
195
|
|
|
219
|
-
Here's a real example showing the complete LightSpec workflow. This works with any AI tool.
|
|
196
|
+
Here's a real example showing the complete LightSpec workflow. This works with any AI tool.
|
|
220
197
|
|
|
221
198
|
#### 1. Draft the Proposal
|
|
222
199
|
Start by asking your AI to create a change proposal:
|
|
@@ -279,8 +256,6 @@ Or run the command yourself in terminal:
|
|
|
279
256
|
$ lightspec archive add-profile-filters --yes # Archive the completed change without prompts
|
|
280
257
|
```
|
|
281
258
|
|
|
282
|
-
**Note:** Tools with native slash commands (Claude Code, CodeBuddy, Cursor, Codex, Qoder, RooCode) can use the shortcuts shown. All other tools work with natural language requests to "create an LightSpec proposal", "apply the LightSpec change", or "archive the change".
|
|
283
|
-
|
|
284
259
|
## Command Reference
|
|
285
260
|
|
|
286
261
|
```bash
|
|
@@ -405,7 +380,7 @@ Run `lightspec update` whenever someone switches tools so your agents pick up th
|
|
|
405
380
|
npm install -g lightspec@latest
|
|
406
381
|
```
|
|
407
382
|
2. **Refresh agent instructions**
|
|
408
|
-
- Run `lightspec update` inside each project to regenerate AI guidance and ensure the latest
|
|
383
|
+
- Run `lightspec update` inside each project to regenerate AI guidance and ensure the latest skills are active.
|
|
409
384
|
|
|
410
385
|
## Contributing
|
|
411
386
|
|