repo-onboarding

Repo Onboarding

1. Purpose

repo-onboarding is a reusable repository investigation and workflow initialization skill for AI-assisted software development.

Its purpose is to establish a consistent, maintainable operating framework for any software repository, regardless of programming language, framework, architecture, or development environment.

When activated, the skill must:

1. Investigate the repository and understand its actual structure.
2. Identify the technology stack, architecture, dependencies, and development tools.
3. Discover actual development, linting, formatting, testing, and build commands.
4. Detect existing AI agent instructions and determine the target agent environment.
5. Establish a centralized project-context/ documentation structure (strictly guarded against overwriting).
6. Generate customized agent instructions using reusable templates (AGENTS.md, CLAUDE.md, GEMINI.md).
7. Establish project management, decision-making, and verification conventions.
8. Verify generated files and report onboarding results.
9. Hand over subsequent development tasks to the companion skill engineering-workflow.

The skill must prioritize existing repository conventions and preserve existing work.

It must never assume project information or blindly generate generic documentation without investigating the repository.

Once onboarding verification is complete, the skill stops and waits for human instructions. It must never automatically start implementing features.

---

2. Core Design Principles

2.1. Evidence-Based Investigation

Every generated project-specific instruction must be based on actual repository evidence.

Distinguish findings using:

• Verified: Directly confirmed from repository files or executed commands.
• Inferred: Reasonable interpretation based on available evidence.
• Unknown: Insufficient information to determine.

Never present inferred or unknown information as verified.

2.2. Technology Agnostic

Support different languages, frameworks, package managers, build systems, testing frameworks, and infrastructure technologies.

Do not assume that every project uses Node.js, Python, Docker, or a particular architecture.

2.3. Single Source of Truth

Every category of project information must have one authoritative location.

Avoid duplicating:

• Agent operating guidelines.
• Architecture decisions.
• Project requirements.
• Implementation plans.
• Task information.
• Current progress.
• Historical progress reports.

2.4. Human-Controlled Decisions

The agent can investigate, analyze, recommend, and propose solutions.

However, significant unresolved decisions must be presented to the user before implementation.

Confirmed decisions must be recorded in DECISIONS.md.

2.5. Incremental Execution

Follow this development cycle:

1. Analyze.
2. Clarify.
3. Plan.
4. Execute incrementally.

Respect user approval and agreed review checkpoints.

2.6. Preserve Existing Work

Never overwrite existing documentation, configuration, or project files without explicit authorization.

Reuse and integrate existing documentation whenever possible.

2.7. Verifiable Results

Never claim that a command, test, build, or application check passed unless it was actually executed and its result was verified.

---

3. Skill Package Structure

Install globally at: ~/.gemini/config/skills/repo-onboarding/

repo-onboarding/
├── SKILL.md
│
├── resources/
│   ├── AGENTS.template.md
│   ├── CLAUDE.template.md
│   ├── GEMINI.template.md
│   │
│   ├── README.template.md
│   ├── DECISIONS.template.md
│   ├── PLAN.template.md
│   ├── PROGRESS.template.md
│   ├── WEEKLY_PROGRESS.template.md
│   ├── BUG_LOG.template.md
│   ├── CHECKLIST.template.md
│   │
│   └── IMPLEMENTATION_PLAN.template.md
│
└── scripts/
    └── scan_repo.py

All skill instructions, templates, and generated documentation must use English.

3.1. Component Responsibilities

Component	Responsibility
SKILL.md	Main skill instructions and execution workflow
AGENTS.template.md	Shared repository operating guidelines
CLAUDE.template.md	Claude Code instructions
GEMINI.template.md	Gemini / Antigravity instructions
README.template.md	Project documentation index
DECISIONS.template.md	Decision records
PLAN.template.md	Project-level roadmap
PROGRESS.template.md	Current project status
WEEKLY_PROGRESS.template.md	Historical weekly progress
BUG_LOG.template.md	Bug and technical pitfall tracking
CHECKLIST.template.md	Manual verification scenarios
IMPLEMENTATION_PLAN.template.md	Feature-specific implementation plans
scan_repo.py	Optional repository metadata scanner

