AGENTS.md Generator Prompt for FINN (EWA-Services)

Instructions

You are generating a comprehensive, org-level AGENTS.md file for FINN (EWA-Services), a fintech startup with 83 active repositories. This file will be the root-level AI context document synced to all repositories via the existing EWA-Actions sync mechanism.

The AGENTS.md must be grounded in reality — derived from the actual configuration, policies, and conventions observed in the org, not aspirational or theoretical.

Input Context

You have been provided with the following collected data from the EWA-Services GitHub org (output of collect-finn-context.sh):

Existing AI context files: EWA-Actions/AGENTS.md, EWA-Actions/CLAUDE.md, any repo-specific files
CI/CD workflow templates: From EWA-Actions/workflow-templates/
Sync configuration: Which repos get which workflows (sync-workflow-files.yml, sync-other-files.yml)
Policy Bot configurations: Team-specific approval rules (.policy-*.yml)
Pre-commit hooks: Language-specific pre-commit configs
Linter/formatter configs: Ruff (Python), ESLint/Prettier (TypeScript), golangci-lint (Go)
Branch protection rules: Required approvals, status checks
CODEOWNERS files: Team ownership mappings
Commit history samples: Convention patterns from recent commits
PR templates: Required fields, checklist items
Test configurations: Frameworks and patterns per language
Repo metadata: Language distribution, team structure

Your Task

Generate a single AGENTS.md file that serves as the org-wide AI coding context for any AI coding assistant (Claude Code, Cursor, Copilot, Codex) working in any FINN repository.

Output Structure

The AGENTS.md must follow this structure:

# AGENTS.md — FINN (EWA-Services)

## About This File
[Brief explanation: what this file is, who it's for (AI agents), and that it's synced from EWA-Actions]

## Organization Overview
[FINN is a fintech startup operating in Thailand. Key context about the business domain that AI needs to know.]

## Repository Architecture
[How repos are organized: tech stacks, team ownership, centralized vs distributed patterns]
- Centralized CI/CD via EWA-Actions (synced to all repos)
- Language distribution: Python (19), TypeScript (17), HCL (11), PHP (9), Go (2)
- Team structure: backend, frontend, infrastructure, QA, data engineering, credit risk

## Code Standards

### General
[Universal rules that apply to ALL repos]

### Python
[Ruff config, pre-commit hooks, pytest conventions, poetry usage]

### TypeScript / JavaScript
[ESLint, Prettier, Jest/Vitest, Angular conventions (FINN-Web-App), NX monorepo (Core)]

### Go
[golangci-lint, test conventions, module structure]

### PHP
[Pre-commit hooks, test conventions]

### HCL / Terraform
[Digger workflow, terraform-docs, Checkov scanning, module conventions]

## Git Conventions

### Branch Strategy
[Trunk-based development vs gitflow — identify from branch protection and policies]

### Commit Messages
[Conventional commits format, enforced by semantic-pr.yaml]
[Format: type(scope): description [TICKET-ID]]
[Valid types: feat, fix, chore, refactor, ci, docs, test, perf, style, build, revert]

### Pull Requests
[PR template requirements: checklist, description, Linear ticket linking]
[PR title format: must pass semantic-pr validation]
[PR description: must have checkboxes checked, must link Linear ticket]

### Merge Strategy
[Squash merge via Bulldozer with automerge label]
[Release PRs are automated via release-please — do not modify directly]

## Review Process

### Human Review
[Policy Bot rules by team: 2 approvals required for most teams]
[Frontend requires: 2 from dev-client/dev-qa + 1 from frontend lead (poom/jai)]
[Backend requires: 2 from dev-backend]
[Infrastructure requires: 2 from dev-infrastructure]
[Exceptions: finn-devops bot bypasses review, codegen-bot needs 2 reviews but no signature]

### AI Code Review
[Claude-powered code review triggered on:
 - PR marked "Ready for review" → full review
 - @claude in PR comment → answer questions
 - @claude in inline comment → thread reply
Only users with write/maintain/admin permissions can trigger reviews]

### PR Metadata Gate
[AI-powered PR metadata validation checks:
 - PR description quality and completeness
 - Linear ticket linking
 - Checkbox completion
 - Automatically re-validates on edits]

## CI/CD Pipeline

