Skip to content

Phases

Jump to bottom
Josemalyson Oliveira edited this page Jun 27, 2026 · 1 revision

Phases

The 10-phase workflow of HES.

Overview

ZERO → DISCOVERY → SPEC → DESIGN → DATA → RED → GREEN → SECURITY → REVIEW → DONE

Each phase has:

  • A skill file (skills/XX-name.md)
  • A gate (condition that must be met before advancing)
  • Artifacts (files that must be created)
  • A step budget (maximum actions before escalation)

ZERO

Purpose: Bootstrap the project

Skill: 00-bootstrap.md

Gate: .hes/ directory exists with valid current.json

Artifacts:

  • .hes/state/current.json
  • .hes/agents/registry.json
  • .hes/schemas/*.json

DISCOVERY

Purpose: Elicit business rules and requirements

Skill: 01-discovery.md

Gate: docs/discovery.md exists with business rules

Artifacts:

  • docs/discovery.md — Business rules
  • docs/business-rules.md — Formal business rules

Activities:

  1. Interview stakeholders
  2. Identify actors and use cases
  3. Document business rules
  4. Validate with stakeholders

SPEC

Purpose: Write BDD scenarios and API contracts

Skill: 02-spec.md

Gate: docs/spec.md exists with BDD scenarios

Artifacts:

  • docs/spec.md — BDD scenarios
  • docs/api-contracts.md — API contracts (if applicable)

Activities:

  1. Convert business rules to BDD scenarios
  2. Define API contracts
  3. Validate scenarios with stakeholders

DESIGN

Purpose: Make architecture decisions

Skill: 03-design.md

Gate: docs/design.md exists with ADRs

Artifacts:

  • docs/design.md — Architecture Decision Records

Activities:

  1. Identify architectural drivers
  2. Make design decisions
  3. Document ADRs
  4. Validate with team

DATA

Purpose: Design data model and migrations

Skill: 04-data.md

Gate: docs/data.md exists with data model

Artifacts:

  • docs/data.md — Data model
  • migrations/ — SQL migrations (if applicable)

Activities:

  1. Design entity-relationship diagram
  2. Define schema
  3. Write migrations
  4. Validate with stakeholders

RED

Purpose: Write tests first (TDD)

Skill: 05-tests.md

Gate: Tests are written and failing

Artifacts:

  • Test files (failing)

Activities:

  1. Write unit tests
  2. Write integration tests
  3. Verify tests fail (RED)

GREEN

Purpose: Implement code to make tests pass

Skill: 06-implementation.md

Gate: All tests pass

Artifacts:

  • Implementation code
  • All tests passing

Activities:

  1. Implement minimal code to pass tests
  2. Refactor as needed
  3. Verify all tests pass (GREEN)

SECURITY

Purpose: Run security scans

Skill: 10-security.md

Gate: No critical/high findings

Artifacts:

  • Security scan reports

Activities:

  1. Run Bandit (Python)
  2. Run Semgrep (multi-language)
  3. Review findings
  4. Fix critical/high issues

REVIEW

Purpose: Code review

Skill: 07-review.md

Gate: Review checklist completed

Artifacts:

  • Review checklist (completed)

Activities:

  1. Review code quality
  2. Review architecture
  3. Review security
  4. Review documentation
  5. Approve or request changes

DONE

Purpose: Feature complete

Skill: None (terminal state)

Gate: All previous gates satisfied

Artifacts:

  • Feature branch ready for merge

Activities:

  1. Final verification
  2. Create PR
  3. Merge to main

Phase Transitions

Advancing

/hes next

The agent will:

  1. Check if the current phase gate is satisfied
  2. If yes, advance to the next phase
  3. If no, explain what's missing

Skipping

/hes skip --reason "justification"

Requires a valid justification. The skip is logged.

Rolling Back

/hes undo

Rolls back to the previous phase.

Last updated: June 2026

Clone this wiki locally