diff --git a/.gemini/skills/fix-pr/README.md b/.gemini/skills/fix-pr/README.md new file mode 100644 index 0000000000..28adbfafca --- /dev/null +++ b/.gemini/skills/fix-pr/README.md @@ -0,0 +1,31 @@ +# Fix PR Skill + +The `fix-pr` skill enables the Gemini CLI agent to autonomously and iteratively +fix a pull request until it is mergeable and passes all quality checks. + +## When to use fix-pr + +- **Autonomous fixing**: Move a PR from failing to green without manual + intervention. +- **Iterative loops**: Automatically handle the "fix -> push -> wait for CI" + cycle. +- **Context preservation**: Maintain context across multiple fix attempts. + +## Sync vs Offload + +This skill is designed to be versatile: + +- **Synchronous mode**: Activate the skill in your current terminal for + quick fixes or conflict resolution. +- **Offloaded mode**: Use `npm run offload fix` to launch an iterative + fix loop on a remote workstation, keeping your local machine free. + +## Objective + +The goal is to move a PR from its current state (failing tests, merge conflicts, +or unaddressed comments) to a "Ready to Merge" state. + +## Technical details + +The skill uses the `gh` CLI and a specialized `wait-for-ci` utility to monitor +remote status. It is governed by the project's standard security policies. diff --git a/.gemini/skills/offload/README.md b/.gemini/skills/offload/README.md index fe1f2677a6..11951e6e6f 100644 --- a/.gemini/skills/offload/README.md +++ b/.gemini/skills/offload/README.md @@ -7,14 +7,39 @@ dedicated terminal window. ## Why use offload? -- **Protect local resources**: Heavy build and lint suites are offloaded to a - beefy remote workstation. -- **Context efficiency**: The main Gemini session remains interactive while - background tasks provide high-fidelity feedback. +As a maintainer, you eventually reach the limits of how much work you can manage +at once on a single local machine. Heavy builds, concurrent test suites, and +multiple PRs in flight can quickly overload local resources, leading to +performance degradation and developer friction. + +While manual remote management is a common workaround, it is often cumbersome +and context-heavy. The `offload` skill addresses these challenges by providing: + +- **Elastic compute**: Offload resource-intensive build and lint suites to a + beefy remote workstation, keeping your local machine responsive. +- **Context preservation**: The main Gemini session remains interactive and + focused on high-level reasoning while automated tasks provide real-time + feedback in a separate window. +- **Automated orchestration**: The skill handles worktree provisioning, + script synchronization, and environment isolation automatically. - **True parallelism**: Infrastructure validation, CI checks, and behavioral proofs run simultaneously, compressing a 15-minute process into 3 minutes. -- **Behavioral verification**: The worker physically exercises the new code - to provide empirical proof that it works. + +## Agentic skills: Sync or Offload + +The `offload` system is designed to work in synergy with specialized agentic +skills. These skills can be run **synchronously** in your current terminal for +quick tasks, or **offloaded** to a remote session for complex, iterative loops. + +- **`review-pr`**: Conducts high-fidelity, behavioral code reviews. It assumes + the infrastructure is already validated and focuses on physical proof of + functionality. +- **`fix-pr`**: An autonomous "Fix-to-Green" loop. It iteratively addresses + CI failures, merge conflicts, and review comments until the PR is mergeable. + +When you run `npm run offload fix`, the orchestrator provisions the remote +environment and then launches a Gemini CLI session specifically powered by the +`fix-pr` skill. ## Playbooks diff --git a/.gemini/skills/review-pr/README.md b/.gemini/skills/review-pr/README.md new file mode 100644 index 0000000000..180e6054d0 --- /dev/null +++ b/.gemini/skills/review-pr/README.md @@ -0,0 +1,34 @@ +# Review PR Skill + +The `review-pr` skill enables the Gemini CLI agent to conduct high-fidelity, +behavioral code reviews that go beyond simple static analysis. + +## When to use review-pr + +- **Deep verification**: Verify that a feature actually works by executing + it in a live environment. +- **Infrastructure awareness**: Leverage build and CI results to focus on + empirical proof of functionality. +- **Interactive collaboration**: Discuss findings and explore edge cases + with the agent in real-time. + +## Sync vs Offload + +This skill supports two primary modes: + +- **Synchronous mode**: Activate the skill locally for quick, high-level + analysis of a peer's PR. +- **Offloaded mode**: Use `npm run offload review` to conduct a + full-scale behavioral review on a remote workstation with parallelized + infrastructure validation. + +## Objective + +Conduct a thorough review that involves physically proving the feature works +through terminal scripts and command execution. + +## Technical details + +The skill assumes the infrastructure (build and CI) is already being validated +and focuses on empirical proofs. It uses the `extract-failures.ts` utility to +automatically identify regressions in CI logs.