agent-native-product

name	agent-native-product
description	Turn a product idea into an agent-native architecture and build plan. Use when designing a new product, MVP, internal tool, or AI feature where agents should be first-class citizens and achieve outcomes in a loop with tools.
argument-hint	["product idea","domain","or feature"]

Agent-Native Product Builder

When To Use

Use this skill when:

• starting a new product from scratch
• turning an AI feature into a first-class part of the product
• deciding what tools an agent should have
• designing shared workspace, files, prompts, and UI integration
• checking whether a new product is truly agent-native or just agent-flavored

If the user gives only a rough idea, help shape it into an agent-native blueprint. If the user already has a spec or codebase, map the existing design to these principles and identify gaps.

Core Principles

1. Parity

Whatever the user can do through the UI, the agent must be able to achieve through tools.

2. Granularity

Prefer atomic primitives. Features are outcomes achieved by an agent in a loop.

3. Composability

When tools are atomic and parity exists, new features should mostly come from new prompts instead of new code.

4. Emergent Capability

The system should let the agent solve reasonable domain tasks you did not explicitly pre-build.

5. Explicit Completion

Do not rely on heuristics to guess whether the agent is done. Give it an explicit completion signal.

6. Shared Workspace

Default to agent and user operating on the same underlying data space.

Workflow

Step 1: Clarify the Product

If important details are missing, ask concise questions before proposing architecture:

1. Who is the user?
2. What outcomes are they trying to achieve?
3. What are the core entities in the product?
4. What actions will users take in the UI?
5. What should the agent be able to do on the user's behalf?
6. Are there constraints around mobile, offline, approvals, privacy, or external APIs?

If $ARGUMENTS contains a product idea, start from that instead of asking broad openers.

Step 2: Build the Capability Map

Create a table that covers the main user-visible actions.

User Action	Agent Outcome	Tools or Methods	Parity Status	Notes

Rules:

• Do not leave important UI actions unmapped.
• If a user can do it and the agent cannot, mark it as a parity gap.
• Focus on outcomes, not button-by-button mirroring.

Step 3: Design the Tool Layer

Prefer primitives first. Add domain tools only when they clearly help.

Use these rules:

• Use primitives by default: read, write, list, search, update, delete, call API, send message
• Add domain tools for vocabulary anchoring: create_note may be clearer than write_file
• Add domain tools for guardrails: validation that should not depend on model judgment
• Add domain tools for efficiency: common multi-step actions worth shortening
• Keep primitives available unless you intentionally want a gate

For every important entity, verify CRUD completeness:

Entity	Create	Read	Update	Delete	Gaps

If the product depends on a broad external API, prefer dynamic capability discovery where possible.

Bad:

• analyze_and_publish
• classify_and_organize_everything

Better:

• read_document
• write_document
• move_item
• publish_content
• list_available_types
• read_data(type)

Step 4: Design the Shared Workspace

Decide what lives in files, what lives in a database, and what the agent can inspect directly.

Use files for:

• user-readable content
• agent-generated content the user may inspect or edit
• transparent configuration
• durable research, notes, drafts, plans

Use databases for:

• high-volume structured data
• indexing and relationships
• fast queries
• ephemeral runtime state when files are a bad fit

If files are part of the product, propose a directory layout like:

{entity_type}/{entity_id}/
├── data.json
├── content.md
├── metadata.json
└── agent_log.md

Distinguish durable from ephemeral data:

Documents/
├── Durable/
│   ├── Notes/
│   └── Projects/
├── AgentCheckpoints/
└── AgentLogs/

Include a context.md pattern whenever useful. The agent should be able to read a concise file that states:

• who it is
• what exists
• what it knows about the user
• recent activity
• guidelines
• current state

Step 5: Define the Agent Loop

Specify how the agent works until completion.

Always design for:

• explicit completion tool or signal
• recoverable errors
• task-level progress tracking
• resumability for longer tasks

