Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion skills
Submodule skills updated 59 files
+1 −1 README.md
+55 −0 docs/TREE.md
+2 −2 skills/raea/3d.md
+5 −0 skills/raea/3d/NOTICE
+26 −3 skills/raea/SKILL.md
+27 −0 skills/raea/apps.md
+29 −0 skills/raea/collaborate.md
+26 −0 skills/raea/craft/NOTICE
+101 −0 skills/raea/craft/ROUTER.md
+75 −0 skills/raea/craft/floor.md
+38 −0 skills/raea/craft/modes/explain.md
+32 −0 skills/raea/craft/modes/pitch.md
+31 −0 skills/raea/craft/modes/play.md
+36 −0 skills/raea/craft/modes/story.md
+30 −0 skills/raea/craft/modes/tool.md
+52 −0 skills/raea/craft/rubric.md
+21 −0 skills/raea/craft/verbs/adapt.md
+21 −0 skills/raea/craft/verbs/animate.md
+18 −0 skills/raea/craft/verbs/bolder.md
+18 −0 skills/raea/craft/verbs/clarify.md
+19 −0 skills/raea/craft/verbs/critique.md
+18 −0 skills/raea/craft/verbs/delight.md
+17 −0 skills/raea/craft/verbs/distill.md
+20 −0 skills/raea/craft/verbs/extract.md
+20 −0 skills/raea/craft/verbs/generate.md
+17 −0 skills/raea/craft/verbs/harden.md
+20 −0 skills/raea/craft/verbs/layout.md
+19 −0 skills/raea/craft/verbs/optimize.md
+13 −0 skills/raea/craft/verbs/polish.md
+22 −0 skills/raea/craft/verbs/quieter.md
+18 −0 skills/raea/craft/verbs/recut.md
+19 −0 skills/raea/craft/verbs/regrade.md
+19 −0 skills/raea/craft/verbs/remix.md
+18 −0 skills/raea/craft/verbs/retime.md
+20 −0 skills/raea/craft/verbs/typeset.md
+24 −0 skills/raea/delivery.md
+34 −0 skills/raea/footage.md
+31 −0 skills/raea/games.md
+26 −0 skills/raea/gen.md
+30 −0 skills/raea/graphics.md
+109 −0 skills/raea/motion.md
+148 −0 skills/raea/motion/3d.md
+111 −0 skills/raea/motion/animating.md
+38 −0 skills/raea/motion/apps.md
+75 −0 skills/raea/motion/assets.md
+120 −0 skills/raea/motion/brand.md
+79 −0 skills/raea/motion/compositions.md
+132 −0 skills/raea/motion/footage.md
+142 −0 skills/raea/motion/games.md
+74 −0 skills/raea/motion/gen.md
+95 −0 skills/raea/motion/layout.md
+200 −0 skills/raea/motion/music.md
+103 −0 skills/raea/motion/parts.md
+102 −0 skills/raea/motion/placement.md
+57 −0 skills/raea/motion/rendering.md
+146 −0 skills/raea/motion/sound.md
+123 −0 skills/raea/motion/timing.md
+117 −0 skills/raea/motion/words.md
+33 −0 skills/raea/sound.md
92 changes: 75 additions & 17 deletions tools/skills.sh
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,10 @@
# links these instead of repeating them, so a verb, a flag, a feed tool or an export changes its reference in the
# same commit.
#
# tools/skills.sh gen write skills/skills/raea/reference/{cli,feed,files,sdk,app}.md, and copy the Bevy craft guides
# (sdk/guides/craft/bevy/*.md) into skills/skills/raea/3d/ as its 3D topic files, so a clone of
# raea-skills reads whole without raea; commit both in raea-skills, then the pointer here
# tools/skills.sh gen write skills/skills/raea/reference/{cli,feed,files,sdk,app}.md, and copy the craft guides
# (sdk/guides/craft, what `raea guide` prints) into the skill (copies() below: bevy/ as 3d/,
# motion.md and motion/, and the router, floor, rubric, modes/ and verbs/ under craft/), so a
# clone of raea-skills reads whole without raea; commit them in raea-skills, then the pointer here
# tools/skills.sh check the drift gate (SK3, in L0): fails on a stale reference, a retired word, a flag a verb
# doesn't take, a RAEA_* variable nothing reads, or a relative link that goes nowhere, each
# with its file, line and fix. engine/cli/conformance/surface.test.ts checks the verbs and
Expand All @@ -19,6 +20,8 @@
# build of this tree, so its help is the truth and every difference fails.
# tools/skills.sh check-cli cli.md against RAEA_BIN's help alone, with no feed app: tools/release.sh on a public
# checkout, where RAEA_BIN is the release's own build
# tools/skills.sh coverage each verb, SDK entry and feed tool, and how many a guide or the skill teaches (coverage() below);
# check warns on each one untaught
# tools/skills.sh stale every section with sources, by how many commits to them it has missed since it last changed
#
# Sources: cli.md from `raea help --json` (engine/cli/src/usage.rs); feed.md from FEED_TOOLS (apps/app
Expand All @@ -33,7 +36,23 @@ ROOT=$(cd "$(dirname "$0")/.." && pwd)
cd "$ROOT"
SK=skills/skills
OUT=${SKILLS_OUT:-$SK/raea/reference}
BEVY_OUT=${SKILLS_BEVY_OUT:-$SK/raea/3d}
# where gen-into puts the copied guides (copies() names them relative to it): the skill itself, or a scratch folder
COPY_OUT=${SKILLS_COPY_OUT:-$SK/raea}
# the guides the skill carries, each as SOURCE<TAB>COPY (COPY relative to the skill): `raea guide NAME` prints the source,
# and the skill's routers (3d.md, and one per domain in raea-skills) link the copy. Skill-only files beside the copies
# (3d/plugins.md, 3d/rows.md) aren't listed.
copies() {
local g
for g in sdk/guides/craft/bevy/*.md sdk/guides/craft/bevy/NOTICE; do printf '%s\t3d/%s\n' "$g" "${g##*/}"; done
printf '%s\tmotion.md\n' sdk/guides/craft/motion.md
for g in sdk/guides/craft/motion/*.md; do printf '%s\tmotion/%s\n' "$g" "${g##*/}"; done
for g in ROUTER.md floor.md rubric.md NOTICE; do printf '%s\tcraft/%s\n' "sdk/guides/craft/$g" "$g"; done
for g in sdk/guides/craft/modes/*.md; do printf '%s\tcraft/modes/%s\n' "$g" "${g##*/}"; done
for g in sdk/guides/craft/verbs/*.md; do printf '%s\tcraft/verbs/%s\n' "$g" "${g##*/}"; done
}
# the folders whose every file is a copy (a file there with no source is one whose guide was removed or renamed)
COPY_DIRS="3d motion craft craft/modes craft/verbs"
SKILL_ONLY="3d/plugins.md 3d/rows.md"
HEAD_LINE="<!-- generated by tools/skills.sh gen; do not edit -->"
APP=${RAEA_APP:-apps/app}
# check-cli reads only raea's help, so it runs where the feed app isn't (a public checkout: release.yml's runners)
Expand Down Expand Up @@ -205,6 +224,34 @@ help_stale() {
[ -n "$newest" ] && [ "$built" -lt "$newest" ]
}

