Windsurf rules

1---
2name: wire-ci
3model: sonnet
4description: "CI pipeline setup with bundled, forge-neutral templates and local validation. Detects the forge from the git remote, generates workflows for supported forges, and skips honestly for the rest. The CI equivalent of wire-observability."
5---
6 
7# Wire CI
8 
9> **HARD GATE (supported forges only)** — Do not ship a project without CI. Run this skill before first merge to main.
10>
11> On a forge bigpowers ships no templates for, this skill **is not a gate**: it reports the forge, explains what it cannot do, and exits 3. A gate that cannot run must not claim it did. See § Unsupported forges.
12>
13> **HARD GATE** — CI that is untestable locally will break every cycle. Always run `--validate` after generating workflows and `--dry-run` before pushing.
14 
15Generate, validate, and test CI workflows. Detects the forge and project type, copies a **bundled** template, and verifies locally before anything reaches CI.
16 
17## Forge resolution
18 
19`scripts/lib/detect-forge.sh` resolves the forge, first match wins: `BIGPOWERS_FORGE` env var → `forge:` in `specs/forge.yaml` → the `origin` remote URL → `unknown`.
20 
21```bash
22bash scripts/wire-ci.sh --detect     # report forge + stack, write nothing
23bash scripts/wire-ci.sh --plan       # show the template that would be used
24bash scripts/wire-ci.sh --apply      # write the workflow
25```
26 
27GitHub ships templates (`.github/workflows/`). GitLab, Bitbucket, Codeberg, and Gitea are detected but **unsupported** — `--apply` writes nothing and exits 3.
28 
29## Template source — configurable, bundled by default
30 
31Templates live in `docs/templates/ci/<forge>/` **inside the bigpowers package**, so there is no network dependency on any third party's repository. Override with `BIGPOWERS_CI_TEMPLATES=/path/to/your/templates`, laid out as `<root>/<forge>/test-build-release-<stack>.yml`.
32 
33## What this sets up
34 
351. **Test Build Release workflow** — lint → test → build → release in one `needs:` chain
362. **`--validate` mode** — YAML syntax, workflow permissions, required secrets, common pitfalls
373. **`--dry-run` mode** — runs workflows locally via `act` before push
384. **Failure pattern documentation** — see the table below
39 
40Deploy workflows are **not** bundled: they are platform-specific. See [REFERENCE.md](REFERENCE.md) for a worked example.
41 
42## Process
43 
44### 1. Detect forge and stack
45 
46```bash
47bash scripts/wire-ci.sh --detect
48```
49 
50Stack detection reads the project root:
51 
52| Manifest | Stack | Bundled template |
53|----------|-------|------------------|
54| `Cargo.toml` | Rust | `test-build-release-rust.yml` |
55| `package.json` | Node | `test-build-release-node.yml` |
56| `pyproject.toml` / `setup.py` | Python | `test-build-release-python.yml` |
57| `go.mod` | Go | `test-build-release-go.yml` |
58 
59No recognized manifest → exit 3 with the list of manifests it looked for. Do not guess.
60 
61### 2. Apply the template
62 
63```bash
64bash scripts/wire-ci.sh --apply
65```
66 
67**Do not rename the workflow `name:` field** — deploy listens for `"Test Build Release"`.
68 
69Edit placeholders after copying: language versions, `APP_TYPE`, `SITE_URL`.
70 
71### 3. Unsupported forges
72 
73`--apply` writes nothing and exits 3. Your options, in the order the runner prints them:
74 
75- point `BIGPOWERS_CI_TEMPLATES` at templates for your forge
76- pin `forge: github` in `specs/forge.yaml` if the remote is misdetected
77- write the CI config by hand
78 
79Contributing a `docs/templates/ci/gitlab/` set and adding `gitlab` to `FORGE_SUPPORTED_LIST` is the natural next slice — per-forge command mapping (`gh pr checks` → `glab ci status`) is not implemented yet.
80 
81### 4. Validate workflows (`--validate`)
82 
83See [REFERENCE.md](REFERENCE.md). Exit codes: `0` clean, `1` YAML syntax errors, `2` warnings only.
84 
85### 5. Dry-run workflows (`--dry-run`)
86 
87See [REFERENCE.md](REFERENCE.md).
88 
89> **act** runs workflows in a local Docker environment — the most accurate pre-push validation.
90> **gh workflow run** sends the workflow to GitHub but does not execute locally.
91 
92### 6. Document common CI failure patterns
93 
94| Failure | Cause | Fix |
95|---------|-------|-----|
96| `npm publish` fails | `NPM_TOKEN` not set as repo secret | Add `NPM_TOKEN` to repo secrets |
97| `semantic-release` fails on push | Missing `permissions: contents: write` | Add it to the release job |
98| `cargo publish` auth fail | `CARGO_REGISTRY_TOKEN` not set | Add token to env or `~/.cargo/config.toml` |
99| `go vet` fails | Go version mismatch | Use `go-version-file: go.mod` |
100| `cargo clippy` errors | New nightly lints | Pin the toolchain; `cargo clippy --fix` |
101| `act` not found | Docker not running or act missing | `brew install act`; `docker ps` |
102| Hardcoded Node version stale | `.nvmrc` exists but workflow hardcodes | Use `node-version-file: .nvmrc` |
103| Deploy never runs | TBR workflow renamed | Keep `name: Test Build Release` |
104| Release rebuilds binary | Artifact not downloaded | `release` must `download-artifact` from `build` |
105 
106## Verify
107 
108→ verify: `bash scripts/wire-ci.sh --self-test`
109→ verify: `test -f docs/templates/ci/github/test-build-release-node.yml && test -f scripts/lib/detect-forge.sh`
110→ verify: `grep -q wire-ci SKILL-INDEX.md`
111 
112---
113 
114# Wire Ci — Reference
115 
116## Navigation
117 
118| Lines | Section |
119|-------|---------|
120| 1 | Title |
121| 3–20 | Navigation |
122| 21–22 | Examples |
123| 23–39 | Create CI for a Go project (TBR + optional deploy) |
124| 40–49 | Create CI for a CLI tool (TBR only, no deploy) |
125| 50–57 | Validate existing workflows (no generation) |
126| 58–70 | Options |
127| 71–79 | Integration with build-epic |
128| 80–154 | Reference block 1 — test-build-release.yml (Go, excerpt) |
129| 155–204 | Reference block 2 — deploy.yml (generic web app, excerpt) |
130| 205–232 | Reference block 3 — CLI dogfood (big-release pattern) |
131| 233–257 | Reference block 4 — validate script |
132| 258–268 | Reference block 5 — dry-run |
133 
134## Examples
135 
136### Create CI for a Go project (TBR + optional deploy)
137 
138```bash
139# Resolve forge + stack, then apply the bundled template
140bash scripts/wire-ci.sh --detect
141bash scripts/wire-ci.sh --apply
142
143wire-ci --validate
144wire-ci --dry-run
145```
146 
147To use your own org templates instead of the bundled ones:
148 
149```bash
150BIGPOWERS_CI_TEMPLATES=/path/to/your/templates bash scripts/wire-ci.sh --apply
151```
152 
153### Create CI for a CLI tool (TBR only, no deploy)
154 
155```bash
156bash scripts/wire-ci.sh --apply
157# Edit release job to download build artifact — see big-release dogfood
158# CLI/library repos: delete deploy.yml; the release job is terminal.
159
160wire-ci --validate
161```
162 
163### Validate existing workflows (no generation)
164 
165```bash
166wire-ci --validate --check-only
167```
168 
169---
170 
171## Options
172 
173| Flag | Description |
174|------|-------------|
175| `--validate` | Check YAML syntax, permissions, secrets, common pitfalls |
176| `--dry-run` | Run workflows locally via `act` or dispatch via `gh` |
177| `--check-only` | Only validate, do not generate new files |
178| `--type <type>` | Force project type (skip auto-detection) |
179| `--force` | Overwrite existing workflow files |
180| `--no-deploy` | Skip deploy.yml even for hosted stacks |
181 
182---
183 
184## Integration with build-epic
185 
186When `wire-ci` is used as part of `build-epic`:
187 
1881. **During develop-tdd**: If the task modifies `.github/workflows/`, run `wire-ci --validate` as a CI dry-run sub-step
1892. **During release-branch**: After push, run `gh run list --limit 1 --branch main --json status,conclusion` to verify CI passes
190 
191---
192 
193## Reference block 1 — test-build-release.yml (Go, excerpt)
194 
195```yaml
196name: Test Build Release
197on:
198  push:
199    branches: [main]
200  pull_request:
201    branches: [main]
202
203permissions:
204  contents: read
205
206concurrency:
207  group: pipeline-${{ github.workflow }}-${{ github.ref }}
208  cancel-in-progress: true
209
210jobs:
211  lint:
212    runs-on: ubuntu-22.04
213    timeout-minutes: 10
214    steps:
215      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
216      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16  # v6.5.0
217        with:
218          go-version: '1.22'
219          cache: true
220      - uses: golangci/golangci-lint-action@55c2c1448f86e01eaae002a5a3a9624417608d84  # v6.5.2
221        with:
222          version: v1.64.8
223
224  test:
225    needs: [lint]
226    runs-on: ubuntu-22.04
227    steps:
228      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
229      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16  # v6.5.0
230        with:
231          go-version: '1.22'
232          cache: true
233      - run: go vet ./...
234      - run: go test ./... -count=1
235
236  build:
237    needs: [test]
238    runs-on: ubuntu-22.04
239    steps:
240      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
241      - uses: actions/setup-go@924ae3a1cded613372ab5595356fb5720e22ba16  # v6.5.0
242        with:
243          go-version: '1.22'
244          cache: true
245      - run: go build ./...
246      - run: jq -n --arg sha "${{ github.sha }}" '{sha: $sha}' > deploy-meta.json
247      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
248        with:
249          name: deploy-meta
250          path: deploy-meta.json
251
252  release:
253    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
254    needs: [build]
255    permissions:
256      contents: write
257    steps:
258      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
259        with:
260          fetch-depth: 0
261      - run: npx semantic-release
262        env:
263          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
264```
265 
266---
267 
268## Reference block 2 — deploy.yml (generic web app, excerpt)
269 
270```yaml
271name: Deploy
272on:
273  workflow_run:
274    workflows: ["Test Build Release"]
275    types: [completed]
276
277permissions:
278  contents: read
279  actions: read
280
281concurrency:
282  group: deploy-production
283  cancel-in-progress: false
284
285env:
286  SITE_URL: "https://CHANGE-ME.example.com"
287
288jobs:
289  deploy:
290    if: >
291      github.event.workflow_run.conclusion == 'success' &&
292      github.event.workflow_run.head_branch == 'main'
293    runs-on: ubuntu-22.04
294    environment: production
295    steps:
296      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
297        with:
298          name: deploy-meta
299          github-token: ${{ secrets.GITHUB_TOKEN }}
300          run-id: ${{ github.event.workflow_run.id }}
301          path: deploy-meta
302      # Placeholder deploy step — bigpowers ships no deploy templates and pins
303      # no third-party action. Substitute your platform's own step here, or drop
304      # the deploy job entirely for CLI and library repos. Pin whatever action
305      # you choose to a full commit SHA rather than a tag. (GH #104)
306      - name: Deploy
307        run: |
308          echo "Replace this step with your platform's deploy command."
309          echo "commit=$(jq -r .sha deploy-meta/deploy-meta.json)"
310          exit 1
311      - name: Health check
312        run: |
313          curl -sf "${{ env.SITE_URL }}" || exit 1
314```
315 
316---
317 
318## Reference block 3 — CLI dogfood (big-release pattern)
319 
320```yaml
321  build:
322    needs: [test]
323    steps:
324      - run: make build
325      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
326        with:
327          name: big-release-${{ github.sha }}
328          path: bin/big-release
329
330  release:
331    needs: [build]
332    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
333    steps:
334      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
335        with:
336          name: big-release-${{ github.sha }}
337          path: bin
338      - run: make release   # cross-compile assets only; host binary from artifact
339      - run: big-release release --verbose
340```
341 
342No `deploy.yml` — CLI publishes via the release job.
343 
344---
345 
346## Reference block 4 — validate script
347 
348```bash
349for f in .github/workflows/*.yml .github/workflows/*.yaml; do
350  [ -f &quot;$f&quot; ] || continue
351  python3 -c &quot;import yaml; yaml.safe_load(open('$f'))&quot; || echo &quot;FAIL: $f has YAML syntax errors&quot;
352done
353
354for f in .github/workflows/test-build-release.yml; do
355  if grep -q &quot;permissions:&quot; &quot;$f&quot;; then
356    echo &quot;OK: $f has permissions block&quot;
357  else
358    echo &quot;WARNING: $f missing permissions block&quot;
359  fi
360done
361
362if grep -q 'workflows: \["Test Build Release"\]' .github/workflows/deploy.yml 2&gt;/dev/null; then
363  if ! grep -q 'name: Test Build Release' .github/workflows/test-build-release.yml; then
364    echo &quot;WARNING: deploy.yml listens for Test Build Release but TBR name may differ&quot;
365  fi
366fi
367```
368 
369---
370 
371## Reference block 5 — dry-run
372 
373```bash
374if command -v act &amp;&gt;/dev/null; then
375  act push --dry-run -W .github/workflows/test-build-release.yml
376elif command -v gh &amp;&gt;/dev/null; then
377  gh workflow run test-build-release.yml --ref &quot;$(git branch --show-current)&quot;
378else
379  echo &quot;Install act or gh for dry-run&quot;
380fi
381```
382