convez.ai
AgenteDevOps & InfraestruturaAvançado
alo-exp

Silver Bullet

alo-exp/silver-bullet

Camada de orquestração de processo para delivery agentic seguro e disciplinado

Ver no GitHub
BomPluginScore · de 0 a 100

Orquestrador de Processos Agentic que compõe workflows de engenharia de software e DevOps ao redor do GSD. Automatiza sequenciamento entre plugins, enforce de quality gates, traceability e entrega disciplinada para agentes de código como Claude.

Instalação

$npx convez-ai alo-exp/silver-bullet

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
7
Forks
3
Acompanhando
1
Saúde
100%
Último commit
há 2 dias
Versão
v0.33.0
Issues abertas
14
Contribuidores
3

Casos de uso

  • Orquestrar workflows complexos de desenvolvimento com enforcement de gates de qualidade
  • Coordenar sequenciamento automático entre múltiplos plugins e ferramentas DevOps
  • Garantir disciplina processual e rastreabilidade em deployments e releases

Veredito

Silver Bullet é um orchestrator robusto para quem precisa de disciplina processual real em pipelines agentic, não marketing. Complementa bem o GSD preservando separação de responsabilidades, mas exige compreensão profunda da stack para máximo valor.

README

A tradução para o português deste README ainda está na fila.

Silver Bullet

version license

Agentic Process Orchestrator for AI-native Software Engineering and DevOps.

Silver Bullet is the orchestration and enforcement layer around GSD. GSD remains the lifecycle engine: project state, roadmaps, phase planning, execution, verification, review, ship, and milestone work. Silver Bullet adds the missing operating system around that engine: dynamic workflow composition, hook-backed gates, cross-plugin sequencing, quality controls, traceability, documentation governance, and release discipline.

Plain version: describe what you want to do. Start with /silver. Silver Bullet classifies the task, composes the right workflow for that task, invokes GSD where GSD owns the lifecycle, and keeps the agent from skipping required steps before code, PRs, deploys, or releases.

"There is no single development, in either technology or management technique, which by itself promises even one order-of-magnitude improvement..." - Fred Brooks, 1986

Brooks was right. Silver Bullet is not one magic technique. It is the coordinated process layer that makes AI-native delivery less dependent on agent memory and operator vigilance.

What Silver Bullet Adds

GSD is already a strong planning and execution system. Silver Bullet adds the APO layer around it:

AreaPlain GSDSilver Bullet + GSD
Entry pointgsd:* commands and gsd:do/silver routes freeform work into a task-shaped SB+GSD workflow
Workflow shapeGSD lifecycle commandsDynamic composition from 18 atomic flows
Process disciplineInstructional and artifact-drivenHook-enforced and state-tracked
Cross-plugin workManual or ad hocExplicit sequencing across GSD, SB gates, and selected helper plugins
QualityGSD review and verificationProduct, security, DevOps, docs, UAT, CI, and release gates
Delivery safetyOperator discipline plus GSD artifactsMechanical blocks on unsafe edits, planning-file writes, PRs, deploys, and releases
ContinuityGSD state and phase artifactsSession logs, handoff, issue capture, knowledge capture, anti-stall checks, and forensics

The important distinction: Silver Bullet does not replace GSD. It composes around GSD and preserves GSD as the authority for .planning/, semver-relevant project work, execution, verification, review, ship, and milestone lifecycle.

Current Positioning

Silver Bullet is an Agentic Process Orchestrator (APO):

  • Agentic: built for AI coding agents that can forget, shortcut, overfit, or over-trust their own prior context.
  • Process: turns SDLC discipline into explicit flows, artifacts, and gates.
  • Orchestrator: chooses and sequences the right tools for the task instead of forcing every task through one rigid workflow.

Silver Bullet uses helper plugins only at selected boundaries. Superpowers is used for SB-required helper surfaces such as TDD, review framing, review receiving, verification-before-completion, and branch finishing when the active workflow calls for them. It is not the execution engine; GSD owns execution.

How It Works

You normally start with:

/silver improve the account settings page and ship it safely

The router classifies the request, displays the selected route, and invokes the appropriate SB or GSD workflow. Examples:

