Meta

ASE Skill Meta Information
==========================

Skill Output
------------

-   *IMPORTANT*: The following rules apply both to regular skill responses
    *and* to generated plan files (`EnterPlanMode` tool).

-   *IMPORTANT*: The syntax `<xxx>[...]</xxx>` is used to *set* the value
    of a placeholder named `xxx`, and the syntax `<xxx/>` is used to *get*
    the value of a placeholder named `xxx`.

-   *IMPORTANT*: *All* output is *exclusively* requested through
    <template/> sections. You *MUST* *NOT* output anything *UNLESS* it
    is explicitly included in such a <template/> section. Especially,
    you *MUST* *NOT* output any explanations on your own, unless
    explicitly requested.

-   *IMPORTANT*: You *MUST* output all <template/> sections *EXACTLY* as provided
    (including newlines), *EXCEPT* for expanding control items, removing
    trailing spaces, replacing the placeholders `<xxx/>` and `[...]`,
    replacing XML entities (like `&#x25CB;`) with the corresponding
    Unicode characters, and the potential reduction of prose according
    to the currently defined persona style.

-   *IMPORTANT*: For *Final-Message-Only Display* ("focus mode"):
    some agent harnesses show the user only the *final* text message of
    a turn and *hide* all text emitted *between* tool calls. If your
    harness instructions indicate such a mode (e.g. *Anthropic Claude Code CLI* with
    "focus mode" enabled), you *MUST* repeat *all* <template/> outputs
    emitted since the last shown final text message -- *verbatim*, in
    their *original order*, and each only *once* -- at the *top* of the
    next final text message (i.e. the text after the last tool call of
    a turn). Never *drop* or *summarize* a <template/> output just
    because it would land between tool calls. If no such display mode
    is indicated, do *not* repeat anything.

-   *IMPORTANT*: The active *persona style* (see `ase-persona.md`) *MUST* be applied
    to all *free-text placeholders* within <template/> sections - i.e. any placeholder
    whose content you author yourself (such as `<description/>`, `<title/>`, `<objective/>`,
    `<summary/>`, `<explanation/>`, etc.). The *structure* of the template (fixed keywords,
    punctuation, labels) remains unchanged; only the *authored content* inside free
    placeholders carries the persona style.

-   *IMPORTANT*: For *Diagrams*: whenever the response needs a
    diagram (structural, control-flow, state, sequence, class,
    entity-relationship, or metrics), you *MUST* build a Mermaid
    specification and dispatch its rendering to the `ase-meta-diagram`
    sub-agent via the `Agent` tool (`subagent_type: "ase:ase-meta-diagram"`),
    then reproduce its returned fenced code block verbatim in the
    response text. All hand-drawn ASCII frames, raw Mermaid source as a
    substitute for a rendered block, and missing reproduction of the
    rendered block are defects defined by that agent.

-   *IMPORTANT*: For Markdown *Tables*:

    -   *Alignment is mandatory*: every vertical edge character
        (`|`, `│`, `+`) that belongs in the same column *must*
        sit at the same column across all rows. Determine box
        width from the *longest* content line plus 1-space
        padding, draw the top edge to that width, then keep every
        inner line (including annotations like `!`, `?`, `*`)
        within it. Count columns and verify before emitting; a
        one-space drift is a defect - re-render.

-   *IMPORTANT*: For *Findings* (problems, tradeoffs, warnings
    emitted by analysis skills):

    -   *Evidence-grounded (mandatory)*: each finding MUST cite
        the exact line range that triggers it AND the cited
        snippet must prove the claim *verbatim*. If the cited
        lines do not prove the claim, *re-investigate and
        re-cite correctly*. Drop the finding *only* if no code
        location in the scanned files proves it - never drop
        due to sloppy citation alone.

    -   *Documented-context alignment*: cross-check each
        finding against documented context - interface
        contracts, docstrings (Javadoc, JSDoc, Python
        docstring, ...), adjacent code comments, and
        project-level AI guidance files (`CLAUDE.md`,
        `AGENTS.md`, `GEMINI.md`, `MEMORY.md`,
        `.github/copilot-instructions.md`, `.cursor/rules/`,
        or similar). Two cases resolve via the same
        mechanism - do *not* drop, keep the finding visible
        for traceability:

        -   *Problem already addressed*: the finding's
            concern is explicitly stated in a contract or
            docstring (e.g. "MUST be non-blocking"). Mark
            severity `ACCEPTED` with note "contractually
            addressed".

        -   *Fix conflicts with documented priority*: the
            recommendation would violate a documented priority
            (hot-path, allocation-free, lock-free,
            latency-sensitive, sub-µs budget). Either weaken the
            recommendation, convert it to a tradeoff, or mark
            severity `ACCEPTED` with note "priority-conflict
            accepted".

        Skills that report severity MUST support `ACCEPTED`
        in addition to `LOW`, `MEDIUM`, and `HIGH`.

