@soederpop/luca 0.1.3 → 0.2.1

package/src/agi/features/assistants-manager.ts

@@ -27,6 +27,10 @@ export interface AssistantEntry {
 	hasHooks: boolean
 	/** Whether a voice.yaml configuration file exists. */
 	hasVoice: boolean
+	/** Contents of ABOUT.md if present, undefined otherwise. */
+	about?: string
+	/** Frontmatter metadata parsed from CORE.md. */
+	meta?: Record<string, any>
 }
 
 export const AssistantsManagerEventsSchema = FeatureEventsSchema.extend({
@@ -191,6 +195,25 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 
 				// Don't overwrite earlier entries (home takes precedence for same name)
 				if (!discovered[entry]) {
+					const hasAbout = fs.exists(`${folder}/ABOUT.md`)
+					let about: string | undefined
+					let meta: Record<string, any> | undefined
+
+					if (hasAbout) {
+						about = fs.readFileSync(`${folder}/ABOUT.md`, 'utf8')
+					}
+
+					try {
+						const coreContent = fs.readFileSync(`${folder}/CORE.md`, 'utf8')
+						const fmMatch = coreContent.match(/^---\r?\n([\s\S]*?)\r?\n---/)
+						if (fmMatch) {
+							const yaml = this.container.feature('yaml')
+							meta = yaml.parse(fmMatch[1])
+						}
+					} catch {
+						// CORE.md exists but couldn't be parsed — skip meta
+					}
+
 					discovered[entry] = {
 						name: entry,
 						folder,
@@ -198,6 +221,8 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 						hasTools: fs.exists(`${folder}/tools.ts`),
 						hasHooks: fs.exists(`${folder}/hooks.ts`),
 						hasVoice: fs.exists(`${folder}/voice.yaml`),
+						...(about != null && { about }),
+						...(meta != null && { meta }),
 					}
 				}
 			}

package/src/agi/features/browser-use.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { Feature } from '../feature.js'
+import type { Helper } from '../../helper.js'
 
 declare module '@soederpop/luca/feature' {
   interface AvailableFeatures {
@@ -223,6 +224,35 @@ export class BrowserUse extends Feature<BrowserUseState, BrowserUseOptions> {
 
   static { Feature.register(this, 'browserUse') }
 
+  /**
+   * When an assistant uses browserUse, inject system prompt guidance
+   * about the browser interaction loop.
+   */
+  override setupToolsConsumer(consumer: Helper) {
+    if (typeof (consumer as any).addSystemPromptExtension === 'function') {
+      (consumer as any).addSystemPromptExtension('browserUse', [
+        '## Browser Automation',
+        '',
+        '**The core loop:** `browserOpen` → `browserGetState` → interact → `browserGetState` again.',
+        '',
+        '`browserGetState` is your eyes. It returns all interactive elements with index numbers. You MUST call it:',
+        '- After every `browserOpen` or navigation',
+        '- After any action that changes the page (click, submit, scroll)',
+        '- Before any interaction — to get fresh element indices',
+        '',
+        'Element indices change whenever the page updates. Never reuse indices from a previous `browserGetState` call after the page has changed.',
+        '',
+        '**Interacting with elements:** Use `browserInput` (click + type) for form fields. Use `browserClick` for buttons and links. Use `browserSelect` for dropdowns. All require an element index from `browserGetState`.',
+        '',
+        '**When things load asynchronously:** Use `browserWaitForSelector` or `browserWaitForText` after actions that trigger page updates (form submissions, AJAX). Then call `browserGetState` to see the updated page.',
+        '',
+        '**Debugging:** If an interaction doesn\'t work, take a `browserScreenshot` to see the actual page state. Check `browserGetState` to see what elements are available.',
+        '',
+        '**Cleanup:** Call `browserClose` when you\'re done to free resources.',
+      ].join('\n'))
+    }
+  }
+
   override async afterInitialize() {
     if (this.options.session) this.state.set('session', this.options.session)
     if (this.options.headed) this.state.set('headed', true)

package/src/agi/features/coding-tools.ts

@@ -0,0 +1,175 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
+import { Feature } from '../feature.js'
+import type { Helper } from '../../helper.js'
+import type { ChildProcess } from '../../node/features/proc.js'
+
+declare module '@soederpop/luca/feature' {
+	interface AvailableFeatures {
+		codingTools: typeof CodingTools
+	}
+}
+
+export const CodingToolsStateSchema = FeatureStateSchema.extend({})
+export const CodingToolsOptionsSchema = FeatureOptionsSchema.extend({})
+
+/**
+ * Shell primitives for AI coding assistants: rg, ls, cat, sed, awk.
+ *
+ * Wraps standard Unix tools into the assistant tool surface with
+ * LLM-optimized descriptions and system prompt guidance. These are
+ * the raw, flexible tools for reading, searching, and exploring code.
+ *
+ * Compose with other features (fileTools, processManager, skillsLibrary)
+ * in assistant hooks for a complete coding tool surface.
+ *
+ * Usage:
+ * ```typescript
+ * assistant.use(container.feature('codingTools'))
+ * ```
+ *
+ * @extends Feature
+ */
+export class CodingTools extends Feature {
+	static override shortcut = 'features.codingTools' as const
+	static override stateSchema = CodingToolsStateSchema
+	static override optionsSchema = CodingToolsOptionsSchema
+
+	static { Feature.register(this, 'codingTools') }
+
+	static override tools: Record<string, { schema: z.ZodType; description?: string }> = {
+		rg: {
+			description: 'ripgrep — fast content search across files. The fastest way to find where something is defined, referenced, or used. Supports regex, file type filtering, context lines, and everything ripgrep supports.',
+			schema: z.object({
+				args: z.string().describe(
+					'Arguments to pass to rg, exactly as you would on the command line. ' +
+					'Examples: "TODO --type ts", "-n "function handleAuth" src/", ' +
+					'"import.*lodash -g "*.ts" --count", "-C 3 "class User" src/models/"'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('ripgrep — fast content search across files. Supports regex, file type filtering, context lines. Use this as your primary search tool for finding code.'),
+		},
+		ls: {
+			description: 'List files and directories. Use to orient yourself in the project structure, check what exists in a directory, or verify paths before operating on them.',
+			schema: z.object({
+				args: z.string().optional().describe(
+					'Arguments to pass to ls. Examples: "-la src/", "-R --color=never commands/", "-1 *.ts". ' +
+					'Defaults to listing the project root.'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('List files and directories. Use to orient yourself, check directory contents, or verify paths.'),
+		},
+		cat: {
+			description: 'Read file contents. Use for reading entire files or specific line ranges. For large files, prefer reading specific ranges with sed or use rg to find the relevant section first.',
+			schema: z.object({
+				args: z.string().describe(
+					'Arguments to pass to cat. Typically just a file path. ' +
+					'Examples: "src/index.ts", "-n src/index.ts" (with line numbers). ' +
+					'For line ranges, use sed instead: sed -n "10,20p" file.ts'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('Read file contents. Best for reading entire files or viewing file content with line numbers.'),
+		},
+		sed: {
+			description: 'Stream editor for extracting or transforming text. Use for reading specific line ranges from files, or performing find-and-replace operations.',
+			schema: z.object({
+				args: z.string().describe(
+					'Arguments to pass to sed. Examples: ' +
+					'"-n \\"10,30p\\" src/index.ts" (print lines 10-30), ' +
+					'"-n \\"1,5p\\" package.json" (first 5 lines), ' +
+					'"s/oldName/newName/g src/config.ts" (find-and-replace)'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('Stream editor for extracting line ranges or transforming text in files.'),
+		},
+		awk: {
+			description: 'Pattern scanning and text processing. Use for extracting specific fields from structured output, summarizing data, or complex text transformations.',
+			schema: z.object({
+				args: z.string().describe(
+					'Arguments to pass to awk. Examples: ' +
+					'"\'{print $1}\' file.txt" (first column), ' +
+					'"-F: \'{print $1, $3}\' /etc/passwd" (colon-delimited fields), ' +
+					'"\'/pattern/ {print}\' file.txt" (lines matching pattern)'
+				),
+				cwd: z.string().optional().describe('Working directory. Defaults to project root.'),
+			}).describe('Pattern scanning and text processing. Extract fields, summarize data, or perform complex text transformations.'),
+		},
+	}
+
+	private get proc(): ChildProcess {
+		return this.container.feature('proc') as unknown as ChildProcess
+	}
+
+	// -------------------------------------------------------------------------
+	// Shell tool implementations
+	// -------------------------------------------------------------------------
+
+	private async _exec(command: string, args: string, cwd?: string): Promise<string> {
+		const fullCommand = args ? `${command} ${args}` : command
+		const result = await this.proc.execAndCapture(fullCommand, {
+			cwd: cwd ?? this.container.cwd,
+		})
+
+		if (result.exitCode !== 0) {
+			const parts: string[] = []
+			if (result.stdout?.trim()) parts.push(result.stdout.trim())
+			if (result.stderr?.trim()) parts.push(`[stderr] ${result.stderr.trim()}`)
+			parts.push(`[exit code: ${result.exitCode}]`)
+			return parts.join('\n')
+		}
+
+		return result.stdout || '(no output)'
+	}
+
+	async rg(args: { args: string; cwd?: string }): Promise<string> {
+		return this._exec('rg', args.args, args.cwd)
+	}
+
+	async ls(args: { args?: string; cwd?: string }): Promise<string> {
+		return this._exec('ls', args.args || '', args.cwd)
+	}
+
+	async cat(args: { args: string; cwd?: string }): Promise<string> {
+		return this._exec('cat', args.args, args.cwd)
+	}
+
+	async sed(args: { args: string; cwd?: string }): Promise<string> {
+		return this._exec('sed', args.args, args.cwd)
+	}
+
+	async awk(args: { args: string; cwd?: string }): Promise<string> {
+		return this._exec('awk', args.args, args.cwd)
+	}
+
+	override setupToolsConsumer(consumer: Helper) {
+		if (typeof (consumer as any).addSystemPromptExtension === 'function') {
+			(consumer as any).addSystemPromptExtension('codingTools', SYSTEM_PROMPT_EXTENSION)
+		}
+	}
+}
+
+// ─── System Prompt Extension ──────────────────────────────────────────────────
+
+const SYSTEM_PROMPT_EXTENSION = [
+	'## Shell Tools',
+	'',
+	'You have direct access to standard Unix tools. These are your primary read/search/explore tools:',
+	'',
+	'**`rg` (ripgrep) — your most important tool.** Use it before guessing where anything is.',
+	'- `rg -n "pattern" --type ts` — search TypeScript files with line numbers',
+	'- `rg -C 3 "pattern"` — show 3 lines of context around matches',
+	'- `rg -l "pattern"` — list only filenames that match',
+	'- `rg "TODO|FIXME" --type ts --count` — count matches per file',
+	'',
+	'**`cat` — read files.** Use `cat -n` for line numbers. For large files, use `sed -n "10,30p"` to read a range.',
+	'',
+	'**`ls` — orient yourself.** `ls -la src/` for details, `ls -R` for recursive listing.',
+	'',
+	'**`sed` — extract line ranges.** `sed -n "50,80p" file.ts` reads lines 50-80.',
+	'',
+	'**`awk` — structured text processing.** Extract columns, summarize, transform.',
+	'',
+	'**Workflow:** `rg` to find → `cat -n` to read → `editFile` to change → `runCommand` to verify.',
+].join('\n')
+
+export default CodingTools

package/src/agi/features/file-tools.ts

@@ -48,20 +48,20 @@ export class FileTools extends Feature {
 			}).describe('Read the contents of a file. Returns the text content. Use offset/limit to read portions of large files.'),
 		},
 		writeFile: {
-			description: 'Create a new file or overwrite an existing file with the given content. Prefer editFile for modifying existing files.',
+			description: 'Create a new file or completely overwrite an existing file. WARNING: this replaces the entire file — use editFile instead for modifying existing files. Use writeFile only for creating new files or intentional full rewrites.',
 			schema: z.object({
-				path: z.string().describe('File path relative to the project root'),
-				content: z.string().describe('The full content to write'),
-			}).describe('Create a new file or overwrite an existing file with the given content. Prefer editFile for modifying existing files.'),
+				path: z.string().describe('File path relative to the project root. Parent directories are created automatically.'),
+				content: z.string().describe('The complete file content. This replaces everything in the file — there is no merge or append.'),
+			}).describe('Create a new file or completely overwrite an existing file. WARNING: this replaces the entire file — use editFile instead for modifying existing files. Use writeFile only for creating new files or intentional full rewrites.'),
 		},
 		editFile: {
-			description: 'Make a surgical edit to a file by replacing an exact string match. The oldString must appear exactly once in the file (unless replaceAll is true). This is the preferred way to modify existing files.',
+			description: 'Make a surgical edit to a file by replacing an exact string match. The preferred way to modify existing files — always use this over writeFile for changes to existing code.',
 			schema: z.object({
 				path: z.string().describe('File path relative to the project root'),
-				oldString: z.string().describe('The exact text to find and replace'),
-				newString: z.string().describe('The replacement text'),
-				replaceAll: z.boolean().optional().describe('Replace all occurrences instead of requiring uniqueness (default: false)'),
-			}).describe('Make a surgical edit to a file by replacing an exact string match. The oldString must appear exactly once in the file (unless replaceAll is true).'),
+				oldString: z.string().describe('The EXACT text to find, copied verbatim from the file — including whitespace and indentation. Must appear exactly once in the file (unless replaceAll is true). If the match fails, read the file again and copy the exact text.'),
+				newString: z.string().describe('The replacement text. Preserve the same indentation style as the surrounding code.'),
+				replaceAll: z.boolean().optional().describe('Replace all occurrences instead of requiring uniqueness. Use for renaming a variable across a file. Default: false.'),
+			}).describe('Make a surgical edit to a file by replacing an exact string match. The preferred way to modify existing files — always use this over writeFile for changes to existing code.'),
 		},
 		listDirectory: {
 			description: 'List files and directories at a path. Returns arrays of file and directory names.',
@@ -73,23 +73,23 @@ export class FileTools extends Feature {
 			}).describe('List files and directories at a path. Returns arrays of file and directory names.'),
 		},
 		searchFiles: {
-			description: 'Search file contents for a pattern using ripgrep. Returns structured matches with file, line number, and content.',
+			description: 'Search inside file contents for a pattern (like grep/ripgrep). Returns matching lines with file path and line number. Use this to find where code is defined, where a function is called, or any text pattern across the codebase.',
 			schema: z.object({
-				pattern: z.string().describe('Search pattern (regex supported)'),
-				path: z.string().optional().describe('Directory to search in (defaults to project root)'),
-				include: z.string().optional().describe('Glob pattern to filter files (e.g. "*.ts")'),
-				exclude: z.string().optional().describe('Glob pattern to exclude (e.g. "node_modules")'),
-				ignoreCase: z.boolean().optional().describe('Case insensitive search'),
-				maxResults: z.number().optional().describe('Maximum number of results to return'),
-			}).describe('Search file contents for a pattern using ripgrep. Returns structured matches with file, line number, and content.'),
+				pattern: z.string().describe('Search pattern — supports regex. Examples: "function handleAuth", "TODO|FIXME", "import.*from.*react"'),
+				path: z.string().optional().describe('Directory to search in (defaults to project root). Narrow this to avoid searching node_modules or irrelevant directories.'),
+				include: z.string().optional().describe('Glob to filter which files to search (e.g. "*.ts", "*.tsx"). Use this to scope to specific file types.'),
+				exclude: z.string().optional().describe('Glob to exclude files (e.g. "node_modules", "dist"). node_modules is excluded by default.'),
+				ignoreCase: z.boolean().optional().describe('Case insensitive search. Default: false.'),
+				maxResults: z.number().optional().describe('Maximum results to return. Default: 50. Use a smaller number for broad patterns.'),
+			}).describe('Search inside file contents for a pattern (like grep/ripgrep). Returns matching lines with file path and line number. Use this to find where code is defined, where a function is called, or any text pattern across the codebase.'),
 		},
 		findFiles: {
-			description: 'Find files by name/glob pattern. Returns matching file paths.',
+			description: 'Find files by name or glob pattern. Returns file paths, not contents. Use this to locate files ("where is the config?"), not to search inside them (use searchFiles for that).',
 			schema: z.object({
-				pattern: z.string().describe('Glob pattern to match (e.g. "**/*.test.ts", "src/**/*.tsx")'),
+				pattern: z.string().describe('Glob pattern to match file names. Examples: "**/*.test.ts", "src/**/*.tsx", "**/config.*"'),
 				path: z.string().optional().describe('Directory to search from (defaults to project root)'),
-				exclude: z.string().optional().describe('Glob pattern to exclude'),
-			}).describe('Find files by name/glob pattern. Returns matching file paths.'),
+				exclude: z.string().optional().describe('Glob pattern to exclude. node_modules and .git are excluded by default.'),
+			}).describe('Find files by name or glob pattern. Returns file paths, not contents. Use this to locate files ("where is the config?"), not to search inside them (use searchFiles for that).'),
 		},
 		fileInfo: {
 			description: 'Get information about a file or directory: whether it exists, its type (file/directory), size, and modification time.',
@@ -273,11 +273,18 @@ export class FileTools extends Feature {
 		if (typeof (consumer as any).addSystemPromptExtension === 'function') {
 			(consumer as any).addSystemPromptExtension('fileTools', [
 				'## File Tools',
-				'- All file paths are relative to the project root unless they start with /',
-				'- Use `searchFiles` to understand code before modifying it',
-				'- Use `editFile` for surgical changes to existing files — prefer it over `writeFile`',
-				'- Use `listDirectory` to explore before assuming paths exist',
-				'- Use `readFile` with offset/limit for large files instead of reading the entire file',
+				'',
+				'All paths are relative to the project root unless they start with /.',
+				'',
+				'**Before modifying code:** Always read the file first. Use `searchFiles` to find where something is defined before making changes. Use `listDirectory` to verify paths exist before assuming.',
+				'',
+				'**Editing files:** Prefer `editFile` over `writeFile` for existing files — it makes surgical replacements. The `oldString` must appear exactly once in the file (unless using `replaceAll`). If your match isn\'t unique, include more surrounding context to make it unique. Never guess at file contents — read first, then edit.',
+				'',
+				'**Finding things:** Use `findFiles` to locate files by name or glob pattern (e.g. "**/*.test.ts"). Use `searchFiles` to find specific content inside files (grep). These are different tools for different questions: "where is the file?" vs "where is this code?".',
+				'',
+				'**Large files:** Use `readFile` with `offset` and `limit` to read portions. Don\'t load a 5000-line file when you only need lines 100-150.',
+				'',
+				'**`writeFile` is destructive** — it overwrites the entire file. Only use it for creating new files or when you intend a complete rewrite.',
 			].join('\n'))
 		}
 	}

package/src/agi/features/skills-library.ts

@@ -76,19 +76,19 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 	static override tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
 		searchAvailableSkills: {
 			schema: z.object({
-				query: z.string().optional().describe('Optional search term to filter skills by name or description'),
-			}).describe('Search for available skills in the library. Returns matching skill names and descriptions.'),
+				query: z.string().optional().describe('A keyword or phrase to filter skills by name or description. Omit to list all available skills.'),
+			}).describe('Discover what skills are available. Call this first when you need specialized knowledge — skills are curated guides and reference material for specific domains (frameworks, tools, patterns). Returns skill names and descriptions so you can decide which to load.'),
 		},
 		loadSkill: {
 			schema: z.object({
-				skillName: z.string().describe('The name of the skill to load'),
-			}).describe('Load a skill by name and return its full SKILL.md content and metadata.'),
+				skillName: z.string().describe('The exact skill name as returned by searchAvailableSkills'),
+			}).describe('Load a skill\'s full reference content (SKILL.md). This gives you detailed guidance, examples, and best practices for that domain. Load a skill before attempting work in an unfamiliar area — the content is curated to prevent common mistakes.'),
 		},
 		askSkillBasedQuestion: {
 			schema: z.object({
-				skillName: z.string().describe('The name of the skill to query'),
-				question: z.string().describe('The question to ask about the skill'),
-			}).describe('Ask a question about a specific skill using AI-assisted document reading.'),
+				skillName: z.string().describe('The exact skill name to query'),
+				question: z.string().describe('A specific question about the skill\'s domain. Be precise — "how do I add a new feature to the container?" is better than "tell me about features".'),
+			}).describe('Ask a focused question about a skill\'s domain using AI-assisted document reading. Use this when you need a specific answer from a skill rather than reading the whole thing. More efficient than loadSkill for targeted lookups.'),
 		},
 	}
 
