# Agent Workflow Kit Guide [Project Home](../README.md) · [中文文档](guide.zh-CN.md) An evaluation-first guide for adding AI-assisted development workflows to software projects. ## Repository Contents - `README.md`: English project homepage. - `README.zh-CN.md`: Chinese project homepage. - `docs/guide.md`: English public guide. - `docs/guide.zh-CN.md`: Chinese public guide. - `skills/agent-workflow-kit`: English agent-facing Skill package, provided in a Codex-compatible structure. - `skills/agent-workflow-kit-zh-cn`: Chinese agent-facing Skill package, provided in a Codex-compatible structure. This document is for maintainers of open-source, personal, team, and product projects. Its goal is not to push every project onto the same toolset, but to help maintainers decide: - whether the project needs an AI workflow at all - how light or heavy that workflow should be - which tools to adopt - which tools to avoid - which project-level rules AI agents must follow The core idea: > Evaluate the project first. Then choose the smallest workflow that reduces real risk. --- ## Quick Start (30-Second Version) If you just want to get going without reading the whole document: 1. Walk the decision tree (Section 4) to see which layers the project needs. 2. Score the project with the risk table (Section 5) for a 0-16 result. 3. Pick a workflow level by score: 0-4 minimal / 5-9 standard / 10+ full (Section 6). 4. Copy the `AGENTS.md` blocks for that level from Section 10 and fill in the project's verification commands. 5. Validate the workflow on one small change before rolling it out. The remaining sections are reference material to consult as needed. In one line: **the best AI workflow is the smallest one that reliably prevents the failures your project actually has.** --- ## 1. What This Guide Solves AI coding agents can significantly speed up development, but they also tend to create the following problems: - requirements that live only in chat history and cannot be tracked later - agents that skip clarification and jump straight to code - work claimed as done without tests or verification - large refactors introduced for small changes - multiple tools each generating their own competing plan - missing boundaries around risky actions like accounts, releases, scraping, and external platforms This guide offers a layered approach: - a **spec layer** that records why a change is needed, its scope, design, tasks, and archive - an **agent discipline layer** that constrains how AI clarifies, tests, debugs, reviews, and verifies - a **specialist review layer** that adds review at key product, design, engineering, QA, security, and release checkpoints - a **harness/tooling layer** that unifies skills, rules, hooks, MCP, memory, and security configuration when a team needs it All layers are optional. A project does not need the full set just to look professional. --- ## 2. Example Tool Roles These tools are examples of common layers. You can replace them with equivalent tools. These projects are examples that illustrate what each layer roughly looks like. They are not requirements, and listing them here is not an endorsement or a guarantee of quality. Their maturity and maintenance vary widely; some are maintained by individuals or small teams and may be renamed, abandoned, or broken at any time. Evaluate each repository's activity, maintenance, and security yourself before adopting it, and review upstream documentation first. When an equivalent tool exists, prefer the one that is better maintained and matched to your project's risk. | Layer | Example Tool | URL | Role | Best For | |---|---|---|---|---| | Spec layer | OpenSpec | https://github.com/Fission-AI/OpenSpec | Project change memory: proposals, specs, design, tasks, archive | Long-lived features, behavior changes, risky automation | | Spec layer | Spec Kit | https://github.com/github/spec-kit | More formal spec-driven development lifecycle | Team standards, organization-level SDD, larger projects | | Agent discipline | Superpowers | https://github.com/obra/superpowers | Engineering discipline: clarify, plan, TDD, debug, review, verify | Most AI-assisted coding work | | Specialist review | gstack | https://github.com/garrytan/gstack | Product/engineering/design/QA/security/release review | User-facing apps, complex UI, production releases | | Harness/tooling pack | ECC | https://github.com/affaan-m/ECC | Skills, rules, hooks, MCP, memory, security, multi-language guidance | Teams standardizing across multiple AI harnesses | Default recommendation: ```text Start with project evaluation. Use a spec layer only when changes need durable memory. Use an agent discipline layer when AI writes or edits code. Use specialist or harness layers only when the project risk justifies the extra process. ``` --- ## 3. Who Should Use This This guide is useful for: - maintainers of long-lived software projects - teams using AI agents for code changes - projects where requirements often live only in chat history - codebases where AI edits need clearer boundaries - products with user-facing workflows, production releases, or security-sensitive behavior - teams that want repeatable AI review, QA, and verification gates This guide is probably too heavy for: - one-off scripts - short demos - learning exercises - throwaway prototypes - tiny libraries with clear tests and stable scope - projects where AI is used only for occasional explanation, not code changes --- ## 4. Decision Tree Use this before installing or adding project rules. The decision tree is qualitative: it tells you which layers the project needs at all. The risk score in the next section is quantitative: it sets the workflow level and how heavy each layer should be. Use them together; if they disagree, the risk score wins. ```mermaid flowchart TD Start([Before installing tools or project rules]) Q1{"One-off script or throwaway prototype?"} L0["No formal AI workflow
Keep normal tests and manual review"] Q2{"Will AI agents edit code?"} NotNeeded["This guide may not be needed"] Discipline["Add at least basic agent discipline"] Q3{"Non-trivial feature, behavior,
architecture, data, or automation changes?"} Spec["Consider a spec layer"] TaskNotes["Use lightweight task notes"] Q4{"Real users, production, complex UI,
security, accounts, payments, scraping,
publishing, or browser automation?"} Review["Consider specialist review,
security review, or QA gates"] AvoidHeavy["Avoid heavy review layers"] Q5{"Need consistent behavior across
Claude, Codex, Cursor, OpenCode,
Gemini, or other harnesses?"} Harness["Consider a harness/tooling pack"] Simple["Keep project rules simple"] Score([Then score project risk in Section 5]) Start --> Q1 Q1 -- yes --> L0 Q1 -- no --> Q2 Q2 -- no --> NotNeeded Q2 -- yes --> Discipline --> Q3 Q3 -- yes --> Spec --> Q4 Q3 -- no --> TaskNotes --> Q4 Q4 -- yes --> Review --> Q5 Q4 -- no --> AvoidHeavy --> Q5 Q5 -- yes --> Harness --> Score Q5 -- no --> Simple --> Score ``` ```text Is this a one-off script or throwaway prototype? yes → Do not add a formal workflow. Use normal tests and review. no → continue Will AI agents edit code in this project? no → You may not need this guide. yes → add at least basic agent discipline rules. Will the project have non-trivial feature, behavior, architecture, data, or automation changes? yes → consider a spec layer. no → use lightweight task notes only. Does the project have real users, production deployment, complex UI, security, accounts, payments, scraping, publishing, or browser automation? yes → consider specialist review or security/QA gates. no → avoid heavy review layers. Does the team need consistent behavior across Claude, Codex, Cursor, OpenCode, Gemini, or other harnesses? yes → consider a harness/tooling pack. no → keep project rules simple. ``` --- ## 5. Project Risk Score Score the project before choosing a workflow. This scoring is a heuristic, not a precise formula; adjust the dimensions and weights to your team's context. | Dimension | 0 | 1 | 2 | |---|---|---|---| | Lifecycle | one-off | maintained occasionally | long-lived product | | Users | author only | internal users | public users/customers | | UI/UX | no UI | simple UI | complex UI/editor/dashboard | | Release risk | no release | manual release | staging/production/CI release | | Security/accounts | none | API keys or limited permissions | auth, cookies, tokens, user data, payments | | External platforms | none | third-party API calls | scraping, publishing, browser automation | | Testing difficulty | unit tests enough | integration tests needed | E2E, screenshots, accessibility, performance | | Collaboration | solo short-term | solo long-term | team or multi-agent work | Suggested result: | Score | Workflow | |---:|---| | 0-4 | Minimal workflow | | 5-9 | Standard workflow | | 10+ | Full workflow | Override: - If security/accounts/external automation scores 2, add at least security review. - If UI/testing difficulty scores 2, add browser or E2E verification. - If collaboration scores 2, add clear project-level AI rules. --- ## 6. Workflow Levels ### Level 0: No Formal AI Workflow Use for tiny scripts, throwaway prototypes, or projects where AI is not editing code. Recommended practice: - keep normal tests - review diffs manually - do not add extra project files just for process ### Level 1: Minimal Workflow Use for small but maintained projects. Add a short `AGENTS.md` or equivalent: - AI must inspect existing project structure first - AI must avoid unrelated refactors - AI must run relevant tests before completion - AI must report what changed and what was verified Spec layer is optional. Specialist tools are usually unnecessary. ### Level 2: Standard Workflow Use for most AI-assisted software projects. Recommended: - basic project-level `AGENTS.md` - spec layer for non-trivial changes - TDD or test-first discipline for features and bug fixes - root-cause debugging before fixes - completion criteria based on evidence Specialist review is optional and used at key points. ### Level 3: Full Workflow Use for production products, complex apps, security-sensitive systems, or teams with multiple AI agents. Recommended: - spec layer is required for non-trivial changes - agent discipline is required - specialist review gates for high-risk changes - security review for sensitive code - browser/E2E verification for user-facing flows - project-level rules committed to the repo - optional harness/tooling pack if the team needs cross-agent consistency --- ## 7. Tool Selection Guide ### Spec Layer Use a spec layer when: - requirements need to survive chat context - multiple changes may be in progress - a feature needs proposal, design, tasks, and archival history - you want AI to implement against written artifacts rather than a vague prompt A spec layer does not have to mean OpenSpec. Choose by project style: | Choice | Good For | Not Good For | |---|---|---| | OpenSpec | Existing projects, solo or small teams, lightweight iteration, brownfield codebases | Very formal organization-level SDD | | Spec Kit | Team engineering standards, organization-level spec-driven development, explicit constitution/spec/plan/tasks phases | Small projects, fast exploration, process-sensitive work | | ADR/RFC/design docs | Architecture decisions, platform projects, human-reviewed design discussions | Agent-executed workflows that need task breakdowns | | GitHub issues / project docs | Small open-source projects, lightweight collaboration | Complex multi-stage features or high-risk automation | | Homegrown `docs/changes/` | Tool-neutral teams | Teams without maintainers enforcing the process | Default recommendation: - For general projects, start with OpenSpec or lightweight `docs/changes/`. - For more formal teams, enterprises, or large projects, consider Spec Kit. - Small projects do not need a dedicated spec tool just to be "spec-driven." Avoid a spec layer when: - the change is a typo, comment, or tiny config tweak - the project is a one-off script - the process would be larger than the change ### Agent Discipline Layer Use an agent discipline layer when AI writes or edits code. Superpowers is one example. The important behaviors are: - clarify before implementing - write tests before or alongside code - debug from root cause - review diffs before declaring success - verify with concrete commands or evidence Avoid making it too rigid for: - throwaway prototypes - generated code - exploratory spikes where speed matters more than long-term maintainability ### Specialist Review Layer Use specialist review when the project has product, design, QA, security, or release risk. gstack is one example. Useful review gates include: - product/scope review before building - engineering/design review before implementation - code review after implementation - browser QA for user-facing flows - security review for sensitive workflows - release review before merging or deploying Avoid specialist review when: - the project is small and test boundaries are clear - no user-facing or production risk exists - the additional process slows down exploration more than it reduces risk ### Harness/Tooling Pack Use a harness/tooling pack when the team wants a broader AI operating layer. ECC is one example. This type of layer can include: - skills - rules - hooks - MCP configuration - memory/session patterns - security scanning - language-specific guidance - cross-harness consistency Avoid installing a heavy pack by default when: - the project already has enough process - the team does not need hooks or cross-harness parity - the codebase is small - maintainers are not ready to manage the extra behavior it adds --- ## 8. Conflict Rules When multiple AI workflow tools overlap, use one source of truth. ### Planning If a spec layer already has a proposal, design, and tasks: - do not generate a second competing plan - review and improve the existing artifacts instead - update the spec artifacts before changing implementation scope Example: ```text Good: OpenSpec proposal → specialist plan review → update OpenSpec tasks → implement Bad: OpenSpec proposal → separate autoplan → separate implementation plan → unclear source of truth ``` ### TDD and Verification If multiple tools define TDD or verification rules: - follow the project’s `AGENTS.md` - prefer the strictest rule only when the project risk justifies it - avoid requiring 80%+ coverage for small scripts unless the project explicitly wants that ### Security and External Actions External actions require explicit approval unless project rules say otherwise. Examples: - pushing commits - merging PRs - deploying - posting to social platforms - sending emails - changing production data - modifying credentials - running paid jobs - automating third-party websites with real accounts For high-risk flows, prefer report-only review first. ### Existing Project Rules Win If a repo already has `AGENTS.md`, `CLAUDE.md`, Cursor rules, Copilot instructions, or team-specific guidelines: - read them first - preserve their intent - add only the missing AI workflow pieces - do not overwrite existing rules without maintainer approval --- ## 9. Project Evaluation Checklist Before adding any workflow files, the AI agent should inspect: - `README.md` - existing AI instructions: `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.github/copilot-instructions.md` - package and toolchain files: `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, etc. - source directories: `src/`, `app/`, `pages/`, `components/`, `lib/` - tests: `tests/`, `spec/`, `e2e/`, Playwright/Cypress configs - CI: `.github/workflows/`, `.gitlab-ci.yml`, etc. - deployment: `vercel.json`, `Dockerfile`, `docker-compose.yml`, infrastructure config - security-sensitive files and patterns: auth, tokens, cookies, payments, user data - platform automation: scraping, posting, browser automation, third-party account workflows The agent should then output: ```markdown ## Agent Workflow Kit Decision Project: ### Summary - Project type: - Lifecycle: - Users: - Risk level: - Score: <0-16> ### Decision - Workflow level: <0 / 1 / 2 / 3> - Spec layer: - Agent discipline: - Specialist review: - Harness/tooling pack: ### Reasoning - - - ### Proposed Files - ### Verification Commands Found - Install: `` - Test: `` - Lint/typecheck: `` - Build: `` - E2E/browser: `` ``` Do not install or commit workflow files until the maintainer approves the decision, unless the maintainer has already delegated that authority. --- ## 10. AGENTS.md Templates Use only the blocks that match the project’s chosen workflow level. ### Base Block ```markdown # AI Project Workflow ## Project Rules Before changing code, inspect the existing project structure and follow local patterns. Do not perform unrelated refactors, formatting churn, dependency upgrades, or broad cleanup unless explicitly requested. If scope needs to expand, stop and explain why before continuing. ## Verification Before completion, run the relevant checks and report the commands and results. Project commands: - Install dependencies: `` - Run tests: `` - Run lint/typecheck: `` - Build: `` - Run E2E/browser checks: `` ## Completion Criteria A task is complete only when: - the requested behavior is implemented - relevant checks pass or failures are clearly explained - user-facing behavior is verified when applicable - no unrelated changes were introduced - the final response reports what changed and what was verified ``` ### Spec Layer Block ```markdown ## Spec Layer For non-trivial feature, behavior, architecture, data, automation, or user-facing changes, create or update a written change artifact before implementation. The change artifact should describe: - why the change is needed - what behavior changes - important design decisions - implementation tasks - verification criteria If a spec/change artifact already exists, use it as the source of truth. Do not create a separate competing plan unless explicitly requested. ``` ### Agent Discipline Block ```markdown ## Agent Discipline Use disciplined engineering workflow: - clarify ambiguous requirements before implementation - prefer test-first or TDD for features and bug fixes - debug from root cause, not symptoms - review diffs before calling work complete - verify behavior with tests, browser checks, logs, screenshots, or reproducible commands Do not claim completion without evidence. ``` ### Specialist Review Block ```markdown ## Specialist Review Use specialist review only when the project risk justifies it. Recommended gates: - product/scope review before large user-facing work - engineering/design review before complex implementation - code review after implementation - QA/browser verification for critical user flows - security review for auth, permissions, user data, payments, scraping, publishing, or third-party automation - release review before production deployment If a spec/change artifact exists, specialist review should improve that artifact, not replace it with a second plan. ``` ### External Action Safety Block ```markdown ## External Action Safety Treat networked and external actions as approval-required unless the user explicitly authorizes them. Ask before: - pushing commits - opening or merging PRs - deploying - modifying production data - posting or sending messages - changing credentials - running paid jobs - operating real third-party accounts Do not send private code, customer data, secrets, production logs, database exports, or credentials to untrusted agents, MCP servers, browser automation, or external services. For high-risk flows, produce a local plan or report first. ``` ### Harness/Tooling Pack Block ```markdown ## Harness and Tooling Packs If this project uses a broader AI tooling pack with skills, hooks, rules, MCP servers, or memory features: - preserve existing project rules - install only the components this project needs - avoid duplicate rules from multiple packs - document what was installed and why - require maintainer approval before enabling hooks or external-action automation ``` ### Full Example: Mid-Size Web App (Standard Workflow) Below is a complete, filled-in `AGENTS.md` for a mid-size web app (standard workflow / Level 2). It combines the base, spec layer, agent discipline, and external action safety blocks, with real commands filled in: ```markdown # AI Project Workflow ## Project Rules Before changing code, inspect the existing project structure and follow local patterns. Do not perform unrelated refactors, formatting churn, dependency upgrades, or broad cleanup unless explicitly requested. If scope needs to expand, stop and explain why before continuing. ## Spec Layer For non-trivial feature, behavior, architecture, data, automation, or user-facing changes, create or update a change artifact under `docs/changes/` before implementation. If a change artifact already exists, use it as the source of truth. Do not create a separate competing plan unless explicitly requested. ## Agent Discipline - clarify ambiguous requirements before implementation - write tests before or alongside code for features and bug fixes - debug from root cause, not symptoms - review the diff before calling work complete - do not claim completion without evidence ## Verification Before completion, run the relevant checks and report the commands and results. Project commands: - Install dependencies: `pnpm install` - Run tests: `pnpm test` - Run lint/typecheck: `pnpm lint && pnpm typecheck` - Build: `pnpm build` - Run E2E/browser checks: `pnpm test:e2e` ## External Action Safety Ask before pushing commits, opening or merging PRs, deploying, or modifying production data. Do not send private code, customer data, secrets, production logs, database exports, or credentials to untrusted agents, MCP servers, browser automation, or external services. ## Completion Criteria A task is complete only when: - the requested behavior is implemented - relevant checks pass or failures are clearly explained - user-facing behavior is verified when applicable - no unrelated changes were introduced - the final response reports what changed and what was verified ``` --- ## 11. Example Workflows ### Minimal Change ```text Read project rules → make scoped change → run relevant test/check → report result ``` ### Standard Feature ```text Evaluate change size → create or update spec/change artifact if non-trivial → review plan → implement with tests → verify → summarize ``` ### High-Risk Product Change ```text Create/update spec → product/engineering/security review as needed → update spec tasks → implement with tests → run code review and QA → verify against spec → release only after approval ``` ### Bug Fix ```text Reproduce issue → investigate root cause → write failing test or minimal reproducer → fix root cause → verify the test passes → check for regressions ``` --- ## 12. Installation Notes Installation commands change over time. Prefer upstream documentation for exact commands. General guidance: - install workflow tools at the agent/user level when possible - avoid vendoring tool internals into every repository - commit only project-specific rules, specs, and configuration - use optional/team mode before requiring a workflow for all contributors - do not enable hooks, MCP servers, or external-action automation without understanding their scope Recommended integration order: ```text 1. Evaluate the project. 2. Choose workflow level. 3. Add or update AGENTS.md. 4. Initialize a spec layer only if needed. 5. Add optional specialist/harness tooling only after maintainer approval. 6. Run a small test change to validate the workflow. ``` --- ## 13. Maintainer Checklist Before merging workflow integration into a repo: - [ ] The project risk score has been recorded. - [ ] The chosen workflow level is justified. - [ ] Existing project instructions were preserved. - [ ] The new rules are short enough for agents to follow. - [ ] Optional tool-specific blocks are included only if needed. - [ ] External actions require approval. - [ ] Verification commands are filled in. - [ ] The workflow has been tested on one small change. --- ## 14. Suggested Repository Files For a public project, keep workflow files minimal: ```text AGENTS.md # AI agent rules for this repo CONTRIBUTING.md # Optional contribution guide for synchronization and validation rules CHANGELOG.md # Optional project change history docs/agent-workflow.md # Optional explanation for humans docs/changes/ # Optional lightweight change docs openspec/ # Optional if using OpenSpec ``` Avoid creating many tool-specific files unless the team actually uses those tools. --- ## 15. Optional Engineering Reference Catalog The following open-source references can be useful, but they should not be part of the default workflow. They are not install requirements. Use them only when the project style, risk, and maturity match, and reference them from `AGENTS.md`, review checklists, design docs, or release process docs as needed. These references are not ranked by star count, and inclusion is not a blanket endorsement. Before adopting one, verify that the source is authoritative for your scenario, maintained or intentionally stable, license-compatible, and aligned with the risk you are trying to reduce. | Scenario | Reference | When To Use | |---|---|---| | Code review | [google/eng-practices](https://github.com/google/eng-practices) | The team needs shared review standards, change author guidance, and review quality expectations. Treat as a stable historical reference if archived. | | Secure development | [OWASP/CheatSheetSeries](https://github.com/OWASP/CheatSheetSeries) | The project touches auth, authorization, input validation, XSS, SQL injection, file upload, or sensitive data. | | Architecture decisions | [adr/madr](https://github.com/adr/madr) / [architecture-decision-record/architecture-decision-record](https://github.com/architecture-decision-record/architecture-decision-record) | The project needs durable records for architecture decisions, tradeoffs, alternatives, and context. | | Commit conventions | [conventional-commits/conventionalcommits.org](https://github.com/conventional-commits/conventionalcommits.org) | The project wants consistent commit messages, automated changelogs, or release automation. | | Versioning | [semver/semver](https://github.com/semver/semver) | Libraries, SDKs, CLIs, APIs, or plugins need clear compatibility and breaking-change semantics. | | Changelog | [olivierlacan/keep-a-changelog](https://github.com/olivierlacan/keep-a-changelog) | Releases need a readable user-facing or developer-facing change history. | | Supply-chain security | [ossf/scorecard](https://github.com/ossf/scorecard) | Open-source projects need checks for security posture, CI, branch protection, and dependency risk. | | SLSA | [slsa-framework/slsa](https://github.com/slsa-framework/slsa) | Mature projects need build, release, provenance, and supply-chain security guarantees. | | API design | [microsoft/api-guidelines](https://github.com/microsoft/api-guidelines) | REST APIs, platform APIs, and SDK APIs need consistent naming, errors, pagination, and compatibility rules. | | Spec-driven reference | [github/spec-kit](https://github.com/github/spec-kit) | The team wants a more formal spec-driven development lifecycle; do not use it as a second source of truth beside another spec layer. | Selection rules: - **Libraries/SDKs/CLIs**: prioritize SemVer, Keep a Changelog, and Conventional Commits. - **Web apps/SaaS**: prioritize OWASP, code review guidance, and E2E/QA rules. - **APIs/platform services**: prioritize API Guidelines, ADRs, and SemVer. - **High-security projects**: prioritize OWASP, Scorecard, and SLSA. - **Team projects**: prioritize code review guidance, ADRs, and commit conventions. - **AI-heavy projects**: prioritize a spec layer and agent discipline (see Sections 7 and 10). - **Small projects**: do not add a catalog; keep only minimal `AGENTS.md` rules and test commands. --- ## 16. Final Principle The best AI workflow is the smallest one that reliably prevents the failures your project actually has. Use specs when memory matters. Use discipline when agents edit code. Use specialists when risk justifies review. Use heavy tooling only when the team benefits from the extra machinery. --- ## 17. License This guide is a tool-neutral open document. You are free to use, modify, and distribute it. - The prose is licensed under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/): copy, adapt, and redistribute it freely, with attribution. - The `AGENTS.md` templates and example code blocks in Section 10 are released to the public domain (CC0): copy them directly into any project, no attribution required. - Third-party tools and references mentioned in this guide are covered by their own licenses, not by this one; check each project's LICENSE before use. If you place this guide in a code repository, consider adding a standalone `LICENSE` file at the repository root.