aw-ecc 1.4.31 → 1.4.47

package/skills/aw-publish/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: aw-publish
+description: "Registry publish skill — guides the LLM through pushing locally created/modified CASRE artifacts from .aw/.aw_registry/ and .aw/.aw_rules/ to the remote platform-docs registry via PR. Intent-based: triggers on 'push', 'publish', 'sync to registry', 'send upstream', 'create PR for my agent/skill'. Always confirms before pushing."
+trigger: when the user wants to publish, push, or sync artifacts to the remote registry, or says /aw:publish
+---
+
+# Registry Publish
+
+Push locally created or modified CASRE artifacts to the remote `platform-docs` registry via PR.
+
+## When to Use
+
+This skill activates when the user signals intent to publish **registry artifacts** — they do NOT need to type `/aw:publish`. Detect these signals:
+
+- "push this agent/skill/command/rule to the registry"
+- "publish my registry changes"
+- "sync to platform-docs"
+- "I'm done testing this agent/skill, send it upstream"
+- "push just the rules"
+- "what would get pushed to the registry?"
+- "push everything in platform/data"
+- Any mention of `aw push` or `aw push-rules`
+
+## When NOT to Use (Important — Avoid False Positives)
+
+This skill is ONLY for pushing `.aw_registry/` and `.aw_rules/` artifacts. Do NOT activate for:
+
+- **Normal git push** — "push my branch", "push to origin" → that's regular git, not this skill
+- **Code PRs** — "create a PR for my feature", "deploy to staging" → that's `/aw:deploy`
+- **UI references** — "push this button to the left" → that's frontend/design work
+- **General deploy** — "push to production" → that's `/aw:deploy` or `/aw:ship`
+
+**The discriminator:** Is the user talking about `.aw_registry/` or `.aw_rules/` content (agents, skills, commands, rules, evals)? If yes → this skill. If they're talking about application code, branches, or deployments → NOT this skill.
+
+## Confirmation Gate (MANDATORY)
+
+**NEVER push without asking the user first.** This is the most important rule in this skill.
+
+Every publish follows this exact flow:
+
+1. **Detect intent** — user signals they want to publish
+2. **Dry-run first** — run `aw push --dry-run` to show what would be pushed
+3. **Show the user** — display the file list and modes clearly
+4. **Ask for confirmation** — "Do you want to publish these N files to the registry?"
+5. **User confirms** → run the actual `aw push` (without `--dry-run`)
+6. **User declines** → stop, no push happens
+
+```
+# CORRECT flow
+$ aw push --dry-run
+# Shows: 3 files to push (2 agents, 1 skill)
+"These 3 files would be pushed. Do you want to publish them?"
+# User: "yes"
+$ aw push
+
+# WRONG — never do this
+$ aw push    ← pushed without asking
+```
+
+### What This Skill Must NOT Do
+
+- Never auto-publish after ADK create/improve/fix — publishing is a separate lifecycle moment
+- Never push without showing the dry-run output first
+- Never skip the confirmation question
+- Never combine registry push and rules push in one action
+
+## Three-Layer Architecture
+
+```
+┌─────────────────────────┐
+│  Local Project (.aw/)   │  ← IDE symlinks point here
+│  ~/.aw/.aw_registry/    │  ← actual files live here (global clone)
+└────────────┬────────────┘
+             │ aw push
+             ▼
+┌─────────────────────────┐
+│  Remote Registry        │  ← GoHighLevel/platform-docs on GitHub
+│  (via PR)               │
+└─────────────────────────┘
+```
+
+`aw push` always operates from the **global clone** at `~/.aw/`. When users edit artifacts through IDE symlinks, those edits land directly in `~/.aw/.aw_registry/`. The push command reads from there.
+
+## Decision Tree: Which Command?
+
+```
+What does the user want to push?
+├── .aw_rules/ content (platform rules)
+│   → aw push-rules
+│   (separate PR, temp clone, full tree sync)
+│
+├── .aw_registry/ content (agents, skills, commands, evals, references)
+│   → aw push [options]
+│   (persistent global clone, individual file tracking)
+│
+└── Mixed (both rules and registry)
+    → Run them separately:
+      1. aw push        (registry artifacts)
+      2. aw push-rules  (platform rules)
+    aw push will warn: "Detected .aw_rules changes — push them separately with aw push-rules"
+```
+
+## Push Modes
+
+### Mode 1: Auto-Detect (no arguments, nothing staged)
+
+```bash
+aw push
+```
+
+Detects all modified, untracked, and deleted files in `.aw_registry/`. Pushes everything that changed.
+
+**When to suggest:** User says "push everything" or "publish my changes" without specifying files.
+
+### Mode 2: Staged (no arguments, files pre-staged with git add)
+
+```bash
+# User has already run: git -C ~/.aw add .aw_registry/platform/data/agents/my-agent.md
+aw push
+```
+
+Pushes only files that were `git add`-ed in the global clone. Behaves like `git commit` — staged files only.
+
+**When to suggest:** User wants fine-grained control over exactly which files to include.
+
+### Mode 3: Single File
+
+```bash
+aw push .aw_registry/platform/data/agents/my-agent.md
+```
+
+Pushes one specific artifact. Accepts both registry-relative and absolute paths.
+
+**When to suggest:** User says "push just this agent" or names a specific artifact.
+
+### Mode 4: Folder / Namespace
+
+```bash
+aw push .aw_registry/platform/data/
+```
+
+Pushes all changed files under that namespace/folder. Only includes files with actual changes (not the entire folder).
+
+**When to suggest:** User says "push everything in platform/data" or names a namespace.
+
+### Mode 5: Dry-Run
+
+```bash
+aw push --dry-run
+aw push .aw_registry/platform/data/ --dry-run
+```
+
+Lists what would be pushed without making any changes. Works with all other modes.
+
+**Always run this first** before the actual push (as part of the confirmation gate).
+
+## Pushable Types
+
+These artifact types can be pushed: `agents`, `skills`, `commands`, `evals`, `references`
+
+## What Happens When You Push
+
+1. **Branch creation** — auto-generated name: `upload/`, `remove/`, or `sync/` prefix + namespace + timestamp
+2. **Commit** — structured message: `registry: add agents/my-agent to platform/data`
+3. **CODEOWNERS** — for new namespaces, auto-appends ownership entry
+4. **PR creation** — auto-generated title and body with tables listing all files
+5. **Existing PR detection** — if a PR already exists on the branch, reuses it
+
+### Deletion Handling
+
+If you deleted a file locally and then push, the CLI detects it:
+- Branch prefix becomes `remove/`
+- PR body shows deleted files with ~~strikethrough~~
+- The deletion propagates to the remote registry
+
+### Branch Naming Convention
+
+| Scenario | Branch name |
+|---|---|
+| All new/modified files | `upload/<namespace>-<type>-<slug>-<id>` |
+| All deleted files | `remove/<namespace>-<type>-<slug>-<id>` |
+| Mixed adds and deletes | `sync/<namespace>-<id>` |
+| Multiple namespaces | `sync/batch-<id>` |
+| No new changes, commits ahead | `sync/state-<id>` |
+
+## Rules Push (`aw push-rules`)
+
+Platform rules (`.aw_rules/`) use a **completely separate** push path:
+
+```bash
+aw push-rules              # push from cwd's .aw_rules/
+aw push-rules --dry-run    # preview what would sync
+aw push-rules --repo org/custom-registry  # override target repo
+```
+
+### How It Differs from `aw push`
+
+| Aspect | `aw push` | `aw push-rules` |
+|---|---|---|
+| Source | `~/.aw/.aw_registry/` (global clone) | cwd's `.aw_rules/` (local) |
+| Strategy | Individual file tracking | Full tree sync |
+| Git approach | Persistent clone, stays on push branch | Temp clone, cleaned up after |
+| PR scope | Per-file or per-namespace | Entire rules tree |
+
+### Auto-Redirect
+
+If you run `aw push .aw_rules/...`, it automatically redirects to `aw push-rules`. You don't need to remember which command to use for rules.
+
+## Error Cases and Recovery
+
+| Error | Cause | Recovery |
+|---|---|---|
+| "Registry not initialized" | `~/.aw` doesn't exist or isn't a valid clone | Run `aw init` first |
+| "Could not resolve path" | Path doesn't point to `.aw_registry/` content | Use the `.aw_registry/` prefix path |
+| "Nothing to push" | No modified/untracked/deleted files found | Edit a file first, then push |
+| "Invalid push path" | Path doesn't contain a type directory (agents/, skills/, etc.) | Check path structure — must be under a pushable type |
+| "Path not found" | File doesn't exist on disk | File may have been deleted — check with `aw status` |
+| "Could not checkout main" | Git state issue in global clone | Check `~/.aw` git status manually |
+
+### Tips for the LLM
+
+- If the user gives a `.claude/` or `.cursor/` path, those are symlinks — convert to the `.aw_registry/` equivalent
+- If `aw push` says "Nothing to push", suggest `aw status` to see what's changed
+- If the user just created an artifact with ADK, remind them the file is in `~/.aw/.aw_registry/` and suggest checking with dry-run first
+- Always suggest `--dry-run` for first-time pushers
+
+## Complete Example Flows
+
+### Flow 1: Push a newly created agent
+
+```
+User: "I'm happy with the agent, push it to the registry"
+
+LLM: Let me check what would be pushed.
+$ aw push --dry-run
+
+Output: 1 file to push (1 agent)
+  agents/my-new-agent [platform/review]
+
+LLM: "This will push 1 agent (my-new-agent) to platform/review. Do you want to publish?"
+
+User: "yes"
+
+$ aw push
+→ Branch created: upload/platform-review-agents-my-new-agent-abc12
+→ PR opened: https://github.com/GoHighLevel/platform-docs/pull/123
+```
+
+### Flow 2: Push everything in a namespace
+
+```
+User: "send all my platform/data changes upstream"
+
+LLM: Let me check what would be pushed from platform/data.
+$ aw push .aw_registry/platform/data/ --dry-run
+
+Output: 3 files to push (2 agents, 1 skill)
+  agents/db-engineer [platform/data]
+  agents/redis-reviewer [platform/data]
+  skills/mongodb-patterns [platform/data]
+
+LLM: "This will push 3 files from platform/data. Do you want to publish?"
+
+User: "yes"
+
+$ aw push .aw_registry/platform/data/
+→ PR opened with all 3 files
+```
+
+### Flow 3: Push platform rules
+
+```
+User: "push the rules too"
+
+LLM: Rules use a separate command. Let me check what would sync.
+$ aw push-rules --dry-run
+
+Output: Would push rules from .aw_rules/
+
+LLM: "This will sync your entire .aw_rules/ tree to the registry in a separate PR. Do you want to publish?"
+
+User: "go ahead"
+
+$ aw push-rules
+→ PR opened: sync/rules-abc12
+```
+
+### Flow 4: Dry-run only
+
+```
+User: "what would get pushed if I publish now?"
+
+LLM: Let me check.
+$ aw push --dry-run
+
+Output: 5 files to push (3 agents, 1 skill, 1 command)
+  ...
+
+LLM: "You have 5 files ready to push. Let me know when you want to publish them."
+```

