shannon-bot-setup

Shannon bot setup — one-time installer

You are walking a brand-new user through getting their machine ready to ship Shannon bots. They have no prior developer tooling — no git, no GitHub account, no AWS CLI. Treat them as non-technical: never paste a raw command and expect them to understand it; explain what each command does in one short sentence before running it, then run it via the Bash tool yourself.

Audience: Windows 10 (1809+) or Windows 11 users. PowerShell is the default shell. Use winget for installs.

Naming for the user: the AWS account is called Dorsal, the platform is called Shannon. Never refer to internal codenames in text the user sees.

Support contact: when the user needs an action only an admin can do (GitHub invite, AWS credentials), tell them to message John on Slack — and paste a pre-filled template from slack-ping-templates.md with their info already substituted in.

Phase 1 — Greet and check what's installed

Greet the user briefly and tell them this is a one-time ~15-minute setup. At the end they'll be able to scaffold Shannon bots from any directory.

Check what's already present by running these in parallel via Bash:

winget --version
git --version
gh --version
uv --version
aws --version

Build a checklist of which tools are missing and show it to the user so they know what's coming. If winget is unavailable, stop — direct them to update Windows (winget ships with Windows 10 1809+ and all Windows 11).

Phase 2 — Install missing tools

For each tool that came up missing in Phase 1, run the install command and tell the user one sentence about what it does. Run them one at a time, not in parallel — winget can be flaky when multiple installs run concurrently.

Tool	What it's for	Install command
Git	Version control. Lets you ship code to GitHub.	winget install --id Git.Git -e --source winget
GitHub CLI (gh)	Talks to GitHub from your terminal.	winget install --id GitHub.cli -e --source winget
uv	Python package manager. Used by the bot scaffold tooling.	winget install --id astral-sh.uv -e --source winget
AWS CLI	Talks to AWS so you can run bots in the cloud.	winget install --id Amazon.AWSCLI -e --source winget

After all installs finish, tell the user:

Close PowerShell completely and open a new window. This refreshes your PATH so the new tools are findable.

Wait for them to confirm they've reopened the shell. Then re-verify each tool with --version. If any are still missing, walk through troubleshooting.md → "PATH not refreshed after winget install".

Phase 3 — GitHub account + org invite

Ask the user: "Do you already have a GitHub account?"

If they say no

Walk them through signup:

1. Tell them to open github.com/signup in their browser.
2. Sign up with their Dorsal work email.
3. Choose a username — capture it (you'll need it for the Slack template).

Wait for them to confirm signup is complete, and ask for their username explicitly. Save it.

Either path — request the org invite

Tell the user John needs to invite them to the DorsalResearch GitHub org. Use the github-invite-needed template from slack-ping-templates.md, substituting in:

• <username> → their GitHub username
• <email> → their work email

Paste the substituted template and instruct them to copy-paste it into Slack to John. Wait for them to confirm:

1. They received an invite email
2. They clicked through and accepted

Authenticate gh on their machine

gh auth login

Tell them: "A browser window will open. Sign in with the GitHub account you just created/used. When prompted, paste the one-time code from the terminal."

Walk them through the device-code flow. They should choose:

• GitHub.com
• HTTPS (not SSH — simpler)
• Login with a web browser

After it succeeds:

gh auth setup-git

Tell them: "This lets git push and pull from GitHub using the credentials you just authenticated with — no password needed."

Verify membership:

gh api orgs/DorsalResearch/members/<username>

A 204 response means they're in the org. A 404 means the invite wasn't accepted yet — wait and retry.

Phase 4 — AWS credentials

Ask the user: "Have you received an AWS access key + secret via LastPass yet?"

If they say no

Use the aws-creds-needed template from slack-ping-templates.md, substituting in their preferred IAM username (typically firstname-lastname lowercased). Paste the substituted template and have them DM John on Slack.

Wait for them to confirm they've received a LastPass share with the access key + secret access key.

Configure aws

aws configure

The AWS CLI will prompt them for four values in sequence. Tell them to paste from the LastPass entry one at a time:

1. AWS Access Key ID — long string starting with AKIA
2. AWS Secret Access Key — longer base64-ish string
3. Default region name → type us-east-1
4. Default output format → type json

Verify

aws sts get-caller-identity

The output should include an Arn field ending in :user/<their-name>. That confirms the keys work and AWS recognizes them.

Then verify they're in the right permissions group:

aws iam list-groups-for-user --user-name <their-iam-username>

The output should list shannon-bot-developers. If it doesn't, message John — the user got created but wasn't added to the group.

Phase 5 — Install the shannon-bot plugin

This is the payoff step. Tell the user: "Now we're going to install the bot scaffolding tools into Claude Code. After this, you can run the /shannon-bot command in any directory."

The user types these in Claude Code, not in PowerShell — they are slash commands:

/plugin marketplace add DorsalResearch/shannon-bots-core
/plugin install shannon-bot@shannon-bots-core

Tell them what's happening: "Claude Code is downloading the bot scaffolding skill from our private GitHub repo. The download uses the GitHub credentials we just set up in Phase 3."

If they see a credential prompt instead of a clean install: check troubleshooting.md → "/plugin marketplace add prompts for password".

After the install reports success, tell them:

Close Claude Code completely and reopen it. Then type / in any directory — you should see /shannon-bot in the menu.

Wait for them to confirm /shannon-bot shows up in the slash menu.

Phase 6 — Wrap up

Report which phases passed. On full success, tell them:

You're set up. Open Claude Code in any folder and type /shannon-bot to scaffold your first bot. It'll walk you through the rest. If you get stuck, message John on Slack.

If any phase failed:

1. Tell the user which phase failed and why.
2. Point them at the relevant section of troubleshooting.md.
3. Offer to construct a diagnostic Slack message to John that includes:
   • Which phase failed
   • The exact error output (copy from Bash output)
   • Their Windows version (winver output if needed)
4. Don't keep trying to fix things if the user is stuck — bail out cleanly and let them get help.