CLAUDE.md

CLAUDE.md — ZeroBuild Engineering Protocol

This file defines the default working protocol for Claude agents in this repository. Scope: entire repository.

1) Project Snapshot (Read First)

This repository is ZeroBuild — the Autonomous Software Factory. Build and host your own AI-powered software development system, forked from ZeroClaw. See AGENTS.md for ZeroBuild-specific rules.

ZeroBuild is a hierarchical multi-agent system that automates the entire software development lifecycle:

• Orchestrator (CEO) — Receives user ideas, analyzes feasibility, spawns specialized sub-agents, coordinates phased execution, and reports progress.
• Specialized Sub-Agents (BA, UI/UX, Developer, Tester, DevOps) — Each operates with dedicated context and permissions, collaborating through a shared blackboard to deliver production-ready software.
• Single-agent mode (default) — One unified agent handles the full workflow for simpler tasks.
• Factory mode (opt-in) — The Orchestrator spawns the full AI team for complex projects.

ZeroBuild (the underlying runtime) is a Rust-first autonomous agent runtime optimized for:

• high performance
• high efficiency
• high stability
• high extensibility
• high sustainability
• high security

Core architecture is trait-driven and modular. Most extension work should be done by implementing traits and registering in factory modules.

Key ZeroBuild extension points:

• src/providers/traits.rs (Provider)
• src/channels/traits.rs (Channel)
• src/tools/traits.rs (Tool)
• src/memory/traits.rs (Memory)
• src/observability/traits.rs (Observer)
• src/runtime/traits.rs (RuntimeAdapter)
• src/peripherals/traits.rs (Peripheral) — hardware boards (STM32, RPi GPIO)

Key ZeroBuild extension points:

• src/tools/sandbox/ — sandbox tools (create, run, write, read, list, preview, public-url, snapshot, restore, kill)
• src/tools/deploy.rs — request_deploy tool (GitHub push)
• src/tools/github_ops.rs — GitHub ops tools (create/edit/close/comment on issues, PRs, reviews, inline comments)
• src/onboard/wizard.rs — onboarding wizard with auto-configured fallback providers
• src/gateway/api.rs — /internal/notify endpoint
• src/gateway/oauth.rs — GitHub OAuth flow
• IDENTITY.md — ZeroBuild user-facing persona definition

2) Deep Architecture Observations (Why This Protocol Exists)

These codebase realities should drive every design decision:

1. Trait + factory architecture is the stability backbone
   • Extension points are intentionally explicit and swappable.
   • Most features should be added via trait implementation + factory registration, not cross-cutting rewrites.
2. Security-critical surfaces are first-class and internet-adjacent
   • src/gateway/, src/security/, src/tools/, src/runtime/ carry high blast radius.
   • Defaults already lean secure-by-default (pairing, bind safety, limits, secret handling); keep it that way.
3. Performance and binary size are product goals, not nice-to-have
   • Cargo.toml release profile and dependency choices optimize for size and determinism.
   • Convenience dependencies and broad abstractions can silently regress these goals.
4. Config and runtime contracts are user-facing API
   • src/config/schema.rs and CLI commands are effectively public interfaces.
   • Backward compatibility and explicit migration matter.
5. The project now runs in high-concurrency collaboration mode
   • CI + docs governance + label routing are part of the product delivery system.
   • PR throughput is a design constraint; not just a maintainer inconvenience.

3) Engineering Principles (Normative)

These principles are mandatory by default. They are not slogans; they are implementation constraints.

3.1 KISS (Keep It Simple, Stupid)

Why here: Runtime + security behavior must stay auditable under pressure.

Required:

• Prefer straightforward control flow over clever meta-programming.
• Prefer explicit match branches and typed structs over hidden dynamic behavior.
• Keep error paths obvious and localized.

