Skip to content

Commit 232f15f

Browse files
Lumos-789Lumos-789
committed
feat(guster): add guster plugin v0.5.4
1 parent 0cc58d6 commit 232f15f

37 files changed

Lines changed: 5224 additions & 13 deletions

‎external_plugins/guster/.codex-plugin/plugin.json‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
{
2+
"name": "guster",
3+
"version": "0.5.4",
4+
"description": "Discover, audit, plan and evolve agent context across projects, skills, tools, knowledge and credentials; optionally scaffold a lightweight Guster Hub for durable knowledge and project state.",
5+
"author": {
6+
"name": "Lumos-789",
7+
"url": "https://github.com/Lumos-789"
8+
},
9+
"homepage": "https://github.com/Lumos-789/guster",
10+
"repository": "https://github.com/Lumos-789/guster",
11+
"license": "MIT",
12+
"keywords": [
13+
"agent",
14+
"context",
15+
"governance",
16+
"skills",
17+
"mcp",
18+
"codex",
19+
"zcode",
20+
"dsh"
21+
],
22+
"skills": "./skills/",
23+
"interface": {
24+
"displayName": "Guster",
25+
"shortDescription": "Audit and evolve agent context",
26+
"longDescription": "Guster discovers agent projects, instruction files, skills, tools, knowledge, state, evidence and credential references. It diagnoses drift, computes a context health score, produces reviewable migration plans, and can scaffold a lightweight hub for durable knowledge and project state.",
27+
"developerName": "Lumos-789",
28+
"category": "Developer Tools",
29+
"capabilities": [
30+
"Read",
31+
"Write with confirmation"
32+
]
33+
}
34+
}

‎external_plugins/guster/.zcode-plugin/plugin.json‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"name": "guster",
3+
"version": "0.5.4",
4+
"description": "Discover, audit, plan and evolve agent context across projects, skills, tools, knowledge and credentials; optionally scaffold a lightweight Guster Hub for durable knowledge and project state.",
5+
"description_i18n": {
6+
"en": "Discover, audit, plan and evolve agent context across projects, skills, tools, knowledge and credentials; optionally scaffold a lightweight Guster Hub for durable knowledge and project state.",
7+
"zh-CN": "发现、诊断、规划和演进全机 agent 上下文：项目、指令、Skill、工具、知识、状态与凭据引用；可初始化一个轻量 Guster Hub，承载长期知识与项目状态。"
8+
},
9+
"author": {
10+
"name": "Lumos-789",
11+
"url": "https://github.com/Lumos-789"
12+
},
13+
"homepage": "https://github.com/Lumos-789/guster",
14+
"repository": "https://github.com/Lumos-789/guster",
15+
"license": "MIT",
16+
"keywords": [
17+
"agent",
18+
"context",
19+
"governance",
20+
"skills",
21+
"mcp",
22+
"codex",
23+
"zcode",
24+
"dsh"
25+
],
26+
"skills": "skills"
27+
}

