@codewalla_india/openspec 1.2.0 → 1.3.1

package/README.md

@@ -1,46 +1,25 @@
 <p align="center">
   <a href="https://github.com/codewalla-engineering/OpenSpec">
     <picture>
-      <source srcset="assets/openspec_bg.png">
-      <img src="assets/openspec_bg.png" alt="OpenSpec logo">
+      <source srcset="assets/codewalla_bg.png">
+      <img src="assets/codewalla_bg.png" alt="Codewalla OpenSpec" width="100%">
     </picture>
   </a>
 </p>
 
+<p align="center"><strong>Codewalla OpenSpec — spec-driven development for AI coding assistants</strong></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://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="./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>
-
-[![Stars](https://img.shields.io/github/stars/codewalla-engineering/OpenSpec?style=flat-square&label=Stars)](https://github.com/codewalla-engineering/OpenSpec/stargazers)
-[![Downloads](https://img.shields.io/npm/dm/@codewalla_india/openspec?style=flat-square&label=Downloads/mo)](https://www.npmjs.com/package/@codewalla_india/openspec)
-[![Contributors](https://img.shields.io/github/contributors/codewalla-engineering/OpenSpec?style=flat-square&label=Contributors)](https://github.com/codewalla-engineering/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.
+> **Codewalla workflow:** Propose from a Jira ticket or plain description, revise with `/opsx:modify`, then apply.
 >
-> 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>
+> 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 -->
 
@@ -55,17 +34,23 @@ AI:  Let me look at your styling setup...
      with system-preference detection. No new dependencies. Scope it?
 You: Yes, let's do it.
 
-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
+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:  Comprehension check — 6 questions on your proposal, design, specs, and tasks...
-     ✓ 83% — ready to implement.
+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
@@ -78,15 +63,6 @@ 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.**
@@ -104,19 +80,36 @@ cd your-project
 openspec init
 ```
 
+> [!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`.
+
 Now talk to your AI:
 
-- **Not sure what 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>`.
-- **Ready to implement?** Run `/opsx:apply` — a short comprehension quiz checks you understand the proposal, design, specs, and tasks before any code is written.
+- **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.
 
-The default `core` profile includes `/opsx:explore`, `/opsx:propose`, `/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`.
+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`.
 
 > [!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).
 
+## Codewalla workflow & MCPs
+
+OpenSpec workflows integrate with MCP servers in your AI tool. MCPs are optional — workflows degrade gracefully when a server is unavailable.
+
+| 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 |
+
+→ **[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
+
 ## Docs
 
 **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`).
@@ -127,6 +120,7 @@ The default `core` profile includes `/opsx:explore`, `/opsx:propose`, `/opsx:app
 → **[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>
@@ -151,18 +145,12 @@ Third-party schema bundles distributed via standalone repositories — these pro
 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
+- **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
 
-### 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**
@@ -173,7 +161,7 @@ npm install -g @codewalla_india/openspec@latest
 
 **Refresh agent instructions**
 
-Run this inside each project to regenerate AI guidance and ensure the latest slash commands are active:
+Run this inside each project to regenerate AI guidance and ensure the latest slash commands and MCP guidance are active:
 
 ```bash
 openspec update
@@ -181,29 +169,11 @@ openspec update
 
 ## Usage Notes
 
-**Model selection**: OpenSpec works best with high-reasoning models. We recommend Codex 5.5 and Opus 4.7 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.
 
-**Comprehension check**: `/opsx:apply` runs a short quiz (enabled by default) on proposal, design, specs, and pending tasks before implementation. Questions test holistic understanding of the change, not task numbers or checklist trivia. Disable with `comprehension.enabled: false` in `openspec/config.yaml`. See [Workflows](docs/workflows.md#comprehension-quiz-before-apply).
-
-## Contributing
-
-**Small fixes** — Bug fixes, typo corrections, and minor improvements can be submitted directly as PRs.
+**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.
 
-**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`
+**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).
 
 ## Other
 
@@ -212,19 +182,10 @@ When writing proposals, keep the OpenSpec philosophy in mind: we serve a wide va
 
 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`.
 
-Events include command names, workflow metrics, change names, and workflow input text (via `--workflow-input` on `new change`) — not file paths or artifact/spec body content.
+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.
 
 </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

package/dist/cli/index.js

@@ -23,7 +23,7 @@ import { registerStoreCommand } from '../commands/store.js';
 import { registerDoctorCommand } from '../commands/doctor.js';
 import { registerContextCommand } from '../commands/context.js';
 import { registerWorksetCommand } from '../commands/workset.js';
-import { statusCommand, instructionsCommand, applyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
+import { statusCommand, instructionsCommand, applyInstructionsCommand, modifyInstructionsCommand, templatesCommand, schemasCommand, newChangeCommand, DEFAULT_SCHEMA, } from '../commands/workflow/index.js';
 import { requireTelemetryIdentity, TelemetryIdentityRequiredError, trackCommand, shutdown } from '../telemetry/index.js';
 import { buildCommandTelemetryContext, resolveTelemetryCommandPath, } from '../telemetry/command-context.js';
 import { COMMON_FLAGS } from '../core/completions/shared-flags.js';
@@ -505,14 +505,20 @@ program
     .option('--score <percent>', 'Quiz score 0-100 (required with --record-comprehension-pass)', parseInt)
     .option('--attempt <n>', 'Quiz attempt number', parseInt)
     .option('--question-count <n>', 'Number of quiz questions taken', parseInt)
+    .option('--artifact <id>', 'Source artifact to modify (use with: instructions modify)')
+    .option('--workflow-input <text>', 'User modify request for telemetry (use with: instructions modify)')
+    .option('--workflow-input-file <path>', 'Read modify request from a file (use with: instructions modify)')
+    .option('--editor <tool>', 'AI editor used (cursor, windsurf, claude)')
     .option('--store <id>', STORE_OPTION_DESCRIPTION)
     .addOption(hiddenStorePathOption())
     .action(async (artifactId, options) => {
     try {
-        // Special case: "apply" is not an artifact, but a command to get apply instructions
         if (artifactId === 'apply') {
             await applyInstructionsCommand(options);
         }
+        else if (artifactId === 'modify') {
+            await modifyInstructionsCommand(options);
+        }
         else {
             await instructionsCommand(artifactId, options);
         }

package/dist/commands/workflow/index.d.ts

@@ -5,8 +5,8 @@
  */
 export { statusCommand } from './status.js';
 export type { StatusOptions } from './status.js';
-export { instructionsCommand, applyInstructionsCommand } from './instructions.js';
-export type { InstructionsOptions } from './instructions.js';
+export { instructionsCommand, applyInstructionsCommand, modifyInstructionsCommand } from './instructions.js';
+export type { InstructionsOptions, ModifyInstructionsOptions } from './instructions.js';
 export { templatesCommand } from './templates.js';
 export type { TemplatesOptions } from './templates.js';
 export { schemasCommand } from './schemas.js';

package/dist/commands/workflow/index.js

@@ -4,7 +4,7 @@
  * Commands for the artifact-driven workflow: status, instructions, templates, schemas, new change.
  */
 export { statusCommand } from './status.js';
-export { instructionsCommand, applyInstructionsCommand } from './instructions.js';
+export { instructionsCommand, applyInstructionsCommand, modifyInstructionsCommand } from './instructions.js';
 export { templatesCommand } from './templates.js';
 export { schemasCommand } from './schemas.js';
 export { newChangeCommand } from './new-change.js';

package/dist/commands/workflow/instructions.d.ts

@@ -4,7 +4,7 @@
  * Generates enriched instructions for creating artifacts or applying tasks.
  * Includes both artifact instructions and apply instructions.
  */
-import { type ArtifactInstructions } from '../../core/artifact-graph/index.js';
+import { type ArtifactInstructions, type ArtifactPathSummary } from '../../core/artifact-graph/index.js';
 import { type PlanningHome } from '../../core/planning-home.js';
 import { type ReferenceIndexEntry } from '../../core/references.js';
 import { type ProjectConfig } from '../../core/project-config.js';
@@ -27,6 +27,24 @@ export interface ApplyInstructionsOptions {
     attempt?: number;
     questionCount?: number;
 }
+export interface ModifyInstructionsOptions extends InstructionsOptions {
+    artifact?: string;
+    workflowInput?: string;
+    workflowInputFile?: string;
+    editor?: string;
+}
+export interface ModifyInstructions {
+    changeName: string;
+    schemaName: string;
+    sourceArtifact: string;
+    modifyInput?: string;
+    downstreamArtifacts: string[];
+    artifactsToUpdate: string[];
+    changeRoot: string;
+    artifactPaths: Record<string, ArtifactPathSummary>;
+    phase: 'pre_apply';
+    instruction: string;
+}
 export declare function instructionsCommand(artifactId: string | undefined, options: InstructionsOptions): Promise<void>;
 export declare function printInstructionsText(instructions: ArtifactInstructions, isBlocked: boolean): void;
 export interface GenerateApplyInstructionsOptions {
@@ -42,4 +60,6 @@ export interface GenerateApplyInstructionsOptions {
 export declare function generateApplyInstructions(projectRoot: string, changeName: string, schemaName?: string, options?: GenerateApplyInstructionsOptions): Promise<ApplyInstructions>;
 export declare function applyInstructionsCommand(options: ApplyInstructionsOptions): Promise<void>;
 export declare function printApplyInstructionsText(instructions: ApplyInstructions): void;
+export declare function modifyInstructionsCommand(options: ModifyInstructionsOptions): Promise<void>;
+export declare function printModifyInstructionsText(instructions: ModifyInstructions): void;
 //# sourceMappingURL=instructions.d.ts.map

package/dist/commands/workflow/instructions.js

@@ -7,14 +7,15 @@
 import ora from 'ora';
 import path from 'path';
 import * as fs from 'fs';
-import { loadChangeContext, generateInstructions, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
+import { loadChangeContext, generateInstructions, formatChangeStatus, resolveSchema, resolveArtifactOutputs, } from '../../core/artifact-graph/index.js';
 import { getChangeDir, resolveCurrentPlanningHomeSync, } from '../../core/planning-home.js';
-import { resolveRootForCommand, withStoreFlag, toPlanningHome, toRootOutput, } from '../../core/root-selection.js';
+import { resolveRootForCommand, withStoreFlag, toPlanningHome, toRootOutput, isStoreSelectedRoot, } from '../../core/root-selection.js';
 import { assembleReferenceIndex, renderReferencedStoresBlock, renderReferencedStoresSection, } from '../../core/references.js';
 import { readRegistrySnapshot } from '../../core/store/registry.js';
 import { readProjectConfig } from '../../core/project-config.js';
 import { checkComprehensionGate, ComprehensionPassError, computeSpecStats, recordComprehensionPass, resolveComprehensionConfig, } from '../../core/comprehension/index.js';
-import { maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, incrementComprehensionAttempt, incrementComprehensionFailureCount, trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, } from '../../telemetry/index.js';
+import { maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackArtifactModifyRequested, incrementComprehensionAttempt, incrementComprehensionFailureCount, trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, } from '../../telemetry/index.js';
+import { normalizeEditor, resolveWorkflowInputAsync, } from '../../telemetry/input.js';
 import { validateChangeExists, validateSchemaExists, } from './shared.js';
 function buildArtifactPresence(contextFiles, pendingTaskCount) {
     return {
@@ -634,4 +635,124 @@ export function printApplyInstructionsText(instructions) {
     console.log('### Instruction');
     console.log(instruction);
 }
+// -----------------------------------------------------------------------------
+// Modify Instructions Command (pre-apply artifact revision)
+// -----------------------------------------------------------------------------
+function buildModifyInstruction(sourceArtifact, downstreamArtifacts, modifyInput) {
+    const downstreamLine = downstreamArtifacts.length > 0
+        ? `Downstream artifacts to refresh: ${downstreamArtifacts.join(', ')}.`
+        : 'No downstream artifacts depend on this source.';
+    const requestLine = modifyInput
+        ? `User modify request: ${modifyInput}`
+        : 'Apply the user modify request from the conversation.';
+    return [
+        `Revise the "${sourceArtifact}" artifact for this change (pre-apply only).`,
+        requestLine,
+        downstreamLine,
+        'For each artifact in artifactsToUpdate (in order): run openspec instructions <id> --change <name> --json, read upstream dependencies, apply a surgical edit aligned with the modify request, and write to resolvedOutputPath.',
+        'When proposal capabilities change, add/remove/rename specs under specs/ accordingly.',
+        'After all updates, run openspec status --change <name> --json, then hand off to /opsx:apply.',
+    ].join('\n');
+}
+export async function modifyInstructionsCommand(options) {
+    const root = await resolveRootForCommand(options, { json: options.json });
+    if (!root) {
+        return;
+    }
+    const spinner = options.json ? undefined : ora('Generating modify instructions...').start();
+    try {
+        const planningHome = toPlanningHome(root);
+        const projectRoot = root.path;
+        const changeName = await validateChangeExists(options.change, projectRoot, root.changesDir, { newChangeHint: withStoreFlag(root, 'openspec new change <name>') });
+        if (options.schema) {
+            validateSchemaExists(options.schema, projectRoot);
+        }
+        const sourceArtifact = options.artifact?.trim();
+        if (!sourceArtifact) {
+            spinner?.stop();
+            throw new Error('Missing required option --artifact. Specify the artifact to modify (e.g., design, proposal, tasks).');
+        }
+        const modifyInput = await resolveWorkflowInputAsync({
+            workflowInput: options.workflowInput,
+            workflowInputFile: options.workflowInputFile,
+        });
+        const editor = normalizeEditor(options.editor);
+        const context = loadChangeContext(projectRoot, changeName, options.schema, {
+            changeDir: getChangeDir(planningHome, changeName),
+            planningHome,
+        });
+        const artifact = context.graph.getArtifact(sourceArtifact);
+        if (!artifact) {
+            spinner?.stop();
+            const validIds = context.graph.getAllArtifacts().map((a) => a.id);
+            throw new Error(`Artifact '${sourceArtifact}' not found in schema '${context.schemaName}'. Valid artifacts:\n  ${validIds.join('\n  ')}`);
+        }
+        const applyInstructions = await generateApplyInstructions(projectRoot, changeName, options.schema, {
+            planningHome,
+        });
+        if (applyInstructions.progress.complete > 0) {
+            spinner?.stop();
+            throw new Error(`Apply has already started (${applyInstructions.progress.complete}/${applyInstructions.progress.total} tasks complete). /opsx:modify is pre-apply only. Edit artifacts manually or start a new change.`);
+        }
+        if (applyInstructions.missingArtifacts && applyInstructions.missingArtifacts.length > 0) {
+            spinner?.stop();
+            throw new Error(`Change is not ready to modify. Missing artifacts: ${applyInstructions.missingArtifacts.join(', ')}. Use /opsx:continue or /opsx:propose to create them first.`);
+        }
+        const sourceOutputs = resolveArtifactOutputs(context.changeDir, artifact.generates);
+        if (sourceOutputs.length === 0) {
+            spinner?.stop();
+            throw new Error(`Artifact '${sourceArtifact}' does not exist yet. Use /opsx:continue to create it first.`);
+        }
+        const downstreamArtifacts = context.graph.getTransitiveDependents(sourceArtifact);
+        const artifactsToUpdate = [sourceArtifact, ...downstreamArtifacts];
+        const status = formatChangeStatus(context, isStoreSelectedRoot(root) ? { storeId: root.storeId } : {});
+        await trackArtifactModifyRequested({
+            changeDir: context.changeDir,
+            changeName,
+            schema: context.schemaName,
+            sourceArtifactId: sourceArtifact,
+            downstreamArtifactIds: downstreamArtifacts,
+            artifactsToUpdate,
+            modifyInput,
+            editor,
+        });
+        const payload = {
+            changeName,
+            schemaName: context.schemaName,
+            sourceArtifact,
+            ...(modifyInput ? { modifyInput } : {}),
+            downstreamArtifacts,
+            artifactsToUpdate,
+            changeRoot: context.changeDir,
+            artifactPaths: status.artifactPaths,
+            phase: 'pre_apply',
+            instruction: buildModifyInstruction(sourceArtifact, downstreamArtifacts, modifyInput),
+        };
+        spinner?.stop();
+        if (options.json) {
+            console.log(JSON.stringify({ ...payload, root: toRootOutput(root) }, null, 2));
+            return;
+        }
+        printModifyInstructionsText(payload);
+    }
+    catch (error) {
+        spinner?.stop();
+        throw error;
+    }
+}
+export function printModifyInstructionsText(instructions) {
+    console.log(`## Modify: ${instructions.changeName}`);
+    console.log(`Schema: ${instructions.schemaName}`);
+    console.log(`Phase: ${instructions.phase}`);
+    console.log();
+    console.log(`Source artifact: ${instructions.sourceArtifact}`);
+    if (instructions.modifyInput) {
+        console.log(`Modify request: ${instructions.modifyInput}`);
+    }
+    console.log(`Downstream: ${instructions.downstreamArtifacts.length > 0 ? instructions.downstreamArtifacts.join(', ') : '(none)'}`);
+    console.log(`Artifacts to update: ${instructions.artifactsToUpdate.join(', ')}`);
+    console.log();
+    console.log('### Instruction');
+    console.log(instructions.instruction);
+}
 //# sourceMappingURL=instructions.js.map

package/dist/core/artifact-graph/graph.d.ts

@@ -35,6 +35,15 @@ export declare class ArtifactGraph {
      * Gets the schema version.
      */
     getVersion(): number;
+    /**
+     * Builds reverse adjacency: artifact ID -> IDs of artifacts that depend on it.
+     */
+    private buildDependentsMap;
+    /**
+     * Returns all transitive downstream artifact IDs that depend on the given artifact,
+     * sorted by build order (excludes the source artifact itself).
+     */
+    getTransitiveDependents(artifactId: string): string[];
     /**
      * Computes the topological build order using Kahn's algorithm.
      * Returns artifact IDs in the order they should be built.

package/dist/core/artifact-graph/graph.js

@@ -55,23 +55,53 @@ export class ArtifactGraph {
         return this.schema.version;
     }
     /**
-     * Computes the topological build order using Kahn's algorithm.
-     * Returns artifact IDs in the order they should be built.
+     * Builds reverse adjacency: artifact ID -> IDs of artifacts that depend on it.
      */
-    getBuildOrder() {
-        const inDegree = new Map();
+    buildDependentsMap() {
         const dependents = new Map();
-        // Initialize all artifacts
         for (const artifact of this.artifacts.values()) {
-            inDegree.set(artifact.id, artifact.requires.length);
             dependents.set(artifact.id, []);
         }
-        // Build reverse adjacency (who depends on whom)
         for (const artifact of this.artifacts.values()) {
             for (const req of artifact.requires) {
                 dependents.get(req).push(artifact.id);
             }
         }
+        return dependents;
+    }
+    /**
+     * Returns all transitive downstream artifact IDs that depend on the given artifact,
+     * sorted by build order (excludes the source artifact itself).
+     */
+    getTransitiveDependents(artifactId) {
+        if (!this.artifacts.has(artifactId)) {
+            return [];
+        }
+        const dependents = this.buildDependentsMap();
+        const collected = new Set();
+        const queue = [artifactId];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            for (const dependentId of dependents.get(current) ?? []) {
+                if (!collected.has(dependentId)) {
+                    collected.add(dependentId);
+                    queue.push(dependentId);
+                }
+            }
+        }
+        return this.getBuildOrder().filter((id) => collected.has(id));
+    }
+    /**
+     * Computes the topological build order using Kahn's algorithm.
+     * Returns artifact IDs in the order they should be built.
+     */
+    getBuildOrder() {
+        const inDegree = new Map();
+        const dependents = this.buildDependentsMap();
+        // Initialize in-degrees
+        for (const artifact of this.artifacts.values()) {
+            inDegree.set(artifact.id, artifact.requires.length);
+        }
         // Start with roots (in-degree 0), sorted for determinism
         const queue = [...this.artifacts.keys()]
             .filter(id => inDegree.get(id) === 0)

package/dist/core/change-status-policy.js

@@ -28,7 +28,7 @@ export function buildNextSteps(input) {
         steps.push(`Run openspec instructions ${readyArtifact.id} --change "${input.changeName}"${storeFlag} --json before writing that artifact.`);
     }
     else if (input.allArtifactsComplete) {
-        steps.push('All planning artifacts are complete; review tasks before implementation.');
+        steps.push('Review planning artifacts; use /opsx:modify to revise or /opsx:apply to implement.');
     }
     return steps;
 }

package/dist/core/completions/command-registry.js

@@ -210,6 +210,26 @@ export const COMMAND_REGISTRY = [
                 description: 'Number of quiz questions taken',
                 takesValue: true,
             },
+            {
+                name: 'artifact',
+                description: 'Source artifact to modify (use with: instructions modify)',
+                takesValue: true,
+            },
+            {
+                name: 'workflow-input',
+                description: 'User modify request for telemetry (use with: instructions modify)',
+                takesValue: true,
+            },
+            {
+                name: 'workflow-input-file',
+                description: 'Read modify request from a file (use with: instructions modify)',
+                takesValue: true,
+            },
+            {
+                name: 'editor',
+                description: 'AI editor used (cursor, windsurf, claude)',
+                takesValue: true,
+            },
             COMMON_FLAGS.json,
             COMMON_FLAGS.store,
         ],

package/dist/core/profile-sync-drift.js

@@ -11,6 +11,7 @@ export const WORKFLOW_TO_SKILL_DIR = {
     'explore': 'openspec-explore',
     'new': 'openspec-new-change',
     'continue': 'openspec-continue-change',
+    'modify': 'openspec-modify-change',
     'apply': 'openspec-apply-change',
     'ff': 'openspec-ff-change',
     'sync': 'openspec-sync-specs',

package/dist/core/profiles.d.ts

@@ -9,11 +9,11 @@ import type { Profile } from './global-config.js';
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export declare const CORE_WORKFLOWS: readonly ["propose", "explore", "apply", "sync", "archive"];
+export declare const CORE_WORKFLOWS: readonly ["propose", "explore", "modify", "apply", "sync", "archive"];
 /**
  * All available workflows in the system.
  */
-export declare const ALL_WORKFLOWS: readonly ["propose", "explore", "new", "continue", "apply", "ff", "sync", "archive", "bulk-archive", "verify", "onboard"];
+export declare const ALL_WORKFLOWS: readonly ["propose", "explore", "modify", "new", "continue", "apply", "ff", "sync", "archive", "bulk-archive", "verify", "onboard"];
 export type WorkflowId = (typeof ALL_WORKFLOWS)[number];
 export type CoreWorkflowId = (typeof CORE_WORKFLOWS)[number];
 /**

package/dist/core/profiles.js

@@ -8,13 +8,14 @@
  * Core workflows included in the 'core' profile.
  * These provide the streamlined experience for new users.
  */
-export const CORE_WORKFLOWS = ['propose', 'explore', 'apply', 'sync', 'archive'];
+export const CORE_WORKFLOWS = ['propose', 'explore', 'modify', 'apply', 'sync', 'archive'];
 /**
  * All available workflows in the system.
  */
 export const ALL_WORKFLOWS = [
     'propose',
     'explore',
+    'modify',
     'new',
     'continue',
     'apply',

package/dist/core/shared/skill-generation.js

@@ -3,7 +3,7 @@
  *
  * Shared utilities for generating skill and command files.
  */
-import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getBulkArchiveChangeSkillTemplate, getVerifyChangeSkillTemplate, getOnboardSkillTemplate, getOpsxProposeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxBulkArchiveCommandTemplate, getOpsxVerifyCommandTemplate, getOpsxOnboardCommandTemplate, getOpsxProposeCommandTemplate, } from '../templates/skill-templates.js';
+import { getExploreSkillTemplate, getNewChangeSkillTemplate, getContinueChangeSkillTemplate, getApplyChangeSkillTemplate, getFfChangeSkillTemplate, getSyncSpecsSkillTemplate, getArchiveChangeSkillTemplate, getBulkArchiveChangeSkillTemplate, getVerifyChangeSkillTemplate, getOnboardSkillTemplate, getOpsxProposeSkillTemplate, getModifyChangeSkillTemplate, getOpsxExploreCommandTemplate, getOpsxNewCommandTemplate, getOpsxContinueCommandTemplate, getOpsxApplyCommandTemplate, getOpsxFfCommandTemplate, getOpsxSyncCommandTemplate, getOpsxArchiveCommandTemplate, getOpsxBulkArchiveCommandTemplate, getOpsxVerifyCommandTemplate, getOpsxOnboardCommandTemplate, getOpsxProposeCommandTemplate, getOpsxModifyCommandTemplate, } from '../templates/skill-templates.js';
 /**
  * Gets skill templates with their directory names, optionally filtered by workflow IDs.
  *
@@ -15,6 +15,7 @@ export function getSkillTemplates(workflowFilter) {
         { template: getNewChangeSkillTemplate(), dirName: 'openspec-new-change', workflowId: 'new' },
         { template: getContinueChangeSkillTemplate(), dirName: 'openspec-continue-change', workflowId: 'continue' },
         { template: getApplyChangeSkillTemplate(), dirName: 'openspec-apply-change', workflowId: 'apply' },
+        { template: getModifyChangeSkillTemplate(), dirName: 'openspec-modify-change', workflowId: 'modify' },
         { template: getFfChangeSkillTemplate(), dirName: 'openspec-ff-change', workflowId: 'ff' },
         { template: getSyncSpecsSkillTemplate(), dirName: 'openspec-sync-specs', workflowId: 'sync' },
         { template: getArchiveChangeSkillTemplate(), dirName: 'openspec-archive-change', workflowId: 'archive' },
@@ -39,6 +40,7 @@ export function getCommandTemplates(workflowFilter) {
         { template: getOpsxNewCommandTemplate(), id: 'new' },
         { template: getOpsxContinueCommandTemplate(), id: 'continue' },
         { template: getOpsxApplyCommandTemplate(), id: 'apply' },
+        { template: getOpsxModifyCommandTemplate(), id: 'modify' },
         { template: getOpsxFfCommandTemplate(), id: 'ff' },
         { template: getOpsxSyncCommandTemplate(), id: 'sync' },
         { template: getOpsxArchiveCommandTemplate(), id: 'archive' },

package/dist/core/shared/tool-detection.d.ts

@@ -6,12 +6,12 @@
 /**
  * Names of skill directories created by openspec init.
  */
-export declare const SKILL_NAMES: readonly ["openspec-explore", "openspec-new-change", "openspec-continue-change", "openspec-apply-change", "openspec-ff-change", "openspec-sync-specs", "openspec-archive-change", "openspec-bulk-archive-change", "openspec-verify-change", "openspec-onboard", "openspec-propose"];
+export declare const SKILL_NAMES: readonly ["openspec-explore", "openspec-new-change", "openspec-continue-change", "openspec-modify-change", "openspec-apply-change", "openspec-ff-change", "openspec-sync-specs", "openspec-archive-change", "openspec-bulk-archive-change", "openspec-verify-change", "openspec-onboard", "openspec-propose"];
 export type SkillName = (typeof SKILL_NAMES)[number];
 /**
  * IDs of command templates created by openspec init.
  */
-export declare const COMMAND_IDS: readonly ["explore", "new", "continue", "apply", "ff", "sync", "archive", "bulk-archive", "verify", "onboard", "propose"];
+export declare const COMMAND_IDS: readonly ["explore", "new", "continue", "modify", "apply", "ff", "sync", "archive", "bulk-archive", "verify", "onboard", "propose"];
 export type CommandId = (typeof COMMAND_IDS)[number];
 /**
  * Status of skill configuration for a tool.

package/dist/core/shared/tool-detection.js

@@ -13,6 +13,7 @@ export const SKILL_NAMES = [
     'openspec-explore',
     'openspec-new-change',
     'openspec-continue-change',
+    'openspec-modify-change',
     'openspec-apply-change',
     'openspec-ff-change',
     'openspec-sync-specs',
@@ -29,6 +30,7 @@ export const COMMAND_IDS = [
     'explore',
     'new',
     'continue',
+    'modify',
     'apply',
     'ff',
     'sync',

package/dist/core/templates/skill-templates.d.ts

@@ -15,5 +15,6 @@ export { getBulkArchiveChangeSkillTemplate, getOpsxBulkArchiveCommandTemplate }
 export { getVerifyChangeSkillTemplate, getOpsxVerifyCommandTemplate } from './workflows/verify-change.js';
 export { getOnboardSkillTemplate, getOpsxOnboardCommandTemplate } from './workflows/onboard.js';
 export { getOpsxProposeSkillTemplate, getOpsxProposeCommandTemplate } from './workflows/propose.js';
+export { getModifyChangeSkillTemplate, getOpsxModifyCommandTemplate } from './workflows/modify-change.js';
 export { getFeedbackSkillTemplate } from './workflows/feedback.js';
 //# sourceMappingURL=skill-templates.d.ts.map

package/dist/core/templates/skill-templates.js

@@ -14,5 +14,6 @@ export { getBulkArchiveChangeSkillTemplate, getOpsxBulkArchiveCommandTemplate }
 export { getVerifyChangeSkillTemplate, getOpsxVerifyCommandTemplate } from './workflows/verify-change.js';
 export { getOnboardSkillTemplate, getOpsxOnboardCommandTemplate } from './workflows/onboard.js';
 export { getOpsxProposeSkillTemplate, getOpsxProposeCommandTemplate } from './workflows/propose.js';
+export { getModifyChangeSkillTemplate, getOpsxModifyCommandTemplate } from './workflows/modify-change.js';
 export { getFeedbackSkillTemplate } from './workflows/feedback.js';
 //# sourceMappingURL=skill-templates.js.map

package/dist/core/templates/workflows/apply-change.js

@@ -181,16 +181,13 @@ export function getOpsxApplyCommandTemplate() {
 
 ${STORE_SELECTION_GUIDANCE}
 
-**Input**: Optionally specify a change name (e.g., \`/opsx:apply add-auth\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+**Input**: Optionally specify a change name (e.g., \`/opsx:apply add-auth\`). If omitted, infer from conversation context; if ambiguous you MUST prompt for available changes.
 
 **Steps**
 
 1. **Select the change**
 
-   If a name is provided, use it. Otherwise:
-   - Infer from conversation context if the user mentioned a change
-   - Auto-select if only one active change exists
-   - If ambiguous, ${PROMPT_SELECT_CHANGE}
+   If a name is provided, use it. Otherwise infer from conversation context, auto-select if only one active change exists, or if ambiguous, ${PROMPT_SELECT_CHANGE}
 
    Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:apply <other>\`).
 
@@ -198,28 +195,19 @@ ${STORE_SELECTION_GUIDANCE}
    \`\`\`bash
    openspec status --change "<name>" --json
    \`\`\`
-   Parse the JSON to understand:
-   - \`schemaName\`: The workflow being used (e.g., "spec-driven")
-   - \`planningHome\`, \`changeRoot\`, and \`actionContext\`: planning scope and edit constraints
-   - Which artifact contains the tasks (typically "tasks" for spec-driven, check status for others)
+   Parse \`schemaName\`, \`planningHome\`/\`changeRoot\`/\`actionContext\` (planning scope and edit constraints), and which artifact holds the tasks (typically "tasks" for spec-driven).
 
 3. **Get apply instructions**
-
    \`\`\`bash
    openspec instructions apply --change "<name>" --json
    \`\`\`
-
-   This returns:
-   - \`contextFiles\`: artifact ID -> array of concrete file paths (varies by schema)
-   - Progress (total, complete, remaining)
-   - Task list with status
-   - Dynamic instruction based on current state
+   Returns \`contextFiles\` (artifact ID -> file paths, varies by schema), progress, task list, and a dynamic instruction.
 
    **Handle states:**
-   - If \`state: "blocked"\` and \`missingArtifacts\`: show message, suggest using \`/opsx:continue\`
-   - If \`state: "blocked"\` and \`missingComprehension\`: proceed to step 4 (comprehension quiz) — do NOT implement
-   - If \`state: "all_done"\`: congratulate, suggest archive
-   - If \`state: "ready"\`: proceed to step 5
+   - \`blocked\` + \`missingArtifacts\`: show message, suggest \`/opsx:continue\`
+   - \`blocked\` + \`missingComprehension\`: proceed to step 4 (comprehension quiz) — do NOT implement
+   - \`all_done\`: congratulate, suggest archive
+   - \`ready\`: proceed to step 5
 
 ${ATLASSIAN_ENRICHMENT_GUIDANCE}
 
@@ -227,116 +215,29 @@ ${COMPREHENSION_QUIZ_GUIDANCE}
 
 5. **Read context files**
 
-   After comprehension is passed (or not required), read every file path listed under \`contextFiles\` from the apply instructions output.
-   The files depend on the schema being used:
-   - **spec-driven**: proposal, specs, design, plan, tasks
-   - Other schemas: follow the contextFiles from CLI output
-
-6. **Show current progress**
+   After comprehension passes (or isn't required), read every path under \`contextFiles\` from the apply instructions output (varies by schema; spec-driven: proposal, specs, design, plan, tasks).
 
-   Display:
-   - Schema being used
-   - Progress: "N/M tasks complete"
-   - Remaining tasks overview
-   - Dynamic instruction from CLI
+6. **Show current progress** — schema, progress ("N/M tasks complete"), remaining tasks, and the dynamic instruction from the CLI.
 
 7. **Implement tasks (loop until done or blocked)**
 
-   For each pending task:
-   - Show which task is being worked on
+   For each pending task, announce which task is being worked on.
 
 ${CONTEXT7_LOOKUP_GUIDANCE}
 
-   - Make the code changes required
-   - Keep changes minimal and focused
-   - Mark task complete in the tasks file: \`- [ ]\` → \`- [x]\`
-   - Continue to next task
-
-   **After editing artifacts:** run \`openspec status --change "<name>" --json\` so revision tracking records content changes.
-
-   **Pause if:**
-   - Task is unclear → ask for clarification
-   - Implementation reveals a design issue → suggest updating artifacts
-   - Error or blocker encountered → report and wait for guidance
-   - User interrupts
-
-8. **On completion or pause, show status**
-
-   Display:
-   - Tasks completed this session
-   - Overall progress: "N/M tasks complete"
-   - If all done: suggest archive
-   - If paused: explain why and wait for guidance
-
-**Output During Implementation**
-
-\`\`\`
-## Implementing: <change-name> (schema: <schema-name>)
-
-Working on task 3/7: <task description>
-[...implementation happening...]
-✓ Task complete
-
-Working on task 4/7: <task description>
-[...implementation happening...]
-✓ Task complete
-\`\`\`
-
-**Output On Completion**
-
-\`\`\`
-## Implementation Complete
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 7/7 tasks complete ✓
-
-### Completed This Session
-- [x] Task 1
-- [x] Task 2
-...
-
-All tasks complete! You can archive this change with \`/opsx:archive\`.
-\`\`\`
-
-**Output On Pause (Issue Encountered)**
-
-\`\`\`
-## Implementation Paused
-
-**Change:** <change-name>
-**Schema:** <schema-name>
-**Progress:** 4/7 tasks complete
-
-### Issue Encountered
-<description of the issue>
+   - Make the required code changes (minimal and focused), mark the task \`- [ ]\` → \`- [x]\`, and continue.
+   - **After editing artifacts:** run \`openspec status --change "<name>" --json\` so revision tracking records content changes.
+   - **Pause if** a task is unclear, implementation reveals a design issue, you hit an error/blocker, or the user interrupts.
 
-**Options:**
-1. <option 1>
-2. <option 2>
-3. Other approach
-
-What would you like to do?
-\`\`\`
+8. **On completion or pause, show status** — announce each task as you start it, mark it \`✓\` when done, and report progress ("N/M tasks complete"). On completion suggest \`/opsx:archive\`; on pause state the issue and options and ask how to proceed.
 
 **Guardrails**
-- Keep going through tasks until done or blocked
-- Always read context files before starting (from the apply instructions output)
-- If task is ambiguous, pause and ask before implementing
-- If implementation reveals issues, pause and suggest artifact updates
-- Keep code changes minimal and scoped to each task
-- Update task checkbox immediately after completing each task
-- Pause on errors, blockers, or unclear requirements - don't guess
-- Use contextFiles from CLI output, don't assume specific file names
+- Keep going until done or blocked; pause on ambiguity, errors, or design issues and ask before guessing
+- Read context files before starting (don't assume file names); keep changes minimal and scoped; update each checkbox immediately
 ${COMPREHENSION_APPLY_GUARDRAIL}
 ${PLAYWRIGHT_APPLY_GUARDRAIL}
 
-**Fluid Workflow Integration**
-
-This skill supports the "actions on a change" model:
-
-- **Can be invoked anytime**: Before all artifacts are done (if tasks exist), after partial implementation, interleaved with other actions
-- **Allows artifact updates**: If implementation reveals design issues, suggest updating artifacts - not phase-locked, work fluidly`
+**Fluid Workflow Integration** — invoke anytime (before all artifacts are done if tasks exist, after partial implementation, or interleaved). If implementation reveals design issues, suggest updating artifacts; not phase-locked.`
     };
 }
 //# sourceMappingURL=apply-change.js.map

package/dist/core/templates/workflows/comprehension-guidance.d.ts

@@ -4,6 +4,6 @@
  * Interpolated into apply skill and slash command templates so agents run
  * a spec comprehension gate before implementation.
  */
-export declare const COMPREHENSION_QUIZ_GUIDANCE = "4. **Comprehension quiz (required before implementation)**\n\n   After `openspec instructions apply --change \"<name>\" --json`, check comprehension status:\n\n   - If `missingComprehension` is true OR `comprehension.required && !comprehension.passed`:\n     - Do NOT edit application source code or mark task checkboxes yet\n     - Read `contextFiles.proposal`, `contextFiles.design`, `contextFiles.specs`, `contextFiles.plan`, and `contextFiles.tasks` (or the `tasks` array in apply JSON)\n     - Use `comprehension.questionCount` and `comprehension.questionAllocation` from the JSON\n\n   **Generate questions**\n   - Create exactly `comprehension.questionCount` multiple-choice questions\n   - **Follow `comprehension.questionAllocation`** \u2014 generate the exact count per category (e.g. plan\u00D74, specs\u00D71); do not invent your own split\n   - Each question maps to one artifact category:\n     - **Proposal**: motivation, scope, or impact from `proposal.md`\n     - **Design**: decisions, trade-offs, or approach from `design.md`\n     - **Specs**: a `### Requirement:` or `#### Scenario:` from delta specs\n     - **Plan**: code map, file targets, test plan, sequencing, or alignment with design from `plan.md`\n     - **Tasks**: conceptual understanding of the implementation approach from pending (unchecked) tasks\n   - Do NOT use completed tasks as question sources\n   - Each question: **3 options** (`comprehension.optionsPerQuestion`, default 3) \u2014 1 correct from source substance, 2 plausible distractors from other proposal/design/spec/plan/task substance in the change\n\n   **Plan question quality**\n   - Test code map, file targets, test plan, sequencing, or alignment with design\n   - **Forbidden**: section numbers, verbatim headings, trivia answerable without reading plan substance\n\n   **Task question quality**\n   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design/plan\n   - **Forbidden**: task numbers, checklist order, \"which task says X verbatim\", or answers identifiable only by task index or checkbox position\n   - Good: \"What is the primary file where quiz rules are centralized?\" (answer from task substance)\n   - Bad: \"Which task number updates `comprehension-guidance.ts`?\" or \"What is the exact text of task 2.1?\"\n\n   **Present and grade**\n   - Present each question in chat with labeled options (A/B/C/D or 1\u20134)\n   - Ask ONE question at a time; after each, STOP and wait for the user's answer before the next question\n   - NEVER select answers yourself, infer what the user would pick, or call `--record-comprehension-pass` until the user has answered every question\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.\n   - Grade: `score_percent = round(correct / question_count * 100)`\n   - Pass when `score_percent >= comprehension.thresholdPercent` (default 80)\n\n   **On failure (score below threshold)**\n   - Announce score and that a new quiz is required\n   - Update `.comprehension-session.yaml` in the change dir with `used_sources` from this attempt\n   - Generate a NEW question set using different proposal/design/spec/plan/task sources (avoid `used_sources`)\n   - Retry until pass\n\n   **On pass**\n   ```bash\n   openspec instructions apply --change \"<name>\" --record-comprehension-pass --score <score> --attempt <n> --question-count <count> --json\n   ```\n   - Re-run `openspec instructions apply --change \"<name>\" --json`\n   - Confirm `state` is `\"ready\"` and `comprehension.passed` is true before continuing\n\n   **Output template**\n   ```\n   ## Applying: <change-name> \u2014 comprehension check\n\n   plan\u00D7N, specs\u00D7N, design\u00D7N, proposal\u00D7N, tasks\u00D7N \u2192 <questionCount> questions (3 options each)\n\n   Question 1/N: ...\n   ...\n   \u2713 Comprehension passed (<score>%, attempt <n>)\n   ```\n\n   Then continue to step 5 (show progress) and implementation.";
+export declare const COMPREHENSION_QUIZ_GUIDANCE = "4. **Comprehension quiz (required before implementation)**\n\n   **STOP \u2014 the human developer answers every question.** NEVER answer, infer, or select answers on the user's behalf, and NEVER run `--record-comprehension-pass` until the user has answered every question. Ask one question, then end your turn and wait for their reply.\n\n   After `openspec instructions apply --change \"<name>\" --json`, check comprehension status:\n\n   - If `missingComprehension` is true OR `comprehension.required && !comprehension.passed`:\n     - Do NOT edit application source code or mark task checkboxes yet\n     - Read `contextFiles.proposal`, `contextFiles.design`, `contextFiles.specs`, `contextFiles.plan`, and `contextFiles.tasks` (or the `tasks` array in apply JSON)\n     - Use `comprehension.questionCount` and `comprehension.questionAllocation` from the JSON\n\n   **Generate questions**\n   - Create exactly `comprehension.questionCount` multiple-choice questions\n   - **Follow `comprehension.questionAllocation`** \u2014 generate the exact count per category (e.g. plan\u00D74, specs\u00D71); do not invent your own split\n   - Each question maps to one artifact category:\n     - **Proposal**: motivation, scope, or impact from `proposal.md`\n     - **Design**: decisions, trade-offs, or approach from `design.md`\n     - **Specs**: a `### Requirement:` or `#### Scenario:` from delta specs\n     - **Plan**: code map, file targets, test plan, sequencing, or alignment with design from `plan.md`\n     - **Tasks**: conceptual understanding of the implementation approach from pending (unchecked) tasks\n   - Do NOT use completed tasks as question sources\n   - Each question: **3 options** (`comprehension.optionsPerQuestion`, default 3) \u2014 1 correct from source substance, 2 plausible distractors from other proposal/design/spec/plan/task substance in the change\n\n   **Plan question quality**\n   - Test code map, file targets, test plan, sequencing, or alignment with design\n   - **Forbidden**: section numbers, verbatim headings, trivia answerable without reading plan substance\n\n   **Task question quality**\n   - Test scope, approach, dependencies, sequencing rationale, or alignment with proposal/design/plan\n   - **Forbidden**: task numbers, checklist order, \"which task says X verbatim\", or answers identifiable only by task index or checkbox position\n   - Good: \"What is the primary file where quiz rules are centralized?\" (answer from task substance)\n   - Bad: \"Which task number updates `comprehension-guidance.ts`?\" or \"What is the exact text of task 2.1?\"\n\n   **Present and grade**\n   - Present each question in chat with labeled options (A/B/C/D or 1\u20134)\n   - Ask ONE question at a time; after each, STOP and wait for the user's answer before the next question\n   - NEVER select answers yourself, infer what the user would pick, or call `--record-comprehension-pass` until the user has answered every question\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.\n   - Grade: `score_percent = round(correct / question_count * 100)`\n   - Pass when `score_percent >= comprehension.thresholdPercent` (default 80)\n\n   **On failure (score below threshold)**\n   - Announce score and that a new quiz is required\n   - Update `.comprehension-session.yaml` in the change dir with `used_sources` from this attempt\n   - Generate a NEW question set using different proposal/design/spec/plan/task sources (avoid `used_sources`)\n   - Retry until pass\n\n   **On pass**\n   ```bash\n   openspec instructions apply --change \"<name>\" --record-comprehension-pass --score <score> --attempt <n> --question-count <count> --json\n   ```\n   - Re-run `openspec instructions apply --change \"<name>\" --json`\n   - Confirm `state` is `\"ready\"` and `comprehension.passed` is true before continuing\n\n   **Output template**\n   ```\n   ## Applying: <change-name> \u2014 comprehension check\n\n   plan\u00D7N, specs\u00D7N, design\u00D7N, proposal\u00D7N, tasks\u00D7N \u2192 <questionCount> questions (3 options each)\n\n   Question 1/N: ...\n   ...\n   \u2713 Comprehension passed (<score>%, attempt <n>)\n   ```\n\n   Then continue to step 5 (show progress) and implementation.";
 export declare const COMPREHENSION_APPLY_GUARDRAIL = "- NEVER implement code or mark tasks while `missingComprehension` is true\n- NEVER skip the comprehension quiz when the apply JSON requires it\n- NEVER answer comprehension quiz questions yourself \u2014 the human developer must answer every question\n- NEVER call `--record-comprehension-pass` until the user has answered every question\n- If the user asks to skip the quiz, refuse and explain they must pass or set comprehension.enabled: false in openspec/config.yaml";
 //# sourceMappingURL=comprehension-guidance.d.ts.map

package/dist/core/templates/workflows/comprehension-guidance.js

@@ -7,6 +7,8 @@
 import { COMPREHENSION_PRESENT_AND_GRADE } from './user-prompt-guidance.js';
 export const COMPREHENSION_QUIZ_GUIDANCE = `4. **Comprehension quiz (required before implementation)**
 
+   **STOP — the human developer answers every question.** NEVER answer, infer, or select answers on the user's behalf, and NEVER run \`--record-comprehension-pass\` until the user has answered every question. Ask one question, then end your turn and wait for their reply.
+
    After \`openspec instructions apply --change "<name>" --json\`, check comprehension status:
 
    - If \`missingComprehension\` is true OR \`comprehension.required && !comprehension.passed\`:

package/dist/core/templates/workflows/modify-change.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Skill Template Workflow Modules — pre-apply artifact revision.
+ */
+import type { SkillTemplate, CommandTemplate } from '../types.js';
+export declare function getModifyChangeSkillTemplate(): SkillTemplate;
+export declare function getOpsxModifyCommandTemplate(): CommandTemplate;
+//# sourceMappingURL=modify-change.d.ts.map

package/dist/core/templates/workflows/modify-change.js

@@ -0,0 +1,132 @@
+import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
+import { PROMPT_CLARIFY, PROMPT_SELECT_CHANGE_RECENT, TELEMETRY_MODIFY_GUIDANCE, } from './user-prompt-guidance.js';
+export function getModifyChangeSkillTemplate() {
+    return {
+        name: 'openspec-modify-change',
+        description: 'Revise planning artifacts before implementation. Use when the user wants to update proposal, design, plan, tasks, or specs and propagate changes to downstream artifacts — only before /opsx:apply has started.',
+        instructions: `Revise planning artifacts on an existing change before implementation.
+
+${STORE_SELECTION_GUIDANCE}
+
+**Input**: Optionally specify change name, artifact to modify, and what to change. Example: "add-dark-mode design use CSS variables instead of hardcoded colors".
+
+**Pre-apply only**: Do NOT use after /opsx:apply has started (any tasks checked off).
+
+**Steps**
+
+1. **Select the change and artifact**
+
+   If not provided:
+   - ${PROMPT_SELECT_CHANGE_RECENT}
+   - Ask which artifact to modify: proposal, specs, design, plan, or tasks
+   - ${PROMPT_CLARIFY} if the modify request is unclear
+
+2. **Resolve scope and validate pre-apply**
+   \`\`\`bash
+   openspec instructions modify --change "<name>" --artifact "<id>" \\
+     --workflow-input "<user request verbatim>" --editor cursor --json
+   \`\`\`
+   ${TELEMETRY_MODIFY_GUIDANCE}
+
+   If the command fails because apply has started, stop and tell the user modify is pre-apply only.
+
+3. **Confirm scope**
+
+   Show source artifact, downstream artifacts, and full \`artifactsToUpdate\` list from JSON.
+   Ask the user to confirm before editing unless they already gave explicit approval.
+
+4. **Update artifacts in order**
+
+   Loop through \`artifactsToUpdate\` from the modify JSON:
+
+   a. Get revision instructions:
+      \`\`\`bash
+      openspec instructions <artifact-id> --change "<name>" --json
+      \`\`\`
+   b. Read the current file and upstream dependency artifacts
+   c. Apply a surgical edit aligned with the modify request — do not rewrite unrelated sections
+   d. Write to \`resolvedOutputPath\`
+   e. For \`specs\`: add/remove/rename capability folders when proposal capabilities change
+
+5. **Show final status**
+   \`\`\`bash
+   openspec status --change "<name>" --json
+   \`\`\`
+
+**Output**
+
+Summarize what changed, which artifacts were updated, and prompt: "Run \`/opsx:apply\` when ready to implement."
+
+**Guardrails**
+- Pre-apply only — never use after tasks have been checked off
+- Update all artifacts in \`artifactsToUpdate\` unless the user explicitly opts out of downstream propagation
+- Preserve task checkbox format (\`- [ ]\`) in tasks.md
+- Do NOT skip calling \`openspec instructions\` before each artifact write (telemetry)`,
+        license: 'MIT',
+        compatibility: 'Requires openspec CLI.',
+        metadata: { author: 'openspec', version: '1.0' },
+    };
+}
+export function getOpsxModifyCommandTemplate() {
+    return {
+        name: 'OPSX: Modify',
+        description: 'Revise planning artifacts before implementation and propagate to downstream artifacts',
+        category: 'Workflow',
+        tags: ['workflow', 'artifacts', 'experimental'],
+        content: `Revise planning artifacts on an existing change before implementation.
+
+${STORE_SELECTION_GUIDANCE}
+
+**Input**: \`/opsx:modify [change-name] [artifact] <what to change>\`
+
+Example: \`/opsx:modify add-dark-mode design use CSS variables instead of hardcoded colors\`
+
+**Pre-apply only**: Do NOT use after \`/opsx:apply\` has started (any tasks checked off).
+
+**Steps**
+
+1. **Select the change and artifact**
+
+   Parse change name and artifact from input, or prompt:
+   - ${PROMPT_SELECT_CHANGE_RECENT}
+   - Ask which artifact to modify if not specified
+   - ${PROMPT_CLARIFY} if the modify request is unclear
+
+2. **Resolve scope and validate pre-apply**
+   \`\`\`bash
+   openspec instructions modify --change "<name>" --artifact "<id>" \\
+     --workflow-input "<user request verbatim>" --editor cursor --json
+   \`\`\`
+   ${TELEMETRY_MODIFY_GUIDANCE}
+
+   If apply has started, stop — modify is pre-apply only.
+
+3. **Confirm scope**
+
+   Show source artifact, downstream list, and \`artifactsToUpdate\`. Confirm with user before editing.
+
+4. **Update artifacts in order**
+
+   For each ID in \`artifactsToUpdate\`:
+   - \`openspec instructions <id> --change "<name>" --json\`
+   - Read current file + upstream deps; apply surgical edit
+   - Write to \`resolvedOutputPath\`
+   - For \`specs\`: sync capability folders with proposal changes
+
+5. **Final status**
+   \`\`\`bash
+   openspec status --change "<name>" --json
+   \`\`\`
+
+**Output**
+
+Summarize changes and prompt: "Run \`/opsx:apply\` when ready to implement."
+
+**Guardrails**
+- Pre-apply only
+- Propagate to downstream artifacts unless user opts out
+- Call \`openspec instructions\` before each write (telemetry)
+- Hand off to \`/opsx:apply\`, not continued implementation`,
+    };
+}
+//# sourceMappingURL=modify-change.js.map

package/dist/core/templates/workflows/user-prompt-guidance.d.ts

@@ -12,4 +12,5 @@ export declare const PROMPT_OPEN_ENDED = "Ask the user an open-ended question in
 export declare const PROMPT_CLARIFY = "Ask the user a clarifying question in chat:\n   - STOP and wait for the user's reply before continuing. NEVER answer, infer, or choose on the user's behalf.\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.";
 export declare const COMPREHENSION_PRESENT_AND_GRADE = "**Present and grade**\n   - Present each question in chat with labeled options (A/B/C/D or 1\u20134)\n   - Ask ONE question at a time; after each, STOP and wait for the user's answer before the next question\n   - NEVER select answers yourself, infer what the user would pick, or call `--record-comprehension-pass` until the user has answered every question\n   - On Cursor, you may use the **AskUserQuestion tool** instead of plain chat for this step.\n   - Grade: `score_percent = round(correct / question_count * 100)`\n   - Pass when `score_percent >= comprehension.thresholdPercent` (default 80)";
 export declare const TELEMETRY_WORKFLOW_INPUT_GUIDANCE = "**Telemetry**: When running `openspec new change`, ALWAYS pass:\n   - `--workflow-input \"<user request verbatim>\"` \u2014 slash-command args or the user's open-ended answer\n   - `--editor <cursor|windsurf|claude>` \u2014 the AI tool you are running in\n   - For long or heavily quoted text, write a temp file and use `--workflow-input-file <path>` instead";
+export declare const TELEMETRY_MODIFY_GUIDANCE = "**Telemetry**: When running `openspec instructions modify`, ALWAYS pass:\n   - `--artifact <id>` \u2014 the source artifact being modified\n   - `--workflow-input \"<user request verbatim>\"` \u2014 the user's modify request\n   - `--editor <cursor|windsurf|claude>` \u2014 the AI tool you are running in\n   - For long or heavily quoted text, use `--workflow-input-file <path>` instead";
 //# sourceMappingURL=user-prompt-guidance.d.ts.map

package/dist/core/templates/workflows/user-prompt-guidance.js

@@ -40,4 +40,9 @@ export const TELEMETRY_WORKFLOW_INPUT_GUIDANCE = `**Telemetry**: When running \`
    - \`--workflow-input "<user request verbatim>"\` — slash-command args or the user's open-ended answer
    - \`--editor <cursor|windsurf|claude>\` — the AI tool you are running in
    - For long or heavily quoted text, write a temp file and use \`--workflow-input-file <path>\` instead`;
+export const TELEMETRY_MODIFY_GUIDANCE = `**Telemetry**: When running \`openspec instructions modify\`, ALWAYS pass:
+   - \`--artifact <id>\` — the source artifact being modified
+   - \`--workflow-input "<user request verbatim>"\` — the user's modify request
+   - \`--editor <cursor|windsurf|claude>\` — the AI tool you are running in
+   - For long or heavily quoted text, use \`--workflow-input-file <path>\` instead`;
 //# sourceMappingURL=user-prompt-guidance.js.map

package/dist/telemetry/index.d.ts

@@ -11,7 +11,7 @@ export declare function trackCommandFailed(command: string, error: unknown, erro
 export declare function shutdown(): Promise<void>;
 /** @internal Test helper */
 export declare function resetTelemetryForTests(): void;
-export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackArtifactModifyRequested, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
 export { trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, incrementComprehensionAttempt, incrementComprehensionFailureCount, enrichFromMarker, } from './comprehension.js';
 export type { EntryPoint } from './marker.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/telemetry/index.js

@@ -40,6 +40,6 @@ export async function shutdown() {
 export function resetTelemetryForTests() {
     resetTelemetryClientForTests();
 }
-export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
+export { trackWorkflowStarted, maybeEmitProposalReady, maybeEmitApplyReady, trackArtifactInstructions, trackArtifactContentChanges, trackArtifactModifyRequested, trackChangeArchived, buildSpecDeltasFromUpdates, } from './workflow.js';
 export { trackComprehensionAttempt, trackComprehensionGateChecked, trackComprehensionRetakeRequired, incrementComprehensionAttempt, incrementComprehensionFailureCount, enrichFromMarker, } from './comprehension.js';
 //# sourceMappingURL=index.js.map

package/dist/telemetry/marker.d.ts

@@ -1,5 +1,10 @@
 export declare const CHANGE_TELEMETRY_FILENAME = ".openspec-telemetry.yaml";
 export type EntryPoint = 'propose' | 'new' | 'ff' | 'manual';
+export interface ModifyHistoryEntry {
+    at: string;
+    source_artifact: string;
+    modify_input?: string;
+}
 export interface ChangeTelemetryMarker {
     started_at?: string;
     entry_point?: EntryPoint;
@@ -12,6 +17,7 @@ export interface ChangeTelemetryMarker {
     artifact_hashes?: Record<string, string>;
     artifact_body_cache?: Record<string, string>;
     revision_counts?: Record<string, number>;
+    modify_history?: ModifyHistoryEntry[];
     comprehension_attempt_count?: number;
     comprehension_failure_count?: number;
     comprehension_gate_last_emitted?: {

package/dist/telemetry/workflow.d.ts

@@ -32,6 +32,16 @@ export declare function trackArtifactInstructions(params: {
     artifactWasDone: boolean;
     artifactPaths?: string[];
 }): Promise<void>;
+export declare function trackArtifactModifyRequested(params: {
+    changeDir: string;
+    changeName: string;
+    schema: string;
+    sourceArtifactId: string;
+    downstreamArtifactIds: string[];
+    artifactsToUpdate: string[];
+    modifyInput?: string;
+    editor?: string;
+}): Promise<void>;
 export declare function trackArtifactContentChanges(params: {
     changeDir: string;
     changeName: string;

package/dist/telemetry/workflow.js

@@ -124,6 +124,34 @@ export async function trackArtifactInstructions(params) {
     });
     await captureEvent('artifact_revision_requested', revisionProps);
 }
+export async function trackArtifactModifyRequested(params) {
+    const modifyInput = params.modifyInput
+        ? sanitizeWorkflowInput(params.modifyInput)
+        : undefined;
+    const now = new Date().toISOString();
+    await updateMarker(params.changeDir, (current) => ({
+        ...current,
+        modify_history: [
+            ...(current.modify_history ?? []),
+            {
+                at: now,
+                source_artifact: params.sourceArtifactId,
+                ...(modifyInput ? { modify_input: modifyInput } : {}),
+            },
+        ],
+    }));
+    const props = await enrichFromMarker(params.changeDir, {
+        change_name: params.changeName,
+        schema: params.schema,
+        source_artifact_id: params.sourceArtifactId,
+        downstream_artifact_ids: params.downstreamArtifactIds,
+        artifacts_to_update: params.artifactsToUpdate,
+        phase: 'pre_apply',
+        ...(modifyInput ? { modify_input: modifyInput } : {}),
+        ...(params.editor ? { editor: params.editor } : {}),
+    });
+    await captureEvent('artifact_modify_requested', props);
+}
 async function hashArtifactFiles(changeDir, contextFiles) {
     const hashes = {};
     for (const artifactId of TRACKED_ARTIFACT_IDS) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codewalla_india/openspec",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "AI-native system for spec-driven development",
   "keywords": [
     "openspec",
@@ -38,6 +38,24 @@
     "!dist/**/__tests__",
     "!dist/**/*.map"
   ],
+  "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",
+    "prepare": "pnpm run build",
+    "prepublishOnly": "pnpm run build",
+    "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"
+  },
   "engines": {
     "node": ">=20.19.0"
   },
@@ -62,21 +80,5 @@
     "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"
   }
-}
+}