@codewalla_india/openspec 1.3.1 → 1.3.3

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

@@ -1,67 +1,166 @@
 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.
+        description: "Modify planning artifacts before implementation starts. Use when the user wants to revise artifacts after they've been created but before implementation begins.",
+        instructions: `Modify planning artifacts before implementation starts.
 
 ${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).
+**Input**: Specify a change name and the artifact to modify (e.g., \`/openspec-modify-change modify-command proposal\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes and artifacts.
 
 **Steps**
 
-1. **Select the change and artifact**
+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, run \`openspec list --json\` to get available changes and ask the user to select one
 
-   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
+   Always announce: "Using change: <name>" and how to override (e.g., \`/openspec-modify-change <other>\`).
 
-2. **Resolve scope and validate pre-apply**
+2. **Check status to understand the schema**
    \`\`\`bash
-   openspec instructions modify --change "<name>" --artifact "<id>" \\
-     --workflow-input "<user request verbatim>" --editor cursor --json
+   openspec status --change "<name>" --json
    \`\`\`
-   ${TELEMETRY_MODIFY_GUIDANCE}
+   Parse the JSON to understand:
+   - \`schemaName\`: The workflow being used (e.g., "spec-driven")
+   - \`planningHome\`, \`changeRoot\`, and \`actionContext\`: planning scope and edit constraints
+   - Which artifacts exist and their completion status
 
-   If the command fails because apply has started, stop and tell the user modify is pre-apply only.
+3. **Validate pre-apply conditions**
 
-3. **Confirm scope**
+   Check if implementation has started by examining the tasks file:
+   - If any tasks are marked as complete (\`- [x]\`), modification is blocked
+   - Explain that modification is only allowed before \`/opsx:apply\` begins
+   - If blocked, suggest creating a new change or using \`/opsx:continue-change\` for artifact updates
 
-   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. **Select the artifact to modify**
 
-4. **Update artifacts in order**
+   If the user specified an artifact, use it. Otherwise:
+   - Show available artifacts from the status output
+   - Ask the user which artifact to modify
+   - Explain that modifying an artifact will also update its dependents
 
-   Loop through \`artifactsToUpdate\` from the modify JSON:
+5. **Get modify instructions**
 
-   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
+   openspec instructions modify --change "<name>" --artifact "<artifact-id>" --json
    \`\`\`
 
-**Output**
+   This returns:
+   - \`artifactsToUpdate\`: list of artifacts that will be updated (direct and propagated)
+   - \`conflicts\`: any conflicts with manual edits (if present, modification is blocked)
+   - Success/failure status
+
+   **Handle states:**
+   - If \`success: false\` with conflicts: show conflicts, explain resolution options
+   - If \`success: false\` with pre-apply error: explain why modification is blocked
+   - If \`success: true\`: proceed with modification
+
+6. **Make the requested changes**
+
+   - Open the artifact file in the editor (if \`--editor\` flag is used)
+   - Make the requested modifications
+   - Save the file
+
+   **Important:** The modify command calculates which artifacts need updating based on the artifact graph. The system will handle:
+   - Direct modification of the specified artifact
+   - Propagation to dependent artifacts (in reverse topological order)
+   - Conflict detection with manual edits
+   - History tracking in the change marker
+
+7. **Verify the changes**
+
+   - Review the modified artifact
+   - If dependents were updated, review those as well
+   - Ensure changes align with the intended modification
+
+8. **Show summary**
+
+   Display:
+   - Artifact modified
+   - Dependent artifacts updated (if any)
+   - Modification history recorded
+   - Next steps (e.g., continue with other artifacts or proceed to apply)
+
+**Output During Modification**
+
+\`\`\`
+## Modifying: <change-name>
+
+**Artifact:** <artifact-id>
+**Dependents to update:** <list of dependent artifacts>
+
+[...modification happening...]
+✓ Modification complete
+\`\`\`
+
+**Output On Success**
+
+\`\`\`
+## Modification Complete
+
+**Change:** <change-name>
+**Artifact modified:** <artifact-id>
+**Dependents updated:** <list>
+
+### History Recorded
+- Timestamp: <timestamp>
+- Modified artifacts: <list>
+- Intent: <user's intent>
+
+**Next steps:**
+- Modify additional artifacts, or
+- Proceed with implementation: \`/opsx:apply-change\`
+\`\`\`
 
-Summarize what changed, which artifacts were updated, and prompt: "Run \`/opsx:apply\` when ready to implement."
+**Output On Block (Pre-apply Validation Failed)**
+
+\`\`\`
+## Modification Blocked
+
+**Change:** <change-name>
+**Reason:** Implementation has started (tasks have been completed)
+
+**Options:**
+1. Use \`/opsx:continue-change\` to update artifacts during implementation
+2. Create a new change for the revision
+3. Proceed with current implementation and address changes in a follow-up
+
+What would you like to do?
+\`\`\`
+
+**Output On Block (Conflicts Detected)**
+
+\`\`\`
+## Modification Blocked
+
+**Change:** <change-name>
+**Artifact:** <artifact-id>
+**Reason:** Conflicts with manual edits
+
+### Conflicts
+- <artifact-id>: <affected sections>
+
+**Options:**
+1. Resolve conflicts manually and retry
+2. Accept manual edits and skip propagation
+3. Revert manual edits and allow propagation
+
+What would you like to do?
+\`\`\`
 
 **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)`,
