agentleFS
Sign inStart free
feimacodefeimacode/open-design-agent-kit/.claude/skills/openspec-propose/SKILL.md

openspec-propose

Skill678 starsChanged yesterdayMITView 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 129 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 129 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)

Does it work?

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

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

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