Communitygithub.com

ASoudy/AGS

当收到前沿AI提供的详细实施计划时,在OpenCode中配合非前沿编码模型执行。验证计划与真实仓库的一致性,将计划分解为安全步骤,验证每一步,检查差异,并防止破坏性更改。触发条件:收到来自Claude Opus/GPT-5等的多步计划,执行预先编写的规范,实施详细的PR描述,或被要求“逐步执行此计划”。

AGS 是什么?

ASoudy/AGS 是一个专门为在OpenCode环境中执行由前沿AI(如Claude Opus、GPT-5)生成的详细实施计划而设计的AI代理技能。它的核心原则是“前沿计划是一个强假设,而非事实”,因此它通过严格的验证流程防止不准确或破坏性的代码更改。该技能支持自动提交和推送,但会避免直接操作受保护的主干分支。其工作流程包括:建立仓库基线检查、解析并验证计划的每一步、创建进度跟踪、逐步骤实施并遵循现有代码约定、进行分层验证(从lint到类型检查到完整测试套件)、检查差异以确保更改范围可控、并在完成后生成全面报告。它还特别处理重复失败,通过停止盲目修补、重新检查错误、形成新假设来避免无意义的尝试。几乎所有高风险操作(如删除文件、强制推送、安装依赖、数据库迁移)都需要用户明确批准。

兼容平台✓Claude Code~Codex CLI~Cursor✓Gemini CLI✓OpenCode
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/frontier-plan-opencode-executor

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

前沿计划 OpenCode 执行器

核心原则

前沿计划是一个强假设,而非事实。

逐步执行计划的意图,但在编辑代码前,需针对实际仓库验证每一项指令。前沿AI的计划经常在以下方面失败:不存在的文件名、凭空想象的导入、不可用的库、与仓库模式不匹配、缺少测试、理想化的架构、以及破坏内部API。

永远不要批量进行大型更改。永远不要跳过验证。永远不要隐藏不确定性。未经明确批准,永远不要执行破坏性操作。

何时使用

  • 你收到由前沿AI编写的、包含详细步骤的实施计划
  • 该计划包含3个或更多不同步骤,并指定了文件路径和代码模式
  • 你正在使用一个非前沿编码模型,该模型受益于执行纪律
  • 该计划存在与实际代码库冲突的风险

不要用于:

  • 单文件更改或琐碎修复
  • 只有1-2个简单步骤的计划
  • 在同一会话中你自己编写的计划
  • 用户希望速度优先于安全性的快速迭代场景

核心工作流程

0. 预检:建立仓库基线

在接触任何文件之前,了解仓库状态并检测预先存在的故障。

1. git status --short          # 仓库是否干净?
2. 检查 package.json          # 可用的脚本、依赖项
3. 检查 AGENTS.md, README.md  # 项目约定、命令
4. 从 package.json 脚本中检测可用的验证命令
5. 如果可用,运行最简单的基线验证(lint 或 typecheck)

如果基线已经失败:

  • 明确记录失败:确切的命令、退出状态和简短的错误摘要
  • 不要尝试广泛的清理或修复不相关的问题
  • 仅当计划中的更改可以与现有失败隔离时才继续
  • 不要将预先存在的失败归因于你的实现

危险状态检测:

  • 如果 git status 显示与计划无关的未提交更改,请警告用户
  • 如果锁文件被修改,请警告用户
  • 如果仓库处于冲突/变基状态,请停止并询问

检查点建议:

  • 如果仓库在开始前是干净的,建议在实施前创建一个检查点提交
  • 除非用户明确要求,否则不要创建提交

自动提交和自动推送

自动提交和自动推送默认启用,除非用户明确禁用。

代理应在每个经过验证的逻辑工作单元完成后提交并将其推送到活动的远程工作分支,以便用户随后可以审查历史记录。

实施前:

  • 确定当前分支;
  • 如果在 main、master、production、release 或其他受保护/主线分支上,根据计划创建一个新的工作分支;
  • 如果已经在工作分支上,则继续使用该分支;
  • 永远不要直接推送到受保护/主线分支。

如果存在预先存在的未提交更改:

  • 不要自动将它们包含在代理的提交中;
  • 仅暂存与当前逻辑工作单元相关的文件;
  • 如果用户更改和代理更改无法安全分离,请停止并报告冲突。

仅在以下条件满足后提交:

  • 逻辑工作单元已完成;
  • 验证通过;
  • 差异已检查;
  • 提交具有一个连贯的目的。

使用约定式提交:

type(scope): concise imperative summary

示例:

feat(auth): add session validation helper
fix(api): handle empty webhook payload
refactor(billing): extract invoice mapper
test(auth): cover expired session flow

1. 解析:提取计划并对现实进行验证

