# 🎯 Product Owner Guide - Creating Features with Crafted Skills

**For**: Product Owners (humans or AI agents)
**Goal**: Transform your feature ideas into production-ready code
**Duration**: 10 minutes read

---

## 🎬 Introduction

As a Product Owner, you have feature ideas but may not code yourself. **Crafted Skills allows you to create features by simply describing what you want, in natural language.**

### How does it work?

```
You describe the feature
         ↓
Skills detects quality level
         ↓
Skills generates:
  - Architecture
  - Code
  - Tests
  - Validation
         ↓
Feature ready! ✅
```

**Time**: ~2-3 minutes for simple features, ~5-10 minutes for complex ones.

---

## 📝 Feature Description Format

### Base Template

```
As a [USER],
I want [ACTION],
So that [BENEFIT]

Acceptance criteria:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

Technical details (optional):
- Data: [what data]
- Validation: [what rules]
- Security: [who can access]
```

### Simplified Format (even faster)

```
I want to add [FUNCTIONALITY] with [DETAILS]
```

**Both formats work!** Skills understands natural language.

---

## 🚀 Concrete Examples

### Example 1: Simple Feature - User Profile

**PO Description**:
```
I want to add a user profile with:
- Full name
- Bio (short text)
- Profile photo (optional)

Users should be able to:
- View their profile
- Edit their information
- Upload a photo

Validation:
- Name is required
- Bio max 500 characters
```

**What Skills will generate** (automatically):
```
✅ Architecture detected: Balanced (3-layer)

Files created:
  📁 packages/api/routers/profile.ts
  📁 packages/services/profile.service.ts
  📁 packages/database/repositories/profile.repository.ts
  📁 packages/validators/profile.validator.ts

Tests generated:
  🧪 profile.service.test.ts (15 tests)
  🧪 profile.router.test.ts (8 tests)

Coverage: 76% ✅

Validation:
  ✅ Code quality OK
  ✅ Architecture OK
  ✅ Tests OK
```

**Time**: ~2 minutes

---

### Example 2: Complex Feature - Payment System

**PO Description**:
```
As a user,
I want to pay by credit card,
So that I can subscribe to a monthly plan.

Acceptance criteria:
- [ ] User can enter credit card information
- [ ] Payment is secure (Stripe)
- [ ] User receives confirmation email
- [ ] Subscription is activated immediately
- [ ] On failure, user sees clear error message

Available plans:
- Starter: $19/month
- Pro: $49/month
- Enterprise: $99/month

Business rules:
- A user can only have one active subscription
- Free trial lasts 14 days
- Payment renews automatically
```

**What Skills will generate**:
```
🔍 Detection: Balanced level, Web platform

🏗️  ARCHITECTURE (Phase 1/4):
  Router Layer:
    - subscriptionRouter.subscribe()
    - subscriptionRouter.cancel()
    - subscriptionRouter.getCurrent()

  Service Layer:
    - subscriptionService.create()
    - subscriptionService.processPayment()
    - subscriptionService.sendConfirmationEmail()

  Repository Layer:
    - subscriptionRepository (Prisma)

  ADR created: ADR-042-subscription-model.md

👨‍💻 IMPLEMENTATION (Phase 2/4):
  Files created:
    ✅ packages/api/routers/subscription.ts (18 lines)
    ✅ packages/services/subscription.service.ts (45 lines)
    ✅ packages/database/repositories/subscription.repository.ts (32 lines)
    ✅ packages/validators/subscription.validator.ts (25 lines)
    ✅ packages/payments/stripe-client.ts (38 lines)
    ✅ packages/emails/templates/SubscriptionConfirmation.tsx

🧪 TESTS (Phase 3/4):
  Tests created:
    ✅ Payment successful
    ✅ Payment failed (card declined)
    ✅ Email sent
    ✅ Subscription activated
    ✅ Auto-renewal
    ✅ Cancellation
    ✅ Only one active subscription

  Coverage: 78% (required: 70%)

👀 VALIDATION (Phase 4/4):
  ✅ Code quality OK
  ✅ Architecture OK (3-layer)
  ✅ Tests OK (78% coverage)
  ✅ Security OK (Stripe secure)

Feature ready! 🎉
```