### Shared Workflows (from EWA-Actions)
[List all workflows synced across repos and what they do]
- semantic-pr.yaml: PR title/description validation
- code-review.yaml: Claude-powered code review
- pr-metadata-gate.yaml: AI metadata validation
- auto-rebase.yaml: Automatic PR rebasing
- rebase-command.yaml: Manual rebase via slash command
- release.yaml: release-please automation
- pre-commit.yaml: Language-specific pre-commit hooks
- growthbook-implementation-check.yaml: Feature flag validation
- growthbook-validation.yaml: GrowthBook experiment validation

### Language-Specific Pipelines
[Python: ruff lint, pre-commit, pytest]
[TypeScript: ESLint, Prettier, Jest/Vitest, build]
[Go: golangci-lint, go test, integration tests]
[Terraform: Digger, Checkov, terraform-docs]

### Deployment
[Describe staging and production deployment patterns observed in workflows]

## Testing Requirements

### By Language
[Python: pytest, pytest-mock, responses (for API mocking)]
[TypeScript: Jest (Core), Angular test (FINN-Web-App), Playwright (Tests repo)]
[Go: go test, integration tests with docker-compose]
[E2E: Playwright, Appium (mobile)]

### Coverage
[Document any observed coverage requirements from CI workflows]

### Feature Flags
[GrowthBook is used for feature flags and experiments]
[CI validates GrowthBook implementation in code]

## Security & Compliance

### Fintech-Specific Rules
[NEVER include financial data, customer PII, or credentials in code, comments, or logs]
[All commits must be GPG-signed (enforced by policy)]
[Private key detection is enforced via pre-commit hooks]
[Large file checks prevent accidental data commits (500KB limit)]

### Secrets Management
[Do not hardcode secrets — use environment variables or secrets manager]
[.secrets.example files may exist for reference but NEVER commit actual secrets]

### Infrastructure as Code
[Checkov scanning for IaC security]
[Terraform state is managed remotely]

## Tool Integrations
[Linear: Project management — tickets referenced in PR titles as [TICKET-ID]]
[GrowthBook: Feature flags and experiments]
[Digger: Terraform automation in CI]
[Bulldozer: Auto-merge when automerge label is applied and checks pass]
[Release Please: Automated semantic versioning and changelogs]
[Cloudflare: CDN and edge configuration]
[Pre-commit: Enforced via CI and local hooks]

## AI Agent-Specific Guidance

### When Working in This Repo
1. Always read this AGENTS.md first
2. Check for repo-specific AGENTS.md or CLAUDE.md (may override org defaults)
3. Follow the language-specific standards for this repo's primary language
4. Reference Linear tickets in all PR titles
5. Ensure PR description checklist is completed
6. Write tests alongside implementation
7. Do not modify files with "This file is synchronized from EWA-Services/EWA-Actions" headers

### Common Pitfalls
[List things AI agents commonly get wrong in this codebase]
- Forgetting Linear ticket references in PR titles
- Not checking PR description checkboxes
- Modifying synced files directly (they'll be overwritten)
- Not running pre-commit hooks before pushing
- Ignoring GrowthBook feature flag patterns
- Using incorrect conventional commit types

### Files You Should Not Modify
[Files synced from EWA-Actions — look for the header comment]
[.policy.yml — managed centrally]
[.bulldozer.yml — managed centrally]
[CODEOWNERS — managed centrally]
[Workflow files in .github/workflows/ that have the sync header]

Generation Rules

Ground every statement in evidence: For each rule or convention you document, it should be traceable to an actual config file, workflow, or commit pattern in the collected data.
Deduplicate and consolidate: The existing AGENTS.md and CLAUDE.md in EWA-Actions may have overlapping content. Merge them into a single coherent document.
Identify undocumented practices: If commit history shows conventional commits but no AGENTS.md mentions it, add it. If policy files enforce 2 approvals but no AI context file mentions it, add it.
Be specific, not generic: Don't write "follow best practices." Write "use ruff with line-length 120, select rules E, F, I, UP."
Include escape hatches: Note where repos may override org defaults and how to detect that.
Keep it scannable: Use headers, bullet points, and code blocks. AI agents need to quickly find relevant sections.
Size target: Aim for 400-800 lines. Long enough to be comprehensive, short enough to fit in context windows.
Validate against sync mechanism: The output will be added to EWA-Actions' other-templates/ and synced via sync-other-files.yml. Ensure the format is compatible (add the sync header comment at the top).

What NOT to Include

Specific API keys, tokens, or credentials
Internal URLs or IP addresses
Customer data schemas or PII field names
Detailed business logic (belongs in repo-specific context)
Aspirational rules not yet enforced (only document what's real)

Quality Checklist

Before finalizing, verify:

jai/agents-md-generator-prompt.md

Select an option

No results found