Skip to content

rse/ase / plugin/skills/ase-spec-edit

ase-spec-edit

Verified

Edit Specification: Use when the user wants to "edit" the SpecBook-based specification (SPEC) in one shot from a query, with optional grilling, SpecBook validation, looping, and Git worktree isolation.

@${CLAUDE_SKILL_DIR}/../../meta/ase-control.md @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md

$ARGUMENTS

@${CLAUDE_SKILL_DIR}/../../meta/ase-format-meta.md @${CLAUDE_SKILL_DIR}/../../meta/ase-format-spec.md @${CLAUDE_SKILL_DIR}/../../meta/ase-tenets.md @${CLAUDE_SKILL_DIR}/../../meta/ase-common-ground.md @${CLAUDE_SKILL_DIR}/../../meta/ase-common-grill.md @${CLAUDE_SKILL_DIR}/../../meta/ase-common-changeset.md @${CLAUDE_SKILL_DIR}/../../meta/ase-common-approach.md

Procedure

This skill is plan-less: it never composes or persists a task plan and MUST NOT call ase_task_save(...). Instead, it applies the requested edit in place, so the implementing state requires Edit and Write to modify the affected artifacts. Every modification MUST stay restricted to the SPEC artifacts the edit actually demands -- the kinds CODE, DOCS, TASK, INFR, and OTHR are never touched, except for an entry in an already existing CHANGELOG.md file.

On finishing the state <arg1/>, only output the following , which shows the established and , where a still empty or renders as (none):

WHAT:

