@rse/ase 0.9.62 → 0.9.64

package/plugin/skills/ase-sync-reconcile/SKILL.md

@@ -5,7 +5,7 @@ description: >
     Reconcile one set of artifact kinds (the target) to reflect the
     current state of another set of artifact kinds (the source), while
     optionally honoring a filtering hint. Use when the user wants to
-    "reconcile", "sync", "align", or "update" artifacts like SPEC, ARCH,
+    "reconcile", "sync", "align", or "update" artifacts like SPEC,
     CODE, DOCS, TASK, INFR, or OTHR against each other.
 user-invocable: true
 disable-model-invocation: false
@@ -35,7 +35,6 @@ artifacts and aligning the target artifacts accordingly:
 
 @${CLAUDE_SKILL_DIR}/../../meta/ase-format-meta.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-format-spec.md
-@${CLAUDE_SKILL_DIR}/../../meta/ase-format-arch.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-format-task.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-tenets.md
 
@@ -46,8 +45,8 @@ Procedure
 
 1.  <step id="STEP 1: Determine Target and Source">
 
-    1.  The recognized artifact kinds are the seven tokens `TASK`,
-        `SPEC`, `ARCH`, `CODE`, `DOCS`, `INFR`, and `OTHR`. Parse
+    1.  The recognized artifact kinds are the six tokens `TASK`,
+        `SPEC`, `CODE`, `DOCS`, `INFR`, and `OTHR`. Parse
         <getopt-option-target/> as the comma-separated <target/> kind list and
         <getopt-option-source/> as the comma-separated <source/> kind list.
         Upper-case and trim every parsed kind token. Do not output
@@ -66,13 +65,13 @@ Procedure
 
     3.  <if condition="<source/> is equal 'AUTO'">
 
-        Set <source/> to the seven recognized kinds
-        `TASK,SPEC,ARCH,CODE,DOCS,INFR,OTHR` *minus* all kinds present
+        Set <source/> to the six recognized kinds
+        `TASK,SPEC,CODE,DOCS,INFR,OTHR` *minus* all kinds present
         in <target/>. Do not output anything.
 
         </if>
 
-    4.  If any token in <target/> or <source/> is *not* one of the seven
+    4.  If any token in <target/> or <source/> is *not* one of the six
         recognized kinds, only output the following <template/> (with
         <kind/> set to the first offending token) and then immediately
         *STOP* processing the entire current skill:
@@ -136,17 +135,18 @@ Procedure
 
     1.  Internalize and honor the artifact-format conventions:
 
-        -   the artifact-set/artifact/aspect meta information (`ase-format-meta.md`),
-        -   the `SPEC` format (`ase-format-spec.md`),
-        -   the `ARCH` format (`ase-format-arch.md`),
+        -   the artifact-set meta information (`ase-format-meta.md`),
+        -   the `SPEC` format, i.e. the SpecBook models and formats plus
+            the SpecBook schema configuration of the project
+            (`ase-format-spec.md`),
         -   the `TASK` format (`ase-format-task.md`).
 
         Whenever a target artifact belongs to one of these
         kinds, the update *MUST* keep it conformant to the
-        corresponding format (headings, structure, identifiers, and the
-        `<timestamp-modified/>` rule). The kinds `CODE`, `DOCS`, `INFR`,
-        and `OTHR` have no dedicated format contract and are treated as
-        free-form.
+        corresponding format (headings, structure, identifiers,
+        references, and the `Modified:` timestamp rule). The kinds
+        `CODE`, `DOCS`, `INFR`, and `OTHR` have no dedicated format
+        contract and are treated as free-form.
 
     2.  You *MUST* internalize and strictly honor the **GENERIC TENETS**,
         the **RECONCILIATION TENETS**, the **REFACTORING TENETS**, and
