zsh-agent-workflow

name	zsh-agent-workflow
description	Chinese AI coding agent workflow for Codex and Claude Code. Use when planning, debugging, reviewing, refactoring, creating or improving AGENTS.md/CLAUDE.md, building skills, publishing agent-rule repositories, or running complex multi-step coding tasks that need staged diagnosis, context control, verification loops, subagent strategy, HTML artifacts, and anti-overengineering guardrails.

ZSH Agent Workflow

Use this skill to structure non-trivial AI coding agent work for Chinese users. Keep the main context lean: use this file for the workflow, and load references only when the task needs them.

Decision Gate

• Simple task: answer or edit directly, then verify with the smallest useful check.
• Ambiguous task: diagnose first; state missing information, assumptions, and likely paths.
• Bug task: reproduce or find observable evidence before proposing a fix.
• Multi-step task: use the staged workflow below.
• Rule, prompt, or skill design: keep permanent instructions short and move detailed knowledge to references.

Staged Workflow

1. Diagnose

   • Read the current AGENTS.md/CLAUDE.md, README, task docs, and directly relevant code.
   • Identify the time scale: short-term stopgap, transitional workflow, or long-term system.
   • Surface conflicts instead of blending incompatible requirements or conventions.

2. Plan

   • State goal, scope, likely files, verification, and risks.
   • Prefer the smallest viable path.
   • For multiple viable approaches, list tradeoffs and recommend one.

3. Implement

   • Make surgical changes only.
   • Reuse existing patterns, scripts, tools, skills, and APIs.
   • Avoid new dependencies unless existing capabilities are insufficient.

4. Verify

   • Verify behavior, not just test status.
   • Use the smallest relevant tests, static checks, render checks, or manual acceptance steps.
   • If verification fails, analyze why before changing direction.

5. Review

   • For risky work, run an independent review or subagent pass.
   • Check edge cases, permissions, concurrency, caching, migration, rollback, and test gaps.
   • Record only durable decisions and validation results.

Reference Loading

Load only what the task needs:

• references/operating-principles.md: when designing workflows, AGENTS.md/CLAUDE.md, stage gates, or long-running collaboration rules.
• references/claude-code-practices.md: when using Claude Code patterns, HTML artifacts, subagents, CLAUDE.md, code review, tools, or large-codebase workflows.
• references/karpathy-guardrails.md: when writing, reviewing, refactoring, or debugging code and overengineering/scope creep is a risk.
• references/mnilax-extensions.md: when tasks involve conflicting conventions, flaky tests, long loops, partial failures, or deterministic runtime decisions.
• references/prompt-recipes.md: when the user asks for reusable prompts or when a task would benefit from a precise prompt template.

Output Shape

• Use Markdown for short answers, checklists, and simple command guidance.
• Use HTML artifacts for dense comparisons, specs, PR/diff explainers, technical reports, design prototypes, diagrams, or temporary editors with export/copy output.
• For long tasks, include checkpoints and stop to realign after budget exhaustion, repeated failure, or changed assumptions.

Subagent Strategy

Use subagents when work benefits from isolation, parallelism, or a fresh perspective:

• read-only codebase research across many files
• independent review before finalizing
• parallel work on independent files or modules
• staged pipelines such as research -> plan -> implement -> test

Do not use subagents for small tasks, strong sequential dependencies, same-file parallel edits, or work that requires agents to coordinate directly.

Completion Criteria

Before claiming completion:

• The task goal is met.
• Verification evidence is available.
• Partial failures, skipped steps, and residual risks are explicit.
• Any durable rule or workflow learning is recorded in the right layer: AGENTS.md/CLAUDE.md for always-on rules, this skill for workflow, references for detailed knowledge.