diff --git a/.changeset/README.md b/.changeset/README.md index 2511ccacb..f387945f8 100644 --- a/.changeset/README.md +++ b/.changeset/README.md @@ -16,7 +16,7 @@ Follow the prompts to select version bump type and describe your changes. 2. **Version PR** — CI opens/updates a "Version Packages" PR when changesets merge to main 3. **Release** — Merging the Version PR triggers npm publish and GitHub Release -> **Note:** Contributors only need to run `pnpm changeset`. Versioning (`changeset version`) and publishing happen automatically in CI. +> **Note:** Contributors only need to run `pnpm changeset`. Versioning and publishing are run via the manual release workflow (`release-prepare`) or local manual release script. ## Template @@ -24,7 +24,7 @@ Use this structure for your changeset content: ```markdown --- -"@fission-ai/openspec": patch +"@augmenter-dev/lightspec": patch --- ### New Features diff --git a/.changeset/config.json b/.changeset/config.json index 50cbb5132..a43f13c3c 100644 --- a/.changeset/config.json +++ b/.changeset/config.json @@ -2,7 +2,7 @@ "$schema": "https://unpkg.com/@changesets/config/schema.json", "changelog": [ "@changesets/changelog-github", - { "repo": "Fission-AI/OpenSpec" } + { "repo": "augmenter-dev/lightspec" } ], "commit": false, "fixed": [], diff --git a/.changeset/thin-pigs-stare.md b/.changeset/thin-pigs-stare.md new file mode 100644 index 000000000..68b1f1341 --- /dev/null +++ b/.changeset/thin-pigs-stare.md @@ -0,0 +1,5 @@ +--- +"lightspec": patch +--- + +Minor CI updates diff --git a/.claude/skills/lightspec-apply/.gitkeep b/.claude/skills/lightspec-apply/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/.claude/skills/lightspec-apply/SKILL.md b/.claude/skills/lightspec-apply/SKILL.md new file mode 100644 index 000000000..4cdcde0fa --- /dev/null +++ b/.claude/skills/lightspec-apply/SKILL.md @@ -0,0 +1,58 @@ +--- +name: lightspec-apply +description: Get instructions for implementing a change +disable-model-invocation: true +--- + +Generate enriched instructions for implementing the tasks in a change. + +## Usage + +Use this skill when ready to implement the tasks for a change. + +## What This Does + +1. Shows which artifacts are complete and which are pending +2. Displays task progress with checkboxes +3. Provides context files to read +4. Gives implementation instructions +5. Shows what's blocking progress (if anything) + +## Implementation + +Use the CLI command: +```bash +lightspec instructions apply [options] +``` + +### Options + +- `--change `: Change name (auto-detected if only one change) +- `--schema `: Schema override (auto-detected from change metadata) +- `--json`: Output as JSON (for agents/automation) + +### Example + +```bash +# Get apply instructions for the current change +lightspec instructions apply + +# Get apply instructions for a specific change +lightspec instructions apply --change add-user-authentication + +# Get JSON output for automation +lightspec instructions apply --json +``` + +## Output Interpretation + +The command shows: +- **Progress**: X/Y tasks complete +- **State**: ready (all artifacts complete), blocked (missing artifacts), or all_done (all tasks complete) +- **Context Files**: List of artifacts to read for context +- **Tasks**: Checklist with [x] for done, [ ] for pending +- **Instruction**: Implementation guidance + +## When Blocked + +If the state is "blocked", create missing artifacts first using the lightspec-new skill for each artifact, or run `lightspec new change ` to continue. diff --git a/.claude/skills/lightspec-archive/.gitkeep b/.claude/skills/lightspec-archive/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/.claude/skills/lightspec-archive/SKILL.md b/.claude/skills/lightspec-archive/SKILL.md new file mode 100644 index 000000000..5e975e42a --- /dev/null +++ b/.claude/skills/lightspec-archive/SKILL.md @@ -0,0 +1,60 @@ +--- +name: lightspec-archive +description: Archive a completed change and update main specs +disable-model-invocation: true +--- + +Archive a completed change, merging delta specs into main specifications. + +## Usage + +Use this skill when: +- A change is fully implemented +- All tasks are complete +- Tests pass +- Ready to integrate changes into main specs + +## What This Does + +1. Validates the change (unless --no-validate) +2. Merges delta specs from the change into main specs +3. Moves the change to the archive +4. Updates spec versions + +## Implementation + +Use the CLI command: +```bash +lightspec archive [change-name] [options] +``` + +### Options + +- `-y, --yes`: Skip confirmation prompts +- `--skip-specs`: Skip spec update (for infrastructure/tooling/doc-only changes) +- `--no-validate`: Skip validation (not recommended, requires confirmation) + +### Example + +```bash +# Archive with prompts +lightspec archive add-user-authentication + +# Archive without confirmation +lightspec archive add-user-authentication -y + +# Archive infrastructure change (no spec updates) +lightspec archive upgrade-dependencies --skip-specs -y +``` + +## Before Archiving + +Ensure: +1. All code changes are committed +2. Tests pass +3. Artifacts are complete (check with `lightspec status`) +4. Delta specs are properly written + +## After Archiving + +The change will be moved to `lightspec/changes/archive/` and main specs will be updated with the changes. diff --git a/.claude/skills/lightspec-new/.gitkeep b/.claude/skills/lightspec-new/.gitkeep new file mode 100644 index 000000000..e69de29bb diff --git a/.claude/skills/lightspec-new/SKILL.md b/.claude/skills/lightspec-new/SKILL.md new file mode 100644 index 000000000..d4dc4438e --- /dev/null +++ b/.claude/skills/lightspec-new/SKILL.md @@ -0,0 +1,41 @@ +--- +name: lightspec-new +description: Create a new change proposal for tracking work +disable-model-invocation: true +--- + +Create a new change proposal to track development work. + +## Usage + +Use this skill when starting a new feature, bug fix, or any tracked work. + +## What This Does + +1. Creates a new change directory under `lightspec/changes//` +2. Creates change metadata for tracking +3. Optionally adds a README.md with description + +## Implementation + +Use the CLI command: +```bash +lightspec new change [options] +``` + +### Options + +- `--description `: Description to add to README.md +- `--schema `: Workflow schema to use (default: spec-driven) + +### Example + +```bash +# Create a new change +lightspec new change add-user-authentication --description "Add OAuth2 authentication" + +# Or use default description +lightspec new change refactor-database +``` + +This creates the change structure and makes it ready for artifact creation. diff --git a/.devcontainer/README.md b/.devcontainer/README.md index 989fa527f..ce5a968e5 100644 --- a/.devcontainer/README.md +++ b/.devcontainer/README.md @@ -1,6 +1,6 @@ # Dev Container Setup -This directory contains the VS Code dev container configuration for OpenSpec development. +This directory contains the VS Code dev container configuration for LightSpec development. ## What's Included diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index c381b61fa..acb5d4954 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -1,5 +1,5 @@ { - "name": "OpenSpec Development", + "name": "LightSpec Development", "image": "mcr.microsoft.com/devcontainers/typescript-node:1-20-bookworm", // Additional tools and features diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index e066888ea..cb2d8c317 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,2 +1,3 @@ # Default code ownership -* @TabishB +* @viteinfinite +* jlnquere diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2b887c745..fb92b4343 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -52,8 +52,6 @@ jobs: - name: Setup pnpm uses: pnpm/action-setup@v4 - with: - version: 9 - name: Setup Node.js uses: actions/setup-node@v4 @@ -108,8 +106,6 @@ jobs: - name: Setup pnpm uses: pnpm/action-setup@v4 - with: - version: 9 - name: Setup Node.js uses: actions/setup-node@v4 @@ -147,8 +143,6 @@ jobs: - name: Setup pnpm uses: pnpm/action-setup@v4 - with: - version: 9 - name: Setup Node.js uses: actions/setup-node@v4 @@ -204,8 +198,8 @@ jobs: echo "Error: Nix build output 'result' symlink not found" exit 1 fi - if [ ! -f "result/bin/openspec" ]; then - echo "Error: openspec binary not found in build output" + if [ ! -f "result/bin/lightspec" ]; then + echo "Error: lightspec binary not found in build output" exit 1 fi echo "✅ Build output verified" @@ -213,7 +207,7 @@ jobs: - name: Test binary execution run: | VERSION=$(nix run . -- --version) - echo "OpenSpec version: $VERSION" + echo "LightSpec version: $VERSION" if [ -z "$VERSION" ]; then echo "Error: Version command returned empty output" exit 1 @@ -251,8 +245,6 @@ jobs: - name: Setup pnpm uses: pnpm/action-setup@v4 - with: - version: 9 - name: Setup Node.js uses: actions/setup-node@v4 diff --git a/.github/workflows/polish-release-notes.yml b/.github/workflows/polish-release-notes.yml index 49e2bff84..c808eb90f 100644 --- a/.github/workflows/polish-release-notes.yml +++ b/.github/workflows/polish-release-notes.yml @@ -19,12 +19,24 @@ permissions: jobs: polish: # Only run on the main repo, not forks - if: github.repository == 'Fission-AI/OpenSpec' + if: github.repository == 'augmenter-dev/lightspec' runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + - name: Check Claude auth availability + id: auth-check + env: + CLAUDE_CODE_OAUTH_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + if [ -n "${CLAUDE_CODE_OAUTH_TOKEN}" ] || [ -n "${ANTHROPIC_API_KEY}" ]; then + echo "has_auth=true" >> "$GITHUB_OUTPUT" + else + echo "has_auth=false" >> "$GITHUB_OUTPUT" + fi + - name: Get current release body id: get-release env: @@ -34,18 +46,20 @@ jobs: echo "Fetched release notes for ${{ env.TAG_NAME }}" - name: Transform release notes with Claude + if: ${{ steps.auth-check.outputs.has_auth == 'true' }} uses: anthropics/claude-code-action@v1 id: claude with: claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }} + anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} github_token: ${{ secrets.GITHUB_TOKEN }} claude_args: "--allowedTools Write,Read" prompt: | - Transform the changelog in `current-notes.md` into release notes for OpenSpec ${{ env.TAG_NAME }}. + Transform the changelog in `current-notes.md` into release notes for LightSpec ${{ env.TAG_NAME }}. ## Voice - OpenSpec is a developer tool. Write like you're talking to a peer: + LightSpec is a developer tool. Write like you're talking to a peer: - Direct and practical, not marketing copy - Focus on what changed and why it matters - Skip the hype, keep it real @@ -62,7 +76,7 @@ jobs: ``` Examples: - - `v0.18.0 - OPSX Experimental Workflow` + - `v0.23.0 - Enhanced Change Management` - `v0.16.0 - Antigravity, iFlow Support` - `v0.15.0 - Gemini CLI, RooCode` @@ -96,7 +110,7 @@ jobs: ## Rules - 1. Write for developers using OpenSpec with AI coding assistants + 1. Write for developers using LightSpec with AI coding assistants 2. Remove commit hashes (like `eb152eb:`), PR numbers, and changesets wrappers (`### Minor Changes`) 3. Lead with what users can do, not implementation details 4. One to two sentences per item, max @@ -109,25 +123,30 @@ jobs: Before: ``` ### Minor Changes - - 8dfd824: Add OPSX experimental workflow commands and enhanced artifact system + - 8dfd824: Add support for archiving completed changes with metadata preservation **New Commands:** - - `/opsx:ff` - Fast-forward through artifact creation + - `lightspec archive` - Archive completed changes ``` After (polished-notes.md): ``` ### New - - **Fast-forward mode** - Generate all planning artifacts at once with `/opsx:ff`. Useful when you already know what you're building. + - **Change archiving** - Archive completed changes with `lightspec archive`. Preserves change history and metadata. ``` After (release-title.txt): ``` - v0.18.0 - OPSX Experimental Workflow + v0.23.0 - Enhanced Change Management ``` Write both files. No other output. + - name: Skip polishing (Claude auth not configured) + if: ${{ steps.auth-check.outputs.has_auth != 'true' }} + run: | + echo "Skipping AI polishing: configure CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY to enable this step." + - name: Update release env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/release-prepare.yml b/.github/workflows/release-prepare.yml index 5e81c9f52..f92b0bcf5 100644 --- a/.github/workflows/release-prepare.yml +++ b/.github/workflows/release-prepare.yml @@ -1,10 +1,10 @@ name: Release (prepare) on: - push: - branches: [main] + workflow_dispatch: permissions: + actions: write contents: write pull-requests: write id-token: write # Required for npm OIDC trusted publishing @@ -15,7 +15,7 @@ concurrency: jobs: prepare: - if: github.repository == 'Fission-AI/OpenSpec' + if: github.repository == 'augmenter-dev/lightspec' runs-on: ubuntu-latest steps: # Generate GitHub App token first - used for checkout and changesets @@ -23,6 +23,7 @@ jobs: # (GITHUB_TOKEN cannot trigger workflows by design) - name: Generate GitHub App Token id: app-token + continue-on-error: true uses: actions/create-github-app-token@v2 with: app-id: ${{ vars.APP_ID }} @@ -31,11 +32,9 @@ jobs: - uses: actions/checkout@v4 with: fetch-depth: 0 - token: ${{ steps.app-token.outputs.token }} + token: ${{ steps.app-token.outputs.token || github.token }} - uses: pnpm/action-setup@v4 - with: - version: 9 - uses: actions/setup-node@v4 with: @@ -56,14 +55,14 @@ jobs: # so package.json already contains the bumped version. publish: pnpm run release:ci env: - GITHUB_TOKEN: ${{ steps.app-token.outputs.token }} + GITHUB_TOKEN: ${{ steps.app-token.outputs.token || github.token }} # npm authentication handled via OIDC trusted publishing (no token needed) # Trigger release notes polishing after a release is published - name: Polish release notes if: steps.changesets.outputs.published == 'true' env: - GH_TOKEN: ${{ steps.app-token.outputs.token }} + GH_TOKEN: ${{ steps.app-token.outputs.token || github.token }} run: | # Get version from package.json (just bumped by changesets) TAG="v$(jq -r .version package.json)" diff --git a/.gitignore b/.gitignore index 743fdf018..d54bf66c6 100644 --- a/.gitignore +++ b/.gitignore @@ -149,3 +149,7 @@ CLAUDE.md # Pnpm .pnpm-store/ result + +# Local ad-hoc tooling +demo/ +.local-scripts/ diff --git a/AGENTS.md b/AGENTS.md index 7f111dd72..483a1ea3b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,18 +1,18 @@ - -# OpenSpec Instructions + +# LightSpec Instructions These instructions are for AI assistants working in this project. -Always open `@/openspec/AGENTS.md` when the request: +Always open `@/lightspec/AGENTS.md` when the request: - Mentions planning or proposals (words like proposal, spec, change, plan) - Introduces new capabilities, breaking changes, architecture shifts, or big performance/security work - Sounds ambiguous and you need the authoritative spec before coding -Use `@/openspec/AGENTS.md` to learn: +Use `@/lightspec/AGENTS.md` to learn: - How to create and apply change proposals - Spec format and conventions - Project structure and guidelines -Keep this managed block so 'openspec update' can refresh the instructions. +Keep this managed block so 'lightspec update' can refresh the instructions. - + diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b25ccb29..f6f15e4fb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,364 +1,41 @@ -# @fission-ai/openspec +# lightspec -## 0.23.0 - -### Minor Changes - -- [#540](https://github.com/Fission-AI/OpenSpec/pull/540) [`c4cfdc7`](https://github.com/Fission-AI/OpenSpec/commit/c4cfdc7c499daef30d8a218f5f59b8d9e5adb754) Thanks [@TabishB](https://github.com/TabishB)! - ### New Features - - - **Bulk archive skill** — Archive multiple completed changes in a single operation with `/opsx:bulk-archive`. Includes batch validation, spec conflict detection, and consolidated confirmation - - ### Other - - - **Simplified setup** — Config creation now uses sensible defaults with helpful comments instead of interactive prompts - -## 0.22.0 - -### Minor Changes - -- [#530](https://github.com/Fission-AI/OpenSpec/pull/530) [`33466b1`](https://github.com/Fission-AI/OpenSpec/commit/33466b1e2a6798bdd6d0e19149173585b0612e6f) Thanks [@TabishB](https://github.com/TabishB)! - Add project-level configuration, project-local schemas, and schema management commands - - **New Features** - - - **Project-level configuration** — Configure OpenSpec behavior per-project via `openspec/config.yaml`, including custom rules injection, context files, and schema resolution settings - - **Project-local schemas** — Define custom artifact schemas within your project's `openspec/schemas/` directory for project-specific workflows - - **Schema management commands** — New `openspec schema` commands (`list`, `show`, `export`, `validate`) for inspecting and managing artifact schemas (experimental) - - **Bug Fixes** - - - Fixed config loading to handle null `rules` field in project configuration - -## 0.21.0 - -### Minor Changes - -- [#516](https://github.com/Fission-AI/OpenSpec/pull/516) [`b5a8847`](https://github.com/Fission-AI/OpenSpec/commit/b5a884748be6156a7bb140b4941cfec4f20a9fc8) Thanks [@TabishB](https://github.com/TabishB)! - Add feedback command and Nix flake support - - **New Features** - - - **Feedback command** — Submit feedback directly from the CLI with `openspec feedback`, which creates GitHub Issues with automatic metadata inclusion and graceful fallback for manual submission - - **Nix flake support** — Install and develop openspec using Nix with the new `flake.nix`, including automated flake maintenance and CI validation - - **Bug Fixes** - - - **Explore mode guardrails** — Explore mode now explicitly prevents implementation, keeping the focus on thinking and discovery while still allowing artifact creation - - **Other** - - - Improved change inference in `opsx apply` — automatically detects the target change from conversation context or prompts when ambiguous - - Streamlined archive sync assessment with clearer delta spec location guidance - -## 0.20.0 - -### Minor Changes - -- [#502](https://github.com/Fission-AI/OpenSpec/pull/502) [`9db74aa`](https://github.com/Fission-AI/OpenSpec/commit/9db74aa5ac6547efadaed795217cfa17444f2004) Thanks [@TabishB](https://github.com/TabishB)! - Add `/opsx:verify` command and fix vitest process storms - - **New Features** - - - **`/opsx:verify` command** — Validate that change implementations match their specifications - - **Bug Fixes** - - - Fixed vitest process storms by capping worker parallelism - - Fixed agent workflows to use non-interactive mode for validation commands - - Fixed PowerShell completions generator to remove trailing commas - -## 0.19.0 - -### Minor Changes - -- eb152eb: Add Continue IDE support, shell completions, and `/opsx:explore` command - - **New Features** - - - **Continue IDE support** – OpenSpec now generates slash commands for [Continue](https://continue.dev/), expanding editor integration options alongside Cursor, Windsurf, Claude Code, and others - - **Shell completions for Bash, Fish, and PowerShell** – Run `openspec completion install` to set up tab completion in your preferred shell - - **`/opsx:explore` command** – A new thinking partner mode for exploring ideas and investigating problems before committing to changes - - **Codebuddy slash command improvements** – Updated frontmatter format for better compatibility - - **Bug Fixes** - - - Shell completions now correctly offer parent-level flags (like `--help`) when a command has subcommands - - Fixed Windows compatibility issues in tests - - **Other** - - - Added optional anonymous usage statistics to help understand how OpenSpec is used. This is **opt-out** by default – set `OPENSPEC_TELEMETRY=0` or `DO_NOT_TRACK=1` to disable. Only command names and version are collected; no arguments, file paths, or content. Automatically disabled in CI environments. - -## 0.18.0 - -### Minor Changes - -- 8dfd824: Add OPSX experimental workflow commands and enhanced artifact system - - **New Commands:** - - - `/opsx:ff` - Fast-forward through artifact creation, generating all needed artifacts in one go - - `/opsx:sync` - Sync delta specs from a change to main specs - - `/opsx:archive` - Archive completed changes with smart sync check - - **Artifact Workflow Enhancements:** - - - Schema-aware apply instructions with inline guidance and XML output - - Agent schema selection for experimental artifact workflow - - Per-change schema metadata via `.openspec.yaml` files - - Agent Skills for experimental artifact workflow - - Instruction loader for template loading and change context - - Restructured schemas as directories with templates - - **Improvements:** - - - Enhanced list command with last modified timestamps and sorting - - Change creation utilities for better workflow support - - **Fixes:** - - - Normalize paths for cross-platform glob compatibility - - Allow REMOVED requirements when creating new spec files - -## 0.17.2 - -### Patch Changes - -- 455c65f: Fix `--no-interactive` flag in validate command to properly disable spinner, preventing hangs in pre-commit hooks and CI environments - -## 0.17.1 - -### Patch Changes - -- a2757e7: Fix pre-commit hook hang issue in config command by using dynamic import for @inquirer/prompts - - The config command was causing pre-commit hooks to hang indefinitely due to stdin event listeners being registered at module load time. This fix converts the static import to a dynamic import that only loads inquirer when the `config reset` command is actually used interactively. - - Also adds ESLint with a rule to prevent static @inquirer imports, avoiding future regressions. - -## 0.17.0 - -### Minor Changes - -- 2e71835: Add `openspec config` command and Oh-my-zsh completions - - **New Features** - - - Add `openspec config` command for managing global configuration settings - - Implement global config directory with XDG Base Directory specification support - - Add Oh-my-zsh shell completions support for enhanced CLI experience - - **Bug Fixes** - - - Fix hang in pre-commit hooks by using dynamic imports - - Respect XDG_CONFIG_HOME environment variable on all platforms - - Resolve Windows compatibility issues in zsh-installer tests - - Align cli-completion spec with implementation - - Remove hardcoded agent field from slash commands - - **Documentation** - - - Alphabetize AI tools list in README and make it collapsible - -## 0.16.0 - -### Minor Changes - -- c08fbc1: Add new AI tool integrations and enhancements: - - - **feat(iflow-cli)**: Add iFlow-cli integration with slash command support and documentation - - **feat(init)**: Add IDE restart instruction after init to inform users about slash command availability - **feat(antigravity)**: Add Antigravity slash command support - - **fix**: Generate TOML commands for Qwen Code (fixes #293) - - Clarify scaffold proposal documentation and enhance proposal guidelines - - Update proposal guidelines to emphasize design-first approach before implementation - -## Unreleased - -### Minor Changes - -- Add Continue slash command support so `openspec init` can generate `.continue/prompts/openspec-*.prompt` files with MARKDOWN frontmatter and `$ARGUMENTS` placeholder, and refresh them on `openspec update`. - -- Add Antigravity slash command support so `openspec init` can generate `.agent/workflows/openspec-*.md` files with description-only frontmatter and `openspec update` refreshes existing workflows alongside Windsurf. - -## 0.15.0 - -### Minor Changes - -- 4758c5c: Add support for new AI tools with native slash command integration - - - **Gemini CLI**: Add native TOML-based slash command support for Gemini CLI with `.gemini/commands/openspec/` integration - - **RooCode**: Add RooCode integration with configurator, slash commands, and templates - - **Cline**: Fix Cline to use workflows instead of rules for slash commands (`.clinerules/workflows/` paths) - - **Documentation**: Update documentation to reflect new integrations and workflow changes - -## 0.14.0 - -### Minor Changes - -- 8386b91: Add support for new AI assistants and configuration improvements - - - feat: add Qwen Code support with slash command integration - - feat: add $ARGUMENTS support to apply slash command for dynamic variable passing - - feat: add Qoder CLI support to configuration and documentation - - feat: add CoStrict AI assistant support - - fix: recreate missing openspec template files in extend mode - - fix: prevent false 'already configured' detection for tools - - fix: use change-id as fallback title instead of "Untitled Change" - - docs: add guidance for populating project-level context - - docs: add Crush to supported AI tools in README - -## 0.13.0 - -### Minor Changes - -- 668a125: Add support for multiple AI assistants and improve validation - - This release adds support for several new AI coding assistants: - - - CodeBuddy Code - AI-powered coding assistant - - CodeRabbit - AI code review assistant - - Cline - Claude-powered CLI assistant - - Crush AI - AI assistant platform - - Auggie (Augment CLI) - Code augmentation tool - - New features: - - - Archive slash command now supports arguments for more flexible workflows - - Bug fixes: - - - Delta spec validation now handles case-insensitive headers and properly detects empty sections - - Archive validation now correctly honors --no-validate flag and ignores metadata - - Documentation improvements: - - - Added VS Code dev container configuration for easier development setup - - Updated AGENTS.md with explicit change-id notation - - Enhanced slash commands documentation with restart notes - -## 0.12.0 - -### Minor Changes - -- 082abb4: Add factory function support for slash commands and non-interactive init options - - This release includes two new features: - - - **Factory function support for slash commands**: Slash commands can now be defined as functions that return command objects, enabling dynamic command configuration - - **Non-interactive init options**: Added `--tools`, `--all-tools`, and `--skip-tools` CLI flags to `openspec init` for automated initialization in CI/CD pipelines while maintaining backward compatibility with interactive mode - -## 0.11.0 - -### Minor Changes - -- 312e1d6: Add Amazon Q Developer CLI integration. OpenSpec now supports Amazon Q Developer with automatic prompt generation in `.amazonq/prompts/` directory, allowing you to use OpenSpec slash commands with Amazon Q's @-syntax. - -## 0.10.0 +## 0.3.0 ### Minor Changes -- d7e0ce8: Improve init wizard Enter key behavior to allow proceeding through prompts more naturally - -## 0.9.2 - -### Patch Changes - -- 2ae0484: Fix cross-platform path handling issues. This release includes fixes for joinPath behavior and slash command path resolution to ensure OpenSpec works correctly across all platforms. +- [#5](https://github.com/augmenter-dev/LightSpec/pull/5) [`5c8c61b`](https://github.com/augmenter-dev/LightSpec/commit/5c8c61be993222e61751f8a3dec7a5d0fd32c97a) Thanks [@viteinfinite](https://github.com/viteinfinite)! - Overhaul the AGENT.md and CLAUDE.md instructions; remove all references to Custom Commands, with now cease to exist -## 0.9.1 +## 0.2.2 ### Patch Changes -- 8210970: Fix OpenSpec not working on Windows when Codex integration is selected. This release includes fixes for cross-platform path handling and normalization to ensure OpenSpec works correctly on Windows systems. +- [`ce7b439`](https://github.com/augmenter-dev/LightSpec/commit/ce7b43941aaaa8ca383684a4c6e5d477684f15b4) Thanks [@viteinfinite](https://github.com/viteinfinite)! - Update the docs with skills and new features -## 0.9.0 - -### Minor Changes - -- efbbf3b: Add support for Codex and GitHub Copilot slash commands with YAML frontmatter and $ARGUMENTS - -## Unreleased - -### Minor Changes - -- Add GitHub Copilot slash command support. OpenSpec now writes prompts to `.github/prompts/openspec-{proposal,apply,archive}.prompt.md` with YAML frontmatter and `$ARGUMENTS` placeholder, and refreshes them on `openspec update`. - -## 0.8.1 +## 0.2.1 ### Patch Changes -- d070d08: Fix CLI version mismatch and add a release guard that validates the packed tarball prints the same version as package.json via `openspec --version`. - -## 0.8.0 - -### Minor Changes +- [`2ff86f0`](https://github.com/augmenter-dev/LightSpec/commit/2ff86f0d61c8a306b2cabfde2249c1006392494e) Thanks [@viteinfinite](https://github.com/viteinfinite)! - Fix command name in the docs -- c29b06d: Add Windsurf support. -- Add Codex slash command support. OpenSpec now writes prompts directly to Codex's global directory (`~/.codex/prompts` or `$CODEX_HOME/prompts`) and refreshes them on `openspec update`. +- [`2ff86f0`](https://github.com/augmenter-dev/LightSpec/commit/2ff86f0d61c8a306b2cabfde2249c1006392494e) Thanks [@viteinfinite](https://github.com/viteinfinite)! - Change support URL -## 0.7.0 - -### Minor Changes - -- Add native Kilo Code workflow integration so `openspec init` and `openspec update` manage `.kilocode/workflows/openspec-*.md` files. -- Always scaffold the managed root `AGENTS.md` hand-off stub and regroup the AI tool prompts during init/update to keep instructions consistent. - -## 0.6.0 - -### Minor Changes - -- Slim the generated root agent instructions down to a managed hand-off stub and update the init/update flows to refresh it safely. - -## 0.5.0 +## 0.2.0 ### Minor Changes -- feat: implement Phase 1 E2E testing with cross-platform CI matrix +- [`f7776e8`](https://github.com/augmenter-dev/LightSpec/commit/f7776e8809b9db94babb3ad39632eb22c4920b9d) Thanks [@viteinfinite](https://github.com/viteinfinite)! - ### New Features - - Add shared runCLI helper in test/helpers/run-cli.ts for spawn testing - - Create test/cli-e2e/basic.test.ts covering help, version, validate flows - - Migrate existing CLI exec tests to use runCLI helper - - Extend CI matrix to bash (Linux/macOS) and pwsh (Windows) - - Split PR and main workflows for optimized feedback + - **Mistral Vibe support** — `lightspec init` now supports `mistral-vibe` and installs LightSpec skills under `.vibe/skills/...`. -### Patch Changes - -- Make apply instructions more specific - - Improve agent templates and slash command templates with more specific and actionable apply instructions. - -- docs: improve documentation and cleanup - - - Document non-interactive flag for archive command - - Replace discord badge in README - - Archive completed changes for better organization - -## 0.4.0 + ### Other -### Minor Changes + - Removed an obsolete Codex-only setup note from init success output. -- Add OpenSpec change proposals for CLI improvements and enhanced user experience -- Add Opencode slash commands support for AI-driven development workflows +## 0.1.1 ### Patch Changes -- Add documentation improvements including --yes flag for archive command template and Discord badge -- Fix normalize line endings in markdown parser to handle CRLF files properly - -## 0.3.0 - -### Minor Changes - -- Enhance `openspec init` with extend mode, multi-tool selection, and an interactive `AGENTS.md` configurator. - -## 0.2.0 - -### Minor Changes - -- ce5cead: - Add an `openspec view` dashboard that rolls up spec counts and change progress at a glance - - Generate and update AI slash commands alongside the renamed `openspec/AGENTS.md` instructions file - - Remove the deprecated `openspec diff` command and direct users to `openspec show` - -## 0.1.0 - -### Minor Changes +- [`037babb`](https://github.com/augmenter-dev/LightSpec/commit/037babb01f66d2f9f90f1c9e473234398774f6fc) Thanks [@viteinfinite](https://github.com/viteinfinite)! - First LightSpec version forked from a previous OpenSpec release -- 24b4866: Initial release +## 0.1.0 (2026-02-07) diff --git a/LICENSE b/LICENSE index 84c125ae7..d15f8bda2 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2024 OpenSpec Contributors +Copyright (c) 2026 LightSpec Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/MAINTAINERS.md b/MAINTAINERS.md index d27e1ef46..44c9c3fc1 100644 --- a/MAINTAINERS.md +++ b/MAINTAINERS.md @@ -1,17 +1,11 @@ # Maintainers -People who maintain and guide OpenSpec. +People who maintain and guide LightSpec. ## Core Maintainers | Name | GitHub | Role | |------|--------|------| -| Tabish Bidiwale | [@TabishB](https://github.com/TabishB) | Lead maintainer | +| Simone Civetta | [@viteinfinite](https://github.com/viteinfinite) | Lead maintainer | -## Advisors - -Advisors help shape technical direction and provide guidance to the project. - -| Name | GitHub | Focus | -|------|--------|-------| -| Hari Krishnan | [@harikrishnan83](https://github.com/harikrishnan83) | Technical direction | +## Forked from Tabish Bidiwale | [@TabishB](https://github.com/TabishB)'s [OpenSpec]. diff --git a/README.md b/README.md index 3424bbff3..de4685cfc 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,50 @@