Skill Sequential Processing
---------------------------

-   *IMPORTANT*: For each given <flow/>, you *MUST* use the
    `TaskCreate` tool to create a corresponding set of processing steps.

    Each `<step id="xxx" [...]>...</step>` corresponds to a
    `TaskCreate({ subject: "xxx", description: "xxx" })`. In other
    words, use the text of the `id` attribute of <step/> exactly
    *as-is* for both the `subject` and the `description` fields of
    `TaskCreate`.

    For speed, emit *all* `TaskCreate` calls together in a *single* turn
    (issued in parallel), *not* one-per-turn sequentially. Do *not*
    rely on the call order to establish the step order, as the parallel
    results carry no guaranteed ordering.

    Instead, in the *single immediately following* turn, first
    reconstruct the step-id-to-taskId mapping: because each task's
    `subject` equals the originating <step/> `id` (and <step/> ids are
    unique), match every created task back to its <step/> by comparing
    the task's `subject` to the step `id` -- read the ids straight from
    the `TaskCreate` results, or call `TaskList` if the results are
    no longer at hand.

    Then establish the strict order explicitly by chaining the created
    tasks with `TaskUpdate`: for each <step/> after the first one, set
    <this/> to the mapped taskId of this step and <prev/> to the mapped
    taskId of the predecessor step from the reconstructed mapping, and
    call `TaskUpdate({ taskId: "<this/>", addBlockedBy: [ "<prev/>" ]
    })` so that every step (with `taskId` <this/>) is blocked by its
    predecessor step (with `taskId` <prev/>).

-   *IMPORTANT*: For each <step/> you *MUST* use the `TaskUpdate` tool
    for updating its status *during* processing, once a <step/> has finished.

-   *IMPORTANT*: Whenever a skill *stops early* -- because a <step/>
    instructed you to *STOP* processing (on an error, a cancelled
    dialog, a short-circuit branch, or any other early exit) -- you
    *MUST*, *before* emitting the final <template/>, use the `TaskUpdate`
    tool to set the status of *every* still `pending` or `in_progress`
    task of the current <flow/> to `deleted`, so that no task of a
    finished skill remains open. Steps that were *skipped* because their
    `condition` attribute was not met *MUST* be treated the same way.

-   *IMPORTANT*: You *MUST* *strictly sequentially* execute every <step/> in
    a <flow/>. You *MUST* not implicitly skip any <step/> during
    processing, unless you were explicitly requested to do this or the
    step is configured to be a conditional step!

-   *IMPORTANT*: You *MUST* *strictly sequentially* execute every numbered
    item in a <step/>. You *MUST* not implicitly skip any numbered item during
    processing, unless you were explicitly requested to do this!

-   *IMPORTANT*: For any <step/> that specifies an *agent* in its
    `agent="[...]"` XML attribute, you *MUST* use the specified
    *agent* to execute the instructions for that <step/>.

-   *IMPORTANT*: If you need clarification on any details of your current
    <step/>, temporarily stop and immediately ask the user specific
    numbered questions, and then continue immediately once you have all
    of the information you need.

-   *IMPORTANT*: You *MUST* output the result of all <step/> *EXACTLY* as
    provided, without any further text interpretations and modifications.

MCP Tool Calls
--------------

-   *IMPORTANT*: Whenever you call *any* tool from the `ase` MCP server,
    you *MUST* check the response immediately:

    -   If the call fails because the `ase` MCP server is not running
        (tool not found, connection refused, server not connected, internal
        error), output the following and stop immediately:

        <template>
        ⧉ **ASE**: **ERROR:** MCP server not running - please start it via `ase service start` and reconnect via `/mcp`, then retry.
        </template>

    -   If the call fails for any other reason (timeout, transport error,
        or other infrastructure problem), output the following and stop immediately:

        <template>
        ⧉ **ASE**: **ERROR:** MCP tool unavailable
        </template>

    -   If the response `text` starts with or contains `ERROR: <info/>`,
        output the following and stop immediately:

        <template>
        ⧉ **ASE**: **ERROR:** MCP tool failed: <info/>
        </template>

        *EXCEPTION*: this rule does *NOT* apply to the `ase_getopt` tool,
        whose `ERROR:`-prefixed output is *expected* option-parsing
        feedback handled exclusively by step 4 of the `getopt` procedure
        (see `ase-getopt.md`); never emit this generic template for an
        `ase_getopt` response.

    -   Only on a clean response: proceed as the skill instructs.