+- Only allow modification before implementation starts (no completed tasks)
+- Always check for conflicts before modifying
+- Show which dependents will be updated
+- Record modification history in the change marker
+- Preserve manual edits when possible (conflict detection)
+- Explain blocking conditions clearly
+- Do not modify artifacts after implementation has begun
+`,
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',
         metadata: { author: 'openspec', version: '1.0' },
@@ -70,63 +169,86 @@ Summarize what changed, which artifacts were updated, and prompt: "Run \`/opsx:a
 export function getOpsxModifyCommandTemplate() {
     return {
         name: 'OPSX: Modify',
-        description: 'Revise planning artifacts before implementation and propagate to downstream artifacts',
+        description: "Modify a planning artifact before implementation starts - with dependency propagation and conflict detection (Experimental)",
         category: 'Workflow',
         tags: ['workflow', 'artifacts', 'experimental'],
-        content: `Revise planning artifacts on an existing change before implementation.
+        content: `Modify a planning artifact before implementation starts. Only works before implementation begins.
 
 ${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\`
+**Input**: Specify a change name and artifact to modify (e.g., \`/opsx:modify <change-name> --artifact <artifact-id>\`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes and artifacts.
 
-**Pre-apply only**: Do NOT use after \`/opsx:apply\` has started (any tasks checked off).
+\`/opsx:continue\` is an expanded-profile workflow and may not be installed. Before suggesting it anywhere below, verify that it is available. If it is unavailable, \`openspec status --change "<name>" --json\` shows the next artifact and \`openspec instructions "<artifact-id>" --change "<name>" --json\` explains how to create it.
 
 **Steps**
 
-1. **Select the change and artifact**
+1. **Select the change**
 
-   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
+   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, run \`openspec list --json\` to get available changes sorted by most recently modified, and ask the user to select one
+
+   When prompting, present the top 3-4 most recently modified changes as options, showing:
+   - Change name
+   - Schema (from \`schema\` field if present, otherwise "spec-driven")
+   - Status (e.g., "0/5 tasks", "complete", "no tasks")
+   - How recently it was modified (from \`lastModified\` field)
+
+   Mark the most recently modified change as "(Recommended)" since it's likely what the user wants to modify.
+
+   Always announce: "Using change: <name>" and how to override (e.g., \`/opsx:modify <other>\`).
+
+2. **Check pre-apply conditions**
 
-2. **Resolve scope and validate pre-apply**
    \`\`\`bash
-   openspec instructions modify --change "<name>" --artifact "<id>" \\
-     --workflow-input "<user request verbatim>" --editor cursor --json
+   openspec instructions modify --change "<name>" --artifact "<artifact-id>" --json
    \`\`\`
-   ${TELEMETRY_MODIFY_GUIDANCE}
 
-   If apply has started, stop — modify is pre-apply only.
+   This validates that implementation hasn't started by checking tasks.md for completed tasks. If blocked, the command returns an error with the reason.
 
-3. **Confirm scope**
+3. **Review update scope**
 
-   Show source artifact, downstream list, and \`artifactsToUpdate\`. Confirm with user before editing.
+   The command returns a list of artifacts that will be updated in reverse topological order (deepest dependents first). Review this list to understand the impact.
 
-4. **Update artifacts in order**
+4. **Check for conflicts**
 
-   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
+   The command returns any conflicts with manual edits in downstream artifacts. If conflicts exist, modification is blocked and you must resolve them first.
 
-5. **Final status**
-   \`\`\`bash
-   openspec status --change "<name>" --json
-   \`\`\`
+5. **Make the modification**
+
+   - Open the artifact file for editing
+   - Make the requested changes
+   - Save the file
+
+   The modify command will:
+   - Calculate affected artifacts using the artifact graph
+   - Propagate changes to dependents automatically
+   - Record modification history in the change marker
+   - Emit telemetry events
+
+6. **Verify the changes**
+
+   - Review the modified artifact
+   - Review any propagated changes to dependents
+   - Ensure changes align with the intended modification
 
 **Output**
 
-Summarize changes and prompt: "Run \`/opsx:apply\` when ready to implement."
+After modification, show:
+- Artifact modified
+- Dependent artifacts updated (if any)
+- Modification history recorded
+- Next steps (e.g., modify additional artifacts or proceed to apply)
 
 **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`,
