HelloAGENTS

📑 Table of Contents

🎯 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.

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

🔁 Before & After

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

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

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:

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

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

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

🛠️ 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:

🔒 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.