@autonomos/core 0.0.1 → 0.1.0

package/dist/workflows/protocol-crystallize.md

@@ -0,0 +1,48 @@
+---
+name: protocol-crystallize
+description: 'Mandatory close-out procedure for any session. Invoked before declaring the session done. Forces the agent to crystallize learnings into AGENT.md files.'
+---
+
+# Protocol Crystallize
+
+**Goal:** Convert session activity into durable project knowledge.
+**Your Role:** Reflective agent that improves the project for the next session.
+
+## STEP 0 — STOP
+
+DO NOT close the session before every step below is complete.
+
+## STEP 1 — Worklog
+
+Create or complete `.autonomos/worklogs/YYYY-MM-DD-[TASK_ID].md`. Free format, but MUST contain:
+
+- A summary of what was done
+- The technical decisions made and why
+- The files modified
+- Clear next steps (for the next session)
+
+## STEP 2 — Crystallize into AGENT.md files
+
+Ask yourself these three questions. For each, you MUST answer honestly. Do NOT say "nothing new".
+
+**Question 1:** `What did I learn of significance about this project during this session?` (preferences, constraints, discovered conventions, user corrections, etc.)
+
+If the answer is not `nothing`, write it to the relevant AGENT.md (root or subfolder). No format is imposed. One line is enough if it is clear.
+
+**Question 2:** `Has any AGENT.md entry been contradicted or superseded?` If yes, update the relevant AGENT.md entry **in place** — the file is a current-state document, not a changelog. Then record the change in the worklog of this session (e.g. `PREF-007: GSAP → Motion, superseded by PREF-009`). Do NOT append superseded entries to AGENT.md; do NOT keep both.
+
+**Question 3:** `Is there something in the worklog that should have been in an AGENT.md and is not yet?` If yes, lift it out of the worklog and put it in the AGENT.md.
+
+## STEP 3 — Task status
+
+Mark the task as `[x]` (or `[!]` if blocked) in `.autonomos/TASKS.md`.
+
+## STEP 4 — Final verification
+
+RESPOND to the user with:
+
+- `Task: [x] / [!] — [ID]`
+- `Worklog created: .autonomos/worklogs/...`
+- `AGENT.md updated: [yes / no, and why]`
+
+If you cannot produce these three lines, the session is not complete. Resume from Step 1.

package/dist/workflows/protocol-session.md

@@ -0,0 +1,50 @@
+---
+name: protocol-session
+description: 'Mandatory bootstrap for any new session on a project following the Autonomos protocol. Invoked at the start of every session, before any work begins.'
+---
+
+# Protocol Session
+
+**Goal:** Load all project context, identify the next task, and establish a clean working state.
+**Your Role:** Disciplined agent that respects the project's accumulated knowledge.
+
+## STEP 0 — STOP
+
+You are starting a new session. You MUST complete Steps 1, 2, and 3 before any other action.
+
+DO NOT skip steps. DO NOT begin work before Step 3 is complete.
+
+## STEP 1 — Load context (three mandatory reads)
+
+1. Read the root `AGENT.md`. This is your project identity.
+2. Run `autonomos agents` (no argument) to get the **full tree of all AGENT.md files in the project**. Read each one. This is your full fractal context — it lets you discover shared packages, cross-cutting conventions, and traps before starting any work.
+3. Read the most recent file in `.autonomos/worklogs/`. This is the memory of the previous session — read it to avoid repeating the same mistakes.
+
+RESPOND to the user with a 5-line maximum summary of what you have retained. You are FORBIDDEN to continue without this response.
+
+## STEP 2 — Identify the next task
+
+Open `.autonomos/TASKS.md`. Identify the highest-priority task that is not yet `[x]`. If none qualify, ask the user what to work on.
+
+RESPOND with: `Task selected: [ID] — [title]. Starting.`
+
+## STEP 3 — Mark the task and begin
+
+- Edit `.autonomos/TASKS.md` to change this task's status from `[ ]` to `[/]`.
+- NOW you may begin working.
+
+## REMINDER — applies to the entire session
+
+- **RAPPEL 1:** For every non-trivial decision (library choice, naming, structure, framework), STOP and ask: "Does an AGENT.md say something about this?" If yes, apply it. If no, propose the decision to the user.
+- **RAPPEL 2:** Every time you learn something important (the user corrects you, you discover a convention, you make a technical choice), STOP. Write it immediately to an AGENT.md (root or subfolder, depending on scope). Do NOT say "I'll note it later". It is NOW.
+- **RAPPEL 3:** No format is imposed on AGENT.md content. One line is enough if it's clear. What matters is that the next session can use it.
+
+## FINAL STEP (MANDATORY before saying "session done")
+
+You CANNOT end a session without all three of the following. DO NOT say "done" until each box is checked.
+
+- [ ] Task status in TASKS.md is `[x]` (or `[!]` if blocked)
+- [ ] A worklog exists at `.autonomos/worklogs/YYYY-MM-DD-[TASK_ID].md` containing: what was done, decisions made, files modified, and clear next steps
+- [ ] You have asked the user the following question and recorded the answer in the worklog: `What did this session learn about this project that deserves to live in an AGENT.md?`
+
+When all three boxes are checked, you may say `session complete`.

