@rse/ase 0.0.56 → 0.0.57

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.0.56",
+    "version":                              "0.0.57",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.0.56",
+    "version":     "0.0.57",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.github/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.0.56",
+    "version":     "0.0.57",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/etc/markdownlint.yaml

@@ -15,4 +15,5 @@ no-space-in-code:   false
 ul-indent:          false
 ol-indent:          false
 heading-style:      false
+no-multiple-space-atx: false
 

package/plugin/meta/ase-constitution.md

@@ -3,7 +3,8 @@ ASE Constitution
 ================
 
 You are **Claude Code**, an expert-level AI coding assistant.
-You have the **Agentic Software Engineering (ASE)** facility enabled.
+You have the **Agentic Software Engineering (ASE)** facility enabled,
+which boosts you to an expert-level Software Engineering AI agent.
 
 If <ase-headless/> is empty or not set,
 you *MUST* once and immediately output the following <template/> now:

package/plugin/meta/ase-getopt.md

@@ -9,7 +9,7 @@ set placeholders into the context as a side-effect.
 
 1.  **Determine Parameters**:
     Set <getopt-skill><arg1/></getopt-skill>.
-    Set <getopt-spec><arg2/></getopt-spec>.
+    Set <getopt-spec>--help|-h <arg2/></getopt-spec>.
     Set <getopt-opts><arg3/></getopt-opts>.
     Set <getopt-args><content/></getopt-args>.
 
@@ -36,7 +36,7 @@ set placeholders into the context as a side-effect.
     then immediately *STOP* processing the entire current skill:
 
     <template>
-    ⧉ **ASE**: ☻ skill: **<getopt-skill/>**, ▶ ERROR: option parsing failed: **<text/>**
+    ⧉ **ASE**: ✪ skill: **<getopt-skill/>**, ▶ ERROR: option parsing failed: **<text/>**
     </template>
 
 5.  **Parsing JSON Result**:
@@ -58,13 +58,14 @@ set placeholders into the context as a side-effect.
     Set <getopt-option-<longN/>/> to the corresponding value
     `<getopt-result/>.opts[<longN/>]`.
     Set <getopt-arguments/> to the value of `<getopt-result/>.args`.
-    Set <getopt-info/> to `<getopt-result/>.info`.
+    Set <getopt-info/> to `<getopt-result/>.info`, but remove
+    information about the `help` option.
 
 7.  **Display Results**:
     Just output the following <template/>:
 
     <template>
-    ⧉ **ASE**: ☻ skill: **<getopt-skill/>**, ▶ options: <getopt-info/>
+    ⧉ **ASE**: ✪ skill: **<getopt-skill/>**, ▶ options: <getopt-info/>
     </template>
 </define>
 

package/plugin/meta/ase-skill.md

@@ -160,14 +160,23 @@ Skill Identification
 
 - *IMPORTANT*: Set <skill></skill> (set to empty)
   and <skill-name></skill-name> (set name to empty).
-  Then, in case <skill/> later becomes *not* empty
-  by defining it as <skill name="<name/>"><body/></skill>,
-  set <skill-name><name/></skill-name> (set skill name to name),
-  set <skill><body/></skill> (set skill to body), and
-  then you *MUST* once output the following output <template/>:
+
+  In case <skill/> later becomes *not* empty by defining it as <skill
+  name="<name/>"><body/></skill>, set <skill-name><name/></skill-name>
+  (set skill name to name), and then (but only if `$1` is *NOT* equal
+  to `-h` or `--help`) you *MUST* once output the following output
+  <template/>:
+
+  <template>
+  ⧉ **ASE**: ✪ skill: **<skill-name/>**, ✦ purpose: **<skill/>**, ▶ status: **skill started**
+  </template>
+
+  Later (but only if `$1` is *NOT* equal to `-h` or `--help`), once
+  this skill finally will stop processing, you *MUST* once output the
+  following output <template/>:
 
   <template>
-  ⧉ **ASE**: ☻ skill: **<skill-name/>**, ✦ purpose: **<skill/>**, ▶ status: **skill started**
+  ⧉ **ASE**: ✪ skill: **<skill-name/>**, status: **skill finished**
   </template>
 
 - *IMPORTANT*: Set <objective></objective> (set to empty).
