@rse/ase 0.9.61 → 0.9.63

package/plugin/meta/ase-common-grill.md

@@ -0,0 +1,89 @@
+
+Grill Skill Common Steps
+========================
+
+<define name="grill-understanding">
+
+-   GOAL:
+
+    Interactively interviewing the user *relentlessly* about every
+    *essential aspect* of <arg1/> *until* reaching a shared
+    understanding and no major decisions/questions are left open.
+
+    This especially means that you *MUST* clarify as many aspects as
+    necessary to ensure that for at least the most important decisions,
+    during a subsequent implementation, no essential freedom of choice
+    exists any longer.
+
+-   FOCUS:
+
+    Focusing on the following outside-in *Focus Areas*, in order of
+    descending importance for the grilling operation:
+
+    1.  *DOMAIN*: Aspects affecting domain-specifics. These
+        aspects *MUST* be clarified, as they are about
+        the "what" of the solution and they
+        non-technically shape the solution noticeably.
+
+    2.  *INTERFACE*: Aspects affecting externally observable
+        behavior or interfaces, especially aspects about user (UI)
+        and machine (API) interfaces. These aspects *MUST* be
+        clarified, as they are externally visible and
+        shape the boundary of the solution.
+
+    3.  *ARCHITECTURE*: Aspects affecting software and system
+        architecture, especially decisions on structure, wiring,
+        placement, or dependencies. These aspects *SHOULD*
+        be clarified, as they technically shape the solution noticeably.
+
+    4.  *IMPLEMENTATION*: Aspects affecting any other
+        implementation details, especially how <arg1/>
+        is realized in the code base. These aspects *CAN* be
+        clarified, as they shape technical inner details only.
+
+-   SEVERITY:
+
+    The *Focus Area* indicate the severity of the aspect:
+
+    -   severity *MUST*   for *DOMAIN*         focus area
+    -   severity *MUST*   for *INTERFACE*      focus area
+    -   severity *SHOULD* for *ARCHITECTURE*   focus area
+    -   severity *MAY*    for *IMPLEMENTATION* focus area
+
+-   INDICATORS:
+
+    Check the following indicators for identifying problematic
+    aspects:
+
+    -   *Fuzzy Language*:
+        When the user uses vague or overloaded terms instead of
+        a precise or canonical term.
+
+    -   *Conflicting Terminology*:
+        When the user uses a term that conflicts with the
+        existing terminology in the code base.
+
+    -   *Conflicting Code*:
+        When the user states how something works, check whether the
+        current code state really agrees.
+
+    -   *Non-Concrete Scenarios*:
+        When domain relationships are being discussed,
+        stress-test them with specific scenarios. Theoretically
+        invent realistic scenarios that probe edge cases and
+        force the user to be precise about the boundaries
+        between concepts.
+
+    -   *Unspecified Architecture Patterns*:
+        When the realization of the functionality is known to
+        be reasonably realizable with more than one decent
+        architecture pattern, but no such pattern was
+        mentioned.
+
+    -   *Unspecified Dependencies*:
+        When the realization of functionality usually is known
+        to be supported by the use of frameworks or libraries,
+        but no dependencies on such solutions were mentioned.
+
+</define>
+

package/plugin/meta/ase-dialog.md

@@ -36,6 +36,12 @@ following procedure:
     description. The second and following lines each provide an
     answer label and an answer description.
 
+    Parse the first line by splitting it at its *first* `: ` into
+    <question-label/> (the text before) and <question-description/>
+    (the remaining text, *without* the label). The label is rendered
+    *only* as the box subtitle below, so <question-description/>
+    *MUST* *NOT* repeat it.
+
     Do not output anything in this step!
 
 2.  Render the custom dialog, collect the user input, and dispatch on the result:

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

@@ -2,115 +2,33 @@
 Artifact Meta Information
 =========================
 
-**ASE** knows about the following three levels of documentation:
+**ASE** knows about the following **Artifact Set**s of a project, each
+identified by a unique <artifact-set-id/>:
 
--   **Artifact Set**:
+-   `Specification` (`SPEC`), aka "Software Requirements Specification
+    (SRS)", "Product Requirements Document (PRD)", "Requirements",
+    "Software Architecture Specification (SAS)", "Architecture
+    Description", or "Architecture Decision Record (ADR)". It covers
+    both the *requirements* ("what") and the *architecture* ("how") of
+    the project and is authored in the **SpecBook** format (see
+    `ase-format-spec.md`).
 
-    At the root, at level 1, there are the following known **Artifact Set**s:
+-   `Source Code` (`CODE`), aka "Software Implementation Results (IMP)",
+    "Code", or "Software".
 
-    -   `Specification` (`SPEC`), aka "Software Requirements Specification
-        (SRS)", "Product Requirements Document (PRD)", or just
-        "Requirements".
+-   `Documentation` (`DOCS`), aka "Software Documentation Results (DOC)".
 
-    -   `Architecture` (`ARCH`), aka "Software Architecture Specification
-        (SAS)", "Architecture Description", or "Architecture Decision
-        Record (ADR)".
+-   `Tasks` (`TASK`), aka "Task Plans", "Issues", or "User Stories". It
+    is authored in the task plan format (see `ase-format-task.md`).
 
