From fbcb9dcfa7bac25a268ea78551ba8f171dae3a01 Mon Sep 17 00:00:00 2001 From: Gabriel Vinhaes Date: Tue, 10 Mar 2026 15:08:17 -0300 Subject: [PATCH] docs: align openclaw agents bootstrap guide --- AGENTS.md | 115 ++++++++++++++++++++---------------------------------- 1 file changed, 43 insertions(+), 72 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 51767db..17f61cf 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,85 +1,56 @@ # AGENTS -This file is for AI agents working in this repository. +This file is the bootstrap guide for AI agents working in `orbio-openclaw-integration/`. -## Workspace positioning -- In the umbrella workspace root, this project is located at `orbio-openclaw-integration/`. -- Sibling projects are `orbio-api/` and `frontend/`. -- For cross-project references, use workspace-root paths (`orbio-api/...`, `frontend/...`) or sibling-relative paths (`../orbio-api/...`, `../frontend/...`). +## Scope +- OpenClaw plugin package and official skill artifacts for Orbio integration. +- Sibling repos: `../orbio-api/`, `../frontend/`. -## Scope (short) -- Official Orbio integration for OpenClaw. -- npm plugin package (`@orbio/orbio-openclaw`) and official skill artifacts. -- Focus: secure account discovery + export workflows through Orbio API. +## Required Skills (order) -## Must-read docs -- `README.md` -- `RELEASING.md` -- `SECURITY.md` -- `orbio-openclaw-plugin/README.md` - -## Hard rules (require explicit approval) -- Architectural changes (plugin contract, command surface, API semantics, security posture). -- Adding fallback behavior that changes runtime outcomes. -- Adding TODOs, stubs, placeholders, or dead code. -- Skipping/disabling linters or tests, or merging with failing checks. -- Introducing shell execution paths (`exec`, `curl`, subprocesses) in plugin runtime. +1. `orbio-workspace-router` +- Confirm repository scope and cross-project impact. -## Pre-launch policy (active) -- Prioritize secure and simple behavior over backward-compatibility shims. -- Replace incorrect behavior directly instead of layering compatibility paths. +2. `implementation-spec-writer` (if long/non-trivial) +- Mandatory before significant behavior changes. -## Repo structure rules -- `orbio-openclaw-plugin/` contains all importable plugin code and test/runtime configs. -- `skill-orbio-official/` contains standalone skill artifact(s) for ClawHub. -- Root docs (`README.md`, `RELEASING.md`, `SECURITY.md`) define operating policy and release process. -- Shared runtime logic must stay in `orbio-openclaw-plugin/src/`. -- Tests must live in `orbio-openclaw-plugin/tests/` and mirror source behavior. +3. `adr-writer` (if architectural decision exists) -## Stack -| Layer | Technology | -|---|---| -| Runtime | Node.js 20+ | -| Language | TypeScript (strict mode) | -| Package manager | pnpm | -| Test runner | Vitest (`@vitest/coverage-v8`) | -| Lint | ESLint 9 flat config + `typescript-eslint` | -| CI | GitHub Actions | +4. `git-worktree-flow` +- Mandatory git/worktree/PR lifecycle. -## Testing rules -- Every change in `orbio-openclaw-plugin/src/` must include or update tests in `orbio-openclaw-plugin/tests/`. -- Coverage threshold is strict: **95%** for lines, branches, functions, and statements. -- Tests must cover security-critical behavior: - - contact masking default - - plan allowlist enforcement - - throttling and retry policy - - error mapping and request-id propagation -- Avoid superficial render/smoke-only tests; assert observable behavior and contract outputs. +5. `orbio-openclaw-delivery` +- Plugin/runtime policy, security constraints, and release validations. -## Quality gates (must pass) -- `pnpm lint` -- `pnpm typecheck` -- `pnpm coverage` -- `pnpm build` -- Use `pnpm verify` to run the full gate (`quality + build`). - -## Workflow -- Run all package operations with `pnpm`. -- This repo uses a `pnpm` workspace (`pnpm-workspace.yaml`); run installs from the repo root. -- Prefer `pnpm install --frozen-lockfile` for deterministic local/CI installs. -- Commit hooks are managed by Husky (`.husky/pre-commit`) and must stay enabled. -- Before publish, run real-environment validation in `REAL_ENV_TESTING.md`. -- Keep release version synchronized across: - - `orbio-openclaw-plugin/package.json` - - `orbio-openclaw-plugin/openclaw.plugin.json` - - `PLUGIN_VERSION` in `orbio-openclaw-plugin/src/index.ts` -- Keep package publishing through documented flow in `RELEASING.md`. +## Must-Read Docs +- `README.md` +- `RELEASING.md` +- `SECURITY.md` +- `orbio-openclaw-plugin/README.md` -## Security baseline -- Never commit secrets, keys, or tokens. -- Avoid logging PII/contact fields unless explicitly required for secure debugging. +## Hard Rules (explicit approval required) +- Architectural changes to plugin contract/command surface/API semantics/security posture. +- Behavior-changing fallback paths. +- TODO/stub/placeholder/dead code. +- Skipping/disabling/ignoring lint/typecheck/coverage/build failures. +- Introducing shell execution in plugin runtime (`exec`, `curl`, subprocesses). + +## Pre-Launch Policy +- Prefer secure/simple behavior over compatibility shims. +- Replace incorrect behavior directly unless compatibility path is explicitly approved. + +## Mandatory Quality Gates +```bash +pnpm verify +``` + +## Security Baseline +- Never commit secrets/keys/tokens. +- Avoid logging PII/contact fields. - Keep plugin runtime shell-free. -- Keep API requests authenticated with scoped workspace tokens only. +- Use scoped workspace tokens for API authentication. -## Generated artifacts -- Do not commit generated artifacts (`dist/`, coverage outputs, tarballs). +## References +- `../AGENTS.md` +- Skill: `orbio-openclaw-delivery` +- Skill: `git-worktree-flow`