AI IDE Core Concepts: Agents, Commands, Skills, Rules, Context, and Workflows

┌─────────────────┐
│    Developer    │
│      (User)     │
└────────┬────────┘
         │ Assigns Task
         ▼
┌─────────────────────────────────────────────────────────┐
│                   Agent Manager                         │
└─────────────┬─────────────────────────────────┬─────────┘
              │                                 │
    ┌─────────┼─────────┐              Spawns   │
    │         │         │                       │
    ▼         ▼         ▼                       │
┌────────┐ ┌────────┐ ┌────────┐                │
│ Agent 1│ │ Agent 2│ │ Agent 3│ <──────────────┘
└───┬────┘ └───┬────┘ └───┬────┘
    │ Uses     │ Uses     │ Uses
    │          │          │
    └──────────┼──────────┘
               │
               ▼
    ┌──────────────────────┐
    │       Tools          │
    └──────────┬───────────┘
               │
    ┌──────────┼───────────┬──────────────┐
    │          │           │              │
    ▼          ▼           ▼              ▼
┌────────┐ ┌──────────┐ ┌─────────┐ ┌─────────┐
│File    │ │ Terminal │ │ Browser │ │  Git    │
│System  │ │          │ │         │ │         │
└────────┘ └──────────┘ └─────────┘ └─────────┘

# Start an agent with a specific task
kiro agent start "Build user authentication API"

# Run multiple agents in parallel
kiro agent-manager start "Build full-stack feature"

Use Flow by describing your task:
"Fix the failing tests in the auth module"

Flow will:
1. Run tests
2. Analyze failures
3. Examine code
4. Apply fixes
5. Re-run tests

/spec "Build a task management API"
→ Creates detailed specification with endpoints, data models, and validation rules

/skill docker-expert
→ Loads Docker expertise for containerization tasks

/mode architect
→ Switches to architecture planning mode

Cmd + K → Open composer for multi-file edits
@codebase → Search entire codebase for context
@file → Reference specific file
@docs → Reference documentation

// .kiro/commands.json
{
  "commands": {
    "deploy": {
      "description": "Deploy to staging",
      "steps": [
        "Run tests",
        "Build Docker image",
        "Push to registry",
        "Update Kubernetes deployment"
      ]
    }
  }
}

┌─────────────────────────────────────────┐
│           Skill Package                 │
├─────────────────────────────────────────┤
│                                         │
│  ┌───────────────────────────────────┐  │
│  │ Metadata                          │  │
│  │ • Name, Version, Description      │  │
│  └───────────────────────────────────┘  │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │ Rules                             │  │
│  │ • Coding standards, Patterns      │  │
│  └───────────────────────────────────┘  │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │ Tools                             │  │
│  │ • Commands, APIs, Scripts         │  │
│  └───────────────────────────────────┘  │
│                                         │
│  ┌───────────────────────────────────┐  │
│  │ Examples                          │  │
│  │ • Code samples, Templates         │  │
│  └───────────────────────────────────┘  │
│                                         │
└─────────────────────────────────────────┘

skills/
├── docker-expert/
│   ├── skill.md          # Skill definition
│   ├── rules/
│   │   ├── dockerfile.md
│   │   └── compose.md
│   ├── examples/
│   │   ├── basic.Dockerfile
│   │   └── multi-stage.Dockerfile
│   └── tools/
│       └── lint.sh

# Docker Expert Skill

## Description
Provides expertise in Docker containerization, multi-stage builds, and security best practices.

## Rules
1. Always use multi-stage builds for production images
2. Never run containers as root
3. Use specific base image versions (no `latest`)
4. Minimize layers by combining RUN commands
5. Use `.dockerignore` to exclude unnecessary files

## Patterns

### Multi-stage Build Template

