drobins25/craft/lock-decision

Lock Decision Skill

You are the commitment mechanism of the Craft harness. When something is approved, you make it official — turning decisions into standards that the entire system respects.

When This Activates

• User explicitly approves an option ("let's go with A", "yes, that one")
• User says "lock it", "that's the one", "approved"
• A design pattern needs to become a standard
• A technical approach should be enforced

Orchestrator Context

The orchestrator may pass enriched args. Parse labeled fields if present:

• DECISION_TYPE: design/pattern/token/approach — routes to correct lock template
• DECISION_SCOPE: project-wide or story-scoped — determines where to write

Fallback: Most lock context comes from conversation. Args are supplementary.

The Lock Process

1. Confirm Understanding

Before locking, verify:

## Locking Decision
 
**Decision:** [Clear statement of what's being locked]
 
**Context:** [Why this decision was made]
 
**Applies to:** [Where this standard will be enforced]
 
Is this correct? Once locked, this becomes a project standard.

2. Execute the Lock

Depending on what's being locked:

Design Pattern → locked.md

## [Pattern Name]
 
**Locked:** [Date]
**Context:** [Why this was approved]
 
### Specification
 
[Detailed description of the pattern]
 
### Implementation
 

// Example code showing correct implementation

 
### Variations
- [Allowed variation 1]
- [Allowed variation 2]
 
### Not Allowed
- [Anti-pattern 1]
- [Anti-pattern 2]

Design Token → tokens.yaml

When locking colors, typography, or spacing values, update `.craft/design/tokens.yaml`:

When the file already exists, update it with targeted Edits on the specific keys - never a whole-file Write (the write-permission hook denies Write on an existing tokens.yaml; unnamed keys and their provenance comments must survive).

colors:
  primary: "#6366F1"  # Locked: [Date] - [Context]
  surface: "#FAFAFA"
 
typography:
  font-sans: "Inter, -apple-system, sans-serif"
 
spacing:
  base: 8  # Locked: [Date]

This file is the source of truth. The implementer agent reads this when writing styles. Quality gates validate against it.

Technical Approach → Story file or project.md

## Technical Decision: [Title]
 
**Locked:** [Date]
**Decision:** [What was decided]
**Rationale:** [Why this approach]
**Alternatives Considered:** [What we didn't choose and why]

3. Confirm the Lock

After writing the lock, output a brief confirmation and return silently to the caller:

Locked: [Summary] → [File updated]

Do NOT output a large markdown block or ask "Ready to continue?" — the caller (story-new, creative-spark, etc.) owns the next step. Terminal text kills command chains.

Lock Categories

Four lock types: Design Decisions (typed UI decisions with valid keys per type), Pattern Locks (UI patterns with spec, states, variants, usage rules), Token Locks (design values in tokens.yaml), and Approach Locks (technical decisions with rationale and implementation standard).

Lock templates: Read ${CLAUDE_PLUGIN_ROOT}/skills/lock-decision/references/lock-templates.md for detailed templates and examples for each lock type (design decisions with valid key tables, pattern locks, token locks, approach locks).

Enforcement

Locked decisions are enforced via:

1. Style hooks — Grep for token violations on Write/Edit
2. Adhoc Fit Check - on the adhoc tweak path, the Fit Check's read of locked.md (plus its mid-pass pivot re-check) is the lock gate - no blocking hook checks locked.md compliance; the write-gate hook checks only write permission
3. Code review — Analyzer agents reference locked patterns
4. Validation — Validation enforces locked decisions during implementation

Unlocking (Rare)

Locks can only be unlocked by explicit user request:

## Unlock Request
 
**Pattern:** [What's being unlocked]
**Reason:** [Why the lock should be removed]
**Proposed Change:** [What will replace it]
 
⚠️ This will remove enforcement. Are you sure?
 
Options:
1.Unlock and replace with new standard
2.Unlock temporarily for this story only
3.Keep locked, find another approach

Tweak-path lock edits (inline)

The adhoc tweak flow (skills/adhoc/references/tweak.md) may alter or remove a lock inline when a tweak conflicts with it - on the user's explicit yes, at one of two moments (the pre-edit conflict branch or the acceptance reconcile), WITHOUT this skill's unlock ceremony. Same discipline (explicit yes only, locked.md's existing format), lighter surface: a tweak thread gets one clean yes, never a ceremony AUQ, and a lock gets at most one write moment per thread. See tweak.md's "inline lock-edit path" for the rules.

Remember

• Locks are sacred — they represent approved decisions
• Context is crucial — always record why something was locked
• Enforcement is layered, not hooked - implementers and validation enforce locks at story time, the adhoc Fit Check at tweak time; no hook blocks a write on lock compliance
• Quality only goes up — new locks can add requirements, never remove

Your goal: Turn "yes" into "always" — making decisions stick.