docs(onboarding): operator-path fixes across QUICK_START + /setup + /onboard-repo skills#432
Open
isadeks wants to merge 5 commits into
Open
docs(onboarding): operator-path fixes across QUICK_START + /setup + /onboard-repo skills#432isadeks wants to merge 5 commits into
isadeks wants to merge 5 commits into
Conversation
…wn, fix toolchain papercuts Setup-UX fixes from a live first-contact deploy to a fresh security-managed AWS Org account. Edits QUICK_START.mdx + the /setup plugin SKILL.md (Starlight mirror regenerated): - X-Ray → CloudWatch Logs tracing reframed as OPTIONAL, not a prerequisite. The stack ships with tracing disabled (`tracingEnabled` in agent.ts), so it deploys fully without any X-Ray account setup. On Org accounts an SCP can make `update-trace-segment-destination` fail with AccessDenied regardless — a dead-end on a step the platform doesn't use. Removed the X-Ray commands from the deploy path; demoted to an opt-in note. - arm64/binfmt pre-empted: x86 hosts hit `exec /bin/sh: exec format error` building the Graviton image. Added the binfmt step + native-arm64 fallback to Prerequisites and a Step 3 caution. - Deploy command now uses `--require-approval never` (avoids the non-TTY approval hang). - Failed-create teardown documented: ROLLBACK_COMPLETE needs destroy+recreate; DELETE_FAILED on SG/subnet is async Hyperplane-ENI reclaim (~20-40min); don't force-delete (orphans the quota-capped VPC). - Toolchain papercuts: mise provisions Node/Yarn/CDK (the "all missing" scare), headless GPG verify, dual mise-config trust, non-interactive PATH, and noisy- but-benign build output (trust the exit code).
…ath; drop misapplied ADR-003 The /onboard-repo skill drove operators to edit cdk/src/stacks/agent.ts and redeploy to add a repo, and invoked ADR-003 contribution governance. Both are wrong for an operator configuring their own deployment: - `bgagent repo onboard <owner/repo>` (cli repo command, "operator path") writes the RepoTable record at runtime — no agent.ts edit, no cdk deploy. The skill never mentioned it. - ADR-003 governs contributing to aws-samples, NOT operating your own stack. Onboarding a repo is an operation, not a codebase contribution. Rewrite: Path A (CLI operator onboard) is the default; Path B (CDK Blueprint) kept as the declarative/canonical alternative. ADR-003 now appears only where it genuinely applies — wiring a brand-new Bedrock model into the stack, the one case that is a real source change (e.g. Opus 4.8, which the runtime doesn't yet grantInvoke). Preserves the model-ID / IAM / Bedrock-access reference. Surfaced during the 2026-06-23 fresh-account live run, where the skill walked through agent.ts surgery for what is a one-line runtime command.
isadeks
changed the title
…s a Blueprint Consistency with @krokoko's review on #435: the CLI `bgagent repo onboard` path applies when the repo fits the platform/default-blueprint setup (default token, already-granted model, default egress). A repo needing its own token, an ungranted model, custom egress, Cedar policies, or system-prompt overrides requires a dedicated Blueprint + redeploy. Reframed the two-path intro to set that expectation up front (start with Path A; promote to a Blueprint if a task later fails on a missing token / model grant / blocked egress).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Onboarding-doc + plugin-skill fixes from a live first-contact deployment to a fresh, security-managed AWS Org account (clone →
/setup→ deploy → first task). The common thread: the docs and skills impose ceremony the platform doesn't require. EditsQUICK_START.mdx, the/setupskill, and the/onboard-reposkill (Starlight mirror regenerated).Fixes #431.
QUICK_START.mdx + /setup skill
aws xray update-trace-segment-destinationwas "required before first deployment." The stack ships with tracing disabled (tracingEnabledinagent.ts) and deploys fully without it; on a security-managed Org account that call is SCP-blocked and unclearable — a dead-end on a no-op step. Removed from the deploy path, demoted to an opt-in note.exec /bin/sh: exec format errorbuilding the Graviton image. Added the binfmt step + native-arm64 fallback.--require-approval neverin the deploy command (avoids the non-TTY hang).ROLLBACK_COMPLETE→ destroy+recreate;DELETE_FAILEDis async Hyperplane-ENI reclaim ~20–40 min; don't force-delete → orphans the quota-capped VPC)./onboard-repo skill (new in this PR)
The skill drove operators to edit
cdk/src/stacks/agent.ts+ redeploy to add a repo, and invoked ADR-003 contribution governance. Both wrong for an operator configuring their own deployment:bgagent repo onboard <owner/repo>(the CLI "operator path") writes the RepoTable record at runtime — noagent.tsedit, nocdk deploy. The skill never mentioned it.Rewrote so Path A (CLI
bgagent repo onboard) is the default, Path B (CDK Blueprint) is the declarative alternative, and ADR-003 appears only where it genuinely applies — wiring a brand-new Bedrock model into the stack (e.g. Opus 4.8, which the runtime doesn't yetgrantInvoke), the one real source change.Validation
End-to-end on a fresh AWS account (never previously used):
git clone→/setupwith the edited plugin →CREATE_COMPLETEfirst attempt, zero X-Ray setup, no rollback → PAT/Cognito/CLI configured → authenticatedGET /tasksworks. binfmt carried the arm64 build through on the x86 host.mise //docs:buildpasses; Starlight mirror in sync.Related
Complements the four bootstrap least-privilege fixes (#403/#405/#408/#410, all merged) — together a fresh-account first deploy now succeeds without the prior gap-by-gap rollback cycle.
For reviewers
Docs/skills only — 4 files (
QUICK_START.mdx,/setupSKILL.md,/onboard-repoSKILL.md, regenerated Starlight mirror). No code or infra changes.