Intent-First: A Lightweight Proxy Workflow Protocol to Stop AI Coding Assistants from 'Guessing'

Intent-First is a minimalist local proxy execution protocol designed to solve the 'guesswork' problem of AI coding assistants (like GitHub Copilot, Cursor, Claude Code). It uses a 5-stage workflow—Intent→Spec→Plan→Execution→Deliverables—with human approval required between each stage to ensure AI aligns with the developer's true intent. This protocol consists of only Markdown files and a Bash script, offering zero vendor lock-in and easy adoption/removal.

AI coding assistants often generate code based on guesses about the developer's intent. For example, a request for a 'login function' may ignore critical details (OAuth vs local, third-party providers, security requirements). This leads to frequent rework, reduced efficiency, and accumulated technical debt for large-scale projects involving multiple file modifications.

The core insight of Intent-First is that modern AI coding's bottleneck has shifted from code generation to intent capture. Key mechanisms include:

1. Phase Locking: After approval, stage files are set to read-only (via chmod) to prevent unapproved changes and scope creep.
2. Integrity Validation: The intent-first validate command checks if approved stages remain immutable. Intent-First is not a framework or SaaS—it’s just Markdown files and a Bash script, keeping it lightweight.

The protocol defines 5 stages with clear inputs/outputs and approval nodes:

• Intent: Developer writes the goal ('what' and 'why') in s1_intent.md (no implementation details).
• Spec: AI drafts technical specs (architecture, data models, dependencies) after /wf-spec {id}; needs approval.
• Plan: AI creates an execution plan (task decomposition, file changes, tests) after /wf-plan {id}; needs approval.
• Execution: AI codes per plan after /wf-execution {id}; no deviation without approval.
• Artifacts: AI generates docs and lessons after /wf-artifacts {id}.

YOLO Mode: For high-confidence tasks, AI auto-approves stages if confidence ≥85% (only pauses for low confidence), marked as [YOLO-AUTO]. Use cases: familiar codebase, low-risk tasks, fast iteration. Tool Compatibility: Supports GitHub Copilot, Cursor, Claude Code, etc., with auto-configured rule/prompt locations. No vendor lock-in—run intent-first implode to remove entirely.

Recommended Use: 3+ file changes, architecture refactors, complex tasks needing audit. Skip: Single-line fixes, config changes, quick docs. Model Strategy: Use strong models (GPT-4, Claude3.5 Sonnet) for Spec/Plan stages (depth needed), medium models for Execution, lightweight models for Artifacts—balancing quality and cost.

Value: Shifts to protocol-based collaboration (structured, traceable decisions, decoupled workflow). Limitations: Not zero-trust (AI can unlock stages, not for malicious agents). Future: Visualization tools, sub-workflows, CI/CD integration, pattern recommendations based on history.