**Time**: ~5 minutes

---

### Example 3: Feature with Permissions

**PO Description**:
```
I want a permissions system for teams:

Roles:
- Admin: Can do everything
- Manager: Can invite/remove members
- Member: Can view team

Features:
- Create team (Admin only)
- Invite members (Admin + Manager)
- Remove members (Admin + Manager)
- View members (Everyone)
- Change role (Admin only)

Rules:
- There must always be at least 1 Admin
- Admin cannot remove themselves
- Invitations expire after 7 days
```

**Result**:
```
✅ Architecture: 3-layer with RBAC (Role-Based Access Control)

Files:
  📁 routers/team.ts
  📁 services/team.service.ts
  📁 services/team-permissions.service.ts
  📁 repositories/team.repository.ts
  📁 middleware/check-team-role.ts

Tests:
  🧪 28 tests (all permission cases)

Coverage: 82%
```

---

## 📋 Checklist Before Describing a Feature

Before asking Skills to create a feature, make sure you have:

- [ ] **Who**: Which user uses this feature?
- [ ] **What**: What action does the user want to do?
- [ ] **Why**: What problem does it solve?
- [ ] **Data**: What data is needed?
- [ ] **Validation**: What validation rules?
- [ ] **Security**: Who can access what?
- [ ] **Edge cases**: What can go wrong?

**The more specific you are, the better the generated code.**

---

## 🎯 Quality Level: Rapid vs Balanced vs Crafted

Skills automatically adapts to your project level:

### Rapid (MVP, 0-100 users)

**When**: Testing an idea, you want to ship fast

**Example**:
```
"I want a like system for posts"
```

**Result**:
- Simple, direct code
- Logic in routers
- No required tests
- **Time**: ~1 minute

### Balanced (Growing product, 100-10K users)

**When**: You have paying customers, you want quality

**Example**:
```
"I want a like system with counter and history"
```

**Result**:
- 3-layer architecture
- Separated business logic
- 70% test coverage
- **Time**: ~3 minutes

### Crafted (Enterprise, 10K+ users)

**When**: Building for 10+ years, maximum quality

**Example**:
```
"I want a thread-safe like system with analytics"
```

**Result**:
- Hexagonal architecture
- Domain-Driven Design
- 100% test coverage
- ADRs for every decision
- **Time**: ~10 minutes

**Skills auto-detects level from `.craftedrc.json`**

---

## 🎨 Ready-to-Use Feature Templates

### Template: Authentication

```
I want to add user authentication with:

Methods:
- Email + Password
- Google OAuth (optional)

Features:
- Sign up (email, password, name)
- Sign in
- Sign out
- Forgot password
- Email verification

Validation:
- Valid email
- Password min 8 characters
- Password must contain: 1 uppercase, 1 number

Security:
- Hash passwords (bcrypt)
- JWT tokens
- Refresh tokens
```

---

### Template: Simple CRUD

```
I want to manage [ENTITY] with:

Fields:
- [field1]: [type]
- [field2]: [type]
- [field3]: [type]

Actions:
- Create [ENTITY]
- Read [ENTITY] (list + detail)
- Update [ENTITY]
- Delete [ENTITY]

Validation:
- [validation rules]

Permissions:
- Who can do what
```

**Concrete example**:
```
I want to manage Products with:

Fields:
- Name: string (required)
- Description: text
- Price: number (in cents)
- Stock: number
- Category: enum (Electronics, Clothing, Food)
- Image: url (optional)

Actions:
- Create product (Admin only)
- Read products (Everyone)
- Update product (Admin only)
- Delete product (Admin only)

Validation:
- Name between 3 and 100 characters
- Price > 0
- Stock >= 0
```

---

### Template: Feature with Workflow

