@rse/ase 0.0.30 → 0.0.31

package/plugin/skills/ase-code-analyze/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: ase-code-analyze
+argument-hint: "<source-reference>"
+description: >
+    Analyze the source code for problems in the logic and semantics and its related control flow.
+user-invocable: true
+disable-model-invocation: false
+effort: medium
+allowed-tools:
+    - "Agent"
+---
+
+@${CLAUDE_SKILL_DIR}/../../meta/ase-persona.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
+
+Analyze Source Code
+===================
+
+<skill name="ase-code-analyze">
+Analyze Source Code
+</skill>
+
+<role>
+Your role is an experienced, *expert-level software developer*,
+specialized in *analyzing source code*.
+</role>
+
+<objective>
+*Analyze* the source code of $ARGUMENTS, and its directly related source
+code, for problems in its *logic* and *semantics* and its related
+*control flow*.
+</objective>
+
+<flow>
+1. <step id="STEP 1: Investigate Code Base">
+   In this STEP 1, investigate on the code. If the code base is large,
+   you *MUST* use the `Agent` tool (not inline work) to create multiple
+   sub-agents to split the investigation task into appropriate chunks.
+   Hints:
+
+   - During investigation in this STEP 1, do *not* output anything else,
+     especially do not give any further explanations or information.
+
+   - Focus on *practically relevant* cases and especially do *not*
+     investigate on theoretical or fictive cases.
+
+   - In case of problems related to *obvious or expected* errors,
+     they *should* be handled *near the origin*.
+
+   - In case of problems related to *theoretical or unexpected* errors,
+     they *should* be handled in parent scopes to avoid cluttering the
+     source code with too much error handling at all.
+
+   - In this STEP 1, still focus on the *problem only* and do *not*
+     investigate on any possible *solution*.
+   </step>
+
+2. <step id="STEP 2: Show Results">
+   In this STEP 2, for every detected problem, immediately report it
+   with the following output <template/>, based on concise bullet
+   points.
+
+   <template>
+   &#x1F7E0; PROBLEM (Severity: **<severity/>**): **P<n/>**: **<title/>**
+
+   <description/>
+   </template>
+
+   Hints:
+   - For the final results, do *not* output anything else, especially do
+     *not* give any further explanations or information.
+
+   - Uniquely identify the problems with `P<n/>` where <n/> is 1, 2, ...
+
+   - In <description/>, use *very brief* but as *precise* as possible problem
+     descriptions.
+
+   - In <description/>, highlight *code* as <template>`<code/>`</template>
+     and *key aspects* as <template>*<aspect/>*</template>.
+
+   - In <description/>, add inline *references* to the related
+     code positions in the form of either
+     <template>(`<filename/>:<line-number/>`)</template>,
+     <template>(`<filename/>:<line-number/>-<line-number/>`)</template> or
+     <template>(`<filename/>#<function-or-method/>`)</template>.
+
+   - In <description/>, classify the problem with a <severity/>
+     of <template>LOW</template>, <template>MEDIUM</template> or
+     <template>HIGH</template>.
+
+   - *Additionally*, first call the `kv_clear()` tool of the `ase`
+     MCP service to clear the in-memory key/value store, and then, for
+     *every* reported problem, persist its problem analysis result
+     via the `kv_set` tool of the `ase` MCP service, using `key` set
+     to `ase-issue-P<n/>` and `val` set to `<title/>: <description/>`.
+   </step>
+
+3. <step id="STEP 3: Give Final Hint">
+   Finally, in this STEP 3, output the following <template/> to give a
+   final hint:
+
+   <template>
+   ⧉ **ASE**: ☻ skill: **<skill-name/>**, ▶ status: **skill finished**
+   ⧉ **ASE**: ↪ hint: **For deeper analysis, suggestions on solution approaches and then final problem resolution, use `/ase-code-resolve P{n}` in the same or even a different session.**
+   </template>
+   </step>
+</flow>
+

