AI Agent Guide
Protocols for AI agents working with Knowns
AI Agent Guide
Protocols and rules for AI assistants working with Knowns CLI and MCP.
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.md2. 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" --plainNote: --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
When MCP is available, use it instead of CLI:
// MCP (preferred)
mcp__knowns__get_task({ taskId: "42" })
mcp__knowns__update_task({ taskId: "42", checkAc: [1] })
// CLI (fallback)
knowns task 42 --plain
knowns task edit 42 --check-ac 1The -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 --plainContext 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 1Verify Coverage
knowns validate --sddCommon 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 |
MCP Tools Reference
| Tool | Purpose |
|---|---|
get_task | Read task details |
update_task | Update task (status, ACs, notes) |
list_tasks | List/filter tasks |
get_doc | Read document |
update_doc | Update document |
search | Search tasks and docs |
start_time / stop_time | Time tracking |
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 executionSync to AI Files
# Update CLAUDE.md, AGENTS.md
knowns agents sync
# Minimal version
knowns agents sync --minimal