package/dist/workflows/protocol-task.md

@@ -0,0 +1,37 @@
+---
+name: protocol-task
+description: 'Mandatory procedure for starting a new task within an active session. Invoked at task start, before any code is touched.'
+---
+
+# Protocol Task
+
+**Goal:** Confirm context, declare intent, and avoid scope drift.
+**Your Role:** Disciplined agent that respects local conventions.
+
+## STEP 0 — STOP
+
+You are about to begin a new task. DO NOT touch code before the end of Step 2.
+
+## STEP 1 — Build the precise fractal context for this task
+
+1. Run `autonomos agents <path-to-target-file-or-folder>` to get the **ordered list of ancestor AGENT.md files** for the file or folder you'll be working in. The output is root-first; non-existent ancestors are silently skipped.
+2. Read each returned AGENT.md **in order** (root → target). This is your precise fractal context for this task.
+3. If no local `AGENT.md` exists at the target AND you have worked in that folder multiple times before, propose to the user: `This folder has no AGENT.md yet. Should we create one to crystallize the conventions we have established here?`
+
+## STEP 2 — Declare the plan
+
+State in 3 to 5 steps what you intend to do for this task. No more. The user must be able to say `OK` or adjust before you begin.
+
+## STEP 3 — Execute
+
+Mark the task `[/]` in TASKS.md, then execute your plan.
+
+## DURING EXECUTION — three reminders
+
+- **REMINDER 1:** For every non-trivial decision, consult the relevant AGENT.md.
+- **REMINDER 2:** For every new learning, append a new line to an AGENT.md. If the new learning contradicts an existing one, replace the old entry in place and log the change in the worklog. AGENT.md stays a sharp current-state document, not a log.
+- **REMINDER 3:** You may edit any AGENT.md at any time. No format is imposed. What matters is that the next session can use it.
+
+## END OF TASK
+
+When the task is complete, mark it `[x]` in TASKS.md and invoke the `protocol-crystallize` workflow.

package/package.json

@@ -1,27 +1,46 @@
 {
   "name": "@autonomos/core",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "SDK and core definitions for the Agent Protocol",
   "type": "module",
-  "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "keywords": [
     "agent",
     "protocol",
     "ai",
-    "workflow"
+    "workflow",
+    "ai-agent",
+    "mcp",
+    "autonomy"
   ],
   "author": "Autonomos",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saoudi-h/autonomos.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/saoudi-h/autonomos/issues"
