Software Standards Bootstrap

Software Standards Bootstrap (ssb) generates four agent-friendly artifacts for a Git repository:

1. Semantic rules for evidence-backed implementation conditions.
2. Verification recipes for deliberately invoked existing commands.
3. Agent Skills for multi-step engineering workflows.
4. Automation proposals for valuable checks that do not yet exist.

An AGENTS.md file is derived from the codebase context and orients coding agents to reason about and routes them to coding rules, code verification processes, and agent skills.

Run ssb in a repository whose engineering conventions are not yet documented for AI tools. A coding agent analyzes the repository and proposes these files. Developers review, edit, delete, or approve them before official adoption via an ADR (architectural decision record), which ssb will create for you.

The coding agent performs semantic analysis. The offline ssb CLI pins the input commit, builds, validates schemas, and exact evidence, renders AGENTS.md, and creates an optional Proposed ADR.

Install

On macOS or Linux, install the latest published CLI release:

curl -fsSL https://raw.githubusercontent.com/nnennandukwe/software-standards-bootstrap/main/install.sh | sh
"$HOME/.local/bin/ssb" --help

The installer detects the operating system and architecture, downloads the matching release archive, verifies its SHA-256 checksum, and installs the binary. It installs the binary into ~/.local/bin by default and prints the exact PATH command when that directory is not already available.

To install the CLI and expose the bootstrap skill in the current repository, run the command for your coding agent from that repository's root:

# Codex
curl -fsSL https://raw.githubusercontent.com/nnennandukwe/software-standards-bootstrap/main/install.sh | sh -s -- --skill-dir .agents/skills

# Claude Code
curl -fsSL https://raw.githubusercontent.com/nnennandukwe/software-standards-bootstrap/main/install.sh | sh -s -- --skill-dir .claude/skills

With --skill-dir, the installer checks out the same release tag as the CLI and copies its software-standards-bootstrap skill into the requested host directory. It stops without replacing an existing skill.

Pin both the CLI and Codex skill to v0.2.0:

curl -fsSL https://raw.githubusercontent.com/nnennandukwe/software-standards-bootstrap/main/install.sh | sh -s -- --version v0.2.0 --skill-dir .agents/skills

Use --install-dir /path/to/bin to choose another binary directory.

On Windows, use the PowerShell installer. Download it, read it, then run it:

irm https://raw.githubusercontent.com/nnennandukwe/software-standards-bootstrap/main/install.ps1 -OutFile install.ps1
# Review install.ps1, then:
powershell -ExecutionPolicy Bypass -File .\install.ps1
& "$env:USERPROFILE\.local\bin\ssb.exe" --help
Remove-Item .\install.ps1

The -ExecutionPolicy Bypass argument applies to that one invocation only, and is needed because the default policy on Windows client editions blocks downloaded scripts.

install.ps1 takes the same options as install.sh, spelled as PowerShell parameters, and -Help prints them:

# Codex
powershell -ExecutionPolicy Bypass -File .\install.ps1 -SkillDir .agents\skills

# Claude Code
powershell -ExecutionPolicy Bypass -File .\install.ps1 -SkillDir .claude\skills

# Pin both the CLI and skill to a release
powershell -ExecutionPolicy Bypass -File .\install.ps1 -Version v0.2.0 -SkillDir .agents\skills

The matching .zip is also available from the published releases for a manual install.

With Go 1.26.5 installed, the CLI alone can also be installed from source:

go install github.com/nnennandukwe/software-standards-bootstrap/cmd/ssb@v0.2.0

What it generates

Semantic rules

Each proposed rule is stored at:

.software-standards/rules/<rule-id>.md

Rules tell future AI tools what to always, never, or prefer, and when to ask a developer before proceeding. Each file opens on its H1 title and actionable body. The manifest carries category, activation lenses, path scopes, derivation, and exact evidence; commands and check metadata never live in a semantic rule.

For example:

Always use the service interface when code under internal/api/ accesses persistence. Do not call the database package directly.