# Surface coverage (raea-skills docs/TREE.md): each verb in raea's help, each SDK entry (sdk/raea/src) and each feed tool,
# with whether a guide or the skill teaches it outside the generated reference (texts(): sdk/guides/craft and the skill's
# own files, not reference/). A row is KIND<TAB>NAME<TAB>taught|untaught|skip. The reference lists everything; coverage
# asks whether anything says when and how to use it. COVERAGE_SKIP names what an agent never runs, each with why.
COVERAGE_SKIP="verb:hook (raea skills install sets it up; an agent never runs it)
verb:traces (raea's own session logs, for whoever debugs raea)
module:dev_tools (raea's own debugging overlays)
module:test (raea's test harness, for raea's own tests)"
coverage() {
local corpus v m t f; corpus=$(mktemp "${TMPDIR:-/tmp}/skills-cov.XXXXXX")
texts | while read -r f; do cat "$f"; echo; done > "$corpus"
row() { # KIND NAME PATTERN (an extended regex)
if printf '%s\n' "$COVERAGE_SKIP" | grep -q "^$1:$2 "; then printf '%s\t%s\tskip\n' "$1" "$2"
elif grep -qE "$3" "$corpus"; then printf '%s\t%s\ttaught\n' "$1" "$2"
else printf '%s\t%s\tuntaught\n' "$1" "$2"; fi
}
if [ "${stale_help:-0}" != 1 ]; then
for v in $("$R" help --json | jq -r '.verbs[].verb' | sort -u); do row verb "$v" "raea $v([^a-z_-]|\$)"; done
fi
for f in sdk/raea/src/*.ts sdk/raea/src/*.tsx; do
m=${f##*/}; m=${m%.tsx}; m=${m%.ts}
case $m in index | prelude | pure | native-calls | *.gen) continue ;; esac
row module "$m" "raea/$m([^a-z_-]|\$)"
done
for t in $(gen_feed | sed -n 's/^## //p'); do row tool "$t" "(^|[^a-z_])$t([^a-z_]|\$)"; done
rm -f "$corpus"
}

