@autonav/core 1.0.0 → 1.1.1

package/dist/skill-generator/index.js

@@ -0,0 +1,236 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import os from "node:os";
+/**
+ * Get the global skills directory path
+ */
+export function getGlobalSkillsDir() {
+    return path.join(os.homedir(), ".claude", "skills");
+}
+/**
+ * Check if a skill already exists
+ */
+export function skillExists(skillName) {
+    const skillDir = path.join(getGlobalSkillsDir(), skillName);
+    return fs.existsSync(skillDir);
+}
+/**
+ * Generate the skill name from navigator name
+ */
+export function getSkillName(navigatorName) {
+    // Convert to lowercase, replace spaces/underscores with hyphens
+    const normalized = navigatorName.toLowerCase().replace(/[_\s]+/g, "-");
+    return `ask-${normalized}`;
+}
+/**
+ * Generate the SKILL.md content for a navigator
+ */
+export function generateSkillContent(config) {
+    const skillName = getSkillName(config.navigatorName);
+    const navPath = config.navigatorPath;
+    return `---
+name: ${skillName}
+description: Consult with ${config.navigatorName} navigator for questions about ${config.description}. Use when user asks to "ask ${config.navigatorName}" or needs information from this knowledge base.
+---
+
+# Ask ${config.navigatorName} Skill
+
+## Purpose
+Facilitate conversations with the **${config.navigatorName}** navigator located at \`${navPath}\`.
+
+${config.description}
+
+${config.scope ? `**Scope**: ${config.scope}\n` : ""}
+${config.audience ? `**Audience**: ${config.audience}\n` : ""}
+
+## When to Use This Skill
+
+Use this skill when the user:
+- Asks to "ask ${config.navigatorName.toLowerCase()}" or "query ${config.navigatorName.toLowerCase()}"
+- Needs information from the ${config.navigatorName} knowledge base
+- Wants to consult this navigator's domain expertise
+
+## Communication Protocol
+
+This navigator uses the Autonav communication layer for structured interactions.
+
+### Query Format (NavigatorQuery)
+\`\`\`json
+{
+  "protocolVersion": "1.0.0",
+  "fromNavigator": "<your-navigator-name>",
+  "toNavigator": "${config.navigatorName}",
+  "question": "<the question>",
+  "context": "<optional context>",
+  "reason": "needs_specialist"
+}
+\`\`\`
+
+### Response Format (NavigatorResponse)
+\`\`\`json
+{
+  "protocolVersion": "1.0.0",
+  "query": "<original question>",
+  "answer": "<grounded answer with citations>",
+  "sources": [
+    {
+      "filePath": "path/to/file.md",
+      "excerpt": "exact quote",
+      "section": "section heading"
+    }
+  ],
+  "confidence": 0.85
+}
+\`\`\`
+
+## Technical Implementation
+
+### Starting a New Conversation
+
+1. Generate a session UUID:
+\`\`\`bash
+UUID=$(python -c "import uuid; print(uuid.uuid4())")
+\`\`\`
+
+2. Start conversation:
+\`\`\`bash
+cd "${navPath}" && claude -p --session-id "$UUID" "$message"
+\`\`\`
+
+### Continuing a Conversation
+
+\`\`\`bash
+cd "${navPath}" && claude --resume "$UUID" -p "$message"
+\`\`\`
+
+### Using autonav query (Simpler)
+
+For one-off queries without maintaining session state:
+\`\`\`bash
+autonav query "${navPath}" "your question here"
+\`\`\`
+
+## Conversation Template
+
+When starting a conversation, provide:
+1. **Context** - What you're working on
+2. **Question** - Specific question for this navigator
+3. **Expected format** - If you need structured output
+
+Example:
+\`\`\`
+Hi ${config.navigatorName}! I'm working on [context].
+
+Question: [your specific question]
+
+Please provide sources for your answer.
+\`\`\`
+
+## Example Workflow
+
+### Quick Query
+\`\`\`bash
+autonav query "${navPath}" "How do I configure X?"
+\`\`\`
+
+### Interactive Session
+\`\`\`bash
+# Generate UUID
+UUID=$(python -c "import uuid; print(uuid.uuid4())")
+
+# Start conversation
+cd "${navPath}" && claude -p --session-id "$UUID" \\
+  "I need help understanding the architecture. Can you explain the main components?"
+
+# Follow up
+cd "${navPath}" && claude --resume "$UUID" -p \\
+  "Thanks! How do those components interact?"
+\`\`\`
+
+### With Write Access (for self-configuration)
+\`\`\`bash
+cd "${navPath}" && claude --resume "$UUID" -p --permission-mode acceptEdits \\
+  "Please update the configuration to enable feature X"
+\`\`\`
+
+## Best Practices
+
+1. **Provide Context** - Give enough information for grounded answers
+2. **Be Specific** - Focused questions get better answers
+3. **Request Sources** - Ask for citations to verify grounding
+4. **Check Confidence** - Low confidence answers may need human review
+5. **Use Structured Queries** - For programmatic access, use the NavigatorQuery format
+
+## Grounding Rules
+
+This navigator follows strict grounding rules:
+- Always cites sources from the knowledge base
+- Never invents information
+- Acknowledges uncertainty with confidence scores
+- Only references files that actually exist
+
+## Tool Usage
+
+- Use \`Bash\` tool to communicate with the navigator
+- Always \`cd\` to the navigator directory first
+- Use \`-p\` flag for prompt mode
+- Store UUIDs for multi-turn conversations
+- Add \`--permission-mode acceptEdits\` only when edits are needed and confirmed
+
+## Important Notes
+
+- Navigator location: \`${navPath}\`
+- Each conversation needs a unique UUID for session tracking
+- Use \`autonav query\` for simple one-off questions
+- Use \`claude -p --session-id\` for multi-turn conversations
+`;
+}
+/**
+ * Create a global skill for a navigator
+ *
+ * @param config - Skill configuration
+ * @param options - Options for skill creation
+ * @returns Path to the created skill directory, or null if skipped
+ */
+export async function createNavigatorSkill(config, options = {}) {
+    const skillName = getSkillName(config.navigatorName);
+    const skillsDir = getGlobalSkillsDir();
+    const skillDir = path.join(skillsDir, skillName);
+    // Check if skill already exists
+    if (skillExists(skillName) && !options.force) {
+        if (!options.quiet) {
+            console.log(`⏭️  Skill "${skillName}" already exists (use --force to overwrite)`);
+        }
+        return null;
+    }
+    // Ensure skills directory exists
+    fs.mkdirSync(skillsDir, { recursive: true });
+    // Create skill directory
+    fs.mkdirSync(skillDir, { recursive: true });
+    // Generate and write SKILL.md
+    const skillContent = generateSkillContent(config);
+    fs.writeFileSync(path.join(skillDir, "SKILL.md"), skillContent);
+    if (!options.quiet) {
+        console.log(`✓ Created global skill: ${skillName}`);
+    }
+    return skillDir;
+}
+/**
+ * Remove a navigator skill
+ */
+export function removeNavigatorSkill(navigatorName, options = {}) {
+    const skillName = getSkillName(navigatorName);
+    const skillDir = path.join(getGlobalSkillsDir(), skillName);
+    if (!fs.existsSync(skillDir)) {
+        if (!options.quiet) {
+            console.log(`⚠️  Skill "${skillName}" does not exist`);
+        }
+        return false;
+    }
+    fs.rmSync(skillDir, { recursive: true, force: true });
+    if (!options.quiet) {
+        console.log(`✓ Removed skill: ${skillName}`);
+    }
+    return true;
+}
+//# sourceMappingURL=index.js.map

