chore: release v1.1.0 - add Support Team Guide and User Guide, update all docs to v1.1.0
This commit is contained in:
Alejandro Malo
574
docs/support-team-guide.md
Normal file
574
docs/support-team-guide.md
Normal file
@@ -0,0 +1,574 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user