3.2 YAGNI (You Aren't Gonna Need It)

Why here: Premature features increase attack surface and maintenance burden.

Required:

• Do not add new config keys, trait methods, feature flags, or workflow branches without a concrete accepted use case.
• Do not introduce speculative “future-proof” abstractions without at least one current caller.
• Keep unsupported paths explicit (error out) rather than adding partial fake support.

3.3 DRY + Rule of Three

Why here: Naive DRY can create brittle shared abstractions across providers/channels/tools.

Required:

• Duplicate small, local logic when it preserves clarity.
• Extract shared utilities only after repeated, stable patterns (rule-of-three).
• When extracting, preserve module boundaries and avoid hidden coupling.

3.4 SRP + ISP (Single Responsibility + Interface Segregation)

Why here: Trait-driven architecture already encodes subsystem boundaries.

Required:

• Keep each module focused on one concern.
• Extend behavior by implementing existing narrow traits whenever possible.
• Avoid fat interfaces and “god modules” that mix policy + transport + storage.

3.5 Fail Fast + Explicit Errors

Why here: Silent fallback in agent runtimes can create unsafe or costly behavior.

Required:

• Prefer explicit bail!/errors for unsupported or unsafe states.
• Never silently broaden permissions/capabilities.
• Document fallback behavior when fallback is intentional and safe.

3.6 Secure by Default + Least Privilege

Why here: Gateway/tools/runtime can execute actions with real-world side effects.

Required:

• Deny-by-default for access and exposure boundaries.
• Never log secrets, raw tokens, or sensitive payloads.
• Keep network/filesystem/shell scope as narrow as possible unless explicitly justified.

3.7 Determinism + Reproducibility

Why here: Reliable CI and low-latency triage depend on deterministic behavior.

Required:

• Prefer reproducible commands and locked dependency behavior in CI-sensitive paths.
• Keep tests deterministic (no flaky timing/network dependence without guardrails).
• Ensure local validation commands map to CI expectations.

3.8 Reversibility + Rollback-First Thinking

Why here: Fast recovery is mandatory under high PR volume.

Required:

• Keep changes easy to revert (small scope, clear blast radius).
• For risky changes, define rollback path before merge.
• Avoid mixed mega-patches that block safe rollback.

4) Repository Map (High-Level)

Rust (ZeroBuild Agent runtime)

• src/main.rs — CLI entrypoint and command routing
• src/lib.rs — module exports and shared command enums
• src/config/ — schema + config loading/merging
• src/agent/ — orchestration loop
• src/gateway/ — webhook/gateway server + /internal/notify endpoint
• src/security/ — policy, pairing, secret store
• src/memory/ — markdown/sqlite memory backends + embeddings/vector merge
• src/providers/ — model providers and resilient wrapper
• src/channels/ — channel implementations (Telegram, Discord, Slack, and others via Channel trait)
• src/tools/ — tool execution surface (shell, file, memory, browser, zerobuild_*)
• src/peripherals/ — hardware peripherals (STM32, RPi GPIO); see docs/hardware-peripherals-design.md
• src/factory/ — multi-agent factory (roles, blackboard, workflow, orchestrator tool)
• src/runtime/ — runtime adapters (currently native)
• docs/ — task-oriented documentation system
• .github/ — CI, templates, automation workflows
• IDENTITY.md — ZeroBuild user-facing persona

Key ZeroBuild Agent modules

• src/agent/ — orchestration loop
• src/tools/sandbox/ — sandbox tools (create, run, write, read, list, preview, public-url, snapshot, restore, kill)
• src/tools/deploy.rs — request_deploy tool (GitHub push via git trees API)
• src/tools/github_ops.rs — GitHub ops tools
• src/gateway/oauth.rs — GitHub OAuth handlers
• src/store/ — SQLite persistence (sandbox session, project snapshots, GitHub token)
• src/factory/ — multi-agent factory workflow (roles, blackboard, workflow orchestrator, factory_build tool)

4.1 Documentation System Contract (Required)

Treat documentation as a first-class product surface, not a post-merge artifact.

