@codewalla_india/openspec 1.3.1 → 1.3.3

package/LICENSE

@@ -1,22 +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.
-
+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.
+

package/README.md

@@ -1,191 +1,272 @@
 <p align="center">
-  <a href="https://github.com/codewalla-engineering/OpenSpec">
+  <a href="https://github.com/codewalla-engineering/openspec-upstream-sync">
     <picture>
-      <source srcset="assets/codewalla_bg.png">
-      <img src="assets/codewalla_bg.png" alt="Codewalla OpenSpec" width="100%">
+      <source srcset="assets/openspec_pixel_dark.svg" media="(prefers-color-scheme: dark)">
+      <source srcset="assets/openspec_pixel_light.svg" media="(prefers-color-scheme: light)">
+      <img src="assets/openspec_pixel_light.svg" alt="OpenSpec logo" height="64">
     </picture>
   </a>
-</p>
-
-<p align="center"><strong>Codewalla OpenSpec — spec-driven development for AI coding assistants</strong></p>
 
+</p>
+<p align="center">Spec-driven development for AI coding assistants.</p>
 <p align="center">
-  <a href="https://github.com/codewalla-engineering/OpenSpec/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/codewalla-engineering/OpenSpec/actions/workflows/ci.yml/badge.svg" /></a>
+  <a href="https://github.com/codewalla-engineering/openspec-upstream-sync/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/codewalla-engineering/openspec-upstream-sync/actions/workflows/ci.yml/badge.svg" /></a>
   <a href="https://www.npmjs.com/package/@codewalla_india/openspec"><img alt="npm version" src="https://img.shields.io/npm/v/@codewalla_india/openspec?style=flat-square" /></a>
+  <a href="https://nodejs.org/"><img alt="node version" src="https://img.shields.io/node/v/@codewalla_india/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://conventionalcommits.org"><img alt="Conventional Commits" src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow.svg?style=flat-square" /></a>
+  <a href="https://discord.gg/YctCnvvshC"><img alt="Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white&style=flat-square" /></a>
 </p>
 
