HelloAGENTS

An intelligent workflow system that keeps going: evaluate → implement → verify.

---

📑 Table of Contents

Click to expand

• 🎯 Why HelloAGENTS?
• 📊 Data That Speaks
• 🔁 Before & After
• ✨ Features
• 🚀 Quick Start
• 🔧 How It Works
• 📖 Documentation
• ❓ FAQ
• 🛠️ Troubleshooting
• 📈 Version History
• 🔒 Security
• 🙏 Acknowledgments
• 📜 License

---

🎯 Why HelloAGENTS?

You know the pattern: the assistant gives a good analysis… then stops. Or it edits code but forgets the docs. Or it “finishes” without running anything.

HelloAGENTS is a structured workflow system (routing + stages + acceptance gates) that pushes the work through to a verifiable end.

Challenge	Without HelloAGENTS	With HelloAGENTS
Inconsistent outputs	Depends on prompt quality	Unified output shell + deterministic stages
Stops too early	“Here’s what you should do…”	Keeps going: implement → test → validate
No quality gates	Manual review required	Stage / Gate / Flow acceptance
Context drift	Decisions get lost	State variables + solution packages
Risky commands	Easy to do damage	EHRB detection + workflow escalation

💡 Best For

• ✅ Coders who want “done” to mean “verified”
• ✅ Teams that need consistent format and traceable changes
• ✅ Projects where docs are part of the deliverable

⚠️ Not For

• ❌ One-off snippets (a normal prompt is faster)
• ❌ Projects where you can’t keep outputs in Git
• ❌ Tasks that require hard guarantees (still review before production)

📊 Data That Speaks

No made-up “50% faster” claims here—just things you can verify in this repo:

Item	Value	Where to verify
Routing layers	3	AGENTS.md / CLAUDE.md (Context → Tools → Intent)
Workflow stages	4	Evaluate → Analyze → Design → Develop
Execution modes	3	Tweak / Lite / Standard
Commands	12	{BUNDLE_DIR}/skills/helloagents/SKILL.md
Reference modules	23	{BUNDLE_DIR}/skills/helloagents/references/
Automation scripts	7	{BUNDLE_DIR}/skills/helloagents/scripts/
Bundles in this repo	5	Codex CLI/, Claude Code/, Gemini CLI/, Grok CLI/, Qwen CLI/

🔁 Before & After

Sometimes the difference is easier to feel than to explain. Here’s a concrete “before vs after” snapshot:

	Without HelloAGENTS	With HelloAGENTS
Start	You jump into implementation quickly	You start by scoring requirements and filling gaps
Delivery	You assemble the steps manually	The workflow keeps pushing to “verified done”
Docs	Often forgotten	Treated as a first-class deliverable
Safety	Risky ops can slip through	EHRB detection escalates risky actions
Repeatability	Depends on the prompt	Same stages + gates, every time

Now let’s make it tangible. Below is a real “before/after” demo snapshot (Snake game generated with/without a structured workflow):

Without HelloAGENTS It works, but you’re still manually driving the process.

With HelloAGENTS More complete delivery, clearer controls, and verification steps baked in.

And here’s what the Evaluate stage looks like in practice: it asks the “boring but necessary” questions (platform, delivery form, controls, acceptance criteria) before writing code.

Evaluate stage: requirement scoring + targeted clarifying questions.

In plain words, you’ll typically be asked to clarify:

• runtime target (browser / desktop / CLI)
• delivery form (single file / repo / packaged build)
• control scheme
• rules and difficulty preferences
• acceptance criteria (screen size, scoring, audio, obstacles, etc.)

✨ Features

Let’s be practical—here’s what you get.

🧭 3-layer intelligent routing Continues the same task across turns Detects tool calls (SKILL/MCP/plugins) vs internal workflow Chooses tweak / lite / standard execution based on complexity Benefit: less “prompt babysitting”	📚 4-stage workflow engine Evaluate → Analyze → Design → Develop Clear entry/exit gates Keeps artifacts as solution packages Benefit: repeatable delivery, not lucky outputs
⚡ 3-layer acceptance Stage-level checks Inter-stage gates (e.g., validate solution package) Flow-level acceptance summary Benefit: you can trust the result more	🛡️ EHRB safety detection Keyword scan + semantic analysis Escalates to confirmation when risky Flags destructive ops (e.g., rm -rf, force push) Benefit: fewer “oops” moments

