Your First Plugin: sanctum

This hands-on tutorial walks you through using the sanctum plugin for git and workspace operations.

What You’ll Build

A working sanctum review pipeline:

• Review your git workspace state
• Generate a conventional commit message
• Prepare a pull request description

Prerequisites

• sanctum plugin installed: /plugin install sanctum@claude-night-market
• A git repository with some uncommitted changes

Part 1: Workspace Review

Before any git operation, understand your current state.

Invoke the Skill

Skill(sanctum:git-workspace-review)

This skill runs a preflight checklist:

• Current branch and remote tracking
• Staged vs unstaged changes
• Recent commit history
• Untracked files

What to Expect

Claude will analyze your repository and report:

Repository: my-project
Branch: feature/add-login
Tracking: origin/feature/add-login (up to date)

Staged Changes:
  M src/auth/login.ts
  A src/auth/types.ts

Unstaged Changes:
  M README.md

Untracked:
  src/auth/tests/login.test.ts

Part 2: Commit Message Generation

Now generate a conventional commit message for your staged changes.

Using the Command

/commit-msg

Or invoke the skills directly:

Skill(sanctum:git-workspace-review)
Skill(sanctum:commit-messages)

Understanding the Output

Claude analyzes staged changes and generates:

feat(auth): add login form with validation

- Implement LoginForm component with email/password fields
- Add form validation using zod schema
- Create auth types for login request/response

Closes #42

The commit follows Conventional Commits format:

• Type: feat, fix, docs, style, refactor, test, chore
• Scope: Optional context (auth, api, ui)
• Description: Imperative mood, present tense
• Body: Bullet points explaining what changed
• Footer: Issue references

Part 3: PR Preparation

Finally, prepare a pull request description.

Using the Command

/pr

This runs the full PR preparation workflow:

1. Workspace review
2. Quality gates check
3. Change summarization
4. PR description generation

Quality Gates

Before generating the PR, Claude checks:

Quality Gates:
  [x] Code compiles
  [x] Tests pass
  [x] Linting clean
  [x] No console.log statements
  [x] Documentation updated

Generated PR Description

Add login form validation to user authentication

| | |
|---|---|
| **Who** | users signing in; @security-owner for the credential path |
| **Where** | `src/auth/`, 4 files. External: adds a 422 response to `POST /login` |
| **When** | on merge. No flag, no migration window |

## Why

Malformed credentials reached the auth backend and returned a generic
500, so users retried a request that could never succeed (#214).

## What and how

Adds a login form component that validates email and password shape
before submission, plus request and response types for the auth call.
Validation runs at the form boundary rather than in the backend client,
so the client keeps its invariant that inputs are already well formed.

## Test plan

1. `npm test`: 15 new unit tests passing.
2. Submit the form with `not-an-email`.
   Expected: inline field error, no network request issued.
3. Submit valid credentials.
   Expected: HTTP 200 and a redirect to the dashboard.

## Checklist

- [x] Tests fail if the validation is reverted
- [x] Documentation updated
- [x] Breaking changes stated in the Where row

Workflow Chaining

These skills work together. The recommended flow:

git-workspace-review (foundation)
├── commit-messages (depends on workspace state)
├── pr-prep (depends on workspace state)
├── doc-updates (depends on workspace state)
└── version-updates (depends on workspace state)

Always run git-workspace-review first to establish context.

Common Patterns

Pre-Commit Workflow

# Stage your changes
git add -p

# Review and commit
Skill(sanctum:git-workspace-review)
Skill(sanctum:commit-messages)

# Apply the message
git commit -m "<generated message>"

Pre-PR Workflow

# Run quality checks
make fmt && make lint && make test

# Prepare PR
/pr

# Create on GitHub
gh pr create --title "<title>" --body "<generated body>"

Next Steps

• Read the Quick Start Guide for more workflow patterns
• Explore other plugins in the Plugin Overview
• Check the Capabilities Reference for all available skills

Achievements Earned

• Skill Apprentice: Used your first skill
• PR Pioneer: Prepared your first PR