IntentTypical routeWhy
Build or enhance a featuresilver:featureAdds SB gates around GSD planning, execution, review, verification, and ship
Fix a regressionsilver:bugfixInserts debug/TDD before the normal lifecycle
Work on UIsilver:uiAdds design contract and UI quality review around GSD execution
Change infrastructuresilver:devopsAdds blast radius, IaC gates, promotion, and rollback discipline
Research a decisionsilver:researchProduces a decision artifact before implementation
Prepare a releasesilver:releaseRuns documentation, UAT, milestone, release, and publication gates
Make a small safe editsilver:fastRoutes low-risk work through a lighter path
Ask GSD to choose a lifecycle actiongsd:doDelegates directly to GSD where GSD owns the decision

Dynamic Composition, Not A Fixed Script

Silver Bullet starts from two workflow families, then composes the exact flow chain needed for the task:

Workflow familyUse forComposition surface
full-dev-cycleApplications, APIs, CLIs, libraries, plugin workClarify, specify, plan, execute, review, secure, verify, document, ship, release
devops-cycleTerraform, Kubernetes, Helm, CI/CD, cloud, opsIncident path, blast radius, IaC quality, environment promotion, deploy/rollback, release

The canonical flow catalog lives in docs/composable-flows-contracts.md. It contains 18 atomic flows:

BOOTSTRAP -> ORIENT -> CLARIFY -> DECIDE -> SPECIFY -> PLAN
-> DESIGN CONTRACT -> EXECUTE -> UI QUALITY -> REVIEW -> SECURE
-> VERIFY -> QUALITY GATE -> SHIP -> DEBUG -> DESIGN HANDOFF
-> DOCUMENT -> RELEASE

/silver includes only the flows whose prerequisites and triggers apply. For example, a UI bugfix can include DEBUG, DESIGN CONTRACT, EXECUTE, UI QUALITY, REVIEW, VERIFY, and SHIP without pretending every task needs a release flow.

Enforcement Model

Silver Bullet is intentionally more than instructions in a README. It installs hooks that observe real tool usage and state transitions.

Common examples:

HARD STOP - Planning incomplete.
Missing: silver-quality-gates, gsd-discuss-phase, gsd-plan-phase
Run the missing planning steps before editing source code.
COMPLETION BLOCKED - Workflow incomplete.
Final delivery requires review, security, validation, test freshness,
release readiness, and ship markers before PR/deploy/release commands proceed.
Silver Bullet: 8 steps | PLANNING 3/3 | REVIEW 1/3 | FINALIZATION 0/4
Next: requesting-code-review

Two-Tier Delivery Discipline

Silver Bullet deliberately does not block every useful intermediate commit.

  • Planning floor: source edits and intermediate development commits require the selected SB+GSD pre-execution chain.
  • Final delivery floor: PR creation, deploy commands, release commands, and completion claims require the broader review/security/validation/test/release chain.

This keeps GSD's atomic task commits viable while still blocking premature final delivery.

Enforcement Layers

LayerHook or surfacePurpose
1record-skill.shRecords completed SB/GSD/helper skill invocations
2record-requested-skill.shRecords requested /silver and GSD routes before work starts
3prompt-reminder.shRe-injects missing steps and core rules before each user prompt
4dev-cycle-check.shBlocks source edits before the required planning floor
5workflow-chain-guard.shBlocks active composed workflows when downstream dependency markers are missing
6dependency-skill-check.shFails closed when required dependency skills are unavailable
7planning-file-guard.shBlocks direct edits to GSD-owned planning artifacts
8completion-audit.shBlocks PR/deploy/release and selected delivery commands when final gates are missing
9ci-status-check.shBlocks push, PR, and release while CI is red; commit remains warning-only so CI fixes are possible
10stop-check.shBlocks task-complete declarations when required gates are missing
11uat-gate.sh and spec-floor-check.shEnforce minimum spec and UAT evidence before lifecycle completion
12forbidden-skill-check.sh, instruction-file-guard.sh, trivial-file-guard.shProtect against deprecated paths, unsafe instruction-file creation, and legacy bypass abuse

Additional support hooks handle session logging, timeout/stall warnings, semantic compression, roadmap freshness, PR traceability, phase archive safety, and compliance status.

Hook-backed enforcement requires a runtime that supports the relevant hook events. In less capable runtimes, Silver Bullet can still provide workflow guidance, but hard blocks depend on host support.

Runtime Support