阅读完整的计划。提取有序的步骤。对于每个步骤,进行现实情况检查:

检查项问题
文件引用的文件是否存在于仓库中?
库引用的库是否在 package.json 中?
模式仓库中是否已存在等效的实用程序/组件?
命令计划的验证命令是否可用?
依赖项此步骤是否依赖于前一步?
风险低/中/高 — 有多大可能破坏现有行为?

如果某个步骤引用了不存在的文件、不存在的库、过时的模式或不可用的命令:在实施前调整该步骤,同时保留计划的意图。

2. 跟踪:创建进度追踪器

如果可用,请使用 todowrite(OpenCode 的任务列表工具)。

如果 todowrite 不可用(例如,在子代理中,默认情况下禁用它):

  • 在你的响应中创建一个可见的 Markdown 复选框列表
  • 在每个步骤后手动更新它
  • 将其作为进度的事实来源
  • 如果未使用该工具,不要假装使用了

每个项目必须包括:实施操作、验证方法以及预计会触及的文件。

3. 实施:一次一步

将当前步骤标记为 in_progress。仅实施该步骤。

  • 在编辑前读取目标文件
  • 遵循现有代码库约定(导入、命名、模式、架构)
  • 使计划适应现有基础设施(例如,如果计划说“创建一个 toast 组件”,但项目使用 Sonner,则包装 Sonner 而不是从头构建)
  • 进行最小的一致更改
  • 不要实施未来步骤,但在做出设计决策时需考虑下游依赖项
  • 不要进行不相关的清理、重构或格式化
  • 除非得到明确批准,否则不要安装依赖项

4. 验证:分层验证

在每个步骤之后,运行最有针对性的验证。 不要每次都“lint 所有内容”。

更改类型最低验证更强的验证
新文件/组件lint 或 typecheck受影响的 typecheck
类型/接口更改typecheck受影响的测试
逻辑/函数更改有目标的单元测试完整测试套件
API/服务器更改有目标的集成测试构建 + 端点检查
UI 更改typecheck + build视觉/手动冒烟检查
配置/构建更改build如有需要,进行干净安装/构建
数据库/模式更改dry-run/check 命令需要用户批准

如果某个步骤没有自动化验证:执行手动审查并准确说明你检查了什么。

如果验证失败:

第一次失败 — 修复并重新验证:

  • 仅修复由当前步骤引起的错误
  • 不要修复预先存在或不相关的错误
  • 立即重新验证

重复失败 — 不要盲目地继续修补。 请参阅下面的“重复失败处理”。

关键: 永远不要通过削弱断言、删除测试、移除行为、更改公共 API、抑制错误或隐藏失败来使验证通过 — 除非计划明确要求并且用户批准。让警报停止不等于解决问题。

5. 差异:检查更改

在验证通过后,检查实际发生了哪些更改:

git diff --stat          # 哪些文件发生了变化?
git diff                 # 当差异足够小时进行审查

确认:

  • 只有预期的文件发生了变化
  • 没有发生不相关的格式化
  • 没有锁文件发生变化(除非明确有意)
  • 没有意外编辑生成的文件
  • 没有引入秘密、本地路径或调试日志
  • 没有意外删除代码

如果差异超出预期范围,请在继续之前停止并纠正。

6. 确认:标记完成

只有当实施、验证和差异检查都干净时:

  • 将该步骤标记为 completed
  • 用一句话总结更改了什么
  • 将下一步标记为 in_progress

7. 最终:完整验证 + 报告

在完成所有步骤后:

  • 运行最合理的强检查:lint + typecheck + build + tests(使用项目命令)
  • 报告:完成的步骤、更改的文件、验证结果、所做的调整、预先存在的失败(如果有)、任何需要用户审查的内容

重复失败处理

如果由于相同的基本原因验证反复失败,不要继续应用小的盲目修复。 目标是检测你是在尝试之间学到新东西,还是只是在随机折腾。

当一个步骤多次失败时:

  1. 停止修补。 停止进行小的调整并重新运行。
  2. 仔细重新阅读错误输出。 完整的堆栈跟踪,而不仅仅是第一行。
  3. 检查差异和周围代码。 git diff,阅读相关的类型、接口、函数。
  4. 重新评估原始假设。 当前的实施策略是否正确?
  5. 对失败进行分类:
    • 对代码库的假设不正确?
    • 仓库不匹配(计划与现实)?
    • 选择了错误的抽象?
    • 接口或类型不兼容?
    • 缺少依赖?
    • 过时的生成产物?
    • 与你的更改无关的预先存在的问题?
    • 验证命令本身配置错误?
  6. 形成一个真正的新假设。 仅当你有一个新假设时才重试。
  7. 考虑缩小范围。 该步骤是否可以拆分为更小的部分以隔离失败?

