ramstack 0.1.0

package/skills/poteto-mode/scripts/worktree-audit.sh

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Read-only worktree prune audit. Classifies every git worktree by size, merge
+# state, uncommitted work, remote/PR state, and the most recent chat that
+# operated in it. Emits a table sorted by size with a suggested bucket. Never
+# deletes anything; deletion stays a human-gated step in the playbook.
+#
+# Usage: worktree-audit.sh [repo-path]   (defaults to the current repo)
+set -u
+
+repo="${1:-$(git rev-parse --show-toplevel 2>/dev/null)}"
+[ -z "$repo" ] && { echo "not in a git repo; pass a repo path" >&2; exit 1; }
+cd "$repo" || exit 1
+
+# Main worktree is the first entry; everything else is a candidate.
+main_wt=$(git worktree list --porcelain | awk '/^worktree /{print $2; exit}')
+
+# origin/main drives the merge check. Best-effort; stale is fine for a first pass.
+git fetch origin main --quiet 2>/dev/null || echo "warn: could not fetch origin/main; merged column may be stale" >&2
+
+# PR state by branch, fetched once. Empty if gh is unavailable.
+prs=$(mktemp)
+gh pr list --author "@me" --state all --limit 1000 \
+	--json number,state,headRefName 2>/dev/null > "$prs" || echo "[]" > "$prs"
+
+# Transcripts dir: ~/.cursor/projects/<slugified-repo-path>/agent-transcripts.
+slug=$(printf '%s' "$main_wt" | sed 's#^/##; s#/#-#g')
+transcripts="$HOME/.cursor/projects/$slug/agent-transcripts"
+now=$(date +%s)
+
+printf "SIZE\tAGE\tMERGED\tDIRTY\tREMOTE\tPR\tLAST_CHAT\tBUCKET\tWORKTREE\n"
+
+git worktree list --porcelain | awk '/^worktree /{print $2}' | while read -r wt; do
+	[ "$wt" = "$main_wt" ] && continue
+
+	size=$(du -sh "$wt" 2>/dev/null | awk '{print $1}')
+	head=$(git -C "$wt" rev-parse HEAD 2>/dev/null)
+	head_ts=$(git -C "$wt" log -1 --format='%ct' HEAD 2>/dev/null || echo 0)
+	age=$([ "$head_ts" -gt 0 ] 2>/dev/null && echo "$(( (now - head_ts) / 86400 ))d" || echo "?")
+
+	# Squash-merged branches are not ancestors of main, so PR state is the
+	# real signal; merge-base only catches fast-forward/rebase merges.
+	git merge-base --is-ancestor "$head" origin/main 2>/dev/null && merged=YES || merged=no
+
+	# Distinguish real WIP (tracked edits) from disposable untracked scratch.
+	porcelain=$(git -C "$wt" status --porcelain 2>/dev/null)
+	if [ -z "$porcelain" ]; then dirty=clean
+	elif printf '%s\n' "$porcelain" | grep -qv '^??'; then
+		dirty="wip:$(printf '%s\n' "$porcelain" | grep -cv '^??')"
+	else dirty="scratch:$(printf '%s\n' "$porcelain" | grep -c '^??')"; fi
+
+	branch=$(git -C "$wt" symbolic-ref --quiet --short HEAD 2>/dev/null || echo "")
+	if [ -z "$branch" ]; then remote=detached
+	elif git -C "$wt" show-ref --verify --quiet "refs/remotes/origin/$branch"; then
+		[ "$(git -C "$wt" rev-parse "origin/$branch" 2>/dev/null)" = "$head" ] \
+			&& remote=pushed \
+			|| remote="ahead$(git -C "$wt" rev-list --count "origin/$branch..HEAD" 2>/dev/null)"
+	else remote=no-remote; fi
+
+	pr=$([ -n "$branch" ] && jq -r --arg b "$branch" \
+		'.[] | select(.headRefName==$b) | "#\(.number)/\(.state)"' "$prs" 2>/dev/null | head -1)
+	[ -z "$pr" ] && pr="-"
+
+	# Most recent chat whose transcript operated in this worktree. Match path
+	# followed by "/" or a quote so glint-482 does not match glint-482-r37.
+	last="-"; last_ts=0
+	if [ -d "$transcripts" ]; then
+		f=$(rg -l -e "${wt}/" -e "${wt}\"" "$transcripts" 2>/dev/null \
+			| xargs stat -f '%m %N' 2>/dev/null | sort -rn | head -1)
+		if [ -n "$f" ]; then last_ts=$(echo "$f" | awk '{print $1}')
+			last=$(date -r "$last_ts" '+%Y-%m-%d' 2>/dev/null); fi
+	fi
+	recent=$([ "$last_ts" -gt 0 ] 2>/dev/null && [ $(( (now - last_ts) / 86400 )) -le 4 ] && echo yes || echo no)
+
+	case "$dirty" in wip:*) bucket=hold-wip ;; *)
+		case "$pr" in *OPEN*) bucket=hold-open-pr ;; *)
+			if [ "$recent" = yes ]; then bucket=verify-recent-chat
+			elif [ "$merged" = YES ] || [ "$pr" != "-" ]; then bucket=safe
+			else bucket=review; fi ;;
+		esac ;;
+	esac
+
+	printf "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n" \
+		"$size" "$age" "$merged" "$dirty" "$remote" "$pr" "$last" "$bucket" "$wt"
+done | sort -t$'\t' -k1,1 -rh
+
+rm -f "$prs"

