universal-dev-standards 5.1.1 → 5.3.0

package/bundled/skills/deploy-assistant/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: deploy
+scope: universal
+description: |
+  Guide reliable deployments without CI/CD platforms (GitHub Actions / GitLab CI).
+  Use when: deploying to VPS, air-gapped servers, or environments without CI/CD infrastructure.
+  Keywords: deployment, no-cicd, shell script, blue-green, smoke test, rollback, 無CI/CD, 部署.
+allowed-tools: Read, Bash(cat VERSION:*), Bash(git describe:*), Bash(which nginx:*), Bash(which rsync:*)
+argument-hint: "[project type | 專案類型: node/python/docker/go]"
+---
+
+# No-CI/CD Deploy Assistant | 無 CI/CD 部署助手
+
+> **Language**: English | [繁體中文](../../locales/zh-TW/skills/deploy-assistant/SKILL.md)
+
+Guide reliable deployments in environments without GitHub Actions or GitLab CI, using a three-layer architecture: prevent errors, verify correctness, recover fast.
+
+引導無 CI/CD 平台環境下的可靠部署，採用三層架構：防錯、驗證、快速回復。
+
+## Three-Layer Architecture | 三層部署架構
+
+```
+Layer 1: Prevent Wrong Deployments   Layer 2: Verify Correctness   Layer 3: Fast Recovery
+  set -euo pipefail                    Smoke Test + /health           Blue-Green switching
+  Version tag enforcement              Version number comparison      rollback.sh < 30s
+  deploy.lock concurrency guard        Auto-rollback on failure
+```
+
+## Interactive Questionnaire | 引導式問答
+
+| Question | Options | Impact |
+|----------|---------|--------|
+| Project type | node / python / go / docker | Build command |
+| Deploy target | SSH+rsync / Docker Compose | Transfer method |
+| Blue-Green support | yes / no | rollback.sh generation |
+| Health check URL | URL input | verify.sh target |
+| Version source | VERSION file / package.json / git tag | Version comparison logic |
+
+## Generated Script Set | 生成的腳本組
+
+### deploy.sh — Main Deploy Script
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+LOCK_FILE="/tmp/deploy.lock"
+trap "rm -f $LOCK_FILE" EXIT
+
+# Concurrency guard | 防並發
+if [ -f "$LOCK_FILE" ]; then
+  echo "❌ Deploy in progress (PID: $(cat $LOCK_FILE))"
+  exit 1
+fi
+echo $$ > "$LOCK_FILE"
+
+# Version tag enforcement | 版本 tag 強制
+CURRENT_TAG=$(git describe --exact-match --tags HEAD 2>/dev/null || echo "")
+if [ -z "$CURRENT_TAG" ]; then
+  echo "❌ No version tag on HEAD. Run: git tag vX.Y.Z && git push --tags"
+  exit 1
+fi
+
+echo "[1/4] Running tests..."
+# {TEST_COMMAND}
+
+echo "[2/4] Building artifact..."
+# {BUILD_COMMAND}
+
+echo "[3/4] Syncing to server..."
+rsync -avz --delete ./dist/ {USER}@{SERVER}:/app/
+
+echo "[4/4] Verifying deployment..."
+./verify.sh || { echo "Verification failed, rolling back..."; ./rollback.sh; exit 1; }
+
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"version\":\"$CURRENT_TAG\",\"operator\":\"$(whoami)\",\"result\":\"success\"}" >> /var/log/deployments.jsonl
+echo "✅ Deploy successful: $CURRENT_TAG"
+```
+
+### verify.sh — Smoke Test
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+HEALTH_URL="${HEALTH_URL:-{HEALTH_URL}}"
+EXPECTED_VERSION=$(cat VERSION)
+
+for i in $(seq 1 3); do
+  RESPONSE=$(curl -sf --max-time 10 "$HEALTH_URL" 2>/dev/null) && break
+  echo "Health check attempt $i/3 failed, retrying in 5s..."
+  sleep 5
+done
+
+ACTUAL_VERSION=$(echo "$RESPONSE" | python3 -c "import json,sys; print(json.load(sys.stdin)['version'])")
+
+if [ "$ACTUAL_VERSION" != "$EXPECTED_VERSION" ]; then
+  echo "❌ Version mismatch! Expected $EXPECTED_VERSION, got $ACTUAL_VERSION"
+  exit 1
+fi
+
+echo "✅ Version verified: $ACTUAL_VERSION"
+```
+
+### rollback.sh — Blue-Green Rollback
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+CURRENT=$(readlink /app/current 2>/dev/null || echo "/app/blue")
+TARGET=$([[ "$CURRENT" == *"green"* ]] && echo "/app/blue" || echo "/app/green")
+
+ln -sfn "$TARGET" /app/current
+nginx -s reload
+
+echo "✅ Rolled back to $TARGET ($(date -u +%Y-%m-%dT%H:%M:%SZ))"
+echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"rollback\",\"from\":\"$CURRENT\",\"to\":\"$TARGET\",\"operator\":\"$(whoami)\"}" >> /var/log/deployments.jsonl
+```
+
+### Makefile
+
+```makefile
+.PHONY: deploy rollback verify status
+
+deploy:
+	@./deploy.sh
+
+rollback:
+	@./rollback.sh
+
+verify:
+	@./verify.sh
+
+status:
+	@echo "Current slot: $$(readlink /app/current 2>/dev/null || echo 'N/A')"
+	@curl -s $${HEALTH_URL:-http://localhost/health} | python3 -m json.tool 2>/dev/null || echo "Health check failed"
+```
+
+## Output Checklist | 輸出確認清單
+
+After generation, AI assistant must confirm:
+
+- [ ] `deploy.sh` includes `set -euo pipefail`
+- [ ] `deploy.sh` includes deploy.lock concurrency guard
+- [ ] `verify.sh` compares version number (not just HTTP 200)
+- [ ] `rollback.sh` triggers automatically on verify failure
+- [ ] `Makefile` provides `make deploy / make rollback / make status`
+
+## Usage | 使用方式
+
+```bash
+/deploy              # Interactive mode — auto-detect project type
+/deploy node         # Node.js project, generate directly
+/deploy docker       # Docker Compose deploy mode
+/deploy --verify-only  # Generate verify.sh only
+```
+
+## Next Steps Guidance | 下一步引導
+
+After `/deploy` completes, the AI assistant should suggest:
+
+> **Deploy scripts generated. Suggested next steps / 部署腳本已生成，建議下一步：**
+> - `chmod +x deploy.sh verify.sh rollback.sh` — Set executable permissions | 設定執行權限
+> - `make verify` — Test health check configuration | 測試健康檢查設定
+> - `git tag v1.0.0 && git push --tags` — Create version tag | 建立版本 tag
+> - `make deploy` — First deployment | 執行第一次部署
+
+## Reference | 參考
+
+- Core standard: [no-cicd-deployment.md](../../core/no-cicd-deployment.md)
+- Core standard: [deployment-standards.md](../../core/deployment-standards.md)
+- Related: [ci-cd-assistant](../ci-cd-assistant/SKILL.md) — For environments WITH CI/CD
+
+## Version History | 版本歷史
+
+| Version | Date | Changes | 變更說明 |
+|---------|------|---------|----------|
+| 1.0.0 | 2026-04-26 | Initial release — XSPEC-085 Phase 1b | 初始版本 |
+
+## License | 授權
+
+CC BY 4.0 — Documentation content

package/bundled/skills/push/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: push
+scope: universal
+description: |
+  AI-assisted safety layer for git push operations with quality gates and collaboration guardrails.
+  Use when: pushing commits, force pushing, pushing to protected branches, pushing feature branches.
+  Keywords: git push, force push, protected branch, quality gate, push receipt, PR automation, 推送, 保護分支, 品質閘門.
+allowed-tools: Read, Bash(git:*), Bash(npm:*), Bash(pnpm:*), Bash(yarn:*), Bash(bun:*)
+argument-hint: "[--force] [--target <branch>] [--skip-gates] [--no-pr]"
+---
+
+# Push Assistant | 推送助手
+
+> **Language**: English | 繁體中文
+
+**Version**: 1.0.0
+**Created**: 2026-04-23
+**Applicability**: Claude Code Skills
+
+---
+
+AI-assisted safety layer for `git push`. Detects protected branches, enforces force-push guardrails, runs pre-push quality gates, outputs a structured push receipt, and integrates with PR automation.
+
+`git push` 的 AI 輔助安全層。偵測保護分支、強制 force-push 護欄、執行 pre-push 品質 gate、輸出結構化推送收據，並整合 PR 自動化。
+
+## Core Standard | 核心標準
+
+This skill implements [`.standards/push-standards.ai.yaml`](../../.standards/push-standards.ai.yaml).
+
+---
+
+## Features | 功能說明
+
+### 1. Push Target Risk Detection | 推送目標風險偵測
+
+Before pushing, the assistant detects whether the target branch is a protected branch (e.g., `main`, `master`, `release/*`, `hotfix/*`).
+
+推送前偵測目標分支是否為保護分支（例如 `main`、`master`、`release/*`、`hotfix/*`）。
+
+- Displays a **warning** with branch name and commit list
+- Requires explicit user confirmation before proceeding
+- Aborts push if user does not confirm
+
+### 2. Force-Push Guardrails | Force-Push 護欄
+
+When `--force` is detected, shows the impact before allowing execution.
+
+偵測到 `--force` 時，推送前顯示影響範圍。
+
+- Calculates commits that will be overwritten on remote
+- Shows count and authors of overwritten commits
+- Requires user to type a confirmation string (`yes, force push`)
+- Records `force_push: true` in the push receipt
+
+### 3. Pre-Push Quality Gates | Pre-Push 品質 Gate
+
+Runs configured quality gates in sequence before pushing.
+
+推送前依序執行已設定的品質 gate。
+
+| Gate | Description | 說明 |
+|------|-------------|------|
+| `lint` | Run project lint command | 執行 lint 檢查 |
+| `test` | Run project test command | 執行測試 |
+| `type-check` | TypeScript type checking (optional) | TypeScript 型別檢查（選用） |
+| `ac-coverage` | Acceptance criteria coverage check (optional) | AC 覆蓋率檢查（選用） |
+| `security-scan` | Security vulnerability scan (optional) | 安全掃描（選用） |
+
+### 4. Push Receipt | 推送收據
+
+After a successful push, outputs a structured receipt for audit trail purposes.
+
+推送成功後輸出結構化收據，供稽核追蹤使用。
+
+```json
+{
+  "branch": "feature/my-feature",
+  "commit_sha": "a1b2c3d",
+  "gates_passed": ["lint", "test"],
+  "gates_skipped": false,
+  "force_push": false,
+  "timestamp": "2026-04-23T10:00:00Z",
+  "target_remote": "origin"
+}
+```
+
+Optionally appended to `~/.uds/push-history.jsonl` for persistent audit trail.
+
+可選擇附加到 `~/.uds/push-history.jsonl` 以持久化稽核追蹤。
+
+### 5. PR Automation Integration | PR 自動化整合入口
+
+After pushing a feature branch, prompts user to create a Pull Request if none exists.
+
+推送 feature branch 後，若尚無 PR，提示使用者建立 Pull Request。
+
+- Checks if an open PR exists for the branch
+- Prompts user to run `pr-automation-assistant`
+- Skipped in `single-owner` repo mode or when `--no-pr` flag is used
+
+---
+
+## Usage | 使用方式
+
+```bash
+# Standard push (runs quality gates automatically)
+/push
+
+# Push with force (shows overwritten commits, requires confirmation)
+/push --force
+
+# Push to a specific remote branch
+/push --target main
+
+# Skip quality gates (emergency use)
+/push --skip-gates
+
+# Push without PR prompt
+/push --no-pr
+
+# Force push without PR prompt (e.g., updating a personal branch)
+/push --force --no-pr
+```
+
+## Arguments | 參數說明
+
+| Argument | Description | 說明 |
+|----------|-------------|------|
+| `--force` | Enable force push with guardrail checks | 啟用 force push，含護欄確認 |
+| `--target <branch>` | Specify target remote branch explicitly | 明確指定目標遠端分支 |
+| `--skip-gates` | Skip pre-push quality gates (emergency only) | 跳過品質 gate（僅緊急情況） |
+| `--no-pr` | Suppress PR automation prompt after push | 推送後不提示建立 PR |
+
+---
+
+## Configuration | 設定
+
+Configure via `uds.project.yaml`:
+
+```yaml
+push:
+  repo_mode: team           # "team" | "single-owner"
+  protected_branches:
+    - main
+    - master
+    - "release/*"
+    - "hotfix/*"
+  push_gates:
+    default:
+      - lint
+      - test
+    optional:
+      - type-check
+      - ac-coverage
+      - security-scan
+  receipt:
+    output: console          # "console" | "file" | "both"
+    file_path: "~/.uds/push-history.jsonl"
+  auto_pr: true              # prompt to create PR after push to non-protected branch
+```
+
+### Options | 選項模式
+
+| Option File | Mode | Description | 說明 |
+|-------------|------|-------------|------|
+| [`options/push/team-mode.md`](../../options/push/team-mode.md) | `team` | Full collaboration guardrails (default) | 完整協作護欄（預設） |
+| [`options/push/single-owner-mode.md`](../../options/push/single-owner-mode.md) | `single-owner` | Reduced friction for personal repos | 個人 repo 低摩擦模式 |
+
+---
+
+## Next Steps Guidance | 下一步引導
+
+After `/push` completes, the AI assistant should suggest:
+
+> **推送完成。建議下一步 / Push complete. Suggested next steps:**
+> - 執行 `/pr-automation-assistant` 建立或更新 Pull Request ⭐ **Recommended / 推薦** — 確保協作流程完整 / Ensure complete collaboration workflow
+> - 執行 `/checkin` 確認程式碼簽入品質 — 下次提交前的品質確認 / Quality verification before next commit
+> - 查看 `~/.uds/push-history.jsonl` 確認推送紀錄 — 稽核追蹤 / Audit trail verification
+
+---
+
+## Related Standards | 相關標準
+
+- [Push Standards](.standards/push-standards.ai.yaml) — Core push safety rules
+- [Git Workflow](../../.standards/git-workflow.ai.yaml) — Branching strategy
+- [Commit Message](../../.standards/commit-message.ai.yaml) — Commit conventions
+- [PR Automation](../pr-automation-assistant/SKILL.md) — Pull Request automation
+
+---
+
+## Version History | 版本歷程
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-04-23 | Initial release — XSPEC-081 Phase 1 |
+
+---
+
+## License | 授權
+
+This skill is released under [MIT License](https://opensource.org/licenses/MIT) and [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "5.1.1",
+  "version": "5.3.0",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",

package/src/config/ai-agent-paths.js

@@ -2,7 +2,6 @@
  * AI Agent Paths Configuration
  *
  * Centralized configuration for all supported AI coding assistants.
- * Based on docs/AI-AGENT-ROADMAP.md specifications.
  *
  * @version 1.0.0
  */

package/standards-registry.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "5.1.1",
+  "version": "5.3.0",
   "lastUpdated": "2026-04-16",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
@@ -58,14 +58,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "5.1.1"
+      "version": "5.3.0"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills",
-      "version": "5.1.1",
+      "version": "5.3.0",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -704,6 +704,17 @@
       "skillName": "ai-collaboration-standards",
       "description": "Guidelines for AI collaboration to prevent hallucination and ensure evidence-based responses"
     },