关键规则: 不要重复相同的修复策略,除非发现了新信息:

  • 日志
  • 堆栈跟踪
  • 差异
  • 测试
  • 仓库检查
  • 文档

如果多次尝试后仍未出现新策略,请停止并清晰地报告阻塞点:

Blocker:
- verification command: `npm run build`
- failing file: `src/app/page.tsx`
- root issue hypothesis: React Server Component importing client-only hook
- attempted strategies:
  1. moved import to client component
  2. isolated hook into separate file
  3. checked existing patterns in repo
- reason for stopping:
  no consistent pattern in repo to resolve boundary safely
- likely next action:
  user review or architectural clarification

一份清晰的阻塞点报告总是好于重复“仍在失败”的同时瞎猜。

使计划适应现有代码

前沿AI的计划经常与实际代码库冲突。当发生冲突时:

  1. 识别冲突 — “计划说 import { X } from 'uninstalled-lib' 但它不在 package.json 中”
  2. 适应,而不是忽略 — 使用现有基础设施来匹配计划的意图
  3. 解释适应 — 用一句话说明你更改了什么以及为什么
  4. 保留计划的接口 — 如果计划导出了 useToast(),你的适应版本仍应导出 useToast(),即使内部实现不同

关键规则:

  • 如果仓库中已有等效的原语,不要创建新的抽象
  • 除非计划明确要求并且用户批准,否则不要安装新的依赖项
  • 没有正当理由,不要更改架构或模式

未经明确用户批准禁止执行的操作

这些命令需要用户说“是”之后才能运行:

破坏性操作:

  • rm -rf
  • git reset --hard
  • git clean -fd
  • git push --force

安装(更改锁文件):

  • npm install
  • pnpm install
  • yarn install
  • bun install
  • npm audit fix

数据库/基础设施:

  • prisma migrate
  • prisma db push
  • supabase db push
  • docker compose down -v

配置:

  • 更改 .env 文件
  • 修改全局工具配置
  • 运行部署/取消发布命令

大规模更改:

  • 广泛格式化(prettier/eslint --fix 对整个仓库)
  • 在不经审查的情况下跨多个文件查找并替换

如果不确定某个命令是否安全,请在运行前询问。

常见错误

错误现实
“前沿AI是这么说的,所以它肯定是对的”前沿计划是假设。对照真实仓库进行验证。
“我会最后一起验证所有内容”错误会累积。以合适的粒度验证每个步骤。
“我已经读过计划了,我可以一次性全部实施”批量实施 = 批量错误 + 更难的调试。
“反正我要顺便修复预先存在的lint错误”不相关的清理掩盖了你的更改实际做了什么。不要这样做。
“这个步骤很简单,我不需要检查git diff”简单的编辑可能会意外删除代码或格式化非预期的文件。
“我会安装计划中引用的缺失库”先询问。该库可能是有意不包含的或未经批准的。
“npm run build 是唯一重要的验证”构建速度慢且范围广。对于中间步骤使用 lint/typecheck。
“如果失败了,我就调整一下再运行,直到通过为止”在没有新信息的情况下盲目修补是瞎折腾。重新阅读错误。先形成新假设。
“又是同样的错误,让我试试另一个小更改”相同的错误 + 相同的策略 = 相同的结果。改变策略,而不是修补的内容。

红旗 — 停止并重新评估

  • “我下一步再验证” — 现在验证。
  • “前沿计划比仓库更懂” — 仓库是事实来源。
  • “这个库没有安装,但计划需要它” — 询问用户。不要静默安装。
  • “差异比预期大,但可能没问题” — 在继续前检查并解释。
  • “我会把步骤2和3合在一起,因为它们相关” — 一个步骤 = 一个验证 + 差异循环。
  • “有预先存在的lint错误,让我先修复它们” — 这不是你的工作。记录下来。保持专注。
  • “让我在编辑这个文件的同时格式化它” — 单独的更改 = 单独的步骤。不要混合。
  • “还是失败,让我再试一个快速修复” — 停止修补。重新阅读错误。先形成新假设。
  • “同样的错误3次了,再调整一下可能就行” — 相同的错误 + 相同的策略 = 瞎折腾。改变策略或报告阻塞点。
  • “我就重写整个东西,看看能不能修好” — 不弄清楚失败原因就丢弃工作没有意义。先诊断。
  • “用户很急,我就跳过差异检查了” — 5秒钟的 git diff --stat 可以防止数小时的调试。

快速参考

阶段操作工具
预检git status, 检测命令, 基线检查Bash
解析 + 现实检查阅读计划, 针对仓库验证每一步Read + Glob
跟踪创建 todowrite

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

相关技能