Skill Identification
--------------------

-   *IMPORTANT*: Set <purpose></purpose> (set to empty)
    and <skill-name></skill-name> (set name to empty).

    In case <purpose/> later becomes *not* empty by defining it as
    <purpose name="<name/>"><body/></purpose>, set
    <skill-name><name/></skill-name> (set skill name to name), and then
    (but only if ((`$1` is *NOT* equal to `-h` or `--help`) *AND*
    (<ase-guidance-level/> is equal to `normal` or `verbose`))) you *MUST*
    once output the following output <template/>:

    <template>
    ⧉ **ASE**: ✪ skill: **<skill-name/>**, ✦ purpose: **<purpose/>**, ▶ status: **skill started**
    </template>

    Later (but only if ((`$1` is *NOT* equal to `-h` or `--help`) *AND*
    (<ase-guidance-level/> is equal to `normal` or `verbose`))), once
    this skill finally will stop processing, you *MUST* once output the
    following output <template/>:

    <template>
    ⧉ **ASE**: ✪ skill: **<skill-name/>**, ▶ status: **skill finished**
    </template>

-   *IMPORTANT*: Set <objective></objective> (set to empty).
    Then, in case <objective/> later becomes *not* empty
    (but only if <ase-guidance-level/> is equal to `normal` or `verbose`),
    you *MUST* once output the following output <template/>:

    <template>
    ⧉ **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>

-   *IMPORTANT*:
    You *MUST* *NOT* output any summaries, explanations, or next
    steps at the end of a skill besides the explicit outputs via any
    <template/>.

Artifact Boxing Transparency
----------------------------

-   *IMPORTANT*: The *boxing* of a project (indicated by
    <ase-project-boxing/> configuration) classifies how *transparent*
    its *source artifacts* (specification, architecture, source code,
    documentation, infrastructure, task plan, and other artifacts) are,
    and thus how *deeply* you *MUST* inspect or produce them and how
    *much* of their internals you *MUST* surface.

-   *IMPORTANT*: Boxing modulates only the *work depth* (inspection and
    production thoroughness) and the *output visibility* (surfaced
    content and findings) of *artifact-touching* skills, per the three
    lists below. It *MUST* *NOT* alter the *communication style*
    (governed exclusively by the persona), and it *MUST* *NOT* apply to
    skills that neither read, critique, nor write any project source
    artifact.

    -   If <ase-project-boxing/> is `white`:
        -   Transparency:      *fully*
        -   Work depth:        inspect *fully*, produce *thoroughly*
        -   Findings surfaced: *all*
        -   Internals exposed: *full* (complete diffs, exhaustive rationale)

    -   If <ase-project-boxing/> is `grey`:
        -   Transparency:      *partially*
        -   Work depth:        inspect *significant* parts, produce *reasonably*
        -   Findings surfaced: *essentials*, summarize rest
        -   Internals exposed: *key* only (essential hunks, condensed rationale), summarize rest

    -   If <ase-project-boxing/> is `black`:
        -   Transparency:      *none*
        -   Work depth:        *minimum* work to satisfy the request
        -   Findings surfaced: *none* (report only the *outcome*)
        -   Internals exposed: *none* (no diffs, no code, no per-artifact explanation)

-   *IMPORTANT*: Precedence rule: a skill's *explicit* `black` branches
    and a skill's *explicit* output suppression instructions
    deterministically skip or suppress and *win* over the implicit decisions
    above. Where no such branches or instructions exist, the decisions
    above apply.

Guidance Hint Level
-------------------

-   *IMPORTANT*: The *guidance* of the agent (indicated by
    <ase-guidance-level/> configuration) classifies how many
    *unsolicited hints* -- pointers to the available *ASE* skills, to
    their options, and to the recommended next operations, which the
    user did *not* explicitly ask for -- you *MUST* emit in addition to
    the requested result.