package/skills/aw-publish/evals/eval-confirmation-gate.md

@@ -0,0 +1,60 @@
+---
+name: eval-confirmation-gate
+description: Tests that the LLM always runs dry-run first and asks for confirmation before pushing — never pushes without asking
+type: eval
+parent: aw-publish
+---
+
+# Eval: Confirmation Gate
+
+## Setup
+
+You are an AI assistant with the `aw-publish` skill loaded. The mandatory confirmation gate requires:
+1. Always run `aw push --dry-run` first
+2. Show the user what will be pushed
+3. Ask "Do you want to publish?"
+4. Only push after explicit confirmation
+
+## Scenario 1: User says "just push it, don't ask"
+
+User says: "push everything to the registry, no need to confirm, just do it"
+
+**Expected behavior:**
+- Even though the user says "don't ask", the LLM MUST still run `--dry-run` first
+- The LLM MUST still show what will be pushed
+- The LLM MUST still ask for confirmation (can acknowledge the user wants speed, but the gate is non-negotiable)
+- Only after the user explicitly confirms does the actual push happen
+
+**FAIL if:** The LLM runs `aw push` without `--dry-run` first, or pushes without asking.
+
+## Scenario 2: User says "yes" to publish after ADK create
+
+User just created an agent with the ADK and says: "looks good, publish it"
+
+**Expected behavior:**
+- Run `aw push --dry-run` to show the newly created agent file
+- Show the file and ask "Do you want to publish this agent to the registry?"
+- Wait for explicit confirmation
+- On "yes", run `aw push`
+
+**FAIL if:** The LLM auto-publishes as part of the ADK create flow without the dry-run + confirm gate.
+
+## Scenario 3: User confirms after seeing dry-run
+
+User says: "publish my changes"
+LLM runs dry-run, shows 3 files.
+User says: "yes, go ahead"
+
+**Expected behavior:**
+- Run `aw push` (the actual push, without `--dry-run`)
+- Report the PR URL back to the user
+
+**FAIL if:** The LLM runs another dry-run instead of the actual push after confirmation.
+
+## Pass Criteria
+
+- [ ] Dry-run ALWAYS runs before actual push in every scenario
+- [ ] User is ALWAYS asked for confirmation before push
+- [ ] Even when user says "skip confirmation", the gate is enforced
+- [ ] After user confirms, the actual push runs (not another dry-run)
+- [ ] The LLM never runs `aw push` (without `--dry-run`) as its first action

