Trsdn Aiscrum Pro Copilot Authoring

Copilot Authoring Guide

Reference for creating and maintaining agent configuration artifacts in this project.

Architecture Overview

Agent configurations live in .aiscrum/roles/<role>/. Each role is a self-contained capsule — the system recursively loads ALL .md files from the role folder as the agent's context. No cross-role sharing, no hardcoded prompts.

.aiscrum/roles/
├── refiner/
│   ├── copilot-instructions.md    # Agent identity, workflow, rules
│   └── skills/
│       ├── issue-editing/SKILL.md # Specialized capability
│       └── codebase-research/SKILL.md
├── planner/
│   ├── copilot-instructions.md
│   └── skills/
│       └── sprint-planning/SKILL.md
├── reviewer/
│   └── ...
├── retro/
│   └── ...
└── general/
    └── copilot-instructions.md

Additionally, .github/skills/<name>/SKILL.md holds project-level skills available to the main Copilot CLI session (not loaded into role agents).

copilot-instructions.md

The core identity file for each role. Defines who the agent is and how it works.

Structure

# {Role Name} Agent — Copilot Instructions

You are a **{Role Name} Agent** for the AiScrum Pro project.

## Role

One-sentence description of what this agent does.

## Workflow

1. **Step 1**: What to do first
2. **Step 2**: Next step
3. ...

## Rules

- Hard constraints the agent must follow
- Safety boundaries
- What the agent must NOT do

## Output Format (optional)

- Expected structure of agent responses

Guidelines

• Be specific: "Use gh issue view <number>" not "check the issue"
• Include CLI commands: Agents work via terminal — give exact commands
• State boundaries: What the agent must NOT do is as important as what it should
• Keep it focused: One role = one responsibility. Avoid multi-purpose agents
• Stakeholder Authority: Every role must respect that the user decides scope and priorities

SKILL.md

Skills are portable, specialized capabilities an agent can use. Each skill lives in its own directory.

File Format

---
name: skill-name
description: "What the skill does and when to use it (max 1024 chars)"
---

# Skill: {Title}

{Brief overview of what this skill accomplishes.}

## When to Use

- Trigger condition 1
- Trigger condition 2

## Instructions

Step-by-step procedures with exact commands.

## Examples

Concrete input/output examples.

## Rules

- Constraints specific to this skill

Frontmatter Fields

Best Practices

• One skill = one capability: issue-editing not github-everything
• Effective descriptions: "Edit GitHub issues via gh CLI — read, update body, manage labels, add comments" not "Help with issues"
• Include exact commands: Agents execute in terminal, they need copy-paste-ready commands
• Add rules: State what the skill should NOT do (e.g., "Never remove labels without stating why")
• Reference resources: Use relative paths for scripts/templates in the skill directory (e.g., [template](./template.md))

Skill Directory Contents

A skill directory can contain more than just SKILL.md:

skills/issue-editing/
├── SKILL.md           # Main skill definition (required)
├── templates/         # Reusable templates
│   └── issue-body.md
├── examples/          # Example inputs/outputs
└── scripts/           # Helper scripts

All .md files in the skill directory are loaded into the agent's context.

Key Principles

1. No hardcoded prompts: All agent behavior comes from .md files in the role folder
2. Sealed capsules: Each agent only sees its own role folder — no shared context injection
3. Config-driven: Drop files to change behavior, don't edit TypeScript
4. Context budget: Keep files concise. Everything in the role folder is loaded into the context window
5. Exclude logs: The log/ subdirectory (when present) is excluded from context loading

Reference

• Agent Skills standard
• GitHub Copilot custom agents
• Our agent loader: src/dashboard/chat-manager.ts → loadRoleContext() recursively reads .md files

Source: trsdn/aiscrum-pro — distributed by TomeVault.