+  },
+  "homepage": "https://github.com/saoudi-h/autonomos/tree/main/packages/core#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
   "devDependencies": {
+    "@tala-tools/eslint": "0.1.3",
+    "@tala-tools/prettier": "0.0.3",
+    "@tala-tools/tsconfig": "0.0.1",
+    "@tala-tools/tsdown": "0.1.3",
     "@types/js-yaml": "4.0.9",
     "typescript": "^5.0.0",
-    "@repo/eslint": "1.0.0",
-    "@repo/prettier": "1.0.0",
-    "@repo/tsdown": "1.0.0",
     "@repo/vitest": "1.0.0"
   },
-  "module": "./dist/index.mjs",
   "exports": {
     ".": "./dist/index.mjs",
     "./package.json": "./package.json"
@@ -32,13 +51,13 @@
   },
   "scripts": {
     "dev": "tsdown --watch",
-    "build": "tsdown",
+    "build": "tsdown && cp ../../LICENSE .",
     "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",
+    "clean": "rimraf node_modules dist LICENSE",
+    "typecheck": "tsgo --noEmit",
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:run": "vitest run",

package/.turbo/turbo-build.log

@@ -1,15 +0,0 @@
-
-> @autonomos/core@0.0.1 build /home/runner/work/autonomos/autonomos/packages/core
-> tsdown
-
-ℹ tsdown v0.18.4 powered by rolldown v1.0.0-beta.57
-ℹ config file: /home/runner/work/autonomos/autonomos/packages/core/tsdown.config.ts 
-ℹ entry: src/index.ts
-ℹ tsconfig: tsconfig.json
-ℹ Build start
-ℹ dist/index.mjs     9.78 kB │ gzip: 4.19 kB
-ℹ dist/index.d.mts  17.09 kB │ gzip: 4.28 kB
-ℹ 2 files, total: 26.88 kB
-✔ Build complete in 1302ms
-✔ [publint] No issues found (329ms)
-🙏 Build succeeded!

package/eslint.config.ts

@@ -1,18 +0,0 @@
-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',
-            'tsdown.config.ts',
-        ],
-    },
-])
-
-export default config

package/lint-staged.config.mjs

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

package/prettier.config.mjs

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

package/src/constants.ts

@@ -1,35 +0,0 @@
-/**
- * Protocol version using SemVer
- * Alpha phase - not yet published to npm
- */
-export const PROTOCOL_VERSION = '0.1.0-alpha'
-
-/**
- * Directory name for Autonomos configuration
- */
-export const AUTONOMOS_DIR = '.autonomos'
-
-/**
- * Manifest filename
- */
-export const MANIFEST_FILE = 'manifest.json'
-
-/**
- * Protocol filename
- */
-export const PROTOCOL_FILE = 'PROTOCOL.md'
-
-/**
- * Tasks filename
- */
-export const TASKS_FILE = 'TASKS.md'
-
-/**
- * Agent context filename (at project root)
- */
-export const AGENT_FILE = 'AGENT.md'
-
-/**
- * Worklogs directory name
- */
-export const WORKLOGS_DIR = 'worklogs'

package/src/index.ts

@@ -1,17 +0,0 @@
-// Constants
-export * from './constants'
-export * from './schemas/manifest'
-
-// Types
-export * from './types'
-
-// Templates
-export * from './templates/agent'
-export * from './templates/manifest'
-export * from './templates/protocol'
-export * from './templates/tasks'
-export * from './templates/worklog'
-
-// Parsers
-export * from './parsers/agent-parser'
-export * from './parsers/task-parser'

package/src/parsers/agent-parser.test.ts

