-
Notifications
You must be signed in to change notification settings - Fork 0
FAQ
Frequently asked questions about HES.
HES (Harness Engineer Standard) is a skill-based orchestration system for AI coding agents. It's a collection of Markdown-based skill files, configuration protocols, and shell/Python helper scripts that are injected into an LLM-powered AI coding assistant to make it execute software development workflows in a structured, phase-locked, quality-controlled manner.
Yes! HES is open source under the MIT License.
- The LLM (Large Language Model) is the Model
- HES is the Harness
When invoked (via /hes), the LLM reads HES's skill files and becomes a "HES Harness Engineer" — an AI agent that guides software development through a strict 10-phase workflow.
git clone https://github.com/josemalyson/hes.git
cd hes
./setupSee Getting-Started for detailed instructions.
HES works with any LLM-based coding assistant that supports structured instructions:
- Claude Code (Anthropic) — Native support
- Cursor — Native support
- GitHub Copilot — Via copilot-instructions.md
- Windsurf — Via .windsurfrules
- Gemini CLI — Via .agents/skills/
- Codex CLI — Via .agents/skills/
- OpenCode — Via .agents/skills/
- Kiro (AWS) — Native support
Yes! Use the --scope global flag:
./setup --scope global/hes start
This will bootstrap the project and begin the DISCOVERY phase.
/hes status
/hes next
The agent will check if the current phase gate is satisfied before advancing.
Yes, but you need a valid justification:
/hes skip --reason "already implemented"
/hes undo
ZERO → DISCOVERY → SPEC → DESIGN → DATA → RED → GREEN → SECURITY → REVIEW → DONE
Each phase has a gate that must be satisfied before advancing.
A gate is a condition that must be met before advancing to the next phase. For example, the DISCOVERY phase gate requires docs/discovery.md to exist with business rules.
The step budget limits the number of actions the agent can take in a single phase. At 80%, the agent warns. At 100%, the agent escalates.
Skill files are Markdown documents that tell the AI agent exactly what to do in each phase. They include:
- Phase-specific instructions
- Gate conditions
- Artifact requirements
- Reference materials
In the skills/ directory:
skills/
├── 00-bootstrap.md
├── 01-discovery.md
├── 02-spec.md
└── ...
Yes! See Contributing for how to add your own skills.
HES includes a SECURITY phase that runs:
- Bandit for Python security scanning
- Semgrep for multi-language security scanning
The agent will:
- Show the findings
- Block critical/high issues
- Ask you to fix them before proceeding
Yes, but it's not recommended:
/hes skip --reason "false positive: ..."
The bypass is logged for audit purposes.
- Check if your AI assistant is running
- Try a different command:
/hes status - Start a new session:
/hes session --restore
Check what's missing:
/hes status
The output will show which artifacts are required.
Options:
- Complete the current task manually
- Skip with justification:
/hes skip --reason "budget exceeded" - Start a new session:
/hes session --restore
See Contributing for detailed instructions.
Use the "Bug Report" issue template on GitHub.
Use the "Feature Request" issue template on GitHub.
See Contributing#Skill File Conventions for the conventions.
- Open a Discussion
- Check the GitHub Issues
- Read the README
Last updated: June 2026