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.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
AI workflow
Chọn đúng flow cho loại việc sắp làm. Tất cả flow dưới đây giả định AI có thể dùng nhóm skill /kn-* khi runtime hỗ trợ.
Dùng tài liệu này khi cần quyết định: đi full spec-driven, task flow thường, hay quick fix.
Chọn flow
| Flow | Khi nào | Trình tự |
|---|---|---|
| Full SDD | feature lớn, hệ thống mới, thay đổi cross-cutting | init → research → spec → plan → implement → verify → extract |
| Normal | feature nhỏ, cải tiến, task đã rõ | init → plan → implement |
| Quick Fix | bug fix, hotfix, sửa nhỏ | init → implement |
Tại sao research trước spec?
AI cần đủ context trước khi viết spec để tránh draft sai yêu cầu.
Research trước khi:
- khu vực codebase còn lạ
- thay đổi liên quan tới pattern hoặc constraint sẵn có
- cần xem chức năng tương tự đang được làm thế nào
Full SDD flow
Dùng cho feature lớn hoặc thay đổi đáng có spec riêng.
1. Init session
/kn-init
Đọc project context, guidance, docs, trạng thái hiện tại.
2. Research
/kn-research
Gom đủ context từ codebase trước khi viết spec.
3. Tạo spec
/kn-spec user-auth
AI tạo spec document, thường gồm:
- overview và requirements
- acceptance criteria
- scenarios và edge cases
4. Plan từ spec
/kn-plan --from @doc/specs/user-auth
AI tách spec thành tasks, map ngược về spec AC.
5. Implement
/kn-implement 42
AI đọc task, follow linked docs/specs, rồi implement.
6. Verify
/kn-verify
Check:
- AC coverage
- reference integrity
- spec/task consistency
7. Extract
/kn-extract
Dùng khi implementation tạo ra pattern, decision, hoặc lesson đáng giữ lại.
Normal flow
Feature nhỏ, task đã có, vấn đề đã rõ.
/kn-init/kn-plan 42/kn-implement 42
Quick Fix flow
Bug fix, hotfix, sửa nhỏ.
/kn-init/kn-implement 42
Khi nào dùng kn-go
kn-go chạy toàn bộ pipeline liên tục, không chặn review giữa các giai đoạn.
Dùng khi:
- spec đã approved
- muốn task generation → planning → implementation → verification → commit prep chạy liền một mạch
- không cần review từng task trước khi code
Ưu tiên /kn-plan + /kn-implement khi:
- muốn xem kỹ từng task trước khi code
- spec vẫn đang thay đổi
- cần review checkpoints rõ ràng giữa các pha
Khi nào dùng kn-debug
Dùng khi bị block bởi lỗi thật sự, không phải thiếu plan.
Các case điển hình:
- build error, type error
- test fail
- runtime crash
- integration failure
- task bị block mà chưa rõ root cause
Nói ngắn: nếu bước tiếp theo hợp lý nhất là reproduce → diagnose → fix có hệ thống, thì chuyển sang kn-debug thay vì cứ tiếp tục implement.
Khi nào dùng kn-extract
Dùng khi vừa hoàn thành phần việc tạo ra thứ gì đó reusable, không nên để chôn trong một task hay chat session.
Các case điển hình:
- tìm ra implementation pattern lặp lại được
- chốt project-level decision mà các phần việc sau cần follow
- gặp failure mode mà cách nhận biết và fix nên được nhớ lại
- muốn chuyển ad-hoc knowledge thành docs, memory, hoặc template
Nên dùng gần cuối task hoặc sau verify, khi đã biết chắc kết quả đáng lưu.
Skill reference
| Skill | Mục đích |
|---|---|
/kn-init | Load project context |
/kn-research | Explore codebase và patterns |
/kn-spec | Tạo spec document |
/kn-plan | Tạo implementation plan |
/kn-implement | Thực hiện công việc |
/kn-verify | Check AC, refs, consistency |
/kn-extract | Lưu reusable knowledge |
/kn-doc | Làm việc với docs |
/kn-template | Chạy templates |
/kn-debug | Debug khi bị block hoặc fail |
CLI fallback
Nếu runtime không có skills, dùng CLI trực tiếp.
# Load context
knowns doc list --plain
knowns doc "readme" --plain --smart
# Nhận task
knowns task edit 42 -s in-progress -a @me
knowns time start 42
# Thêm plan
knowns task edit 42 --plan '1. Research\n2. Implement\n3. Test'
# Check AC và thêm notes
knowns task edit 42 --check-ac 1
knowns task edit 42 --append-notes "Completed feature X"
# Xong
knowns time stop
knowns task edit 42 -s done
Tách session khi cần
Với công việc lớn, nên tách session riêng theo task hoặc pha.
Ví dụ:
- một session cho research
- một session cho spec + planning
- một session cho implementation
Giảm nguy cơ context bị compact, mỗi session dễ kiểm soát hơn.
Khi nào coi là "xong"
Một task coi là done khi:
- AC đã check
- notes/implementation details đã ghi lại
- timer đã stop (nếu đang track time)
- validation/test đã pass
- task status đã update đúng