Canonical entry points:

• root READMEs: README.md, README.zh-CN.md, README.ja.md, README.ru.md, README.fr.md, README.vi.md
• docs hubs: docs/README.md, docs/README.zh-CN.md, docs/README.ja.md, docs/README.ru.md, docs/README.fr.md, docs/i18n/vi/README.md
• unified TOC: docs/SUMMARY.md

Supported locales (current contract):

• en, zh-CN, ja, ru, fr, vi

Collection indexes (category navigation):

• docs/getting-started/README.md
• docs/reference/README.md
• docs/operations/README.md
• docs/security/README.md
• docs/hardware/README.md
• docs/contributing/README.md
• docs/project/README.md

Runtime-contract references (must track behavior changes):

• docs/commands-reference.md
• docs/providers-reference.md
• docs/channels-reference.md
• docs/config-reference.md
• docs/operations-runbook.md
• docs/troubleshooting.md
• docs/one-click-bootstrap.md

Required docs governance rules:

• Keep README/hub top navigation and quick routes intuitive and non-duplicative.
• Keep entry-point parity across all supported locales (en, zh-CN, ja, ru, fr, vi) when changing navigation architecture.
• If a change touches docs IA, runtime-contract references, or user-facing wording in shared docs, perform i18n follow-through for currently supported locales in the same PR:
  • Update locale navigation links (README*, docs/README*, docs/SUMMARY.md).
  • Update localized runtime-contract docs where equivalents exist (at minimum commands-reference, config-reference, troubleshooting for fr and vi).
  • For Vietnamese, treat docs/i18n/vi/** as canonical. Keep docs/*.<locale>.md compatibility shims aligned if present.
• Keep proposal/roadmap docs explicitly labeled; avoid mixing proposal text into runtime-contract docs.
• Keep project snapshots date-stamped and immutable once superseded by a newer date.

5) Risk Tiers by Path (Review Depth Contract)

Use these tiers when deciding validation depth and review rigor.

• Low risk: docs/chore/tests-only changes
• Medium risk: most src/** behavior changes without boundary/security impact, src/factory/** (multi-agent workflow, agent spawning)
• High risk: src/security/**, src/runtime/**, src/gateway/**, src/tools/**, .github/workflows/**, access-control boundaries

When uncertain, classify as higher risk.

6) Agent Workflow (Required)

1. Read before write
   • Inspect existing module, factory wiring, and adjacent tests before editing.
2. Define scope boundary
   • One concern per PR; avoid mixed feature+refactor+infra patches.
3. Implement minimal patch
   • Apply KISS/YAGNI/DRY rule-of-three explicitly.
4. Validate by risk tier
   • Docs-only: lightweight checks.
   • Code/risky changes: full relevant checks and focused scenarios.
5. Document impact
   • Update docs/PR notes for behavior, risk, side effects, and rollback.
   • If CLI/config/provider/channel behavior changed, update corresponding runtime-contract references.
   • If docs entry points changed, keep all supported locale README/docs-hub navigation aligned (en, zh-CN, ja, ru, fr, vi).
6. Respect queue hygiene
   • If stacked PR: declare Depends on #....
   • If replacing old PR: declare Supersedes #....

6.1 Branch / Commit / PR Flow (Required)

All contributors (human or agent) must follow the same collaboration flow:

• Create and work from a non-main branch.
• Commit changes to that branch with clear, scoped commit messages.
• Open a PR to main; do not push directly to main.
• Wait for required checks and review outcomes before merging.
• Merge via PR controls (squash/rebase/merge as repository policy allows).
• Branch deletion after merge is optional; long-lived branches are allowed when intentionally maintained.

6.2 Worktree Workflow (Required for Multi-Track Agent Work)

Use Git worktrees to isolate concurrent agent/human tracks safely and predictably:

• Use one worktree per active branch/PR stream to avoid cross-task contamination.
• Keep each worktree on a single branch; do not mix unrelated edits in one worktree.
• Run validation commands inside the corresponding worktree before commit/PR.
• Name worktrees clearly by scope (for example: wt/ci-hardening, wt/provider-fix) and remove stale worktrees when no longer needed.
• PR checkpoint rules from section 6.1 still apply to worktree-based development.

6.3 Code Naming Contract (Required)

Apply these naming rules for all code changes unless a subsystem has a stronger existing pattern.

• Use Rust standard casing consistently: modules/files snake_case, types/traits/enums PascalCase, functions/variables snake_case, constants/statics SCREAMING_SNAKE_CASE.
• Name types and modules by domain role, not implementation detail (for example DiscordChannel, SecurityPolicy, MemoryStore over vague names like Manager/Helper).
• Keep trait implementer naming explicit and predictable: <ProviderName>Provider, <ChannelName>Channel, <ToolName>Tool, <BackendName>Memory.
• Keep factory registration keys stable, lowercase, and user-facing (for example "openai", "discord", "shell"), and avoid alias sprawl without migration need.
• Name tests by behavior/outcome (<subject>_<expected_behavior>) and keep fixture identifiers neutral/project-scoped.
• If identity-like naming is required in tests/examples, use ZeroBuild-native labels only (ZeroBuildAgent, zerobuild_user, zerobuild_node).

6.4 Architecture Boundary Contract (Required)

Use these rules to keep the trait/factory architecture stable under growth.

• Extend capabilities by adding trait implementations + factory wiring first; avoid cross-module rewrites for isolated features.
• Keep dependency direction inward to contracts: concrete integrations depend on trait/config/util layers, not on other concrete integrations.
• Avoid creating cross-subsystem coupling (for example provider code importing channel internals, tool code mutating gateway policy directly).
• Keep module responsibilities single-purpose: orchestration in agent/, transport in channels/, model I/O in providers/, policy in security/, execution in tools/, multi-agent workflow in factory/.
• Introduce new shared abstractions only after repeated use (rule-of-three), with at least one real caller in current scope.
• For config/schema changes, treat keys as public contract: document defaults, compatibility impact, and migration/rollback path.

7) Change Playbooks

7.1 Adding a Provider

• Implement Provider in src/providers/.
• Register in src/providers/mod.rs factory.
• Add focused tests for factory wiring and error paths.
• Avoid provider-specific behavior leaks into shared orchestration code.

7.2 Adding a Channel

• Implement Channel in src/channels/.
• Keep send, listen, health_check, typing semantics consistent.
• Cover auth/allowlist/health behavior with tests.

7.3 Adding a Tool

• Implement Tool in src/tools/ with strict parameter schema.
• Validate and sanitize all inputs.
• Return structured ToolResult; avoid panics in runtime path.

7.4 Adding a Peripheral

• Implement Peripheral in src/peripherals/.
• Peripherals expose tools() — each tool delegates to the hardware (GPIO, sensors, etc.).
• Register board type in config schema if needed.
• See docs/hardware-peripherals-design.md for protocol and firmware notes.

7.5 Security / Runtime / Gateway Changes

• Include threat/risk notes and rollback strategy.
• Add/update tests or validation evidence for failure modes and boundaries.
• Keep observability useful but non-sensitive.
• For .github/workflows/** changes, include Actions allowlist impact in PR notes and update docs/actions-source-policy.md when sources change.

7.6 Adding Factory Agent Roles

• Define the new role variant in AgentRole enum in src/factory/roles.rs.
• Add a default_for() match arm with system prompt, allowed tools, temperature, and agentic flag.
• Wire the role into the appropriate workflow phase in src/factory/workflow.rs.
• If the role needs new tools, add tools first (playbook 7.3) before referencing them in allowed_tools.
• Add tests for config resolution and role defaults.
• Update AGENTS.md Section 6 (Multi-Agent Factory Workflow) with the new role.

7.7 Docs System / README / IA Changes

• Treat docs navigation as product UX: preserve clear pathing from README -> docs hub -> SUMMARY -> category index.
• Keep top-level nav concise; avoid duplicative links across adjacent nav blocks.
• When runtime surfaces change, update related references (commands/providers/channels/config/runbook/troubleshooting).
• Keep multilingual entry-point parity for all supported locales (en, zh-CN, ja, ru, fr, vi) when nav or key wording changes.
• When shared docs wording changes, sync corresponding localized docs for supported locales in the same PR (or explicitly document deferral and follow-up PR).
• For docs snapshots, add new date-stamped files for new sprints rather than rewriting historical context.

8) Validation Matrix

Default local checks for code changes:

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test

Preferred local pre-PR validation path (recommended, not required):

./dev/ci.sh all

Notes:

• Local Docker-based CI is strongly recommended when Docker is available.
• Contributors are not blocked from opening a PR if local Docker CI is unavailable; in that case run the most relevant native checks and document what was run.

Additional expectations by change type:

• Docs/template-only:
  • run markdown lint and link-integrity checks
  • if touching README/docs-hub/SUMMARY/collection indexes, verify EN/ZH/JA/RU navigation parity
  • if touching bootstrap docs/scripts, run bash -n bootstrap.sh scripts/bootstrap.sh scripts/install.sh
• Workflow changes: validate YAML syntax; run workflow lint/sanity checks when available.
• Security/runtime/gateway/tools: include at least one boundary/failure-mode validation.

If full checks are impractical, run the most relevant subset and document what was skipped and why.

9) Collaboration and PR Discipline

• Follow .github/pull_request_template.md fully (including side effects / blast radius).
• Keep PR descriptions concrete: problem, change, non-goals, risk, rollback.
• Use conventional commit titles.
• Prefer small PRs (size: XS/S/M) when possible.
• Agent-assisted PRs are welcome, but contributors remain accountable for understanding what their code will do.

9.0 GitHub Ops Language, Title Format, and Label Contract (Required)

These rules apply to every issue and pull request created, edited, or managed by the agent or contributors.

Language:

• All issues and pull requests MUST be written in English. This applies to titles, bodies, comments, and review feedback — no exceptions regardless of the user's language of instruction.

Issue title format:

• Use a bracketed type prefix: [Feature]: <title>, [Bug]: <title>, [Chore]: <title>, [Docs]: <title>, [Security]: <title>, [Refactor]: <title>, [Test]: <title>, [Perf]: <title>.
• Do NOT use wordy forms like "Feature Request: …" or "Bug Report: …". Use the bracketed prefix only.
• Keep titles concise, specific, and system-focused (no first-person or vague language).

Labels (Required for every issue and PR):

• Every issue must have at least one type label: feature, bug, chore, docs, security, refactor, test, or perf.
• Every PR must have at least one type label and optionally a scope label: provider, channel, tool, gateway, memory, runtime, config, ci, peripheral.
• Size labels (size: XS, size: S, size: M, size: L, size: XL) are required for PRs.
• Add breaking-change label when the change breaks a public API, config contract, or user-facing behavior.
• Add needs-review or blocked labels when appropriate.
• Agent must apply labels at creation time; do not open unlabeled issues or PRs.

GitHub ops tool scope:

• github_ops.rs supports: create issue, edit issue, close issue, create PR, review PR.
• Use edit-issue to update title, body, or labels after creation (do not close and recreate).
• Use close-issue with a resolution comment explaining outcome (fixed, won't fix, duplicate).

9.5 Issue Template (Required)

All issues must follow this structure. Fill every section; remove sections only if genuinely not applicable and note why inline.

## Summary
<One paragraph: what this issue is about and why it matters.>

## Problem Statement
<Describe the current behavior, gap, or pain point. Be specific; include repro steps for bugs.>

## Proposed Solution
<Describe the intended outcome. For features: what it should do. For bugs: what correct behavior looks like.>

## Non-goals / Out of Scope
- <Explicitly list what this issue will NOT address.>

## Alternatives Considered
- <List alternatives evaluated and why they were not chosen.>

## Acceptance Criteria
- [ ] <Concrete, testable condition 1>
- [ ] <Concrete, testable condition 2>

## Architecture Impact
- Affected subsystems: <list modules/traits/tools/channels impacted>
- New dependencies: <none or list>
- Config/schema changes: <yes/no — if yes, describe>

## Risk and Rollback
- Risk: <low/medium/high and why>
- Rollback: <how to revert if the fix/feature causes regression>

## Breaking Change?
- [ ] Yes — describe impact and migration path
- [ ] No

## Data Hygiene Checks
- [ ] I removed personal/sensitive data from examples, payloads, and logs.
- [ ] I used neutral, project-focused wording and placeholders.

9.6 Pull Request Template (Required)

All PRs must follow this structure. Keep each section factual and concise.

## Summary
<One paragraph: what this PR does and why.>

## Problem
<What broken/missing behavior or gap does this PR address?>

## Root Cause
<For bug fixes: what was the underlying cause? For features: what need/gap drove this?>

## Changes
- <Bullet list of concrete changes: files, modules, behaviors modified.>

## Validation
- [ ] `cargo fmt --all -- --check` passed
- [ ] `cargo clippy --all-targets -- -D warnings` passed
- [ ] `cargo test` passed
- [ ] Manual test / scenario: <describe>
- [ ] Docker CI (`./dev/ci.sh all`) run: <yes/no/skipped — if skipped, explain>

## Automation / Workflow Notes
<Any CI/CD, workflow, label-routing, or automation changes introduced or affected by this PR.>

## Scope
- Affected subsystems: <list>
- Files changed: <count or list key files>

## Non-goals
- <Explicitly list what this PR does NOT change.>

## Risk
- Risk tier: <low/medium/high>
- Blast radius: <which subsystems or users could be affected by a regression>

## Rollback
- Revert strategy: <e.g., `git revert <commit>` or specific steps>
- Any migration needed on rollback: <yes/no — if yes, describe>

9.1 Privacy/Sensitive Data and Neutral Wording (Required)

Treat privacy and neutrality as merge gates, not best-effort guidelines.

• Never commit personal or sensitive data in code, docs, tests, fixtures, snapshots, logs, examples, or commit messages.
• Prohibited data includes (non-exhaustive): real names, personal emails, phone numbers, addresses, access tokens, API keys, credentials, IDs, and private URLs.
• Use neutral project-scoped placeholders (for example: user_a, test_user, project_bot, example.com) instead of real identity data.
• Test names/messages/fixtures must be impersonal and system-focused; avoid first-person or identity-specific language.
• If identity-like context is unavoidable, use ZeroBuild-scoped roles/labels only (for example: ZeroBuildAgent, ZeroBuildOperator, zerobuild_user) and avoid real-world personas.
• Recommended identity-safe naming palette (use when identity-like context is required):
  • actor labels: ZeroBuildAgent, ZeroBuildOperator, ZeroBuildMaintainer, zerobuild_user
  • service/runtime labels: zerobuild_bot, zerobuild_service, zerobuild_runtime, zerobuild_node
  • environment labels: zerobuild_project, zerobuild_workspace, zerobuild_channel
• If reproducing external incidents, redact and anonymize all payloads before committing.
• Before push, review git diff --cached specifically for accidental sensitive strings and identity leakage.

9.2 Superseded-PR Attribution (Required)

When a PR supersedes another contributor's PR and carries forward substantive code or design decisions, preserve authorship explicitly.

• In the integrating commit message, add one Co-authored-by: Name <email> trailer per superseded contributor whose work is materially incorporated.
• Use a GitHub-recognized email (<login@users.noreply.github.com> or the contributor's verified commit email) so attribution is rendered correctly.
• Keep trailers on their own lines after a blank line at commit-message end; never encode them as escaped \\n text.
• In the PR body, list superseded PR links and briefly state what was incorporated from each.
• If no actual code/design was incorporated (only inspiration), do not use Co-authored-by; give credit in PR notes instead.

9.3 Superseded-PR PR Template (Recommended)

When superseding multiple PRs, use a consistent title/body structure to reduce reviewer ambiguity.

• Recommended title format: feat(<scope>): unify and supersede #<pr_a>, #<pr_b> [and #<pr_n>]
• If this is docs/chore/meta only, keep the same supersede suffix and use the appropriate conventional-commit type.
• In the PR body, include the following template (fill placeholders, remove non-applicable lines):

## Supersedes
- #<pr_a> by @<author_a>
- #<pr_b> by @<author_b>
- #<pr_n> by @<author_n>

## Integrated Scope
- From #<pr_a>: <what was materially incorporated>
- From #<pr_b>: <what was materially incorporated>
- From #<pr_n>: <what was materially incorporated>

## Attribution
- Co-authored-by trailers added for materially incorporated contributors: Yes/No
- If No, explain why (for example: no direct code/design carry-over)

## Non-goals
- <explicitly list what was not carried over>

## Risk and Rollback
- Risk: <summary>
- Rollback: <revert commit/PR strategy>

9.4 Superseded-PR Commit Template (Recommended)

When a commit unifies or supersedes prior PR work, use a deterministic commit message layout so attribution is machine-parsed and reviewer-friendly.

• Keep one blank line between message sections, and exactly one blank line before trailer lines.
• Keep each trailer on its own line; do not wrap, indent, or encode as escaped \n text.
• Add one Co-authored-by trailer per materially incorporated contributor, using GitHub-recognized email.
• If no direct code/design is carried over, omit Co-authored-by and explain attribution in the PR body instead.

feat(<scope>): unify and supersede #<pr_a>, #<pr_b> [and #<pr_n>]

<one-paragraph summary of integrated outcome>

Supersedes:
- #<pr_a> by @<author_a>
- #<pr_b> by @<author_b>
- #<pr_n> by @<author_n>

Integrated scope:
- <subsystem_or_feature_a>: from #<pr_x>
- <subsystem_or_feature_b>: from #<pr_y>

Co-authored-by: <Name A> <login_a@users.noreply.github.com>
Co-authored-by: <Name B> <login_b@users.noreply.github.com>

Reference docs:

• CONTRIBUTING.md
• docs/README.md
• docs/SUMMARY.md
• docs/docs-inventory.md
• docs/commands-reference.md
• docs/providers-reference.md
• docs/channels-reference.md
• docs/config-reference.md
• docs/operations-runbook.md
• docs/troubleshooting.md
• docs/one-click-bootstrap.md
• docs/pr-workflow.md
• docs/reviewer-playbook.md
• docs/ci-map.md
• docs/actions-source-policy.md

10) Anti-Patterns (Do Not)

• Do not add heavy dependencies for minor convenience.
• Do not silently weaken security policy or access constraints.
• Do not add speculative config/feature flags “just in case”.
• Do not mix massive formatting-only changes with functional changes.
• Do not modify unrelated modules “while here”.
• Do not bypass failing checks without explicit explanation.
• Do not hide behavior-changing side effects in refactor commits.
• Do not include personal identity or sensitive information in test data, examples, docs, or commits.

11) Handoff Template (Agent -> Agent / Maintainer)

When handing off work, include:

1. What changed
2. What did not change
3. Validation run and results
4. Remaining risks / unknowns
5. Next recommended action

12) Vibe Coding Guardrails

When working in fast iterative mode:

• Keep each iteration reversible (small commits, clear rollback).
• Validate assumptions with code search before implementing.
• Prefer deterministic behavior over clever shortcuts.
• Do not “ship and hope” on security-sensitive paths.
• If uncertain, leave a concrete TODO with verification context, not a hidden guess.