Contributing to the AI Website Cloner: A Developer's Guide to the JCodesMore Template

Contributing to the AI website cloner involves forking the Next.js 16 repository, modifying components in src/components/ui/ or utilities in src/lib/utils.ts, synchronizing documentation changes via scripts/sync-agent-rules.sh, and submitting pull requests that pass the automated CI pipeline in .github/workflows/ci.yml.

The AI Website Cloner Template is a type-safe Next.js 16 project built with React 19, shadcn/ui, and Tailwind CSS v4. It powers a five-phase cloning pipeline that converts target websites into structured component code. Understanding the repository's architecture and contribution workflow is essential for developers looking to extend the template's capabilities or improve the AI agent instructions.

Understanding the Repository Architecture

Before contributing to the AI website cloner, familiarize yourself with the project's layered architecture. The codebase separates concerns between the Next.js framework, UI primitives, utility helpers, and AI agent specifications.

Framework and Entry Points

The application runs on Next.js 16 with the App Router and React 19. All entry points reside in src/app/, including page.tsx and layout.tsx. The project uses strict TypeScript configurations to ensure type safety across the entire codebase.

UI Components and Styling

UI primitives are built using shadcn/ui components styled with Tailwind CSS v4. These components live in src/components/ui/ (e.g., button.tsx). The project uses a centralized cn() utility function defined in src/lib/utils.ts to safely merge Tailwind class strings using clsx and tailwind-merge.

Type Definitions and Assets

Centralized TypeScript interfaces are stored in src/types/, defining component props, asset metadata, and the specification format used by the cloning pipeline. Downloaded images and videos are stored under public/ (e.g., public/images/), while research documents and component specifications generated by AI agents are kept in docs/research/.

Documentation and Scripts

The repository maintains two critical documentation files:

• README.md contains user-facing documentation and quick-start guides
• AGENTS.md serves as the single source of truth for platform instructions and tech stack details

The scripts/ directory contains sync-agent-rules.sh and sync-skills.mjs, which regenerate platform-specific instruction files from AGENTS.md and the Claude skill file.

Step-by-Step Contribution Workflow

Follow this seven-step workflow when contributing to the AI website cloner to ensure your changes integrate correctly with the automated pipeline.

1. Fork and Clone the Repository

Start by forking the repository using the Use this template button recommended in the README.md. Clone your fork locally to begin development.

2. Create a Feature Branch

Isolate your changes by creating a descriptive feature branch:

git checkout -b feat/your-idea

3. Modify Source Code

Make your changes to the appropriate layer:

• For UI changes, edit or add components under src/components/ui/
• For utility work, modify src/lib/utils.ts
• For type definitions, update files in src/types/

4. Update Documentation

Any change to the pipeline, command set, or supported agents must be reflected in both README.md and AGENTS.md. The five-phase pipeline (Reconnaissance → Foundation → Component Specs → Parallel Build → Assembly & QA) is documented in these files and serves as the instruction set for AI agents.

5. Regenerate Derived Files

After modifying AGENTS.md or the Claude skill file, run the synchronization scripts to propagate changes to platform-specific documentation:

# After touching AGENTS.md

bash scripts/sync-agent-rules.sh

# After touching the Claude skill file

node scripts/sync-skills.mjs

These scripts ensure that agent instructions remain consistent across different platforms and IDEs.

6. Run the Test Suite

Validate your changes using the built-in lint and type-check scripts:

npm run check   # Runs lint + typecheck + build

This command verifies that your code meets the project's strict TypeScript standards and builds successfully.

7. Submit a Pull Request

Push your branch and open a pull request. The CI workflow defined in .github/workflows/ci.yml automatically lints, type-checks, and builds the project, blocking merges that introduce errors.

Code Contribution Examples

These practical examples demonstrate common contribution patterns for the AI website cloner template.

Adding a New shadcn/ui Component

When adding new UI primitives, use the existing cn() utility to maintain consistent Tailwind class merging. Here is an example adding an Alert component to src/components/ui/alert.tsx:

