This is the new-user path for adding tools to AI SAFE2 Developer Workflow.
Install the required core first, then add only the capabilities that match the
repository’s goals and trust boundaries.
A tool named in adapters/manifests.json is discoverable, not automatically
installed: a manifest is not execution. Setup is complete only when the tool
produces verified evidence for the exact pull-request revision.
The setup decision
flowchart TD
A[Install required AI SAFE2 core] --> B{What outcome needs help?}
B -->|Better planning and debugging| C[Superpowers]
B -->|Repeatable security checks| D[CodeQL + Semgrep + Gitleaks]
B -->|Routine contextual PR review| E[PR-Agent + OpenRouter]
B -->|Specialized security review| F[Codex Security or Claude security review]
B -->|Independent integration or release review| G[Greptile]
B -->|Runtime or delegated authority| H[NEXUS + MCP/runtime adapter]
C --> I[Pin, test, and record evidence]
D --> I
E --> I
F --> I
G --> I
H --> I
I --> J[Ready for named human decision]
Step 1 — Install the required core
Every adoption starts here. Optional tools supplement this layer; they do not
replace it.
-
Install and verify the pinned CLI in an isolated environment:
python -m pip install "ai-safe2[all]==1.0.1"
safe2 --version
safe2 self-check --strict
- Copy
repository-template/ into the adopting repository.
- Replace every
REPLACE-* value in .ai-safe2/ and the PR template.
- Adapt the profile’s critical and enhanced paths to the real repository.
-
Validate the installation:
python scripts/validate_workflow.py --root .
- Open a setup PR and confirm that documentation-only, normal code, and one
critical-path fixture choose the expected routes.
- Confirm the CLI decision result and human decision record name the exact
candidate revision. They must remain at
hold while required evidence is
absent.
Step 2 — Generate a goal-based setup plan
The repository template includes a setup assistant. It asks about outcomes,
not vendors, and writes a reviewable plan without changing external systems.
python scripts/setup_assistant.py \
--interactive \
--output AI-SAFE2-SETUP-PLAN.md
For repeatable automation, select goals explicitly:
python scripts/setup_assistant.py \
--goals planning,deterministic-security,semantic-review \
--output AI-SAFE2-SETUP-PLAN.md
Supported goals are planning, deterministic-security, semantic-review,
security-review, strategic-review, and runtime.
The assistant does not create accounts, install third-party software, add
credentials, enable repository apps, or change branch protection. A human
reviews the generated plan and authorizes each external action separately.
Step 3 — Add selected modules
Better planning — Superpowers
Use when the team wants stronger problem framing, plans, test-first work,
debugging, or completion verification.
- Review Superpowers, its installation
method, and the skills that will enter the agent environment.
- Record the reviewed commit in
upstreams.lock.json.
- Install only the needed skills using the upstream instructions for the
chosen agent environment.
- Run one bounded task through planning, implementation, tests, and
verification.
- Keep method output separate from evidence: a plan is not a test result and
cannot authorize merge or release.
- Update through an isolated PR; never execute from a floating upstream
branch.
Repeatable security — CodeQL, Semgrep CE, and Gitleaks
Start here before relying on probabilistic security review.
CodeQL
- In GitHub, open Settings → Security and analysis → Code scanning.
- Choose default setup, or add a SHA-pinned advanced workflow when the
repository needs custom languages, queries, schedules, or build steps.
- Open a representative PR and confirm CodeQL analyzes the expected languages.
- Triage the existing baseline before making findings blocking.
- Require the named CodeQL check only after a clean and failing fixture prove
the rule works.
See GitHub CodeQL setup.
- Choose repository-owned rules or a reviewed ruleset; do not use an
unreviewed moving rules source as a merge gate.
- Pin the Semgrep version or container digest.
-
Run locally first, for example:
semgrep scan --config .semgrep/security.yml --error --metrics=off
- Add the same command to PR CI with read-only repository permissions.
- Verify a deliberately vulnerable fixture fails and a clean fixture passes.
- Normalize completion, findings, revision, version, and limitations into an
evidence envelope.
See Semgrep CI examples.
Gitleaks
- Choose a pinned binary or SHA-pinned action. Check licensing before using
the hosted action for an organization repository.
- Scan the PR-visible history and enable redaction.
- Keep approved test tokens in a narrow baseline; never baseline a real secret.
- Verify a fake-secret fixture fails without printing the secret.
- Rotate any real exposed credential; deleting it from the latest commit is
not sufficient remediation.
See the Gitleaks project and
Gitleaks Action.
Routine PR review — PR-Agent with OpenRouter
Use for non-trivial code changes when a low-cost contextual reviewer is useful.
It remains advisory.
Owner tasks
- Create an OpenRouter account and an API key with an expiry and spending
limit suitable for the repository. The plaintext key is sensitive and may
be shown only once.
- In GitHub, open Repository Settings → Secrets and variables → Actions.
Do not use Agents secrets for GitHub Actions.
- Add
OPENROUTER_API_KEY as a repository or approved organization secret.
- Decide whether a metered OpenAI fallback is acceptable. If yes, add
OPENAI_KEY; if no, leave it absent and preserve fallback unavailability.
- Review repository and data-retention boundaries before sending source to
any hosted model.
See OpenRouter key information
and its live model catalog API.
Maintainer tasks
- Adapt these tested reference files from the AI SAFE2 repository:
.github/workflows/pr-agent.yml
.ai-safe2/pr-agent-preflight-policy.json
scripts/pr_agent_preflight.py
scripts/classify_pr_change.py
- Install PR-Agent’s supported Python CLI from a reviewed commit SHA. The
reference workflow intentionally avoids the Docker-based action so Docker
Hub throttling cannot prevent the reviewer from starting.
- Map the route classifier to the adopting repository. Documentation and
simple asset changes should not consume a semantic review by default.
- Keep live model discovery and the bounded canary. Free-model names and
availability change; do not document a model as permanently available.
- Preserve preflight qualification separately from execution. A degraded
model may be used for advisory evidence but must remain labeled degraded.
- Verify substantive publication instead of trusting the action exit code.
- Retain the preflight and execution receipts for the exact head revision.
Acceptance test
- Open a non-draft PR containing a small, known code defect and a test gap.
- Confirm the workflow records eligible, tested, selected, and final models.
- Confirm PR-Agent publishes a substantive review for the current head.
- Push a correction and confirm the review updates to the new head.
- Temporarily test missing-provider behavior in a safe branch: the receipt
must report
unavailable or failed, never approval.
- Confirm
OPENAI_KEY is not invoked when OpenRouter produced the review.
Current package boundary: v0.1.0 provides the adapter contract and this tested
reference path; it does not silently copy credentials or enable the workflow
in an adopting repository.
Specialized AI security — Codex Security or Claude security review
Use only for routes whose trust boundary warrants specialized review.
- Define or review
SECURITY.md, in-scope assets, trust boundaries, and
prohibited claims before enabling the reviewer.
- Choose the provider after reviewing source-access, retention, permissions,
and execution boundaries.
- Bind it to critical or explicitly selected enhanced routes.
- Use a representative security-sensitive diff to confirm the reviewer sees
the correct base, head, and policy.
- Validate candidate findings against code and policy before fixing them.
- Record no-finding, finding, failed, unavailable, and not-requested outcomes
distinctly.
- Keep human security and release authority explicit.
Upstream options are inventoried in upstreams.lock.json. Their current
Developer Workflow status is manifest_only; installation and evidence
bridges remain repository-specific.
Strategic third-party review — Greptile
Use Greptile at major integration or release boundaries when another
repository-context perspective is worth the time or review credit.
Owner tasks
- Review and install the Greptile GitHub App
only for approved repositories.
- In Greptile, confirm the repository is indexed and review the requested
source, metadata, and PR permissions.
- Choose a cost-aware policy:
- automatic review on PR open only for repositories where that spend is acceptable;
- label-filtered review for selected integration or release PRs; or
- manual review after the candidate head is frozen.
- Keep draft reviews off unless early review is deliberate.
- Do not use On new pushes or On all events when each rerun consumes a
constrained review allowance.
See Greptile’s product overview.
Reviewer tasks
- Finish first-party checks and freeze the candidate head.
- Request one Greptile review using the configured dashboard, PR integration,
or CLI path.
- Confirm the last-reviewed commit equals the current PR head.
- Triage every finding as actionable, informational, already addressed, or
accepted residual risk.
- Fix valid findings and rerun affected deterministic checks.
- Retrigger only when the changed head requires new evidence.
- Record Greptile as
produced, failed, unavailable, or not_requested.
A green advisory-status wrapper is not proof that a substantive review ran.
Do not trigger Greptile for routine text, link, image, or low-impact
documentation changes unless the route or owner explicitly selects it.
Runtime and consequential actions — NEXUS and MCP adapters
- Identify the model, harness, tools, identities, delegated authority,
enforcement plane, and consequential actions.
- Select only adapters that match the deployed system.
- Verify policy enforcement and evidence production in the actual environment.
- Exercise authorization, delegation, prompt-injection, stale-evidence,
interruption, rollback, and dependency-failure cases.
- Bind receipts to software, configuration, policy, environment, and owner.
- Keep source-review evidence separate from deployment/runtime evidence.
See MCP Pro and
Agency Check. NEXUS and other runtime adapters
remain separate surfaces with their own readiness evidence.
Step 4 — Control upstream updates
- Add every selected repository, action, package, and hosted service to
upstreams.lock.json.
- Replace
resolve-during-adoption with the exact reviewed version or commit.
- Use one update authority—Dependabot or Renovate—to open isolated update PRs.
- Never depend on an upstream
main branch at runtime.
- Test the previous and proposed versions using the same fixtures.
- Preserve the last known-good pin and rollback path.
- Never let an adapter approve its own upgrade.
See Upstream Update Policy.
Step 5 — Know when setup is complete
| Check |
Required result |
| Core configuration |
Validator passes and no REPLACE-* placeholders remain |
| Route fixtures |
Documentation, code, and critical paths route as intended |
| CLI |
Pinned version and strict self-check pass |
| Decision records |
Exact revision, policy, missing evidence, and human owner are visible |
| Selected deterministic tools |
Clean and deliberately failing fixtures behave correctly |
| Selected AI reviewers |
Substantive output is tied to the current head |
| Provider failure |
Appears as failed or unavailable, never produced |
| Secrets |
Stored only in the approved secret store and absent from logs/artifacts |
| Upstreams |
Exact pins and isolated update policy are recorded |
| Authority |
A named human still owns merge, release, deployment, and risk decisions |
Setup is not complete merely because an app is installed or a workflow is
green. It is complete when the selected capability produces truthful,
revision-bound evidence and fails visibly when it cannot.