HOW:

  1. Initialize:

    1. Set (with any leading and trailing whitespace stripped), set and (both empty), and set (empty). If is true, set true, as --grill-auto implies --grill. Do not output anything.

    2. If is not a positive integer, only output the following and then immediately STOP processing the entire current skill:

    3. Resolve a potentially misparsed former boolean --worktree option:

  2. Iterate:

    Perform the states (1) querying, (2) discovering, (3) grilling, (4) implementing, and (5) verifying below as one iteration. Without --loop perform exactly one iteration. Under --loop repeat the iteration until the querying state receives a STOP SKILL result. Do not output anything in this item.

  3. State: querying:

      1. In the following, you MUST NOT use your built-in tool! Instead, you MUST just show a custom dialog according to the expanded custom-dialog definition. You MUST closely follow this definition. Its only answer option is the fixed STOP SKILL, so the user normally answers with the edit query in one free-text reply:

      2. If is STOP SKILL or CANCEL, only output the following and then immediately STOP processing the entire current skill:

        Otherwise, strip any leading OTHER: prefix from and set to the remainder.

    1. Convert the fresh into -- the domain-specific, non-implementation-detail information -- and -- the remaining information -- discarding all / content of any previous iteration. Without --grill or --approach you MUST NOT ask any clarifying questions and during later implementation just interpret the query best-effort. Do not output anything.

    2. Expand the following:

    3. Set (clear the query, so every further --loop iteration asks for a fresh one). Do not output anything.

  4. State: discovering:

    1. One single worktree serves the whole skill run: it is prepared once before the first discovery, so discovering, grilling, and implementing all operate on the same tree, and all further --loop iterations land in it, too.

      Set . Do not output anything.

    2. Resolve the SPEC artifacts to their project-relative file list. Do not output anything.

    3. Read the SpecBook SCHEMA Model of the project (resolved as described in ase-format-spec.md) to learn the allowed object kinds, properties, nestings, and value constraints. Do not output anything.

    4. Read all resolved SPEC artifacts which are related to and , and check the structure of the existing specification -- its artifacts, object kinds, ids, properties, descriptions, and [[xxx]] references -- to understand the overall models and their relationships. Do not output anything.

    5. Ground the edit, where is WHAT HOW WHEN if is not equal none, or WHAT HOW otherwise, as under --verify none no verification takes place:

  5. State: grilling:

    Enter this state only if or is equal true; otherwise silently skip the entire state. Do not output anything about the skipping.

    1. Understand what "grilling" is about:

    2. Perform the approach round -- the grilling round 0 before the regular rounds -- based on and plus the information gathered in the discovering state. Set to GRILLING ROUND 0/<getopt-option-grill-rounds/> if is equal true, or to GRILLING otherwise. Do not output anything.

      If is STOP, only output the following and then immediately STOP processing the entire current skill:

      Otherwise, merge exclusively into , where the chosen approach overrides any conflicting implementation detail, and expand the following:

      If is SKIP, skip all regular rounds below and continue with the implementing state.

    3. Perform at most grilling rounds, numbered (1-) -- the round count is a maximum only, as every round can stop the grilling early in its item 2 below.

      For each round:

      1. INITIALIZE TODO:

        Explicitly start from scratch from only the current and and forget all information gathered in previous rounds -- except the grounding facts . Set to GRILLING ROUND <m/>/<getopt-option-grill-rounds/> if is greater than 1 or is equal true, or to GRILLING otherwise (a single round without an approach round needs no round numbering). Do not output anything.

      2. DETERMINE QUESTIONS:

        Raise no questions at all of focus area REGRESSION or CONFIRMATION, as under --verify none no verification takes place which could honor their decisions. Raise no questions at all of focus area CONFIRMATION, as under --verify light no change-specific checks take place which could honor their decisions.

        If is true, skip the remaining items of this round and all remaining rounds, and continue with the implementing state.

      3. INTERACTIVE DIALOG:

        Treat as the combined free-text answers to all questions of the round and continue with item 4 below. In the following, you MUST NOT use your built-in tool! Instead, you MUST just show a custom dialog according to the expanded custom-dialog definition. You MUST closely follow this definition. The dialog below carries the two fixed answer options SKIP GRILLING and STOP SKILL, dispatched as follows:

        • If a is SKIP GRILLING or CANCEL, ask no further questions, continue with item 4 below (merging the answers gathered so far), and after item 5 skip all remaining rounds and continue with the implementing state.

        • If a is STOP SKILL, only output the following and then immediately STOP processing the entire current skill:

        Show a custom dialog. Its only answer options are the two fixed ones, so the user normally answers all aspects in one free-text reply:

        Dispatch SKIP GRILLING, STOP SKILL, and CANCEL as defined above. Otherwise, strip any leading OTHER: prefix from and treat the remainder as the combined free-text answers to all questions of the round.

      4. MERGE ANSWERS INTO TODO:

        Merge all gathered answers in of the round -- the combined reply -- exclusively back into and . Do not output anything.

      5. SHOW UPDATED TODO:

        Set to round <m/>/<getopt-option-grill-rounds/> if is greater than 1 or is equal true, or to empty otherwise, and expand the following -- this intentionally closes every round, so the intermediate / states stay visible:

  6. State: implementing:

    1. You MUST first forget all previous internalized tenets and then freshly internalize and strictly honor the GENERIC TENETS and the SPECIFYING TENETS of the ASE Tenets in the following creation and updating of specification content. Do not output anything.

    2. Call the ase_timestamp(format: "yyyy-LL-dd HH:mm") tool of the ase MCP server once to find out the current time and store it in . Do not output anything.

    3. Apply the edit by modifying the affected SPEC artifacts with a corresponding, complete change set, honoring only and plus the information gathered in the discovering state.

      The change set MUST keep every touched artifact conformant to the SPEC format contract (ase-format-spec.md): the Created:/Modified: frontmatter block, the heading levels, the Complex/Concise/Grouped format variants, the schema-allowed object kinds, nestings, and property keys, the object ids and {{<id/>}} anchors, the , BECAUSE rationale split, and the [[xxx]] references.

      Generate a SPEC artifact which does not yet exist but is warranted by the edit, using for both its Created: and Modified: timestamps. Whenever an existing artifact is changed and carries a Modified: <timestamp-modified-old/> line, replace this with Modified: <timestamp-modified/>.

      Also, if a CHANGELOG.md file exists, make an appropriate entry there, too.

    4. Output only the following . You MUST NOT output a change summary, a list of modified artifacts, a rationale, or a unified diff of the changes -- independent of , whose exposure rules are explicitly overridden here:

  7. State: verifying:

    Enter this state only if is equal light or full (both perform the same validation). Otherwise (none) you MUST strictly skip the entire state and any verification: do NOT validate the specification at all and do NOT run any build, tests, linter, or type-checker.

    1. Validate the specification and capture its array of { file, line, column, severity, message } objects:

    2. If is not empty, fix the reported problems in the affected SPEC artifacts via the Edit/Write tools and re-validate as in item 7.1 -- for at most ten rounds in total.

    3. Only output the following , listing one bullet line per remaining diagnostic:

      REMAINING DIAGNOSTICS:

      • <file/>:<line/>:<column/>: [...]

      Only output the following :

  8. Loop or Finish:

receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 319kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 319kUpdated Claude CodeCodexVerifiedInstall