108 lines
7.1 KiB
Markdown
108 lines
7.1 KiB
Markdown
---
|
|
name: tooling-guide
|
|
description: Inventory the current jsc plugins, skills, hook management, and usage paths as the baseline tooling guide. Use when the user asks for a skill-set guide, tooling map, supported plugin list, supported skill list, hook management overview, or onboarding reference. Do not use for installing, updating, deleting, auditing, or repairing the skill set; use jsc-cli:deploy, jsc-meta:skill-check, jsc-meta:skill-update, jsc-meta:skill-delete, or jsc-hooks:hooks-install instead.
|
|
---
|
|
|
|
# tooling-guide - build the baseline tooling guide
|
|
|
|
Goal: produce a current guide for the jsc skill set from the local repos and the supported tooling scripts.
|
|
|
|
Single source of guidelines: [`../../references/guidelines.md`](../../references/guidelines.md).
|
|
|
|
## Rules
|
|
|
|
- Keep the guide factual and current.
|
|
- Prefer script output over copied lists.
|
|
- Use `tools/inventory-tooling.sh` for the baseline inventory.
|
|
- Keep command syntax in the guide only when it comes from README files or tool output.
|
|
- Do not modify README files, manifests, marketplace files, hooks, tools, or other skills.
|
|
- Put generated guide text in the response or in the user-requested target only.
|
|
- Run detail synthesis as a sub agent when the guide needs explanations, grouping, or onboarding prose.
|
|
|
|
Done when these rules are all checked before the final report.
|
|
|
|
## Inputs
|
|
|
|
- Optional user scope: plugin inventory, skill inventory, hook management, CLI usage, or all areas.
|
|
- Optional output target: chat response, wiki draft text, or a named file that the user explicitly requests.
|
|
|
|
Done when the scope and output target are known. If the user gives no scope, use all areas. If the user gives no target, return the guide in chat.
|
|
|
|
## Flow
|
|
|
|
1. Confirm the working roots. Use `/root/plugins/meta` as the meta root. Use sibling repos under `/root/plugins` for current domain checkouts. Completion condition: the meta root exists and contains `references/guidelines.md`.
|
|
|
|
2. Sync the domain inventory with `tools/sync-domains.sh` from the meta root. This script owns marketplace discovery and local repo synchronization.
|
|
- Exit 0: continue with the printed `domain<TAB>path` rows.
|
|
- Exit 3: keep the printed rows, report every skipped or dirty repo from stderr as stale input, and continue only after the user accepts a guide with stale rows.
|
|
- Exit 2: report the clone failure and stop.
|
|
- Exit 1: report the unreadable canonical marketplace and stop.
|
|
|
|
Completion condition: each plugin row used by the guide has a domain and a local path, or the stale-input decision is recorded.
|
|
|
|
3. Build the baseline guide with `tools/inventory-tooling.sh` from the meta root. Use its Markdown output as the base document.
|
|
- Exit 0: continue with the generated guide.
|
|
- Any other exit: report the command, exit code, and stderr, then stop.
|
|
|
|
Completion condition: the generated guide contains `Source freshness`, `Supported plugins`, `Supported skills`, `Supported CLIs`, `Hook management`, `Plugin and skill management`, `Operational checks`, and `Use this when`.
|
|
|
|
4. Build the skill catalog with `tools/list-skills.sh` from the meta root. Use its TSV rows as the skill list when the baseline guide needs verification or a smaller scope.
|
|
- Exit 0: continue with the printed `domain<TAB>name<TAB>description` rows.
|
|
- Any other exit: report the command, exit code, and stderr, then stop.
|
|
|
|
Completion condition: every skill row used by the guide comes from the script output.
|
|
|
|
5. Detect supported CLIs with `/root/plugins/cli/tools/detect-clis.sh`. Use its TSV rows as the installed CLI list when the baseline guide needs verification or a smaller scope.
|
|
- Exit 0 with rows: continue with the printed `name<TAB>path<TAB>version` rows.
|
|
- Exit 0 with no rows: continue and mark CLI-specific checks as not available on this machine.
|
|
- Any other exit: report the command, exit code, and stderr, then stop.
|
|
|
|
Completion condition: the guide states the detected CLI set, or states that no installed CLI was detected.
|
|
|
|
6. Collect hook wiring facts for each detected CLI with `/root/plugins/hooks/tools/wire-cli.sh status {cli}`. Use `status` only when the baseline guide needs verification or a smaller scope.
|
|
- Exit 0, 1, or 5: keep the status and all `item` lines.
|
|
- Exit 3: mark that CLI as skipped.
|
|
- Exit 2: fix the CLI code from the detect output and rerun.
|
|
- Any other exit: report the command, exit code, and stderr, then mark the hook status as unknown.
|
|
|
|
Completion condition: every detected CLI has one hook-wiring verdict, or the guide states why the verdict is unknown.
|
|
|
|
7. Collect management-flow facts from the current docs and skills. Read only README files, `SKILL.md` files, and tool help or headers from `tools/` under the synced domain repos. Do not infer support from missing or stale files. Completion condition: each management flow in the guide points to one source file or one tool output.
|
|
|
|
8. Synthesize the guide. This step MUST run as a sub agent when the output needs explanations, grouping, onboarding prose, or cross-domain comparison. Give the sub agent only the collected inventories, the relevant README and SKILL paths, and this required section list:
|
|
- Supported plugins
|
|
- Supported skills
|
|
- Supported CLIs and usage forms
|
|
- Hook management
|
|
- Plugin and skill management
|
|
- Health checks and repair paths
|
|
- Known coverage limits
|
|
|
|
Completion condition: the sub agent returns a guide draft with every required section and with source paths for each factual claim.
|
|
|
|
9. Verify the draft in the main agent.
|
|
- Check that each plugin comes from `sync-domains.sh`.
|
|
- Check that each skill comes from `list-skills.sh`.
|
|
- Check that each hook-wiring fact comes from `wire-cli.sh status`.
|
|
- Check that install, update, delete, audit, repair, and health-check actions point to the owning skill or tool.
|
|
- Check that the draft does not copy long implementation details from README files or scripts.
|
|
|
|
Completion condition: every factual claim has a source path or tool output, and no required section is empty.
|
|
|
|
10. Deliver the guide in the requested target. If the target is chat, keep it concise and include the source paths used. If the target is a file, write only that user-requested file and do not update manifests or README files. Completion condition: the guide is delivered and the final report names the target, source freshness, stale inputs if any, and any unknown hook verdicts.
|
|
|
|
## Output Contract
|
|
|
|
The guide must include these fields in this order:
|
|
|
|
1. `Source freshness`: synced, stale accepted, or blocked.
|
|
2. `Supported plugins`: one row per domain.
|
|
3. `Supported skills`: one row per skill.
|
|
4. `Supported CLIs`: one row per detected CLI, or one sentence for none detected.
|
|
5. `Hook management`: wiring, smoke, error scan, repair owner, and coverage limits.
|
|
6. `Plugin and skill management`: install, update, delete, audit, and creation owners.
|
|
7. `Operational checks`: doctor, setup, version guard, restart gate, language guard, and comment-scope guard.
|
|
8. `Use this when`: short usage guidance for maintainers.
|
|
|
|
Done when the output has all fields in order and each non-empty table has at least one source reference.
|