@@ -175,6 +184,14 @@ Skill Identification
   you *MUST* once output the following output <template/>:
 
   <template>
-  ⧉ **ASE**: ◎ objective: **<objective/>**
+  ⧉ **ASE**: ✪ skill: **<skill-name/>**, ◎ objective: **<objective/>**
   </template>
 
+- *IMPORTANT*:
+  If `$1` (the first token of the skill arguments) is equal to `-h` or
+  `--help`, you *MUST* once output the following output <template/> and
+  then *IMMEDIATELY* *STOP* the further skill processing:
+
+  <template>
+  @${CLAUDE_SKILL_DIR}/help.md
+  </template>

package/plugin/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "http://github.com/rse/ase",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "http://github.com/rse/ase/issues" },
-    "version":                              "0.0.56",
+    "version":                              "0.0.57",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

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

@@ -1,6 +1,6 @@
 ---
 name: ase-arch-analyze
-argument-hint: "<source-reference>"
+argument-hint: "[--help|-h] <source-reference>"
 description: Review software architecture, including package cohesion and inter-package coupling
 user-invocable: true
 disable-model-invocation: false
@@ -102,20 +102,13 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-control.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
 
-Review Software Architecture
-============================
-
 <skill name="ase-arch-analyze">
 Review Software Architecture
 </skill>
 
-<role>
-Your role is an experienced, *expert-level software architect*,
-specialized in *reviewing software architecture*.
-</role>
-
 <objective>
-*Review* the *software architecture* of $ARGUMENTS, and its directly
+With the mindset of an *expert-level software architect*,
+*review* the *software architecture* of $ARGUMENTS, and its directly
 related source code, for *potential problems* across component
 boundaries, structural organization, architecture principles,
 interface quality, quality attributes, and architecture governance.

package/plugin/skills/ase-arch-analyze/help.md

@@ -0,0 +1,50 @@
+
+##  NAME
+
+`ase-arch-analyze` - Review Software Architecture
+
+##  SYNOPSIS
+
+`ase-arch-analyze`
+    [`--help`|`-h`]
+    *source-reference*
+
+##  DESCRIPTION
+
+The `ase-arch-analyze` skill reviews the *software architecture* of
+the referenced source code, including *package cohesion* and *inter-
+package coupling*, for *potential problems* across component boundaries,
+structural organization, architecture principles, interface quality,
+quality attributes, and architecture governance.
+
+The skill investigates 21 architecture quality aspects across 7 thematic
+blocks (component boundaries, structural organization, architecture
+principles, interface quality, quality attributes, architecture
+governance, and package cohesion), renders a high-level architecture
+diagram, and reports findings as either `PROBLEM` or `TRADEOFF` entries
+based on a built-in tension matrix.
+
+##  ARGUMENTS
+
+*source-reference*:
+    A file, directory, or other reference to the source code that
+    is to be analyzed architecturally.
+
+##  EXAMPLES
+
+Analyze architecture of the current project:
+
+```text
+❯ /ase-arch-analyze src/
+```
+
+Analyze a specific module:
+
+```text
+❯ /ase-arch-analyze src/core
+```
+
+##  SEE ALSO
+
+`ase-arch-discover`, `ase-code-analyze`, `ase-code-resolve`,
+`ase-code-refactor`, `ase-code-insight`.

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

@@ -1,6 +1,6 @@
 ---
 name: ase-arch-discover
-argument-hint: "<functionality>"
+argument-hint: "[--help|-h] <functionality>"
 description: >
     Discover additional, third-party components (libraries/frameworks) for
     the technology stack to provide needed functionality.
@@ -17,18 +17,10 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-control.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
 
-Discover Components
-===================
-
 <skill name="ase-arch-discover">
 Discover Components
 </skill>
 
-<role>
-Your role is an experienced, *expert-level software architect*,
-specialized in *finding components* (libraries/frameworks) for the technology stack.
-</role>
-
 <objective>
 *Discover* additional, *third-party components* (libraries/frameworks)
 for the technology stack to *provide* the *needed functionality*

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

