docs(skills): audit deploy/submit-task/troubleshoot/status — stale claims, node PATH, onboard path#435
Merged
Merged
Conversation
…ms, node PATH, onboard path Audit of the four remaining plugin skills against issues found in live use: deploy: - Correct the inverted least-privilege claim. It said bootstrap grants AdministratorAccess by default and scoping is an optional prod step — the opposite of reality: the custom least-privilege bootstrap (ADR-002) IS the default. Rewritten to describe that, plus the add-a-resource→add-an-action consequence (the #402/#404/#407/#409 class). - Deploy command uses `--require-approval never` (non-TTY hang); add arch/binfmt pre-check; add DELETE_FAILED/Hyperplane-ENI teardown + ROLLBACK_COMPLETE notes to destroy; "trust the exit code" on the noisy build; onboard via `bgagent repo onboard`, not Blueprint-by-default. troubleshoot: - REPO_NOT_ONBOARDED fix is `bgagent repo onboard`, not "needs a Blueprint". - 403-model fix: point the repo at an already-granted model, or add a model via the shared `bedrockModels` context (#433) + account-level Bedrock access — not "edit grantInvoke in agent.ts". submit-task / troubleshoot / status: - Note that `node cli/lib/bin/bgagent.js …` needs `mise exec --` in a non-interactive / mise-managed shell (the live `node: command not found`). Docs-only; abca-plugin skills are not Starlight-mirrored (no docs:sync needed).
krokoko
reviewed
Jun 23, 2026
krokoko
reviewed
Jun 23, 2026
…latform doctor Per @krokoko on #435: - The `bgagent repo onboard` line over-claimed. Clarify it's the runtime path for repos that fit 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 still needs a dedicated CDK Blueprint + redeploy with correct permissions. - Add `bgagent platform doctor` to post-deploy as the readiness check before submitting a task (smoke-checks API/Cognito/token/Bedrock/onboarded repos); keep the raw curl as a lower-level alternative.
isadeks
pushed a commit
that referenced
this pull request
Jun 23, 2026
…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).
krokoko
approved these changes
Jun 23, 2026
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
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
Audit of the four plugin skills not touched by #432, against issues found during a live first-contact deployment. All doc-only edits to
docs/abca-plugin/skills/*/SKILL.md. The recurring theme (same as #432): skills describe ceremony or a reality that no longer matches the platform.deploy(most significant)AdministratorAccessby default and scoping is an optional production step. That's backwards — the custom least-privilege bootstrap (ADR-002) is the default. Rewritten to describe the default accurately, plus the practical consequence: adding a new resource type / feature may require adding the IAM action tocdk/src/bootstrap/policies/(the fix(cdk): bootstrap least-privilege policy missing JiraIntegration* secret pattern → deploy rolls back #402/fix(cdk): bootstrap S3 policy missing s3:PutBucketVersioning → AttachmentsBucket deploy rolls back #404/fix(cdk): bootstrap policy missing lambda:TagResource on event-source-mappings → deploy rolls back #407/fix(cdk): bootstrap policy missing lambda:Put/DeleteProvisionedConcurrencyConfig → deploy rolls back #409 class of rollbacks).--require-approval never(non-TTY hang); added an x86/arm64 binfmt pre-check; addedDELETE_FAILED(async Hyperplane-ENI reclaim, ~20–40 min) +ROLLBACK_COMPLETEnotes to the destroy workflow; "trust the exit code" note on the noisy build; onboard viabgagent repo onboardrather than "Blueprint constructs if needed."troubleshootREPO_NOT_ONBOARDED(422) fix isbgagent repo onboard <owner/repo>, not "needs a Blueprint construct."bedrockModelsCDK context (feat(cdk): make the runtime's invocable Bedrock model set stack-configurable (one list, not two hardcoded arrays) #433) plus account-level Bedrock access — not "editgrantInvokeinagent.ts."submit-task/troubleshoot/statusnode cli/lib/bin/bgagent.js …needs amise exec --prefix in a non-interactive / mise-managed shell (the livenode: command not found).submit-task's prompt-quality and cost-control guidance was otherwise solid and is unchanged.Notes
abca-pluginskills are not Starlight-mirrored, so nodocs:syncneeded.troubleshoot403-model wording references thebedrockModelscontext from feat(cdk): make the runtime's invocable Bedrock model set stack-configurable (one list, not two hardcoded arrays) #433 (PR feat(cdk): single source of truth for invocable Bedrock models, context-overridable (#433) #434, open). It also gives the no-redeploy quick fix (repoint to a granted model), so it's accurate regardless of feat(cdk): single source of truth for invocable Bedrock models, context-overridable (#433) #434's merge state./setup+/onboard-repo). Together the full six-skill set is audited.