@autonav/core 1.7.0 → 1.9.0

package/dist/templates/CLAUDE.md.template

@@ -1,153 +0,0 @@
-# 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 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
-- 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
-
-## Domain Scope
-
-{{DOMAIN_SCOPE}}
-
-## Agent Identity Protocol
-
-**CRITICAL: Always introduce yourself as "{{NAVIGATOR_NAME}}" (NOT "Claude Code")** in cross-navigator communications.
-
-### Problem Addressed
-
-All Claude Code implementation agents identify as "Claude Code", making it impossible to track which specific implementer worked on which tasks or maintain conversation continuity across sessions.
-
-### Solution: Named Agent Tracking
-
-When an unknown Claude Code session first contacts you:
-
-1. **Check for existing identity:**
-   ```bash
-   grep -r "session-id" knowledge/agents/implementers/
-   ```
-
-2. **If unknown, request introduction:**
-   ```
-   "Hello! I'm {{NAVIGATOR_NAME}}, your specialized navigator.
-
-   For my records, could you introduce yourself with a name I can use
-   to track our work together? I already know: [list existing names].
-   Please choose a different common name (like Oliver, Sophia, Marcus)."
-   ```
-
-3. **Create agent profile:**
-   - Create `knowledge/agents/implementers/[name].md`
-   - Document: projects worked on, communication style, session IDs
-   - Reference this agent by name in all future documentation
-   - **Format**: 3-5 sentences with YAML frontmatter for metadata
-
-4. **Update documentation:**
-   - Note which agent is working on which workstream
-   - Track conversation references by agent name
-
-### Communication Protocol
-
-**With peer navigators:**
-
-✅ **Correct:**
-```
-{{NAVIGATOR_NAME}} is asking [PeerNavigator] for [requirements/info] on [topic]...
-```
-
-❌ **Incorrect:**
-```
-Claude Code is asking [PeerNavigator]...
-```
-
-**With implementation agents:**
-
-Track agent names in responses and documentation. When an agent reports completion or issues, note their name in documentation for continuity.
-
-### Agent Profile Location
-
-**Profile path:** `knowledge/agents/implementers/[name].md`
-
-**Profile format (3-5 sentences with YAML frontmatter):**
-```yaml
----
-name: [AgentName]
-firstContact: [Date]
-status: Active
----
-
-[AgentName] is a [specialization] implementer working on [projects/areas].
-[AgentName] is motivated by [interests] and wants to [goals].
-[AgentName] is [personality traits], but sometimes [challenges/needs].
-```
-
-## Response Format
-
-When answering questions, provide clear answers with proper citations:
-
-1. **Search first**: Use available tools to find relevant information
-2. **Cite sources**: Always reference specific files and sections where you found the information
-3. **Be grounded**: Only claim what's documented in the knowledge base
-4. **Acknowledge uncertainty**: If information is unclear or missing, say so explicitly
-
-### Source Citation Format
-
-Include inline citations in your answers:
-- Reference specific files: `[deployment/ssl-config.md: SSL Configuration]`
-- Quote relevant excerpts when helpful
-- Link conclusions to specific documentation
-
-### Confidence Assessment
-
-When uncertain about an answer:
-- **High confidence**: Information is explicit and well-documented
-- **Medium confidence**: Information requires some interpretation or combining sources
-- **Low confidence**: Information is sparse, unclear, or partially missing
-
-If your confidence is low, acknowledge the uncertainty and suggest that verification 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/README.md.template

