Agent Workflow Kit Guide

Project Home · 中文文档

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:

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.

flowchart TD
  Start([Before installing tools or project rules])
  Q1{"One-off script or throwaway prototype?"}
  L0["No formal AI workflow<br/>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,<br/>architecture, data, or automation changes?"}
  Spec["Consider a spec layer"]
  TaskNotes["Use lightweight task notes"]
  Q4{"Real users, production, complex UI,<br/>security, accounts, payments, scraping,<br/>publishing, or browser automation?"}
  Review["Consider specialist review,<br/>security review, or QA gates"]
  AvoidHeavy["Avoid heavy review layers"]
  Q5{"Need consistent behavior across<br/>Claude, Codex, Cursor, OpenCode,<br/>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

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:

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:

## Agent Workflow Kit Decision

Project: <project-name>

### Summary

- Project type: <library / CLI / web app / automation / data pipeline / editor / internal tool / etc.>
- Lifecycle: <one-off / maintained / long-lived>
- Users: <author / internal / public / customers>
- Risk level: <low / medium / high>
- Score: <0-16>

### Decision

- Workflow level: <0 / 1 / 2 / 3>
- Spec layer: <none / light / required>
- Agent discipline: <none / recommended / required>
- Specialist review: <none / light / full>
- Harness/tooling pack: <none / optional / recommended>

### Reasoning

- <reason 1>
- <reason 2>
- <reason 3>

### Proposed Files

- <file to create/update, or "none">

### Verification Commands Found

- Install: `<command or unknown>`
- Test: `<command or unknown>`
- Lint/typecheck: `<command or unknown>`
- Build: `<command or unknown>`
- E2E/browser: `<command or unknown>`

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

# 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: `<fill in>`
- Run tests: `<fill in>`
- Run lint/typecheck: `<fill in>`
- Build: `<fill in>`
- Run E2E/browser checks: `<fill in>`

## 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

## 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

## 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

## 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

## 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

## 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:

# 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

Read project rules
→ make scoped change
→ run relevant test/check
→ report result

Standard Feature

Evaluate change size
→ create or update spec/change artifact if non-trivial
→ review plan
→ implement with tests
→ verify
→ summarize

High-Risk Product Change

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

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:

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:

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	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	The project touches auth, authorization, input validation, XSS, SQL injection, file upload, or sensitive data.
Architecture decisions	adr/madr / architecture-decision-record/architecture-decision-record	The project needs durable records for architecture decisions, tradeoffs, alternatives, and context.
Commit conventions	conventional-commits/conventionalcommits.org	The project wants consistent commit messages, automated changelogs, or release automation.
Versioning	semver/semver	Libraries, SDKs, CLIs, APIs, or plugins need clear compatibility and breaking-change semantics.
Changelog	olivierlacan/keep-a-changelog	Releases need a readable user-facing or developer-facing change history.
Supply-chain security	ossf/scorecard	Open-source projects need checks for security posture, CI, branch protection, and dependency risk.
SLSA	slsa-framework/slsa	Mature projects need build, release, provenance, and supply-chain security guarantees.
API design	microsoft/api-guidelines	REST APIs, platform APIs, and SDK APIs need consistent naming, errors, pagination, and compatibility rules.
Spec-driven reference	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: 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.