add openspec CLI
This commit is contained in:
22
extensions/openspec/LICENSE
Normal file
22
extensions/openspec/LICENSE
Normal file
@@ -0,0 +1,22 @@
|
|||||||
|
MIT License
|
||||||
|
|
||||||
|
Copyright (c) 2024 OpenSpec Contributors
|
||||||
|
|
||||||
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
|
|
||||||
199
extensions/openspec/README.md
Normal file
199
extensions/openspec/README.md
Normal file
@@ -0,0 +1,199 @@
|
|||||||
|
<p align="center">
|
||||||
|
<a href="https://github.com/Fission-AI/OpenSpec">
|
||||||
|
<picture>
|
||||||
|
<source srcset="assets/openspec_bg.png">
|
||||||
|
<img src="assets/openspec_bg.png" alt="OpenSpec logo">
|
||||||
|
</picture>
|
||||||
|
</a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a href="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Fission-AI/OpenSpec/actions/workflows/ci.yml/badge.svg" /></a>
|
||||||
|
<a href="https://www.npmjs.com/package/@fission-ai/openspec"><img alt="npm version" src="https://img.shields.io/npm/v/@fission-ai/openspec?style=flat-square" /></a>
|
||||||
|
<a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" /></a>
|
||||||
|
<a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/discord/1411657095639601154?style=flat-square&logo=discord&logoColor=white&label=Discord&suffix=%20online" /></a>
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>The most loved spec framework.</strong></summary>
|
||||||
|
|
||||||
|
[](https://github.com/Fission-AI/OpenSpec/stargazers)
|
||||||
|
[](https://www.npmjs.com/package/@fission-ai/openspec)
|
||||||
|
[](https://github.com/Fission-AI/OpenSpec/graphs/contributors)
|
||||||
|
|
||||||
|
</details>
|
||||||
|
<p></p>
|
||||||
|
Our philosophy:
|
||||||
|
|
||||||
|
```text
|
||||||
|
→ fluid not rigid
|
||||||
|
→ iterative not waterfall
|
||||||
|
→ easy not complex
|
||||||
|
→ built for brownfield not just greenfield
|
||||||
|
→ scalable from personal projects to enterprises
|
||||||
|
```
|
||||||
|
|
||||||
|
> [!TIP]
|
||||||
|
> **New workflow now available!** We've rebuilt OpenSpec with a new artifact-guided workflow.
|
||||||
|
>
|
||||||
|
> Run `/opsx:propose "your idea"` to get started. → [Learn more here](docs/opsx.md)
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
Follow <a href="https://x.com/0xTab">@0xTab on X</a> for updates · Join the <a href="https://discord.gg/YctCnvvshC">OpenSpec Discord</a> for help and questions.
|
||||||
|
</p>
|
||||||
|
|
||||||
|
<!-- TODO: Add GIF demo of /opsx:propose → /opsx:archive workflow -->
|
||||||
|
|
||||||
|
## See it in action
|
||||||
|
|
||||||
|
```text
|
||||||
|
You: /opsx:propose add-dark-mode
|
||||||
|
AI: Created openspec/changes/add-dark-mode/
|
||||||
|
✓ proposal.md — why we're doing this, what's changing
|
||||||
|
✓ specs/ — requirements and scenarios
|
||||||
|
✓ design.md — technical approach
|
||||||
|
✓ tasks.md — implementation checklist
|
||||||
|
Ready for implementation!
|
||||||
|
|
||||||
|
You: /opsx:apply
|
||||||
|
AI: Implementing tasks...
|
||||||
|
✓ 1.1 Add theme context provider
|
||||||
|
✓ 1.2 Create toggle component
|
||||||
|
✓ 2.1 Add CSS variables
|
||||||
|
✓ 2.2 Wire up localStorage
|
||||||
|
All tasks complete!
|
||||||
|
|
||||||
|
You: /opsx:archive
|
||||||
|
AI: Archived to openspec/changes/archive/2025-01-23-add-dark-mode/
|
||||||
|
Specs updated. Ready for the next feature.
|
||||||
|
```
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>OpenSpec Dashboard</strong></summary>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<img src="assets/openspec_dashboard.png" alt="OpenSpec dashboard preview" width="90%">
|
||||||
|
</p>
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
## Quick Start
|
||||||
|
|
||||||
|
**Requires Node.js 20.19.0 or higher.**
|
||||||
|
|
||||||
|
Install OpenSpec globally:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install -g @fission-ai/openspec@latest
|
||||||
|
```
|
||||||
|
|
||||||
|
Then navigate to your project directory and initialize:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd your-project
|
||||||
|
openspec init
|
||||||
|
```
|
||||||
|
|
||||||
|
Now tell your AI: `/opsx:propose <what-you-want-to-build>`
|
||||||
|
|
||||||
|
If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:sync`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
|
||||||
|
|
||||||
|
> [!NOTE]
|
||||||
|
> Not sure if your tool is supported? [View the full list](docs/supported-tools.md) – we support 25+ tools and growing.
|
||||||
|
>
|
||||||
|
> Also works with pnpm, yarn, bun, and nix. [See installation options](docs/installation.md).
|
||||||
|
|
||||||
|
## Docs
|
||||||
|
|
||||||
|
→ **[Getting Started](docs/getting-started.md)**: first steps<br>
|
||||||
|
→ **[Workflows](docs/workflows.md)**: combos and patterns<br>
|
||||||
|
→ **[Commands](docs/commands.md)**: slash commands & skills<br>
|
||||||
|
→ **[CLI](docs/cli.md)**: terminal reference<br>
|
||||||
|
→ **[Supported Tools](docs/supported-tools.md)**: tool integrations & install paths<br>
|
||||||
|
→ **[Concepts](docs/concepts.md)**: how it all fits<br>
|
||||||
|
→ **[Multi-Language](docs/multi-language.md)**: multi-language support<br>
|
||||||
|
→ **[Customization](docs/customization.md)**: make it yours
|
||||||
|
|
||||||
|
|
||||||
|
## Why OpenSpec?
|
||||||
|
|
||||||
|
AI coding assistants are powerful but unpredictable when requirements live only in chat history. OpenSpec adds a lightweight spec layer so you agree on what to build before any code is written.
|
||||||
|
|
||||||
|
- **Agree before you build** — human and AI align on specs before code gets written
|
||||||
|
- **Stay organized** — each change gets its own folder with proposal, specs, design, and tasks
|
||||||
|
- **Work fluidly** — update any artifact anytime, no rigid phase gates
|
||||||
|
- **Use your tools** — works with 20+ AI assistants via slash commands
|
||||||
|
|
||||||
|
### How we compare
|
||||||
|
|
||||||
|
**vs. [Spec Kit](https://github.com/github/spec-kit)** (GitHub) — Thorough but heavyweight. Rigid phase gates, lots of Markdown, Python setup. OpenSpec is lighter and lets you iterate freely.
|
||||||
|
|
||||||
|
**vs. [Kiro](https://kiro.dev)** (AWS) — Powerful but you're locked into their IDE and limited to Claude models. OpenSpec works with the tools you already use.
|
||||||
|
|
||||||
|
**vs. nothing** — AI coding without specs means vague prompts and unpredictable results. OpenSpec brings predictability without the ceremony.
|
||||||
|
|
||||||
|
## Updating OpenSpec
|
||||||
|
|
||||||
|
**Upgrade the package**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install -g @fission-ai/openspec@latest
|
||||||
|
```
|
||||||
|
|
||||||
|
**Refresh agent instructions**
|
||||||
|
|
||||||
|
Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
openspec update
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage Notes
|
||||||
|
|
||||||
|
**Model selection**: OpenSpec works best with high-reasoning models. We recommend Opus 4.5 and GPT 5.2 for both planning and implementation.
|
||||||
|
|
||||||
|
**Context hygiene**: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
**Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
|
||||||
|
|
||||||
|
**Larger changes** — For new features, significant refactors, or architectural changes, please submit an OpenSpec change proposal first so we can align on intent and goals before implementation begins.
|
||||||
|
|
||||||
|
When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide variety of users across different coding agents, models, and use cases. Changes should work well for everyone.
|
||||||
|
|
||||||
|
**AI-generated code is welcome** — as long as it's been tested and verified. PRs containing AI-generated code should mention the coding agent and model used (e.g., "Generated with Claude Code using claude-opus-4-5-20251101").
|
||||||
|
|
||||||
|
### Development
|
||||||
|
|
||||||
|
- Install dependencies: `pnpm install`
|
||||||
|
- Build: `pnpm run build`
|
||||||
|
- Test: `pnpm test`
|
||||||
|
- Develop CLI locally: `pnpm run dev` or `pnpm run dev:cli`
|
||||||
|
- Conventional commits (one-line): `type(scope): subject`
|
||||||
|
|
||||||
|
## Other
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>Telemetry</strong></summary>
|
||||||
|
|
||||||
|
OpenSpec collects anonymous usage stats.
|
||||||
|
|
||||||
|
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`
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><strong>Maintainers & Advisors</strong></summary>
|
||||||
|
|
||||||
|
See [MAINTAINERS.md](MAINTAINERS.md) for the list of core maintainers and advisors who help guide the project.
|
||||||
|
|
||||||
|
</details>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
MIT
|
||||||
3
extensions/openspec/bin/openspec.js
Executable file
3
extensions/openspec/bin/openspec.js
Executable file
@@ -0,0 +1,3 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
|
||||||
|
import '../dist/cli/index.js';
|
||||||
5043
extensions/openspec/package-lock.json
generated
Normal file
5043
extensions/openspec/package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
81
extensions/openspec/package.json
Normal file
81
extensions/openspec/package.json
Normal file
@@ -0,0 +1,81 @@
|
|||||||
|
{
|
||||||
|
"name": "@fission-ai/openspec",
|
||||||
|
"version": "1.3.1",
|
||||||
|
"description": "AI-native system for spec-driven development",
|
||||||
|
"keywords": [
|
||||||
|
"openspec",
|
||||||
|
"specs",
|
||||||
|
"cli",
|
||||||
|
"ai",
|
||||||
|
"development"
|
||||||
|
],
|
||||||
|
"homepage": "https://github.com/Fission-AI/OpenSpec",
|
||||||
|
"repository": {
|
||||||
|
"type": "git",
|
||||||
|
"url": "https://github.com/Fission-AI/OpenSpec"
|
||||||
|
},
|
||||||
|
"license": "MIT",
|
||||||
|
"author": "OpenSpec Contributors",
|
||||||
|
"type": "module",
|
||||||
|
"publishConfig": {
|
||||||
|
"access": "public"
|
||||||
|
},
|
||||||
|
"exports": {
|
||||||
|
".": {
|
||||||
|
"types": "./dist/index.d.ts",
|
||||||
|
"default": "./dist/index.js"
|
||||||
|
}
|
||||||
|
},
|
||||||
|
"bin": {
|
||||||
|
"openspec": "./bin/openspec.js"
|
||||||
|
},
|
||||||
|
"files": [
|
||||||
|
"dist",
|
||||||
|
"bin",
|
||||||
|
"schemas",
|
||||||
|
"scripts/postinstall.js",
|
||||||
|
"!dist/**/*.test.js",
|
||||||
|
"!dist/**/__tests__",
|
||||||
|
"!dist/**/*.map"
|
||||||
|
],
|
||||||
|
"engines": {
|
||||||
|
"node": ">=20.19.0"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"@changesets/changelog-github": "^0.5.2",
|
||||||
|
"@changesets/cli": "^2.27.7",
|
||||||
|
"@types/node": "^24.2.0",
|
||||||
|
"@vitest/ui": "^3.2.4",
|
||||||
|
"eslint": "^9.39.2",
|
||||||
|
"typescript": "^5.9.3",
|
||||||
|
"typescript-eslint": "^8.50.1",
|
||||||
|
"vitest": "^3.2.4"
|
||||||
|
},
|
||||||
|
"dependencies": {
|
||||||
|
"@inquirer/core": "^10.2.2",
|
||||||
|
"@inquirer/prompts": "^7.8.0",
|
||||||
|
"chalk": "^5.5.0",
|
||||||
|
"commander": "^14.0.0",
|
||||||
|
"fast-glob": "^3.3.3",
|
||||||
|
"ora": "^8.2.0",
|
||||||
|
"posthog-node": "^5.20.0",
|
||||||
|
"yaml": "^2.8.2",
|
||||||
|
"zod": "^4.0.17"
|
||||||
|
},
|
||||||
|
"scripts": {
|
||||||
|
"lint": "eslint src/",
|
||||||
|
"build": "node build.js",
|
||||||
|
"dev": "tsc --watch",
|
||||||
|
"dev:cli": "pnpm build && node bin/openspec.js",
|
||||||
|
"test": "vitest run",
|
||||||
|
"test:watch": "vitest",
|
||||||
|
"test:ui": "vitest --ui",
|
||||||
|
"test:coverage": "vitest --coverage",
|
||||||
|
"test:postinstall": "node scripts/postinstall.js",
|
||||||
|
"postinstall": "node scripts/postinstall.js",
|
||||||
|
"check:pack-version": "node scripts/pack-version-check.mjs",
|
||||||
|
"release": "pnpm run release:ci",
|
||||||
|
"release:ci": "pnpm run check:pack-version && pnpm exec changeset publish",
|
||||||
|
"changeset": "changeset"
|
||||||
|
}
|
||||||
|
}
|
||||||
153
extensions/openspec/schemas/spec-driven/schema.yaml
Normal file
153
extensions/openspec/schemas/spec-driven/schema.yaml
Normal file
@@ -0,0 +1,153 @@
|
|||||||
|
name: spec-driven
|
||||||
|
version: 1
|
||||||
|
description: Default OpenSpec workflow - proposal → specs → design → tasks
|
||||||
|
artifacts:
|
||||||
|
- id: proposal
|
||||||
|
generates: proposal.md
|
||||||
|
description: Initial proposal document outlining the change
|
||||||
|
template: proposal.md
|
||||||
|
instruction: |
|
||||||
|
Create the proposal document that establishes WHY this change is needed.
|
||||||
|
|
||||||
|
Sections:
|
||||||
|
- **Why**: 1-2 sentences on the problem or opportunity. What problem does this solve? Why now?
|
||||||
|
- **What Changes**: Bullet list of changes. Be specific about new capabilities, modifications, or removals. Mark breaking changes with **BREAKING**.
|
||||||
|
- **Capabilities**: Identify which specs will be created or modified:
|
||||||
|
- **New Capabilities**: List capabilities being introduced. Each becomes a new `specs/<name>/spec.md`. Use kebab-case names (e.g., `user-auth`, `data-export`).
|
||||||
|
- **Modified Capabilities**: List existing capabilities whose REQUIREMENTS are changing. Only include if spec-level behavior changes (not just implementation details). Each needs a delta spec file. Check `openspec/specs/` for existing spec names. Leave empty if no requirement changes.
|
||||||
|
- **Impact**: Affected code, APIs, dependencies, or systems.
|
||||||
|
|
||||||
|
IMPORTANT: The Capabilities section is critical. It creates the contract between
|
||||||
|
proposal and specs phases. Research existing specs before filling this in.
|
||||||
|
Each capability listed here will need a corresponding spec file.
|
||||||
|
|
||||||
|
Keep it concise (1-2 pages). Focus on the "why" not the "how" -
|
||||||
|
implementation details belong in design.md.
|
||||||
|
|
||||||
|
This is the foundation - specs, design, and tasks all build on this.
|
||||||
|
requires: []
|
||||||
|
|
||||||
|
- id: specs
|
||||||
|
generates: "specs/**/*.md"
|
||||||
|
description: Detailed specifications for the change
|
||||||
|
template: spec.md
|
||||||
|
instruction: |
|
||||||
|
Create specification files that define WHAT the system should do.
|
||||||
|
|
||||||
|
Create one spec file per capability listed in the proposal's Capabilities section.
|
||||||
|
- New capabilities: use the exact kebab-case name from the proposal (specs/<capability>/spec.md).
|
||||||
|
- Modified capabilities: use the existing spec folder name from openspec/specs/<capability>/ when creating the delta spec at specs/<capability>/spec.md.
|
||||||
|
|
||||||
|
Delta operations (use ## headers):
|
||||||
|
- **ADDED Requirements**: New capabilities
|
||||||
|
- **MODIFIED Requirements**: Changed behavior - MUST include full updated content
|
||||||
|
- **REMOVED Requirements**: Deprecated features - MUST include **Reason** and **Migration**
|
||||||
|
- **RENAMED Requirements**: Name changes only - use FROM:/TO: format
|
||||||
|
|
||||||
|
Format requirements:
|
||||||
|
- Each requirement: `### Requirement: <name>` followed by description
|
||||||
|
- Use SHALL/MUST for normative requirements (avoid should/may)
|
||||||
|
- Each scenario: `#### Scenario: <name>` with WHEN/THEN format
|
||||||
|
- **CRITICAL**: Scenarios MUST use exactly 4 hashtags (`####`). Using 3 hashtags or bullets will fail silently.
|
||||||
|
- Every requirement MUST have at least one scenario.
|
||||||
|
|
||||||
|
MODIFIED requirements workflow:
|
||||||
|
1. Locate the existing requirement in openspec/specs/<capability>/spec.md
|
||||||
|
2. Copy the ENTIRE requirement block (from `### Requirement:` through all scenarios)
|
||||||
|
3. Paste under `## MODIFIED Requirements` and edit to reflect new behavior
|
||||||
|
4. Ensure header text matches exactly (whitespace-insensitive)
|
||||||
|
|
||||||
|
Common pitfall: Using MODIFIED with partial content loses detail at archive time.
|
||||||
|
If adding new concerns without changing existing behavior, use ADDED instead.
|
||||||
|
|
||||||
|
Example:
|
||||||
|
```
|
||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: User can export data
|
||||||
|
The system SHALL allow users to export their data in CSV format.
|
||||||
|
|
||||||
|
#### Scenario: Successful export
|
||||||
|
- **WHEN** user clicks "Export" button
|
||||||
|
- **THEN** system downloads a CSV file with all user data
|
||||||
|
|
||||||
|
## REMOVED Requirements
|
||||||
|
|
||||||
|
### Requirement: Legacy export
|
||||||
|
**Reason**: Replaced by new export system
|
||||||
|
**Migration**: Use new export endpoint at /api/v2/export
|
||||||
|
```
|
||||||
|
|
||||||
|
Specs should be testable - each scenario is a potential test case.
|
||||||
|
requires:
|
||||||
|
- proposal
|
||||||
|
|
||||||
|
- id: design
|
||||||
|
generates: design.md
|
||||||
|
description: Technical design document with implementation details
|
||||||
|
template: design.md
|
||||||
|
instruction: |
|
||||||
|
Create the design document that explains HOW to implement the change.
|
||||||
|
|
||||||
|
When to include design.md (create only if any apply):
|
||||||
|
- Cross-cutting change (multiple services/modules) or new architectural pattern
|
||||||
|
- New external dependency or significant data model changes
|
||||||
|
- Security, performance, or migration complexity
|
||||||
|
- Ambiguity that benefits from technical decisions before coding
|
||||||
|
|
||||||
|
Sections:
|
||||||
|
- **Context**: Background, current state, constraints, stakeholders
|
||||||
|
- **Goals / Non-Goals**: What this design achieves and explicitly excludes
|
||||||
|
- **Decisions**: Key technical choices with rationale (why X over Y?). Include alternatives considered for each decision.
|
||||||
|
- **Risks / Trade-offs**: Known limitations, things that could go wrong. Format: [Risk] → Mitigation
|
||||||
|
- **Migration Plan**: Steps to deploy, rollback strategy (if applicable)
|
||||||
|
- **Open Questions**: Outstanding decisions or unknowns to resolve
|
||||||
|
|
||||||
|
Focus on architecture and approach, not line-by-line implementation.
|
||||||
|
Reference the proposal for motivation and specs for requirements.
|
||||||
|
|
||||||
|
Good design docs explain the "why" behind technical decisions.
|
||||||
|
requires:
|
||||||
|
- proposal
|
||||||
|
|
||||||
|
- id: tasks
|
||||||
|
generates: tasks.md
|
||||||
|
description: Implementation checklist with trackable tasks
|
||||||
|
template: tasks.md
|
||||||
|
instruction: |
|
||||||
|
Create the task list that breaks down the implementation work.
|
||||||
|
|
||||||
|
**IMPORTANT: Follow the template below exactly.** The apply phase parses
|
||||||
|
checkbox format to track progress. Tasks not using `- [ ]` won't be tracked.
|
||||||
|
|
||||||
|
Guidelines:
|
||||||
|
- Group related tasks under ## numbered headings
|
||||||
|
- Each task MUST be a checkbox: `- [ ] X.Y Task description`
|
||||||
|
- Tasks should be small enough to complete in one session
|
||||||
|
- Order tasks by dependency (what must be done first?)
|
||||||
|
|
||||||
|
Example:
|
||||||
|
```
|
||||||
|
## 1. Setup
|
||||||
|
|
||||||
|
- [ ] 1.1 Create new module structure
|
||||||
|
- [ ] 1.2 Add dependencies to package.json
|
||||||
|
|
||||||
|
## 2. Core Implementation
|
||||||
|
|
||||||
|
- [ ] 2.1 Implement data export function
|
||||||
|
- [ ] 2.2 Add CSV formatting utilities
|
||||||
|
```
|
||||||
|
|
||||||
|
Reference specs for what needs to be built, design for how to build it.
|
||||||
|
Each task should be verifiable - you know when it's done.
|
||||||
|
requires:
|
||||||
|
- specs
|
||||||
|
- design
|
||||||
|
|
||||||
|
apply:
|
||||||
|
requires: [tasks]
|
||||||
|
tracks: tasks.md
|
||||||
|
instruction: |
|
||||||
|
Read context files, work through pending tasks, mark complete as you go.
|
||||||
|
Pause if you hit blockers or need clarification.
|
||||||
19
extensions/openspec/schemas/spec-driven/templates/design.md
Normal file
19
extensions/openspec/schemas/spec-driven/templates/design.md
Normal file
@@ -0,0 +1,19 @@
|
|||||||
|
## Context
|
||||||
|
|
||||||
|
<!-- Background and current state -->
|
||||||
|
|
||||||
|
## Goals / Non-Goals
|
||||||
|
|
||||||
|
**Goals:**
|
||||||
|
<!-- What this design aims to achieve -->
|
||||||
|
|
||||||
|
**Non-Goals:**
|
||||||
|
<!-- What is explicitly out of scope -->
|
||||||
|
|
||||||
|
## Decisions
|
||||||
|
|
||||||
|
<!-- Key design decisions and rationale -->
|
||||||
|
|
||||||
|
## Risks / Trade-offs
|
||||||
|
|
||||||
|
<!-- Known risks and trade-offs -->
|
||||||
@@ -0,0 +1,23 @@
|
|||||||
|
## Why
|
||||||
|
|
||||||
|
<!-- Explain the motivation for this change. What problem does this solve? Why now? -->
|
||||||
|
|
||||||
|
## What Changes
|
||||||
|
|
||||||
|
<!-- Describe what will change. Be specific about new capabilities, modifications, or removals. -->
|
||||||
|
|
||||||
|
## Capabilities
|
||||||
|
|
||||||
|
### New Capabilities
|
||||||
|
<!-- Capabilities being introduced. Replace <name> with kebab-case identifier (e.g., user-auth, data-export, api-rate-limiting). Each creates specs/<name>/spec.md -->
|
||||||
|
- `<name>`: <brief description of what this capability covers>
|
||||||
|
|
||||||
|
### Modified Capabilities
|
||||||
|
<!-- Existing capabilities whose REQUIREMENTS are changing (not just implementation).
|
||||||
|
Only list here if spec-level behavior changes. Each needs a delta spec file.
|
||||||
|
Use existing spec names from openspec/specs/. Leave empty if no requirement changes. -->
|
||||||
|
- `<existing-name>`: <what requirement is changing>
|
||||||
|
|
||||||
|
## Impact
|
||||||
|
|
||||||
|
<!-- Affected code, APIs, dependencies, systems -->
|
||||||
@@ -0,0 +1,8 @@
|
|||||||
|
## ADDED Requirements
|
||||||
|
|
||||||
|
### Requirement: <!-- requirement name -->
|
||||||
|
<!-- requirement text -->
|
||||||
|
|
||||||
|
#### Scenario: <!-- scenario name -->
|
||||||
|
- **WHEN** <!-- condition -->
|
||||||
|
- **THEN** <!-- expected outcome -->
|
||||||
@@ -0,0 +1,9 @@
|
|||||||
|
## 1. <!-- Task Group Name -->
|
||||||
|
|
||||||
|
- [ ] 1.1 <!-- Task description -->
|
||||||
|
- [ ] 1.2 <!-- Task description -->
|
||||||
|
|
||||||
|
## 2. <!-- Task Group Name -->
|
||||||
|
|
||||||
|
- [ ] 2.1 <!-- Task description -->
|
||||||
|
- [ ] 2.2 <!-- Task description -->
|
||||||
83
extensions/openspec/scripts/postinstall.js
Normal file
83
extensions/openspec/scripts/postinstall.js
Normal file
@@ -0,0 +1,83 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Postinstall script that hints about shell completions
|
||||||
|
*
|
||||||
|
* Completion installation is opt-in: the user must run
|
||||||
|
* `openspec completion install` explicitly. This script only
|
||||||
|
* prints a one-line tip after npm install.
|
||||||
|
*
|
||||||
|
* The tip is suppressed when:
|
||||||
|
* - CI=true environment variable is set
|
||||||
|
* - OPENSPEC_NO_COMPLETIONS=1 environment variable is set
|
||||||
|
* - dist/ directory doesn't exist (dev setup scenario)
|
||||||
|
*
|
||||||
|
* The script never fails npm install - all errors are caught and handled gracefully.
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { promises as fs } from 'fs';
|
||||||
|
import path from 'path';
|
||||||
|
import { fileURLToPath } from 'url';
|
||||||
|
|
||||||
|
const __filename = fileURLToPath(import.meta.url);
|
||||||
|
const __dirname = path.dirname(__filename);
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check if we should skip installation
|
||||||
|
*/
|
||||||
|
function shouldSkipInstallation() {
|
||||||
|
// Skip in CI environments
|
||||||
|
if (process.env.CI === 'true' || process.env.CI === '1') {
|
||||||
|
return { skip: true, reason: 'CI environment detected' };
|
||||||
|
}
|
||||||
|
|
||||||
|
// Skip if user opted out
|
||||||
|
if (process.env.OPENSPEC_NO_COMPLETIONS === '1') {
|
||||||
|
return { skip: true, reason: 'OPENSPEC_NO_COMPLETIONS=1 set' };
|
||||||
|
}
|
||||||
|
|
||||||
|
return { skip: false };
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Check if dist/ directory exists
|
||||||
|
*/
|
||||||
|
async function distExists() {
|
||||||
|
const distPath = path.join(__dirname, '..', 'dist');
|
||||||
|
try {
|
||||||
|
const stat = await fs.stat(distPath);
|
||||||
|
return stat.isDirectory();
|
||||||
|
} catch {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Main function
|
||||||
|
*/
|
||||||
|
async function main() {
|
||||||
|
try {
|
||||||
|
// Check if we should skip
|
||||||
|
const skipCheck = shouldSkipInstallation();
|
||||||
|
if (skipCheck.skip) {
|
||||||
|
// Silent skip - no output
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Check if dist/ exists (skip silently if not - expected during dev setup)
|
||||||
|
if (!(await distExists())) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Completions are opt-in — just print a hint
|
||||||
|
console.log(`\nTip: Run 'openspec completion install' for shell completions`);
|
||||||
|
} catch (error) {
|
||||||
|
// Fail gracefully - never break npm install
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Run main and handle any unhandled errors
|
||||||
|
main().catch(() => {
|
||||||
|
// Silent failure - never break npm install
|
||||||
|
process.exit(0);
|
||||||
|
});
|
||||||
Reference in New Issue
Block a user