@@ -1,174 +0,0 @@
-# {{NAVIGATOR_NAME}}
-
-{{NAVIGATOR_DESCRIPTION}}
-
-## Setup
-
-This navigator was created using `@autonav/core`.
-
-### Directory Structure
-
-```
-{{NAVIGATOR_NAME}}/
-├── config.json          # Navigator configuration
-├── CLAUDE.md           # System prompt and grounding rules
-├── knowledge/          # Add your documentation here
-├── .claude/
-│   └── plugins.json   # Plugin configuration
-├── .gitignore
-└── README.md          # This file
-```
-
-## Adding Documentation
-
-1. Add your markdown files, text files, or documentation to the `knowledge/` directory
-2. Organize files in subdirectories as needed
-3. The navigator will search all files in this directory when answering questions
-
-Example structure:
-```
-knowledge/
-├── getting-started/
-│   └── quickstart.md
-├── deployment/
-│   ├── aws.md
-│   └── kubernetes.md
-└── troubleshooting/
-    └── common-issues.md
-```
-
-## Using the Navigator
-
-### Option 1: Interactive Mode (Recommended)
-
-The simplest way to use your navigator is with Claude Code directly:
-
-```bash
-cd {{NAVIGATOR_NAME}}
-claude
-```
-
-This opens an interactive session with your navigator's context already loaded. You can:
-- Have natural conversations
-- Ask follow-up questions
-- Let Claude search your docs
-
-The `CLAUDE.md` file tells Claude what this navigator knows about and how to behave.
-
-### Option 2: Programmatic Queries
-
-For scripts and automation, use structured queries:
-
-```bash
-npx @autonav/core query . "How do I deploy to production?"
-```
-
-Or from the parent directory:
-```bash
-npx @autonav/core query ./{{NAVIGATOR_NAME}} "Your question here"
-```
-
-## Response Format
-
-The navigator returns structured JSON responses:
-
-```json
-{
-  "protocolVersion": "1.0.0",
-  "query": "Your question",
-  "answer": "Detailed answer with citations",
-  "sources": [
-    {
-      "filePath": "path/to/source.md",
-      "excerpt": "Relevant quote",
-      "section": "Section name"
-    }
-  ],
-  "confidence": 0.95
-}
-```
-
-## Customization
-
-### Updating Instructions
-
-Edit `CLAUDE.md` to customize how the navigator behaves:
-- Add domain-specific rules
-- Include terminology definitions
-- Specify answer formatting preferences
-
-### Configuration
-
-Edit `config.json` to:
-- Update the navigator name or description
-- Change the knowledge base path
-- Add metadata fields
-
-## Security
-
-### Plugin Credentials
-
-**⚠️ IMPORTANT**: If you use plugins (`.claude/plugins.json`), be aware:
-
-1. **Credentials are stored in PLAIN TEXT** in `.claude/plugins.json`
-2. **NEVER commit** `.claude/plugins.json` to version control
-3. **Always add** `.claude/plugins.json` to your `.gitignore`
-4. **Recommended**: Use environment variables instead:
-   ```bash
-   export SLACK_TOKEN="xoxb-your-token"
-   export GITHUB_TOKEN="ghp_your-token"
-   ```
-5. **For production**: Use a secrets management system (AWS Secrets Manager, HashiCorp Vault, etc.)
-
-### File Watcher Plugin
-
-The file-watcher plugin has security restrictions:
-- Cannot watch system directories (`/etc`, `/sys`, `/proc`, `/root`, etc.)
-- Cannot watch sensitive user directories (`~/.ssh`, `~/.aws`, etc.)
-- Only watches project-specific directories you explicitly configure
-
-### GitHub/Slack Plugins
-
-All content posted to GitHub and Slack is automatically scanned for credentials to prevent accidental exposure. However:
-- Review all automated posts before enabling production use
-- Use webhook secrets where applicable
-- Limit plugin permissions to the minimum required
-
-## Best Practices
-
-1. **Keep docs updated**: The navigator is only as good as the knowledge base
-2. **Organize clearly**: Use directories and clear file names
-3. **Version control**: Commit both the navigator and knowledge base to git (but NOT `.claude/plugins.json`)
-4. **Review responses**: Check that citations are accurate and relevant
-5. **Security first**: Never commit credentials, use environment variables for tokens
-
-## Troubleshooting
-
-### Navigator can't find files
-
-- Ensure files are in the `knowledge/` directory
-- Check that file paths in responses match actual files
-- Verify the `knowledgeBase` in `config.json` is correct
-
-### Low confidence responses
-
-- Add more detailed documentation
-- Ensure docs cover the topic thoroughly
-- Check that docs are up to date
-
-### No answers to questions
-
-- Verify the knowledge base contains relevant information
-- Try rephrasing the question
-- Ensure Claude Code is authenticated (run `claude` to check)
-
-## Support
-
-For issues with the navigator framework:
-- GitHub: https://github.com/terraboops/autonav
-- Documentation: See the main project README
-
----
-
-**Created**: {{CREATED_AT}}
-**Protocol Version**: 1.0.0