Templates are starting points, not rigid schemas. Adapt them to the actual repository.

---

4. Target Repository Documentation Structure

The default documentation structure is:

your-project/
│
├── AGENTS.md
├── CLAUDE.md
├── GEMINI.md
│
├── src/
├── tests/
│
└── project-context/
    │
    ├── README.md
    ├── DECISIONS.md
    ├── PLAN.md
    ├── PROGRESS.md
    │
    ├── progress/
    │   ├── 2026-W45.md
    │   ├── 2026-W46.md
    │   └── 2026-W47.md
    │
    ├── specs/
    │   ├── feature-a/
    │   │   ├── REQUIREMENTS.md
    │   │   ├── TECHNICAL_DESIGN.md
    │   │   └── IMPLEMENTATION_PLAN.md
    │   │
    │   ├── feature-b/
    │   │   └── ...
    │   │
    │   ├── architecture/
    │   └── screens/
    │
    ├── tasks/
    │   ├── feature-a/
    │   │   ├── TASK-001.md
    │   │   └── TASK-002.md
    │   │
    │   └── feature-b/
    │
    ├── bugs/
    │   └── BUG_LOG.md
    │
    ├── testing/
    │   ├── CHECKLIST.md
    │   └── reports/
    │
    └── references/

4.1. Directory Responsibilities

Path	Responsibility
project-context/	Centralized project knowledge and management documentation
specs/	Functional requirements, technical specifications, and feature designs
specs/architecture/	System architecture documentation
specs/screens/	Mockups, wireframes, and UI screenshots
tasks/	Actionable implementation tasks
bugs/	Known defects and technical pitfalls
testing/	Manual test scenarios and verification reports
progress/	Historical weekly progress reports
references/	Supporting technical references

The skill must not create unnecessary empty directories.

If an existing repository already has an equivalent structure, reuse it or establish a clear mapping instead of duplicating it.

---

5. Documentation Ownership and Responsibilities

This section defines the authoritative responsibility of every primary document.

5.1. README.md — Documentation Index

Purpose: Provide a navigation entry point for all project documentation.

Must explain:

• The purpose of project-context/.
• The responsibility of each document.
• The documentation structure.
• Naming conventions.
• Document relationships.
• How AI agents should navigate and maintain documentation.

This file is an index, not a duplicate of other documents.

5.2. DECISIONS.md — Decision Records

Purpose: Maintain an authoritative record of confirmed project decisions.

Use sequential identifiers:

• D-001
• D-002
• D-003

Each decision should include:

• Decision ID.
• Title.
• Date.
• Status.
• Context.
• Options considered.
• Final decision.
• Rationale.
• Consequences.
• Related decisions or specifications.

Supported statuses:

• Proposed
• Accepted
• Rejected
• Superseded

Rules:

1. Only confirmed decisions become accepted records.
2. Never silently change an accepted decision.
3. Superseding decisions must reference previous decisions.
4. Decisions take precedence over conflicting outdated plans or specifications within their scope.
5. Do not create a decision record for every minor implementation detail.

5.3. PLAN.md — Project Roadmap

Purpose: Maintain the high-level development roadmap of the entire project.

PLAN.md is a living document that describes the project's direction, major development phases, milestones, priorities, and expected capabilities.

It is not:

• A feature implementation plan.
• A task list.
• A daily progress log.
• A historical archive.
• A list of every requested feature.

Required Sections

• Project vision.
• Project objectives.
• Major milestones.
• Expected capabilities and deliverables.
• Milestone dependencies.
• Current development focus.
• Future priorities.
• Major risks and constraints.

Update Rules

Update PLAN.md only when:

1. A significant feature or capability is approved for the roadmap.
2. Development priorities change.
3. A milestone is completed or its scope changes.
4. Project direction or strategic objectives change.
5. New dependencies or constraints affect the roadmap.

Do not update it for:

