AI Software Toolkit

AI is the accelerant. Assurance is mandatory.

Turn directives into reviewed changes with clear boundaries and evidence for what actually ran. AI Software Toolkit combines engineering standards, agent skills, and Proof, which binds check results to the evaluated revision. Your repository owns its commands, acceptance criteria, and release decisions.

All checks are optional to adopt. Core selects 12 advisory checks. Installing files, selecting a check, configuring it, executing it, and obtaining passing evidence are distinct steps. Installation does not enforce checks or change branch protection. Advanced lifecycle and polyglot execution stay manual.

See the evidence

The reference app shows separate checks, outcomes and next decisions for PR review and verification after merge. These recorded examples come from different changes; each keeps its own revision and evidence. Explore the live reference app report.

Start here

Use Git, Python 3.11+, and a POSIX shell. Preview the starter installation (Proof and seven skills) before applying it to your application repository:

git clone --branch v2.3.3 --depth 1 https://github.com/ravisingh11/ai-software-toolkit.git
cd ai-software-toolkit
python3 tooling/ai_toolkit discover --target /path/to/your-repo
python3 tooling/ai_toolkit init --target /path/to/your-repo --clients codex --preview
python3 tooling/ai_toolkit init --target /path/to/your-repo --clients codex --yes
python3 tooling/ai_toolkit doctor --target /path/to/your-repo

Replace the target path with your repository. Discovery, preview, and doctor are read-only; doctor does not run producers. Configure your real commands before executing checks. Code on main may be newer than the published release. For Claude Code, replace --clients codex with --clients claude-code. For Proof without starter skills, explicitly use --components proof on both init commands. See workspace and skill discovery before expecting an agent to find or use installed skills.

Onboarding covers local and CI setup. The installation guide covers component selection, runtime-only installs, updates, ownership, and rollback. The activation index covers all 33 checks, including prerequisites, execution, evidence, disabling, and optional enforcement.

In v2.3.0, fresh installations default to --install-set starter: Proof, seven starter skills, and 11 Core workflows covering all 12 advisory Core checks. Existing installations keep their prior behavior. See starter and full installation sets.

Use across the SDLC

The v2.4.0 candidate adds a read-only checkpoint planner and separately bound handoff receipts. See checkpoint commands and integrity limits. The published installation below remains v2.3.4 until this candidate is reviewed. Explicit pre-commit adapters inspect an isolated copy of the exact index with pinned Semgrep/Gitleaks tools; they preserve partial staging and invalidate applicability after index changes. Hooks remain separately adopted.

Place selected checks around the decision you are making. An early review, a PR check, and a result for merged main establish different things. Read down the first column for the process, and across each row for the invocation and relevant toolkit capabilities.