package/skills/principle-boundary-discipline/README.md

@@ -0,0 +1,17 @@
+# Boundary discipline
+
+Validate at the edges. Trust internal types.
+
+## When it applies
+
+- You wire validation, error handling, or framework adapters.
+- You parse external input (CLI args, config files, network payloads, third-party APIs).
+- You decide where a guard or nil-check belongs.
+
+## The rule
+
+Place all validation and type narrowing at system boundaries where untrusted data enters. Inside the system, trust the typed data and skip re-validation. Keep business logic in pure functions with no framework dependencies. Expose domain concepts at the boundary, not transport or wire types.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-boundary-discipline/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: principle-boundary-discipline
+description: "Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions."
+disable-model-invocation: true
+---
+
+# Boundary Discipline
+
+Place validation, type narrowing, and error handling at system boundaries. Trust internal code unconditionally. Business logic lives in pure functions; the shell is thin and mechanical.
+
+**Why:** Scattered validation is noisy, redundant, and gives a false sense of safety. Validate data once at the boundary. Keep logic out of framework wiring so it can be tested without the framework.
+
+**The pattern:**
+- **At boundaries** (CLI args, config files, external APIs, network protocols): validate, return errors, handle defensively.
+- **Inside the system:** typed data, error propagation, no re-validation. Trust the types.
+- **Across the boundary.** Expose domain concepts, not the boundary's private representation. Keep general-purpose mechanism inside and special-purpose policy at the edge.
+
+**Applications:**
+
+Validation and error handling:
+- Validate config at parse time (the boundary), not inside business logic
+- Parse raw data into domain types at the boundary
+- Do not re-export transport, storage, framework, or wire types through the public surface
+- No redundant nil checks deep in call chains if the boundary already validated
+
+Code organization:
+- Business logic in pure functions with no framework dependencies
+- Parse functions: pure transforms from raw bytes to typed state
+- Prompt construction: structured state in, string out
+- Scoring and assessment: pure transforms from state to results
+
+**The tests:**
+- "Is this data crossing a system boundary right now?" If not, validation is redundant.
+- "Can this be a pure function that the shell just calls?" If yes, extract it.

package/skills/principle-boundary-discipline/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Boundary Discipline"
+  short_description: "Concentrate guards at system boundaries"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-build-the-lever/README.md

