PinionEducation/pinion-innovation-content
12
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6e0d87d56c6cac420cd32885ac1fd96861f79f43
pinion-innovation-content/docs/support-team-guide.md

14 KiB
Raw Blame History

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

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:

# 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\

# On macOS/Linux
cp innovation-content/modes/*/mode-config.yaml ~/.roo/modes/

Option B: Automated Installation

# 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:

# 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\
)

# 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:

# On Windows (cmd.exe)
xcopy /E /I innovation-content\skills %USERPROFILE%\.agents\skills\

# 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:

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:

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

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

# 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

mkdir -p modes/new-mode/rules

Step 2: Create Mode Configuration

Create modes/new-mode/mode-config.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:

# 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

mkdir -p skills/new-skill

Step 2: Create SKILL.md

Create skills/new-skill/SKILL.md:

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

cd innovation-content
git pull origin main
# Re-install modes and skills if new ones were added

8.2 Backing Up Customizations

# 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 View Git Blame Copy Permalink