```
I want a workflow for [PROCESS]:

Possible states:
- State 1
- State 2
- State 3

Transitions:
- State 1 → State 2 (when: [condition], who: [role])
- State 2 → State 3 (when: [condition], who: [role])

Business rules:
- [rule 1]
- [rule 2]

Notifications:
- Email when [event]
```

**Concrete example**:
```
I want a workflow for Orders:

Possible states:
- Pending (awaiting)
- Paid (paid)
- Shipped (shipped)
- Delivered (delivered)
- Cancelled (cancelled)

Transitions:
- Pending → Paid (when: payment validated, automatic)
- Paid → Shipped (when: package sent, admin)
- Shipped → Delivered (when: delivery confirmed, admin)
- Pending → Cancelled (when: user cancels, user)
- Paid → Cancelled (when: admin refunds, admin)

Business rules:
- A Shipped order cannot be cancelled
- A Delivered order is final
- Cancellation < 24h is automatic, > 24h requires admin validation

Notifications:
- Email when order Paid
- Email when order Shipped (with tracking)
- Email when order Delivered
```

---

### Template: Feature with Relations

```
I want to manage [ENTITY A] and [ENTITY B] with:

Relations:
- [ENTITY A] [relation] [ENTITY B]
  (ex: A User has many Posts)

[ENTITY A]:
- [fields]

[ENTITY B]:
- [fields]

Actions:
- CRUD [ENTITY A]
- CRUD [ENTITY B]
- Link A to B
- Unlink A from B

Rules:
- [relation constraints]
```

**Concrete example**:
```
I want to manage Teams and Members with:

Relations:
- A Member can belong to multiple Teams
- A Team has multiple Members
- A Member has a role per Team (Admin, Manager, Member)

Team:
- Name (unique)
- Description
- CreatedAt

Member:
- User (relation to User)
- Team (relation to Team)
- Role (enum: Admin, Manager, Member)
- JoinedAt

Actions:
- Create team
- Invite member (by email)
- Accept invitation
- Remove member
- Change role

Rules:
- There must be at least 1 Admin per team
- An Admin cannot remove themselves if they're the only Admin
- Invitations expire after 7 days
```

---

## 🔄 Complete Workflow: From Idea to Code

### Step 1: Prepare the Feature

**Example**: Notification System

```markdown
# Feature: Notification System

## User Story
As a user,
I want to receive notifications,
So that I'm informed of important events.

## Acceptance Criteria
- [ ] User can see their notifications
- [ ] Notifications can be read/unread
- [ ] User can mark as read
- [ ] User sees unread count
- [ ] Notifications are real-time

## Notification Types
- New follower
- New comment
- New like
- Mention
- Private message

## Details
- Storage: Database
- Real-time: WebSocket (optional for Rapid)
- Retention: 30 days
```

---

### Step 2: Ask Skills

**In Claude Code**, simply type:

```
I want to create a notification system with:

Types:
- New follower
- New comment
- New like
- Mention
- Private message

Features:
- View all notifications (with pagination)
- Mark as read
- Mark all as read
- Delete notification
- Unread counter

Data:
- Notification type
- Message
- Link to related resource
- Read/Unread
- Created date

Rules:
- Notifications > 30 days are auto-deleted
- Max 100 notifications per user
- Real-time with WebSocket (if Balanced+)
```

---

### Step 3: Skills Generates the Code

**You'll see in real-time**:

