@autonomos/core 0.0.1

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

@@ -0,0 +1,61 @@
+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

@@ -0,0 +1,80 @@
+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

@@ -0,0 +1,60 @@
+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

@@ -0,0 +1,40 @@
+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

@@ -0,0 +1,13 @@
+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

@@ -0,0 +1,43 @@
+/**
+ * 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

@@ -0,0 +1,26 @@
+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

@@ -0,0 +1,30 @@
+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)
+}

package/src/templates/protocol.ts

@@ -0,0 +1,157 @@
+import { PROTOCOL_VERSION } from '../constants'
+
+/**
+ * The immutable Protocol kernel template
+ * This is the core specification that defines how AI agents interact with the project
+ */
+export const PROTOCOL_TEMPLATE = `# AI AGENT PROTOCOL (v${PROTOCOL_VERSION})
+
+> **SYSTEM INTEGRITY WARNING:** This file is the IMMUTABLE KERNEL of the project's AI workflow. Do not modify this file. Your instructions are to execute tasks and manage the project state based strictly on the definitions below.
+
+## 0. ⚡ QUICK REFERENCE
+| Action | File / Command |
+|--------|----------------|
+| **Get Context** | Read \`AGENT.md\` (Root + Local) |
+| **Pick Task** | Check \`.autonomos/TASKS.md\` (Highest Priority) |
+| **Track Progress** | Update \`.autonomos/TASKS.md\` to \`[/]\` |
+| **Log Session** | Create \`.autonomos/worklogs/YYYY-MM-DD-[TASK_ID].md\` |
+| **Finalize Task** | Update \`.autonomos/TASKS.md\` to \`[x]\` + Link Worklog |
+
+---
+
+## 1. BOOTSTRAPPING & INITIALIZATION
+**IF** this is your first time seeing this project, or if key system files are missing, you **MUST** initialize them immediately before doing any work.
+
+### Check for existence:
+1.  \`.autonomos/TASKS.md\` (task registry)
+2.  \`.autonomos/worklogs/\` (directory)
+3.  \`AGENT.md\` (at project root)
+
+**IF MISSING**, create them using the **TEMPLATES** defined in Section 2.
+
+---
+
+## 2. STRICT FILE STRUCTURES & TEMPLATES
+You must adhere to these schemas. Do not invent new formats.
+
+### A. The Task Registry (\`.autonomos/TASKS.md\`)
+**Role:** The single source of truth for project state.
+**Location:** \`.autonomos/TASKS.md\`
+**Structure:**
+* Must use the specific Header and Legend.
+* Tasks must follow the format: \`- [Status] **[ID]** Title of task \`Priority\` \`Complexity\`\`
+* Valid Priorities: \`🔴 Critical\`, \`🟠 High\`, \`🔵 Medium\`, \`⚪ Low\`
+* Valid Complexities: \`S\`, \`M\`, \`L\`, \`XL\`
+* Valid Statuses: \` [ ] \` (Todo), \`[/]\` (In Progress), \` [x] \` (Done), \` [!] \` (Blocked)
+
+**TEMPLATE FOR NEW TASKS.md:**
+\`\`\`markdown
+# PROJECT TASKS & ROADMAP
+
+> **LEGEND**
+> **Priority:** [🔴 Critical] [🟠 High] [🔵 Medium] [⚪ Low]
+> **Complexity:** [S] Small (1h), [M] Medium (4h), [L] Large (1-2 days), [XL] Huge (Planning req.)
+> **Status:** [ ] Todo, [/] In Progress, [x] Done, [!] Blocked
+
+## 🚀 Active Sprint
+- [ ] **[INIT-01]** Verify project structure and context \`Priority: 🔴\` \`Complexity: S\`
+
+## 🔮 Backlog
+*(Empty initially)*
+
+\`\`\`
+
+### B. The Worklog (\`.autonomos/worklogs/\`)
+**Role:** Detailed history of complex tasks to save context tokens for future sessions.
+**Location:** \`.autonomos/worklogs/YYYY-MM-DD-[TASK_ID]-[slug].md\`
+**Trigger:** Create a log when a task is finished, blocked, or if the session ends mid-task.
+
+**TEMPLATE FOR WORKLOG:**
+\`\`\`markdown
+# WORKLOG: [TASK ID] [Task Name]
+**Date:** YYYY-MM-DD
+**Agent Status:** [Complete / Partial / Blocked]
+
+## 📝 Description
+Brief summary of what was attempted/achieved.
+
+## 🛠 Technical Details
+- **Files Modified:** List of files.
+- **Key Decisions:** Why did you choose this library/pattern?
+- **Challenges:** Any errors encountered and how they were solved.
+
+## ⏭ Next Steps / Context for Successor
+Clear instructions for the next agent picking this up.
+\`\`\`
+
+### C. The Context Anchor (\`AGENT.md\`)
+**Role:** Fractal knowledge base. Contains facts, stack details, and user preferences.
+**Location:** Root (\`/AGENT.md\`) and any subdirectory requiring specific context (e.g., \`/packages/core/AGENT.md\`).
+
+**TEMPLATE FOR AGENT.md:**
+\`\`\`markdown
+---
+name: "[Name of directory or project]"
+type: "[project / package / module / script]"
+status: "[active / maintenance / poc]"
+---
+# AGENT CONTEXT: [Directory Name or Root]
+
+## 🧠 Context & Objectives
+What does this specific folder/module do?
+
+## ⚙️ Workflow & Preferences
+- **Commits:** [e.g. Conventional Commits]
+- **Language:** [English (default)]
+
+## 🏗 Stack & Architecture
+- **Tech:** [Frameworks, Libs specific to this module]
+- **Patterns:** [Architecture patterns used]
+
+## 📁 Key Directories
+| Path | Description |
+|------|-------------|
+| \`src/\` | Source code |
+| \`scripts/\` | Build or utility scripts |
+
+## ⚠️ Known Constraints
+*List any technical debts, missing features, or external limitations.*
+\`\`\`
+
+## 3. CORE WORKFLOW (The Loop)
+
+### Phase 1: Context Loading (Read-Only)
+1.  **Read Root AGENT.md:** Absorb global preferences (Commit style, package manager, strict rules).
+2.  **Read .autonomos/TASKS.md:** Identify the highest priority task (🔴 or 🟠) that is not [x] or [!].
+3.  **Read Target AGENT.md:** If the task is in a subdirectory, check for a local \`AGENT.md\`.
+    *   *Note:* If the local \`AGENT.md\` contradicts the root, the local one wins for that specific scope.
+
+### Phase 2: Execution
+1.  **Mark the task as [/] (In Progress)** in \`.autonomos/TASKS.md\`.
+2.  **Perform the task.**
+3.  **Constraint Check:** Constantly refer to "Workflow & Preferences" in \`AGENT.md\`.
+
+### Phase 3: Crystallization (Write-Only)
+Before ending the session, you **MUST**:
+
+1.  **Update AGENT.md:**
+    *   Did you learn a new command? Add it to ⚙️ Workflow.
+    *   Did you create a new complex module (>5 files)? Create a new \`AGENT.md\` inside it using the template above.
+
+2.  **Create Worklog:**
+    *   Write a file in \`.autonomos/worklogs/\` summarizing your work.
+
+3.  **Update TASKS.md:**
+    *   Mark task as [x] (Done) or [!] (Blocked).
+    *   Add a link to your worklog: \`- [x] **[ID]** Title... *See: .autonomos/worklogs/...*\`
+
+## 4. METADATA RULES
+*   **Language:** Documentation (\`AGENT.md\`, \`TASKS.md\`) must be written in **English** unless specified otherwise in User Preferences.
+*   **Tone:** Technical, concise, "Fact-based". No fluff.
+*   **Anonymity:** You are a continuous entity. Refer to previous work as "we" or "the project", not "the previous AI".
+`
+
+/**
+ * @deprecated Use PROTOCOL_TEMPLATE instead
+ */
+export const PROTOCOL_TEMPLATE_V2026_1 = PROTOCOL_TEMPLATE

