# AI Agent Guide

Protocols for AI agents working with Knowns

## Core Rules

### 1. CLI-Only Operations

**Never edit `.md` files directly.** All modifications must use CLI or MCP:

```
# ✅ Correct
knowns task edit 42 --check-ac 1

# ❌ Wrong - Never edit files directly
# Edit .knowns/tasks/task-42.md
```

### 2. Always Use `--plain`

Machine-readable output for all read operations:

```
knowns task list --plain
knowns task 42 --plain
knowns doc "README" --plain
knowns search "auth" --plain
```

**Note:**`--plain` is only for read commands (view, list, search). Not for create/edit.

### 3. Always Use `--smart` for Docs

Auto-handles both small and large documents:

```
knowns doc "README" --plain --smart
```

- **≤2000 tokens** → full content
- **>2000 tokens** → stats + TOC, then use `--section N`

### 4. MCP Preferred (v0.20 Consolidated Tools)

When MCP is available, use consolidated action-based tools:

```javascript
// MCP (preferred) - v0.20 consolidated format
tasks({ action: "get", taskId: "42" })
tasks({ action: "update", taskId: "42", checkAc: [1] })

// CLI (fallback)
knowns task 42 --plain
knowns task edit 42 --check-ac 1
```

## The `-a` Flag Warning

**CRITICAL:**`-a` means different things in different commands!

| Command | `-a` Means | NOT This |
| --- | --- | --- |
| `task create/edit` | `--assignee` | ~~acceptance criteria~~ |
| `doc edit` | `--append` | ~~assignee~~ |

```
# ❌ WRONG (sets assignee to garbage!)
knowns task edit 42 -a "Criterion text"

# ✅ CORRECT (use --ac)
knowns task edit 42 --ac "Criterion text"
```

## Workflow Selection

Choose based on task size:

| Flow | Use When | Command |
| --- | --- | --- |
| **Full SDD** | Large features | `/kn-init` → `/kn-spec` → `/kn-plan` → `/kn-implement` → `/kn-verify` |
| **Normal** | Small features | `/kn-init` → `/kn-plan` → `/kn-implement` |
| **Quick Fix** | Bug fixes | `/kn-init` → `/kn-implement` |

See [Workflow Guide](https://knowns.sh/docs/workflow) for details.

## Context Gathering

Before implementing, gather full context:

```
# 1. Read task
knowns task 42 --plain

# 2. Follow ALL references in task
# If task mentions @doc/patterns/auth:
knowns doc "patterns/auth" --plain --smart

# If task mentions @task-15:
knowns task 15 --plain

# If task has spec: field:
knowns doc "specs/user-auth" --plain --smart

# 3. Search for related docs
knowns search "auth" --type doc --plain
```

### Context Checklist

Before writing code, verify:

- [ ] Read all `@doc/...` references
- [ ] Read all `@task-...` references
- [ ] Read linked spec (if `spec:` field exists)
- [ ] Understand project architecture
- [ ] Know coding conventions

## SDD Integration

### Task-Spec Linking

Tasks can link to specs via `spec:` field:

```
---
id: task-42
title: Implement login
spec: specs/user-auth # Links to @doc/specs/user-auth
---
```

### AC Auto-Sync

When you check an AC on a task linked to a spec, the matching AC in the spec is automatically updated.

```
# This updates both task AC and spec AC
knowns task edit 42 --check-ac 1
```

### Verify Coverage

```
knowns validate --sdd
```

## Common Mistakes

| ❌ Wrong | ✅ Right |
| --- | --- |
| Edit .md files directly | Use CLI/MCP commands |
| `-a "criterion"` for AC | `--ac "criterion"` |
| Skip reading docs | Read ALL referenced docs |
| Code before plan approval | Wait for user approval |
| Forget `--plain` | Always use `--plain` for reads |
| Check AC before work done | Check AC AFTER completing work |
| Forget time tracking | `time start` → work → `time stop` |
| Use `notes` for updates | Use `appendNotes` for progress |

## MCP Tools Reference (v0.20 Consolidated)

| Tool | Key Actions |
| --- | --- |
| `project` | detect, set, current, status |
| `tasks` | list, get, create, update, delete, board |
| `docs` | list, get, create, update, delete |
| `memory` | add, get, list, update, delete, promote |
| `search` | search, retrieve, resolve |
| `time` | start, stop, add, report |
| `templates` | list, get, run, create |
| `code` | search, symbols, deps, graph |
| `validate` | Validate references, SDD coverage |

## Guidelines System

Get context-aware guidelines:

```
# Full guidelines
knowns agents guideline

# Compact (core rules only)
knowns agents guideline --compact

# Stage-specific
knowns agents guideline --stage execution
```

### Sync to AI Files

```
# Sync skills + instructions to platform dirs
knowns sync

# Sync skills only
knowns sync --skills

# Sync instructions only
knowns sync --instructions
```