```
🔍 Auto-detection...
  Level: balanced
  Platform: web

🏗️  Phase 1/4: Architecture

Designing 3-layer architecture for notifications...

Router Layer:
  - notificationRouter.list()
  - notificationRouter.markAsRead()
  - notificationRouter.markAllAsRead()
  - notificationRouter.delete()
  - notificationRouter.getUnreadCount()

Service Layer:
  - notificationService.create()
  - notificationService.list()
  - notificationService.markAsRead()
  - notificationService.cleanup()

Repository Layer:
  - notificationRepository (Prisma)

WebSocket:
  - notificationEmitter (real-time)

Creating ADR-043: Notification System Architecture

✅ Architecture complete

---

👨‍💻 Phase 2/4: Implementation

Creating files...
  ✅ packages/api/routers/notification.ts (22 lines)
  ✅ packages/services/notification.service.ts (48 lines)
  ✅ packages/database/repositories/notification.repository.ts (35 lines)
  ✅ packages/validators/notification.validator.ts (15 lines)
  ✅ packages/websocket/notification-emitter.ts (28 lines)

Validating code quality...
  ✅ Function length: All < 50 lines
  ✅ Parameters: All ≤ 3
  ✅ No violations

✅ Implementation complete

---

🧪 Phase 3/4: Testing

Writing tests...
  ✅ notificationService.create() - 5 tests
  ✅ notificationService.list() - 8 tests
  ✅ notificationService.markAsRead() - 3 tests
  ✅ notificationRouter tests - 10 tests

Running tests...
  ✅ 26 tests passing

Coverage: 74% (required: 70%)

✅ Tests complete

---

👀 Phase 4/4: Review

Validating...
  ✅ Code quality (all rules respected)
  ✅ Architecture (clean 3-layer separation)
  ✅ Tests (74% coverage)
  ✅ Type safety (all typed)
  ✅ Security (user isolation OK)

✅ Feature ready! 🎉

Summary:
  📊 5 files created
  📝 1 ADR documented
  🧪 26 tests written
  ✅ All validations passed

Time: ~4 minutes
```

---

### Step 4: Verify and Test

**Useful commands**:

```bash
# Check code quality
/validate

# Check architecture
/guard

# Check coverage
/coverage

# Run tests
pnpm test

# Run app
pnpm dev
```

---

## 💡 Tips for Better Features

### ✅ DO: Best Practices

1. **Be specific about data**
```
✅ "Price in cents (integer), min 0, max 1000000"
❌ "A price"
```

2. **Describe business rules**
```
✅ "A user can only like a post once"
❌ "Like system"
```

3. **Mention error cases**
```
✅ "If email already exists, return clear error"
❌ "Create a user"
```

4. **Specify permissions**
```
✅ "Only author or admin can delete"
❌ "Delete a post"
```

5. **Give data examples**
```
✅ "Status: draft | published | archived"
❌ "A status"
```

---

### ❌ DON'T: Avoid

1. **Too vague descriptions**
```
❌ "I want a blog"
✅ "I want a blog system with posts, categories, tags and comments"
```

2. **Forgetting validations**
```
❌ "An email field"
✅ "An email field (validated, unique, required)"
```

3. **Ignoring security**
```
❌ "List users"
✅ "List users (admins only)"
```

4. **Not mentioning relations**
```
❌ "Posts and comments"
✅ "A post has many comments, a comment belongs to a post"
```

---

## 📊 Feature Examples by Domain

### E-Commerce

```
1. Product Catalog
"I want to manage products with name, description, price, images, stock, categories"

2. Shopping Cart
"I want a cart with add/remove products, quantity, total calculation, session persistence"

3. Checkout
"I want a checkout process with shipping address, Stripe payment, confirmation email"

4. Orders
"I want to manage orders with states (pending, paid, shipped, delivered), history"

5. Wishlist
"I want a wishlist where users can save products"
```

---

### B2B SaaS

```
1. Organizations/Teams
"I want organizations with members, roles (owner, admin, member), invitations"

2. Subscriptions
"I want plans (starter, pro, enterprise) with limits per plan, Stripe billing"

3. Usage Tracking
"I want to track usage per organization (API calls, storage, users) with quotas"

4. Billing
"I want to manage invoices with PDF generation, history, download"

5. SSO/SAML
"I want SSO authentication for enterprises (Google Workspace, Microsoft 365)"
```

---

### Social Network

```
1. Profiles
"I want user profiles with photo, bio, followers/following"

2. Posts
"I want to publish posts with text, images, likes, comments, shares"

3. Feed
"I want a personalized feed with posts from followed users, infinite pagination"

4. Notifications
"I want real-time notifications for likes, comments, follows, mentions"

5. Private Messages
"I want a 1-to-1 messaging system with real-time, history, read/unread"
```