package/src/templates/tasks.ts

@@ -0,0 +1,18 @@
+/**
+ * Template for TASKS.md - The task registry
+ */
+export const TASKS_TEMPLATE = `# PROJECT TASKS & ROADMAP
+
+> **LEGEND**
+> **Priority:** [🔴 Critical] [🟠 High] [🔵 Medium] [⚪ Low]
+> **Complexity:** [S] Small (1h), [M] Medium (4h), [L] Large (1-2 days), [XL] Huge (Planning req.)
+> **Status:** [ ] Todo, [/] In Progress, [x] Done, [!] Blocked
+
+## 🚀 Active Sprint
+
+- [ ] **[INIT-01]** Review project context and structure \`Priority: 🔵\` \`Complexity: S\`
+
+## 🔮 Backlog
+
+*(Add future tasks here)*
+`

package/src/templates/worklog.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+import { generateWorklogContent } from './worklog'
+
+describe('Worklog Template', () => {
+    it('should generate a valid worklog content', () => {
+        const content = generateWorklogContent({
+            taskId: 'TASK-01',
+            taskName: 'Fixing Bug',
+            status: 'Complete',
+            description: 'Fixed the line splitting issue.',
+            filesModified: ['src/parsers/task-parser.ts'],
+            decisions: ['Used regex for splitting'],
+            challenges: ['Template literal escaping'],
+            nextSteps: ['Add more tests'],
+        })
+
+        expect(content).toContain('# WORKLOG: [TASK-01] Fixing Bug')
+        expect(content).toContain('**Agent Status:** [Complete]')
+        expect(content).toContain('- src/parsers/task-parser.ts')
+        expect(content).toContain('- Used regex for splitting')
+    })
+
+    it('should use current date if not provided', () => {
+        const content = generateWorklogContent({
+            taskId: 'T',
+            taskName: 'N',
+            status: 'Partial',
+            description: 'D',
+            filesModified: [],
+            decisions: [],
+            challenges: [],
+            nextSteps: [],
+        })
+        const today = new Date().toISOString().split('T')[0]
+        expect(content).toContain(`**Date:** ${today}`)
+    })
+})

