kitsune-den/skulk-skills/git-ritual

gitRitual: The Human Pattern Lab's Git Ceremony

Overview

The gitRitual is The Human Pattern Lab's ceremonial process for completing work sessions. It ensures all changes across repositories are properly committed with lore-coded messages, attributed to collaborators, and documented in PRs.

When to Trigger This Skill

Execute gitRitual when the user:

• Says "gitRitual", "git ritual", or references the ritual
• Says "let's wrap this up", "create PRs", "commit everything"
• Has completed work across multiple repos
• Asks for commit messages and PR descriptions
• References finishing a feature or work session

Start of Work: Branch Hygiene

Before any ritual phase runs, and before the first edit, file create, or code-changing command in a repo, run the three-step branch hygiene dance:

1. git checkout main
2. git pull (latest from origin)
3. git checkout -b <meaningful-branch-name>

Only then start editing.

Why: starting from whatever branch happens to be checked out risks branching off stale code, piling unrelated work into an existing feature branch, or creating merge mess later. Starting every change from fresh main with its own purpose-named branch keeps history clean and PRs focused on one thing each.

Branch naming: describe the change, not the author or date.

• Good: feat/hero-sticky-bg, cleanup/tracked-artifacts, fix/miso-panel-vhost, add/git-ritual-branch-hygiene, update/signature-system
• Bad: ada-work, patch-1, tmp, wip, new-stuff

One branch per intent. If the branch needs a second unrelated change, start a second branch. If in doubt, split. The discipline matters more than the ceremony.

Already on a feature branch from a previous task? Stop. Go back to main, pull, and branch again. Do not git checkout -b off a stale feature branch, it will compound the mess.

This rule applies to every repo the ritual touches, not just the "main" one. If a session ends up modifying three repos, each one gets its own three-step dance before its first edit.

The Ritual Steps

Phase 1: Assessment 🔍

Before starting, identify:

1. Which repos were touched?

• lab-api
• the-human-pattern-lab (frontend)
• the-human-pattern-lab-cli
• the-human-pattern-lab-content
• Other repos

1. What changed in each repo?

• List files modified
• Understand the scope of changes
• Note any breaking changes

1. What's the narrative?

• What was accomplished?
• How do the changes relate?
• What problem was solved?

Phase 2: Signature and Attribution 👥

CRITICAL: All commits must include the standard co-author trailer so AI collaboration is attributed at the git level, and every PR description must end with the pairing signature.

Commit trailer (on every commit, last line of the message, preceded by a blank line):

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Use this exact string. Capital letters in Co-Authored-By matter for some git tooling, and GitHub surfaces this trailer in the PR UI as a co-author avatar.

PR description footer (on every PR body, its own line, at the very end after test plan and related links):

Paired with Claude (Opus 4.6)

No emoji, no link, no "Generated with" language. "Paired with" reads honestly: the work is actually paired, Ada drives direction, Claude executes and suggests, the commits belong to both.

Voices vs. trailers: The Skulk has a narrative voice system (Sage, Lyric, Coda, Vesper) that still exists as lore and framing, and is an active concept in Koda's world and other Skulk projects. It is still useful for thinking about what kind of work is happening (architecture vs. creative content vs. QA vs. research) and for narrative prose like commit bodies that describe the shape of the work. But the actual git-level Co-authored-by: trailer is now Claude Opus 4.6, not a voice name. Keep voice language in prose where it helps; do not use Co-authored-by: Sage <sage@thehumanpatternlab.com> (or lyric@, coda@, vesper@) as the commit trailer. See the Voice Selection Guide further down for when voice framing still applies narratively.