RuntimeStatusNotes
Claude CodePrimary plugin runtimeUses Claude plugin skills, commands, and hooks
CodexSupported package runtimeUses an SB-only Codex package plus dependency marketplaces
KayTested agent for isolated live testingUsed for isolated live testing via the opencode-go provider path

Silver Bullet's Codex package intentionally contains only SB-owned surfaces: skills, hooks, templates, commands, and helper scripts. GSD, Superpowers, and selected helper plugins are installed from their own official sources or via thin Codex wrappers in the shared alo-labs/codex-plugins marketplace.

Install

Install jq first:

brew install jq
# or
sudo apt install jq

Claude Code

Install Silver Bullet and its required helper dependencies:

/plugin install alo-exp/silver-bullet
/plugin install obra/superpowers
/plugin install anthropics/knowledge-work-plugins/tree/main/engineering
/plugin install anthropics/knowledge-work-plugins/tree/main/design
/plugin install anthropics/knowledge-work-plugins/tree/main/product-management

Install GSD:

npx get-shit-done-cc@latest

Then open a project and run:

/silver:init

Codex

For normal use, install or refresh Silver Bullet from the public Codex marketplace. The published package exposes SB through the native /Silver: picker namespace, keeps internal skill-source/ files hidden from duplicate plugin listings, and wires hooks through the package manifest.

For local development from this repository checkout, use the same installer with legacy cleanup enabled:

./scripts/install-codex.sh --purge-legacy-skills

The installer:

  • syncs the curated SB-only Codex bundle in plugins/silver-bullet/
  • registers the shared alo-labs/codex-plugins marketplace
  • installs or wires GSD, Superpowers, Engineering, Design, and Product Management from their official sources when needed
  • keeps /silver and /silver:* in the main Silver Bullet package
  • includes the packaged scripts/workflows.sh helper used by composed workflow tracking
  • includes the scripts/silver-bullet invoke-skill <name> Codex adapter so required skills can be invoked and recorded without a Claude-only Skill tool
  • enables SB only when the current working directory is an actual SB project root (.silver-bullet.json plus silver-bullet.md)
  • purges stale SB user-level hook entries so unrelated Codex projects do not get Silver Bullet hooks
  • seeds Codex hook trust from the installed plugin manifest instead of duplicating SB hooks into the user's global hook cache

For isolated Codex-compatible live testing, Kay v0.9.6 plus the opencode-go provider path is the tested route. The live harness creates a temporary KAY_HOME root so tests do not rewrite the user's real Kay or Codex hook cache.

Optional DevOps Plugins

The devops-cycle works without optional DevOps plugins, but these enrich provider-specific work when installed:

/plugin marketplace add hashicorp/agent-skills
/plugin marketplace add awslabs/agent-plugins
/plugin marketplace add pulumi/agent-skills
/plugin marketplace add ahmedasmar/devops-claude-skills
/plugin marketplace add wshobson/agents

Silver Bullet detects installed DevOps plugins during /silver:init and records availability in .silver-bullet.json.

Project Initialization

Run this once in a project:

/silver:init

It will:

  • detect project name, source paths, stack, and workflow type
  • create or update .silver-bullet.json
  • create silver-bullet.md from templates/silver-bullet.md.base
  • reconcile existing host instruction files (CLAUDE.md in Claude, AGENTS.md in Codex) without overwriting user-owned content
  • copy workflow docs into docs/workflows/
  • scaffold the documentation scheme and durable knowledge/lessons folders
  • initialize or connect GSD planning artifacts
  • set up enforcement state paths under ${SB_RUNTIME_HOME_ROOT}/.silver-bullet/

After that, use /silver for normal work.

Built-In Skills And Routes

