@autonomos/cli 0.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,16 @@
+
+> @autonomos/cli@0.0.1 build /home/runner/work/autonomos/autonomos/packages/cli
+> tsdown
+
+ℹ tsdown v0.18.4 powered by rolldown v1.0.0-beta.57
+ℹ config file: /home/runner/work/autonomos/autonomos/packages/cli/tsdown.config.ts 
+ℹ entry: src/index.ts
+ℹ tsconfig: tsconfig.json
+ℹ Build start
+ℹ Granting execute permission to dist/index.mjs
+ℹ dist/index.mjs    9.19 kB │ gzip: 3.35 kB
+ℹ dist/index.d.mts  0.01 kB │ gzip: 0.03 kB
+ℹ 2 files, total: 9.20 kB
+✔ Build complete in 1088ms
+✔ [publint] No issues found (342ms)
+🙏 Build succeeded!

package/AGENT.md

@@ -0,0 +1,11 @@
+# AGENT CONTEXT: @autonomos/cli
+
+## 🧠 Context & Objectives
+
+This package is the public-facing tool for the Agent Protocol.
+It consumes `@autonomos/core` to perform actions like bootstrapping projects (`init`), updating docs, or parsing tasks.
+
+## ⚙️ Workflow
+
+- **Dependencies:** Uses `commander` for CLI args.
+- **Linkage:** Depends on `workspace:@autonomos/core`.

package/LICENSE