package/plugin/skills/ase-code-craft/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: ase-code-craft
+argument-hint: "[<task-id>:] <feature>"
+description: >
+    Craft Source Code:
+    Use when user wants to create or craft a new feature from scratch.
+user-invocable: true
+disable-model-invocation: false
+effort: high
+allowed-tools:
+    - "Skill"
+---
+
+@${CLAUDE_SKILL_DIR}/../../meta/ase-persona.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md
+
+Craft Feature
+=============
+
+<skill name="ase-code-craft">
+Craft Source Code
+</skill>
+
+<role>
+Your role is an experienced, *expert-level software developer*.
+</role>
+
+<objective>
+From scratch *craft* the following feature:
+<feature>$ARGUMENTS</feature>
+</objective>
+
+@${CLAUDE_SKILL_DIR}/../../meta/ase-plan.md
+
+Procedure
+---------
+
+You *MUST* follow the following numbered items *strictly* *sequentially*!
+You *MUST* not skip any numbered item during processing!
+
+You *MUST* *NOT* output anything in this entire procedure, *except* when
+explicitly requested by this procedure via outputs based on a <template/>!
+
+1.  **Reason About Feature**:
+
+    1.  <if condition="
+            <feature/> matches the regexp `^[a-zA-Z][a-zA-Z0-9_-]*$`
+        ">
+        Set <ase-task-id><feature/></ase-task-id> (set task id to feature)
+        and <feature></feature> (set feature empty), call the
+        `task_id(id: <ase-task-id/>, session: <ase-session-id/>)` tool
+        from the `ase` MCP service to switch the task, and then only
+        output the following <template/>:
+
+        <template>
+        ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ▶ status: **task given**
+        </template>
+        </if>
+
+    2.  If <feature/> has the format `<id/>: <text/>` where <id/> matches
+        the regexp `^[a-zA-Z][a-zA-Z0-9_-]+$`, then set
+        <feature><text/></feature> and <ase-task-id><id/></ase-task-id>
+        and call the `task_id(id: <ase-task-id/>, session:
+        <ase-session-id/>)` tool from the `ase` MCP service to
+        implicitly switch the task.
+
+    3.  If <feature/> is empty,
+        ask the user interactively, without a special tool, for the
+        initial feature with a single question:
+
+        `**No feature known yet. What is the feature you want to craft?**`
+
+        Then set <feature/> to the response of the user.
+
+    4.  Report the task and feature with the following <template/>:
+
+        <template>
+        ⧉ **ASE**: ◉ task: **<ase-task-id/>**
+        ⧉ **ASE**: ⇌ feature: **<feature/>**
+        </template>
+
+    5.  Figure out what the requested <feature/> to be crafted is about.
+
+    6.  Ask the user for clarification if the goal of this crafting is too
+        unclear.
+
+    7.  Do not output anything in this step, except you asked the user.
+
+2.  **Investigate Code Base**:
+
+    1.  Check the existing source files for all code which is related to the
+        requested new <feature/>.
+
+    2.  Check the architecture of the existing code base to understand the
+        overall structures and dynamics.
+
+    3.  Do not output anything in this step.
+
+3.  **Find Feature Crafting Approaches**:
+
+    1.  *Propose* corresponding *feature approach*, including optionally,
+        some *alternative* feature approaches.
+
+    2.  Annotate the approach you recommend with an <annotation/> of
+        ` ⚝ **RECOMMENDATION** ⚝`.
+
+    3.  Report each approach with the following <template/>:
+
+        <template>
+        &#x1F535; **APPROACH A<n/>**<annotation/>: *<summary/>*
+        - [...]
+        - [...]
+        - [...]
+        <optional-diagram/>
+        </template>
+
+        Hints:
+
+        -   Give a short one-sentence <summary/> of the feature approach plus
+            *precise* and *brief* feature information. Try to keep the
+            number of bullet points in the range of 1-4.
+
+        -   In case of a *complex feature situation* only, visualize it with
+            an optional diagram <optional-diagram/> by invoking the
+            `ase-meta-diagram` skill via the `Skill` tool. For *current vs.
+            proposed* comparisons, render each side as a *separate*
+            `ase-meta-diagram` invocation and stack the rendered blocks
+            *vertically* (labels `**Before:**` / `**After:**`); never
+            side-by-side. Omit <optional-diagram/> entirely for simple or
+            purely local situation.
+
+        *Recommended* Tenets (generic):
+
+        -   **Surgical Changes**:
+            Keep source code changes always as small as possible.
+
+        -   **Separation of Concerns**:
+            Clearly separate all individual concerns as good as possible.
+
+        -   **Single Responsibility Principle**:
+            Every module, class, or function should have only one reason to change.
+
+        -   **Behavior Preservation**:
+            Refactoring changes only re-structure, never change any observable behavior.
+
+        -   **Align with Code Base**:
+            Strictly align with the existing code base by exactly following its
+            coding style, its structure, its naming conventions, etc.
+
+        *Essential* Tenets (specific):
+
+        -   **High Cohesion, Low Coupling**:
+            Strike for a set of small, focused parts (high cohesion) connected by
+            thin, explicit wires (low coupling).
+
+4.  **Choose Feature Crafting Approach**:
+
+    1.  Let the *user interactively choose* the preferred feature approach A<n/>
+        with the help of the <user-dialog-tool/> tool. Use *single-selection* only
+        and provide small *code change previews*. Mark your recommended
+        feature approach with ` ⚝ **RECOMMENDATION** ⚝` here again.
+
+5.  **Write Feature Crafting Plan**:
+
+    1.  *Write a feature plan* for the chosen feature A<n/> by
+        closely aligning to the existing architecture and the existing
+        code base. Use the <format/> defined for a task plan and inject
+        the information from feature A<n/> and all derived realization
+        decisions into it. Store the resulting task plan in <content/>.
+
+    2.  Call the `timestamp(format: "yyyy-LL-dd HH:mm")` tool of the
+        `ase` MCP service and use the `text` field of its response for
+        <timestamp-created/> and <timestamp-modified/> information. Then
+        insert the current <ase-task-id/>, <timestamp-created/>, and
+        <timestamp-modified/> information and calculate the number of
+        words <words/> of <content/>.
+
+    3.  You *MUST* *save* the resulting plan content with the
+        `task_save(id: <ase-task-id/>, text: <content/>)`.
+
+    4.  Output a hint with the following <template/>:
+
+        <template>
+        ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ✪ plan: **<words/>** words, ▶ status: **plan created**
+        </template>
+
+    5.  *Ask user*: Let the *user interactively choose*
+        what to do as the next step.
+
+        <expand name="user-dialog>
+        Next Step: How would you like to proceed with the plan?
+        DONE: Stop processing.
+        EDIT: Hand processing off to editing.
+        PREFLIGHT: Hand processing off to preflighting.
+        IMPLEMENT: Hand processing off to implementation.
+        </expand>
+
+    6.  Check the tool <result/> and dispatch accordingly:
+
+        -   If <result/> is `DONE` or `CANCEL`:
+            Only output the following <template/> and then *STOP*.
+
+            <template>
+            ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ✪ plan: **<words/>** words, ▶ status: **done**
+            </template>
+
+        -   If <result/> is `EDIT`:
+            Only output the following <template/> and then use the
+            `Skill` tool to invoke the `ase:ase-task-edit` skill in
+            order to edit the plan. Immediately stop processing the
+            current skill once the `Skill` tool was used.
+
+            <template>
+            ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ✪ plan: **<words/>** words, ▶ status: **hand off to edit**
+            </template>
+
+        -   If <result/> is `PREFLIGHT`:
+            Only output the following <template/> and then use the
+            `Skill` tool to invoke the `ase:ase-task-preflight` skill in
+            order to preflight the plan. Immediately stop processing the
+            current skill once the `Skill` tool was used.
+
+            <template>
+            ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ✪ plan: **<words/>** words, ▶ status: **hand off to preflight**
+            </template>
+
+        -   If <result/> is `IMPLEMENT`:
+            Only output the following <template/> and then use the
+            `Skill` tool to invoke the `ase:ase-task-implement` skill in
+            order to implement the plan. Immediately stop processing the
+            current skill once the `Skill` tool was used.
+
+            <template>
+            ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ✪ plan: **<words/>** words, ▶ status: **hand off to implement**
+            </template>
+