• Routine task completion.
• Daily development activities.
• Minor bug fixes.
• Implementation details.
• Unapproved feature requests.

Keep PLAN.md concise.

Update existing milestones rather than continuously appending historical information.

Do not invent milestones, deadlines, or delivery commitments.

5.4. PROGRESS.md — Current Project Status

Purpose: Maintain the latest known state of the entire project.

PROGRESS.md is the current project status document, not a historical activity log.

Required Sections

• Last updated.
• Current phase.
• Current milestone.
• Overall status.
• Completed work.
• In-progress work.
• Blockers.
• Next steps.
• Weekly report index.

Update Rules

1. Update when meaningful development progress occurs.
2. Reflect the latest confirmed project state.
3. Keep the document concise.
4. Do not duplicate weekly report details.
5. Link to relevant historical reports.
6. Do not claim work is completed without verification.

5.5. progress/ — Weekly Progress Archive

Purpose: Preserve historical development progress by week.

All weekly reports must be stored directly inside: project-context/progress/

Use ISO 8601 week-based naming: YYYY-Www.md

Examples:

• 2026-W45.md
• 2026-W46.md
• 2026-W47.md
• 2027-W01.md

Do not create year-based subdirectories.

Weekly Report Structure

Each report should contain:

1. Reporting period.
2. Weekly overview.
3. Completed work.
4. Ongoing work.
5. Bugs and blockers.
6. Decisions made.
7. Verification results.
8. Next week's priorities.

Archive Rules

• Generate weekly reports at the end of a reporting week or when explicitly requested.
• Do not create an archive for every session.
• Never silently overwrite an existing weekly report.
• Update the weekly index in PROGRESS.md after archiving.
• Preserve historical information.
• Use the correct ISO week and ISO week-year, including year boundaries.

5.6. specs/ — Requirements and Technical Specifications

Purpose: Store detailed specifications for features and system components.

Organize feature-specific documentation under: project-context/specs/<feature-name>/

Documents may include:

• REQUIREMENTS.md
• TECHNICAL_DESIGN.md
• IMPLEMENTATION_PLAN.md

Create only documents justified by the feature's complexity.

REQUIREMENTS.md

Defines:

• Feature objectives.
• Functional requirements.
• Non-functional requirements.
• User workflows.
• Scope and exclusions.
• Acceptance criteria.
• Constraints and dependencies.

TECHNICAL_DESIGN.md

Defines:

• Technical approach.
• Architecture.
• Components and modules.
• Data models.
• API contracts.
• Integration points.
• Error handling.
• Security considerations.
• Technical trade-offs.

IMPLEMENTATION_PLAN.md

Defines how the approved feature will be implemented.

Include:

• Implementation scope.
• Affected components and files.
• Dependencies.
• Implementation steps.
• Execution order.
• Risks.
• Verification strategy.
• Expected deliverables.

An implementation plan is feature-specific and must not replace the overall project roadmap.

5.7. tasks/ — Task Tracking

Purpose: Break approved implementation plans into actionable work items.

Organize tasks under: project-context/tasks/<feature-name>/

Use sequential task identifiers:

• TASK-001
• TASK-002
• TASK-003

Each task should contain:

• Task ID.
• Title.
• Description.
• Related specification.
• Dependencies.
• Expected outcome.
• Acceptance criteria.
• Verification requirements.
• Status.

Suggested statuses:

• Todo
• In Progress
• Blocked
• In Review
• Done

Do not create excessive task files for trivial work. For small features, a single task document or checklist may be sufficient.

5.8. bugs/BUG_LOG.md — Bug and Technical Pitfall Tracking

Purpose: Maintain a centralized record of known defects and technical pitfalls.

Use two identifier categories:

• BUG-nnn: Confirmed defects.
• T-n: Technical traps, limitations, and implementation pitfalls.

Each entry should include:

• Description.
• Affected component.
• Reproduction steps when applicable.
• Root cause when known.
• Workaround or resolution.
• Status.
• Related references.

Do not classify an unverified suspicion as a confirmed bug.

