> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fliiq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Playbooks & Personas

> Domain-specific instructions and specialized agent personas

Playbooks are domain-specific instructions that load into the agent's system prompt when the task matches a domain. While [SOUL.md](/guides/identity) defines WHO the agent is, playbooks define HOW it approaches specific types of work.

**Personas** are the user-facing way to activate a playbook — use `--persona` to start a session with a specialized mindset.

## Personas

Use the `--persona` flag to run Fliiq as a specialized agent:

```bash theme={null}
fliiq run "write a PRD for user onboarding" --persona product-manager
fliiq run "build a responsive nav component" --persona frontend
fliiq --persona product-manager           # REPL in PM mode
fliiq tui --persona frontend              # TUI in frontend mode
fliiq plan "refactor auth" --persona frontend
```

The persona stays active for the entire session (REPL/TUI) or the single-shot command.

### Built-in Personas

Fliiq ships with four personas:

| Persona             | Flag                        | Best for                                                                              |
| ------------------- | --------------------------- | ------------------------------------------------------------------------------------- |
| **Coding**          | `--persona coding`          | Architecture, refactoring, debugging, engineering standards                           |
| **Product Manager** | `--persona product-manager` | PRDs, user stories, sprint planning, prioritization, stakeholder communication        |
| **Frontend**        | `--persona frontend`        | Component architecture, accessibility, responsive design, performance, visual quality |
| **Blog SEO**        | `--persona blog-seo`        | Content marketing, SEO-optimized blog posts, editorial standards, keyword targeting   |

```bash theme={null}
fliiq playbook list                       # List all personas/playbooks
fliiq playbook show product-manager       # View a persona's full instructions
fliiq playbook show blog-seo              # View the blog SEO playbook
```

## Auto-Detection

When no `--persona` flag is given, Fliiq automatically detects which playbook to load based on keywords in your prompt. If 2+ keywords match a playbook, it activates.

**Examples:**

```bash theme={null}
# Contains "sprint" + "user story" → loads product-manager
fliiq run "help me plan this sprint with user stories"

# Contains "react" + "responsive" → loads frontend
fliiq run "build a responsive react dashboard"

# Contains "refactor" + "api" → loads coding
fliiq run "refactor the API endpoints"
```

## Creating Custom Personas

```bash theme={null}
fliiq playbook create devops
```

This scaffolds `.fliiq/playbooks/devops.md` from a template. Edit the file to add your instructions.

### Keywords

The `# Keywords:` line defines when the playbook activates automatically:

```markdown theme={null}
# Keywords: devops, deploy, kubernetes, terraform, infrastructure, ci/cd
```

When 2+ of these keywords appear in your prompt, the playbook loads. You can also activate it explicitly with `--persona devops`.

### Content

The rest of the file is free-form markdown instructions the agent follows:

```markdown theme={null}
# Keywords: devops, deploy, kubernetes, terraform, infrastructure, ci/cd

## Deployment Standards

- Always use blue-green deployments
- Never deploy to production on Fridays
- Run health checks after every deployment
- Use terraform plan before terraform apply

## Kubernetes Conventions

- Use namespaces for environment isolation
- Set resource limits on all pods
- Use ConfigMaps for non-sensitive config, Secrets for credentials
```

## Playbooks in Jobs

Scheduled jobs can load a playbook directly via the `playbook:` field in job YAML. This lets a job run with specialized domain instructions without requiring a `--persona` flag at the command line:

```yaml theme={null}
name: daily-blog-draft
trigger:
  type: cron
  schedule: "0 8 * * 1"   # Monday 8am
prompt: "Draft a blog post on the queued topic from content-calendar.md"
playbook: blog-seo
skills:
  - read_file
  - write_file
  - memory_read
delivery:
  type: telegram
  to: "your-chat-id"
```

Any bundled or custom playbook name works. The playbook loads into the job's system prompt the same way `--persona` does in interactive mode.

## Playbook Resolution

| Source  | Location             | Priority |
| ------- | -------------------- | -------- |
| Custom  | `.fliiq/playbooks/`  | Highest  |
| Bundled | Package `playbooks/` | Fallback |

Custom playbooks with the same name override bundled ones. Custom playbooks with new names are additive.