Route or skillPurpose
/silverMain natural-language router and APO entry point
/silver:initProject setup, dependency checks, config, workflow docs, doc scheme
/silver:featureFeature workflow around GSD lifecycle
/silver:bugfixDebug/TDD-oriented bugfix workflow
/silver:uiUI workflow with design contract and UI quality gates
/silver:devopsInfrastructure workflow with blast radius and IaC gates
/silver:researchResearch and decision workflow
/silver:specSpec and requirements elicitation
/silver:ingestExternal artifact ingestion with manifest review
/silver:validateGap analysis and validation before implementation or release
/silver:releaseRelease preparation workflow
/silver:create-releaseFinal release artifact creation after GSD release readiness
/silver:fastSmall, low-risk work through a routed fast path
/silver:ensure-docsDocumentation scheme bootstrap, reconciliation, and recovery
/silver:scanRetrospective session scan for deferred issues and insights
/silver:addFile an issue or backlog item
/silver:removeRemove or close an issue/backlog item
/silver:remCapture knowledge or lessons learned
/silver:handoffCreate a project-level handoff prompt
/silver:forensicsReconstruct failed, stalled, or abandoned sessions
/silver:quality-gatesProduct/software quality assessment
/silver-blast-radiusDevOps change-impact and rollback assessment
/devops-quality-gatesIaC quality assessment
/devops-skill-routerSelects optional DevOps plugin skills for the current toolchain
/verify-testsRuns configured verification commands or stack defaults and writes a freshness marker

Workflow contracts use logical names such as silver:feature. In Codex, SB mirrors its packaged skill-source/ files into the native ~/.codex/skills surface so the picker shows a single /Silver: namespace instead of plugin prefixed duplicates.

In Codex, use silver-bullet invoke-skill <name> when SB requires a recorded skill invocation and the runtime has no callable Skill tool. Directly reading SKILL.md is loaded-only metadata and does not satisfy workflow gates.

Configuration

Project config lives in .silver-bullet.json. The default source of truth is templates/silver-bullet.config.json.default.

Minimal shape:

{
  "config_version": "0.37.0",
  "version": "0.37.0",
  "project": {
    "name": "my-app",
    "src_pattern": "/src/",
    "src_exclude_pattern": "__tests__|\\.test\\.",
    "active_workflow": "full-dev-cycle"
  },
  "skills": {
    "required_planning": [
      "silver-quality-gates",
      "gsd-discuss-phase",
      "gsd-plan-phase"
    ],
    "required_deploy": [
      "silver-quality-gates",
      "gsd-discuss-phase",
      "gsd-plan-phase",
      "gsd-execute-phase",
      "gsd-verify-work",
      "gsd-ship",
      "gsd-code-review",
      "gsd-secure-phase",
      "gsd-validate-phase",
      "requesting-code-review",
      "receiving-code-review",
      "finishing-a-development-branch",
      "silver-create-release",
      "verification-before-completion",
      "test-driven-development",
      "verify-tests"
    ]
  },
  "state": {
    "state_file": "${SB_RUNTIME_HOME_ROOT}/.silver-bullet/state",
    "trivial_file": "${SB_RUNTIME_HOME_ROOT}/.silver-bullet/trivial"
  },
  "release": {
    "profile": "generic",
    "require_plugin_runtime_matrix": true,
    "require_pre_release_quality_gate": true,
    "quality_gate_state_file": "${SB_RUNTIME_HOME_ROOT}/.silver-bullet/quality-gate-state"
  }
}

Important fields:

FieldMeaning
project.src_patternRegex for files that count as source and trigger enforcement
project.src_exclude_patternRegex for source-like files excluded from implementation gates
project.active_workflowfull-dev-cycle or devops-cycle
skills.required_planningPlanning floor before implementation work
skills.required_planning_devopsDevOps-specific planning floor
skills.required_deployFinal delivery floor for PR/deploy/release
skills.all_trackedCanonical list of skill markers hooks record
devops_pluginsOptional DevOps plugin availability detected by init
release.require_plugin_runtime_matrixMandatory live runtime release gate for plugin projects
release.require_pre_release_quality_gateMandatory 4-stage pre-release quality gate
semantic_compressionTF-IDF context compression settings for large files

Downstream projects normally use the generic release profile. This repository requires plugin-runtime live matrices and the 4-stage pre-release gate because Silver Bullet itself is a Claude/Codex plugin.

Documentation Governance

Silver Bullet treats documentation as a delivery artifact, not an afterthought.

/silver:init scaffolds a doc scheme from templates/doc-scheme.md.base. The hooks then check that required docs are present and current when delivery commands run. The release flow expects README, changelog, architecture/testing/release docs, and workflow docs to match the current product surface.

Useful docs:

Testing

Run the normal suite:

bash scripts/verify-tests.sh

That runs hook unit tests, script unit tests, integration scenarios, E2E harness sanity checks, and coverage matrix checks. Current release baseline:

2,025 passed, 0 failed

Run live runtime tests when validating plugin/runtime behavior:

bash tests/live/run-live-tests.sh
bash tests/e2e-live/run-e2e-live-tests.sh

Limit live tests to one runtime:

SB_LIVE_RUNTIMES=codex bash tests/live/run-live-tests.sh
SB_E2E_LIVE_RUNTIMES=codex bash tests/e2e-live/run-e2e-live-tests.sh

Codex-compatible live tests use Kay v0.9.6 and the opencode-go provider path when configured. SB tests should not be run against the upstream codex binary directly. The harness isolates config roots so live tests do not mutate the user's normal Codex hook cache.

CI/CD And Release Gates

For downstream deploy pipelines, use:

bash scripts/deploy-gate-snippet.sh

The snippet checks the workflow state file and blocks deploys if required delivery skills are missing.

Release behavior:

  • git commit is warning-only for red CI, so CI fixes can be committed.
  • git push, gh pr create, and gh release create are blocked when CI is red.
  • gh release create can require plugin live matrices and the pre-release quality-gate markers when the project release profile opts in.
  • The SB plugin repo requires the shared live matrix, todo-app live E2E marker, inline full-surface marker, 4-stage pre-release gate, and a fresh full-suite rerun before release.

Repository Layout

commands/                         Codex/Claude command surfaces
skills/                           Source SB skills
hooks/                            Runtime enforcement hooks
scripts/                          Installers, workflow helpers, verification tools
templates/                        Project config, instruction, workflow, and docs templates
docs/                             Product, architecture, enforcement, testing, release docs
site/                             Public website and Help Center
plugins/silver-bullet/            Codex package surface, mostly symlinks to source
tests/                            Unit, integration, live, and E2E harnesses
.claude-plugin/                   Claude plugin marketplace metadata
.planning/                        GSD project lifecycle artifacts for this repo

The Codex package mostly symlinks source-owned assets into plugins/silver-bullet/, stores internal generated skill files under skill-source/, and mirrors those files into native ~/.codex/skills during install so the picker exposes only the /Silver: namespace. Project-instance artifacts such as .planning/ and .claude/, and runtime state are not treated as plugin package content.

Troubleshooting

SymptomFix
jq not foundInstall jq with Homebrew or apt
/silver not available in Claude CodeInstall the plugin and restart/reload the Claude Code session
/Silver: entries not available in CodexRefresh the public Codex marketplace install, or run ./scripts/install-codex.sh --purge-legacy-skills from a repo checkout when developing SB itself
GSD skills missingRepair or reinstall GSD with npx get-shit-done-cc@latest
Superpowers helper missingRepair or reinstall obra/superpowers; SB uses it only at selected helper boundaries
Engineering helper missingRepair or reinstall anthropics/knowledge-work-plugins/tree/main/engineering
Design helper missingRepair or reinstall anthropics/knowledge-work-plugins/tree/main/design
Product Management helper missingRepair or reinstall anthropics/knowledge-work-plugins/tree/main/product-management
Hooks not firingConfirm .silver-bullet.json and silver-bullet.md both exist in the project root
Too many files trigger enforcementAdjust project.src_pattern and project.src_exclude_pattern
YAML/JSON edits are unexpectedly gatedIn devops-cycle, YAML/JSON/TOML are infrastructure code and intentionally gated
CI is red and you need to push a fixCommit normally; for push use the explicit CI override marker only when fixing CI: touch ${SB_RUNTIME_HOME_ROOT}/.silver-bullet/ci-red-override
Want to refresh templatesRe-run /silver:init; it detects existing config and preserves project-owned content
Want to start freshRemove .silver-bullet.json and silver-bullet.md, then rerun /silver:init

Current Release

  • Version: 0.37.22
  • Release: v0.37.22
  • Notable changes:
    • The Codex package no longer exposes a plugin-owned skills/ directory, preventing /Silver Bullet: duplicate picker entries.
    • The Codex installer maps internal skill-source/ files into the native ~/.codex/skills mirror so the picker-facing surface remains /Silver:.
    • Public-release refresh removes stale cached plugins/silver-bullet/skills trees and verifies the native SB mirror.

License

MIT - Alo Labs

Ver o original no GitHub

Bom para

Relacionados