@@ -0,0 +1,11 @@
+MIT License
+
+Copyright (c) 2026 Hakim Saoudi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+The Software may include icons that are licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). Commercial use is allowed, but attribution is required for the use of these icons. See LICENSE-THIRD-PARTY for more details.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @autonomos/cli
+
+A command-line interface for managing the Autonomos Agent Protocol.
+
+## Installation
+
+```bash
+# Locally in your project
+pnpm add -D @autonomos/cli
+
+# Or globally
+pnpm add -g @autonomos/cli
+```
+
+## Commands
+
+### `init`
+
+Initialize the Agent Protocol in the current directory.
+
+```bash
+autonomos init
+autonomos init --dry-run
+```
+
+### `update`
+
+Update the project's Protocol to the latest version embedded in the CLI.
+
+```bash
+autonomos update
+```
+
+### `status`
+
+Show project status and a summary of tasks from `TASKS.md`.
+
+```bash
+autonomos status
+```
+
+### `agents`
+
+List all `AGENT.md` files in the project.
+
+```bash
+autonomos agents        # Search from current directory
+autonomos agents --all  # Search from project root
+```
+
+### `version`
+
+Show current CLI and Protocol versions.
+
+```bash
+autonomos --version
+```
+
+## How it works
+
+The CLI manages the `.autonomos/` directory in your project, which contains:
+
+- `manifest.json`: Protocol metadata and versioning.
+- `PROTOCOL.md`: The immutable protocol specification.
+- `TASKS.md`: Your project's task registry.
+- `worklogs/`: Directory for session logs.
+
+It also creates a root `AGENT.md` file if it doesn't exist, which serves as the primary context for AI agents.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/index.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import{Command as e}from"commander";import t from"picocolors";import{AGENT_FILE as n,AUTONOMOS_DIR as r,MANIFEST_FILE as i,PROTOCOL_FILE as a,PROTOCOL_TEMPLATE as o,PROTOCOL_VERSION as s,TASKS_FILE as c,TASKS_TEMPLATE as l,TaskParser as u,WORKLOGS_DIR as d,createManifest as f,generateAgentTemplate as p,generateManifestContent as m,parseManifest as h}from"@autonomos/core";import{existsSync as g,mkdirSync as _,readFileSync as v,readdirSync as y,statSync as b,writeFileSync as x}from"node:fs";import{basename as S,join as C,relative as w}from"node:path";function T(e){let t=e;for(;t!==`/`;){if(g(C(t,r))||g(C(t,`.git`)))return t;t=C(t,`..`)}return null}function E(e,t,r=0){let i=[],a=C(e,n);g(a)&&i.push({path:a,relativePath:w(t,a)||n,depth:r});try{let n=y(e);for(let a of n){if(a.startsWith(`.`)||a===`node_modules`||a===`dist`||a===`build`)continue;let n=C(e,a);try{b(n).isDirectory()&&i.push(...E(n,t,r+1))}catch{}}}catch{}return i}function D(e,t){if(e.length===0)return`  (no AGENT.md files found)`;let n=[],r=S(t);n.push(`📁 ${r}/`);for(let t=0;t<e.length;t++){let r=e[t],i=t===e.length-1?`└── `:`├── `,a=`    `.repeat(r.depth);n.push(`${a}${i}📄 ${r.relativePath}`)}return n.join(`
+`)}function O(e={}){let t=e.cwd??process.cwd(),n;if(e.all){let e=T(t);if(!e)return{success:!1,message:`Could not find project root (.autonomos or .git directory).`};n=e}else n=t;let r=E(n,n);if(r.length===0)return{success:!0,message:`No AGENT.md files found.`,count:0};let i=D(r,n);return{success:!0,message:`Found ${r.length} AGENT.md file(s)`,tree:i,count:r.length}}function k(e={}){let t=e.cwd??process.cwd(),u=e.dryRun??!1,h=[],v=[];g(C(t,`.git`))||v.push("No Git repository detected. Consider running `git init` first.");let y=C(t,r);if(g(y))return{success:!1,message:`Project already initialized with Protocol v${s}. Use \`autonomos update\` to update.`,created:[],warnings:[],dryRun:u};if(u)return h.push(r),h.push(`${r}/${d}`),h.push(`${r}/${i}`),h.push(`${r}/${a}`),h.push(`${r}/${c}`),g(C(t,n))?v.push(`${n} already exists, would skip.`):h.push(n),{success:!0,message:`Would initialize project with Agent Protocol v${s}`,created:h,warnings:v,dryRun:!0};_(y,{recursive:!0}),h.push(r),_(C(y,d),{recursive:!0}),h.push(`${r}/${d}`);let b=f(`0.0.1`);x(C(y,i),m(b)),h.push(`${r}/${i}`),x(C(y,a),o),h.push(`${r}/${a}`),x(C(y,c),l),h.push(`${r}/${c}`);let S=C(t,n);return g(S)?v.push(`${n} already exists, skipping.`):(x(S,p(t.split(`/`).pop()??`Project`)),h.push(n)),{success:!0,message:`Project initialized with Agent Protocol v${s}`,created:h,warnings:v,dryRun:!1}}function A(e={}){let t=C(e.cwd??process.cwd(),r),n=C(t,i);if(!g(n))return{success:!1,message:"Project not initialized. Run `autonomos init` first.",initialized:!1};let a;try{a=h(v(n,`utf-8`))}catch{return{success:!1,message:`Could not read manifest.json`,initialized:!0}}let o,s=C(t,c);if(g(s))try{let e=v(s,`utf-8`),t=u.parse(e);o={total:t.length,todo:t.filter(e=>e.status===`TODO`).length,inProgress:t.filter(e=>e.status===`IN_PROGRESS`).length,done:t.filter(e=>e.status===`DONE`).length,blocked:t.filter(e=>e.status===`BLOCKED`).length}}catch{}return{success:!0,message:`Project status retrieved`,protocolVersion:a.protocolVersion,cliVersion:a.cliVersion,initialized:!0,taskSummary:o}}function j(e,t){let n=e.split(`.`).map(Number),r=t.split(`.`).map(Number);for(let e=0;e<3;e++){let t=n[e]??0,i=r[e]??0;if(t<i)return-1;if(t>i)return 1}return 0}function M(e={}){let t=C(e.cwd??process.cwd(),r),n=C(t,i);if(!g(n))return{success:!1,message:"Project not initialized. Run `autonomos init` first."};let c=h(v(n,`utf-8`)),l=c.protocolVersion,u=j(l,s);return u===0?{success:!0,message:`Already up to date (Protocol v${s})`,previousVersion:l,newVersion:s}:u>0?{success:!1,message:`This project uses Protocol v${l}, but your CLI only knows v${s}. Update your CLI with \`npm i -g @autonomos/cli\`.`,previousVersion:l,newVersion:s,cliOutdated:!0}:(x(C(t,a),o),x(n,m({...c,protocolVersion:s,cliVersion:`0.0.1`,lastUpdated:new Date().toISOString()})),{success:!0,message:`Protocol updated: v${l} → v${s}`,previousVersion:l,newVersion:s})}const N=`0.0.1`,P=new e;P.name(`autonomos`).description(t.cyan(`CLI for the Autonomos Agent Protocol
+
+The Agent Protocol is a specification for AI agents to interact with codebases
+in a structured, consistent way. It defines how agents should read context,
+execute tasks, and persist knowledge.`)+`
+
+Documentation: ${t.underline(`https://github.com/saoudi-h/autonomos`)}`).version(`${t.bold(`CLI:`)} ${t.green(N)}\n${t.bold(`Protocol:`)} ${t.green(s)}`,`-v, --version`,`Show version information`).helpOption(`-h, --help`,`Show help information`).addHelpText(`after`,`
+${t.bold(`Examples:`)}
+  $ ${t.cyan(`autonomos init`)}          Initialize the Agent Protocol in current directory
+  $ ${t.cyan(`autonomos update`)}        Update Protocol to the latest version
+  $ ${t.cyan(`autonomos status`)}        Show project status and task summary
+  $ ${t.cyan(`autonomos agents`)}        List all AGENT.md files in the project
+
+${t.bold(`More info:`)}
+  Run '${t.cyan(`autonomos <command> --help`)}' for detailed information about a command.
+`),P.command(`init`).description(`Initialize the Agent Protocol in the current directory`).addHelpText(`after`,`
+This command creates the following structure:
+  ${t.blue(`.autonomos/`)}
+  ├── ${t.white(`manifest.json`)}    # Protocol metadata and version
+  ├── ${t.white(`PROTOCOL.md`)}      # Immutable protocol specification
+  ├── ${t.white(`TASKS.md`)}         # Task registry
+  └── ${t.blue(`worklogs/`)}        # Session logs directory
+  ${t.white(`AGENT.md`)}             # Project context file (at root)
+
+${t.bold(`Examples:`)}
+  $ ${t.cyan(`autonomos init`)}
+  $ ${t.cyan(`cd my-project && autonomos init`)}
+`).option(`-n, --dry-run`,`Preview what would be created without writing files`).action(e=>{let n=k({dryRun:e.dryRun});n.success||(console.error(t.red(`\n❌ ${n.message}`)),process.exit(1)),n.dryRun?console.log(t.cyan(`\n🔍 ${n.message} (dry-run)`)):console.log(t.green(`\n✅ ${n.message}`)),n.created.length>0&&(console.log(`\n${t.bold(n.dryRun?`Would create:`:`Created:`)}`),n.created.forEach(e=>console.log(`  ${t.blue(`📄`)} ${t.white(e)}`))),n.warnings.length>0&&(console.log(t.yellow(`
+Warnings:`)),n.warnings.forEach(e=>console.log(`  ${t.yellow(`⚠️`)}  ${e}`)))}),P.command(`update`).description(`Update the Protocol to the latest version`).addHelpText(`after`,`
+This command updates ${t.white(`PROTOCOL.md`)} to the latest version embedded in the CLI.
+Only ${t.white(`PROTOCOL.md`)} is modified; your ${t.white(`TASKS.md`)} and ${t.white(`AGENT.md`)} files are preserved.
+
+${t.bold(`Version comparison:`)}
+  - If your project has an older version: Updates to the new version
+  - If your project has a newer version: Warns you to update the CLI
+  - If versions match: No action needed
+
+${t.bold(`Examples:`)}
+  $ ${t.cyan(`autonomos update`)}
+`).action(()=>{let e=M();e.success||(e.cliOutdated?console.error(t.yellow(`\n⚠️  ${e.message}`)):console.error(t.red(`\n❌ ${e.message}`)),process.exit(1)),console.log(t.green(`\n✅ ${e.message}`))}),P.command(`status`).description(`Show project status and task summary`).addHelpText(`after`,`
+Displays information about the current project:
+  - Protocol version
+  - CLI version used for initialization
+  - Task summary (todo, in-progress, done, blocked)
+
+${t.bold(`Examples:`)}
+  $ ${t.cyan(`autonomos status`)}
+`).action(()=>{let e=A();if(e.success||(console.error(t.red(`\n❌ ${e.message}`)),process.exit(1)),console.log(`\n${t.bold(`📦 Protocol`)} ${t.green(`v${e.protocolVersion}`)} ${t.dim(`(CLI v${e.cliVersion})`)}`),e.taskSummary){let n=e.taskSummary;console.log(`\n${t.bold(`📋 Tasks:`)} ${t.cyan(n.total)} total`),console.log(`   ${t.white(`⬜ Todo:`)} ${t.white(n.todo)}`),console.log(`   ${t.blue(`🔄 In Progress:`)} ${t.blue(n.inProgress)}`),console.log(`   ${t.green(`✅ Done:`)} ${t.green(n.done)}`),n.blocked>0&&console.log(`   ${t.red(`🚫 Blocked:`)} ${t.red(n.blocked)}`)}}),P.command(`agents`).description(`List all AGENT.md files in the project`).option(`-a, --all`,`Search from project root instead of current directory`).addHelpText(`after`,`
+This command discovers and displays all ${t.white(`AGENT.md`)} files in a tree structure.
+${t.white(`AGENT.md`)} files provide context to AI agents about specific directories.
+
+${t.bold(`Modes:`)}
+  (default)   Search from current directory downwards
+  --all       Search from project root (finds .autonomos or .git)
+
+${t.bold(`Examples:`)}
+  $ ${t.cyan(`autonomos agents`)}           # List from current directory
+  $ ${t.cyan(`autonomos agents --all`)}     # List from project root
+  $ ${t.cyan(`cd packages/core && autonomos agents`)}  # List only in packages/core
+`).action(e=>{let n=O({all:e.all});n.success||(console.error(t.red(`\n❌ ${n.message}`)),process.exit(1)),console.log(`
+`+(n.tree??n.message)),console.log(t.dim(`\n${n.message}`))}),P.command(`version`).description(`Show the current Protocol version`).action(()=>{console.log(`${t.bold(`Agent Protocol`)} ${t.green(`v${s}`)} ${t.dim(`(CLI v${N})`)}`)}),P.parse();export{};

package/eslint.config.ts

@@ -0,0 +1,18 @@
+import type { Config } from '@repo/eslint'
+import { base } from '@repo/eslint'
+import { defineConfig } from 'eslint/config'
+
+const config: Config[] = defineConfig([
+    ...base,
+    {
+        ignores: [
+            'eslint.config.ts',
+            'eslint-types.d.ts',
+            'prettier.config.mjs',
+            'lint-staged.config.mjs',
+            'lowercase-script.ts',
+        ],
+    },
+])
+
+export default config

package/lint-staged.config.mjs

@@ -0,0 +1,4 @@
+export default {
+    '**/*.{ts,tsx}': ['prettier --write', 'eslint --fix --no-warn-ignored'],
+    '**/*.{json,md,mdx}': 'prettier --write',
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@autonomos/cli",
+  "version": "0.0.1",
+  "description": "CLI tool for the Autonomos Agent Protocol",
+  "type": "module",
+  "bin": {
+    "autonomos": "./dist/index.mjs"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "picocolors": "1.1.1",
+    "@autonomos/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.0.0",
+    "@repo/eslint": "1.0.0",
+    "@repo/prettier": "1.0.0",
+    "@repo/tsdown": "1.0.0"
+  },
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "scripts": {
+    "start": "node dist/index.mjs",
+    "build": "tsdown",
+    "lint": "eslint . --max-warnings 0",
+    "lint:fix": "eslint . --max-warnings 0 --fix",
+    "format:check": "prettier \"**/*\" --ignore-unknown --list-different",
+    "format:fix": "prettier \"**/*\" --ignore-unknown --write",
+    "clean": "rimraf node_modules dist",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:run": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "pre-commit": "lint-staged"
+  }
+}

package/prettier.config.mjs

@@ -0,0 +1,3 @@
+import baseConfig from '@repo/prettier'
+
+export default baseConfig

package/src/commands/agents.ts

@@ -0,0 +1,154 @@
+import { existsSync, readdirSync, statSync } from 'node:fs'
+import { basename, join, relative } from 'node:path'
+
+import { AGENT_FILE, AUTONOMOS_DIR } from '@autonomos/core'
+
+interface AgentsOptions {
+    cwd?: string
+    all?: boolean
+}
+
+interface AgentEntry {
+    path: string
+    relativePath: string
+    depth: number
+}
+
+/**
+ * Find the project root by looking for .autonomos or .git directory
+ */
+function findProjectRoot(startDir: string): string | null {
+    let currentDir = startDir
+
+    while (currentDir !== '/') {
+        if (existsSync(join(currentDir, AUTONOMOS_DIR)) || existsSync(join(currentDir, '.git'))) {
+            return currentDir
+        }
+        currentDir = join(currentDir, '..')
+    }
+
+    return null
+}
+
+/**
+ * Recursively find all AGENT.md files in a directory
+ */
+function findAgentFiles(dir: string, baseDir: string, depth = 0): AgentEntry[] {
+    const entries: AgentEntry[] = []
+
+    // Check if AGENT.md exists in current directory
+    const agentPath = join(dir, AGENT_FILE)
+    if (existsSync(agentPath)) {
+        entries.push({
+            path: agentPath,
+            relativePath: relative(baseDir, agentPath) || AGENT_FILE,
+            depth,
+        })
+    }
+
+    // Scan subdirectories
+    try {
+        const items = readdirSync(dir)
+        for (const item of items) {
+            // Skip hidden directories and node_modules
+            if (
+                item.startsWith('.') ||
+                item === 'node_modules' ||
+                item === 'dist' ||
+                item === 'build'
+            ) {
+                continue
+            }
+
+            const itemPath = join(dir, item)
+            try {
+                if (statSync(itemPath).isDirectory()) {
+                    entries.push(...findAgentFiles(itemPath, baseDir, depth + 1))
+                }
+            } catch {
+                // Skip inaccessible directories
+            }
+        }
+    } catch {
+        // Skip inaccessible directories
+    }
+
+    return entries
+}
+
+/**
+ * Format agent entries as a tree structure
+ */
+function formatAsTree(entries: AgentEntry[], baseDir: string): string {
+    if (entries.length === 0) {
+        return '  (no AGENT.md files found)'
+    }
+
+    const lines: string[] = []
+    const baseName = basename(baseDir)
+
+    lines.push(`📁 ${baseName}/`)
+
+    // Group entries by their parent directory
+    for (let i = 0; i < entries.length; i++) {
+        const entry = entries[i]
+        const isLast = i === entries.length - 1
+        const prefix = isLast ? '└── ' : '├── '
+        const indent = '    '.repeat(entry.depth)
+
+        lines.push(`${indent}${prefix}📄 ${entry.relativePath}`)
+    }
+
+    return lines.join('\n')
+}
+
+interface AgentsResult {
+    success: boolean
+    message: string
+    tree?: string
+    count?: number
+}
+
+/**
+ * List all AGENT.md files in the project
+ */
+export function agents(options: AgentsOptions = {}): AgentsResult {
+    const cwd = options.cwd ?? process.cwd()
+
+    // Determine search base
+    let searchBase: string
+
+    if (options.all) {
+        // Find project root
+        const projectRoot = findProjectRoot(cwd)
+        if (!projectRoot) {
+            return {
+                success: false,
+                message: 'Could not find project root (.autonomos or .git directory).',
+            }
+        }
+        searchBase = projectRoot
+    } else {
+        searchBase = cwd
+    }
+
+    // Find all AGENT.md files
+    const entries = findAgentFiles(searchBase, searchBase)
+
+    if (entries.length === 0) {
+        return {
+            success: true,
+            message: 'No AGENT.md files found.',
+            count: 0,
+        }
+    }
+
+    const tree = formatAsTree(entries, searchBase)
+
+    return {
+        success: true,
+        message: `Found ${entries.length} AGENT.md file(s)`,
+        tree,
+        count: entries.length,
+    }
+}

package/src/commands/init.ts

@@ -0,0 +1,128 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+    AGENT_FILE,
+    AUTONOMOS_DIR,
+    createManifest,
+    generateAgentTemplate,
+    generateManifestContent,
+    MANIFEST_FILE,
+    PROTOCOL_FILE,
+    PROTOCOL_TEMPLATE,
+    PROTOCOL_VERSION,
+    TASKS_FILE,
+    TASKS_TEMPLATE,
+    WORKLOGS_DIR,
+} from '@autonomos/core'
+
+// Get CLI version from package.json
+const CLI_VERSION = '0.0.1' // TODO: Import from package.json
+
+interface InitOptions {
+    cwd?: string
+    dryRun?: boolean
+}
+
+interface InitResult {
+    success: boolean
+    message: string
+    created: string[]
+    warnings: string[]
+    dryRun?: boolean
+}
+
+/**
+ * Initialize the Autonomos Agent Protocol in a directory
+ */
+export function init(options: InitOptions = {}): InitResult {
+    const cwd = options.cwd ?? process.cwd()
+    const dryRun = options.dryRun ?? false
+    const created: string[] = []
+    const warnings: string[] = []
+
+    // Check for .git
+    const gitDir = join(cwd, '.git')
+    if (!existsSync(gitDir)) {
+        warnings.push('No Git repository detected. Consider running `git init` first.')
+    }
+
+    // Check if already initialized
+    const autonomosDir = join(cwd, AUTONOMOS_DIR)
+    if (existsSync(autonomosDir)) {
+        return {
+            success: false,
+            message: `Project already initialized with Protocol v${PROTOCOL_VERSION}. Use \`autonomos update\` to update.`,
+            created: [],
+            warnings: [],
+            dryRun,
+        }
+    }
+
+    // In dry-run mode, just collect what would be created
+    if (dryRun) {
+        created.push(AUTONOMOS_DIR)
+        created.push(`${AUTONOMOS_DIR}/${WORKLOGS_DIR}`)
+        created.push(`${AUTONOMOS_DIR}/${MANIFEST_FILE}`)
+        created.push(`${AUTONOMOS_DIR}/${PROTOCOL_FILE}`)
+        created.push(`${AUTONOMOS_DIR}/${TASKS_FILE}`)
+
+        const agentPath = join(cwd, AGENT_FILE)
+        if (!existsSync(agentPath)) {
+            created.push(AGENT_FILE)
+        } else {
+            warnings.push(`${AGENT_FILE} already exists, would skip.`)
+        }
+
+        return {
+            success: true,
+            message: `Would initialize project with Agent Protocol v${PROTOCOL_VERSION}`,
+            created,
+            warnings,
+            dryRun: true,
+        }
+    }
+
+    // Create .autonomos directory
+    mkdirSync(autonomosDir, { recursive: true })
+    created.push(AUTONOMOS_DIR)
+
+    // Create worklogs directory
+    const worklogsDir = join(autonomosDir, WORKLOGS_DIR)
+    mkdirSync(worklogsDir, { recursive: true })
+    created.push(`${AUTONOMOS_DIR}/${WORKLOGS_DIR}`)
+
+    // Create manifest.json
+    const manifest = createManifest(CLI_VERSION)
+    const manifestPath = join(autonomosDir, MANIFEST_FILE)
+    writeFileSync(manifestPath, generateManifestContent(manifest))
+    created.push(`${AUTONOMOS_DIR}/${MANIFEST_FILE}`)
+
+    // Create PROTOCOL.md
+    const protocolPath = join(autonomosDir, PROTOCOL_FILE)
+    writeFileSync(protocolPath, PROTOCOL_TEMPLATE)
+    created.push(`${AUTONOMOS_DIR}/${PROTOCOL_FILE}`)
+
+    // Create TASKS.md
+    const tasksPath = join(autonomosDir, TASKS_FILE)
+    writeFileSync(tasksPath, TASKS_TEMPLATE)
+    created.push(`${AUTONOMOS_DIR}/${TASKS_FILE}`)
+
+    // Create AGENT.md at root (only if it doesn't exist)
+    const agentPath = join(cwd, AGENT_FILE)
+    if (!existsSync(agentPath)) {
+        const projectName = cwd.split('/').pop() ?? 'Project'
+        writeFileSync(agentPath, generateAgentTemplate(projectName))
+        created.push(AGENT_FILE)
+    } else {
+        warnings.push(`${AGENT_FILE} already exists, skipping.`)
+    }
+
+    return {
+        success: true,
+        message: `Project initialized with Agent Protocol v${PROTOCOL_VERSION}`,
+        created,
+        warnings,
+        dryRun: false,
+    }
+}