@@ -0,0 +1,17 @@
+# Build the lever
+
+When the work is not trivial, build the tool that does it instead of doing it by hand.
+
+## When it applies
+
+- You face non-trivial edits, migrations, analyses, or checks.
+- A reviewer needs a rerunnable artifact to verify the work.
+- You fan work out to subagents and need a shared recipe.
+
+## The rule
+
+Do the first unit by hand to learn the recipe, then build a codemod, script, or generator that handles the rest. The tool is one artifact a reviewer can read and rerun. A deterministic script turns "trust me" into "run this." Skip the lever only when the task is a couple of obvious edits you can see at a glance.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-build-the-lever/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: principle-build-the-lever
+description: "Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun."
+disable-model-invocation: true
+---
+# Build the Lever
+
+When the work isn't trivial, build the tool that does it instead of doing it by hand.
+
+**Why:** Two payoffs. Throughput: a codemod, generator, or script does the work the same way every time and reruns for free. Confidence: the tool is one artifact a reviewer can read and rerun to check the work. Hand-done changes can only be re-verified by redoing them. A deterministic script turns "trust me" into "run this".
+
+**Pattern:** Default to building the lever. Skip it only when the task is genuinely trivial, a couple of obvious edits you can see at a glance.
+
+- Do the first unit by hand to learn the recipe, then build the tool. Prove it by rerunning it on that unit and diffing against your hand-done version. Make the lever safe to rerun. A reviewer will.
+- Codemod or script for edits, generator for repetitive files, a dump-to-sqlite query for analysis, a rerunnable check for verification.
+- A deterministic lever beats fan-out. If the tool can process every unit in one pass, run it yourself; don't fan out delegates to hand-apply what a script can do.
+- When you fan work out to subagents, write the lever as a skill they all read: the recipe, the verification contract, and the do-not-touch fences in one artifact, so every delegate inherits the same hardened version instead of re-explaining it per prompt and watching each one drift. Keep it outside the delegates' write scope so they can't quietly edit the contract.
+- Applying this principle produces a file. If you cited it and there is no codemod, script, generator, or delegate skill in the diff, you didn't apply it.
+- Commit the lever when the work outlives the session, so the next run reruns it instead of redoing it.
+
+**Balance:** The bar is triviality, not repetition. A one-off still earns a lever when the lever is what makes the work checkable. Per the [Laziness Protocol](../principle-laziness-protocol/SKILL.md), build the smallest script that does or proves the job, never a framework.
+
+Distinct from [Encode Lessons in Structure](../principle-encode-lessons-in-structure/SKILL.md), which makes a recurring instruction a durable guardrail. This is throughput and reviewability on the work in front of you. For scripting the verification itself, see [Prove It Works](../principle-prove-it-works/SKILL.md).

package/skills/principle-build-the-lever/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Build the Lever"
+  short_description: "Build the tool that does the work"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-encode-lessons-in-structure/README.md

@@ -0,0 +1,17 @@
+# Encode lessons in structure
+
+Turn recurring fixes into mechanisms, not instructions.
+
+## When it applies
+
+- You catch yourself writing the same instruction a second time.
+- A human correction or test failure reveals a recurring pattern.
+- A textual rule could instead be a lint, metadata flag, runtime check, or script.
+
+## The rule
+
+When a fix recurs, encode it as the strongest structural mechanism the situation allows: an unrepresentable state, a lint rule, a canonical helper, or a runtime check. Delete the instruction it replaces. If the fix genuinely requires judgment, make the instruction more visible and add a failure-mode example.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-encode-lessons-in-structure/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: principle-encode-lessons-in-structure
+description: "Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text."
+disable-model-invocation: true
+---
+
+# Encode Lessons in Structure
+
+Encode recurring fixes in mechanisms (tools, code, metadata, automation) instead of textual instructions. Every error, human correction, and unexpected outcome is a learning signal. Capture it, route it, and close the loop.
+
+**Why:** Textual instructions are easy to miss. They require the reader to notice, remember, and comply. Structural mechanisms (lint rules, metadata flags, runtime checks, automation scripts) enforce the rule without cooperation.
+
+**Pattern:**
+When you catch yourself writing the same instruction a second time:
+1. Ask: can this be a lint rule, a metadata flag, a runtime check, or a script?
+2. If yes, encode it. Delete the instruction
+3. If no (genuinely requires judgment), make the instruction more prominent and add an example of the failure mode
+
+**Pick the strongest rung.** When more than one mechanism would work, choose the strongest the situation allows (an unrepresentable state that cannot compile, then a lint or banned API that fails CI, then a canonical helper, then a runtime check), because agents copy whatever the surrounding code already does and a weaker guard becomes the next template.
+
+**Corollary:** Don't paper over symptoms. If the fix is structural, ONLY use the structural fix. The instruction IS the symptom.
+
+**Feedback loop:**
+- **Capture every correction.** When the human intervenes or tests fail, decide if it's a one-off or a pattern.
+- **Route to the right layer.** One-off -> brain note. Recurring fix -> skill or lint rule. Systemic issue -> principle.
+- **Close the loop.** Don't just record. Apply now or create a concrete todo.
+
+**Anti-patterns:**
+- Acknowledging without recording ("I'll keep that in mind" does not persist)
+- Recording without routing (a brain note about a lint rule that should exist is wasted unless the lint rule gets implemented)
+- Fixing without generalizing (fixing one instance while leaving the recurring pattern intact)