@@ -1,61 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { AgentParser } from './agent-parser'
-
-describe('AgentParser', () => {
-    it('should parse an AGENT.md with standard title correctly', () => {
-        const markdown = '# AGENT CONTEXT: My Project\n\n## Section 1\nHello'
-        const context = AgentParser.parse(markdown)
-        expect(context.title).toBe('My Project')
-        expect(context.sections).toHaveLength(1)
-        expect(context.sections[0]!.title).toBe('Section 1')
-        expect(context.sections[0]!.content).toBe('Hello')
-    })
-
-    it('should parse multiple sections correctly', () => {
-        const markdown = `
-# AGENT CONTEXT: Test
-## Context & Objectives
-Objective 1
-## Workflow & Preferences
-Strict Linting
-        `
-        const context = AgentParser.parse(markdown)
-        expect(context.sections).toHaveLength(2)
-        expect(context.sections[0]!.title).toBe('Context & Objectives')
-        expect(context.sections[0]!.content).toBe('Objective 1')
-        expect(context.sections[1]!.title).toBe('Workflow & Preferences')
-        expect(context.sections[1]!.content).toBe('Strict Linting')
-    })
-
-    it('should handle alternative title format', () => {
-        const markdown = '# Simple Title\n## Content'
-        const context = AgentParser.parse(markdown)
-        expect(context.title).toBe('Simple Title')
-    })
-
-    it('should parse YAML frontmatter correctly', () => {
-        const markdown = `---
-name: "Advanced Agent"
-stack: ["React", "Node"]
-status: "Active"
----
-# AGENT CONTEXT: Should ignore H1 if name exists
-## Section 1
-Content`
-        const context = AgentParser.parse(markdown)
-        expect(context.title).toBe('Advanced Agent')
-        expect(context.metadata).toEqual({
-            name: 'Advanced Agent',
-            stack: ['React', 'Node'],
-            status: 'Active',
-        })
-        expect(context.sections).toHaveLength(1)
-        expect(context.sections[0]!.title).toBe('Section 1')
-    })
-
-    it('should return default title if missing', () => {
-        const markdown = '## No Title'
-        const context = AgentParser.parse(markdown)
-        expect(context.title).toBe('Unknown Agent')
-    })
-})

package/src/parsers/agent-parser.ts

@@ -1,80 +0,0 @@
-import yaml from 'js-yaml'
-import type { AgentContext, AgentSection } from '../types'
-
-export class AgentParser {
-    /**
-     * Parse an AGENT.md content into a structured AgentContext
-     */
-    static parse(markdown: string): AgentContext {
-        let content = markdown
-        let metadata: Record<string, any> = {}
-
-        // Parse Frontmatter
-        const frontmatterRegex = /^---\r?\n([\s\S]*?)\r?\n---/
-        const match = markdown.match(frontmatterRegex)
-        if (match) {
-            try {
-                metadata = yaml.load(match[1] as string) as Record<string, any>
-                content = markdown.slice(match[0].length).trim()
-            } catch (e) {
-                console.error('Failed to parse Agent frontmatter:', e)
-            }
-        }
-
-        const lines = content.split(/\r?\n/)
-        const sections: AgentSection[] = []
-        let title = metadata.name ?? 'Unknown Agent'
-        let currentSection: AgentSection | null = null
-        let currentContent: string[] = []
-
-        for (const line of lines) {
-            // Parse Title (Only if not already set by frontmatter)
-            if (line.startsWith('# ') && !metadata.name) {
-                const rawTitle = line.replace('# ', '').trim()
-                // Handle "AGENT CONTEXT: [Name]" format
-                if (rawTitle.toUpperCase().startsWith('AGENT CONTEXT:')) {
-                    title = rawTitle
-                        .slice(14)
-                        .replace(/^[:\s-]+/, '')
-                        .trim()
-                } else {
-                    title = rawTitle
-                }
-                continue
-            }
-
-            // Parse Sections
-            if (line.startsWith('## ')) {
-                // Save previous section
-                if (currentSection) {
-                    currentSection.content = currentContent.join('\n').trim()
-                    sections.push(currentSection)
-                }
-
-                currentSection = {
-                    title: line.replace('## ', '').trim(),
-                    content: '',
-                }
-                currentContent = []
-                continue
-            }
-
-            // Collect content
-            if (currentSection) {
-                currentContent.push(line)
-            }
-        }
-
-        // Save last section
-        if (currentSection) {
-            currentSection.content = currentContent.join('\n').trim()
-            sections.push(currentSection)
-        }
-
-        return {
-            title,
-            sections,
-            metadata,
-        }
-    }
-}

