Magi.web.ci.spec

/magi.web.ci.spec — CI/CD elaboration

You are the coordinator. Plan a CI/CD pipeline change and capture the analysis in docs/<num>-<slug>/CI.md. You never push to the workflow, trigger a deploy, or rotate a secret. Read references/domain/web/ci-cd.md before starting.

0. Preflight

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
[[ -z "$PLUGIN_ROOT" ]] && PLUGIN_ROOT="$(cd "$(dirname "$BASH_SOURCE[0]")/../.." 2>/dev/null && pwd)"
USER_CONFIG="$HOME/.config/magi-workflow-workflow/config.json"

If config missing → tell user to run /magi.setup.

0.5. State preflight (auto-refuse if not allowed)

STATE_JSON=$(bash "$PLUGIN_ROOT/scripts/shared/detect-state.sh")
blocked=$(jq -r '.disallowed_skills["magi.web.ci.spec"] // empty' <<<"$STATE_JSON")
if [[ -n "$blocked" ]]; then
  reason=$(jq -r '.disallowed_skills["magi.web.ci.spec"].reason' <<<"$STATE_JSON")
  suggest=$(jq -r '.disallowed_skills["magi.web.ci.spec"].suggest' <<<"$STATE_JSON")
  echo "Cannot run /magi.web.ci.spec: $reason"
  echo "Suggested: $suggest"
  exit 1
fi

--force skips preflight (advanced/recovery only).

1. Locate sprint + CI tool

Find the sprint folder (default: most recent; or --sprint <num>-<slug>).

Detect the CI tool per references/domain/web/ci-cd.md "Discovery":

• .github/workflows/*.yml → GitHub Actions
• cloudbuild.yaml / cloudbuild/*.yaml → Cloud Build
• .gitlab-ci.yml → GitLab CI
• azure-pipelines.yml → Azure DevOps
• Jenkinsfile → Jenkins
• vercel.json → Vercel
• wrangler.toml → Cloudflare

If multiple coexist (e.g. GHA for tests + Cloud Build for prod deploy), document the boundary explicitly.

2. Read existing pipeline + spec

• List existing workflow files; for each, summarise: trigger, stages, duration, last failure rate (if available via gh run list or gcloud builds list).
• Read PLAN/SPEC.md to understand what change is needed:
  • New tests added → wire them into test stage?
  • New deployable surface → new deploy job?
  • New secret needed → secret store + scoping plan?
  • Performance budget regression → add budget check?

3. Identify CI-relevant scope

Out-of-scope: pure code changes that don't touch the pipeline. Be honest if the user invoked this skill for something the existing pipeline already handles — recommend they skip this skill.

4. Generate the CI section

Following references/domain/web/ci-cd.md "Deliverable":

a. Triggers

on: push / pull_request / workflow_dispatch / schedule / tag. Justify each.

b. Stages & jobs

A table or list of stages (preflight / static / test / build / e2e / security / publish / deploy / smoke). For each:

• What runs?
• What artifacts are produced?
• What blocks the next stage?
• Approximate duration target (so regressions can be flagged later).

Use the templates in the reference for GHA / Cloud Build skeletons.

c. Secrets & permissions

• Which secrets does this change need?
• Where do they live? (GH Actions secrets / Secret Manager / Vault)
• Workload Identity Federation used? (preferred over key files)
• Token scope per job (permissions: in GHA).
• Rotation plan + owner.

Forbidden patterns to flag (echoing secrets, committing .env.*, service-account JSON keys when WIF is available, pull_request_target without input sanitisation): if any are proposed, mark 🔴 and push back.

d. Caching

• Cache keys (lockfile hashes; per-OS / per-language version).
• Cache size budget if the project has hit limits.
• Layer cache strategy for Docker (buildx --cache-from).

e. Deployment strategy

For deploy stages:

f. Smoke tests post-deploy

Required for any shared-env deploy. Use the curl + jq pattern from the reference. Document expected response shape.

g. Observability for the pipeline

• Workflow run summaries ($GITHUB_STEP_SUMMARY).
• Notifications: Slack / Chat — what triggers them, on which channel.
• DORA tracking: deploy frequency / lead time / change failure rate / MTTR (only if the team tracks these).

h. Test plan for the workflow itself

How will the user validate this change before merging?

• Draft PR run.
• act for GHA local sim.
• gcloud builds submit --config=... --no-source for Cloud Build dry-run.
• Diff the rendered config (gh workflow view, gcloud builds describe) against the previous version.

i. Open questions

5. Generate workflow draft

Based on the section above, generate a draft workflow file:

• GHA: docs/<num>-<slug>/.github/workflows/<name>.yml
• Cloud Build: docs/<num>-<slug>/cloudbuild-<name>.yaml
• etc.

The path is inside the doc dir so it does not pollute the project's real workflow directory until the user reviews and moves it.

Use the skeletons from the reference. Fill in concrete values from the project (Node version from .nvmrc, package manager from lockfile, etc.). Pin third-party actions to a specific SHA, not @v1.

6. Write CI.md

Use the deliverable template. Reference the draft workflow path.

7. Stop and hand off

Show the user:

• CI.md path
• Draft workflow path inside the sprint dir
• Top 3 risks (especially secret-handling concerns)
• Recommendation to test via act / draft PR / Cloud Build dry-run before moving the workflow to its real location.

Recommend next:

• Manual review of the draft workflow.
• /magi.review-plan to have other models inspect it.
• After review, user moves the file to its real location and opens a PR.

Never push the workflow to its live location, never trigger a build, never rotate a secret.

Argument parsing

• --sprint <num>-<slug> — explicit sprint folder.
• --ci gha|cloudbuild|gitlab|azure|jenkins|vercel|cloudflare — skip detection.
• --draft-name <name> — name for the draft workflow file.

Conventions

• Draft, not deploy — outputs land in the sprint dir, never the real workflow path.
• Pin third-party actions to SHA — never @vN or @main.
• Least privilege by default — permissions: contents: read baseline, raise per job.
• WIF over key files — push back hard on any service account JSON key proposal.
• Smoke tests are mandatory for shared-env deploys.
• For very small CI changes (e.g., bumping a Node version in matrix), this skill is overkill — recommend an inline edit to the existing workflow with manual review.