work CLI - Agent Guidelines

You are not rewarded for progress. You are rewarded for correctness under adversarial scrutiny.

Assume earlier conclusions are wrong until re‑proven with fresh evidence.

Project Overview

The work CLI is a unified, stateless command-line tool that bridges AI agents and task management systems (Jira, GitHub, Linear, Azure DevOps, local filesystem). It provides a consistent interface for managing work items across multiple backends without vendor lock-in.

Considerable effort has been invested in planning and designing this system to ensure robust architecture and clear implementation guidelines.

Core principles

Keep it simple

• Do not over engineer
• Keep it simple
• Keep core code and principles well tested

YAGNI

• Justify every line of code you write

Keep in mind that we are early in development and we do not have any users yet, so do not be afraid of breaking things. We also do not need complicated backwards compatibility since we are building core primitives first.

Project Structure

work-cli/
├── src/
│   ├── cli/           # Command parsing and CLI interface
│   ├── core/          # Core engine and graph logic
│   ├── adapters/      # Backend implementations
│   │   ├── local-fs/  # Local filesystem adapter
│   │   ├── jira/      # Jira adapter
│   │   ├── github/    # GitHub adapter
│   │   ├── linear/    # Linear adapter
│   │   └── ado/       # Azure DevOps adapter
│   ├── types/         # TypeScript type definitions
│   └── utils/         # Shared utilities
├── tests/             # Test files (unit/integration/e2e)
├── docs/              # Documentation
├── scripts/           # Build and development scripts
├── examples/          # Usage examples and sample configurations
├── dev/               # Intermediate and temporary files (gitignored)
└── .kiro/             # Kiro CLI configuration

Root Directory Rules

Keep the root directory clean. Only these files are allowed:

• package.json, package-lock.json - Node.js project files
• tsconfig.json - TypeScript configuration
• jest.config.js - Testing configuration
• eslint.config.js, .prettierrc - Code quality tools
• Makefile - Development commands
• README.md, AGENTS.md - Documentation
• .gitignore, .gitattributes - Git configuration
• LICENSE - Project license

All other files must be organized into appropriate subdirectories.

Temporary Development Files: Place todos, notes, scratch files, and other development artifacts in dev/ (gitignored). This keeps the root clean while preserving work-in-progress materials.

Code Quality Standards

TypeScript Standards

• Use strict mode with explicit types
• Never use any - prefer specific types or unknown
• Use camelCase for variables/functions, PascalCase for classes
• Enable all strict TypeScript compiler options

Code Structure

• Add JSDoc comments for all public APIs
• Implement explicit error handling with typed errors
• No silent failures - always handle or propagate errors
• Follow Prettier formatting (auto-applied)
• Use meaningful variable and function names

Language Constraints

FORBIDDEN WITHOUT EXHAUSTIVE PROOF:

• "most"
• "all"
• "nearly"
• "already"
• "looks complete"

To use these words, you MUST:

• show a complete enumeration
• show total count
• show zero unknowns

Tool Completeness Rule

TOOL COMPLETENESS RULE: Any tool with limits (max_files, pagination, sampling) MUST be looped until exhaustion.

If exhaustion is impossible:

• Declare the result INCOMPLETE
• Do NOT draw conclusions

Testing Requirements

• Write tests following 70/20/10 pyramid (unit/integration/e2e)
• Maintain >60% test coverage
• Mock external dependencies in unit tests
• Test files: *.test.ts or *.spec.ts
• Hard rule: after a coding session, before reporting back to the user run make ci to test the changes and fix issues until the test suite passes.

Security Practices

• Validate and sanitize all user inputs
• Never log sensitive data (credentials, tokens, PII)
• Never read credentials into context - always check existence only, pipe to secure storage, or redact values
• Use explicit error types without exposing internal details
• Implement proper credential isolation per context

Architecture Principles

• Stateless Execution: No daemon, no caching, ephemeral graph slices
• Adapter Pattern: Uniform interface for all backends
• CLI Framework: Use oclif for command parsing and help
• Separation of Concerns: CLI parses intent, core implements semantics

Performance Requirements

• List operations: <2s for up to 1,000 items
• CLI startup: <500ms
• Memory usage: <100MB per command
• Test coverage: >60%

File Naming Conventions

• TypeScript files: camelCase with .ts extension
• Test files: *.test.ts or *.spec.ts
• Configuration files: kebab-case
• Documentation: kebab-case with .md extension

Documentation Reference

Detailed technical documentation is available in docs/:

• README.md - Complete documentation index and overview
• work-cli-spec.md - Complete CLI specification and command reference
• work-adapter-architecture.md - Multi-backend support via adapter pattern
• work-graph-ontology-and-runtime.md - Internal graph model and stateless execution
• work-local-fs-execution-flow.md - Detailed execution flow for local filesystem backend
• work-c4-architecture.md - C4 architecture diagrams in PlantUML format
• work-configuration-overview.md - Configuration system and credential management
• work-user-journey-context-and-query.md - Concrete user journey demonstrating context and querying
• work-nonfunctional-requirements.md - Quality attributes and performance requirements
• work-cli-tech-selection.md - CLI technology selection and rationale
• work-poc.md - Proof of concept implementation plan

Product requirements and strategic vision:

• work-cli-unified-task-management.prd.md - Complete product requirements document with problem statement, solution architecture, and implementation phases