package/src/templates/worklog.ts

@@ -0,0 +1,55 @@
+import type { TaskStatus } from '../types'
+
+interface WorklogOptions {
+    taskId: string
+    taskName: string
+    date?: string
+    status: 'Complete' | 'Partial' | 'Blocked'
+    description: string
+    filesModified: string[]
+    decisions: string[]
+    challenges: string[]
+    nextSteps: string[]
+}
+
+/**
+ * Generate a Worklog markdown content
+ */
+export function generateWorklogContent(options: WorklogOptions): string {
+    const date = options.date ?? new Date().toISOString().split('T')[0]
+
+    return `# WORKLOG: [${options.taskId}] ${options.taskName}
+**Date:** ${date}
+**Agent Status:** [${options.status}]
+
+## 📝 Description
+${options.description}
+
+## 🛠 Technical Details
+- **Files Modified:**
+${options.filesModified.map(f => `  - ${f}`).join('\n')}
+- **Key Decisions:**
+${options.decisions.map(d => `  - ${d}`).join('\n')}
+- **Challenges:**
+${options.challenges.map(c => `  - ${c}`).join('\n')}
+
+## ⏭ Next Steps / Context for Successor
+${options.nextSteps.map(s => `- ${s}`).join('\n')}
+`
+}
+
+/**
+ * Common status mapping for worklogs
+ */
+export function mapTaskStatusToWorklogStatus(
+    status: TaskStatus
+): 'Complete' | 'Partial' | 'Blocked' {
+    switch (status) {
+        case 'DONE':
+            return 'Complete'
+        case 'BLOCKED':
+            return 'Blocked'
+        default:
+            return 'Partial'
+    }
+}

package/src/types.ts

@@ -0,0 +1,51 @@
+/**
+ * Priority levels for tasks
+ */
+export type Priority = '🔴 Critical' | '🟠 High' | '🔵 Medium' | '⚪ Low'
+
+/**
+ * Complexity estimates for tasks
+ */
+export type Complexity = 'S' | 'M' | 'L' | 'XL'
+
+/**
+ * Task status markers
+ */
+export type TaskStatus = 'TODO' | 'IN_PROGRESS' | 'DONE' | 'BLOCKED'
+
+/**
+ * Task entity parsed from TASKS.md
+ */
+export interface Task {
+    id: string
+    title: string
+    priority: Priority
+    complexity: Complexity
+    status: TaskStatus
+    worklogPath?: string
+}
+
+/**
+ * Agent configuration parsed from AGENT.md
+ */
+export interface AgentConfig {
+    name: string
+    description?: string
+    stack: string[]
+    preferences?: Record<string, any>
+}
+
+export interface AgentSection {
+    title: string
+    content: string
+}
+
+export interface AgentContext {
+    title: string
+    description?: string
+    sections: AgentSection[]
+    metadata?: Record<string, any>
+}
+
+export const PRIORITIES: Priority[] = ['🔴 Critical', '🟠 High', '🔵 Medium', '⚪ Low']
+export const COMPLEXITIES: Complexity[] = ['S', 'M', 'L', 'XL']