Blacklight Add Agent or Artifact
Add the catalog baseline deterministically, then complete the code surfaces that require semantic decisions. Treat an "agent" as an AI coding/agentic tool supported by Blacklight, not as a Codex subagent profile.
Choose the operation
- New agent/tool: require a canonical tool id, home-relative root, and at least one config path. Use
add-agent.
- New artifact: require the existing tool id, stable artifact id, family, home-relative path, path kind, priority, evidence source, and assessment coverage. Use
add-artifact.
- Codex custom subagent: do not use this workflow. Project profiles belong in
.codex/agents/*.toml and use the Codex custom-agent schema.
Establish evidence first
- Confirm the path from sanitized documentation, a lab system, or existing parser behavior.
- Never copy credential values, session content, host-identifying paths, or raw evidence into catalogs, fixtures, docs, or prompts.
- Classify the path with the existing family vocabulary whenever possible:
root, auth, config, mcp, sessions, history, workspace, rules, plugins, extensions, skills, plans, telemetry, sandbox, cache, or logs.
- Use
explicitly_assessed only when Scout targets the exact path. Use recursively_discovered for bounded descendant matching and intentionally_deferred when cataloged without collection or parsing.
Scaffold the catalogs
Run from the repository root. Omit --write for a preview.
python skills/blacklight-add-agent-artifact/scripts/scaffold.py --write add-agent \
--tool example_agent \
--root-path .example-agent \
--config-path .example-agent/settings.json
python skills/blacklight-add-agent-artifact/scripts/scaffold.py --write add-artifact \
--tool cursor \
--artifact-id cursor.example_state \
--family workspace \
--relative-path .cursor/example-state.json \
--path-kind file \
--priority medium
Use --rules-only for globs, recursively discovered paths, and intentionally deferred artifacts that must not become exact Scout targets. Add --analyze-confirmed only when the named path is actually consumed by run_session_detail.
The script updates:
blacklight-scout/catalog/targets.jsonblacklight-rules/catalog/confirmed_artifacts.jsonblacklight-scout/catalog/static_targets_generated.hblacklight-scout/managed/GeneratedTargets.cs
It refuses duplicate ids, duplicate paths, unknown tools, invalid home-relative paths, glob Scout targets, and inconsistent coverage choices.
Complete semantic integration
Read integration-surfaces.md after scaffolding. Inspect each listed surface and change only those required by the requested support level. A new catalog row does not imply parsing support.
For a new agent, explicitly decide and document whether the change is:
- discovery-only,
- metadata triage,
- Analyze parsing,
- Rules/detection coverage, or
- full end-to-end support.
Do not claim a broader level than the implemented and tested surfaces establish.
Validate
Run the focused gates:
python blacklight-scout/catalog/generate_targets.py
python -m unittest blacklight.tests.test_targets_catalog blacklight.tests.test_rules_content -v
Then run tests for every semantic surface changed. Review git diff for generated-file drift, cross-platform path parity, canonical family alignment, secret leakage, and unrelated edits.
1---2name: blacklight-add-agent-artifact3description: Add a newly supported AI agent/tool or a newly discovered artifact file, directory, or glob to Blacklight while keeping Scout and Rules catalogs, generated target tables, schemas, and validation surfaces aligned. Use for requests to add agent support, register an artifact path, extend an existing agent directory inventory, or scaffold cross-platform target metadata.4---56# Blacklight Add Agent or Artifact78Add the catalog baseline deterministically, then complete the code surfaces that require semantic decisions. Treat an "agent" as an AI coding/agentic tool supported by Blacklight, not as a Codex subagent profile.910## Choose the operation1112- **New agent/tool**: require a canonical tool id, home-relative root, and at least one config path. Use `add-agent`.13- **New artifact**: require the existing tool id, stable artifact id, family, home-relative path, path kind, priority, evidence source, and assessment coverage. Use `add-artifact`.14- **Codex custom subagent**: do not use this workflow. Project profiles belong in `.codex/agents/*.toml` and use the Codex custom-agent schema.1516## Establish evidence first17181. Confirm the path from sanitized documentation, a lab system, or existing parser behavior.192. Never copy credential values, session content, host-identifying paths, or raw evidence into catalogs, fixtures, docs, or prompts.203. Classify the path with the existing family vocabulary whenever possible: `root`, `auth`, `config`, `mcp`, `sessions`, `history`, `workspace`, `rules`, `plugins`, `extensions`, `skills`, `plans`, `telemetry`, `sandbox`, `cache`, or `logs`.214. Use `explicitly_assessed` only when Scout targets the exact path. Use `recursively_discovered` for bounded descendant matching and `intentionally_deferred` when cataloged without collection or parsing.2223## Scaffold the catalogs2425Run from the repository root. Omit `--write` for a preview.2627```bash28python skills/blacklight-add-agent-artifact/scripts/scaffold.py --write add-agent \29 --tool example_agent \30 --root-path .example-agent \31 --config-path .example-agent/settings.json32```3334```bash35python skills/blacklight-add-agent-artifact/scripts/scaffold.py --write add-artifact \36 --tool cursor \37 --artifact-id cursor.example_state \38 --family workspace \39 --relative-path .cursor/example-state.json \40 --path-kind file \41 --priority medium42```4344Use `--rules-only` for globs, recursively discovered paths, and intentionally deferred artifacts that must not become exact Scout targets. Add `--analyze-confirmed` only when the named path is actually consumed by `run_session_detail`.4546The script updates:4748- `blacklight-scout/catalog/targets.json`49- `blacklight-rules/catalog/confirmed_artifacts.json`50- `blacklight-scout/catalog/static_targets_generated.h`51- `blacklight-scout/managed/GeneratedTargets.cs`5253It refuses duplicate ids, duplicate paths, unknown tools, invalid home-relative paths, glob Scout targets, and inconsistent coverage choices.5455## Complete semantic integration5657Read [integration-surfaces.md](references/integration-surfaces.md) after scaffolding. Inspect each listed surface and change only those required by the requested support level. A new catalog row does not imply parsing support.5859For a new agent, explicitly decide and document whether the change is:6061- discovery-only,62- metadata triage,63- Analyze parsing,64- Rules/detection coverage, or65- full end-to-end support.6667Do not claim a broader level than the implemented and tested surfaces establish.6869## Validate7071Run the focused gates:7273```bash74python blacklight-scout/catalog/generate_targets.py75python -m unittest blacklight.tests.test_targets_catalog blacklight.tests.test_rules_content -v76```7778Then run tests for every semantic surface changed. Review `git diff` for generated-file drift, cross-platform path parity, canonical family alignment, secret leakage, and unrelated edits.
specterops