Technical Documenation

Every file in a GitHub export, the documented format it targets, and where the export goes beyond what GitHub specifies. Use this to review a package before you commit it to a repository.

Matches GitHub formatPreview formatDesigner convention

Matches GitHub format means the file path and frontmatter follow a published GitHub specification. Preview format means GitHub documents it but the product is still in public preview and may change. Designer convention means GitHub does not read the file at all — it exists for your team or your own tooling.

Agent definitions

One file per non-human stage. These are the files Copilot coding agent and the agents CLI load when a task is delegated to a named agent.

.github/agents/<stage>.agent.mdMatches GitHub format

Target format: Custom agents (.agent.md)
Read by: Copilot coding agent, Copilot Chat agent picker, agents CLI

YAML frontmatter carries name, description, tools, and model. Tool names are validated against GitHub's resolvable aliases and MCP server/tool syntax; unresolvable tools are dropped and surfaced as an export warning. Models are mapped to Copilot display names (for example Claude Sonnet 4.5). High-stakes roles set disable-model-invocation so they are only run deliberately.

AGENTS.mdMatches GitHub format

Target format: AGENTS.md repository guidance
Read by: Copilot coding agent, Codex, Cursor, Jules, and other AGENTS.md-aware tools

Plain Markdown, no frontmatter, at the repository root. Contains the pipeline overview, stage responsibilities, handoff contract, and quality gates derived from your flow.

.github/copilot-instructions.mdMatches GitHub format

Target format: Repository custom instructions
Read by: Copilot Chat, Copilot code review, Copilot coding agent

Single Markdown file, no frontmatter. Kept short and stack-specific so it applies to every request rather than duplicating per-stage detail.

.github/HUMAN-STAGES.mdDesigner convention

Target format: No GitHub format — designer convention
Read by: People, not agents

Human-intervention stages have no machine-executable GitHub equivalent, so they ship as a runbook: who acts, what they receive, what they must produce, and which stage resumes after approval.

Path-scoped instructions

Rules that apply automatically when a matching file is in context, rather than when an agent is chosen.

.github/instructions/<topic>.instructions.mdMatches GitHub format

Target format: Path-specific custom instructions
Read by: Copilot Chat, Copilot code review, Copilot coding agent

Frontmatter requires description and applyTo. applyTo uses glob syntax derived from your stack settings (for example src/**/*.ts). Every generated file includes both keys because Copilot silently ignores instruction files with missing frontmatter.

.github/skills/<skill>/SKILL.mdMatches GitHub format

Target format: Agent skills (SKILL.md)
Read by: Copilot coding agent, agents CLI

One folder per skill with frontmatter name and description. Skills are the progressive-disclosure alternative to long instruction files: the agent loads the body only when the description matches the task.

Prompt files

Repeatable tasks a person or agent can invoke on demand.

.github/prompts/<stage>.prompt.mdMatches GitHub format

Target format: Prompt files (.prompt.md)
Read by: Copilot Chat (/prompt), VS Code, agents CLI

Frontmatter uses description, plus the agent key to target the matching .agent.md file so the prompt runs with that stage's tools and model instead of the default agent.

Workflows and automation

Deterministic CI is standard GitHub Actions. Agentic workflows follow GitHub's preview Markdown workflow format.

.github/workflows/*.ymlMatches GitHub format

Target format: GitHub Actions workflow syntax
Read by: GitHub Actions

CI, test, build, CodeQL, dependency review, deploy, and release workflows. Join/merge handoffs in your flow become needs: dependencies so a stage runs once, only after every upstream stage succeeds.

.github/workflows/copilot-setup-steps.ymlMatches GitHub format

Target format: Copilot coding agent environment setup
Read by: Copilot coding agent

Must define a single job named copilot-setup-steps. Installs your declared toolchain so the agent starts from a working environment.

.github/workflows/<flow>.mdPreview format

Target format: Agentic workflows (Markdown workflows)
Read by: GitHub Agentic Workflows (public preview)

Markdown with frontmatter for triggers, permissions, and tools; the body is the agent's natural-language job. This is a preview product, so the export is optional and the install guide flags that the format may change. Compile with the gh-aw CLI before relying on it.

.github/hooks/*.jsonDesigner convention

Target format: No stable public GitHub format — builder convention
Read by: Your own automation

Policy, security, and audit hook definitions expressed as plain JSON so they can be wired into Actions, an MCP server, or an internal runner. Nothing on GitHub reads these automatically.

Repository governance

Standard GitHub repository files, generated from your flow's roles and gates.

.github/CODEOWNERSMatches GitHub format

Target format: CODEOWNERS syntax
Read by: GitHub pull requests and branch protection

Optional. Generated only when CODEOWNERS generation is enabled under Repository governance and owners are listed. Otherwise no file is written.

.github/ISSUE_TEMPLATE/*.ymlMatches GitHub format

Target format: Issue forms schema
Read by: GitHub issue creation

Feature, bug, technical debt, and security forms with fields matching the inputs your first pipeline stage expects.

.github/PULL_REQUEST_TEMPLATE.mdMatches GitHub format

Target format: Pull request template
Read by: GitHub pull request creation

Checklist mirrors the quality gates defined on your stages.

.github/dependabot.ymlMatches GitHub format

Target format: Dependabot configuration
Read by: Dependabot

Ecosystems inferred from your declared stack.

README.md, CONTRIBUTING.md, SECURITY.mdMatches GitHub format

Target format: GitHub community health files
Read by: People and, indirectly, agents reading repo context

Conventional Markdown. CONTRIBUTING documents the human path through the same pipeline the agents follow.

Portable specification

The vendor-neutral description of your flow. Nothing on GitHub reads these; they exist so the blueprint survives a change of tooling.

.sdlc/blueprint.jsonDesigner convention

Target format: Designer schema (versioned)
Read by: This designer — re-import to keep editing

The lossless source of truth. Every other exported file is derived from it, so this is the file to keep in version control.

.sdlc/*.ymlDesigner convention

Target format: Designer YAML projection
Read by: Your own tooling

Lifecycle, quality gates, agent routing, and compliance expressed as readable YAML for teams that want to diff pipeline changes in review.

INSTALL-GITHUB.md, DISCLAIMER.mdDesigner convention

Target format: No GitHub format — designer convention
Read by: People

Step-by-step placement instructions, required repository settings, preview caveats, and the liability acknowledgement you accepted at download time.

Known gaps

MCP servers are configured in repository settings, not in an exported file. The install guide lists the servers your stages reference so you can add them manually.
Branch protection, required checks, and environment approvals cannot be committed as files. They ship as a checklist in the install guide.
Human-intervention stages are documentation only. GitHub has no format for pausing an agent pipeline on a person, so enforce those pauses with environment approvals or required reviewers.
Agentic workflows are a public preview. Treat that part of the export as provisional and re-generate after GitHub finalises the format.

Open the builder Back to overview