agentleFS
Sign inStart free
Microsoft AzureKnown publisherAzure/azure-cosmos-dotnet-v3/.github/skills/openspec-propose/SKILL.md

openspec-propose

Skill798 starsChanged 6 months agoMITView on GitHub

Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.

We split this skill into the rules it gives an agent

20 rules. 5 are common, 7 are distinctive, and 8 are very specific to this project.

  • 5

    Common

    Most of the 127 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    When ready to implement, run /opsx:apply

    line 19
  2. Distinctive:

    Use the AskUserQuestion tool (open-ended, no preset options) to ask:

    line 29
  3. Common:

    IMPORTANT: Do NOT proceed without understanding what the user wants to build.

    line 34
  4. Distinctive:

    Use the TodoWrite tool to track progress through the artifacts.

    line 52
  5. Distinctive:

    Read any completed dependency files for context

    line 68
  6. Very specific:

    Create the artifact file using template as the structure

    line 69
  7. Very specific:

    After creating each artifact, re-run openspec status --change "<name>" --json

    line 74
  8. Very specific:

    Check if every artifact ID in applyRequires has status: "done" in the artifacts array

    line 75
  9. Very specific:

    Stop when all applyRequires artifacts are done

    line 76
  10. Distinctive:

    Use AskUserQuestion tool to clarify

    line 79
  11. Common:

    After completing all artifacts, summarize:

    line 89
  12. Very specific:

    Follow the instruction field from openspec instructions for each artifact type

    line 97
  13. Common:

    Read dependency artifacts for context before creating new ones

    line 99
  14. Very specific:

    Use template as the structure for your output file - fill in its sections

    line 100
  15. Very specific:

    Do NOT copy <context>, <rules>, <project_context> blocks into the artifact

    line 102
  16. Very specific:

    Create ALL artifacts needed for implementation (as defined by schema's apply.requires)

    line 106
  17. Distinctive:

    Always read dependency artifacts before creating a new one

    line 107
  18. Distinctive:

    If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum

    line 108
  19. Common:

    If a change with that name already exists, ask if user wants to continue it or create a new one

    line 109
  20. Common:

    Verify each artifact file exists after writing before proceeding to next

    line 110

“Common” is measured: kept by at least 6 in 10 of the 127 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Propose a new change - create the change and generate all artifacts in one step.

I'll create a change with artifacts:

  • proposal.md (what & why)
  • design.md (how)
  • tasks.md (implementation steps)

When ready to implement, run /opsx:apply

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. Create the change directory
    openspec new change "<name>"
    This creates a scaffolded change at openspec/changes/<name>/ with .openspec.yaml.
  3. Get the artifact build order
    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

  4. Create artifacts in sequence until apply-ready

    Use the TodoWrite tool to track progress through the artifacts.

    Loop through artifacts in dependency order (artifacts with no pending dependencies first):

    a. For each artifact that is ready (dependencies satisfied):

    • Get instructions:
      openspec instructions <artifact-id> --change "<name>" --json
    • The instructions JSON includes:
      • context: Project background (constraints for you - do NOT include in output)
      • rules: Artifact-specific rules (constraints for you - do NOT include in output)
      • template: The structure to use for your output file
      • instruction: Schema-specific guidance for this artifact type
      • outputPath: Where to write the artifact
      • dependencies: Completed artifacts to read for context
    • Read any completed dependency files for context
    • Create the artifact file using template as the structure
    • Apply context and rules as constraints - but do NOT copy them into the file
    • Show brief progress: "Created <artifact-id>"

    b. Continue until all applyRequires artifacts are complete

    • After creating each artifact, re-run openspec status --change "<name>" --json
    • Check if every artifact ID in applyRequires has status: "done" in the artifacts array
    • Stop when all applyRequires artifacts are done

    c. If an artifact requires user input (unclear context):

    • Use AskUserQuestion tool to clarify
    • Then continue with creation
  5. Show final status
    openspec status --change "<name>"

Output

After completing all artifacts, summarize:

  • Change name and location
  • List of artifacts created with brief descriptions
  • What's ready: "All artifacts created! Ready for implementation."
  • Prompt: "Run /opsx:apply or ask me to implement to start working on the tasks."

Artifact Creation Guidelines

  • Follow the instruction field from openspec instructions for each artifact type
  • The schema defines what each artifact should contain - follow it
  • Read dependency artifacts for context before creating new ones
  • Use template as the structure for your output file - fill in its sections
  • IMPORTANT: context and rules are constraints for YOU, not content for the file
    • Do NOT copy <context>, <rules>, <project_context> blocks into the artifact
    • These guide what you write, but should never appear in the output

Guardrails

  • Create ALL artifacts needed for implementation (as defined by schema's apply.requires)
  • Always read dependency artifacts before creating a new one
  • If context is critically unclear, ask the user - but prefer making reasonable decisions to keep momentum
  • If a change with that name already exists, ask if user wants to continue it or create a new one
  • Verify each artifact file exists after writing before proceeding to next

Download now (ZIP)

  • Other versions167 projects use a version of this.

    Word for word · 37

    1. akkadotnet/akka.net★ 5.1k100% same
    2. moka-rs/moka★ 2.7k100% same
    3. dotnetfactory/fluid-calendar★ 996100% same
    4. yaoyao2mm/cheatreader★ 655100% same
    5. atilladeniz/Kubeli★ 387100% same
    6. lis186/ccxray★ 295100% same
    7. zhe-qi/clhoria-template★ 193100% same
    8. webspatial/webspatial-sdk★ 153100% same
    9. hiromaily/go-crypto-wallet★ 128100% same
    10. Happenmass/omux★ 94100% same

    27 more not listed

    Edited · 127

    1. Fission-AI/OpenSpec★ 74k16% same
    2. halo-dev/halo★ 40k79% same
    3. gogf/gf★ 13k100% same
    4. databasus/databasus★ 9.2k25% same
    5. RostislavDugin/postgresus★ 9.1k24% same
    6. fonoster/fonoster★ 8.1k91% same
    7. fleetdm/fleet★ 7.1k99% same
    8. KunAgent/Kun★ 6.3k99% same
    9. XingYu-Zhong/DeepSeek-GUI★ 6.3k99% same
    10. aiogram/aiogram★ 5.9k79% same

    117 more not listed

    Wrote their own version · 3

    1. studyzy/OpenSpec-cn★ 1.2ksame name
    2. henhen6/mdp★ 133same name
    3. beautifulSoup/speccoding-template★ 62same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

  • Used alongsideProjects with it also use source-command-opsx-apply, source-command-opsx-archive and 10 more.

    Other files people use alongside this one.

    Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
    • antech2-asyncSkill

      source-command-opsx-apply

      Implement tasks from an OpenSpec change (Experimental)

      Also in 5 projects that use this

    • antech2-asyncSkill

      source-command-opsx-archive

      Archive a completed change in the experimental workflow

      Also in 5 projects that use this

    • Microsoft AzureSkill

      openspec-update-change

      Update an OpenSpec change by revising its existing planning artifacts and keeping them coherent with one another. Use when the user wants to revise a change's plan, fold new decisions into it, or reconcile its artifacts after an edit. Never edits code.

      Also in 70 projects that use this

    • studyzySkill

      draft-openspec-docs

      OpenSpec 文档的协作式页面起草模式。在目标页面内部构建一份草稿计划（目的、结构、编号起草步骤），与用户一起迭代，然后按已批准的步骤逐章节起草，并在完成后清理自身。在页面需要从头重写，或一个新区块需要用户参与塑形时使用。

      Also in 3 projects that use this

    • studyzySkill

      release-openspec

      Use this skill when releasing OpenSpec: audit merged work and changeset coverage, decide whether a catch-up changeset PR is needed, prepare or resume the Changesets Version Packages PR, cut a beta or stable release, verify publishing, and polish GitHub release notes. Also use when asked whether an open release PR is complete, what the next release step is, or to continue a release paused for human approval.

      Also in 3 projects that use this

    • ElasticSkill

      openspec-verify-change

      Verify implementation matches change artifacts. Use when the user wants to validate that implementation is complete, correct, and coherent before archiving.

      Also in 39 projects that use this

    • +2 more from antech2-async
    • +2 more from studyzy
  • In this repository4 other files it gives its agents.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free