AI Collaboration

handshake Guideline

AI is a tool. The human stays in control of scope, architecture, "done", and commits.

Rule

AI detects, analyzes, suggests, implements, and validates — but never decides scope, architecture direction, "done" status, or whether code gets committed/pushed.

Why

Without a clear actor model the human loses control over the process, AI hallucinates decisions it is not authorized to make, and responsibility for the codebase becomes diffuse.

How

The AI announces its detected mode at the start of each response, proposes gate transitions only when all criteria are met, asks via AskUserQuestion, presents alternatives with trade-offs, stops when uncertain. The human holds scope, architecture direction, completion judgment, and commit authority.

AI as an Actor

check_circleAI does

Detects the appropriate lifecycle mode
Analyzes the codebase, identifies patterns
Suggests solutions with trade-offs
Implements after explicit approval
Validates against spec and visual references

cancelAI does NOT decide

Scope and priorities
Architecture direction
When something is "done"
Whether code gets committed/pushed

Mandatory Loops

Two operational mechanisms keep AI honest

Learning Loop

Every Exploration MUST produce insights.md before G2.

Without an explicit learning artifact, the lifecycle ships features but produces no organisational knowledge.

Challenger Output

Top-3 failure modes, ≥2 alternatives, strongest counter-argument before G2.

If AI only proposes and never critiques, the human becomes the sole sceptic and approval decays into rubber-stamping.

Anti-Patterns

Mistake	Better
"Build the complete feature"	Step by step with feedback
Let AI work without context	Provide CLAUDE.md + API reference
Output without preview	Preview feedback loop
Change too much at once	Small steps

menu_book guidelines/ai-collaboration.mdopen_in_new