package/skills/principle-encode-lessons-in-structure/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Encode Lessons in Structure"
+  short_description: "Encode rules as checks, not more text"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-exhaust-the-design-space/README.md

@@ -0,0 +1,17 @@
+# Exhaust the design space
+
+When the right answer is not obvious, explore several alternatives before committing.
+
+## When it applies
+
+- A novel UI interaction has no precedent in the codebase.
+- An architectural decision has multiple viable approaches.
+- User experience depends on feel, not logic.
+
+## The rule
+
+Build 2-3 competing prototypes or sketches and compare them side by side. A second flavor of the same shape does not count. Only commit after the comparison. Skip this for mechanical work, bug fixes, or changes where constraints dictate a single approach.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-exhaust-the-design-space/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-exhaust-the-design-space
+description: "Apply when facing a novel UI interaction or architectural decision with no precedent in the codebase. Build 2-3 competing prototypes and compare side by side before committing."
+disable-model-invocation: true
+---
+
+# Exhaust the Design Space
+
+When a novel interaction or architectural decision has no established precedent, explore several concrete alternatives before implementation. Building the wrong thing costs more than exploring three options.
+
+**The rule.** When the right answer is not obvious, build 2-3 competing prototypes or sketches. Compare them side by side. Only then commit. Design it twice is this rule by another name. A second flavor of the first shape does not count.
+
+**When it applies:**
+- Novel UI interactions (no prior art in the codebase)
+- Architectural choices with multiple viable approaches
+- Product design decisions where user experience depends on feel, not logic
+
+**When it doesn't:**
+- Mechanical implementation where the pattern is established
+- Bug fixes or refactors with a clear target state
+- Changes where constraints dictate a single viable approach

package/skills/principle-exhaust-the-design-space/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Exhaust the Design Space"
+  short_description: "Compare competing prototypes before committing"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-experience-first/README.md

@@ -0,0 +1,17 @@
+# Experience first
+
+When implementation convenience conflicts with user delight, choose delight.
+
+## When it applies
+
+- Product, UX, or feature-scope tradeoffs come up.
+- You decide between shipping more features rough or fewer features polished.
+- You weigh implementation ease against the experience of any consumer (end user, API caller, future maintainer).
+
+## The rule
+
+The product is the experience. Ship less and ship better. Every feature, control, and option must earn its place. Sweat details like transitions, alignment, spacing, and error states. The "user" includes anyone who consumes the work: end users, API callers, and the next engineer who reads the code.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-experience-first/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-experience-first
+description: "Apply when product, UX, or feature-scope tradeoffs come up. Choose user delight over implementation convenience; ship fewer polished features over more rough ones."
+disable-model-invocation: true
+---
+
+# Experience First
+
+The product is the experience. Every technical decision either helps or hurts it. When implementation convenience conflicts with user delight, choose delight.
+
+- Say no to 1,000 things (every feature, control, and option must earn its place)
+- Ship less, ship better (polished experience with three features beats rough one with ten)
+- Prototype before committing (design decisions are cheaper in throwaway HTML than production code)
+- Sweat the details (transitions, alignment, spacing, feedback, error states)
+- Tighten the core loop (every feature should serve the central workflow or get out of the way)
+
+The user is whoever consumes the work. For a UI that is the end user. For a library or an internal API it is the colleague who imports it. The engineer who maintains the code next is a user too. Weigh their experience the same way, and explain impact from their seat.
+
+Foundations should serve the experience, not the other way around. Foundational thinking governs the *sequence* of work; this principle governs the *target*.

