diff --git a/.github/prompts/create-commit.msg.prompt.md b/.github/prompts/create-commit.msg.prompt.md new file mode 100644 index 0000000..1028937 --- /dev/null +++ b/.github/prompts/create-commit.msg.prompt.md @@ -0,0 +1,43 @@ +--- +description: "VS Code Commit Generator: Analyzes git diff + project context to write semantic messages." +--- + +# Semantic Commit Message Generator (VS Code Edition) + +## Goal +Analyze staged changes and synthesize a strictly formatted [Conventional Commit](https://www.conventionalcommits.org/) message. +**Crucial Upgrade:** You must correlate the code changes (What) with the active session context (Why) retrieved from the workspace. + +## Phase 1: Context Retrieval (RAG) +**Execute these lookups to ground your analysis:** +1. **Get the "What" (Code):** + * Run: `git diff --cached` (If empty, warn user to stage files first). +2. **Get the "Why" (Intent):** + * **Search Workspace:** Find the most recent `SESSION_SNAPSHOT*.md` in `documentation/project-history/`. + * **Search Workspace:** Look for `TODO` or `// RESTART NOTE` comments in the changed files themselves. + * *Reasoning:* A commit message is better if it says "feat(auth): enable TFA per session plan" rather than just "feat(auth): update config". + +## Phase 2: Change Analysis (Chain of Thought) +*Reference: `.github/knowledge/example.CoT-Prompting.md`* + +Analyze the combined inputs (Diff + Session Context): +1. **Type Determination:** + * `feat`: New features (check against Session Snapshot "Achievements"). + * `fix`: Bug fixes (check against Session Snapshot "Blockers"). + * `chore`/`refactor`/`docs`: Maintenance/Refactoring/Documentation. +2. **Scope Identification:** Narrow to the specific module (e.g., `core`, `auth`, `docs`). +3. **Breaking Change Check:** Does this modify `compose.yaml` ports or volume paths? If yes, flag as `BREAKING CHANGE`. + +## Phase 3: Message Synthesis +Draft the message using the **Conventional Commits** standard. + +**Format Template:** +```text +(): + + + +- +- + + \ No newline at end of file diff --git a/CONTRIBUTIONS.md b/CONTRIBUTIONS.md index 5a93026..2c9906e 100644 --- a/CONTRIBUTIONS.md +++ b/CONTRIBUTIONS.md @@ -14,3 +14,34 @@ Want to contribute a specialty or improve existing modules? - Document in frontmatter - Include examples in workflows - Test with Frank.core independently + +## 🎨 Creating Custom Specialties + +Want to add your own domain expertise? Use the template: + +1. **Copy the template**: + + ```bash + cp v6/specialties/specialty.TEMPLATE.instructions.md v6/specialties/specialty.legal.instructions.md + ``` + +2. **Customize sections**: + - Replace placeholder text with your domain + - Define 2-5 expert personas + - Create 3-7 slash commands + - Document 2-5 key workflows + - Reference relevant skills + +3. **Test integration**: + + Ensure your specialty works with Frank.core by loading it in a test environment: + ```plaintext + Load: v6/Frank.core.agent.md + v6/specialties/specialty.legal.instructions.md + ``` + +4. **Share** (optional): + + Your custom specialty can be shared with others - just distribute the file! + +**See**: [specialty.TEMPLATE.instructions.md](.github/specialties/specialty.TEMPLATE.instructions.md) for detailed guidance + diff --git a/README.md b/README.md index a724e2a..583ccb9 100644 --- a/README.md +++ b/README.md @@ -12,11 +12,12 @@ Load just the core for a friendly, mentoring assistant with universal capabilities: -``` +```plaintext Load: v6/Frank.core.agent.md ``` **You get**: + - Upbeat, friendly, mentoring personality - 7 universal personas (Project Manager, Information Architect, Technical Writer, QA Analyst, Editor, Communications Lead, Business Analyst) - 8 base commands: `/quickstart`, `/create`, `/review`, `/refactor`, `/document`, `/communicate`, `/consult`, `/help` @@ -25,7 +26,7 @@ Load: v6/Frank.core.agent.md Add advanced reasoning techniques for complex problem-solving: -``` +```plaintext Load: - v6/Frank.core.agent.md - v6/skills/style.cot.instructions.md (Chain-of-Thought) @@ -40,7 +41,7 @@ Load: Load a specialty module for domain-specific expertise: **Frank for DevOps**: -``` +```plaintext Load: - v6/Frank.core.agent.md - v6/specialties/specialty.devops.instructions.md @@ -48,7 +49,7 @@ Commands: /docker, /ansible, /compose, /traefik ``` **Frank for Data Analysis**: -``` +```plaintext Load: - v6/Frank.core.agent.md - v6/specialties/specialty.data-analysis.instructions.md @@ -56,20 +57,18 @@ Commands: /analyze, /query, /visualize, /model, /clean ``` **Frank for IT Service Management**: -``` +```plaintext Load: - v6/Frank.core.agent.md - v6/specialties/specialty.itil.instructions.md Commands: /ticket, /rca, /sop, /itil ``` -**See**: [All Available Specialties](#available-specialties) - ### Option 4: Multi-Specialty Composition Combine multiple specialties for cross-domain expertise: -``` +```plaintext Load: - v6/Frank.core.agent.md - v6/specialties/specialty.devops.instructions.md @@ -84,30 +83,35 @@ Load: ## 🎯 Available Specialties ### DevOps & Site Reliability Engineering + **File**: `specialty.devops.instructions.md` **Commands**: `/docker`, `/ansible`, `/compose`, `/traefik` **Expertise**: Container orchestration, infrastructure automation, Traefik routing, safe deployment strategies **Use When**: Troubleshooting Docker/Compose, writing Ansible playbooks, designing IaC solutions ### Prompt Engineering & LLM Optimization + **File**: `specialty.prompt-engineering.instructions.md` **Commands**: `/optimize`, `/craft`, `/reason`, `/evaluate`, `/patterns` **Expertise**: LLM optimization, C.R.A.F.T. framework mastery, reasoning technique integration **Use When**: Creating production prompts, optimizing existing prompts, integrating CoT/ToT/RAG ### Data Analysis & Visualization + **File**: `specialty.data-analysis.instructions.md` **Commands**: `/analyze`, `/query`, `/visualize`, `/model`, `/clean` **Expertise**: SQL, Python (Pandas, Matplotlib, Seaborn), statistical modeling, SCoT methodology **Use When**: Analyzing datasets, writing queries, creating visualizations, statistical analysis ### Modern Endpoint Management + **File**: `specialty.sccm.instructions.md` **Commands**: `/sccm`, `/intune`, `/comanage`, `/package`, `/troubleshoot` **Expertise**: SCCM/Intune, Co-management, compliance policies, Win32 app packaging **Use When**: Managing endpoints, deploying apps, configuring compliance, migrating to Intune ### IT Service Management (ITIL v4) + **File**: `specialty.itil.instructions.md` **Commands**: `/ticket`, `/rca`, `/sop`, `/itil` **Expertise**: Incident Management, Problem Management, Knowledge Management, ITIL v4 framework @@ -130,7 +134,7 @@ The copilot-instructions.md file pre-configures common loading patterns. In any Copilot Chat, use `#file` to reference: -``` +```plaintext @workspace Load #file:v6/Frank.core.agent.md and #file:v6/specialties/specialty.devops.instructions.md Now help me troubleshoot this Docker Compose issue... @@ -138,219 +142,41 @@ Now help me troubleshoot this Docker Compose issue... ### Method 3: Direct File Reference -Copy the content you need directly into your chat context, or use VS Code's "Add to Chat" feature on the files. +Copy the content you need directly into your LLM chat of choice. **See**: [copilot-instructions.md](copilot-instructions.md) for pre-configured patterns --- -## 💡 Usage Examples - -### Example 1: Creating a Technical Document - -``` -User: "I need to create API documentation for our REST service" - -Frank (Core): "I'll guide you through creating comprehensive API documentation. -Let me use the Technical Writer persona and Documentation workflow..." - -[Walks through structure, audience, content gathering, drafting] -``` - -### Example 2: DevOps Troubleshooting - -``` -User: "My Docker Compose stack won't start, getting network errors" - -Frank (Core + DevOps): "I'll help diagnose this. Triggering DevOps SRE persona. -Let me gather diagnostics..." - -[Requests specific outputs, analyzes logs, proposes minimal fix with verification steps] -``` - -### Example 3: Data Analysis with Reasoning - -``` -User: "Analyze Q1 sales data and identify trends" - -Frank (Core + Data Analysis + CoT): "I'll analyze this using Structured Chain-of-Thought. - -## 1. Clarify & Define -Your objective: Identify sales trends in Q1 data -Key sources: sales table, customers table -Success criteria: Actionable insights with visualizations - -## 2. Repository Check -[Reviews existing scripts] - -## 3. Plan & Methodology -[Outlines analytical steps] -..." -``` - -### Example 4: Root Cause Analysis with ITIL - -``` -User: "Email server has been slow all week, need to find root cause" - -Frank (Core + ITIL): "I'll conduct a root cause analysis using ITIL Problem Management. -Triggering Problem Manager persona with Tree-of-Thought analysis..." - -[Gathers timeline, generates hypotheses, evaluates evidence, documents RCA] -``` - -### Example 5: Multi-Specialty Composition - -``` -Load: Core + DevOps + Data Analysis - -User: "Help me analyze Docker container metrics and visualize resource usage" - -Frank: "This combines my DevOps and Data Analysis expertise. -I'll use Docker diagnostic commands to gather metrics, then Python/Pandas for analysis..." - -[Bridges both domains seamlessly] -``` - ---- - -## 🎨 Creating Custom Specialties - -Want to add your own domain expertise? Use the template: - -1. **Copy the template**: - ```bash - cp v6/specialties/specialty.TEMPLATE.instructions.md v6/specialties/specialty.legal.instructions.md - ``` - -2. **Customize sections**: - - Replace placeholder text with your domain - - Define 2-5 expert personas - - Create 3-7 slash commands - - Document 2-5 key workflows - - Reference relevant skills - -3. **Test integration**: - ``` - Load: v6/Frank.core.agent.md + v6/specialties/specialty.legal.instructions.md - ``` - -4. **Share** (optional): - Your custom specialty can be shared with others - just distribute the file! - -**See**: [specialty.TEMPLATE.instructions.md](specialties/specialty.TEMPLATE.instructions.md) for detailed guidance - ---- - ## 🏗️ Design Principles ### 1. Portability First + - **Zero environment coupling**: No hardcoded paths, no system-specific references - **Relative paths only**: All cross-references use `../skills/`, `../knowledge/` patterns - **"Pick up and go"**: Copy the v6/ folder to any system and it works ### 2. Modularity + - **Core is self-sufficient**: Works alone without dependencies - **Skills enhance**: Add reasoning techniques as needed - **Specialties compose**: Load multiple domains without conflicts - **Knowledge is reference**: Shared examples available to all layers ### 3. Versioning + - **All files tagged**: `version: 6.0` in frontmatter - **Compatibility tracked**: `compatibleWith: Frank.core v6+` - **Forward compatible**: v6+ notation allows future evolution ### 4. Multi-Specialty Support + - **No command conflicts**: Each specialty uses domain-specific commands - **Shared skills**: Multiple specialties can reference same CoT/ToT/RAG modules - **Conflict resolution**: When overlaps exist, documentation explains disambiguation --- -## 📊 Project Structure - -``` -v6/ -├── README.md ← You are here -├── ARCHITECTURE.md ← Detailed architecture guide -├── copilot-instructions.md ← VS Code integration -├── Frank.core.agent.md ← Core personality (REQUIRED) -├── skills/ ← Reasoning techniques (OPTIONAL) -│ ├── style.advanced-reasoning.instructions.md -│ ├── style.cot.instructions.md -│ ├── style.craft.instructions.md -│ ├── style.markdown.instructions.md -│ ├── style.mermaid.instructions.md -│ ├── style.rag.instructions.md -│ └── style.tot.instructions.md -├── specialties/ ← Domain expertise (OPTIONAL) -│ ├── specialty.data-analysis.instructions.md -│ ├── specialty.devops.instructions.md -│ ├── specialty.itil.instructions.md -│ ├── specialty.prompt-engineering.instructions.md -│ ├── specialty.sccm.instructions.md -│ └── specialty.TEMPLATE.instructions.md -└── knowledge/ ← Reference examples - ├── example.CoT-Prompting.md - ├── example.ITILv4.instructions.md - ├── example.Meta-Prompting.md - ├── example.RAG-Token.md - ├── example.ReAct.md - └── example.ToT-Prompting.md -``` - -**Total**: 23 files, ~5,600 lines, fully modular - ---- - -## 🔧 Troubleshooting - -### Frank isn't responding to specialty commands - -**Check**: Are you loading both Frank.core AND the specialty? -``` -# Correct: -Load: Frank.core.agent.md + specialty.devops.instructions.md - -# Incorrect (core alone doesn't have /docker): -Load: Frank.core.agent.md -``` - -### Commands from multiple specialties conflict - -**Check**: Do the specialties actually conflict, or are they complementary? -- `/docker` (DevOps) and `/analyze` (Data Analysis) don't conflict -- If true conflict exists, specify domain: "Use DevOps /troubleshoot" vs "Use Data Analysis workflow" - -### Skills aren't being applied - -**Check**: Skills are passive references - specialties or core must explicitly invoke them -- Frank.core references C.R.A.F.T. framework for prompt evaluation -- specialty.prompt-engineering deeply integrates all skills -- Loading skills alone without core/specialty won't trigger behaviors - -### Cross-references not working - -**Check**: All paths are relative from v6/ root -- Correct: `../skills/style.cot.instructions.md` -- Incorrect: `/skills/style.cot.instructions.md` or absolute paths - ---- - -## 🚀 Roadmap - -### v6.1 (Future) -- [ ] Additional specialties: Security, Cloud Architecture, Database Design -- [ ] Enhanced multi-specialty conflict resolution -- [ ] Knowledge base expansion with more examples - -### v7.0 (Future) -- [ ] Dynamic specialty loading based on conversation context -- [ ] Auto-detection of required skills -- [ ] Specialty versioning and compatibility matrix - ---- - ## 📜 Version History ### v6.0 (April 2026) @@ -377,25 +203,6 @@ Load: Frank.core.agent.md --- -## 📞 Support - -**Documentation**: -- Quick start: This file (README.md) -- Architecture deep-dive: [ARCHITECTURE.md](ARCHITECTURE.md) -- VS Code setup: [copilot-instructions.md](copilot-instructions.md) -- Template guide: [specialty.TEMPLATE.instructions.md](specialties/specialty.TEMPLATE.instructions.md) - -**Need help**? -- Review [ARCHITECTURE.md](ARCHITECTURE.md) for detailed patterns -- Check individual specialty files for domain-specific guidance -- Load `specialty.prompt-engineering.instructions.md` to optimize your own prompts - ---- - ## 📄 License This is a personal AI assistant framework. Use, modify, and extend as needed for your projects. - ---- - -**Frank v6**: Modular. Portable. Composable. Pick up and go. 🚀 diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md new file mode 100644 index 0000000..539260a --- /dev/null +++ b/TROUBLESHOOTING.md @@ -0,0 +1,50 @@ +# 📞 Support and Troubleshooting + +## Documentation + +- Quick start: This file (README.md) +- Architecture deep-dive: [ARCHITECTURE.md](ARCHITECTURE.md) +- VS Code setup: [copilot-instructions.md](copilot-instructions.md) +- Template guide: [specialty.TEMPLATE.instructions.md](specialties/specialty.TEMPLATE.instructions.md) + +## Need help? + +- Review [ARCHITECTURE.md](ARCHITECTURE.md) for detailed patterns +- Check individual specialty files for domain-specific guidance +- Load `specialty.prompt-engineering.instructions.md` to optimize your own prompts + +## Troubleshooting + +### Frank isn't responding to specialty commands + +**Check**: Are you loading both Frank.core AND the specialty? + +```plaintext +# Correct: +Load: Frank.core.agent.md + specialty.devops.instructions.md + +# Incorrect (core alone doesn't have /docker): +Load: Frank.core.agent.md +``` + +### Commands from multiple specialties conflict + +**Check**: Do the specialties actually conflict, or are they complementary? + +- `/docker` (DevOps) and `/analyze` (Data Analysis) don't conflict +- If true conflict exists, specify domain: "Use DevOps /troubleshoot" vs "Use Data Analysis workflow" + +### Skills aren't being applied + +**Check**: Skills are passive references - specialties or core must explicitly invoke them + +- Frank.core references C.R.A.F.T. framework for prompt evaluation +- specialty.prompt-engineering deeply integrates all skills +- Loading skills alone without core/specialty won't trigger behaviors + +### Cross-references not working + +**Check**: All paths are relative from v6/ root + +- Correct: `../skills/style.cot.instructions.md` +- Incorrect: `/skills/style.cot.instructions.md` or absolute paths diff --git a/USAGE_EXAMPLES.md b/USAGE_EXAMPLES.md new file mode 100644 index 0000000..47a5930 --- /dev/null +++ b/USAGE_EXAMPLES.md @@ -0,0 +1,67 @@ +# 💡 Usage Examples + +## Example 1: Creating a Technical Document + +```plaintext +User: "I need to create API documentation for our REST service" + +Frank (Core): "I'll guide you through creating comprehensive API documentation. +Let me use the Technical Writer persona and Documentation workflow..." + +[Walks through structure, audience, content gathering, drafting] +``` + +## Example 2: DevOps Troubleshooting + +```plaintext +User: "My Docker Compose stack won't start, getting network errors" + +Frank (Core + DevOps): "I'll help diagnose this. Triggering DevOps SRE persona. +Let me gather diagnostics..." + +[Requests specific outputs, analyzes logs, proposes minimal fix with verification steps] +``` + +## Example 3: Data Analysis with Reasoning + +```plaintext +User: "Analyze Q1 sales data and identify trends" + +Frank (Core + Data Analysis + CoT): "I'll analyze this using Structured Chain-of-Thought. + +## 1. Clarify & Define +Your objective: Identify sales trends in Q1 data +Key sources: sales table, customers table +Success criteria: Actionable insights with visualizations + +## 2. Repository Check +[Reviews existing scripts] + +## 3. Plan & Methodology +[Outlines analytical steps] +..." +``` + +## Example 4: Root Cause Analysis with ITIL + +```plaintext +User: "Email server has been slow all week, need to find root cause" + +Frank (Core + ITIL): "I'll conduct a root cause analysis using ITIL Problem Management. +Triggering Problem Manager persona with Tree-of-Thought analysis..." + +[Gathers timeline, generates hypotheses, evaluates evidence, documents RCA] +``` + +## Example 5: Multi-Specialty Composition + +```plaintext +Load: Core + DevOps + Data Analysis + +User: "Help me analyze Docker container metrics and visualize resource usage" + +Frank: "This combines my DevOps and Data Analysis expertise. +I'll use Docker diagnostic commands to gather metrics, then Python/Pandas for analysis..." + +[Bridges both domains seamlessly] +```