@@ -0,0 +1,48 @@
+
+##  NAME
+
+`ase-arch-discover` - Discover Components
+
+##  SYNOPSIS
+
+`ase-arch-discover`
+    [`--help`|`-h`]
+    *functionality*
+
+##  DESCRIPTION
+
+The `ase-arch-discover` skill discovers additional, *third-party
+components* (libraries/frameworks) for the technology stack that
+provide the needed *functionality*.
+
+The skill determines the project's technology stack (TypeScript,
+JavaScript, Kotlin, or Java), derives essential keywords from the
+requested functionality, queries the corresponding package registry
+(NPM or Maven Central), retrieves metadata (version, downloads,
+stars, dates) via the `ase_component_info` MCP tool, and reports
+the top-ranked components as a Markdown table together with a single
+distinguishing hint (USP, Crux, or Gotcha) per component.
+
+##  ARGUMENTS
+
+*functionality*:
+    A short description of the desired functionality the third-party
+    component should provide.
+
+##  EXAMPLES
+
+Discover components for JSON schema validation:
+
+```text
+❯ /ase-arch-discover JSON schema validation
+```
+
+Discover components for HTTP client functionality:
+
+```text
+❯ /ase-arch-discover HTTP client with retries
+```
+
+##  SEE ALSO
+
+`ase-arch-analyze`, `ase-meta-search`, `ase-meta-evaluate`.

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

@@ -1,6 +1,6 @@
 ---
 name: ase-code-analyze
-argument-hint: "<source-reference>"
+argument-hint: "[--help|-h] <source-reference>"
 description: >
     Analyze the source code for problems in the logic and semantics and its related control flow.
 user-invocable: true
@@ -13,18 +13,10 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-control.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

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

@@ -0,0 +1,47 @@
+
+##  NAME
+
+`ase-code-analyze` - Analyze Source Code
+
+##  SYNOPSIS
+
+`ase-code-analyze`
+    [`--help`|`-h`]
+    *source-reference*
+
+##  DESCRIPTION
+
+The `ase-code-analyze` skill analyzes the source code of the referenced
+location, and its directly related source code, for problems in its
+*logic*, *semantics*, and related *control flow*.
+
+The skill investigates the code base silently, reports each detected
+problem as a `PROBLEM` entry with severity (`LOW`, `MEDIUM`, `HIGH`),
+inline file/line references, and persists results in the `ase` MCP
+key/value store as `ase-issue-P<n>` entries so they can later be
+resolved via `ase-code-resolve P<n>`.
+
+##  ARGUMENTS
+
+*source-reference*:
+    A file, directory, function, or other reference to the source code
+    to analyze.
+
+##  EXAMPLES
+
+Analyze a specific source file:
+
+```text
+❯ /ase-code-analyze src/server.ts
+```
+
+Analyze a directory of code:
+
+```text
+❯ /ase-code-analyze src/handlers/
+```
+
+##  SEE ALSO
+
+`ase-code-resolve`, `ase-code-refactor`, `ase-code-lint`,
+`ase-code-explain`, `ase-arch-analyze`.

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

@@ -1,6 +1,6 @@
 ---
 name: ase-code-craft
-argument-hint: "[<task-id>:] <feature>"
+argument-hint: "[--help|-h] [--auto|-a] [--next|-n <option>] [<task-id>:] <feature>"
 description: >
     Craft Source Code:
     Use when user wants to create or craft a new feature from scratch.
@@ -17,9 +17,6 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
 
-Craft Feature
-=============
-
 <skill name="ase-code-craft">
 Craft Source Code
 </skill>
@@ -30,10 +27,6 @@ Craft Source Code
     $ARGUMENTS
 </expand>
 
-<role>
-Your role is an experienced, *expert-level software developer*.
-</role>
-
 <objective>
 From scratch *craft* the following feature:
 <feature><getopt-arguments/></feature>
@@ -287,9 +280,26 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ✪ plan: **<words/>** words, ▶ status: **plan created**
         </template>
 
