onboard-repo（机载回购协议）

Skill: Onboard Repository (Orchestrator)

Purpose

This skill does not perform analysis itself. It is a meta skill that orchestrates a fixed sequence of atomic skills to rapidly onboard a new or unfamiliar repository — producing architecture findings, standardized documentation, and actionable recommendations in one pass. Use it when joining a new project, inheriting a codebase, or preparing a repository for team onboarding. For individual tasks (e.g. only generating a README or only reviewing architecture), invoke the corresponding atomic skill directly (generate-standard-readme, review-architecture, etc.).

Core Objective

Primary Goal: Produce a comprehensive repository onboarding report by orchestrating atomic skills in a fixed sequence, aggregating architecture findings, standardized documentation, and recommendations.

Success Criteria (ALL must be met):

1. ✅ Codebase review completed: Architecture, patterns, and tech debt assessed via review-codebase
2. ✅ Architecture findings generated: Module boundaries, dependency direction, and coupling assessed via review-architecture
3. ✅ README generated or improved: Standardized front-page documentation produced via generate-standard-readme
4. ✅ AGENTS.md generated or improved: Agent entry contract established via write-agents-entry
5. ✅ Aggregated report delivered: All findings, generated docs, and recommendations merged into a single onboarding report

Acceptance Test: Can a new team member understand the repository's architecture, navigate its structure, and start contributing based solely on the onboarding output?

Scope Boundaries

This skill handles:

• Orchestrating atomic onboarding skills in fixed order
• Confirming onboarding scope with user (repo root or specific directory)
• Collecting findings and artifacts from each atomic skill
• Aggregating into a single onboarding report with recommendations

This skill does NOT handle:

• Direct code analysis (delegated to review-codebase and review-architecture)
• Direct documentation authoring (delegated to generate-standard-readme and write-agents-entry)
• Code review for correctness or style (use review-code)
• Implementation of fixes (use development/refactoring skills)
• CI/CD setup (use generate-github-workflow)

Handoff point: When the aggregated onboarding report is complete, hand off to user for review or to development workflow for implementing recommendations.

Use Cases

• New team member onboarding: Developer joins a project and needs a rapid overview of architecture, patterns, documentation, and contribution guidelines.
• Repository acquisition or handoff: Team inherits a codebase from another team or project; need to understand structure, quality, and gaps before taking ownership.
• Open-source preparation: Before making a repository public, run the full pipeline to ensure documentation, agent entry, and architecture quality meet standards.

When to use: When the user wants a comprehensive onboarding pass across analysis and documentation dimensions. When the user wants only one dimension (e.g. "generate a README" or "review architecture"), use the atomic skill instead.

Behavior

Orchestration only

• Do not analyze code or write documentation yourself. Do invoke (or simulate invoking) the following skills in order, then aggregate their outputs.
• Execution order is fixed so that Cursor or an agent can follow it step by step.

Interaction policy

• Pre-flight: Before execution, confirm the onboarding scope with the user. Offer: *Onboard from repo root?* [default] *Or pick a subdirectory?* — user selects; do not assume.
• Existing docs: If README.md or AGENTS.md already exist, ask: *Improve existing documentation?* [default: Yes] *Or skip documentation steps?*
• Optional step: discover-skills is optional. If the user wants only analysis and docs, skip it and note the skip in the report.
• Always state which steps were executed and which were skipped (with reason).

Defaults

Pre-flight: confirm before running

Resolve the following with the user once, before executing any step. Prefer confirm default or select from options; avoid asking for free-text input when a default exists.

After pre-flight, run the pipeline without further questions; report which steps ran and which were skipped.

Execution order

When performing this skill, sequentially apply the following steps. For each step, load and run the corresponding skill's instructions, collect its output, then proceed to the next step.

1. review-codebase — Understand architecture, patterns, tech debt Load review-codebase and run it on the confirmed scope. Collect all findings (architecture, design, tech debt). This step provides the foundational understanding for subsequent steps.
2. review-architecture — Assess boundaries, dependencies, coupling Load review-architecture and run it on the same scope. Collect architecture-specific findings (module boundaries, dependency direction, cyclic dependencies, interface stability, coupling). This deepens the structural understanding from step 1.
3. generate-standard-readme — Create or improve the README Load generate-standard-readme and run it. Use findings from steps 1–2 to inform content (project purpose, architecture overview, setup instructions). If README exists, improve it; otherwise create from scratch.
4. write-agents-entry — Create or improve AGENTS.md Load write-agents-entry and run it. Use findings from steps 1–2 to establish the Agent entry contract (project identity, authoritative sources, behavioral expectations). If AGENTS.md exists, improve it; otherwise create from scratch.
5. discover-skills *(optional)* — Recommend additional skills Load discover-skills and run it on the repository. Based on the stack, patterns, and gaps identified in steps 1–2, recommend skills that would benefit the project (e.g. language-specific review skills, CI/CD skills). If skipped, note in report.
6. Aggregation Merge all collected outputs into one onboarding report. Structure the report using the diagnostic-report format (see Appendix). Include:

- Summary of repository (language, framework, size, key patterns) - Architecture findings (from steps 1–2) - Documentation status (generated or improved README + AGENTS.md) - Skill recommendations (from step 5, if run) - Action items and next steps

Summary for Cursor/Agent

• When performing this skill, sequentially apply:

1. review-codebase (architecture, patterns, debt) 2. review-architecture (boundaries, dependencies, coupling) 3. generate-standard-readme (create or improve README) 4. write-agents-entry (create or improve AGENTS.md) 5. discover-skills (optional; recommend skills) 6. aggregate all outputs into one onboarding report