%%{init: {"block": {"padding": 32}}}%%
block-beta
  columns 3

  block:process
    columns 1
    PH["SDLCcheckpoint"]
    P1["Codingfinished"]
    P2["Beforecommit"]
    P3["Commitcreation"]
    P4["Post-commitfeedback"]
    P5["Beforepush"]
    P6["PR createdor updated"]
    P7["Beforemerge"]
    P8["Aftermerge"]
  end

  block:hooks
    columns 1
    HH["Hook orinvocation"]
    H1["Explicit humanor agent request"]
    H2["Optional localpre-commit hook"]
    H3["Repository-ownedcommit-msg hook"]
    H4["Explicit commandor adopted hook"]
    H5["Repository-ownedpre-push hook"]
    H6["Configured GitHubPR workflows"]
    H7["Platform checksand evaluation"]
    H8["Repository-adoptedmain-branch CI"]
  end

  block:toolkit
    columns 1
    TH["AI Software Toolkitcapabilities"]
    T1["Review skillsTest-gap analysis"]
    T2["Local static and secret checksExact staged scope: future"]
    T3["Message conventionsNo built-in producer"]
    T4["Commit-bound checksEvidence recording"]
    T5["Outgoing-range checksSecrets and change scope"]
    T6["Build, tests and PR metadataSecurity and review evidence"]
    T7["Policy evaluationInspect accepted evidence"]
    T8["Merged-revision checksRelease handoff"]
  end

  P1 --> P2
  P2 --> P3
  P3 --> P4
  P4 --> P5
  P5 --> P6
  P6 --> P7
  P7 --> P8

  P1 --> H1
  H1 --> T1
  P2 --> H2
  H2 --> T2
  P3 --> H3
  H3 --> T3
  P4 --> H4
  H4 --> T4
  P5 --> H5
  H5 --> T5
  P6 --> H6
  H6 --> T6
  P7 --> H7
  H7 --> T7
  P8 --> H8
  H8 --> T8

  classDef stage fill:#d1fae5,stroke:#047857,color:#064e3b
  classDef hook fill:#f3e8ff,stroke:#7e22ce,color:#581c87
  classDef capability fill:#dbeafe,stroke:#1d4ed8,color:#172554
  classDef limitation fill:#fef3c7,stroke:#b45309,color:#78350f,stroke-dasharray:5 4

  classDef stageHeader fill:#065f46,stroke:#065f46,color:#ffffff
  classDef hookHeader fill:#6b21a8,stroke:#6b21a8,color:#ffffff
  classDef capabilityHeader fill:#1e40af,stroke:#1e40af,color:#ffffff

  class PH stageHeader
  class HH hookHeader
  class TH capabilityHeader
  class P1,P2,P3,P4,P5,P6,P7,P8 stage
  class H1,H2,H3,H4,H5,H6,H7,H8 hook
  class T1,T4,T5,T6,T7,T8 capability
  class T2,T3 limitation

Downward arrows show process progression. Across each row, a hook or explicit request can invoke selected capabilities; this is not an automatically installed pipeline. Dashed boxes identify current limitations.

The optional local hook bundle provides static and secret checks with its configured scope. General Proof evaluation of an exact staged snapshot is a future capability; working-tree results do not prove partially staged contents passed. Commit-message conventions have no built-in producer. Pre-push hooks, main-branch CI, and integration-candidate validation require repository adoption. Local hooks are bypassable and do not replace hosted merge checks.

The SDLC checkpoint guide maps all 33 checks to these checkpoints or later release, deployment, and runtime handoffs. It covers scope, authority, invalidation rules, partial staging, PR edits, and squash/merge examples. Existing operations remain change and release; checkpoint names are guidance, not new CLI flags. All checks remain optional, Core advisory, and lifecycle/polyglot manual. The diagram installs no hooks, enables no triggers, and grants no action authority.

Act on the checkpoint report

Existing acceptance runs now finish with an SDLC checkpoint report in the job summary and a retained checkpoint-- artifact. It records why the workflow ran, its actual tested revision and comparison base when supplied, the observed step outcomes, links to logs, and the next action.

Checkpoint: PR review
Hook / invocation: pull_request:synchronize
Evidence scope: PR head
Tested revision: 

Archive build          Passed
Consumer verification  Failed      Inspect exact-consumer differences
Later step             Unverified  No result; inspect the preceding failure

Next: Resolve the finding; review current merge requirements separately.

This is an illustrative example, not a claimed run. Acceptance reports describe their own workflow steps, not all selected checks or an authoritative Proof score. Inspect the separate Proof Scorecard runs for evaluated policy evidence. The CLI’s check presentation separately groups supplied evaluator results as passed, failed, blocked, unverified/not run, stale evidence, and inactive, preserving original statuses and scores. Repair skills are recommended only when their project files are installed; a recommendation is not execution evidence.

See checkpoint report usage and limits. PR runs and main-push runs retain their original identities. Main results require a new run after merge; passing main CI does not establish live deployment health.

Observed hosted examples: successful PR-update report (tested source f07876015209) and retained failure report (tested source 34f0befb16c5). These are historical runs of this PR, not results for a later revision. Inspect a new main-push report separately after merge; earlier PR results do not establish main health.

Two invocation hooks, visible in the output

The diagram uses teal for decisions, purple for invocation, blue for capabilities, and dashed amber for limitations. Labels and line styles carry the meaning as well as color.