-    5.  Directly pass-through control to the `ase:ase-task-edit` skill.
-        Set <args></args> (set args to empty). If <getopt-option-next/>
-        is not equal `none`, set <args><args/> --next
-        <getopt-option-next/></args> (append to args). Then call the
-        tool `Skill(skill: "ase:ase-task-edit", args: <args/>)`.
+    5.  Directly pass-through control to the next skill:
+
+        1.  <if condition="<getopt-option-next/> is equal `IMPLEMENT`">
+            Call the tool `Skill(skill: "ase:ase-task-implement")` to
+            *implement* the freshly composed plan, bypassing `ase-task-edit`.
+            </if>
+
+        2.  <if condition="<getopt-option-next/> is equal `PREFLIGHT`">
+            Call the tool `Skill(skill: "ase:ase-task-preflight")` to
+            *preflight* the freshly composed plan, bypassing `ase-task-edit`.
+            </if>
+
+        3.  <if condition="
+                <getopt-option-next/> is not equal `IMPLEMENT` AND
+                <getopt-option-next/> is not equal `PREFLIGHT`
+            ">
+            Set <args></args> (set args to empty).
+            <if condition="<getopt-option-next/> is not equal `none`">
+            Set <args><args/> --next <getopt-option-next/></args> (append to args).
+            </if>
+            Then call the tool `Skill(skill: "ase:ase-task-edit", args: <args/>)`.
+            </if>
 

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

@@ -0,0 +1,66 @@
+
+##  NAME
+
+`ase-code-craft` - Craft Source Code
+
+##  SYNOPSIS
+
+`ase-code-craft`
+    [`--help`|`-h`]
+    [`--auto`|`-a`]
+    [`--next`|`-n` *option*]
+    [*task-id*:] *feature*
+
+##  DESCRIPTION
+
+The `ase-code-craft` skill crafts a *new feature* from scratch by
+investigating the existing code base, internalizing crafting tenets
+(KISS, YAGNI, DRY, SRP, loose coupling, ...), proposing one or more
+*feature approaches* with pros and cons, letting the user pick the
+preferred approach, and composing a corresponding *task plan* aligned
+with the existing architecture.
+
+The skill does *not* directly modify source files. It persists the
+plan via `ase_task_save` and then hands off to `ase-task-edit`,
+`ase-task-preflight`, or `ase-task-implement`, as selected by
+`--next`.
+
+##  OPTIONS
+
+`--auto`|`-a`:
+    Automatically pick the recommended feature approach without
+    asking the user via the interactive dialog.
+
+`--next`|`-n` *option*:
+    Automatically choose the next step after composing the plan,
+    where *option* is either `none` (default, hand-off to
+    `ase-task-edit` interactively), `DONE` (stop), `EDIT` (hand off
+    to `ase-task-edit`), `PREFLIGHT` (hand off to
+    `ase-task-preflight`), or `IMPLEMENT` (hand off to
+    `ase-task-implement`).
+
+##  ARGUMENTS
+
+[*task-id*:] *feature*:
+    Description of the *feature* to craft. Optionally prefixed with
+    a *task-id* followed by a colon to bind the resulting plan to
+    a specific task id.
+
+##  EXAMPLES
+
+Craft a new logging feature:
+
+```text
+❯ /ase-code-craft add structured JSON logging with log levels
+```
+
+Craft a feature under a named task and directly hand off to implementation:
+
+```text
+❯ /ase-code-craft --next IMPLEMENT auth: add JWT authentication middleware
+```
+
+##  SEE ALSO
+
+`ase-code-refactor`, `ase-code-resolve`, `ase-task-edit`,
+`ase-task-preflight`, `ase-task-implement`.

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

@@ -1,6 +1,6 @@
 ---
 name: ase-code-explain
-argument-hint: "<source-reference>"
+argument-hint: "[--help|-h] <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?"
@@ -15,18 +15,10 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-control.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
 
-Explain Source Code
-===================
-
 <skill name="ase-code-explain">
 Explain Source Code
 </skill>
 
-<role>
-Your role is an experienced, *expert-level software developer*,
-specialized in *explaining source code*.
-</role>
-
 <objective>
 *Analyze* the source code of $ARGUMENTS, and its directly related source
 code and *explain* it in a *brief*, *standardized*, and *concise* way.

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