5.9. testing/ — Testing Documentation

Purpose: Maintain manual verification scenarios and actual test reports.

CHECKLIST.md should define:

• Test ID.
• Feature.
• Preconditions.
• Test steps.
• Expected result.
• Actual result.
• Status.
• Evidence and notes.

reports/ stores execution-specific test reports when needed.

Keep automated test code in the repository's actual test directories. Do not confuse test documentation with automated test implementation.

5.10. references/ — Supporting References

Store useful supporting materials, such as:

• External technical references.
• Vendor documentation.
• Research notes.
• Supporting diagrams.
• Non-authoritative background information.

References must not override confirmed project decisions or specifications.

---

6. Separation of Concerns & Handoff to Ongoing Engineering Workflow

To avoid conflating repository bootstrapping with day-to-day software engineering, responsibilities are strictly separated between two dedicated skills:

flowchart LR
    Repo["Unfamiliar Repository"] --> Onboard["repo-onboarding\n(Prepare & Scaffold)"]
    Onboard --> Ready["Onboarded Repository\n(AGENTS.md & project-context/)"]
    Ready --> Eng["engineering-workflow\n(Develop, Fix, Refactor, Architect)"]

6.1. Boundary Between Onboarding and Engineering

Skill	Primary Responsibility	Boundaries & Non-Goals
repo-onboarding	Prepares an unfamiliar repository: investigates stack, discovers commands, detects agents, establishes project-context/ (anti-overwrite protected), generates customized AGENTS.md, and produces an onboarding report.	Never writes application source code. Never begins implementing features automatically after onboarding. Stops after presenting report.
engineering-workflow	Guides ongoing development tasks: feature implementation, bug fixing, refactoring, and architectural redesigns using risk-based classification, incremental slices, TDD, and engineering review.	Activated only upon specific engineering requests after onboarding is complete.

6.2. Transition Protocol

Once Phase 5 of onboarding completes and the onboarding report is delivered:

1. The onboarding agent reports completion and asks the user for team conventions.
2. The agent stops and waits for user instructions.
3. Subsequent user coding requests are governed by engineering-workflow rules, which are embedded directly into the generated AGENTS.md.

---

7. Five-Phase Onboarding Execution

The skill must follow five sequential phases when initially onboarding a repository.

Phase 1 — Deep Repository Investigation

Objective: Understand the actual repository.

7.1.1. Inspect Repository Structure

Identify:

• Repository root.
• Project type.
• Source directories.
• Test directories.
• Configuration files.
• Documentation.
• Infrastructure.
• CI/CD.
• Existing agent instructions.
• Git state.

Determine whether the project is:

• New or existing.
• Monolithic or multi-service.
• A monorepo.
• Backend, frontend, mobile, or desktop.
• A library or SDK.
• An AI/ML or data engineering project.
• An infrastructure repository.

A repository may belong to multiple categories.

7.1.2. Detect Technology Stack

Inspect relevant configuration files:

• JavaScript / TypeScript: package.json, tsconfig.json, pnpm-lock.yaml, yarn.lock, package-lock.json, bun.lock, bun.lockb
• Python: pyproject.toml, requirements.txt, Pipfile, poetry.lock, uv.lock, setup.py
• Go: go.mod, go.sum
• Rust: Cargo.toml, Cargo.lock
• Java / Kotlin: pom.xml, build.gradle, build.gradle.kts
• .NET: *.csproj, *.sln, Directory.Build.props
• Containers and Infrastructure: Dockerfile, compose.yaml, docker-compose.yml, Terraform files, Kubernetes manifests, Helm charts

The list is not exhaustive. Inspect additional technologies when evidence indicates their presence.

7.1.3. Discover Core Commands

Discover actual commands for:

Category	Purpose
Development	Start or run the application
Build	Production build
Lint	Static code analysis
Format	Code formatting
Typecheck	Type verification
Unit Test	Unit tests
Integration Test	Integration tests
E2E Test	End-to-end tests
Database	Migration and initialization
Deployment	Deployment workflows

