amika-annotations

Process Amika Annotations

Find Amika annotations in the target, act on each one's intent, dispose of it (keep or delete), and report what you did. This skill is a processor, not the amikalyze enforcement engine: it does not install hooks, fire prompts, or enforce freezes. It only acts on imperative annotations and stays out of the way of the deterministic tooling.

Usage: /amika-annotations [path]

• path (optional): a file or directory to process. If omitted, process the files in the current git diff / working tree (git status --porcelain, plus staged changes).

---

Phase 1: Find the annotations

1. Resolve scope.

   • If path is given, scope to that file or directory subtree.
   • Otherwise, scope to changed files: git diff --name-only HEAD plus untracked files from git status --porcelain. If there are no changes, say so and stop.

2. Grep for both markers across the scoped files:

   • EDN: #amika/[A-Za-z][\w-]*
   • XML: <amika:[A-Za-z][\w-]*

3. For each hit, read enough surrounding context to parse the full annotation (EDN expressions and XML elements can span multiple lines) and to identify what it targets.

If nothing is found, report that and stop.

---

Phase 2: Parse each annotation

There are two syntaxes. Parse the whole expression before acting.

EDN style: #amika/<type> ...

• The value after the type is an EDN expression. It may be:
  • a bare string: #amika/generate "create a zod schema for the type below"
  • a bare map of args: #amika/frozen { :override "computeChecksum" }
  • a paren form pairing a string with an options map: #amika/rewrite ( "tighten this" { :model "claude-opus-4-7" :effort "high" } )
• Multi-line: the comment prefix is repeated on every line. Strip the leading prefix (//, #, or * inside a block comment) from each line before reading the EDN value.
• Target: by default an EDN annotation applies to the next semantic block below it (a function, class, or top-level variable; at the top of a file it applies to the whole module). If there is no following block (e.g. it sits at the end of a section, or in prose/markdown), treat it as an inline instruction to act at that point.

XML style: <amika:<type>>…</amika:<type>>

• A paired element describes the content it wraps: the text/code between the tags is the subject the annotation acts on.
• A self-closing element <amika:<type> … /> is a point annotation with no contained content; it acts at its location.
• Attributes on the tag are the annotation's args/options (analogous to the EDN options map).

---

Phase 3: Decide behavior

Look up the type in the built-in table below. If it isn't there, infer the behavior from the type name, the content, and the args.

Built-in table

Constraint / advisory types (respected, never processed or deleted here):

These belong to the amikalyze tooling/hooks. This skill only reads them so it doesn't trample what they protect.

Imperative types (acted on, then disposed of; default is delete after acting):

The imperative set above is a starter. It's safe to extend this table as new types appear; until then, unknown types are handled by inference (below).

Inference for unknown types

If the type isn't in the table:

1. Read the type name, content, and args and determine the intent.
2. Carry out that intent on the resolved target (next block, inline, or wrapped content).
3. Decide keep vs. delete yourself using the disposition rules below.
4. Flag it as inferred in the report so the user can review your judgment.

---

Phase 4: Act and dispose

For each annotation, in file order:

1. Check boundaries first. If acting would modify a frozen symbol or a frozen-paths glob (and no override is present), do not act. Record a boundary conflict and move on.

2. Act on the intent against the resolved target.

3. Dispose of the annotation. Disposition is decided in this priority order:

   1. Per-annotation override wins. :keep true (EDN) or keep="true" (XML attr) forces keep; :once true / once="true" forces delete-after-acting.
   2. Otherwise use the table default for a known imperative type.
   3. Otherwise (inferred type) use your judgment: an instruction that is consumed by doing it (generate, do this task) should be deleted; an annotation that remains true about the content (a description, a standing note) should be kept.
   • When deleting an EDN annotation, remove its whole comment (all continuation lines). When "unwrapping" an XML element, remove the open/close tags but keep the (possibly transformed) content. Removing a self-closing tag removes just that tag.

4. Never leave an annotation unprocessed. Every one found is either acted on, or recorded as a boundary conflict, or (for the respected constraint types) intentionally left in place, and every case appears in the report.

---

Phase 5: Report

End with a summary so the user can review the judgment calls. Use a table:

Then call out, as separate short lists:

• Inferred types: annotations whose behavior you guessed (type was not in the table).
• Boundary conflicts: actions you refused because they'd touch a frozen symbol/path.
• Left in place: frozen / frozen-paths / prompt annotations you respected.

Do not commit anything. Stop after reporting so the user can review the edits.