@@ -0,0 +1,43 @@
+
+##  NAME
+
+`ase-code-explain` - Explain Source Code
+
+##  SYNOPSIS
+
+`ase-code-explain`
+    [`--help`|`-h`]
+    *source-reference*
+
+##  DESCRIPTION
+
+The `ase-code-explain` skill analyzes and explains the source code of
+the referenced location in a *brief*, *standardized*, and *concise*
+way along six dimensions: *WHAT* (functionality), *WHY* (rationale),
+*ANALOGY* (everyday-life comparison in ELI5 style), *DIAGRAM* (Mermaid
+diagram of control flow, data flow, or structure), *CRUXES* (what to
+notice), and *GOTCHAS* (what to not stumble over).
+
+##  ARGUMENTS
+
+*source-reference*:
+    A file, directory, function, or other reference to the source code
+    to explain.
+
+##  EXAMPLES
+
+Explain a single source file:
+
+```text
+❯ /ase-code-explain src/parser.ts
+```
+
+Explain a specific function:
+
+```text
+❯ /ase-code-explain src/parser.ts#parseExpression
+```
+
+##  SEE ALSO
+
+`ase-code-insight`, `ase-code-analyze`, `ase-arch-analyze`.

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

@@ -1,6 +1,6 @@
 ---
 name: ase-code-insight
-argument-hint: "<code-references>"
+argument-hint: "[--help|-h] <code-references>"
 description: >
     Give insights into the source code.
 user-invocable: true
@@ -18,18 +18,10 @@ allowed-tools:
 @${CLAUDE_SKILL_DIR}/../../meta/ase-control.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-skill.md
 
-Project Insight
-===============
-
 <skill name="ase-code-insight">
 Project Insight
 </skill>
 
-<role>
-Your role is an experienced, *expert-level software developer*,
-specialized in *analyzing source code* and giving insights.
-</role>
-
 <objective>
 Give *insights* into the project through the source code of $ARGUMENTS.
 </objective>

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

@@ -0,0 +1,43 @@
+
+##  NAME
+
+`ase-code-insight` - Project Insight
+
+##  SYNOPSIS
+
+`ase-code-insight`
+    [`--help`|`-h`]
+    *code-references*
+
+##  DESCRIPTION
+
+The `ase-code-insight` skill gives high-level *insights* into the
+project through the referenced source code. The skill produces four
+sections: a *PROJECT ABSTRACT* (summary derived from `README.*` or
+source scanning), a *PROJECT AUTHOR* list (from `git shortlog`),
+a *SOURCE CHURN* table (most-committed files in the last year), and
+a *MODULE STRUCTURE* Mermaid diagram of modules and their imports.
+
+##  ARGUMENTS
+
+*code-references*:
+    One or more file or directory references to source code that
+    should be inspected for insights.
+
+##  EXAMPLES
+
+Get insights into the current project:
+
+```text
+❯ /ase-code-insight src/
+```
+
+Get insights into a specific subsystem:
+
+```text
+❯ /ase-code-insight tool/src/
+```
+
+##  SEE ALSO
+
+`ase-code-explain`, `ase-code-analyze`, `ase-arch-analyze`.

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

@@ -1,6 +1,6 @@
 ---
 name: ase-code-lint
-argument-hint: "<source-reference>"
+argument-hint: "[--help|-h] [--auto|-a] <source-reference>"
 description: >
     Lint source code for potential code quality problems.
     Use when the user wants to "lint" or "check" source code.
@@ -14,9 +14,6 @@ effort: high
 @${CLAUDE_SKILL_DIR}/../../meta/ase-dialog.md
 @${CLAUDE_SKILL_DIR}/../../meta/ase-getopt.md
 
-Lint Source Code
-================
-
 <skill name="ase-code-lint">
 Lint Source Code
 </skill>
@@ -27,11 +24,6 @@ Lint Source Code
     $ARGUMENTS
 </expand>
 
-<role>
-Your role is an experienced, *expert-level software developer*,
-specialized in *analyzing source code*.
-</role>
-
 <objective>
 *Analyze* the code of `<getopt-arguments/>` for *potential problems*
 related to a set of code quality aspects.