Here, “hook” means an invocation point. These are GitHub events, not installed local Git hooks. The contrast is before merge: PR update versus after merge: push to main, using the same Distribution Acceptance workflow.

flowchart LR
  PR["Hook 1: PR updatepull_request: synchronize"] --> CHECK["Distribution AcceptanceRun adopted checks"]
  MAIN["Hook 2: Push to mainpush: refs/heads/main"] --> CHECK
  CHECK --> OUTPUT["Output names invocationActual tested revision and separate result"]
  style PR fill:#f3e8ff,stroke:#7e22ce,color:#581c87
  style MAIN fill:#d1fae5,stroke:#047857,color:#064e3b
  style CHECK fill:#dbeafe,stroke:#1d4ed8,color:#172554
  style OUTPUT fill:#dbeafe,stroke:#1d4ed8,color:#172554

This repository adopts the push to main trigger in its maintainer-only Distribution Acceptance workflow. That workflow is not distributed as a consumer default; installed check selection and consumer workflow triggers are unchanged. All toolkit checks remain optional to adopt, Core advisory, and lifecycle/polyglot execution manual. These invocations do not deploy or publish anything.

For a committed change on your open PR’s branch:

git push
gh pr checks --required

After review, merge only when required CI and repository requirements pass. Then inspect the new main-branch run:

gh run list --workflow distribution-acceptance.yml --branch main --event push --limit 5

Open Record hook / invocation in the run log or job summary. It identifies why the job ran, separately from its outcome. Illustrative output (revision values are placeholders):

Hook / invocation: GitHub pull_request:synchronize
Checkpoint: PR review readiness
Git ref: refs/pull//merge
Evidence scope: PR head
Tested revision: 
PR head: 
PR base: 
Result: reported separately by the check; invocation is not a pass

Hook / invocation: GitHub push
Checkpoint: Post-merge/main validation
Git ref: refs/heads/main
Evidence scope: Main revision
Tested revision: 
PR head: not supplied
PR base: not supplied
Result: reported separately by the check; invocation is not a pass

A push event does not identify a PR by itself: establish the merge relationship from the merged PR record and resulting commit. Do not relabel the PR result as the resulting main commit. The event revision and actual tested revision are recorded separately, along with the run/attempt link. Invocation labels are display context, not signed provenance or accepted Proof evidence.

Explicit manual dispatch remains supported, labeled GitHub workflow_dispatch and Explicit manual verification; it is a separate invocation, not one of the two checkpoints above. No local tests are needed to inspect hosted runs. See the workflow and hosted runs.

How to invoke it

Ask an agent to use a skill

After installing skills for your selected client, name the relevant skill and the decision you want help with. For example, in Codex:

Use $code-review to review my working changes. Read AGENTS.md first. Report correctness risks and test gaps. Do not run tests, commit, or push.

Before merging:

Use $prepare-safe-change to assess before-merge using the existing change policy and hosted evidence. Identify the tested revision, comparison base, missing results, and unresolved findings. Do not run local tests or merge.

The checkpoint describes the task. It does not introduce a new runtime operation or authorize the next action. See skill onboarding for client discovery and evidence of actual skill use.

Inspect readiness without running producers

From your application checkout, use your toolkit source path:

python3 /path/to/ai-software-toolkit/tooling/ai_toolkit doctor --target .

Doctor is read-only. It reports selection, configuration gaps, available evidence, and next steps; it does not execute producers or enable checks.

Execute selected local checks when authorized

For a clean, committed feature branch with the installed runtime, available prerequisites, and a meaningful origin/main comparison, an example is:

export PROOF_UNIT_TEST_COMMAND="npm test"
python3 /path/to/ai-software-toolkit/tooling/ai_toolkit check \
  --target . \
  --operation change \
  --revision "$(git rev-parse HEAD)" \
  --base-ref origin/main

Replace the example test command with your repository’s real command and prepare its dependencies first. check can execute multiple selected supported producers and write evidence artifacts. The local scanner uses producer configuration such as environment variables; the command-runner JSON below is not automatically its fallback. Missing providers remain visibly unverified. An advisory ALLOW can coexist with unresolved evidence.