Also: The default Claude Code footer 🤖 Generated with [Claude Code](https://claude.com/claude-code) should be swapped for Paired with Claude (Opus 4.6) on PR descriptions, release notes, and similar long-form artifacts.

Phase 3: Commit Messages 📝

For each repository, create lore-coded commit messages following The Human Pattern Lab system.

Commit Message Format

<emoji> <scope>: <subject>
 
<body>
 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Common Prefixes (The Lore-Coded System)

Engineering & Code (SCMS)

• ⚙️ feat: - New features
• 🐛 fix: - Bug fixes
• 🔧 refactor: - Code restructuring (no behavior change)
• ⚡ perf: - Performance improvements
• 🏗️ build: - Build system changes

Documentation & Knowledge (KROM)

• 📚 docs: - Documentation changes
• 📝 content: - Content updates
• 🎨 style: - Code style/formatting (no logic change)

Testing & Quality

• ✅ test: - Adding or updating tests
• 🧪 experiment: - Experimental features

Infrastructure

• 🚀 deploy: - Deployment changes
• 🔒 security: - Security improvements
• 🗄️ db: - Database migrations/schema changes

Domain-Specific

• 🌉 bridge: - Liminal Bridge system changes

Example Commits

Single-purpose change:

🐛 fix: Add missing .js extensions to CLI imports
 
TypeScript compiles .ts files but doesn't add .js extensions
to imports. Node.js ES Modules require explicit extensions.
 
Fixed imports in:
- src/contract/capabilities.ts
- src/commands/version.ts (package.json path)
 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Multi-part feature:

🌉 feat: Implement complete Liminal Bridge relay system
 
Add database schema, API endpoints, and admin UI for the
Liminal Bridge - enabling AI agents to post Lab Notes through
temporary, single-use relay URLs.
 
Changes:
- Add relay_sessions and bridge_posts tables
- Add relay generation and usage endpoints
- Add admin UI for relay management
- Rename from "Hallway Architecture" to "Liminal Bridge"
 
Tested end-to-end with successful relay creation and usage.
 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Documentation:

📚 docs: Add comprehensive style guide and quick reference
 
Create STYLE_GUIDE.md with detailed conventions for:
- Import rules (ES modules .js requirement)
- File structure and naming
- Commit message format (lore-coded)
- Common gotchas and debugging
 
Add QUICK_REFERENCE.md as one-page cheat sheet.
 
Add VS Code settings to auto-add .js extensions.
 
Prevents future ES module import issues and helps
onboard contributors (biological and digital).
 
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Phase 4: PR Descriptions 🎯

For each repository with changes, create a comprehensive PR description.

PR Template

## Summary
 
[One paragraph explaining what this PR does and why]
 
## Changes
 
### [Repo Name]
 
-[Change 1]
-[Change 2]
-[Change 3]
 
### [Another Repo if applicable]
 
-[Change 1]
-[Change 2]
 
## Testing
 
-[ ] [Test 1 performed]
-[ ] [Test 2 performed]
-[ ] [Test 3 performed]
 
## Breaking Changes
 
[List any breaking changes, or write "None"]
 
## Related
 
-Related to [issue/PR number]
-Closes [issue number]
-Depends on [PR in another repo]
 
## Screenshots/Examples
 
[If applicable, show before/after or demo]
 
## Checklist
 
-[ ] Code follows style guide
-[ ] All tests passing
-[ ] Documentation updated
-[ ] Commit messages follow lore-coded format
-[ ] Breaking changes documented
 
---
 
Paired with Claude (Opus 4.6)

Example PR Description

## Summary
 
Complete implementation of the Liminal Bridge relay system and comprehensive repository improvements. This PR adds the infrastructure for AI agents to post Lab Notes through temporary, single-use relay URLs, fixes critical ES module import issues in the CLI, and establishes style guides to prevent future issues.
 
## Changes
 
### lab-api
 
-🌉 Add `bridge_posts` table migration
-🌉 Wire `bridge_posts` migration into `bootstrapDb()`
-📚 Update RELAY_IMPLEMENTATION.md from "Hallway Architecture" to "Liminal Bridge"
-✅ Test relay endpoints end-to-end
 
### the-human-pattern-lab
 
-🌉 Update Admin Relays page to use "Liminal Bridge" terminology
-🎨 Change info box emoji from 🏛️ to 🌉
 
### the-human-pattern-lab-cli
 
-🐛 Fix missing .js extension in `capabilities.ts`
-🐛 Fix package.json path for compiled code
-📚 Add comprehensive STYLE_GUIDE.md
-📚 Add QUICK_REFERENCE.md cheat sheet
 
## Testing
 
-[x] CLI builds and installs successfully (`npm run build && npm install -g .`)
-[x] All CLI commands work (`hpl version`, `hpl capabilities`, `hpl health`)
-[x] Relay generation works (`POST /admin/relay/generate`)
-[x] Relay usage creates notes (`POST /relay/:relayId`)
-[x] Single-use enforcement works (second use returns ALREADY_USED)
-[x] Voice tags automatically applied (`vocal-sage` tag present)
-[x] Database tables created (`relay_sessions` and `bridge_posts`)
 
## Breaking Changes
 
None - all changes are additive or documentation-only.
 
## Related
 
-Completes Liminal Bridge implementation
-Fixes ES module import issues in CLI
-Establishes style guide to prevent future issues
 
## Database Schema
 
New tables added:

-- Relay credentials relay_sessions (id, voice, created_at, expires_at, used, used_at)

-- Posts flowing through bridge bridge_posts (id, content, voice, relay_session_id, created_at, posted_at, status)

 
## Examples
 
### Successful Relay Usage

Generate relay

curl -X POST http://localhost:8001/admin/relay/generate \ -H "Content-Type: application/json" \ -d '{"voice": "sage", "expires": "1h"}'

Use relay to post

curl -X POST http://localhost:8001/relay/relay_abc123 \ -H "Content-Type: application/json" \ -d '{"title": "Test Note", "content": "# Hello from Sage"}'

Response: {"success": true, "note_id": "...", "voice": "sage"}

 
## Checklist
 
- [x] Code follows style guide
- [x] All tests passing
- [x] Documentation updated
- [x] Commit messages follow lore-coded format
- [x] Breaking changes documented (none)
- [x] End-to-end testing completed
 
---
 
**The bridge exists, serves its purpose, and is working!** 🌉
 
Paired with Claude (Opus 4.6)

Phase 5: Execution 🚀

Step-by-Step Process

For each repository:

1. Review changes:

``bash cd /path/to/repo git status git diff ``

1. Stage changes:

``bash git add [files] # Or for everything: git add . ``

1. Commit with co-author:

```bash git commit -m "emoji scope: subject

Body paragraph explaining the change in detail.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>" ```

1. Push to branch:

``bash git push origin [branch-name] ``

1. Create PR:

• Navigate to GitHub
• Create Pull Request
• Use prepared PR description
• Add co-author in PR description footer

Multi-Repo Coordination

When changes span multiple repos:

1. Create branches with consistent naming:

```bash # lab-api git checkout -b feat/liminal-bridge

# the-human-pattern-lab git checkout -b feat/liminal-bridge

# the-human-pattern-lab-cli git checkout -b fix/es-module-imports ```

1. Note dependencies in PR descriptions:

```markdown ## Related

• Depends on lab-api#123
• Related to the-human-pattern-lab-cli#45

```

1. Coordinate merge order if dependencies exist:

• Merge foundation changes first (database, API)
• Then dependent changes (UI, CLI)

Output Format

Present the ritual results clearly:

# gitRitual Complete 🌉
 
## Commits Created