agents

This repository is a collection of reusable documentation boilerplates centered on AGENTS.md and docs/README.md.

All templates in this repository are intended to support a feature-based project structure, adapted to the conventions of each stack.

Each folder represents a stack type or project context, for example:

• backend-bun/
• backend-go/
• backend-node/
• backend-rust/
• frontend-nextjs/
• frontend-react/
• frontend-solidjs/
• android-kotlin/
• ios-swiftui/
• mobile-expo/
• mobile-flutter/
• mobile-react-native/
• monorepo/

Each folder typically contains:

• AGENTS.md
  • stable and reusable working rules
• docs/README.md
  • the canonical project portal for source-of-truth docs, documentation mapping, and critical context summaries
• README.md
  • a quick overview of the template, its architecture, and when to use it

Goals of this repository:

• speed up agent-documentation bootstrap for new projects
• keep AGENTS.md and docs/README.md structures consistent
• provide templates that can be adapted without starting from scratch

CLI Usage

Install the generator globally:

npm install -g frogg-agents

Or install it with Homebrew:

brew install FroggLabs/tap/frogg

Then run it from any project directory:

frogg

You can also generate a template directly:

frogg node ./my-node-api
frogg go ./my-go-api
frogg next ./my-next-project
frogg react ./my-react-project
frogg expo ./my-expo-app
frogg flutter ./my-flutter-app
frogg mono ./my-monorepo

You can generate Frogg Design docs separately:

frogg frogg-design
frogg frogg-design monorepo ./my-monorepo
frogg frogg-design non-monorepo ./my-frontend

The Frogg Design source markdown lives in frogg-design/.

Frogg Design output paths:

| Target | Output | | --- | --- | | monorepo | docs/shared/frogg-design/ | | non-monorepo | docs/frogg-design/ |

Template generation copies only:

• AGENTS.md
• docs/

Template README.md files are used as references inside this repository and are not copied into generated projects.

Available template names and aliases:

| Template | Aliases | | --- | --- | | backend-bun | bun | | backend-go | go, golang | | backend-node | node, nodejs | | backend-rust | rust | | frontend-nextjs | next, nextjs | | frontend-react | react, frontend, spa | | frontend-solidjs | solid, solidjs | | android-kotlin | android, kotlin | | ios-swiftui | ios, swift, swiftui | | mobile-expo | expo | | mobile-flutter | flutter, riverpod, flutter-riverpod | | mobile-react-native | react-native, rn, native | | monorepo | mono, workspace |

For local development, link the CLI from this repository:

npm install
npm link
frogg

Quick usage:

1. Choose the template folder that best matches the new project's stack
2. Read the template README.md to confirm the architecture and intended use
3. Copy AGENTS.md and docs/ into the target repository
4. Use the folder README.md and docs/README.md as guides for the target repository structure and conventions
5. Customize the project-specific details in docs/README.md
6. Keep AGENTS.md stable unless the global working rules truly need to change

Template Summary

| Folder | Stack | Architecture | Testing Posture | Best For | | --- | --- | --- | --- | --- | | backend-bun/ | Bun backend | Feature-based modular monolith using Hexagonal Architecture (Ports & Adapters) with Elysia and Drizzle | Strict affected-scope coverage gates | Bun services that want fast runtime ergonomics, clean boundaries, and strong testability | | backend-go/ | Go backend | Feature-based modular monolith using Hexagonal Architecture (Ports & Adapters) | Strict affected-scope coverage gates | Backend services with strong boundaries and focused unit-test coverage | | backend-node/ | Node.js backend | Feature-based modular monolith using Hexagonal Architecture (Ports & Adapters) with Hono and a pluggable persistence toolkit | Strict affected-scope coverage gates | Node.js and TypeScript services that need clear runtime, transport, persistence, and contract boundaries | | backend-rust/ | Rust backend | Feature-based modular monolith using Hexagonal Architecture (Ports & Adapters) with an explicit application core | Strict affected-scope coverage gates | Highly testable backend systems with strict boundary control | | frontend-nextjs/ | Next.js frontend | Feature-based App Router architecture with explicit Server Component, Client Component, route handler, server action, and deployment boundaries | Strict affected-scope coverage gates | Next.js apps that need strong server/client and runtime discipline | | frontend-react/ | React SPA | Feature-based frontend architecture for browser SPA projects with explicit routing, browser storage, and API client seams | Strict affected-scope coverage gates | React/Vite-style apps that do not need Next.js server/runtime rules | | frontend-solidjs/ | SolidJS SPA | Feature-based frontend architecture for SolidJS browser SPA projects with explicit routing, browser storage, API client, and reactivity seams | Strict affected-scope coverage gates | SolidJS/Vite-style apps that need clear signal, memo, resource, store, and effect ownership | | android-kotlin/ | Android Kotlin | Modular feature-based Android architecture using Clean Architecture, strict UDF/MVI, pure use cases, and strict module isolation | Strict affected-scope coverage gates | Modern Android apps with strong state and module discipline | | ios-swiftui/ | iOS SwiftUI | Modular feature-based iOS architecture using TCA, a pure reducer core, and explicit dependency clients | Strict affected-scope coverage gates | SwiftUI apps that want highly testable state management | | mobile-expo/ | Expo mobile | Feature-based Expo architecture with explicit Expo Router, SDK module, config plugin, EAS, OTA update, and release boundaries | Strict affected-scope coverage gates | Expo-managed apps that need clear SDK and release governance | | mobile-flutter/ | Flutter mobile | Modular feature-based Flutter architecture using Clean Architecture, Riverpod, and a strict application/domain split | Strict affected-scope coverage gates | Cross-platform Flutter apps with clear layering and Riverpod-based state composition | | mobile-react-native/ | Bare React Native mobile | Feature-based mobile architecture with explicit navigation, native module, permission, storage, and release boundaries | Strict affected-scope coverage gates | Bare React Native apps that need direct native runtime ownership | | monorepo/ | Multi-package workspace | Apps and packages workspace with pluggable package manager (Bun/pnpm/Yarn), task runner (Turborepo/Nx/Moon), and Changesets-based releases | Strict affected-scope coverage gates | Repositories that host multiple deployable apps and shared internal packages with explicit boundaries and coordinated releases |

Adoption Checklist

After copying a template into a real repository:

1. Replace template titles and architecture summaries with the real project name, runtime, and ownership model
2. Mark unused docs as intentionally unused or delete them, especially unused transport or platform docs
3. Fill in the real verification commands and note which commands are required locally, in CI, and before release
4. Define the coverage gate for changed code, affected packages, and integration boundaries before enforcing CI
5. Replace default high-risk facts with repo-specific invariants, contracts, and rollback-sensitive areas
6. Add at least one real feature doc before feature behavior starts living only in code

What To Change After Copying

When you copy a template into a target repository, these markdown files do not have the same editing expectations:

• AGENTS.md
  • keep this mostly stable
  • change it only when the working model, engineering rules, testing rules, or architecture policy truly change
• docs/README.md
  • expect to customize this immediately
  • update the project title, architecture summary, docs map, repository model, highest-risk facts, and any project-specific rules
• README.md
  • update this when onboarding, setup, architecture overview, or template usage guidance needs to change

In most target repositories:

• AGENTS.md should change rarely
• docs/README.md should change often
• README.md should change when onboarding or structure changes