@litfamily/litgravity 0.1.9 → 0.1.11
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/CHANGELOG.md +26 -0
- package/README.md +153 -132
- package/README_ko-KR.md +154 -133
- package/bin/litgravity.mjs +17 -2
- package/lib/agent-file.mjs +9 -7
- package/lib/doctor.mjs +11 -3
- package/lib/extension-manager.mjs +641 -0
- package/lib/install.mjs +5 -2
- package/lib/list.mjs +5 -2
- package/package.json +1 -1
- package/plugin/hooks/lib/auto-handoff.mjs +107 -0
- package/plugin/hooks/lib/common.mjs +1 -1
- package/plugin/hooks/lib/extensions.mjs +13 -8
- package/plugin/hooks/lib/reentry.mjs +2 -2
- package/plugin/hooks/lib/routes.mjs +28 -2
- package/plugin/hooks/lib/shown.mjs +65 -0
- package/plugin/hooks/lib/transcript.mjs +20 -0
- package/plugin/hooks/session-start.mjs +26 -14
- package/plugin/hooks/stop.mjs +5 -0
- package/plugin/plugin.json +1 -1
- package/plugin/rules/AGENTS.md +1 -1
- package/plugin/skills/autoresearch/references/visualization-guide.md +5 -2
- package/plugin/skills/frontend-ui-ux/SKILL.md +20 -7
- package/plugin/skills/lit-diagram-drawer/SKILL.md +21 -8
- package/plugin/skills/lit-docx/SKILL.md +21 -8
- package/plugin/skills/lit-pptx/SKILL.md +21 -8
- package/plugin/skills/lit-schematic/SKILL.md +21 -8
- package/plugin/skills/lit-scientific-visualization/SKILL.md +21 -8
- package/plugin/skills/lit-typographic-motion/SKILL.md +21 -8
- package/plugin/skills/readme-studio/SKILL.md +21 -8
- package/plugin/skills/visual-qa/SKILL.md +20 -7
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,31 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.1.11 — 2026-11-16
|
|
4
|
+
|
|
5
|
+
- The handoff is saved for you. agy has no compaction event, so the Stop hook now writes `.litgravity/handoff/auto.md` at every turn end of a conversation a lit route has touched (the last request, the next plan row, the open goal criterion, the tail of the last reply; credentials redacted), and a new conversation's SessionStart carries the newest of that note and `latest.md` whole instead of only pointing at `latest.md`. It is on by default; `LITGRAVITY_AUTO_HANDOFF=0` turns both halves off and restores the pointer.
|
|
6
|
+
- A notice is no longer repeated in a project that already saw it. The update notice (per release), the extensions notice and the `lit adhd` nudge are recorded in `.litgravity/shown/notices.jsonl`; a missing or corrupt record shows them as before. The same file gets one `run-end` line (`waiting`, `nothing` or `sent`) when a start-work, lit-loop or litgoal turn ends.
|
|
7
|
+
|
|
8
|
+
## 0.1.10 — 2026-11-14
|
|
9
|
+
|
|
10
|
+
- New `litgravity extensions` command, so the four install lines no longer have to be pasted by hand. It writes nothing until you add `--yes`; without it, it prints which folder moves where.
|
|
11
|
+
- `extensions install <id...>` (or `--family <name>`, `--all`; `--project` for `.agents/skills`) looks for another skill with the same name in every folder agy 1.5.6 loads and stops, naming its path, when there is one (`--allow-shadow` installs anyway and only warns). It moves an existing copy whole into `~/.gemini/extension-backups/<stamp>[-project]/<id>`, copies the skill in through a temporary folder so a failed copy changes nothing, and writes the receipt. The temporary folder sits outside every folder agy loads (`~/.gemini/extension-backups/.staging` for user scope, `.agents/.litgravity-staging` beside a workspace's `skills/`), so a copy cut short by Ctrl-C never appears as a second skill with the same name; if the last step fails, the old copy is put back and the ids already installed are named. The receipt keeps the four keys of the hand lines and adds `scope`, `hash`, `files`, `source_commit` and `installed_by`.
|
|
12
|
+
- The source is a clone you name with `--from <path>`, or LitGravity's own shallow, sparse clone of `variants/litgravity` in `~/.cache/litgravity/extensions-src` (`$XDG_CACHE_HOME`). When git is missing or the network is down, it stops before any write and points at `--from`.
|
|
13
|
+
- `extensions update [<id...>]` fetches the source and reinstalls only the extensions whose files changed; the rest are reported as current. When a planned copy stops, no receipt is touched. A dry run compares with the cached copy without fetching and says so. Naming an id that is not installed exits 1. A receipt written by the hand lines has no hash, so update compares with the installed files instead.
|
|
14
|
+
- `extensions remove <id...>` moves a copy LitGravity installed into the backups and refuses a folder without its receipt, naming the path.
|
|
15
|
+
- `extensions list [--json]` shows each of the nine as installed (with receipt), not installed, user-managed, or shadowed by and competing with a same-name skill elsewhere. `extensions check [--json]` changes nothing. It reports duplicates, copies without a receipt, receipts whose source is gone, a plugin copy that still carries a full old skill, and the backups with their total size, and prints the fix for each; it exits 1 when something needs action.
|
|
16
|
+
- `extensions prune-backups [--older-than <days>]` lists the backups with their sizes and deletes only with `--yes`, only inside `~/.gemini/extension-backups/`.
|
|
17
|
+
- The nine stubs, the extensions notice, the router note, `litgravity list`, `help`, both READMEs and doctor name the command first and keep the four lines as the manual route. Doctor adds an `extensions` row with the `check` summary. When an install or update finds something for `check` (an old copy without a receipt, a duplicate), the extensions notice gets one more line pointing at `extensions check`; nothing changes on its own.
|
|
18
|
+
- Installing an extension over a folder that is already there is safe now. The stubs, both READMEs, the post-install extensions note, the router note, `litgravity list`, `doctor` and the autoresearch figure guide all give the same four lines, for user scope (`~/.gemini/config/skills`) and for one workspace (`.agents/skills`), pasted one at a time in zsh or bash:
|
|
19
|
+
1. A read-only `find` that prints the `SKILL.md` of every skill with that name in the four folders agy 1.5.6 loads bare skills from: a workspace's `.agents/skills` and `_agents/skills`, then `~/.gemini/config/skills` and `~/.gemini/skills`. agy keeps one same-name skill without a word, a workspace copy first, so a second copy anywhere there would shadow the extension.
|
|
20
|
+
2. When the destination exists, a move of the whole folder into `~/.gemini/extension-backups/<YYYYmmdd-HHMMSS>/<id>` (`…-project/<id>` for a workspace copy), a folder agy never scans. Your own files in the old copy stay there intact. An `<id>.bak` folder beside the skill would be loaded as a second skill with the same name, and agy may prefer it, so no line ever writes one.
|
|
21
|
+
3. A `cp -R` into the emptied `<dest>/<id>`, guarded so it never copies over a folder that is still there (the old line copied into `<dest>/`, which mixed the new files into an old copy and left its stale files in place).
|
|
22
|
+
4. A receipt, `<dest>/<id>/.litfamily-extension.json`, holding `id`, `source`, `variant` and `installed_at`. agy ignores the dot-file.
|
|
23
|
+
|
|
24
|
+
To update, run the same lines again; to remove, run the second line alone. Nothing deletes. LitGravity's own install and update still write only the plugin folder, so they leave the extension and its receipt alone.
|
|
25
|
+
- When the global rule file `~/.gemini/config/rules/litgravity.md` holds text LitGravity did not write, or was edited, the refusal used to suggest moving it to `litgravity.md.saved-<date>` inside agy's rules folder, which agy and its agent read. It now suggests `~/.local/share/litgravity/saved/rules-litgravity-<time>.md` (`$XDG_DATA_HOME/litgravity/saved/`), outside every folder agy reads.
|
|
26
|
+
- The nine stub budgets in `skills.lock.json` grew to fit the new lines (7,000-byte ceiling, 4,800-byte floor).
|
|
27
|
+
- Both READMEs are shorter and easier to scan. The status line, hand install, agent prompt and limit details moved to `docs/reference.md` (and `docs/reference_ko-KR.md`), run-on paragraphs are split, Quick start points at Install, and the update line is there.
|
|
28
|
+
|
|
3
29
|
## 0.1.9 — 2026-11-11
|
|
4
30
|
|
|
5
31
|
LitGravity is now the LitFamily core for agy, complete on its own. The nine skills that make files became LitFamily extensions, kept on the extension shelf at https://github.com/wjgoarxiv/wjgoarxiv-skills, so a LitGravity install stays small; install the ones you use alongside LitGravity for the full LitFamily experience. Their ids, route words and `/litgravity:<id>` forms still work, and each one now answers with a short stub that says it is a LitFamily extension and how to install it.
|
package/README.md
CHANGED
|
@@ -12,7 +12,10 @@
|
|
|
12
12
|
<a href="https://github.com/wjgoarxiv/litgravity/stargazers"><img src="https://img.shields.io/github/stars/wjgoarxiv/litgravity?style=flat" alt="GitHub stars" /></a>
|
|
13
13
|
</p>
|
|
14
14
|
|
|
15
|
-
<p align="center"><a href="#install"><img src="./docs/assets/readme/icon-book.svg" width="16" alt="" /> Install</a> <a href="#demo"><img src="./docs/assets/readme/icon-play.svg" width="16" alt="" /> Demo</a> <a href="#safety-and-uninstall"><img src="./docs/assets/readme/icon-shield.svg" width="16" alt="" />
|
|
15
|
+
<p align="center"><a href="#install"><img src="./docs/assets/readme/icon-book.svg" width="16" alt="" /> Install</a> <a href="#demo"><img src="./docs/assets/readme/icon-play.svg" width="16" alt="" /> Demo</a> <a href="#safety-and-uninstall"><img src="./docs/assets/readme/icon-shield.svg" width="16" alt="" /> Update & remove</a> <a href="#quick-start">Quick start</a> <a href="#what-you-can-make">What you can make</a> <a href="#what-you-get">What you get</a> <a href="#what-agy-limits-today">agy limits</a> <a href="./README_ko-KR.md">한국어</a></p>
|
|
16
|
+
|
|
17
|
+
> [!TIP]
|
|
18
|
+
> One npm command installs LitGravity as an agy plugin ([Install](#install)). Then start any agy prompt with `lit`, as [Quick start](#quick-start) shows.
|
|
16
19
|
|
|
17
20
|
## Demo
|
|
18
21
|
|
|
@@ -20,23 +23,12 @@ What ignition looks like, captured from the real hook and status line on this Ma
|
|
|
20
23
|
|
|
21
24
|
<!-- demo-gif --><p align="center"><img src="./docs/assets/litgravity/demo-ignition.webp" width="960" alt="Terminal capture. The prompt reads lit add a --shout flag that prints the greeting in capitals, with a test. The hook answers with the LIT mark and LIT IGNITED · lit-loop, names the lit-loop skill file to read first, and notes that tool events go to the conversation ledger. Below, the status line shows the model, the context gauge at 42 percent, the lit-loop chip with its clock, and the PIN through RECORD map with PIN lit." /></p>
|
|
22
25
|
|
|
23
|
-
##
|
|
24
|
-
|
|
25
|
-
Each picture is a real output made on this Mac. The `lit-adhd` brief was drawn by its collector over three real agy conversations; the others were made by each skill's own engine from the skill's worked example. The deck, the P&ID, the schematics and the film come from skills that now live in wjgoarxiv-skills (see [Extensions](#extensions)); install those extensions and agy makes them the same way.
|
|
26
|
-
|
|
27
|
-
| Picture | Skill | What it shows |
|
|
28
|
-
|---|---|---|
|
|
29
|
-
| <img src="./docs/assets/litgravity/showcase/deck-themes.webp" width="480" alt="The same Korean deck about a logistics platform in four tonalities: a dark night cover with an amber year, a navy cover with four KPI figures, a cobalt cover on cream, and a teal cover; below each, the matching chart slide with a native bar chart of monthly shipments, two bullet takeaways and a data table." /> | `lit-pptx` | One deck in four of its tonalities. Charts and KPI rows stay native and editable, Pretendard is embedded, and each deck passed the gate for overflow, contrast and empty slides. |
|
|
30
|
-
| <img src="./docs/assets/litgravity/showcase/pid-dosing-skid.webp" width="480" alt="P&ID of a sodium hypochlorite dosing skid on a framed sheet: a storage tank TK-101 with level transmitter and alarm, duty and standby metering pumps P-101A and P-101B behind filters and check valves, a relief valve PSV-101 back to the tank, a flow loop FE-101, FT-101 and FIC-101 signalling the pump, a legend, notes and a title block." /> | `lit-schematic` | A P&ID with ISA-5.1 tags, line numbers, a legend and a title block. Its checker passed: no text on a line, no line through a symbol, no loose end. |
|
|
31
|
-
| <img src="./docs/assets/litgravity/showcase/schematics.webp" width="480" alt="Two drawings side by side: an isometric cutaway of a shell-and-tube heat exchanger with copper tube bundle, baffles and saddle supports, each part labelled; and a journal-style two-panel figure of an adsorption rig, panel a a flow diagram with gas cylinders, mass flow controllers, an oven column and a mass spectrometer, panel b the column itself with adsorbent bed and thermocouples." /> | `lit-schematic` | The same skill drawing equipment as an isometric cutaway and as a two-panel figure for a paper. |
|
|
32
|
-
| <img src="./docs/assets/litgravity/showcase/motion-film.webp" width="480" alt="Four frames of a 12-second film in one dark house style: a ring drawing on beside the Korean line 작게 시작해서 끝까지, a bar chart beside One clock for every frame, a line through points beside 한 화면에 한 가지 생각, and a grid of teal and amber tiles over Same house, every film." /> | `lit-typographic-motion` | Four frames of a 12-second film from a one-line Korean request. The skill wrote a treatment first, rendered it frame by frame with a sound bed, and its gate checked flashes, legibility and the loop. |
|
|
33
|
-
| <img src="./docs/assets/litgravity/showcase/adhd-brief-en.webp" width="480" alt="The lit adhd brief in a dark chat pane: a headline counting three sessions, two active cards for a P&ID and a landing page with what each wrote and its next step, a table row for an ended deck session, a roadmap line, and a box with the recommended next step." /> | `lit-adhd` | Type `lit adhd` after a scattered day: a KPI board with the one thing to do now and exactly what to type, done and remaining milestones with progress bars, and reminders shaped as `thing → what to do` (a conversation waiting on you, uncommitted changes, lanes still running, a plan left for a week). `lit adhd detail` adds the per-session brief shown in the picture. |
|
|
34
|
-
|
|
35
|
-
## Why LitGravity
|
|
36
|
-
|
|
37
|
-
agy starts fast: you type a line and it gets to work. The trouble shows up later. A long conversation fills its context, the next one begins without what the last one learned, and "done" often means the model said so. You end up re-explaining where you were and checking by hand what really works.
|
|
26
|
+
## Quick start
|
|
38
27
|
|
|
39
|
-
|
|
28
|
+
1. [Install LitGravity](#install), then open agy in a project. Type `/skills` to see the LitGravity skills and `/hooks` to see the plugin's hooks.
|
|
29
|
+
2. Start a prompt with `lit`. The word after it picks the route, as the table below shows.
|
|
30
|
+
3. Approve a plan, then `lit start plans/<slug>.md` builds it row by row with tests.
|
|
31
|
+
4. Before you stop, `lit handoff`. Next time, `lit recap` reads where you were.
|
|
40
32
|
|
|
41
33
|
```text
|
|
42
34
|
you type lit plan a tiny todo app
|
|
@@ -44,46 +36,57 @@ it does reads the plan skill, explores the repo, writes plans/todo-app.md wi
|
|
|
44
36
|
it ends "Plan saved. Run `lit start plans/todo-app.md` when you are happy with it."
|
|
45
37
|
```
|
|
46
38
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
| What agy does | What lit adds |
|
|
39
|
+
| You type | What happens |
|
|
50
40
|
|---|---|
|
|
51
|
-
|
|
|
52
|
-
|
|
|
53
|
-
|
|
|
41
|
+
| `lit` | Runs the default loop, or picks up a plan you started with `lit start` |
|
|
42
|
+
| `lit` while its route is already active | A short "continues" note |
|
|
43
|
+
| `lit plan`, `lit review`, `lit research`, `lit debug`, `lit handoff`, `lit recap`, `lit brainstorm`, `lit korean` | Picks that route |
|
|
44
|
+
| `lit <other route>` | Switches |
|
|
45
|
+
| Any skill id as that word (`lit debugging`, `lit structural-search`) | Runs that skill; `/litgravity:<skill-id>` does the same as a slash command |
|
|
46
|
+
| `lit new` | Starts over |
|
|
54
47
|
|
|
55
|
-
|
|
48
|
+
`npx @litfamily/litgravity list` prints every skill with the words that reach it.
|
|
56
49
|
|
|
57
|
-
|
|
50
|
+
## What you can make
|
|
58
51
|
|
|
59
|
-
Each
|
|
52
|
+
Each picture is a real output made on this Mac. The `lit-adhd` brief was drawn by its collector over three real agy conversations; the others were made by each skill's own engine from the skill's worked example. The deck, the P&ID, the schematics and the film come from skills that now live in wjgoarxiv-skills (see [Extensions](#extensions)); install those extensions and agy makes them the same way.
|
|
60
53
|
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
54
|
+
| Picture | Skill | What it shows |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| <img src="./docs/assets/litgravity/showcase/deck-themes.webp" width="480" alt="The same Korean deck about a logistics platform in four tonalities: a dark night cover with an amber year, a navy cover with four KPI figures, a cobalt cover on cream, and a teal cover; below each, the matching chart slide with a native bar chart of monthly shipments, two bullet takeaways and a data table." /> | `lit-pptx` | One deck in four of its tonalities. Charts and KPI rows stay native and editable, Pretendard is embedded, and each deck passed the gate for overflow, contrast and empty slides. |
|
|
57
|
+
| <img src="./docs/assets/litgravity/showcase/pid-dosing-skid.webp" width="480" alt="P&ID of a sodium hypochlorite dosing skid on a framed sheet: a storage tank TK-101 with level transmitter and alarm, duty and standby metering pumps P-101A and P-101B behind filters and check valves, a relief valve PSV-101 back to the tank, a flow loop FE-101, FT-101 and FIC-101 signalling the pump, a legend, notes and a title block." /> | `lit-schematic` | A P&ID with ISA-5.1 tags, line numbers, a legend and a title block. Its checker passed: no text on a line, no line through a symbol, no loose end. |
|
|
58
|
+
| <img src="./docs/assets/litgravity/showcase/schematics.webp" width="480" alt="Two drawings side by side: an isometric cutaway of a shell-and-tube heat exchanger with copper tube bundle, baffles and saddle supports, each part labelled; and a journal-style two-panel figure of an adsorption rig, panel a a flow diagram with gas cylinders, mass flow controllers, an oven column and a mass spectrometer, panel b the column itself with adsorbent bed and thermocouples." /> | `lit-schematic` | The same skill drawing equipment as an isometric cutaway and as a two-panel figure for a paper. |
|
|
59
|
+
| <img src="./docs/assets/litgravity/showcase/motion-film.webp" width="480" alt="Four frames of a 12-second film in one dark house style: a ring drawing on beside the Korean line 작게 시작해서 끝까지, a bar chart beside One clock for every frame, a line through points beside 한 화면에 한 가지 생각, and a grid of teal and amber tiles over Same house, every film." /> | `lit-typographic-motion` | Four frames of a 12-second film from a one-line Korean request. The skill wrote a treatment first, rendered it frame by frame with a sound bed, and its gate checked flashes, legibility and the loop. |
|
|
60
|
+
| <img src="./docs/assets/litgravity/showcase/adhd-brief-en.webp" width="480" alt="The lit adhd brief in a dark chat pane: a headline counting three sessions, two active cards for a P&ID and a landing page with what each wrote and its next step, a table row for an ended deck session, a roadmap line, and a box with the recommended next step." /> | `lit-adhd` | Type `lit adhd` after a scattered day for a KPI board. `lit adhd detail` adds the per-session brief shown here. |
|
|
61
|
+
|
|
62
|
+
The lit-adhd board shows the one thing to do now and exactly what to type, done and remaining milestones with progress bars, and reminders shaped as `thing → what to do`. The reminders cover a conversation waiting on you, uncommitted changes, lanes still running and a plan left for a week.
|
|
67
63
|
|
|
68
64
|
## Install
|
|
69
65
|
|
|
70
|
-
You need Node.js 20 or newer and the Antigravity CLI, signed in once.
|
|
66
|
+
You need Node.js 20 or newer and the Antigravity CLI, signed in once. Run from any folder, and the check ends with `LitGravity: ready` when nothing is broken:
|
|
71
67
|
|
|
72
68
|
```bash
|
|
73
69
|
npx @litfamily/litgravity install
|
|
70
|
+
npx @litfamily/litgravity doctor
|
|
74
71
|
```
|
|
75
72
|
|
|
76
|
-
|
|
73
|
+
To update later, run the same `install` again; [Safety and uninstall](#safety-and-uninstall) lists every lifecycle command. To let a coding agent do the install, paste the prompt in the [reference](./docs/reference.md#let-a-coding-agent-install-it).
|
|
77
74
|
|
|
78
|
-
|
|
79
|
-
npx @litfamily/litgravity doctor
|
|
80
|
-
```
|
|
75
|
+
The installer shows every destination first and validates the plugin with `agy plugin validate` before and after copying. agy loads a plugin's hooks, skills and agents without a trust step, so there is nothing to approve. By default the plugin goes to `~/.gemini/config/plugins/litgravity`, so LitGravity is available in every project.
|
|
81
76
|
|
|
82
|
-
|
|
77
|
+
| Switch | What it does |
|
|
78
|
+
|---|---|
|
|
79
|
+
| `--scope project` | Copies to `./.agents/plugins/litgravity` for one project |
|
|
80
|
+
| `--dry-run` | Previews and writes nothing |
|
|
81
|
+
| `--yes` | Installs from a shell without a terminal (agent, CI), which otherwise only previews |
|
|
82
|
+
| `--no-agent-file` | Skips the global rule file for one run |
|
|
83
|
+
| `--status-line` | Adds the opt-in status line to agy's user settings, after a backup |
|
|
84
|
+
|
|
85
|
+
Every user-scope install also leaves one owned rule file at `~/.gemini/config/rules/litgravity.md`, because agy reads that folder at every session start. The rule stays short on purpose (the lit activation word, where plans and handoffs live, and the release freeze), so the ground rules hold before any skill loads. An interactive install asks first and a No stores the rule off, while `--yes` adds it; the [lifecycle table](#safety-and-uninstall) turns it off later or adds a project block.
|
|
83
86
|
|
|
84
|
-
|
|
87
|
+
`doctor` lists the installed copy, the validation result, the six hook events and a smoke run of each hook script, the global rule file, every skill and agent, the extensions with their install line, any old engine cache or stray saved copy, and the host programs the skills call.
|
|
85
88
|
|
|
86
|
-
The installer writes in a few places outside your project, and
|
|
89
|
+
The installer writes in a few places outside your project, and the map shows them. If the destination is a symlink, someone else's folder, or a copy you edited, it stops with `No files written.`; otherwise it copies the plugin, then writes the rule file and a small receipt. Everything else LitGravity leaves on disk is written later by your conversations, and the installer never changes your extension copies (it only reads the skill folders to tell you, once, when `extensions check` has something to show).
|
|
87
90
|
|
|
88
91
|
<p align="center">
|
|
89
92
|
<picture>
|
|
@@ -94,52 +97,9 @@ The installer writes in a few places outside your project, and it is easier to s
|
|
|
94
97
|
|
|
95
98
|
<p align="center"><img src="./docs/assets/litgravity/install-doctor.webp" width="960" alt="Terminal capture. The install command ends with Status: Ready, and the doctor command ends with LitGravity: ready after thirty passing checks." /></p>
|
|
96
99
|
|
|
97
|
-
Useful switches: `--dry-run` previews and writes nothing; `--yes` lets an agent or CI shell install (a shell without a terminal otherwise only previews); `--no-agent-file` skips the global rule file for one run; `--status-line` adds the optional LitGravity status line to agy's user settings (never on by default).
|
|
98
|
-
|
|
99
|
-
The status line is one row under the prompt, drawn in the LitFamily status-line style: the `[🔥LIT v…]` mark, then every segment in LitGravity's flame orange. It reads `model [effort] │ ctx [█▎░] 42%/1049k │ quota [▌░]28% ↻ 2h5m`, then the active lit route as a pink `🔥 LIT` chip with its clock, then where the route stands on its map (PIN, RED, GREEN, VERIFY, REVIEW, RECORD for the open criterion of litwork and lit-loop, read from its evidence files; interview, plan, work, review, done for planning and start-work, with the plan's rows), the lanes of a lit-team, and whatever agy also reports: cost, background tasks, the branch and the title. The context and quota gauges turn yellow at 70% and red at 90%. On a narrow terminal the extras go first and the route and the context gauge stay. `NO_COLOR` turns colour off and `LITGRAVITY_HUD_ASCII=1` keeps every glyph ASCII. If agy already shows another status line, the installer refuses to touch it; `install --status-line --replace-status-line` swaps it after saving the old value, and `uninstall` puts that value back.
|
|
100
|
-
|
|
101
|
-
### Let a coding agent install it
|
|
102
|
-
|
|
103
|
-
Paste this into a coding agent opened in any folder:
|
|
104
|
-
|
|
105
|
-
```text
|
|
106
|
-
Install LitGravity, the LitFamily plugin for Google's Antigravity CLI.
|
|
107
|
-
Use only the official npm package @litfamily/litgravity. Show me your plan and wait for my yes before changing anything.
|
|
108
|
-
1. Check that Node.js 20+ and agy are on PATH (`agy --version`).
|
|
109
|
-
2. Preview: npx @litfamily/litgravity install --dry-run
|
|
110
|
-
3. Install: npx @litfamily/litgravity install --yes
|
|
111
|
-
4. Verify: npx @litfamily/litgravity doctor and report its last line.
|
|
112
|
-
5. Tell me what was written (the installer prints a "Written:" list) and anything it refused.
|
|
113
|
-
```
|
|
114
|
-
|
|
115
|
-
## Quick start
|
|
116
|
-
|
|
117
|
-
1. Open agy in a project. Type `/skills` to see the LitGravity skills and `/hooks` to see the plugin's hooks.
|
|
118
|
-
2. Start a prompt with `lit`. Plain `lit` runs the default loop; the word after it picks the route: `lit plan`, `lit review`, `lit research`, `lit debug`, `lit handoff`, `lit recap`, `lit brainstorm`, `lit korean`. Any skill id works as that word (`lit debugging`, `lit structural-search`), and `/litgravity:<skill-id>` runs a skill as a slash command.
|
|
119
|
-
3. Approve a plan, then `lit start plans/<slug>.md` builds it row by row with tests.
|
|
120
|
-
4. Before you stop, `lit handoff`. Next time, `lit recap` reads where you were.
|
|
121
|
-
|
|
122
|
-
`npx @litfamily/litgravity list` prints every skill with the words that reach it. A `lit` while its route is already active gets a short "continues" note, `lit <other route>` switches, a bare `lit` picks up a plan you started with `lit start`, and `lit new` starts over.
|
|
123
|
-
|
|
124
|
-
## The status line
|
|
125
|
-
|
|
126
|
-
One row under the prompt shows where the work stands: the model and its effort tier, the context and quota gauges, the active route with its clock, and the map of that route with the current stage lit. The capture below is a real render from this Mac, before and after a `lit` prompt.
|
|
127
|
-
|
|
128
|
-
<p align="center"><img src="./docs/assets/litgravity/status-states.webp" width="960" alt="Terminal capture of the status line. Before lit it shows the model and the context gauge at 42 percent. After lit it adds the lit-loop chip with its clock and the PIN through RECORD map with PIN lit." /></p>
|
|
129
|
-
|
|
130
|
-
When the terminal narrows, the extras give way first and the route and the context gauge stay. Where colour is off, the same row renders in plain text:
|
|
131
|
-
|
|
132
|
-
```text
|
|
133
|
-
[LIT] | GF3.8 | ctx [#--] 42%/1049k | [LIT] . lit-loop 2:20 | [PIN] = RED . - GREEN . - VERIFY . - REVIEW . - RECORD .
|
|
134
|
-
```
|
|
135
|
-
|
|
136
|
-
Some moments change the look of the row. While `lit adhd` (or `lit-rewind`, the skill typed whole or after `/`, or the skill the model loads by itself) is the route, every cell turns its own colour of a slow rainbow. When the turn ends on a question, a typed approval, a BLOCKED report or a goal that needs a decision, the row turns amber and reads `⚠ YOUR TURN · <why>` until you type. During `lit review work` the five lanes (goal, qa, quality, security, context) appear as each reports, in its own colour with its verdict mark and a count such as `2/5`. A plan or goal finished during the route shows `✦ DONE ✦` for twenty seconds. Other conversations in the same workspace appear as one count, `+2 running · 1 idle` (shortened to `+3 others` when the row is tight), read from the small liveness record each conversation's hooks keep; a start-work that just finished counts as done for a minute. agy repaints the line when it chooses, so every look is static, and `NO_COLOR` keeps the labels in plain text.
|
|
137
|
-
|
|
138
100
|
## What you get
|
|
139
101
|
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
A lit turn runs the same routine through these parts. A bigger change gets a written plan first, the work is built row by row with tests under a goal record that outlives one conversation, a second look reviews it before anything merges, research shows its sources, documents and prose read clean, and the turn ends with a handoff the next conversation reads:
|
|
102
|
+
A lit turn runs the same routine through these parts. A bigger change gets a written plan first, the work is built row by row with tests under a goal record that outlives one conversation, and a second look reviews it before anything merges. Research shows its sources, documents and prose read clean, and the turn ends with a handoff the next conversation reads.
|
|
143
103
|
|
|
144
104
|
| Part | Contents | Role |
|
|
145
105
|
|---|---|---|
|
|
@@ -147,45 +107,45 @@ A lit turn runs the same routine through these parts. A bigger change gets a wri
|
|
|
147
107
|
| 11 agents | Child agents agy starts under their type names | Plan, execute, verify, review, Korean prose |
|
|
148
108
|
| 6 hooks | Run at session start, each turn, each tool call, and the stop gate | Route `lit`, hold unfinished turns, ledger every tool |
|
|
149
109
|
|
|
150
|
-
agy loads only the first 24,000 bytes of a `SKILL.md`, so the
|
|
151
|
-
|
|
152
|
-
The skills also call programs already on your machine: Python 3, Chrome or Chromium for browser work, ast-grep, ripgrep and the language checkers that `lsp` drives. `doctor` names what is missing and the command that installs it; LitGravity never installs software globally.
|
|
110
|
+
agy loads only the first 24,000 bytes of a `SKILL.md`, so each of the 33 dense skills, read on demand, keeps its references, scripts and templates in its own folder, with the long material in `references/` and the skill naming the file to open. The skill groups are loop and goals, ideas and planning, building, review and cleanup, research and knowledge, teams, prose, continuity and guidance, and tools, plus the nine stubs of the moved families (see [Extensions](#extensions)).
|
|
153
111
|
|
|
154
|
-
**
|
|
112
|
+
- **Host programs.** The skills call programs already on your machine: Python 3, Chrome or Chromium for browser work, ast-grep, ripgrep and the language checkers that `lsp` drives. `doctor` names what is missing and the command that installs it; LitGravity never installs software globally.
|
|
113
|
+
- **Agents.** agy starts them with `invoke_subagent` under their type name: lit-planner, lit-executor, lit-verifier, qa-runner, quality-reviewer, librarian-researcher, and five Korean prose agents (korean-style-analyzer, korean-prose-editor, meaning-preservation-auditor, native-flow-reviewer, polish-orchestrator). Reviewers and the Korean agents get read and search tools only.
|
|
114
|
+
- **Models.** `npx @litfamily/litgravity models` lists the models and effort tiers your agy offers, read from agy itself, so a model Google adds later shows up with no LitGravity update.
|
|
155
115
|
|
|
156
|
-
|
|
116
|
+
<details>
|
|
117
|
+
<summary>The six hook events</summary>
|
|
157
118
|
|
|
158
|
-
- SessionStart adds the LitGravity route list,
|
|
119
|
+
- SessionStart adds the LitGravity route list, the newest handoff note (cut to 6,000 characters) and an update notice, once per new conversation. An update notice or the `lit adhd` nudge is not repeated in a project that already saw it (`.litgravity/shown/notices.jsonl`).
|
|
120
|
+
- Stop saves `.litgravity/handoff/auto.md` at every turn end of a conversation a lit route has touched: the last request, the plan row that is next, the open goal criterion and the tail of the last reply. This replaces the compaction event agy lacks. `LITGRAVITY_AUTO_HANDOFF=0` turns the save and the full-note carry off; SessionStart then points at `latest.md` as before.
|
|
159
121
|
- PreInvocation is the `lit` router. agy has no prompt hook, so on the first model call of a turn the router reads the newest prompt from the transcript, applies the re-entry rule and injects one step that names the skill file to read.
|
|
160
|
-
- PostInvocation and Stop run the checks that agy cannot run in advance (see the limits
|
|
122
|
+
- PostInvocation and Stop run the checks that agy cannot run in advance (see [the limits](#what-agy-limits-today)). Stop also holds an unfinished turn, as [Held turns](#held-turns-and-the-ledger) describes.
|
|
161
123
|
- PreToolUse refuses child agents that could write while lit-plan is active.
|
|
162
124
|
- PostToolUse writes one ledger line per tool call while a route is active, in `.litgravity/ledger/<conversation>.jsonl`, with key shapes redacted. A silent ledger means the hooks are not loaded.
|
|
163
125
|
|
|
164
|
-
|
|
126
|
+
</details>
|
|
127
|
+
|
|
128
|
+
### The status line
|
|
129
|
+
|
|
130
|
+
One row under the prompt shows where the work stands: the model and its effort tier, the context and quota gauges, the active route with its clock, and the map of that route with the current stage lit. The capture below is a real render from this Mac, before and after a `lit` prompt.
|
|
131
|
+
|
|
132
|
+
<p align="center"><img src="./docs/assets/litgravity/status-states.webp" width="960" alt="Terminal capture of the status line. Before lit it shows the model and the context gauge at 42 percent. After lit it adds the lit-loop chip with its clock and the PIN through RECORD map with PIN lit." /></p>
|
|
133
|
+
|
|
134
|
+
`--status-line` at install turns it on. Its segments, colours, plain-text form and the looks for `lit adhd`, YOUR TURN, review lanes and DONE are in the [reference](./docs/reference.md#the-status-line).
|
|
165
135
|
|
|
166
136
|
## Extensions
|
|
167
137
|
|
|
168
|
-
LitGravity is the LitFamily core for agy, and it is complete on its own: planning, building, checking, research, handoffs and the `lit` router all ship in this package. The skills that make files
|
|
138
|
+
LitGravity is the LitFamily core for agy, and it is complete on its own: planning, building, checking, research, handoffs and the `lit` router all ship in this package. The skills that make files (slides, Word documents, diagrams, schematics, figures, interfaces, films and README covers) each pull in their own engines, and together they used to be most of the package, while most people use one or two of them. They are now LitFamily extensions on one extension shelf, the wjgoarxiv-skills repository, where each skill has a folder written for agy.
|
|
169
139
|
|
|
170
|
-
|
|
140
|
+
Everything on the left ships in the npm package, and the core needs nothing on the right to plan, build, check, research or hand off. Install the extensions you use alongside LitGravity for the full LitFamily experience; leave the rest out and nothing in the core is missing.
|
|
171
141
|
|
|
172
142
|
<p align="center">
|
|
173
143
|
<picture>
|
|
174
144
|
<source media="(prefers-color-scheme: dark)" srcset="./docs/assets/litgravity/diagrams/core-extensions.en.dark.png">
|
|
175
|
-
<img src="./docs/assets/litgravity/diagrams/core-extensions.en.light.png" width="900" alt="Two areas. Left, the LitGravity plugin: 33 core skills in nine groups (loop and goals, ideas and planning, building, review and cleanup, research and knowledge, teams, prose, continuity and guidance, tools), 11 agents, 6 hooks, and nine stubs that keep the old names: lit-pptx, lit-docx, lit-diagram-drawer, lit-schematic, lit-scientific-visualization, frontend-ui-ux, visual-qa, lit-typographic-motion and readme-studio. Right, wjgoarxiv-skills extensions in five families: decks, documents, figures, design and video-covers, each folder at variants/litgravity/<id>. An arrow labelled
|
|
145
|
+
<img src="./docs/assets/litgravity/diagrams/core-extensions.en.light.png" width="900" alt="Two areas. Left, the LitGravity plugin: 33 core skills in nine groups (loop and goals, ideas and planning, building, review and cleanup, research and knowledge, teams, prose, continuity and guidance, tools), 11 agents, 6 hooks, and nine stubs that keep the old names: lit-pptx, lit-docx, lit-diagram-drawer, lit-schematic, lit-scientific-visualization, frontend-ui-ux, visual-qa, lit-typographic-motion and readme-studio. Right, wjgoarxiv-skills extensions in five families: decks, documents, figures, design and video-covers, each folder at variants/litgravity/<id>. An arrow labelled install <id> --yes runs from that folder to a card for litgravity extensions install with four numbered steps: check same-name skills and stop if any; move an old copy aside, whole, to ~/.gemini/extension-backups/<date>/; copy into the emptied folder; write a receipt inside the copy. An arrow labelled new copy + receipt runs on to agy user skills at ~/.gemini/config/skills/<id>, which answers as /<id>. Another arrow labelled if installed runs from the stubs to the same place. Below it, a card lists the other verbs, list, check, update, remove and prune-backups, each a plan only until --yes, and a note says that when the extension is not installed, the stub gives this command and the four hand lines and makes nothing.">
|
|
176
146
|
</picture>
|
|
177
147
|
</p>
|
|
178
148
|
|
|
179
|
-
LitGravity keeps a short stub under each extension's old name, so `lit deck …`, `lit motion …`, `/litgravity:lit-pptx` and the rest still land somewhere useful. The stub hands the turn to your installed copy, or, when the extension is not installed yet, gives you the one line that installs it and makes nothing. The installer says the same after every install or update, and the first agy conversation after it mentions it once.
|
|
180
|
-
|
|
181
|
-
wjgoarxiv-skills is public at <https://github.com/wjgoarxiv/wjgoarxiv-skills>. Clone it (`git clone https://github.com/wjgoarxiv/wjgoarxiv-skills`), then copy a skill from your clone into agy's user skills folder:
|
|
182
|
-
|
|
183
|
-
```bash
|
|
184
|
-
mkdir -p ~/.gemini/config/skills && cp -R "<path to your wjgoarxiv-skills clone>/variants/litgravity/<id>" ~/.gemini/config/skills/
|
|
185
|
-
```
|
|
186
|
-
|
|
187
|
-
For one workspace only, copy it into that workspace's `.agents/skills/` instead. Start a new conversation (or type `/skills reload`), and the skill answers as `/<id>`. To update it, delete the copied folder and copy it again. The LitGravity installer writes only its own plugin folder, so upgrading or removing LitGravity never touches the copy, and the stub (`litgravity:<id>`) and the copy (`<id>`) keep different names.
|
|
188
|
-
|
|
189
149
|
| Family in wjgoarxiv-skills | Extensions |
|
|
190
150
|
|---|---|
|
|
191
151
|
| `decks` | `lit-pptx` |
|
|
@@ -194,24 +154,59 @@ For one workspace only, copy it into that workspace's `.agents/skills/` instead.
|
|
|
194
154
|
| `design` | `frontend-ui-ux`, `visual-qa` |
|
|
195
155
|
| `video-covers` | `lit-typographic-motion`, `readme-studio` |
|
|
196
156
|
|
|
197
|
-
|
|
157
|
+
LitGravity keeps a short stub under each extension's old name, so `lit deck …`, `lit motion …`, `/litgravity:lit-pptx` and the rest still land somewhere useful. The stub hands the turn to your installed copy, or, when the extension is not installed yet, gives you the lines that install it and makes nothing. The installer says the same after every install or update, and the first agy conversation after it mentions it once.
|
|
198
158
|
|
|
199
|
-
|
|
159
|
+
The easiest way in is LitGravity's own `extensions` command. Every verb that changes anything prints its plan first and waits for `--yes`, so you can read exactly which folder moves where before it happens:
|
|
200
160
|
|
|
201
|
-
|
|
161
|
+
```bash
|
|
162
|
+
npx @litfamily/litgravity extensions install lit-pptx # the plan only
|
|
163
|
+
npx @litfamily/litgravity extensions install lit-pptx --yes # do it (--project: this workspace only)
|
|
164
|
+
```
|
|
202
165
|
|
|
203
|
-
|
|
166
|
+
| Verb | What it does |
|
|
167
|
+
|---|---|
|
|
168
|
+
| `install` | Backs up any old copy, then copies in the new one and its receipt |
|
|
169
|
+
| `list` | Shows each as installed (with receipt), not installed, receipt-less, or shadowed by a same-name skill |
|
|
170
|
+
| `update` | Fetches the source and reinstalls only the ones whose files changed |
|
|
171
|
+
| `remove` | Moves its own copy into the backups; a folder without a receipt is yours, so it refuses |
|
|
172
|
+
| `check` | Changes nothing; prints one fix line per duplicate, receipt-less copy or missing source |
|
|
173
|
+
| `prune-backups` | Shows the backups with their sizes and deletes them only with `--yes` |
|
|
204
174
|
|
|
205
|
-
|
|
206
|
-
- **Headless runs cannot ask.** In `agy -p`, a `run_command` or `write_file` that needs permission is denied, and the denial ends the run with an empty answer (the JSON lists it under `denied_actions`). `read_file` inside the workspace works. The skills read first and report `BLOCKED` with the permission they need. For scripted use add allow rules to agy's settings or pass `--dangerously-skip-permissions`, at your own risk. Use a project-scope install (`--scope project`) when a headless run has to read the skill files, because a plugin whose real path lies outside the workspace was denied its `read_file` in the same probe.
|
|
207
|
-
- **Seeing images.** agy's model reads a PNG through `read_file`. Every look step in the visual skills relies on that, and it was proven with a picture whose only content was a word the prompt never mentioned.
|
|
208
|
-
- **Starter Quota.** Every model call counts against your account's quota, so tests and probes use `agy plugin validate` and `/hooks`, `/skills`, `/agents`, which cost nothing, and a build of LitGravity spends only a handful of real calls.
|
|
209
|
-
- **No compaction event, no slash-command folder, no MCP server from a plugin here.** `lit-handoff` writes `.litgravity/handoff/latest.md` and a new conversation is pointed at it. Skills are the commands (`/litgravity:<skill-id>`). `wikify` runs as script subcommands inside the skill.
|
|
210
|
-
- **No lsp tool.** The `lsp` and `lsp-setup` skills drive language checkers from the command line instead.
|
|
175
|
+
A few rules keep the command safe and easy to drive:
|
|
211
176
|
|
|
212
|
-
|
|
177
|
+
- **Same-name check.** Before copying, `install` looks in every folder agy loads and stops with the path of any skill sharing the name. Your skill is never moved, and `--allow-shadow` installs anyway with a warning.
|
|
178
|
+
- **Backups.** An existing copy at the destination goes whole into a dated folder under `~/.gemini/extension-backups/` before the new copy goes in.
|
|
179
|
+
- **Source.** It keeps its own shallow clone of just the agy folders of wjgoarxiv-skills in `~/.cache/litgravity/extensions-src` (or reads a clone you already have with `--from <path>`), so there is nothing to clone by hand.
|
|
180
|
+
- **Several at once.** `--family <name>` and `--all` pick several. `npx @litfamily/litgravity extensions help` has the details, and `doctor` runs `check` and prints its summary.
|
|
213
181
|
|
|
214
|
-
|
|
182
|
+
Start a new conversation (or type `/skills reload`), and the skill answers as `/<id>`. To install by hand, the [reference](./docs/reference.md#install-an-extension-by-hand) gives the four shell lines, the workspace-only version, and how to update and remove a copy.
|
|
183
|
+
|
|
184
|
+
## How a lit turn runs
|
|
185
|
+
|
|
186
|
+
agy still runs the conversation and picks the model. LitGravity adds a routine in plain files you can read, so you stop re-explaining where you were and checking by hand what really works:
|
|
187
|
+
|
|
188
|
+
| What agy does | What lit adds |
|
|
189
|
+
|---|---|
|
|
190
|
+
| Starts fast from one typed line | A plan in `plans/` before the first edit |
|
|
191
|
+
| Forgets the last conversation once a long one fills its context | A handoff in `.litgravity/` the next turn reads |
|
|
192
|
+
| Calls it done when the model says so | Checks against the plan, marks the unchecked as unverified |
|
|
193
|
+
|
|
194
|
+
<p align="center">
|
|
195
|
+
<picture>
|
|
196
|
+
<source media="(prefers-color-scheme: dark)" srcset="./docs/assets/litgravity/diagrams/lit-route.en.dark.png">
|
|
197
|
+
<img src="./docs/assets/litgravity/diagrams/lit-route.en.light.png" width="900" alt="Flowchart of one lit turn in agy. You type lit plan a tiny todo app. The PreInvocation hook reads the prompt from the transcript and injects one step: read lit-plan/SKILL.md. After the model call, the PreToolUse hook checks invoke_subagent and may start one of 11 child agent types, only read-only ones during lit-plan. After each tool call, the PostToolUse hook appends a line to .litgravity/ledger/<conversation>.jsonl. The PostInvocation hook runs boundary and prose checks and tells the model to undo changes outside plans/, at most twice per turn. The Stop hook asks whether work is left open: held, the turn continues for up to three holds and pause releases it; released, the turn ends. Below, the next turns: lit start on plans/<slug>.md, lit review with five lanes (goal, qa, quality, security, context), lit handoff writing .litgravity/handoff/latest.md, and the SessionStart hook pointing the next conversation to that note.">
|
|
198
|
+
</picture>
|
|
199
|
+
</p>
|
|
200
|
+
|
|
201
|
+
agy gives a plugin no hook on the prompt itself, so the PreInvocation hook steers from the first model call and the other hooks each watch one moment of the turn. Each moment leaves a file you can open afterwards (the plan, the ledger, the handoff note), and the next turns pick up from those files:
|
|
202
|
+
|
|
203
|
+
- **`lit start`** builds the plan, checked with tests and a look at the real surface. Whatever nobody could check is marked as unverified.
|
|
204
|
+
- **`lit review`** checks the result in five lanes.
|
|
205
|
+
- **`lit handoff`** writes `.litgravity/handoff/latest.md` with what was built, how it was checked and what is left. The SessionStart hook of your next conversation points to it.
|
|
206
|
+
|
|
207
|
+
### What a planning turn may do
|
|
208
|
+
|
|
209
|
+
`lit plan` turns are planning only. Most of that is asked, then checked afterwards, because agy offers no safe way to stop a write before it happens (see [the limits](#what-agy-limits-today)):
|
|
215
210
|
|
|
216
211
|
- The router tells the model to write only under `plans/` and `.litgravity/` and to keep the shell to plain read-only commands. Your own approval prompts still decide whether a write or command runs.
|
|
217
212
|
- After every model call and at the end of the turn, the boundary check compares the workspace with its state at the start of the turn. A file changed or removed outside `plans/` is reported and the model is asked to undo it, at most twice per turn. A command that changed nothing on disk leaves no trace for this check.
|
|
@@ -219,9 +214,9 @@ These are the facts of agy 1.4.3, probed on a real install. LitGravity works ins
|
|
|
219
214
|
|
|
220
215
|
Route state lives outside the project, under `~/.local/state/litgravity/`, away from the files a planning turn is asked to touch. If that state is damaged, the child-agent limit and the plan gate stay on; if it goes missing, the hooks fall back to the route journal kept beside it.
|
|
221
216
|
|
|
222
|
-
|
|
217
|
+
### Held turns and the ledger
|
|
223
218
|
|
|
224
|
-
If you think in process plants, here is the same routine as one. Your prompt is the feed, the PreInvocation router is the header, and each route word opens the line to its vessel.
|
|
219
|
+
If you think in process plants, here is the same routine as one. Your prompt is the feed, the PreInvocation router is the header, and each route word opens the line to its vessel. I drew the stages as one train to keep it readable; in agy each of them is a separate `lit` prompt, usually in a later turn.
|
|
225
220
|
|
|
226
221
|
<p align="center">
|
|
227
222
|
<picture>
|
|
@@ -233,42 +228,68 @@ If you think in process plants, here is the same routine as one. Your prompt is
|
|
|
233
228
|
</picture>
|
|
234
229
|
</p>
|
|
235
230
|
|
|
236
|
-
|
|
231
|
+
Every vessel bleeds a sample line into the ledger, and the handoff note leaves on the right for whichever conversation comes next. Between the vessels, the Stop hook's two analysers hold a turn while its work is open:
|
|
232
|
+
|
|
233
|
+
| Route | Held at the end while |
|
|
234
|
+
|---|---|
|
|
235
|
+
| lit-plan | no `plans/<slug>.md` exists yet |
|
|
236
|
+
| start-work | an approved plan has open rows |
|
|
237
|
+
| litgoal, lit-loop | a goal record has an open criterion |
|
|
238
|
+
|
|
239
|
+
A turn is held at most three times in a row without progress. Say `pause`, or write `BLOCKED at row N:`, `PAUSED at row N:` or `CANCELLED:` in the ledger, to release a hold. The capture below is the real hold from a planning turn that wrote nothing.
|
|
237
240
|
|
|
238
241
|
<p align="center"><img src="./docs/assets/litgravity/handoff-hold.webp" width="960" alt="Terminal capture. After the prompt lit plan a tiny todo app with no plan file written, the Stop hook answers decision continue with the lit-plan gate reason asking for the plan file. A second block shows a ledger line recording a read_file tool call." /></p>
|
|
239
242
|
|
|
240
|
-
|
|
243
|
+
## What agy limits today
|
|
244
|
+
|
|
245
|
+
These are the facts of agy 1.4.3, probed on a real install. LitGravity works inside them, and the [reference](./docs/reference.md#what-agy-limits-today-in-detail) gives each one in full.
|
|
246
|
+
|
|
247
|
+
- **No blocking before a write.** agy's PreToolUse hook has to decide every call it sees, so LitGravity checks file changes and prose after the fact. The one hard stop is a child agent that could write during a lit-plan turn.
|
|
248
|
+
- **Headless runs cannot ask.** In `agy -p`, a `run_command` or `write_file` that needs permission is denied and ends the run. The skills read first and report `BLOCKED` with the permission they need.
|
|
249
|
+
- **Seeing images.** agy's model reads a PNG through `read_file`, and every look step in the visual skills relies on that.
|
|
250
|
+
- **Starter Quota.** Every model call counts against your account's quota, so tests and probes use the free `agy plugin validate` and `/hooks`, `/skills`, `/agents`.
|
|
251
|
+
- **No compaction event, no slash-command folder, no MCP server from a plugin here.** Handoff notes, skills as commands (`/litgravity:<skill-id>`) and script subcommands take their place.
|
|
252
|
+
- **No lsp tool.** The `lsp` and `lsp-setup` skills drive language checkers from the command line instead.
|
|
241
253
|
|
|
242
254
|
## Safety and uninstall
|
|
243
255
|
|
|
244
|
-
|
|
245
|
-
- A symlinked, foreign or edited destination stops the install before the first write. To keep an edited copy, the installer gives a command that moves it to `~/.local/share/litgravity/saved/<scope>-<date>`. That folder is outside agy's plugins folder on purpose: agy loads every folder it finds there, so a copy saved beside the plugin would run as a second LitGravity. `doctor` warns about any such leftover. `--dry-run` never mutates.
|
|
246
|
-
- Hooks fail open: if one breaks, your conversation continues.
|
|
247
|
-
- Releases up to 0.1.8 cached engines under `~/.local/share/litgravity/runtime/`. Nothing writes there now and `uninstall` leaves it, so delete that folder to free the space.
|
|
248
|
-
- Set `LITGRAVITY_HOOK_TRACE=<file>` before starting agy to log one line per hook call. It is off otherwise.
|
|
249
|
-
Three commands cover the lifecycle, and every one previews with `--dry-run`:
|
|
256
|
+
Every lifecycle command previews with `--dry-run`, and hooks fail open: if one breaks, your conversation continues. Files that conversations created in your projects (`plans/`, `.litgravity/`) stay where they are.
|
|
250
257
|
|
|
251
258
|
| Task | Command |
|
|
252
259
|
|---|---|
|
|
253
260
|
| Install | `npx @litfamily/litgravity install` |
|
|
254
261
|
| Update | `npx @litfamily/litgravity install` (validates, replaces in place) |
|
|
255
262
|
| Global rule off or back on | `npx @litfamily/litgravity config agentFile off` (or `on`) |
|
|
256
|
-
| Project block | `npx @litfamily/litgravity agent-file project --dir <path>` |
|
|
263
|
+
| Project block | `npx @litfamily/litgravity agent-file project --dir <path>` (writes only the marked block into the repo's `AGENTS.md`) |
|
|
257
264
|
| Check | `npx @litfamily/litgravity doctor` |
|
|
265
|
+
| Extensions | `npx @litfamily/litgravity extensions list` (then `install`, `update`, `remove`, `check`, `prune-backups`) |
|
|
258
266
|
| Remove | `npx @litfamily/litgravity uninstall --yes` |
|
|
259
267
|
|
|
260
|
-
|
|
268
|
+
The installer writes only its own plugin folder, its data directory, its rule file and, when you ask, the status line key, and it never reads agy's credential files.
|
|
269
|
+
|
|
270
|
+
<details>
|
|
271
|
+
<summary>What each part may write, and what it leaves</summary>
|
|
272
|
+
|
|
273
|
+
- The installer writes only its own plugin folder, its data directory (`$XDG_DATA_HOME/litgravity`), the owned rule file in agy's global rules folder, and, when you ask, the status line key in agy's user settings, after a backup. It never reads agy's credential files. A rule file it did not write stops the install before the first write instead of being merged into.
|
|
274
|
+
- A symlinked, foreign or edited destination stops the install before the first write. To keep an edited copy, the installer gives a command that moves it to `~/.local/share/litgravity/saved/<scope>-<date>`. That folder is outside agy's plugins folder on purpose: agy loads every folder it finds there, so a copy saved beside the plugin would run as a second LitGravity. `doctor` warns about any such leftover. `--dry-run` never mutates.
|
|
275
|
+
- `extensions` writes only into agy's skill folder for the scope (`~/.gemini/config/skills/<id>` or `.agents/skills/<id>`), `~/.gemini/extension-backups/` and its own source clone in `~/.cache/litgravity/extensions-src`. Without `--yes` it only prints its plan. It never moves a same-name skill you keep elsewhere, never removes a folder without its receipt, and deletes only inside `~/.gemini/extension-backups/`, only with `prune-backups --yes`.
|
|
276
|
+
- Releases up to 0.1.8 cached engines under `~/.local/share/litgravity/runtime/` (`$XDG_DATA_HOME/litgravity/runtime/`), and the cache can take 150 MB or more. Nothing reads or writes there now, the extensions included, and `uninstall` leaves it, so delete that folder to free the space; `doctor` names it while it is there.
|
|
277
|
+
- Set `LITGRAVITY_HOOK_TRACE=<file>` before starting agy to log one line per hook call. It is off otherwise.
|
|
278
|
+
|
|
279
|
+
</details>
|
|
280
|
+
|
|
281
|
+
## Reference
|
|
282
|
+
|
|
283
|
+
[docs/reference.md](./docs/reference.md) keeps the material most readers need only once: [the status line](./docs/reference.md#the-status-line) in full, [a coding agent's install prompt](./docs/reference.md#let-a-coding-agent-install-it), [installing an extension by hand](./docs/reference.md#install-an-extension-by-hand), and [what agy limits today, in detail](./docs/reference.md#what-agy-limits-today-in-detail).
|
|
261
284
|
|
|
262
285
|
## Family
|
|
263
286
|
|
|
264
|
-
LitGravity is one of the seven LitFamily packages. Each one brings the same way of working to a single coding agent, and each installs and runs on its own: install the one for the agent you use, and it needs none of the others.
|
|
287
|
+
LitGravity is one of the seven LitFamily packages. Each one brings the same way of working to a single coding agent, and each installs and runs on its own: install the one for the agent you use, and it needs none of the others. [LitFamily](https://github.com/wjgoarxiv/litfamily) lists all seven and the agent each one is for.
|
|
265
288
|
|
|
266
289
|
The seven armored machines on the cover are those seven packages, and LitGravity is the orbit machine in the seventh bay. The cover is brand motion made with the LitFamily motion skill: drawn and animated artwork, with no agy session recorded in it. If your system asks for reduced motion, you see a still frame instead.
|
|
267
290
|
|
|
268
291
|
<p align="center"><img src="./docs/assets/litfamily-machines.png" width="100%" alt="The seven LitFamily machines side by side, all lit: LitClaude, LitHermes, LitCodex, LitOpenCode, LitGrok, LitMuse and LitGravity, under LITFAMILY and KEEP THE WORK LIT." /></p>
|
|
269
292
|
|
|
270
|
-
[LitFamily](https://github.com/wjgoarxiv/litfamily) lists all seven and the agent each one is for.
|
|
271
|
-
|
|
272
293
|
## License
|
|
273
294
|
|
|
274
295
|
MIT. See [LICENSE](./LICENSE).
|