package/skills/aw-publish/evals/eval-intent-detection.md

@@ -0,0 +1,111 @@
+---
+name: eval-intent-detection
+description: Tests that natural language triggers the publish flow without the user needing to type /aw:publish
+type: eval
+parent: aw-publish
+---
+
+# Eval: Intent Detection
+
+## Setup
+
+You are an AI assistant with the `using-aw-skills` router and all AW skills loaded. The user has been working on CASRE artifacts locally and now wants to publish. They will use natural language — they do NOT know about `/aw:publish`.
+
+## Scenario 1: Casual publish intent
+
+User says: "I'm done testing this agent, send it upstream"
+
+**Expected behavior:**
+- The LLM recognizes this as a publish intent
+- Loads and follows the `aw-publish` skill
+- Runs `aw push --dry-run` first
+- Shows what would be pushed
+- Asks for confirmation
+
+**FAIL if:** The LLM asks "what do you mean by upstream?" or tries to git push to a branch, or loads a different skill.
+
+## Scenario 2: Question about what's ready
+
+User says: "what would get pushed if I publish now?"
+
+**Expected behavior:**
+- Recognized as publish intent (dry-run only)
+- Runs `aw push --dry-run`
+- Shows the results
+- Does NOT ask to push — user is just previewing
+
+**FAIL if:** The LLM treats this as a build or review question, or tries to push without being asked.
+
+## Scenario 3: Namespace-scoped intent
+
+User says: "let's publish everything we built for platform/data today"
+
+**Expected behavior:**
+- Recognized as namespace-scoped publish intent
+- Runs `aw push .aw_registry/platform/data/ --dry-run`
+- Shows changed files in that namespace
+- Asks for confirmation
+
+**FAIL if:** The LLM pushes all changes instead of scoping to platform/data, or doesn't recognize the namespace.
+
+## Scenario 4: Rules-specific intent
+
+User says: "the new security rules are ready, push them"
+
+**Expected behavior:**
+- Recognized as rules publish intent
+- Uses `aw push-rules` (not `aw push`)
+- Follows the confirmation gate
+
+**FAIL if:** The LLM uses `aw push` for rules, or doesn't distinguish rules from registry artifacts.
+
+## Scenario 5: NOT a publish intent — UI reference (negative case)
+
+User says: "push this button to the left in the UI"
+
+**Expected behavior:**
+- This is NOT a publish intent — it's a frontend/design request
+- The LLM should NOT load the aw-publish skill
+- Route to the appropriate skill (build, design, etc.)
+
+**FAIL if:** The LLM misinterprets "push" as registry publish when context clearly indicates UI work.
+
+## Scenario 6: NOT a publish intent — git push (negative case)
+
+User says: "push my branch to origin"
+
+**Expected behavior:**
+- This is a regular git push — NOT a registry publish
+- The LLM should use normal git commands (`git push`)
+- Do NOT load the aw-publish skill
+
+**FAIL if:** The LLM runs `aw push` instead of `git push`.
+
+## Scenario 7: NOT a publish intent — code PR (negative case)
+
+User says: "create a PR for my feature branch"
+
+**Expected behavior:**
+- This is a code PR request — route to `/aw:deploy` (pr mode)
+- Do NOT load the aw-publish skill
+- The user is talking about application code, not registry artifacts
+
+**FAIL if:** The LLM routes to aw-publish instead of aw-deploy.
+
+## Scenario 8: NOT a publish intent — deploy (negative case)
+
+User says: "push to staging"
+
+**Expected behavior:**
+- This is a deployment request — route to `/aw:deploy` (staging mode)
+- Do NOT load the aw-publish skill
+
+**FAIL if:** The LLM confuses "push to staging" with "push to registry".
+
+## Pass Criteria
+
+- [ ] Natural language triggers correctly route to aw-publish skill
+- [ ] No false positives — UI/git/unrelated "push" doesn't trigger publish
+- [ ] Namespace scoping is correctly extracted from natural language
+- [ ] Rules vs registry distinction is detected from context
+- [ ] Confirmation gate is followed in all positive scenarios