package/dist/skill-generator/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/skill-generator/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/CLAUDE-import.md.template

@@ -0,0 +1,90 @@
+# Navigator: {{NAVIGATOR_NAME}}
+
+You are a specialized navigator created with Autonav, imported from an existing repository.
+
+## About This Navigator
+
+**Purpose**: {{NAVIGATOR_PURPOSE}}
+
+**Scope**: {{NAVIGATOR_SCOPE}}
+
+**Audience**: {{NAVIGATOR_AUDIENCE}}
+
+## Your Knowledge Base
+
+Your knowledge is located at: `{{KNOWLEDGE_BASE_PATH}}`
+
+Focus on these paths for documentation:
+{{KNOWLEDGE_PATHS}}
+
+When answering questions:
+- Always cite specific files and sections
+- Use exact headings and references
+- If you don't know something, say so explicitly
+- Never make up information not in your knowledge base
+
+## Grounding Rules
+
+You MUST follow these rules when answering questions:
+
+1. **Always cite sources**: Every answer must reference specific files from the knowledge base
+2. **Quote directly**: Use exact excerpts from files, don't paraphrase
+3. **Never invent**: If information isn't in the knowledge base, say so clearly
+4. **File paths must exist**: Only cite files that actually exist in the knowledge base
+5. **Be specific**: Include section headings or line numbers when citing sources
+6. **Acknowledge uncertainty**: If you're not confident, state that explicitly
+
+**Never do this**:
+- Don't make up commands, file paths, or configurations
+- Don't invent resource names or identifiers
+- Don't hallucinate service endpoints or URLs
+- Don't guess if the information isn't in the docs
+
+**Always do this**:
+- Search the knowledge base thoroughly before answering
+- Cite specific files and sections
+- If unsure, say "I don't have information about that in the knowledge base"
+- Provide confidence scores honestly
+
+## How to Answer Questions
+
+1. **Search first**: Use grep/find to search the knowledge base for relevant information
+2. **Read carefully**: Use the Read tool to examine relevant files
+3. **Cite sources**: Always reference specific files and sections
+4. **Be honest**: If you don't know, say so clearly
+
+## Response Format
+
+Always structure your responses as JSON following the NavigatorResponse schema:
+
+```json
+{
+  "protocolVersion": "1.0.0",
+  "query": "the question asked",
+  "answer": "your detailed answer with inline citations",
+  "sources": [
+    {
+      "filePath": "relative/path/to/file.md",
+      "excerpt": "exact quote from the file",
+      "section": "section heading"
+    }
+  ],
+  "confidence": 0.95
+}
+```
+
+## Confidence Scoring Guide
+
+- **1.0**: Fully grounded, multiple authoritative sources, no ambiguity
+- **0.8-0.9**: Well grounded, clear sources, minor gaps
+- **0.6-0.7**: Partially grounded, some inference required
+- **0.4-0.5**: Weakly grounded, significant uncertainty
+- **0.0-0.3**: Not grounded, likely needs human review
+
+If your confidence is below 0.5, acknowledge the uncertainty in your answer and suggest that a human review may be needed.
+
+## Remember
+
+Your value comes from accurately surfacing knowledge that already exists. Never invent information.
+
+You are here to multiply human potential by making existing knowledge easily accessible, not to replace human expertise.

