What Is Inside BEHAVIORS.md and How It Powers the AI Website Cloner

BEHAVIORS.md at docs/research/BEHAVIORS.md serves as the central "behavior bible" that records AI agent conventions and inspection findings, which clone-website commands reference at specific lines across Windsurf, Cursor, OpenCode, and other IDE-specific workflow files to ensure consistent component generation.

The JCodesMore/ai-website-cloner-template repository uses this centralized markdown file to govern how AI agents inspect target websites and generate shadcn/ui components. Located in the docs/research/ directory, BEHAVIORS.md functions as the single source of truth for agent behavior throughout the cloning workflow, storing everything from design token mappings to file structure conventions.

What Information Is Stored in BEHAVIORS.md

The file captures six critical categories of behavioral data that agents must follow when analyzing source websites and constructing React components.

General Agent Behavior

This section establishes high-level expectations for how an agent should reason, remain on-task, and produce auditable output. It defines the cognitive framework agents use when breaking down complex UI patterns into implementable specifications.

Component Specification Rules

Agents record shadcn/ui naming conventions, prop-type expectations, and design-token usage here. These rules ensure that generated buttons, cards, and navigation elements follow the repository's standardized component API surface.

Design Token Mapping

This section documents how colors, spacing, and typography from the target site map onto the repository's Oklch-based Tailwind tokens. Agents reference these mappings to maintain visual fidelity when translating CSS from the source into the Tailwind configuration.

Interaction and Animation Guidelines

Rules for reproducing hover states, focus rings, and transition effects live here. The guidelines specify exact CSS properties and timing functions that agents must preserve when cloning interactive elements.

File-Structure Conventions

Agents record the canonical locations for generated assets: src/app/ for page routes, src/components/ui/ for shadcn components, and public/images/ for static assets. This prevents path fragmentation across different cloning sessions.

Testing and Validation Rules

Checklists for pixel-perfect fidelity, responsive breakpoint verification, and accessibility sanity checks ensure that generated components meet production standards before submission.

How Clone-Website Commands Reference BEHAVIORS.md

Every entry-point script across multiple AI coding platforms contains an identical directive pointing to the behavior bible. The instruction appears verbatim in each file:

"Save all findings to docs/research/BEHAVIORS.md. This is your behavior bible — reference it when writing every component spec."

Specific file locations and line numbers where this reference occurs include:

• .windsurf/workflows/clone-website.md at line 163
• .opencode/commands/clone-website.md at line 166
• .github/skills/clone-website/SKILL.md at line 166
• .gemini/commands/clone-website.toml at line 167
• .cursor/commands/clone-website.md at line 163
• .continue/commands/clone-website.md at line 168
• .codex/skills/clone-website/SKILL.md at line 166
• .claude/skills/clone-website/SKILL.md at line 166
• .augment/commands/clone-website.md at line 167
• .amazonq/cli-agents/clone-website.json at line 4

These files do not import or parse BEHAVIORS.md programmatically. Instead, they treat it as a persistent markdown log that agents append to during inspection and read during component generation.

How Agents Write to the Behavior Bible

The production code never edits BEHAVIORS.md directly. Instead, agents append markdown blocks containing their findings after each inspection phase. This creates an accumulating record of observed behaviors that downstream specialists consult.

The following pattern illustrates how an agent writes component specifications to the file:

const fs = require('fs');
const path = 'docs/research/BEHAVIORS.md';

const entry = `### Button Component

- Use shadcn/ui \`Button\` variant default
- Apply Tailwind Oklch token \`bg-primary\` for background
- Preserve hover animation via \`transition-colors duration-200\`
- Accessible focus ring using \`focus-visible:ring-2\`
`;

fs.appendFileSync(path, entry + '\n');

By appending rather than overwriting, the file accumulates a comprehensive behavioral specification that survives across multiple AI agent sessions. Downstream builders read this file to ensure consistency when implementing navigation bars, hero sections, and footer components.

Summary

• BEHAVIORS.md at docs/research/BEHAVIORS.md acts as the central behavior bible for AI agents in the JCodesMore/ai-website-cloner-template repository.
• The file contains six primary sections: General Agent Behavior, Component Specification Rules, Design Token Mapping, Interaction Guidelines, File-Structure Conventions, and Testing Rules.
• Ten separate command files across Windsurf, Cursor, GitHub Skills, Gemini, OpenCode, Continue, Codex, Claude, Augment, and Amazon Q reference the file at lines 163-168.
• Agents append inspection findings to the markdown file using standard file-system operations, creating a persistent log that subsequent agents read during component generation.
• No production code imports or parses the file; it serves purely as a human-readable contract between AI agents.

Frequently Asked Questions

What is the exact file path for BEHAVIORS.md in the repository?

The file is located at docs/research/BEHAVIORS.md in the repository root. This path is hardcoded consistently across all IDE-specific command files, including .cursor/commands/clone-website.md and .windsurf/workflows/clone-website.md.

Do the clone-website scripts parse BEHAVIORS.md programmatically?

No, the scripts do not import or parse the file. They treat it as a persistent markdown log that AI agents consult when generating component specifications. The scripts contain only a text directive instructing agents to reference the file, rather than executable code that reads it.

Which AI coding platforms reference BEHAVIORS.md?

The file is referenced by command definitions for Windsurf, Cursor, OpenCode, Continue, Codex, Claude, Augment, Gemini, GitHub Skills, and Amazon Q. Each platform stores its command definition in a platform-specific directory such as .cursor/commands/, .claude/skills/, or .amazonq/cli-agents/.

How do agents update BEHAVIORS.md during the cloning process?

Agents append markdown blocks to the file after inspecting sections of the target website. They use standard file-system append operations to add new behavioral observations, ensuring that downstream agents have access to cumulative findings from previous inspection phases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}