‎external_plugins/guster/CHANGELOG.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Changelog
2+
3+
Notable changes. Earlier history is in `git log`.
4+
5+
## 0.5.4 — 2026-11-04
6+
7+
- Removed three skill sub-pages that nothing pointed at: `init/SETUP.md`,
8+
`use/OPERATE.md`, `test/SELFTEST.md`. `SKILL.md` carries the workflow itself;
9+
the sub-pages had drifted and were never loaded.
10+
11+
## 0.5.3 — 2026-11-04
12+
13+
- `doctor` reports exactly the dimensions that enter CHI for the run's scope.
14+
`--scope hub` no longer prints RBR/PCR/SIR rows it never scores, and the
15+
always-informational GCR value is labeled `Not counted in CHI`.
16+
- `project` and `group` runs now apply one boundary to artifacts and findings:
17+
hub knowledge, hub state documents and the machine-level local wiki no longer
18+
sit in ICR/FRS/PHR denominators while their findings are filtered out. A
19+
denominator now only contains documents that can raise an in-scope finding,
20+
so those scopes no longer inherit a score from out-of-scope health.
21+
- Removed the unused `templates/` file skeletons and `schema/*.json`: nothing
22+
read them, and the project `AGENTS.md` / `.agents/README.md` text already
23+
lives in `planner.py`. `templates/hub/` is the only shipped template set and
24+
`package.json` no longer ships `schema/`.
25+
26+
## 0.5.2 — 2026-11-04
27+
28+
- Bad plan files no longer crash: a non-object plan, a malformed operation, or an
29+
unreadable plan path fails through the `[guster] ...` / plan-error output and a
30+
non-zero exit.
31+
- `guster apply --dry-run` is accepted as the documented explicit dry run and is
32+
rejected when combined with `--yes`.
33+
- A missing `--root` workspace and an unreadable or non-object Guster config now
34+
fail loud instead of silently scanning defaults.
35+
- Pointer health counts each target once per file, so a link whose text is also
36+
inline code is no longer double-counted.
37+
- Project `.agents/README.md` and hub knowledge indexes are now actually
38+
pointer-checked; the filter listed them but they were never scanned.
39+
- A refused `apply`, `init` or `hub init` prints `FAILED` instead of `APPLIED`.
40+
- The home directory is no longer classified as a project just because it holds
41+
the user-level `~/.agents/`; a fresh `init --home` setup scores clean.
42+
- The setup skill points at the shipped `skills/` directory.
43+
44+
## 0.5.1 — 2026-11-03
45+
46+
- Added reasoned `doctor.waivers` and precise pointer checks.
47+
- Fixed double-counting of linked wiki files and OpenSpec state.
48+
- Added `GUSTER_EXTRA_SKILL_ROOTS` for additional skill hosts.

