575 lines
14 KiB
Markdown
575 lines
14 KiB
Markdown
# Support Team Guide
|
|
|
|
## Innovation Content: Educational Content Development Modes & Skills
|
|
|
|
**Version:** 1.1.0
|
|
**Audience:** Support Team, System Administrators, Technical Leads
|
|
**Date:** 2026-04-24
|
|
|
|
---
|
|
|
|
## 1. Introduction
|
|
|
|
This guide provides the support team with precise instructions for installing, configuring, troubleshooting, and extending the Innovation Content modes and skills for Roo Code.
|
|
|
|
---
|
|
|
|
## 2. Prerequisites
|
|
|
|
### 2.1 System Requirements
|
|
|
|
| Component | Requirement |
|
|
|-----------|-------------|
|
|
| Roo Code | Version 3.8 or later |
|
|
| Node.js | Version 18.x or later (for validation scripts) |
|
|
| Git | Version 2.30 or later |
|
|
| Operating System | Windows 10/11, macOS 12+, Linux (Ubuntu 20.04+) |
|
|
|
|
### 2.2 Required Permissions
|
|
|
|
- Read/write access to the project workspace
|
|
- Ability to modify `.roomodes` configuration file
|
|
- Access to `.agents/skills/` directory
|
|
- Browser access (for Content Producer and LX Designer modes)
|
|
|
|
---
|
|
|
|
## 3. Installation
|
|
|
|
### 3.1 Clone Repository
|
|
|
|
```bash
|
|
git clone https://archi.pinion.education/PinionEducation/pinion-modes-skills.git innovation-content
|
|
cd innovation-content
|
|
```
|
|
|
|
### 3.2 Install Modes
|
|
|
|
**Option A: Manual Installation**
|
|
|
|
Copy each mode configuration to your Roo Code `.roomodes` file:
|
|
|
|
```bash
|
|
# On Windows (cmd.exe)
|
|
copy innovation-content\modes\curriculum-designer\mode-config.yaml %USERPROFILE%\.roo\modes\
|
|
copy innovation-content\modes\instructional-writer\mode-config.yaml %USERPROFILE%\.roo\modes\
|
|
copy innovation-content\modes\assessment-dev\mode-config.yaml %USERPROFILE%\.roo\modes\
|
|
copy innovation-content\modes\content-producer\mode-config.yaml %USERPROFILE%\.roo\modes\
|
|
copy innovation-content\modes\lx-designer\mode-config.yaml %USERPROFILE%\.roo\modes\
|
|
copy innovation-content\modes\accessibility-auditor\mode-config.yaml %USERPROFILE%\.roo\modes\
|
|
```
|
|
|
|
```bash
|
|
# On macOS/Linux
|
|
cp innovation-content/modes/*/mode-config.yaml ~/.roo/modes/
|
|
```
|
|
|
|
**Option B: Automated Installation**
|
|
|
|
```bash
|
|
# Run the installation script (if available)
|
|
./scripts/install-modes.sh
|
|
```
|
|
|
|
### 3.3 Install Rules
|
|
|
|
Copy XML rule files to the appropriate rules directory for each mode:
|
|
|
|
```bash
|
|
# On Windows (cmd.exe)
|
|
for %m in (curriculum-designer instructional-writer assessment-dev content-producer lx-designer accessibility-auditor) do (
|
|
xcopy /E /I innovation-content\modes\%m\rules %USERPROFILE%\.roo\rules-%m\
|
|
)
|
|
```
|
|
|
|
```bash
|
|
# On macOS/Linux
|
|
for mode in curriculum-designer instructional-writer assessment-dev content-producer lx-designer accessibility-auditor; do
|
|
mkdir -p ~/.roo/rules-$mode
|
|
cp innovation-content/modes/$mode/rules/*.xml ~/.roo/rules-$mode/
|
|
done
|
|
```
|
|
|
|
### 3.4 Install Skills
|
|
|
|
Copy all skill directories to your skills folder:
|
|
|
|
```bash
|
|
# On Windows (cmd.exe)
|
|
xcopy /E /I innovation-content\skills %USERPROFILE%\.agents\skills\
|
|
```
|
|
|
|
```bash
|
|
# On macOS/Linux
|
|
cp -r innovation-content/skills/* ~/.agents/skills/
|
|
```
|
|
|
|
### 3.5 Verify Installation
|
|
|
|
1. Open Roo Code
|
|
2. Switch to each mode and verify it loads without errors:
|
|
- `curriculum-designer`
|
|
- `instructional-writer`
|
|
- `assessment-dev`
|
|
- `content-producer`
|
|
- `lx-designer`
|
|
- `accessibility-auditor`
|
|
3. Test a skill invocation in each mode
|
|
|
|
---
|
|
|
|
## 4. Configuration
|
|
|
|
### 4.1 Mode Configuration Structure
|
|
|
|
Each mode configuration file (`mode-config.yaml`) follows this structure:
|
|
|
|
```yaml
|
|
name: "Mode Display Name"
|
|
slug: "mode-slug"
|
|
roleDefinition: "Detailed description of what this mode does"
|
|
whenToUse: "Guidance on when to activate this mode"
|
|
permissions:
|
|
fileRestrictions:
|
|
- "patterns/*.md"
|
|
- "directory/**/*"
|
|
allowedCommands:
|
|
- "command-name"
|
|
browserAccess: true/false
|
|
customInstructions: |
|
|
Additional instructions for mode behavior
|
|
```
|
|
|
|
### 4.2 Skill Configuration Structure
|
|
|
|
Each skill file (`SKILL.md`) follows this structure:
|
|
|
|
```yaml
|
|
---
|
|
name: skill-name
|
|
description: Brief description of the skill
|
|
---
|
|
|
|
# Skill Name
|
|
|
|
## Capabilities
|
|
- Capability 1
|
|
- Capability 2
|
|
|
|
## Usage
|
|
When and how to use this skill
|
|
|
|
## Input
|
|
Expected input format
|
|
|
|
## Output
|
|
Expected output format
|
|
|
|
## Limitations
|
|
Known limitations
|
|
|
|
## Assumptions
|
|
Assumptions made by this skill
|
|
```
|
|
|
|
### 4.3 Customizing Permissions
|
|
|
|
To modify file permissions for a mode, edit the `mode-config.yaml` file:
|
|
|
|
```yaml
|
|
permissions:
|
|
fileRestrictions:
|
|
- "custom-directory/**/*"
|
|
- "*.custom-extension"
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Troubleshooting
|
|
|
|
### 5.1 Common Issues
|
|
|
|
| Issue | Cause | Resolution |
|
|
|-------|-------|------------|
|
|
| Mode not appearing in Roo Code | Configuration not copied | Verify `.roomodes` file contains mode entry |
|
|
| Skill not found | Skill not in correct directory | Check `~/.agents/skills/skill-name/SKILL.md` exists |
|
|
| Permission denied | File restriction too narrow | Update `fileRestrictions` in mode-config.yaml |
|
|
| XML parsing error | Malformed XML | Validate XML with `xmllint` or online validator |
|
|
| YAML parsing error | Invalid YAML syntax | Validate YAML with `yamllint` or online validator |
|
|
|
|
### 5.2 Diagnostic Commands
|
|
|
|
```bash
|
|
# Validate all YAML files
|
|
find . -name "*.yaml" -exec yamllint {} \;
|
|
|
|
# Validate all XML files
|
|
find . -name "*.xml" -exec xmllint --noout {} \;
|
|
|
|
# Check skill files exist
|
|
for skill in $(ls skills/); do
|
|
test -f "skills/$skill/SKILL.md" && echo "$skill: OK" || echo "$skill: MISSING"
|
|
done
|
|
|
|
# Check mode rules exist
|
|
for mode in $(ls modes/); do
|
|
count=$(ls "modes/$mode/rules/"*.xml 2>/dev/null | wc -l)
|
|
echo "$mode: $count rules"
|
|
done
|
|
```
|
|
|
|
### 5.3 Log Locations
|
|
|
|
| Log Type | Location |
|
|
|----------|----------|
|
|
| Roo Code logs | `~/.roo/logs/` |
|
|
| Mode activation logs | Console output when switching modes |
|
|
| Skill invocation logs | Console output when using skills |
|
|
|
|
---
|
|
|
|
## 6. Extending Modes and Skills
|
|
|
|
### 6.1 Adding a New Mode
|
|
|
|
**Step 1: Create Mode Directory**
|
|
|
|
```bash
|
|
mkdir -p modes/new-mode/rules
|
|
```
|
|
|
|
**Step 2: Create Mode Configuration**
|
|
|
|
Create `modes/new-mode/mode-config.yaml`:
|
|
|
|
```yaml
|
|
name: "New Mode Name"
|
|
slug: "new-mode"
|
|
roleDefinition: "Describe what this mode does"
|
|
whenToUse: "Describe when to use this mode"
|
|
permissions:
|
|
fileRestrictions:
|
|
- "new-mode-directory/**/*"
|
|
allowedCommands:
|
|
- "relevant-command"
|
|
customInstructions: |
|
|
Additional instructions
|
|
```
|
|
|
|
**Step 3: Create XML Rule Files**
|
|
|
|
Create the 7 required XML rule files:
|
|
|
|
```bash
|
|
# Use this prompt sequence to generate each rule file:
|
|
```
|
|
|
|
**Prompt for 1_workflow.xml:**
|
|
```
|
|
Create an XML rule file for the 'new-mode' mode called '1_workflow.xml'.
|
|
Define the primary workflow with these stages:
|
|
1. Receive input
|
|
2. Process input
|
|
3. Validate output
|
|
4. Deliver result
|
|
|
|
Use this format:
|
|
<?xml version="1.0" encoding="UTF-8"?>
|
|
<rule name="workflow" mode="new-mode">
|
|
<workflow>
|
|
<stage name="Receive Input">...</stage>
|
|
<stage name="Process Input">...</stage>
|
|
<stage name="Validate Output">...</stage>
|
|
<stage name="Deliver Result">...</stage>
|
|
</workflow>
|
|
</rule>
|
|
```
|
|
|
|
**Prompt for 2_best_practices.xml:**
|
|
```
|
|
Create an XML rule file for the 'new-mode' mode called '2_best_practices.xml'.
|
|
Define 5 best practices for this mode with descriptions and examples.
|
|
```
|
|
|
|
**Prompt for 3_common_patterns.xml:**
|
|
```
|
|
Create an XML rule file for the 'new-mode' mode called '3_common_patterns.xml'.
|
|
Define 3-5 common design patterns used in this mode.
|
|
```
|
|
|
|
**Prompt for 4_decision_guidance.xml:**
|
|
```
|
|
Create an XML rule file for the 'new-mode' mode called '4_decision_guidance.xml'.
|
|
Provide decision trees and guidance for common choices in this mode.
|
|
```
|
|
|
|
**Prompt for 5_examples.xml:**
|
|
```
|
|
Create an XML rule file for the 'new-mode' mode called '5_examples.xml'.
|
|
Provide 2-3 worked examples showing correct output from this mode.
|
|
```
|
|
|
|
**Prompt for 6_error_handling.xml:**
|
|
```
|
|
Create an XML rule file for the 'new-mode' mode called '6_error_handling.xml'.
|
|
Define error scenarios, detection methods, and resolution steps.
|
|
```
|
|
|
|
**Prompt for 7_communication.xml:**
|
|
```
|
|
Create an XML rule file for the 'new-mode' mode called '7_communication.xml'.
|
|
Define handoff templates for passing work to and from this mode.
|
|
```
|
|
|
|
**Step 4: Register Mode**
|
|
|
|
Add the mode to `.roomodes` file or copy `mode-config.yaml` to the modes directory.
|
|
|
|
### 6.2 Adding a New Skill
|
|
|
|
**Step 1: Create Skill Directory**
|
|
|
|
```bash
|
|
mkdir -p skills/new-skill
|
|
```
|
|
|
|
**Step 2: Create SKILL.md**
|
|
|
|
Create `skills/new-skill/SKILL.md`:
|
|
|
|
```markdown
|
|
---
|
|
name: new-skill
|
|
description: Brief description of what this skill does
|
|
---
|
|
|
|
# New Skill
|
|
|
|
## Capabilities
|
|
- Capability 1: Description
|
|
- Capability 2: Description
|
|
- Capability 3: Description
|
|
|
|
## Usage
|
|
Describe when and how to use this skill. Include specific scenarios.
|
|
|
|
## Input
|
|
Describe the expected input format:
|
|
- File types accepted
|
|
- Data structure expected
|
|
- Required fields
|
|
|
|
## Output
|
|
Describe the output format:
|
|
- File types produced
|
|
- Data structure returned
|
|
- Success/failure indicators
|
|
|
|
## Limitations
|
|
- Limitation 1
|
|
- Limitation 2
|
|
|
|
## Assumptions
|
|
- Assumption 1
|
|
- Assumption 2
|
|
```
|
|
|
|
**Step 3: Test Skill**
|
|
|
|
1. Activate the parent mode
|
|
2. Invoke the skill by name
|
|
3. Verify it returns expected output
|
|
4. Test error handling with invalid input
|
|
|
|
### 6.3 Modifying Existing Modes
|
|
|
|
**To change permissions:**
|
|
1. Edit `modes/[mode]/mode-config.yaml`
|
|
2. Update `fileRestrictions` or `allowedCommands`
|
|
3. Test that the mode still works correctly
|
|
|
|
**To change workflow:**
|
|
1. Edit `modes/[mode]/rules/1_workflow.xml`
|
|
2. Ensure XML is well-formed
|
|
3. Test the workflow in Roo Code
|
|
|
|
**To add best practices:**
|
|
1. Edit `modes/[mode]/rules/2_best_practices.xml`
|
|
2. Add new `<practice>` elements
|
|
3. Verify the mode applies the new practices
|
|
|
|
### 6.4 Modifying Existing Skills
|
|
|
|
**To update a skill:**
|
|
1. Edit `skills/[skill]/SKILL.md`
|
|
2. Update the relevant section (Capabilities, Usage, Input, Output, etc.)
|
|
3. Test the skill in its parent mode
|
|
|
|
---
|
|
|
|
## 7. Prompt Sequences for Support Tasks
|
|
|
|
### 7.1 Install All Modes and Skills
|
|
|
|
```
|
|
Install all 6 modes and 30 skills from the innovation-content project.
|
|
Copy mode configurations to .roomodes, XML rules to .roo/rules-[slug]/,
|
|
and skills to .agents/skills/. Verify each mode loads correctly.
|
|
```
|
|
|
|
### 7.2 Validate Installation
|
|
|
|
```
|
|
Validate the innovation-content installation:
|
|
1. Check all 6 mode configs exist and are valid YAML
|
|
2. Check all 42 XML rule files exist and are well-formed
|
|
3. Check all 30 SKILL.md files exist and have YAML frontmatter
|
|
4. Test switching to each mode
|
|
5. Report any issues found
|
|
```
|
|
|
|
### 7.3 Add New Mode
|
|
|
|
```
|
|
Create a new mode called '[Mode Name]' with slug '[mode-slug]'.
|
|
It should [describe purpose].
|
|
Create mode-config.yaml and 7 XML rule files in modes/[mode-slug]/.
|
|
The mode should have permissions for [list directories/patterns].
|
|
```
|
|
|
|
### 7.4 Add New Skill
|
|
|
|
```
|
|
Create a new skill called '[Skill Name]' for the [mode-name] mode.
|
|
It should [describe capability].
|
|
Create SKILL.md in skills/[skill-slug]/ with YAML frontmatter,
|
|
Capabilities, Usage, Input, Output, Limitations, and Assumptions sections.
|
|
```
|
|
|
|
### 7.5 Debug Mode Loading Issue
|
|
|
|
```
|
|
Debug why the [mode-slug] mode is not loading correctly.
|
|
1. Check mode-config.yaml exists and is valid YAML
|
|
2. Check all 7 XML rule files exist and are well-formed XML
|
|
3. Check file permissions are not too restrictive
|
|
4. Check for conflicts with other modes
|
|
5. Report findings and suggested fix
|
|
```
|
|
|
|
### 7.6 Debug Skill Not Found
|
|
|
|
```
|
|
Debug why the [skill-name] skill is not being found.
|
|
1. Check skills/[skill-name]/SKILL.md exists
|
|
2. Check YAML frontmatter has name and description
|
|
3. Check the skill is in the correct mode's skill list
|
|
4. Check for naming conflicts
|
|
5. Report findings and suggested fix
|
|
```
|
|
|
|
### 7.7 Update Mode Permissions
|
|
|
|
```
|
|
Update the permissions for [mode-slug] mode to allow editing of:
|
|
- [new-pattern-1]/**/*
|
|
- *.[new-extension]
|
|
Update modes/[mode-slug]/mode-config.yaml and verify the change.
|
|
```
|
|
|
|
### 7.8 Generate Mode Documentation
|
|
|
|
```
|
|
Generate documentation for the [mode-slug] mode including:
|
|
1. Mode purpose and when to use
|
|
2. List of 5 skills with descriptions
|
|
3. Workflow summary
|
|
4. File permissions
|
|
5. Communication protocols (handoffs to/from this mode)
|
|
Output as markdown suitable for inclusion in README or wiki.
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Maintenance
|
|
|
|
### 8.1 Updating from Remote
|
|
|
|
```bash
|
|
cd innovation-content
|
|
git pull origin main
|
|
# Re-install modes and skills if new ones were added
|
|
```
|
|
|
|
### 8.2 Backing Up Customizations
|
|
|
|
```bash
|
|
# Backup custom mode configurations
|
|
cp ~/.roo/modes/*.yaml backups/modes/
|
|
|
|
# Backup custom skills
|
|
cp -r ~/.agents/skills/* backups/skills/
|
|
|
|
# Backup custom rules
|
|
cp -r ~/.roo/rules-* backups/rules/
|
|
```
|
|
|
|
### 8.3 Version Compatibility
|
|
|
|
| Innovation Content Version | Minimum Roo Code Version | Notes |
|
|
|---------------------------|-------------------------|-------|
|
|
| 1.0.x | 3.8 | Initial release |
|
|
| 1.1.x | 3.8 | Added Support Team Guide and User Guide |
|
|
|
|
---
|
|
|
|
## 9. Contact and Escalation
|
|
|
|
| Issue Type | Contact | Escalation Path |
|
|
|------------|---------|-----------------|
|
|
| Installation issues | Support Team | Technical Lead |
|
|
| Mode behavior issues | Mode Developer | Project Lead |
|
|
| Skill issues | Skill Developer | Project Lead |
|
|
| Feature requests | Project Lead | Product Owner |
|
|
|
|
---
|
|
|
|
## 10. Appendix
|
|
|
|
### 10.1 File Structure Reference
|
|
|
|
```
|
|
innovation-content/
|
|
├── modes/
|
|
│ └── [mode-slug]/
|
|
│ ├── mode-config.yaml
|
|
│ └── rules/
|
|
│ ├── 1_workflow.xml
|
|
│ ├── 2_best_practices.xml
|
|
│ ├── 3_common_patterns.xml
|
|
│ ├── 4_decision_guidance.xml
|
|
│ ├── 5_examples.xml
|
|
│ ├── 6_error_handling.xml
|
|
│ └── 7_communication.xml
|
|
├── skills/
|
|
│ └── [skill-slug]/
|
|
│ └── SKILL.md
|
|
└── docs/
|
|
├── plan.md
|
|
├── srs.md
|
|
├── support-team-guide.md
|
|
└── user-guide.md
|
|
```
|
|
|
|
### 10.2 Quick Reference Card
|
|
|
|
| Task | Command/Action |
|
|
|------|----------------|
|
|
| Install modes | `cp modes/*/mode-config.yaml ~/.roo/modes/` |
|
|
| Install rules | `cp -r modes/*/rules/* ~/.roo/rules-[slug]/` |
|
|
| Install skills | `cp -r skills/* ~/.agents/skills/` |
|
|
| Validate YAML | `yamllint mode-config.yaml` |
|
|
| Validate XML | `xmllint --noout rule.xml` |
|
|
| Test mode | Switch to mode in Roo Code |
|
|
| Test skill | Invoke skill by name in mode |
|