feat: add mosaic ops skills (portainer, gitea, woodpecker, deploy, orchestrator)

- mosaic-portainer: stack list/status/redeploy/logs via Portainer API scripts - mosaic-gitea: PR/issue/milestone ops for git.mosaicstack.dev - mosaic-woodpecker: pipeline status, trigger, CI wait - mosaic-deploy: full end-to-end deploy flow (push → CI → merge → redeploy) - mosaic-orchestrator: mission init/run/status + worker launch rules
2026-03-22 15:32:05 +00:00
parent be320644e2
commit 12545cf98c
5 changed files with 400 additions and 0 deletions
--- a/skills/mosaic-deploy/SKILL.md
+++ b/skills/mosaic-deploy/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: mosaic-deploy
+description: Full end-to-end deploy flow for Mosaic Stack projects: push branch → open PR → wait for CI → merge → redeploy Portainer stack. Use when deploying a feature branch to production or staging, or when asked to ship a completed feature. Orchestrates mosaic-gitea, mosaic-woodpecker, and mosaic-portainer skills.
+---
+
+# mosaic-deploy
+
+End-to-end deployment flow for Mosaic Stack projects.
+
+## Full Deploy Sequence
+
+```
+push branch → open PR → CI passes → merge → portainer redeploy
+```
+
+### Step 1: Push branch and open PR
+
+```bash
+cd ~/src/<repo>-worktrees/<task-slug>
+git push -u origin <branch>
+~/.config/mosaic/tools/git/pr-create.sh -t "feat: ..." -b "..." -i <issue#>
+# Note the PR number from output
+```
+
+### Step 2: Wait for CI
+
+```bash
+~/.config/mosaic/tools/git/pr-ci-wait.sh -n <pr#>
+```
+
+If CI fails, check:
+```bash
+source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials woodpecker
+~/.config/mosaic/tools/woodpecker/pipeline-status.sh -r <org>/<repo>
+```
+
+### Step 3: Merge
+
+```bash
+cd ~/src/<repo>
+~/.config/mosaic/tools/git/pr-merge.sh -n <pr#> -d
+```
+
+For branch-protected repos (force merge):
+```bash
+GITEA_TOKEN=$(cat ~/.config/mosaic/credentials/gitea.env | grep TOKEN | cut -d= -f2)
+curl -X POST "https://git.mosaicstack.dev/api/v1/repos/<org>/<repo>/pulls/<pr#>/merge" \
+  -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" \
+  -d '{"Do":"squash","force_merge":true}'
+```
+
+### Step 4: Redeploy Portainer stack
+
+```bash
+source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
+~/.config/mosaic/tools/portainer/stack-redeploy.sh -n <stack-name> -p
+```
+
+Check deployment:
+```bash
+~/.config/mosaic/tools/portainer/stack-status.sh -n <stack-name>
+~/.config/mosaic/tools/portainer/stack-logs.sh -n <stack-name> -l 50
+```
+
+## Stack Name Map
+
+| Project | Stack Name |
+|---|---|
+| mosaic-stack | `mosaic-stack` |
+| sage-phr | `sage-phr` |
+| openbrain | `openbrain` |
+| jarvis-crypto | `jarvis-crypto` |
+| firefly | `firefly` |
+
+## Notes
+
+- Workers open PRs but **never merge** — orchestrator or Merge Guard handles step 3+
+- Docker Swarm image pinning: if `-p` doesn't pull a new image, SSH to `w-docker0` (10.1.1.45) and run `docker pull <image>` manually, then redeploy
+- Worktrees: all coding work in `~/src/<repo>-worktrees/<task-slug>`, never in main checkout
+- Always clean up worktree after push: `git worktree remove ~/src/<repo>-worktrees/<task-slug>`
--- a/skills/mosaic-gitea/SKILL.md
+++ b/skills/mosaic-gitea/SKILL.md
@@ -0,0 +1,97 @@
+---
+name: mosaic-gitea
+description: Interact with Gitea repositories on git.mosaicstack.dev — create/merge/close PRs, manage issues, milestones, and CI queue waits. Use when working with Mosaic Stack git repos. Wraps scripts in ~/.config/mosaic/tools/git/. Works on both Gitea and GitHub (auto-detected via detect-platform.sh).
+---
+
+# mosaic-gitea
+
+Git operations via Mosaic wrapper scripts. Platform-aware (Gitea or GitHub).
+
+## Setup
+
+Scripts auto-detect platform from git remote. Run from inside the repo directory.
+
+For force-merge (branch protection bypass):
+```bash
+GITEA_TOKEN=$(cat ~/.config/mosaic/credentials/gitea.env | grep TOKEN | cut -d= -f2)
+```
+
+Or use the credentials loader:
+```bash
+source ~/.config/mosaic/tools/_lib/credentials.sh
+load_credentials gitea-mosaicstack
+# Exports: GITEA_TOKEN, GITEA_URL
+```
+
+## Script Reference
+
+All scripts in `~/.config/mosaic/tools/git/`.
+
+### Pull Requests
+
+| Script | Purpose | Key flags |
+|---|---|---|
+| `pr-create.sh` | Create a PR | `-t "Title" [-b "Body"] [-B base] [-H head] [-i issue#]` |
+| `pr-list.sh` | List open PRs | `[-s state]` |
+| `pr-view.sh` | View PR details | `-n <pr#>` |
+| `pr-merge.sh` | Squash-merge a PR | `-n <pr#> [-d]` (delete branch) |
+| `pr-close.sh` | Close a PR | `-n <pr#>` |
+| `pr-diff.sh` | Show PR diff | `-n <pr#>` |
+| `pr-review.sh` | Submit a review | `-n <pr#> [-a approve\|request-changes]` |
+| `pr-ci-wait.sh` | Wait for CI on PR | `-n <pr#>` |
+| `pr-metadata.sh` | Get PR metadata as JSON | `-n <pr#>` |
+
+### Issues
+
+| Script | Purpose | Key flags |
+|---|---|---|
+| `issue-create.sh` | Create an issue | `-t "Title" [-b "Body"] [-l labels] [-m milestone]` |
+| `issue-list.sh` | List issues | `[-s state] [-l label]` |
+| `issue-view.sh` | View issue | `-n <issue#>` |
+| `issue-close.sh` | Close issue | `-n <issue#>` |
+| `issue-comment.sh` | Add comment | `-n <issue#> -c "Comment"` |
+| `issue-assign.sh` | Assign issue | `-n <issue#> -u username` |
+| `issue-edit.sh` | Edit issue | `-n <issue#> [-t title] [-b body]` |
+
+### Milestones
+
+| Script | Purpose | Key flags |
+|---|---|---|
+| `milestone-create.sh` | Create milestone | `-t "Title" [-d "due date"]` |
+| `milestone-list.sh` | List milestones | — |
+| `milestone-close.sh` | Close milestone | `-n <number>` |
+
+### CI / Queue
+
+| Script | Purpose | Key flags |
+|---|---|---|
+| `ci-queue-wait.sh` | Wait for CI queue slot | `[-t timeout] [-B branch]` |
+| `detect-platform.sh` | Detect git platform | outputs `gitea` or `github` |
+
+## Common Workflows
+
+**Create PR from current branch:**
+```bash
+cd ~/src/<repo>
+~/.config/mosaic/tools/git/pr-create.sh -t "feat: my feature" -b "Description" -i <issue#>
+```
+
+**Merge a PR (squash, with CI queue guard):**
+```bash
+cd ~/src/<repo>
+~/.config/mosaic/tools/git/pr-merge.sh -n <pr#> -d
+```
+
+**Force-merge bypassing branch protection:**
+```bash
+GITEA_TOKEN=$(cat ~/.config/mosaic/credentials/gitea.env | grep TOKEN | cut -d= -f2)
+curl -X POST "https://git.mosaicstack.dev/api/v1/repos/<org>/<repo>/pulls/<PR>/merge" \
+  -H "Authorization: token $GITEA_TOKEN" -H "Content-Type: application/json" \
+  -d '{"Do":"squash","force_merge":true}'
+```
+
+## Notes
+
+- Mosaic policy: squash merges only, targeting `main`
+- Gitea SSH: `git@git.mosaicstack.dev` → resolves via `~/.ssh/config` to `10.1.1.90:2222`
+- Workers push branches and open PRs but **never merge** — orchestrator handles merges
--- a/skills/mosaic-orchestrator/SKILL.md
+++ b/skills/mosaic-orchestrator/SKILL.md
@@ -0,0 +1,94 @@
+---
+name: mosaic-orchestrator
+description: Initialize and run Mosaic orchestration missions. Use when starting a new mission (set of tasks for a project), checking mission status, resuming an orchestrator session, or running the coordinator loop. Wraps scripts in ~/.config/mosaic/tools/orchestrator/. Read ORCHESTRATOR.md and E2E-DELIVERY.md before initiating Orchestrator mode.
+---
+
+# mosaic-orchestrator
+
+Mosaic mission and orchestrator session management.
+
+## Mandatory Pre-Flight
+
+Before initiating Orchestrator mode, always read:
+1. `~/.config/mosaic/guides/ORCHESTRATOR.md`
+2. `~/.config/mosaic/guides/E2E-DELIVERY.md`
+
+Then declare: **"Now initiating Orchestrator mode..."**
+
+## Binary
+
+```bash
+export PATH="$HOME/.config/mosaic/bin:$PATH"
+mosaic --help
+```
+
+## CLI Commands
+
+```bash
+# Initialize a mission (PRD-driven)
+mosaic prdy init --project <path>
+
+# Initialize coordinator mission
+mosaic coord init --name <name> --project <path> [--milestones m1,m2]
+
+# Run coordinator (launches orchestrator session)
+mosaic coord run --project <path>
+
+# Launch a coding worker (Claude Code with mosaic rails)
+mosaic yolo claude   # Claude Code
+mosaic yolo codex    # Codex
+mosaic yolo glm      # GLM-5
+
+# Health audit
+mosaic doctor
+```
+
+## Orchestrator Scripts
+
+Located in `~/.config/mosaic/tools/orchestrator/`.
+
+| Script | Purpose |
+|---|---|
+| `mission-init.sh` | Initialize mission.json and TASKS.md scaffold |
+| `mission-status.sh` | Show current mission + task state |
+| `session-run.sh` | Launch an orchestrator session |
+| `session-resume.sh` | Resume a paused orchestrator session |
+| `session-status.sh` | Check session health / lock status |
+| `smoke-test.sh` | Post-deploy smoke test |
+| `continue-prompt.sh` | Generate a continue prompt for session |
+
+## Mission Init Pattern
+
+```bash
+export PATH="$HOME/.config/mosaic/bin:$PATH"
+cd ~/src/<repo>
+mosaic coord init \
+  --name "<mission-name>" \
+  --project . \
+  --milestones "milestone-1,milestone-2"
+mosaic coord run --project .
+```
+
+## Worker Launch Rules (MANDATORY)
+
+- **Max 1 Claude (Sonnet) worker at a time** — serial only
+- **Max 6 Codex workers at a time**
+- Always use `mosaic yolo <agent>` from the project directory — never `sessions_spawn` for coding
+- Workers: implement → lint → push branch → open PR → fire system event → **EXIT** (never merge)
+
+## Agent State
+
+```bash
+~/.openclaw/workspace/agents/bin/agent-state status   # Check active agents
+~/.openclaw/workspace/agents/bin/agent-state clear <task>  # Clear stale entry
+```
+
+## Completion Gates
+
+A task is NOT done until all of:
+- [ ] Code review ✓
+- [ ] Security review ✓
+- [ ] Tests GREEN ✓
+- [ ] CI green ✓
+- [ ] Issue closed ✓
+- [ ] Docs updated ✓
--- a/skills/mosaic-portainer/SKILL.md
+++ b/skills/mosaic-portainer/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: mosaic-portainer
+description: Manage Portainer stacks on the Mosaic infrastructure. Use when asked to list, start, stop, redeploy, or check logs of Docker Swarm stacks via Portainer. Wraps scripts in ~/.config/mosaic/tools/portainer/. Requires load_credentials portainer first.
+---
+
+# mosaic-portainer
+
+Manage Portainer stacks via pre-built Mosaic scripts.
+
+## Setup
+
+Always load credentials before running scripts:
+
+```bash
+source ~/.config/mosaic/tools/_lib/credentials.sh
+load_credentials portainer
+# Exports: PORTAINER_URL, PORTAINER_API_KEY
+```
+
+## Scripts
+
+All scripts live in `~/.config/mosaic/tools/portainer/`.
+
+| Script | Purpose | Key flags |
+|---|---|---|
+| `stack-list.sh` | List all stacks | — |
+| `stack-status.sh` | Status of a stack | `-n <name>` |
+| `stack-redeploy.sh` | Redeploy (file or git-based) | `-n <name> [-p]` (pull images) |
+| `stack-start.sh` | Start a stopped stack | `-n <name>` |
+| `stack-stop.sh` | Stop a running stack | `-n <name>` |
+| `stack-logs.sh` | Tail stack logs | `-n <name> [-l lines]` |
+| `endpoint-list.sh` | List Portainer endpoints | — |
+
+## Common Workflows
+
+**Redeploy a stack with fresh images:**
+```bash
+source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
+~/.config/mosaic/tools/portainer/stack-redeploy.sh -n mosaic-stack -p
+```
+
+**Check all stack statuses:**
+```bash
+source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
+~/.config/mosaic/tools/portainer/stack-list.sh
+```
+
+**Tail logs for a service:**
+```bash
+source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials portainer
+~/.config/mosaic/tools/portainer/stack-logs.sh -n mosaic-stack -l 100
+```
+
+## Notes
+
+- Portainer URL: `https://10.1.1.43:9443`
+- Primary Docker host: `w-docker0` (10.1.1.45) managed via Portainer agent
+- Docker Swarm image updates: `stack-redeploy.sh -p` does NOT guarantee new image pull if digest is pinned; SSH to node and `docker pull` first if needed
+- Credentials source: `~/src/jarvis-brain/credentials.json` (must be cloned)
--- a/skills/mosaic-woodpecker/SKILL.md
+++ b/skills/mosaic-woodpecker/SKILL.md
@@ -0,0 +1,70 @@
+---
+name: mosaic-woodpecker
+description: Manage Woodpecker CI pipelines for Mosaic Stack projects. Use when checking pipeline status, triggering pipelines, waiting for CI to complete, or debugging build failures. Wraps scripts in ~/.config/mosaic/tools/woodpecker/. CI URL: https://ci.mosaicstack.dev.
+---
+
+# mosaic-woodpecker
+
+Woodpecker CI management via Mosaic wrapper scripts.
+
+## Setup
+
+```bash
+source ~/.config/mosaic/tools/_lib/credentials.sh
+load_credentials woodpecker
+# Exports: WOODPECKER_URL, WOODPECKER_TOKEN
+```
+
+For a specific instance (e.g. `usc`):
+```bash
+load_credentials woodpecker-usc
+```
+
+## Scripts
+
+All scripts in `~/.config/mosaic/tools/woodpecker/`.
+
+| Script | Purpose | Key flags |
+|---|---|---|
+| `pipeline-status.sh` | Check pipeline status | `[-r owner/repo] [-n number] [-f json\|table]` |
+| `pipeline-list.sh` | List recent pipelines | `[-r owner/repo] [-l limit]` |
+| `pipeline-trigger.sh` | Trigger a pipeline | `[-r owner/repo] [-b branch]` |
+
+CI queue management is in `~/.config/mosaic/tools/git/`:
+
+| Script | Purpose | Key flags |
+|---|---|---|
+| `ci-queue-wait.sh` | Wait for CI queue slot | `[-t timeout_sec] [-B branch] [--purpose merge]` |
+| `pr-ci-wait.sh` | Wait for PR CI to pass | `-n <pr#> [-t timeout]` |
+
+## Common Workflows
+
+**Check latest pipeline on current repo:**
+```bash
+cd ~/src/<repo>
+source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials woodpecker
+~/.config/mosaic/tools/woodpecker/pipeline-status.sh
+```
+
+**Check specific pipeline number:**
+```bash
+~/.config/mosaic/tools/woodpecker/pipeline-status.sh -n 42
+```
+
+**Wait for CI before merging:**
+```bash
+cd ~/src/<repo>
+~/.config/mosaic/tools/git/pr-ci-wait.sh -n <pr#>
+```
+
+**Trigger a pipeline on a branch:**
+```bash
+~/.config/mosaic/tools/woodpecker/pipeline-trigger.sh -r mosaic/mosaic-stack -b main
+```
+
+## Notes
+
+- CI URL: `https://ci.mosaicstack.dev`
+- Credentials: `load_credentials woodpecker` (from `~/src/jarvis-brain/credentials.json`)
+- `ci-queue-wait.sh` is automatically called by `pr-merge.sh` unless `--skip-queue-guard` is passed
+- Pipeline output shows step-level status: OK / FAIL / RUN / SKIP / WAIT