name	ai-workflow-optimizer
description	Live AI coding workflow research and optimization protocol. Use when 初始化/优化项目工作流, 工作流优化, AI 编程最佳实践, adapting Claude Code/Codex/OpenCode/Cursor/Copilot/Gemini workflows, or when an agent is stuck, repeatedly failing bugs, moving slowly, thrashing context, missing verification gates, or needing to learn current GitHub workflow best practices in real time.

AI Workflow Optimizer

This is a meta-workflow skill. Its job is to make the agent improve how it works before spending more effort inside a failing process.

Do not treat bundled references as a static best-practice library. Treat them as the protocol for live study: how to read current repositories, decide what matters, adapt ideas to the active platform, and verify that the workflow actually improves behavior.

Trigger Discipline

Use this skill when the task is about workflow, not ordinary implementation:

Initialize an AI coding workflow for a repo or project.
Optimize existing agent rules, skills, prompts, hooks, MCP/tools, tests, review, QA, memory, or release flow.
Recover from repeated failed bug fixes, weak feedback loops, or slow/chaotic agent work.
Port a Claude Code workflow to Codex, OpenCode, Copilot, Cursor, Gemini, or another coding agent.
Decide which modern GitHub workflow pattern fits the current project.

If the immediate issue is a normal bug or test failure, first run a systematic debugging loop. Invoke this skill only when the debugging evidence shows the process itself is the bottleneck.

Core Protocol

Classify the situation. Name the mode: initialization, optimization, stuck-loop recovery, platform migration, or post-mortem hardening. Define observable success criteria.
Audit the current harness. Identify the agent platform, existing instruction files, skills, commands, hooks, MCP/tools, tests, CI, browser/QA path, memory, task tracking, and pain signal.
Run live source study. Follow live-source-study.md. Shallow-scan the seed repositories first, then deep-read only the sources that fit the current problem and task weight.
Extract principles, not frozen content. Capture what problem each source pattern solves, what evidence supports it, what primitives it requires, and what would break if copied blindly.
Choose the smallest useful workflow change. Use workflow-selection.md to select phases, gates, artifacts, roles, and fallback paths.
Adapt to the active platform. Use platform-adaptation.md. Translate Claude-specific concepts into native primitives for the current harness.
Apply with approval discipline. For major workflow changes, propose the change and ask for user confirmation before editing. For small reversible workflow improvements, make them traceable and explain exactly what changed.
Verify and iterate. Use validation-and-iteration.md. Test discovery, trigger fit, live-source reasoning, platform mapping, and a realistic usage scenario. If behavior is weak, revise the workflow and test again.

Reading Depth Rules

Always begin with a shallow scan of the seed repository set or the relevant subset so the agent knows what is current.
Do not skip shallow scan just because the task seems small. Lightweight work still needs a brief freshness check before recommending patterns.
For lightweight workflow improvement, deep-read the 1-2 repositories or nested references that best match the problem.
For major workflow initialization, cross-platform migration, or large workflow redesign, deep-read broadly across the seed repositories and follow relevant nested references.
Stop reading when additional sources repeat the same pattern and the chosen workflow has enough evidence to implement safely.

Approval Rules

Major changes require confirmation: new workflow architecture, new persistent agent config, broad instruction rewrites, hooks that enforce behavior, CI changes, new MCP/tooling, or repository-wide skill/rule systems.
Small reversible changes may proceed: clarifying a local workflow doc, adding a task checklist, improving a skill description, adding a lightweight validation note, or updating a traceable index. Explain what changed and where.
Preserve existing user/project changes. Prefer additive edits and versioned artifacts.

Required Response Shape

When recommending or implementing workflow changes, include:

Diagnosis: the current workflow bottleneck and evidence.
Live sources read: repositories/files/links inspected during this run and why they were relevant.
Principles extracted: reusable ideas, not copied static content.
Selected workflow: phases, artifacts, gates, roles/agents, and fallback path.
Platform adaptation: how each borrowed idea maps to this agent/harness.
Changes made or proposed: exact files/settings and reversibility.
Verification: scenario or commands used, results, gaps, and next iteration if needed.

Non-Negotiables

