@hasna/skills 0.1.59 → 0.1.61

package/agent-skills/merge-pr/tests/fixtures/trailer-free-provider.json

@@ -0,0 +1,28 @@
+{
+  "pr_view": {
+    "state": "MERGED",
+    "mergedAt": "2026-07-23T15:36:23Z",
+    "mergeCommit": {
+      "oid": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+    },
+    "headRefOid": "2797e3264c416018c06608434c0c57340f647330",
+    "baseRefName": "main",
+    "url": "https://github.com/hasna/tai/pull/4"
+  },
+  "source_commits": [
+    {
+      "oid": "5d38cd4fe95556a06f7d9f31481ce88c8bb78e85",
+      "message": "ci: add provider-native validation workflow"
+    },
+    {
+      "oid": "2797e3264c416018c06608434c0c57340f647330",
+      "message": "ci: disable setup action cache and token"
+    }
+  ],
+  "commit": {
+    "sha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "commit": {
+      "message": "ci: add provider-native validation workflow (#4)\n\nMerge validated changes with an explicit sanitized message."
+    }
+  }
+}

package/agent-skills/skill-goal-execute/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: skill-goal-execute
+description: Take a high-level goal and drive it to done — break it into tasks via the todos CLI, open a goal thread in the project's conversations channel, create a plan in todos, generate the tasks under that plan, then execute them one by one until complete. Use for 'execute this goal', 'break down and do X', 'set a goal and run it'.
+user_invocable: true
+---
+
+# skill-goal-execute — Goal → Channel Thread → Plan → Tasks → Execute
+
+Turn a stated goal into structured, tracked, executed work. This skill is the bridge
+between "here's what I want" and "it's done", using the three canonical systems:
+**conversations** (one goal thread in the project's channel), **todos** (a plan +
+tasks), and **mementos** (learnings as you go).
+
+## Inputs
+
+- **The goal** — what the user wants achieved (one or more sentences).
+- **The project** — the project this goal belongs to. If global / not tied to a
+  project, use the **machine-name** project returned by `hostname`.
+
+## Workflow
+
+### 0. Log in & route
+
+Ensure you're logged in as an agent (`skill-login`). Determine the target
+project; for global work ensure the machine-name project exists
+(`todos projects --add "$HOME" --name "$(hostname | sed 's/\.local$//')"`).
+
+### 1. Open a goal thread in the project's conversations channel
+
+Every project has ONE channel, named per the channel classes (flat repo name
+for repo/package projects, full name for `platform-*`/`iapp-*`/`cweb-*`/
+`community-*` products, `oss-*`/`internal-*`/`research-*` for initiatives —
+same naming as `skill-project-create`). Goals do NOT get their own channels:
+one thread per goal inside the project channel, updated in-thread.
+
+```bash
+# Ensure the project's channel exists (create if missing; "already exists" is fine)
+conversations channel create "<project-channel>" --description "<project> coordination" --from <agent> 2>/dev/null || true
+conversations channel join "<project-channel>" --from <agent>
+
+# Open the goal thread: post the kickoff and capture its message id
+GOAL_MSG_ID=$(conversations send "🎯 Goal: <goal>. Breaking into a plan + tasks now." \
+  --channel "<project-channel>" --from <agent> -j \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+```
+
+Machines have no channels of their own (machine traffic folds into `ops`), so
+for global / machine-level goals open the thread in `ops` instead.
+
+### 2. Create a plan in todos
+
+```bash
+todos plans --add "<goal title>" -d "<the goal, in full>"
+# capture the returned PLAN_ID
+```
+
+### 3. Break the goal into tasks under that plan
+
+Decompose the goal into concrete, ordered, individually-verifiable steps. Create each
+as a task assigned to the plan and the project:
+
+```bash
+todos add "<step 1>" --plan "<PLAN_ID>" --project "<project>" -p high
+todos add "<step 2>" --plan "<PLAN_ID>" --project "<project>" -p high
+# ... one per step. Use --parent for sub-steps and deps for ordering if needed.
+```
+
+Post the breakdown to the goal thread so it's visible:
+
+```bash
+conversations reply "<plan id + task list>" --to $GOAL_MSG_ID --from <agent>
+```
+
+### 4. Execute the tasks ONE BY ONE
+
+Work strictly one task at a time — never batch:
+
+```
+for each task in plan order:
+  todos start <id>                 # claim + in_progress
+  ... do the work, verify it actually works ...
+  todos comment <id> "<what was done / result>"
+  todos done <id>                  # only after verified
+  conversations reply "✓ <task title>" --to $GOAL_MSG_ID --from <agent>
+  (save a memory with skill-memory-save if something non-obvious was learned)
+```
+
+Respect the "execute tasks one by one — never in bulk" rule: each task gets individual
+attention and verification before moving on.
+
+### 5. Close out
+
+When all tasks are done:
+
+```bash
+todos plans --complete "<PLAN_ID>"
+conversations reply "🏁 Goal complete: <goal>. <summary of what shipped>." --to $GOAL_MSG_ID --from <agent>
+```
+
+Save a summary memory (`skill-memory-save`) capturing the outcome and any decisions.
+
+## Rules
+
+- ALWAYS: goal thread (project channel) → plan (todos) → tasks (todos) → execute one
+  by one. Don't skip the plan or the thread.
+- One thread per goal in the project's channel — never a per-goal channel, never
+  duplicate threads; update in-thread (`conversations reply --to <goal-msg-id>`).
+- The project channel follows the channel-class naming (see `skill-project-create`);
+  global/machine goals thread into `ops`.
+- Route the plan/tasks to the specific project, or the machine-name project for global
+  goals.
+- Execute tasks individually and verify each before completing — never bulk-complete.
+- Post progress to the goal thread; save learnings to mementos. Never go dark.
+- Prefer the CLIs (`todos`, `conversations`, `mementos`); fall back from MCP to CLI if
+  an MCP is stale/broken.