Rules:

• Extract commands from repository configuration.
• Identify the actual package manager.
• Prefer existing project scripts.
• Do not assume conventional commands exist.
• Do not invent missing commands.
• Distinguish discovered commands from executed commands.
• Record unavailable commands explicitly.

7.1.4. Inspect Existing Documentation

Inspect:

• README.md, CONTRIBUTING.md, CHANGELOG.md
• Architecture documentation.
• Specifications.
• .github/workflows/
• Git hooks.
• .gitignore.
• Existing agent instructions.

Identify:

• Coding conventions.
• Branch naming.
• Commit conventions.
• PR requirements.
• CI/CD workflows.
• Deployment policies.
• Testing requirements.

7.1.5. Produce Investigation Summary

Report:

• Project type.
• Programming languages.
• Frameworks.
• Major dependencies.
• Architecture.
• Package managers.
• Core commands.
• Testing infrastructure.
• CI/CD.
• Existing documentation.
• Potential gaps and risks.

Label all findings as Verified, Inferred, or Unknown.

Do not modify repository files during investigation.

---

Phase 2 — Agent Environment Detection

Objective: Determine the required agent instruction files.

Supported targets:

Environment	Instruction File
General-purpose agents	AGENTS.md
Claude Code	CLAUDE.md
Gemini CLI / Antigravity	GEMINI.md

7.2.1. Automatic Detection Mechanism

The skill attempts to detect the active coding agent using:

1. Runtime Context & Environment Indicators:
   • Antigravity / Gemini CLI (e.g., active identity, execution context).
   • Claude Code (e.g., CLAUDE_CODE environment variable or Claude process trees).
   • IDE rules (.cursorrules, .windsurfrules, Copilot instructions).
2. Repository Evidence:
   • Existing files in the repository root (AGENTS.md, CLAUDE.md, GEMINI.md).

7.2.2. User Confirmation Gate (Mandatory when Uncertain)

Automatic detection may identify the current executing agent, but cannot assume the entire team's workflow or multi-agent preferences.

Rule: If the target agent environment is ambiguous, unknown, or not 100% confirmed by existing repository conventions, the agent MUST pause and ask the user for confirmation before generating any instruction files:

• Option 1: Multi-Agent Setup (Recommended): AGENTS.md as shared SSoT + lightweight tool-specific CLAUDE.md and GEMINI.md.
• Option 2: Gemini CLI / Antigravity Only: Standalone GEMINI.md.
• Option 3: Claude Code Only: Standalone CLAUDE.md.
• Option 4: General Agent Only: Standalone AGENTS.md.

7.2.3. Multi-Agent Strategy

When multiple agents are used, prefer:

AGENTS.md
CLAUDE.md
GEMINI.md

Use AGENTS.md as the shared primary instruction file. CLAUDE.md and GEMINI.md should reference AGENTS.md and contain only tool-specific instructions.

7.2.4. Important Rules

• Detect existing files before creating anything.
• Preserve custom instructions.
• Do not duplicate shared guidelines.
• Always ask the user if the target environment is ambiguous or unverified.
• Generate only the instruction files that are actually needed.
• If only one agent is used, generate a standalone instruction file based on the corresponding template.

---

Phase 3 — Documentation Scaffolding

Objective: Establish the project documentation structure.

7.3.1. Strict Anti-Overwrite Guard for project-context/

Rule: Only scaffold project-context/ when the directory DOES NOT exist. Never overwrite an existing project-context/ directory.

Before creating or touching any documentation files, check:

[ -d "project-context" ]

1. If project-context/ ALREADY EXISTS:

   • DO NOT recreate, overwrite, or wipe the directory.
   • DO NOT overwrite any existing files (README.md, DECISIONS.md, PLAN.md, PROGRESS.md, etc.).
   • Inspect all existing files and directory structure inside project-context/.
   • Compare existing documents against the standard layout:
     • Record existing files as Preserved.
     • Identify any missing essential documents (e.g., missing BUG_LOG.md or CHECKLIST.md).
   • Report findings to the user.
   • Ask the user for explicit confirmation before scaffolding ONLY the missing files. If the user declines, keep the existing documentation intact without modification.