---

## 🎓 Practical Exercises

### Exercise 1: Basic Feature (5 min)

**Goal**: Create a tag system

**Description**:
```
I want to manage tags for articles with:

Tag:
- Name (unique, required, 3-30 characters)
- Color (hex color, optional)
- Slug (auto-generated from name)

Actions:
- Create tag
- List tags
- Update tag
- Delete tag (if not used)

Validation:
- Unique name
- No special characters
- Auto-generated slug (lowercase, hyphens)

Relations:
- An article can have multiple tags
- A tag can be on multiple articles
```

---

### Exercise 2: Medium Feature (10 min)

**Goal**: Comment system

**Description**:
```
I want a comment system on posts with:

Comment:
- Content (text, required, max 1000 chars)
- Author (User relation)
- Post (Post relation)
- Parent (optional, for replies)
- CreatedAt, UpdatedAt

Features:
- Add comment
- Reply to comment (nested)
- Edit own comment (< 15 min after creation)
- Delete own comment (soft delete)
- List comments (threaded, pagination)

Permissions:
- Anyone can comment (if authenticated)
- Only author can edit/delete
- Post author can delete any comment
- Admins can delete everything

Validation:
- Non-empty content
- Max 1000 characters
- No spam (max 10 comments/hour per user)

Rules:
- Replies limited to 3 levels depth
- Deleted comment shows "[deleted]"
- Comment counter includes replies
```

---

## 📚 Resources and Next Steps

### Documentation

- **QUICKSTART.md**: 5-minute quick guide
- **TUTORIAL.md**: 6 detailed tutorials
- **README.md**: Complete skills reference
- **TESTING-GUIDE.md**: How to test
- **VIDEO-DEMO-SCRIPT.md**: Demo video script

### Useful Commands

```bash
# Create new project
crafted clone

# Install skills (existing project)
crafted install-skills

# Validate code
/validate

# Check architecture
/guard

# Check tests
/coverage

# Help
/help
```

### Available Skills

**Workflows** (to create features):
- `/feature` - Create complete feature
- `/bugfix` - Fix a bug
- `/refactor` - Refactor code
- `/security` - Security review

**Agents** (for specific tasks):
- `/architect` - Design only
- `/developer` - Code only
- `/tester` - Tests only
- `/reviewer` - Review only

**Utilities** (quick validations):
- `/validate` - Code quality
- `/guard` - Architecture
- `/coverage` - Tests

---

## 🎯 Final Checklist: Are You Ready?

Before creating your first feature, check:

- [ ] You have a Crafted project with skills installed
- [ ] You know the project level (rapid/balanced/crafted)
- [ ] You read at least one complete example
- [ ] You prepared your feature description
- [ ] You know what data is needed
- [ ] You defined validation rules
- [ ] You thought about permissions
- [ ] You're ready to launch `/feature`!

---

## 🚀 Your Turn!

**Your first feature**:

1. Open Claude Code in your project
2. Think of a simple feature (ex: like system)
3. Describe it following the templates
4. Type your description
5. Watch Skills work!

**Ultra-simple example to start**:
```
I want to add a like system for posts.

A user can:
- Like a post (only once)
- Unlike a post
- See like count

Rules:
- A user can only like once per post
- Like counter updates in real-time
```

**That's it!** Skills will generate architecture, code, tests and validate everything.

---

## 💪 You Are Now an AI-Augmented PO

With Crafted Skills, you can:

✅ Create features in minutes
✅ Guarantee code quality (tests, architecture)
✅ Adapt quality level to your needs
✅ Iterate quickly
✅ Deliver production-ready code

**Skills transforms your ideas into code. You keep control.**

---

**Questions?**
- Problems: `.claude/skills/TESTING-GUIDE.md`
- Examples: `.claude/skills/TUTORIAL.md`
- Reference: `.claude/skills/README.md`
- Issues: https://github.com/crafted-saas/issues

**Happy building! 🚀**