The generated rule would cite the repository files and line ranges that establish that boundary.

ssb does not turn generic best practices into repository rules. Extracted rules need repository authority or enforcement. Inferred rules need three supporting occurrences across at least two files. Rejected candidates are discarded.

Before proposing artifacts, the agent reviews dependency boundaries, parallel implementations, platform seams, compatibility surfaces, source/test/documentation symmetry, and existing automatic enforcement.

Repository orientation

Optional reviewed context that does not belong in an actionable artifact is stored at:

.software-standards/orientation.yaml

ssb.dev/orientation/v1 can describe the repository, important areas, prerequisites, canonical documents, related recipes or skills, and concise planning, implementation, verification, or handoff guidance. Every rendered statement has exact declares or enforces evidence at the pinned baseline. Orientation is context, not active policy: it is not counted as an artifact and is not eligible for the adoption ADR.

Verification recipes

Existing commands that deliver value when deliberately invoked are recorded at:

.software-standards/verification/<recipe-id>.yaml

A newly generated ssb.dev/verification/v2 recipe states when it applies, its ordered commands, each command's required working_directory, exact enforces evidence, and the expected successful result. . means repository root; another value must be a canonical tracked directory outside submodules. ssb records but never executes recipe commands. Existing strict ssb.dev/verification/v1 recipes remain readable and normalize to root .; v1 never accepts the v2-only working_directory field.

Agent Skills

Multi-step procedures are generated as reusable Agent Skills:

.agents/skills/<skill-name>/SKILL.md

A skill can tell an AI coding tool how to plan a cross-boundary change, update generated code, modify a schema and its dependents, or recover a multi-step engineering workflow.

Rules define semantic conditions. Recipes record existing commands. Skills define procedures.

Automation proposals

Valuable automatic checks that do not exist are described at:

.software-standards/automation/<proposal-id>.yaml

These are reviewable designs, not implemented checks or active standards.

Keeping an automation proposal preserves it for separate design review. It is not included in AGENTS.md or the adoption ADR. Adopting or merging the standards pack does not authorize its implementation or activation. Implementing or activating the proposed check requires a separate reviewed change.

Optimized AGENTS.md

For manifest-layout packs, ssb renders a finite bootloader into one managed section in root AGENTS.md and writes a portable routing tree:

.software-standards/routing/catalog.md
.software-standards/routing/bundles/<selector-digest>.md

The root keeps the lifecycle boundary, essential orientation, routing protocol, tree digest, and only manifest-selected root_core rules. The catalog describes exact normalized scope-and-lens selectors. Each artifact is assigned to exactly one bundle; selected bundles inline non-root rule bodies and inert recipe steps and link complete Agent Skills and canonical sources. Automation proposals remain absent because they are not active behavior.

