@giljae/pi-pstack 0.0.0-stage → 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +67 -2
- package/agents/comment-sicko.md +35 -0
- package/agents/poteto-agent.md +12 -0
- package/harness/pi.md +87 -0
- package/package.json +37 -4
- package/skills/architect/SKILL.md +14 -0
- package/skills/arena/SKILL.md +51 -0
- package/skills/automate-me/SKILL.md +107 -0
- package/skills/benchmark-checklist/SKILL.md +42 -0
- package/skills/blast-radius/SKILL.md +53 -0
- package/skills/bro/SKILL.md +10 -0
- package/skills/correct/SKILL.md +35 -0
- package/skills/create-formal-verification-skill/SKILL.md +46 -0
- package/skills/create-verification-skill/SKILL.md +47 -0
- package/skills/create-verification-skill/references/feature-map-example/README.md +47 -0
- package/skills/create-verification-skill/references/feature-map-example/create-note.md +39 -0
- package/skills/create-verification-skill/references/feature-map-example/search.md +45 -0
- package/skills/figure-it-out/SKILL.md +55 -0
- package/skills/how/SKILL.md +24 -0
- package/skills/in-your-own-words/SKILL.md +10 -0
- package/skills/interrogate/SKILL.md +34 -0
- package/skills/ketchup/SKILL.md +46 -0
- package/skills/ketchup-video/SKILL.md +32 -0
- package/skills/maintain-formal-verification-skill/SKILL.md +61 -0
- package/skills/maintain-verification-skill/SKILL.md +42 -0
- package/skills/make-bot-ui/SKILL.md +118 -0
- package/skills/no-comments/SKILL.md +27 -0
- package/skills/poteto-help/SKILL.md +165 -0
- package/skills/poteto-help/references/prompting.md +51 -0
- package/skills/poteto-help/references/recipes.md +51 -0
- package/skills/poteto-mode/SKILL.md +111 -0
- package/skills/poteto-mode/playbooks/authoring-a-skill.md +12 -0
- package/skills/poteto-mode/playbooks/autonomous-run.md +13 -0
- package/skills/poteto-mode/playbooks/autopilot-full.md +25 -0
- package/skills/poteto-mode/playbooks/autopilot-stack.md +8 -0
- package/skills/poteto-mode/playbooks/babysit.md +10 -0
- package/skills/poteto-mode/playbooks/bug-fix.md +15 -0
- package/skills/poteto-mode/playbooks/eval.md +25 -0
- package/skills/poteto-mode/playbooks/feature.md +21 -0
- package/skills/poteto-mode/playbooks/hillclimb.md +21 -0
- package/skills/poteto-mode/playbooks/investigation.md +14 -0
- package/skills/poteto-mode/playbooks/multi-phase-plan.md +11 -0
- package/skills/poteto-mode/playbooks/opening-a-pr.md +9 -0
- package/skills/poteto-mode/playbooks/pause-safely.md +10 -0
- package/skills/poteto-mode/playbooks/perf-issue.md +25 -0
- package/skills/poteto-mode/playbooks/prototype.md +14 -0
- package/skills/poteto-mode/playbooks/refactoring.md +16 -0
- package/skills/poteto-mode/playbooks/runtime-forensics.md +11 -0
- package/skills/poteto-mode/playbooks/session-pickup.md +11 -0
- package/skills/poteto-mode/playbooks/shipping.md +12 -0
- package/skills/poteto-mode/playbooks/trace-forensics.md +14 -0
- package/skills/poteto-mode/playbooks/visual-parity.md +11 -0
- package/skills/poteto-mode/playbooks/worktree-cleanup.md +12 -0
- package/skills/poteto-mode/references/bugbot-triage.md +142 -0
- package/skills/poteto-mode/scripts/bootstrap.ts +62 -0
- package/skills/poteto-mode/scripts/bun.lock +67 -0
- package/skills/poteto-mode/scripts/package.json +16 -0
- package/skills/poteto-mode/scripts/watch-pr/cli.test.ts +224 -0
- package/skills/poteto-mode/scripts/watch-pr/cli.ts +223 -0
- package/skills/poteto-mode/scripts/watch-pr/fakes.test-helper.ts +129 -0
- package/skills/poteto-mode/scripts/watch-pr/github.test.ts +498 -0
- package/skills/poteto-mode/scripts/watch-pr/github.ts +726 -0
- package/skills/poteto-mode/scripts/watch-pr/policy.test.ts +482 -0
- package/skills/poteto-mode/scripts/watch-pr/policy.ts +842 -0
- package/skills/poteto-mode/scripts/watch-pr/render.ts +169 -0
- package/skills/poteto-mode/scripts/watch-pr/tsconfig.json +13 -0
- package/skills/poteto-mode/scripts/watch-pr/types.compile.ts +93 -0
- package/skills/poteto-mode/scripts/watch-pr/types.ts +414 -0
- package/skills/poteto-mode/scripts/watch-pr/watch-pr +6 -0
- package/skills/poteto-mode/scripts/worktree-audit.sh +134 -0
- package/skills/poteto-mode/worker.md +11 -0
- package/skills/principle-attack-the-premise/SKILL.md +18 -0
- package/skills/principle-boundary-discipline/SKILL.md +14 -0
- package/skills/principle-build-the-lever/SKILL.md +17 -0
- package/skills/principle-encode-lessons-in-structure/SKILL.md +14 -0
- package/skills/principle-exhaust-the-design-space/SKILL.md +12 -0
- package/skills/principle-experience-first/SKILL.md +22 -0
- package/skills/principle-explain-the-number/SKILL.md +17 -0
- package/skills/principle-fix-root-causes/SKILL.md +17 -0
- package/skills/principle-foundational-thinking/SKILL.md +16 -0
- package/skills/principle-guard-the-context-window/SKILL.md +15 -0
- package/skills/principle-laziness-protocol/SKILL.md +13 -0
- package/skills/principle-make-operations-idempotent/SKILL.md +18 -0
- package/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md +17 -0
- package/skills/principle-minimize-reader-load/SKILL.md +18 -0
- package/skills/principle-model-the-domain/SKILL.md +18 -0
- package/skills/principle-never-block-on-the-human/SKILL.md +18 -0
- package/skills/principle-outcome-oriented-execution/SKILL.md +24 -0
- package/skills/principle-prove-it-works/SKILL.md +14 -0
- package/skills/principle-redesign-from-first-principles/SKILL.md +19 -0
- package/skills/principle-separate-before-serializing-shared-state/SKILL.md +14 -0
- package/skills/principle-sequence-verifiable-units/SKILL.md +16 -0
- package/skills/principle-subtract-before-you-add/SKILL.md +21 -0
- package/skills/principle-test-behavior-not-implementation/SKILL.md +19 -0
- package/skills/principle-type-system-discipline/SKILL.md +18 -0
- package/skills/recall/SKILL.md +38 -0
- package/skills/reflect/SKILL.md +20 -0
- package/skills/setup-pstack/SKILL.md +81 -0
- package/skills/sharpen/SKILL.md +19 -0
- package/skills/show-me-your-work/SKILL.md +85 -0
- package/skills/show-me-your-work/references/decision-log-template.tsv +1 -0
- package/skills/show-me-your-work/scripts/log.sh +42 -0
- package/skills/statechart/SKILL.md +85 -0
- package/skills/statechart/references/render.md +93 -0
- package/skills/statechart/scripts/backends/cfg.ts +33 -0
- package/skills/statechart/scripts/backends/mermaid.ts +249 -0
- package/skills/statechart/scripts/backends/plain-text.ts +72 -0
- package/skills/statechart/scripts/backends/report.ts +177 -0
- package/skills/statechart/scripts/frontends/config.ts +276 -0
- package/skills/statechart/scripts/frontends/dot.ts +74 -0
- package/skills/statechart/scripts/frontends/marks.ts +93 -0
- package/skills/statechart/scripts/frontends/messages.ts +52 -0
- package/skills/statechart/scripts/frontends/spec.ts +114 -0
- package/skills/statechart/scripts/frontends/trace.ts +24 -0
- package/skills/statechart/scripts/frontends/value.ts +166 -0
- package/skills/statechart/scripts/frontends/verdict.ts +40 -0
- package/skills/statechart/scripts/frontends/view.ts +119 -0
- package/skills/statechart/scripts/ir.ts +547 -0
- package/skills/statechart/scripts/package.json +11 -0
- package/skills/statechart/scripts/passes/annotate.ts +128 -0
- package/skills/statechart/scripts/passes/label.ts +269 -0
- package/skills/statechart/scripts/passes/lift.ts +85 -0
- package/skills/statechart/scripts/passes/loop-check.ts +68 -0
- package/skills/statechart/scripts/passes/paths.ts +60 -0
- package/skills/statechart/scripts/passes/reach.ts +135 -0
- package/skills/statechart/scripts/passes/region-check.ts +97 -0
- package/skills/statechart/scripts/passes/regions.ts +295 -0
- package/skills/statechart/scripts/pipeline.ts +76 -0
- package/skills/statechart/scripts/run.ts +506 -0
- package/skills/statechart/scripts/statechart +29 -0
- package/skills/statechart/scripts/statechart.ts +164 -0
- package/skills/statechart/scripts/tsconfig.json +11 -0
- package/skills/statechart/scripts/worker.ts +35 -0
- package/skills/swarm/SKILL.md +44 -0
- package/skills/tdd/SKILL.md +45 -0
- package/skills/teach/SKILL.md +24 -0
- package/skills/technical-writing/SKILL.md +73 -0
- package/skills/typescript-best-practices/SKILL.md +33 -0
- package/skills/typescript-best-practices/references/patterns.md +328 -0
- package/skills/unslop/SKILL.md +43 -0
- package/skills/why/SKILL.md +12 -0
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
#!/usr/bin/env bash
|
|
2
|
+
# Read-only worktree prune audit. Classifies every git worktree by size, merge
|
|
3
|
+
# state, uncommitted work, remote/PR state, and the most recent chat that
|
|
4
|
+
# operated in it. Emits a table sorted by size with a suggested bucket. Never
|
|
5
|
+
# deletes anything; deletion stays a human-gated step in the playbook.
|
|
6
|
+
#
|
|
7
|
+
# Usage: worktree-audit.sh [-b|--base <ref>] [repo-path]
|
|
8
|
+
# repo-path defaults to the current repo.
|
|
9
|
+
# -b sets the ref the MERGED column checks against (e.g. origin/integration).
|
|
10
|
+
# Without it the base is origin/HEAD, then origin/main, then origin/master.
|
|
11
|
+
# origin/HEAD is the remote's default branch, not necessarily the branch PRs
|
|
12
|
+
# merge into; pass -b when they differ.
|
|
13
|
+
set -u
|
|
14
|
+
|
|
15
|
+
base=""
|
|
16
|
+
while [ $# -gt 0 ]; do
|
|
17
|
+
case "$1" in
|
|
18
|
+
-b|--base) [ $# -ge 2 ] || { echo "error: $1 needs a ref" >&2; exit 2; }; base="$2"; shift 2 ;;
|
|
19
|
+
-h|--help) sed -n '2,/^set -u/p' "$0" | sed '$d; s/^# \{0,1\}//'; exit 0 ;;
|
|
20
|
+
-*) echo "error: unknown option: $1" >&2; exit 2 ;;
|
|
21
|
+
*) break ;;
|
|
22
|
+
esac
|
|
23
|
+
done
|
|
24
|
+
|
|
25
|
+
repo="${1:-$(git rev-parse --show-toplevel 2>/dev/null)}"
|
|
26
|
+
[ -z "$repo" ] && { echo "not in a git repo; pass a repo path" >&2; exit 1; }
|
|
27
|
+
cd "$repo" || exit 1
|
|
28
|
+
git rev-parse --git-dir >/dev/null 2>&1 || { echo "error: not a git repo: $repo" >&2; exit 1; }
|
|
29
|
+
|
|
30
|
+
# Main worktree is the first entry; everything else is a candidate.
|
|
31
|
+
main_wt=$(git worktree list --porcelain | awk '/^worktree /{print $2; exit}')
|
|
32
|
+
|
|
33
|
+
if [ -z "$base" ]; then
|
|
34
|
+
for cand in "$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null)" origin/main origin/master; do
|
|
35
|
+
[ -n "$cand" ] && git rev-parse --verify --quiet "$cand^{commit}" >/dev/null && { base="$cand"; break; }
|
|
36
|
+
done
|
|
37
|
+
[ -z "$base" ] && { echo "error: no base ref (origin/HEAD, origin/main, origin/master all missing); pass -b <ref>" >&2; exit 1; }
|
|
38
|
+
echo "warn: no -b given; MERGED checks against $base" >&2
|
|
39
|
+
fi
|
|
40
|
+
|
|
41
|
+
# The base drives the merge check. The fetch is best-effort (stale is fine for
|
|
42
|
+
# a first pass) and runs before the check, since -b may name a branch not
|
|
43
|
+
# fetched yet. The explicit refspec creates it even in a single-branch clone.
|
|
44
|
+
case "$base" in
|
|
45
|
+
origin/*) git fetch origin "+refs/heads/${base#origin/}:refs/remotes/$base" --quiet 2>/dev/null \
|
|
46
|
+
|| echo "warn: could not fetch $base; merged column may be stale" >&2 ;;
|
|
47
|
+
esac
|
|
48
|
+
git rev-parse --verify --quiet "$base^{commit}" >/dev/null 2>&1 || { echo "error: base ref not found: $base" >&2; exit 1; }
|
|
49
|
+
|
|
50
|
+
# GNU coreutils (Linux, Homebrew gnubin) reads `stat -f` as file system status
|
|
51
|
+
# and `date -r` as a file, so pick the stat and date flags once.
|
|
52
|
+
if stat -c %Y / >/dev/null 2>&1; then
|
|
53
|
+
stat_fmt=(-c '%Y %n'); fmt_day() { date -d "@$1" '+%Y-%m-%d'; }
|
|
54
|
+
else
|
|
55
|
+
stat_fmt=(-f '%m %N'); fmt_day() { date -r "$1" '+%Y-%m-%d'; }
|
|
56
|
+
fi
|
|
57
|
+
|
|
58
|
+
# PR state by branch, fetched once as [{number, state, head}] with a lowercase
|
|
59
|
+
# state. Origin when its CLI can read this repo's PRs, otherwise gh. Empty when
|
|
60
|
+
# neither can.
|
|
61
|
+
prs=$(mktemp)
|
|
62
|
+
if command -v origin >/dev/null 2>&1 \
|
|
63
|
+
&& raw=$(origin pr list --author "@me" --state all --limit 1000 \
|
|
64
|
+
--json number,status,headRef 2>/dev/null); then
|
|
65
|
+
printf '%s' "$raw" | jq '[.[] | {number, state: .status, head: .headRef}]' > "$prs" 2>/dev/null
|
|
66
|
+
elif raw=$(gh pr list --author "@me" --state all --limit 1000 \
|
|
67
|
+
--json number,state,headRefName 2>/dev/null); then
|
|
68
|
+
printf '%s' "$raw" | jq '[.[] | {number, state: (.state | ascii_downcase), head: .headRefName}]' > "$prs" 2>/dev/null
|
|
69
|
+
fi
|
|
70
|
+
[ -s "$prs" ] || echo "[]" > "$prs"
|
|
71
|
+
|
|
72
|
+
# Transcripts dir: ~/.cursor/projects/<slugified-repo-path>/agent-transcripts.
|
|
73
|
+
slug=$(printf '%s' "$main_wt" | sed 's#^/##; s#/#-#g')
|
|
74
|
+
transcripts="$HOME/.cursor/projects/$slug/agent-transcripts"
|
|
75
|
+
now=$(date +%s)
|
|
76
|
+
|
|
77
|
+
echo "# base: $base"
|
|
78
|
+
printf "SIZE\tAGE\tMERGED\tDIRTY\tREMOTE\tPR\tLAST_CHAT\tBUCKET\tWORKTREE\n"
|
|
79
|
+
|
|
80
|
+
git worktree list --porcelain | awk '/^worktree /{print $2}' | while read -r wt; do
|
|
81
|
+
[ "$wt" = "$main_wt" ] && continue
|
|
82
|
+
|
|
83
|
+
size=$(du -sh "$wt" 2>/dev/null | awk '{print $1}')
|
|
84
|
+
head=$(git -C "$wt" rev-parse HEAD 2>/dev/null)
|
|
85
|
+
head_ts=$(git -C "$wt" log -1 --format='%ct' HEAD 2>/dev/null || echo 0)
|
|
86
|
+
age=$([ "$head_ts" -gt 0 ] 2>/dev/null && echo "$(( (now - head_ts) / 86400 ))d" || echo "?")
|
|
87
|
+
|
|
88
|
+
# Squash-merged branches are not ancestors of the base, so PR state is the
|
|
89
|
+
# real signal; merge-base only catches fast-forward/rebase merges.
|
|
90
|
+
git merge-base --is-ancestor "$head" "$base" 2>/dev/null && merged=YES || merged=no
|
|
91
|
+
|
|
92
|
+
# Distinguish real WIP (tracked edits) from disposable untracked scratch.
|
|
93
|
+
porcelain=$(git -C "$wt" status --porcelain 2>/dev/null)
|
|
94
|
+
if [ -z "$porcelain" ]; then dirty=clean
|
|
95
|
+
elif printf '%s\n' "$porcelain" | grep -qv '^??'; then
|
|
96
|
+
dirty="wip:$(printf '%s\n' "$porcelain" | grep -cv '^??')"
|
|
97
|
+
else dirty="scratch:$(printf '%s\n' "$porcelain" | grep -c '^??')"; fi
|
|
98
|
+
|
|
99
|
+
branch=$(git -C "$wt" symbolic-ref --quiet --short HEAD 2>/dev/null || echo "")
|
|
100
|
+
if [ -z "$branch" ]; then remote=detached
|
|
101
|
+
elif git -C "$wt" show-ref --verify --quiet "refs/remotes/origin/$branch"; then
|
|
102
|
+
[ "$(git -C "$wt" rev-parse "origin/$branch" 2>/dev/null)" = "$head" ] \
|
|
103
|
+
&& remote=pushed \
|
|
104
|
+
|| remote="ahead$(git -C "$wt" rev-list --count "origin/$branch..HEAD" 2>/dev/null)"
|
|
105
|
+
else remote=no-remote; fi
|
|
106
|
+
|
|
107
|
+
pr=$([ -n "$branch" ] && jq -r --arg b "$branch" \
|
|
108
|
+
'.[] | select(.head==$b) | "#\(.number)/\(.state)"' "$prs" 2>/dev/null | head -1)
|
|
109
|
+
[ -z "$pr" ] && pr="-"
|
|
110
|
+
|
|
111
|
+
# Most recent chat whose transcript operated in this worktree. Match path
|
|
112
|
+
# followed by "/" or a quote so glint-482 does not match glint-482-r37.
|
|
113
|
+
last="-"; last_ts=0
|
|
114
|
+
if [ -d "$transcripts" ]; then
|
|
115
|
+
f=$(rg -l -e "${wt}/" -e "${wt}\"" "$transcripts" 2>/dev/null \
|
|
116
|
+
| xargs stat "${stat_fmt[@]}" 2>/dev/null | sort -rn | head -1)
|
|
117
|
+
if [ -n "$f" ]; then last_ts=$(echo "$f" | awk '{print $1}')
|
|
118
|
+
last=$(fmt_day "$last_ts" 2>/dev/null); fi
|
|
119
|
+
fi
|
|
120
|
+
recent=$([ "$last_ts" -gt 0 ] 2>/dev/null && [ $(( (now - last_ts) / 86400 )) -le 4 ] && echo yes || echo no)
|
|
121
|
+
|
|
122
|
+
case "$dirty" in wip:*) bucket=hold-wip ;; *)
|
|
123
|
+
case "$pr" in */open|*/draft) bucket=hold-open-pr ;; *)
|
|
124
|
+
if [ "$recent" = yes ]; then bucket=verify-recent-chat
|
|
125
|
+
elif [ "$merged" = YES ] || [ "$pr" != "-" ]; then bucket=safe
|
|
126
|
+
else bucket=review; fi ;;
|
|
127
|
+
esac ;;
|
|
128
|
+
esac
|
|
129
|
+
|
|
130
|
+
printf "%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n" \
|
|
131
|
+
"$size" "$age" "$merged" "$dirty" "$remote" "$pr" "$last" "$bucket" "$wt"
|
|
132
|
+
done | sort -t$'\t' -k1,1 -rh
|
|
133
|
+
|
|
134
|
+
rm -f "$prs"
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
You are working for the operator. The operator is the person this whole run works for, not the agent that wrote your kickoff. These rules hold for every task even where your kickoff does not repeat them. Your kickoff overrides one only when it says so in so many words.
|
|
2
|
+
|
|
3
|
+
- If you start an agent, the first line of its kickoff is `Read <path>/worker.md before anything else.`, with `<path>` the absolute path of the folder that holds this file.
|
|
4
|
+
- The bar in your kickoff is the whole bar. Add no check, gate, sign-off or review round above it.
|
|
5
|
+
- With no bar stated, the change must be no worse than its base and pass its own tests.
|
|
6
|
+
- Hold or block only for a failing run at this head or a bug a user would hit. Report a problem the base already has in one line.
|
|
7
|
+
- Never call a tool that shows a person a question. Make any choice you can undo, then say what you chose and why. Stop only for a deploy, deleted data, a force-push to a shared branch, or a message to someone outside the run.
|
|
8
|
+
- Open every PR ready for review, never as a draft.
|
|
9
|
+
- PR title: `type(scope): subject`.
|
|
10
|
+
- PR body: 40 lines at most, with these `##` headings in this order, empty ones dropped: `Why`, `What changed`, `Scope`, `Tradeoffs`, `Blast Radius`, `Verification`.
|
|
11
|
+
- Put evidence logs, run histories and long tables in a file or a PR comment, and link to them from the body.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-attack-the-premise
|
|
3
|
+
description: "Apply when two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before you write another fix that assumes it."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Attack the Premise
|
|
11
|
+
|
|
12
|
+
When two or more fixes that share one premise have failed the same gate, suspect the premise, not the fixes.
|
|
13
|
+
|
|
14
|
+
- Write the premise down: the one sentence every failed fix assumed.
|
|
15
|
+
- Test it before the next fix. Find an observation that would come out differently if the premise were false, and make it. Look at how the failures are distributed, not only at how large they are.
|
|
16
|
+
- If the evidence contradicts the premise, look for what the failures share that it did not predict. If one part always lands on the losing side, change what puts it there instead of adding a mechanism that cleans up after it.
|
|
17
|
+
|
|
18
|
+
Do not start the next fix before the premise is written down and tested.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-boundary-discipline
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Boundary Discipline
|
|
11
|
+
|
|
12
|
+
Validate, narrow types, and handle errors where data crosses a system boundary (CLI args, config files, external APIs, network). Inside, trust the types: no re-validation and no redundant nil checks. Parse raw data into domain types at the boundary, and keep transport and framework types out of the public surface. Business logic lives in pure functions with no framework dependencies. The shell that calls them is thin.
|
|
13
|
+
|
|
14
|
+
Two tests. Is this data crossing a boundary right now? If not, the validation is redundant. Can this be a pure function the shell just calls? If yes, extract it.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-build-the-lever
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Build the Lever
|
|
11
|
+
|
|
12
|
+
When the work isn't trivial, build the tool that does it (a codemod, script, generator, or rerunnable check) instead of doing it by hand. The bar is triviality, not repetition. Skip the tool only for a couple of obvious edits.
|
|
13
|
+
|
|
14
|
+
- Do the first unit by hand, then build the tool and prove it by rerunning it on that unit. Make it safe to rerun.
|
|
15
|
+
- A deterministic tool beats fan-out. When you do fan out, write the recipe, the verification contract, and the fences as one skill the delegates read and cannot edit.
|
|
16
|
+
- Applying this produces a file. No script, codemod, generator, or delegate skill in the diff means you didn't apply it. Commit it when the work outlives the session.
|
|
17
|
+
- Build the smallest script that does or proves the job, never a framework.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-encode-lessons-in-structure
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Encode Lessons in Structure
|
|
11
|
+
|
|
12
|
+
If the lesson needs judgment and cannot be encoded, make the instruction more prominent and add an example of the failure mode.
|
|
13
|
+
|
|
14
|
+
**Corollary:** If the fix is structural, only use the structural fix. The instruction is the symptom.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-exhaust-the-design-space
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Exhaust the Design Space
|
|
11
|
+
|
|
12
|
+
It also applies to product design decisions where user experience depends on feel, not logic.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-experience-first
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Experience First
|
|
11
|
+
|
|
12
|
+
When implementation convenience conflicts with user delight, choose delight.
|
|
13
|
+
|
|
14
|
+
- Every feature, control, and option must be justified
|
|
15
|
+
- Ship less, ship better (polished experience with three features beats rough one with ten)
|
|
16
|
+
- Prototype before committing (design decisions are cheaper in throwaway HTML than production code)
|
|
17
|
+
- Get the details right (transitions, alignment, spacing, feedback, error states)
|
|
18
|
+
- Tighten the core loop (every feature should serve the central workflow or get out of the way)
|
|
19
|
+
|
|
20
|
+
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 perspective.
|
|
21
|
+
|
|
22
|
+
Foundations should serve the experience. Foundational thinking governs the *sequence* of work. This principle governs the *target*.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-explain-the-number
|
|
3
|
+
description: "Apply before you measure, and before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Explain the Number
|
|
11
|
+
|
|
12
|
+
- **Write the decision before you run.** Name the result that would change it, and the noise floor. Stop when the run-to-run spread is larger than the effect.
|
|
13
|
+
- **Ask "why not double?"** Name the resource or code path that bounds the result, from a profile or counters taken during a run. A guess from reading the code is not a limiter.
|
|
14
|
+
- **List what else the number could be measuring** (errors, skipped or cached work, code that never ran, an untuned side, noise, a piece too small to matter) and rule out each one with evidence.
|
|
15
|
+
- **Keep the run count, the spread, and the limiter with the number.**
|
|
16
|
+
|
|
17
|
+
For a performance number, run the [benchmark-checklist](../benchmark-checklist/SKILL.md) skill. For an eval result, ask whether every run did the task, whether the gap holds across trials and models, and whether the scenario matters.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-fix-root-causes
|
|
3
|
+
description: "Apply when debugging. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Fix Root Causes
|
|
11
|
+
|
|
12
|
+
Fix the fault, not the place where it surfaced. The root cause is the first place the system did something it should not do, or failed to handle a state it should handle.
|
|
13
|
+
|
|
14
|
+
- Reproduce first. Ask "why" until the answer is a wrong decision in the code. When stuck, instrument and read the actual state.
|
|
15
|
+
- Ask whether the state that triggered the symptom is legitimate. If it is, handle it where the code broke. If it should never exist, a check there hides the bug, so find what produced it. Guards, retries, swallowed errors, clamped values, and discarded state are the usual ways to hide a bug.
|
|
16
|
+
- Fix the pattern, not the instance. Find every place with the same fault.
|
|
17
|
+
- If the deciding fact took a deep dig, propose the cheap, always-on signal that would have shown it at first look.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-foundational-thinking
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Foundational Thinking
|
|
11
|
+
|
|
12
|
+
Get the data shape right before writing logic. Define core types early, trace every access pattern, and choose structures that match the dominant paths. DRY the structure, not every line.
|
|
13
|
+
|
|
14
|
+
Before sharing state between actors, ask what happens if another actor modifies it concurrently. If the answer is not "nothing", isolate.
|
|
15
|
+
|
|
16
|
+
Scaffold first. Whatever helps every later phase (CI, tests, shared types) goes first, after removing dead code. Keep commits small and single-purpose.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-guard-the-context-window
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Guard the Context Window
|
|
11
|
+
|
|
12
|
+
**Why:** Context overflow degrades reasoning quality, creates compression artifacts, and halts progress.
|
|
13
|
+
|
|
14
|
+
**Pattern:**
|
|
15
|
+
- **Size phases and cap scope.** Limit files per phase, set turn budgets, account for mechanism costs.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-laziness-protocol
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Laziness Protocol
|
|
11
|
+
|
|
12
|
+
- **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.
|
|
13
|
+
- **Minimize the diff.** Make the smallest change that solves the problem. Fewer lines beat "elegant" boilerplate.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-make-operations-idempotent
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Make Operations Idempotent
|
|
11
|
+
|
|
12
|
+
Design every state-changing operation to converge to the correct state however many times it runs and wherever the previous run stopped.
|
|
13
|
+
|
|
14
|
+
Derive each step from the state that exists, not from what the previous run meant to do. Read the current state, compare it to the goal, and apply only the difference.
|
|
15
|
+
|
|
16
|
+
Anything a run leaves behind (a lock, a temporary file, a half-written record, a claimed job) must be recognizable as stale by the next run, by evidence that holds wherever the previous run could have stopped. Write to a temporary path and rename it into place.
|
|
17
|
+
|
|
18
|
+
The test: what happens if this runs twice? What if the previous run crashed at every possible point? If the answer depends on what was left behind, add a reconciliation step.
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-migrate-callers-then-delete-legacy-apis
|
|
3
|
+
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."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Migrate Callers Then Delete Legacy APIs
|
|
11
|
+
|
|
12
|
+
- Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details
|
|
13
|
+
|
|
14
|
+
**When this applies:**
|
|
15
|
+
- No external users depend on backward compatibility
|
|
16
|
+
- The project can absorb coordinated breaking changes
|
|
17
|
+
- The new API is part of a simplification or refactor initiative
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-minimize-reader-load
|
|
3
|
+
description: "Apply when reviewing or shaping code that's hard to trace. Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Minimize Reader Load
|
|
11
|
+
|
|
12
|
+
Reader load is the work a reader must do to understand code. It has two independent axes: layers to trace between the question and the answer, and hidden or mutable state to hold in their head. Guard both.
|
|
13
|
+
|
|
14
|
+
- Collapse layers that only forward: wrappers with one caller, adapters with no second implementation, pass-through methods. Inline them.
|
|
15
|
+
- Shrink state scope: returns over mutations, locals over fields, fields over module state, module state over globals. Derive instead of sync.
|
|
16
|
+
- Name an invariant once at the boundary, not in every consumer.
|
|
17
|
+
|
|
18
|
+
The test: can a new reader answer "where does X come from?" and "what can change X?" in under 30 seconds? If not, cut layers or cut state.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-model-the-domain
|
|
3
|
+
description: "Apply when writing stateful logic, or when code branches a lot or repeats a shape assumption across files."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Model the Domain
|
|
11
|
+
|
|
12
|
+
Encode the domain in a data structure instead of scattering it across conditionals. The right structure makes invalid states unrepresentable and deletes branches.
|
|
13
|
+
|
|
14
|
+
Reach for a state machine instead of scattered booleans or phase checks, a typed model instead of loose parameters, a map, registry, or discriminated union instead of branching spread across files, a reducer instead of ad hoc mutations, and an index, queue, or normalized collection where the access pattern calls for it.
|
|
15
|
+
|
|
16
|
+
Do not force it. Keep boring code when the shape is clear, local, and unlikely to grow, and distrust an abstraction that adds indirection without removing branches or invalid states.
|
|
17
|
+
|
|
18
|
+
The sign that you skipped this: a feature that grows an if/else chain by one more branch, or a second boolean that must stay in sync with the first.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-never-block-on-the-human
|
|
3
|
+
description: "Apply when tempted to ask 'should I do X?' on reversible work."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Never Block on the Human
|
|
11
|
+
|
|
12
|
+
The human supervises asynchronously. Agents must stay unblocked. Make reasonable decisions, proceed, and let the human course-correct after the fact. Since code changes are reversible and reviewable, a wrong decision usually costs less than blocking.
|
|
13
|
+
|
|
14
|
+
- Proceed, then present. Do the work, show the result. Don't ask "should I do X?" Do X, explain why.
|
|
15
|
+
- Make the system self-healing. When you notice a problem, log it and fix it in the next round.
|
|
16
|
+
- Irreversible actions (force-push, delete production data, send external messages) still require confirmation.
|
|
17
|
+
- Reversible actions (write code, edit notes, split tasks) should proceed without blocking.
|
|
18
|
+
- Product direction comes from the human. Execution should not block.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-outcome-oriented-execution
|
|
3
|
+
description: "Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Outcome-Oriented Execution
|
|
11
|
+
|
|
12
|
+
Optimize for the intended, verifiable end state rather than preserving smooth intermediate states.
|
|
13
|
+
|
|
14
|
+
**Why:** Keeping every intermediate step fully stable often creates temporary compatibility code that becomes long-lived debt. Converge on the target architecture and prove correctness at explicit verification boundaries.
|
|
15
|
+
|
|
16
|
+
**Core rule:**
|
|
17
|
+
- Prioritize end-state integrity over transitional stability
|
|
18
|
+
- Intermediate breakage is acceptable when it is planned, scoped, and reversible
|
|
19
|
+
|
|
20
|
+
**Guardrails:**
|
|
21
|
+
- Use this for planned rewrites and migrations with explicit phase boundaries
|
|
22
|
+
- Declare where temporary breakage is acceptable
|
|
23
|
+
- Keep high-signal checks for actively touched areas while migrating
|
|
24
|
+
- Require full static and runtime verification at plan completion
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-prove-it-works
|
|
3
|
+
description: "Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'"
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Prove It Works
|
|
11
|
+
|
|
12
|
+
Verify every output by checking the real thing directly: run the feature, read the actual value, inspect the diff. Proxies (file mtimes, self-reports, cached output, "it compiles") do not count. When a check fails, suspect the observation method before the system.
|
|
13
|
+
|
|
14
|
+
Script the check when you can. A deterministic script that reruns the comparison beats a one-time look. Keep its output where the human can see it, and commit it only when the trail must be auditable later.
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-redesign-from-first-principles
|
|
3
|
+
description: "Apply when integrating a new requirement into an existing design."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Redesign From First Principles
|
|
11
|
+
|
|
12
|
+
When integrating a change, don't bolt it onto the existing design. Redesign as if the requirement had been a foundational assumption from the start.
|
|
13
|
+
|
|
14
|
+
- Read all affected files and understand the current design
|
|
15
|
+
- Ask: "if we were writing this from scratch with this new requirement, what would we build?"
|
|
16
|
+
- Propagate the change through every reference: types, docs, examples, rationale sections
|
|
17
|
+
- Think about the whole redesign, then deliver it incrementally
|
|
18
|
+
|
|
19
|
+
This is the method for preserving option value when integrating changes into an existing design.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-separate-before-serializing-shared-state
|
|
3
|
+
description: "Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Separate Before Serializing Shared State
|
|
11
|
+
|
|
12
|
+
When concurrent actors might write the same file, branch, key, or object, first ask whether they need one shared object or are publishing independent facts. Default to giving each actor its own file, key, branch, or state directory, and merge only where the state is read. Two workers writing their own field into one `state.json` is still shared mutation.
|
|
13
|
+
|
|
14
|
+
Only when one shared write target is a real invariant, serialize access structurally (a lockfile, a single writer, sequential phases, compare-and-swap). Instructions are not concurrency control, and "we need a lock" is a smell to check first.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-sequence-verifiable-units
|
|
3
|
+
description: "Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Sequence work into verifiable units
|
|
11
|
+
|
|
12
|
+
Order work as small units that each end in a state you can check, and do not advance until the current one is green.
|
|
13
|
+
|
|
14
|
+
In a sweep, migration, or run of similar edits, each unit is a bracket: known-good state, one change, run the check, proceed. Run the per-unit check even when a tool does the edits.
|
|
15
|
+
|
|
16
|
+
Deliver in the order that proves the work: the failing test first, then the fix. The subtraction before the reshape. The baseline before the treatment. Each commit lands on its own.
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-subtract-before-you-add
|
|
3
|
+
description: "Apply when sequencing an addition, refactor, or rewrite. Remove dead code, redundant validators, and stub references first, then build on the simpler base."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Subtract Before You Add
|
|
11
|
+
|
|
12
|
+
When evolving a system, remove complexity first, then build. Default to subtraction.
|
|
13
|
+
|
|
14
|
+
Make simplification a continual investment. Leave the design slightly simpler and more capable behind the same or smaller surface than you found it.
|
|
15
|
+
|
|
16
|
+
- Sequence removal before construction
|
|
17
|
+
- Cut before you polish (get to the minimum before investing in quality)
|
|
18
|
+
- Design for observed usage, not speculative edge cases
|
|
19
|
+
- No speculative validators, parsers, or guards beyond what the spec demands
|
|
20
|
+
- Simplify prompts (remove redundant instructions, excessive templates)
|
|
21
|
+
- When a reference has no novel content, delete it rather than leaving a stub
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-test-behavior-not-implementation
|
|
3
|
+
description: "Apply when you write, change, or keep a test. Assert what the code's users can observe, so that the test fails when that behavior breaks and keeps passing when only the internals change."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Test Behavior, Not Implementation
|
|
11
|
+
|
|
12
|
+
A test is a claim about what users of the code can observe through its interface: return values, errors, state they can read back, and effects on outside systems. Private helpers, internal call order, and intermediate data are implementation.
|
|
13
|
+
|
|
14
|
+
Judge each test against two imagined edits:
|
|
15
|
+
|
|
16
|
+
- **Break the behavior** (a wrong value, a skipped or doubled effect). If the test still passes, it proves nothing. The usual causes are a loose assertion, an expected value computed by the code under test, and an assertion on data the test built itself.
|
|
17
|
+
- **Change the internals** and keep every observable result. If the test fails, it is pinned to the implementation.
|
|
18
|
+
|
|
19
|
+
Keep a test that catches the first edit and survives the second. Rewrite or delete the rest. Drive the code through its public interface with a concrete input, and derive the expected value from the requirement. What an external service receives is behavior. A call to an internal helper is not. Pair "this never happens" with a case where it does happen. Assert the error type that callers branch on, not the message.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principle-type-system-discipline
|
|
3
|
+
description: "Apply when designing types, reviewing a function signature, or writing code in any statically-typed language. Make illegal states unrepresentable, brand semantic primitives, parse external data at boundaries, exhaust variants, derive from authoritative schemas."
|
|
4
|
+
disable-model-invocation: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
> On Pi, read `harness/pi.md` at this package's root before acting, and map every Cursor name it lists (`Task`, model slugs, `.cursor` paths) onto Pi.
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
# Type System Discipline
|
|
11
|
+
|
|
12
|
+
Make the compiler reject impossible states, mismatched primitives, and unhandled variants.
|
|
13
|
+
|
|
14
|
+
- **Brand semantic primitives.** If two arguments share a primitive type but mean different things, give each its own type. Validate once at creation.
|
|
15
|
+
- **External data is untyped until parsed.** JSON, RPC payloads, CLI args, config, environment variables, and database rows go through a parse function at the boundary that returns the typed model.
|
|
16
|
+
- **Derive types from authoritative schemas.** When a schema file owns a shape, derive the type from it instead of hand-rolling a parallel one.
|
|
17
|
+
|
|
18
|
+
For TypeScript syntax, see the **typescript-best-practices** skill.
|