-
Notifications
You must be signed in to change notification settings - Fork 1.3k
feat: Add A2Z non-negotiable contract rules to CLAUDE.md #89
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -1,3 +1,72 @@ | ||||||||||||||||
| # Non-Negotiables (A2Z Contract) | ||||||||||||||||
|
|
||||||||||||||||
| ## Autonomy and approval | ||||||||||||||||
| - The agent operates autonomously during planning, development, and testing. | ||||||||||||||||
| - The agent MUST ask for explicit user approval before: | ||||||||||||||||
| - Any purchase or enabling a paid plan, OR | ||||||||||||||||
| - Any action that is likely to exceed $50 (one-time or monthly), OR | ||||||||||||||||
| - Any irreversible/destructive operation (deletes, terminations, drops, key deletions), OR | ||||||||||||||||
| - Any production change (prod deploy, prod DNS, prod DB writes). | ||||||||||||||||
| - If cost is uncertain, assume it may exceed $50 and ask first. | ||||||||||||||||
|
|
||||||||||||||||
| ## Isolation (mandatory for every mission) | ||||||||||||||||
| - Every mission MUST run in an isolated environment: | ||||||||||||||||
| - A dedicated git branch and git worktree per mission (no work directly on main). | ||||||||||||||||
| - A dedicated dev/staging namespace for cloud resources (never reuse existing prod resources). | ||||||||||||||||
| - A dedicated data plane for new data (new DB preferred). | ||||||||||||||||
| - Naming + tagging for all newly created cloud resources: | ||||||||||||||||
| - Names MUST start with: `a2z-<mission-slug>-...` | ||||||||||||||||
| - AWS tags MUST include: | ||||||||||||||||
| - `a2z:managed = true` | ||||||||||||||||
| - `a2z:mission = <mission-slug>` | ||||||||||||||||
| - `a2z:env = dev` | ||||||||||||||||
| - The agent MUST NOT mutate any existing (non-A2Z) resources except the explicitly allowlisted existing resources described below. | ||||||||||||||||
|
|
||||||||||||||||
| ## Existing resources access (allowlist only) | ||||||||||||||||
| - The agent may access ONLY the explicitly allowlisted existing resources that the user has approved. | ||||||||||||||||
| - For any other existing resources (Lambdas, S3 buckets, databases, IAM, etc.), the agent must behave as if it has no access and MUST NOT attempt to modify or depend on them. | ||||||||||||||||
|
|
||||||||||||||||
| ## Database safety (critical) | ||||||||||||||||
| - Existing databases are READ-ONLY. | ||||||||||||||||
| - The agent MAY read existing DBs only using read-only credentials. | ||||||||||||||||
| - The agent MUST NOT modify existing database tables/rows or run destructive DDL/DML against existing DBs (including but not limited to: DROP, TRUNCATE, DELETE, UPDATE, ALTER). | ||||||||||||||||
| - New project data MUST be written only to: | ||||||||||||||||
| - A NEW database created for the project (preferred), OR | ||||||||||||||||
| - A NEW schema explicitly approved by the user. | ||||||||||||||||
| - Any migration/reset commands that could drop data (e.g., “reset”, “flush”, “dropAll”) require explicit user approval. | ||||||||||||||||
|
|
||||||||||||||||
| ## Security and secrets | ||||||||||||||||
| - Least privilege everywhere (MCP tokens, AWS IAM, Cloudflare tokens, WordPress access, Jira/monday scopes). | ||||||||||||||||
| - Never print secrets to logs or console output. | ||||||||||||||||
| - Never commit secrets. `.env` files must not be committed. | ||||||||||||||||
| - Use managed secret stores where applicable (e.g., AWS Secrets Manager) and inject secrets via environment variables at runtime. | ||||||||||||||||
| - All external inputs must be validated; error messages must not leak sensitive data. | ||||||||||||||||
|
|
||||||||||||||||
| ## Quality bars (must satisfy) | ||||||||||||||||
| - Scalability: prefer stateless services and horizontally scalable architectures. | ||||||||||||||||
| - Availability: timeouts, retries, health checks; graceful degradation. | ||||||||||||||||
| - Cost: default to free-tier / serverless / local emulation; avoid heavy managed services unless explicitly justified. | ||||||||||||||||
| - Performance: avoid obvious inefficiencies; measure where relevant. | ||||||||||||||||
| - UX/UI: accessible, consistent, minimal steps for core user journeys. | ||||||||||||||||
| - Testing: add appropriate automated tests; tests must be green before declaring done. | ||||||||||||||||
|
|
||||||||||||||||
| ## Execution contract (OpenSpec) | ||||||||||||||||
| - No implementation begins until an OpenSpec change exists and is validated: | ||||||||||||||||
| - `openspec/changes/<change-id>/proposal.md` | ||||||||||||||||
| - `openspec/changes/<change-id>/tasks.md` | ||||||||||||||||
| - Implementation must map to `tasks.md` items. | ||||||||||||||||
| - A change is not “done” until it is archived and specs represent the new truth: | ||||||||||||||||
| - `openspec archive <change-id> --yes` | ||||||||||||||||
|
Comment on lines
+53
to
+59
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. references |
||||||||||||||||
|
|
||||||||||||||||
| ## WordPress.com MCP limitation | ||||||||||||||||
| - WordPress.com MCP access is read-only; it may be used for context retrieval only. | ||||||||||||||||
| - Publishing/editing content requires an explicitly approved, separate write mechanism (not MCP). | ||||||||||||||||
|
|
||||||||||||||||
| You MUST also read: | ||||||||||||||||
| - openspec/project.md | ||||||||||||||||
| - CLAUDE.md (repo root) | ||||||||||||||||
| and follow all constraints within. | ||||||||||||||||
|
Comment on lines
+65
to
+68
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. circular reference - instructs to read
Suggested change
|
||||||||||||||||
|
|
||||||||||||||||
| # Ralph Agent Instructions | ||||||||||||||||
|
|
||||||||||||||||
| You are an autonomous coding agent working on a software project. | ||||||||||||||||
|
|
||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
check that these A2Z contract rules (AWS resources, cloud infrastructure, mission-based isolation) align with Ralph's purpose as a local autonomous coding agent
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!