package/agent-skills/skill-login/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: skill-login
+description: Full session start — reuse or register an agent identity across todos, conversations, and mementos, send a heartbeat, join your duty channels per agent class, then check unread messages and pending tasks. Run this at the very start of EVERY session. (Replaces the former skill-agent-login.)
+user_invocable: true
+---
+
+# skill-login — Session Start
+
+Log in at the very start of every session: make sure the session has an agent
+identity, signal you're active, join the channels your class owes attention to,
+and catch up on what you missed. This is the full flow; for bare registration
+only, see **`skill-register`**.
+
+**Subagent carve-out (hard rule): SUBAGENTS NEVER REGISTER, JOIN, OR
+SUBSCRIBE.** A subagent inherits its parent's identity and context and posts
+only where the parent directs. If you were spawned by another agent, skip this
+skill entirely.
+
+## Workflow
+
+### 1. Reuse or register an identity
+
+Register only if the session lacks an identity — never mint a duplicate.
+Standing roles (chief, loop runners, named coordinators) keep their stable
+identity across sessions.
+
+```bash
+conversations whoami            # already have an identity? reuse it, go to step 2
+```
+
+If the session has no identity: pick an unused Roman name and register across
+**todos + conversations + mementos** (see **`skill-register`** for the name
+pool and exact commands):
+
+```bash
+todos agents                          # see who's active, pick an unused Roman name
+todos init <name>                     # or mcp__todos__register_agent(name, working_dir)
+conversations agents register <name>  # or mcp__conversations__register_agent(name)
+mementos register-agent <name>        # or mcp__mementos__register_agent(name)
+```
+
+### 2. Send a heartbeat
+
+```bash
+todos heartbeat <name>          # or conversations agents heartbeat
+```
+
+Repeat every 30 minutes while active, and immediately after claiming or
+completing a task.
+
+### 3. Join your duty channels (per agent class)
+
+Join = membership + unread tracking (`conversations channel join`). Subscribe =
+preview-only notifications (`conversations channel subscribe`).
+
+| Class | Join | Subscribe |
+|---|---|---|
+| Interactive coordinator | `announcements`, `incidents`, `agent-policy` + owned project channels | `help`, `oss-cloud-runtime` |
+| Interactive worker | `announcements` + current task's channel (at claim; may leave at completion) | `incidents` |
+| Headless loop identity (stable, per-loop) | its `loops-*` lane + serviced package channel | `announcements` |
+| chief (standing) | all fleet-tier channels | all `loops-*` |
+| Subagent | NOTHING — never register, join, or subscribe | — |
+
+```bash
+# interactive worker example
+conversations channel join announcements --from <name>
+conversations channel subscribe incidents --from <name>
+# join the task's project channel when you claim the task
+```
+
+### 4. Check in — unread messages and pending tasks
+
+Bounded to 7 days so a fresh identity is never handed full history as unread.
+`--since` requires an ISO timestamp (durations like `7d` silently match
+nothing):
+
+```bash
+SINCE=$(date -u -d '7 days ago' +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || date -u -v-7d +%Y-%m-%dT%H:%M:%SZ)
+conversations context                              # one-shot boot context
+conversations blockers -j --from <name>            # unread blocking messages
+conversations digest announcements --unread --since "$SINCE" --mark-read --from <name>
+conversations digest incidents --unread --since "$SINCE" --from <name>
+todos list --status pending --agent <name>         # tasks waiting on you
+todos list --status in_progress                    # anything mid-flight
+```
+
+Clear mentions directed at you before starting work. An unread `[FREEZE]`
+means stop and escalate to `help`.
+
+### 5. Report
+
+```
+Logged in as <name> (todos id: <id>).
+- Blockers: N | unread announcements/incidents: N
+- Channels joined: <list per class matrix>
+- Pending/assigned tasks: N
+- Ready to work.
+```
+
+## Rules
+
+- Run at the start of EVERY session, before doing work. Mandatory.
+- Register only when the session has no identity; reuse standing identities.
+- SUBAGENTS NEVER REGISTER, JOIN, OR SUBSCRIBE — they inherit the parent's context.
+- When registering: ALWAYS all three systems; ALWAYS heartbeat; ALWAYS check
+  messages+tasks; ALWAYS apply your class's duty-channel row right after.
+- Pick a Roman name not currently active to avoid collisions.
+- If any MCP is unavailable, use its CLI immediately.
+- For just (re)registering identity without the check-in, use `skill-register`.

