From c4787c221af31a0c75148697e6314162a1cd79d4 Mon Sep 17 00:00:00 2001 From: Marcos Kichel Date: Tue, 31 Mar 2026 17:53:14 -0300 Subject: [PATCH] feat(skills): add change complexity tier assessment to propose and new workflows Add a tier assessment step (step 2) to /opsx:propose and /opsx:new that classifies each change before creating any artifacts: - Tier A (trivial): warns user a direct PR is sufficient, asks confirmation - Tier B (small): suggests a lightweight schema, queries available schemas - Tier C (meaningful): proceeds silently with full workflow Prevents overhead for low-risk changes while preserving full rigor for behavior changes, API/contract, migrations, and cross-team work. --- src/core/templates/workflows/new-change.ts | 52 +++++++++++++++---- src/core/templates/workflows/propose.ts | 58 ++++++++++++++++------ 2 files changed, 86 insertions(+), 24 deletions(-) diff --git a/src/core/templates/workflows/new-change.ts b/src/core/templates/workflows/new-change.ts index 10017422f..b3b07a39c 100644 --- a/src/core/templates/workflows/new-change.ts +++ b/src/core/templates/workflows/new-change.ts @@ -25,30 +25,46 @@ export function getNewChangeSkillTemplate(): SkillTemplate { **IMPORTANT**: Do NOT proceed without understanding what the user wants to build. -2. **Determine the workflow schema** +2. **Assess change complexity — recommend the right tier** + + Based on the description, classify the change: + + | Tier | When to use | Signals | + |------|-------------|---------| + | A – Direct PR | Trivial change | Typo, formatting, comment-only, non-semantic refactor with obvious intent | + | B – Lightweight OpenSpec | Small, low-risk | Minor UX/config tweak, refactor with preserved behavior; no API, data, or security impact | + | C – Full OpenSpec | Meaningful change | Behavior change, API/contract, migration, security/privacy, cross-team, multi-iteration | + + **Act on the tier before proceeding:** + - **Tier A**: Tell the user: "This looks like a trivial change — a direct PR is probably sufficient. OpenSpec may be overkill here. Do you still want to create a change?" Use **AskUserQuestion** to confirm. Stop if they decline. + - **Tier B**: Tell the user: "This is a small change. A lightweight schema (proposal + tasks only) would reduce overhead. Want me to pick a lightweight schema, or proceed with the default?" Use **AskUserQuestion**. If lightweight: run \`openspec schemas --json\` to find a minimal schema and suggest it. If full: proceed normally. + - **Tier C**: Proceed without prompting. + +3. **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 \` - "show workflows" or "what workflows" → run \`openspec schemas --json\` and let them choose + - A lightweight tier was chosen in step 2 → use the schema selected there **Otherwise**: Omit \`--schema\` to use the default. -3. **Create the change directory** +4. **Create the change directory** \`\`\`bash openspec new change "" \`\`\` Add \`--schema \` only if the user requested a specific workflow. This creates a scaffolded change at \`openspec/changes//\` with the selected schema. -4. **Show the artifact status** +5. **Show the artifact status** \`\`\`bash openspec status --change "" \`\`\` This shows which artifacts need to be created and which are ready (dependencies satisfied). -5. **Get instructions for the first artifact** +6. **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 @@ -56,7 +72,7 @@ export function getNewChangeSkillTemplate(): SkillTemplate { \`\`\` This outputs the template and context for creating the first artifact. -6. **STOP and wait for user direction** +7. **STOP and wait for user direction** **Output** @@ -100,37 +116,53 @@ export function getOpsxNewCommandTemplate(): CommandTemplate { **IMPORTANT**: Do NOT proceed without understanding what the user wants to build. -2. **Determine the workflow schema** +2. **Assess change complexity — recommend the right tier** + + Based on the description, classify the change: + + | Tier | When to use | Signals | + |------|-------------|---------| + | A – Direct PR | Trivial change | Typo, formatting, comment-only, non-semantic refactor with obvious intent | + | B – Lightweight OpenSpec | Small, low-risk | Minor UX/config tweak, refactor with preserved behavior; no API, data, or security impact | + | C – Full OpenSpec | Meaningful change | Behavior change, API/contract, migration, security/privacy, cross-team, multi-iteration | + + **Act on the tier before proceeding:** + - **Tier A**: Tell the user: "This looks like a trivial change — a direct PR is probably sufficient. OpenSpec may be overkill here. Do you still want to create a change?" Use **AskUserQuestion** to confirm. Stop if they decline. + - **Tier B**: Tell the user: "This is a small change. A lightweight schema (proposal + tasks only) would reduce overhead. Want me to pick a lightweight schema, or proceed with the default?" Use **AskUserQuestion**. If lightweight: run \`openspec schemas --json\` to find a minimal schema and suggest it. If full: proceed normally. + - **Tier C**: Proceed without prompting. + +3. **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 \` - "show workflows" or "what workflows" → run \`openspec schemas --json\` and let them choose + - A lightweight tier was chosen in step 2 → use the schema selected there **Otherwise**: Omit \`--schema\` to use the default. -3. **Create the change directory** +4. **Create the change directory** \`\`\`bash openspec new change "" \`\`\` Add \`--schema \` only if the user requested a specific workflow. This creates a scaffolded change at \`openspec/changes//\` with the selected schema. -4. **Show the artifact status** +5. **Show the artifact status** \`\`\`bash openspec status --change "" \`\`\` This shows which artifacts need to be created and which are ready (dependencies satisfied). -5. **Get instructions for the first artifact** +6. **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 --change "" \`\`\` This outputs the template and context for creating the first artifact. -6. **STOP and wait for user direction** +7. **STOP and wait for user direction** **Output** diff --git a/src/core/templates/workflows/propose.ts b/src/core/templates/workflows/propose.ts index 09395935c..f00ea7c6a 100644 --- a/src/core/templates/workflows/propose.ts +++ b/src/core/templates/workflows/propose.ts @@ -34,7 +34,22 @@ When ready to implement, run /opsx:apply **IMPORTANT**: Do NOT proceed without understanding what the user wants to build. -2. **Determine if this is a single-scope or cross-scope change** +2. **Assess change complexity — recommend the right tier** + + Based on the description, classify the change: + + | Tier | When to use | Signals | + |------|-------------|---------| + | A – Direct PR | Trivial change | Typo, formatting, comment-only, non-semantic refactor with obvious intent | + | B – Lightweight OpenSpec | Small, low-risk | Minor UX/config tweak, refactor with preserved behavior; no API, data, or security impact | + | C – Full OpenSpec | Meaningful change | Behavior change, API/contract, migration, security/privacy, cross-team, multi-iteration | + + **Act on the tier before proceeding:** + - **Tier A**: Tell the user: "This looks like a trivial change — a direct PR is probably sufficient. OpenSpec may be overkill here. Do you still want to create a full change proposal?" Use **AskUserQuestion** to confirm. Stop if they decline. + - **Tier B**: Tell the user: "This is a small change. A lightweight schema (proposal + tasks only) would reduce overhead. Want me to use a lightweight approach, or proceed with the full workflow?" Use **AskUserQuestion**. If lightweight: run \`openspec schemas --json\` to find a minimal schema and pass \`--schema \` when creating the change. If full: proceed normally. + - **Tier C**: Proceed without prompting. + +3. **Determine if this is a single-scope or cross-scope change** Check for a workspace manifest: \`\`\`bash @@ -43,24 +58,24 @@ When ready to implement, run /opsx:apply If workspace.yaml exists: - Based on the description, ask: "Does this change touch more than one scope?" - - If **single scope**: ask which scope (show list from workspace.yaml). Store as \`\`. Continue to step 3. + - If **single scope**: ask which scope (show list from workspace.yaml). Store as \`\`. Continue to step 4. - If **cross-scope (umbrella)**: jump to **Umbrella Flow** section below. If no workspace.yaml (single-project): - - \`\` is the current directory. Skip to step 3. + - \`\` is the current directory. Skip to step 4. All \`openspec\` commands must be run as: \`\`\`bash (cd && openspec ...) \`\`\` -3. **Create the change directory** +4. **Create the change directory** \`\`\`bash (cd && openspec new change "") \`\`\` This creates a scaffolded change at \`/openspec/changes//\` with \`.openspec.yaml\`. -4. **Get the artifact build order** +5. **Get the artifact build order** \`\`\`bash (cd && openspec status --change "" --json) \`\`\` @@ -68,7 +83,7 @@ When ready to implement, run /opsx:apply - \`applyRequires\`: array of artifact IDs needed before implementation (e.g., \`["tasks"]\`) - \`artifacts\`: list of all artifacts with their status and dependencies -5. **Create artifacts in sequence until apply-ready** +6. **Create artifacts in sequence until apply-ready** Use the **TodoWrite tool** to track progress through the artifacts. @@ -100,7 +115,7 @@ When ready to implement, run /opsx:apply - Use **AskUserQuestion tool** to clarify - Then continue with creation -6. **Show final status** +7. **Show final status** \`\`\`bash (cd && openspec status --change "") \`\`\` @@ -190,7 +205,22 @@ When ready to implement, run /opsx:apply **IMPORTANT**: Do NOT proceed without understanding what the user wants to build. -2. **Determine if this is a single-scope or cross-scope change** +2. **Assess change complexity — recommend the right tier** + + Based on the description, classify the change: + + | Tier | When to use | Signals | + |------|-------------|---------| + | A – Direct PR | Trivial change | Typo, formatting, comment-only, non-semantic refactor with obvious intent | + | B – Lightweight OpenSpec | Small, low-risk | Minor UX/config tweak, refactor with preserved behavior; no API, data, or security impact | + | C – Full OpenSpec | Meaningful change | Behavior change, API/contract, migration, security/privacy, cross-team, multi-iteration | + + **Act on the tier before proceeding:** + - **Tier A**: Tell the user: "This looks like a trivial change — a direct PR is probably sufficient. OpenSpec may be overkill here. Do you still want to create a full change proposal?" Use **AskUserQuestion** to confirm. Stop if they decline. + - **Tier B**: Tell the user: "This is a small change. A lightweight schema (proposal + tasks only) would reduce overhead. Want me to use a lightweight approach, or proceed with the full workflow?" Use **AskUserQuestion**. If lightweight: run \`openspec schemas --json\` to find a minimal schema and pass \`--schema \` when creating the change. If full: proceed normally. + - **Tier C**: Proceed without prompting. + +3. **Determine if this is a single-scope or cross-scope change** Check for a workspace manifest: \`\`\`bash @@ -199,24 +229,24 @@ When ready to implement, run /opsx:apply If workspace.yaml exists: - Based on the description, ask: "Does this change touch more than one scope?" - - If **single scope**: ask which scope (show list from workspace.yaml). Store as \`\`. Continue to step 3. + - If **single scope**: ask which scope (show list from workspace.yaml). Store as \`\`. Continue to step 4. - If **cross-scope (umbrella)**: jump to **Umbrella Flow** section below. If no workspace.yaml (single-project): - - \`\` is the current directory. Skip to step 3. + - \`\` is the current directory. Skip to step 4. All \`openspec\` commands must be run as: \`\`\`bash (cd && openspec ...) \`\`\` -3. **Create the change directory** +4. **Create the change directory** \`\`\`bash (cd && openspec new change "") \`\`\` This creates a scaffolded change at \`/openspec/changes//\` with \`.openspec.yaml\`. -4. **Get the artifact build order** +5. **Get the artifact build order** \`\`\`bash (cd && openspec status --change "" --json) \`\`\` @@ -224,7 +254,7 @@ When ready to implement, run /opsx:apply - \`applyRequires\`: array of artifact IDs needed before implementation (e.g., \`["tasks"]\`) - \`artifacts\`: list of all artifacts with their status and dependencies -5. **Create artifacts in sequence until apply-ready** +6. **Create artifacts in sequence until apply-ready** Use the **TodoWrite tool** to track progress through the artifacts. @@ -256,7 +286,7 @@ When ready to implement, run /opsx:apply - Use **AskUserQuestion tool** to clarify - Then continue with creation -6. **Show final status** +7. **Show final status** \`\`\`bash (cd && openspec status --change "") \`\`\`