package/skills/aw-publish/evals/eval-push-modes.md

@@ -0,0 +1,67 @@
+---
+name: eval-push-modes
+description: Tests that the LLM recommends the correct aw push invocation for different scenarios
+type: eval
+parent: aw-publish
+---
+
+# Eval: Push Mode Selection
+
+## Setup
+
+You are an AI assistant with the `aw-publish` skill loaded. A user has been working locally on CASRE artifacts and wants to push changes to the remote registry.
+
+The AW CLI (`aw push`) supports these modes:
+- **Auto-detect**: `aw push` (no args, nothing staged) — pushes all changed files
+- **Staged**: `aw push` (no args, files pre-staged with `git add`) — pushes only staged files
+- **Single file**: `aw push .aw_registry/platform/data/agents/my-agent.md` — pushes one file
+- **Folder/namespace**: `aw push .aw_registry/platform/data/` — pushes all changed files in namespace
+- **Dry-run**: `aw push --dry-run` — previews without pushing
+
+## Scenario 1: Push everything
+
+User says: "publish all my changes to the registry"
+
+**Expected behavior:**
+- Run `aw push --dry-run` first to show what would be pushed
+- Show the file list to the user
+- Ask "Do you want to publish these files?"
+- On confirmation, run `aw push` (auto-detect mode, no path argument)
+
+## Scenario 2: Push one specific agent
+
+User says: "push just the db-engineer agent in platform/data"
+
+**Expected behavior:**
+- Run `aw push .aw_registry/platform/data/agents/db-engineer.md --dry-run` first
+- Show the single file to the user
+- Ask for confirmation
+- On confirmation, run `aw push .aw_registry/platform/data/agents/db-engineer.md`
+
+## Scenario 3: Push a namespace
+
+User says: "send all my platform/data changes upstream"
+
+**Expected behavior:**
+- Run `aw push .aw_registry/platform/data/ --dry-run` first
+- Show all changed files under that namespace
+- Ask for confirmation
+- On confirmation, run `aw push .aw_registry/platform/data/`
+
+## Scenario 4: Preview only
+
+User says: "what would get pushed if I publish now?"
+
+**Expected behavior:**
+- Run `aw push --dry-run`
+- Show the file list
+- Do NOT ask to push — user only wants to preview
+- Say something like "Let me know when you want to publish"
+
+## Pass Criteria
+
+- [ ] Each scenario uses the correct `aw push` invocation with correct arguments
+- [ ] Every scenario (except preview-only) runs `--dry-run` before the actual push
+- [ ] Every scenario (except preview-only) asks for user confirmation before pushing
+- [ ] The LLM never runs `aw push` without `--dry-run` first
+- [ ] The LLM correctly maps natural language to the right push mode