package/src/commands/status.ts

@@ -0,0 +1,94 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+    AUTONOMOS_DIR,
+    MANIFEST_FILE,
+    parseManifest,
+    TaskParser,
+    TASKS_FILE,
+    type Manifest,
+} from '@autonomos/core'
+
+interface StatusOptions {
+    cwd?: string
+}
+
+interface TaskSummary {
+    total: number
+    todo: number
+    inProgress: number
+    done: number
+    blocked: number
+}
+
+interface StatusResult {
+    success: boolean
+    message: string
+    protocolVersion?: string
+    cliVersion?: string
+    initialized: boolean
+    taskSummary?: TaskSummary
+}
+
+/**
+ * Get project status and task summary
+ */
+export function status(options: StatusOptions = {}): StatusResult {
+    const cwd = options.cwd ?? process.cwd()
+
+    // Check if initialized
+    const autonomosDir = join(cwd, AUTONOMOS_DIR)
+    const manifestPath = join(autonomosDir, MANIFEST_FILE)
+
+    if (!existsSync(manifestPath)) {
+        return {
+            success: false,
+            message: 'Project not initialized. Run `autonomos init` first.',
+            initialized: false,
+        }
+    }
+
+    // Read manifest
+    let manifest: Manifest
+    try {
+        const manifestContent = readFileSync(manifestPath, 'utf-8')
+        manifest = parseManifest(manifestContent)
+    } catch {
+        return {
+            success: false,
+            message: 'Could not read manifest.json',
+            initialized: true,
+        }
+    }
+
+    // Parse tasks
+    let taskSummary: TaskSummary | undefined
+    const tasksPath = join(autonomosDir, TASKS_FILE)
+
+    if (existsSync(tasksPath)) {
+        try {
+            const tasksContent = readFileSync(tasksPath, 'utf-8')
+            const tasks = TaskParser.parse(tasksContent)
+
+            taskSummary = {
+                total: tasks.length,
+                todo: tasks.filter(t => t.status === 'TODO').length,
+                inProgress: tasks.filter(t => t.status === 'IN_PROGRESS').length,
+                done: tasks.filter(t => t.status === 'DONE').length,
+                blocked: tasks.filter(t => t.status === 'BLOCKED').length,
+            }
+        } catch {
+            // Tasks file exists but couldn't be parsed
+        }
+    }
+
+    return {
+        success: true,
+        message: 'Project status retrieved',
+        protocolVersion: manifest.protocolVersion,
+        cliVersion: manifest.cliVersion,
+        initialized: true,
+        taskSummary,
+    }
+}

