Claude-Code-Workflow/.claude/skills_lib/team-skill-designer-v2/specs/quality-standards.md

Quality Standards for Team Skills (v2)

Quality assessment criteria for generated team skill packages (v3 style: text + decision tables, no pseudocode).

When to Use

Phase	Usage	Section
Phase 5	Score generated command	All dimensions
Phase 3	Guide generation quality	Checklist

---

Quality Dimensions

1. Completeness (25%)

Score	Criteria
100%	All 15 required sections present with substantive content
80%	12+ sections present, minor gaps in non-critical areas
60%	Core sections present (front matter, message bus, 5 phases, error handling)
40%	Missing critical sections
0%	Skeleton only

Required Sections Checklist (role.md files):

• Role Identity (name, task prefix, output tag, responsibility)
• Role Boundaries (MUST / MUST NOT)
• Toolbox section (Available Commands with markdown links)
• Phase 2: Context Loading (decision tables, no pseudocode)
• Phase 3: Core Work (decision tables + tool call templates)
• Phase 4: Validation/Summary (checklist tables)
• Error Handling table
• Phase 1/5: Reference to SKILL.md Shared Infrastructure (not inline)
• No JavaScript pseudocode in any phase
• All branching logic expressed as decision tables

Required Sections Checklist (SKILL.md):

• Frontmatter (name, description, allowed-tools)
• Architecture Overview (role routing diagram with flow symbols)
• Role Router (Input Parsing + Role Registry table with markdown links)
• Shared Infrastructure (Worker Phase 1 Task Discovery + Phase 5 Report templates)
• Pipeline Definitions with Cadence Control (beat diagram + checkpoints)
• Compact Protection (Phase Reference table with Compact column)
• Coordinator Spawn Template
• Role Isolation Rules table
• Error Handling table

SKILL.md MUST NOT contain:

• ❌ No JavaScript pseudocode (VALID_ROLES object, routing functions, etc.)
• ❌ No role-specific implementation logic (belongs in role.md or commands/*.md)
• ❌ No ${variable} notation (use <placeholder> instead)

Note

: For commands/*.md file quality criteria, see Command File Quality Standards below.

2. Pattern Compliance (25%)

Score	Criteria
100%	All 9 infrastructure patterns + selected collaboration patterns fully implemented
80%	7 core infra patterns + at least 1 collaboration pattern with convergence
60%	Minimum 6 infra patterns, collaboration patterns present but incomplete
40%	Missing critical patterns (message bus or task lifecycle)
0%	No pattern compliance

Infrastructure Pattern Checklist:

• Pattern 1: Message bus - team_msg before every SendMessage
• Pattern 1b: CLI fallback section
• Pattern 2: YAML front matter - all fields present
• Pattern 3: Task lifecycle - TaskList/Get/Update flow
• Pattern 4: Five-phase structure (Phase 1/5 shared in SKILL.md, Phase 2-4 in role.md)
• Pattern 5: Complexity-adaptive (if applicable)
• Pattern 6: Coordinator spawn compatible
• Pattern 7: Error handling table
• Pattern 8: Session files (if applicable)
• Pattern 9: Compact Protection (Phase Reference table + re-read directives)

Collaboration Pattern Checklist:

• At least one CP selected (CP-1 minimum)
• Each selected CP has convergence criteria defined
• Each selected CP has feedback loop mechanism
• Each selected CP has timeout/fallback behavior
• CP-specific message types registered in message bus section
• Escalation path defined (CP-5) for error scenarios

3. Integration (25%)

Score	Criteria
100%	All integration checks pass, spawn snippet ready
80%	Minor integration notes, no blocking issues
60%	Some checks need attention but functional
40%	Task prefix conflict or missing critical tools
0%	Incompatible with team system

4. Consistency (25%)

Score	Criteria
100%	Role name, task prefix, message types consistent throughout
80%	Minor inconsistencies in non-critical areas
60%	Some mixed terminology but intent clear
40%	Confusing or contradictory content
0%	Internally inconsistent

---

Quality Gates

Gate	Threshold	Action
PASS	>= 80%	Deliver to .claude/skills/team-{name}/
REVIEW	60-79%	Fix recommendations, re-validate
FAIL	< 60%	Major rework needed, re-run from Phase 3

---

Issue Classification

Errors (Must Fix)

• Missing YAML front matter
• Missing group: team
• No message bus section
• No task lifecycle (TaskList/Get/Update)
• No SendMessage to coordinator
• Task prefix conflicts with existing
• Coordinator dispatch owner values not in Role Registry — all task owners must match a role in SKILL.md Role Registry table
• Monitor spawn prompt missing Skill callback — spawn prompt must contain Skill(skill="team-xxx", args="--role=yyy")
• Spawn template missing description parameter — Task() requires description as a mandatory field
• Spawn template missing team_name or name parameter — agent will not join the team or have identity

Warnings (Should Fix)

• Missing error handling table
• Incomplete Phase implementation (skeleton only)
• Missing team_msg before some SendMessage calls
• Missing CLI fallback section (### CLI 回退 with ccw team examples)
• No complexity-adaptive routing when role is complex
• Dispatch task IDs not aligned with pipeline diagram — task IDs (e.g., RESEARCH-001, DRAFT-001) must match the pipeline defined in SKILL.md
• Coordinator commands reference roles not in Message Routing Tables — all roles in dispatch/monitor must appear in SKILL.md Available Roles table

Info (Nice to Have)

• Decision tables could cover more edge cases
• Additional tool call examples
• Session file structure documentation

---

Coordinator Commands Consistency Standards

Quality assessment for coordinator's dispatch.md and monitor.md command files. These files are the most common source of integration failures.

6. Coordinator-SKILL Alignment (Applies to coordinator commands)

Score	Criteria
100%	All 5 alignment checks pass
80%	4/5 pass, one minor mismatch
60%	3/5 pass, cosmetic role naming issues
40%	Critical mismatch: roles not in VALID_ROLES or missing Skill callback
0%	dispatch/monitor written independently of SKILL.md

Check 1: Role Name Alignment

• Every owner value in dispatch.md TaskCreate calls exists in SKILL.md Role Registry table
• No invented role names (e.g., "spec-writer" when Role Registry has "writer")
• No typos or case mismatches in role names

Check 2: Task ID-Pipeline Alignment

• Task IDs in dispatch.md match the pipeline diagram in SKILL.md
• Task prefix mapping is consistent (e.g., RESEARCH-* → analyst, DRAFT-* → writer)
• Dependency chain in dispatch.md matches pipeline flow arrows

Check 3: Spawn Template Completeness

• monitor.md Task() calls include ALL required parameters: description, team_name, name, prompt
• Spawn prompt contains Skill(skill="team-xxx", args="--role=yyy") callback
• Spawn prompt includes role boundaries (task prefix constraint, output tag, communication rules)
• Spawn prompt is NOT a minimal generic instruction (e.g., "Execute task X")

Check 4: Message Routing Table Alignment

• All roles in dispatch.md appear in monitor.md's Message Routing Tables
• All message types used by roles are listed in the routing tables
• Sender roles in routing tables match Role Registry entries

Check 5: v3 Style Compliance

• No JavaScript pseudocode in any generated file
• All branching logic expressed as decision tables
• Code blocks contain only actual tool calls
• <placeholder> notation used (not ${variable})
• Phase 1/5 reference SKILL.md Shared Infrastructure (not inline)

---

Command File Quality Standards

Quality assessment criteria for generated command .md files in roles/{name}/commands/.

5. Command File Quality (Applies to folder-based roles)

Score	Criteria
100%	All 4 dimensions pass, all command files self-contained
80%	3/4 dimensions pass, minor gaps in one area
60%	2/4 dimensions pass, some cross-references or missing sections
40%	Missing required sections or broken references
0%	No command files or non-functional

Dimension 1: Structural Completeness

Each command file MUST contain:

• ## When to Use - Trigger conditions
• ## Strategy with delegation mode (Subagent / CLI / Sequential / Direct)
• ## Execution Steps with decision tables and tool call templates
• ## Error Handling table with Scenario/Resolution
• ## Output Format section

Dimension 2: Self-Containment

• No Ref: or cross-references to other command files
• No imports or dependencies on sibling commands
• All context loaded within the command (task, plan, files)
• Any subagent can Read() the command and execute independently

Dimension 3: Toolbox Consistency

• Every command listed in role.md Toolbox has a corresponding file in commands/
• Every file in commands/ is listed in role.md Toolbox
• Phase mapping in Toolbox matches command's ## When to Use phase reference
• Delegation mode in command matches role's subagent/CLI capabilities

Dimension 4: Pattern Compliance

• Pre-built command patterns (explore, analyze, implement, validate, review, dispatch, monitor) follow templates/role-command-template.md
• Custom commands follow the template skeleton structure
• Delegation mode is appropriate for the command's complexity
• Output format is structured and parseable by the calling role.md