@@ -188,7 +188,28 @@ Procedure
         <timestamp-modified-old/>` line, replace this with `Modified:
         <timestamp-modified/>`.
 
-    5.  Report the performed updates with the following <template/>, listing
+    5.  <if condition="at least one `SPEC` output artifact was changed">
+
+        Validate the specification by calling the `ase_specbook_lint()`
+        tool of the `ase` MCP server and reading its returned
+        `diagnostics` array of `{ file, line, column, message }`
+        objects. If it is not empty, fix the reported problems in the
+        affected `SPEC` artifacts via the `Write`/`Edit` tools and call
+        the tool again -- for at most *three* rounds in total. Do not
+        output anything, unless diagnostics remain after the last round,
+        in which case output the following <template/>, listing one
+        bullet line per remaining diagnostic:
+
+        <template>
+        <ase-tpl-bullet-signal/> **REMAINING DIAGNOSTICS**:
+
+        -   `<file/>:<line/>:<column/>`: <message/>
+        [...]
+        </template>
+
+        </if>
+
+    6.  Report the performed updates with the following <template/>, listing
         one bullet line per changed output file (with <file/> its
         project-relative path and <note/> an ultra-brief description of
         what was reconciled):
@@ -210,7 +231,7 @@ Procedure
 
         </if>
 
-    6.  Finally, give the closing hints by expanding the following
+    7.  Finally, give the closing hints by expanding the following
         (which, depending on the configured <ase-guidance-level/>, may
         each expand into nothing and hence emit no output at all):
 

package/plugin/skills/ase-sync-reconcile/help.md

@@ -20,20 +20,23 @@ kinds (the *source*). It reads the source artifacts and then adjusts the
 target artifacts *directly* and *surgically* to match the source state,
 while optionally honoring a filtering *hint*.
 
-Both *target* and *source* are comma-separated lists over the seven
-recognized artifact kinds `SPEC` (Specification), `ARCH` (Architecture),
-`CODE` (Source Code), `DOCS` (Documentation), `TASK` (Task Plans), `INFR`
-(Infrastructure), and `OTHR` (catch-all). When *source* is `auto`, it
-resolves to all seven kinds *minus* the kinds listed in *target*. Unless
-`--bidirectional` is given, a kind present in *target* is never used as
-its own source.
+Both *target* and *source* are comma-separated lists over the six
+recognized artifact kinds `SPEC` (Specification, covering both
+requirements and architecture), `CODE` (Source Code), `DOCS`
+(Documentation), `TASK` (Task Plans), `INFR` (Infrastructure), and
+`OTHR` (catch-all). When *source* is `auto`, it resolves to all six
+kinds *minus* the kinds listed in *target*. Unless `--bidirectional` is
+given, a kind present in *target* is never used as its own source.
 
 The file lists for all involved kinds are resolved via the
 `ase_artifact_list` MCP tool of the `ase` MCP server. While reconciling,
 the skill honors the artifact-format conventions of `ase-format-meta.md`,
-`ase-format-spec.md`, `ase-format-arch.md`, and `ase-format-task.md`;
-the kinds `CODE`, `DOCS`, `INFR`, and `OTHR` have no dedicated format
-contract and are treated as free-form.
+`ase-format-spec.md` (the *SpecBook* models and formats plus the
+SpecBook schema configuration), and `ase-format-task.md`; the kinds
+`CODE`, `DOCS`, `INFR`, and `OTHR` have no dedicated format contract and
+are treated as free-form. Changed `SPEC` artifacts are validated via
+the `ase_specbook_lint` MCP tool and the reported diagnostics are fixed
+in at most three rounds; any remaining diagnostics are surfaced.
 
 ##  OPTIONS
 
@@ -59,28 +62,35 @@ contract and are treated as free-form.
     target artifacts, or the aspects of those artifacts to take into
     account during reconciliation.
 
+##  SCENARIOS
+
+-   You want one artifact set updated to reflect another one
+-   You want code and docs aligned with the specification
+-   You want the specification recovered from the code base
+-   You want spec and code bidirectionally synchronized
+
 ##  EXAMPLES
 
 Reconcile the code and documentation
-to reflect the current specification and architecture
+to reflect the current specification
 in a "forward engineering" approach:
 
 ```text
