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

> Learn how to contribute to the AI website cloner by forking the Next.js template, modifying components, and submitting pull requests. A developer's guide to JCodesMore ai-website-cloner-template.

- Repository: [JCodesMore/ai-website-cloner-template](https://github.com/JCodesMore/ai-website-cloner-template)
- Tags: how-to-guide
- Published: 2026-06-27

---

**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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts), synchronizing documentation changes via [`scripts/sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/sync-agent-rules.sh), and submitting pull requests that pass the automated CI pipeline in [`.github/workflows/ci.yml`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/page.tsx) and [`layout.tsx`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/button.tsx)). The project uses a centralized `cn()` utility function defined in [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) contains user-facing documentation and quick-start guides
- [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) serves as the single source of truth for platform instructions and tech stack details

The `scripts/` directory contains [`sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/sync-agent-rules.sh) and `sync-skills.mjs`, which regenerate platform-specific instruction files from [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md). Clone your fork locally to begin development.

### 2. Create a Feature Branch

Isolate your changes by creating a descriptive feature branch:

```bash
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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) and [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) or the Claude skill file, run the synchronization scripts to propagate changes to platform-specific documentation:

```bash

# 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:

```bash
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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/components/ui/alert.tsx):

```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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts).

### Updating the Pipeline Documentation

When modifying the cloning pipeline, update the documentation in [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) to reflect the current phase behavior. For example, when documenting the Parallel Build phase:

```md
<!-- 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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md), you must regenerate the derived skill files for the changes to take effect in the AI agents:

```bash

# 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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) directly.

## Key Files Every Contributor Should Know

Understanding these core files streamlines the contribution process:

- **[`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts)** — Contains the `cn()` helper for safe Tailwind class merging
- **`src/components/ui/`** — Directory for shadcn/ui component implementations
- **[`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md)** — Single source of truth for platform instructions and project structure
- **[`scripts/sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/sync-agent-rules.sh)** — Script to regenerate agent instructions after [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) changes
- **`scripts/sync-skills.mjs`** — Node.js script for updating the `/clone-website` skill definitions
- **[`.github/workflows/ci.yml`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/src/lib/utils.ts) for utility updates, using the `cn()` helper for Tailwind class merging.
- **Update documentation** in both [`README.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/README.md) and [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/AGENTS.md) when changing pipeline behavior or tech stack details.
- **Run sync scripts** ([`scripts/sync-agent-rules.sh`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/scripts/sync-agent-rules.sh) and `scripts/sync-skills.mjs`) after modifying [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/alert.tsx)) that imports the `cn()` utility from [`src/lib/utils.ts`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/button.tsx).

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

The [`AGENTS.md`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/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`](https://github.com/JCodesMore/ai-website-cloner-template/blob/main/.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.