@caddis/cli 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (153) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +150 -1
  3. package/bundles/antigravity-plugin/agents/code-reviewer.md +47 -0
  4. package/bundles/antigravity-plugin/agents/preflight.md +53 -0
  5. package/bundles/antigravity-plugin/guard_agy.py +338 -0
  6. package/bundles/antigravity-plugin/hooks.json +36 -0
  7. package/bundles/antigravity-plugin/mcp_config.json +8 -0
  8. package/bundles/antigravity-plugin/mcp_ping_server.py +55 -0
  9. package/bundles/antigravity-plugin/plugin.json +5 -0
  10. package/bundles/antigravity-plugin/session_end_agy.py +57 -0
  11. package/bundles/antigravity-plugin/skills/_registry.md +115 -0
  12. package/bundles/antigravity-plugin/skills/add-rules/SKILL.md +45 -0
  13. package/bundles/antigravity-plugin/skills/api-design/SKILL.md +249 -0
  14. package/bundles/antigravity-plugin/skills/backend-development/SKILL.md +305 -0
  15. package/bundles/antigravity-plugin/skills/best-practices/SKILL.md +500 -0
  16. package/bundles/antigravity-plugin/skills/best-practices/agents/best-practices-referencer.md +263 -0
  17. package/bundles/antigravity-plugin/skills/best-practices/agents/codebase-context-builder.md +326 -0
  18. package/bundles/antigravity-plugin/skills/best-practices/agents/task-intent-analyzer.md +245 -0
  19. package/bundles/antigravity-plugin/skills/best-practices/references/anti-patterns.md +571 -0
  20. package/bundles/antigravity-plugin/skills/best-practices/references/before-after-examples.md +1114 -0
  21. package/bundles/antigravity-plugin/skills/best-practices/references/best-practices-guide.md +513 -0
  22. package/bundles/antigravity-plugin/skills/best-practices/references/common-workflows.md +692 -0
  23. package/bundles/antigravity-plugin/skills/best-practices/references/prompt-patterns.md +547 -0
  24. package/bundles/antigravity-plugin/skills/brainstorming/SKILL.md +57 -0
  25. package/bundles/antigravity-plugin/skills/ci-cd-pipeline/SKILL.md +315 -0
  26. package/bundles/antigravity-plugin/skills/code-documentation/SKILL.md +271 -0
  27. package/bundles/antigravity-plugin/skills/code-review/SKILL.md +122 -0
  28. package/bundles/antigravity-plugin/skills/codebase-audit/SKILL.md +204 -0
  29. package/bundles/antigravity-plugin/skills/context-curator/SKILL.md +157 -0
  30. package/bundles/antigravity-plugin/skills/cross-review/SKILL.md +40 -0
  31. package/bundles/antigravity-plugin/skills/css-architecture/SKILL.md +305 -0
  32. package/bundles/antigravity-plugin/skills/css-architecture/references/RESPONSIVE-DESIGN.md +604 -0
  33. package/bundles/antigravity-plugin/skills/database-design/SKILL.md +177 -0
  34. package/bundles/antigravity-plugin/skills/db-diagram/SKILL.md +148 -0
  35. package/bundles/antigravity-plugin/skills/db-diagram/scripts/sql_to_graph.py +1212 -0
  36. package/bundles/antigravity-plugin/skills/digress/SKILL.md +61 -0
  37. package/bundles/antigravity-plugin/skills/draw-io/SKILL.md +162 -0
  38. package/bundles/antigravity-plugin/skills/draw-io/references/aws-icons.md +677 -0
  39. package/bundles/antigravity-plugin/skills/draw-io/references/layout-guidelines.md +142 -0
  40. package/bundles/antigravity-plugin/skills/draw-io/references/troubleshooting.md +118 -0
  41. package/bundles/antigravity-plugin/skills/draw-io/references/workflows.md +103 -0
  42. package/bundles/antigravity-plugin/skills/draw-io/scripts/convert-drawio-to-png.sh +25 -0
  43. package/bundles/antigravity-plugin/skills/draw-io/scripts/find_aws_icon.py +79 -0
  44. package/bundles/antigravity-plugin/skills/error-handling/SKILL.md +260 -0
  45. package/bundles/antigravity-plugin/skills/excalidraw-db/SKILL.md +38 -0
  46. package/bundles/antigravity-plugin/skills/fastapi-dev/SKILL.md +300 -0
  47. package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md +198 -0
  48. package/bundles/antigravity-plugin/skills/frontend-design/SKILL.md +193 -0
  49. package/bundles/antigravity-plugin/skills/frontend-design/references/my-tech-stack.md +127 -0
  50. package/bundles/antigravity-plugin/skills/gh-cli/SKILL.md +195 -0
  51. package/bundles/antigravity-plugin/skills/git-commit/SKILL.md +285 -0
  52. package/bundles/antigravity-plugin/skills/golden-plan/SKILL.md +577 -0
  53. package/bundles/antigravity-plugin/skills/handoff/SKILL.md +100 -0
  54. package/bundles/antigravity-plugin/skills/implement/SKILL.md +114 -0
  55. package/bundles/antigravity-plugin/skills/javascript-typescript/SKILL.md +142 -0
  56. package/bundles/antigravity-plugin/skills/kb/SKILL.md +60 -0
  57. package/bundles/antigravity-plugin/skills/mermaid-db/SKILL.md +33 -0
  58. package/bundles/antigravity-plugin/skills/mermaid-diagrams/SKILL.md +236 -0
  59. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/ENHANCEMENTS.md +264 -0
  60. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/MERMAID-SUMMARY.md +137 -0
  61. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/advanced-features.md +556 -0
  62. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/architecture-diagrams.md +192 -0
  63. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/c4-diagrams.md +410 -0
  64. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/class-diagrams.md +361 -0
  65. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/erd-diagrams.md +510 -0
  66. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/flowcharts.md +450 -0
  67. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/sequence-diagrams.md +394 -0
  68. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/troubleshooting.md +335 -0
  69. package/bundles/antigravity-plugin/skills/mermaid-diagrams/references/workflows.md +418 -0
  70. package/bundles/antigravity-plugin/skills/migrate-dir/SKILL.md +68 -0
  71. package/bundles/antigravity-plugin/skills/mockup/SKILL.md +242 -0
  72. package/bundles/antigravity-plugin/skills/particle-art/SKILL.md +243 -0
  73. package/bundles/antigravity-plugin/skills/particle-art/references/canvas-utils.ts +171 -0
  74. package/bundles/antigravity-plugin/skills/particle-art/references/dot-field.template.tsx +203 -0
  75. package/bundles/antigravity-plugin/skills/particle-art/references/flow-field.template.tsx +263 -0
  76. package/bundles/antigravity-plugin/skills/particle-art/references/node-shape.template.tsx +261 -0
  77. package/bundles/antigravity-plugin/skills/particle-art/references/shape-sampler.ts +281 -0
  78. package/bundles/antigravity-plugin/skills/particle-art/references/stipple-morph.template.tsx +167 -0
  79. package/bundles/antigravity-plugin/skills/particle-art/references/stipple.template.tsx +175 -0
  80. package/bundles/antigravity-plugin/skills/particle-art/references/trail-ghost.template.tsx +266 -0
  81. package/bundles/antigravity-plugin/skills/particle-art/references/usage-examples.md +320 -0
  82. package/bundles/antigravity-plugin/skills/playwright/API_REFERENCE.md +653 -0
  83. package/bundles/antigravity-plugin/skills/playwright/SKILL.md +454 -0
  84. package/bundles/antigravity-plugin/skills/playwright/lib/helpers.js +441 -0
  85. package/bundles/antigravity-plugin/skills/playwright/package.json +26 -0
  86. package/bundles/antigravity-plugin/skills/playwright/run.js +228 -0
  87. package/bundles/antigravity-plugin/skills/prd/SKILL.md +107 -0
  88. package/bundles/antigravity-plugin/skills/preflight/SKILL.md +435 -0
  89. package/bundles/antigravity-plugin/skills/python/SKILL.md +388 -0
  90. package/bundles/antigravity-plugin/skills/react-best-practices/SKILL.md +269 -0
  91. package/bundles/antigravity-plugin/skills/react-dev/README.md +404 -0
  92. package/bundles/antigravity-plugin/skills/react-dev/SKILL.md +459 -0
  93. package/bundles/antigravity-plugin/skills/react-dev/examples/generic-components.md +579 -0
  94. package/bundles/antigravity-plugin/skills/react-dev/examples/server-components.md +579 -0
  95. package/bundles/antigravity-plugin/skills/react-dev/references/event-handlers.md +574 -0
  96. package/bundles/antigravity-plugin/skills/react-dev/references/hooks.md +456 -0
  97. package/bundles/antigravity-plugin/skills/react-dev/references/react-19-patterns.md +638 -0
  98. package/bundles/antigravity-plugin/skills/react-dev/references/react-router.md +1002 -0
  99. package/bundles/antigravity-plugin/skills/react-dev/references/tanstack-router.md +587 -0
  100. package/bundles/antigravity-plugin/skills/refactoring/SKILL.md +486 -0
  101. package/bundles/antigravity-plugin/skills/resume/SKILL.md +36 -0
  102. package/bundles/antigravity-plugin/skills/security-review/SKILL.md +196 -0
  103. package/bundles/antigravity-plugin/skills/setup-project-ai/SKILL.md +61 -0
  104. package/bundles/antigravity-plugin/skills/ship/SKILL.md +107 -0
  105. package/bundles/antigravity-plugin/skills/ship-merge/SKILL.md +103 -0
  106. package/bundles/antigravity-plugin/skills/ship-pr/SKILL.md +102 -0
  107. package/bundles/antigravity-plugin/skills/skill-creator/LICENSE.txt +202 -0
  108. package/bundles/antigravity-plugin/skills/skill-creator/SKILL.md +491 -0
  109. package/bundles/antigravity-plugin/skills/skill-creator/agents/analyzer.md +274 -0
  110. package/bundles/antigravity-plugin/skills/skill-creator/agents/comparator.md +202 -0
  111. package/bundles/antigravity-plugin/skills/skill-creator/agents/grader.md +223 -0
  112. package/bundles/antigravity-plugin/skills/skill-creator/assets/eval_review.html +146 -0
  113. package/bundles/antigravity-plugin/skills/skill-creator/eval-viewer/generate_review.py +471 -0
  114. package/bundles/antigravity-plugin/skills/skill-creator/eval-viewer/viewer.html +1325 -0
  115. package/bundles/antigravity-plugin/skills/skill-creator/references/schemas.md +430 -0
  116. package/bundles/antigravity-plugin/skills/skill-creator/scripts/__init__.py +0 -0
  117. package/bundles/antigravity-plugin/skills/skill-creator/scripts/aggregate_benchmark.py +401 -0
  118. package/bundles/antigravity-plugin/skills/skill-creator/scripts/generate_report.py +326 -0
  119. package/bundles/antigravity-plugin/skills/skill-creator/scripts/improve_description.py +247 -0
  120. package/bundles/antigravity-plugin/skills/skill-creator/scripts/package_skill.py +136 -0
  121. package/bundles/antigravity-plugin/skills/skill-creator/scripts/quick_validate.py +103 -0
  122. package/bundles/antigravity-plugin/skills/skill-creator/scripts/run_eval.py +310 -0
  123. package/bundles/antigravity-plugin/skills/skill-creator/scripts/run_loop.py +328 -0
  124. package/bundles/antigravity-plugin/skills/skill-creator/scripts/utils.py +47 -0
  125. package/bundles/antigravity-plugin/skills/sql/SKILL.md +321 -0
  126. package/bundles/antigravity-plugin/skills/tdd/SKILL.md +37 -0
  127. package/bundles/antigravity-plugin/skills/tdd-workflow/SKILL.md +188 -0
  128. package/bundles/antigravity-plugin/skills/technical-writing/SKILL.md +286 -0
  129. package/bundles/antigravity-plugin/skills/test-strategy/SKILL.md +155 -0
  130. package/bundles/antigravity-plugin/skills/ui-brief/SKILL.md +84 -0
  131. package/bundles/antigravity-plugin/skills/ui-review/SKILL.md +176 -0
  132. package/bundles/antigravity-plugin/skills/ui-review/references/framework-fixes.md +471 -0
  133. package/bundles/antigravity-plugin/skills/ui-review/references/visual-checklist.md +236 -0
  134. package/bundles/antigravity-plugin/skills/usage-review/SKILL.md +77 -0
  135. package/bundles/antigravity-plugin/skills/use-model/SKILL.md +64 -0
  136. package/bundles/antigravity-plugin/skills/using-git-worktrees/SKILL.md +217 -0
  137. package/bundles/antigravity-plugin/skills/version/SKILL.md +18 -0
  138. package/bundles/antigravity-plugin/skills/warm-editorial-ui/DESIGN_TOKENS.md +487 -0
  139. package/bundles/antigravity-plugin/skills/warm-editorial-ui/IMPLEMENTATION_GUIDE.md +177 -0
  140. package/bundles/antigravity-plugin/skills/warm-editorial-ui/SKILL.md +732 -0
  141. package/bundles/antigravity-plugin/skills/webapp-testing/LICENSE.txt +202 -0
  142. package/bundles/antigravity-plugin/skills/webapp-testing/SKILL.md +97 -0
  143. package/bundles/antigravity-plugin/skills/webapp-testing/examples/console_logging.py +35 -0
  144. package/bundles/antigravity-plugin/skills/webapp-testing/examples/element_discovery.py +40 -0
  145. package/bundles/antigravity-plugin/skills/webapp-testing/examples/static_html_automation.py +33 -0
  146. package/bundles/antigravity-plugin/skills/webapp-testing/scripts/with_server.py +106 -0
  147. package/bundles/antigravity-plugin/skills/windows-deployment/SKILL.md +880 -0
  148. package/bundles/antigravity-plugin/skills/writing-plans/SKILL.md +384 -0
  149. package/bundles/antigravity-plugin/statusline-command-agy.sh +91 -0
  150. package/bundles/antigravity-plugin/warm_start_agy.py +149 -0
  151. package/bundles/manifest.json +6 -0
  152. package/dist/cli.js +5363 -0
  153. package/package.json +61 -4