2. If project-context/ DOES NOT EXIST:

   • Proceed to scaffold the baseline structure fresh using templates in resources/.
   • Populate templates with verified project information gathered in Phase 1.
   • Use explicit placeholders such as [To be determined] when information is unavailable.
   • Never fabricate project requirements, decisions, commands, test results, or milestones.

Create or establish the primary documentation (when missing):

• project-context/README.md
• project-context/DECISIONS.md
• project-context/PLAN.md
• project-context/PROGRESS.md
• project-context/bugs/BUG_LOG.md
• project-context/testing/CHECKLIST.md

Create additional directories (specs/, tasks/, progress/, references/) only when justified. Do not generate historical weekly reports without actual historical information.

---

Phase 4 — Agent Guideline Generation

Objective: Generate customized agent instructions.

Use the appropriate templates and populate them with actual investigation results. All generated instructions must include:

7.4.1. Project Overview

• Project purpose.
• Technology stack.
• Architecture.
• Repository structure.
• Important configuration files.

7.4.2. Three Core Principles

1. Single Source of Truth.
2. No Unapproved Assumptions.
3. Definition of Done.

7.4.3. Risk-Based Engineering Workflow

Incorporate the core disciplines of engineering-workflow:

1. Three-Level Work Classification:
   • Level 1 (Small Change): Fast path (Understand → Analyze → Implement → Verify → Review → Finalize). No unnecessary specs.
   • Level 2 (Feature Development): Standard path (Analyze → Clarify → Plan Slices → Approval → Incremental Slices → Finalize).
   • Level 3 (Architectural Change): Deep path (Investigate → Options Analysis → ADR in DECISIONS.md → Approval → Phased Slices → Finalize).
2. Incremental Slicing & TDD:
   • Decompose multi-component work into small, independently verifiable slices.
   • Apply TDD (Red $\rightarrow$ Green $\rightarrow$ Refactor) where testing infrastructure exists.
3. Failure Forensics: Stop on failure; distinguish implementation bug vs test bug vs env issue vs pre-existing failure.

7.4.4. Proportional Verification & Engineering Review

1. Calibrated Verification: Run checks proportional to blast radius (automated checks, engineering review, application verification).
2. Honest Status Taxonomy: Report explicitly as PASS, FAIL, BLOCKED, NOT RUN, or NOT APPLICABLE. Segregate pre-existing test failures.
3. Ten-Point Engineering Review: Execute self-review covering requirement fulfillment, architectural consistency, simplicity, edge cases, error handling, test quality, security, backward compatibility, documentation, and blast radius control.

7.4.5. Documentation Map

Link to:

• project-context/README.md
• project-context/DECISIONS.md
• project-context/PLAN.md
• project-context/PROGRESS.md
• project-context/progress/
• project-context/specs/
• project-context/tasks/
• project-context/bugs/
• project-context/testing/

7.4.6. Repository-Specific Commands

Populate actual discovered commands. Include command status:

• Verified.
• Discovered but not executed.
• Unavailable.

7.4.7. Git and Commit Policies

Use existing team conventions. If none exist, propose defaults and request confirmation. Never automatically commit or push.

7.4.8. Session Start and End Guidelines

At session start:

1. Read relevant agent instructions.
2. Read project-context/README.md.
3. Review project-context/PROGRESS.md.
4. Read relevant decisions and specifications.
5. Inspect the current repository state.

At meaningful session completion:

1. Summarize changes.
2. Report verification results.
3. Update relevant progress information.
4. Record confirmed decisions.
5. Identify blockers and pending work.

---

Phase 5 — Verification and Onboarding Report

Objective: Verify the scaffolding and align with the user.

7.5.1. Verify Generated Files

Check:

• All intended files exist.
• Templates are populated correctly.
• Relative links are valid.
• Documentation references are consistent.
• No duplicated instructions exist.
• No sensitive information was included.
• Existing files were preserved.
• No application source files were modified.