If your task excludes local tests, skip this execution step and use hosted CI. To inspect the current branch’s PR required checks from its checkout:

gh pr checks --required

This reads GitHub results. It does not run checks, evaluate every Proof control, or authorize a merge. Confirm the current head, applicable required checks, and review requirements before integrating.

Example: connect unit tests to a checkpoint

Adopt the Unit Tests workflow and configure the repository-owned test command. When the PR is opened, reopened, or receives new commits, the workflow runs against the PR head revision:

block-beta
  columns 1
  A["HookPR opened, reopened, or new commits pushed"]
  B["AI Software ToolkitUnit Tests workflow and command runner"]
  C["Repository-owned test commandExample: npm test"]
  D["GitHub check resultBound to the exact tested commit"]
  E["Trusted evidence collection and ProofEvaluate selected policy and publish the scorecard"]
  A --> B
  B --> C
  C --> D
  D --> E
  classDef toolkit fill:#dbeafe,stroke:#1d4ed8,color:#172554
  class B,E toolkit

For a Node application, one optional configuration is .proof/commands.json:

{
  "version": 1,
  "setup": "npm ci",
  "working_directory": ".",
  "commands": {
    "unit-tests": "npm test"
  }
}

Merge these values into an existing configuration, preserving other adopted commands. Choose setup and test commands appropriate to your application; the installer does not create or overwrite this consumer-owned file. Nonempty corresponding PROOF_* variables take precedence. See repository command configuration for provider setup.

The installed Unit Tests workflow invokes the existing runner in two phases:

python3 .proof/run_repository_command.py --command unit-tests --phase setup
python3 .proof/run_repository_command.py --command unit-tests --phase producer

The runner preserves the command’s failure status. A missing command fails the job rather than becoming passing evidence. GitHub records the tested revision; the configured trusted collector must accept the correct workflow, provider, and revision before Proof evaluates that evidence. Running the command runner alone does not create authoritative CI evidence. Editing only the PR body does not rerun this unit-test workflow; metadata has its own invalidation rules.

For optional early feedback, your repository could adopt a custom pre-push hook that calls the same runner after dependencies are available:

#!/bin/sh
exec python3 .proof/run_repository_command.py \
  --command unit-tests --phase producer

This is a repository-owned example, not an automatically installed toolkit hook. Compose it with existing hooks instead of overwriting them. Its exit status can stop that local push, but it is bypassable, does not satisfy remote required CI, and does not prove every outgoing commit was tested. Leave it unconfigured when local tests are excluded. See the checkpoint guide for evidence scope and boundaries.

What you can use

For Claude Code, use --components skills --clients claude-code --skills starter; for Codex, use --clients codex. The same canonical skills populate the selected client’s project directory. Installing a skill does not execute it. See client setup and replacement safety.

Choose what fits your project

Keep the 33-check activation index available as you adopt more checks. Provider selection does not prove configuration or execution. Independent provenance and Trivy can be adopted separately from advanced lifecycle verification.

Read the scorecard

Illustrative evidence for one revision:

Failed, blocked, unverified, and inactive checks remain separate. Missing credentials, stale evidence, or skipped/manual producers never become a pass. Only selected, applicable checks affect scores. Advisory / Enforced is a separate choice; ALLOW means policy permits that snapshot, not release readiness. GitHub required merge checks are configured separately.

Inspect the live toolkit scorecard, full illustrative report, and reading evidence guide for revision binding, freshness, result states, and provider limitations. Historical verification records remain in the provider ledger. The v2.3.0 compatibility review explains hosted verification against the published CLI and its limits.

See it in an application

Fieldnotes is a TypeScript issue tracker with a running application, live scorecard, and setup and evidence guide. Its five polyglot quality examples run manually and do not establish full-application coverage. An isolated Python demo is included here.

Choose language tools and thresholds through the optional quality recipes.

Repository map

Documentation explains source ownership and intentional installed copies. See contributing, validation, vision, and licensing. MIT licensed; third-party tools retain their own terms.