From silver-bullet
Executes detailed scaffolding steps for Silver Bullet plugin: updates lifecycle skills, overwrites silver-bullet.md, manages project instruction files, runs conflict detection, and handles template refreshes. Full tool access.
How this agent operates — its isolation, permissions, and tool access model
Agent reference
silver-bullet:agents/codex/silver-init/references/scaffold-stepsThe summary Claude sees when deciding whether to delegate to this agent
This reference expands the steps summarized in `SKILL.md` Phase 3. Follow the sub-steps in order. The top-level phase gating (update vs. fresh setup) is decided in SKILL.md; this file contains only the detailed execution. --- If Phase 0 determined this is an update: 1. Refresh the SB-owned lifecycle surface from the bundled `silver:*` skills. 2. Overwrite `silver-bullet.md` from `${PLUGIN_ROOT}...This reference expands the steps summarized in SKILL.md Phase 3. Follow the sub-steps in order. The top-level phase gating (update vs. fresh setup) is decided in SKILL.md; this file contains only the detailed execution.
.silver-bullet.json already exists)If Phase 0 determined this is an update:
silver:* skills.silver-bullet.md from ${PLUGIN_ROOT}/templates/silver-bullet.md.base with placeholder replacements. Read .silver-bullet.json first for project.name and other values. This is safe — Silver Bullet owns this file.
{{PROJECT_NAME}} with the project name from .silver-bullet.json{{ACTIVE_WORKFLOW}} with the active workflow name from .silver-bullet.json (default: full-dev-cycle)CLAUDE.md in Claude, AGENTS.md in Codex), strip any SB-owned sections from it (migration from pre-v0.7.0). Check for headings matching ## N. <Known SB Title> where N is 0–9 (titles: Session Startup, Automated Enforcement, Active Workflow, NON-NEGOTIABLE, Review Loop, Session Mode, Model Routing, GSD, File Safety, Third-Party, Pre-Release). If found, remove these sections (from heading to next ## or EOF), preserving all non-SB content. Also remove old-style reference lines that do not mention silver-bullet.md.> **Always adhere strictly to this file and silver-bullet.md — they override all defaults.**$HOME/.codex/settings.json.If the user asks to refresh templates:
I'll update these files from the plugin templates:
silver-bullet.md— refresh Silver Bullet enforcement rules (SB-owned, safe to overwrite)docs/workflows/full-dev-cycle.md— pull latest workflow steps Proceed? (yes / no)
silver-bullet.md from ${PLUGIN_ROOT}/templates/silver-bullet.md.base with placeholder replacements (SB-owned, no confirmation needed).<file>.backup first..silver-bullet.json to carry forward project.name, project.src_pattern customizations.Write silver-bullet.md from ${PLUGIN_ROOT}/templates/silver-bullet.md.base. This is always safe — it's a new file owned by Silver Bullet.
Perform these placeholder replacements:
{{PROJECT_NAME}} → the detected/confirmed project name{{ACTIVE_WORKFLOW}} → full-dev-cycle (default)Keep user-facing bootstrap language runtime-neutral. In Codex, describe the local instruction surface as a project instruction file and avoid runtime-specific model-routing jargon; when the repository actually uses AGENTS.md, reconcile that file in place rather than synthesizing a new one.
Check if a project instruction file exists in the project root (CLAUDE.md or AGENTS.md, depending on the runtime).
If NO existing project instruction file: do not create a new agent instruction file during Codex initialization. Silver Bullet's own instructions live in silver-bullet.md; a project instruction file is optional.
If an existing project instruction file is present: First, strip any existing Silver Bullet sections (migration from pre-v0.7.0). Then add the reference line and run conflict detection.
Step 1 — Strip SB-owned sections from the project instruction file:
Silver Bullet sections are identified by headings matching ## N. <Known SB Title> where N is 0–9 (including ## 3a.). Known titles include: Session Startup, Automated Enforcement, Active Workflow, NON-NEGOTIABLE, Review Loop, Session Mode, Model Routing, GSD, File Safety, Third-Party, Pre-Release. These sections start at the heading and end just before the next ## heading or end-of-file.
Run via shell to detect SB sections:
grep -nE '^## [0-9]+[a-z]?\. (Session Startup|Automated Enforcement|Active Workflow|NON-NEGOTIABLE|Review Loop|Session Mode|Model Routing|GSD|File Safety|Third-Party|Pre-Release)' CLAUDE.md AGENTS.md 2>/dev/null || echo "NO_SB_SECTIONS"
If NO_SB_SECTIONS → skip to Step 2.
If sections found:
## N. heading to just before the next ## heading or EOF)> **Always adhere strictly to this file — it overrides all defaults.** (note: this is the pre-separation version that does NOT mention silver-bullet.md)Step 2 — Add reference line:
Add at the very top of the file (before any other content):
> **Always adhere strictly to this file and silver-bullet.md — they override all defaults.**
But ONLY if the file does not already contain the string "silver-bullet.md".
Then run conflict detection (step 3.1c).
Scan the project instruction file for patterns that conflict with silver-bullet.md rules. Check for these conflict patterns:
(always|default|prefer|use).*(claude-opus|claude-sonnet|opus|sonnet) on directive-like lines (conflicts with SB Section 5)(always|never|must).*(subagent-driven|executing-plans) on directive-like lines (conflicts with SB Section 6)(skip|disable|no).*(review.*loop|code.review)|approved.*(once|single) on directive-like lines (conflicts with SB Section 3a)(override|replace|ignore).*(workflow|silver.bullet) on directive-like lines (conflicts with SB Section 2)(always|default|must).*(interactive|autonomous).*mode on directive-like lines (conflicts with SB Section 4)For each match found, present it to the user directly:
If user selects A, use the active runtime file-editing mechanism to remove the line. If user selects B, leave it. If user selects C, stop checking further conflicts.
mkdir -p docs/specs docs/workflows .codex/rules
When the active runtime is Cursor or .codex/ already exists in the project, copy the SB orchestrator rule so agents see the directive contract even before hook injection:
mkdir -p .codex/rules
cp "${PLUGIN_ROOT}/templates/cursor-rules/silver-orchestrator.mdc" .cursor/rules/silver-orchestrator.mdc
Idempotent — safe to overwrite on /silver:init refresh (SB-owned file).
Copy worker prompt templates for parent-mode Task delegation:
mkdir -p .silver-bullet/orchestrator-workers
cp -R "${PLUGIN_ROOT}/templates/orchestrator-workers/." .silver-bullet/orchestrator-workers/
Set orchestrator_mode to "parent" in .silver-bullet.json (only supported mode).
Check if a GitHub Actions CI workflow exists:
test -d .github/workflows && ls .github/workflows/*.yml 2>/dev/null | head -1
If no CI workflow exists, create .github/workflows/ and generate ci.yml based on the detected stack from Phase 2. Select the matching template from references/ci-templates.md and write it to .github/workflows/ci.yml. For unknown stacks, prompt user to specify verify commands and store under "verify_commands" in .silver-bullet.json.
Applies only when an existing project instruction file was found in step 3.1b. If none was found, skip this step — Silver Bullet does not synthesize a new project instruction file during Codex init.
Read ${PLUGIN_ROOT}/templates/CLAUDE.md.base, perform replacements, write back to the existing filename (CLAUDE.md or AGENTS.md):
{{PROJECT_NAME}} → the detected/confirmed project name{{TECH_STACK}} → the detected/confirmed tech stack{{GIT_REPO}} → the detected/confirmed repo URLRead ${PLUGIN_ROOT}/templates/silver-bullet.config.json.default, replace {{PROJECT_NAME}}, set src_pattern to the detected value (replacing default /src/ if different), set sb_initiated to true, and write to .silver-bullet.json.
Copy both workflow templates to docs/workflows/, backing up any existing file first:
${PLUGIN_ROOT}/templates/workflows/full-dev-cycle.md → docs/workflows/full-dev-cycle.md (back up existing to .backup)${PLUGIN_ROOT}/templates/workflows/devops-cycle.md → docs/workflows/devops-cycle.md (back up existing to .backup)Also copy ${PLUGIN_ROOT}/scripts/workflows.sh → scripts/workflows.sh (executable) when absent — required for autonomous flow-advance workflow tracking in downstream projects.
Copy ${PLUGIN_ROOT}/scripts/workflows.sh → scripts/workflows.sh (create scripts/ if missing, chmod +x). Required for flow-advance.sh auto workflow tracker (Wave 0.8).
silver:init no longer performs direct docs migration/scaffolding.
Invoke through the active runtime's SB-recognized skill invocation channel:
silver:ensure-docs --bootstrap
silver:ensure-docs is responsible for:
docs/archive/<timestamp>/... with manifest traceability.docs/doc-scheme.md and docs/doc-scheme.json synchronized.docs/task-doc-checklist.json against the contract inventory.After silver:ensure-docs --bootstrap, verify these files exist and are not symlinks:
docs/doc-scheme.mddocs/doc-scheme.jsondocs/task-doc-checklist.jsonIf any are missing, stop and rerun:
silver:ensure-docs --recover-scheme
git add silver-bullet.md .silver-bullet.json docs/
if test -f CLAUDE.md; then
git add CLAUDE.md
fi
if test -f AGENTS.md; then
git add AGENTS.md
fi
git commit -m "$(cat <<'EOF'
feat: initialize Silver Bullet enforcement
Co-Authored-By: host-appropriate co-author line
EOF
)"
If the commit fails due to a pre-commit hook, read the error, fix the issue, re-stage, and create a new commit (do NOT use --amend).
Merges the SB hook entries into the user's global host settings file so hooks remain active in projects installed without the marketplace (e.g. manual installs, workspace clones). Target the active host hooks manifest path (see docs/RUNTIME-COMPATIBILITY.md).
Resolve the plugin install path:
INSTALL_PATH=$(python3 -c "
import json, os, sys
reg = os.path.expanduser('$HOME/.codex/plugins/installed_plugins.json')
with open(reg) as f:
data = json.load(f)
plugins = data.get('plugins', {})
for key, entries in plugins.items():
if 'silver-bullet' in key:
path = entries[0].get('installPath', '')
if path:
print(path)
sys.exit(0)
sys.exit(1)
" 2>/dev/null)
echo "SB install path: ${INSTALL_PATH:-NOT FOUND}"
If INSTALL_PATH is empty, skip this step silently and continue.
Verify core-rules integrity pin (L-02):
After resolving INSTALL_PATH, confirm ${INSTALL_PATH}/hooks/core-rules.sha256 matches ${INSTALL_PATH}/hooks/core-rules.md. If the pin file is missing or mismatched, warn the user to reinstall the plugin from the official marketplace — do not proceed silently on a tampered hooks directory.
HOOKS_DIR="${INSTALL_PATH}/hooks"
if [[ -f "$HOOKS_DIR/core-rules.md" && -f "$HOOKS_DIR/core-rules.sha256" && -f "$HOOKS_DIR/lib/core-rules-integrity.sh" ]]; then
# shellcheck source=/dev/null
source "$HOOKS_DIR/lib/core-rules-integrity.sh"
sb_core_rules_integrity_ok "$HOOKS_DIR/core-rules.md" "$HOOKS_DIR" || \
echo "WARN: core-rules.md integrity pin mismatch — reinstall Silver Bullet"
fi
Merge hooks idempotently:
if [[ "${SILVER_BULLET_RUNTIME:-}" == "cursor" ]]; then
python3 "${PLUGIN_ROOT}/skills/silver-init/scripts/merge-cursor-hooks.py" "$INSTALL_PATH"
else
python3 "${PLUGIN_ROOT}/skills/silver-init/scripts/merge-hooks.py" "$INSTALL_PATH"
fi
scripts/merge-hooks.py substitutes the plugin install path, removes stale mirrored Silver Bullet hook registrations from other app roots or placeholder entries, and appends only new hook entries — never duplicates. On nonzero exit, warn but do NOT stop init:
⚠️ Could not auto-register hooks in the host settings file. Run
/silver:initagain after installation completes, or add hooks manually fromhooks/hooks.json.
Idempotent — re-running /silver:init adds no duplicate entries.
Do not activate lifecycle-overlap plugins for core SB workflows. If the user explicitly requests an optional enrichment plugin later, route through that plugin's own install/activation flow at that time.
Output:
Silver Bullet initialized. Start any task and the active workflow will be enforced automatically.
npx claudepluginhub alo-exp/silver-bullet --plugin silver-bulletExpert Go code reviewer that analyzes diffs, runs go vet and staticcheck, and checks for idiomatic Go, concurrency bugs, error handling, and security issues.