@rse/ase 0.0.30 → 0.0.32

package/plugin/skills/ase-arch-discover/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: ase-arch-discover
+argument-hint: "<functionality>"
+description: >
+    Discover additional, third-party components (libraries/frameworks) for
+    the technology stack to provide needed functionality.
+user-invocable: true
+disable-model-invocation: false
+effort: medium
+allowed-tools:
+    - "Bash(npm search --json *)"
+    - "Bash(npm view --json *)"
+    - "Skill"
+    - "Agent"
+    - "WebFetch"
+---
+
+@${CLAUDE_SKILL_DIR}/../../meta/ase-persona.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
+
+Discover Components
+===================
+
+Your role is an experienced, *expert-level software architect*,
+specialized in *finding components* (libraries/frameworks) for the technology stack.
+
+<objective>
+*Discover* additional, *third-party components* (libraries/frameworks)
+for the technology stack to *provide* the *needed functionality*
+<request>$ARGUMENTS</request>.
+</objective>
+
+<flow>
+1.  <step id="STEP 1: Determine Functionality">
+    -   Derive the needed <functionality/> from the <request/>, but keep
+        the functionality description very *brief* but still *precise*.
+
+    -   If <functionality/> is not clear or not precise enough, raise
+        questions to the user with the help of an interactive user dialog tool.
+
+    -   Display the determined final functionality with just the following
+        <template/>:
+
+        <template>
+        &#x1F535; **FUNCTIONALITY**: <functionality/>
+        </template>
+    </step>
+
+2.  <step id="STEP 2: Determine Technology Stack">
+    -   Determine the used technology stack:
+
+        -   If a file `package.json` is found in the top-level directory
+            of the project and contains an entry `typescript` under `dependencies`
+            or `devDependencies`, then <stack>TypeScript</stack>.
+
+        -   Else, if a file `package.json` is found in the top-level directory
+            of the project, then <stack>JavaScript</stack>.
+
+        -   Else, if a file `build.gradle.kts` or `settings.gradle.kts`
+            is found in the top-level directory, then <stack>Kotlin</stack>.
+
+        -   Else, if a file `build.gradle` is found in the top-level directory and
+            is applying `kotlin`, `org.jetbrains.kotlin.jvm`, `kotlin-android`,
+            or `kotlin-multiplatform` plugins, then <stack>Kotlin</stack>.
+
+        -   Else, if a file `pom.xml` is found in the top-level directory and
+            contains `kotlin-maven-plugin` or `kotlin-stdlib` dependencies, then
+            <stack>Kotlin</stack>.
+
+        -   Else, if a file `pom.xml` or `build.gradle` is found in the top-level directory
+            of the project, then <stack>Java</stack>.
+
+        -   Else, use <stack>Unknown</stack>.
+
+    -   Display the determined final technology stack with just the
+        following <template/>:
+
+        <template>
+        &#x1F535; **TECHNOLOGY STACK**: <stack/>
+        </template>
+    </step>
+
+3.  <step id="STEP 3: Discover Components">
+    -   From <stack/> and <functionality/>, derive essential keywords
+        <keyword-L/> (L=1-M), which allow you to search for suitable
+        components.
+
+    -   In the to be discovered result set of components <component-K/>
+        (K=1-N), remember the component name as <name-K/>, the
+        official package name as <package-K/>, the latest version as
+        <version-K/>, the stars as <stars-K/>, the created date as
+        <created-K/>, the last updated date as <updated-K/>, the total
+        number of downloads in the last month is <downloads-K/>.
+
+    -   If <stack/> is "JavaScript" or "TypeScript":
+
+        -   Based on the essential keywords <keyword-L/> (L=1-M),
+            use the `ase-meta-search` skill in a subagent to *generally*
+            discover an initial set of a maximum of 12 *NPM packages*
+            <component-K/> and at least their real name <name-K/> and
+            their unique package names <package-K/>.
+
+        -   Use the shell command `npm search --json --searchlimit 12
+            "<keyword-1/>" [...] "<keyword-M/>"` to *specifically*
+            discover an additional set of a maximum of 12 *NPM packages*
+            <component-K/> and at least their unique package names
+            <package-K/>, based on the essential keywords <keyword-L/>
+            (L=1-M). Merge the results into the already existing result
+            set, but deduplicate entries.
+
+        -   For each discovered *NPM package* <component-K/> (K=1-N),
+            use the shell command `npm view --json "<package-K/>"
+            version time repository.url` to discover
+            its version <version-K/>, the publish time of that
+            version <updated-K/> (read from `time[<version-K/>]`),
+            its time created <created-K/> (read from `time.created`),
+            and its repository URL <repository-K/>.
+
+        -   If the <repository-K/> regexp-matches
+            `.+?//github\.com/([^/]+/[^/.]+).*` use the `WebFetch` tool
+            to fetch the URL `https://api.github.com/repos/$1` (`$1`
+            is the value matched by the first capturing parenthesis
+            in the regexp) and extract <stars-K/> from its JSON
+            `stargazers_count` field, else set <stars-K/> to `N.A.`.
+
+        -   For each discovered *NPM package* <component-K/>
+            (K=1-N), use the `WebFetch` tool on the URL
+            `https://api.npmjs.org/downloads/point/last-month/<package-K/>`
+            to extract the <downloads-K/> from the `downloads` field.
+
+    -   If <stack/> is "Java" or "Kotlin":
+
+        -   Based on the essential keywords <keyword-L/> (L=1-M),
+            use the `ase-meta-search` skill in a subagent to *generally*
+            discover an initial set of a maximum of 12 *Java packages*
+            <component-K/> and at least their real name <name-K/> and
+            their unique package names <package-K/>.
+    </step>
+
+4.  <step id="STEP 4: Report Components">
+    -   Sort, in descending order, the discovered components
+        <component-K/> (K=1-N) first by their <downloads-K/> and second
+        by their <stars-K/> and trim the result list to just a maximum
+        of 12 total components.
+
+    -   Display the discovered components as a Markdown *table*
+        with just the following <template/>:
+
+        <template>
+        &#x1F535; **COMPONENTS**:
+
+        | *Component*   | *Package*      | *Version*    | *Downloads*        | *Stars*        | *Updated*        | *Created*    |
+        | :------------ | :------------- | -----------: | -----------------: | -------------: | :--------------- | :----------- |
+        | **<name-1/>** | `<package-1/>` | <version-1/> | **<downloads-1/>** | **<stars-1/>** | **<updated-1/>** | <created-1/> |
+        [...]
+        | **<name-N/>** | `<package-N/>` | <version-N/> | **<downloads-N/>** | **<stars-N/>** | **<updated-N/>** | <created-N/> |
+        </template>
+    </step>
+</flow>
+

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

@@ -0,0 +1,110 @@
+---
+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,117 @@
+---
+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>
+