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:
// 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 |
|
doc edit |
--append |
# ❌ 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 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