+    {
+      "id": "agent-behavior-discipline",
+      "name": "Agent Behavior Discipline",
+      "nameZh": "Agent 行為紀律標準",
+      "source": {
+        "human": "core/agent-behavior-discipline.md",
+        "ai": "ai/standards/agent-behavior-discipline.ai.yaml"
+      },
+      "category": "core",
+      "description": "Four behavioral disciplines for AI agents: Ask (surface assumptions), Simple (minimum code), Precision (scope only what's needed), Test (loop until verified)"
+    },
     {
       "id": "ai-friendly-architecture",
       "name": "AI-Friendly Architecture",
@@ -2051,6 +2062,62 @@
       },
       "category": "core",
       "description": "MISSING vs OUTDATED distinction, semver-aware severity (PATCH/MINOR/MAJOR), and automation integration (pre-commit hook, release gate) for multi-locale documentation"
+    },
+    {
+      "id": "push-standards",
+      "name": "Git Push Safety Gates",
+      "nameZh": "Git Push 安全閘門標準",
+      "source": {
+        "human": "skills/push/SKILL.md",
+        "ai": "ai/standards/push-standards.ai.yaml"
+      },
+      "category": "skill",
+      "skillName": "push",
+      "description": "Git push safety gates, protected branch detection, force-push guardrails, pre-push quality gate enforcement, and push receipt audit trail"
+    },
+    {
+      "id": "no-cicd-deployment",
+      "name": "No-CI/CD Deployment Strategy",
+      "nameZh": "無 CI/CD 部署策略",
+      "source": {
+        "human": "core/no-cicd-deployment.md",
+        "ai": "ai/standards/no-cicd-deployment.ai.yaml"
+      },
+      "category": "core",
+      "description": "Reliable deployment strategy without CI/CD platforms: shell scripts with fail-fast, smoke test verification, Blue-Green rollback"
+    },
+    {
+      "id": "rollback-standards",
+      "name": "Rollback Standards",
+      "nameZh": "回滾標準",
+      "source": {
+        "human": "core/rollback-standards.md",
+        "ai": "ai/standards/rollback-standards.ai.yaml"
+      },
+      "category": "core",
+      "description": "Rollback trigger conditions, auto vs manual decisions, and error budget integration"
+    },
+    {
+      "id": "cd-deployment-strategies",
+      "name": "CD Deployment Strategies",
+      "nameZh": "CD 部署策略",
+      "source": {
+        "human": "core/cd-deployment-strategies.md",
+        "ai": "ai/standards/cd-deployment-strategies.ai.yaml"
+      },
+      "category": "core",
+      "description": "Strategy selection matrix for blue-green, canary, rolling, and recreate deployments"
+    },
+    {
+      "id": "pipeline-security-gates",
+      "name": "Pipeline Security Gates",
+      "nameZh": "CI Pipeline 安全閘門",
+      "source": {
+        "human": "core/pipeline-security-gates.md",
+        "ai": "ai/standards/pipeline-security-gates.ai.yaml"
+      },
+      "category": "core",
+      "description": "Security checkpoints embedded in CI pipeline — SAST, DAST, SCA, secrets scan with block/warn/log behavior"
     }
   ]
-}
+}