fork-ops

name	fork-ops
description	Use when operating a maintained repository fork, validating .agents/fork-ops.toml, assessing fork-ops readiness, inspecting upstream tracks, or migrating fork-related agent materials into Fork Ops.

Fork Ops

Use this skill when the task concerns a maintained fork: a repository operated with an explicit upstream, local contracts, checked-in fork ops config, and repo-owned agent guidance.

Authority Order

1. Read .agents/fork-ops.toml when it exists.
2. Read fork-local docs and agent instructions named by local_surfaces.
3. Read upstream source and docs when fork-local authority points there.
4. Use live Git and GitHub state to verify Descriptive Fork Facts.
5. Label inferred conclusions when direct evidence is unavailable.

Fork-local authority is the source of truth for the specific fork. The plugin supplies reusable operations and does not replace checked-in fork policy.

Tool Surfaces

• CLI: uv run --project ${PLUGIN_ROOT} fork-ops ...
• Plugin health: uv run --project ${PLUGIN_ROOT} fork-ops plugin health
• Workflow catalog: uv run --project ${PLUGIN_ROOT} fork-ops workflow catalog
• MCP: fork_ops_plugin_health, fork_ops_workflow_catalog, fork_ops_workflow_migration_inventory, fork_ops_config_read, fork_ops_config_validate, fork_ops_capability_report, fork_ops_migration_assessment, fork_ops_equipment_migration_preflight, fork_ops_migration_plan, fork_ops_migration_dry_run, fork_ops_migration_execute, fork_ops_migration_blocker_resolution, fork_ops_migration_config_patch, fork_ops_schema
• Schema: ${PLUGIN_ROOT}/schema/fork-ops.schema.json
• Operation docs: ${PLUGIN_ROOT}/docs/operation-guide.md

Default Workflow

1. Run a capability report before choosing an operation:

   uv run --project ${PLUGIN_ROOT} fork-ops plugin health
   uv run --project ${PLUGIN_ROOT} fork-ops workflow catalog
   uv run --project ${PLUGIN_ROOT} fork-ops capability report --repo /path/to/fork
   

2. For config questions, validate the config before trusting dependent policy:

   uv run --project ${PLUGIN_ROOT} fork-ops config validate --repo /path/to/fork --required-level track-aware
   

3. For existing fork materials, start with read-only migration assessment:

   uv run --project ${PLUGIN_ROOT} fork-ops migration assess --repo /path/to/fork
   

4. For prior equipment, run read-only equipment preflight before relying on replacement or activation claims:

   uv run --project ${PLUGIN_ROOT} fork-ops migration preflight --repo /path/to/fork --source-root /path/to/global-skills
   

5. For a reviewed migration path, generate a non-mutating migration plan:

   uv run --project ${PLUGIN_ROOT} fork-ops migration plan --repo /path/to/fork
   

6. For a migration preview, run a non-mutating dry run. If the plan includes semantic_coverage.incomplete, guarded config creation is available only when every affected source path has a reviewed retain decision in the migration review artifact or a reviewed retain_authoritative_owner disposition in the equipment review record:

   uv run --project ${PLUGIN_ROOT} fork-ops migration dry-run --repo /path/to/fork
   

7. For a reviewed config migration whose dry run has no blockers, run guarded migration execution:

   uv run --project ${PLUGIN_ROOT} fork-ops migration execute --repo /path/to/fork
   

8. For a first config draft, generate a non-mutating proposed config patch and review it against the source materials before applying it:

   uv run --project ${PLUGIN_ROOT} fork-ops migration propose-config --repo /path/to/fork --format toml
   

9. For a migration blocker, explain the blocker from the workflow output instead of inferring from prose:

   uv run --project ${PLUGIN_ROOT} fork-ops migration explain-blocker --input /path/to/migration-output.json --blocker-code semantic_coverage.incomplete
   

10. Treat sync, publication, equipment edits, equipment disabling, source-material removal, and arbitrary migration mutations as unavailable unless the config capability level and tool surface explicitly support them.

Escalation Boundaries

Escalate when fork-local authority is missing, contradictory, or insufficient for a stakeholder decision. Escalate when an operation requires a control surface the agent does not have. Make the return contract concrete: requested decision, command output, URL, or artifact path.

Current Capability

This foundation version targets track-aware. Capabilities include discovering, parsing, validating, normalizing, and reporting config state. The implementation inspects local Git remotes and configured upstream track refs. Migration capabilities include assessment, equipment migration preflight, reviewed non-mutating migration plans with source material dispositions, review artifact decision choices, proposed equipment review records, activation-readiness reports, dry runs, config proposals, replayable wet-run metadata, operator-readable narratives, blocker explanations, and guarded config creation when dry-run blockers are resolved. Reviewed retain decisions and reviewed retain_authoritative_owner equipment dispositions can unblock config creation for incomplete semantic coverage while retained authority remains preserved and source-material replacement/removal stays unavailable. It does not execute broad upstream sync, PR publication closeout, equipment edits, equipment disabling, source-material removal, or arbitrary migration edits.