hGATE — human Guided AI assisted Traceable Engineering

Human guided · AI assisted · Traceable engineering

Specs first. Every step traced. Nothing drifts.

hGATE is a manual, guided workflow for specification-driven development with an AI coding agent — domain-driven design, behavior-driven development, and test-driven development, connected by a traceability chain from spec to generated code to test to shipped change, so nothing can drift without leaving a trace.

Eight markdown skills + deterministic verifiers + a session-start sync protocol · MIT License

How it works

Three rules, all the way through.

The agent recommends and executes one specialist skill at a time. Humans confirm requirements, boundaries, plans, and every workflow transition.

Spec before code

Every stage traces back to an approved specification, not an improvised prompt. Generation never runs ahead of what's been agreed.

Domain boundaries hold

Bounded contexts (BCs) are established before behavior is written. Review checks that nothing generated implements behavior outside an approved spec.

Traced end to end

Every stage leaves a record — spec, decision, test, shipped code — reconciled by a mandatory session-start protocol before new work continues, so nothing can drift without leaving a trace.

What actually happens

One recommended skill at a time.

hgate-guide inspects your artifacts and recommends exactly one next skill — it never starts that skill or advances lifecycle state on its own.

A BC's first pass only needs a spec that covers what's shipping now — not a complete, permanent one. bc-enhancement below is how it deepens from there; most BCs go through several rounds of it as understanding grows.

→

VERIFY

Cross-BC Validation

ITERATE

bc-enhancement loops back into an already-shipped BC to add a new capability slice or change existing behavior. This is the normal way a BC matures — not a bug-fix exception — and every pass still closes with a full BC review.

Starting from an existing codebase rather than a blank one? domain-exploration and bc-refinement can read your existing code, APIs, and schemas as evidence to produce a first-draft spec — then bc-review full surfaces where the spec and the code have already drifted apart.

Already know your domain boundaries? architecture-decision-exploration handles a cross-system technical decision on its own, without repeating domain mapping.

What you actually get

Not process for its own sake — checkable artifacts.

Every guardrail below produces something you can point at, not just a convention everyone's supposed to remember.

ADR

Architecture Decision Records

Every non-trivial technical or domain decision gets a durable record — context, alternatives considered, and consequences — not just the decision that won.

GHOST CHECK

Ghost-behavior detection

Review flags any generated code implementing behavior that isn't traceable to an approved spec line. The agent doesn't get to quietly add scope.

TRACE

Scenario-to-test traceability

Every BDD scenario is linked to a real test. No orphaned tests, no untested scenarios sitting in a spec no one implemented. A deterministic verifier (verify:bdd) checks scenario IDs against Jest tests, and a BDD-to-TDD human sign-off loop records approval. Browse any BC's scenarios directly with the built-in Gherkin viewer instead of parsing raw Markdown by eye.

FAST PATH

Trivial-change fast path

A conservative triviality gate lets no-spec-impact changes — a rename, a perf tweak — skip the full pipeline. It still leaves an audit entry; it's a fast path, not a bypass.

PER-BC

Per-BC decision & status logs

Decisions and lifecycle status live next to the bounded context they describe, not in one global file every parallel agent collides on.

ACL

Anti-corruption layers

Each bounded context gets an explicit ACL at its integration points, so an external system's model can't quietly leak into yours.

PROPERTY

Property based testing

Test the rules, not just the examples. Example scenarios only cover the cases someone thought of. For the business rules that must always hold, hGATE can check them across thousands of generated cases and flag any that break. Optional, and added where the risk justifies it.

SIGN-OFF

Human sign-off

A person reviews and approves the behavior examples and the business rules separately, and each approval is kept as a permanent record. Passing tests never replace that judgment.

VERIFY-SPEC

Automatic spec checks

Routine consistency checks on your specifications run automatically and report only what's wrong, with the exact file and line. The AI saves its effort for the questions that need judgment.

PROJECTION

Always-current project map

The project overview used by the viewer is generated from your specs, so it never goes stale or gets edited by hand. CI tells you if it falls out of date.

Skill catalog

Eight skills. Each with one job.

Every skill produces a specific, checkable artifact — never just code. Skills are split into phases with on-demand references to keep agent context small.

Skill	Use it when	Main output
hgate-guide	You don't know the next workflow step	One recommended skill, never auto-started
domain-exploration	Problem, language, or BC boundaries are unclear	Confirmed domain map and context map
architecture-decision-exploration	A cross-system technical decision is unresolved	An ADR (Architecture Decision Record) or design report
bc-refinement	One BC needs an approved specification	Domain model, BDD scenarios, decisions, ACLs (anti-corruption layers)
bc-review	One BC needs a read-only audit	Evidence-based findings
bc-implementation	A refined BC has no material implementation	Tested implementation, traceability report, sign-off; optional property verification
bc-enhancement	A BC needs a new capability slice, a changed rule, or a bug fixed	Synchronized spec + code, ghost behavior removed; optional property verification
cross-bc-validation	A completed journey crosses several implemented BCs	Feature-local contract + validation report

Who it's for

The workflow doesn't change. The ceremony does.

Startup, scale-up, or enterprise client — the same eight skills apply. What flexes is how much gets formally signed off.

Startup

Move fast, keep the gates

Compress documentation and skip formal sign-off meetings.

Session-start sync stays mandatory
BC review still gates every merge
Lighter artifacts for throwaway prototype code

Scale-up

Full catalog, async

Every skill in play, without scheduled ceremony.

Specs live in the repo next to the code
Gates exist but run on pull requests, not meetings
Decision and status artifacts stay per-BC

Enterprise

Full ceremony, audited

Traceability treated as a compliance artifact, not a courtesy.

Independent review required before lifecycle transitions
Decision and status artifacts audited on a cadence
Scenario-to-test traceability checked, not assumed

Quickstart

Three steps. Then talk to your agent.

Copy the skills and verifiers in, install the session-start protocol, then hand it to your AI agent.

Add hGATE to your project

mkdir -p /path/to/your-project/.github/skills
cp -R skills/* /path/to/your-project/.github/skills/
mkdir -p /path/to/your-project/tools
cp -R tools/. /path/to/your-project/tools/
# copies every tool plus project-schema.json and other shared artifacts
# preserve each skill's SKILL.md, assets/, references/, decisions.md
# optional Goal 3: install fast-check for tools/business-verification

Install the project instructions

cp templates/CLAUDE.hgate.md /path/to/your-project/CLAUDE.md
# already have a CLAUDE.md? append the template, keep your conventions

Start with the guide

Use hgate-guide. I want to start using hGATE for this project.