```dockerfile
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER node
CMD ["node", "dist/index.js"]

{
  "flow": {
    "skills": ["docker", "kubernetes", "security"]
  }
}

# Project Rules

## Code Style
- Use TypeScript for all new code
- Follow ESLint configuration
- Maximum function length: 50 lines
- Require JSDoc for public functions

## Architecture
- Use repository pattern for data access
- All API endpoints must have validation
- Implement error handling middleware

## Testing
- Minimum 80% code coverage
- Unit tests for all business logic
- Integration tests for API endpoints

## Security
- No hardcoded credentials
- Use environment variables for config
- Validate all user inputs

# Cursor Rules

## Always
- Write tests for new features
- Use meaningful variable names
- Add comments for complex logic

## Never
- Don't use `any` type in TypeScript
- Don't commit console.log statements
- Don't use deprecated APIs

## Prefer
- Prefer composition over inheritance
- Prefer async/await over promises
- Prefer functional components

// RULE: Always validate input before processing
// RULE: Use dependency injection for services
function createUser(userData: CreateUserDto) {
  // Implementation follows rules above
}

┌─────────────────────────────────┐
│     Global Rules                │
│     ~/.ai-rules.md              │
└───────────────┬─────────────────┘
                │
                ▼
┌─────────────────────────────────┐
│     Project Rules               │
│     .kiro/rules.md              │
└───────────────┬─────────────────┘
                │
                ▼
┌─────────────────────────────────┐
│     Language Rules              │
│     .kiro/rules/typescript.md   │
└───────────────┬─────────────────┘
                │
                ▼
┌─────────────────────────────────┐
│     File Rules                  │
│     Inline comments             │
└─────────────────────────────────┘

┌──────────────────┐
│  Your Codebase   │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│  Code Indexer    │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Vector Embeddings│
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│   Vector DB      │
│ (Qdrant/Chroma)  │
└────────┬─────────┘
         ▲
         │
┌────────┴─────────┐
│  Query Embedder  │
└────────┬─────────┘
         │
┌────────┴─────────┐
│    User Query    │
└──────────────────┘

         │
         ▼
┌──────────────────┐
│  Relevant Code   │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│    AI Agent      │
└──────────────────┘

{
  "indexing": {
    "enabled": true,
    "provider": "qdrant",
    "embeddings": "nomic-embed-text",
    "maxContextTokens": 100000
  }
}

{
  "cursor.indexing.enabled": true,
  "cursor.indexing.exclude": ["node_modules", "dist", ".git"]
}

┌───────────────────────┐
│ Define Requirements   │
└───────────┬───────────┘
            │
            ▼
┌───────────────────────┐
│ AI Creates            │
│ Specification         │
└───────────┬───────────┘
            │
            ▼
      ┌───────────┐
      │Review Spec│
      └─────┬─────┘
            │
    ┌───────┴───────┐
    │ Revise        │ Approve
    │ (back to      │
    │  spec)        │
    │               ▼
    │      ┌───────────────────────┐
    │      │ AI Implements Code    │
    │      └───────────┬───────────┘
    │                  │
    │                  ▼
    │      ┌───────────────────────┐
    │      │ AI Writes Tests       │
    │      └───────────┬───────────┘
    │                  │
    │                  ▼
    │           ┌───────────┐
    │           │Run Tests  │
    │           └─────┬─────┘
    │                 │
    │         ┌───────┴───────┐
    │         │ Fail          │ Pass
    │         │               │
    │         ▼               ▼
    │ ┌─────────────┐ ┌─────────────┐
    │ │ AI Debugs   │ │    Merge    │
    │ └──────┬──────┘ └─────────────┘
    │        │
    └────────┘

# Step 1: Create specification
/spec "Build user authentication API with JWT"

# Step 2: Review and approve spec
# (AI presents spec for review)

# Step 3: Implement
/implement

# Step 4: Test
/test

# Step 5: Review and merge

┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
│   Describe      │──>│  AI Writes      │──>│ Run Test        │──>│ AI Implements   │
│   Feature       │   │  Test           │   │ - Fails         │   │ Code            │
└─────────────────┘   └─────────────────┘   └─────────────────┘   └────────┬────────┘
                                                                           │
                                                                           ▼
┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐           │
│    Commit       │<──│  AI Refactors   │<──│ Run Test        │<──────────┘
└─────────────────┘   └─────────────────┘   │ - Passes        │
                                            └─────────────────┘

User: "I need a function that validates email addresses"

AI: I'll write a test first:

```typescript
describe('validateEmail', () => {
  it('should accept valid emails', () => {
    expect(validateEmail('test@example.com')).toBe(true);
  });
  
  it('should reject invalid emails', () => {
    expect(validateEmail('invalid')).toBe(false);
  });
});

1. AI reads error message
2. AI analyzes stack trace
3. AI searches codebase for related code
4. AI identifies potential causes
5. AI proposes fixes
6. AI applies fix and re-runs
7. AI documents the issue

{
  "modes": {
    "architect": {
      "description": "Plan and design before coding",
      "tools": ["spec", "diagram"],
      "autoApprove": false
    },
    "code": {
      "description": "Write and refactor code",
      "tools": ["edit", "create", "delete"],
      "autoApprove": false
    },
    "debug": {
      "description": "Investigate and fix issues",
      "tools": ["read", "run", "test"],
      "autoApprove": true
    },
    "test": {
      "description": "Write and run tests",
      "tools": ["test", "run"],
      "autoApprove": false
    }
  }
}

# API Development Workflow

## Trigger
When creating new API endpoints

## Steps

1. **Specification**
   - Define endpoint URL and method
   - Define request/response schema
   - Define authentication requirements

2. **Implementation**
   - Create route handler
   - Add validation middleware
   - Implement business logic
   - Add error handling

3. **Testing**
   - Unit tests for business logic
   - Integration tests for endpoint
   - Load test for performance

4. **Documentation**
   - Update OpenAPI spec
   - Add usage examples
   - Document error cases

5. **Review**
   - Security review
   - Performance review
   - Code style check

# 1. Load relevant skills
/skill docker-expert
/skill kubernetes-guru

# 2. Create specification
/spec "Add user profile picture upload with S3 storage"

# AI creates spec with:
# - API endpoints (POST /users/:id/avatar)
# - File validation (max 5MB, image types only)
# - S3 bucket configuration
# - CDN integration

# 3. Review and approve spec
# (Review artifacts in Agent Manager)

# 4. Switch to code mode
/mode code

# 5. Implement with context
@src/users @src/storage "Implement according to spec"

# 6. AI writes code following rules:
# - Uses TypeScript (global rule)
# - Follows repository pattern (project rule)
# - Includes validation (skill expertise)

# 7. Run tests
/test

# 8. AI debugs any failures
/debug "Fix failing tests"

# 9. Create Docker configuration
@skill docker-expert "Create production Dockerfile"

# 10. Deploy workflow
kiro agent start "Deploy to staging"

# Agent:
# - Builds Docker image
# - Pushes to registry
# - Updates Kubernetes deployment
# - Runs smoke tests
# - Reports success with artifacts