root_core is optional, defaults to empty, and accepts at most 16 retained semantic-rule IDs. Every selected rule must use exactly the sole base lens and sole **/* scope. Contextual or path-specific guidance belongs in routing bundles, never the root. Published embedded-layout packs retain their existing single-file projection byte-for-byte.

An unmerged generated change is a proposal. Review and merge are the adoption decision; file presence alone does not prove adoption. Rendering does not stage, commit, push, open a pull request, execute a command, or activate another system, and a recorded expected result is not execution evidence.

The manifest, inventory, report, and canonical artifact files are editable sources. AGENTS.md and .software-standards/routing/ are derived.

Report and ADR

New packs use the human-first manifest layout:

.software-standards/manifest.yaml
.software-standards/inventory.json
.software-standards/orientation.yaml # optional
.software-standards/report.md

The ssb.dev/manifest/v1 manifest records the baseline, accepted index, selection and provenance metadata, confidence, utility, relationships, and exact raw-byte digests. Its optional orientation reference binds the exact ssb.dev/orientation/v1 bytes without adding an artifact. inventory.json preserves the complete unedited inspection response. report.md opens on # Software standards report and contains only run-wide limitations and accepted-output narrative, with links to both machine files. A zero-artifact manifest is valid.

Published v0.1.1 packs remain fully supported through the embedded layout: their ssb.dev/report/v1 frontmatter continues to validate, render, create ADRs, and participate in governed prune without conversion. Validation never rewrites or migrates either layout.

After developer review, ssb can create an optional ADR:

docs/adr/NNNN-actionable-standards.md

The ADR remains Proposed until the developer-created pull request is merged.

How future AI work uses the output

Once reviewed and merged, compatible AI coding tools can use the generated files throughout the software development lifecycle.

AI-assisted activity	Repository context supplied
Planning	Architectural boundaries, affected components, required workflows, approval points, and constraints
Code generation	Coding conventions, preferred patterns, prohibited patterns, file scopes, and implementation guidance
Testing	Repository-specific verification recipes and expected successful results
Code review	The repository's correctness, maintainability, security, compatibility, and review requirements
Maintenance	Established patterns for changing code without breaking repository structure or conventions

Human review and deterministic guardrails

Generation creates an uncommitted proposal. Developers decide which artifacts become part of the repository through normal Git review.

Semantic rules, command recipes, procedures, and proposed automation stay separate. ssb does not execute a recipe, implement a proposed checker, or claim that any external check passed.

Who it is for

ssb is for teams making an existing repository's SDLC more AI-integrated while preserving engineering judgment, repository conventions, and review responsibility. It fits repositories that:

• use or plan to use AI tools for software development;
• contain coding or SDLC conventions that AI tools need to follow;
• need documented rules, reusable Agent Skills, or a clearer root AGENTS.md;
• want generated guidance backed by inspectable repository evidence; and
• require developer approval before that guidance is adopted.

It does not provide a generic rules catalog, invent standards without repository evidence, or replace developer review.

Quick start

Requirements

• Git 2.39 or newer
• curl when using install.sh on macOS or Linux
• A repository with at least one commit on an attached branch
• No tracked or staged working-tree changes
• A compatible coding agent that can use the bundled Agent Skill

Go 1.26.5 is required only when building ssb from source.

Untracked files are allowed during inspection.

1. Install the CLI and expose the bootstrap skill

From the target repository's root, run the Codex or Claude Code command under Install. Run "$HOME/.local/bin/ssb" --help to verify the default CLI installation before continuing. If the installer prints a PATH command, run it in the current shell before using ssb directly.

2. Generate the proposal

From the clean target repository, ask the coding agent:

Use the software-standards-bootstrap skill to analyze this repository
and generate evidence-backed actionable artifacts and AGENTS.md guidance.

The agent runs the inventory, analyzes repository evidence, writes the proposal, validates it, renders AGENTS.md, and reports every changed or untracked path.

3. Review and rerender

Review the manifest, inventory, human report, every canonical artifact, the generated AGENTS.md section, and the generated routing tree. Do not edit derived projection files directly. When a digest-bound source changes, update its matching manifest digest, then rerun validation and rendering.

ssb validate --repo .
ssb render --repo . --dry-run
ssb render --repo .

Review the complete uncommitted diff before creating a pull request.

4. Create an optional ADR

Only after reviewing the retained proposal:

ssb adr --repo . --dry-run
ssb adr --repo .

The developer-created pull request and its merge are the adoption decision.

CLI commands

ssb inspect  [--repo PATH] [--format text|json] [resource limits]
ssb validate [--repo PATH] [--format text|json]
ssb render   [--repo PATH] [--review ID] [--dry-run]
ssb adr      [--repo PATH] [--review ID] [--adr-dir PATH] [--dry-run]
ssb prune    <inspect|validate|approve|apply|recover|status|verify> [options]

• inspect creates a safe inventory of one committed repository snapshot.
• validate checks the detected pack layout, all four artifact schemas, optional orientation, inventory, evidence, digests, confidence, utility, scopes, verification-v1/v2 compatibility, and relationships.
• render transactionally projects the managed root section and, for manifest packs, the generated routing catalog and bundles. With no active rule, recipe, or skill, it removes the stale managed section and generated routing tree while preserving human-authored root content.
• Existing generated files and review rollback snapshots are read under hard limits of 8 MiB per file, 64 MiB per routing tree, 10,000 files per tree, and 20,000 total tree entries. SSB applies the same limits to generated routing output before writing it, so a successful render remains inspectable and can be safely rerendered or removed. If only post-commit backup cleanup fails, the command succeeds and warns with the repository-relative backup path for manual cleanup.
• adr creates one new Proposed ADR from retained rules, recipes, and skills.

inspect supports --max-candidate-files and --max-candidate-bytes. --allow-partial permits diagnostic output from an incomplete inventory, but that output cannot be used to generate a proposal. Exit code 4: inventory coverage incomplete.

ssb validate --format json uses response schema 3. Valid output identifies pack.layout as manifest or embedded; manifest-layout packs also expose separate manifest, inventory, report, and optional orientation paths plus the normalized orientation content and routing bundles. Additive projection measurements report exact generated bytes, and warnings report non-blocking root-over-16-KiB or catalog-over-64-KiB diagnostics with actual and threshold values. Verification steps always expose normalized working_directory, including . for verification/v1. Invalid output omits pack.

• 0: success
• 1: actionable-pack or prune-proposal validation failure
• 2: usage or repository precondition failure
• 3: unexpected internal failure
• 4: inventory coverage incomplete

Run ssb <command> --help for complete command options.

Governed lifecycle review

prune is the current name for a governed lifecycle review of an adopted pack. It does not mean automatic cleanup. The workflow compares every rule and repository Agent Skill with a developer-selected, point-in-time host/model capability profile and proposes keep, update, consolidate, remove, or unable-to-determine. Every disposition requires evidence and rationale. Actionable dispositions bind repository and capability evidence; an unable-to-determine disposition records a structured evidence gap against an exact artifact. Unknown provenance remains unable to determine. Skill provenance covers the complete tracked bundle; a partially declared skill remains unknown, and ignored untracked governed files block inspection.

Each review is stored under .software-standards/reviews/<review-id>/ with its immutable context, proposal, candidate inputs, evidence snapshots, and digest-chained events.

Prune inspection fails closed on incomplete inventory and writes only an immutable review context. The Agent Skill writes the semantic proposal. The CLI validates it, records one digest-bound human approval, shows application as a dry run by default, and applies only after --write. Application, rerendering, optional ADR creation, and receipt-backed verification are separate events. One canonical application-plan digest binds dry run, mutation, recovery, and verification. If no changes are approved, status reports a terminal no-change outcome without inventing application or verification. See the prune protocol.

Safety

The ssb CLI:

• does not call an AI model;
• does not make network requests or send telemetry;
• does not execute repository code, tests, hooks, or recipe commands;
• does not stage, commit, branch, push, or open pull requests;
• reads inspection input from the committed Git tree rather than worktree files;
• stops proposal generation when inventory coverage is incomplete;
• leaves generated files local and uncommitted for developer review;
• pins prune capability evidence and preserves unknown provenance as unknown;
• keeps prune application dry-run by default and journals approved writes for recovery;
• binds artifact removals and their pack index updates into one recoverable plan;
• rejects portable-path escapes and case-fold collisions before mutation; and
• binds verification to the exact application, governed poststate, rerender, and external check receipts.

Detailed documentation

• Rule format
• Category taxonomy
• Architecture and trust boundaries
• Agent workflow tests
• Governed prune protocol
• Verification record
• Contributing

Non-goals

ssb does not provide a generic rules catalog, automatic synchronization with an online model registry, vendor-release-note trust, tool-specific rule projections, checker generation, hosted services, direct model APIs, telemetry, hooks, automatic refresh, unreviewed rewriting or deletion, or downstream product activation. The prune name and command architecture remain revisable.

Development

go test ./...
go test -race ./...
go vet ./...
go build ./cmd/ssb
go tool govulncheck ./...

Licensed under Apache-2.0.