package/plugin/skills/ase-code-explain/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: ase-code-explain
+argument-hint: "<source-reference>"
+description: >
+    Explains code with WHAT, WHY, ANALOGY, DIAGRAM, CRUXES, and GOTCHAS.
+    Use when you want to know how code works or when the user asks "how does this work?"
+user-invocable: true
+disable-model-invocation: false
+effort: medium
+allowed-tools:
+    - "Skill"
+    - "Agent"
+---
+
+@${CLAUDE_SKILL_DIR}/../../meta/ase-persona.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
+
+Explain Source Code
+===================
+
+Your role is an experienced, *expert-level software developer*,
+specialized in *explaining source code*.
+
+<objective>
+*Analyze* the source code of $ARGUMENTS, and its directly related source
+code and *explain* it in *brief*, *standardized*, and *concise* way.
+</objective>
+
+<flow>
+1.  <step id="STEP 1: Investigate Code Base">
+    Investigate on the code. If the code base is large, you *MUST* use
+    the `Agent` tool (not inline work) to create multiple sub-agents to
+    split the investigation task into appropriate chunks.
+    </step>
+
+2.  <step id="STEP 2: WHAT and WHY">
+    **Explain the WHAT and WHY**.
+
+    First, explain *WHAT* the code does (*functionality*).
+    Second, explain *WHY* the code does it (*rationale*).
+
+    Keep your explanations *brief* and *concise*.
+    Output the result with the following <template/>:
+
+    <template>
+    &#x1F535; **WHAT** (You should know what):
+    - [...]
+    - [...]
+    - [...]
+
+    &#x1F535; **WHY** (You should know why):
+    - [...]
+    - [...]
+    - [...]
+    </template>
+    </step>
+
+3.  <step id="STEP 3: ANALOGY and DIAGRAM">
+    **Give insights with ANALOGY and DIAGRAM**.
+
+    First, give an analogy by comparing the code to something from
+    everyday life. How can I understand this by something I already
+    know? Use simple wording as in "Explain Like I'm 5 Years Old (ELI5)"
+    style of explanations. For very complex concepts, use multiple
+    analogies.
+
+    Second, draw a diagram to show the control or data flow, code or
+    data structure, or code or data relationships. What gives the best
+    overall overview of the code?
+    Choose the Mermaid diagram type per intent: `classDiagram` for
+    class/method structure, `sequenceDiagram` for actor/message flow,
+    or `flowchart TB` for boxes-and-lines component layouts.
+    Invoke the `ase-meta-diagram` skill via the `Skill` tool to render the
+    diagram. Do *not* hand-draw.
+
+    Keep your explanation *brief* and *concise*.
+    Output the result with the following <template/>:
+
+    <template>
+    &#x26AA; **ANALOGY** (You should imagine):
+    - [...]
+    - [...]
+    - [...]
+
+    &#x26AA; **DIAGRAM** (You should grasp):
+    [...]
+    </template>
+    </step>
+
+4.  <step id="STEP 4: CRUXES and GOTCHAS">
+    **Highlight CRUXES and GOTCHAS**.
+
+    First, tell what are the *cruxes* of the code.
+    Is there something one should really *notice*?
+
+    Second, tell what are the gotchas of the code.
+    Is there something one could really *stumble over*?
+
+    Keep your explanation *brief* and *concise*.
+    Output the result with the following <template/>:
+
+    <template>
+    &#x1F7E0; **CRUXES** (You should notice):
+    - [...]
+    - [...]
+    - [...]
+
+    &#x1F7E0; **GOTCHAS** (You should not stumble over):
+    - [...]
+    - [...]
+    - [...]
+    </template>
+    </step>
+</flow>
+