-   *IMPORTANT*: Guidance modulates only the *hints*, per the four
    levels below. It *MUST* *NOT* alter the *communication style*
    (governed exclusively by the persona), it *MUST* *NOT* alter the
    *work depth* or the *output visibility* (governed exclusively by the
    boxing), and it *MUST* *NOT* suppress, reduce, or expand any
    *requested* output. In particular, guidance *MUST* *NOT* apply to:

    -   the *manual page* emitted for `-h`/`--help`, which is
        explicitly requested,
    -   the *skill catalog*, *manual page*, and *command proposal*
        results of the `ase-help-skill` and `ase-help-intent` skills,
        which are explicitly requested,
    -   the *option affordance* lines of a user dialog (e.g. `Please
        choose *one* option by typing ...`), which are functional parts
        of the dialog and not hints,
    -   the *artifact state* lines of a skill (e.g. `plan loaded`, `plan
        created`, `task given`) and every `ERROR:` line, which carry
        state rather than pointers.

    The *skill identification* chrome (the `skill started`, `skill
    finished`, and `objective` lines) is the sole exception: it is
    *decoration* rather than result, so it is gated on `normal` and
    `verbose` directly in the `Skill Identification` section above.

-   *IMPORTANT*: Every hint carries a *level* -- `minimal`, `normal`,
    or `verbose` -- and is emitted only if the configured
    <ase-guidance-level/> *includes* that level:

    -   If <ase-guidance-level/> is `none`:
        -   Hints emitted: *none*
    -   If <ase-guidance-level/> is `minimal`:
        -   Hints emitted: `minimal` -- the *essential* pointers only,
            i.e. those without which the just-produced result cannot be
            consumed at all (such as the follow-up command that turns
            persisted findings into actual changes)
    -   If <ase-guidance-level/> is `normal`:
        -   Hints emitted: `minimal` *and* `normal` -- additionally the
            *canonical next step* of the finished skill
    -   If <ase-guidance-level/> is `verbose`:
        -   Hints emitted: `minimal`, `normal`, *and* `verbose` --
            additionally the *unused options* of the current skill, the
            *related* skills, and the *configuration* skills
    -   If <ase-guidance-level/> is empty or not set:
        -   Treat it as `normal`

-   *IMPORTANT*: A hint *MUST* be emitted *exclusively* through the
    `<ase-tpl-hint/>` template pattern below, and *never* as free-text
    prose, so that its suppression is uniform across all skills.

Template Patterns
-----------------

-   *IMPORTANT*: In every `<template/>` below you *MUST* reproduce all
    box-drawing and decorative glyphs *verbatim*, character-for-character,
    exactly as written. This especially includes the corner and edge
    characters `╭`, `╰`, and `│`, the shoulder character `━`, the bar
    character `─`, and the trailing dotted character `┈`. You *MUST* *NOT*
    substitute visually similar ASCII fallbacks (e.g. `+`, `|`, `-`) or
    other Unicode look-alikes, and you *MUST* *NOT* drop, add, or reorder
    any of these glyphs.

-   When `<ase-tpl-head/>` (no title attribute) should be expanded, use:

    <template>

    ╭───────────────────────────────────────────────────────────────────┈┈┈┈┈┈┈┈┈┈

    </template>

-   When `<ase-tpl-head title="<title/>"[ subtitle="<subtitle/>"]/>`
    should be expanded use the following helper placeholders and then
    the following <template/>:

    -   <if condition="<subtitle/> is not empty">
            Set <raw-title>⧉ ASE: <title/>: <subtitle/></raw-title>.
            Set <render-title>⧉ ASE: **`<title/>`**: `<subtitle/>`</render-title>.
        </if>
        <else>
            Set <raw-title>⧉ ASE: <title/></raw-title>.
            Set <render-title>⧉ ASE: **`<title/>`**</render-title>.
        </else>
    -   Set <raw-title-len/> to the number of characters in the visible
        un-styled text <raw-title/>.
    -   Set <bar/> to the `─` character repeated exactly max(0, 67 - <raw-title-len/>)
        times -- clamped to zero so an over-long title never yields a
        negative count -- the very same bar-width rule as `<ase-tpl-foot/>`
        and `<ase-tpl-boxed/>`, so equal visible text yields equal total
        width.

    <template>

    ╭────━━━━**(** <render-title/> **)**━━━━────<bar/>┈┈┈┈┈┈┈┈┈┈

    </template>

-   When `<ase-tpl-foot/>` (no title attribute) should be expanded, use:

    <template>

    ╰───────────────────────────────────────────────────────────────────┈┈┈┈┈┈┈┈┈┈

    </template>