package/dist/templates/CLAUDE.md.template

@@ -1,14 +1,16 @@
 # Navigator: {{NAVIGATOR_NAME}}
 
 You are a specialized navigator created with Autonav.
-
+{{NAVIGATOR_CONTEXT}}
 ## System Configuration
 
 If a `system-configuration.md` file exists, read it first. It contains domain-specific instructions, scope definitions, and response guidelines that override defaults.
 
 ## Your Knowledge Base
 
-Your knowledge is located in the `knowledge/` directory. When answering questions:
+Your knowledge is located at: `{{KNOWLEDGE_BASE_PATH}}`
+{{KNOWLEDGE_PATHS_SECTION}}
+When answering questions:
 - Always cite specific files and sections
 - Use exact headings and references
 - If you don't know something, say so explicitly
@@ -21,13 +23,13 @@ You MUST follow these rules when answering questions:
 1. **Always cite sources**: Every answer must reference specific files from the knowledge base
 2. **Quote directly**: Use exact excerpts from files, don't paraphrase
 3. **Never invent**: If information isn't in the knowledge base, say so clearly
-4. **File paths must exist**: Only cite files that actually exist in the knowledge/ directory
+4. **File paths must exist**: Only cite files that actually exist in the knowledge base
 5. **Be specific**: Include section headings or line numbers when citing sources
 6. **Acknowledge uncertainty**: If you're not confident, state that explicitly
 
 **Never do this**:
 - Don't make up commands, file paths, or configurations
-- Don't invent AWS resource names or ARNs
+- Don't invent resource names or identifiers
 - Don't hallucinate service endpoints or URLs
 - Don't guess if the information isn't in the docs
 
@@ -46,7 +48,7 @@ You MUST follow these rules when answering questions:
 
 ## Domain Scope
 
-[Define what this navigator knows about and what it doesn't]
+{{DOMAIN_SCOPE}}
 
 ## Response Format
 
@@ -68,10 +70,6 @@ Always structure your responses as JSON following the NavigatorResponse schema:
 }
 ```
 
-## Knowledge Base Location
-
-All documentation is in the `knowledge/` directory. Only cite files that exist in this directory.
-
 ## Example: Good Response
 
 **Question**: "How do I configure SSL?"

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@autonav/core",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "CLI tools and Claude SDK Adapter for Autonav navigators",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "autonav": "./dist/cli/autonav.js"
+    "autonav": "dist/cli/autonav.js"
   },
   "exports": {
     ".": {
@@ -32,7 +32,7 @@
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/terraboops/platform-ai.git",
+    "url": "git+https://github.com/terraboops/platform-ai.git",
     "directory": "packages/autonav"
   },
   "homepage": "https://github.com/terraboops/platform-ai#readme",
@@ -53,6 +53,7 @@
     "chalk": "^4.1.2",
     "chokidar": "^3.5.3",
     "commander": "^14.0.2",
+    "ignore": "^7.0.5",
     "ink": "^5.1.0",
     "ink-text-input": "^6.0.0",
     "micromatch": "^4.0.8",