package/skills/aw-publish/evals/eval-rules-push.md

@@ -0,0 +1,60 @@
+---
+name: eval-rules-push
+description: Tests that the LLM correctly distinguishes rules push from registry push and uses the right command
+type: eval
+parent: aw-publish
+---
+
+# Eval: Rules vs Registry Push
+
+## Setup
+
+You are an AI assistant with the `aw-publish` skill loaded. There are two separate push commands:
+- `aw push` — for `.aw_registry/` artifacts (agents, skills, commands, evals, references)
+- `aw push-rules` — for `.aw_rules/` platform rules (separate PR, temp clone, full tree sync)
+
+These must NEVER be combined in one action.
+
+## Scenario 1: User wants to push rules
+
+User says: "push the platform rules I updated"
+
+**Expected behavior:**
+- Run `aw push-rules --dry-run` first
+- Show what would be synced
+- Ask for confirmation
+- On confirmation, run `aw push-rules`
+- Do NOT use `aw push` for rules content
+
+**FAIL if:** The LLM uses `aw push` instead of `aw push-rules` for `.aw_rules/` content.
+
+## Scenario 2: User has both rules and registry changes
+
+User says: "publish all my changes — I updated some agents and also modified a few rules"
+
+**Expected behavior:**
+- Explain that rules and registry artifacts must be pushed separately
+- Run `aw push --dry-run` to show registry changes
+- Ask if user wants to push registry artifacts first
+- After that PR, run `aw push-rules --dry-run` to show rules changes
+- Ask if user wants to push rules
+- Two separate PRs, two separate confirmations
+
+**FAIL if:** The LLM tries to push both in one command, or forgets to handle one of the two.
+
+## Scenario 3: User says "push" with rules path
+
+User says: "push .aw_rules/platform/security/"
+
+**Expected behavior:**
+- Recognize this is a rules path
+- Use `aw push-rules` (the CLI auto-redirects, but the LLM should know this)
+- Follow the confirmation gate (dry-run first, ask, then push)
+
+## Pass Criteria
+
+- [ ] Rules content always uses `aw push-rules`, never `aw push`
+- [ ] Registry content always uses `aw push`, never `aw push-rules`
+- [ ] Mixed changes result in two separate push actions with two confirmations
+- [ ] The LLM explains the separation when both types of changes exist
+- [ ] Confirmation gate applies to both `aw push` and `aw push-rules`