package/skills/principle-experience-first/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Experience First"
+  short_description: "Choose user delight over implementation convenience"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-fix-root-causes/README.md

@@ -0,0 +1,17 @@
+# Fix root causes
+
+Trace every problem to its root cause and fix it there. Do not paper over symptoms.
+
+## When it applies
+
+- You debug a failure, crash, or unexpected behavior.
+- You are tempted to add a guard or nil-check to silence an error.
+- Something breaks after a restart and you suspect state, not code.
+
+## The rule
+
+Reproduce first. Ask "why" until you reach the root cause. Resist adding guards that silence crashes without fixing the underlying bug. When something fails after a restart, suspect stale persistent state before suspecting code. Check for the same pattern across the codebase and fix all instances.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-fix-root-causes/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: principle-fix-root-causes
+description: "Apply when debugging. Trace each symptom to its root cause and fix it there; reproduce first, ask why until you reach it, resist nil-check guards that silence crashes."
+disable-model-invocation: true
+---
+
+# Fix Root Causes
+
+When debugging, do not paper over symptoms. Trace every problem to its root cause and fix it there.
+
+**Why:** Symptom fixes accumulate. Each workaround makes the system harder to reason about, and the real bug remains. Root-cause fixes are slower upfront but reduce total debugging time.
+
+**Pattern:**
+- Reproduce first (if you can't reproduce it, you can't verify your fix)
+- Ask "why" until you hit the root cause
+- Resist the urge to add guards (adding a nil check to silence a crash is a symptom fix)
+- If a workaround needs a paragraph-long comment to justify it, the code is wrong (fix the code, not the comment)
+- Check for the pattern, not just the instance (grep for the same pattern, fix all instances)
+- When stuck, instrument. Don't guess (add logging, read the actual error)
+
+**Restart bugs: suspect state before code**
+
+Code doesn't change between runs. State does. When something "fails after restart," suspect stale persistent state first: config files, caches, lock files, serialized state. If clearing a state file restores behavior, prioritize state validation as the fix.

package/skills/principle-fix-root-causes/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Fix Root Causes"
+  short_description: "Trace symptoms to the real cause and fix it there"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-foundational-thinking/README.md

@@ -0,0 +1,17 @@
+# Foundational thinking
+
+Get the data structures right so downstream code becomes obvious.
+
+## When it applies
+
+- You choose core types and data structures before writing logic.
+- You sequence scaffold-vs-feature work.
+- You decide what concurrent actors share.
+
+## The rule
+
+Define data shapes before writing logic. The right structure makes downstream code obvious; a late data-structure change is a rewrite. Sequence for option value: scaffold (CI, tests, shared types) before features. Before sharing state between actors, ask what happens if another actor modifies it concurrently. Remove dead weight first, then lay foundations.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-foundational-thinking/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-foundational-thinking
+description: "Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious."
+disable-model-invocation: true
+---
+
+# Foundational Thinking
+
+**Structural decisions** protect option value. **Code-level decisions** protect simplicity. Over-engineering is often a premature decision that closes doors. The right foundational data structure keeps doors open.
+
+**Data structures first.** Get the data shape right before writing logic. The right shape makes downstream code obvious. Define core types early, trace every access pattern, and choose structures that match the dominant paths. A data-structure change late is a rewrite. Early, it is often a one-line diff.
+
+At code level, DRY the structure, not every line. Types and data models should converge. Three similar statements still beat a premature abstraction. Prefer explicit over clever. Test behavior and edge cases, not line counts.
+
+**Concurrency corollary.** Before sharing state between actors, ask "what happens if another actor modifies this concurrently?" If not "nothing", isolate.
+
+**Scaffold first.** If something helps every later phase, do it first. Ask "does every subsequent phase benefit from this existing?" CI, linting, test infrastructure, and shared types are scaffold. Sequence for option value: setup before features, tests before fixes. Keep commits small and single-purpose.
+
+Each increment should land a coherent abstraction or deepen one that exists. Do not spread a new capability across callers as special-case coordination.
+
+Subtraction comes before scaffolding: remove dead weight first, then lay foundations.