package/plugin/skills/ase-code-insight/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: ase-code-insight
+argument-hint: "<code-references>"
+description: >
+    Give insights into the source code.
+user-invocable: true
+disable-model-invocation: false
+effort: low
+allowed-tools:
+    - "Bash(git)"
+    - "Bash(sort)"
+    - "Bash(uniq)"
+    - "Bash(head)"
+    - "Skill"
+---
+
+@${CLAUDE_SKILL_DIR}/../../meta/ase-persona.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
+
+Project Insight
+===============
+
+Your role is an experienced, *expert-level software developer*,
+specialized in *analyzing source code* and giving insights.
+
+<objective>
+Give *insights* into the project through the source code of $ARGUMENTS.
+</objective>
+
+<flow>
+1.  <step id="STEP 1: PROJECT ABSTRACT">
+    Determine an <abstract/> summary of this project.
+    For this, check a potentially existing `README.*` file
+    or scan the source files and figure it out indirectly.
+
+    Display the results with the following <template/>:
+
+    <template>
+    &#x1F535; **PROJECT ABSTRACT**:
+
+    <abstract/>
+    </template>
+    </step>
+
+2.  <step id="STEP 2: PROJECT AUTHOR">
+    Determine the <author/> of this project.
+    For this, run the following command...
+
+    ```
+    git shortlog -sn --no-merges HEAD
+    ```
+
+    ...and then display the results with the following <template/>:
+
+    <template>
+    &#x1F535; **PROJECT AUTHOR**:
+
+    <author/>
+    </template>
+    </step>
+
+3.  <step id="STEP 3: SOURCE CHURN">
+    Display the source files with caused the most churn by
+    figuring out which source files have the most commits.
+    Display the following <template/>:
+
+    <template>
+    &#x1F535; **SOURCE CHURN**:
+    </template>
+
+    Then run the following command...
+
+    ```
+    git log --format=format: --name-only --since="1 year ago" | sort | uniq -c | sort -nr | head -10
+    ```
+
+    ...and then display its result as a table with a table head and
+    columns named "Commits" and "Source File". Do not display any
+    further explanation of this result.
+    </step>
+
+4.  <step id="STEP 4: MODULE STRUCTURE">
+    Display the following <template/>:
+
+    <template>
+    &#x1F535; **MODULE STRUCTURE**:
+    </template>
+
+    Find all modules (or OOP classes) and draw a `flowchart TB`
+    diagram with all modules as boxes and the imports between modules
+    as the directed edges. Invoke the `ase-meta-diagram` skill via the
+    `Skill` tool to render the diagram. Do not display any further
+    explanation except for this diagram.
+    </step>
+</flow>
+