Codifying Product Intent: A Repository-First Framework for Agent-Aligned UI
Current Situation Analysis
Coding agents have reached a level of proficiency where they can generate functional UI components rapidly. However, a critical disconnect remains between syntactic correctness and product intent. Agents operate on the codebase as their primary context window. When a developer asks an agent to "build a settings modal," the agent analyzes existing components, prop interfaces, and styling tokens. It produces code that compiles and renders.
The failure mode is semantic. The agent cannot distinguish between a component that exists because it is the optimal solution and one that exists due to a legacy constraint, a temporary workaround, or a specific business rule that was never documented in code. The reasoning behind product decisions—why a modal requires two-step confirmation, why a specific error state triggers a redirect, or why copy must avoid certain terminology—resides in design reviews, Slack threads, Figma comments, and tribal knowledge. To an agent, this context is invisible.
This creates a "Context Gap." As teams adopt agents for UI work, they risk scaling inconsistencies. Agents will replicate patterns found in the codebase without understanding the underlying product logic. A team might ship a feature that works technically but violates accessibility standards, brand voice, or user flow expectations because the agent lacked the governing constraints.
The industry often treats design systems and coding agents as separate domains. Design systems provide tokens and components; agents write code. The missing layer is the explicit codification of product decisions. Without this, agents are effectively guessing at product requirements based on historical code, which may be outdated or suboptimal.
WOW Moment: Key Findings
The shift from implicit product knowledge to explicit repository-based governance fundamentally changes how agents interact with UI development. By treating product decisions as version-controlled artifacts, teams transform agents from pattern-matching code generators into intent-aware collaborators.
The following comparison illustrates the operational difference between traditional knowledge management and a repository-first approach:
Dimension
Implicit Knowledge (Status Quo)
Explicit Repository Knowledge (Codified)
Context Source
Slack, Figma, PR comments, Tribal memory
references/ directory, manifest.yaml, exemplars/
Agent Access
None; agents hallucinate or copy code blindly
Deterministic; agents load directives via skill routing
Update Mechanism
Meetings, ad-hoc messages, design updates
Pull requests, lint checks, review loops
Auditability
Low; decisions scattered across tools
High; every guideline change is versioned and reviewed
Failure Mode
Agent produces "correct" code that violates product intent
Agent flags conflicts or requests clarification based on explicit rules
Scalability
Degrades as team grows; knowledge silos form
Improves as repository grows; single source of truth
This finding matters because it enables deterministic UI generation. When product intent is codified, agents can validate their output against explicit constraints before writing code. This reduces review cycles, prevents regression of product standards, and allows teams to scale agent usage without sacrificing design quality.
Core Solution
The solution is a Product-as-Code framework. This approach treats product decisions, interaction patterns, and quality standards as first-class citizens in the repository, structured for machine consumption by agents while remaining readable for humans.
Architecture Overview
The framework consists of three integrated components:
Agent Skill Manifest: Defines the skill's scope, routing logic, and operating contract. This file instructs the agent on when to activate, what modes are available, and how to resolve conflicts.
Reference Library: A structured directory containing decision frameworks, state inventories, copy standards, and surface-specific guidelines. These files provide the "why" behind UI patterns.
Exemplar Repository: A collection of approved pull requests and patterns that demonstrate correct implementation. This serves a
s positive reinforcement and helps agents understand nuanced application of rules.
Directory Structure
The following structure demonstrates a repository-first approach. Note the separation of concerns and the explicit naming conventions.
The manifest acts as the entry point. It declares the skill's purpose, triggers, and constraints. This file should be concise to minimize token usage while providing clear routing instructions.
Directives define the agent's operating contract. Crucially, directives must separate concerns into distinct modes to prevent scope creep. An agent asked to "fix copy" should not redesign the layout.
# .ai/skills/ux-intent/directives.md
## Operating Contract
- **Intent First:** Identify the user goal and product object before selecting components.
- **Evidence Over Taste:** Justify decisions using repository guidelines, accepted patterns, or verified user data.
- **State Completeness:** Design for all reachable states, including loading, empty, error, and permission variants.
- **Minimal Intervention:** Prefer behavior changes or defaults over adding new UI elements.
## Request Modes
| Mode | Trigger Verbs | Scope | Constraints |
|------|---------------|-------|-------------|
| `Shape` | "design", "flow", "how should" | Define requirements, states, and acceptance criteria | No implementation; output plan only |
| `Build` | "build", "implement", "create" | Develop UI based on settled decisions | Must load relevant references; verify states |
| `Review` | "audit", "critique", "review" | Inspect existing UI against standards | Report findings; no edits unless requested |
| `Polish` | "polish", "refine", "edge cases" | Improve resilience, accessibility, and copy | Preserve settled direction; fix defects only |
## Decision Authority Hierarchy
1. User's explicit goal and constraints.
2. Verified product evidence and system behavior.
3. Repository guidelines (`references/`, `manifest.yaml`).
4. Approved exemplars and stable patterns.
5. General interface heuristics.
## Workflow
1. **Resolve Mode:** Determine mode from trigger verb. If ambiguous, use narrowest scope.
2. **Load Context:** Read `decision-framework.md` and surface-specific rules.
3. **Model Decision:** For `Shape` or `Build`, document user, job, outcome, and states.
4. **Map States:** Inventory all reachable states including error, empty, and responsive variants.
5. **Apply Rules:** Enforce copy standards, accessibility criteria, and interaction patterns.
6. **Verify:** Check against `state-inventory.md` and run lint checks.
Step 3: Populate Reference Library
References provide the granular rules agents need. Avoid duplicating design system documentation; instead, link to canonical sources or summarize decisions relevant to agents.
# .ai/skills/ux-intent/references/decision-framework.md
## Product Judgment Criteria
When evaluating UI decisions, apply the following filters:
- **User Task Alignment:** Does the interface support the primary user job?
- **Consequence Clarity:** Are the results of actions explicit and reversible?
- **Scope Management:** Does the solution avoid introducing unrelated settings or abstractions?
- **Context Preservation:** Does the change maintain the user's mental model?
## Surface-Specific Routing
- **Modals:** Load `surface-rules/settings.md` for validation and progressive disclosure patterns.
- **Dashboards:** Load `surface-rules/dashboard.md` for data density and navigation rules.
- **Forms:** Apply `copy-standards.md` for labels, errors, and accessible names.
Step 4: Establish Exemplars and Gaps
Exemplars help agents understand nuanced application of rules. Include both positive examples and anti-patterns to avoid.
# .ai/skills/ux-intent/exemplars/approved-patterns.md
## Approved: Destructive Action Confirmation
**Context:** PR #4821 - Delete Account Flow
**Pattern:** Two-step confirmation with explicit consequence statement.
**Implementation:**
- Modal title: "Delete Account"
- Body: "This action cannot be undone. All data will be permanently removed."
- Input: User must type "DELETE" to enable confirmation button.
- Rationale: Prevents accidental data loss; aligns with security policy.
## Anti-Pattern: Silent State Transitions
**Context:** PR #3990 - Status Update
**Issue:** Component updated status without user feedback or loading state.
**Correction:** Add optimistic update with rollback on error; display toast notification.
Step 5: Integrate Linting and Review Loops
Automate enforcement where possible. Linters can check for common violations, such as missing state handling or copy inconsistencies. Additionally, establish a review loop where guideline updates are proposed via pull requests, ensuring that product standards evolve with team consensus.
Pitfall Guide
1. The Duplicate Doc TrapExplanation: Teams often copy design system documentation or Figma specs directly into the repository. This creates maintenance overhead and leads to drift when source documents update.
Fix: Reference canonical sources via links or summaries. Only codify decisions that are unique to the product or require agent-specific context.
2. Mode BleedExplanation: Agents expand the scope of a request. For example, an agent asked to "fix copy" might also redesign the layout or change component structure.
Fix: Enforce strict mode boundaries in directives. Define clear constraints for each mode and instruct the agent to report structural blockers without silently broadening scope.
3. Stale ExemplarsExplanation: Over time, exemplars may become outdated as product standards evolve. Agents might reference old patterns that no longer align with current guidelines.
Fix: Implement a periodic review process for exemplars. Use coverage-gap files to flag areas where standards have changed but exemplars have not been updated.
4. Ignoring Coverage GapsExplanation: When agents encounter areas without explicit guidelines, they may hallucinate solutions or default to suboptimal patterns.
Fix: Maintain a coverage-gaps.md file that lists areas without standards. Instruct agents to flag these gaps during reviews and propose guidelines for team review.
5. Over-Engineering the SkillExplanation: Creating overly complex routing logic or excessive files can confuse agents and increase token usage.
Fix: Start with a minimal viable directive. Iterate based on agent behavior and team feedback. Prioritize clarity and conciseness over exhaustive coverage.
6. Missing State InventoryExplanation: Agents often focus on the happy path and neglect edge cases like loading, empty, or error states.
Fix: Require a state inventory step in the workflow. Use state-inventory.md to define all reachable states and mandate that agents verify coverage before implementation.
7. Lack of Feedback LoopExplanation: Guidelines become static and disconnected from evolving product needs.
Fix: Establish a review loop where guideline updates are proposed via pull requests. Gather evidence from Slack, Figma, and GitHub to inform updates. Ensure that changes are reviewed and approved by the team.
Production Bundle
Action Checklist
Initialize Directory Structure: Create .ai/skills/ux-intent/ with manifest.yaml, directives.md, references/, and exemplars/.
Define Operating Contract: Write directives.md with clear modes, decision hierarchy, and workflow steps.
Populate References: Add decision-framework.md, state-inventory.md, and surface-specific rules. Link to canonical sources where appropriate.
Seed Exemplars: Include approved patterns and anti-patterns from recent pull requests. Document rationale and implementation details.
Configure Routing: Update manifest.yaml with triggers, exclusions, and routing paths. Ensure agents load the skill on relevant requests.
Integrate Linting: Add scripts to validate copy standards, state coverage, and accessibility criteria. Run checks in CI/CD pipeline.
Establish Review Loop: Create a process for proposing guideline updates via pull requests. Gather evidence from design reviews and user feedback.
Test Agent Behavior: Run agent tasks in Shape, Build, Review, and Polish modes. Verify adherence to directives and refine as needed.
Decision Matrix
Scenario
Recommended Approach
Why
Cost Impact
Startup / MVP
Minimal directives with core modes (Build, Review)
Reduces overhead; focuses on rapid iteration
Low initial cost; scales with team growth
Enterprise / Compliance
Comprehensive framework with strict state inventory and audit trails
# .ai/skills/ux-intent/directives.md
## Operating Contract
- **Intent First:** Align UI with user goals and product objects.
- **Evidence Over Taste:** Justify decisions using guidelines and verified data.
- **State Completeness:** Design for all reachable states.
- **Minimal Intervention:** Prefer behavior changes over new UI.
## Request Modes
| Mode | Trigger Verbs | Scope | Constraints |
|------|---------------|-------|-------------|
| `Shape` | "design", "flow" | Define requirements and states | No implementation |
| `Build` | "build", "implement" | Develop UI based on decisions | Load references; verify states |
| `Review` | "audit", "critique" | Inspect UI against standards | Report findings; no edits |
| `Polish` | "polish", "refine" | Improve resilience and copy | Preserve direction; fix defects |
## Decision Authority
1. User goal and constraints.
2. Verified product evidence.
3. Repository guidelines.
4. Approved exemplars.
5. Interface heuristics.
## Workflow
1. Resolve mode.
2. Load context.
3. Model decision.
4. Map states.
5. Apply rules.
6. Verify output.
Quick Start Guide
Create the Skill Directory: Run mkdir -p .ai/skills/ux-intent/{references,surface-rules,exemplars} in your repository root.
Add Manifest and Directives: Copy the configuration template into manifest.yaml and directives.md. Customize triggers and modes to match your team's workflow.
Seed Initial References: Create decision-framework.md and state-inventory.md with core product rules. Add surface-specific files for key UI areas.
Test Agent Integration: Trigger an agent task using a defined mode (e.g., "Build a settings form"). Verify that the agent loads the skill, applies directives, and produces compliant output.
Iterate and Expand: Review agent behavior and refine directives. Add exemplars and expand references based on team feedback and evolving product standards.
🎉 Mid-Year Sale — Unlock Full Article
Base plan from just $4.99/mo or $49/yr
Sign in to read the full article and unlock all 635+ tutorials.
