From 29297c6e3fc8d59c6aa3a076af2c71fe9552adf0 Mon Sep 17 00:00:00 2001 From: anupsdf Date: Mon, 9 Mar 2026 22:03:46 -0700 Subject: [PATCH] Add SKILL.md and copilot-instructions.md for core CAPs --- .claude/skills/core/SKILL.md | 59 +++++++++++++++++++++++++++++++++ .github/copilot-instructions.md | 51 ++++++++++++++++++++++++++++ 2 files changed, 110 insertions(+) create mode 100644 .claude/skills/core/SKILL.md create mode 100644 .github/copilot-instructions.md diff --git a/.claude/skills/core/SKILL.md b/.claude/skills/core/SKILL.md new file mode 100644 index 000000000..1f0eb119f --- /dev/null +++ b/.claude/skills/core/SKILL.md @@ -0,0 +1,59 @@ +--- +name: core +description: 'Work on Stellar Core Advancement Proposals in core/. Use when editing CAP documents, checking CAP status fields, or syncing a CAP preamble Status with the corresponding entry in core/README.md.' +argument-hint: 'CAP number or core/ task, for example: sync CAP-0082 status with core/README.md' +--- + +# Core CAP Workflow + +Use this skill for tasks in `core/`, especially when creating, editing, reviewing, or validating Core Advancement Proposals (CAPs). + +## When to Use + +- Edit a CAP under `core/cap-xxxx.md`. +- Create a new CAP draft from `cap-template.md`. +- Verify that a CAP's `Status` field matches the corresponding entry in `core/README.md`. +- Update a CAP's status and keep the index tables in `core/README.md` synchronized. + +## Sources of Truth + +- Use `core/README.md` for the allowed CAP statuses and how CAPs are grouped in the proposal tables. +- Use `cap-template.md` for the default structure of new CAP drafts. +- Use the target CAP document for the exact preamble fields, terminology, and section structure already in use. + +## Status Synchronization Rules + +When a task involves a CAP status: + +1. Read the CAP preamble in `core/cap-xxxx.md` and find the `Status` line. +2. Read the matching CAP row in `core/README.md`. +3. Compare the status text exactly, including values such as `Draft`, `Accepted`, `Implemented`, `Final`, `Rejected`, `Awaiting Decision`, `FCP: Acceptance`, `FCP: Rejection`, or `Superseded: ...`. +4. If the status is intended to change, update both places in the same edit. +5. If the new status changes which README table the CAP belongs in, move the row to the correct section instead of only changing the text in place. +6. Keep the CAP title, number, and author fields aligned with the corresponding README row when you touch the status entry. +7. If there is a mismatch but the intended new status is not clear from the task or surrounding context, stop and ask rather than guessing which side is correct. + +## CAP Editing Rules + +- Preserve preamble fields and their meaning: `CAP`, `Title`, `Author` or working group fields, `Status`, `Created`, `Discussion`, and `Protocol version`. +- Follow the existing section structure of the target CAP. Older CAPs may not match the current template exactly. +- Keep protocol language normative and concrete. Describe exact ledger, transaction, operation, XDR, or meta effects. +- Make downstream effects explicit when relevant, especially for validators, Horizon/RPC consumers, and SDKs. +- Keep compatibility, migration, and security sections specific and actionable. +- Prefer surgical edits over broad rewrites. + +## Procedure + +1. Read `core/README.md`, `cap-template.md` if relevant, and the target `core/cap-xxxx.md`. +2. Determine whether the task is a drafting task, a status-sync task, or both. +3. For status-sync tasks, update the CAP preamble and `core/README.md` together. +4. For status transitions, confirm the CAP row is located in the correct README section. +5. Preserve existing Markdown style, heading levels, and table formatting. +6. Before finishing substantial Markdown edits, run `./bin/prettier.sh` when appropriate. + +## Do Not + +- Do not change unrelated CAPs while fixing one CAP's status. +- Do not silently infer a new status from partial evidence. +- Do not mix SEP process guidance into `core/` tasks unless explicitly requested. +- Do not rewrite accepted or final CAPs beyond the requested change. \ No newline at end of file diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..c623ae355 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,51 @@ +# Copilot Instructions for stellar-protocol + +This repository contains protocol specification documents, not application source code. Treat Markdown in this repository as normative technical documentation that must stay precise, internally consistent, and easy to review. + +## Primary Focus: `core/` + +When a task involves files under `core/`, optimize for Core Advancement Proposals (CAPs). + +- Treat `core/README.md` as the source of truth for CAP statuses, process, and protocol goals. +- Treat `cap-template.md` as the default structure for new CAP drafts. +- Preserve the intent and historical context of accepted or final CAPs. Prefer surgical edits over rewriting large sections. +- Keep changes specific to the proposal being edited. Do not silently harmonize unrelated CAPs. + +## CAP Authoring Rules + +When creating or editing a CAP in `core/`: + +- Preserve the preamble fields and their meaning: `CAP`, `Title`, `Author` or working group fields, `Status`, `Created`, `Discussion`, and `Protocol version`. +- Follow the existing section structure in the target document. Older CAPs may use a simpler structure than the current template. +- For new drafts, start from `cap-template.md` and keep the main sections in order unless there is a clear repository precedent to do otherwise. +- Keep technical statements normative and concrete. Avoid vague wording such as "improves things" or "makes it better" without specifying semantics. +- Distinguish clearly between motivation, specification, rationale, compatibility impact, security concerns, and implementation status. +- If a proposal changes protocol behavior, explain exact ledger, transaction, operation, XDR, or meta effects rather than describing only high-level intent. +- When describing protocol transitions, call out downstream impacts on validators, Horizon/RPC consumers, SDKs, and other ecosystem tooling when relevant. +- For compatibility or migration sections, be explicit about what breaks, what remains valid, and what downstream systems must update. +- For security sections, include concrete risks, invariants, abuse cases, or a short explanation of why there are no material new security concerns. +- For test cases, prefer specific scenarios and edge cases over generic placeholders. + +## Style and Editing Expectations + +- Keep Markdown plain, readable, and review-friendly. +- Preserve existing heading levels, capitalization style, and table formats within the edited file. +- Keep terminology consistent with Stellar protocol language already used in `core/README.md` and nearby CAPs. +- Use fenced code blocks for XDR, enum, struct, or protocol examples. +- Do not introduce unnecessary prose, marketing language, or product framing. +- Avoid changing historical status labels, dates, authorship, or protocol versions unless the task explicitly requires it. +- When referencing other proposals, use the repository's existing `CAP-xxxx` naming and relative links where appropriate. + +## Scope Discipline + +- If the user asks for help on a specific CAP, limit edits to that CAP and directly related supporting files. +- If the task is ambiguous, prefer reading `core/README.md`, `cap-template.md`, and the target CAP before editing. +- Do not infer implementation details that are not supported by the proposal text or task context. +- If a requested change would alter protocol semantics, surface the semantic impact clearly in the document instead of hiding it in wording changes. + +## Repository Conventions + +- `core/` contains CAP documents. +- `ecosystem/` contains SEP documents; do not mix SEP process guidance into CAP edits unless explicitly requested. +- `contents/` may contain supporting assets for a specific CAP; keep references aligned with the corresponding CAP number. +- Before concluding substantial Markdown edits, prefer the repository formatting command: `./bin/prettier.sh`. \ No newline at end of file