Skip to content

feat(skills): add change complexity tier assessment to propose and new workflows #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marcoskichel wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat(skills): add change complexity tier assessment to propose and new workflows #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 42 additions & 10 deletions src/core/templates/workflows/new-change.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,38 +25,54 @@ 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 <name>\`
- "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 "<name>"
\`\`\`
Add \`--schema <name>\` only if the user requested a specific workflow.
This creates a scaffolded change at \`openspec/changes/<name>/\` with the selected schema.

4. **Show the artifact status**
5. **Show the artifact status**
\`\`\`bash
openspec status --change "<name>"
\`\`\`
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
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**
7. **STOP and wait for user direction**

**Output**

Expand Down Expand Up @@ -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 <name>\`
- "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 "<name>"
\`\`\`
Add \`--schema <name>\` only if the user requested a specific workflow.
This creates a scaffolded change at \`openspec/changes/<name>/\` with the selected schema.

4. **Show the artifact status**
5. **Show the artifact status**
\`\`\`bash
openspec status --change "<name>"
\`\`\`
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 <first-artifact-id> --change "<name>"
\`\`\`
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**

Expand Down
58 changes: 44 additions & 14 deletions src/core/templates/workflows/propose.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <name>\` 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
Expand All @@ -43,32 +58,32 @@ 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 \`<workspace>\`. Continue to step 3.
- If **single scope**: ask which scope (show list from workspace.yaml). Store as \`<workspace>\`. Continue to step 4.
- If **cross-scope (umbrella)**: jump to **Umbrella Flow** section below.

If no workspace.yaml (single-project):
- \`<workspace>\` is the current directory. Skip to step 3.
- \`<workspace>\` is the current directory. Skip to step 4.

All \`openspec\` commands must be run as:
\`\`\`bash
(cd <workspace> && openspec ...)
\`\`\`

3. **Create the change directory**
4. **Create the change directory**
\`\`\`bash
(cd <workspace> && openspec new change "<name>")
\`\`\`
This creates a scaffolded change at \`<workspace>/openspec/changes/<name>/\` with \`.openspec.yaml\`.

4. **Get the artifact build order**
5. **Get the artifact build order**
\`\`\`bash
(cd <workspace> && openspec status --change "<name>" --json)
\`\`\`
Parse the JSON to get:
- \`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.

Expand Down Expand Up @@ -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 <workspace> && openspec status --change "<name>")
\`\`\`
Expand Down Expand Up @@ -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 <name>\` 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
Expand All @@ -199,32 +229,32 @@ 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 \`<workspace>\`. Continue to step 3.
- If **single scope**: ask which scope (show list from workspace.yaml). Store as \`<workspace>\`. Continue to step 4.
- If **cross-scope (umbrella)**: jump to **Umbrella Flow** section below.

If no workspace.yaml (single-project):
- \`<workspace>\` is the current directory. Skip to step 3.
- \`<workspace>\` is the current directory. Skip to step 4.

All \`openspec\` commands must be run as:
\`\`\`bash
(cd <workspace> && openspec ...)
\`\`\`

3. **Create the change directory**
4. **Create the change directory**
\`\`\`bash
(cd <workspace> && openspec new change "<name>")
\`\`\`
This creates a scaffolded change at \`<workspace>/openspec/changes/<name>/\` with \`.openspec.yaml\`.

4. **Get the artifact build order**
5. **Get the artifact build order**
\`\`\`bash
(cd <workspace> && openspec status --change "<name>" --json)
\`\`\`
Parse the JSON to get:
- \`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.

Expand Down Expand Up @@ -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 <workspace> && openspec status --change "<name>")
\`\`\`
Expand Down