name	using-antmachine
description	Use at session start. Teaches antmachine skill activation.

Using Antmachine

You have antmachine - a system with SPECIFIC mechanics you don't know. Do NOT assume you understand these skills based on their names. Each has unique implementation details. You MUST read the full SKILL.md when invoked.

The Rule: Orient First

ALL user messages route through ant-orient first.

Orient is the cognitive hub that determines what's needed:

Purpose unclear? → Orient invokes intent
Need facts? → Orient invokes ant-observe
Need options? → Orient generates plans
High confidence, clear action? → Orient routes to ant-act

Never skip Orient. Even "simple questions" need Orient to assess what's required. This includes:

Tasks ("implement X")
Questions ("where is Y?")
Clarifications ("what about Z?")

If you find yourself looking at files or taking action without invoking Orient first, STOP. You're breaking the loop.

How to Invoke

Use the Skill tool to invoke antmachine skills:

To do this	Invoke
Discover purpose (new task)	`Skill("antmachine:intent")`
Gather facts before deciding	`Skill("antmachine:ant-observe")`
Think before acting	`Skill("antmachine:ant-orient")`
Choose between options	`Skill("antmachine:ant-decide")`
Execute a chosen plan	`Skill("antmachine:ant-act")`

Development Skills

To do this	Invoke
Define behavior examples (before code)	`Skill("antmachine:bdd")`
Write code (requires tests first)	`Skill("antmachine:tdd")`
Verify before claiming done	`Skill("antmachine:verification")`
Create or edit skills	`Skill("antmachine:writing-skills")`

Do NOT use the Read tool on skill files. Use the Skill tool - it properly injects the skill into context.

Red Flags (Anti-Rationalization)

These thoughts mean STOP - you're skipping the system:

Thought	Reality
"This is just a question"	Questions need Orient. Orient decides if observation is needed.
"I'll just look at the files quickly"	That's observation without ant-observe. Invoke Orient first.
"This is simple, I'll just do it"	Simple tasks still need Orient to assess.
"I know what these skills do"	You don't. Antmachine has specific mechanics. Read them.
"Let me start coding first"	Orient first. Always.
"I'll think in my head"	Use the skill. Artifacts matter.
"Purpose is obvious"	Invoke intent skill. 5 Whys required before planning.
"I need to gather info first"	That's ant-observe's job. Invoke Orient, let it dispatch observers.

Artifact-Driven Development (ADD)

Antmachine follows ADD: each phase produces required artifacts before progressing.

The Flow

Intent → Orient → Decide → BDD → TDD → Verify
   ↓        ↓        ↓       ↓      ↓       ↓
purpose   plans   choice  examples code  evidence

Phase Gates

Phase	Gate (Artifact Required)	Next Phase
New task	Intent artifact (5 Whys, purpose, values)	Orient
Orient	Plan artifacts (2-4 options with tradeoffs)	Decide
Decide	Decision record (chosen plan + reasoning)	BDD
BDD	Approved behavior examples	TDD
TDD	Passing tests for each example	Verify
Verify	Evidence (all examples pass)	Done

No artifact = phase not complete = can't proceed.

Intent First

Every new task starts with intent:

Receive task
Invoke intent skill
Do 5 Whys → find purpose and values
Write intent artifact to .antmachine/intent/
THEN invoke orient for planning

Without intent artifact, orient will refuse to generate plans.

Install Skill

SKILL.md