docs(structure): split README into focused documentation files

- Extract troubleshooting guide to TROUBLESHOOTING.md
- Move usage examples to USAGE_EXAMPLES.md for better discoverability
- Add custom specialty creation guide to CONTRIBUTIONS.md
- Create semantic commit message generator prompt in prompts/
- Streamline README.md by removing 200+ lines of content now in dedicated files
- Improve documentation navigation with clearer separation of concerns
This commit is contained in:
nathan 2026-04-19 16:50:58 -04:00
parent 6c8955fe49
commit f596f41a01
5 changed files with 209 additions and 211 deletions

View File

@ -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
<type>(<scope>): <imperative summary (max 50 chars)>
<blank line>
- <bullet point connecting change to specific file>
- <bullet point explaining the 'why' based on session context>
<optional: Footer for BREAKING CHANGE or 'Ref: #IssueID'>

View File

@ -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

229
README.md
View File

@ -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. 🚀

50
TROUBLESHOOTING.md Normal file
View File

@ -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

67
USAGE_EXAMPLES.md Normal file
View File

@ -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]
```