Skip to main content

1.5 Fork the Example Repository

In this section, you'll use Claude Code to fork the Emerald Grove Pet Clinic — the example application you'll work with throughout this program.

About Emerald Grove Pet Clinic​

Emerald Grove Pet Clinic is a veterinary clinic management application designed as an AI-native development example. It mirrors the complexity of real enterprise codebases:

  • Full-stack architecture — Spring Boot backend with Thymeleaf frontend
  • Comprehensive test suite — Unit tests, integration tests, and Playwright E2E tests
  • CI/CD pipeline — GitHub Actions workflows for build, test, and deployment
  • AI-native documentation — AGENTS.md, architecture docs, and coding standards
  • Sample data — Pre-loaded owners, pets, vets, and visits for immediate testing

Prerequisites for the Example Project​

Before forking, ensure you have Java installed. The Pet Clinic application requires Java 25 or later.

Check your Java version:

java -version

Install Java if needed:

macOS:

brew install openjdk@25

Ubuntu/Debian:

sudo apt install openjdk-25-jdk
Maven Wrapper

The project includes a Maven wrapper (mvnw), so you don't need to install Maven separately. The wrapper will download the correct Maven version automatically.

Fork the Repository​

Fork the repository into the liatrio-forge organization with your name appended, then clone it:

Need access to the liatrio-forge org?

The fork command below will fail if you aren't a member of the liatrio-forge GitHub organization. Request access in #liatrio-forge before you start this section.

Replace <first>-<last> before running!

The commands below contain <first>-<last> as a placeholder. Replace it with your first and last name in lowercase, separated by hyphens (e.g., jane-doe). If you copy-paste without editing, the < and > characters will cause a shell error.

gh repo fork liatrio-labs/emerald-grove-pet-clinic \
  --org liatrio-forge \
  --fork-name emerald-grove-pet-clinic-<first>-<last> \
  --clone
cd emerald-grove-pet-clinic-<first>-<last>

Then install the pre-commit hooks (requires pre-commit):

./scripts/setup-precommit.sh

Then start Claude Code inside the project:

claude

Copy Issues to Your Fork​

GitHub forks don't include the parent repository's issues, so you'll need to copy them over. These issues represent the backlog of work you'll tackle throughout the program.

Ask Claude to enable issues on your fork and copy them from the parent repo:

Replace <first>-<last> before running!

The prompt below contains <first>-<last> as a placeholder. Replace it with the same name you used when forking (e.g., jane-doe).

Enable issues on liatrio-forge/emerald-grove-pet-clinic-<first>-<last> using
`gh api repos/liatrio-forge/emerald-grove-pet-clinic-<first>-<last> --method PATCH -f has_issues=true`,
then use the gh cli to fetch all open issues from liatrio-labs/emerald-grove-pet-clinic
and create identical issues (same title and body) on liatrio-forge/emerald-grove-pet-clinic-<first>-<last>.
tip

This is a great early example of using Claude Code to automate a multi-step workflow. Claude will use the gh CLI to enable issues, list the parent repo's issues, and recreate each one on your fork — all in one prompt.

Two things that will trip you up here