‎external_plugins/guster/LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Lumos-789
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎external_plugins/guster/README.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
# Guster
2+
3+
Guster is a distributable agent plugin that audits and evolves the context of a whole machine: projects, instruction files, skills, tools, knowledge, project state, evidence and credential references. It can also scaffold a lightweight Hub for durable knowledge and project state.
4+
5+
It is the **control plane** for agent context. A Guster Hub is the optional **data plane**: the local repository that holds project cards, knowledge, tools and reports. The plugin does not replace the hub; it discovers it, validates it, and helps keep it coherent.
6+
7+
## What it does
8+
9+
- **Discovers** Git roots, `AGENTS.md` / `CLAUDE.md`, `.agents/` directories, skills, tools, knowledge, state, evidence and credential locations.
10+
- **Diagnoses** resident budgets, skill metadata budgets, copy drift, duplicate canonical sources, orphan knowledge, broken pointers, misplaced task folders, stale state, inline tokens and credentials outside the canonical root.
11+
- **Scores** context health with seven dimensions and a CHI dashboard.
12+
- **Plans** structural changes as reviewable JSON plans.
13+
- **Applies** only with `--yes`, with a backup and rollback path.
14+
- **Initializes** a standard `.agents/` layout for a new project or a new machine.
15+
- **Scaffolds** a lite Guster Hub when the user does not have a data plane yet.
16+
17+
## Quick start
18+
19+
```bash
20+
cd <checkout>
21+
./bin/guster init --home --yes
22+
./bin/guster hub init --path <hub> --yes
23+
./bin/guster scan
24+
./bin/guster doctor
25+
./bin/guster score --write
26+
```
27+
28+
The CLI is Python 3.9+ and has no third-party Python dependencies.
29+
30+
Install a stable command on your `PATH`:
31+
32+
```bash
33+
ln -s "$(pwd)/bin/guster" ~/.local/bin/guster
34+
```
35+
36+
## Commands
37+
38+
| Command | Purpose |
39+
|---|---|
40+
| `guster status` | Show plugin version, registry and health summary |
41+
| `guster scan` | Discover context assets and write `registry.json` |
42+
| `guster doctor` | Run policy checks and write `findings.json` |
43+
| `guster score` | Compute metrics and CHI; append `metrics.jsonl` |
44+
| `guster plan findings` | Turn findings into a review checklist |
45+
| `guster plan move` | Plan a move with backup and pointer |
46+
| `guster plan init` | Plan a standard `.agents/` layout |
47+
| `guster apply <plan>` | Dry-run by default; `--yes` writes with backup |
48+
| `guster init` | Initialize the state home or a project |
49+
| `guster hub init` | Create a lite Hub and attach it to the local config |
50+
| `guster hub attach` | Attach an existing Hub without copying its content |
51+
| `guster hub status` | Show the Hub manifest and contract checks |
52+
| `guster hub validate` | Validate the lite Hub contract |
53+
| `guster link` | Check context pointers |
54+
| `guster export` | Export a redacted Markdown/JSON report |
55+
| `guster credentials` | List registered credentials by scope (company / personal) |
56+
| `guster upgrade` | Check Codex/ZCode/package manifest versions |
57+
58+
## Lite Hub
59+
60+
The plugin can create a deliberately small data plane:
61+
62+
```text
63+
Guster/
64+
├── AGENTS.md
65+
├── README.md
66+
├── hub.yaml
67+
├── knowledge/
68+
│ ├── README.md
69+
│ └── general/start-here.md
70+
├── projects/
71+
│ └── _registry.md
72+
└── tools/
73+
└── README.md
74+
```
75+
76+
`tools/` is present as an index and contract, with no tool preinstalled. `handoff/` and `reports/` are optional and are not created by the lite profile. The scanner skips missing optional directories.
77+
78+
`guster hub init` refuses a non-empty target, writes a reviewable plan, and attaches the new Hub to `~/.agents/guster/config.json`. Use `guster hub attach --path <hub>` for an existing Hub.
79+
80+
The three core roots can be chosen at creation time:
81+
82+
```bash
83+
guster hub init --path <hub> --knowledge notes --projects work --tools scripts --yes
84+
```
85+
86+
They are recorded in `hub.yaml` under `paths` and can be changed later. Paths must be relative to the Hub and must stay inside it.
87+
88+
A full Hub uses `profile: full` and is scanned across knowledge, projects, handoff, reports, `Human Output`, provision, tools, manuals, cron tasks, OpenSpec changes, archive and `strategy.md`. Generated or runtime areas such as `out/`, `.manual-site/`, `.playwright-mcp/` and `.codegraph/` are not treated as knowledge sources. `--scope hub` is Hub-only; local wiki and machine-level secrets belong to the machine scope.
89+
90+
## Health model
91+
92+
```text
93+
CHI = 0.20 SSR + 0.15 RBR + 0.15 PCR + 0.15 ICR
94+
+ 0.15 FRS + 0.10 PHR + 0.10 SIR
95+
```
96+
97+
- **SSR** single-source rate
98+
- **RBR** resident budget ratio
99+
- **PCR** placement compliance rate
100+
- **ICR** index coverage rate
101+
- **FRS** state freshness rate
102+
- **PHR** pointer health rate
103+
- **SIR** secret isolation rate
104+
105+
Red-line failures override the score: credential in git, broken resident pointer, duplicate canonical source, resident hard-cap breach, or a governance entry pointing at an archived asset.
106+
107+
## Scopes
108+
109+
| Level | Command | Scored dimensions |
110+
|---|---|---|
111+
| machine | `guster doctor` | SSR RBR PCR ICR FRS PHR SIR |
112+
| hub | `guster doctor --scope hub` | SSR ICR FRS PHR |
113+
| group | `guster doctor --root A --root B` | SSR PCR ICR FRS PHR |
114+
| project | `guster doctor --root <repo>` | SSR PCR ICR FRS PHR |
115+
116+
Scoped runs write to `~/.agents/guster/scoped/<hash>/`.
117+
118+
Every scoped run applies one boundary to both sides of the report: an artifact
119+
counts toward a denominator only when a finding about it could also appear in
120+
that scope. `project` and `group` runs therefore drop hub knowledge, hub state
121+
documents and the machine-level local wiki from ICR/FRS/PHR unless they live
122+
under one of the given roots; the report table shows exactly the dimensions that
123+
enter CHI, and any extra value is labeled `Not counted in CHI`. A dimension with
124+
no in-scope artifacts stays vacuous (`0/0` in the raw column, score 1.0) instead
125+
of borrowing health from out-of-scope files. This changes CHI for `project` and
126+
`group` scopes; hub health keeps being reported by `--scope hub` and the
127+
machine-wide run.
128+
129+
## Credential registry
130+
131+
Guster reads `~/.agents/credentials/registry.md` and checks it against every credential file it finds:
132+
133+
- `secret-undeclared` - a credential file is not registered.
134+
- `secret-missing` - a registered location no longer exists.
135+
136+
The registry holds scope (`company` / `personal`), site, account, kind, location and variable names.
137+
It never holds values. `guster credentials` prints the split.
138+
139+
## The eight planes
140+
141+
1. **Truth** — code, tests, build and runtime config.
142+
2. **Instruction** — `AGENTS.md` and policies.
143+
3. **Capability** — skills, tools, MCP, plugins, scripts.
144+
4. **Knowledge** — durable principles, methods, business semantics, pitfalls.
145+
5. **State** — project cards, handoffs, environment and port registries.
146+
6. **Evidence** — reports, screenshots, videos, test output.
147+
7. **Runtime** — sessions, caches, logs, temp files, browser profiles.
148+
8. **Secret** — passwords, tokens, keys, cookies; references only.
149+
150+
## Safety
151+
152+
- Read-only by default. `apply`, `init --yes`, `hub init --yes` and `hub attach` are the only writers.
153+
- Credential values are never persisted or printed; scans keep only paths and redacted shapes.
154+
- No automatic `git add`, `commit`, `push` or deploy.
155+
- Company/public repository tracked files are not ordinary migration targets.
156+
- Plans are written to `~/.agents/guster/plans/`; backups to `~/.agents/guster/backups/`.
157+
158+
## Plugin hosts
159+
160+
| Host | Manifest |
161+
|---|---|
162+
| Codex | `.codex-plugin/plugin.json` |
163+
| ZCode | `.zcode-plugin/plugin.json` |
164+
| DSH | `package.json` + `cordis.patch.yml` |
165+
166+
All three point at `skills/` (the `guster` and `guster-hub` skills). Keep their versions synchronized.
167+
168+
```bash
169+
# DSH bundle
170+
dsh plugin add /path/to/guster
171+
```
172+
173+
### Extra skill roots
174+
175+
By default guster scans `~/.agents/skills`, `~/.codex/skills`, `~/.dsh/skills` and
176+
`~/.claude/skills`. Additional hosts stay local and are injected without changing
177+
the published source:
178+
179+
```bash
180+
export GUSTER_EXTRA_SKILL_ROOTS="name=/path/to/skills:other=/another/path"
181+
```
182+
183+
## Project layout
184+
185+
```text
186+
skills/guster/ agent-facing skill
187+
skills/guster-hub/ hub bootstrap and validation skill
188+
src/guster/ Python CLI and policy engine
189+
bin/guster executable wrapper
190+
templates/hub/ lite Hub scaffold (the only shipped template set)
191+
tests/ fixture and plugin tests
192+
```
193+
194+
## Test
195+
196+
```bash
197+
python3 -m unittest discover -s tests -v
198+
node --test tests/test_plugin.mjs
199+
```
200+
201+
## License
202+
203+
MIT © Lumos-789

0 commit comments

Comments
 (0)