Imported from agarwalvivek29/skillbridge (AGENTS.md). Install upstream with npx skills add agarwalvivek29/skillbridge. Copyright stays with the author.

AGENTS.md — Agent Contract

This file governs how Agents operates in this repository and all projects derived from it. Read this before taking any action.

⚠️ Bootstrap Check — Read This First

Before anything else: does BOOTSTRAP.md exist in this repository?

ls BOOTSTRAP.md 2>/dev/null && echo "EXISTS" || echo "NOT FOUND"

Mandatory Pre-Flight Checks

Before starting any task, you MUST:

1. Read docs/CORE_RULES.md — The binding rules for this repository. No exceptions.
2. Find the GitHub Issue — Task context, requirements, and acceptance criteria come from the linked issue.
3. Check for a spec — Look in docs/specs/ for a file matching the issue number. If none exists for a feature task, stop and create one before proceeding.
4. Check relevant ADRs — Scan docs/adr/ for decisions that affect the area you're working in.
5. Read AGENTS.md for the service — If you're modifying a specific service, read its AGENTS.md before touching any code.
6. Check packages/schema/proto/ — If your task involves any data type (entity, enum, event, request/response shape), verify it's defined in proto. If not, define it there first before writing any service code.

Workflow Gates

Gate 1: Spec Gate

• Non-trivial features require a spec. If docs/specs/[ISSUE-NUMBER]-*.md does not exist, create it using docs/specs/TEMPLATE.md before writing any implementation code.
• Bug fixes, dependency updates, and documentation changes are exempt.

Gate 2: Plan Gate

• Changes touching more than 2 files or introducing new architecture require an approved plan.
• Use EnterPlanMode to explore, design, and present your plan. Do not write production code during planning.
• Exit planning only after the plan is approved by the user.

Gate 3: ADR Gate

• Any architectural decision requires an ADR. See docs/adr/README.md for what triggers an ADR.
• Create the ADR in docs/adr/[NNNN]-[title].md before implementing the decision.

File and Code Rules

• Never create a new service manually. Always use scripts/new-service.sh.
• Prefer editing existing files over creating new ones.
• Never skip git hooks. Do not use --no-verify or --no-gpg-sign.
• Never commit to main directly. All changes go through a PR on a feature branch.
• Never hardcode secrets. Use .env files (gitignored). Update .env.example with placeholder values.
• Never modify infra/docker-compose.yml or AWS configs without explicit human approval.

Task Tracking Discipline

Use the built-in task system for any multi-step work:

TaskCreate  → when starting a complex task
TaskUpdate  → mark in_progress before beginning, completed when done
TaskList    → check for next task after completing one

Break large tasks into smaller, independently completable units. Never mark a task complete if tests are failing or implementation is partial.

Memory Management

Maintain .agents/memory/ to preserve context across sessions:

• MEMORY.md — high-level summary, always loaded (keep under 200 lines)
• Topic files (e.g., auth.md, database.md) — detailed notes linked from MEMORY.md

Write to memory when you discover:

• Stable architectural patterns in this repo
• Non-obvious conventions or gotchas
• Important file paths and entry points
• Solutions to recurring problems

Do NOT write: session-specific state, incomplete conclusions, or anything that duplicates CORE_RULES.md.

Capabilities and Tools

You may use any available skills, MCP servers, and tools as needed to complete tasks. Common useful MCPs:

• filesystem — file operations
• github — issue/PR management, branch operations
• postgres/mongo — database inspection (read-only in production)
• Web search — for researching libraries and patterns

Document any MCP or tool you add to a workflow in the relevant service's AGENTS.md.

Service Modification Checklist

When modifying a service:

• Read services/[name]/AGENTS.md
• Spec exists in docs/specs/
• ADR created if architectural decision needed
• Plan approved (EnterPlanMode for >2 files)
• Auth middleware applied to all new routes (check it's not bypassed)
• JWT_SECRET and API_KEY present in .env.example with placeholder values
• New data types defined in packages/schema/proto/ — NOT in service code
• packages/schema/generated/ regenerated and committed if proto changed
• Unit tests written for new domain functions (tests/unit/)
• E2E tests written for new API endpoints (tests/e2e/)
• .env.example updated if new env vars added
• AGENTS.md updated if service behavior or architecture changed
• All commits follow type(scope): description format

Creating a New Service

# Always use the scaffold script
./scripts/new-service.sh

# Then follow the printed next steps:
# 1. Create GitHub Issue
# 2. Write spec in docs/specs/
# 3. Create ADR if needed
# 4. Plan → implement → PR

Schema-First Rule (Critical)

Before writing any type definition in service code:

1. Check if the type exists in packages/schema/proto/
2. If not → create the .proto definition first
3. Run cd packages/schema && ./scripts/generate.sh
4. Commit the proto + generated files
5. Import the generated type in the service

Never define a type, interface, struct, class, dataclass, or enum for a business domain concept in service code. The generated types from packages/schema are the only source of truth.

When Spawned via ao

If you were launched by ao spawn or ao start, you are in orchestrated mode:

• You are in a git worktree — isolated from main and all other sessions. Never touch another session's branch.
• Your task is a GitHub Issue — check docs/specs/ for a matching spec file before writing any implementation code.
• docs/CORE_RULES.md is already in your system prompt — injected by ao. It still fully binds you.
• Pushing your feature branch is pre-authorized — open a PR when implementation is complete. Do not push to main.
• ao manages the PR pipeline — CI failures and review comments will be forwarded to you automatically. Address them when they arrive.
• Do not manually create or close GitHub Issues or PRs — use gh pr create once, then let ao handle the loop.

Behavior Boundaries

Without explicit human approval, you MUST NOT:

• Push to remote branches
• Create, close, or comment on GitHub Issues or PRs
• Modify CI/CD pipeline configurations
• Drop or migrate databases
• Change infrastructure (AWS, docker-compose services)
• Delete files that may represent in-progress work
• Force-push any branch

When in doubt: stop, explain what you were about to do, and ask.

Quick Reference