@rse/ase 0.0.57 → 0.0.59

package/dst/ase-getopt.js

@@ -52,7 +52,7 @@ export class GetoptMCP {
                 });
                 /*  tokenize spec and add one option per token  */
                 const tokens = args.spec.split(/\s+/).filter((e) => e.length > 0);
-                const re = /^--([A-Za-z][A-Za-z0-9-]*)(?:\|-([A-Za-z]))?(?:=(\((.*)\)|.*))?$/;
+                const re = /^--([A-Za-z][A-Za-z0-9-]*)(?:\|-([A-Za-z]))?(?:=(\((.*)\)(\.\.\.)?|.*))?$/;
                 for (const tok of tokens) {
                     const m = re.exec(tok);
                     if (m === null)
@@ -61,14 +61,16 @@ export class GetoptMCP {
                     const short = m[2] ?? null;
                     const valuePart = m[3] ?? null;
                     const choicePart = m[4] ?? null;
+                    const listMarker = m[5] ?? null;
                     const takesValue = valuePart !== null;
                     const choices = choicePart !== null ? choicePart.split("|") : null;
+                    const isList = listMarker !== null;
                     const dflt = choices !== null ? choices[0] : valuePart;
                     const head = short !== null ? `-${short}, --${long}` : `--${long}`;
                     const flags = takesValue ? `${head} <value>` : head;
                     const opt = new Option(flags);
                     if (takesValue) {
-                        if (choices !== null)
+                        if (choices !== null && !isList)
                             opt.choices(choices);
                         opt.default(dflt);
                     }
@@ -78,6 +80,30 @@ export class GetoptMCP {
                 }
                 /*  parse args  */
                 cmd.parse(argsVec, { from: "user" });
+                /*  validate comma-separated list-of-choices options  */
+                const listOpts = [];
+                for (const tok of tokens) {
+                    const m = re.exec(tok);
+                    if (m === null)
+                        continue;
+                    const long = m[1];
+                    const choicePart = m[4] ?? null;
+                    const listMarker = m[5] ?? null;
+                    if (choicePart !== null && listMarker !== null)
+                        listOpts.push({ long, choices: choicePart.split("|") });
+                }
+                if (listOpts.length > 0) {
+                    const opts = cmd.opts();
+                    for (const { long, choices } of listOpts) {
+                        const v = opts[long];
+                        if (typeof v !== "string")
+                            continue;
+                        const items = v.split(",").map((s) => s.trim()).filter((s) => s.length > 0);
+                        if (items.length > 0 && !choices.includes(items[0]))
+                            throw new Error(`invalid token "${items[0]}" for --${long} ` +
+                                `(allowed: ${choices.join(", ")})`);
+                    }
+                }
                 /*  compute verbatim trailing argument string  */
                 let argsVerbatim = "";
                 if (argsRaw !== null) {

package/dst/ase-hello.js

@@ -6,7 +6,7 @@
 import { Chalk } from "chalk";
 /*  forced-color chalk instance: stdout is a pipe under Claude Code,
     so chalk auto-detection would yield level 0; force level 1 to keep
-    emitting ANSI sequences  */
+    emitting ANSI sequences as the original implementation did  */
 const c = new Chalk({ level: 1 });
 /*  command-line handling  */
 export default class HelloCommand {
@@ -18,10 +18,10 @@ export default class HelloCommand {
     register(program) {
         program
             .command("hello")
-            .description("Print a friendly \"Hello World\" greeting in red")
-            .action(async () => {
-            this.log.write("debug", "hello: printing greeting");
-            process.stdout.write(c.red("Hello World") + "\n");
+            .description("Show a greeting message")
+            .option("-s, --subject <subject>", "subject to greet", "Universe")
+            .action(async (opts) => {
+            process.stdout.write(c.red(`${opts.subject} World!`) + "\n");
         });
     }
 }

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.57",
+    "version":                              "0.0.59",
     "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.57",
+    "version":     "0.0.59",
     "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.57",
+    "version":     "0.0.59",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/meta/ase-format-adr.md

@@ -0,0 +1,199 @@
+
+Architecture Decision Record (ADR)
+==================================
+
+An *Architecture Decision Record (ADR)* records
+a major decision related to the architecture.
+
+FORMAT
+------
+
+Every ADR uses a strict and fixed format:
+
+<format>
+
+# ✪ <id/> - **<title/>**
+
+✳ created:  **<timestamp-created/>**
+✎ modified: **<timestamp-modified/>**
+▶ status:   <status/>
+
+## ※ WHEN (Context)
+
+<context/>
+
+## ※ WHAT (Decision)
+
+<decision/>
+
+## ※ WHY (Rationale)
+
+<rationale/>
+
+## ※ NOTES (Background)
+
+<notes/>
+
+</format>
+
+You *MUST* honor the following hints on this *ADR* format:
+
+-   The <id/> is `ADR-<N/>-<slug/>` where <N/> is a 3-digit zero-padded
+    unique number, <slug/> is a unique "slug" of always 2 lower-cased
+    words (concatenated with "-" characters and in total not longer than
+    30 characters, and derived from the <decision/>).
+
+-   The <title/> is a short summary of the <decision/>, not longer than
+    80 characters.
+
+-   The <timestamp-created/> is the timestamp when this ADR
+    was created. The <timestamp-modified/> is the timestamp when this
+    ADR was last modified. Both use an ISO-style format value. The value
+    of both can be determined by a call to the `ase_timestamp(format:
+    "yyyy-LL-dd HH:mm")` tool of the `ase` MCP server and use the `text`
+    field of its response.
+
+-   The <status/> is `proposed`, `accepted`, `deprecated` or `superseded
+    by ADR-NNN-xxx-yyy`)
+
+-   The <context/> captures the situation that forces the <decision/> -
+    the "why are we even talking about this" part. It describes the
+    situation as it is, before the <decision/> is made.
+
+    The following usually goes into <context/>:
+
+    -   The problem or need — what's broken, missing, or about to change
+        that requires a decision.
+    -   The forces at play — technical constraints, business requirements,
+        deadlines, team skills, existing systems, regulatory/compliance
+        pressures. These are often competing and that tension is the whole point.
+    -   Relevant facts — current architecture, prior decisions,
+        assumptions, what's known and what's uncertain.
+    -   Scope/boundaries — what this decision is (and isn't) about.
+
+    It is written neutrally and factually. It should not contain the
+    decision itself, nor advocate for an option — a reader should
+    be able to read the <context/>, pause, and arrive at the decision
+    themselves because the forces make it (nearly) inevitable.
+
+-   The <decision/> states what you are actually going to do — the chosen
+    response to the forces laid out in the <context/>. It is written in
+    active, assertive voice, in the present or imperative tense, as a
+    committed position rather than a discussion.
+
+    The following usually goes into <decision/>:
+
+    -   The choice itself — clearly and unambiguously.
+    -   The essence of how — enough of the approach to make the choice
+        concrete (the mechanism, pattern, or technology), but not a full
+        implementation specification.
+
+    The <decision/> is a declaration, not a deliberation. The
+    <decision/> usually uses the wording "We use..." or "We do..."
+    and is active, definite, owning the choice. In <decision/> avoid
+    hedging ("we might", "we could consider"). The deliberation already
+    happened, the ADR records the verdict.
+
+-   The <rationale/> is the reasoning that justifies the <decision/> — the
+    bridge that explains why this choice, given those forces. It
+    answers: "Of all the things we could have done, why was this the
+    right one?". Where <context/> states the forces and <decision/>
+    states the choice, <rationale/> is the logical connective tissue
+    between them — it shows that the <decision/> actually follows from
+    the <context/>.
+
+    The following usually goes in <rationale/>:
+
+    -   The deciding factors — which forces from the <context/> carried the
+        most weight, and how the chosen option satisfies them best.
+    -   The trade-off reasoning — what you optimized for and what you
+        knowingly sacrificed. Naming the trade-off is the heart of rationale.
+    -   Why the alternatives lost — the comparative argument: "option B
+        failed on X, option C cost too much on Y."
+    -   Assumptions and evidence — benchmarks, prior experience,
+        constraints, or principles the reasoning rests on.
+
+-   The <notes/> section is *OPTIONAL* and can be omitted
+    when it does not add genuine value. Most ADRs won't need it.
+
+    The following usually goes in <notes/>:
+
+    -   Information of the decision *process* like e.g.
+        weighted decision matrix of considered alternatives.
+    -   Consequences of the <decision/> — but only when non-obvious downstream
+        effects need to be called out.
+    -   Links to strongly related ADRs.
+
+-   For the relationship between <context/>, <decision/> and <rationale/>
+    good checks are:
+
+    -   The "litmus test" is:
+        -   <context/>   = forces
+        -   <decision/>  = response to those forces,
+        -   <rationale/> = why <decision/> answers the forces in <context/>.
+
+    -   The <decision/> should feel like the natural, almost inevitable
+        answer to the <context/>. If a reader is surprised by the
+        <decision/>, either the <context/> is missing a force, or the
+        <decision/> is under-justified.
+
+    -   The <rationale/> should make the <decision/> feel earned, not
+        asserted. If you would delete the <rationale/> and the
+        <decision/> suddenly looks arbitrary, the <rationale/> was
+        doing its job. So, the <rationale/> is the justification that
+        ties the <decision/> back to the pressures in <context/>.
+
+-   The <context/>, <decision/> and <rationale/> all are just a
+    single paragraph of concise and brief prose text, usually comprised
+    of just 1 to 3 sentences. The paragraphs break all lines with a
+    newline character after about 120 characters per line. The value of
+    an ADR is in recording *that* a decision was made and *why* — not in
+    filling out sections of a document.
+
+TENETS
+------
+
+For an ADR, all of the following three tenets must be true:
+
+-   **Hard to Reverse**: the cost of changing it later is meaningful
+    ("Oh my god, this would result in a dramatic refactoring!"). So,
+    if a decision is easy to reverse, just skip it.
+
+-   **Surprising without Context**: a future architect will look at
+    the code and wonder ("Why on earth did they do it this way?").
+    So, if a decision is not surprising, nobody will wonder why.
+
+-   **Result of a Real Trade-Off**: there were genuine alternatives
+    and one was picked for specific reasons ("We deliberately chose
+    this, because..."). So, if there was no real alternative,
+    there's nothing to record beyond "we did the obvious thing."
+
+For an ADR, the following qualify:
+
+-   **Architectural shape.** "We're using a monorepo." "The write
+    model is event-sourced, the read model is projected into PostgreSQL."
+
+-   **Integration patterns between contexts.** "Ordering and Billing
+    communicate via domain events, not synchronous HTTP."
+
+-   **Technology choices that carry lock-in.** Database, message bus,
+    auth provider, deployment target. Not every library — just the
+    ones that would take a quarter to swap out.
+
+-   **Boundary and scope decisions.** "Customer data is owned by the
+    Customer context; other contexts reference it by ID only." The explicit
+    no-s are as valuable as the yes-s.
+
+-   **Deliberate deviations from the obvious path.** "We're using
+    manual SQL instead of an ORM because X." Anything where a reasonable
+    reader would assume the opposite. These stop the next engineer from
+    "fixing" something that was deliberate.
+
+-   **Constraints not visible in the code.** "We can't use AWS because
+    of compliance requirements." "Response times must be under 200ms because
+    of the partner API contract."
+
+-   **Rejected alternatives when the rejection is non-obvious.** If
+    you considered GraphQL and picked REST for subtle reasons, record it —
+    otherwise someone will suggest GraphQL again in six months.
+

package/plugin/meta/ase-getopt.md

@@ -10,24 +10,44 @@ set placeholders into the context as a side-effect.
 1.  **Determine Parameters**:
     Set <getopt-skill><arg1/></getopt-skill>.
     Set <getopt-spec>--help|-h <arg2/></getopt-spec>.
-    Set <getopt-opts><arg3/></getopt-opts>.
     Set <getopt-args><content/></getopt-args>.
 
-2.  **Short-Circuit for Quick Processing**:
-    If <getopt-opts/> contains `quick` *AND*
-    <getopt-args/> does *NOT* match the regexp `^\s*-`:
-    Set <getopt-arguments><getopt-args/></getopt-arguments> and
-    then just silently *SKIP* the following steps 3-7!
+2.  **Short-Circuit Processing**:
+    If <getopt-args/> does *NOT* match the regexp `(^|\s)-` (i.e.
+    contains no options at all):
+
+    For each option token in <getopt-spec/> of the form
+    `--<long/>[|-<short/>][=<default/>|=(<c1/>|<c2/>|...)[...]]`, set
+    <getopt-option-<long/>/> to <default/> (for `=<default/>`
+    form), or to <c1/> (the first choice, for `=(<c1/>|<c2>/|...)`
+    form, or for the list form `=(<c1/>|<c2>/|...)...`),
+    or to `false` (for value-less options). Then set
+    <getopt-arguments><getopt-args/></getopt-arguments>.
+
+    Additionally, simulate <getopt-info/> as a comma-separated
+    markdown rendering of the parsed options in the form `<longN/>:
+    **<valueN/>**, [...]` (joined with `, `, with each value
+    shell-quoted if value contains spaces or special characters, and
+    excluding the `help` option).
+
+    Then silently *SKIP* only the following steps 3-6
+    and proceed directly to step 7 to display the results.
 
 3.  **MCP Call**:
     Call the `ase_getopt(name: "<getopt-skill/>", spec:
     "<getopt-spec/>", args: "<getopt-args/>")` tool of the `ase`
     MCP server and set <text/> to the `text` output field of
     this tool call. The `spec` syntax for each option token is
-    `--<long>[|-<short>][=<default>|=(<c1>|<c2>|...)]`, where
-    `=<default>` declares a value-taking option with a default, and
+    `--<long>[|-<short>][=<default>|=(<c1>|<c2>|...)[...]]`, where
+    `=<default>` declares a value-taking option with a default,
     `=(<c1>|<c2>|...)` declares a value-taking option restricted to the
-    listed fixed choices (the first choice acts as the default).
+    listed fixed choices (the first choice acts as the default), and the
+    trailing `...` (as in `=(<c1>|<c2>|...)...`) declares a value-taking
+    option whose value is a *comma-separated list* of choice tokens
+    (the first choice still acts as the default; only the *first*
+    token of the list is validated by the parser against the choice
+    set -- subsequent tokens are *not* validated, and skills validate
+    each remaining token themselves as they consume it).
 
 4.  **Short-Circuit for Error**:
     If <text/> starts with `ERROR:`:

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.57",
+    "version":                              "0.0.59",
     "license":                              "GPL-3.0-only",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

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

@@ -6,7 +6,7 @@ description: >
     the technology stack to provide needed functionality.
 user-invocable: true
 disable-model-invocation: false
-effort: medium
+effort: high
 allowed-tools:
     - "Bash(npm search --json *)"
     - "Bash(curl -s https://search.maven.org/*)"

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

@@ -1,12 +1,12 @@
 ---
 name: ase-code-craft
-argument-hint: "[--help|-h] [--auto|-a] [--next|-n <option>] [<task-id>:] <feature>"
+argument-hint: "[--help|-h] [--auto|-a] [--dry|-d] [--next|-n <option>[,...]] [<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
+effort: xhigh
 allowed-tools:
     - "Skill"
     - "Agent"
@@ -23,7 +23,7 @@ Craft Source Code
 
 <expand name="getopt"
     arg1="ase-code-craft"
-    arg2="--auto|-a --next|-n=(none|DONE|EDIT|PREFLIGHT|IMPLEMENT)">
+    arg2="--auto|-a --dry|-d --next|-n=(none|DONE|EDIT|PREFLIGHT|IMPLEMENT)...">
     $ARGUMENTS
 </expand>
 
@@ -32,7 +32,7 @@ From scratch *craft* the following feature:
 <feature><getopt-arguments/></feature>
 </objective>
 
-@${CLAUDE_SKILL_DIR}/../../meta/ase-plan.md
+@${CLAUDE_SKILL_DIR}/../../meta/ase-format-plan.md
 
 Procedure
 ---------
@@ -172,7 +172,10 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
 
     You *MUST* perform the following sub-steps *internally* and *without
     any output* until and including the recommendation decision. Only
-    sub-step 4 below is allowed to produce output.
+    sub-steps 4-6 below are allowed to produce output, and only if
+    <getopt-option-auto/> is equal `false`. If <getopt-option-auto/> is
+    equal `true`, *skip* the reporting sub-steps 4-6 entirely (perform
+    no output at all) to speed up processing.
 
     1.  *Propose* corresponding *feature approach*, including optionally,
         some *alternative* feature approaches. Do *not* output anything
@@ -261,6 +264,18 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
         the information from feature A<n/> and all derived realization
         decisions into it. Store the resulting task plan in <content/>.
 
+        If a `CHANGELOG.md` file exists in the project (or in any
+        affected sub-package), the plan *MUST* include, as part of its
+        `## ※ CHANGES` section, an explicit bullet point describing
+        the addition of a corresponding new entry to that `CHANGELOG.md`
+        file, aligned with its existing style and conventions.
+
+        <if condition="<getopt-option-dry/> is equal `true`">
+        You *MUST* completely omit the `## ※ VERIFICATION` section
+        (including its heading and all of its bullet points) from
+        <content/>.
+        </if>
+
         You *MUST* *NOT* call `Edit`, `Write`, `NotebookEdit`, or any
         filesystem-modifying tool during this step.
 
@@ -282,23 +297,42 @@ permitted way to persist artifacts is via `ase_task_save(...)`.
 
     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`.
+        Treat <getopt-option-next/> as a comma-separated chronological
+        list of pre-selected next-step tokens. *Peek* the *first* token
+        as <head/> (or `none` if the list is `none`/empty).
+
+        1.  <if condition="<head/> is equal `IMPLEMENT`">
+            Consume the head: set <getopt-option-next/> to the remaining
+            tokens (joined back with `,`, or `none` if empty). Set
+            <args></args> (empty).
+            <if condition="<getopt-option-next/> is not equal `none`">
+            Set <args>--next <getopt-option-next/></args> (forward
+            remaining list tokens to the downstream skill).
+            </if>
+            Call the tool `Skill(skill: "ase:ase-task-implement", args: <args/>)`
+            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`.
+        2.  <if condition="<head/> is equal `PREFLIGHT`">
+            Consume the head: set <getopt-option-next/> to the remaining
+            tokens (joined back with `,`, or `none` if empty). Set
+            <args></args> (empty).
+            <if condition="<getopt-option-next/> is not equal `none`">
+            Set <args>--next <getopt-option-next/></args> (forward
+            remaining list tokens to the downstream skill).
+            </if>
+            Call the tool `Skill(skill: "ase:ase-task-preflight", args: <args/>)`
+            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`
+                <head/> is not equal `IMPLEMENT` AND
+                <head/> is not equal `PREFLIGHT`
             ">
-            Set <args></args> (set args to empty).
+            Forward the *entire* (unshifted) list to `ase-task-edit`, which
+            will consume its head itself. Set <args></args> (empty).
             <if condition="<getopt-option-next/> is not equal `none`">
-            Set <args><args/> --next <getopt-option-next/></args> (append to args).
+            Set <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

@@ -8,7 +8,8 @@
 `ase-code-craft`
     [`--help`|`-h`]
     [`--auto`|`-a`]
-    [`--next`|`-n` *option*]
+    [`--dry`|`-d`]
+    [`--next`|`-n` *option*[,...]]
     [*task-id*:] *feature*
 
 ##  DESCRIPTION
@@ -31,13 +32,28 @@ plan via `ase_task_save` and then hands off to `ase-task-edit`,
     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`).
+`--dry`|`-d`:
+    Compose the plan *without* the `※ VERIFICATION` section. When
+    `ase-task-implement` later applies such a plan, it strictly skips
+    the entire verification phase (no build, tests, linter,
+    type-checker, or program execution) once the source files have
+    been modified.
+
+`--next`|`-n` *option*[,...]:
+    Automatically choose the next step after composing the plan.
+    *option* is a single token or a *comma-separated chronological
+    list* of tokens; an `IMPLEMENT` or `PREFLIGHT` head token is
+    consumed by this skill (bypassing `ase-task-edit`), and any
+    remaining tokens are *forwarded* (via `--next`) to the downstream
+    skill. For all other head tokens, the *entire* list is forwarded
+    to `ase-task-edit`, which consumes its head itself. This lets an
+    entire pipeline be pre-scripted in one shot. Recognized tokens at
+    this skill: `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`). Example:
+    `--next PREFLIGHT,IMPLEMENT,DONE` crafts the plan, preflights it,
+    implements it, and exits without further dialog.
 
 ##  ARGUMENTS
 

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

@@ -6,7 +6,7 @@ description: >
     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
+effort: high
 allowed-tools:
     - "Skill"
     - "Agent"

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

@@ -5,7 +5,7 @@ description: >
     Give insights into the source code.
 user-invocable: true
 disable-model-invocation: false
-effort: medium
+effort: high
 allowed-tools:
     - "Bash(git)"
     - "Bash(sort)"