- + - - - OpenSpec logo + LightSpec logo

Spec-driven development for AI coding assistants.

- CI - npm version - node version + CI + npm version + node version License: MIT Conventional Commits Discord

- OpenSpec dashboard preview + LightSpec dashboard preview

-

- Follow @0xTab on X for updates · Join the OpenSpec Discord for help and questions. -

- -

- 🧪 New: Experimental Workflow (OPSX) — schema-driven, hackable, fluid. Iterate on workflows without code changes. -

+# LightSpec -# OpenSpec +A fork of [OpenSpec](https://github.com/Fission-AI/OpenSpec), focused on simplicity and skill-based agents. -OpenSpec 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.** +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.** -## Why OpenSpec? +## Why LightSpec? -AI coding assistants are powerful but unpredictable when requirements live in chat history. OpenSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs. +AI coding assistants are powerful but unpredictable when requirements live in chat history. LightSpec adds a lightweight specification workflow that locks intent before implementation, giving you deterministic, reviewable outputs. Key outcomes: - Human and AI stakeholders agree on specs before work begins. - Structured change folders (proposals, tasks, and spec updates) keep scope explicit and auditable. - Shared visibility into what's proposed, active, or archived. -- Works with the AI tools you already use: custom slash commands where supported, context rules everywhere else. +- Works with the AI tools you already use via [agent skills](https://agentskills.io/). -## How OpenSpec compares (at a glance) +## How LightSpec compares (at a glance) - **Lightweight**: simple workflow, no API keys, minimal setup. -- **Brownfield-first**: works great beyond 0→1. OpenSpec separates the source of truth from proposals: `openspec/specs/` (current truth) and `openspec/changes/` (proposed updates). This keeps diffs explicit and manageable across features. +- **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. - **Change tracking**: proposals, tasks, and spec deltas live together; archiving merges the approved updates back into specs. -- **Compared to spec-kit & Kiro**: those shine for brand-new features (0→1). OpenSpec also excels when modifying existing behavior (1→n), especially when updates span multiple specs. +- **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. +- **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. -See the full comparison in [How OpenSpec Compares](#how-openspec-compares). +See the full comparison in [How LightSpec Compares](#how-lightspec-compares). ## How It Works @@ -89,49 +82,29 @@ See the full comparison in [How OpenSpec Compares](#how-openspec-compares). ### Supported AI Tools -
-Native Slash Commands (click to expand) - -These tools have built-in OpenSpec commands. Select the OpenSpec integration when prompted. - -| Tool | Commands | -|------|----------| -| **Amazon Q Developer** | `@openspec-proposal`, `@openspec-apply`, `@openspec-archive` (`.amazonq/prompts/`) | -| **Antigravity** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.agent/workflows/`) | -| **Auggie (Augment CLI)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.augment/commands/`) | -| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` | -| **Cline** | Workflows in `.clinerules/workflows/` directory (`.clinerules/workflows/openspec-*.md`) | -| **CodeBuddy Code (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.codebuddy/commands/`) — see [docs](https://www.codebuddy.ai/cli) | -| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (global: `~/.codex/prompts`, auto-installed) | -| **Continue** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.continue/prompts/`) | -| **CoStrict** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.cospec/openspec/commands/`) — see [docs](https://costrict.ai)| -| **Crush** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.crush/commands/openspec/`) | -| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | -| **Factory Droid** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.factory/commands/`) | -| **Gemini CLI** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.gemini/commands/openspec/`) | -| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.github/prompts/`) | -| **iFlow (iflow-cli)** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.iflow/commands/`) | -| **Kilo Code** | `/openspec-proposal.md`, `/openspec-apply.md`, `/openspec-archive.md` (`.kilocode/workflows/`) | -| **OpenCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` | -| **Qoder (CLI)** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` (`.qoder/commands/openspec/`) — see [docs](https://qoder.com/cli) | -| **Qwen Code** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.qwen/commands/`) | -| **RooCode** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.roo/commands/`) | -| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (`.windsurf/workflows/`) | - -Kilo Code discovers team workflows automatically. Save the generated files under `.kilocode/workflows/` and trigger them from the command palette with `/openspec-proposal.md`, `/openspec-apply.md`, or `/openspec-archive.md`. - -
- -
-AGENTS.md Compatible (click to expand) - -These tools automatically read workflow instructions from `openspec/AGENTS.md`. Ask them to follow the OpenSpec workflow if they need a reminder. Learn more about the [AGENTS.md convention](https://agents.md/). - -| Tools | -|-------| -| Amp • Jules • Others | - -
+- Amazon Q Developer +- Antigravity +- Auggie (Augment CLI) +- Claude Code +- Cline +- Codex +- CodeBuddy Code (CLI) +- Continue (VS Code / JetBrains / CLI) +- CoStrict +- Crush +- Cursor +- Factory Droid +- Gemini CLI +- GitHub Copilot +- iFlow +- Kilo Code +- Mistral Vibe +- OpenCode +- Qoder (CLI) +- Qwen Code +- RooCode +- Windsurf +- Any AGENTS.md-compatible assistant (via Universal `AGENTS.md`) ### Install & Initialize @@ -143,24 +116,24 @@ These tools automatically read workflow instructions from `openspec/AGENTS.md`. **Option A: Using npm** ```bash -npm install -g @fission-ai/openspec@latest +npm install -g lightspec@latest ``` Verify installation: ```bash -openspec --version +lightspec --version ``` **Option B: Using Nix (NixOS and Nix package manager)** -Run OpenSpec directly without installation: +Run LightSpec directly without installation: ```bash -nix run github:Fission-AI/OpenSpec -- init +nix run github:augmenter-dev/lightspec -- init ``` Or install to your profile: ```bash -nix profile install github:Fission-AI/OpenSpec +nix profile install github:augmenter-dev/lightspec ``` Or add to your development environment in `flake.nix`: @@ -168,12 +141,12 @@ Or add to your development environment in `flake.nix`: { inputs = { nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; - openspec.url = "github:Fission-AI/OpenSpec"; + lightspec.url = "github:augmenter-dev/lightspec"; }; - outputs = { nixpkgs, openspec, ... }: { + outputs = { nixpkgs, lightspec, ... }: { devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell { - buildInputs = [ openspec.packages.x86_64-linux.default ]; + buildInputs = [ lightspec.packages.x86_64-linux.default ]; }; }; } @@ -181,10 +154,10 @@ Or add to your development environment in `flake.nix`: Verify installation: ```bash -openspec --version +lightspec --version ``` -#### Step 2: Initialize OpenSpec in your project +#### Step 2: Initialize LightSpec in your project Navigate to your project directory: ```bash @@ -193,53 +166,53 @@ cd my-project Run the initialization: ```bash -openspec init +lightspec init ``` **What happens during initialization:** - 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 -- OpenSpec automatically configures slash commands for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root -- A new `openspec/` directory structure is created in your project +- LightSpec automatically configures skills for the tools you choose and always writes a managed `AGENTS.md` hand-off at the project root +- A new `lightspec/` directory structure is created in your project **After setup:** -- Primary AI tools can trigger `/openspec` workflows without additional configuration -- Run `openspec list` to verify the setup and view any active changes -- If your coding assistant doesn't surface the new slash commands right away, restart it. Slash commands are loaded at startup, - so a fresh launch ensures they appear +- Primary AI tools can trigger `/lightspec` workflows without additional configuration +- Run `lightspec list` to verify the setup and view any active changes +- 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 +- 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 ### Optional: Populate Project Context -After `openspec init` completes, you'll receive a suggested prompt to help populate your project context: +After `lightspec init` completes, you'll receive a suggested command to validate and populate your project context: ```text -Populate your project context: -"Please read openspec/project.md and help me fill it out with details about my project, tech stack, and conventions" +Validate and populate your project context: +"/lightspec:context-check" ``` -Use `openspec/project.md` to define project-level conventions, standards, architectural patterns, and other guidelines that should be followed across all changes. +Use the `/lightspec:context-check` skill to validate that your agent instruction file (CLAUDE.md or AGENTS.md) contains adequate project context. The skill will check for required properties like Purpose, Tech Stack, Architecture Patterns, and more. If anything is missing, it can help you explore the codebase and populate the missing information. ### Create Your First Change -Here's a real example showing the complete OpenSpec workflow. This works with any AI tool. Those with native slash commands will recognize the shortcuts automatically. +Here's a real example showing the complete LightSpec workflow. This works with any AI tool. #### 1. Draft the Proposal Start by asking your AI to create a change proposal: ```text -You: Create an OpenSpec change proposal for adding profile search filters by role and team - (Shortcut for tools with slash commands: /openspec:proposal Add profile search filters) +You: Create an LightSpec change proposal for adding profile search filters by role and team + (Shortcut for tools with slash commands: /lightspec:proposal Add profile search filters) -AI: I'll create an OpenSpec change proposal for profile filters. - *Scaffolds openspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.* +AI: I'll create an LightSpec change proposal for profile filters. + *Scaffolds lightspec/changes/add-profile-filters/ with proposal.md, tasks.md, spec deltas.* ``` #### 2. Verify & Review Check that the change was created correctly and review the proposal: ```bash -$ openspec list # Confirm the change folder exists -$ openspec validate add-profile-filters # Validate spec formatting -$ openspec show add-profile-filters # Review proposal, tasks, and spec delta +$ lightspec list # Confirm the change folder exists +$ lightspec validate add-profile-filters # Validate spec formatting +$ lightspec show add-profile-filters # Review proposal, tasks, and spec delta ``` #### 3. Refine the Specs @@ -249,7 +222,7 @@ Iterate on the specifications until they match your needs: You: Can you add acceptance criteria for the role and team filters? AI: I'll update the spec delta with scenarios for role and team filters. - *Edits openspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.* + *Edits lightspec/changes/add-profile-filters/specs/profile/spec.md and tasks.md.* ``` #### 4. Implement the Change @@ -257,10 +230,10 @@ Once specs look good, start implementation: ```text You: The specs look good. Let's implement this change. - (Shortcut for tools with slash commands: /openspec:apply add-profile-filters) + (Shortcut for tools with slash commands: /lightspec:apply add-profile-filters) AI: I'll work through the tasks in the add-profile-filters change. - *Implements tasks from openspec/changes/add-profile-filters/tasks.md* + *Implements tasks from lightspec/changes/add-profile-filters/tasks.md* *Marks tasks complete: Task 1.1 ✓, Task 1.2 ✓, Task 2.1 ✓...* ``` @@ -271,36 +244,34 @@ After implementation is complete, archive the change: AI: All tasks are complete. The implementation is ready. You: Please archive the change - (Shortcut for tools with slash commands: /openspec:archive add-profile-filters) + (Shortcut for tools with slash commands: /lightspec:archive add-profile-filters) AI: I'll archive the add-profile-filters change. - *Runs: openspec archive add-profile-filters --yes* + *Runs: lightspec archive add-profile-filters --yes* ✓ Change archived successfully. Specs updated. Ready for the next feature! ``` Or run the command yourself in terminal: ```bash -$ openspec archive add-profile-filters --yes # Archive the completed change without prompts +$ lightspec archive add-profile-filters --yes # Archive the completed change without prompts ``` -**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 OpenSpec proposal", "apply the OpenSpec change", or "archive the change". - ## Command Reference ```bash -openspec list # View active change folders -openspec view # Interactive dashboard of specs and changes -openspec show # Display change details (proposal, tasks, spec updates) -openspec validate # Check spec formatting and structure -openspec archive [--yes|-y] # Move a completed change into archive/ (non-interactive with --yes) +lightspec list # View active change folders +lightspec view # Interactive dashboard of specs and changes +lightspec show # Display change details (proposal, tasks, spec updates) +lightspec validate # Check spec formatting and structure +lightspec archive [--yes|-y] # Move a completed change into archive/ (non-interactive with --yes) ``` -## Example: How AI Creates OpenSpec Files +## Example: How AI Creates LightSpec Files When you ask your AI assistant to "add two-factor authentication", it creates: ``` -openspec/ +lightspec/ ├── specs/ │ └── auth/ │ └── spec.md # Current auth spec (if exists) @@ -314,7 +285,7 @@ openspec/ └── spec.md # Delta showing additions ``` -### AI-Generated Spec (created in `openspec/specs/auth/spec.md`): +### AI-Generated Spec (created in `lightspec/specs/auth/spec.md`): ```markdown # Auth Specification @@ -331,7 +302,7 @@ The system SHALL issue a JWT on successful login. - THEN a JWT is returned ``` -### AI-Generated Change Delta (created in `openspec/changes/add-2fa/specs/auth/spec.md`): +### AI-Generated Change Delta (created in `lightspec/changes/add-2fa/specs/auth/spec.md`): ```markdown # Delta for Auth @@ -345,7 +316,7 @@ The system MUST require a second factor during login. - THEN an OTP challenge is required ``` -### AI-Generated Tasks (created in `openspec/changes/add-2fa/tasks.md`): +### AI-Generated Tasks (created in `lightspec/changes/add-2fa/tasks.md`): ```markdown ## 1. Database Setup @@ -364,7 +335,7 @@ The system MUST require a second factor during login. **Important:** You don't create these files manually. Your AI assistant generates them based on your requirements and the existing codebase. -## Understanding OpenSpec Files +## Understanding LightSpec Files ### Delta Format @@ -379,81 +350,37 @@ Deltas are "patches" that show how specs change: - Every requirement needs at least one `#### Scenario:` block - Use SHALL/MUST in requirement text -## How OpenSpec Compares +## How LightSpec Compares + +### vs. OpenSpec +OpenSpec has evolved into a more mature yet complex tool with a rich feature set. LightSpec focuses on simplicity and ease of adoption, especially for teams new to spec-driven development. LightSpec's minimalist approach has the additional benefit of reducing the number of skills and commands needed, and reducing the risk of involuntary skill activation from AI assistants. ### vs. spec-kit -OpenSpec’s two-folder model (`openspec/specs/` for the current truth, `openspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features. +LightSpec’s two-folder model (`lightspec/specs/` for the current truth, `lightspec/changes/` for proposed updates) keeps state and diffs separate. This scales when you modify existing features or touch multiple specs. spec-kit is strong for greenfield/0→1 but provides less structure for cross-spec updates and evolving features. ### vs. Kiro.dev -OpenSpec groups every change for a feature in one folder (`openspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder. +LightSpec groups every change for a feature in one folder (`lightspec/changes/feature-name/`), making it easy to track related specs, tasks, and designs together. Kiro spreads updates across multiple spec folders, which can make feature tracking harder. ### vs. No Specs -Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. OpenSpec brings predictability by agreeing on the desired behavior before any code is written. +Without specs, AI coding assistants generate code from vague prompts, often missing requirements or adding unwanted features. LightSpec brings predictability by agreeing on the desired behavior before any code is written. ## Team Adoption -1. **Initialize OpenSpec** – Run `openspec init` in your repo. +1. **Initialize LightSpec** – Run `lightspec init` in your repo. 2. **Start with new features** – Ask your AI to capture upcoming work as change proposals. 3. **Grow incrementally** – Each change archives into living specs that document your system. 4. **Stay flexible** – Different teammates can use Claude Code, CodeBuddy, Cursor, or any AGENTS.md-compatible tool while sharing the same specs. -Run `openspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings. +Run `lightspec update` whenever someone switches tools so your agents pick up the latest instructions and slash-command bindings. -## Updating OpenSpec +## Updating LightSpec 1. **Upgrade the package** ```bash - npm install -g @fission-ai/openspec@latest + npm install -g lightspec@latest ``` 2. **Refresh agent instructions** - - Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active. - -## Experimental Features - -
-🧪 OPSX: Fluid, Iterative Workflow (Claude Code only) - -**Why this exists:** -- Standard workflow is locked down — you can't tweak instructions or customize -- When AI output is bad, you can't improve the prompts yourself -- Same workflow for everyone, no way to match how your team works - -**What's different:** -- **Hackable** — edit templates and schemas yourself, test immediately, no rebuild -- **Granular** — each artifact has its own instructions, test and tweak individually -- **Customizable** — define your own workflows, artifacts, and dependencies -- **Fluid** — no phase gates, update any artifact anytime - -``` -You can always go back: - - proposal ──→ specs ──→ design ──→ tasks ──→ implement - ▲ ▲ ▲ │ - └───────────┴──────────┴────────────────────┘ -``` - -| Command | What it does | -|---------|--------------| -| `/opsx:new` | Start a new change | -| `/opsx:continue` | Create the next artifact (based on what's ready) | -| `/opsx:ff` | Fast-forward (all planning artifacts at once) | -| `/opsx:apply` | Implement tasks, updating artifacts as needed | -| `/opsx:archive` | Archive when done | - -**Setup:** `openspec artifact-experimental-setup` - -[Full documentation →](docs/experimental-workflow.md) - -
- -
-Telemetry – OpenSpec collects anonymous usage stats (opt-out: OPENSPEC_TELEMETRY=0) - -We collect only command names and version to understand usage patterns. No arguments, paths, content, or PII. Automatically disabled in CI. - -**Opt-out:** `export OPENSPEC_TELEMETRY=0` or `export DO_NOT_TRACK=1` - -
+ - Run `lightspec update` inside each project to regenerate AI guidance and ensure the latest skills are active. ## Contributing @@ -470,6 +397,15 @@ See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and adviso +## Agent Skills + +LightSpec includes 3 Claude Code skills for the core development workflow: +- `lightspec-proposal` - Create a new change +- `lightspec-apply` - Get apply instructions for implementation +- `lightspec-archive` - Archive a completed change + +See [README_SKILLS.md](README_SKILLS.md) for details. + ## License MIT diff --git a/assets/augmenter-lightspec.svg b/assets/augmenter-lightspec.svg new file mode 100644 index 000000000..8a0dabde9 --- /dev/null +++ b/assets/augmenter-lightspec.svg @@ -0,0 +1,105 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/assets/openspec_pixel_dark.svg b/assets/openspec_pixel_dark.svg deleted file mode 100644 index 799c2761f..000000000 --- a/assets/openspec_pixel_dark.svg +++ /dev/null @@ -1,89 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/assets/openspec_pixel_light.svg b/assets/openspec_pixel_light.svg deleted file mode 100644 index 3b89a5ffc..000000000 --- a/assets/openspec_pixel_light.svg +++ /dev/null @@ -1,89 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/bin/openspec.js b/bin/lightspec.js similarity index 100% rename from bin/openspec.js rename to bin/lightspec.js diff --git a/build.js b/build.js index fc9aecf94..641b02dba 100644 --- a/build.js +++ b/build.js @@ -11,7 +11,7 @@ const runTsc = (args = []) => { execFileSync(process.execPath, [tscPath, ...args], { stdio: 'inherit' }); }; -console.log('🔨 Building OpenSpec...\n'); +console.log('🔨 Building LightSpec...\n'); // Clean dist directory if (existsSync('dist')) { diff --git a/docs/artifact_poc.md b/docs/artifact_poc.md deleted file mode 100644 index 01dd00985..000000000 --- a/docs/artifact_poc.md +++ /dev/null @@ -1,597 +0,0 @@ -# POC-OpenSpec-Core Analysis - ---- - -## Design Decisions & Terminology - -### Philosophy: Not a Workflow System - -This system is **not** a workflow engine. It's an **artifact tracker with dependency awareness**. - -| What it's NOT | What it IS | -|---------------|------------| -| Linear step-by-step progression | Exploratory, iterative planning | -| Bureaucratic checkpoints | Enablers that unlock possibilities | -| "You must complete step 1 first" | "Here's what you could create now" | -| Form-filling | Fluid document creation | - -**Key insight:** Dependencies are *enablers*, not *gates*. You can't meaningfully write a design document if there's no proposal to design from - that's not bureaucracy, it's logic. - -### Terminology - -| Term | Definition | Example | -|------|------------|---------| -| **Change** | A unit of work being planned (feature, refactor, migration) | `openspec/changes/add-auth/` | -| **Schema** | An artifact graph definition (what artifacts exist, their dependencies) | `spec-driven.yaml` | -| **Artifact** | A node in the graph (a document to create) | `proposal`, `design`, `specs` | -| **Template** | Instructions/guidance for creating an artifact | `templates/proposal.md` | - -### Hierarchy - -``` -Schema (defines) ──→ Artifacts (guided by) ──→ Templates -``` - -- **Schema** = the artifact graph (what exists, dependencies) -- **Artifact** = a document to produce -- **Template** = instructions for creating that artifact - -### Schema Variations - -Schemas can vary across multiple dimensions: - -| Dimension | Examples | -|-----------|----------| -| Philosophy | `spec-driven`, `tdd`, `prototype-first` | -| Version | `v1`, `v2`, `v3` | -| Language | `en`, `zh`, `es` | -| Custom | `team-alpha`, `experimental` | - -### Schema Resolution (XDG Standard) - -Schemas follow the XDG Base Directory Specification with a 2-level resolution: - -``` -1. ${XDG_DATA_HOME}/openspec/schemas//schema.yaml # Global user override -2. /schemas//schema.yaml # Built-in defaults -``` - -**Platform-specific paths:** -- Unix/macOS: `~/.local/share/openspec/schemas/` -- Windows: `%LOCALAPPDATA%/openspec/schemas/` -- All platforms: `$XDG_DATA_HOME/openspec/schemas/` (when set) - -**Why XDG?** -- Schemas are workflow definitions (data), not user preferences (config) -- Built-ins baked into package, never auto-copied -- Users customize by creating files in global data dir -- Consistent with modern CLI tooling standards - -### Template Inheritance (2 Levels Max) - -Templates are co-located with schemas in a `templates/` subdirectory: - -``` -1. ${XDG_DATA_HOME}/openspec/schemas//templates/.md # User override -2. /schemas//templates/.md # Built-in -``` - -**Rules:** -- User overrides take precedence over package built-ins -- A CLI command shows resolved paths (no guessing) -- No inheritance between schemas (copy if you need to diverge) -- Templates are always co-located with their schema - -**Why this matters:** -- Avoids "where does this come from?" debugging -- No implicit magic that works until it doesn't -- Schema + templates form a cohesive unit - ---- - -## Executive Summary - -This is an **artifact tracker with dependency awareness** that guides iterative development through a structured artifact pipeline. The core innovation is using the **filesystem as a database** - artifact completion is detected by file existence, making the system stateless and version-control friendly. - -The system answers: -- "What artifacts exist for this change?" -- "What could I create next?" (not "what must I create") -- "What's blocking X?" (informational, not prescriptive) - ---- - -## Core Components - -### 1. ArtifactGraph (Slice 1 - COMPLETE) - -The dependency graph engine with XDG-compliant schema resolution. - -| Responsibility | Approach | -|----------------|----------| -| Model artifacts as a DAG | Artifact with `requires: string[]` | -| Track completion state | `Set` for completed artifacts | -| Calculate build order | Kahn's algorithm (topological sort) | -| Find ready artifacts | Check if all dependencies are in `completed` set | -| Resolve schemas | XDG global → package built-ins | - -**Key Data Structures (Zod-validated):** - -```typescript -// Zod schemas define types + validation -const ArtifactSchema = z.object({ - id: z.string().min(1), - generates: z.string().min(1), // e.g., "proposal.md" or "specs/*.md" - description: z.string(), - template: z.string(), // path to template file - requires: z.array(z.string()).default([]), -}); - -const SchemaYamlSchema = z.object({ - name: z.string().min(1), - version: z.number().int().positive(), - description: z.string().optional(), - artifacts: z.array(ArtifactSchema).min(1), -}); - -// Derived types -type Artifact = z.infer; -type SchemaYaml = z.infer; -``` - -**Key Methods:** -- `resolveSchema(name)` - Load schema with XDG fallback -- `ArtifactGraph.fromSchema(schema)` - Build graph from schema -- `detectState(graph, changeDir)` - Scan filesystem for completion -- `getNextArtifacts(graph, completed)` - Find artifacts ready to create -- `getBuildOrder(graph)` - Topological sort of all artifacts -- `getBlocked(graph, completed)` - Artifacts with unmet dependencies - ---- - -### 2. Change Utilities (Slice 2) - -Simple utility functions for programmatic change creation. No class, no abstraction layer. - -| Responsibility | Approach | -|----------------|----------| -| Create changes | Create dirs under `openspec/changes//` with README | -| Name validation | Enforce kebab-case naming | - -**Key Paths:** - -``` -openspec/changes// → Change instances with artifacts (project-level) -``` - -**Key Functions** (`src/utils/change-utils.ts`): -- `createChange(projectRoot, name, description?)` - Create new change directory + README -- `validateChangeName(name)` - Validate kebab-case naming, returns `{ valid, error? }` - -**Note:** Existing CLI commands (`ListCommand`, `ChangeCommand`) already handle listing, path resolution, and existence checks. No need to extract that logic - it works fine as-is. - ---- - -### 3. InstructionLoader (Slice 3) - -Template resolution and instruction enrichment. - -| Responsibility | Approach | -|----------------|----------| -| Resolve templates | XDG 2-level fallback (schema-specific → shared → built-in) | -| Build dynamic context | Gather dependency status, change info | -| Enrich templates | Inject context into base templates | -| Generate status reports | Formatted markdown with progress | - -**Key Class - ChangeState:** - -``` -ChangeState { - changeName: string - changeDir: string - graph: ArtifactGraph - completed: Set - - // Methods - getNextSteps(): string[] - getStatus(artifactId): ArtifactStatus - isComplete(): boolean -} -``` - -**Key Functions:** -- `getTemplatePath(artifactId, schemaName?)` - Resolve with 2-level fallback -- `getEnrichedInstructions(artifactId, projectRoot, changeName?)` - Main entry point -- `getChangeStatus(projectRoot, changeName?)` - Formatted status report - ---- - -### 4. CLI (Slice 4) - -User interface layer. **All commands are deterministic** - require explicit `--change` parameter. - -| Command | Function | Status | -|---------|----------|--------| -| `status --change ` | Show change progress (artifact graph) | **NEW** | -| `next --change ` | Show artifacts ready to create | **NEW** | -| `instructions --change ` | Get enriched instructions for artifact | **NEW** | -| `list` | List all changes | EXISTS (`openspec change list`) | -| `new ` | Create change | **NEW** (uses `createChange()`) | -| `init` | Initialize structure | EXISTS (`openspec init`) | -| `templates --change ` | Show resolved template paths | **NEW** | - -**Note:** Commands that operate on a change require `--change`. Missing parameter → error with list of available changes. Agent infers the change from conversation and passes it explicitly. - -**Existing CLI commands** (not part of this slice): -- `openspec change list` / `openspec change show ` / `openspec change validate ` -- `openspec list --changes` / `openspec list --specs` -- `openspec view` (dashboard) -- `openspec init` / `openspec archive ` - ---- - -### 5. Claude Commands - -Integration layer for Claude Code. **Operational commands only** - artifact creation via natural language. - -| Command | Purpose | -|---------|---------| -| `/status` | Show change progress | -| `/next` | Show what's ready to create | -| `/run [artifact]` | Execute a specific step (power users) | -| `/list` | List all changes | -| `/new ` | Create a new change | -| `/init` | Initialize structure | - -**Artifact creation:** Users say "create the proposal" or "write the tests" in natural language. The agent: -1. Infers change from conversation (confirms if uncertain) -2. Infers artifact from request -3. Calls CLI with explicit `--change` parameter -4. Creates artifact following instructions - -This works for ANY artifact in ANY schema - no new slash commands needed when schemas change. - -**Note:** Legacy commands (`/openspec-proposal`, `/openspec-apply`, `/openspec-archive`) exist in the main project for backward compatibility but are separate from this architecture. - ---- - -## Component Dependency Graph - -``` -┌─────────────────────────────────────────────────────────────┐ -│ PRESENTATION LAYER │ -│ ┌──────────────┐ ┌────────────────────┐ │ -│ │ CLI │ ←─shell exec───────│ Claude Commands │ │ -│ └──────┬───────┘ └────────────────────┘ │ -└─────────┼───────────────────────────────────────────────────┘ - │ imports - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ ORCHESTRATION LAYER │ -│ ┌────────────────────┐ ┌──────────────────────────┐ │ -│ │ InstructionLoader │ │ change-utils (Slice 2) │ │ -│ │ (Slice 3) │ │ createChange() │ │ -│ └─────────┬──────────┘ │ validateChangeName() │ │ -│ │ └──────────────────────────┘ │ -└────────────┼────────────────────────────────────────────────┘ - │ uses - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ CORE LAYER │ -│ ┌──────────────────────────────────────────────────────┐ │ -│ │ ArtifactGraph (Slice 1) │ │ -│ │ │ │ -│ │ Schema Resolution (XDG) ──→ Graph ──→ State Detection│ │ -│ └──────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ - ▲ - │ reads from - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ PERSISTENCE LAYER │ -│ ┌──────────────────┐ ┌────────────────────────────────┐ │ -│ │ XDG Schemas │ │ Project Artifacts │ │ -│ │ ~/.local/share/ │ │ openspec/changes// │ │ -│ │ openspec/ │ │ - proposal.md, design.md │ │ -│ │ schemas/ │ │ - specs/*.md, tasks.md │ │ -│ └──────────────────┘ └────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` - ---- - -## Key Design Patterns - -### 1. Filesystem as Database - -No SQLite, no JSON state files. The existence of `proposal.md` means proposal is complete. - -``` -// State detection is just file existence checking -if (exists(artifactPath)) { - completed.add(artifactId) -} -``` - -### 2. Deterministic CLI, Inferring Agent - -**CLI layer:** Always deterministic - requires explicit `--change` parameter. - -``` -openspec status --change add-auth # explicit, works -openspec status # error: "No change specified" -``` - -**Agent layer:** Infers from conversation, confirms if uncertain, passes explicit `--change`. - -This separation means: -- CLI is pure, testable, no state to corrupt -- Agent handles all "smartness" -- No config.yaml tracking of "active change" - -### 3. XDG-Compliant Schema Resolution - -``` -${XDG_DATA_HOME}/openspec/schemas//schema.yaml # User override - ↓ (not found) -/schemas//schema.yaml # Built-in - ↓ (not found) -Error (schema not found) -``` - -### 4. Two-Level Template Fallback - -``` -${XDG_DATA_HOME}/openspec/schemas//templates/.md # User override - ↓ (not found) -/schemas//templates/.md # Built-in - ↓ (not found) -Error (no silent fallback to avoid confusion) -``` - -### 5. Glob Pattern Support - -`specs/*.md` allows multiple files to satisfy a single artifact: - -``` -if (artifact.generates.includes("*")) { - const parentDir = changeDir / patternParts[0] - if (exists(parentDir) && hasFiles(parentDir)) { - completed.add(artifactId) - } -} -``` - -### 6. Stateless State Detection - -Every command re-scans the filesystem. No cached state to corrupt. - ---- - -## Artifact Pipeline (Default Schema) - -The default `spec-driven` schema: - -``` -┌──────────┐ -│ proposal │ (no dependencies) -└────┬─────┘ - │ - ▼ -┌──────────┐ -│ specs │ (requires: proposal) -└────┬─────┘ - │ - ├──────────────┐ - ▼ ▼ -┌──────────┐ ┌──────────┐ -│ design │ │ │ -│ │◄──┤ proposal │ -└────┬─────┘ └──────────┘ - │ (requires: proposal, specs) - ▼ -┌──────────┐ -│ tasks │ (requires: design) -└──────────┘ -``` - -Other schemas (TDD, prototype-first) would have different graphs. - ---- - -## Implementation Order - -Structured as **vertical slices** - each slice is independently testable. - ---- - -### Slice 1: "What's Ready?" (Core Query) ✅ COMPLETE - -**Delivers:** Types + Graph + State Detection + Schema Resolution - -**Implementation:** `src/core/artifact-graph/` -- `types.ts` - Zod schemas and derived TypeScript types -- `schema.ts` - YAML parsing with Zod validation -- `graph.ts` - ArtifactGraph class with topological sort -- `state.ts` - Filesystem-based state detection -- `resolver.ts` - XDG-compliant schema resolution -- `builtin-schemas.ts` - Package-bundled default schemas - -**Key decisions made:** -- Zod for schema validation (consistent with project) -- XDG for global schema overrides -- `Set` for completion state (immutable, functional) -- `inProgress` and `failed` states deferred (require external tracking) - ---- - -### Slice 2: "Change Creation Utilities" - -**Delivers:** Utility functions for programmatic change creation - -**Scope:** -- `createChange(projectRoot, name, description?)` → creates directory + README -- `validateChangeName(name)` → kebab-case pattern enforcement - -**Not in scope (already exists in CLI commands):** -- `listChanges()` → exists in `ListCommand` and `ChangeCommand.getActiveChanges()` -- `getChangePath()` → simple `path.join()` inline -- `changeExists()` → simple `fs.access()` inline -- `isInitialized()` → simple directory check inline - -**Why simplified:** Extracting existing CLI logic into a class would require similar refactoring of `SpecCommand` for consistency. The existing code works fine (~15 lines each). Only truly new functionality is `createChange()` + name validation. - ---- - -### Slice 3: "Get Instructions" (Enrichment) - -**Delivers:** Template resolution + context injection - -**Testable behaviors:** -- Template fallback: schema-specific → shared → built-in → error -- Context injection: completed deps show ✓, missing show ✗ -- Output path shown correctly based on change directory - ---- - -### Slice 4: "CLI + Integration" - -**Delivers:** New artifact graph commands (builds on existing CLI) - -**New commands:** -- `status --change ` - Show artifact completion state -- `next --change ` - Show ready-to-create artifacts -- `instructions --change ` - Get enriched template -- `templates --change ` - Show resolved paths -- `new ` - Create change (wrapper for `createChange()`) - -**Already exists (not in scope):** -- `openspec change list/show/validate` - change management -- `openspec list --changes/--specs` - listing -- `openspec view` - dashboard -- `openspec init` - initialization - -**Testable behaviors:** -- Each new command produces expected output -- Commands compose correctly (status → next → instructions flow) -- Error handling for missing changes, invalid artifacts, etc. - ---- - -## Directory Structure - -``` -# Global (XDG paths - user overrides) -~/.local/share/openspec/ # Unix/macOS ($XDG_DATA_HOME/openspec/) -%LOCALAPPDATA%/openspec/ # Windows -└── schemas/ # Schema overrides - └── custom-workflow/ # User-defined schema directory - ├── schema.yaml # Schema definition - └── templates/ # Co-located templates - └── proposal.md - -# Package (built-in defaults) -/ -└── schemas/ # Built-in schema definitions - ├── spec-driven/ # Default: proposal → specs → design → tasks - │ ├── schema.yaml - │ └── templates/ - │ ├── proposal.md - │ ├── design.md - │ ├── spec.md - │ └── tasks.md - └── tdd/ # TDD: tests → implementation → docs - ├── schema.yaml - └── templates/ - ├── test.md - ├── implementation.md - ├── spec.md - └── docs.md - -# Project (change instances) -openspec/ -└── changes/ # Change instances - ├── add-auth/ - │ ├── README.md # Auto-generated on creation - │ ├── proposal.md # Created artifacts - │ ├── design.md - │ └── specs/ - │ └── *.md - ├── refactor-db/ - │ └── ... - └── archive/ # Completed changes - └── 2025-01-01-add-auth/ - -.claude/ -├── settings.local.json # Permissions -└── commands/ # Slash commands - └── *.md -``` - ---- - -## Schema YAML Format - -```yaml -# Built-in: /schemas/spec-driven/schema.yaml -# Or user override: ~/.local/share/openspec/schemas/spec-driven/schema.yaml -name: spec-driven -version: 1 -description: Specification-driven development - -artifacts: - - id: proposal - generates: "proposal.md" - description: "Create project proposal document" - template: "proposal.md" # resolves from co-located templates/ directory - requires: [] - - - id: specs - generates: "specs/*.md" # glob pattern - description: "Create technical specification documents" - template: "specs.md" - requires: - - proposal - - - id: design - generates: "design.md" - description: "Create design document" - template: "design.md" - requires: - - proposal - - specs - - - id: tasks - generates: "tasks.md" - description: "Create tasks breakdown document" - template: "tasks.md" - requires: - - design -``` - ---- - -## Summary - -| Layer | Component | Responsibility | Status | -|-------|-----------|----------------|--------| -| Core | ArtifactGraph | Pure dependency logic + XDG schema resolution | ✅ Slice 1 COMPLETE | -| Utils | change-utils | Change creation + name validation only | Slice 2 (new functionality only) | -| Core | InstructionLoader | Template resolution + enrichment | Slice 3 (all new) | -| Presentation | CLI | New artifact graph commands | Slice 4 (new commands only) | -| Integration | Claude Commands | AI assistant glue | Slice 4 | - -**What already exists (not in this proposal):** -- `getActiveChangeIds()` in `src/utils/item-discovery.ts` - list changes -- `ChangeCommand.list/show/validate()` in `src/commands/change.ts` -- `ListCommand.execute()` in `src/core/list.ts` -- `ViewCommand.execute()` in `src/core/view.ts` - dashboard -- `src/core/init.ts` - initialization -- `src/core/archive.ts` - archiving - -**Key Principles:** -- **Filesystem IS the database** - stateless, version-control friendly -- **Dependencies are enablers** - show what's possible, don't force order -- **Deterministic CLI, inferring agent** - CLI requires explicit `--change`, agent infers from context -- **XDG-compliant paths** - schemas and templates use standard user data directories -- **2-level inheritance** - user override → package built-in (no deeper) -- **Schemas are versioned** - support variations by philosophy, version, language diff --git a/docs/experimental-release-plan.md b/docs/experimental-release-plan.md deleted file mode 100644 index 387b48cff..000000000 --- a/docs/experimental-release-plan.md +++ /dev/null @@ -1,926 +0,0 @@ -# OpenSpec Experimental Release Plan - -This document outlines the plan to release the experimental artifact workflow system for user testing. - -## Overview - -The goal is to allow users to test the new artifact-driven workflow system alongside the existing OpenSpec commands. This experimental system (`opsx`) provides a more granular, step-by-step approach to creating change artifacts. - -## Three Workflow Modes - -### 1. Old Workflow (Current Production) -- **Commands**: `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` -- **Behavior**: Hardcoded slash commands that generate all artifacts in one command -- **Status**: Production, unchanged - -### 2. New Artifact System - Batch Mode (Future) -- **Commands**: Refactored `/openspec:proposal` using schemas -- **Behavior**: Schema-driven but generates all artifacts at once (like legacy) -- **Status**: Not in scope for this experimental release -- **Note**: This is a future refactor to unify the old system with schemas - -### 3. New Artifact System - Granular Mode (Experimental) -- **Commands**: `/opsx:new`, `/opsx:continue` -- **Behavior**: One artifact at a time, dependency-driven, iterative -- **Status**: Target for this experimental release - ---- - -## Work Items - -### 1. Rename AWF to OPSX - -**Current State:** -- Commands: `/awf:start`, `/awf:continue` -- Files: `.claude/commands/awf/start.md`, `.claude/commands/awf/continue.md` - -**Target State:** -- Commands: `/opsx:new`, `/opsx:continue` -- Files: `.claude/commands/opsx/new.md`, `.claude/commands/opsx/continue.md` - -**Tasks:** -- [x] Create `.claude/commands/opsx/` directory -- [x] Rename `start.md` → `new.md` and update content -- [x] Copy `continue.md` with updated references -- [x] Update all references from "awf" to "opsx" in command content -- [x] Update frontmatter (name, description) to use "opsx" naming -- [x] Remove `.claude/commands/awf/` directory - -**CLI Commands:** -The underlying CLI commands (`openspec status`, `openspec instructions`, etc.) remain unchanged. Only the slash command names change. - ---- - -### 2. Remove WF Skill Files - -**Current State:** -- `.claude/commands/wf/start.md` - References non-existent `openspec wf` commands -- `.claude/commands/wf/continue.md` - References non-existent `openspec wf` commands - -**Target State:** -- Directory and files removed - -**Tasks:** -- [x] Delete `.claude/commands/wf/start.md` -- [x] Delete `.claude/commands/wf/continue.md` -- [x] Delete `.claude/commands/wf/` directory - ---- - -### 3. Add Agent Skills for Experimental Workflow - -**Purpose:** -Generate experimental workflow skills using the [Agent Skills](https://agentskills.io/specification) open standard. - -**Why Skills Instead of Slash Commands:** -- **Cross-editor compatibility**: Skills work in Claude Code, Cursor, Windsurf, and other compatible editors automatically -- **Simpler implementation**: Single directory (`.claude/skills/`) instead of 18+ editor-specific configurators -- **Standard format**: Open standard with simple YAML frontmatter + markdown -- **User invocation**: Users explicitly invoke skills when they want to use them - -**Behavior:** -1. Create `.claude/skills/` directory if it doesn't exist -2. Generate two skills using the Agent Skills specification: - - `openspec-new-change/SKILL.md` - Start a new change with artifact workflow - - `openspec-continue-change/SKILL.md` - Continue working on a change (create next artifact) -3. Skills are added **alongside** existing `/openspec:*` commands (not replacing) - -**Supported Editors:** -- Claude Code (native support) -- Cursor (native support via Settings → Rules → Import Settings) -- Windsurf (imports `.claude` configs) -- Cline, Codex, and other Agent Skills-compatible editors - -**Tasks:** -- [x] Create skill template content for `openspec-new-change` (based on current opsx:new) -- [x] Create skill template content for `openspec-continue-change` (based on current opsx:continue) -- [x] Add temporary `artifact-experimental-setup` command to CLI -- [x] Implement skill file generation (YAML frontmatter + markdown body) -- [x] Add success message with usage instructions - -**Note:** The `artifact-experimental-setup` command is temporary and will be merged into `openspec init` once the experimental workflow is promoted to stable. - -**Skill Format:** -Each skill is a directory with a `SKILL.md` file: -``` -.claude/skills/ -├── openspec-new-change/ -│ └── SKILL.md # name, description, instructions -├── openspec-continue-change/ -│ └── SKILL.md # name, description, instructions -└── openspec-apply-change/ - └── SKILL.md # name, description, instructions -``` - -**CLI Interface:** -```bash -openspec artifact-experimental-setup - -# Output: -# 🧪 Experimental Artifact Workflow Skills Created -# -# ✓ .claude/skills/openspec-new-change/SKILL.md -# ✓ .claude/skills/openspec-continue-change/SKILL.md -# ✓ .claude/skills/openspec-apply-change/SKILL.md -# -# 📖 Usage: -# -# Skills work automatically in compatible editors: -# • Claude Code - Auto-detected, ready to use -# • Cursor - Enable in Settings → Rules → Import Settings -# • Windsurf - Auto-imports from .claude directory -# -# Ask Claude naturally: -# • "I want to start a new OpenSpec change to add " -# • "Continue working on this change" -# -# Claude will automatically use the appropriate skill. -# -# 💡 This is an experimental feature. -# Feedback welcome at: https://github.com/Fission-AI/OpenSpec/issues -``` - -**Implementation Notes:** -- Simple file writing: Create directories and write templated `SKILL.md` files (no complex logic) -- Use existing `FileSystemUtils.writeFile()` pattern like slash command configurators -- Template structure: YAML frontmatter + markdown body -- Keep existing `/opsx:*` slash commands for now (manual cleanup later) -- Skills use invocation model (user explicitly asks Claude to use them) -- Skill `description` field guides when Claude suggests using the skill -- Each `SKILL.md` has required fields: `name` (matches directory) and `description` - ---- - -### 4. Update `/opsx:new` Command Content - -**Current Behavior (awf:start):** -1. Ask user what they want to build (if no input) -2. Create change directory -3. Show artifact status -4. Show what's ready -5. Get instructions for proposal -6. STOP and wait - -**New Behavior (opsx:new):** -Same flow but with updated naming: -- References to "awf" → "opsx" -- References to `/awf:continue` → `/opsx:continue` -- Update frontmatter name/description - -**Tasks:** -- [x] Update all "awf" references to "opsx" -- [x] Update command references in prompt text -- [x] Verify CLI commands still work (they use `openspec`, not `awf`) - ---- - -### 5. Update `/opsx:continue` Command Content - -**Current Behavior (awf:continue):** -1. Prompt for change selection (if not provided) -2. Check current status -3. Create ONE artifact based on what's ready -4. Show progress and what's unlocked -5. STOP - -**New Behavior (opsx:continue):** -Same flow with updated naming. - -**Tasks:** -- [x] Update all "awf" references to "opsx" -- [x] Update command references in prompt text - ---- - -### 6. End-to-End Testing - -**Objective:** -Run through a complete workflow with Claude using the new skills to create a real feature, validating the entire flow works. - -**Test Scenario:** -Use a real OpenSpec feature as the test case (dog-fooding). - -**Test Flow:** -1. Run `openspec artifact-experimental-setup` to create skills -2. Verify `.claude/skills/openspec-new-change/SKILL.md` created -3. Verify `.claude/skills/openspec-continue-change/SKILL.md` created -4. Verify `.claude/skills/openspec-apply-change/SKILL.md` created -5. Ask Claude: "I want to start a new OpenSpec change to add feature X" -6. Verify Claude invokes the `openspec-new-change` skill -7. Verify change directory created at `openspec/changes/add-feature-x/` -8. Verify proposal template shown -9. Ask Claude: "Continue working on this change" -10. Verify Claude invokes the `openspec-continue-change` skill -11. Verify `proposal.md` created with content -12. Ask Claude: "Continue" (create specs) -13. Verify `specs/*.md` created -14. Ask Claude: "Continue" (create design) -15. Verify `design.md` created -16. Ask Claude: "Continue" (create tasks) -17. Verify `tasks.md` created -18. Verify status shows 4/4 complete -19. Implement the feature based on tasks -20. Run `/openspec:archive` to archive the change - -**Validation Checklist:** -- [ ] `openspec artifact-experimental-setup` creates correct directory structure -- [ ] Skills are auto-detected in Claude Code -- [ ] Skill descriptions trigger appropriate invocations -- [ ] Skills create change directory and show proposal template -- [ ] Skills correctly identify ready artifacts -- [ ] Skills create artifacts with meaningful content -- [ ] Dependency detection works (specs requires proposal, etc.) -- [ ] Progress tracking is accurate -- [ ] Template content is useful and well-structured -- [ ] Error handling works (invalid names, missing changes, etc.) -- [ ] Works with different schemas (spec-driven, tdd) -- [ ] Test in Cursor (Settings → Rules → Import Settings) - -**Document Results:** -- Create test log documenting what worked and what didn't -- Note any friction points or confusing UX -- Identify bugs or improvements needed before user release - ---- - -### 7. Documentation for Users - -**Create user-facing documentation explaining:** - -1. **What is the experimental workflow?** - - A new way to create OpenSpec changes step-by-step using Agent Skills - - One artifact at a time with dependency tracking - - More interactive and iterative than the batch approach - - Works across Claude Code, Cursor, Windsurf, and other compatible editors - -2. **How to set up experimental workflow** - ```bash - openspec artifact-experimental-setup - ``` - - Note: This is a temporary command that will be integrated into `openspec init` once promoted to stable. - -3. **Available skills** - - `openspec-new-change` - Start a new change with artifact workflow - - `openspec-continue-change` - Continue working (create next artifact) - -4. **How to use** - - **Claude Code**: Skills are auto-detected, just ask Claude naturally - - "I want to start a new OpenSpec change to add X" - - "Continue working on this change" - - **Cursor**: Enable in Settings → Rules → Import Settings - - **Windsurf**: Auto-imports `.claude` directory - -5. **Example workflow** - - Step-by-step walkthrough with natural language interactions - - Show how Claude invokes skills based on user requests - -6. **Feedback mechanism** - - GitHub issue template for feedback - - What to report (bugs, UX issues, suggestions) - -**Tasks:** -- [ ] Create `docs/experimental-workflow.md` user guide -- [ ] Add GitHub issue template for experimental feedback -- [ ] Update README with mention of experimental features - ---- - -## Dependency Graph - -``` -1. Remove WF skill files - └── (no dependencies) - -2. Rename AWF to OPSX - └── (no dependencies) - -3. Add Agent Skills - └── Depends on: Rename AWF to OPSX (uses opsx content as templates) - -4. Update opsx:new content - └── Depends on: Rename AWF to OPSX - -5. Update opsx:continue content - └── Depends on: Rename AWF to OPSX - -6. E2E Testing - └── Depends on: Add Agent Skills (tests the skills workflow) - -7. User Documentation - └── Depends on: E2E Testing (need to know final behavior) -``` - ---- - -## Out of Scope - -The following are explicitly NOT part of this experimental release: - -1. **Batch mode refactor** - Making legacy `/openspec:proposal` use schemas -2. **New schemas** - Only shipping with existing `spec-driven` and `tdd` -3. **Schema customization UI** - No `openspec schema list` or similar -4. **Multiple editor support in CLI** - Skills work cross-editor automatically via `.claude/skills/` -5. **Replacing existing commands** - Skills are additive, not replacing `/openspec:*` or `/opsx:*` - ---- - -## Success Criteria - -The experimental release is ready when: - -1. `openspec-new-change`, `openspec-continue-change`, and `openspec-apply-change` skills work end-to-end -2. `openspec artifact-experimental-setup` creates skills in `.claude/skills/` -3. Skills work in Claude Code and are compatible with Cursor/Windsurf -4. At least one complete workflow has been tested manually -5. User documentation exists explaining how to generate and use skills -6. Feedback mechanism is in place -7. WF skill files are removed -8. No references to "awf" remain in user-facing content - ---- - -## Open Questions - -1. **Schema selection** - Should `opsx:new` allow selecting a schema, or always use `spec-driven`? - - Current: Always uses `spec-driven` as default - - Consider: Add `--schema tdd` option or prompt - -2. **Namespace in CLI** - Should experimental CLI commands be namespaced? - - Current: `openspec status`, `openspec instructions` (no namespace) - - Alternative: `openspec opsx status` (explicit experimental namespace) - - Recommendation: Keep current, less typing for users - -3. **Deprecation path** - If opsx becomes the default, how do we migrate? - - Not needed for experimental release - - Document that command names may change - ---- - -## Estimated Work Breakdown - -| Item | Complexity | Notes | -|------|------------|-------| -| Remove WF files | Trivial | Just delete 2 files + directory | -| Rename AWF → OPSX | Low | File renames + content updates | -| Add Agent Skills | **Low** | **Simple: 3-4 files, single output directory, standard format** | -| Update opsx:new content | Low | Text replacements | -| Update opsx:continue content | Low | Text replacements | -| E2E Testing | Medium | Manual testing, documenting results | -| User Documentation | Medium | New docs, issue template | - -**Key Improvement:** Switching to Agent Skills reduces complexity significantly: -- **Before:** 20+ files (type definitions, 18+ editor configurators, editor selection UI) -- **After:** 3-4 files (skill templates, simple CLI command) -- **Cross-editor:** Works automatically in Claude Code, Cursor, Windsurf without extra code - ---- - -## User Feedback from E2E Testing - -### What Worked Well - -1. **Clear dependency graph** ⭐ HIGH PRIORITY - KEEP - - The status command showing blocked/unblocked artifacts was intuitive: - ``` - [x] proposal - [ ] design - [-] tasks (blocked by: design, specs) - ``` - - Users always knew what they could work on next - - **Relevance**: Core UX strength to preserve - -2. **Structured instructions output** ⭐ HIGH PRIORITY - KEEP - - `openspec instructions ` gave templates, output paths, and context in one call - - Very helpful for understanding what to create - - **Relevance**: Essential for agent-driven workflow - -3. **Simple scaffolding** ✅ WORKS WELL - - `openspec new change "name"` just worked - created directory structure without fuss - - **Relevance**: Good baseline, room for improvement (see pain points) - ---- - -### Pain Points & Confusion - -1. **Redundant CLI calls** ⚠️ MEDIUM PRIORITY - - Users called both `status` AND `next` every time, but they overlap significantly - - `status` already shows what's blocked - - **Recommendation**: Consider merging or making `next` give actionable guidance beyond just listing names - - **Relevance**: Reduces friction in iterative workflow - -2. **Specs directory structure was ambiguous** 🔥 HIGH PRIORITY - FIX - - Instructions said: `Write to: .../specs/**/*.md` - - Users had to guess: `specs/spec.md`? `specs/game/spec.md`? `specs/tic-tac-toe/spec.md`? - - Users ended up doing manual `mkdir -p .../specs/tic-tac-toe` then writing `spec.md` inside - - **Recommendation**: CLI should scaffold this directory structure automatically - - **Relevance**: Critical agent UX - ambiguous paths cause workflow friction - -3. **Repetitive --change flag** ⚠️ MEDIUM PRIORITY - - Every command needed `--change "tic-tac-toe-game"` - - After 10+ calls, this felt verbose - - **Recommendation**: `openspec use "tic-tac-toe-game"` to set context, then subsequent commands assume that change - - **Relevance**: Quality of life improvement for iterative sessions - -4. **No validation feedback** 🔥 HIGH PRIORITY - ADD - - After writing each artifact, users just ran `status` hoping it would show `[x]` - - Questions raised: - - How did it know the artifact was "done"? File existence? - - What if spec format was wrong (e.g., wrong heading levels)? - - **Recommendation**: Add `openspec validate --change "name"` to check content quality - - **Relevance**: Critical for user confidence and catching errors early - -5. **Query-heavy, action-light CLI** 🔥 HIGH PRIORITY - ENHANCE - - Most commands retrieve info. The only "action" is `new change` - - Artifact creation is manual Write to guessed paths - - **Recommendation**: `openspec create proposal --change "name"` could scaffold the file with template pre-filled, then user just edits - - **Relevance**: Directly impacts agent productivity - reduce manual file writing - -6. **Instructions output was verbose** ⚠️ LOW PRIORITY - - XML-style output (``, `