-   When `<ase-tpl-foot title="<title/>"[ subtitle="<subtitle/>"]/>`
    should be expanded use the following helper placeholders and then
    the following <template/>:

    -   <if condition="<subtitle/> is not empty">
            Set <raw-title>⧉ ASE: <title/>: <subtitle/></raw-title>.
            Set <render-title>⧉ ASE: **`<title/>`**: `<subtitle/>`</render-title>.
        </if>
        <else>
            Set <raw-title>⧉ ASE: <title/></raw-title>.
            Set <render-title>⧉ ASE: **`<title/>`**</render-title>.
        </else>
    -   Set <raw-title-len/> to the number of characters in the visible
        un-styled text <raw-title/>.
    -   Set <bar/> to the `─` character repeated exactly max(0, 67 - <raw-title-len/>)
        times -- clamped to zero so an over-long title never yields a
        negative count.

    <template>

    ╰────━━━━**(** <render-title/> **)**━━━━────<bar/>┈┈┈┈┈┈┈┈┈┈

    </template>

-   When `<ase-tpl-hint level="<level/>"><content/></ase-tpl-hint>`
    should be expanded, first determine whether the hint passes the
    configured guidance level (see `Guidance Hint Level` above):

    -   Set <emit>false</emit>.
    -   If <ase-guidance-level/> is `minimal` and <level/> is `minimal`,
        set <emit>true</emit>.
    -   If <ase-guidance-level/> is `normal` and <level/> is `minimal`
        or `normal`, set <emit>true</emit>.
    -   If <ase-guidance-level/> is `verbose` and <level/> is `minimal`,
        `normal`, or `verbose`, set <emit>true</emit>.
    -   If <ase-guidance-level/> is empty or not set, treat it as
        `normal` and apply the corresponding decision above.

    Then dispatch on <emit/>:

    <if condition="<emit/> is `true`">
        <template>
        ⧉ **ASE**: ▷ hint [<level/>]: **<content/>**
        </template>
    </if>
    <else>
        This construct is expanded into *nothing*.
        Do not output anything.
    </else>

-   When `<ase-tpl-boxed title="<title/>"[ subtitle="<subtitle/>"]><content/></ase-tpl-boxed>`
    should be expanded use the following helper placeholders and then
    the following <template/>:

    -   <if condition="<subtitle/> is not empty">
            Set <raw-title>⧉ ASE: <title/>: <subtitle/></raw-title>.
            Set <render-title>⧉ ASE: **`<title/>`**: `<subtitle/>`</render-title>.
        </if>
        <else>
            Set <raw-title>⧉ ASE: <title/></raw-title>.
            Set <render-title>⧉ ASE: **`<title/>`**</render-title>.
        </else>
    -   Set <raw-title-len/> to the number of characters in the visible
        un-styled text <raw-title/>.
    -   Set <bar/> to the `─` character repeated exactly max(0, 67 - <raw-title-len/>)
        times -- clamped to zero so an over-long title never yields a negative count.
    -   Set <body/> to <content/> with all non-empty lines prefixed with
        `│ ` and all empty lines prefixed with just `│` (so no trailing
        whitespace is produced). Do *not* prefix any line twice -- the
        <content/> itself *MUST* *NOT* contain any `│` prefixes already.

    <template>

    ╭────━━━━**(** <render-title/> **)**━━━━────<bar/>┈┈┈┈┈┈┈┈┈┈
    │
    <body/>
    │
    ╰────━━━━**(** <render-title/> **)**━━━━────<bar/>┈┈┈┈┈┈┈┈┈┈

    </template>

-   When `<ase-tpl-key digit="<digit/>"/>` should be expanded, use:

    <if condition="<digit/> is '1'"><template>➊</template></if>
    <if condition="<digit/> is '2'"><template>➋</template></if>
    <if condition="<digit/> is '3'"><template>➌</template></if>
    <if condition="<digit/> is '4'"><template>➍</template></if>
    <if condition="<digit/> is '5'"><template>➎</template></if>
    <if condition="<digit/> is '6'"><template>➏</template></if>
    <if condition="<digit/> is '7'"><template>➐</template></if>
    <if condition="<digit/> is '8'"><template>➑</template></if>
    <if condition="<digit/> is '9'"><template>➒</template></if>

-   When `<ase-tpl-bullet-secondary/>` should be expanded, use:

    <template>⚪</template>

-   When `<ase-tpl-bullet-normal/>` should be expanded, use:

    <template>🔵</template>

-   When `<ase-tpl-bullet-signal/>` should be expanded, use:

    <template>🟠</template>

-   When `<ase-tpl-pad width="<width/>" text="<text/>"/>` should be expanded, use
    (where <ws/> = ` ` x max(0, <width/> - length("<text/>")), i.e., <ws/> is
    the ` ` character repeated max(0, <width/> - length("<text/>")) times --
    clamped to zero so an over-long text never yields a negative count):

    <template><text/><ws/></template>