Your paste collapsed to [Pasted text #2 +3 lines]. Claude Code folds long pastes into a placeholder to keep the prompt readable. The content is there, but if you want to see and edit the literal text, paste the same content a second time — the second paste expands into the full text instead of another placeholder.

Nothing is happening. This prompt makes Claude run a series of gh commands, and in Plan or Manual mode it will stop and ask for approval on each one — or refuse to act at all. Press Shift+Tab to cycle to Accept Edits or Auto before you send it.

Detach from the Fork Network​

GitHub forks are linked to their parent repository in a "fork network." This linkage prevents you from changing the fork's visibility — which you'll need to set to internal later in this section.

To detach, you'll use the Leave fork network option in GitHub's UI. There is no API or CLI equivalent for this action.

Verify issue preservation

The confirmation dialog will explain what happens to your repo's metadata. Read it carefully before proceeding. If the dialog indicates that issues, PRs, or other metadata will be lost, stop and contact GitHub Support instead — select "Attach, detach, or reroute forks" and they can detach while preserving everything.

Steps to detach:

  1. Open your fork's settings: https://github.com/liatrio-forge/emerald-grove-pet-clinic-<first>-<last>/settings
  2. Scroll to the Danger Zone at the bottom of the page
  3. Find "Leave fork network" and click the button
  4. Read the confirmation dialog — confirm that issues and repo metadata will be preserved
  5. Complete the detach process
Clean up your local git remotes

After detaching, your local clone may still have an upstream remote pointing to the original parent repository. Remove it so your repo only references your own fork:

git remote remove upstream
git remote -v   # verify only 'origin' remains

You don't have to leave your Claude Code session to do this. Prefix any shell command with ! and Claude Code runs it directly in your shell, dropping the output into the conversation:

! git remote -v
! git remote remove upstream

This is worth building into muscle memory now — you'll use it constantly for quick git status, ls, and build checks without losing your place.

Once detached, your repository is a standalone repo. You can now change its visibility to internal:

gh repo edit liatrio-forge/emerald-grove-pet-clinic-<first>-<last> --visibility internal --accept-visibility-change-consequences
Why internal?

Internal repositories are visible to all members of the liatrio-forge organization but private to outsiders. This allows teammates to collaborate while still enabling access to organization-level secrets — required for CI workflows that use secrets, such as automated code review with Claude Code. The --accept-visibility-change-consequences flag is required for the command to work

Enable GitHub Actions​

Forking disables GitHub Actions workflows by default (disabled_fork). Leaving the fork network and setting visibility to internal does not re-enable them — Settings → Actions can look enabled while workflows on the Actions tab are still disabled.

  1. Open your repo's Actions tab: https://github.com/liatrio-forge/emerald-grove-pet-clinic-<first>-<last>/actions
  2. If prompted that workflows aren't enabled / Actions isn't enabled, click to enable workflows
  3. Confirm workflows such as E2E Tests and Performance Tests appear as enabled

Do this before opening your first pull request — otherwise CI won't run even though the workflow YAML is present.

Project Structure Overview​

Ask Claude to give you a high-level overview:

Give me a high-level overview of this project's structure. What are the main directories and their purposes?

Claude will analyze the repository and explain:

emerald-grove-pet-clinic-<first>-<last>/
├── src/                    # Java source code
│   ├── main/
│   │   ├── java/           # Application code
│   │   └── resources/      # Configuration, templates, static assets
│   └── test/               # Test code
├── e2e-tests/              # Playwright end-to-end tests
├── docs/                   # Documentation and specs
│   └── specs/              # SDD specification artifacts
├── .github/                # GitHub Actions workflows
├── .claude/                # Claude Code configuration
├── AGENTS.md              # AI assistant context file (open standard)
├── CLAUDE.md              # Points at AGENTS.md (Claude Code workaround)
├── pom.xml                 # Maven build configuration
└── README.md               # Project documentation

Build and Run the Application​

Let's verify the application works. Ask Claude:

How do I build and run this application locally?

Claude will read the project configuration and provide instructions. Typically:

./mvnw spring-boot:run

The application will start on http://localhost:8080.

App didn't start?

Run it yourself with the ! prefix you used when cleaning up git remotes — it executes directly in your shell from inside the Claude Code session, so you see the real error output:

! ./mvnw spring-boot:run

Explore with Claude​

Try these prompts to explore the codebase:

Find the main application entry point:

Where is the main application entry point? Show me the main class.

Understand the domain model:

What entities does this application manage? Show me the domain model.

Find the test structure:

What kinds of tests does this project have? Where are they located?

Check for AI-native configuration:

Does this project have an AGENTS.md file? Show me its contents, and show me what CLAUDE.md contains.

What Makes This Repo "AI-Native"?​

As you explore, notice these AI-native characteristics:

  1. AGENTS.md — A context file that helps AI assistants understand the project. AGENTS.md is an open standard supported by multiple AI coding tools. The repo also includes a CLAUDE.md that resolves to the same content — a workaround because Claude Code does not yet support AGENTS.md natively. Always author in AGENTS.md; CLAUDE.md is only a pointer and should never accumulate content of its own. Section 1.6 covers how to set this up correctly in your own repositories.
  2. docs/specs/ — Directory structure for SDD artifacts
  3. Comprehensive tests — Provide feedback loops for AI-generated code
  4. Clear architecture — Makes it easier for AI to understand and modify code
  5. Coding standards — Documented conventions AI can follow

Next Steps​

Now that you have the project forked and running, the next section takes you on a guided tour of the AI-native repository structure — understanding the patterns that make this codebase optimized for AI-assisted development.

Knowledge Check​

Question 1 of 6

Fork the Example Repository Knowledge Check

Q1. You've forked a repository but find you cannot change its visibility, and CI workflows can't access organization-level secrets. What is the most likely cause?