Agent Rules

Deployments and Destructive Changes

NEVER run any command that mutates production infrastructure without the user explicitly saying to deploy.

If a deploy or mutating action seems like the logical next step, stop and ask the user whether they want to proceed. Do not infer consent from context. Do not deploy just because the plan says "next step is deploy". Wait for an explicit instruction like "go ahead and deploy" or "run the deploy now".

Violating this rule is not a minor mistake. It is unacceptable.

Deployment workflow

We generally deploy services exclusively via CDK in CD. To trigger builds on the test servers, they are triggered by force pushing the current feature branch onto the branches t1 or t2. There are git aliases git t1 and git t2 that can be used to do this. Always seek confirmation before using these commands however.

AWS Access

The aws CLI is blocked at the system level. Do not attempt to use it.

For AWS inspection tasks, use the appropriate AWS MCP server. The following servers may be available — ask the user to enable the relevant one if it is not already active:

aws-cloudwatch — CloudWatch logs and metrics
aws-ecs — ECS cluster and service inspection
aws-cloudformation — CloudFormation stacks
aws-iac — Infrastructure-as-code tooling
aws-cost-explorer — Cost and billing

The one exception is cdk diff, which runs locally and is permitted:

AWS_PROFILE=ro npx cdk diff ...

If a task requires write access to AWS, stop and ask the user to run the command themselves.

Git Worktree Setup

Projects are set up using a git bare-clone alias that creates a bare-clone worktree layout:

project-name/          ← project root (cd here)
  .bare/               ← bare git repo (the actual git data)
  .git                 ← file containing "gitdir: ./.bare"
  main/                ← example worktree for main branch
  feature-branch/      ← example worktree for a feature

The alias does this:

mkdir "$folder_name" && cd "$folder_name"
git clone --bare "$repo_url" .bare
echo "gitdir: ./.bare" > .git
git config remote.origin.fetch "+refs/heads/*:refs/remotes/origin/*"
git fetch origin

Worktree placement rules

Always place worktrees as direct children of the project root, e.g. ~/projects/myrepo/my-feature/
Never use a nested .worktrees/ subdirectory — worktrees sit at the top level alongside other branch worktrees
The project root itself is not a worktree; it's the container. You must cd into a branch worktree to do any work
To add a new worktree: git worktree add my-feature -b my-feature (from the project root), or git worktree add ../my-feature -b my-feature (from within an existing worktree)
No .gitignore entry is needed for worktree directories since the repo is bare and the project root is not itself a working tree

Git Commits

Commit early and often. After completing any logical unit of work — a bug fix, a feature addition, a refactor, a config change — create a commit immediately rather than batching everything at the end.

All commits must follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

Common types:

feat — a new feature
fix — a bug fix
refactor — code change that neither fixes a bug nor adds a feature
chore — maintenance, dependency updates, config changes
docs — documentation only changes
test — adding or updating tests
style — formatting, missing semicolons, etc. (no logic change)

Examples:

feat(auth): add JWT refresh token support
fix(api): handle null response from payments endpoint
chore: update dependencies to latest versions

Rules:

Use lowercase for the type and description
Keep the description concise (under 72 characters)
Do not end the description with a period
Commit after each discrete, coherent change — do not wait until the end of a task

Use Context7 MCP to fetch current documentation whenever the user asks about a library, framework, SDK, API, CLI tool, or cloud service -- even well-known ones like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This includes API syntax, configuration, version migration, library-specific debugging, setup instructions, and CLI tool usage. Use even when you think you know the answer -- your training data may not reflect recent changes. Prefer this over web search for library docs.

Do not use for: refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.

Steps

Always start with resolve-library-id using the library name and the user's question, unless the user provides an exact library ID in /org/project format
Pick the best match (ID format: /org/project) by: exact name match, description relevance, code snippet count, source reputation (High/Medium preferred), and benchmark score (higher is better). If results don't look right, try alternate names or queries (e.g., "next.js" not "nextjs", or rephrase the question). Use version-specific IDs when the user mentions a version
query-docs with the selected library ID and the user's full question (not single words)
Answer using the fetched docs

5.3 KiB Raw Permalink Blame History