Recommended completion model:

success(output)        // task succeeded, may continue
error(message)         // recoverable issue, may continue
complete(summary)      // done, stop loop

Recommended task statuses:

• pending
• in_progress
• completed
• failed
• skipped

If mobile or background interruption matters, include checkpoint/resume behavior.

Step 6: Draft Context Injection

Write the system prompt so the agent knows what exists and what it can do.

Always include:

• available resources
• available capabilities
• recent context
• domain guidelines
• completion rule

Use a structure like:

## Available Data
- 12 notes in /notes
- 3 projects in /projects

## What You Can Do
- create, edit, organize, and delete notes
- search across all content
- update project metadata

## Recent Context
- user created "Project kickoff" today

## Guidelines
- be concise
- avoid destructive actions without confirmation when stakes are high

## Completion
- call complete_task when the requested outcome is achieved

Step 7: Define Agent-to-UI Communication

Make agent activity visible.

Common event types:

• thinking
• tool_call
• tool_result
• text_response
• status_change

Rules:

• no silent actions
• show progress during execution, not only at the end
• reflect shared data changes in the UI immediately
• if internal tool chatter is noisy, hide only the noise, not the meaningful progress

Step 8: Stress-Test the Design

Before signing off, check these questions:

1. Can the agent achieve every important user action?
2. To change behavior, would you mostly edit prompts or refactor code?
3. Can the agent solve a reasonable open-ended request in this domain?
4. Are any tools workflow-shaped instead of primitive?
5. Does every important entity have full CRUD?
6. Does the agent know what resources exist at runtime?
7. Do agent actions show up in the UI immediately?
8. Does the loop stop through an explicit completion signal?

If the answer to any of these is no, call it out as a design gap.

Required Output

Always end with a concrete blueprint in this format:

# Agent-Native Product Blueprint: <product name>

## 1. Product Outcome
- Who the product is for
- Core user job
- What makes the agent first-class

## 2. Core Entities
- List the main objects in the system

## 3. Capability Map
| User Action | Agent Outcome | Tools or Methods | Gap? | Notes |

## 4. Tool Design
### Primitive Tools
- ...

### Domain Tools
- ...

### CRUD Coverage
| Entity | Create | Read | Update | Delete | Notes |

## 5. Shared Workspace and Data Model
- What lives in files
- What lives in the database
- Directory layout or schema notes
- `context.md` strategy

## 6. Agent Loop
- Completion signal
- Progress tracking
- Resume/checkpoint strategy

## 7. System Prompt Skeleton
- Available data
- Capabilities
- Recent context
- Guidelines
- Completion instruction

## 8. UI Integration
- How agent actions become visible
- Event model
- Approval boundaries

## 9. Implementation Sequence
1. ...
2. ...
3. ...

## 10. Risks and Anti-Patterns
- parity gaps
- workflow-shaped tools
- context starvation
- heuristic completion
- isolated agent workspace

## 11. Open-Ended Capability Test
- One domain request the team did not explicitly build
- Why the proposed architecture should still handle it

## 12. Success Checklist
- [ ] parity achieved
- [ ] tools are atomic
- [ ] CRUD complete
- [ ] explicit completion exists
- [ ] context injection defined
- [ ] shared workspace chosen
- [ ] UI reflects agent actions
- [ ] system can handle an unexpected but in-domain request

Anti-Patterns

Flag these clearly when they appear:

• agent as router only
• workflow-shaped tools
• orphan UI actions
• context starvation
• heuristic completion detection
• static tool-per-endpoint mapping where dynamic discovery would work
• incomplete CRUD
• separate agent-only workspace without a good reason
• hidden agent actions that never surface to the user

Output Style

Be opinionated, concrete, and product-minded. Do not stay abstract if you can turn the idea into a proposed architecture. Prefer tables, checklists, and named tradeoffs over vague prose. When uncertain, state assumptions explicitly.