package/skills/principle-foundational-thinking/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Foundational Thinking"
+  short_description: "Get data structures right so later code is obvious"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-guard-the-context-window/README.md

@@ -0,0 +1,17 @@
+# Guard the context window
+
+Every token that enters the context window should earn its place.
+
+## When it applies
+
+- Context is filling up with large outputs, long files, or repeated reads.
+- You plan fan-out work across subagents.
+- You decide whether to inline or externalize reference material.
+
+## The rule
+
+The context window is finite and non-renewable within a session. Route verbose outputs and large documents to subagents. Keep summaries in the main thread, not raw payloads. Do not read what you will not use. Size phases and cap scope to stay within budget.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-guard-the-context-window/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: principle-guard-the-context-window
+description: "Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads."
+disable-model-invocation: true
+---
+
+# Guard the Context Window
+
+The context window is finite and non-renewable within a session. Every token that enters should earn its place.
+
+**Why:** Context overflow degrades reasoning quality, creates compression artifacts, and halts progress. Unlike compute or time, context spent inside a session cannot be reclaimed.
+
+**Pattern:**
+- **Isolate large payloads.** Route verbose outputs, screenshots, and large documents to subagents. The main context gets summaries, not raw data.
+- **Don't read what you won't use.** Read selectively based on relevance. If a file isn't needed for the current task, skip it.
+- **Keep frequently used content inline.** Templates and references used on every invocation belong in the skill file, not in separate files that cost a read each time.
+- **Size phases and cap scope.** Limit files per phase, set turn budgets, account for mechanism costs.

package/skills/principle-guard-the-context-window/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Guard the Context Window"
+  short_description: "Keep bulk work out of the main thread"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-laziness-protocol/README.md

@@ -0,0 +1,17 @@
+# Laziness protocol
+
+Aim for the most result with the least code and complexity.
+
+## When it applies
+
+- You refactor, evaluate diff size, or review code.
+- You are tempted to add abstractions, layers, or signal threading.
+- You choose between deletion and addition.
+
+## The rule
+
+Prefer deletion over addition. Maintain a flat call hierarchy. Minimize the diff by making the smallest change that solves the problem. Before threading a new signal through types, schemas, or pipelines, look for a more direct path. If a human developer would find the code exhausting to maintain, it is a bad solution.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-laziness-protocol/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: principle-laziness-protocol
+description: "Apply when refactoring, evaluating diff size, or tempted to add abstractions, layers, or signal threading. Bias toward deletion and the smallest change that solves the problem."
+disable-model-invocation: true
+---
+
+# Laziness Protocol
+
+Writing code is cheap for you, which makes over-engineering easy. Counter it by borrowing a human maintainer's fatigue. Aim for the most result with the least code and complexity.
+
+- **Prefer deletion.** When asked to refactor or improve, look for removals before additions.
+- **Maintain a flat call hierarchy.** Avoid deep call chains. A rich interface that hides substantial work is not a deep call chain. If answering a question requires tracing through more than 3 files or layers, flatten it.
+- **Consolidate decisions.** Do not repeat the same choice in several places. Put it behind one source of truth and pass the result as a simple flag.
+- **Minimize the diff.** Make the smallest change that solves the problem. Fewer lines beat "elegant" boilerplate.
+- **Question the threading.** If a task asks you to pass a new signal through types, schemas, pipelines, or similar layers, stop and look for a more direct path.
+- **Sweat the small leaks.** Remove tiny pass-throughs, representation leaks, and duplicated choices before they spread. Small leaks compound into permanent coordination costs.
+
+**Prime directive:** If a human developer would find the code exhausting to maintain, it is a bad solution. Be lazy. Stay simple.