Never claim current best practice without checking live sources when the task depends on freshness.
Never copy a public workflow stack wholesale just because it is popular.
Never write Claude-only paths, tools, or frontmatter into another platform without adaptation.
Never add ceremony unless it prevents a named failure mode.
Never hide uncertainty about repository access, platform support, or validation.
Never let workflow optimization become an excuse to avoid reproducing bugs, running tests, or shipping useful work.

AI Workflow Optimizer

This is a meta-workflow skill. Its job is to make the agent improve how it works before spending more effort inside a failing process.

Trigger Discipline

Use this skill when the task is about workflow, not ordinary implementation:

Initialize an AI coding workflow for a repo or project.

Optimize existing agent rules, skills, prompts, hooks, MCP/tools, tests, review, QA, memory, or release flow.

Recover from repeated failed bug fixes, weak feedback loops, or slow/chaotic agent work.

Port a Claude Code workflow to Codex, OpenCode, Copilot, Cursor, Gemini, or another coding agent.

Decide which modern GitHub workflow pattern fits the current project.

If the immediate issue is a normal bug or test failure, first run a systematic debugging loop. Invoke this skill only when the debugging evidence shows the process itself is the bottleneck.

Core Protocol

Classify the situation. Name the mode: initialization, optimization, stuck-loop recovery, platform migration, or post-mortem hardening. Define observable success criteria.

Audit the current harness. Identify the agent platform, existing instruction files, skills, commands, hooks, MCP/tools, tests, CI, browser/QA path, memory, task tracking, and pain signal.

Run live source study. Follow live-source-study.md. Shallow-scan the seed repositories first, then deep-read only the sources that fit the current problem and task weight.

Extract principles, not frozen content. Capture what problem each source pattern solves, what evidence supports it, what primitives it requires, and what would break if copied blindly.

Choose the smallest useful workflow change. Use workflow-selection.md to select phases, gates, artifacts, roles, and fallback paths.

Adapt to the active platform. Use platform-adaptation.md. Translate Claude-specific concepts into native primitives for the current harness.

Apply with approval discipline. For major workflow changes, propose the change and ask for user confirmation before editing. For small reversible workflow improvements, make them traceable and explain exactly what changed.

Verify and iterate. Use validation-and-iteration.md. Test discovery, trigger fit, live-source reasoning, platform mapping, and a realistic usage scenario. If behavior is weak, revise the workflow and test again.

Reading Depth Rules

Always begin with a shallow scan of the seed repository set or the relevant subset so the agent knows what is current.

Do not skip shallow scan just because the task seems small. Lightweight work still needs a brief freshness check before recommending patterns.

For lightweight workflow improvement, deep-read the 1-2 repositories or nested references that best match the problem.

For major workflow initialization, cross-platform migration, or large workflow redesign, deep-read broadly across the seed repositories and follow relevant nested references.

Stop reading when additional sources repeat the same pattern and the chosen workflow has enough evidence to implement safely.

Approval Rules

Major changes require confirmation: new workflow architecture, new persistent agent config, broad instruction rewrites, hooks that enforce behavior, CI changes, new MCP/tooling, or repository-wide skill/rule systems.

Small reversible changes may proceed: clarifying a local workflow doc, adding a task checklist, improving a skill description, adding a lightweight validation note, or updating a traceable index. Explain what changed and where.

Preserve existing user/project changes. Prefer additive edits and versioned artifacts.

Required Response Shape

When recommending or implementing workflow changes, include:

Diagnosis: the current workflow bottleneck and evidence.

Live sources read: repositories/files/links inspected during this run and why they were relevant.

Principles extracted: reusable ideas, not copied static content.

Selected workflow: phases, artifacts, gates, roles/agents, and fallback path.

Platform adaptation: how each borrowed idea maps to this agent/harness.

Changes made or proposed: exact files/settings and reversibility.

Verification: scenario or commands used, results, gaps, and next iteration if needed.

Non-Negotiables

Never claim current best practice without checking live sources when the task depends on freshness.

Never copy a public workflow stack wholesale just because it is popular.

Never write Claude-only paths, tools, or frontmatter into another platform without adaptation.

Never add ceremony unless it prevents a named failure mode.

Never hide uncertainty about repository access, platform support, or validation.

Never let workflow optimization become an excuse to avoid reproducing bugs, running tests, or shipping useful work.

ai-workflow-optimizer