check() {
local fail=0 tmp; tmp=$(mktemp -d "${TMPDIR:-/tmp}/skills-check.XXXXXX")
[ -f "$SK/raea/SKILL.md" ] || { echo "FAIL skills: $SK/raea/SKILL.md:1: missing; fix: git submodule update --init skills (raea-skills, at the commit raea pins)"; rm -rf "$tmp"; return 1; }
Expand All @@ -213,7 +260,7 @@ check() {
echo "skills: note $R is older than the help's sources; cli.md and the flags aren't checked (rebuild raea-cli)"
fi
local stale_help=0; help_stale && stale_help=1
SKILLS_OUT=$tmp/ref SKILLS_BEVY_OUT=$tmp/bevy R=$R SKIP_CLI=$stale_help "$0" gen-into >/dev/null || { echo "FAIL skills: tools/skills.sh gen failed"; rm -rf "$tmp"; return 1; }
SKILLS_OUT=$tmp/ref SKILLS_COPY_OUT=$tmp/copies R=$R SKIP_CLI=$stale_help "$0" gen-into >/dev/null || { echo "FAIL skills: tools/skills.sh gen failed"; rm -rf "$tmp"; return 1; }
for f in cli feed files sdk app; do
[ "$f" = cli ] && [ $stale_help = 1 ] && continue
if ! diff -q "$tmp/ref/$f.md" "$SK/raea/reference/$f.md" >/dev/null 2>&1; then
Expand All @@ -234,21 +281,27 @@ check() {
fi
fi
done
# the 3D topic files (raea/3d/): copies of the Bevy craft guides, so raea-skills reads whole on its own (and on GitHub)
local g c
for g in sdk/guides/craft/bevy/*.md; do
c=$SK/raea/3d/${g##*/}
cmp -s "$g" "$c" && continue
# the guides the skill carries (copies()): each a copy of its source, and no copy left whose guide is gone, so raea-skills
# reads whole on its own (and on GitHub) and says what `raea guide` says
local g c d
while IFS=$'\t' read -r g c; do
cmp -s "$g" "$SK/raea/$c" && continue
if [ "$(git symbolic-ref -q HEAD 2>/dev/null)" = refs/heads/gitbutler/workspace ]; then
echo "skills: warning $c differs from $g (other lanes' code is applied here; L1's export decides)"
echo "skills: warning $SK/raea/$c differs from $g (other lanes' code is applied here; L1's export decides)"
else
echo "FAIL skills: $c:1: isn't a copy of $g; fix: tools/skills.sh gen, and commit it in raea-skills, then the pointer"; fail=1
echo "FAIL skills: $SK/raea/$c:1: isn't a copy of $g; fix: tools/skills.sh gen, and commit it in raea-skills, then the pointer"; fail=1
fi
done < <(copies)
for d in $COPY_DIRS; do
for c in "$SK/raea/$d"/*; do
[ -f "$c" ] || continue
c=${c#"$SK/raea/"}
case " $SKILL_ONLY " in *" $c "*) continue ;; esac
copies | cut -f2 | grep -qxF "$c" || { echo "FAIL skills: $SK/raea/$c:1: copies a guide that's gone; fix: delete it in raea-skills, or name the guide that replaced it"; fail=1; }
done
done
for c in "$SK"/raea/3d/*.md; do
case ${c##*/} in plugins.md | rows.md) continue ;; esac
[ -f "sdk/guides/craft/bevy/${c##*/}" ] || { echo "FAIL skills: $c:1: copies sdk/guides/craft/bevy/${c##*/}, which is gone; fix: delete it in raea-skills, or name the guide that replaced it"; fail=1; }
done
# surface coverage: a warning per verb, SDK entry or feed tool nothing teaches yet (tools/skills.sh coverage lists all)
coverage | awk -F'\t' -v sk="$SK/raea" '$3 == "untaught" { k = $1 == "verb" ? "raea " $2 : $1 == "module" ? "raea/" $2 : "the feed tool " $2; print "skills: coverage: " k " is in raea, but no guide or router says when to use it; fix: teach it in the router for its domain (" sk "/DOMAIN.md) or its guide (sdk/guides/craft), or add it to COVERAGE_SKIP with why" }'
# 2. retired words (docs/skills.glossary.md), whole words where they start with a letter
local words g=${RAEA_GLOSSARY:-docs/skills.glossary.md} # the glossary is the maintainers' (private); without it, no retired words
words=$( [ -f "$g" ] && sed -n '/<!-- retired -->/,/<!-- \/retired -->/p' "$g" | sed '1d;$d' || true )
Expand Down Expand Up @@ -361,14 +414,19 @@ case "${1:-}" in
gen_files > "$OUT/files.md"
gen_sdk > "$OUT/sdk.md"
gen_app > "$OUT/app.md"
mkdir -p "$BEVY_OUT" && cp sdk/guides/craft/bevy/*.md "$BEVY_OUT/"
copies | while IFS=$'\t' read -r g c; do mkdir -p "$COPY_OUT/$(dirname "$c")" && cp "$g" "$COPY_OUT/$c"; done
if [ "$1" = gen ]; then wc -l "$OUT"/*.md; fi
;;
check)
R=$(raea_bin)
[ -x "$R" ] || { echo "FAIL skills: no raea to read the help from (RAEA_BIN, or build raea-cli)"; exit 1; }
check
;;
coverage)
R=$(raea_bin)
[ -x "$R" ] || { echo "skills.sh: no raea to read the help from (RAEA_BIN, or build raea-cli)" >&2; exit 2; }
coverage | awk -F'\t' '{ n[$1]++; if ($3 == "untaught") { u[$1]++; l[$1] = l[$1] " " $2 } } END { for (k in n) printf "%-7s %3d of %3d taught%s\n", k, n[k] - u[k], n[k], u[k] ? "; untaught:" l[k] : "" }' | sort
;;
check-cli)
R=$(raea_bin)
[ -x "$R" ] || { echo "FAIL skills: no raea to read the help from (RAEA_BIN, or build raea-cli)"; exit 1; }
Expand Down
Loading