From 1bba655c421c8384a94fdfb0304f0b6b7139a3c2 Mon Sep 17 00:00:00 2001 From: Simon Paitrault Date: Fri, 10 Apr 2026 13:04:45 +0200 Subject: [PATCH 1/4] docs: adapt AGENTS guidance for interop Replace inherited agglayer-specific references with interop-specific guidance and document the design and execution plan for local skill usage. This keeps repo instructions truthful to the current workspace while preserving the shared operating style. --- AGENTS.md | 72 +++++++ .../2026-04-10-agents-interop-adaptation.md | 177 ++++++++++++++++++ .../specs/2026-04-10-interop-agents-design.md | 153 +++++++++++++++ 3 files changed, 402 insertions(+) create mode 100644 AGENTS.md create mode 100644 docs/superpowers/plans/2026-04-10-agents-interop-adaptation.md create mode 100644 docs/superpowers/specs/2026-04-10-interop-agents-design.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..152daea --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,72 @@ +# AGENTS.md + +## Documentation and skills index + +Key references for navigating this project: + +- `README.md` -- project overview and local development prerequisites. +- `Cargo.toml` -- workspace members, shared dependencies, and repo metadata. +- `crates/` -- implementation crates and crate-local manifests. +- `proto/` -- protobuf contracts and wire-format definitions. +- `scripts/` -- repo automation and helper scripts. +- `Makefile.toml` -- common task entry points. + +## Response priorities + +- Start with high-level recommendations before implementation details. +- Keep recommendations short, opinionated, and tied to tradeoffs. +- If multiple paths exist, present one default path and one fallback. + +## Clarification Before Action + +- If ambiguity can affect correctness, security, scope, or destination path, + ask before acting. +- When unknown terms or domain concepts appear, ask for an explanation + and document them in the repository only when a canonical location exists. +- Low-risk ambiguity in instructions may be assumed: + state one explicit assumption and proceed with the smallest reversible change. +- Ambiguity about technical meaning, domain semantics, or definitions + is never low-risk. Always ask for clarification and document it if necessary. + +## Evidence-Based Debugging and Communication + +- Avoid overconfidence. + Do not present uncertain conclusions as facts. +- State uncertainty explicitly when evidence is incomplete. +- Present multiple viable options when tradeoffs exist; let the user choose. +- Treat root-cause analysis as hypothesis-first until verified. +- Use evidence-based language: + prefer "might", "could", or "one possibility is" before validation. +- Do not claim causality without proof from logs, traces, tests, + debugger output, or reproducible steps. +- Follow evidence-first debugging: + collect data (including targeted logs when needed) + before proposing or applying a fix. + +## Dedicated domain behavior (Interop) + +- Frame recommendations in interop terms: proofs, witnesses, bridge safety, + settlement correctness, and operational reliability. +- Prefer changes that improve safety invariants, wire compatibility, + observability, and rollback clarity over local optimizations. +- Call out likely blast radius across crates, RPC, gRPC, and protobuf + boundaries, serialization formats, and end-to-end flows before proposing + deep refactors. + +## Collaboration norms + +- Confirm assumptions in one sentence when requirements are ambiguous, + then proceed with the safest minimal change. +- Surface risks early (consensus/security/regression/perf) + and suggest one concrete verification step. +- Do not run non-read-only git operations + (e.g., `add`, `rm`, `mv`, `checkout`, `restore`, `commit`, `push`) + without explicit user approval. + Read-only commands (`status`, `diff`, `log`, `show`) are always allowed. +- Repo-local skills, if introduced, live in `.agents/skills/`. +- Express skill dependencies explicitly in prose; do not assume automatic + dependency loading. +- Do not reference required docs or directories in `AGENTS.md` until they + exist. +- Precedence: when rules conflict, + favor the Clarification Before Action section. diff --git a/docs/superpowers/plans/2026-04-10-agents-interop-adaptation.md b/docs/superpowers/plans/2026-04-10-agents-interop-adaptation.md new file mode 100644 index 0000000..307afb5 --- /dev/null +++ b/docs/superpowers/plans/2026-04-10-agents-interop-adaptation.md @@ -0,0 +1,177 @@ +# AGENTS.md Interop Adaptation Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Rewrite `AGENTS.md` so it keeps the `agglayer/agglayer` operating style while becoming fully truthful and repo-specific for `agglayer/interop`. + +**Architecture:** This is a documentation-only change centered on one file, `AGENTS.md`. The work is split by section so each edit has a narrow scope and a matching red/green verification loop using `rg` to prove the old wording is gone and the new wording is present. + +**Tech Stack:** Markdown, `rg`, git (approval-gated by current repo rules) + +--- + +### Task 1: Rewrite The Documentation Index + +**Files:** +- Modify: `AGENTS.md:3-13` +- Test: `AGENTS.md` + +- [ ] **Step 1: Write the failing verification** + +```bash +rg -n 'CONTRIBUTING\.md|docs/knowledge-base|Cargo\.toml|crates/|proto/|scripts/' AGENTS.md +``` + +Expected: matches `CONTRIBUTING.md`, but does not show the new `Cargo.toml`, `crates/`, `proto/`, and `scripts/` anchors in the index section. + +- [ ] **Step 2: Run the verification to confirm the current file fails the target state** + +Run: `rg -n 'CONTRIBUTING\.md|docs/knowledge-base|Cargo\.toml|crates/|proto/|scripts/' AGENTS.md` +Expected: output includes the stale `CONTRIBUTING.md` reference and misses some or all required interop-specific references. + +- [ ] **Step 3: Write the minimal implementation** + +Replace the `Documentation and skills index` section with: + +```markdown +## Documentation and skills index + +Key references for navigating this project: + +- `README.md` -- project overview and local development prerequisites. +- `Cargo.toml` -- workspace members, shared dependencies, and repo metadata. +- `crates/` -- implementation crates and crate-local manifests. +- `proto/` -- protobuf contracts and wire-format definitions. +- `scripts/` -- repo automation and helper scripts. +- `Makefile.toml` -- common task entry points. +``` + +- [ ] **Step 4: Run the verification to confirm the update passes** + +Run: `rg -n 'README\.md|Cargo\.toml|crates/|proto/|scripts/|Makefile\.toml' AGENTS.md` +Expected: all six anchors are present. + +Run: `rg -n 'CONTRIBUTING\.md' AGENTS.md` +Expected: no matches, exit code `1`. + +- [ ] **Step 5: Commit the change if the user approves git writes** + +```bash +git add AGENTS.md +git commit -m "docs: adapt AGENTS references for interop" +``` + + +### Task 2: Rewrite Domain Guidance For Interop Risks + +**Files:** +- Modify: `AGENTS.md:46-53` +- Test: `AGENTS.md` + +- [ ] **Step 1: Write the failing verification** + +```bash +rg -n 'Dedicated domain behavior \(Interop\)|proofs, witnesses, bridge safety|wire compatibility|RPC, gRPC, and protobuf boundaries|serialization formats|end-to-end flows' AGENTS.md +``` + +Expected: no matches, because the file still uses the inherited Agglayer-wide domain wording. + +- [ ] **Step 2: Run the verification to confirm it fails for the expected reason** + +Run: `rg -n 'Dedicated domain behavior \(Interop\)|proofs, witnesses, bridge safety|wire compatibility|RPC, gRPC, and protobuf boundaries|serialization formats|end-to-end flows' AGENTS.md` +Expected: no output and exit code `1`. + +- [ ] **Step 3: Write the minimal implementation** + +Replace the `Dedicated domain behavior (Agglayer)` section with: + +```markdown +## Dedicated domain behavior (Interop) + +- Frame recommendations in interop terms: proofs, witnesses, bridge safety, settlement correctness, and operational reliability. +- Prefer changes that improve safety invariants, wire compatibility, observability, and rollback clarity over local optimizations. +- Call out likely blast radius across crates, RPC, gRPC, and protobuf boundaries, serialization formats, and end-to-end flows before proposing deep refactors. +``` + +- [ ] **Step 4: Run the verification to confirm the rewrite passes** + +Run: `rg -n 'Dedicated domain behavior \(Interop\)|proofs, witnesses, bridge safety|wire compatibility|RPC, gRPC, and protobuf boundaries|serialization formats|end-to-end flows' AGENTS.md` +Expected: matches the new section. + +Run: `rg -n 'Dedicated domain behavior \(Agglayer\)|cross-chain settlement' AGENTS.md` +Expected: no matches, exit code `1`. + +- [ ] **Step 5: Commit the change if the user approves git writes** + +```bash +git add AGENTS.md +git commit -m "docs: focus AGENTS domain guidance on interop" +``` + + +### Task 3: Replace Aspirational Docs Rules With Truthful Skill Rules + +**Files:** +- Modify: `AGENTS.md:55-68` +- Test: `AGENTS.md` + +- [ ] **Step 1: Write the failing verification** + +```bash +rg -n 'All other documentation belongs in `docs/knowledge-base/`|Repo-local skills live in `\.agents/skills/`|automatic dependency loading|Do not reference required docs or directories in `AGENTS\.md` until they exist' AGENTS.md +``` + +Expected: matches the old `docs/knowledge-base` rule, but does not match the new truthful skill and documentation rules. + +- [ ] **Step 2: Run the verification to confirm the gap** + +Run: `rg -n 'All other documentation belongs in `docs/knowledge-base/`|Repo-local skills live in `\.agents/skills/`|automatic dependency loading|Do not reference required docs or directories in `AGENTS\.md` until they exist' AGENTS.md` +Expected: output shows the stale documentation rule and misses the replacement wording. + +- [ ] **Step 3: Write the minimal implementation** + +Update the clarification sentence and replace the bottom of `Collaboration norms` with: + +```markdown +## Clarification Before Action + +- If ambiguity can affect correctness, security, scope, or destination path, + ask before acting. +- When unknown terms or domain concepts appear, ask for an explanation + and document them in the repository only when a canonical location exists. +- Low-risk ambiguity in instructions may be assumed: + state one explicit assumption and proceed with the smallest reversible change. +- Ambiguity about technical meaning, domain semantics, or definitions + is never low-risk. Always ask for clarification and document it if necessary. + +## Collaboration norms + +- Confirm assumptions in one sentence when requirements are ambiguous, + then proceed with the safest minimal change. +- Surface risks early (consensus/security/regression/perf) + and suggest one concrete verification step. +- Do not run non-read-only git operations + (e.g., `add`, `rm`, `mv`, `checkout`, `restore`, `commit`, `push`) + without explicit user approval. + Read-only commands (`status`, `diff`, `log`, `show`) are always allowed. +- Repo-local skills live in `.agents/skills/`. +- Express skill dependencies explicitly in prose; do not assume automatic dependency loading. +- Do not reference required docs or directories in `AGENTS.md` until they exist. +- Precedence: when rules conflict, + favor the Clarification Before Action section. +``` + +- [ ] **Step 4: Run the verification to confirm the new rules pass** + +Run: `rg -n 'Repo-local skills, if introduced, live in `\.agents/skills/`|canonical location exists|dependency loading|Do not reference required docs or directories in `AGENTS\.md` until they exist' AGENTS.md` +Expected: matches the updated clarification rule and all three new collaboration rules. + +Run: `rg -n 'All other documentation belongs in `docs/knowledge-base/`' AGENTS.md` +Expected: no matches, exit code `1`. + +- [ ] **Step 5: Commit the change if the user approves git writes** + +```bash +git add AGENTS.md +git commit -m "docs: clarify local skills and docs rules" +``` diff --git a/docs/superpowers/specs/2026-04-10-interop-agents-design.md b/docs/superpowers/specs/2026-04-10-interop-agents-design.md new file mode 100644 index 0000000..b35b8b1 --- /dev/null +++ b/docs/superpowers/specs/2026-04-10-interop-agents-design.md @@ -0,0 +1,153 @@ +## Purpose + +Adapt the inherited `AGENTS.md` from `agglayer/agglayer` into a truthful, reusable operating contract for `agglayer/interop`, while preserving the source repo's standard style and engineering discipline. + +## Current Repo Context + +- `interop` currently has `README.md`, `Cargo.toml`, `Makefile.toml`, `crates/`, `proto/`, and `scripts/`. +- `CONTRIBUTING.md`, `docs/knowledge-base/`, and `.agents/skills/` do not currently exist in this repo. +- `docs/superpowers/specs/` was created for this design doc and should not be treated as proof that a broader repo documentation structure already exists. +- The current `AGENTS.md` references several of those missing paths, so it is partially aspirational rather than fully accurate. + +## Goals + +- Keep the overall style and operating model inspired by `agglayer/agglayer`. +- Remove or rewrite statements that are false for `interop` today. +- Preserve high-signal collaboration guidance around ambiguity, debugging, safety, and git operations. +- Introduce a standard place for repo-local skills without overpromising tool support that may not exist. + +## Non-Goals + +- Do not redesign the entire repository workflow. +- Do not create placeholder docs just to satisfy inherited references. +- Do not define automatic skill-loading or dependency metadata unless the tooling is verified to support it. + +## Recommended Approach + +Use a mirror-with-adaptation strategy: + +- Preserve the section structure and tone from `agglayer/agglayer` where it still fits. +- Rewrite repo references and domain language so each rule is true for `interop`. +- Prefer explicit, enforceable instructions over aspirational documentation layout. + +This keeps a standard way of working across repos without copying assumptions from the larger `agglayer/agglayer` node-oriented codebase. + +## Section-by-Section Decisions + +### Keep Mostly As-Is + +- `Response priorities` +- `Clarification Before Action` +- `Evidence-Based Debugging and Communication` +- The git-safety parts of `Collaboration norms` + +These sections already fit protocol-heavy and safety-sensitive work in `interop`. + +### Rewrite + +#### `Documentation and skills index` + +Replace inherited references with paths that exist and matter in `interop`: + +- `README.md` for repo overview +- `Cargo.toml` for workspace layout and shared dependencies +- `crates/` for crate-level implementation work +- `proto/` for protobuf contracts +- `scripts/` for repo automation +- `Makefile.toml` for common task entry points + +Optional additions if useful: + +- `.github/workflows/` for CI conventions +- crate-specific `README.md` files if they are added later + +#### `Dedicated domain behavior` + +Rename to `Dedicated domain behavior (Interop)` and refocus guidance around the actual risks in this repo: + +- proof and witness correctness +- bridge and settlement safety +- RPC, gRPC, and protobuf boundary compatibility +- serialization compatibility across bincode, serde, and wire formats +- blast radius across shared crates and end-to-end flows + +The language should avoid assuming the full `agglayer/agglayer` node, orchestrator, epoch, or prover deployment architecture unless a rule truly applies here. + +### Remove + +Remove or replace references that are currently false: + +- `CONTRIBUTING.md` +- `docs/` +- `docs/knowledge-base/` +- The rule that all non-skill documentation belongs in `docs/knowledge-base/` + +These can be reintroduced later if the directories are actually created and adopted. + +## Proposed Final Structure + +1. `Documentation and skills index` +2. `Response priorities` +3. `Clarification Before Action` +4. `Evidence-Based Debugging and Communication` +5. `Dedicated domain behavior (Interop)` +6. `Collaboration norms` + +## Repo-Local Skills Standard + +The repo can define local skills inside: + +`.agents/skills//SKILL.md` + +Recommended standard: + +- `AGENTS.md` may require repo-local skills for repo-specific workflows. +- Repo-local skills may explicitly name required background skills. +- Repo-local skills may explicitly name required next skills. + +Example patterns: + +- "Before changing protocol behavior, invoke `brainstorming` and any applicable repo-local interop skill." +- "REQUIRED BACKGROUND: use `test-driven-development`." +- "After completing the change, use `verification-before-completion`." + +## Skill Dependency Model + +The recommended dependency model is explicit composition in prose, not automatic dependency resolution. + +Supported by design: + +- `AGENTS.md` requiring a skill before a class of tasks +- A local skill requiring another skill before or after execution +- A local skill documenting related skills that should be used together + +Not assumed without tool verification: + +- declarative dependency metadata that auto-loads other skills +- hidden or transitive dependency resolution +- guaranteed ordered loading from repo-local skill manifests + +This keeps the standard portable across tools and avoids encoding behavior the runtime may not implement. + +## Recommended Wording Changes + +- Keep the source-repo inspiration visible in tone, not in inaccurate repo references. +- Use `interop`-specific crate and protocol examples instead of `agglayer` node/orchestrator examples. +- State only rules that can be followed immediately in this repo. +- Avoid requiring future directories until they exist. + +## Risks and Tradeoffs + +- Keeping too much inherited wording will make `AGENTS.md` look authoritative while silently pointing to missing structures. +- Making the file too minimal would lose the standardization goal and reduce cross-repo consistency. +- Defining skill dependencies as prose is less automated, but it is safer than relying on unverified tool features. + +## Follow-Up Recommendations + +- Rewrite `AGENTS.md` now using the structure above. +- Create `.agents/skills/` only when the first repo-local skill is ready to be added. +- If the repo later adopts a documentation tree, update `AGENTS.md` only after the location is created and agreed upon. + +## Constraint Note + +The brainstorming workflow normally calls for committing the design doc. This repo's current `AGENTS.md` forbids non-read-only git operations without explicit user approval, so the spec should be written first and committed only if the user requests or approves that step. From abb275be370a6d834eb3781f27187cacd52bd3d1 Mon Sep 17 00:00:00 2001 From: Simon Paitrault Date: Fri, 10 Apr 2026 13:42:18 +0200 Subject: [PATCH 2/4] docs: remove temporary planning artifacts --- .../2026-04-10-agents-interop-adaptation.md | 177 ------------------ .../specs/2026-04-10-interop-agents-design.md | 153 --------------- 2 files changed, 330 deletions(-) delete mode 100644 docs/superpowers/plans/2026-04-10-agents-interop-adaptation.md delete mode 100644 docs/superpowers/specs/2026-04-10-interop-agents-design.md diff --git a/docs/superpowers/plans/2026-04-10-agents-interop-adaptation.md b/docs/superpowers/plans/2026-04-10-agents-interop-adaptation.md deleted file mode 100644 index 307afb5..0000000 --- a/docs/superpowers/plans/2026-04-10-agents-interop-adaptation.md +++ /dev/null @@ -1,177 +0,0 @@ -# AGENTS.md Interop Adaptation Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Rewrite `AGENTS.md` so it keeps the `agglayer/agglayer` operating style while becoming fully truthful and repo-specific for `agglayer/interop`. - -**Architecture:** This is a documentation-only change centered on one file, `AGENTS.md`. The work is split by section so each edit has a narrow scope and a matching red/green verification loop using `rg` to prove the old wording is gone and the new wording is present. - -**Tech Stack:** Markdown, `rg`, git (approval-gated by current repo rules) - ---- - -### Task 1: Rewrite The Documentation Index - -**Files:** -- Modify: `AGENTS.md:3-13` -- Test: `AGENTS.md` - -- [ ] **Step 1: Write the failing verification** - -```bash -rg -n 'CONTRIBUTING\.md|docs/knowledge-base|Cargo\.toml|crates/|proto/|scripts/' AGENTS.md -``` - -Expected: matches `CONTRIBUTING.md`, but does not show the new `Cargo.toml`, `crates/`, `proto/`, and `scripts/` anchors in the index section. - -- [ ] **Step 2: Run the verification to confirm the current file fails the target state** - -Run: `rg -n 'CONTRIBUTING\.md|docs/knowledge-base|Cargo\.toml|crates/|proto/|scripts/' AGENTS.md` -Expected: output includes the stale `CONTRIBUTING.md` reference and misses some or all required interop-specific references. - -- [ ] **Step 3: Write the minimal implementation** - -Replace the `Documentation and skills index` section with: - -```markdown -## Documentation and skills index - -Key references for navigating this project: - -- `README.md` -- project overview and local development prerequisites. -- `Cargo.toml` -- workspace members, shared dependencies, and repo metadata. -- `crates/` -- implementation crates and crate-local manifests. -- `proto/` -- protobuf contracts and wire-format definitions. -- `scripts/` -- repo automation and helper scripts. -- `Makefile.toml` -- common task entry points. -``` - -- [ ] **Step 4: Run the verification to confirm the update passes** - -Run: `rg -n 'README\.md|Cargo\.toml|crates/|proto/|scripts/|Makefile\.toml' AGENTS.md` -Expected: all six anchors are present. - -Run: `rg -n 'CONTRIBUTING\.md' AGENTS.md` -Expected: no matches, exit code `1`. - -- [ ] **Step 5: Commit the change if the user approves git writes** - -```bash -git add AGENTS.md -git commit -m "docs: adapt AGENTS references for interop" -``` - - -### Task 2: Rewrite Domain Guidance For Interop Risks - -**Files:** -- Modify: `AGENTS.md:46-53` -- Test: `AGENTS.md` - -- [ ] **Step 1: Write the failing verification** - -```bash -rg -n 'Dedicated domain behavior \(Interop\)|proofs, witnesses, bridge safety|wire compatibility|RPC, gRPC, and protobuf boundaries|serialization formats|end-to-end flows' AGENTS.md -``` - -Expected: no matches, because the file still uses the inherited Agglayer-wide domain wording. - -- [ ] **Step 2: Run the verification to confirm it fails for the expected reason** - -Run: `rg -n 'Dedicated domain behavior \(Interop\)|proofs, witnesses, bridge safety|wire compatibility|RPC, gRPC, and protobuf boundaries|serialization formats|end-to-end flows' AGENTS.md` -Expected: no output and exit code `1`. - -- [ ] **Step 3: Write the minimal implementation** - -Replace the `Dedicated domain behavior (Agglayer)` section with: - -```markdown -## Dedicated domain behavior (Interop) - -- Frame recommendations in interop terms: proofs, witnesses, bridge safety, settlement correctness, and operational reliability. -- Prefer changes that improve safety invariants, wire compatibility, observability, and rollback clarity over local optimizations. -- Call out likely blast radius across crates, RPC, gRPC, and protobuf boundaries, serialization formats, and end-to-end flows before proposing deep refactors. -``` - -- [ ] **Step 4: Run the verification to confirm the rewrite passes** - -Run: `rg -n 'Dedicated domain behavior \(Interop\)|proofs, witnesses, bridge safety|wire compatibility|RPC, gRPC, and protobuf boundaries|serialization formats|end-to-end flows' AGENTS.md` -Expected: matches the new section. - -Run: `rg -n 'Dedicated domain behavior \(Agglayer\)|cross-chain settlement' AGENTS.md` -Expected: no matches, exit code `1`. - -- [ ] **Step 5: Commit the change if the user approves git writes** - -```bash -git add AGENTS.md -git commit -m "docs: focus AGENTS domain guidance on interop" -``` - - -### Task 3: Replace Aspirational Docs Rules With Truthful Skill Rules - -**Files:** -- Modify: `AGENTS.md:55-68` -- Test: `AGENTS.md` - -- [ ] **Step 1: Write the failing verification** - -```bash -rg -n 'All other documentation belongs in `docs/knowledge-base/`|Repo-local skills live in `\.agents/skills/`|automatic dependency loading|Do not reference required docs or directories in `AGENTS\.md` until they exist' AGENTS.md -``` - -Expected: matches the old `docs/knowledge-base` rule, but does not match the new truthful skill and documentation rules. - -- [ ] **Step 2: Run the verification to confirm the gap** - -Run: `rg -n 'All other documentation belongs in `docs/knowledge-base/`|Repo-local skills live in `\.agents/skills/`|automatic dependency loading|Do not reference required docs or directories in `AGENTS\.md` until they exist' AGENTS.md` -Expected: output shows the stale documentation rule and misses the replacement wording. - -- [ ] **Step 3: Write the minimal implementation** - -Update the clarification sentence and replace the bottom of `Collaboration norms` with: - -```markdown -## Clarification Before Action - -- If ambiguity can affect correctness, security, scope, or destination path, - ask before acting. -- When unknown terms or domain concepts appear, ask for an explanation - and document them in the repository only when a canonical location exists. -- Low-risk ambiguity in instructions may be assumed: - state one explicit assumption and proceed with the smallest reversible change. -- Ambiguity about technical meaning, domain semantics, or definitions - is never low-risk. Always ask for clarification and document it if necessary. - -## Collaboration norms - -- Confirm assumptions in one sentence when requirements are ambiguous, - then proceed with the safest minimal change. -- Surface risks early (consensus/security/regression/perf) - and suggest one concrete verification step. -- Do not run non-read-only git operations - (e.g., `add`, `rm`, `mv`, `checkout`, `restore`, `commit`, `push`) - without explicit user approval. - Read-only commands (`status`, `diff`, `log`, `show`) are always allowed. -- Repo-local skills live in `.agents/skills/`. -- Express skill dependencies explicitly in prose; do not assume automatic dependency loading. -- Do not reference required docs or directories in `AGENTS.md` until they exist. -- Precedence: when rules conflict, - favor the Clarification Before Action section. -``` - -- [ ] **Step 4: Run the verification to confirm the new rules pass** - -Run: `rg -n 'Repo-local skills, if introduced, live in `\.agents/skills/`|canonical location exists|dependency loading|Do not reference required docs or directories in `AGENTS\.md` until they exist' AGENTS.md` -Expected: matches the updated clarification rule and all three new collaboration rules. - -Run: `rg -n 'All other documentation belongs in `docs/knowledge-base/`' AGENTS.md` -Expected: no matches, exit code `1`. - -- [ ] **Step 5: Commit the change if the user approves git writes** - -```bash -git add AGENTS.md -git commit -m "docs: clarify local skills and docs rules" -``` diff --git a/docs/superpowers/specs/2026-04-10-interop-agents-design.md b/docs/superpowers/specs/2026-04-10-interop-agents-design.md deleted file mode 100644 index b35b8b1..0000000 --- a/docs/superpowers/specs/2026-04-10-interop-agents-design.md +++ /dev/null @@ -1,153 +0,0 @@ -## Purpose - -Adapt the inherited `AGENTS.md` from `agglayer/agglayer` into a truthful, reusable operating contract for `agglayer/interop`, while preserving the source repo's standard style and engineering discipline. - -## Current Repo Context - -- `interop` currently has `README.md`, `Cargo.toml`, `Makefile.toml`, `crates/`, `proto/`, and `scripts/`. -- `CONTRIBUTING.md`, `docs/knowledge-base/`, and `.agents/skills/` do not currently exist in this repo. -- `docs/superpowers/specs/` was created for this design doc and should not be treated as proof that a broader repo documentation structure already exists. -- The current `AGENTS.md` references several of those missing paths, so it is partially aspirational rather than fully accurate. - -## Goals - -- Keep the overall style and operating model inspired by `agglayer/agglayer`. -- Remove or rewrite statements that are false for `interop` today. -- Preserve high-signal collaboration guidance around ambiguity, debugging, safety, and git operations. -- Introduce a standard place for repo-local skills without overpromising tool support that may not exist. - -## Non-Goals - -- Do not redesign the entire repository workflow. -- Do not create placeholder docs just to satisfy inherited references. -- Do not define automatic skill-loading or dependency metadata unless the tooling is verified to support it. - -## Recommended Approach - -Use a mirror-with-adaptation strategy: - -- Preserve the section structure and tone from `agglayer/agglayer` where it still fits. -- Rewrite repo references and domain language so each rule is true for `interop`. -- Prefer explicit, enforceable instructions over aspirational documentation layout. - -This keeps a standard way of working across repos without copying assumptions from the larger `agglayer/agglayer` node-oriented codebase. - -## Section-by-Section Decisions - -### Keep Mostly As-Is - -- `Response priorities` -- `Clarification Before Action` -- `Evidence-Based Debugging and Communication` -- The git-safety parts of `Collaboration norms` - -These sections already fit protocol-heavy and safety-sensitive work in `interop`. - -### Rewrite - -#### `Documentation and skills index` - -Replace inherited references with paths that exist and matter in `interop`: - -- `README.md` for repo overview -- `Cargo.toml` for workspace layout and shared dependencies -- `crates/` for crate-level implementation work -- `proto/` for protobuf contracts -- `scripts/` for repo automation -- `Makefile.toml` for common task entry points - -Optional additions if useful: - -- `.github/workflows/` for CI conventions -- crate-specific `README.md` files if they are added later - -#### `Dedicated domain behavior` - -Rename to `Dedicated domain behavior (Interop)` and refocus guidance around the actual risks in this repo: - -- proof and witness correctness -- bridge and settlement safety -- RPC, gRPC, and protobuf boundary compatibility -- serialization compatibility across bincode, serde, and wire formats -- blast radius across shared crates and end-to-end flows - -The language should avoid assuming the full `agglayer/agglayer` node, orchestrator, epoch, or prover deployment architecture unless a rule truly applies here. - -### Remove - -Remove or replace references that are currently false: - -- `CONTRIBUTING.md` -- `docs/` -- `docs/knowledge-base/` -- The rule that all non-skill documentation belongs in `docs/knowledge-base/` - -These can be reintroduced later if the directories are actually created and adopted. - -## Proposed Final Structure - -1. `Documentation and skills index` -2. `Response priorities` -3. `Clarification Before Action` -4. `Evidence-Based Debugging and Communication` -5. `Dedicated domain behavior (Interop)` -6. `Collaboration norms` - -## Repo-Local Skills Standard - -The repo can define local skills inside: - -`.agents/skills//SKILL.md` - -Recommended standard: - -- `AGENTS.md` may require repo-local skills for repo-specific workflows. -- Repo-local skills may explicitly name required background skills. -- Repo-local skills may explicitly name required next skills. - -Example patterns: - -- "Before changing protocol behavior, invoke `brainstorming` and any applicable repo-local interop skill." -- "REQUIRED BACKGROUND: use `test-driven-development`." -- "After completing the change, use `verification-before-completion`." - -## Skill Dependency Model - -The recommended dependency model is explicit composition in prose, not automatic dependency resolution. - -Supported by design: - -- `AGENTS.md` requiring a skill before a class of tasks -- A local skill requiring another skill before or after execution -- A local skill documenting related skills that should be used together - -Not assumed without tool verification: - -- declarative dependency metadata that auto-loads other skills -- hidden or transitive dependency resolution -- guaranteed ordered loading from repo-local skill manifests - -This keeps the standard portable across tools and avoids encoding behavior the runtime may not implement. - -## Recommended Wording Changes - -- Keep the source-repo inspiration visible in tone, not in inaccurate repo references. -- Use `interop`-specific crate and protocol examples instead of `agglayer` node/orchestrator examples. -- State only rules that can be followed immediately in this repo. -- Avoid requiring future directories until they exist. - -## Risks and Tradeoffs - -- Keeping too much inherited wording will make `AGENTS.md` look authoritative while silently pointing to missing structures. -- Making the file too minimal would lose the standardization goal and reduce cross-repo consistency. -- Defining skill dependencies as prose is less automated, but it is safer than relying on unverified tool features. - -## Follow-Up Recommendations - -- Rewrite `AGENTS.md` now using the structure above. -- Create `.agents/skills/` only when the first repo-local skill is ready to be added. -- If the repo later adopts a documentation tree, update `AGENTS.md` only after the location is created and agreed upon. - -## Constraint Note - -The brainstorming workflow normally calls for committing the design doc. This repo's current `AGENTS.md` forbids non-read-only git operations without explicit user approval, so the spec should be written first and committed only if the user requests or approves that step. From 1906d317fea230be7838b2b3a7f26f94ceb12ec7 Mon Sep 17 00:00:00 2001 From: Simon Paitrault Date: Fri, 10 Apr 2026 17:28:51 +0200 Subject: [PATCH 3/4] docs: require agglayer-ai-skills plugin Make the repository policy explicit that agents should only proceed with agglayer-ai-skills available and must stop to ask if the plugin or required skills are missing. --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 152daea..4e31e21 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,6 +66,10 @@ Key references for navigating this project: - Repo-local skills, if introduced, live in `.agents/skills/`. - Express skill dependencies explicitly in prose; do not assume automatic dependency loading. +- `agglayer-ai-skills` must be installed for work in this repository. +- If the plugin or its required skills are unavailable, stop and ask the user + to install or enable it before proceeding. +- Do not continue with fallback behavior when the required plugin is missing. - Do not reference required docs or directories in `AGENTS.md` until they exist. - Precedence: when rules conflict, From 1cdb01bb10154cc579ff553e933c9361ef66de1c Mon Sep 17 00:00:00 2001 From: Simon Paitrault Date: Sat, 11 Apr 2026 09:04:24 +0200 Subject: [PATCH 4/4] docs: strengthen agglayer-ai-skills gate Make plugin availability a hard precondition before repository work and carve the availability check out of the normal clarification precedence so agents fail closed when required task skills are missing. --- AGENTS.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4e31e21..7934942 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,11 +66,10 @@ Key references for navigating this project: - Repo-local skills, if introduced, live in `.agents/skills/`. - Express skill dependencies explicitly in prose; do not assume automatic dependency loading. -- `agglayer-ai-skills` must be installed for work in this repository. -- If the plugin or its required skills are unavailable, stop and ask the user - to install or enable it before proceeding. -- Do not continue with fallback behavior when the required plugin is missing. +- `agglayer-ai-skills` must be installed and enabled so its required task skills can be loaded in the current session before doing any work in this repository. +- If the plugin or the skills required for the current task are unavailable, stop immediately and ask the user to install or enable them before any further clarification, planning, or repository exploration. +- This availability gate takes precedence over the `Clarification Before Action` section. Do not proceed until the plugin and task-required skills are available. - Do not reference required docs or directories in `AGENTS.md` until they exist. - Precedence: when rules conflict, - favor the Clarification Before Action section. + favor the Clarification Before Action section, except for the `agglayer-ai-skills` availability gate above.