// src/components/ui/alert.tsx
import { cn } from "@/lib/utils";

export interface AlertProps {
  variant?: "default" | "destructive";
  children: React.ReactNode;
}

export function Alert({ variant = "default", children }: AlertProps) {
  const base = "rounded-md border p-4 text-sm";
  const variants = {
    default: "bg-neutral-100 border-neutral-200 text-neutral-900",
    destructive: "bg-red-100 border-red-200 text-red-900",
  };
  return (
    <div className={cn(base, variants[variant])}>
      {children}
    </div>
  );
}

This pattern ensures that Tailwind classes are merged safely without conflicts, following the project's style conventions established in src/lib/utils.ts.

Updating the Pipeline Documentation

When modifying the cloning pipeline, update the documentation in README.md to reflect the current phase behavior. For example, when documenting the Parallel Build phase:

<!-- In README.md, under "How It Works" -->
5. **Parallel Build** — each section is built in its own Git worktree; 
   agents receive the full component spec JSON generated in `docs/research/components/`.

After editing documentation, always run the sync scripts to ensure platform-specific files remain synchronized.

Regenerating Agent Instructions

When you modify AGENTS.md, you must regenerate the derived skill files for the changes to take effect in the AI agents:

# In your terminal

bash scripts/sync-agent-rules.sh

# Verify the generated file was updated

git diff .github/skills/clone-website/SKILL.md

This step is critical because the AI agents read from the generated files in .github/skills/ rather than the source AGENTS.md directly.

Key Files Every Contributor Should Know

Understanding these core files streamlines the contribution process:

• src/lib/utils.ts — Contains the cn() helper for safe Tailwind class merging
• src/components/ui/ — Directory for shadcn/ui component implementations
• AGENTS.md — Single source of truth for platform instructions and project structure
• scripts/sync-agent-rules.sh — Script to regenerate agent instructions after AGENTS.md changes
• scripts/sync-skills.mjs — Node.js script for updating the /clone-website skill definitions
• .github/workflows/ci.yml — CI pipeline configuration that validates all pull requests

Summary

• Fork the template using the repository's "Use this template" button to begin contributing to the AI website cloner.
• Modify code in src/components/ui/ for UI changes or src/lib/utils.ts for utility updates, using the cn() helper for Tailwind class merging.
• Update documentation in both README.md and AGENTS.md when changing pipeline behavior or tech stack details.
• Run sync scripts (scripts/sync-agent-rules.sh and scripts/sync-skills.mjs) after modifying AGENTS.md to propagate changes to AI agent instructions.
• Validate changes with npm run check before submitting PRs to ensure they pass the CI pipeline in .github/workflows/ci.yml.

Frequently Asked Questions

What is the five-phase pipeline in the AI Website Cloner?

The AI Website Cloner uses a five-phase pipeline consisting of Reconnaissance, Foundation, Component Specs, Parallel Build, and Assembly & QA. During the Foundation phase, agents write assets to public/images/, while the Parallel Build phase generates component code in Git worktrees using specifications from docs/research/.

How do I add a new UI component to the template?

Create a new TypeScript file in src/components/ui/ (e.g., alert.tsx) that imports the cn() utility from src/lib/utils.ts. Define your component props interface and use the cn() function to merge Tailwind classes safely, ensuring consistency with existing shadcn/ui components like button.tsx.

Why must I run sync scripts after editing AGENTS.md?

The AGENTS.md file serves as the single source of truth, but AI agents read from platform-specific files in .github/skills/. Running bash scripts/sync-agent-rules.sh regenerates these derived files, ensuring that agents like Claude receive updated instructions when executing the /clone-website command.

What checks run in the CI pipeline for pull requests?

The CI workflow defined in .github/workflows/ci.yml automatically runs linting, type-checking, and build verification on every pull request. The npm run check command combines these steps locally, ensuring your contribution meets the project's strict TypeScript and Next.js 16 standards before submission.

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