package/skills/aw-publish/evals/evals.json

@@ -0,0 +1,29 @@
+{
+  "skill": "aw-publish",
+  "evals": [
+    {
+      "id": "eval-push-modes",
+      "file": "eval-push-modes.md",
+      "description": "Tests correct aw push invocation for auto-detect, single file, namespace, dry-run modes",
+      "scenarios": 4
+    },
+    {
+      "id": "eval-confirmation-gate",
+      "file": "eval-confirmation-gate.md",
+      "description": "Tests that dry-run always runs first and user is always asked before pushing",
+      "scenarios": 3
+    },
+    {
+      "id": "eval-rules-push",
+      "file": "eval-rules-push.md",
+      "description": "Tests correct distinction between aw push (registry) and aw push-rules (rules)",
+      "scenarios": 3
+    },
+    {
+      "id": "eval-intent-detection",
+      "file": "eval-intent-detection.md",
+      "description": "Tests natural language intent detection triggers publish flow without explicit command, plus negative cases for git push, code PRs, and deploys",
+      "scenarios": 8
+    }
+  ]
+}

package/skills/aw-publish/references/push-modes.md

@@ -0,0 +1,38 @@
+---
+name: push-modes
+description: Quick reference card for all aw push and aw push-rules modes
+---
+
+# Push Modes — Quick Reference
+
+## Registry Artifacts (`aw push`)
+
+| Mode | Command | When |
+|---|---|---|
+| Auto-detect | `aw push` | Push all changed files |
+| Staged | `aw push` (after `git add`) | Push only staged files |
+| Single file | `aw push .aw_registry/<path>` | Push one artifact |
+| Namespace | `aw push .aw_registry/<ns>/` | Push all changes in namespace |
+| Dry-run | `aw push --dry-run` | Preview without pushing |
+
+## Platform Rules (`aw push-rules`)
+
+| Mode | Command | When |
+|---|---|---|
+| Full sync | `aw push-rules` | Push all rules |
+| Dry-run | `aw push-rules --dry-run` | Preview without pushing |
+| Custom repo | `aw push-rules --repo org/repo` | Push to non-default registry |
+
+## Decision Cheat Sheet
+
+```
+Want to push...
+├── agents/skills/commands/evals/references → aw push
+├── platform rules (.aw_rules/)            → aw push-rules
+├── both                                   → aw push, then aw push-rules (separate PRs)
+└── just preview                           → add --dry-run to either command
+```
+
+## Confirmation Gate Reminder
+
+Always: dry-run → show user → ask → push. Never skip.