package/agent-skills/skill-project-create/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: skill-project-create
+description: Bootstrap a brand-new Hasna repo project or work project with the current `projects create`/`start` workflow, register todos/conversations, create the project's conversations channel, and preserve the intended category and naming convention.
+user_invocable: true
+---
+
+# skill-project-create
+
+Create a new project end to end: folder, Projects registry row, todos tracking,
+the project conversations channel, and launch session. First classify it as a
+repo project or work project.
+
+## Inputs
+
+- Name or idea from the user.
+- Description derived from the prompt.
+- Division/root, inferred when obvious.
+- Category: repo project or work project.
+
+## Naming
+
+Repo projects are code repositories/apps such as `open-*`, platform repos, and
+internal apps. Work projects are business/research/operations folders under
+`.../project/<project-name>`.
+
+For new work projects, follow the user's requested name and the local root
+convention. Existing work folders may already use `project-*`; do not rename or
+collapse those names during import. For new repo projects, use the repo's naming
+convention, such as `open-<name>` for Hasna OSS apps.
+
+The project channel is named after the slug (flat repo name for repo projects).
+Channel class for the topic line: `package` for `open-*` and other repo/package
+projects, `product` for `platform-*`/`iapp-*`/`cweb-*`/`community-*`, and
+`initiative` for work projects (`oss-*`/`internal-*`/`research-*`) — initiative
+topics must carry `owner:<agent> until:<date|gate-id>`. When the installed
+conversations CLI supports `--class` on `channel create` (newer than 0.3.3),
+pass `--class <package|product|initiative>` as well so the class lands in
+`metadata.channel_schema.class`; the topic line stays either way.
+
+## Workflow
+
+```bash
+export HASNA_PROJECTS_DB_PATH="$HOME/.hasna/projects/projects.db"
+export HASNA_PROJECTS_HOME="$HOME/.hasna/projects"
+projects roots list --json
+mkdir -p "<path>"
+projects create \
+  --name "<Name>" \
+  --slug "<slug>" \
+  --path "<path>" \
+  --kind "<project|open-source|internal-app|platform>" \
+  --description "<description>" \
+  --tmux
+todos projects --add "<path>" --name "<slug>"
+# Every project has a conversations channel — create it if missing, then join.
+# "Already exists" is fine; join and continue.
+conversations channel create "<slug>" \
+  --description "<description>" \
+  --topic "class:<package|product|initiative> owner:<agent>" \
+  --from <agent>
+conversations channel join "<slug>" --from <agent>
+conversations send "project created: <slug> — <description>" \
+  --channel "<slug>" --from <agent>
+projects show "<slug>" --json
+projects status "<slug>" --json
+projects context "<slug>" --for-agent
+```
+
+Use `projects publish <slug>` only for repo projects and only when the user wants
+a GitHub repository now.
+
+The project channel is the project's coordination home from this point on:
+post there when you claim a task, get blocked, hit a milestone, or finish
+(max 3 lines: task id, state, next step).
+
+## Safety
+
+- Keep secrets out of the repo; use vaults or gitignored `.secrets/`.
+- `cleanup-create` is for rollback of a creation run only; do not use it for
+  imported rows.
+- Do not delete source directories without backup and a clear registry/import
+  undo plan.
+- Store/canvas/loop commands are allowed only when `projects --help` on the
+  active machine shows `store`, `canvases`, and `loops`.
+
+## Done When
+
+The folder exists, `projects show` resolves it, `projects status` reports the
+launch state, todos is registered, the project conversations channel exists
+with you joined and the creation message posted, and the description and path
+are reported.