package/src/commands/update.ts

@@ -0,0 +1,111 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+import {
+    AUTONOMOS_DIR,
+    generateManifestContent,
+    MANIFEST_FILE,
+    parseManifest,
+    PROTOCOL_FILE,
+    PROTOCOL_TEMPLATE,
+    PROTOCOL_VERSION,
+    type Manifest,
+} from '@autonomos/core'
+
+// Get CLI version from package.json
+const CLI_VERSION = '0.0.1' // TODO: Import from package.json
+
+interface UpdateOptions {
+    cwd?: string
+}
+
+interface UpdateResult {
+    success: boolean
+    message: string
+    previousVersion?: string
+    newVersion?: string
+    cliOutdated?: boolean
+}
+
+/**
+ * Compare two SemVer versions
+ * Returns: -1 if a < b, 0 if a === b, 1 if a > b
+ */
+function compareVersions(a: string, b: string): number {
+    const aParts = a.split('.').map(Number)
+    const bParts = b.split('.').map(Number)
+
+    for (let i = 0; i < 3; i++) {
+        const aNum = aParts[i] ?? 0
+        const bNum = bParts[i] ?? 0
+        if (aNum < bNum) return -1
+        if (aNum > bNum) return 1
+    }
+    return 0
+}
+
+/**
+ * Update the Protocol to the latest version
+ */
+export function update(options: UpdateOptions = {}): UpdateResult {
+    const cwd = options.cwd ?? process.cwd()
+
+    // Check if initialized
+    const autonomosDir = join(cwd, AUTONOMOS_DIR)
+    const manifestPath = join(autonomosDir, MANIFEST_FILE)
+
+    if (!existsSync(manifestPath)) {
+        return {
+            success: false,
+            message: 'Project not initialized. Run `autonomos init` first.',
+        }
+    }
+
+    // Read current manifest
+    const manifestContent = readFileSync(manifestPath, 'utf-8')
+    const manifest: Manifest = parseManifest(manifestContent)
+    const currentVersion = manifest.protocolVersion
+
+    // Compare versions
+    const comparison = compareVersions(currentVersion, PROTOCOL_VERSION)
+
+    if (comparison === 0) {
+        return {
+            success: true,
+            message: `Already up to date (Protocol v${PROTOCOL_VERSION})`,
+            previousVersion: currentVersion,
+            newVersion: PROTOCOL_VERSION,
+        }
+    }
+
+    if (comparison > 0) {
+        // Project uses a newer version than CLI knows
+        return {
+            success: false,
+            message: `This project uses Protocol v${currentVersion}, but your CLI only knows v${PROTOCOL_VERSION}. Update your CLI with \`npm i -g @autonomos/cli\`.`,
+            previousVersion: currentVersion,
+            newVersion: PROTOCOL_VERSION,
+            cliOutdated: true,
+        }
+    }
+
+    // Update Protocol (comparison < 0)
+    const protocolPath = join(autonomosDir, PROTOCOL_FILE)
+    writeFileSync(protocolPath, PROTOCOL_TEMPLATE)
+
+    // Update manifest
+    const updatedManifest: Manifest = {
+        ...manifest,
+        protocolVersion: PROTOCOL_VERSION,
+        cliVersion: CLI_VERSION,
+        lastUpdated: new Date().toISOString(),
+    }
+    writeFileSync(manifestPath, generateManifestContent(updatedManifest))
+
+    return {
+        success: true,
+        message: `Protocol updated: v${currentVersion} → v${PROTOCOL_VERSION}`,
+        previousVersion: currentVersion,
+        newVersion: PROTOCOL_VERSION,
+    }
+}