-> [!TIP]
-> **Codewalla workflow:** Propose from a Jira ticket or plain description, revise with `/opsx:modify`, then apply.
->
-> Run `/opsx:propose CW-1234 add dark mode` or `/opsx:propose "your idea"` to get started.
-> → [Jira integration](docs/workflows.md#jira-integration) · [MCP setup](docs/mcp-setup.md)
-
-<!-- TODO: Add GIF demo of /opsx:propose → /opsx:archive workflow -->
-
-## See it in action
-
-```text
-You: /opsx:explore
-AI:  What would you like to explore?
-You: I want dark mode but I'm not sure how to do it cleanly.
-AI:  Let me look at your styling setup...
-     Cleanest path here: CSS variables + a small theme context,
-     with system-preference detection. No new dependencies. Scope it?
-You: Yes, let's do it.
-
-You: /opsx:propose CW-1234 add-dark-mode
-AI:  Found CW-1234: 'Add dark mode'. Creating change from Jira ticket...
-     ✓ proposal.md  (Impact: Jira: CW-1234)
-     ✓ specs/ui/    (requirements from Jira ACs)
-     ✓ design.md    — technical approach
-     ✓ plan.md      — file-level code map
-     ✓ tasks.md     — implementation checklist
-     Ready for implementation!
-
-You: /opsx:modify add-dark-mode design use CSS variables instead of hardcoded colors
-AI:  Updated design.md → propagated to plan.md and tasks.md
-     Run /opsx:apply when ready.
-
-You: /opsx:apply
-AI:  Jira context: CW-1234 — all ACs covered ✓
-     Comprehension check — 7 questions on proposal, design, specs, plan, and tasks...
-     ✓ 86% — ready to implement.
-     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.
-```
+<p align="center">
+  <img src="assets/codewalla_bg.png" alt="OpenSpec dashboard preview" width="90%">
+</p>
+
+<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>
 
-## Quick Start
+<p align="center">
+  <sub>🚀 <strong>New:</strong> <a href="docs/opsx.md">OPSX Workflow</a> — schema-driven, hackable, fluid. Iterate on workflows without code changes.</sub>
+</p>
 
-**Requires Node.js 20.19.0 or higher.**
+# OpenSpec
 
-Install OpenSpec globally:
+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.**
 
-```bash
-npm install -g @codewalla_india/openspec@latest
-```
+## 🎯 Why OpenSpec?
 
-Then navigate to your project directory and initialize:
+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.
+
+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
+
+## 🌟 What's New in v1.8.0
+
+### 🚀 OPSX Workflow - The New Standard
+
+**OPSX is now the default workflow for OpenSpec.** It's a fluid, iterative approach that replaces rigid phases with flexible actions you can take anytime.
+
+**Key improvements:**
+- **Schema-driven**: Edit `schema.yaml` and `templates/*.md` to customize workflows without code changes
+- **Fluid actions**: Create, implement, update, archive — do any of them anytime
+- **Hackable**: Experiment with instructions, test granularly, customize workflows
+- **Team-ready**: Create workflows that match how your team actually works
 
 ```bash
-cd your-project
+# Quick start with OPSX
 openspec init
+# Then in your AI chat:
+/opsx:explore      # Think through ideas
+/opsx:propose      # Create change with planning artifacts
+/opsx:apply        # Implement tasks
+/opsx:archive      # Archive when done
 ```
 
-> [!NOTE]
-> **Codewalla identity:** `openspec init` prompts for your Codewalla email or username. All commands require telemetry identity. CI runners should pre-provision `~/.config/openspec/telemetry-identity.json` or set `OPENSPEC_TELEMETRY_USER`.
+### 🆕 New AI Tool Integrations
 
-Now talk to your AI:
+- **Atlassian Rovo Dev CLI** support (`--tools rovodev`)
+- **MiniMax Code** as a global skills-only tool target
+- **Enhanced GitHub Copilot** integration with opt-in cloud coding agent files
+- **Improved Codex skills** now use the shared `.agents` directory
 
-- **Not sure what you want to build yet?** Start with `/opsx:explore`, a no-stakes thinking partner that reads your code, weighs options, and shapes a plan before anything is written. ([Explore guide](docs/explore.md))
-- **Already know what you want?** Go straight to `/opsx:propose <what-you-want-to-build>` or `/opsx:propose CW-1234 <summary>` to import from Jira.
-- **Need to revise the plan before coding?** Run `/opsx:modify` — pre-apply only; propagates changes to downstream artifacts. ([Editing a change](docs/editing-changes.md))
-- **Ready to implement?** Run `/opsx:apply` — a short comprehension quiz checks you understand the proposal, design, specs, plan, and tasks before any code is written.
+### � New Plan Artifact
 
-The default `core` profile includes `/opsx:explore`, `/opsx:propose`, `/opsx:modify`, `/opsx:apply`, `/opsx:sync`, and `/opsx:archive`. If you want the expanded workflow (`/opsx:new`, `/opsx:continue`, `/opsx:ff`, `/opsx:verify`, `/opsx:bulk-archive`, `/opsx:onboard`), select it with `openspec config profile` and apply with `openspec update`.
+- **Mandatory planning artifact** with implementation guidance
+- **Code maps** showing files to create, modify, and delete
+- **Implementation order** with sequenced steps
+- **Test plans** covering unit, integration, and manual testing
+- **Risk assessment** with mitigation strategies
+- **Dependency chain**: specs → design → plan → tasks
 
-> [!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).
+### 🔧 Enhanced Features
 
-## Codewalla workflow & MCPs
+- **OPSX Modify Command** (experimental): `/opsx:modify` for revising planning artifacts before implementation
+- **Dependency propagation**: Automatic updates to dependent artifacts when modifying
+- **Conflict detection**: Identifies conflicts with manual edits before modification
+- **Modification history**: Tracks all artifact changes with timestamps
 
-OpenSpec workflows integrate with MCP servers in your AI tool. MCPs are optional — workflows degrade gracefully when a server is unavailable.
+### �🔧 Enhanced Features
 
-| MCP | Workflow | Behavior |
-|-----|----------|----------|
-| **Atlassian** | `/opsx:propose`, `/opsx:apply` | Import Jira tickets; enrich and cross-check ACs vs tasks; skips if unavailable |
-| **Context7** | `/opsx:apply` | Fetch current library docs when tasks reference packages; max 3 calls per session |
-| **Browser** | `/opsx:verify` (expanded profile) | Screenshots, a11y snapshot, console errors; not run during apply |
+- **Capability retirement**: Automatically retire capabilities when changes remove their last requirements
+- **Multi-language validation**: `openspec validate` now treats English `SHALL`/`MUST` as guidance in normal mode
+- **Better task progress**: Counts indented sub-tasks and provides more accurate progress tracking
+- **Improved archive guidance**: Better error messages and flag suggestions for non-interactive environments
 
-→ **[MCP Setup guide](docs/mcp-setup.md)** — enable servers in Cursor or your AI tool<br>
-→ **[Jira integration](docs/workflows.md#jira-integration)** — naming conventions and ticket flows
+## 📚 How It Works
 
-## Docs
+```
+┌────────────────────┐
+│ Draft Change       │
+│ Proposal           │
+└────────┬───────────┘
+         │ share intent with your AI
+         ▼
+┌────────────────────┐
+│ Review & Align     │
+│ (edit specs/tasks) │◀──── feedback loop ──────┐
+└────────┬───────────┘                          │
+         │ approved plan                        │
+         ▼                                      │
+┌────────────────────┐                          │
+│ Implement Tasks    │──────────────────────────┘
+│ (AI writes code)   │
+└────────┬───────────┘
+         │ ship the change
+         ▼
+┌────────────────────┐
+│ Archive & Update   │
+│ Specs (source)     │
+└────────────────────┘
+
+1. Draft a change proposal that captures the spec updates you want
+2. Review the proposal with your AI assistant until everyone agrees
+3. Implement tasks that reference the agreed specs
+4. Archive the change to merge the approved updates back into the source-of-truth specs
+```
 
-**Start here:** the **[Documentation Home](docs/README.md)** maps everything. New to OpenSpec? Read [Getting Started](docs/getting-started.md), then [How Commands Work](docs/how-commands-work.md) (where you actually type `/opsx:propose`).
+## 🚀 Getting Started
 
-→ **[Getting Started](docs/getting-started.md)**: first steps<br>
-→ **[Explore First](docs/explore.md)**: think it through with `/opsx:explore` before you commit<br>
-→ **[How Commands Work](docs/how-commands-work.md)**: where slash commands run vs the CLI<br>
-→ **[Core Concepts at a Glance](docs/overview.md)**: the whole mental model, one page<br>
-→ **[Examples & Recipes](docs/examples.md)**: real changes, start to finish<br>
-→ **[Workflows](docs/workflows.md)**: combos and patterns<br>
-→ **[MCP Setup](docs/mcp-setup.md)**: Atlassian, Context7, and browser MCPs<br>
-→ **[Existing Projects](docs/existing-projects.md)**: adopt OpenSpec on a brownfield codebase<br>
-→ **[Editing a Change](docs/editing-changes.md)**: update artifacts, go back, reconcile manual edits<br>
-→ **[Commands](docs/commands.md)**: slash commands & skills<br>
-→ **[CLI](docs/cli.md)**: terminal reference<br>
-→ **[Stores](docs/stores-beta/user-guide.md)**: plan in a separate repo, shared across your team (beta)<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<br>
-→ **[FAQ](docs/faq.md)** · **[Troubleshooting](docs/troubleshooting.md)** · **[Glossary](docs/glossary.md)**: quick help
+### Prerequisites
+- **Node.js >= 20.19.0** - Check your version with `node --version`
 
+### Step 1: Install the CLI globally
 
-## Community schemas
+**Option A: Using npm**
+```bash
+npm install -g @codewalla_india/openspec@latest
+```
 
-Third-party schema bundles distributed via standalone repositories — these provide opinionated workflows that integrate OpenSpec with other tools, similar to how [github/spec-kit's community extension catalog](https://github.com/github/spec-kit/tree/main/extensions) handles tool integrations.
+Verify installation:
+```bash
+openspec --version
+```
 
-→ **[Browse the catalog](docs/customization.md#community-schemas)** in the customization docs.
+**Option B: Using Nix (NixOS and Nix package manager)**
+```bash
+nix run github:codewalla-engineering/openspec-upstream-sync -- init
+```
 
+Or install to your profile:
+```bash
+nix profile install github:codewalla-engineering/openspec-upstream-sync
+```
 
-## Why OpenSpec?
+### Step 2: Initialize OpenSpec in your project
 
-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.
+```bash
+cd your-project
+openspec init
+```
 
-- **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, plan, and tasks
-- **Work fluidly** — update any artifact anytime with `/opsx:modify`; no rigid phase gates
-- **Jira-native workflow** — propose from ticket keys, enrich from Jira during apply, traceability in proposal Impact
-- **MCP-powered** — Atlassian, Context7, and browser MCPs built into generated skills
-- **Use your tools** — works with 20+ AI assistants via slash commands
+This creates:
+- `openspec/` directory for your specs and changes
+- AI tool integration files (slash commands or skills)
+- Optional project configuration (`openspec/config.yaml`)
 
-## Updating OpenSpec
+### Step 3: Start using OpenSpec
 
-**Upgrade the package**
+**In your AI assistant's chat:**
 
 ```bash
-npm install -g @codewalla_india/openspec@latest
-```
+# Explore an idea (recommended first step)
+/opsx:explore
 
-**Refresh agent instructions**
+# Create a new change
+/opsx:propose add-dark-mode
 
-Run this inside each project to regenerate AI guidance and ensure the latest slash commands and MCP guidance are active:
+# Implement the tasks
+/opsx:apply
 
-```bash
-openspec update
+# Archive when complete
+/opsx:archive
 ```
 
-## Usage Notes
+## 🛠️ Supported AI Tools
+
+OpenSpec integrates with 30+ AI coding assistants. Here are the most popular:
+
+### Native Slash Commands
+These tools have built-in OpenSpec commands:
+
+| Tool | Commands |
+|------|----------|
+| **Claude Code** | `/openspec:proposal`, `/openspec:apply`, `/openspec:archive` |
+| **Cursor** | `/openspec-proposal`, `/openspec-apply`, `/openspec:archive` |
+| **GitHub Copilot** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **Windsurf** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **Continue** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` |
+| **Cline** | Workflows in `.clinerules/workflows/` directory |
+| **Codex** | `/openspec-proposal`, `/openspec-apply`, `/openspec-archive` (auto-installed) |
+
+### AGENTS.md Compatible
+These tools automatically read workflow instructions from `openspec/AGENTS.md`:
+
+| Tools |
+|-------|
+| Amp • Jules • Others |
+
+For the complete list of supported tools, see [Supported Tools](docs/supported-tools.md).
+
+## 📖 Documentation
+
+### Start Here
+- [Getting Started](docs/getting-started.md) - Install, initialize, and run your first change
+- [OPSX Workflow](docs/opsx.md) - The new fluid, schema-driven workflow
+- [How Commands Work](docs/how-commands-work.md) - Where to type slash commands vs terminal commands
+
+### Core Concepts
+- [Core Concepts at a Glance](docs/overview.md) - The mental model on one page
+- [Concepts](docs/concepts.md) - In-depth explanation of specs, changes, artifacts
+- [Glossary](docs/glossary.md) - Every term defined in one place
+
+### Day-to-Day Usage
+- [Workflows](docs/workflows.md) - Common patterns and when to reach for each command
+- [Examples & Recipes](docs/examples.md) - Full walkthroughs of real changes
+- [Writing Good Specs](docs/writing-specs.md) - What strong requirements look like
+- [Reviewing Changes](docs/reviewing-changes.md) - The two-minute review pass
+- [Commands Reference](docs/commands.md) - Complete reference for all OPSX commands including `/opsx:modify`
+
+### Advanced
+- [Customization](docs/customization.md) - Project config, custom schemas, shared context
+- [Multi-Language](docs/multi-language.md) - Generate artifacts in other languages
+- [Stores (beta)](docs/stores-beta/user-guide.md) - Plan across repos and teams
+
+### Help
+- [FAQ](docs/faq.md) - Quick answers to common questions
+- [Troubleshooting](docs/troubleshooting.md) - Concrete fixes for concrete failures
+- [Migration Guide](docs/migration-guide.md) - Moving from legacy workflow to OPSX
+
+## 🔄 Migration from Legacy Workflow
+
+If you're using the old OpenSpec workflow, the [Migration Guide](docs/migration-guide.md) explains what changed and how to transition. Your existing work is safe — the migration is non-destructive.
+
+## 🤝 Contributing
 
-**Context hygiene**: OpenSpec benefits from a clean context window. Clear your context before starting implementation and maintain good context hygiene throughout your session.
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. The most valuable contributions are:
 
-**Modify before apply**: `/opsx:modify` revises planning artifacts and propagates changes downstream. It is pre-apply only — once tasks are checked off in `/opsx:apply`, use manual edits or start a new change.
+- Documentation improvements
+- Bug fixes
+- New AI tool integrations
+- Workflow enhancements
 
-**Comprehension check**: `/opsx:apply` runs a short quiz (enabled by default) on proposal, design, specs, plan, and pending tasks before implementation. Questions test holistic understanding of the change, not task numbers or checklist trivia; plan receives the majority of questions when present. You need ≥ 80% to proceed. Disable with `comprehension.enabled: false` in `openspec/config.yaml`. See [Workflows](docs/workflows.md#comprehension-quiz-before-apply).
+## 📄 License
 
-## Other
+MIT License - see [LICENSE](LICENSE) file for details
 
-<details>
-<summary><strong>Telemetry</strong></summary>
+## 🆘 Support
 
-Codewalla OpenSpec collects mandatory usage analytics tied to your email or username. Identity is collected during interactive `openspec init` or `openspec update` and stored at `~/.config/openspec/telemetry-identity.json` (never committed). All other commands require identity. CI runners should pre-provision that file or set `OPENSPEC_TELEMETRY_USER`.
+- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) for questions, ideas, and help
+- **GitHub Issues:** [github.com/codewalla-engineering/openspec-upstream-sync/issues](https://github.com/codewalla-engineering/openspec-upstream-sync/issues) for bugs and feature requests
+- **Feedback:** Run `openspec feedback "your message"` to send feedback directly from your terminal
 
-Events include command names, workflow metrics, change names, workflow input text (via `--workflow-input` on `new change`), and modify requests (`artifact_modify_requested` with modify input) — not file paths or artifact/spec body content.
+## 🌟 Acknowledgments
 
-</details>
+Built with ❤️ for the AI-assisted development community. Special thanks to all contributors who make OpenSpec better every day.
 
-## License
+---
 
-MIT
+**⚡ Powered by OPSX Workflow — the future of spec-driven development**

package/bin/openspec.js

@@ -1,5 +1,5 @@
-#!/usr/bin/env node
-
-import { runCli } from '../dist/cli/index.js';
-
-runCli();
+#!/usr/bin/env node
+
+import { runCli } from '../dist/cli/index.js';
+
+runCli();