package/agent-skills/skill-publish/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: skill-publish
+description: Full publish workflow for @hasna npm packages. Runs tests, logical commits, push, OSS checks (if hasna org), posts publish intent to git-publishing, publishes to npm, installs locally via bun, verifies via CLI, confirms in-thread. Never uses npm to install.
+user_invocable: true
+---
+
+# skill-publish — Full Publish Workflow
+
+Complete end-to-end publish for `@hasna/*` packages. Covers OSS requirements,
+version bump, validation, PR merge, publish intent to `git-publishing`, npm
+registry publish, bun install, CLI verification, and in-thread confirmation.
+
+## Workflow
+
+### 1. Pre-flight checks
+
+```bash
+# Detect org from git remote
+REMOTE=$(git remote get-url origin)
+ORG=$(echo $REMOTE | grep -oP '(?<=github\.com[:/])[^/]+')
+PKG=$(cat package.json | python3 -c "import sys,json; print(json.load(sys.stdin)['name'])")
+echo "Org: $ORG | Package: $PKG"
+```
+
+### 2. OSS checks (hasna org only)
+
+If org is `hasna` (public open source), verify before doing anything else:
+
+**LICENSE** — Must be Apache 2.0:
+```bash
+[ -f LICENSE ] || echo "MISSING: LICENSE file"
+grep -q "Apache" LICENSE 2>/dev/null || echo "WRONG LICENSE: must be Apache-2.0"
+```
+If missing, create it (full Apache 2.0 text). Update `package.json` → `"license": "Apache-2.0"`.
+
+**README.md** — Must exist with at minimum: package name, description, install command, basic usage.
+
+**package.json** fields required:
+- `"license": "Apache-2.0"`
+- `"description"` — non-empty
+- `"repository"` — pointing to github.com/hasna/<name>
+- `"publishConfig": { "registry": "https://registry.npmjs.org", "access": "public" }`
+
+**GitHub repo visibility** — Hasna OSS packages must be public, but changing
+repo visibility is a risky disclosure action. Check it and stop for explicit
+human approval if it is private; do not auto-flip visibility inside this skill.
+```bash
+if gh repo view --json isPrivate -q '.isPrivate' | grep -q true; then
+  echo "BLOCKED: repo is private; get explicit approval and complete a full history/secret review before making it public"
+  exit 1
+fi
+```
+
+If org is `hasnaxyz` (private), ensure:
+- `"publishConfig": { "access": "restricted" }`
+
+### 3. Bump version on a release branch
+
+Do release edits on a branch, never directly on `main`.
+
+```bash
+git switch -c "release/${PKG##*/}-$(date -u +%Y%m%d%H%M%S)"
+
+# Check current published version. Prefer bun; fall back to npm only if present.
+CURRENT=$(bun pm view "$PKG" version 2>/dev/null || npm view "$PKG" version 2>/dev/null || echo "0.0.0")
+echo "Current: $CURRENT"
+
+# Bump patch in package.json unless the user explicitly requested another level.
+node -e "
+const fs = require('fs');
+const pkg = JSON.parse(fs.readFileSync('package.json'));
+const parts = pkg.version.split('.').map(Number);
+parts[2]++;
+pkg.version = parts.join('.');
+fs.writeFileSync('package.json', JSON.stringify(pkg, null, 2) + '\n');
+console.log('New version:', pkg.version);
+"
+```
+
+### 4. Run tests and build
+
+```bash
+bun test 2>&1
+[ "$(cat package.json | python3 -c "import sys,json; print('build' in json.load(sys.stdin).get('scripts',{}))")" = "True" ] && bun run build
+```
+If tests fail → fix them before continuing. Never publish broken tests.
+
+### 5. Secrets scan
+
+```bash
+git add package.json bun.lock
+SECRET_PATTERN='sk-(ant|proj)-|npm_[[:alpha:]]|gh[op]_|AKIA[[:upper:][:digit:]]|xai[-]|AI[z]a'
+if git diff --cached --diff-filter=ACM --unified=0 | grep -iE "^\\+[^+].*($SECRET_PATTERN)"; then
+  echo "SECRETS - STOP"
+  exit 1
+fi
+```
+
+### 6. Logical commit, push, PR, and merge
+
+```bash
+NEW_VERSION=$(cat package.json | python3 -c "import sys,json; print(json.load(sys.stdin)['version'])")
+git commit -m "chore: release $PKG@$NEW_VERSION"
+git push -u origin HEAD
+```
+
+Open a PR for the release branch. Wait for required CI and an independent review,
+then merge it. After merge, update local `main` and verify that `package.json`
+on `main` contains the exact version you are about to publish. Do not publish
+from an unmerged branch or unreviewed local commit.
+
+```bash
+gh pr create --fill
+# after CI/review approval:
+gh pr merge --squash --delete-branch
+git switch main
+git pull --ff-only origin main
+test "$(cat package.json | python3 -c "import sys,json; print(json.load(sys.stdin)['version'])")" = "$NEW_VERSION"
+```
+
+### 7. Post publish intent to git-publishing (BEFORE publishing)
+
+Fleet rule: publish intent goes to the `git-publishing` channel BEFORE any
+`bun publish`/`npm publish`, and the result is confirmed in the same thread
+after. Re-check blockers first — an unread `[FREEZE]` means stop and escalate
+to `help`.
+
+```bash
+conversations blockers --from <agent>    # unread [FREEZE] → STOP
+NEW_VERSION=$(cat package.json | python3 -c "import sys,json; print(json.load(sys.stdin)['version'])")
+INTENT_ID=$(conversations send "publish intent: $PKG@$NEW_VERSION — <one-line changelog>" \
+  --channel git-publishing --from <agent> -j \
+  | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])")
+echo "Intent posted: message $INTENT_ID"
+```
+
+### 8. Publish
+
+```bash
+ACCESS=public
+[ "$ORG" = "hasnaxyz" ] && ACCESS=restricted
+if command -v bun >/dev/null 2>&1; then
+  bun publish --access "$ACCESS"
+elif command -v npm >/dev/null 2>&1; then
+  npm publish --access "$ACCESS"
+else
+  echo "BLOCKED: neither bun nor npm publish is available"
+  exit 1
+fi
+```
+
+### 9. Install locally via bun (NOT npm)
+
+```bash
+bun install -g $PKG
+```
+
+Remove any npm global install if it exists:
+```bash
+if command -v npm >/dev/null 2>&1 && npm list -g "$PKG" 2>/dev/null | grep -q "$PKG"; then
+  npm uninstall -g "$PKG" && echo "Removed npm global install"
+fi
+```
+
+### 10. Verify via CLI
+
+Get the CLI binary name from `package.json#bin`, then test it:
+```bash
+BIN=$(cat package.json | python3 -c "import sys,json; bins=json.load(sys.stdin).get('bin',{}); print(next(iter(bins), '')) if isinstance(bins, dict) else print('')" 2>/dev/null)
+if [ -z "$BIN" ]; then
+  echo "BLOCKED: package.json has no CLI bin to verify"
+  exit 1
+fi
+"$BIN" --version || "$BIN" --help 2>&1 | head -3
+echo "$PKG published and verified via $BIN"
+```
+
+### 11. Confirm in-thread on git-publishing
+
+Reply to the intent message — success or failure, always close the thread:
+
+```bash
+conversations reply "published: $PKG@$NEW_VERSION — verified via $BIN" --to $INTENT_ID --from <agent>
+```
+
+If the publish failed or was aborted after the intent post:
+```bash
+conversations reply "publish aborted: $PKG@$NEW_VERSION — <reason>" --to $INTENT_ID --from <agent>
+```
+
+Repo releases (GitHub tags/releases) are announced on `git-releases`, not
+`git-publishing`.
+
+## Rules
+
+- NEVER `npm install -g` — always `bun install -g`
+- NEVER publish from an unmerged branch or unreviewed local commit
+- NEVER push release changes directly to `main`; use a branch, PR, CI, review, and merge
+- NEVER publish without running tests and build first
+- NEVER publish with secrets in the staged diff
+- NEVER publish without posting intent to `git-publishing` first (step 7)
+- ALWAYS confirm in the intent thread after — published or aborted, no silent exits
+- NEVER bump minor or major — patch only unless user explicitly says otherwise
+- NEVER skip the CLI verification step
+- NEVER auto-change GitHub repo visibility; stop for explicit approval and full history/secret review
+- If `hasna` org: Apache 2.0 + public + README required — no exceptions
+- If `hasnaxyz` org: restricted access required