@@ -107,8 +107,23 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 		if (!(assistant instanceof Assistant)) {
 			throw new Error('Skills library tools require an Assistant instance (including subclasses).')
 		}
-		
+
 		const a : Assistant = assistant as Assistant
+
+		a.addSystemPromptExtension('skillsLibrary', [
+			'## Skills Library',
+			'',
+			'You have access to a library of curated skills — domain-specific reference guides with examples, patterns, and best practices.',
+			'',
+			'**When to use skills:**',
+			'- When working in an unfamiliar domain or framework — load the skill before writing code',
+			'- When the user asks about a topic that might have a matching skill — search first',
+			'- When you see "Required Skills" in a message — load those skills immediately with `loadSkill` before answering',
+			'',
+			'**Workflow:** `searchAvailableSkills` → find relevant skill → `loadSkill` to get the full guide → follow its patterns. Use `askSkillBasedQuestion` for targeted lookups when you don\'t need the whole guide.',
+			'',
+			'**Skills are authoritative.** When a loaded skill contradicts your general knowledge, follow the skill — it reflects project-specific conventions and decisions.',
+		].join('\n'))
 		
 		const { container } = a
 		
@@ -451,10 +466,12 @@ Return only the skill names that are directly relevant. Return an empty array if
 			
 			const fork = assistant.conversation.fork()
 			const result = await fork.ask(prompt, { schema: responseSchema }) as unknown as { skills: string[] }
-			
-			console.log('Got a result', result)
 
-			return result.skills.filter(name => this.find(name) !== undefined)
+			const found = result.skills.filter(name => this.find(name) !== undefined)
+			
+			this.emit('foundSkills', found, assistant, userQuery)
+			
+			return found
 	}
 }
 

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-04-03T01:24:53.975Z
+// Generated at: 2026-04-05T06:58:07.990Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
 //
 // Do not edit manually. Run: luca build-bootstrap

package/src/cli/build-info.ts

@@ -1,4 +1,4 @@
 // Generated at compile time — do not edit manually
-export const BUILD_SHA = '2d0d67e'
+export const BUILD_SHA = '8323521'
 export const BUILD_BRANCH = 'main'
-export const BUILD_DATE = '2026-04-03T01:24:54Z'
+export const BUILD_DATE = '2026-04-05T06:58:08Z'