From 12545cf98c3df6df1a4ff5d602cd29139aec1f92 Mon Sep 17 00:00:00 2001 From: Jarvis Date: Sun, 22 Mar 2026 15:32:05 +0000 Subject: [PATCH] feat: add mosaic ops skills (portainer, gitea, woodpecker, deploy, orchestrator) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- skills/mosaic-deploy/SKILL.md | 80 ++++++++++++++++++++++++ skills/mosaic-gitea/SKILL.md | 97 +++++++++++++++++++++++++++++ skills/mosaic-orchestrator/SKILL.md | 94 ++++++++++++++++++++++++++++ skills/mosaic-portainer/SKILL.md | 59 ++++++++++++++++++ skills/mosaic-woodpecker/SKILL.md | 70 +++++++++++++++++++++ 5 files changed, 400 insertions(+) create mode 100644 skills/mosaic-deploy/SKILL.md create mode 100644 skills/mosaic-gitea/SKILL.md create mode 100644 skills/mosaic-orchestrator/SKILL.md create mode 100644 skills/mosaic-portainer/SKILL.md create mode 100644 skills/mosaic-woodpecker/SKILL.md diff --git a/skills/mosaic-deploy/SKILL.md b/skills/mosaic-deploy/SKILL.md new file mode 100644 index 0000000..509900d --- /dev/null +++ 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/-worktrees/ +git push -u origin +~/.config/mosaic/tools/git/pr-create.sh -t "feat: ..." -b "..." -i +# Note the PR number from output +``` + +### Step 2: Wait for CI + +```bash +~/.config/mosaic/tools/git/pr-ci-wait.sh -n +``` + +If CI fails, check: +```bash +source ~/.config/mosaic/tools/_lib/credentials.sh && load_credentials woodpecker +~/.config/mosaic/tools/woodpecker/pipeline-status.sh -r / +``` + +### Step 3: Merge + +```bash +cd ~/src/ +~/.config/mosaic/tools/git/pr-merge.sh -n -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///pulls//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 -p +``` + +Check deployment: +```bash +~/.config/mosaic/tools/portainer/stack-status.sh -n +~/.config/mosaic/tools/portainer/stack-logs.sh -n -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 ` manually, then redeploy +- Worktrees: all coding work in `~/src/-worktrees/`, never in main checkout +- Always clean up worktree after push: `git worktree remove ~/src/-worktrees/` diff --git a/skills/mosaic-gitea/SKILL.md b/skills/mosaic-gitea/SKILL.md new file mode 100644 index 0000000..3249589 --- /dev/null +++ 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-merge.sh` | Squash-merge a PR | `-n [-d]` (delete branch) | +| `pr-close.sh` | Close a PR | `-n ` | +| `pr-diff.sh` | Show PR diff | `-n ` | +| `pr-review.sh` | Submit a review | `-n [-a approve\|request-changes]` | +| `pr-ci-wait.sh` | Wait for CI on PR | `-n ` | +| `pr-metadata.sh` | Get PR metadata as JSON | `-n ` | + +### 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-close.sh` | Close issue | `-n ` | +| `issue-comment.sh` | Add comment | `-n -c "Comment"` | +| `issue-assign.sh` | Assign issue | `-n -u username` | +| `issue-edit.sh` | Edit issue | `-n [-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 ` | + +### 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/ +~/.config/mosaic/tools/git/pr-create.sh -t "feat: my feature" -b "Description" -i +``` + +**Merge a PR (squash, with CI queue guard):** +```bash +cd ~/src/ +~/.config/mosaic/tools/git/pr-merge.sh -n -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///pulls//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 diff --git a/skills/mosaic-orchestrator/SKILL.md b/skills/mosaic-orchestrator/SKILL.md new file mode 100644 index 0000000..80a62a7 --- /dev/null +++ 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 + +# Initialize coordinator mission +mosaic coord init --name --project [--milestones m1,m2] + +# Run coordinator (launches orchestrator session) +mosaic coord run --project + +# 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/ +mosaic coord init \ + --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 ` 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 # 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 ✓ diff --git a/skills/mosaic-portainer/SKILL.md b/skills/mosaic-portainer/SKILL.md new file mode 100644 index 0000000..47c2dba --- /dev/null +++ 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 ` | +| `stack-redeploy.sh` | Redeploy (file or git-based) | `-n [-p]` (pull images) | +| `stack-start.sh` | Start a stopped stack | `-n ` | +| `stack-stop.sh` | Stop a running stack | `-n ` | +| `stack-logs.sh` | Tail stack logs | `-n [-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) diff --git a/skills/mosaic-woodpecker/SKILL.md b/skills/mosaic-woodpecker/SKILL.md new file mode 100644 index 0000000..427100a --- /dev/null +++ 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 [-t timeout]` | + +## Common Workflows + +**Check latest pipeline on current repo:** +```bash +cd ~/src/ +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/ +~/.config/mosaic/tools/git/pr-ci-wait.sh -n +``` + +**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