+- Modification is blocked if implementation has started (any completed tasks)
+- Modification is blocked if conflicts with manual edits exist
+- Do not modify artifacts after implementation begins
+- Always check for conflicts before modifying
+- Use the artifact ids and paths reported by \`openspec status\`; never branch on hardcoded artifact names
+- The modify command handles dependency propagation automatically - do not manually update dependents
+`,
     };
 }
 //# sourceMappingURL=modify-change.js.map

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

@@ -1,76 +1,72 @@
 import { STORE_SELECTION_GUIDANCE } from './store-selection.js';
-import { PROMPT_OPEN_ENDED, TELEMETRY_WORKFLOW_INPUT_GUIDANCE } from './user-prompt-guidance.js';
 export function getNewChangeSkillTemplate() {
     return {
         name: 'openspec-new-change',
         description: 'Start a new OpenSpec change using the experimental artifact workflow. Use when the user wants to create a new feature, fix, or modification with a structured step-by-step approach.',
-        instructions: `Start a new change using the experimental artifact-driven approach.
-
-${STORE_SELECTION_GUIDANCE}
-
-**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
-
-**Steps**
-
-1. **If no clear input provided, ask what they want to build**
-
-   ${PROMPT_OPEN_ENDED} Ask:
-   > "What change do you want to work on? Describe what you want to build or fix."
-
-   From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
-
-   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
-
-2. **Determine the workflow schema**
-
-   Use the default schema (omit \`--schema\`) unless the user explicitly requests a different workflow.
-
-   **Use a different schema only if the user mentions:**
-   - A specific schema name → use \`--schema <name>\`
-   - "show workflows" or "what workflows" → run \`openspec schemas --json\` and let them choose
-
-   **Otherwise**: Omit \`--schema\` to use the default.
-
-3. **Create the change directory**
-   \`\`\`bash
-   openspec new change "<name>" --entry-point new \
-     --workflow-input "<user request verbatim>" \
-     --editor cursor
-   \`\`\`
-   ${TELEMETRY_WORKFLOW_INPUT_GUIDANCE}
-   Add \`--schema <name>\` only if the user requested a specific workflow.
-   This creates a scaffolded change in the planning home resolved by the CLI.
-
-4. **Show the artifact status**
-   \`\`\`bash
-   openspec status --change "<name>" --json
-   \`\`\`
-   Use the returned \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`nextSteps\` instead of assuming repo-local paths.
-
-5. **Get instructions for the first artifact**
-   The first artifact depends on the schema (e.g., \`proposal\` for spec-driven).
-   Check the status output to find the first artifact with status "ready".
-   \`\`\`bash
-   openspec instructions <first-artifact-id> --change "<name>"
-   \`\`\`
-   This outputs the template and context for creating the first artifact.
-
-6. **STOP and wait for user direction**
-
-**Output**
-
-After completing the steps, summarize:
-- Change name and location
-- Schema/workflow being used and its artifact sequence
-- Current status (0/N artifacts complete)
-- The template for the first artifact
-- Prompt: "Ready to create the first artifact? Just describe what this change is about and I'll draft it, or ask me to continue."
-
-**Guardrails**
-- Do NOT create any artifacts yet - just show the instructions
-- Do NOT advance beyond showing the first artifact template
-- If the name is invalid (not kebab-case), ask for a valid name
-- If a change with that name already exists, suggest continuing that change instead
+        instructions: `Start a new change using the experimental artifact-driven approach.
+
+${STORE_SELECTION_GUIDANCE}
+
+**Input**: The user's request should include a change name (kebab-case) OR a description of what they want to build.
+
+**Steps**
+
+1. **If no clear input provided, ask what they want to build**
+
+   Ask the user (open-ended, no preset options):
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Determine the workflow schema**
+
+   Use the default schema (omit \`--schema\`) unless the user explicitly requests a different workflow.
+
+   **Use a different schema only if the user mentions:**
+   - A specific schema name → use \`--schema <name>\`
+   - "show workflows" or "what workflows" → run \`openspec schemas --json\` and let them choose
+
+   **Otherwise**: Omit \`--schema\` to use the default.
+
+3. **Create the change directory**
+   \`\`\`bash
+   openspec new change "<name>"
+   \`\`\`
+   Add \`--schema <name>\` only if the user requested a specific workflow.
+   This creates a scaffolded change in the planning home resolved by the CLI.
+
+4. **Show the artifact status**
+   \`\`\`bash
+   openspec status --change "<name>" --json
+   \`\`\`
+   Use the returned \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`nextSteps\` instead of assuming repo-local paths.
+
+5. **Get instructions for the first artifact**
+   The first artifact depends on the schema (e.g., \`proposal\` for spec-driven).
+   Check the status output to find the first artifact with status "ready".
+   \`\`\`bash
+   openspec instructions <first-artifact-id> --change "<name>"
+   \`\`\`
+   This outputs the template and context for creating the first artifact.
+
+6. **STOP and wait for user direction**
+
+**Output**
+
+After completing the steps, summarize:
+- Change name and location
+- Schema/workflow being used and its artifact sequence
+- Current status (0/N artifacts complete)
+- The template for the first artifact
+- Prompt: "Ready to create the first artifact? Just describe what this change is about and I'll draft it, or ask me to continue."
+
+**Guardrails**
+- Do NOT create any artifacts yet - just show the instructions
+- Do NOT advance beyond showing the first artifact template
+- If the name is invalid (not kebab-case), ask for a valid name
+- If a change with that name already exists, suggest continuing that change instead
 - Pass --schema if using a non-default workflow`,
         license: 'MIT',
         compatibility: 'Requires openspec CLI.',
@@ -83,72 +79,69 @@ export function getOpsxNewCommandTemplate() {
         description: 'Start a new change using the experimental artifact workflow (OPSX)',
         category: 'Workflow',
         tags: ['workflow', 'artifacts', 'experimental'],
-        content: `Start a new change using the experimental artifact-driven approach.
-
-${STORE_SELECTION_GUIDANCE}
-
-**Input**: The argument after \`/opsx:new\` is the change name (kebab-case), OR a description of what the user wants to build.
-
-**Steps**
-
-1. **If no input provided, ask what they want to build**
-
-   ${PROMPT_OPEN_ENDED} Ask:
-   > "What change do you want to work on? Describe what you want to build or fix."
-
-   From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
-
-   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
-
-2. **Determine the workflow schema**
-
-   Use the default schema (omit \`--schema\`) unless the user explicitly requests a different workflow.
-
-   **Use a different schema only if the user mentions:**
-   - A specific schema name → use \`--schema <name>\`
-   - "show workflows" or "what workflows" → run \`openspec schemas --json\` and let them choose
-
-   **Otherwise**: Omit \`--schema\` to use the default.
-
-3. **Create the change directory**
-   \`\`\`bash
-   openspec new change "<name>" --entry-point new \
-     --workflow-input "<user request verbatim>" \
-     --editor cursor
-   \`\`\`
-   ${TELEMETRY_WORKFLOW_INPUT_GUIDANCE}
-   Add \`--schema <name>\` only if the user requested a specific workflow.
-   This creates a scaffolded change in the planning home resolved by the CLI.
-
-4. **Show the artifact status**
-   \`\`\`bash
-   openspec status --change "<name>" --json
-   \`\`\`
-   Use the returned \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`nextSteps\` instead of assuming repo-local paths.
-
-5. **Get instructions for the first artifact**
-   The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".
-   \`\`\`bash
-   openspec instructions <first-artifact-id> --change "<name>"
-   \`\`\`
-   This outputs the template and context for creating the first artifact.
-
-6. **STOP and wait for user direction**
-
-**Output**
-
-After completing the steps, summarize:
-- Change name and location
-- Schema/workflow being used and its artifact sequence
-- Current status (0/N artifacts complete)
-- The template for the first artifact
-- Prompt: "Ready to create the first artifact? Run \`/opsx:continue\` or just describe what this change is about and I'll draft it."
-
-**Guardrails**
-- Do NOT create any artifacts yet - just show the instructions
-- Do NOT advance beyond showing the first artifact template
-- If the name is invalid (not kebab-case), ask for a valid name
-- If a change with that name already exists, suggest using \`/opsx:continue\` instead
+        content: `Start a new change using the experimental artifact-driven approach.
+
+${STORE_SELECTION_GUIDANCE}
+
+**Input**: The argument after \`/opsx:new\` is the change name (kebab-case), OR a description of what the user wants to build.
+
+**Steps**
+
+1. **If no input provided, ask what they want to build**
+
+   Ask the user (open-ended, no preset options):
+   > "What change do you want to work on? Describe what you want to build or fix."
+
+   From their description, derive a kebab-case name (e.g., "add user authentication" → \`add-user-auth\`).
+
+   **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
+
+2. **Determine the workflow schema**
+
+   Use the default schema (omit \`--schema\`) unless the user explicitly requests a different workflow.
+
+   **Use a different schema only if the user mentions:**
+   - A specific schema name → use \`--schema <name>\`
+   - "show workflows" or "what workflows" → run \`openspec schemas --json\` and let them choose
+
+   **Otherwise**: Omit \`--schema\` to use the default.
+
+3. **Create the change directory**
+   \`\`\`bash
+   openspec new change "<name>"
+   \`\`\`
+   Add \`--schema <name>\` only if the user requested a specific workflow.
+   This creates a scaffolded change in the planning home resolved by the CLI.
+
+4. **Show the artifact status**
+   \`\`\`bash
+   openspec status --change "<name>" --json
+   \`\`\`
+   Use the returned \`planningHome\`, \`changeRoot\`, \`artifactPaths\`, and \`nextSteps\` instead of assuming repo-local paths.
+
+5. **Get instructions for the first artifact**
+   The first artifact depends on the schema. Check the status output to find the first artifact with status "ready".
+   \`\`\`bash
+   openspec instructions <first-artifact-id> --change "<name>"
+   \`\`\`
+   This outputs the template and context for creating the first artifact.
+
+6. **STOP and wait for user direction**
+
+**Output**
+
+After completing the steps, summarize:
+- Change name and location
+- Schema/workflow being used and its artifact sequence
+- Current status (0/N artifacts complete)
+- The template for the first artifact
+- Prompt: "Ready to create the first artifact? Run \`/opsx:continue\` or just describe what this change is about and I'll draft it."
+
+**Guardrails**
+- Do NOT create any artifacts yet - just show the instructions
+- Do NOT advance beyond showing the first artifact template
+- If the name is invalid (not kebab-case), ask for a valid name
+- If a change with that name already exists, suggest using \`/opsx:continue\` instead
 - Pass --schema if using a non-default workflow`
     };
 }