package/src/parsers/task-parser.test.ts

@@ -1,60 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { TaskParser } from './task-parser'
-
-describe('TaskParser', () => {
-    it('should parse a TODO task correctly', () => {
-        const markdown = '- [ ] **[TASK-01]** Initial task `Priority: 🔴 Critical` `Complexity: S`'
-        const tasks = TaskParser.parse(markdown)
-        expect(tasks).toHaveLength(1)
-        expect(tasks[0]).toEqual({
-            id: 'TASK-01',
-            title: 'Initial task',
-            priority: '🔴 Critical',
-            complexity: 'S',
-            status: 'TODO',
-        })
-    })
-
-    it('should parse an IN_PROGRESS task correctly', () => {
-        const markdown = '- [/] **[CLI-01]** Coding `Priority: 🟠 High` `Complexity: M`'
-        const tasks = TaskParser.parse(markdown)
-        expect(tasks).toHaveLength(1)
-        expect(tasks[0]!.status).toBe('IN_PROGRESS')
-    })
-
-    it('should parse a DONE task correctly', () => {
-        const markdown = '- [x] **[DOC-01]** Writing `Priority: 🔵 Medium` `Complexity: L`'
-        const tasks = TaskParser.parse(markdown)
-        expect(tasks).toHaveLength(1)
-        expect(tasks[0]!.status).toBe('DONE')
-    })
-
-    it('should parse a BLOCKED task correctly', () => {
-        const markdown = '- [!] **[CORE-01]** Waiting `Priority: ⚪ Low` `Complexity: XL`'
-        const tasks = TaskParser.parse(markdown)
-        expect(tasks).toHaveLength(1)
-        expect(tasks[0]!.status).toBe('BLOCKED')
-    })
-
-    it('should parse multiple tasks across lines', () => {
-        const markdown = `
-# Tasks
-- [ ] **[T1]** One \`Priority: 🔴 Critical\` \`Complexity: S\`
-- [x] **[T2]** Two \`Priority: 🟠 High\` \`Complexity: M\`
-        `
-        const tasks = TaskParser.parse(markdown)
-        expect(tasks).toHaveLength(2)
-        expect(tasks[0]!.id).toBe('T1')
-        expect(tasks[1]!.id).toBe('T2')
-    })
-
-    it('should ignore non-task lines', () => {
-        const markdown = `
-# Legend
-This is some text.
-- This is a list but not a task.
-        `
-        const tasks = TaskParser.parse(markdown)
-        expect(tasks).toHaveLength(0)
-    })
-})

package/src/parsers/task-parser.ts

@@ -1,40 +0,0 @@
-import type { Complexity, Priority, Task, TaskStatus } from '../types'
-
-export class TaskParser {
-    static parse(markdown: string): Task[] {
-        const tasks: Task[] = []
-        const lines = markdown.split(/\r?\n/)
-        const taskRegex = /- \[([ x/!])\] \*\*\[(.+)\]\*\* (.+) `Priority: (.+)` `Complexity: (.+)`/
-
-        for (const line of lines) {
-            const match = line.match(taskRegex)
-            if (match) {
-                const [, statusChar = ' ', id = '', title = '', priority = '', complexity = ''] =
-                    match
-                tasks.push({
-                    id,
-                    title: title.trim(),
-                    priority: priority as Priority,
-                    complexity: complexity as Complexity,
-                    status: this.mapStatus(statusChar),
-                })
-            }
-        }
-        return tasks
-    }
-
-    private static mapStatus(char: string): TaskStatus {
-        switch (char) {
-            case ' ':
-                return 'TODO'
-            case '/':
-                return 'IN_PROGRESS'
-            case 'x':
-                return 'DONE'
-            case '!':
-                return 'BLOCKED'
-            default:
-                return 'TODO'
-        }
-    }
-}