7.5.2. Produce Onboarding Report

Include:

• Repository Overview: Project type, technology stack, architecture, major dependencies.
• Core Commands: Dev, lint, format, typecheck, tests, build, along with execution status.
• Agent Environment: Detected agents, generated instruction files, primary instruction file, SSoT strategy.
• Documentation Structure: List created, reused, skipped, and pending files.
• Outstanding Questions: Identify missing team conventions and unresolved decisions.

7.5.3. User Alignment

Ask:

"Are there any team-specific conventions or project requirements that should be incorporated into the guidelines before development begins?"

Examples:

• Branch naming.
• Commit message format.
• Architecture preferences.
• Code review requirements.
• Deployment procedures.
• Testing policies.
• Documentation conventions.

Stop after presenting the report and wait for user feedback. Do not automatically start implementing features.

---

8. Agent Instruction Template Specifications

All three agent templates must support both standalone and multi-agent configurations.

8.1. AGENTS.template.md

Purpose: Shared, tool-agnostic repository operating guidelines.

Required sections:

1. Project Overview.
2. Core Principles.
3. Project Documentation.
4. Development Workflow.
5. Verification Requirements.
6. Repository Commands.
7. Coding Conventions.
8. Git and Commit Policies.
9. Progress and Task Tracking.
10. Bug Management.
11. Session Start and End Guidelines.

When multiple agents are used, this is the primary source of shared instructions.

8.2. CLAUDE.template.md

Purpose: Claude Code entry point.

When AGENTS.md is primary:

# Claude Code Instructions

## Shared Repository Guidelines
The authoritative shared guidelines are maintained in [AGENTS.md](./AGENTS.md).
Read AGENTS.md before starting development work.
Follow all shared coding conventions, development workflows, documentation requirements, and verification policies.

## Project Context
Project documentation is maintained in: `project-context/`
Read the relevant documentation before beginning a task.

## Claude Code-Specific Instructions
[Insert only Claude Code-specific instructions.]
Do not duplicate shared repository guidelines.

When Claude Code is the only agent, generate complete standalone guidelines using the shared template structure.

8.3. GEMINI.template.md

Purpose: Gemini CLI / Antigravity entry point.

When AGENTS.md is primary:

# Gemini Instructions

## Shared Repository Guidelines
The authoritative shared guidelines are maintained in [AGENTS.md](./AGENTS.md).
Read AGENTS.md before starting development work.
Follow all shared coding conventions, development workflows, documentation requirements, and verification policies.

## Project Context
Project documentation is maintained in: `project-context/`
Read the relevant documentation before beginning a task.

## Gemini-Specific Instructions
[Insert only Gemini CLI / Antigravity-specific instructions.]
Do not duplicate shared repository guidelines.

When Gemini is the only agent, generate complete standalone guidelines.

Tool-specific instructions must be compatible with the actual agent's instruction-loading mechanism. Do not assume that every tool automatically reads every instruction filename.

---

9. Optional Repository Scanner

File: scripts/scan_repo.py

Purpose: Provide preliminary repository metadata to support Phase 1.

9.1. Detection Capabilities

Detect:

• Repository root.
• Programming languages.
• Framework indicators.
• Package managers.
• Dependency manifests.
• Lockfiles.
• Build configurations.
• Test configurations.
• Lint and formatting configurations.
• Container and infrastructure files.
• CI/CD workflows.
• Existing agent instruction files.
• Existing documentation structure.

9.2. Output

Produce structured JSON to stdout. Include:

• Repository metadata.
• Detected technologies.
• Configuration paths.
• Package manager candidates.
• Available project scripts.
• Existing documentation.
• Existing agent instructions.

9.3. Safety

The scanner must:

• Never modify repository files.
• Never install dependencies.
• Never execute arbitrary project scripts.
• Never expose secret values.
• Exclude unnecessary directories such as .git, node_modules, .venv, and build outputs.
• Handle missing files gracefully.