package/skills/principle-laziness-protocol/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Laziness Protocol"
+  short_description: "Bias toward deletion and the smallest change"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-make-operations-idempotent/README.md

@@ -0,0 +1,17 @@
+# Make operations idempotent
+
+Design operations to converge to the correct state no matter how many times they run.
+
+## When it applies
+
+- You design commands, lifecycle steps, or processing loops.
+- Crashes, restarts, and retries are normal operating conditions.
+- Partial prior runs might leave behind stale state.
+
+## The rule
+
+Every state-mutating operation must answer two questions: "What happens if this runs twice?" and "What happens if the previous run crashed halfway?" Use convergent startup, content-based cleanup, and self-healing locks. If re-execution does not converge to the same end state, add a reconciliation step.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-make-operations-idempotent/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: principle-make-operations-idempotent
+description: "Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state regardless of partial prior runs."
+disable-model-invocation: true
+---
+
+# Make Operations Idempotent
+
+Design operations so they converge to the correct state regardless of how many times they run or where they start from. Every state-mutating operation should answer: "What happens if this runs twice? What happens if the previous run crashed halfway?"
+
+**Why:** Commands, lifecycle operations, and processing loops run where crashes, restarts, and retries are normal. If partial state changes the next run's outcome, every restart becomes a debugging session.
+
+**The pattern:**
+- Convergent startup: scan for existing state, clean stale artifacts, adopt live sessions
+- Content-based cleanup: compare by content equivalence, not creation order
+- Self-healing locks: use PID-based stale lock detection
+- Idempotent scheduling: failed work respawns cleanly, fresh input regenerated after each cycle
+
+**The test:**
+1. What happens if this runs twice in a row?
+2. What happens if the previous run crashed at every possible point?
+3. Does re-execution converge to the same end state?
+
+If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.

package/skills/principle-make-operations-idempotent/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Make Operations Idempotent"
+  short_description: "Same end state after crashes, restarts, and retries"
+policy:
+  allow_implicit_invocation: false

package/skills/principle-migrate-callers-then-delete-legacy-apis/README.md

@@ -0,0 +1,17 @@
+# Migrate callers then delete legacy APIs
+
+When a new API replaces an old one, migrate callers and remove the old API in the same wave.
+
+## When it applies
+
+- You introduce a new internal API while old callers still exist.
+- No external users depend on backward compatibility.
+- The project can absorb coordinated breaking changes.
+
+## The rule
+
+Do not keep legacy API paths alive just because internal callers still use them. Inventory callers, migrate them, and delete the old API immediately. Treat temporary adapters as exceptional and time-boxed. Update tests to assert the new contract and delete tests that only protect pre-refactor details.
+
+## Related
+
+- [Full rule](SKILL.md)

package/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: principle-migrate-callers-then-delete-legacy-apis
+description: "Apply when introducing a new internal API while old callers still exist. Migrate callers and delete the old API in the same wave instead of preserving compatibility layers."
+disable-model-invocation: true
+---
+
+# Migrate Callers Then Delete Legacy APIs
+
+When we decide a new API is the right design, migrate callers and remove the old API in the same refactor wave instead of preserving compatibility layers.
+
+**Rule:**
+- Do not keep legacy API paths alive only because internal callers still exist
+- Inventory callers, migrate them, and delete the old API immediately
+- Treat temporary adapters as exceptional and time-boxed, not default architecture
+- Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details
+
+**When this applies:**
+- No external users depend on backward compatibility
+- The project can absorb coordinated breaking changes
+- The new API is part of a simplification or refactor initiative
+
+Keeping both old and new APIs creates dual-path complexity, slows cleanup, and makes the codebase feel append-only.