@fission-ai/openspec 0.17.2 → 0.19.0

package/README.md

@@ -26,6 +26,10 @@
   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>
 
+<p align="center">
+  <sub>🧪 <strong>New:</strong> <a href="docs/experimental-workflow.md">Experimental Workflow (OPSX)</a> — schema-driven, hackable, fluid. Iterate on workflows without code changes.</sub>
+</p>
+
 # OpenSpec
 
 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.**
@@ -99,6 +103,7 @@ These tools have built-in OpenSpec commands. Select the OpenSpec integration whe
 | **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` |
@@ -368,6 +373,53 @@ Run `openspec update` whenever someone switches tools so your agents pick up the
 2. **Refresh agent instructions**
    - Run `openspec update` inside each project to regenerate AI guidance and ensure the latest slash commands are active.
 
+## Experimental Features
+
+<details>
+<summary><strong>🧪 OPSX: Fluid, Iterative Workflow</strong> (Claude Code only)</summary>
+
+**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)
+
+</details>
+
+<details>
+<summary><strong>Telemetry</strong> – OpenSpec collects anonymous usage stats (opt-out: <code>OPENSPEC_TELEMETRY=0</code>)</summary>
+
+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>
+
 ## Contributing
 
 - Install dependencies: `pnpm install`

package/dist/cli/index.js

@@ -14,21 +14,52 @@ import { ValidateCommand } from '../commands/validate.js';
 import { ShowCommand } from '../commands/show.js';
 import { CompletionCommand } from '../commands/completion.js';
 import { registerConfigCommand } from '../commands/config.js';
+import { registerArtifactWorkflowCommands } from '../commands/artifact-workflow.js';
+import { maybeShowTelemetryNotice, trackCommand, shutdown } from '../telemetry/index.js';
 const program = new Command();
 const require = createRequire(import.meta.url);
 const { version } = require('../../package.json');
+/**
+ * Get the full command path for nested commands.
+ * For example: 'change show' -> 'change:show'
+ */
+function getCommandPath(command) {
+    const names = [];
+    let current = command;
+    while (current) {
+        const name = current.name();
+        // Skip the root 'openspec' command
+        if (name && name !== 'openspec') {
+            names.unshift(name);
+        }
+        current = current.parent;
+    }
+    return names.join(':') || 'openspec';
+}
 program
     .name('openspec')
     .description('AI-native system for spec-driven development')
     .version(version);
 // Global options
 program.option('--no-color', 'Disable color output');
-// Apply global flags before any command runs
-program.hook('preAction', (thisCommand) => {
+// Apply global flags and telemetry before any command runs
+// Note: preAction receives (thisCommand, actionCommand) where:
+// - thisCommand: the command where hook was added (root program)
+// - actionCommand: the command actually being executed (subcommand)
+program.hook('preAction', async (thisCommand, actionCommand) => {
     const opts = thisCommand.opts();
     if (opts.color === false) {
         process.env.NO_COLOR = '1';
     }
+    // Show first-run telemetry notice (if not seen)
+    await maybeShowTelemetryNotice();
+    // Track command execution (use actionCommand to get the actual subcommand)
+    const commandPath = getCommandPath(actionCommand);
+    await trackCommand(commandPath, version);
+});
+// Shutdown telemetry after command completes
+program.hook('postAction', async () => {
+    await shutdown();
 });
 const availableToolIds = AI_TOOLS.filter((tool) => tool.available).map((tool) => tool.value);
 const toolsOptionDescription = `Configure AI tools non-interactively. Use "all", "none", or a comma-separated list of: ${availableToolIds.join(', ')}`;
@@ -90,11 +121,14 @@ program
     .description('List items (changes by default). Use --specs to list specs.')
     .option('--specs', 'List specs instead of changes')
     .option('--changes', 'List changes explicitly (default)')
+    .option('--sort <order>', 'Sort order: "recent" (default) or "name"', 'recent')
+    .option('--json', 'Output as JSON (for programmatic use)')
     .action(async (options) => {
     try {
         const listCommand = new ListCommand();
         const mode = options?.specs ? 'specs' : 'changes';
-        await listCommand.execute('.', mode);
+        const sort = options?.sort === 'name' ? 'name' : 'recent';
+        await listCommand.execute('.', mode, { sort, json: options?.json });
     }
     catch (error) {
         console.log(); // Empty line for spacing
@@ -307,5 +341,7 @@ program
         process.exitCode = 1;
     }
 });
+// Register artifact workflow commands (experimental)
+registerArtifactWorkflowCommands(program);
 program.parse();
 //# sourceMappingURL=index.js.map

package/dist/commands/artifact-workflow.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Artifact Workflow CLI Commands (Experimental)
+ *
+ * This file contains all artifact workflow commands in isolation for easy removal.
+ * Commands expose the ArtifactGraph and InstructionLoader APIs to users and agents.
+ *
+ * To remove this feature:
+ * 1. Delete this file
+ * 2. Remove the registerArtifactWorkflowCommands() call from src/cli/index.ts
+ */
+import type { Command } from 'commander';
+/**
+ * Registers all artifact workflow commands on the given program.
+ * All commands are marked as experimental in their help text.
+ */
+export declare function registerArtifactWorkflowCommands(program: Command): void;
+//# sourceMappingURL=artifact-workflow.d.ts.map