keboss/openspec-zcode
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
163483eb50
openspec-zcode/skills/openspec-new-change/SKILL.md
keboss-m 163483eb50 feat: initial OpenSpec skills + /opsx commands for ZCode 
Port of @fission-ai/openspec@1.4.1 workflow templates into ZCode-native
skills and slash commands.

- 11 skills (skills/openspec-*/SKILL.md): auto-trigger + /skill force-load
- 11 commands (commands/opsx/*.md): /opsx:explore, /opsx:propose, /opsx:apply,
  /opsx:sync, /opsx:archive, /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify,
  /opsx:bulk-archive, /opsx:onboard
- install.sh / install.ps1 (idempotent, copies to ~/.zcode/)
- uninstall.sh / uninstall.ps1
- README.md with command table, install/update/uninstall, upstream mapping

Skill instruction text is ported verbatim from the upstream
get…SkillTemplate().instructions fields, with three ZCode adaptations:
1. /opsx:<cmd> cross-refs inside skill bodies → /skill openspec-<name>
2. Task tool → Agent tool (one occurrence in openspec-archive-change)
3. Source-version comment header in each SKILL.md
2026-07-06 15:36:43 +03:00

3.0 KiB
Raw Blame History

name description
openspec-new-change 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, scaffold a new change folder and step through artifacts one at a time.

Start a new change using the experimental artifact-driven approach.

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

    Use the AskUserQuestion tool (open-ended, no preset options) to 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

    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

    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".

    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