-    -   `Source Code` (`CODE`), aka "Software Implementation Results (IMP)",
-        "Code", or "Software".
+-   `Infrastructure` (`INFR`), aka "Infrastructure as Code (IaC)",
+    "Deployment", or "Operations".
 
-    -   `Documentation` (`DOCS`), aka "Software Documentation Results (DOC)".
+-   `Other` (`OTHR`), the implicit catch-all for any artifacts not
+    covered by the other **Artifact Set**s.
 
-    -   `Tasks` (`TASK`), aka "Task Plans", "Issues", or "User Stories".
-
-    -   `Infrastructure` (`INFR`), aka "Infrastructure as Code (IaC)",
-        "Deployment", or "Operations".
-
-    -   `Other` (`OTHR`), the implicit catch-all for any artifacts not
-        covered by the other **Artifact Set**s.
-
-    Each **Artifact Set** has a unique identifier <artifact-set-id/>,
-    which is one of `SPEC`, `ARCH`, `CODE`, `DOCS`, `TASK`, `INFR`, or
-    `OTHR`.
-
--   **Artifact**:
-
-    At level 2, each **Artifact Set** is composed of many **Artifact**s.
-    Each **Artifact** has an identifier <artifact-id/>, which is an
-    upper-case, two-letter identifier (e.g. `CJ` for `Customer Journey`)
-    derived from the **Artifact** name. The <artifact-id/> is unique
-    only *within* its **Artifact Set**; the globally-unique handle of an
-    **Artifact** is the qualified form <artifact-set-id/>-<artifact-id/>
-    (e.g. `SPEC-DP` and `ARCH-DP` are distinct artifacts). All
-    references to an **Artifact** *MUST* use this qualified form.
-
-    Each **Artifact** also has a sequence number <artifact-no/>, which
-    is the zero-padded, two-digit position of the **Artifact** (starting
-    at `01`) within the ordered list of **Artifact**s of its **Artifact
-    Set**. The <artifact-no/> is used only in the **Artifact**'s file
-    name (for stable ordering) and is *not* part of the **Artifact**'s
-    or its **Aspect**s' identifiers.
-
-    All lines of an **Artifact** should be kept below 140 characters,
-    whenever possible by line-breaking with newlines after about 120
-    characters per line.
-
--   **Aspect**:
-
-    At level 3, each **Artifact** is composed of many **Aspect**s.
-    Each **Aspect** has a unique identifier <aspect-id/>, which is a
-    unique "slug" of always 1-3 lower-cased words (concatenated with "-"
-    characters and in total not longer than 30 characters). An example
-    is `user-login`.
-
-Each **Artifact** file *MUST* begin with a single blank line before its
-`#` heading and end with a single blank line after its last content line
-(followed by the trailing newline), mirroring the blank lines shown
-inside the `<format>` blocks below.
-
-Each **Artifact** contains two timestamps: the <timestamp-created/>
-is the timestamp when this **Artifact** was created. The
-<timestamp-modified/> is the timestamp when this **Artifact** 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, using the `text` field of its response.
-Whenever an **Artifact** is updated, the <timestamp-modified/> *MUST* be
-updated, too.
-
-An **Artifact** *MAY* additionally declare an **Export** -- a derived,
-ready-to-consume rendering of (part of) its content, materialized as a
-*side-by-side* file next to the **Artifact** itself. An **Artifact**
-without an `-   Export:` bullet is *not* exported.
-
-An **Export** is declared by a single `-   Export:` bullet point in the
-**Artifact**'s format definition (see `ase-format-spec.md` and
-`ase-format-arch.md`), of the following format:
-
-<format>
-
--   Export: `<export-name/>.<export-ext/>`
-    <export-transform/>
-
-</format>
-
-with the following details:
-
--   <export-ext/> is the file-name extension (without the leading dot,
-    e.g. `svg`, `md`) of the exported file, which also implies its
-    target format.
-
--   <export-transform/> is a description of *how* the **Artifact**'s
-    content is transformed into the exported file (e.g. "the entities,
-    attributes, and relations rendered as a Mermaid `classDiagram` and
-    converted to SVG").
-
-The exported file is stored *side-by-side* with the **Artifact** under
-the path:
-
-`<basedir/>/<artifact-set-id/>-<artifact-no/>-<artifact-id/>-<artifact-slug/>-<export-name/>.<export-ext/>`
-
-where <artifact-slug/> is the same slug used in the **Artifact**'s own
-file name -- derived from the **Artifact** name by Pascal-casing each
-word and joining the words with `-` characters (e.g. `Customer-Journey`)
--- as defined by the **Artifact Set**'s own format definition (see
-`ase-format-spec.md` and `ase-format-arch.md`).
+The <artifact-set-id/> is one of `SPEC`, `CODE`, `DOCS`, `TASK`, `INFR`,
+or `OTHR`. The files of every **Artifact Set** except `TASK` are resolved
+via the `ase_artifact_list(kind: [ ... ])` tool of the `ase` MCP server
+(with the lower-cased <artifact-set-id/> as `kind`), while the `TASK`
+files are managed by the `ase_task_*` tools.