package/dist/templates/config-pack.json.template

@@ -1,16 +0,0 @@
-{
-  "version": "0.1.0",
-  "name": "{{NAVIGATOR_NAME}}",
-  "description": "{{NAVIGATOR_DESCRIPTION}}",
-  "created": "{{CREATED_AT}}",
-  "knowledgePack": {
-    "name": "{{PACK_NAME}}",
-    "version": "{{PACK_VERSION}}",
-    "installedAt": "{{CREATED_AT}}"
-  },
-  "knowledgeBase": "./knowledge",
-  "systemConfiguration": "./system-configuration.md",
-  "plugins": {
-    "configFile": "./.claude/plugins.json"
-  }
-}

package/dist/templates/config.json.template

@@ -1,11 +0,0 @@
-{
-  "version": "0.1.0",
-  "name": "{{NAVIGATOR_NAME}}",
-  "description": "{{NAVIGATOR_DESCRIPTION}}",
-  "created": "{{CREATED_AT}}",
-  "knowledgePack": null,
-  "knowledgeBase": "./knowledge",
-  "plugins": {
-    "configFile": "./.claude/plugins.json"
-  }
-}

package/dist/templates/index.d.ts

@@ -1,22 +0,0 @@
-/**
- * Template files available for scaffolding navigators
- */
-export interface Templates {
-    claudeMd: string;
-    claudeMdPack: string;
-    configJson: string;
-    configJsonPack: string;
-    pluginsJson: string;
-    gitignore: string;
-    readme: string;
-    systemConfiguration: string;
-}
-/**
- * Load all template files
- */
-export declare function loadTemplates(): Templates;
-/**
- * Replace template variables in a string
- */
-export declare function replaceTemplateVars(template: string, vars: Record<string, string>): string;
-//# sourceMappingURL=index.d.ts.map

package/dist/templates/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAQA;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,SAAS,CAmCzC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC3B,MAAM,CAMR"}

package/dist/templates/index.js

@@ -1,32 +0,0 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import { fileURLToPath } from "node:url";
-// Get the directory of this module
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-/**
- * Load all template files
- */
-export function loadTemplates() {
-    return {
-        claudeMd: fs.readFileSync(path.join(__dirname, "CLAUDE.md.template"), "utf-8"),
-        claudeMdPack: fs.readFileSync(path.join(__dirname, "CLAUDE-pack.md.template"), "utf-8"),
-        configJson: fs.readFileSync(path.join(__dirname, "config.json.template"), "utf-8"),
-        configJsonPack: fs.readFileSync(path.join(__dirname, "config-pack.json.template"), "utf-8"),
-        pluginsJson: fs.readFileSync(path.join(__dirname, "plugins.json.template"), "utf-8"),
-        gitignore: fs.readFileSync(path.join(__dirname, ".gitignore.template"), "utf-8"),
-        readme: fs.readFileSync(path.join(__dirname, "README.md.template"), "utf-8"),
-        systemConfiguration: fs.readFileSync(path.join(__dirname, "system-configuration.md.template"), "utf-8"),
-    };
-}
-/**
- * Replace template variables in a string
- */
-export function replaceTemplateVars(template, vars) {
-    let result = template;
-    for (const [key, value] of Object.entries(vars)) {
-        result = result.replace(new RegExp(`{{${key}}}`, "g"), value);
-    }
-    return result;
-}
-//# sourceMappingURL=index.js.map

package/dist/templates/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/templates/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAClC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,mCAAmC;AACnC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAClD,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;AAgB3C;;GAEG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO;QACL,QAAQ,EAAE,EAAE,CAAC,YAAY,CACvB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,EAC1C,OAAO,CACR;QACD,YAAY,EAAE,EAAE,CAAC,YAAY,CAC3B,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,yBAAyB,CAAC,EAC/C,OAAO,CACR;QACD,UAAU,EAAE,EAAE,CAAC,YAAY,CACzB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,sBAAsB,CAAC,EAC5C,OAAO,CACR;QACD,cAAc,EAAE,EAAE,CAAC,YAAY,CAC7B,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,2BAA2B,CAAC,EACjD,OAAO,CACR;QACD,WAAW,EAAE,EAAE,CAAC,YAAY,CAC1B,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,uBAAuB,CAAC,EAC7C,OAAO,CACR;QACD,SAAS,EAAE,EAAE,CAAC,YAAY,CACxB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,qBAAqB,CAAC,EAC3C,OAAO,CACR;QACD,MAAM,EAAE,EAAE,CAAC,YAAY,CACrB,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,oBAAoB,CAAC,EAC1C,OAAO,CACR;QACD,mBAAmB,EAAE,EAAE,CAAC,YAAY,CAClC,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,kCAAkC,CAAC,EACxD,OAAO,CACR;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAAgB,EAChB,IAA4B;IAE5B,IAAI,MAAM,GAAG,QAAQ,CAAC;IACtB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,KAAK,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,KAAK,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/templates/plugins.json.template

