# Agent Bootstrap — Read This First > Every dispatched agent reads this before their role-specific guide. > Base guide for rdc-skills — provides credential, git, and reporting patterns across projects. --- ## Who You Are You are a subagent dispatched by the rdc:build supervisor. You have a specific scope (files, package, feature) that will be in your prompt. Stay in that scope. NEVER modify files outside it. Read `guides/engineering-behavior.md` next when it is available. It defines the RDC implementation posture for assumptions, minimal changes, surgical scope, verification evidence, and escalation. --- ## Credentials — Daemon Access Pattern You do NOT have access to cloud MCP connectors. Instead, all credentials come from a daemon running locally (typically on localhost:52437). **Ping first to confirm availability:** ```bash curl -s http://127.0.0.1:52437/ping ``` If it doesn't respond — report BLOCKED, do not proceed. **Get a credential:** ```bash curl -s http://127.0.0.1:52437/get/ ``` **Pattern for extracting key/value without printing:** ```bash # Correct pattern — never echo the key KEY=$(curl -s http://127.0.0.1:52437/get/ | python3 -c "import sys,json; print(json.load(sys.stdin)['key'])") curl -s -H "Authorization: Bearer $KEY" https://api.example.com/... ``` **Never print credentials to stdout.** Capture to a variable, use inline, discard. --- ## Project Directory Convention This plugin uses the `.rdc/` directory convention. Check for it first: ```bash # Check if .rdc/ exists at project root ls {PROJECT_ROOT}/.rdc/config.json 2>/dev/null && echo "using .rdc/" || echo "using docs/ fallback" ``` **Path resolution rule:** - Guides: `{PROJECT_ROOT}/.rdc/guides/` → fallback: `{PROJECT_ROOT}/docs/guides/` - Plans: `{PROJECT_ROOT}/.rdc/plans/` → fallback: `{PROJECT_ROOT}/docs/plans/` - Reports: `{PROJECT_ROOT}/.rdc/reports/` → fallback: `{PROJECT_ROOT}/docs/reports/` - Research: `{PROJECT_ROOT}/.rdc/research/` → fallback: `{PROJECT_ROOT}/docs/research/` If `.rdc/config.json` exists, read it for project metadata (name, description, conventions). --- ## Database Access — Check Project Overlay The project overlay guide will specify: - Database project reference / instance name - Whether to use MCP connectors or daemon - Available RPC functions - Work item management patterns Read the project-specific agent-bootstrap.md overlay for exact connection details. --- ## Git Rules - Branch: Always use the project's primary development branch (typically `develop` or `main`) - Auto-commit after completing your scope — no confirmation needed - Commit message must use conventional format: `feat/fix/chore/refactor(): description` - Push to origin after committing - NEVER force-push --- ## Build Rules Never run `pnpm build` or equivalent full builds locally — they consume excessive memory. Type-check only: `npx tsc --noEmit --project /tsconfig.json` Run tests only for modified packages: modify tests in isolation, not whole suite. ### No Foreground Windows Agent-launched processes must not steal focus. This is a hard local-operator rule, not a preference. - Playwright must run headless. Do not use `--headed`, `--ui`, `codegen`, `open`, `show-report`, or `PWDEBUG=1` in agent sessions. - Use list/dot/json reporters and saved trace/report artifacts instead of opening the Playwright UI. - PowerShell helpers must use `-WindowStyle Hidden -NonInteractive`, or a hidden wrapper. - `Start-Process` must include `-WindowStyle Hidden` or `-WindowStyle Minimized`. - `cmd /c start` must use `/min` for intentionally visible tools or `/b` for background work. - Node/cmd/ps1 helpers launched by hooks must go through the RDC hidden hook runner. Check the project overlay for specific language, package manager, and build constraints. --- ## RDC_TEST Sandbox Contract When `RDC_TEST=1` is set, the skill is running inside the Tier 2 sandbox harness. Short-circuit all destructive external side effects. **How to detect:** `process.env.RDC_TEST === '1'` (Node/JS) or `[ "$RDC_TEST" = "1" ]` (bash). The Tier 2 runner sets this before invoking `claude --print`. **Allowed under RDC_TEST** — run normally, no guard: | Operation | Why | |-----------|-----| | Local git commits | Commit to the worktree branch; never pushed | | Local filesystem writes | Inside the sandbox worktree | | Supabase reads | Assertions read prod DB; no writes | | Service reads | Coolify status, CF DNS lookup, GitHub read — all safe | | `clauth` credential reads | Read-only against the daemon | **Short-circuit under RDC_TEST** — must be wrapped in a guard: - Supabase INSERT/UPDATE/DELETE (work items, prototype_registry, design_context, etc.) — runner uses main-db mode, no test branch - Coolify app deploys / restarts / config writes - Cloudflare DNS writes / cache purges - R2 object writes / deletes - `git push` to any remote - `gh pr create`, `gh release create`, tag pushes - `npm publish` - Any webhook fire, email send, Slack post - MCP connector tools that mutate external state (e.g. `mcp__coolify__deploy`) **Bash pattern:** ```bash if [ "$RDC_TEST" != "1" ]; then curl -X POST "$DEPLOY_API_BASE/api/v1/applications/$UUID/deploy" ... else echo "[RDC_TEST] skipping Coolify deploy" fi ``` **Node/JS pattern:** ```js if (process.env.RDC_TEST !== '1') { await deployToCoolify(...); } else { console.log('[RDC_TEST] skipping Coolify deploy'); } ``` **Why this matters:** Tier 2 runs every skill in a throwaway sandbox. If your skill fires a real deploy or DNS change under `RDC_TEST`, the test isn't a test — it's a production incident. **New-skill contract:** every new `rdc:*` skill MUST honor `RDC_TEST` before shipping. Tier 2 manifests will fail any skill that writes to external state under the flag. **Known blocker:** Project-specific cwd hooks must check `process.env.RDC_TEST === '1'` and call `process.exit(0)` early to allow Tier 2 sandbox runs. Without this bypass, headless self-test invocations can fail before the skill loads. File: `~/.claude/hooks/check-cwd.js`. --- ## Completion Report When your scope is done, return a structured report to the supervisor: ``` AGENT_COMPLETE: { scope: "", files_changed: ["path/to/file", ...], work_item_id: "", commits: [" "], blockers: [""] } ``` If you hit a blocker mid-task: stop, report it, do not guess or work around it. --- ## Self-Check Rules — Prevent Getting Lost ### 10-Minute Rule If you have been working on a **single step** for more than 10 minutes without measurable progress (no new files changed, no successful tool calls, no forward movement), **stop immediately**. Do not keep trying variations. Report it as a blocker. ### 2-Retry Rule If the **same command or approach fails twice**, stop. Do not attempt a third variation or creative workaround. Report the failure with the exact error output. ### Scope Drift Rule If you discover that fixing your assigned task would also require changing files **outside your scope**, stop. Do not fix them. Add them to `blockers` in your AGENT_COMPLETE report. The supervisor assigns them separately. ### What "measurable progress" means - A file was created or modified ✅ - A tool call succeeded and returned useful data ✅ - A command ran without error ✅ - Trying the same thing with slightly different parameters ❌ - Reading the same file again hoping for different insight ❌ - Rephrasing a failing query ❌ --- ## ⛔ Implementation Report + CodeFlow Exit Contract Every implementation agent MUST follow this protocol before moving a work item to `review`. Agents do not close non-epic work as `done`; validators close it after fresh verification. ### Step 1 — Tick checklist items as you complete them ```sql SELECT update_checklist_item( ''::uuid, 'item-id', true, '', 'agent', 'rpc' ); ``` Call this for each item AS you complete it — not all at once at the end. The database records every tick in `work_item_checklist_events`. Supervisor and validator re-ticks are rejected by the exit gate. ### Step 2 — Submit implementation report BEFORE marking done ```sql SELECT submit_implementation_report( ''::uuid, '{ "tldr":"...", "assumptions":[], "deviations":[], "uncertainty":[], "detail":"...", "flags":[], "codeflow_post":{ "agent_session_id":"", "summary":"...", "files_changed":["path/to/file"], "verification":["command or evidence"], "commit":"" } }'::jsonb ); ``` Returns `{ flags_count, deviations_count, has_deviations }`. Include this signal in your `AGENT_COMPLETE` report. ### Step 3 — Move to review ```sql SELECT update_work_item_status( ''::uuid, 'review', '["Implementation complete; ready for validator"]'::jsonb, '', 'agent' ); ``` If the report or `codeflow_post` is missing, the database raises EXCEPTION. ### Validator close — mark done only after fresh review ```sql SELECT update_work_item_status( ''::uuid, 'done', '["Validator verified implementation report, CodeFlow post, and checklist evidence"]'::jsonb, '', 'validator' ); ``` If any `required: true` checklist item is still unchecked, was re-ticked by a supervisor/validator, or was ticked by a different session than the originating agent, the DB and PreToolUse hook reject the close. ### Supervisor workflow - All zeros → clean run, proceed - `flags_count > 0` or `deviations_count > 0` → pull full report: ```sql SELECT implementation_report FROM work_items WHERE id = ''; ``` --- ## Now read your role-specific guide Path: `{PROJECT_ROOT}/.rdc/guides/.md` (e.g., `frontend.md`, `backend.md`, `data.md`) Fallback: `{PROJECT_ROOT}/docs/guides/.md` if `.rdc/` does not exist. The project overlay will specify the exact location if it differs from the convention above.