code-copilot-team: Instructions file for GitHub Copilot

Spec Workflow — SDD Specification Protocol

Rules governing when a Software Design Document (SDD) spec is required, what sections it must contain, and how it gates the transition from Plan to Build.

Risk-Based spec_mode Classification

Every planned feature is assigned a spec_mode based on change risk. The Plan agent determines this value and records it in specs/<feature-id>/plan.md YAML frontmatter.

spec_mode	When to use
full	Security changes, schema changes, integration work, features touching more than 2 files
lightweight	Features touching 1–2 files, non-critical changes
none	Bug fixes (non-security), docs-only changes, trivial or cosmetic changes

When in doubt, escalate to the next higher mode. Under-speccing a risky change costs more than over-speccing a safe one.

Required Spec Sections per Mode

full

All sections from spec-template.md are required, plus a tasks.md task breakdown:

• User Scenarios
• Requirements
• Constraints / What NOT to Build
• Key Entities
• Success Criteria
• tasks.md — discrete, bounded build tasks derived from the spec

lightweight

Only two sections are required in spec.md:

• Requirements
• Constraints

none

No spec.md is required. The Plan agent writes only plan.md.

Plan Approval Gate Protocol

What the Plan Agent Writes

The Plan agent always writes specs/<feature-id>/plan.md regardless of spec_mode. The file must include YAML frontmatter with at minimum:

---
feature_id: <feature-id>
spec_mode: full | lightweight | none
status: draft | approved
origin:
  # at least one of: issue, urls, transcripts — OR the explicit
  # internal/unrecoverable exemption. See origin-confirmation skill.
  issue: <repo>#<number>
  urls:
    - <external-reference-url>
  transcripts:
    - specs/<feature-id>/origin/<date>-<slug>.md
  origin_claim: |
    One paragraph in the user's words quoting their original ask.
---