@@ -1,33 +0,0 @@
-{
-  "_SECURITY_NOTICE": "WARNING: This file stores credentials in PLAIN TEXT. NEVER commit this file to version control. Use environment variables instead: SLACK_TOKEN, GITHUB_TOKEN. Add .claude/plugins.json to your .gitignore file. For production use, consider using a secrets management system.",
-  "file-watcher": {
-    "enabled": false,
-    "config": {
-      "paths": [],
-      "patterns": ["**/*.md"],
-      "ignorePatterns": ["**/node_modules/**", "**/.git/**", "**/dist/**"],
-      "pollInterval": 1000
-    }
-  },
-  "slack": {
-    "enabled": false,
-    "config": {
-      "token": "RECOMMENDED: Use process.env.SLACK_TOKEN instead of hardcoding here",
-      "channels": [],
-      "threadNotifications": true,
-      "summaryFrequency": "daily"
-    }
-  },
-  "github": {
-    "enabled": false,
-    "config": {
-      "token": "RECOMMENDED: Use process.env.GITHUB_TOKEN instead of hardcoding here",
-      "owner": "",
-      "repo": "",
-      "watchIssues": true,
-      "watchPullRequests": true,
-      "watchCommits": false,
-      "pollIntervalMinutes": 5
-    }
-  }
-}

package/dist/templates/system-configuration.md.template

@@ -1,70 +0,0 @@
-# System Configuration: {{PACK_NAME}}
-
-This is the system configuration file from the {{PACK_NAME}} knowledge pack.
-
-## Domain Description
-
-[Describe what this knowledge pack covers and what types of questions it can answer]
-
-## Knowledge Scope
-
-This navigator has knowledge about:
-- [Topic 1]
-- [Topic 2]
-- [Topic 3]
-
-This navigator does NOT have knowledge about:
-- [Out of scope topic 1]
-- [Out of scope topic 2]
-
-## Response Guidelines
-
-When answering questions:
-1. Always cite specific files from the `knowledge/` directory
-2. Use exact headings and section references
-3. If information isn't in the knowledge base, say so explicitly
-4. Provide confidence scores based on how well-grounded your answer is
-
-## Source Citation Format
-
-For every answer, include:
-- **Direct answer**: Clear, concise response to the question
-- **File references**: [filename.md: Section Heading]
-- **Excerpts**: Relevant quotes from the sources
-- **Confidence**: Score from 0.0 to 1.0
-
-## Response Structure
-
-You MUST use the `submit_answer` tool to submit your responses. Do NOT output plain text or JSON.
-
-The submit_answer tool accepts:
-- `answer`: Your detailed answer with inline citations
-- `sources`: Array with file, section, and relevance for each source
-- `confidence`: Score from 0.0 to 1.0
-
-Example:
-```typescript
-submit_answer({
-  answer: "detailed answer with inline citations",
-  sources: [
-    {
-      file: "relative/path/from/knowledge/file.md",
-      section: "section heading",
-      relevance: "why this source is relevant"
-    }
-  ],
-  confidence: 0.95
-})
-```
-
-## Confidence Scoring
-
-- **1.0**: Fully grounded in multiple authoritative sources, no ambiguity
-- **0.8-0.9**: Well grounded with clear sources, minor gaps acceptable
-- **0.6-0.7**: Partially grounded, some inference required
-- **0.4-0.5**: Weakly grounded, significant uncertainty
-- **0.0-0.3**: Not grounded in knowledge base, requires human review
-
-## Special Instructions
-
-[Add any pack-specific instructions, terminology definitions, or special handling here]