The agent must independently inspect and verify scanner findings. The scanner is optional. The skill must remain functional without it.

---

10. Safety and Preservation Rules

These rules apply to all phases.

10.1. File Preservation & Project-Context Protection

Before creating or modifying a file:

1. Check whether it exists.
2. Read its contents.
3. Determine whether it can be reused.
4. Identify potential conflicts.
5. Request authorization before destructive replacement.

Strict Anti-Overwrite Rule for project-context/:

• NEVER overwrite, recreate, or delete an existing project-context/ directory.
• If project-context/ already exists, treat all existing documentation as the authoritative Single Source of Truth.
• Never overwrite existing files (README.md, DECISIONS.md, PLAN.md, PROGRESS.md, etc.).
• Only propose scaffolding missing files, and only proceed after explicit user confirmation.

Never silently overwrite existing documentation.

10.2. Source Code Protection

Onboarding must not modify application source code. Do not:

• Refactor source code.
• Change business logic.
• Upgrade dependencies.
• Install packages.
• Change application behavior.
• Modify infrastructure configuration.

These activities require a separate user request.

10.3. Sensitive Information

Never copy secrets or credentials into:

• Agent instructions.
• Project documentation.
• Reports.
• Scanner output.
• Git commits.

Do not print secret environment variable values.

10.4. Git Safety

Before Git-related investigation:

• Inspect the working tree.
• Preserve uncommitted changes.
• Never run destructive cleanup.
• Never reset the repository.
• Never rewrite Git history.
• Never commit or push automatically.

10.5. Existing Convention Preservation

An existing repository may already have a mature development workflow. The skill must integrate with that workflow rather than blindly replacing it.

---

11. Onboarding Quality Gates

Before reporting successful onboarding, verify:

ID	Requirement	Expected Result
QG-01	Repository investigation	Stack identified with evidence
QG-02	Core commands	Discovered or explicitly unavailable
QG-03	Existing documentation	Inspected and preserved
QG-04	Agent environment	Target agents identified or confirmed with user
QG-05	Single Source of Truth	Instruction ownership established
QG-06	Documentation structure	Required documents established without overwriting existing project-context/
QG-07	Agent instructions	Customized from actual findings
QG-08	Progress management	Current state and weekly archive defined
QG-09	Roadmap management	Project roadmap separated from feature plans
QG-10	Git safety	Sensitive and generated files considered
QG-11	File integrity	No unintended destructive modifications
QG-12	Final report	Created, reused, skipped, and pending items reported

Possible onboarding statuses:

• PASS: All applicable requirements satisfied.
• PARTIAL: Some requirements remain incomplete.
• BLOCKED: User input or access is required.

Do not report successful completion if critical quality gates remain unresolved.

---

12. Final Execution Contract

When activated, the skill must follow this sequence:

1. Investigate the repository.
2. Summarize findings and uncertainties.
3. Determine target agent environment (ask user to confirm if ambiguous or unverified).
4. Establish the Single Source of Truth strategy.
5. Inspect project-context/ (preserve if existing and confirm before adding missing files; scaffold only if absent).
6. Generate customized agent instructions.
7. Verify generated files and repository integrity.
8. Present the onboarding report.
9. Ask for remaining team-specific conventions.
10. Stop and wait for user feedback.

The skill must not automatically proceed to feature development. It must not fabricate information to make documentation appear complete. It must prefer accurate, maintainable documentation over unnecessary files.

---

13. Success Criteria

The skill is successful when it can onboard an unfamiliar repository and establish a reliable AI-assisted development framework without making unsupported assumptions or damaging existing project files.

A successfully onboarded repository must have:

1. An evidence-based understanding of its codebase.
2. A centralized project-context/ documentation system.
3. A clear distinction between project roadmap and feature implementation plans.
4. A current progress document and historical weekly archive.
5. Consistent instructions across supported AI coding agents.
6. Traceable architecture and product decisions.
7. Structured feature specifications and task execution.
8. Explicit verification requirements.
9. A clear boundary between agent autonomy and user approval.