Agents Md Generator

AGENTS.md / CLAUDE.md Generator

Overview

This skill helps you generate comprehensive instruction files (AGENTS.md with optional CLAUDE.md compatibility) that teach AI coding agents how to work effectively in your project. It combines automatic project scanning with interactive questions to create tailored guidelines.

When to use this skill:

• Setting up a new project for AI-assisted development
• Updating existing instruction files after project changes
• Standardizing AI agent behavior across team members
• Migrating from one AI tool to another

Key Principle

Do not duplicate specialized skills. If a request falls into a specialized domain (e.g., Design System), delegate to the specialized skill when available.

Use `AGENTS.md` as the shared project manual. AGENTS.md is plain Markdown with no required fields. Cover the details an agent needs to work effectively: project overview, build and test commands, code style, testing expectations, security notes, PR/commit rules, and deployment gotchas.

Handle `AGENTS.override.md` as a Codex-specific override, not the default. Codex checks AGENTS.override.md before AGENTS.md at both global and project-directory scopes, and includes at most one instruction file per directory. If both files exist in the same directory, Codex uses AGENTS.override.md and ignores that directory's AGENTS.md. Create or update AGENTS.override.md only when the user explicitly wants a Codex-specific or nested-directory override.

Respect Codex instruction discovery. Codex builds its instruction chain once per run/session: global instructions first, then project files from repository root down to the current working directory. The global Codex directory defaults to ~/.codex and can be changed with CODEX_HOME. Files closer to the current directory appear later and override earlier guidance. Codex skips empty files and stops adding files when the combined size reaches project_doc_max_bytes (32 KiB by default). If ~/.codex/config.toml defines project_doc_fallback_filenames, Codex checks those names after AGENTS.override.md and AGENTS.md.

Use `CLAUDE.md` only as Claude Code compatibility by default. Claude Code reads CLAUDE.md, not AGENTS.md directly, so a shared setup needs a CLAUDE.md file that imports AGENTS.md.

Quick Start

To generate a new AGENTS.md file: 1. Navigate to your project root 2. Tell the AI agent: "Use the agents-md-generator skill to create an AGENTS.md file" 3. Answer the interactive questions about your project 4. Review and customize the generated file

Answering Questions (Convenient Formats)

When this skill asks numbered questions with lettered options, users can answer in any style:

• Short form (fast): 1a 2b 3c
• Mixed form: 1a 2b 3c 4b (also scan packages/*) 5d
• Full sentences: “Use medium scan depth and Docker Compose; service name is app.”

Short form is never required; it is only provided for convenience.

Generation Modes

Interactive Mode (Default):

• Guides you through each phase with questions
• Best for first-time setup or complex projects
• Maximum customization

Quick Mode:

• Tell the AI: "Generate AGENTS.md in quick mode"
• Skips all questions, uses auto-detection only
• Best for experienced users or simple projects
• Uses Medium scan depth by default
• Generates all standard sections based on detection

Interactive Workflow

Phase 1: Initialization & Discovery

Check for existing files: 1. Look for CLAUDE.md, AGENTS.md, and AGENTS.override.md in the project root. 2. If AGENTS.md exists, ask user: "I found an existing AGENTS.md. Would you like to:" 1. Update it (merge new content while preserving customizations) 2. Replace it (generate fresh, backup existing) 3. Cancel

• Reply examples (optional): 1 or update; 2 or replace; 3 or cancel

3. If CLAUDE.md exists but AGENTS.md does not, ask user before changing it: 1. Migrate to AGENTS.md as the primary file and replace CLAUDE.md with a compatibility reference to AGENTS.md 2. Keep CLAUDE.md and AGENTS.md side by side with separate instructions for different AI agents 3. Cancel

• Reply examples (optional): 1 or migrate; 2 or keep both; 3 or cancel

4. If both AGENTS.md and CLAUDE.md exist, ask whether AGENTS.md should become the single source of truth with CLAUDE.md referencing it, or whether the user intentionally wants both files to remain independent. 5. If AGENTS.override.md exists, explain that Codex gives it priority over AGENTS.md in that directory. Ask whether to update the override, merge it back into AGENTS.md, or leave it as a Codex-specific override.

Determine primary file:

• Default: AGENTS.md as primary source of truth.
• AGENTS.override.md is not the primary file. Use it only for Codex-specific overrides, temporary overrides, or nested directory rules that should supersede broader AGENTS.md guidance for Codex.
• CLAUDE.md is a secondary compatibility file for Claude Code, because Claude Code reads CLAUDE.md rather than AGENTS.md directly. Do not use symbolic links; some AI agents may read both files and duplicate context.
• When sharing the same instructions with Claude Code, make CLAUDE.md a normal text file whose first line is:

  @AGENTS.md

• Additional Claude-specific instructions may be added below the import only when the user explicitly wants them.
• If the project already has a meaningful CLAUDE.md, ask the user before replacing it. The user may prefer to keep both files with different guidance for different AI tools.

Phase 1b: Agent Tooling & System Prompt Alignment (Scripted)

Goal: Detect AI tool instruction files, global system prompts, and MCP configs using scripts (not AI scanning) to save tokens and avoid missing overrides.

Run the detection script (best effort):

• bash/zsh: bash skills/agents-md-generator/scripts/detect-agent-context --root .
• Windows cmd: skills\agents-md-generator\scripts\detect-agent-context.cmd --root .

The script should report:

• Project instruction files for AI tools (Copilot, Cursor, Cline, Kilo Code, Roo Code, OpenCode, Codex, Claude Code)
• Global instruction files (e.g., ~/.claude/CLAUDE.md, ~/.codex/AGENTS.override.md, ~/.codex/AGENTS.md, ~/.codex/config.toml, ~/.roo/rules/, ~/.kilocode/rules/)
• MCP config files and server names (from .mcp.json, .roo/mcp.json, mcp_settings.json, plus any --mcp-path entries)

If script is unavailable:

• Do a minimal manual check using the paths listed in references/tech-stack-detection.md under AI Agent Tooling Detection.

Warn the user about overrides:

• If ~/.claude/CLAUDE.md or other global instruction files exist, explicitly warn that they can override project prompts.
• Ask the user to review or adjust those system prompts to avoid conflicts with this repo.

Ask the user to confirm tool usage:

I detected these AI tool instruction sources:
- .github/copilot-instructions.md (GitHub Copilot)
- .cursorrules (Cursor)
- .clinerules or .clinerules/ (Cline)
- .kilocoderules / .kilo/ / .kilocodemodes (Kilo Code)
- .roo/rules/ / .roo/rules-* / .roorules* (Roo Code)
- opencode.jsonc (OpenCode)
- AGENTS.override.md / AGENTS.md (Codex project instructions)
- ~/.codex/AGENTS.override.md / ~/.codex/AGENTS.md / ~/.codex/config.toml (Codex global instructions and config)
- .claude/CLAUDE.md or ~/.claude/CLAUDE.md (Claude Code)

Which of these do you actively use for this project, and should we align or ignore any of them?

If MCP servers are detected:

• Ask whether they should be used in this project.
• Capture a short purpose/usage note for each server.

Phase 1c: Skill Library Duplicate Scan (Scripted)

If a skills/ folder exists, run the duplicate scan script to avoid copy-pasted skills:

• bash/zsh: bash skills/agents-md-generator/scripts/scan-skill-duplicates --skills-dir skills
• Windows cmd: skills\agents-md-generator\scripts\scan-skill-duplicates.cmd --skills-dir skills

If duplicates are detected:

• Recommend choosing one canonical folder under skills/ and merging any unique content into it.
• Do not recommend symbolic links for duplicate skill folders; agent scanners may count both paths as separate context.
• If a duplicate only exists under plugins/<plugin-name>/skills/, treat it as a generated package copy. Edit the source under skills/ and run npm run sync.

Phase 2: Scan Depth Selection

Ask the user:

What scan depth should I use to analyze your project?

1. Quick (approximately 30 seconds)
   Scans: package.json, composer.json, docker-compose.yml, pyproject.toml,
          Gemfile, go.mod, Cargo.toml, and other root config files
   Best for: When you know your stack well and want fast generation

2. Medium (approximately 1-2 minutes) [RECOMMENDED]
   Scans: Root configs + src/, app/, lib/, config/, routes/, components/,
          pages/, views/, controllers/, models/, services/
   Best for: Most projects - good balance of accuracy and speed

3. Deep (approximately 3-5 minutes)
   Scans: Entire project tree including tests/, docs/, scripts/, all
          subdirectories, hidden configs, and build artifacts
   Best for: Complex projects, monorepos, or unfamiliar codebases

Reply examples:
- Short: `2` (or `1` / `3`)
- With extra notes: `2 (also scan packages/*)`

Scan actions per depth:

Phase 3: Environment Detection

Ask the user:

What development environment does this project use?

1. Docker Compose
   - Commands run via: docker compose exec <service> <command>
   - Example: docker compose exec app php artisan migrate

2. Laravel Sail
   - Commands run via: ./vendor/bin/sail <command>
   - Example: ./vendor/bin/sail artisan migrate

3. Native/Host Machine
   - Commands run directly on your machine
   - Example: php artisan migrate

4. Dev Containers / Codespaces
   - Commands run inside the container environment

5. Other (please describe)
   - Specify your custom environment setup

Reply examples:
- Short: `1` (or `2` / `3` / `4` / `5`)
- Detailed: `1; main service is app; node runs in node service`

Follow-up questions based on selection:

• Docker: "What is the main service name? (e.g., app, web, php)"
• Docker: "Do you have separate services for different runtimes? (e.g., app for PHP, node for JS)"
• Native: "Do you use any version managers? (nvm, rbenv, pyenv, etc.)"

Phase 4: Auto-Detection + Confirmation

Scan the project based on selected depth and detect:

1. Backend Framework:

• Laravel (composer.json + artisan)
• Express/Node (package.json + server files)
• Django/Flask (requirements.txt + manage.py/app.py)
• Rails (Gemfile + config/routes.rb)
• Spring Boot (pom.xml/build.gradle + @SpringBootApplication)

2. Frontend Framework:

• Vue.js (package.json + .vue files)
• React (package.json + .jsx/.tsx files)
• Angular (angular.json)
• Svelte (svelte.config.js)
• Next.js/Nuxt.js (next.config.js/nuxt.config.ts)

3. Package Manager:

• npm/yarn/pnpm/bun (package-lock.json/yarn.lock/pnpm-lock.yaml/bun.lockb)
• Composer (composer.lock)
• pip/poetry (requirements.txt/poetry.lock)

4. Testing Framework:

• PHPUnit (phpunit.xml)
• Pest (pestphp/pest in composer.json)
• Jest (jest.config.js)
• Vitest (vitest.config.ts)
• pytest (pytest.ini/conftest.py)

5. Code Style/Linting:

• Laravel Pint (pint.json)
• ESLint (.eslintrc.*)
• Prettier (.prettierrc.*)
• PHP CS Fixer (.php-cs-fixer.php)

6. Database:

• MySQL/MariaDB (config references)
• PostgreSQL (config references)
• SQLite (database/*.sqlite)
• MongoDB (mongoose in package.json)

7. AI Agent Tooling (scripted detection):

• GitHub Copilot (.github/copilot-instructions.md)
• Cursor (.cursorrules)
• Cline (.clinerules or .clinerules/)
• Kilo Code (.kilocoderules, .kilo/, .kilocodemodes, .kilocode/config.json)
• Roo Code (.roo/rules/, .roo/rules-*, .roorules*, .roo/mcp.json, mcp_settings.json)
• OpenCode (opencode.jsonc, OPENCODE_CONFIG)
• Codex (AGENTS.override.md, AGENTS.md, ~/.codex/AGENTS.override.md, ~/.codex/AGENTS.md, ~/.codex/config.toml)
• Claude Code (.claude/CLAUDE.md, ~/.claude/CLAUDE.md, .mcp.json)

Present findings to user:

I detected the following tech stack:

Backend:
  - Laravel 11 (high confidence)
  - PHP 8.3 (from composer.json)

Frontend:
  - Vue.js 3 with Composition API (high confidence)
  - TailwindCSS v3 (from package.json)

Testing:
  - Pest PHP (from composer.json)
  - Vitest (from package.json)

Code Style:
  - Laravel Pint (pint.json found)
  - ESLint + Prettier (configs found)

Environment:
  - Docker Compose detected (docker-compose.yml)
  - Services: app, mysql, redis

Is this correct? Would you like to add or modify anything?

Phase 4b: Optional Sections (Interactive Mode Only)

Ask the user about optional sections:

Would you like to include any of these optional sections?

1. CI/CD Configuration
   - Detect: GitHub Actions, GitLab CI, CircleCI, Jenkins
   - Include: Pipeline commands, deployment notes

2. Git Workflow Guidelines
   - Include: Branch naming, commit message format, PR guidelines
   - Detect: .github/PULL_REQUEST_TEMPLATE.md, commitlint config

3. Security Guidelines
   - Include: Env file handling, secrets management, input validation
   - Best practices for the detected stack

4. API Documentation
   - Detect: OpenAPI/Swagger specs, Postman collections
   - Include: Documentation conventions and tooling

5. Mobile App Guidelines (if detected)
   - React Native / Flutter specific patterns
   - Platform-specific considerations

6. Monorepo Guidelines (if detected)
   - Nx / Turborepo / Lerna workspace patterns
   - Package management and dependencies

7. System Prompt Alignment (if detected)
   - Document global or editor-level prompts that can override project rules
   - Remind contributors to review and align prompts

8. MCP Servers & Tooling (if detected)
   - List MCP servers and when to use them
   - Include required environment variables or access notes

9. Project Progress Memory (PROGRESS.md)
   - Ask if the team wants `PROGRESS.md` for continuity across tasks
   - Require an `Original Prompt` section so future runs can compare intent vs current status

Select the sections you need (comma-separated numbers, or 'none' to skip):

Reply examples:
- Short: `none`
- Multiple: `1,3,4`
- With extra notes: `2,3,7 (also include branch naming rules)`

Note: In Quick Mode, these optional sections are skipped unless auto-detected with high confidence.

Phase 5: Section Generation

Generate the following sections based on detected stack and user input:

Section 1: Header & Role

# AI Agent Guidelines & Repository Manual

**Role:** You are an expert Senior [DETECTED_ROLE] and Technical Lead.
You are responsible for the entire lifecycle of a task: understanding,
planning, [STACK_SPECIFIC_RESPONSIBILITIES].

Role detection rules:

• Laravel only → "Laravel Backend Engineer"
• Vue/React only → "[Framework] Frontend Engineer"
• Laravel + Vue/React → "Full-Stack Developer"
• Node.js backend → "Node.js Backend Engineer"
• Generic → "Software Engineer"

Section 2: Auto-Pilot Workflow

Generate the 6-step workflow cycle: 1. Discovery & Context - What to read first, where to find docs 2. Plan - How to break down tasks, constraints to check 3. Documentation - When to update docs, what format to use 4. Implementation - Coding standards, patterns to follow 5. Verification & Refinement - Testing, linting, manual checks 6. Self-Review - Checklist of common mistakes to avoid

Each step includes stack-specific instructions from templates.

Section 3: Documentation & Knowledge Base

List paths to important documentation:

## Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

* **[Doc Type]**: `[path/to/doc.md]` ([Brief description])

Auto-detect common paths:

• docs/, documentation/
• README.md, CONTRIBUTING.md
• docs/api/, docs/architecture/
• Important: Do not list CLAUDE.md or AGENTS.md in this section. These files are already loaded by AI tools, and self-references waste context.
• For new docs, prefer YAML frontmatter + Markdown body (headings, tables, examples) so metadata and content stay consistent.

Section 4: Project Structure & Architecture

Map the folder structure with purposes:

## Project Structure & Architecture

* **`[folder/]`**: [Purpose description]

Common patterns to detect:

• MVC structure (controllers, models, views)
• Feature-based modules
• Domain-driven design
• Component-based frontend

Section 5: Development Environment

Based on Phase 3 selection:

## Development Environment

### Container Commands (if Docker)
* App container: `docker compose exec [service] <command>`

### Host Commands
* Git, file operations, IDE commands

### Key Commands
* Format: `[detected formatter command]`
* Test: `[detected test command]`
* Build: `[detected build command]`

Section 6: Coding Standards

Based on detected stack:

## Coding Standards (The "Gold Standard")

* **Language**: [Language] [Version]
* **Framework**: [Framework] [Version]
* **Code Style**: [Style guide/tool]
* **Strictness**: [Type hints, strict mode, etc.]

Include anti-patterns section if applicable:

### Critical Anti-Patterns
- [Stack-specific anti-patterns to avoid]

Section 7: Domain Specifics (Optional)

If the project has specific domain rules detected:

## Domain Specifics & Non-Negotiables

* **[Rule Category]**: [Rule description]

Common domain patterns:

• Multi-tenant applications
• Permission/role systems
• Localization requirements
• Real-time features

Section 8: CI/CD Configuration (Optional)

If user selected or auto-detected:

## CI/CD & Deployment

### Detected Pipelines
* **GitHub Actions**: `.github/workflows/`
* **GitLab CI**: `.gitlab-ci.yml`

### Pipeline Commands
* Run tests: `[detected command]`
* Build: `[detected command]`
* Deploy: `[detected command]`

### Deployment Notes
* [Environment-specific notes]

Section 9: Git Workflow (Optional)

If user selected:

## Git Workflow

### Branch Naming
* Feature: `feature/<ticket>-<description>`
* Bugfix: `fix/<ticket>-<description>`
* Hotfix: `hotfix/<description>`

### Commit Message Format

type(scope): description

[optional body]

Types: `feat`, `fix`, `docs`, `style`, `refactor`, `test`, `chore`

### Pull Request Guidelines
* Reference ticket/issue in description
* Ensure tests pass before requesting review
* Keep PRs focused and reasonably sized

Section 10: Security Guidelines (Optional)

If user selected:

## Security Guidelines

### Environment Variables
* Never commit `.env` files (only `.env.example`)
* Use secrets management for production
* Rotate credentials regularly

### Input Validation
* Validate all user input at boundaries
* Sanitize data before database queries
* Use parameterized queries (ORM handles this)

### Authentication & Authorization
* [Stack-specific auth patterns]
* Always verify permissions before actions

Section 11: API Documentation (Optional)

If detected or user selected:

## API Documentation

### Documentation Location
* OpenAPI Spec: `[path/to/openapi.yaml]`
* Postman Collection: `[path/to/collection.json]`

### Documentation Standards
* Keep API docs in sync with implementation
* Document all endpoints, request/response schemas
* Include example requests and responses

Section 12: Mobile Guidelines (Optional)

If React Native or Flutter detected:

## Mobile Development

### Platform Considerations
* Test on both iOS and Android
* Handle platform-specific UI patterns
* Consider offline functionality

### Build Commands
* iOS: `[build command]`
* Android: `[build command]`

Section 13: Monorepo Guidelines (Optional)

If monorepo detected:

## Monorepo Structure

### Workspace Management
* Package manager: [pnpm/yarn/npm workspaces]
* Build tool: [Nx/Turborepo/Lerna]

### Package Dependencies
* Use workspace protocol for internal packages
* Keep shared dependencies at root level

### Commands
* Build all: `[command]`
* Build affected: `[command]`
* Test affected: `[command]`

Section 14: System Prompt Alignment (Optional)

If global or editor-level prompts were detected or the user requests it:

## System Prompt Alignment

These prompts can override project instructions. Review and align them with this file:

* **Claude Code Global Prompt**: `~/.claude/CLAUDE.md` (review for conflicts)
* **GitHub Copilot**: `.github/copilot-instructions.md` (project scope)
* **Cursor Rules**: `.cursorrules`
* **Cline Rules**: `.clinerules` or `.clinerules/`
* **Kilo Code Rules**: `.kilocoderules` / `.kilo/` / `.kilocodemodes`
* **Roo Code Rules**: `.roo/rules/` / `.roo/rules-*` / `.roorules*`
* **OpenCode Config**: `opencode.jsonc`
* **Codex Project Instructions**: `AGENTS.override.md` / `AGENTS.md`
* **Codex Global Instructions**: `~/.codex/AGENTS.override.md` / `~/.codex/AGENTS.md`
* **Codex Config**: `~/.codex/config.toml`

If any of these conflict with this file, update the global/system prompts first.

### Local AI Tool Folders & Git Hygiene
Remind contributors to keep local AI tool data out of Git:

* Add local folders like `.codex/` and `.claude/` to `.gitignore` because they may contain sensitive prompts, logs, or secrets.
* Put shareable skill packs in `.agents/skills/` so teams can version and share them safely.

Section 15: MCP Servers & Tooling (Optional)

If MCP servers are detected and user opts in:

## MCP Servers & Tooling

Use these MCP servers when the task matches their capability:

* **[server-name]**: [Purpose, when to use it, required env vars]

If a server is not needed for this project, disable it in the MCP config.

Section 16: Project Progress Memory (PROGRESS.md) (Optional)

If the user wants project progress tracking:

## Project Progress Tracking

Use one lightweight progress file that all agents can continue from:

* **Progress**: `PROGRESS.md` (current focus + recent completions)
* **Required field**: `Original Prompt` (copy exact user request that started the task)

At the start of every task, read `PROGRESS.md` first, compare with the active request, and continue unfinished work before starting unrelated changes.

If a memory MCP server is used instead, keep `PROGRESS.md` minimal or omit it.

Phase 6: File Creation/Update

For new files: 1. Write AGENTS.md with generated content. 2. Create CLAUDE.md as a normal text file for Claude Code compatibility. The first line must be:

   @AGENTS.md

3. Do not create a symbolic link between CLAUDE.md and AGENTS.md. Claude Code supports symlinks, but this skill intentionally uses the @AGENTS.md import to avoid duplicate-context behavior in other agents. 4. If the user wants Claude-specific rules, add them below the @AGENTS.md import under a ## Claude Code heading. 5. Do not create AGENTS.override.md by default. Create it only when the user asks for Codex-specific override behavior.

If `AGENTS.override.md` exists or is requested: 1. Treat it as a Codex-only override with higher precedence than AGENTS.md in the same directory. 2. If it exists beside AGENTS.md, warn that Codex ignores that directory's AGENTS.md and reads the override instead. 3. For specialized subprojects, place AGENTS.override.md as close as possible to the files it should govern. 4. Keep override content narrow; common instructions should remain in AGENTS.md. 5. If the project uses project_doc_fallback_filenames, mention that fallback files are checked only after AGENTS.override.md and AGENTS.md.

If an existing `CLAUDE.md` is present without `AGENTS.md`: 1. Ask the user whether to migrate or keep both files. 2. If migrating:

• Back up the existing CLAUDE.md.
• Move or merge its useful guidance into AGENTS.md.
• Replace CLAUDE.md with a normal text file starting with @AGENTS.md.

3. If keeping both:

• Treat AGENTS.md and CLAUDE.md as intentionally separate instruction files.
• Ask which guidance belongs in each file before editing.

For updates (merge mode): 1. Parse the primary existing file (AGENTS.md by default) into sections (split by ## headers) 2. Compare auto-detected findings against existing guidance; if they conflict, ask the user whether to keep existing content, replace it, or merge. 3. For each section:

• If exists in both: Show diff and ask user preference
• If only in existing: Preserve (user customization)
• If only in new: Add with note

4. Generate merged file 5. Show summary of changes 6. Ensure the generated AGENTS.md content does not instruct the agent to read CLAUDE.md or AGENTS.md, since those files are already loaded by AI tools.

Design System Delegation (Skill Reuse Policy)

This skill is intentionally not a full Design System engine. When the user requests any of the following:

• "design system", "UI consistency", "style guide"
• "colors/typography/tokens"
• "component library rules"
• "generate DESIGN_SYSTEM.md"

Then this skill must:

If design-system-generator skill is available:

1. Delegate generation of DESIGN_SYSTEM.md to design-system-generator 2. Then update AGENTS.md/CLAUDE.md to reference DESIGN_SYSTEM.md with this block:

## Design System
All UI components and pages must follow `DESIGN_SYSTEM.md`:
- Use design tokens (no hardcoded colors/sizes).
- Implement component states (hover/focus/disabled/loading/error).
- Meet accessibility and performance requirements.

If design-system-generator is NOT available:

1. Suggest installing design-system-generator from:

• https://github.com/thienanblog/awesome-ai-agent-skills (project-development-skills plugin)

2. Produce only:

• AGENTS.md/CLAUDE.md patch referencing DESIGN_SYSTEM.md
• Optional minimal scaffold DESIGN_SYSTEM.md (no deep recommendations)

Minimal Scaffold for DESIGN_SYSTEM.md (only if design-system-generator unavailable)

If the user still wants a file now, generate ONLY this scaffold:

# DESIGN_SYSTEM.md (Scaffold)

## Scope
Defines UI consistency rules for this project.

## Tokens (TBD)
- Colors: CSS variables
- Typography: scale + line-height
- Spacing: spacing scale
- Radius/Shadows: scales

## Components
Define component patterns and required states:
- hover, focus, disabled, loading, error

## Production assets
Use hashed filenames + a manifest mapping to avoid cache issues.
Minify CSS/JS and optimize images/fonts.

Do not pick Tailwind/MUI/shadcn/etc. in the scaffold unless the project already uses it.

Never implement the full Design System logic inside agents-md-generator.

Tech Stack Detection Reference

See references/tech-stack-detection.md for complete detection patterns.

Section Templates Reference

See references/section-templates.md for complete section templates per stack.

Update/Merge Strategy Reference

See references/merge-strategy.md for detailed merge logic.

Progress Tracking (Maintainers)

When discussing or implementing new ideas/features for this skill, use PROGRESS.md as the single continuity file.

Required PROGRESS.md sections:

• Original Prompt (verbatim user request that initiated the task)
• Current Status (what is done, in progress, blocked)
• Next Steps (clear continuation checklist)

Maintainer workflow: 1. Read PROGRESS.md before starting any task. 2. Compare Original Prompt and Current Status against the new request. 3. Continue unfinished work first when it matches the same objective. 4. Update Current Status and Next Steps before ending the task.

Archiving rule: keep PROGRESS.md readable (about 200-300 lines max). Move old completed entries to docs/archives/PROGRESS-YYYY-MM.md when needed.

Output File Naming

Primary file: AGENTS.md

• This is the main instruction file that AI agents read
• All edits should be made to this file
• Keep it concise; Codex has a combined project-doc size cap (project_doc_max_bytes, 32 KiB by default)
• Use nested AGENTS.md files for subprojects when closer-directory guidance should override broader guidance

Codex override file: AGENTS.override.md

• Higher priority than AGENTS.md for Codex in the same directory
• Use only for Codex-specific, temporary, or nested-directory override rules
• Do not create by default because Codex includes at most one instruction file per directory

Secondary file: CLAUDE.md

• Normal text file for Claude Code compatibility
• First line: @AGENTS.md
• May contain separate Claude-specific guidance only if the user explicitly wants parallel files
• Claude Code expands @AGENTS.md when loading CLAUDE.md

Why this approach:

• Single source of truth prevents drift
• Works across all AI coding tools
• Avoids symbolic links that can cause duplicate context reads
• Lets Claude Code share AGENTS.md through a lightweight file reference

---

This skill is part of the awesome-ai-agent-skills community library.

AI Agent Guidelines & Repository Manual

Role: You are an expert Senior Software Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, implementing, testing, documenting, and reviewing.

1. The "Auto-Pilot" Workflow

For every task, you must strictly follow this cycle. Do not stop at "it works"; stop at "it is production-ready".

1. Discovery & Context:

• Read First: Project configuration files and README
• Check Docs: Consult docs/ for project-specific guidelines
• Scan: Understand existing code patterns before adding new code

2. Plan:

• Break down the request into atomic steps
• Identify which files need creation or modification
• Consider impact on existing functionality

3. Documentation:

• Update documentation when behavior changes
• Add comments for complex logic
• Keep README up to date

4. Implementation:

• Follow existing code patterns and conventions
• Write clean, readable code
• Handle edge cases and errors

5. Verification:

• Test: Run the test suite
• Format: Run code formatter
• Build: Verify the build succeeds

6. Self-Review:

• Did you follow existing patterns?
• Did you handle error cases?
• Did you add/update tests?
• Did you update documentation?

2. Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

• README: README.md (Project overview and setup)
• Contributing: CONTRIBUTING.md (Contribution guidelines)
• Architecture: docs/architecture.md (System design)

3. Project Structure & Architecture

{{PROJECT_STRUCTURE}}

4. Development Environment

{{ENVIRONMENT_SECTION}}

Key Commands

# Install dependencies
{{INSTALL_COMMAND}}

# Start development
{{DEV_COMMAND}}

# Run tests
{{TEST_COMMAND}}

# Build for production
{{BUILD_COMMAND}}

# Format code
{{FORMAT_COMMAND}}

# Lint code
{{LINT_COMMAND}}

5. Coding Standards

• Language: {{LANGUAGE}} {{VERSION}}
• Style Guide: {{STYLE_GUIDE}}
• Formatting: {{FORMATTER}}

Best Practices

• Write self-documenting code with clear naming
• Keep functions small and focused
• Handle errors appropriately
• Write tests for new functionality
• Use version control effectively

Code Review Checklist

• Code follows existing patterns
• Tests are included
• Documentation is updated
• No security vulnerabilities introduced
• Performance considerations addressed

6. Testing

{{TESTING_SECTION}}

Test Categories

• Unit Tests: Test individual functions/classes
• Integration Tests: Test component interactions
• End-to-End Tests: Test complete user flows

7. Git Workflow

• Create feature branches from main
• Write descriptive commit messages
• Keep commits atomic and focused
• Request code reviews before merging

Commit Message Format

type(scope): description

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore

8. Domain Specifics

{{DOMAIN_SECTION}}

--- This file is the primary instruction set for AI agents. If you change project structure or conventions, update this file.

AI Agent Guidelines & Repository Manual

Role: You are an expert Senior Laravel Backend Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, documenting, implementing, and verifying.

1. The "Auto-Pilot" Workflow

For every task, you must strictly follow this cycle. Do not stop at "it works"; stop at "it is production-ready".

1. Discovery & Context:

• Read First: config/app.php and config/settings.php (if exists)
• Check Docs: Consult docs/ for specific guidelines
• Environment: Ensure you are using the correct environment for all runtime commands

2. Plan:

• Break down the request into atomic steps (Migration -> Model -> Service -> Controller)
• Constraint Check: Verify database relationships and validation requirements

3. Documentation (Mandatory Pre-Code):

• Sync Rule: Before writing logic, create or update docs/features/<module>.md
• Requirements: Include API contracts, database schema, and validation rules

4. Implementation:

• Standards: Apply PSR-12 and declare(strict_types=1);
• Migrations: Never edit existing migrations; create new ones
• Validation: Use Form Request classes, not inline validation

5. Verification & Refinement:

• Format: Run vendor/bin/pint immediately after writing code
• Test: Run tests following project testing guidelines
• Manual Check: Verify via Tinker or standalone scripts if needed

6. Self-Review:

• Did you use proper type declarations?
• Did you add validation in Form Requests?
• Did you create/update documentation?
• Did you handle edge cases and errors?

2. Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

• Testing: docs/testing-guidelines.md (Test structure and coverage requirements)
• Documentation: docs/documentation-guidelines.md (How to write feature docs)
• Architecture: docs/architecture.md (System design and patterns)

3. Project Structure & Architecture

• `app/Http/Controllers/`: Feature-grouped controllers. Keep thin, delegate to Services.
• `app/Services/`: Business logic layer. Encapsulate complex operations.
• `app/Models/`: Eloquent models with relationships, scopes, and accessors.
• `app/Http/Resources/`: API response transformers. Collections return pagination metadata.
• `app/Http/Requests/`: Form Request validation classes.
• `routes/api.php`: API routes with middleware.
• `routes/web.php`: Web routes for views.
• `database/migrations/`: Database schema changes (never edit existing).
• `database/factories/`: Model factories for testing.
• `tests/`: Feature and Unit tests.

4. Development Environment

{{ENVIRONMENT_SECTION}}

Key Commands

# Code formatting
{{FORMAT_COMMAND}}

# Run migrations
{{MIGRATE_COMMAND}}

# Run tests
{{TEST_COMMAND}}

# Generate files
{{MAKE_COMMAND}} make:model ModelName -mfs
{{MAKE_COMMAND}} make:controller ControllerName
{{MAKE_COMMAND}} make:request RequestName

5. Coding Standards (The "Gold Standard")

• Language: PHP {{PHP_VERSION}}
• Framework: Laravel {{LARAVEL_VERSION}}
• Strictness: Always use declare(strict_types=1);
• Style: PSR-12, enforced by Laravel Pint

Type Declarations

• Always use explicit return type declarations
• Use appropriate PHP type hints for parameters
• Use PHPDoc for complex array shapes

Database

• Prefer Eloquent over raw queries
• Use Model Scopes for reusable query logic
• Use $fillable or $guarded on all models
• Add database indexes for frequently queried columns

Controllers

• Keep controllers thin - delegate to Services
• Use dependency injection
• Return Resources for API responses

Testing

• Write tests for all new features
• Use factories for test data
• Follow Arrange-Act-Assert pattern

Anti-Patterns to Avoid

• No business logic in controllers
• No raw queries when Eloquent suffices
• No hardcoded configuration values (use config files)
• No direct env() calls outside config files

6. Domain Specifics & Non-Negotiables

{{DOMAIN_SECTION}}

--- This file is the primary instruction set for AI agents. If you change project structure or conventions, update this file.

AI Agent Guidelines & Repository Manual

Role: You are an expert Senior Full-Stack Developer and Technical Lead specializing in Laravel backend and {{FRONTEND_FRAMEWORK}} frontend. You are responsible for the entire lifecycle of a task: understanding, planning, documenting, implementing, testing, and verifying.

1. The "Auto-Pilot" Workflow

For every task, you must strictly follow this cycle. Do not stop at "it works"; stop at "it is production-ready".

1. Discovery & Context:

• Read First: config/app.php, package.json, and project documentation
• Check Docs: Consult docs/ for guidelines and patterns
• Environment: Use appropriate environment for backend vs frontend commands

2. Plan:

• Break down into atomic steps (Migration -> Model -> Controller -> Frontend Component)
• Backend-First: Usually implement API before UI
• API Contract: Define request/response structure before implementation

3. Documentation:

• Sync Rule: Before writing logic, update docs/features/<module>.md
• API Docs: Document endpoints, payloads, and responses

4. Implementation:

• Backend: PSR-12, declare(strict_types=1);, Form Requests
• Frontend: Composition API, typed props, store-based state
• Integration: Use {{INTEGRATION_LIBRARY}} for frontend-backend communication

5. Verification:

• Backend: Run {{BACKEND_TEST_COMMAND}}
• Frontend: Run {{FRONTEND_TEST_COMMAND}}
• Build: Run {{BUILD_COMMAND}} before finalizing

6. Self-Review:

• Did you implement both backend and frontend for the feature?
• Did you add validation on both layers?
• Did you handle loading and error states?
• Did you update documentation?

2. Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

• Testing: docs/testing-guidelines.md
• Documentation: docs/documentation-guidelines.md
• Architecture: docs/architecture.md
• API Standards: docs/api-standards.md
• UI/UX Guidelines: docs/ui-ux-guidelines.md

3. Project Structure & Architecture

Backend (Laravel)

• `app/Http/Controllers/`: API controllers (thin, delegate to Services)
• `app/Services/`: Business logic layer
• `app/Models/`: Eloquent models with relationships
• `app/Http/Resources/`: API response transformers
• `app/Http/Requests/`: Form Request validation
• `routes/api.php`: API endpoints
• `routes/web.php`: Web routes (Inertia pages)

Frontend ({{FRONTEND_FRAMEWORK}})

• `resources/js/Pages/`: {{INTEGRATION_LIBRARY}} page components
• `resources/js/Components/`: Reusable UI components
• `resources/js/Layouts/`: Layout components
• `resources/js/Composables/` or `resources/js/hooks/`: Shared logic
• `resources/js/types/`: TypeScript definitions

4. Development Environment

{{ENVIRONMENT_SECTION}}

Backend Commands

# Format PHP code
{{PHP_FORMAT_COMMAND}}

# Run migrations
{{MIGRATE_COMMAND}}

# Run PHP tests
{{PHP_TEST_COMMAND}}

# Generate files
{{MAKE_COMMAND}} make:model ModelName -mfs
{{MAKE_COMMAND}} make:controller Api/ControllerName

Frontend Commands

# Install dependencies
{{NPM_INSTALL_COMMAND}}

# Start dev server
{{NPM_DEV_COMMAND}}

# Build for production
{{NPM_BUILD_COMMAND}}

# Run frontend tests
{{NPM_TEST_COMMAND}}

5. Coding Standards (The "Gold Standard")

Backend (PHP/Laravel)

• Language: PHP {{PHP_VERSION}}
• Framework: Laravel {{LARAVEL_VERSION}}
• Strictness: declare(strict_types=1);
• Style: PSR-12, Laravel Pint

Frontend ({{FRONTEND_FRAMEWORK}})

• Framework: {{FRONTEND_FRAMEWORK}} {{FRONTEND_VERSION}}
• Integration: {{INTEGRATION_LIBRARY}} {{INTEGRATION_VERSION}}
• Styling: {{CSS_FRAMEWORK}} {{CSS_VERSION}}
• Style: ESLint + Prettier

Integration Patterns

API Responses

Return consistent response structures:

return new UserResource($user);  // Single resource
return UserResource::collection($users);  // Collection with pagination

Frontend Data Fetching

Use {{INTEGRATION_LIBRARY}} for data:

// Props from controller
defineProps<{
  users: Paginated<User>
}>()

// Forms
const form = useForm({
  name: '',
  email: ''
})

Anti-Patterns to Avoid

• Backend: No business logic in controllers, no raw queries
• Frontend: No direct API calls in components, no prop drilling
• Integration: Always validate on both layers

6. Inertia.js / Livewire Patterns

{{INTEGRATION_PATTERNS_SECTION}}

7. Domain Specifics

{{DOMAIN_SECTION}}

--- This file is the primary instruction set for AI agents. If you change project structure or conventions, update this file.

AI Agent Guidelines & Repository Manual

Role: You are an expert Senior Node.js Backend Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, implementing, testing, documenting, and reviewing.

1. The "Auto-Pilot" Workflow

For every task, you must strictly follow this cycle. Do not stop at "it works"; stop at "it is production-ready".

1. Discovery & Context:

• Read First: package.json, tsconfig.json, and environment configuration
• Check Docs: Consult docs/ for API specifications and patterns
• Environment: Verify environment variables and dependencies

2. Plan:

• Break down into atomic steps (Schema -> Model -> Service -> Controller -> Route)
• API Design: Define endpoints and payloads before implementation
• Error Handling: Plan error responses and edge cases

3. Documentation:

• Sync Rule: Update docs/api/<resource>.md before implementation
• OpenAPI: Keep API specs in sync with implementation

4. Implementation:

• TypeScript: Strict typing for all modules
• Async/Await: Proper error handling with try/catch
• Validation: Validate all inputs at the boundary

5. Verification:

• Test: Run {{TEST_COMMAND}}
• Type Check: Run {{TYPECHECK_COMMAND}}
• Lint: Run {{LINT_COMMAND}}

6. Self-Review:

• Did you handle all error cases?
• Did you validate inputs properly?
• Did you add proper logging?
• Did you write tests for the new code?

2. Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

• API Design: docs/api-design.md (Endpoint conventions)
• Error Handling: docs/error-handling.md (Error response patterns)
• Database: docs/database.md (Schema and query patterns)
• Testing: docs/testing.md (Test structure and conventions)

3. Project Structure & Architecture

• `src/controllers/`: Request handlers (thin, delegate to services)
• `src/services/`: Business logic layer
• `src/models/`: Database models/schemas
• `src/routes/`: Route definitions and middleware
• `src/middleware/`: Express/Fastify middleware
• `src/utils/`: Utility functions
• `src/types/`: TypeScript type definitions
• `src/config/`: Configuration management
• `src/validators/`: Input validation schemas
• `tests/`: Test files (mirrors src structure)

Architecture Pattern:

Request -> Route -> Middleware -> Controller -> Service -> Model -> Database

4. Development Environment

{{ENVIRONMENT_SECTION}}

Key Commands

# Install dependencies
{{INSTALL_COMMAND}}

# Start dev server
{{DEV_COMMAND}}

# Run tests
{{TEST_COMMAND}}

# Type check
{{TYPECHECK_COMMAND}}

# Build for production
{{BUILD_COMMAND}}

# Lint
{{LINT_COMMAND}}

# Database operations
{{DB_MIGRATE_COMMAND}}
{{DB_SEED_COMMAND}}

5. Coding Standards (The "Gold Standard")

• Runtime: Node.js {{NODE_VERSION}}
• Language: TypeScript (strict mode)
• Framework: {{FRAMEWORK}} {{FRAMEWORK_VERSION}}
• Style: ESLint + Prettier

TypeScript Configuration

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true
  }
}

Controller Pattern

// Controllers should be thin
export class UserController {
  constructor(private userService: UserService) {}

  async getUser(req: Request, res: Response) {
    try {
      const user = await this.userService.findById(req.params.id);
      res.json({ data: user });
    } catch (error) {
      next(error);
    }
  }
}

Service Pattern

// Services contain business logic
export class UserService {
  constructor(private userRepository: UserRepository) {}

  async findById(id: string): Promise<User | null> {
    return this.userRepository.findById(id);
  }

  async create(data: CreateUserDto): Promise<User> {
    // Validation, business rules, etc.
    return this.userRepository.create(data);
  }
}

Error Handling

// Custom error classes
export class NotFoundError extends Error {
  status = 404;
  constructor(resource: string) {
    super(`${resource} not found`);
  }
}

// Global error handler middleware
app.use((error: Error, req: Request, res: Response, next: NextFunction) => {
  const status = error instanceof AppError ? error.status : 500;
  res.status(status).json({
    error: error.message,
    status
  });
});

Validation

// Use Zod/Joi for input validation
import { z } from 'zod';

const CreateUserSchema = z.object({
  email: z.string().email(),
  name: z.string().min(1).max(100),
  password: z.string().min(8)
});

// Validate in middleware or controller
const validated = CreateUserSchema.parse(req.body);

Anti-Patterns to Avoid

• No `any` Types: Use proper TypeScript types
• No Callback Hell: Use async/await
• No Unhandled Promises: Always catch errors
• No Business Logic in Controllers: Delegate to services
• No Hardcoded Config: Use environment variables via config

6. Database Patterns

ORM Usage ({{ORM_NAME}})

// Repository pattern for database access
export class UserRepository {
  async findById(id: string): Promise<User | null> {
    return this.model.findUnique({ where: { id } });
  }

  async create(data: CreateUserDto): Promise<User> {
    return this.model.create({ data });
  }
}

Migrations

# Create migration
{{DB_MIGRATE_CREATE_COMMAND}}

# Run migrations
{{DB_MIGRATE_COMMAND}}

# Rollback
{{DB_ROLLBACK_COMMAND}}

7. Testing Patterns

// Unit test example
describe('UserService', () => {
  let service: UserService;
  let mockRepository: jest.Mocked<UserRepository>;

  beforeEach(() => {
    mockRepository = createMockRepository();
    service = new UserService(mockRepository);
  });

  it('should find user by id', async () => {
    mockRepository.findById.mockResolvedValue(mockUser);
    const result = await service.findById('1');
    expect(result).toEqual(mockUser);
  });
});

// Integration test example
describe('POST /users', () => {
  it('should create a user', async () => {
    const response = await request(app)
      .post('/users')
      .send({ name: 'Test', email: 'test@example.com' });

    expect(response.status).toBe(201);
    expect(response.body.data.name).toBe('Test');
  });
});

8. Domain Specifics

{{DOMAIN_SECTION}}

--- This file is the primary instruction set for AI agents. If you change project structure or conventions, update this file.

AI Agent Guidelines & Repository Manual

Role: You are an expert Senior Python Backend Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, implementing, testing, documenting, and reviewing.

1. The "Auto-Pilot" Workflow

For every task, you must strictly follow this cycle. Do not stop at "it works"; stop at "it is production-ready".

1. Discovery & Context:

• Read First: pyproject.toml, requirements.txt, and project configuration
• Check Docs: Consult docs/ for project-specific guidelines
• Environment: Ensure you are using the correct virtual environment

2. Plan:

• Break down into atomic steps (Model -> Schema -> Service -> Route/View)
• API Design: Define endpoints and data structures before implementation
• Database: Plan migrations and model relationships

3. Documentation:

• Docstrings: Add Google/NumPy style docstrings to all functions and classes
• API Docs: Update OpenAPI/Swagger documentation if applicable
• README: Keep setup instructions current

4. Implementation:

• Type Hints: Use type annotations for all function signatures
• PEP 8: Follow Python style guidelines
• SOLID: Apply design principles appropriately

5. Verification:

• Test: Run {{TEST_COMMAND}}
• Type Check: Run {{TYPECHECK_COMMAND}} (mypy/pyright)
• Lint: Run {{LINT_COMMAND}} (ruff/flake8/pylint)
• Format: Run {{FORMAT_COMMAND}} (black/ruff format)

6. Self-Review:

• Did you add type hints to all functions?
• Did you write tests for the new code?
• Did you handle exceptions properly?
• Did you update documentation?

2. Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

• API Design: docs/api.md (Endpoint conventions and schemas)
• Database: docs/database.md (Models and migrations)
• Testing: docs/testing.md (Test structure and conventions)
• Architecture: docs/architecture.md (System design)

3. Project Structure & Architecture

Django Project

• `project/settings/`: Configuration (base, dev, prod)
• `apps/`: Django applications (one per domain)
• `apps/<app>/models.py`: Database models
• `apps/<app>/views.py` or `apps/<app>/api/`: Views/ViewSets
• `apps/<app>/serializers.py`: DRF serializers
• `apps/<app>/services.py`: Business logic layer
• `apps/<app>/tests/`: App-specific tests
• `templates/`: Django templates (if server-rendered)
• `static/`: Static files

Flask/FastAPI Project

• `app/` or `src/`: Main application package
• `app/models/`: Database models (SQLAlchemy/etc.)
• `app/routes/` or `app/api/`: Route handlers
• `app/services/`: Business logic
• `app/schemas/`: Pydantic models (FastAPI) or Marshmallow schemas
• `app/core/`: Core configuration and dependencies
• `tests/`: Test directory
• `migrations/`: Alembic migrations

4. Development Environment

{{ENVIRONMENT_SECTION}}

Key Commands

# Create/activate virtual environment
{{VENV_CREATE_COMMAND}}
{{VENV_ACTIVATE_COMMAND}}

# Install dependencies
{{INSTALL_COMMAND}}

# Run development server
{{DEV_COMMAND}}

# Run tests
{{TEST_COMMAND}}

# Type checking
{{TYPECHECK_COMMAND}}

# Linting and formatting
{{LINT_COMMAND}}
{{FORMAT_COMMAND}}

# Database migrations
{{MIGRATE_COMMAND}}
{{MAKEMIGRATIONS_COMMAND}}

5. Coding Standards (The "Gold Standard")

• Language: Python {{PYTHON_VERSION}}
• Framework: {{FRAMEWORK}} {{FRAMEWORK_VERSION}}
• Style: PEP 8, enforced by {{LINTER}}
• Formatting: {{FORMATTER}}
• Type Checking: {{TYPE_CHECKER}}

Type Hints

from typing import Optional, List

def get_user(user_id: int) -> Optional[User]:
    """Retrieve a user by ID."""
    return User.query.get(user_id)

def list_users(active: bool = True) -> List[User]:
    """List all users, optionally filtered by status."""
    query = User.query
    if active:
        query = query.filter(User.is_active == True)
    return query.all()

Docstrings (Google Style)

def process_order(order_id: int, validate: bool = True) -> Order:
    """Process an order and update its status.

    Args:
        order_id: The unique identifier of the order.
        validate: Whether to validate before processing.

    Returns:
        The processed Order object.

    Raises:
        OrderNotFoundError: If the order doesn't exist.
        ValidationError: If validation fails.
    """
    ...

Exception Handling

# Define custom exceptions
class OrderNotFoundError(Exception):
    """Raised when an order cannot be found."""
    pass

# Handle exceptions properly
try:
    order = get_order(order_id)
except OrderNotFoundError:
    logger.warning(f"Order {order_id} not found")
    raise HTTPException(status_code=404, detail="Order not found")

Database Patterns

Django ORM

# Use select_related/prefetch_related to avoid N+1
users = User.objects.select_related('profile').prefetch_related('orders')

# Use managers for reusable queries
class ActiveUserManager(models.Manager):
    def get_queryset(self):
        return super().get_queryset().filter(is_active=True)

SQLAlchemy

# Use eager loading
users = session.query(User).options(
    joinedload(User.profile),
    selectinload(User.orders)
).all()

# Use repository pattern for complex queries
class UserRepository:
    def get_active_users(self) -> List[User]:
        return self.session.query(User).filter(User.is_active == True).all()

Anti-Patterns to Avoid

• No bare except: Always catch specific exceptions
• No mutable default arguments: Use None and set inside function
• No business logic in views/routes: Delegate to services
• No hardcoded secrets: Use environment variables
• No `print()` for logging: Use the logging module

6. Testing Patterns

pytest Structure

# tests/test_users.py
import pytest
from app.services import UserService

class TestUserService:
    @pytest.fixture
    def user_service(self, db_session):
        return UserService(db_session)

    def test_create_user(self, user_service):
        user = user_service.create(name="Test", email="test@example.com")
        assert user.id is not None
        assert user.name == "Test"

    def test_create_user_duplicate_email(self, user_service):
        user_service.create(name="Test", email="test@example.com")
        with pytest.raises(DuplicateEmailError):
            user_service.create(name="Test2", email="test@example.com")

Django Tests

from django.test import TestCase
from rest_framework.test import APITestCase

class UserAPITestCase(APITestCase):
    def setUp(self):
        self.user = User.objects.create_user(
            username='testuser',
            email='test@example.com'
        )

    def test_list_users(self):
        response = self.client.get('/api/users/')
        self.assertEqual(response.status_code, 200)

Test Coverage

# Run with coverage
pytest --cov=app --cov-report=html

# Minimum coverage threshold
pytest --cov=app --cov-fail-under=80

7. API Patterns

FastAPI Example

from fastapi import APIRouter, Depends, HTTPException
from app.schemas import UserCreate, UserResponse
from app.services import UserService

router = APIRouter(prefix="/users", tags=["users"])

@router.post("/", response_model=UserResponse, status_code=201)
async def create_user(
    user_data: UserCreate,
    service: UserService = Depends(get_user_service)
):
    return await service.create(user_data)

Django REST Framework Example

from rest_framework import viewsets, status
from rest_framework.response import Response
from .serializers import UserSerializer
from .services import UserService

class UserViewSet(viewsets.ModelViewSet):
    serializer_class = UserSerializer

    def create(self, request):
        serializer = self.get_serializer(data=request.data)
        serializer.is_valid(raise_exception=True)
        user = UserService.create_user(serializer.validated_data)
        return Response(
            UserSerializer(user).data,
            status=status.HTTP_201_CREATED
        )

8. Domain Specifics

{{DOMAIN_SECTION}}

--- This file is the primary instruction set for AI agents. If you change project structure or conventions, update this file.

AI Agent Guidelines & Repository Manual

Role: You are an expert Senior React Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, implementing, testing, documenting, and reviewing.

1. The "Auto-Pilot" Workflow

For every task, you must strictly follow this cycle. Do not stop at "it works"; stop at "it is production-ready".

1. Discovery & Context:

• Read First: package.json, tsconfig.json, and folder structures
• Check Docs: Consult component documentation and coding guidelines
• Scan: Check src/components/ for reusable components before creating new ones

2. Plan:

• Break down the request into atomic steps
• Identify which files need creation or modification
• Consider component hierarchy and state management needs

3. Implementation:

• Functional Components: Use hooks, avoid class components
• TypeScript: Strict typing for props, state, and functions
• Formatting: Always format code with Prettier

4. Verification:

• Test: Run {{TEST_COMMAND}}
• Type Check: Run {{TYPECHECK_COMMAND}}
• Build Check: Run {{BUILD_COMMAND}} for production build

5. Documentation:

• Add JSDoc comments to exported functions
• Update component documentation if behavior changes

6. Self-Review:

• Did you use proper TypeScript types (no any)?
• Did you handle loading and error states?
• Did you memoize expensive computations?
• Did you avoid prop drilling?

2. Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

• Design System: docs/design-system.md (Colors, components, layouts)
• Component Guide: docs/components.md (Reusable component catalog)
• State Management: docs/state-management.md (State patterns)
• Testing Guide: docs/testing.md (Testing conventions)

3. Project Structure & Architecture

• `src/components/`: Reusable UI components
• `src/pages/`: Page-level components (for routing)
• `src/hooks/`: Custom React hooks
• `src/context/`: React Context providers
• `src/services/` or `src/api/`: API service layer
• `src/stores/`: State management (Zustand/Redux)
• `src/utils/`: Utility functions
• `src/types/`: TypeScript type definitions
• `src/styles/`: Global styles

Naming Conventions:

• Components: PascalCase (UserCard.tsx)
• Hooks: camelCase with use prefix (useAuth.ts)
• Utils: camelCase (formatDate.ts)
• Types: PascalCase with descriptive names (UserProfile.ts)

4. Development Environment

{{ENVIRONMENT_SECTION}}

Key Commands

# Install dependencies
{{INSTALL_COMMAND}}

# Start dev server
{{DEV_COMMAND}}

# Run tests
{{TEST_COMMAND}}

# Type check
{{TYPECHECK_COMMAND}}

# Build for production
{{BUILD_COMMAND}}

# Lint and format
{{LINT_COMMAND}}

5. Coding Standards (The "Gold Standard")

• Framework: React {{REACT_VERSION}}
• Language: TypeScript (strict mode)
• Build Tool: {{BUILD_TOOL}}
• Styling: {{CSS_FRAMEWORK}}
• Code Style: ESLint + Prettier

Component Guidelines

• Functional components with hooks only
• Props interfaces defined explicitly with TypeScript
• Prefer named exports over default exports
• Co-locate styles with components when possible

TypeScript Rules

• No any types (use unknown if type is truly unknown)
• Explicit return types on exported functions
• Interface over type for object shapes
• Use generics for reusable type patterns

State Management

• Server State: React Query / TanStack Query
• Client State: Zustand, Jotai, or Context
• Form State: React Hook Form
• Local State: useState for component-specific data

Hooks Guidelines

// Custom hooks should:
// 1. Start with 'use'
// 2. Be pure functions
// 3. Handle their own cleanup

function useUser(id: string) {
  const { data, isLoading, error } = useQuery({
    queryKey: ['user', id],
    queryFn: () => fetchUser(id)
  });
  return { user: data, isLoading, error };
}

Critical Anti-Patterns

• No `any` Types: Use proper TypeScript types
• No Prop Drilling: Use Context or state management for deep props
• No Direct DOM Manipulation: Use refs and React's declarative approach
• No Inline Functions in JSX: Extract to useCallback for performance
• No Business Logic in Components: Extract to hooks or services

6. Performance Patterns

// Memoize expensive components
const MemoizedComponent = React.memo(Component);

// Memoize callbacks
const handleClick = useCallback(() => {
  // handler logic
}, [dependencies]);

// Memoize computed values
const expensiveValue = useMemo(() => {
  return computeExpensiveValue(data);
}, [data]);

7. Testing Patterns

// Component tests with Testing Library
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('renders user name', async () => {
  render(<UserCard user={mockUser} />);
  expect(screen.getByText(mockUser.name)).toBeInTheDocument();
});

// Hook tests
import { renderHook, waitFor } from '@testing-library/react';

test('fetches user data', async () => {
  const { result } = renderHook(() => useUser('1'));
  await waitFor(() => {
    expect(result.current.user).toBeDefined();
  });
});

8. Domain Specifics

{{DOMAIN_SECTION}}

--- This file is the primary instruction set for AI agents. If you change project structure or conventions, update this file.

AI Agent Guidelines & Repository Manual

Role: You are an expert Senior Vue.js Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, implementing, testing, documenting, and reviewing.

1. The "Auto-Pilot" Workflow

For every task, you must strictly follow this cycle. Do not stop at "it works"; stop at "it is production-ready".

1. Discovery & Context:

• Read First: package.json and folder structures
• Check Docs: Consult component documentation and style guides
• Scan: Check src/components/ for reusable components before creating new ones

2. Plan:

• Break down the request into atomic steps
• Identify which files need creation or modification
• Check shared components before building new UI pieces

3. Implementation:

• Surgical Editing: Make focused changes
• Composition API: Use <script setup> syntax
• Formatting: Always format touched files with Prettier/ESLint

4. Verification:

• Test: Run {{TEST_COMMAND}} for component tests
• Build Check: If changing core configs, run {{BUILD_COMMAND}}
• Linting: Ensure ESLint passes

5. Documentation:

• Update component documentation if behavior changes
• Add JSDoc comments to exported functions

6. Self-Review:

• Did you avoid prop drilling (3+ component layers)?
• Did you use stores for shared state?
• Did you avoid direct API calls in components?
• Did you check for existing components before creating new ones?

2. Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

• Design System: docs/design-system.md (Colors, components, layouts)
• Component Guide: docs/components.md (Reusable component catalog)
• State Management: docs/state-management.md (Store patterns)

3. Project Structure & Architecture

• `src/components/`: Reusable UI components
• `src/views/` or `src/pages/`: Page-level components
• `src/stores/`: Pinia stores for state management
• `src/composables/`: Reusable composition functions
• `src/services/` or `src/api/`: API service layer
• `src/assets/`: Static assets (images, fonts)
• `src/styles/`: Global styles and variables
• `src/router/`: Vue Router configuration
• `src/types/`: TypeScript type definitions

Organization Rules:

• Flat: For small modules (<10 files)
• Folder-based: For large modules (forms/, display/, items/)
• Naming: ModuleName + Function (e.g., OrderBasicForm.vue)

4. Development Environment

{{ENVIRONMENT_SECTION}}

Key Commands

# Install dependencies
{{INSTALL_COMMAND}}

# Start dev server
{{DEV_COMMAND}}

# Run tests
{{TEST_COMMAND}}

# Build for production
{{BUILD_COMMAND}}

# Lint and format
{{LINT_COMMAND}}

5. Coding Standards (The "Gold Standard")

• Framework: Vue {{VUE_VERSION}} (Composition API)
• Build Tool: {{BUILD_TOOL}}
• UI Library: {{UI_LIBRARY}}
• Style: ESLint + Prettier

Component Guidelines

• Use <script setup> syntax
• Props should have type definitions with defineProps<T>()
• Emit events with defineEmits<T>()
• Use ref() and reactive() appropriately

State Management (Pinia)

• Complex Features: Create a dedicated Pinia Store
• Isolated Components: Use local state for reusable UI atoms
• API Calls: Handle in stores or composables, not components

Styling

• Use {{CSS_FRAMEWORK}} for styling
• Follow existing class naming conventions
• Support dark mode if project requires it

Critical Anti-Patterns

• Prop Drilling: Do not pass data through 3+ component layers. Use stores.
• Direct API Calls in Components: NEVER call axios/fetch inside .vue files. Use stores/services.
• Hardcoded Text: Use i18n for user-facing text if applicable
• Logic in Templates: Complex logic should be in computed properties or methods

6. Debug & Telemetry

When debugging, use Vue Devtools and inject debug panels:

<template>
  <Accordion v-if="isDev">
    <AccordionTab header="Debug Data">
      <pre>{{ JSON.stringify(debugData, null, 2) }}</pre>
    </AccordionTab>
  </Accordion>
</template>

7. Domain Specifics

{{DOMAIN_SECTION}}

--- This file is the primary instruction set for AI agents. If you change project structure or conventions, update this file.

PROGRESS — agents-md-generator

This progress log tracks current and recently completed work for the agents-md-generator skill.

Rules:

• When new ideas/features are discussed, update both PROGRESS.md and ROADMAP.md.
• When a task is completed, update both files.
• Keep this file ~200–300 lines max; if it exceeds, archive oldest entries to docs/archives/PROGRESS-YYYY-MM.md.

Current Focus

• Maintenance: Keep roadmap/progress in sync with feature discussions and shipped updates.

Done (Most Recent First)

• 2026-01-22 — Added scripted detection of AI tool prompts, MCP servers, and optional prompt-alignment/memory sections; added skill duplicate scan and reference updates.
• 2026-01-09 — Standardized multi-choice prompts to include explicit reply examples (while still allowing full-sentence answers).
• 2026-01-09 — Improved question prompts with optional compact reply examples (e.g., 1a 2b 3c) and documented a maintainer workflow that runs the archive helper scripts.
• 2026-01-09 — Added terminal-aware launcher + Windows .cmd wrapper to pick the best archiving tool (PowerShell vs bash).
• 2026-01-09 — Added helper scripts to archive ROADMAP.md/PROGRESS.md (bash + PowerShell).
• 2026-01-09 — Added ROADMAP.md and PROGRESS.md for the skill, including archiving rules.

Merge Strategy Reference

This document defines how to update existing AGENTS.md/CLAUDE.md files while preserving user customizations.

Overview

When a user requests an update to an existing instruction file, the merge strategy must: 1. Preserve custom content the user has added 2. Update outdated information with new detections 3. Add new sections that don't exist 4. Provide clear conflict resolution

Default to AGENTS.md as the primary file. CLAUDE.md should be treated as a secondary Claude Code compatibility file unless the user explicitly wants separate Claude-specific guidance.

File Parsing

Section Detection

Parse the existing file into sections using ## (h2) headers as delimiters:

// Pseudo-code for parsing
function parseIntoSections(content) {
  const sections = {};
  const lines = content.split('\n');
  let currentSection = 'header';
  let currentContent = [];

  for (const line of lines) {
    if (line.startsWith('## ')) {
      // Save previous section
      sections[currentSection] = currentContent.join('\n');
      // Start new section
      currentSection = normalizeHeaderName(line);
      currentContent = [line];
    } else {
      currentContent.push(line);
    }
  }
  // Save last section
  sections[currentSection] = currentContent.join('\n');

  return sections;
}

Standard Section Names

Map common variations to standard names:

Merge Modes

Mode 1: Section-Level Merge (Default)

Compare sections individually and decide per-section:

For each section:
  IF section exists in BOTH existing AND new:
    -> Compare content
    -> If identical: Keep as-is
    -> If different: Ask user preference (see Conflict Resolution)

  IF section exists ONLY in existing:
    -> Preserve (user customization)
    -> Mark with comment: <!-- Preserved from previous version -->

  IF section exists ONLY in new:
    -> Add to output
    -> Mark with comment: <!-- Added by generator -->

Mode 2: Smart Merge (Line-Level)

For sections that exist in both versions, perform line-level analysis:

1. Identify "generated" vs "custom" content:
   - Generated: Matches template patterns exactly
   - Custom: User-added bullet points, rules, or text

2. Merge strategy:
   - Keep ALL custom content
   - Update generated content with new values
   - Add new generated content at appropriate positions

Mode 3: Full Replace (User-Requested)

When user explicitly requests full replacement: 1. Create backup of the primary file: AGENTS.md.backup 2. Generate completely new file 3. Show diff summary to user

Conflict Resolution

Presenting Conflicts

When content differs, present to user:

Section "Development Environment" has differences:

EXISTING:

docker compose exec app php artisan migrate docker compose exec app vendor/bin/pint

NEW (detected):

docker compose exec php php artisan migrate docker compose exec php ./vendor/bin/pint

Options:
1. Keep existing (preserve your customizations)
2. Use new (update to detected values)
3. Merge (keep both, you'll edit manually)
4. Skip (leave this section unchanged, continue)

Auto-Resolution Rules

Some conflicts can be auto-resolved:

Customization Detection

Markers for Custom Content

Look for these patterns to identify user customizations:

<!-- CUSTOM: reason -->
Content here
<!-- /CUSTOM -->

<!-- User-added section -->

<!-- Do not auto-update this section -->

# My Custom Section
(Any section not in standard template)

Implicit Custom Content

Content is likely custom if: 1. Not present in any template file 2. Added after initial generation date (if tracked) 3. Contains project-specific terminology not in detection 4. Has different formatting than templates

Merge Algorithm

def merge_files(existing: dict, new: dict) -> dict:
    result = {}
    conflicts = []

    # 1. Process header
    result['header'] = merge_header(existing.get('header'), new.get('header'))

    # 2. Process standard sections in order
    for section in STANDARD_SECTIONS:
        existing_content = existing.get(section)
        new_content = new.get(section)

        if existing_content and new_content:
            if content_is_same(existing_content, new_content):
                result[section] = existing_content
            else:
                conflicts.append({
                    'section': section,
                    'existing': existing_content,
                    'new': new_content
                })
        elif existing_content:
            result[section] = existing_content  # Preserve
        elif new_content:
            result[section] = new_content  # Add new

    # 3. Preserve custom sections
    for section, content in existing.items():
        if section not in STANDARD_SECTIONS and section not in result:
            result[section] = content

    # 4. Process footer
    result['footer'] = merge_footer(existing.get('footer'), new.get('footer'))

    return result, conflicts

Output Format

Updated File Structure

# AI Agent Guidelines & Repository Manual

**Role:** [Updated or preserved role]

<!-- Last updated: YYYY-MM-DD by agents-md-generator -->
<!-- Sections marked with 'Preserved' contain user customizations -->

## 1. The "Auto-Pilot" Workflow
[Content]

## 2. Documentation & Knowledge Base
<!-- Preserved from previous version -->
[User's custom documentation paths]

## 3. Project Structure & Architecture
[Updated structure from new scan]

## 4. Development Environment
[Content]

## 5. Coding Standards
[Content]

## 6. Domain Specifics
<!-- Preserved from previous version -->
[User's custom domain rules]

## 7. My Custom Section
<!-- User-added section (preserved) -->
[User's custom content]

---
*This file is the primary instruction set for AI agents.*

Change Summary

After merge, provide summary:

Update Summary:
--------------
Sections updated: 3
  - Workflow: Version numbers updated
  - Structure: New folders detected
  - Environment: Container name changed

Sections preserved: 2
  - Documentation: Custom paths kept
  - Domain Specifics: Custom rules kept

Sections added: 0

Conflicts resolved: 1
  - Environment: User chose 'Keep existing'

Custom sections preserved: 1
  - My Custom Section

Total changes: 4 lines added, 2 lines modified, 0 lines removed

Backup Strategy

Before Any Merge

1. Create timestamped backup:

   AGENTS.md.backup.2024-01-15T10-30-00

2. Keep last 3 backups, remove older ones

3. If merge fails, offer restore:

   Merge failed. Would you like to:
   1. Restore from backup
   2. Keep partial merge
   3. Start fresh

Backup Location Options

Option 1: Same directory (default)
  AGENTS.md.backup

Option 2: Hidden backup directory
  .agent-instructions-backups/
    AGENTS.md.2024-01-15

Option 3: Git-based (if git repo)
  Commit current state before changes
  User can git checkout to restore

Edge Cases

Empty Sections

If a section exists but is empty:

• Existing empty + New has content = Use new
• Existing has content + New empty = Preserve existing (warn user)
• Both empty = Remove section

Malformed Files

If existing file has parsing errors: 1. Attempt best-effort parse 2. Show warning to user 3. Offer options:

• Continue with partial merge
• Full replace (with backup)
• Cancel and let user fix manually

Very Large Files

If file exceeds reasonable size (>500 lines): 1. Warn user about large file 2. Offer section-by-section review 3. Show progress during merge

No Standard Sections Found

If existing file doesn't match expected structure: 1. Treat entire file as "custom content" 2. Place at end of new generated file 3. Ask user to reorganize manually

Section Templates Reference

This document provides complete templates for each standard section of AGENTS.md/CLAUDE.md instruction files. Use these as building blocks when generating instruction files.

Section 1: Header & Role

Laravel Backend Engineer

# AI Agent Guidelines & Repository Manual

**Role:** You are an expert Senior Laravel Backend Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, documenting, implementing, and verifying.

Vue.js Frontend Engineer

# AI Agent Guidelines & Repository Manual

**Role:** You are an expert Senior Vue.js Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, implementing, testing, documenting, and reviewing.

React Frontend Engineer

# AI Agent Guidelines & Repository Manual

**Role:** You are an expert Senior React Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, implementing, testing, documenting, and reviewing.

Full-Stack Developer (Laravel + Vue/React)

# AI Agent Guidelines & Repository Manual

**Role:** You are an expert Senior Full-Stack Developer and Technical Lead specializing in Laravel backend and [Vue.js/React] frontend. You are responsible for the entire lifecycle of a task: understanding, planning, documenting, implementing, testing, and verifying.

Node.js Backend Engineer

# AI Agent Guidelines & Repository Manual

**Role:** You are an expert Senior Node.js Backend Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, implementing, testing, documenting, and reviewing.

Generic Software Engineer

# AI Agent Guidelines & Repository Manual

**Role:** You are an expert Senior Software Engineer and Technical Lead. You are responsible for the entire lifecycle of a task: understanding, planning, implementing, testing, documenting, and reviewing.

---

Section 2: Auto-Pilot Workflow

Standard 6-Step Cycle (Adapt per stack)

## The "Auto-Pilot" Workflow

For every task, you must strictly follow this cycle. Do not stop at "it works"; stop at "it is production-ready".

1. **Discovery & Context**:
   - **Read First**: [PRIMARY_CONFIG_FILE]
   - **Check Docs**: Consult [DOCS_PATH] for specific guidelines
   - **Environment**: [ENVIRONMENT_INSTRUCTIONS]

2. **Plan**:
   - Break down the request into atomic steps ([EXAMPLE_STEPS])
   - **Constraint Check**: [PROJECT_SPECIFIC_CONSTRAINTS]

3. **Documentation (Mandatory Pre-Code)**:
   - **Sync Rule**: Before writing logic, create or update [DOC_PATH]
   - **Requirements**: [DOC_REQUIREMENTS]

4. **Implementation**:
   - **Standards**: [CODING_STANDARDS]
   - **Patterns**: [ARCHITECTURE_PATTERNS]
   - [ADDITIONAL_IMPLEMENTATION_RULES]

5. **Verification & Refinement**:
   - **Format**: Run [FORMATTER_COMMAND] immediately after writing code
   - **Test**: [TEST_COMMAND_AND_GUIDELINES]
   - **Manual Check**: [MANUAL_VERIFICATION_APPROACH]

6. **Self-Review**:
   - [SELF_REVIEW_CHECKLIST]

Laravel-Specific Steps

1. **Discovery & Context**:
   - **Read First**: `config/settings.php` or `config/app.php`
   - **Check Docs**: Consult `docs/` for specific guidelines
   - **Environment**: Ensure you are using the Docker container for all runtime commands

2. **Plan**:
   - Break down the request into atomic steps (Migration -> Model -> Service -> Controller)
   - **Constraint Check**: Verify database relationships and validation rules

3. **Documentation**:
   - **Sync Rule**: Before writing logic, create or update `docs/features/<module>.md`
   - **Requirements**: Include API contracts and database schema changes

4. **Implementation**:
   - **Standards**: Apply PSR-12 and `declare(strict_types=1);`
   - **Migrations**: Never edit existing migrations; create new ones

5. **Verification & Refinement**:
   - **Format**: Run `vendor/bin/pint` immediately after writing code
   - **Test**: Run `php artisan test` or `vendor/bin/pest`

6. **Self-Review**:
   - Did you use proper type declarations?
   - Did you add validation in Form Requests?
   - Did you handle edge cases?

Vue.js-Specific Steps

1. **Discovery & Context**:
   - **Read First**: `package.json` and folder structures
   - **Check Docs**: Consult component documentation and style guides
   - **Scan**: Check existing components before creating new ones

2. **Plan**:
   - Break down the request into atomic steps
   - Identify which files need creation or modification
   - Check `src/components/` for reusable components

3. **Implementation**:
   - **Surgical Editing**: Make focused changes
   - **Composition API**: Use `<script setup>` syntax
   - **Formatting**: Always format touched files

4. **Verification**:
   - **Test**: Run `npm test` or `bun test`
   - **Build Check**: If changing core configs, run build
   - **Linting**: Run ESLint/Prettier

5. **Self-Review**:
   - Did you avoid prop drilling (3+ layers)?
   - Did you use stores for shared state?
   - Did you avoid direct API calls in components?

---

Section 3: Documentation & Knowledge Base

Template

## Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

* **[Category]**: `[path/to/file.md]` ([Description])

Laravel Example

## Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

* **Testing**: `docs/testing-guidelines.md` (Test structure and coverage requirements)
* **Documentation**: `docs/documentation-guidelines.md` (How to write feature docs)
* **API Standards**: `docs/api-standards.md` (API design conventions)
* **Architecture**: `docs/architecture.md` (System design patterns)

Frontend Example

## Documentation & Knowledge Base

You are expected to read and adhere to these single sources of truth:

* **Design System**: `docs/design-system.md` (Colors, components, layouts)
* **Component Guide**: `docs/components.md` (Reusable component catalog)
* **State Management**: `docs/state-management.md` (Store patterns and conventions)

---

Section 4: Project Structure & Architecture

Laravel Structure

## Project Structure & Architecture

* **`app/Http/Controllers/`**: Feature-grouped controllers. Thin controllers delegate to Services.
* **`app/Services/`**: Business logic. Encapsulate queries via Model Scopes.
* **`app/Models/`**: Eloquent models with relationships and scopes.
* **`app/Http/Resources/`**: API response transformers.
* **`app/Http/Requests/`**: Form Request validation classes.
* **`routes/api.php`**: API routes with middleware.
* **`routes/web.php`**: Web routes for views.
* **`database/migrations/`**: Database schema changes.
* **`tests/`**: Feature and Unit tests.

Vue.js Structure

## Project Structure & Architecture

* **`src/components/`**: Reusable UI components.
* **`src/views/`** or **`src/pages/`**: Page-level components.
* **`src/stores/`**: Pinia stores for state management.
* **`src/composables/`**: Reusable composition functions.
* **`src/services/`** or **`src/api/`**: API service layer.
* **`src/assets/`**: Static assets (images, fonts).
* **`src/styles/`**: Global styles and variables.
* **`src/router/`**: Vue Router configuration.

React Structure

## Project Structure & Architecture

* **`src/components/`**: Reusable UI components.
* **`src/pages/`**: Page components (Next.js) or route components.
* **`src/hooks/`**: Custom React hooks.
* **`src/context/`**: React Context providers.
* **`src/services/`** or **`src/api/`**: API service layer.
* **`src/utils/`**: Utility functions.
* **`src/types/`**: TypeScript type definitions.

Full-Stack (Laravel + Frontend)

## Project Structure & Architecture

### Backend (Laravel)
* **`app/Http/Controllers/`**: API controllers.
* **`app/Services/`**: Business logic layer.
* **`app/Models/`**: Eloquent models.
* **`routes/api.php`**: API endpoints.

### Frontend
* **`resources/js/`**: Frontend source (Inertia.js).
* **`resources/js/Pages/`**: Inertia page components.
* **`resources/js/Components/`**: Reusable components.
* **`resources/js/Layouts/`**: Layout components.

---

Section 5: Development Environment

Docker Compose

## Development Environment

### Container vs Host Commands
* Use **container** for: PHP, Artisan, Composer, database access, tests
* Use **host** for: Git, file operations, IDE commands, npm/node (if not containerized)

### Container Commands

PHP/Laravel commands

docker compose exec app php artisan migrate docker compose exec app php artisan test docker compose exec app composer install docker compose exec app vendor/bin/pint

Database access

docker compose exec db mysql -u root -p

### Host Commands

Git operations

git status git commit -m "message"

Node.js (if not containerized)

npm install npm run dev

Laravel Sail

## Development Environment

### Sail Commands
All runtime commands should use Sail:

Artisan commands

./vendor/bin/sail artisan migrate ./vendor/bin/sail artisan test

Composer

./vendor/bin/sail composer install

npm

./vendor/bin/sail npm install ./vendor/bin/sail npm run dev

### Direct Host Commands
* Git operations run directly
* IDE/editor commands run directly

Native/Host Machine

## Development Environment

### Prerequisites
* [Language] [Version] installed
* [Package Manager] installed
* [Database] running locally

### Key Commands

Install dependencies

[INSTALL_COMMAND]

Run development server

[DEV_COMMAND]

Run tests

[TEST_COMMAND]

Format code

[FORMAT_COMMAND]

Build for production

[BUILD_COMMAND]

---

Section 6: Coding Standards

PHP/Laravel

## Coding Standards (The "Gold Standard")

* **Language**: PHP 8.2+
* **Framework**: Laravel 11
* **Strictness**: Always use `declare(strict_types=1);`
* **Style**: PSR-12, enforced by Laravel Pint

### Type Declarations
* Always use explicit return type declarations
* Use appropriate PHP type hints for parameters
* Use PHPDoc for complex array shapes

### Database
* Prefer Eloquent over raw queries
* Use Model Scopes for reusable query logic
* Never edit existing migrations; create new ones

### Controllers
* Keep controllers thin
* Delegate business logic to Services
* Use Form Requests for validation

### Anti-Patterns to Avoid
* No business logic in controllers
* No raw queries when Eloquent suffices
* No hardcoded configuration values

Vue.js

## Coding Standards (The "Gold Standard")

* **Framework**: Vue 3 (Composition API)
* **Build Tool**: Vite
* **UI Library**: [Detected or specify]
* **Style**: ESLint + Prettier

### Component Guidelines
* Use `<script setup>` syntax
* Props should have type definitions
* Emit events with proper typing

### State Management
* Use Pinia for shared state
* Local state (`ref`/`reactive`) for component-specific data
* Avoid prop drilling (3+ component layers)

### Anti-Patterns to Avoid
* No direct API calls in components (use services/stores)
* No hardcoded text (use i18n if applicable)
* No business logic in templates

React/TypeScript

## Coding Standards (The "Gold Standard")

* **Framework**: React 18+
* **Language**: TypeScript (strict mode)
* **Style**: ESLint + Prettier

### Component Guidelines
* Functional components with hooks
* Props interfaces defined explicitly
* Prefer named exports

### State Management
* React Query for server state
* Context/Zustand for client state
* Local state for component-specific data

### TypeScript
* No `any` types
* Explicit return types on functions
* Interface over type for objects

---

Section 7: Domain Specifics (Optional)

Permission System

## Domain Specifics

### Permissions
* Every controller action requires permission middleware
* Permission naming: `resource.action` (e.g., `users.create`)
* Super admin bypasses permission checks via config

Multi-Zone Application

## Domain Specifics

### Application Zones
* **Production Zone**: Prefix classes with `Production` (e.g., `ProductionOrder`)
* **Office Zone**: Standard naming
* **Separation**: Production UIs must not use Office resources

Localization

## Domain Specifics

### Localization
* All user-facing messages in [Language]
* Use `mb_strtolower()` and `mb_strtoupper()` for unicode
* Date format: [Format] (e.g., DD/MM/YYYY)

Real-time Features

## Domain Specifics

### Real-time Broadcasting
* Endpoint: `POST /api/broadcast/[event]`
* Channels: [List of channels]
* Use Laravel Echo / Socket.io for frontend

---

Section 14: System Prompt Alignment (Optional)

## System Prompt Alignment

These prompts can override project instructions. Review and align them with this file:

* **Claude Code Global Prompt**: `~/.claude/CLAUDE.md` (review for conflicts)
* **GitHub Copilot**: `.github/copilot-instructions.md`
* **Cursor Rules**: `.cursorrules`
* **Cline Rules**: `.clinerules` or `.clinerules/`
* **Kilo Code Rules**: `.kilocoderules` / `.kilo/` / `.kilocodemodes`
* **Roo Code Rules**: `.roo/rules/` / `.roo/rules-*` / `.roorules*`
* **OpenCode Config**: `opencode.jsonc`
* **Codex Project Instructions**: `AGENTS.override.md` / `AGENTS.md`
* **Codex Global Instructions**: `~/.codex/AGENTS.override.md` / `~/.codex/AGENTS.md`
* **Codex Config**: `~/.codex/config.toml`

If any of these conflict with this file, update the global/system prompts first.

Section 15: MCP Servers & Tooling (Optional)

## MCP Servers & Tooling

Use these MCP servers when the task matches their capability:

* **[server-name]**: [Purpose, when to use it, required env vars]

If a server is not needed for this project, disable it in the MCP config.

Section 16: Project Memory (ROADMAP/PROGRESS) (Optional)

## Project Memory & Progress Tracking

Keep lightweight, human-readable project memory:

* **Roadmap**: `ROADMAP.md` (future ideas, use checklists)
* **Progress**: `PROGRESS.md` (current focus + recent completions)

If a memory MCP server is used instead, keep these files minimal or omit them.

---

Footer

Always end the file with:

---
*This file is the primary instruction set for AI agents. If you change project structure or conventions, update this file.*

Tech Stack Detection Reference

This document defines the file patterns and indicators used to auto-detect project tech stacks.

Detection Priority

When multiple frameworks are detected, prioritize based on: 1. Primary backend framework (Laravel, Express, Django, etc.) 2. Primary frontend framework (Vue, React, Angular, etc.) 3. Build tools and package managers 4. Testing frameworks 5. Linting/formatting tools

Backend Framework Detection

Laravel

Confidence: HIGH if 3+ indicators present

Version Detection:

// composer.json
"require": {
    "laravel/framework": "^11.0"  // Extract major version
}

Sub-framework Detection:

• Laravel Sail: laravel/sail in composer.json dev dependencies
• Laravel Sanctum: laravel/sanctum in composer.json
• Laravel Fortify: laravel/fortify in composer.json
• Inertia.js: inertiajs/inertia-laravel in composer.json

Express.js / Node.js

Confidence: HIGH if 2+ indicators present

Django

Confidence: HIGH if 2+ indicators present

Flask

Confidence: HIGH if 2+ indicators present

Ruby on Rails

Confidence: HIGH if 2+ indicators present

---

Frontend Framework Detection

Vue.js

Confidence: HIGH if 2+ indicators present

Version Detection:

// package.json
"dependencies": {
    "vue": "^3.4.0"  // Vue 3
}

Sub-framework Detection:

• Nuxt.js: nuxt in package.json, nuxt.config.ts exists
• Pinia: pinia in package.json
• Vue Router: vue-router in package.json
• Vuetify: vuetify in package.json
• PrimeVue: primevue in package.json

React

Confidence: HIGH if 2+ indicators present

Sub-framework Detection:

• Next.js: next in package.json, next.config.js exists
• Remix: @remix-run/react in package.json
• Inertia React: @inertiajs/react in package.json
• Redux: redux or @reduxjs/toolkit in package.json
• React Query: @tanstack/react-query in package.json

Angular

Confidence: HIGH if 2+ indicators present

Svelte

Confidence: HIGH if 2+ indicators present

---

UI Library Detection

TailwindCSS

Version Detection:

• v3: tailwind.config.js with module.exports
• v4: CSS-based config with @theme directive

Bootstrap

---

Package Manager Detection

---

Testing Framework Detection

PHP Testing

JavaScript Testing

Python Testing

---

Code Style/Linting Detection

PHP

JavaScript/TypeScript

---

Container/Environment Detection

Docker

Service Detection (from docker-compose.yml):

services:
  app:        # PHP/Laravel container
  web:        # Nginx/Apache
  db:         # Database (mysql, postgres, mariadb)
  redis:      # Cache/Queue
  node:       # Node.js for frontend builds

Dev Containers

---

Database Detection

---

Scan Depth File Lists

Quick Scan (Root Level Only)

package.json
package-lock.json / yarn.lock / pnpm-lock.yaml / bun.lockb
composer.json
composer.lock
docker-compose.yml / docker-compose.yaml
Dockerfile
.env.example
pyproject.toml
requirements.txt
Gemfile
go.mod
Cargo.toml
artisan
manage.py

Medium Scan (Root + Common Directories)

All Quick Scan files, plus:

src/
  *.vue, *.jsx, *.tsx (first level only)
app/
  Http/Controllers/ (scan for patterns)
  Models/ (scan for patterns)
config/
  app.php, database.php (Laravel)
routes/
  web.php, api.php
resources/
  js/ (check for Inertia)
  views/ (check for Blade)
components/ (first level)
pages/ (first level)

Deep Scan (Full Tree)

All Medium Scan files, plus:

tests/
  **/*.php, **/*.js, **/*.ts
docs/
  **/*.md
scripts/
  **/*
public/
  index.php, index.html
storage/
  (skip - runtime files)
vendor/
  (skip - dependencies)
node_modules/
  (skip - dependencies)

---

Confidence Scoring

HIGH (90%+): Primary framework indicators present MEDIUM (60-89%): Secondary indicators or config files LOW (< 60%): Inferred from file patterns only

When presenting to user, show confidence levels:

Backend:
  - Laravel 11 (HIGH confidence - composer.json + artisan + config)
  - PHP 8.3 (HIGH confidence - composer.json require)

Frontend:
  - Vue.js 3 (HIGH confidence - package.json + .vue files)
  - TailwindCSS v4 (MEDIUM confidence - package.json only)

---

CI/CD Detection

Workflow Detection (from GitHub Actions):

# Look for common workflow patterns
on:
  push:
    branches: [main, master]
  pull_request:
    branches: [main, master]

jobs:
  test:      # Testing workflow
  build:     # Build workflow
  deploy:    # Deployment workflow

---

Mobile App Detection

React Native

Flutter

---

Monorepo Detection

Nx

Turborepo

Lerna

pnpm Workspaces

Yarn Workspaces

---

API Documentation Detection

---

AI Agent Tooling Detection

Project Instruction Files

Global Instruction Files

MCP Config Detection

If the MCP config location is unknown, ask the user for the path and add it to detection scripts via --mcp-path.

---

Python Detection (Additional)

Django

Flask

FastAPI

Python Tools

ROADMAP — agents-md-generator

This roadmap tracks future plans for the agents-md-generator skill.

Rules:

• When new ideas/features are discussed, update both ROADMAP.md and PROGRESS.md.
• When a task is completed, update both files.
• ROADMAP.md uses checklists so items can be marked done.
• Keep this file ~200–300 lines max; if it exceeds, archive oldest entries to docs/archives/ROADMAP-YYYY-MM.md.

Near-Term (Next)

• [ ] Add contributor-friendly “how to update/merge” mini-guide (with examples) in SKILL.md
• [ ] Add a short “what I detected” output template with confidence levels and override prompts
• [ ] Add guidance for Claude Code compatibility file (CLAUDE.md with @AGENTS.md) in the Quick Start section
• [ ] Add a “safe defaults” section: do/don’t for agents (no secrets, no destructive commands, ask-first rules)

Detection Enhancements

• [ ] Improve monorepo/workspace detection (pnpm/yarn/npm workspaces; Nx/Turborepo/Lerna)
• [ ] Add stronger Docker/Sail/Devcontainer detection signals and command-prefix rules
• [ ] Expand test framework detection (Playwright/Cypress; PHPUnit/Pest; pytest)
• [ ] Expand formatter/linter detection (Biome; Ruff; Black; golangci-lint)

Merge & Update Strategy

• [ ] Add explicit rules for preserving user customizations vs. regenerating boilerplate
• [ ] Add a “section-level diff summary” workflow that does not dump huge diffs by default
• [ ] Add “deprecated guidance” marking strategy (keep but annotate + date)

Reference Docs

• [ ] Add a “section catalog” index pointing to references/* docs
• [ ] Add more stack examples in references/section-templates.md (API-only, full-stack, monorepo)

Completed

• [x] Add scripted detection for AI tool prompts, MCP servers, and prompt-alignment notes (2026-01-22)
• [x] Add skill duplicate scan script with canonical-source guidance (2026-01-22)
• [x] Add optional System Prompt Alignment, MCP Servers, and Project Memory sections (2026-01-22)
• [x] Document AI agent tooling detection paths in references (2026-01-22)
• [x] Add ROADMAP.md + PROGRESS.md workflow and archiving rules (2026-01-09)
• [x] Add helper scripts to archive roadmap/progress (bash + PowerShell) (2026-01-09)
• [x] Add terminal-aware launcher and Windows cmd wrapper for archiving scripts (2026-01-09)
• [x] Add compact reply examples for Q&A prompts and maintainer workflow using the archive scripts (2026-01-09)
• [x] Standardize multi-choice prompts with explicit “reply examples” while keeping full-sentence answers supported (2026-01-09)