package/src/index.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+import { Command } from 'commander'
+import pc from 'picocolors'
+
+import { PROTOCOL_VERSION } from '@autonomos/core'
+import { agents } from './commands/agents'
+import { init } from './commands/init'
+import { status } from './commands/status'
+import { update } from './commands/update'
+
+const CLI_VERSION = '0.0.1'
+
+const program = new Command()
+
+program
+    .name('autonomos')
+    .description(
+        pc.cyan(`CLI for the Autonomos Agent Protocol
+
+The Agent Protocol is a specification for AI agents to interact with codebases
+in a structured, consistent way. It defines how agents should read context,
+execute tasks, and persist knowledge.`) +
+            `
+
+Documentation: ${pc.underline('https://github.com/saoudi-h/autonomos')}`
+    )
+    .version(
+        `${pc.bold('CLI:')} ${pc.green(CLI_VERSION)}\n${pc.bold('Protocol:')} ${pc.green(PROTOCOL_VERSION)}`,
+        '-v, --version',
+        'Show version information'
+    )
+    .helpOption('-h, --help', 'Show help information')
+    .addHelpText(
+        'after',
+        `
+${pc.bold('Examples:')}
+  $ ${pc.cyan('autonomos init')}          Initialize the Agent Protocol in current directory
+  $ ${pc.cyan('autonomos update')}        Update Protocol to the latest version
+  $ ${pc.cyan('autonomos status')}        Show project status and task summary
+  $ ${pc.cyan('autonomos agents')}        List all AGENT.md files in the project
+
+${pc.bold('More info:')}
+  Run '${pc.cyan('autonomos <command> --help')}' for detailed information about a command.
+`
+    )
+
+program
+    .command('init')
+    .description('Initialize the Agent Protocol in the current directory')
+    .addHelpText(
+        'after',
+        `
+This command creates the following structure:
+  ${pc.blue('.autonomos/')}
+  ├── ${pc.white('manifest.json')}    # Protocol metadata and version
+  ├── ${pc.white('PROTOCOL.md')}      # Immutable protocol specification
+  ├── ${pc.white('TASKS.md')}         # Task registry
+  └── ${pc.blue('worklogs/')}        # Session logs directory
+  ${pc.white('AGENT.md')}             # Project context file (at root)
+
+${pc.bold('Examples:')}
+  $ ${pc.cyan('autonomos init')}
+  $ ${pc.cyan('cd my-project && autonomos init')}
+`
+    )
+    .option('-n, --dry-run', 'Preview what would be created without writing files')
+    .action(opts => {
+        const result = init({ dryRun: opts.dryRun })
+
+        if (!result.success) {
+            console.error(pc.red(`\n❌ ${result.message}`))
+            process.exit(1)
+        }
+
+        if (result.dryRun) {
+            console.log(pc.cyan(`\n🔍 ${result.message} (dry-run)`))
+        } else {
+            console.log(pc.green(`\n✅ ${result.message}`))
+        }
+
+        if (result.created.length > 0) {
+            console.log(`\n${pc.bold(result.dryRun ? 'Would create:' : 'Created:')}`)
+            result.created.forEach(file => console.log(`  ${pc.blue('📄')} ${pc.white(file)}`))
+        }
+
+        if (result.warnings.length > 0) {
+            console.log(pc.yellow('\nWarnings:'))
+            result.warnings.forEach(warn => console.log(`  ${pc.yellow('⚠️')}  ${warn}`))
+        }
+    })
+
+program
+    .command('update')
+    .description('Update the Protocol to the latest version')
+    .addHelpText(
+        'after',
+        `
+This command updates ${pc.white('PROTOCOL.md')} to the latest version embedded in the CLI.
+Only ${pc.white('PROTOCOL.md')} is modified; your ${pc.white('TASKS.md')} and ${pc.white('AGENT.md')} files are preserved.
+
+${pc.bold('Version comparison:')}
+  - If your project has an older version: Updates to the new version
+  - If your project has a newer version: Warns you to update the CLI
+  - If versions match: No action needed
+
+${pc.bold('Examples:')}
+  $ ${pc.cyan('autonomos update')}
+`
+    )
+    .action(() => {
+        const result = update()
+
+        if (!result.success) {
+            if (result.cliOutdated) {
+                console.error(pc.yellow(`\n⚠️  ${result.message}`))
+            } else {
+                console.error(pc.red(`\n❌ ${result.message}`))
+            }
+            process.exit(1)
+        }
+
+        console.log(pc.green(`\n✅ ${result.message}`))
+    })
+
+program
+    .command('status')
+    .description('Show project status and task summary')
+    .addHelpText(
+        'after',
+        `
+Displays information about the current project:
+  - Protocol version
+  - CLI version used for initialization
+  - Task summary (todo, in-progress, done, blocked)
+
+${pc.bold('Examples:')}
+  $ ${pc.cyan('autonomos status')}
+`
+    )
+    .action(() => {
+        const result = status()
+
+        if (!result.success) {
+            console.error(pc.red(`\n❌ ${result.message}`))
+            process.exit(1)
+        }
+
+        console.log(
+            `\n${pc.bold('📦 Protocol')} ${pc.green(`v${result.protocolVersion}`)} ${pc.dim(`(CLI v${result.cliVersion})`)}`
+        )
+
+        if (result.taskSummary) {
+            const s = result.taskSummary
+            console.log(`\n${pc.bold('📋 Tasks:')} ${pc.cyan(s.total)} total`)
+            console.log(`   ${pc.white('⬜ Todo:')} ${pc.white(s.todo)}`)
+            console.log(`   ${pc.blue('🔄 In Progress:')} ${pc.blue(s.inProgress)}`)
+            console.log(`   ${pc.green('✅ Done:')} ${pc.green(s.done)}`)
+            if (s.blocked > 0) {
+                console.log(`   ${pc.red('🚫 Blocked:')} ${pc.red(s.blocked)}`)
+            }
+        }
+    })
+
+program
+    .command('agents')
+    .description('List all AGENT.md files in the project')
+    .option('-a, --all', 'Search from project root instead of current directory')
+    .addHelpText(
+        'after',
+        `
+This command discovers and displays all ${pc.white('AGENT.md')} files in a tree structure.
+${pc.white('AGENT.md')} files provide context to AI agents about specific directories.
+
+${pc.bold('Modes:')}
+  (default)   Search from current directory downwards
+  --all       Search from project root (finds .autonomos or .git)
+
+${pc.bold('Examples:')}
+  $ ${pc.cyan('autonomos agents')}           # List from current directory
+  $ ${pc.cyan('autonomos agents --all')}     # List from project root
+  $ ${pc.cyan('cd packages/core && autonomos agents')}  # List only in packages/core
+`
+    )
+    .action(opts => {
+        const result = agents({ all: opts.all })
+
+        if (!result.success) {
+            console.error(pc.red(`\n❌ ${result.message}`))
+            process.exit(1)
+        }
+
+        console.log('\n' + (result.tree ?? result.message))
+        console.log(pc.dim(`\n${result.message}`))
+    })
+
+program
+    .command('version')
+    .description('Show the current Protocol version')
+    .action(() => {
+        console.log(
+            `${pc.bold('Agent Protocol')} ${pc.green(`v${PROTOCOL_VERSION}`)} ${pc.dim(`(CLI v${CLI_VERSION})`)}`
+        )
+    })
+
+program.parse()