-❯ /ase-sync-reconcile -t CODE,DOCS -s SPEC,ARCH
+❯ /ase-sync-reconcile -t CODE,DOCS -s SPEC
 ```
 
-Reconcile specification and architecture from everything else
+Reconcile the specification from everything else
 in a "reverse engineering" approach:
 
 ```text
-❯ /ase-sync-reconcile -t SPEC,ARCH -s CODE,DOCS
+❯ /ase-sync-reconcile -t SPEC -s CODE,DOCS
 ```
 
-Bidirectionally reconcile specification and architecture against
+Bidirectionally reconcile specification and code against
 each other, limited to the authentication aspect:
 
 ```text
-❯ /ase-sync-reconcile -b -t SPEC -s ARCH authentication
+❯ /ase-sync-reconcile -b -t SPEC -s CODE authentication
 ```
 
 ##  SEE ALSO

package/plugin/skills/ase-task-condense/help.md

@@ -57,6 +57,12 @@ After condensing, the user is asked whether to stop or hand off to
     The unique identifier of the task whose plan should be condensed.
     If omitted, the *current* task id is used.
 
+##  SCENARIOS
+
+-   You want a task plan shortened without losing meaning
+-   You want plan wording compressed for faster reading
+-   You want fluff removed from a plan while keeping all semantics
+
 ##  EXAMPLES
 
 Condense the current task plan:

package/plugin/skills/ase-task-delete/help.md

@@ -23,6 +23,12 @@ switched back to `default`.
     The unique identifier of the task plan to delete. If omitted,
     the current task id is used.
 
+##  SCENARIOS
+
+-   You want a task plan removed
+-   You want a finished or obsolete task cleared
+-   You want a plan discarded, falling back to the default task
+
 ##  EXAMPLES
 
 Delete the current task plan:

package/plugin/skills/ase-task-dissect/help.md

@@ -76,6 +76,13 @@ The epic plan itself always stays *untouched*.
     A free-text hint telling *how* the epic should be split. If omitted,
     the parts are derived from the plan alone.
 
+##  SCENARIOS
+
+-   You want a large task plan split into cohesive sub-tasks
+-   You want an epic decomposed into independently implementable parts
+-   You want a preview of how a plan would be divided
+-   You want each part of a plan persisted as its own separate plan
+
 ##  EXAMPLES
 
 Dissect the current task plan:

package/plugin/skills/ase-task-edit/help.md

@@ -65,6 +65,13 @@ for the changed plan.
     Optionally, *instruction* either gives instructions for creating a
     new task or gives instructions for refining an existing task.
 
+##  SCENARIOS
+
+-   You want a task planned through chat-driven refinement
+-   You want a plan created or refined round by round
+-   You want a plan iterated on before implementing it
+-   You want plan refinement with hand-off to preflight or implementation
+
 ##  EXAMPLES
 
 Edit the current task:

package/plugin/skills/ase-task-grill/SKILL.md

@@ -141,10 +141,11 @@ Set <args>--int-reuse-task</args>.
             `ARCHITECTURE`, and then all `IMPLEMENTATION` ones -- and
             *secondarily*, within each focus area, by the decision tree
             order, so that each decision is asked *after* the decisions
-            it depends on. Renumber <N/> according to this order.
-            Truncate the list after a maximum of 10 questions and set
-            <n/> to the number of remaining questions. Do not output
-            anything.
+            it depends on. Renumber <N/> according to this order,
+            starting at `1` in *every* round, independent of the
+            numbering of previous rounds. Truncate the list after a
+            maximum of 10 questions and set <n/> to the number of
+            remaining questions. Do not output anything.
 
         5.  For each question <question-N/> in the iteration cycle <N/>,
             *one at a time*:

package/plugin/skills/ase-task-grill/help.md

@@ -73,6 +73,13 @@ offered a hand-off to editing, implementation, or preflight.
     The skill accepts *only* an optional *id* argument and never a
     free-text instruction.
 
+##  SCENARIOS
+
+-   You want to be interviewed about your plan until it is watertight
+-   You want the open decisions of a plan resolved question by question
+-   You want fuzzy language and conflicts flushed out of a plan
+-   You want shared understanding before the implementation starts
+
 ##  EXAMPLES
 
 Grill the current task plan:

package/plugin/skills/ase-task-id/help.md

@@ -22,6 +22,12 @@ task id via the `ase_task_id` MCP tool.
     The new task id to activate. If omitted, the currently active
     task id is reported.
 
+##  SCENARIOS
+
+-   You want to know which task is currently active
+-   You want the session switched to another task
+-   You want to work on a certain task
+
 ##  EXAMPLES
 
 Show the current task id:

package/plugin/skills/ase-task-implement/help.md

@@ -79,6 +79,13 @@ delete the task plan, unless `--next` pre-selects this choice.
     The unique identifier of the task whose plan should be
     implemented. If omitted, the *current* task id is used.
 
+##  SCENARIOS
+
+-   You want a task plan turned into actual changes
+-   You want the planned change set applied and verified
+-   You want a reviewed implementation draft applied 1:1
+-   You want the implementation isolated in a Git worktree
+
 ##  EXAMPLES
 
 Implement the current task plan:

package/plugin/skills/ase-task-list/help.md

@@ -54,6 +54,12 @@ REJECTED  DEFERRED  BLOCKED  CANCELLED
     `COMPLETED,CANCELLED`; pass `--exclude none` to suppress the
     default and list task plans in every state.
 
+##  SCENARIOS
+
+-   You want an overview of all task plans
+-   You want task ids listed with status and timestamps
+-   You want the unfinished or in-progress tasks found
+
 ##  EXAMPLES
 
 List all unfinished task ids:

package/plugin/skills/ase-task-preflight/help.md

@@ -55,6 +55,13 @@ unless `--next` pre-selects this choice.
     The unique identifier of the task whose plan should be
     preflighted. If omitted, the *current* task id is used.
 
+##  SCENARIOS
+
+-   You want a dry-run of a plan's implementation
+-   You want the change set previewed as a unified diff before applying
+-   You want an implementation draft to review before committing to it
+-   You want a plan test-driven without touching any source files
+
 ##  EXAMPLES
 
 Preflight the current task plan:

package/plugin/skills/ase-task-reboot/help.md

@@ -43,6 +43,12 @@ unless `--next` pre-selects this choice.
     The unique identifier of the task whose plan should be rebooted.
     If omitted, the *current* task id is used.
 
+##  SCENARIOS
+
+-   You want a task plan re-created from scratch
+-   You want a fresh plan from the original WHAT and WHY
+-   You want planning restarted after a plan degraded
+
 ##  EXAMPLES
 
 Reboot the current task plan:

package/plugin/skills/ase-task-rename/help.md

@@ -24,6 +24,12 @@ task id is automatically switched to *new*.
     If only one token is given, *old* defaults to the current
     task id.
 
+##  SCENARIOS
+
+-   You want a task plan renamed
+-   You want a task given a better id
+-   You want the current task moved to a new id
+
 ##  EXAMPLES
 
 Rename the current task:

package/plugin/skills/ase-task-view/help.md

@@ -36,6 +36,12 @@ the plan in full, without any truncation or summarization.
     The unique identifier of the task plan to view. If omitted,
     the current task id is used.
 
+##  SCENARIOS
+
+-   You want the current or a given task plan shown
+-   You want a plan rendered before deciding the next steps
+-   You want a plan inspected including its implementation draft
+
 ##  EXAMPLES
 
 View the current task plan: