@neikyun/ciel 6.11.2 → 6.13.0

package/assets/skills/utility/branch-cleaner/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: branch-cleaner
+description: Deletes merged branches safely — `git branch --merged` for locals, `git fetch --prune` for stale tracking refs, opt-in `git push origin --delete` per-branch confirm. Excludes main/master/develop + current. Invoke post-merge, on "clean up branches", or when >20 stale branches. Inline.
+allowed-tools: Bash
+context: inline
+---
+
+# branch-cleaner — Delete merged, keep history tidy
+
+Local + remote branches accumulate silently. After 3 months, `git branch` shows 40+ old branches, most of them merged. This skill deletes safely.
+
+---
+
+## Inputs
+
+```
+BASE_BRANCH: [default: origin's default branch — main/master]
+REMOTE_CLEANUP: [true | false — default false; requires explicit confirmation for remote deletes]
+PROTECTED: [comma-separated list — default: main,master,develop,release/*]
+DRY_RUN: [true | false — default true on first invocation; shows what would be deleted]
+```
+
+### Auto-inference sources
+
+- **BASE_BRANCH** → `git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'`
+- **Current branch** → always protected (cannot delete the branch you're on)
+
+---
+
+## Preflight
+
+```bash
+git rev-parse --git-dir > /dev/null 2>&1 || { echo "Not a git repo"; exit 1; }
+
+# Don't run with dirty tree — in case user is in the middle of something
+git status --porcelain | grep -q . && { echo "Working tree dirty — commit or stash first"; exit 1; }
+
+# Fetch to get fresh remote state
+git fetch --all --prune --quiet
+```
+
+`--prune` already removes stale remote-tracking refs (remotes of branches deleted on origin).
+
+---
+
+## Process
+
+### 1. Identify merged local branches
+
+```bash
+BASE=${BASE_BRANCH:-$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')}
+CURRENT=$(git rev-parse --abbrev-ref HEAD)
+
+# Branches merged into BASE, excluding protected
+MERGED=$(git branch --merged "origin/$BASE" --format='%(refname:short)' \
+  | grep -vE "^(main|master|develop|${CURRENT}|release/.*)$" \
+  | grep -v "^\*")
+```
+
+`git branch --merged` is safer than `--no-merged`: only shows branches whose tip commit is reachable from BASE.
+
+**Caveat**: squash-merged PRs are NOT detected by `--merged` (the commit SHA is different). For these, use the PR-title heuristic:
+
+```bash
+# Branches that match a closed-merged PR title
+CLOSED_PRS=$(gh pr list --state=closed --search "is:merged" --limit=100 --json headRefName --jq '.[].headRefName')
+for BRANCH in $(git branch --format='%(refname:short)' | grep -v "^\*"); do
+  echo "$CLOSED_PRS" | grep -qx "$BRANCH" && SQUASH_MERGED+=("$BRANCH")
+done
+```
+
+### 2. Show what would be deleted (DRY_RUN)
+
+```
+[BRANCH CLEANER — DRY RUN]
+
+Local branches merged into origin/$BASE:
+  - fix/1042-library-update     (last commit: 2026-03-15, 4 weeks ago)
+  - feat/1055-new-endpoint      (last commit: 2026-04-02, 2 weeks ago)
+
+Squash-merged (by PR title match):
+  - fix/1048-typo               (PR #1048 closed 2026-04-10)
+
+Protected (not deleted):
+  - main, master, develop, release/2026-q2
+  - <current: your current branch>
+
+Remote branches fully merged (would delete with REMOTE_CLEANUP=true):
+  - origin/fix/1042-library-update
+  - origin/fix/1048-typo
+
+To proceed: re-run with DRY_RUN=false
+```
+
+### 3. Delete local branches (on user confirmation)
+
+```bash
+for B in $MERGED $SQUASH_MERGED; do
+  git branch -d "$B" 2>&1 || {
+    # -d refuses if upstream diverged; confirm before -D
+    if [ -n "$ASSUME_YES" ]; then
+      if [ "$ASSUME_YES" = "force" ]; then
+        git branch -D "$B"
+      else
+        echo "Branch '$B' not fully merged; skipping (set ASSUME_YES=force to force-delete)"
+      fi
+    else
+      echo "Branch '$B' not fully merged per -d — use -D? [y/N]"
+      read CONFIRM
+      [ "$CONFIRM" = "y" ] && git branch -D "$B"
+    fi
+  }
+done
+```
+
+`-d` is the safe delete (requires merged). `-D` force-deletes — only use after explicit confirmation.
+
+### 4. Delete remote branches (only if REMOTE_CLEANUP=true)
+
+```bash
+if [ "$REMOTE_CLEANUP" = "true" ]; then
+  for B in $MERGED $SQUASH_MERGED; do
+    # Only if remote branch still exists
+    git ls-remote --exit-code origin "$B" > /dev/null 2>&1 || continue
+
+    echo "Delete origin/$B? [y/N]"
+    read CONFIRM
+    [ "$CONFIRM" = "y" ] && git push origin --delete "$B"
+  done
+fi
+```
+
+### 5. Prune remote-tracking refs (already done in preflight, re-run for safety)
+
+```bash
+git remote prune origin
+```
+
+### 6. Emit summary
+
+```
+[BRANCH CLEANED]
+Local deleted: <N> branches
+Remote deleted: <N> branches (skipped if REMOTE_CLEANUP=false)
+Remote-tracking pruned: <N> refs
+Branches remaining: <N> local / <N> remote
+
+Protected (untouched): main, master, develop, <current>, release/*
+```
+
+---
+
+## Guardrails
+
+- **DRY_RUN by default on first call** — show before delete. Second call with DRY_RUN=false actually deletes.
+- **Never delete the current branch** — `git branch -d` would fail anyway; bail early.
+- **Never delete protected branches** — hard-coded: main, master, develop, release/*. Add repo-specific via `.ciel-protected-branches` (one branch per line).
+- **Squash-merge detection is heuristic** — a branch name matching a closed-merged PR isn't proof of merge (someone could have renamed + re-used). Confirm per branch in non-dry mode.
+- **Remote deletes require REMOTE_CLEANUP=true** — two opt-ins (flag + per-branch confirm) before touching origin.
+- **Force-delete `-D` requires per-branch confirm** — don't silently `-D`. Diverged branches might hold unpushed work.
+- **Backup via `git reflog`** — informative only; `git reflog` keeps deleted commits for 90 days. Mention this before force-delete so user knows recovery exists.
+- **Never `git push --force` in this skill** — deletion is `--delete`, not force.
+- **Respect in-progress work** — preflight dirty-tree check prevents deleting branches while user is switching contexts.
+
+---
+
+## When triggered
+
+- Post-merge handoff from `pr-merger` (after `issue-closer`)
+- `meta-critiquer` item 4 "Stale branches?" when count > 20
+- User says: "clean up branches", "delete merged", "prune stale"
+- Session end when `git branch | wc -l` is high and user confirms cleanup
+
+---
+
+## Anti-pattern
+
+```
+❌ git branch -D $(git branch | grep -v main)     # nukes everything including unmerged work
+✅ git branch -d <merged-only>                    # safe, refuses diverged
+```
+
+```
+❌ git push origin --delete $(git branch -r)      # deletes remote branches blind
+✅ Per-branch confirm with REMOTE_CLEANUP flag
+```
+
+---
+
+## References
+
+- `git branch --merged` — git-scm.com/docs/git-branch
+- `git fetch --prune` — git-scm.com/docs/git-fetch
+- `git reflog` (recovery) — git-scm.com/docs/git-reflog
+- Ciel pipeline: pr-merger → issue-closer → branch-cleaner → (changelog-updater | release-publisher)

package/assets/skills/utility/branch-setup/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: branch-setup
+description: Creates a git branch named with Ciel's convention — `fix/<issue-number>-<slug>` for bug fixes, `feat/<issue-number>-<slug>` for features. Verifies clean working tree first. Records branch as work context so commit-writer adds `Refs #<issue>` footers. Inline — fast git commands, no fork needed.
+allowed-tools: Bash
+context: inline
+---
+
+# branch-setup — Branch name as audit trail
+
+## What this covers
+Naming the branch after the issue makes traceability automatic — GitHub auto-links, reviewers see the reason, the history tells the story.
+
+## Core principle
+**Every branch traces to an issue. No orphan branches.** The branch name IS the audit trail.
+
+## Inputs
+
+```
+ISSUE_NUMBER: [e.g., "123" — from issue-creator OR explicit user reference]
+TITLE_SLUG: [kebab-case short description, ≤ 40 chars]
+TYPE: [fix | feat | chore | docs | refactor | test | perf]
+BASE_BRANCH: [usually "main" — override if working off release/*]
+```
+
+### Auto-inference sources
+
+- **ISSUE_NUMBER** → from `issue-creator` output, or parse `#N` from user prompt, or from `gh issue view`
+- **TITLE_SLUG** → from issue title, lowercase, keep first 4-5 meaningful words, kebab-case
+- **TYPE** → infer from issue labels: `bug` → `fix`, `enhancement` → `feat`, else `chore`
+- **BASE_BRANCH** → `git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'`
+
+## Preflight
+
+```bash
+# 1. Working tree is clean
+git status --porcelain | grep -q . && { echo "Working tree dirty — stash or commit first"; exit 1; }
+
+# 2. We're in a git repo
+git rev-parse --git-dir > /dev/null 2>&1 || { echo "Not a git repo"; exit 1; }
+
+# 3. Base branch is reachable
+git rev-parse --verify "origin/$BASE_BRANCH" > /dev/null 2>&1 || { echo "Base branch $BASE_BRANCH not found on origin"; exit 1; }
+```
+
+If dirty, offer 3 options:
+1. Stash (`git stash push -m "ciel pre-branch stash"`)
+2. Commit to current branch first (user's call)
+3. Abort
+
+## Process
+
+### 1. Compute branch name
+
+```bash
+BRANCH_NAME="${TYPE}/${ISSUE_NUMBER}-${TITLE_SLUG}"
+# Example: fix/1042-library-update-db-timeout
+```
+
+Validate:
+- ≤ 80 chars total (many git hosts truncate)
+- Only `[a-z0-9/-]` (no uppercase, no underscore, no special)
+- Not already exists locally OR remotely
+
+```bash
+git rev-parse --verify "$BRANCH_NAME" 2>/dev/null && { echo "Branch exists locally — checkout instead?"; exit 1; }
+git ls-remote --exit-code origin "$BRANCH_NAME" && { echo "Branch exists on origin — checkout instead?"; exit 1; }
+```
+
+### 2. Create + checkout from fresh base
+
+```bash
+git fetch origin "$BASE_BRANCH" --quiet
+git checkout -b "$BRANCH_NAME" "origin/$BASE_BRANCH"
+```
+
+### 3. Record the work context
+
+Write to `.git/ciel-work-context` (local, not committed):
+
+```
+ISSUE: #<N>
+BRANCH: <branch>
+TYPE: <type>
+STARTED: <ISO timestamp>
+BASE: <base branch>
+```
+
+### 4. Emit output
+
+```
+[BRANCH CREATED]
+Name: fix/1042-library-update-db-timeout
+From: origin/main (SHA <short>)
+Issue: #1042
+Work context recorded.
+```
+
+## Common patterns
+
+### Good branch names
+
+```
+fix/342-null-pointer-auth-login
+feat/567-user-avatar-upload
+chore/890-update-ci-node-version
+refactor/123-extract-payment-service
+```
+
+### Bad branch names
+
+```
+myfix                          # no type, no issue
+fix/library-timeout            # no issue number
+feature/add-the-thing-with-all-the-details  # way too long
+FIX/123-UPPERCASE              # uppercase breaks some tools
+```
+
+## Anti-patterns
+
+- `git checkout -b myfix` → no issue link, no type prefix, untraceable
+- Working directly on `main` → violates every workflow — Ciel refuses and forces branching
+- `git checkout -b fix/library-timeout` without issue number → enforce the `#N` prefix
+- Branching from stale local `main` → always fetch + branch from `origin/main`
+- Branch names > 80 chars → GitHub truncates, CI tools break
+
+## How to verify
+
+- [ ] Branch name matches `<type>/<N>-<slug>` pattern? (`git branch --show-current | grep -E '^[a-z]+/[0-9]+-'`)
+- [ ] ≤ 80 chars total? (`git branch --show-current | wc -c` ≤ 81)
+- [ ] Working tree clean before branch? (preflight passed)
+- [ ] Branched from `origin/<base>`, not stale local? (`git log --oneline -1 origin/main` matches recent)
+- [ ] `.git/ciel-work-context` written with ISSUE + BRANCH + TYPE?
+
+## When triggered
+
+- Right after `issue-creator` returns a number
+- User says "start working on issue #N"
+- Beginning of FAIRE step when depth is Standard/Critical AND an issue exists
+
+## References
+
+- Conventional branches — conventional-branch.org
+- Conventional commits — conventionalcommits.org
+- Ciel pipeline: issue-creator → branch-setup → FAIRE → commit-writer → pr-opener → issue-closer

package/assets/skills/utility/changelog-updater/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: changelog-updater
+description: Appends a versioned entry to CHANGELOG.md following Keep-a-Changelog format, with Added/Changed/Fixed/Removed sections and fix/revert ratio metric when available. Auto-triggered by version bumps or when /ciel-improve adopts new skill variants.
+allowed-tools: Read, Bash
+---
+
+# changelog-updater — Structured version history
+
+## What this covers
+Keeps `CHANGELOG.md` up to date with a consistent format. The changelog is the project's public-facing history — every user and contributor reads it.
+
+## Core principle
+**Changelog is append-only history.** Never rewrite old entries. Each new entry answers: "What changed since last release, and why should I care?"
+
+## Inputs
+
+- **version**: new version number (semver)
+- **date**: release date (YYYY-MM-DD)
+- **changes**: structured changes — added / changed / fixed / removed / security
+- **metric** (optional): fix/revert ratio measured since last release
+
+## Process
+
+### 1. Read current CHANGELOG.md
+
+Confirm format. If the file follows Keep-a-Changelog structure, preserve it. If not, migrate to that structure.
+
+### 2. Compose new entry
+
+```markdown
+## [<version>] — <YYYY-MM-DD>
+
+### Added
+- <new feature / skill / command>
+
+### Changed
+- <modified behavior / skill rewrite>
+
+### Fixed
+- <bug fix with reference>
+
+### Removed
+- <deprecated / removed>
+
+### Security
+- <security fix (CVE-like severity)>
+
+### Metrics
+- Fix/revert ratio: <X%> (baseline v<prev>: <Y%>)
+```
+
+Omit sections that have no entries.
+
+### 3. Insert at top (most recent first)
+
+After any header/preamble, before previous version entries.
+
+### 4. Preserve previous entries
+
+Never rewrite old entries — append only.
+
+## Common patterns
+
+### Good changelog entry
+
+```markdown
+## [3.5.0] — 2026-04-17
+
+### Added
+- `test-strategy-vitest-playwright` skill — 2026 test pyramid (70/20/10) with decision rules per test type
+- `playwright-visual-critic` skill — accessibility-first UI review using Playwright MCP
+
+### Changed
+- Skills refactored from pipeline steps to knowledge references (Phase 5 of v4.0.0 plan)
+- Agent frontmatter: added `model`, `memory`, `skills` preload fields
+
+### Fixed
+- Hook `session.deleted` renamed to `session.destroy` (OpenCode 0.4 breaking change)
+- Agent dispatch: removed stale `context: fork` from 3 workflow skills
+
+### Removed
+- Platform directories for Cursor, Windsurf, Codex, KiloCode, LMStudio, Ollama (unsupported)
+```
+
+### Bad changelog entry
+
+```markdown
+## update
+- fixed stuff
+- changed things
+- added new features
+```
+
+Problems: no version, no date, no specifics, sections not following Keep-a-Changelog.
+
+## Anti-patterns
+
+- **Rewriting old entries** — changelog is historical record, additive only
+- **Missing date** — every entry needs a `YYYY-MM-DD` date
+- **Vague descriptions** — "fixed bugs" says nothing. Link to issue: "fix: prevent N+1 query in dashboard (#567)"
+- **Missing breaking changes** — breaking changes must be prominent, in a separate section or with `!` marker
+- **Empty sections** — omit sections with no entries, don't leave empty headers
+- **Not linking to issues/PRs** — each entry should reference `#N` where possible
+
+## How to verify
+
+- [ ] Version follows semver? (`MAJOR.MINOR.PATCH`)
+- [ ] Date is ISO 8601? (`YYYY-MM-DD`)
+- [ ] Entry inserted at top (most recent first)?
+- [ ] Previous entries untouched?
+- [ ] Breaking changes highlighted (if any)?
+- [ ] Each entry references issue/PR number (where applicable)?
+- [ ] Sections follow Keep-a-Changelog names? (Added, Changed, Fixed, Removed, Security)
+
+## When triggered
+
+- Version bump (SHA change in `.version`)
+- After `/ciel-improve` adopts new skill variants
+- User request: "update changelog" / "release notes"
+- CI/CD pre-release step
+
+## References
+
+- Keep a Changelog v1.1.0 — keepachangelog.com
+- Semantic Versioning v2.0.0 — semver.org

package/assets/skills/utility/commit-writer/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: commit-writer
+description: Writes commit messages in conventional commit format (feat/fix/chore/docs/refactor/test/perf) with imperative mood, issue references, and warnings on secret files. Invoked before git commit. Short, structured, mechanical — for reviewer clarity and changelog automation.
+allowed-tools: Bash, Read
+---
+
+# commit-writer — Conventional commit messages
+
+## What this covers
+Ensures every commit is structured, informative, traceable to an issue, and free of secrets. The commit message is the first thing a reviewer reads — make it count.
+
+## Core principle
+**The commit message explains WHY, not WHAT.** The diff shows what changed. The message explains why it changed. "Fix null pointer in auth" is better than "Update auth.ts".
+
+## Methodology
+
+Reads from current git state:
+- `git status --porcelain` — staged files
+- `git diff --staged` — diff content
+- Optional: recent commit history for style matching
+
+### 1. Scan staged files — secrets gate
+
+Flag if any of:
+- `.env*` (not `.env.example`)
+- `credentials.*`, `secrets.*`, `*-keys.*`
+- Files > 10 MB (binary?)
+- `id_rsa`, `id_ed25519`, other SSH keys
+
+**Block immediately.** Do NOT commit secrets.
+
+### 2. Classify change type
+
+From diff content:
+- New feature (new endpoint / component / capability) → `feat`
+- Bug fix → `fix`
+- Build config / CI / dependencies → `chore` or `build`
+- Docs only → `docs`
+- Refactor (no behavior change) → `refactor`
+- Test only → `test`
+- Performance → `perf`
+- Breaking change → add `!` suffix: `feat!:` or include `BREAKING CHANGE:` in body
+
+### 3. Identify scope (optional)
+
+From top-level folder(s) changed: `feat(auth):`, `fix(users):`, `refactor(db):`.
+
+### 4. Write subject line
+
+- Imperative mood: "add" not "added", "fix" not "fixed"
+- ≤ 72 chars (hard limit — git log truncates beyond this)
+- No trailing period
+- Lowercase after type prefix
+
+### 5. Write body (optional)
+
+If non-trivial:
+- What changed (1-2 sentences)
+- Why (the rationale — the most important part)
+- Any side effects / migration notes
+
+### 6. Add issue reference
+
+If branch name matches pattern `<type>/<N>-<slug>` or an open issue is linked, add at the bottom:
+```
+Closes #<N>
+```
+
+## Output format
+
+```
+<type>(<scope>): <subject ≤72 chars>
+
+<body: what + why>
+
+Closes #<N>
+```
+
+## Common patterns
+
+### Good commits (before → after)
+
+```
+# Feature — clear scope, imperative, issue linked
+feat(auth): add OAuth2 PKCE flow for mobile clients
+
+Mobile apps can't safely store client secrets. PKCE eliminates
+the need by using a code verifier/challenge pair.
+
+Closes #342
+
+# Bug fix — explains the root cause, not just the symptom
+fix(db): prevent N+1 query in user dashboard endpoint
+
+The /dashboard endpoint was loading each user's posts in a
+separate query. Eager-load posts via JOIN to reduce 101 queries
+to 1.
+
+Closes #567
+
+# Chore — explains WHY the dependency was updated
+chore(deps): bump @auth/core from 3.1 to 4.0
+
+v4.0 fixes CVE-2026-1234 (session fixation). Breaking change:
+useSession() now returns null instead of throwing on expired
+tokens. Updated 3 call sites.
+```
+
+### Bad commits
+
+```
+# BAD — no type prefix, no scope, no issue
+update auth stuff
+
+# BAD — describes WHAT not WHY
+fix(users): change line 42 in users.ts
+
+# BAD — too vague, could be anything
+fix: bugs
+
+# BAD — past tense, trailing period, > 72 chars
+Fixed the authentication module to properly handle the case where users have expired tokens and the refresh flow fails silently.
+```
+
+## Anti-patterns
+
+- **"Update X"** — update is not a type. Use `fix`, `feat`, `refactor`, or `chore`.
+- **Past tense** — "added", "fixed", "changed" — use imperative: "add", "fix", "change".
+- **No issue reference on feat/fix** — every feature and bug fix should trace to an issue. If no issue exists, prompt user to create one first.
+- **Secrets in diff** — never commit `.env`, API keys, credentials. Block and warn.
+- **Squashing unrelated changes** — one logical change per commit. If you fixed a bug AND added a feature, make two commits.
+- **Bodyless non-trivial commits** — if the diff touches > 3 files or > 50 lines, write a body explaining why.
+
+## How to verify
+
+- [ ] Subject line ≤ 72 chars? (`echo "$SUBJECT" | wc -c` ≤ 73)
+- [ ] Starts with valid type prefix? (`feat|fix|chore|docs|refactor|test|perf|build|ci`)
+- [ ] Imperative mood? (not "added", "fixed", "changed")
+- [ ] No trailing period?
+- [ ] `feat`/`fix` commits have issue reference (`Closes #N` or `Refs #N`)?
+- [ ] No secrets in staged files? (check `.env`, `credentials.*`, `*-keys.*`)
+- [ ] Style matches recent commits? (`git log --oneline -5` for reference)
+
+## When triggered
+
+- Before `git commit`
+- User says "write a commit message for these changes"
+- In `/ciel` workflow at end of FAIRE before pushing
+
+## References
+
+- Conventional Commits v1.0.0 — conventionalcommits.org
+- Angular commit convention (widely adopted baseline) — github.com/angular/angular/blob/main/CONTRIBUTING.md
+- Ciel pipeline: FAIRE → commit-writer → push