🚀 Quick Start

This repo ships multiple ready-to-copy bundles (one per AI CLI):

Codex CLI, Claude Code, Gemini CLI, Grok CLI, Qwen CLI.

1) Clone the repo

git clone https://github.com/hellowind777/helloagents.git
cd helloagents

2) Install (placeholder-based)

Because every CLI stores its config in a different place, the README uses placeholders.

First, pick your bundle parameters:

Your CLI	BUNDLE_DIR	CONFIG_FILE
Codex CLI	Codex CLI	AGENTS.md
Claude Code	Claude Code	CLAUDE.md
Gemini CLI	Gemini CLI	GEMINI.md
Grok CLI	Grok CLI	GROK.md
Qwen CLI	Qwen CLI	QWEN.md

Then copy both the config file and the skills/helloagents/ folder into your CLI config root.

macOS / Linux (bash)

CLI_CONFIG_ROOT="..."
BUNDLE_DIR="Codex CLI"
CONFIG_FILE="AGENTS.md"

mkdir -p "$CLI_CONFIG_ROOT/skills"
cp -f "$BUNDLE_DIR/$CONFIG_FILE" "$CLI_CONFIG_ROOT/$CONFIG_FILE"
cp -R "$BUNDLE_DIR/skills/helloagents" "$CLI_CONFIG_ROOT/skills/helloagents"

Windows (PowerShell)

$CLI_CONFIG_ROOT = "..."
$BUNDLE_DIR = "Codex CLI"
$CONFIG_FILE = "AGENTS.md"

New-Item -ItemType Directory -Force "$CLI_CONFIG_ROOT\\skills" | Out-Null
Copy-Item -Force "$BUNDLE_DIR\\$CONFIG_FILE" "$CLI_CONFIG_ROOT\\$CONFIG_FILE"
Copy-Item -Recurse -Force "$BUNDLE_DIR\\skills\\helloagents" "$CLI_CONFIG_ROOT\\skills\\helloagents"

3) Verify it works

In your CLI, run:

• /helloagents or $helloagents

Expected: a welcome message that starts with something like:

💡【HelloAGENTS】- 技能已激活

4) Start using it

• Try ~help to see all commands
• Or just describe what you want; the router will pick the workflow

🔧 How It Works

📊 Click to view the architecture diagram

flowchart TD
  Start([User input / 用户输入]) --> L1{Layer 1: Context / 上下文}
  L1 -->|Continue / 继续| Continue[Continue task / 继续任务]
  L1 -->|New request / 新请求| L2{Layer 2: Tools / 工具}

  L2 -->|External tool / 外部工具| Tool[Run tool + shell wrap / 执行工具+Shell包装]
  L2 -->|No tool / 无工具| L3{Layer 3: Intent / 意图}

  L3 -->|Q&A / 问答| Answer[Direct answer / 直接回答]
  L3 -->|Change / 改动| Eval[Evaluate / 需求评估]

  Eval -->|Score >= 7 / >=7| Complexity{Complexity / 复杂度}
  Eval -->|Score < 7 / <7| Clarify[Clarify / 追问补充]

  Complexity -->|Tweak / 微调| Tweak[Tweak mode / 微调模式]
  Complexity -->|Lite / 轻量| Analyze[Analyze / 项目分析]
  Complexity -->|Standard / 标准| Analyze

  Analyze --> Design[Design / 方案设计（方案包）]
  Design --> Develop[Develop / 开发实施（实现+测试）]
  Develop --> Done[✅ Done / 完成 + acceptance / 验收摘要]

  style Eval fill:#e3f2fd
  style Analyze fill:#fff3e0
  style Design fill:#ede9fe
  style Develop fill:#dcfce7
  style Done fill:#16a34a,color:#fff

Loading

Key artifacts you’ll see in real projects:

• plan/YYYYMMDDHHMM_<feature>/ solution package (proposal + tasks)
• helloagents/ knowledge base workspace (INDEX/context/CHANGELOG/modules…)

📖 Documentation

This repo is intentionally a “multi-bundle distribution”.

Each bundle contains:

• Entry config: {BUNDLE_DIR}/{CONFIG_FILE}
• Skill package: {BUNDLE_DIR}/skills/helloagents/

Start here (replace {BUNDLE_DIR} with your chosen bundle folder):

