AI Workflow

Guide for AI agents working with Knowns CLI

3 min read

AI Workflow

This guide establishes protocols for AI assistants (Claude, GPT, Gemini, etc.) working with Knowns.

Core Principles

1. CLI-Only Operations

Never edit .md files directly. All modifications must use CLI commands:

# Correct
knowns task edit 42 --check-ac 1
 
# Wrong - Never do this
# Edit .knowns/tasks/task-42.md directly

2. Documentation First

Always read docs before coding. Understand patterns and architecture:

knowns doc list --plain
knowns doc view "patterns/auth" --plain
knowns doc view "architecture" --plain

3. Plain Text Output

Always use --plain flag for machine-readable results:

knowns task list --plain
knowns task view 42 --plain
knowns search "auth" --plain

Workflow Steps

1. Session Initialization

When starting a new session:

# List all documentation
knowns doc list --plain
 
# Read essential docs
knowns doc view "README" --plain
knowns doc view "ARCHITECTURE" --plain
knowns doc view "CONVENTIONS" --plain
 
# Check current task backlog
knowns task list --plain

2. Take a Task

# View task details
knowns task view 42 --plain
 
# Take the task
knowns task edit 42 -s in-progress -a @me
 
# Start timer
knowns time start 42

3. Follow References

Resolve all @doc/... and @task-... references in the task:

# If task mentions @doc/patterns/auth
knowns doc view "patterns/auth" --plain
 
# If task mentions @task-15
knowns task view 15 --plain

4. Create Implementation Plan

knowns task edit 42 --plan $'1. Research existing patterns
2. Design solution
3. Implement changes
4. Add tests
5. Update documentation'

Wait for user approval before coding.

5. Execute with Progress Updates

# Check off criteria as you complete them
knowns task edit 42 --check-ac 1
knowns task edit 42 --append-notes "✓ Implemented auth middleware"
 
knowns task edit 42 --check-ac 2
knowns task edit 42 --append-notes "✓ Added unit tests"

6. Complete the Task

# Add final implementation notes
knowns task edit 42 --notes $'## Summary
Implemented JWT authentication.
 
## Changes
- Added auth middleware
- Created token utilities
- Added 12 unit tests
 
## Files Modified
- src/middleware/auth.ts
- src/utils/jwt.ts'
 
# Stop timer and mark done
knowns time stop
knowns task edit 42 -s done

Context Checklist

Before writing any code, verify:

Read all referenced @doc/... documents
Read all referenced @task-... tasks
Understand project architecture
Know coding conventions
Identified reusable patterns/utilities

Common Mistakes

Wrong	Right
Edit .md files directly	Use `knowns task edit`
Skip reading docs	Read ALL related docs first
Code before plan approval	Wait for approval
Forget `--plain` flag	Always use `--plain`
Mark done without all criteria	Check ALL criteria first

Agent Instruction Sync

Keep AI instructions updated:

knowns agents

This updates:

CLAUDE.md for Claude Code
GEMINI.md for Gemini
.github/copilot-instructions.md for Copilot