@atollhq/skill-claude 0.4.26 → 0.4.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atollhq/skill-claude",
-  "version": "0.4.26",
+  "version": "0.4.28",
   "description": "Install the Atoll project management skill for Claude Code",
   "bin": {
     "skill-claude": "bin/install.mjs"

package/skill/SKILL.md

@@ -38,6 +38,18 @@ Read only the references required for the current task:
 - Request and response fields, enums, and validation:
   [api-fields.md](references/api-fields.md)
 
+For automation rule V1 actions (including create issue), explicit project or
+organization scope, CI create-only rules, event conditions, validation, safe
+disabling, repair, and example-only CI dry runs, read [Automation Rule Fields](references/api-fields.md#automation-rule-fields).
+Use `atoll automation` for rule management, previews, and run history; see
+[CLI operations](references/cli-operations.md#automation-rules).
+Rule creates require an explicit `project_id`: use a project UUID for project
+scope or `null` for organization scope. Partial updates preserve the saved
+scope when `project_id` is omitted; include it only when intentionally changing
+scope. An invalid rule executes no actions. Repair an invalid rule with
+separate `disable`, `update` while it is disabled, `test`, and `enable`
+operations. Enable only after the latest saved revision passes the dry run.
+
 Do not load every reference by default. Start with this entrypoint and load a
 topic reference only when the requested operation needs it.
 

package/skill/references/api-endpoints.md

@@ -729,7 +729,24 @@ receive projectless work. An inaccessible explicit `projectId` is concealed as
 | GET | `/api/orgs/{id}/automation-rules/{ruleId}/activity` | Rule execution history (owner/admin; latest 100 runs) |
 | POST | `/api/orgs/{id}/automation-rules/{ruleId}/test` | Dry-run test |
 
-Trigger events: `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed`.
+V1 definitions validate on create, merged partial updates, dry runs, and runtime.
+On create, `project_id` must be explicit: use a project UUID for project scope
+or `null` for organization scope. Partial updates preserve the saved scope
+when `project_id` is omitted; include it only when intentionally changing
+scope. A concurrent edit during validation returns `409`; reload before
+retrying. An enabled rule must be
+disabled with a separate exact `{ "enabled": false }` update before changing
+scope or repairing an invalid definition. A disabled invalid rule can be
+repaired while remaining disabled; run `test` on that saved revision before a
+separate `enable` update.
+GET/list preserve invalid rows with optional `validation: { valid, issues }`
+(`issues` contain `path`, `code`, and `message`). Owner/admin callers can disable
+an invalid rule with only `{ "enabled": false }`. Change-condition dry runs
+require a canonical `event`; snapshots cannot establish transitions. See
+[Automation Rule Fields](api-fields.md#automation-rule-fields) for the grammar
+and legacy normalization. No public MCP tool is added.
+
+Trigger events: `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed`, `pr.merged`, `ci.run.completed`.
 Create and update requests reject unsupported action types or malformed action
 values before persistence. Activity returns safe durable run/action history;
 non-matches, dry runs, and rules without executable actions create no history,
@@ -938,3 +955,5 @@ not a hosted API or MCP surface. Its browser projection excludes credentials,
 raw configuration, prompts, and model output. Local bindings use `repo_ref` but
 do not grant project/repository access. Intake is read-only locally; hosted
 Workspace Settings → Runners owns pause/resume. See the CLI local-runner guide.
+
+Automation rule create/update accepts the core action set including one `create_issue` per rule. See [Automation Rule Fields](api-fields.md#automation-rule-fields) for required fields, original-issue targets, replay results, and external-event limits.

package/skill/references/api-fields.md

@@ -483,22 +483,101 @@ multiple exact-name milestones already exist, upsert returns a structured
 
 ```json
 {
+  "schema_version": 1,
   "name": "Auto-assign urgent bugs",
   "trigger_event": "issue.created",
-  "conditions": [{ "field": "priority", "operator": "eq", "value": 0 }],
+  "conditions": [{ "kind": "field", "field": "priority", "operator": "eq", "value": 0 }],
   "actions": [{ "type": "set_assignee", "value": "member-uuid" }],
   "enabled": true,
   "project_id": "project-uuid"
 }
 ```
 
-Supported action values are: `set_status` (lowercase status key using letters,
-digits, and underscores), `set_assignee` (member UUID or `null`),
-`set_priority` (integer `0` through `3`), `add_label` (label UUID),
-`post_comment` (non-empty text), and `close_issue` (no value or `null`).
+Supported action values are: `set_status` (canonical project status key),
+`set_assignee` (replace the full assignee set with one member UUID, or `null` to
+clear it), `add_assignee` (add a member UUID without removing others), `unassign`
+(omit `value`), `set_priority` (integer `0` through `3`), `add_label` and
+`remove_label` (label UUID), `post_comment` (non-empty text, at most 10,000
+characters), and legacy `close_issue` (omit `value`, targets the valid `done` key).
+Already satisfied assignments, priorities, statuses, and label relationships
+succeed without duplicate mutation events. Invalid references still fail.
 Unsupported action types or malformed values return `400` and are not saved.
 
-**Dry-run test**: Send `{ "issue_id": "uuid" }` or `{ "issue": { "status": "todo", "priority": 2 } }`. Returns `{ matched, actions_that_would_run }`.
+`create_issue` requires `project_id` (UUID), `status` (that project's column key),
+and `title` (1–500 characters). Optional fields are `description` (up to 10,000
+characters), `priority` (0–3), `assignee_ids` (member UUID array), and `label_ids`
+(label UUID array). The member and label arrays accept at most 100 entries each.
+At most one create action is allowed per rule. Configure the new issue inside
+this action; later actions still target the original issue. Target-project access,
+references, limits, and normal creation rules remain authoritative.
+
+Creation content supports fixed text and approved `{{repository}}`, `{{workflow}}`,
+`{{conclusion}}`, and `{{run_url}}` fields only. Missing event fields and invalid or
+oversized rendered content fail before creation. Current issue triggers do not
+provide those external fields; use fixed text for issue triggers. The
+`ci.run.completed` trigger supplies them from a signed GitHub completion event.
+CI rules require organization scope (`project_id: null`) and support only
+`create_issue`. CI rules accept only event conditions. Issue triggers reject event conditions.
+Event conditions use `kind: "event"`, `eq` or `neq`, and fields
+`conclusion`, `repository`, `workflow`, `branch` (strings), `has_pr`, or
+`has_linked_issue` (booleans). Use conclusion `failure` and
+`has_linked_issue: false` to create an issue only for an unlinked failed run.
+The first receipt freezes link state; duplicate repository/run/attempt deliveries
+reuse it. A new run attempt is a distinct event. CI dry runs use marked example
+values and never execute actions.
+
+A durable action result records `created_issue_id` in the same transaction as
+canonical creation. Repeated execution of that action cannot create another issue.
+If a process stops after creation but before effects finish, the created ID remains
+visible and the interrupted action fails closed; this does not prove all effects
+completed. Deleting the created issue does not permit automatic recreation.
+Dry runs create no issue and fail clearly when required content fields are missing.
+
+**CI dry-run test:** Send `{}` with no event or issue overrides. The result has
+`preview_source: "example"`, fixed `test_ci` values, and `test_issue: null`.
+Custom repository or branch conditions can fail to match this example; a preview
+does not verify a live run.
+
+**Issue dry-run test**: Send `{ "issue_id": "uuid" }` or `{ "issue": { "status": "todo", "priority": 2 } }`. Returns `{ matched, actions_that_would_run }`.
+
+**Rule definition V1:** `schema_version` defaults to `1`. Conditions are ANDed;
+actions run in array order. A field condition uses `kind: "field"`, a field
+(`status`, `priority`, or `assignee_id`), `eq` or `neq`, and a typed `value`.
+A change condition uses `kind: "change"` with `changed` (omit `value`),
+`changed_from`, or `changed_to` (require a typed `value`). Change conditions
+require an issue change trigger; `issue.created` and `pr.merged` reject them.
+Priority values are integers `0`–`3`; status values are lowercase workflow keys;
+assignee values are organization member UUIDs or `null`.
+
+Create and partial `PUT` requests reject unknown keys, unsupported versions,
+malformed conditions/actions, and invalid references with `400` and
+`issues: [{ path, code, message }]`. A partial update is merged with the stored
+definition and the complete result is validated. If another edit changes the rule
+during validation, `PUT` returns `409`; reload the rule before retrying. An enabled
+rule must be disabled by a separate exact `{ "enabled": false }` request before
+changing `project_id`; combining disable with a scope change is rejected. An
+enabled invalid rule must also be disabled separately before repair. A disabled
+invalid rule accepts a valid repair only while remaining disabled; repair and
+enable must be separate. Project-scoped status values
+must exist in that workflow; project, member, and label references must belong
+to the organization. A request containing only `{ "enabled": false }` can
+disable an invalid rule without changing its definition; owner/admin access
+is still required. Enabling requires a valid definition.
+
+GET/list rules can include `validation: { valid, issues: [{ path, code, message }] }`.
+Invalid saved rows remain readable. Runtime validation rejects the whole invalid
+rule before any action; valid actions are not salvaged from a malformed rule.
+Legacy missing `schema_version` and condition `kind` normalize to `1` and `field`;
+priority strings `"0"`–`"3"` normalize to integers. Stored legacy `close_issue`
+with `value: null` normalizes to no value, and stored empty `set_assignee` values
+normalize to `null`. New writes must omit `close_issue.value`. Prefer `unassign` to clear all
+assignees; legacy `set_assignee` with `null` remains supported.
+
+**Change-condition dry runs:** Send `{ "event": <canonical IssueDomainEventV1> }`
+to the existing `/test` endpoint. The event must match the organization and rule
+project scope. Its derived triggers and before/after change map determine the
+result. An issue snapshot alone returns `400` for a change-aware rule. Dry runs
+perform no actions and create no run history.
 
 **Automation run history**: `GET /api/orgs/{id}/automation-rules/{ruleId}/activity`
 returns `{ runs }` to owner/admin members, newest first and limited to the
@@ -919,7 +998,7 @@ metadata are never returned by the public API.
 | Status update | `status` | `on_track`, `at_risk`, `off_track` |
 | Member | `role` | `owner`, `admin`, `member`, `guest` |
 | Project member | `accessLevel` | `view`, `edit`, `admin` |
-| Automation | `trigger_event` | `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed` |
+| Automation | `trigger_event` | `issue.created`, `issue.status_changed`, `issue.assigned`, `issue.priority_changed`, `pr.merged`, `ci.run.completed` |
 | Heartbeat signal | `type` | `kpi_off_pace`, `kpi_stale`, `issue_stale`, `issue_blocked`, `milestone_overdue`, `initiative_stalled`, `initiative_target_due_soon`, `initiative_target_overdue`, `initiative_target_blocked`, `webhook_failing` |
 | Heartbeat signal | `severity` | `info`, `warning`, `critical` |
 | Custom view | `display_mode` | `board`, `list` |

package/skill/references/cli-operations.md

@@ -193,3 +193,29 @@ CLI JSON conventions:
 ### Bulk create tasks from a plan
 
 `POST /api/orgs/{id}/issues/bulk` with `{ "issues": [{...}, ...] }` (max 50).
+
+## Automation rules
+
+Use `atoll automation list`, `get <rule-uuid>`, `create --file rule.json`,
+`update <rule-uuid> --file patch.json`, `test <rule-uuid> [--file preview.json]`,
+`runs <rule-uuid> --limit 20`, `enable`, `disable`, and `delete --force`.
+Use `delete <rule-uuid> --dry-run` to preview deletion. Use `--json`
+for machine-readable results and `--file -` for standard input. Create defaults
+to disabled when `enabled` is omitted, but the JSON must include an explicit
+`project_id` UUID or `null` for Organization-wide scope; update preserves omitted
+fields.
+List uses the selected organization and applies a project filter only with
+explicit `--project`; it does not inherit the default project.
+
+Rule files use the canonical Automation Rule Fields contract. CI rules require
+`project_id: null`, only `create_issue` actions, and event conditions. Use
+conclusion `failure` and `has_linked_issue: false` for unlinked CI failures.
+The action chooses its target project/status and accepts approved
+`{{repository}}`, `{{workflow}}`, `{{conclusion}}`, `{{run_url}}` substitutions.
+CI `test` sends `{}` by default, uses marked fixed examples, rejects overrides,
+and executes no actions. Inspect the preview before explicitly enabling.
+Rule writes, tests, and run history require owner/admin access; CLI does not bypass it.
+`runs` preserves created issue IDs and interrupted-action evidence. For an invalid
+rule, use separate `disable`, `update` while disabled, `test`, and `enable`
+operations. Human `get` output includes invalid state and validation paths;
+`--json` preserves the API response.