package/tsconfig.json

@@ -0,0 +1,36 @@
+{
+    "extends": "@repo/tsconfig/base.json",
+    "compilerOptions": {
+        "target": "esnext",
+        "lib": ["es2022"],
+        "moduleDetection": "force",
+        "module": "esnext",
+        "moduleResolution": "bundler",
+        "resolveJsonModule": true,
+        "types": ["node", "vitest"],
+        "strict": true,
+        "noUnusedLocals": true,
+        "declaration": true,
+        "esModuleInterop": true,
+        "isolatedModules": true,
+        "verbatimModuleSyntax": true,
+        "skipLibCheck": true,
+        "baseUrl": ".",
+        "outDir": "./dist",
+        "rootDir": ".",
+        "paths": {
+            "@/*": ["src/*"],
+            "@tests/*": ["tests/*"]
+        }
+    },
+    "include": [
+        "./src/**/*",
+        "./src/**/*.json",
+        "tsdown.config.ts",
+        "vitest.config.ts",
+        "tests/**/*",
+        "lint-staged.config.mjs",
+        "prettier.config.mjs"
+    ],
+    "exclude": ["dist", "build", "node_modules", ".vscode", ".turbo", "coverage"]
+}

package/tsdown.config.ts

@@ -0,0 +1,10 @@
+import { base } from '@repo/tsdown'
+import type { UserConfigFn } from 'tsdown/config'
+import { defineConfig } from 'tsdown/config'
+
+const configFn: UserConfigFn = defineConfig(async options => ({
+    ...(await base(options, { ci: true })),
+    entry: ['./src/index.ts', './src/*/index.ts'],
+}))
+
+export default configFn

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { base } from '@repo/vitest'
+import type { ViteUserConfig } from 'vitest/config'
+import { defineConfig } from 'vitest/config'
+
+const config: ViteUserConfig = defineConfig({
+    ...base,
+})
+
+export default config