package/src/schemas/manifest.ts

@@ -1,13 +0,0 @@
-import { z } from 'zod'
-
-/**
- * Manifest Schema for .autonomos/manifest.json
- */
-export const ManifestSchema = z.object({
-    protocolVersion: z.string().describe('Version of the Agent Protocol specification'),
-    cliVersion: z.string().describe('Version of the CLI that last updated this project'),
-    initializedAt: z.string().datetime().describe('ISO timestamp of project initialization'),
-    lastUpdated: z.string().datetime().describe('ISO timestamp of last protocol update'),
-})
-
-export type Manifest = z.infer<typeof ManifestSchema>

package/src/templates/agent.ts

@@ -1,43 +0,0 @@
-/**
- * Template for AGENT.md - The context anchor at project root
- * @param projectName - Name of the project to personalize the template
- */
-export function generateAgentTemplate(projectName: string = 'Project'): string {
-    return `---
-name: "${projectName}"
-type: "project"
-status: "active"
----
-# AGENT CONTEXT: ${projectName}
-
-## 🧠 Context & Objectives
-
-*Describe what this project does and its main goals.*
-
-## ⚙️ Workflow & Preferences
-
-- **Commits:** Conventional Commits
-- **Language:** English
-
-## 🏗 Stack & Architecture
-
-- **Tech:** *(List frameworks, libraries)*
-- **Patterns:** *(Architecture patterns used)*
-
-## 📁 Key Directories
-
-| Path | Description |
-|------|-------------|
-| \`src/\` | Source code |
-| \`.autonomos/\` | Agent Protocol files |
-
-## ⚠️ Known Constraints
-
-*List any technical debts, missing features, or external limitations.*
-`
-}
-
-/**
- * Default AGENT.md template
- */
-export const AGENT_TEMPLATE = generateAgentTemplate()

package/src/templates/manifest.test.ts

@@ -1,26 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { createManifest, parseManifest } from './manifest'
-
-describe('Manifest Parser', () => {
-    it('should validate a correct manifest correctly', () => {
-        const manifest = createManifest('0.0.1')
-        const json = JSON.stringify(manifest)
-        const parsed = parseManifest(json)
-        expect(parsed.cliVersion).toBe('0.0.1')
-    })
-
-    it('should throw error on invalid manifest', () => {
-        const invalidJson = JSON.stringify({
-            protocolVersion: '1.0',
-            // Missing fields or invalid types
-        })
-        expect(() => parseManifest(invalidJson)).toThrow()
-    })
-
-    it('should throw error on invalid date format', () => {
-        const manifest = createManifest('0.0.1')
-        manifest.initializedAt = 'invalid-date'
-        const json = JSON.stringify(manifest)
-        expect(() => parseManifest(json)).toThrow()
-    })
-})

package/src/templates/manifest.ts

@@ -1,30 +0,0 @@
-import { PROTOCOL_VERSION } from '../constants'
-import { ManifestSchema, type Manifest } from '../schemas/manifest'
-
-/**
- * Creates a new manifest object with current timestamps
- */
-export function createManifest(cliVersion: string): Manifest {
-    const now = new Date().toISOString()
-    return {
-        protocolVersion: PROTOCOL_VERSION,
-        cliVersion,
-        initializedAt: now,
-        lastUpdated: now,
-    }
-}
-
-/**
- * Generates the manifest.json content as a formatted string
- */
-export function generateManifestContent(manifest: Manifest): string {
-    return JSON.stringify(manifest, null, 4) + '\n'
-}
-
-/**
- * Parses manifest.json content into a Manifest object with validation
- */
-export function parseManifest(content: string): Manifest {
-    const data = JSON.parse(content)
-    return ManifestSchema.parse(data)
-}