• {BUNDLE_DIR}/skills/helloagents/SKILL.md (command list + entry behavior)
• {BUNDLE_DIR}/skills/helloagents/references/ (stages, rules, services)
• {BUNDLE_DIR}/skills/helloagents/scripts/ (automation scripts)

What you actually copy

You copy a config file plus a skill folder:

• Config: {CONFIG_FILE} (picked from the table above)
• Skill: skills/helloagents/ (includes SKILL.md, references/, scripts/, assets/)

Configuration (the knobs you’ll actually touch)

Most people only tweak a few global settings:

OUTPUT_LANGUAGE: zh-CN
ENCODING: UTF-8
KB_CREATE_MODE: 2
BILINGUAL_COMMIT: 1

KB_CREATE_MODE controls knowledge base writes:

• 0 (OFF): skip all KB operations
• 1 (ON_DEMAND): create KB only when explicitly requested
• 2 (ON_DEMAND_AUTO_FOR_CODING): auto-create for coding tasks (default)
• 3 (ALWAYS): always create/update KB

❓ FAQ

Q: Which bundle should I install?

A: Match the CLI you’re using:

• Codex CLI → Codex CLI/
• Claude Code → Claude Code/
• Gemini CLI → Gemini CLI/
• Grok CLI → Grok CLI/
• Qwen CLI → Qwen CLI/

Q: Can I install both?

A: Yes. They live in different config roots (~/.codex/ vs ~/.claude/). Just don’t mix the files inside one root.

Q: How do I invoke HelloAGENTS?

A: Use /helloagents or $helloagents to explicitly activate the skill. After that, use ~help or describe your task.

Q: Where does the knowledge base go?

A: In the project you are working on, HelloAGENTS writes to helloagents/ (unless disabled). It is the single source of truth for project knowledge in the workflow.

Q: How do I disable knowledge base writes?

A: Set KB_CREATE_MODE: 0 in your installed AGENTS.md / CLAUDE.md.

Q: What if I only want a light change?

A: The router can choose tweak mode for small, clear changes. You can also ask for “tweak mode / minimal change” explicitly.

Q: What are the key commands?

A: Try ~help. Common ones: ~plan, ~exec, ~test, ~commit, ~validate.

🛠️ Troubleshooting

Stuck in Evaluate (requirement score < 7)

Fix: answer the clarifying questions with concrete details (inputs/outputs, files to change, acceptance criteria).

---

Solution package validation failed

Fix: ensure the package has both files:

• proposal.md
• tasks.md

Then run ~validate (or follow the tool output).

---

“Skill not found” after copying

Fix:

• Confirm skills/helloagents/SKILL.md exists under your CLI config root (after copying)
• Re-run /helloagents or $helloagents

---

Windows path/encoding issues

Fix: keep files in UTF-8, and prefer quoted paths when copying folders with spaces (like Codex CLI/).

📈 Version History

Latest: v2.0 (2026-01)

• Positioning: from “AI programming partner” → intelligent workflow system
• Workflow: 3 stages → 4 stages (added Evaluate)
• Routing: simple routing → 3-layer routing (Context → Tools → Intent)
• Acceptance: basic checks → Stage / Gate / Flow acceptance
• Bundle distribution: Codex CLI and Claude Code both supported

🆚 v1 vs v2 snapshot:

Area	v1 (2025-12)	v2 (2026-01)
Positioning	AI programming partner	Intelligent workflow system
Stages	3 stages	4 stages (+ Evaluate)
Routing	Simple	3 layers (Context → Tools → Intent)
Acceptance	Basic	3 layers (Stage / Gate / Flow)
Files	6 files	44 files
Commands	4 commands	12 commands

🔒 Security

• EHRB detection is designed to catch destructive or high-risk operations before they run.
• Even so, review commands and diffs before applying changes to important systems.

If you believe you found a security issue, prefer using GitHub’s private reporting (Security Advisories) if enabled for this repo. Otherwise, contact the maintainer via their GitHub profile.

🙏 Acknowledgments

• AI CLI ecosystems (Codex CLI, Claude Code, etc.)
• Keep a Changelog conventions (used by the workflow knowledge base)
• MCP and the broader tool integration community

📜 License

This project uses a dual license:

• Code: Apache-2.0
• Documentation: CC BY 4.0

See LICENSE for details.