Merge branch 'main' into feat/ec2-fleet-strategy

Author: krokoko

.gitignore

@@ -0,0 +1,6 @@
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

LEGAL_DISCLAIMER.md

@@ -69,7 +69,76 @@ See the full [ROADMAP](./docs/guides/ROADMAP.md) for details on each iteration.
 
 ## Getting started
 
-### Installation and deployment
+### Claude Code plugin (recommended)
+
+This repository ships a [Claude Code plugin](https://docs.anthropic.com/en/docs/claude-code/plugins) that provides guided workflows for setup, deployment, task submission, and troubleshooting.
+
+#### Installing the plugin
+
+```bash
+git clone https://github.com/aws-samples/sample-autonomous-cloud-coding-agents.git
+cd sample-autonomous-cloud-coding-agents
+claude --plugin-dir docs/abca-plugin
+```
+
+The `--plugin-dir` flag tells Claude Code to load the local plugin from the `docs/abca-plugin/` directory. The plugin's skills, commands, agents, and hooks will be available immediately.
+
+> **Tip:** If you use Claude Code via VS Code or JetBrains, you can add `--plugin-dir docs/abca-plugin` to the extension's CLI arguments setting.
+
+#### What the plugin provides
+
+**Skills** (guided multi-step workflows — Claude activates these automatically based on your request):
+
+| Skill | Triggers on | What it does |
+|-------|------------|--------------|
+| `setup` | "get started", "install", "first time setup" | Full guided setup: prerequisites, toolchain, deploy, smoke test |
+| `deploy` | "deploy", "cdk diff", "destroy" | Deploy, diff, or destroy the CDK stack with pre-checks |
+| `onboard-repo` | "add a repo", "onboard", 422 errors | Add a new GitHub repository via Blueprint construct |
+| `submit-task` | "submit task", "run agent", "review PR", "quick submit" | Submit a coding task with prompt quality coaching (supports quick mode) |
+| `troubleshoot` | "debug", "error", "not working", "failed" | Diagnose deployment, auth, or task execution issues |
+| `status` | "status", "health check", "is ABCA running" | Platform health check: stack status, running tasks, build health |
+
+**Agents** (specialized subagents, spawned automatically or via the Agent tool):
+
+| Agent | When it's used |
+|-------|---------------|
+| `cdk-expert` | CDK architecture, construct design, handler implementation, stack modifications |
+| `agent-debugger` | Task failure investigation, CloudWatch log analysis, agent runtime debugging |
+
+**Hook** (runs automatically):
+
+A `SessionStart` hook advertises available skills and agents so Claude can proactively suggest them when your request matches.
+
+#### Local plugin development
+
+If you're modifying the plugin itself, here's the file layout:
+
+```
+docs/abca-plugin/
+  plugin.json                    # Plugin manifest (name, version, description)
+  skills/
+    setup/SKILL.md               # First-time setup workflow
+    deploy/SKILL.md              # CDK deployment workflow
+    onboard-repo/SKILL.md        # Repository onboarding workflow
+    submit-task/SKILL.md         # Task submission (guided + quick mode)
+    troubleshoot/SKILL.md        # Diagnostic workflow
+    status/SKILL.md              # Platform health check
+  agents/
+    cdk-expert.md                # CDK infrastructure specialist
+    agent-debugger.md            # Task failure debugger
+  hooks/
+    hooks.json                   # SessionStart capability advertisement
+```
+
+**Key conventions:**
+- The plugin lives under `docs/` to keep documentation and plugin content colocated
+- Skills live in subdirectories with a `SKILL.md` file (not flat `.md` files)
+- Agents are flat `.md` files with YAML frontmatter
+- The hook advertises plugin capabilities only (no project-specific content)
+
+**After editing plugin files**, restart Claude Code with `claude --plugin-dir docs/abca-plugin` to pick up changes.
+
+### Manual installation and deployment
 
 Install [mise](https://mise.jdx.dev/getting-started.html) if you want to use repo tasks (`mise run install`, `mise run build`). For monorepo-prefixed tasks (`mise //cdk:build`, etc.), set **`MISE_EXPERIMENTAL=1`** — see [CONTRIBUTING.md](./CONTRIBUTING.md).
 

README.md

@@ -111,6 +111,56 @@ if [[ -z "${AWS_REGION:-}" ]]; then
     exit 1
 fi
 
+# ---------------------------------------------------------------------------
+# Resolve AWS credentials (before Docker build to fail fast)
+# ---------------------------------------------------------------------------
+# Store resolved credentials in variables so they can be applied to DOCKER_ARGS
+# after the image is built. This avoids a lengthy Docker build only to discover
+# that AWS credentials are missing or expired.
+AWS_CRED_MODE=""
+RESOLVED_KEY=""
+RESOLVED_SECRET=""
+RESOLVED_TOKEN=""
+
+if [[ -n "${AWS_ACCESS_KEY_ID:-}" ]]; then
+    AWS_CRED_MODE="explicit"
+    RESOLVED_KEY="${AWS_ACCESS_KEY_ID}"
+    RESOLVED_SECRET="${AWS_SECRET_ACCESS_KEY}"
+    RESOLVED_TOKEN="${AWS_SESSION_TOKEN:-}"
+    echo "  AWS:       using explicit credentials (AWS_ACCESS_KEY_ID)"
+elif command -v aws &>/dev/null; then
+    # Resolve credentials from the AWS CLI (handles SSO, profiles, credential files).
+    # This avoids the need to mount ~/.aws and replicate the full credential chain
+    # inside the container — SSO tokens in particular don't resolve well there.
+    echo "  AWS:       resolving credentials via AWS CLI${AWS_PROFILE:+ (profile '${AWS_PROFILE}')}..."
+    EXPORT_CMD=(aws configure export-credentials --format process)
+    [[ -n "${AWS_PROFILE:-}" ]] && EXPORT_CMD+=(--profile "${AWS_PROFILE}")
+
+    CREDS_JSON=$("${EXPORT_CMD[@]}" 2>/dev/null) || {
+        echo "ERROR: Failed to resolve AWS credentials via AWS CLI." >&2
+        echo "  Possible fixes:" >&2
+        echo "    - Run 'aws sso login${AWS_PROFILE:+ --profile ${AWS_PROFILE}}' if using SSO" >&2
+        echo "    - Run 'aws configure${AWS_PROFILE:+ --profile ${AWS_PROFILE}}' to set up a profile" >&2
+        echo "    - Export AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY directly" >&2
+        exit 1
+    }
+
+    AWS_CRED_MODE="resolved"
+    RESOLVED_KEY=$(echo "$CREDS_JSON" | python3 -c "import sys,json; c=json.load(sys.stdin); print(c['AccessKeyId'])")
+    RESOLVED_SECRET=$(echo "$CREDS_JSON" | python3 -c "import sys,json; c=json.load(sys.stdin); print(c['SecretAccessKey'])")
+    RESOLVED_TOKEN=$(echo "$CREDS_JSON" | python3 -c "import sys,json; c=json.load(sys.stdin); print(c.get('SessionToken',''))")
+    echo "  AWS:       resolved temporary credentials (AccessKeyId: ${RESOLVED_KEY:0:8}...)"
+elif [[ -d "${HOME}/.aws" ]]; then
+    AWS_CRED_MODE="mount"
+    if [[ -n "${AWS_PROFILE:-}" ]]; then
+        echo "  AWS:       mounting ~/.aws with profile '${AWS_PROFILE}' (SSO may not work)"
+    else
+        echo "  AWS:       mounting ~/.aws (using default profile)"
+    fi
+else
+    echo "WARNING: No AWS credentials detected. Set AWS_ACCESS_KEY_ID or AWS_PROFILE, or ensure ~/.aws exists." >&2
+fi
+
 # ---------------------------------------------------------------------------
 # Build
 # ---------------------------------------------------------------------------
@@ -161,49 +211,17 @@ if [[ "$MODE" == "server" ]]; then
     DOCKER_ARGS+=(-p 8080:8080)
 fi
 
-# AWS credentials: prefer explicit env vars, then resolve from profile/SSO
-if [[ -n "${AWS_ACCESS_KEY_ID:-}" ]]; then
-    DOCKER_ARGS+=(
-        -e "AWS_ACCESS_KEY_ID=${AWS_ACCESS_KEY_ID}"
-        -e "AWS_SECRET_ACCESS_KEY=${AWS_SECRET_ACCESS_KEY}"
-    )
-    [[ -n "${AWS_SESSION_TOKEN:-}" ]] && DOCKER_ARGS+=(-e "AWS_SESSION_TOKEN=${AWS_SESSION_TOKEN}")
-    echo "  AWS:       using explicit credentials (AWS_ACCESS_KEY_ID)"
-elif command -v aws &>/dev/null; then
-    # Resolve credentials from the AWS CLI (handles SSO, profiles, credential files).
-    # This avoids the need to mount ~/.aws and replicate the full credential chain
-    # inside the container — SSO tokens in particular don't resolve well there.
-    PROFILE_ARG=()
-    [[ -n "${AWS_PROFILE:-}" ]] && PROFILE_ARG=(--profile "${AWS_PROFILE}")
-
-    echo "  AWS:       resolving credentials via AWS CLI${AWS_PROFILE:+ (profile '${AWS_PROFILE}')}..."
-    CREDS_JSON=$(aws configure export-credentials "${PROFILE_ARG[@]}" --format process 2>/dev/null) || {
-        echo "ERROR: Failed to resolve AWS credentials. Make sure you are logged in:" >&2
-        echo "  aws sso login${AWS_PROFILE:+ --profile ${AWS_PROFILE}}" >&2
-        exit 1
-    }
-
-    RESOLVED_KEY=$(echo "$CREDS_JSON" | python3 -c "import sys,json; c=json.load(sys.stdin); print(c['AccessKeyId'])")
-    RESOLVED_SECRET=$(echo "$CREDS_JSON" | python3 -c "import sys,json; c=json.load(sys.stdin); print(c['SecretAccessKey'])")
-    RESOLVED_TOKEN=$(echo "$CREDS_JSON" | python3 -c "import sys,json; c=json.load(sys.stdin); print(c.get('SessionToken',''))")
-
+# Apply previously resolved AWS credentials to DOCKER_ARGS
+if [[ "$AWS_CRED_MODE" == "explicit" || "$AWS_CRED_MODE" == "resolved" ]]; then
     DOCKER_ARGS+=(
         -e "AWS_ACCESS_KEY_ID=${RESOLVED_KEY}"
         -e "AWS_SECRET_ACCESS_KEY=${RESOLVED_SECRET}"
     )
     [[ -n "${RESOLVED_TOKEN}" ]] && DOCKER_ARGS+=(-e "AWS_SESSION_TOKEN=${RESOLVED_TOKEN}")
-    echo "  AWS:       resolved temporary credentials (AccessKeyId: ${RESOLVED_KEY:0:8}...)"
-elif [[ -d "${HOME}/.aws" ]]; then
+elif [[ "$AWS_CRED_MODE" == "mount" ]]; then
     # Fallback: mount ~/.aws directly (works for static credential files, not SSO)
     DOCKER_ARGS+=(-v "${HOME}/.aws:/home/agent/.aws:ro")
-    if [[ -n "${AWS_PROFILE:-}" ]]; then
-        DOCKER_ARGS+=(-e "AWS_PROFILE=${AWS_PROFILE}")
-        echo "  AWS:       mounting ~/.aws with profile '${AWS_PROFILE}' (SSO may not work)"
-    else
-        echo "  AWS:       mounting ~/.aws (using default profile)"
-    fi
-else
-    echo "WARNING: No AWS credentials detected. Set AWS_ACCESS_KEY_ID or AWS_PROFILE, or ensure ~/.aws exists." >&2
+    [[ -n "${AWS_PROFILE:-}" ]] && DOCKER_ARGS+=(-e "AWS_PROFILE=${AWS_PROFILE}")
 fi
 
 echo ""