• Aggregate all outputs into a single diagnostic report using the format in the Appendix. Do not analyze code or write docs in this skill; only orchestrate and aggregate.

Input & Output

Input

• Repository scope: Path to the repository root or a specific directory to onboard.
• User preferences: Whether to improve existing docs, skip optional steps, etc.

Output

• Single aggregated onboarding report in diagnostic-report format (see Appendix) containing: repository summary, architecture findings, documentation status, skill recommendations, and action items.
• Generated or improved documentation: README.md and AGENTS.md files (produced by delegated skills).

Restrictions

Hard Boundaries

• Do not perform any code analysis inside this skill. Only orchestrate other skills and aggregate.
• Do not write documentation directly. Delegate to generate-standard-readme and write-agents-entry.
• Do not change the execution order; keep review-codebase → review-architecture → generate-standard-readme → write-agents-entry → discover-skills.
• Do not invent findings; only include outputs produced by the atomic skills you run.

Skill Boundaries (Avoid Overlap)

Do NOT do these (other skills handle them):

• Code review: Running full review pipeline → Use review-code
• Diff review: Reviewing current changes → Use review-diff
• Security audit: Deep security analysis → Use review-security
• CI/CD setup: Creating workflows → Use generate-github-workflow
• Skill creation: Writing new skills → Use refine-skill-design

When to stop and hand off:

• Onboarding report delivered → User reviews and decides next steps
• User asks "review my code" → Hand off to review-code
• User asks "set up CI" → Hand off to generate-github-workflow

Self-Check

Core Success Criteria (ALL must be met)

• Codebase review completed: Architecture, patterns, and tech debt assessed via review-codebase
• Architecture findings generated: Boundaries, dependencies, coupling assessed via review-architecture
• README generated or improved: Standardized documentation produced via generate-standard-readme
• AGENTS.md generated or improved: Agent entry contract established via write-agents-entry
• Aggregated report delivered: All findings, docs, and recommendations in one diagnostic report

Process Quality Checks

• Was the execution order followed (review-codebase → review-architecture → generate-standard-readme → write-agents-entry → discover-skills)?
• Were pre-flight items (scope, existing docs handling, optional steps) confirmed with the user before running?
• Were findings only collected from the atomic skills, not invented?
• Did this skill refrain from analyzing code or writing documentation directly?
• Were skipped steps noted with reasons in the report?

Acceptance Test

Can a new team member understand the repository's architecture, navigate its structure, and start contributing based solely on the onboarding output?

If NO: Onboarding is incomplete. Identify missing information and re-run relevant steps. If YES: Onboarding is complete. Hand off to user.

Examples

Example 1: Full onboarding of a Node.js monorepo

• Input: User says "onboard this repo" pointing at a Node.js monorepo with existing README but no AGENTS.md.
• Expected:

1. Run review-codebase on repo root → collect architecture findings (monorepo structure, shared packages, build pipeline, tech debt). 2. Run review-architecture → collect boundary and dependency findings (package coupling, cyclic deps, interface stability). 3. Run generate-standard-readme → improve existing README with standardized structure (add missing sections: architecture overview, setup instructions, contribution guide). 4. Run write-agents-entry → create AGENTS.md from scratch (project identity, authoritative sources, behavioral expectations). 5. Run discover-skills → recommend review-typescript, review-react (frontend packages), generate-github-workflow (missing CI). 6. Aggregate into onboarding report: repository summary, architecture findings, documentation status (README improved, AGENTS.md created), recommendations.

Example 2: Onboarding a Go microservice

• Input: User says "onboard src/services/auth-service" targeting a Go authentication microservice with no existing docs.
• Expected:

1. Run review-codebase on src/services/auth-service → collect findings (handler patterns, middleware, database layer, test coverage gaps). 2. Run review-architecture → collect findings (layer boundaries, dependency injection, external API coupling). 3. Run generate-standard-readme → create README from scratch. 4. Run write-agents-entry → create AGENTS.md from scratch. 5. Run discover-skills → recommend review-go, review-security (auth service), review-sql (database layer). 6. Aggregate into onboarding report.

Edge case: Empty or minimal repository

• Input: User says "onboard this repo" on a newly initialized repository with only a .gitignore and empty src/ directory.
• Expected:

1. Run review-codebase → findings note: no meaningful code to analyze; report repository as empty/scaffolding stage. 2. Run review-architecture → findings note: no architecture to assess; skip with reason "no code present". 3. Run generate-standard-readme → create a minimal README with project name and placeholder sections. 4. Run write-agents-entry → create a minimal AGENTS.md with project identity and placeholder sections. 5. Run discover-skills → recommend skills based on intended stack (if detectable from config files like package.json, go.mod, etc.) or skip with reason "insufficient context". 6. Aggregate: report clearly states the repository is at scaffolding stage, documentation has been bootstrapped, and recommends running onboard-repo again once code is in place.

Appendix: Output contract

The aggregated onboarding report MUST use the following diagnostic-report structure:

Finding format (for architecture findings)

Findings within the Architecture Findings section use the standard format:

Report format

# Onboarding Report: <repository-name>

## Repository Summary
<!-- Language, framework, size, key patterns -->

## Architecture Findings
<!-- Grouped findings from review-codebase + review-architecture -->

## Tech Debt & Quality
<!-- Debt items, pattern violations -->

## Documentation Status
<!-- README and AGENTS.md status -->

## Skill Recommendations
<!-- Recommended skills with install commands -->

## Action Items
<!-- Prioritized next steps -->