@@ -0,0 +1,61 @@
1
+ ---
2
+ name: setup-project-ai
3
+ description: Install or refresh the agent-agnostic dev harness in this project (AGENTS.md-canonical rules hierarchy + CLAUDE.md @import shims, subagents, commands, settings)
4
+ ---
5
+
6
+ # /setup-project-ai — install the harness
7
+
8
+ Set up (or refresh) the agent-agnostic development harness for this project. Follow the
9
+ `setup-project-ai` skill end-to-end: run the deterministic generator, resolve any reported
10
+ placeholders, enrich the generated AGENTS.md rules hierarchy (the canonical files — never the CLAUDE.md
11
+ shims) with project-specific facts, ensure the test env, and smoke-test.
12
+
13
+ Context / args: **$ARGUMENTS**
14
+
15
+ Load and follow the `setup-project-ai` skill. Do not hand-roll the steps — the deterministic parts
16
+ must go through the bundled generator so they don't vary. Resolve its path per the skill's Step 1:
17
+ - Plugin install: `${CLAUDE_PLUGIN_ROOT}/scripts/setup_project_ai.py`
18
+ - harness (caddis) checkout: `scripts/setup_project_ai.py`
19
+
20
+ ## After the deterministic step — install the claude-oss / claude-glm launchers (optional)
21
+
22
+ `claude-oss` / `claude-glm` (see `/caddis:use-model`) let a session run on an OSS provider (GLM,
23
+ DeepSeek, OpenRouter). They live at `claude-harness/scripts/claude-oss.{sh,ps1}`. This step never
24
+ silently edits the user's shell profile — print the one-liner and let them run it:
25
+
26
+ ```powershell
27
+ # PowerShell — add to $PROFILE (or run once per session):
28
+ function claude-oss { & "<path-to>\claude-harness\scripts\claude-oss.ps1" @args }
29
+ function claude-glm { & "<path-to>\claude-harness\scripts\claude-oss.ps1" @args }
30
+ ```
31
+ ```bash
32
+ # bash/zsh — add to ~/.bashrc / ~/.zshrc:
33
+ alias claude-oss="<path-to>/claude-harness/scripts/claude-oss.sh"
34
+ alias claude-glm="<path-to>/claude-harness/scripts/claude-oss.sh"
35
+ ```
36
+ Resolve `<path-to>` per the same plugin-vs-source rule as the generator itself (`${CLAUDE_PLUGIN_ROOT}`
37
+ for a plugin install, the harness checkout path for caddis). Also set `CADDIS_KEYS_FILE`
38
+ (default `~/.claudster/keys.env`) with the provider keys — see `docs/guide/providers-and-keys.md`.
39
+
40
+ ## After the deterministic step — deploy private harness skills (optional)
41
+
42
+ Some harness authors keep **private** skills on disk (organization-specific deploy/workflow skills, for
43
+ example) that are **not** shipped in the public plugin. This step is for a local harness author who keeps
44
+ such a source on disk; it is a no-op for everyone else. Point `CADDIS_HARNESS_SRC` at your harness root
45
+ (the folder containing your private `skills/private/`) and run:
46
+
47
+ ```powershell
48
+ # CADDIS_HARNESS_SRC is current; CLAUDSTER_HARNESS_SRC is read as a one-version fallback.
49
+ $harnessSrc = if ($env:CADDIS_HARNESS_SRC) { $env:CADDIS_HARNESS_SRC } else { $env:CLAUDSTER_HARNESS_SRC }
50
+ $src = if ($harnessSrc) { Join-Path $harnessSrc "skills\private" } else { $null }
51
+ $dest = ".github\skills\private"
52
+ if ($src -and (Test-Path $src)) {
53
+ New-Item -ItemType Directory -Force $dest | Out-Null
54
+ Copy-Item "$src\*" $dest -Recurse -Force
55
+ Write-Host "private skills deployed to $dest"
56
+ } else {
57
+ Write-Host "private harness source not found (set CADDIS_HARNESS_SRC) — skipping; public installs have none."
58
+ }
59
+ ```
60
+
61
+ Do not commit these private skills to the project repo — they are private harness resources.
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: ship
3
+ description: Commit, push, and monitor the deploy pipeline (auto-detects Gitea, GitHub Actions, or local-only)
4
+ ---
5
+
6
+ # /ship — commit → push → CI → prod
7
+
8
+ Ship the current working changes via this repo's actual delivery pipeline. The pipeline differs per
9
+ repo, so **detect it first**, then follow the matching lane. Preflight, staging, and commit are
10
+ identical across lanes; only monitoring and validation differ.
11
+
12
+ > **This is the express lane** — on repos where a push to the default branch deploys, `/ship` sends
13
+ > work straight to prod with no review pause. Right for a hotfix. **For feature work, use the
14
+ > reviewed lane instead: `/ship-pr`** (open a PR, monitor CI, stop at green) **→ `/ship-merge`**
15
+ > (merge the green PR behind a deploy-confirm, validate, clean up).
16
+
17
+ Optional message: **$ARGUMENTS** (if empty, derive a conventional commit message from staged changes)
18
+
19
+ ## Step 0 — Detect the pipeline (do this before anything else)
20
+ Inspect the repo and pick exactly one lane:
21
+ - **Gitea lane** — `.gitea/workflows/` exists. Monitor via the Gitea API; follow the `deploy-local`
22
+ skill (CalVer/NSSM prod deploy). This is the harness's local deploy setup.
23
+ - **GitHub lane** — `.github/workflows/` exists (and no `.gitea/`). Monitor via the `gh` CLI.
24
+ - **Local-only lane** — neither exists, or there is no push remote. Commit (and push if a remote
25
+ exists); there is no CI to monitor — say so explicitly and stop after the push + local validation.
26
+
27
+ Read `AGENTS.md` and the detected workflow file(s) before starting so you use this repo's real gate
28
+ names, branch, and service identifiers — never assume.
29
+
30
+ ## Steps 1–3 — common to every lane
31
+
32
+ **1. PREFLIGHT** — Run local quality gates that mirror CI:
33
+ - Backend: `ruff check .` (must be clean before any commit)
34
+ - Frontend: `npm run typecheck && npm run build` (if `frontend/` exists)
35
+ - Tests: run only if the user says they're needed or a gate explicitly requires them
36
+ - Fix any failures before proceeding. Do not commit broken code.
37
+
38
+ **2. STAGE + COMMIT** — Stage only the intended files (never `git add -A` blindly):
39
+ ```
40
+ git status --short # confirm what's staged
41
+ git add <specific files>
42
+ git commit -m "<type>(<scope>): <message>"
43
+ git rev-parse HEAD # record SHA for monitoring
44
+ ```
45
+ Use conventional commits: `fix:`, `feat:`, `chore:`, `refactor:`, `docs:`. Scope = affected module.
46
+
47
+ **3. PUSH** — to the repo's default branch (confirm the branch first; don't assume `main`):
48
+ ```
49
+ git push origin <branch>
50
+ ```
51
+ Confirm the push succeeded and the SHA is accepted by the remote. (Local-only lane: skip if there is
52
+ no remote, and note that nothing was pushed.)
53
+
54
+ ## Step 4 — MONITOR CI (lane-specific)
55
+
56
+ **Gitea lane** — Poll the Gitea API using the token from `config/.env.gitea` (load it first):
57
+ ```powershell
58
+ $envFile = Join-Path (Get-Location) "config/.env.gitea"
59
+ # ... (load the bot token from file — see deploy-local skill)
60
+ ```
61
+ Track jobs in order: `lint_and_test` → `frontend_checks` (if present) → `deploy_prod` →
62
+ `release_metadata` → `notify`. Report status as each job completes. On failure, classify it and apply
63
+ the minimum fix (see `deploy-local` skill §6).
64
+
65
+ **GitHub lane** — Watch the run the push triggered via the `gh` CLI:
66
+ ```
67
+ gh run list --branch <branch> --limit 1 # find the run id for the pushed SHA
68
+ gh run watch <run-id> --exit-status # stream until done; non-zero on failure
69
+ gh run view <run-id> --log-failed # on failure, pull only the failing job logs
70
+ ```
71
+ Report each job's status as it resolves. On failure, classify it and apply the minimum source fix.
72
+
73
+ **Local-only lane** — no CI; skip monitoring.
74
+
75
+ ## Step 5 — PROD / POST-DEPLOY VALIDATION
76
+ - **Gitea lane:** after `deploy_prod` succeeds — prod checkout SHA matches the pushed commit; NSSM
77
+ services for this repo are Running; health endpoint green; version endpoint shows the expected
78
+ SHA/CalVer (if exposed).
79
+ - **GitHub lane:** if the workflow deploys, validate against its target the same way (deployed SHA /
80
+ health / version endpoint). If it's CI-only (no deploy job), confirm the run is green and stop.
81
+ - **Local-only lane:** run the app's smoke/health check locally if one exists; otherwise report that
82
+ validation is limited to the green preflight.
83
+
84
+ ## Step 6 — REPORT
85
+ ```
86
+ Repo: <name>
87
+ Pipeline: gitea | github | local-only
88
+ Commit: <sha> — <message>
89
+ CI jobs: <job ✓ / ✗ per job, or "n/a (local-only)">
90
+ Prod/Target SHA: matches ✓ | n/a
91
+ Health: green ✓ | n/a
92
+ Release tag: <tag> → <sha> | n/a
93
+ ```
94
+
95
+ ## Rules
96
+ - Never push before preflight gates are green.
97
+ - Never use `git add -A` without reviewing `git status` first.
98
+ - Do not edit a workflow file (`.gitea/workflows/` or `.github/workflows/`) to make a failing gate
99
+ pass — fix the source.
100
+ - Gitea lane: tag-triggered runs after `release_metadata` are expected; verify `deploy_prod` is
101
+ **skipped** in them.
102
+ - If health is red after deploy, report it immediately — do not attempt a silent re-deploy.
103
+
104
+ ## Skill reference
105
+ Full procedures for the Gitea lane (CI monitoring, prod validation, queue triage, failure remediation)
106
+ are in `skills/devops/deploy-local/SKILL.md`. For the GitHub lane, the `gh-cli` skill covers `gh run`
107
+ usage. Load whichever matches the detected lane when a step needs more detail.
@@ -0,0 +1,103 @@
1
+ ---
2
+ name: ship-merge
3
+ description: Merge an already-green, already-reviewed PR behind an explicit deploy-confirm, monitor the deploy, validate prod, then clean up the branch — only on green.
4
+ ---
5
+
6
+ # /ship-merge — the reviewed lane, half 2: green PR → deployed → cleaned up
7
+
8
+ The deliberate second door. `/ship-pr` produced a reviewable artifact and stopped; this command
9
+ takes an **already-green, already-reviewed** PR through the one irreversible step — on these repos
10
+ **merge == deploy** — then watches the deploy, validates prod, and cleans up the branch **only
11
+ after** the deploy is confirmed green.
12
+
13
+ This command **never creates a PR** — that is `/ship-pr`'s job. A single create-and-merge shot
14
+ would recreate exactly what PRs exist to prevent: the ceremony of review with none of the pause.
15
+
16
+ Argument: **$ARGUMENTS** (PR number/URL; if empty, infer the current branch's open PR). An optional
17
+ strategy word (`squash` | `merge` | `rebase`) overrides the detected merge strategy.
18
+
19
+ ## Step 0 — Detect the lane, resolve the PR
20
+
21
+ - **Gitea lane** — `.gitea/workflows/` exists: PR state + merge via the Gitea API; deploy
22
+ monitoring via the `deploy-local` skill.
23
+ - **GitHub lane** — `.github/workflows/` (no `.gitea/`): `gh pr view/merge`, `gh run watch`
24
+ (the `gh-cli` skill).
25
+ - **Local-only lane** — no forge, no PR concept: **refuse** and point at `/ship`. Stop.
26
+
27
+ Resolve the target PR from `$ARGUMENTS`, else the current branch's open PR. No open PR → report
28
+ that and point at `/ship-pr`. Read `AGENTS.md` + the workflow file(s) for the repo's real deploy
29
+ job names and default branch — never assume.
30
+
31
+ ## Step 1 — Refuse unless green + mergeable + reviewed
32
+
33
+ All of, per the repo's own rules:
34
+ - **Required checks green** (including the scope-guard check when the repo has one).
35
+ - **Mergeable** — no merge **conflicts** against the default branch.
36
+ - **Reviewed** — if the repo configures **required** reviewers/approvals, they must be satisfied.
37
+ On a solo repo with none configured, Step 2's explicit human confirm IS the review gate.
38
+
39
+ If anything fails: report **exactly what is missing** (which check is red, which review is absent,
40
+ whether it conflicts) and **stop**. Never merge around a red or a rule.
41
+
42
+ ## Step 2 — Explicit human-confirm gate (the deploy warning)
43
+
44
+ State plainly, then wait for confirmation:
45
+
46
+ > Merging PR #N will **DEPLOY** `<head-sha>` to prod via the pipeline. Confirm to proceed.
47
+
48
+ This is the one irreversible, outward-facing step. Approval here **does not carry over** to any
49
+ future run — ask every time, even for the same PR five minutes later.
50
+
51
+ ## Step 3 — Merge
52
+
53
+ Use the repo's configured **merge strategy** — read it from repo settings (Gitea repo settings API /
54
+ `gh repo view --json squashMergeAllowed,mergeCommitAllowed,rebaseMergeAllowed`) and `AGENTS.md`;
55
+ an explicit argument wins. Options: **squash**, **merge-commit**, rebase-merge. **Don't assume** —
56
+ if detection is inconclusive, say so and use merge-commit (never silently squash someone's history).
57
+ Record the merge SHA.
58
+
59
+ ## Step 4 — Monitor the deploy
60
+
61
+ The merge lands on the default branch and triggers the pipeline. Watch it via the lane's skill:
62
+ - Gitea: `lint_and_test` → `frontend_checks` (if present) → **`deploy_prod`** → `release_metadata`
63
+ → `notify` (`deploy-local` skill §monitoring; classify + minimum-fix on failure).
64
+ - GitHub: `gh run watch <run-id> --exit-status` on the default branch; if the workflow has a deploy
65
+ job, watch it through; if CI-only, note that no deploy occurs.
66
+
67
+ ## Step 5 — Post-deploy validation
68
+
69
+ - Prod/target checkout **SHA matches the merge commit**.
70
+ - Services (NSSM or equivalent) **Running**; **health** endpoint green.
71
+ - Version endpoint shows the expected SHA/CalVer, when exposed.
72
+ (Same checklist as `/ship` Step 5 — reuse it.) If validation is red, report immediately; do not
73
+ attempt a silent re-deploy — and **skip cleanup** (Step 6).
74
+
75
+ ## Step 6 — Branch cleanup — only after a confirmed-green deploy
76
+
77
+ **Only after** Step 5 is green:
78
+ - Delete the **remote** feature branch; delete the **local** feature branch.
79
+ - Switch to the default branch and fast-forward it to the merge commit.
80
+ - Drop the `backup/<branch>-preship` ref `/ship-pr` created.
81
+
82
+ If deploy validation failed: **skip cleanup** entirely and say so — never delete a branch whose
83
+ work may need re-work.
84
+
85
+ ## Step 7 — Report
86
+
87
+ ```
88
+ PR: #<n> <title> — merged (<strategy>) as <merge-sha>
89
+ Deploy: <job ✓ / ✗ per job>
90
+ Prod SHA: matches merge ✓ | MISMATCH
91
+ Health: green ✓ | red — reported, cleanup skipped
92
+ Cleanup: remote branch ✗ deleted / local ✗ deleted / backup ref dropped | SKIPPED (<why>)
93
+ ```
94
+
95
+ ## Rules
96
+ - Never merge without: green required checks **and** the explicit human deploy-confirm.
97
+ - Never delete a branch before its deploy is validated green.
98
+ - Never `git add -A` without reviewing `git status`; never edit a workflow file to make a gate pass.
99
+ - Local-only lane: no PR, no merge — refuse and point at `/ship`.
100
+
101
+ ## Skill reference
102
+ Gitea deploy monitoring, prod validation, failure triage: `skills/devops/deploy-local/SKILL.md`.
103
+ GitHub `gh pr merge` / `gh run` usage: the `gh-cli` skill.
@@ -0,0 +1,102 @@
1
+ ---
2
+ name: ship-pr
3
+ description: Open a reviewed PR for the current feature branch — rebase-safe push, PR create/update, monitor CI, STOP at green. Never merges, never deploys (that's /ship-merge).
4
+ ---
5
+
6
+ # /ship-pr — the reviewed lane, half 1: branch → green PR
7
+
8
+ Land feature-branch work as a **Pull Request** so CI + a human gate run **before** the deploy, not
9
+ after. This command does the mechanics only: push safely, open (or update) the PR, watch its checks,
10
+ and **stop at green** with a mergeability verdict. It **never merges and never deploys** — on these
11
+ repos merge == deploy, so the merge stays a separate, deliberate act: `/ship-merge`.
12
+
13
+ For a hotfix straight to the default branch, use `/ship` (the express lane) instead.
14
+
15
+ Optional argument: **$ARGUMENTS** (PR title override; default = derived from the branch's
16
+ conventional-commit summary).
17
+
18
+ ## Step 0 — Detect the lane (before anything else)
19
+
20
+ - **Gitea lane** — `.gitea/workflows/` exists. PR + CI monitoring via the Gitea API (token loading
21
+ and job-polling procedure: the `deploy-local` skill).
22
+ - **GitHub lane** — `.github/workflows/` exists (and no `.gitea/`). PR + monitoring via the `gh` CLI
23
+ (`gh pr create`, `gh pr checks` — see the `gh-cli` skill).
24
+ - **Local-only lane** — neither exists, or there is no push remote. There is no PR concept here:
25
+ **refuse early**, tell the user to use `/ship`, and stop. Do not fabricate a PR flow.
26
+
27
+ Read `AGENTS.md` + the detected workflow file(s) first for the repo's real gate names, default
28
+ branch, and merge conventions — never assume `main`, never assume job names.
29
+
30
+ ## Step 1 — Refuse on the default branch
31
+
32
+ A PR is *branch → default*. If HEAD **is** the default branch, stop and point at `/ship` — there is
33
+ nothing to open a PR from. (Offer to create a feature branch from the current work if the changes
34
+ are uncommitted.)
35
+
36
+ ## Step 2 — Preflight (local gates mirroring CI)
37
+
38
+ - Backend: `ruff check .` clean.
39
+ - Frontend: `npm run typecheck && npm run build` if `frontend/` exists.
40
+ - Fix failures first. **Never open a PR over red preflight** — a PR that arrives red wastes the
41
+ reviewer it exists to serve.
42
+
43
+ ## Step 3 — Scope-guard pre-check (before the PR exists)
44
+
45
+ - If the repo has a **named scope-guard workflow** (e.g. a Gitea `pr-scope-guard` that blocks PRs
46
+ mixing infra `.gitea/`/`.github/` changes with product `src/`/`frontend/`/`tests/` changes): read
47
+ the workflow's own rule and check the branch diff against exactly that rule **before** creating
48
+ the PR. On a violation, **refuse with the specific offending files** — do not let the guard fail
49
+ the PR after the fact.
50
+ - Without a named guard, apply the generic infra-vs-product mixed-diff heuristic as a **warning
51
+ only** — surface it and proceed (repos without a guard allow mixed PRs by construction).
52
+
53
+ ## Step 4 — Rebase-safe currency
54
+
55
+ - If the branch is **behind** the default branch, offer to rebase onto it (stale branches are how
56
+ merges rot). Only when behind — never rebase gratuitously.
57
+ - If the branch was already pushed, a rebase rewrites history. **Snapshot first, then push safely:**
58
+ ```
59
+ git branch backup/<branch>-preship # recovery ref BEFORE any rewrite
60
+ git rebase <default-branch>
61
+ git push --force-with-lease origin <branch> # never bare --force
62
+ ```
63
+
64
+ ## Step 5 — Push + create/update the PR
65
+
66
+ - Push the branch (plain push if no rewrite happened).
67
+ - Create the PR: title from the branch's conventional-commit summary (or `$ARGUMENTS`); body = the
68
+ commit list + a "generated by /ship-pr" note.
69
+ - **Idempotent:** if a PR for this branch **already exists**, update its title/body and report it —
70
+ never error, never open a duplicate.
71
+
72
+ ## Step 6 — Monitor PR CI
73
+
74
+ Watch the PR's checks job-by-job (never the deploy — PRs don't deploy here), including the
75
+ scope-guard check when present:
76
+ - Gitea lane: poll the run for the PR's head SHA via the API (`deploy-local` skill procedure).
77
+ - GitHub lane: `gh pr checks <pr> --watch` / `gh run watch` (`gh-cli` skill).
78
+ On a red check, classify the failure and apply the minimum **source** fix, then re-push (through
79
+ Step 4's safety if history must change).
80
+
81
+ ## Step 7 — STOP at green, report
82
+
83
+ ```
84
+ PR: <url>
85
+ Branch: <branch> → <default-branch> (rebased: yes/no, backup ref: backup/<branch>-preship | n/a)
86
+ Checks: <check ✓ / ✗ per check>
87
+ Scope-guard: pass | warn (<files>) | n/a
88
+ Mergeable: YES — run /ship-merge <pr> when reviewed | BLOCKED by <exact reason>
89
+ ```
90
+ This command's job ends here. **Never merge.** The merge is `/ship-merge`'s deliberately separate,
91
+ human-confirmed door.
92
+
93
+ ## Rules
94
+ - **Never merges, never deploys** — no merge action exists in this command, by design.
95
+ - Never `git add -A` without reviewing `git status` first.
96
+ - Never force-push without a `backup/*-preship` recovery ref; force pushes are `--force-with-lease` only.
97
+ - Never edit a workflow file (`.gitea/workflows/`, `.github/workflows/`) to make a gate pass — fix the source.
98
+ - Local-only lane: refuse + point at `/ship`. On the default branch: stop + point at `/ship`.
99
+
100
+ ## Skill reference
101
+ Gitea API monitoring + failure triage: `skills/devops/deploy-local/SKILL.md`. GitHub `gh pr` / `gh run`
102
+ usage: the `gh-cli` skill. Load whichever matches the detected lane.
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.