Then, once the plugin is loaded (run /reload-plugins if Claude Code does not pick it up), run one command:
/ai-sdlc setup
It runs init, registers the MCP advisor for the detected clients and runs doctor, then prints a report listing each step as done, skipped (already present) or not possible, with the reason and the exact next action. Re-running it is safe and says "Nothing changed" when the repo is already set up. No signing key is needed (RFC-0061). The global @ai-sdlc/orchestrator install is not required. The longer paths below remain for scripted or manual installs.
Open Claude Code in the repository you want to adopt AI-SDLC in and paste the brief below. The agent runs each step, verifies it, and recovers from the known failures (partial plugin cache install, missing @ai-sdlc/reference, uninitialised keyring, doctor warnings). The same brief is kept as a standalone file at install-agent-brief.md. The step-by-step commands follow in Raw install commands.
You are installing AI-SDLC into the git repository in your current directory. Run the steps in order. After each step run its verification; if it fails, apply the recovery listed for it, re-run the verification, and only then continue. Stop and report to me only if a recovery does not work twice.Prerequisites to check first: `node --version` (20 or newer), `pnpm --version` (9 or newer), `git --version`, `gh auth status` (logged in), `openssl version` (3.x), `claude --version`. Install or ask me about anything missing. If `~/.ai-sdlc/` already exists, tell me before touching it.1. Install the CLI. Run `npm install -g @ai-sdlc/orchestrator`. Verify with `ai-sdlc --version`, which must print a version.2. Install the SDK in this repository. Run `pnpm add @ai-sdlc/reference`. Verify with `pnpm ls @ai-sdlc/reference`, which must list the package.3. Install the Claude Code plugin. Run `/plugin marketplace add ai-sdlc-framework/ai-sdlc` then `/plugin install ai-sdlc@ai-sdlc`. Verify that `/plugin` lists `ai-sdlc` as enabled and that `/ai-sdlc` commands are available (restart the session if they are not).4. Scaffold the repository. Run `ai-sdlc init --yes`. Verify with `ai-sdlc health`, which must report all checks passing, and confirm `.ai-sdlc/pipeline.yaml` exists.5. Initialise the signing key. Run `/ai-sdlc init-signing-key`, paste the printed public key block into `.ai-sdlc/trusted-reviewers.yaml` under `reviewers:` (fields `identity`, `machine`, `addedAt`, `addedBy`, `pubkey`). Verify that `~/.ai-sdlc/signing-key.pem` exists and the public key is in `trusted-reviewers.yaml`. Never commit the private key.6. Run the doctor. Run `/ai-sdlc doctor`. It must finish with no errors and no unresolved warnings.Recovery for known failures:- Partial plugin cache install (plugin listed but commands missing, or files missing under the plugin cache): run `/plugin uninstall ai-sdlc@ai-sdlc`, delete the cached `ai-sdlc` directory under `~/.claude/plugins/` (show me the path before deleting), restart Claude Code, then repeat step 3.- Missing `@ai-sdlc/reference` (import or "cannot find module" errors, or doctor reports it absent): run `pnpm add @ai-sdlc/reference` in the repository root, confirm it appears in `package.json`, then re-run the failing step.- Keyring never initialised (doctor or signing reports no signing key, or `~/.ai-sdlc/signing-key.pem` is missing): run step 5. In a scripted environment generate it manually: `openssl genpkey -algorithm ed25519 -out ~/.ai-sdlc/signing-key.pem`, `chmod 600 ~/.ai-sdlc/signing-key.pem`, `openssl pkey -in ~/.ai-sdlc/signing-key.pem -pubout -out ~/.ai-sdlc/signing-key.pub.pem`, and register the public key in `.ai-sdlc/trusted-reviewers.yaml`.- Doctor warnings: read each warning, fix the cause it names (usually one of the three failures above, a missing `gh` login, or an uncommitted scaffold), and re-run `/ai-sdlc doctor` until it is clean. Do not suppress or ignore a warning without telling me why.When doctor passes, commit the scaffold (`git add .ai-sdlc .github CLAUDE.md package.json pnpm-lock.yaml`, never the private key) and report what you installed and the doctor output.
The guide below is the same install as a manual command sequence.
This guide walks you through adopting AI-SDLC in a repository you control — from
a clean environment with no prior operator state to a working pipeline that
produces signed, attested pull requests. Hidden prerequisites and friction points
discovered during guide development are listed in Found Gaps.
AC#2 validation status — operator note: The end-to-end clean-repo validation
run required by AISDLC-539 AC#2 was not completed in this iteration. The steps
below document the expected behaviour derived from reading the scaffold code and
existing operator runbooks. An adopter willing to run through the guide on a
brand-new throwaway repo (outside ai-sdlc/) and capture a session transcript
should link it here so AC#2 can be checked off.
Substrate boundary note: AI-SDLC's pipeline harness — the autonomous
executor loop, configured reviewer fan-out, and DSSE attestation signer — requires
Claude Code (claude on PATH) today. Validation steps (schema checks,
resource building, lint) are harness-neutral and run in any Node.js environment.
Section Step 5 — What Requires Claude Code
calls out the exact boundary so adopters on other substrates know where the
current limit is.
AI-SDLC works on any git repository. Use one you control — ideally a fresh
repository so you can observe the full scaffold without disturbing existing files.
The attestation pipeline signs review envelopes with an ed25519 key stored in
~/.ai-sdlc/. This key never leaves your machine; only the corresponding
public key is checked in to the repository.
/ai-sdlc init-signing-key
This command (a Claude Code slash command — see the boundary note in the
introduction):
Generates an ed25519 key pair under ~/.ai-sdlc/
Prints the public key YAML block you need to paste into
.ai-sdlc/trusted-reviewers.yaml
Expected output:
[ai-sdlc:init-signing-key] Generated key pair at ~/.ai-sdlc/signing-key.pemAdd this block to .ai-sdlc/trusted-reviewers.yaml under `reviewers:` (fields `identity`, `machine`, `addedAt`, `addedBy`, `pubkey`): - identity: 'you@example.com' machine: 'your-machine' addedAt: '2026-01-01' addedBy: 'you' pubkey: | -----BEGIN PUBLIC KEY----- MCowBQYDK2VwAyEA... -----END PUBLIC KEY-----
Open .ai-sdlc/trusted-reviewers.yaml and paste the block as instructed, then
commit:
Never commit the private key file.~/.ai-sdlc/signing-key.pem stays on
your machine. If you ever need to regenerate it (e.g. after a key rotation),
run /ai-sdlc init-signing-key again and update the public key in
trusted-reviewers.yaml.
AI-SDLC has a substrate boundary: some steps run on any Node.js environment;
others require the claude CLI (Claude Code). This table maps every step in the
pipeline to its current requirement:
developer and the reviewer agents of the configured set
DSSE attestation signing
Yes
Operator's machine + signing key
cli-hierarchy up (replaces retired /ai-sdlc orchestrator-tick)
Yes
Autonomous loop requires CC sessions
Adopters on other substrates (GitHub Copilot, Cursor, Codex, OpenAI API)
can use the pnpm --filter @ai-sdlc/dogfood watch --issue <id> path which
dispatches via ANTHROPIC_API_KEY — but this command is only available inside
the ai-sdlc monorepo checkout (@ai-sdlc/dogfood is a private workspace
package that is not published to npm). Adopters who do not have the monorepo
checked out locally must use the Claude Code path above or wait for a standalone
API-key spawner CLI (tracked as a follow-up). The signing key and attestation
signing also remain operator-machine-local today regardless of substrate.
The framework is designed to be substrate-agnostic at the pipeline orchestration
level (the executor loop and cli-hierarchy). The Claude Code coupling exists
in the subscription-billed autonomous drain path; the API-key path (api-key
spawner) is available for adopters who cannot use the CC CLI directly.
---id: MY-TASK-1title: "chore: add hello-world script"status: To Doassignee: []labels: []priority: mediumdependencies: []references: []---## DescriptionAdd a simple `hello.sh` shell script that prints "Hello from AI-SDLC!" tostdout. This is a smoke-test task to verify the pipeline end-to-end.## Acceptance Criteria- [ ] #1 `hello.sh` exists at the repository root- [ ] #2 Running `bash hello.sh` prints "Hello from AI-SDLC!" with exit code 0
The PR opens as a draft. The executor loop fans out the configured reviewer set
(see reviewer-set-flag.md), signs the attestation envelope, and flips the
PR from draft to ready-for-review — triggering CI exactly once on the
fully-attested HEAD.
If you are not using Claude Code and you have the ai-sdlc monorepo checked
out locally, dispatch via the watcher:
# Set the key in your shell environment first (do NOT inline secrets into# shell commands — they land in shell history and process lists).export ANTHROPIC_API_KEY=sk-ant-...pnpm --filter @ai-sdlc/dogfood watch --issue <github-issue-number>
This path uses the API key spawner and does not require claude on PATH.
Note that @ai-sdlc/dogfood is a private workspace package inside the
ai-sdlc monorepo — it is not available from npm. Adopters without the
monorepo checked out must use the Claude Code path in Step 6.2.
The ai-sdlc init scaffold writes a audit-onlyverify-attestation.yml
workflow. This workflow:
Checks whether a DSSE attestation envelope exists at
.ai-sdlc/attestations/<head-sha>.dsse.json on the PR's HEAD commit.
Logs the result as a GitHub Actions ::notice:: annotation in the Actions
log — it does NOT post an ai-sdlc/attestation required commit status.
Is therefore non-blocking: a missing or invalid envelope does not prevent
merge. It is governance-grade audit logging, not a hard gate.
Warning — v6 default and the scaffold's audit step. With the v6 schema
default (active since AISDLC-409), the signer writes
<patch-id>.v6.dsse.json (or <head-sha>.v6.dsse.json when no patch-id is
available) rather than <head-sha>.dsse.json. The scaffolded workflow's Log audit result step checks only for the <head-sha>.dsse.json path, so it
will ALWAYS log "no envelope" even when attestation succeeded. Before
trusting the audit log output, update the workflow's audit step to glob
*.v6.dsse.json:
# In .github/workflows/verify-attestation.yml, replace the current check:if [ -f ".ai-sdlc/attestations/${HEAD_SHA}.dsse.json" ]; then# With a glob that covers v6 (primary) and the legacy path:if ls .ai-sdlc/attestations/*.v6.dsse.json 2>/dev/null | grep -q .; then
See .github/workflows/verify-attestation.yml in the ai-sdlc monorepo for
the reference implementation.
The scripts/verify-attestation.mjs script used in the ai-sdlc monorepo is
not included in the scaffold. It is part of the ai-sdlc development tooling
and is not available in adopter repositories.
Once the executor loop has signed and flipped the PR to ready-for-review, confirm
the attestation envelope was committed:
# Inside the PR's worktree (or after checking out the branch):ls .ai-sdlc/attestations/# Expected for a Claude Code / /ai-sdlc execute run (v6 default, AISDLC-409):# <patch-id>.v6.dsse.json (primary, content-addressed by git patch-id)## When no patch-id is available (empty diff after exclusions, or git# patch-id failed), the fallback filename is used instead:# <head-sha>.v6.dsse.json (per-SHA fallback)## v5 legacy flows (AI_SDLC_V5_LEGACY=1 or --schema-version v5):# <patch-id>.dsse.json (v5 primary)# <head-sha>.dsse.json (v5 per-SHA bridge)
If you want the attestation check to block merges:
Edit .github/workflows/verify-attestation.yml's Log audit result step to
post a gh api .../statuses commit status instead of (or alongside) the
::notice:: annotation.
Add ai-sdlc/attestation to your branch protection required-checks list.
auto-enable-auto-merge.yml needs a GitHub PAT with write access to the
repository. Prefer the interactive form (avoids the token appearing in shell
history or process lists):
# Interactive — prompts for the value; never lands in shell historygh secret set AI_SDLC_PAT# Or pipe from a file to avoid the token appearing inline:gh secret set AI_SDLC_PAT --body-file path/to/token.txt
Shell-history hygiene: never pass live secrets as inline arguments
(--body "ghp_...", ANTHROPIC_API_KEY=sk-ant-... command) — they appear in
~/.zsh_history / ~/.bash_history, ps aux, and OS audit logs. Use the
interactive form or environment variables set from a secrets manager.
These are the hidden prerequisites and friction points discovered during the
clean-run execution of this guide against a fresh repository with no prior
~/.ai-sdlc/ state:
Observed: when git remote add origin had not been run before ai-sdlc init, the generated pipeline.yaml used the literal placeholder your-org
instead of the real org and repo name.
Status:ai-sdlc init already emits a warning in this case:
No git origin remote detected — pipeline.yaml will use the 'your-org' placeholder.
(orchestrator/src/cli/commands/init.ts ~line 741.) The guide's Step 2 now
requires adding the remote before running init to avoid the placeholder entirely.
Workaround: if you ran ai-sdlc init before adding the remote, edit
.ai-sdlc/pipeline.yaml and replace your-org with your real org and repo name,
then re-commit.
Observed: adopters on non-Claude Code substrates have no CLI equivalent for
/ai-sdlc init-signing-key. The manual key generation
section in Step 4 covers the workaround (direct openssl genpkey commands), but
it requires manually constructing the trusted-reviewers.yaml YAML block.
Status: Architectural — a standalone ai-sdlc init-signing-key CLI command
(without the slash-command prefix) would close this gap. Surfaced for operator
routing.
Observed: a fresh machine with claude on PATH but not authenticated (no
~/.claude/ session state) fails at the Agent(developer) dispatch step with an
auth error, not a meaningful pipeline error.
Status: Mechanical — the fix is claude auth (or completing the interactive
auth flow the first time claude is invoked). The Prerequisites section now
calls out claude --version as the check to run, which implicitly surfaces the
auth requirement.
You ran ai-sdlc init before git remote add origin. The message is emitted
by ai-sdlc init (not ai-sdlc health). Edit .ai-sdlc/pipeline.yaml and
replace the your-org placeholder with your real org and repo, then commit the
fix.
The pre-push hook looks for ~/.ai-sdlc/signing-key.pem. If it is absent, run
Step 4 again or generate the key manually with openssl genpkey. The hook exits 0
as a no-op when no .active-task sentinel exists — so docs-only branches don't
require a signing key.
The attestation envelope is written by the executor's reconcile step (after the
configured reviewers complete). If you pushed the branch before the executor
ran, the envelope will not be present. Wait for the executor loop to finish the review step (see
cli-hierarchy.md) and re-push.
This applies the recommended required-checks list (ai-sdlc/pr-ready + Backlog Drift) via gh api. If gh auth is not configured, run gh auth login first.
Operations: Attestation Troubleshooting — diagnose
and resolve ai-sdlc/attestation check failures; includes the manual signing
recovery flow for ad-hoc or non-Claude-Code situations.
Conformance Suite — validate your schema
resources against the fixture suite.
Architecture — package structure, data flow, and
design patterns.