From 7cc3d0a41dcaef2cf85d79fbc877d6df08c9cd4a Mon Sep 17 00:00:00 2001 From: ersan bilik Date: Fri, 10 Apr 2026 01:07:12 +0300 Subject: [PATCH] feat: full Copilot CLI skill parity with Claude integration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Port all 40 Claude skills to Copilot CLI format with proper YAML frontmatter (tools array instead of allowed-tools string). Includes lifecycle hook scripts (bash + PowerShell), agent instructions, and hook configuration. Contents: - 40 skill SKILL.md files under integrations/copilot-cli/skills/ - 8 hook scripts (session-start/end, pre/post-tool-use × bash/ps1) - INSTRUCTIONS.md agent bootstrap instructions - ctx-hooks.json lifecycle hook configuration - Updated embed.go to include integrations assets - Parity spec document (specs/copilot-feature-parity-kit.md) Signed-off-by: ersan bilik Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: ersan bilik --- .../integrations/copilot-cli/INSTRUCTIONS.md | 94 +++++ .../integrations/copilot-cli/ctx-hooks.json | 70 +++- .../copilot-cli/scripts/post-tool-use.ps1 | 12 + .../copilot-cli/scripts/post-tool-use.sh | 14 + .../copilot-cli/scripts/pre-tool-use.ps1 | 11 + .../copilot-cli/scripts/pre-tool-use.sh | 15 + .../copilot-cli/scripts/session-end.ps1 | 8 + .../copilot-cli/scripts/session-end.sh | 10 + .../copilot-cli/scripts/session-start.ps1 | 5 + .../copilot-cli/scripts/session-start.sh | 10 + .../skills/_ctx-alignment-audit/SKILL.md | 61 +++ .../skills/ctx-add-convention/SKILL.md | 47 +++ .../skills/ctx-add-decision/SKILL.md | 47 +++ .../skills/ctx-add-learning/SKILL.md | 45 +++ .../copilot-cli/skills/ctx-add-task/SKILL.md | 54 +++ .../copilot-cli/skills/ctx-agent/SKILL.md | 43 ++ .../skills/ctx-architecture/SKILL.md | 69 ++++ .../copilot-cli/skills/ctx-archive/SKILL.md | 46 +++ .../skills/ctx-blog-changelog/SKILL.md | 132 +++++++ .../copilot-cli/skills/ctx-blog/SKILL.md | 57 +++ .../skills/ctx-brainstorm/SKILL.md | 132 +++++++ .../skills/ctx-check-links/SKILL.md | 136 +++++++ .../copilot-cli/skills/ctx-commit/SKILL.md | 90 +++++ .../skills/ctx-consolidate/SKILL.md | 57 +++ .../copilot-cli/skills/ctx-doctor/SKILL.md | 78 ++++ .../copilot-cli/skills/ctx-drift/SKILL.md | 237 ++--------- .../copilot-cli/skills/ctx-implement/SKILL.md | 129 ++++++ .../skills/ctx-import-plans/SKILL.md | 56 +++ .../skills/ctx-journal-enrich-all/SKILL.md | 59 +++ .../skills/ctx-journal-enrich/SKILL.md | 60 +++ .../skills/ctx-journal-normalize/SKILL.md | 46 +++ .../copilot-cli/skills/ctx-loop/SKILL.md | 62 +++ .../copilot-cli/skills/ctx-next/SKILL.md | 45 +-- .../copilot-cli/skills/ctx-pad/SKILL.md | 140 +++++++ .../copilot-cli/skills/ctx-pause/SKILL.md | 47 +++ .../skills/ctx-prompt-audit/SKILL.md | 54 +++ .../copilot-cli/skills/ctx-prompt/SKILL.md | 49 +++ .../copilot-cli/skills/ctx-recall/SKILL.md | 38 +- .../copilot-cli/skills/ctx-reflect/SKILL.md | 75 ++++ .../copilot-cli/skills/ctx-remember/SKILL.md | 69 ++++ .../copilot-cli/skills/ctx-remind/SKILL.md | 46 +++ .../copilot-cli/skills/ctx-resume/SKILL.md | 35 ++ .../skills/ctx-sanitize-permissions/SKILL.md | 67 ++++ .../skills/ctx-skill-audit/SKILL.md | 78 ++++ .../skills/ctx-skill-creator/SKILL.md | 76 ++++ .../copilot-cli/skills/ctx-spec/SKILL.md | 76 ++++ .../copilot-cli/skills/ctx-status/SKILL.md | 87 +--- .../copilot-cli/skills/ctx-verify/SKILL.md | 52 +++ .../copilot-cli/skills/ctx-worktree/SKILL.md | 170 ++++++++ .../copilot-cli/skills/ctx-wrap-up/SKILL.md | 121 ++++++ specs/copilot-feature-parity-kit.md | 373 ++++++++++++++++++ 51 files changed, 3337 insertions(+), 353 deletions(-) create mode 100644 internal/assets/integrations/copilot-cli/INSTRUCTIONS.md create mode 100644 internal/assets/integrations/copilot-cli/scripts/post-tool-use.ps1 create mode 100644 internal/assets/integrations/copilot-cli/scripts/post-tool-use.sh create mode 100644 internal/assets/integrations/copilot-cli/scripts/pre-tool-use.ps1 create mode 100644 internal/assets/integrations/copilot-cli/scripts/pre-tool-use.sh create mode 100644 internal/assets/integrations/copilot-cli/scripts/session-end.ps1 create mode 100644 internal/assets/integrations/copilot-cli/scripts/session-end.sh create mode 100644 internal/assets/integrations/copilot-cli/scripts/session-start.ps1 create mode 100644 internal/assets/integrations/copilot-cli/scripts/session-start.sh create mode 100644 internal/assets/integrations/copilot-cli/skills/_ctx-alignment-audit/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-add-convention/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-add-decision/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-add-learning/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-add-task/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-agent/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-architecture/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-archive/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-blog-changelog/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-blog/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-brainstorm/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-check-links/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-commit/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-consolidate/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-doctor/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-implement/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-import-plans/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich-all/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-journal-normalize/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-loop/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-pad/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-pause/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-prompt-audit/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-prompt/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-reflect/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-remind/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-resume/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-sanitize-permissions/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-skill-audit/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-skill-creator/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-spec/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-verify/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-worktree/SKILL.md create mode 100644 internal/assets/integrations/copilot-cli/skills/ctx-wrap-up/SKILL.md create mode 100644 specs/copilot-feature-parity-kit.md diff --git a/internal/assets/integrations/copilot-cli/INSTRUCTIONS.md b/internal/assets/integrations/copilot-cli/INSTRUCTIONS.md new file mode 100644 index 000000000..9419a3dc7 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/INSTRUCTIONS.md @@ -0,0 +1,94 @@ +# ctx Agent Instructions — Copilot CLI + + + + +## IMPORTANT: You Have Persistent Memory + +This project uses Context (`ctx`) for context persistence across sessions. +**Your memory is NOT ephemeral**: it lives in the context directory. + +## On Session Start + +1. **Run `ctx system bootstrap`**: CRITICAL, not optional. + This tells you where the context directory is. If it fails or returns + no context_dir, STOP and warn the user. +2. **Read AGENT_PLAYBOOK.md** from the context directory: it explains + how to use this system +3. **Run `ctx agent --budget 4000`** for a content summary + +## When Asked "Do You Remember?" + +When the user asks "Do you remember?", "What were we working on?", or any +memory-related question: + +**Do this FIRST (silently):** +- Read TASKS.md, DECISIONS.md, and LEARNINGS.md from the context directory +- Run `ctx recall list --limit 5` for recent session history + +**Then respond with a structured readback:** + +1. **Last session**: cite the most recent session topic and date +2. **Active work**: list pending or in-progress tasks +3. **Recent context**: mention 1-2 recent decisions or learnings +4. **Next step**: offer to continue or ask what to focus on + +**Never** lead with "I don't have memory", "Let me check if there are files", +or narrate your discovery process. The context files are your memory. +Read them silently, then present what you found as recall, not as a search. + +## Quick Context Load + +```bash +# Get AI-optimized context packet (what you should know) +ctx agent --budget 4000 + +# Or see full status +ctx status +``` + +## Context Files + +| File | Purpose | +|-----------------|----------------------------------------| +| CONSTITUTION.md | Hard rules — NEVER violate | +| TASKS.md | Current work items | +| DECISIONS.md | Architectural decisions with rationale | +| LEARNINGS.md | Gotchas, tips, lessons learned | +| CONVENTIONS.md | Code patterns and standards | + +All files live in the context directory reported by `ctx system bootstrap`. + +## Context Updates During Work + +Proactively update context files as you work: + +| Event | Action | +|-----------------------------|-------------------------------------| +| Made architectural decision | Add to `.context/DECISIONS.md` | +| Discovered gotcha/bug | Add to `.context/LEARNINGS.md` | +| Established new pattern | Add to `.context/CONVENTIONS.md` | +| Completed task | Mark [x] in `.context/TASKS.md` | + +## Self-Check + +Periodically ask yourself: + +> "If this session ended right now, would the next session know what happened?" + +If no — save a session file or update context files before continuing. + +## Session Persistence + +After completing meaningful work, save a session summary to +`.context/sessions/`. Use the `ctx-wrap-up` skill for the full ceremony. + +## Build Commands + +```bash +make build # or: go build ./cmd/ctx/... +make lint # or: golangci-lint run +make test # or: go test ./... +``` + + diff --git a/internal/assets/integrations/copilot-cli/ctx-hooks.json b/internal/assets/integrations/copilot-cli/ctx-hooks.json index 2aa48f448..b4ae75012 100644 --- a/internal/assets/integrations/copilot-cli/ctx-hooks.json +++ b/internal/assets/integrations/copilot-cli/ctx-hooks.json @@ -1,40 +1,68 @@ { - "version": 1, "hooks": { "sessionStart": [ { - "type": "command", - "bash": ".github/hooks/scripts/ctx-sessionStart.sh", - "powershell": ".github/hooks/scripts/ctx-sessionStart.ps1", - "cwd": ".", - "timeoutSec": 10 + "description": "Bootstrap ctx context on session start", + "command": "ctx system bootstrap" + }, + { + "description": "Load AI-optimized context packet", + "command": "ctx agent --budget 4000" } ], "preToolUse": [ { - "type": "command", - "bash": ".github/hooks/scripts/ctx-preToolUse.sh", - "powershell": ".github/hooks/scripts/ctx-preToolUse.ps1", - "cwd": ".", - "timeoutSec": 5 + "description": "Context load gate — ensure context is loaded before work", + "command": "ctx system context-load-gate" + }, + { + "description": "Block dangerous non-path ctx commands", + "matcher": "bash", + "command": "ctx system block-non-path-ctx" + }, + { + "description": "QA reminder nudge", + "matcher": "bash", + "command": "ctx system qa-reminder" } ], "postToolUse": [ { - "type": "command", - "bash": ".github/hooks/scripts/ctx-postToolUse.sh", - "powershell": ".github/hooks/scripts/ctx-postToolUse.ps1", - "cwd": ".", - "timeoutSec": 5 + "description": "Post-commit context persistence check", + "matcher": "bash", + "command": "ctx system post-commit" + }, + { + "description": "Check if a task was just completed", + "matcher": "edit", + "command": "ctx system check-task-completion" + }, + { + "description": "Check if a task was just completed (write)", + "matcher": "write", + "command": "ctx system check-task-completion" } ], "sessionEnd": [ { - "type": "command", - "bash": ".github/hooks/scripts/ctx-sessionEnd.sh", - "powershell": ".github/hooks/scripts/ctx-sessionEnd.ps1", - "cwd": ".", - "timeoutSec": 15 + "description": "Check context size for budget drift", + "command": "ctx system check-context-size" + }, + { + "description": "Persistence check — unsaved decisions/learnings", + "command": "ctx system check-persistence" + }, + { + "description": "Journal export check", + "command": "ctx system check-journal" + }, + { + "description": "Version freshness check", + "command": "ctx system check-version" + }, + { + "description": "Heartbeat — record session activity", + "command": "ctx system heartbeat" } ] } diff --git a/internal/assets/integrations/copilot-cli/scripts/post-tool-use.ps1 b/internal/assets/integrations/copilot-cli/scripts/post-tool-use.ps1 new file mode 100644 index 000000000..4dceed315 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/scripts/post-tool-use.ps1 @@ -0,0 +1,12 @@ +# ctx post-tool-use hook for Copilot CLI (PowerShell) +# Checks for post-commit context and task completion + +$Tool = $args[0] + +if ($Tool -eq "bash" -or $Tool -eq "powershell") { + try { ctx system post-commit 2>$null } catch {} +} + +if ($Tool -eq "edit" -or $Tool -eq "write") { + try { ctx system check-task-completion 2>$null } catch {} +} diff --git a/internal/assets/integrations/copilot-cli/scripts/post-tool-use.sh b/internal/assets/integrations/copilot-cli/scripts/post-tool-use.sh new file mode 100644 index 000000000..7d9ccb906 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/scripts/post-tool-use.sh @@ -0,0 +1,14 @@ +#!/bin/bash +# ctx post-tool-use hook for Copilot CLI +# Checks for post-commit context and task completion +set -euo pipefail + +TOOL="${1:-}" + +if [ "$TOOL" = "bash" ] || [ "$TOOL" = "powershell" ]; then + ctx system post-commit 2>/dev/null || true +fi + +if [ "$TOOL" = "edit" ] || [ "$TOOL" = "write" ]; then + ctx system check-task-completion 2>/dev/null || true +fi diff --git a/internal/assets/integrations/copilot-cli/scripts/pre-tool-use.ps1 b/internal/assets/integrations/copilot-cli/scripts/pre-tool-use.ps1 new file mode 100644 index 000000000..c7fed6f7b --- /dev/null +++ b/internal/assets/integrations/copilot-cli/scripts/pre-tool-use.ps1 @@ -0,0 +1,11 @@ +# ctx pre-tool-use hook for Copilot CLI (PowerShell) +# Ensures context is loaded and blocks dangerous commands + +$Tool = $args[0] + +try { ctx system context-load-gate 2>$null } catch {} + +if ($Tool -eq "bash" -or $Tool -eq "powershell") { + try { ctx system block-non-path-ctx 2>$null } catch {} + try { ctx system qa-reminder 2>$null } catch {} +} diff --git a/internal/assets/integrations/copilot-cli/scripts/pre-tool-use.sh b/internal/assets/integrations/copilot-cli/scripts/pre-tool-use.sh new file mode 100644 index 000000000..cd9cd926c --- /dev/null +++ b/internal/assets/integrations/copilot-cli/scripts/pre-tool-use.sh @@ -0,0 +1,15 @@ +#!/bin/bash +# ctx pre-tool-use hook for Copilot CLI +# Ensures context is loaded and blocks dangerous commands +set -euo pipefail + +TOOL="${1:-}" + +# Always check context load gate +ctx system context-load-gate 2>/dev/null || true + +# Bash-specific hooks +if [ "$TOOL" = "bash" ] || [ "$TOOL" = "powershell" ]; then + ctx system block-non-path-ctx 2>/dev/null || true + ctx system qa-reminder 2>/dev/null || true +fi diff --git a/internal/assets/integrations/copilot-cli/scripts/session-end.ps1 b/internal/assets/integrations/copilot-cli/scripts/session-end.ps1 new file mode 100644 index 000000000..8b840f2bb --- /dev/null +++ b/internal/assets/integrations/copilot-cli/scripts/session-end.ps1 @@ -0,0 +1,8 @@ +# ctx session end hook for Copilot CLI (PowerShell) +# Checks for unsaved context and records heartbeat + +try { ctx system check-context-size 2>$null } catch {} +try { ctx system check-persistence 2>$null } catch {} +try { ctx system check-journal 2>$null } catch {} +try { ctx system check-version 2>$null } catch {} +try { ctx system heartbeat 2>$null } catch {} diff --git a/internal/assets/integrations/copilot-cli/scripts/session-end.sh b/internal/assets/integrations/copilot-cli/scripts/session-end.sh new file mode 100644 index 000000000..776ddcfd5 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/scripts/session-end.sh @@ -0,0 +1,10 @@ +#!/bin/bash +# ctx session end hook for Copilot CLI +# Checks for unsaved context and records heartbeat +set -euo pipefail + +ctx system check-context-size 2>/dev/null || true +ctx system check-persistence 2>/dev/null || true +ctx system check-journal 2>/dev/null || true +ctx system check-version 2>/dev/null || true +ctx system heartbeat 2>/dev/null || true diff --git a/internal/assets/integrations/copilot-cli/scripts/session-start.ps1 b/internal/assets/integrations/copilot-cli/scripts/session-start.ps1 new file mode 100644 index 000000000..8cbbd22fb --- /dev/null +++ b/internal/assets/integrations/copilot-cli/scripts/session-start.ps1 @@ -0,0 +1,5 @@ +# ctx session start hook for Copilot CLI (PowerShell) +# Bootstraps context and loads the agent packet + +try { ctx system bootstrap 2>$null } catch {} +try { ctx agent --budget 4000 2>$null } catch {} diff --git a/internal/assets/integrations/copilot-cli/scripts/session-start.sh b/internal/assets/integrations/copilot-cli/scripts/session-start.sh new file mode 100644 index 000000000..1206e14c3 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/scripts/session-start.sh @@ -0,0 +1,10 @@ +#!/bin/bash +# ctx session start hook for Copilot CLI +# Bootstraps context and loads the agent packet +set -euo pipefail + +# Bootstrap ctx context +ctx system bootstrap 2>/dev/null || true + +# Load AI-optimized context packet +ctx agent --budget 4000 2>/dev/null || true diff --git a/internal/assets/integrations/copilot-cli/skills/_ctx-alignment-audit/SKILL.md b/internal/assets/integrations/copilot-cli/skills/_ctx-alignment-audit/SKILL.md new file mode 100644 index 000000000..26dd5576d --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/_ctx-alignment-audit/SKILL.md @@ -0,0 +1,61 @@ +--- +name: _ctx-alignment-audit +description: "Audit alignment between docs and agent instructions. Use when docs make claims about agent behavior that may not be backed by the playbook or skills." +tools: [bash, read, glob, grep] +--- + +Audit whether behavioral claims in documentation are backed by +actual agent instructions. + +## When to Use + +- After writing or updating documentation +- After modifying the Agent Playbook or skills +- When a doc makes claims about proactive agent behavior +- Periodically to catch drift between docs and instructions + +## When NOT to Use + +- For code-level drift (use `ctx-drift` instead) +- For context file staleness (use `ctx-status`) +- When reviewing docs for prose quality (not behavioral claims) + +## Process + +### Step 1: Collect Claims + +Read target docs. Extract every behavioral claim — statements +describing what an agent "will do", "may do", or "offers to do". + +### Step 2: Trace Each Claim + +Search for matching instructions in: +1. **AGENT_PLAYBOOK.md**: primary behavioral source +2. **skills/*/SKILL.md**: skill-specific instructions +3. **INSTRUCTIONS.md**: project-level instructions + +For each claim, determine: +- **Covered**: matching instruction exists +- **Partial**: related but incomplete +- **Gap**: no instruction exists + +### Step 3: Report + +| Claim (file:line) | Status | Backing instruction | Gap | +|---|---|---|---| +| "agent creates tasks" | Gap | None | Not taught | +| "agent saves learnings" | Covered | Playbook | — | + +### Step 4: Fix (if requested) + +For each gap, propose: +- **Playbook addition**: if behavior applies broadly +- **Skill addition**: if specific to one skill +- **Doc correction**: if the claim overpromises + +## Quality Checklist + +- [ ] Every behavioral claim was traced +- [ ] Each claim has clear status (Covered/Partial/Gap) +- [ ] Gaps have proposed fixes +- [ ] No new claims introduced without backing diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-add-convention/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-add-convention/SKILL.md new file mode 100644 index 000000000..dcf929503 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-add-convention/SKILL.md @@ -0,0 +1,47 @@ +--- +name: ctx-add-convention +description: "Record a coding convention. Use when a repeated pattern should be codified so all sessions follow it consistently." +tools: [bash] +--- + +Record a coding convention in CONVENTIONS.md. + +## When to Use + +- When a pattern has been used 2-3 times and should be standardized +- When establishing a naming, formatting, or structural rule +- When a new contributor would need to know "how we do things here" +- When the user says "codify that" or "make that a convention" + +## When NOT to Use + +- One-off implementation details (use code comments instead) +- Architectural decisions with trade-offs (use `ctx-add-decision`) +- Debugging insights or gotchas (use `ctx-add-learning`) +- Rules that are already enforced by linters or formatters + +## Gathering Information + +Conventions are simpler than decisions or learnings. You need: + +1. **Name**: What is the convention called? +2. **Rule**: What is the rule? One clear sentence. +3. **Section**: Where does it belong in CONVENTIONS.md? + +If the user provides only a description, infer the section from the +topic. Check existing sections in CONVENTIONS.md first to place it +correctly: don't create a new section if an existing one fits. + +## Execution + +```bash +ctx add convention "Use kebab-case for all CLI flag names" --section "Naming" +``` + +## Quality Checklist + +- [ ] The rule is clear enough that someone unfamiliar could follow it +- [ ] It is specific to this project (not a general rule) +- [ ] It is not already in CONVENTIONS.md (check first) +- [ ] The section matches an existing section, or a new one is needed +- [ ] It describes a pattern, not a one-time choice (that's a decision) diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-add-decision/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-add-decision/SKILL.md new file mode 100644 index 000000000..82f3698f0 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-add-decision/SKILL.md @@ -0,0 +1,47 @@ +--- +name: ctx-add-decision +description: "Record architectural decision. Use when a trade-off is resolved or a non-obvious design choice is made that future sessions need to know." +tools: [bash] +--- + +Record an architectural decision in DECISIONS.md. + +## When to Use + +- After resolving a trade-off between alternatives +- When making a non-obvious design choice +- When the "why" behind a choice needs to be preserved + +## When NOT to Use + +- Minor implementation details (use code comments instead) +- Routine maintenance or bug fixes +- When there was no real alternative to consider + +## Decision Formats + +### Quick Format (Y-Statement) + +> "In the context of **[situation]**, facing **[constraint]**, we decided +> for **[choice]** and against **[alternatives]**, to achieve +> **[benefit]**, accepting that **[trade-off]**." + +### Full Format + +Gather: Context, Alternatives, Decision, Rationale, Consequence. + +## Execution + +```bash +ctx add decision "Use Cobra for CLI framework" \ + --context "Need CLI framework for Go project" \ + --rationale "Better subcommand support, team familiarity" \ + --consequence "More boilerplate, but clearer command structure" +``` + +## Quality Checklist + +- [ ] Context explains the problem clearly +- [ ] At least one alternative was considered +- [ ] Rationale addresses why alternatives were rejected +- [ ] Consequence includes both benefits and trade-offs diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-add-learning/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-add-learning/SKILL.md new file mode 100644 index 000000000..7ac679724 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-add-learning/SKILL.md @@ -0,0 +1,45 @@ +--- +name: ctx-add-learning +description: "Record a learning. Use when discovering gotchas, bugs, or unexpected behavior that future sessions should know about." +tools: [bash] +--- + +Record a learning in LEARNINGS.md. + +## Before Recording + +Three questions: if any answer is "no", don't record: + +1. **"Could someone Google this in 5 minutes?"** → If yes, skip it +2. **"Is this specific to this codebase?"** → If no, skip it +3. **"Did it take real effort to discover?"** → If no, skip it + +Learnings should capture **principles and heuristics**, not code snippets. + +## When to Use + +- After discovering a gotcha or unexpected behavior +- When a debugging session reveals root cause +- When finding a pattern that will help future work + +## When NOT to Use + +- General programming knowledge (not specific to this project) +- One-off workarounds that won't recur +- Things already documented in the codebase + +## Execution + +```bash +ctx add learning "Title" \ + --context "What were you doing when you discovered this?" \ + --lesson "What's the key insight?" \ + --application "How should we handle this going forward?" +``` + +## Quality Checklist + +- [ ] Context explains what happened (not just what you learned) +- [ ] Lesson is a principle, not a code snippet +- [ ] Application gives actionable guidance for next time +- [ ] Not already in LEARNINGS.md (check first) diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-add-task/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-add-task/SKILL.md new file mode 100644 index 000000000..7090eaabe --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-add-task/SKILL.md @@ -0,0 +1,54 @@ +--- +name: ctx-add-task +description: "Add a task. Use when follow-up work is identified or when breaking down complex work into subtasks." +tools: [bash] +--- + +Add a task to TASKS.md. + +## Before Recording + +Three questions: if any answer is "no", don't record: + +1. **"Is this actionable?"** → If it's a vague wish, clarify first +2. **"Would someone else know what to do?"** → If not, add more detail +3. **"Is this tracked elsewhere?"** → If yes, don't duplicate + +Tasks should describe **what to do and why**, not just a topic. + +## When to Use + +- When follow-up work is identified during a session +- When breaking down a complex task into subtasks +- When the user mentions something that should be tracked + +## When NOT to Use + +- Vague ideas without clear scope (discuss first, then add) +- Work already completed (mark existing tasks done instead) +- One-line fixes you can do right now (just do it) + +## Execution + +```bash +ctx add task "Task description" [--priority high|medium|low] [--section "Phase N"] +``` + +**Good examples:** +```bash +ctx add task "Add --cooldown flag to ctx agent" --priority medium +ctx add task "Investigate ctx init overwriting user content" --priority high +``` + +**Bad examples (too shallow):** +```bash +ctx add task "Fix bug" # What bug? Where? +ctx add task "Improve performance" # Of what? How? +``` + +## Quality Checklist + +- [ ] Task starts with a verb (Add, Fix, Implement, Investigate, Update) +- [ ] Someone unfamiliar with the session could act on it +- [ ] Not a duplicate of an existing task in TASKS.md (check first) +- [ ] Priority set if the user indicated urgency diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-agent/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-agent/SKILL.md new file mode 100644 index 000000000..2475bc6ba --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-agent/SKILL.md @@ -0,0 +1,43 @@ +--- +name: ctx-agent +description: "Load full context packet. Use at session start or when context seems stale or incomplete." +tools: [bash] +--- + +Load the full context packet for AI consumption. + +## When to Use + +- At the start of a session to load all context +- When context seems stale or incomplete +- When switching between different areas of work + +## When NOT to Use + +- The session start hook already runs `ctx agent` automatically: + you rarely need to invoke this manually +- Don't run it just to "refresh" if you already have context loaded + +## After Loading + +**Read the files listed in "Read These Files (in order)"**: the +packet is a summary, not a substitute. In particular, read +CONVENTIONS.md before writing any code. + +Confirm to the user: "I have read the required context files and +I'm following project conventions." + +## Flags + +| Flag | Default | Description | +|--------------|---------|-----------------------------------------------| +| `--budget` | 8000 | Token budget for context packet | +| `--format` | md | Output format: `md` or `json` | +| `--cooldown` | 10m | Suppress repeated output within this duration | +| `--session` | (none) | Session ID for cooldown isolation | + +## Execution + +```bash +ctx agent --budget 4000 +``` diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-architecture/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-architecture/SKILL.md new file mode 100644 index 000000000..0667d8c02 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-architecture/SKILL.md @@ -0,0 +1,69 @@ +--- +name: ctx-architecture +description: "Build and maintain ARCHITECTURE.md and DETAILED_DESIGN.md. Use when working on structure, adding packages, or tracing flow." +tools: [bash, read, write, glob, grep] +--- + +Build and maintain architecture documentation with incremental +coverage tracking. + +## When to Use + +- Working on system structure or adding packages +- Tracing data flow across the codebase +- Onboarding to understand the system +- After significant structural changes + +## When NOT to Use + +- For code-level changes within a single package +- When ARCHITECTURE.md is already up-to-date +- For documentation-only projects + +## Process + +### 1. Scan the codebase + +```bash +ctx status +``` + +Read the existing ARCHITECTURE.md if it exists. +Scan the directory tree to identify: +- Top-level packages and their responsibilities +- Data flow between components +- External dependencies + +### 2. Build or update ARCHITECTURE.md + +Structure: +- **Overview**: 2-3 sentence system description +- **Package Map**: table of packages → responsibilities +- **Data Flow**: how data moves through the system +- **Key Interfaces**: important boundaries +- **Dependencies**: external deps and why they're used + +### 3. Build DETAILED_DESIGN.md (optional) + +Deeper dive into internals for complex packages: +- Function-level documentation +- State machines +- Error handling patterns +- Concurrency model + +### 4. Coverage tracking + +Track which packages have been documented: + +``` +Coverage: 18/24 packages documented (75%) +Missing: internal/hub, internal/crypto, ... +``` + +## Quality Checklist + +- [ ] Every top-level package mentioned +- [ ] Data flow is traceable end-to-end +- [ ] External dependencies listed with rationale +- [ ] Coverage percentage reported +- [ ] No stale references to removed packages diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-archive/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-archive/SKILL.md new file mode 100644 index 000000000..90920e161 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-archive/SKILL.md @@ -0,0 +1,46 @@ +--- +name: ctx-archive +description: "Archive completed tasks. Use when TASKS.md has many completed items cluttering the view." +tools: [bash] +--- + +Move completed tasks from TASKS.md to the archive. + +## Before Archiving + +1. **"Are the completed tasks cluttering the view?"** → If TASKS.md is + still easy to scan, there's no urgency +2. **"Are all `[x]` items truly done?"** → Verify nothing was checked + off prematurely + +## When to Use + +- When TASKS.md has many completed `[x]` tasks +- When the task list is hard to navigate +- Periodically to keep context clean + +## When NOT to Use + +- When there are only a few completed tasks +- When you're unsure if tasks are truly complete (verify first) +- **Never delete tasks**: only archive (CONSTITUTION invariant) + +## Execution + +```bash +# Preview first (recommended) +ctx tasks archive --dry-run + +# Archive after confirming the preview +ctx tasks archive +``` + +Archived tasks go to `archive/tasks-YYYY-MM-DD.md` in the context +directory, preserving Phase headers for traceability. + +## Quality Checklist + +- [ ] Previewed with `--dry-run` before archiving +- [ ] All archived items are truly complete +- [ ] No tasks were deleted (only archived) +- [ ] Reported how many tasks were archived diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-blog-changelog/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-blog-changelog/SKILL.md new file mode 100644 index 000000000..3366a7625 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-blog-changelog/SKILL.md @@ -0,0 +1,132 @@ +--- +name: ctx-blog-changelog +description: "Generate themed blog post from commits. Use when writing about changes between releases or documenting a development arc." +tools: [bash, read, write, edit, glob, grep] +--- + +Generate a blog post about changes since a specific commit, with a given theme. + +## Before Writing + +Two questions; if any answer is "no", reconsider: + +1. **"Is there enough change to tell a story?"** → A handful of typo + fixes doesn't warrant a post +2. **"Is the theme clear?"** → If the commit range covers unrelated + work, narrow the scope or split into multiple posts + +## When to Use + +- When documenting changes between releases +- When writing about a development arc or theme +- When the user wants to explain "what changed and why" + +## When NOT to Use + +- For general project updates without a commit range (use `/ctx-blog`) +- When the changes are minor or routine maintenance +- When there's no unifying theme across the commits + +## Input + +Required: +- **Commit hash**: Starting point (e.g., `040ce99`, `HEAD~50`, `v0.1.0`) +- **Theme**: The narrative angle (e.g., "human-assisted refactoring", + "the recall system") + +Optional: +- **Reference post**: An existing post to match the style + +## Process + +1. **Analyze the commit range**: +```bash +git --no-pager log --oneline ..HEAD +git --no-pager diff --stat ..HEAD +git --no-pager log --format="%s" ..HEAD | head -50 +``` + +2. **Gather supporting context**: +```bash +# Files most changed +git --no-pager diff --stat ..HEAD | sort -t'|' -k2 -rn | head -20 + +# Journal entries from this period +ctx recall list +``` + +3. **Draft the narrative** following the theme +4. Save to `docs/blog/YYYY-MM-DD-slug.md` +5. **Update `docs/blog/index.md`** with an entry at the top: + +```markdown +### [Post Title](YYYY-MM-DD-slug.md) + +*Author / Date* + +2-3 sentence blurb. + +**Topics**: topic-one, topic-two, topic-three + +--- +``` + +## Blog Structure + +### Frontmatter + +```yaml +--- +title: "[Theme]: [Specific Angle]" +date: YYYY-MM-DD +author: [Ask user] +topics: + - topic-one + - topic-two + - topic-three +--- +``` + +### Body + +```markdown +# [Title] + +![ctx](../images/ctx-banner.png) + +> [Hook related to theme] + +## The Starting Point +[State of codebase at , what prompted the change] + +## The Journey +[Narrative of changes, organized by theme not chronology] + +## Before and After +[Comparison table or code diff showing improvement] + +## Key Commits + +| Commit | Change | +|--------|-------------| +| abc123 | Description | + +## Lessons Learned +[Insights from this work] + +## What's Next +[Future work enabled by these changes] +``` + +## Style Guidelines + +- **Personal voice**: Use "I", "we", share the journey +- **Show don't tell**: Include actual code, commits, diffs +- **Tables for comparisons**: Before/after, key commits +- **Honest about failures**: Include what went wrong and why +- **Concrete examples**: Reference specific files, commits, decisions +- **No em-dashes**: Use `:`, `;`, or restructure the sentence instead +- **Straight quotes only**: Use "dumb quotes" (`"`, `'`), never + typographic/curly quotes +- **80-character line width**: Wrap prose at ~80 characters; exceptions + for tables, code blocks, and URLs diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-blog/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-blog/SKILL.md new file mode 100644 index 000000000..bae7e5adf --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-blog/SKILL.md @@ -0,0 +1,57 @@ +--- +name: ctx-blog +description: "Generate blog post drafts from project activity. Use to communicate progress, decisions, or technical insights." +tools: [bash, read, write] +--- + +Generate blog post drafts from project activity. + +## When to Use + +- After completing a significant feature +- When a decision or learning is worth sharing publicly +- For project updates and changelogs +- When the user says "write a blog post about..." + +## When NOT to Use + +- For internal context (use learnings/decisions instead) +- When there's nothing noteworthy to share + +## Process + +### 1. Gather material + +- Recent commits: `git log --oneline -20` +- Recent decisions from DECISIONS.md +- Recent learnings from LEARNINGS.md +- Completed tasks from TASKS.md + +### 2. Identify the narrative + +What's the story? Options: +- Feature announcement +- Technical deep-dive +- Lessons learned +- Project update / changelog + +### 3. Draft the post + +Structure: +- **Title**: clear and engaging +- **Introduction**: what and why (2-3 sentences) +- **Body**: the story with technical details +- **Conclusion**: what's next + +### 4. Write to blog directory + +Target: `site/blog/{date}-{slug}/index.html` or +`docs/blog/{date}-{slug}.md` per project convention. + +## Quality Checklist + +- [ ] Title is clear and engaging +- [ ] Technical accuracy verified +- [ ] No sensitive information exposed +- [ ] Proper frontmatter/metadata +- [ ] Links to relevant specs/docs where appropriate diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-brainstorm/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-brainstorm/SKILL.md new file mode 100644 index 000000000..e2b5ba45e --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-brainstorm/SKILL.md @@ -0,0 +1,132 @@ +--- +name: ctx-brainstorm +description: "Design before implementation. Use before any creative or constructive work to transform vague ideas into validated designs." +tools: [bash, read, write] +--- + +Transform raw ideas into **clear, validated designs** through +structured dialogue **before any implementation begins**. + +## Before Brainstorming + +1. **Check if design is needed**: is the change complex enough? +2. **Review prior art**: check `.context/DECISIONS.md` for related + past decisions +3. **Identify what exists**: read relevant code before asking + questions the codebase already answers + +## When to Use + +- Before implementing a new feature +- Before architectural changes +- Before significant behavior modifications +- When an idea is vague and needs shaping + +## When NOT to Use + +- Bug fixes with clear solutions +- Routine maintenance tasks +- Well-defined requirements +- Small, isolated changes +- When the user explicitly wants to jump to code + +## Operating Mode + +Design facilitator, not builder. No implementation while +brainstorming. + +## The Process + +### 1. Understand Current Context + +Before asking questions: +- Review project state, docs, prior decisions +- Identify what exists vs what is proposed +- Note implicit constraints + +### 2. Clarify the Idea + +Rules: +- Ask **one question per message** +- Prefer **multiple-choice** when possible + +Focus on: +- Purpose: why does this need to exist? +- Users: who benefits? +- Constraints: what limits apply? +- Success criteria: how do we know it works? +- Non-goals: what is explicitly out of scope? + +### 3. Non-Functional Requirements + +Clarify or propose assumptions for: +- Performance, scale, security, reliability, maintenance + +### 4. Understanding Lock (Gate) + +Before proposing any design, provide: + +**Understanding Summary** (5-7 bullets): +- What is being built, why, for whom, constraints, non-goals + +**Assumptions**: list all explicitly. + +**Open Questions**: list unresolved items. + +> "Does this accurately reflect your intent? Confirm or correct +> before we move to design." + +**Do NOT proceed until confirmed.** + +### 5. Explore Design Approaches + +- Propose **2-3 viable approaches** +- Lead with recommended option +- Explain trade-offs + +### 6. Stress-Test the Chosen Approach + +After the user picks an approach: +- Surface assumptions and dependencies +- Identify failure modes +- Steel-man an alternative + +> "These are the risks I see. Do they change your preference?" + +### 7. Present the Design + +Break into digestible sections. Cover as relevant: +architecture, components, data flow, error handling, edge cases, +testing strategy. + +### 8. Decision Log + +Maintain a running log: + +| Decision | Alternatives | Rationale | +|----------|--------------|-----------| +| ... | ... | ... | + +## After the Design + +### Persist to Context + +```bash +ctx add decision "..." --context "..." --rationale "..." +``` + +### Implementation Handoff + +Only after documentation, ask: +> "Ready to begin implementation?" + +## Quality Checklist + +Exit brainstorming **only when**: +- [ ] Understanding Lock confirmed by the user +- [ ] At least one design approach accepted +- [ ] Stress-test completed +- [ ] Major assumptions documented +- [ ] Key risks acknowledged +- [ ] Decision Log complete +- [ ] Decisions persisted to context diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-check-links/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-check-links/SKILL.md new file mode 100644 index 000000000..dac6a0e72 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-check-links/SKILL.md @@ -0,0 +1,136 @@ +--- +name: ctx-check-links +description: "Audit docs for dead links. Use before releases, after restructuring docs, or when running a documentation audit." +tools: [bash, read, glob, grep] +--- + +Scan markdown files for broken links. Two passes: +internal (file targets) and external (HTTP URLs). + +## Scope Discovery + +Determine which directories to scan: + +1. If the user specifies a path, use that +2. Otherwise, glob for common doc directories: `docs/`, `doc/`, + `documentation/`, `site/` +3. If none exist, fall back to scanning all `.md` files in the + project root (excluding `node_modules/`, `.git/`, `vendor/`) + +Report which directories are being scanned at the start of output. + +## When to Use + +- Before releases or doc deployments +- After renaming, moving, or deleting doc pages +- After restructuring documentation directories or nav +- When `/_ctx-audit` runs (audit check #12) +- When a user reports a 404 on the site + +## When NOT to Use + +- When editing a single doc (just eyeball links in that file) +- When offline and only external checks would matter + +## Execution + +### Pass 1: Internal Links + +Scan every `.md` file in the discovered scope for markdown links +pointing to other files: `[text](target.md)`, +`[text](../path/file.md)`, `[text](path/file.md#anchor)`. + +For each link: + +1. Resolve the target **relative to the source file's directory** +2. Strip any `#anchor` fragment before checking file existence +3. Skip external URLs (`http://`, `https://`, `mailto:`) +4. Skip bare anchors (`#section-name`): these are intra-page +5. Verify the target file exists on disk + +Collect all broken internal links as: + +``` +BROKEN: source-file.md:LINE → target.md (file not found) +``` + +### Pass 2: External Links + +Scan every `.md` file in the discovered scope for `http://` and +`https://` URLs in markdown link syntax. + +For each URL: + +1. Send an HTTP HEAD request with a 10-second timeout +2. If HEAD fails or returns 405, retry with GET +3. Record the HTTP status code + +Report failures as: + +``` +WARN: source-file.md:LINE → https://example.com (HTTP 404) +WARN: source-file.md:LINE → https://example.com (timeout) +``` + +**Do not treat external failures as errors.** Network partitions, +rate limiting, and transient outages are common. Report them but +do not fail the check. + +Exceptions: skip these URLs: +- `localhost` / `127.0.0.1` URLs (local dev servers) +- `example.com` / `example.org` (placeholder domains) + +### Pass 3: Image References + +Scan for image links: `![alt](path/to/image.png)` and +`![alt](images/file.jpg)`. + +Verify the image file exists on disk. Same resolution rules as +internal links. + +## Output Format + +``` +## Link Check Report + +### Internal Links +- N broken links found (or "All clear") +- [list of broken links with file:line and target] + +### External Links +- N warnings (or "All reachable") +- [list of failures with file:line, URL, and reason] + +### Images +- N missing images (or "All present") +- [list of missing images with file:line and target] + +### Summary +Internal: N broken / M total +External: N unreachable / M total +Images: N missing / M total +``` + +## Fixing + +For broken internal links, offer specific fixes: + +- If the target was renamed, suggest the new path +- If the target was deleted, suggest removing the link or + pointing to an alternative +- If the target is a typo (close match exists), suggest the + correction + +For external links, just report. The user decides whether to +update, remove, or ignore. + +## Quality Checklist + +After running the check: +- [ ] All `.md` files in the discovered scope were scanned +- [ ] Relative path resolution accounts for subdirectories +- [ ] Anchors stripped before file existence check +- [ ] External check used timeouts (not hanging on slow hosts) +- [ ] localhost/example URLs were skipped +- [ ] Report distinguishes errors (internal) from warnings + (external) diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-commit/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-commit/SKILL.md new file mode 100644 index 000000000..aa63466a4 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-commit/SKILL.md @@ -0,0 +1,90 @@ +--- +name: ctx-commit +description: "Commit with context persistence. Use instead of raw git commit to capture decisions and learnings alongside code changes." +tools: [bash, read, write, edit] +--- + +Commit code changes, then prompt for decisions and learnings +worth persisting. Bridges the gap between committing code and +recording the context behind it. + +## When to Use + +- When committing after meaningful work (feature, bugfix, + refactor) +- When the commit involves a design choice or trade-off +- When the user says "commit" or "commit this" + +## When NOT to Use + +- For trivial commits (typo, formatting): just commit normally +- When the user explicitly says "just commit, no context" +- When nothing has changed + +## Process + +### 1. Pre-commit checks + +Unless the user says "skip checks": + +- Run `git diff --name-only` to see what changed +- If Go files changed, run `go build ./cmd/ctx/...` +- If build fails, stop and report: do not commit broken code + +### 2. Stage and commit + +- Review unstaged changes with `git status` +- Stage relevant files (prefer specific files over `git add -A`) +- Craft a concise commit message: + - If the user provided a message, use it + - If not, draft one based on the changes +- Commit with trailers as required by project conventions + +### 3. Context prompt + +After a successful commit, ask the user: + +> **Any context to capture?** +> +> - **Decision**: Did you make a design choice or trade-off? +> - **Learning**: Did you hit a gotcha or discover something? +> - **Neither**: No context to capture. + +If they provide a decision or learning, record it: + +```bash +ctx add decision "..." +ctx add learning --context "..." --lesson "..." --application "..." +``` + +### 4. Doc drift check + +If committed files include source code that could affect docs, +offer to check for doc drift. + +### 5. Reflect (optional) + +If the commit represents a significant milestone, suggest: + +> This looks like a good checkpoint. Want me to run a quick +> reflection to capture the bigger picture? + +## Commit Message Style + +- Focus on **why**, not what (the diff shows what) +- Concise (1-2 sentences) +- Follow the repository's existing commit style +- Include required trailers (Spec:, Co-authored-by:, etc.) + +## Quality Checklist + +Before committing: +- [ ] Build passes (if Go files changed) +- [ ] Commit message explains the why +- [ ] No secrets in staged changes +- [ ] Specific files staged (not blind `git add -A`) + +After committing: +- [ ] Context prompt was presented +- [ ] Any decisions/learnings were recorded +- [ ] Doc drift check offered if source code changed diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-consolidate/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-consolidate/SKILL.md new file mode 100644 index 000000000..4a36f7280 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-consolidate/SKILL.md @@ -0,0 +1,57 @@ +--- +name: ctx-consolidate +description: "Consolidate redundant entries in LEARNINGS.md or DECISIONS.md. Use when context files grow large with overlapping entries." +tools: [bash, read, write, edit] +--- + +Find and merge duplicate or overlapping entries in context files. + +## When to Use + +- Context files have grown large (50+ entries) +- Multiple entries cover the same topic from different sessions +- After a long project phase where many similar learnings accumulated +- When `ctx status` shows high token counts for context files + +## When NOT to Use + +- Files are small and manageable +- Entries are all distinct +- Just after a fresh `ctx init` + +## Process + +### 1. Read the target file + +Read the full content of the file to consolidate +(LEARNINGS.md or DECISIONS.md). + +### 2. Identify clusters + +Group entries by topic. Look for: +- Same subject with different wording +- Entries that build on each other chronologically +- Contradictory entries (later one supersedes) + +### 3. Propose merges + +For each cluster, propose a consolidated entry: + +> **Cluster: [topic]** (N entries → 1) +> - Entry A: "..." +> - Entry B: "..." +> - **Merged**: "..." +> +> Approve? + +### 4. Apply approved merges + +Replace the cluster entries with the merged version. +Archive originals if requested. + +## Quality Checklist + +- [ ] No information lost in merges +- [ ] Contradictions resolved (latest wins) +- [ ] User approved each merge +- [ ] File is valid markdown after edits diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-doctor/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-doctor/SKILL.md new file mode 100644 index 000000000..710f38f31 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-doctor/SKILL.md @@ -0,0 +1,78 @@ +--- +name: ctx-doctor +description: "Troubleshoot ctx behavior. Runs structural health checks, analyzes event log patterns, and presents findings with suggested actions." +tools: [bash, read] +--- + +Diagnose ctx problems by combining structural health checks with +event log analysis. + +## When to Use + +- User says "doctor", "diagnose", "troubleshoot", "health check" +- User asks "why didn't my hook fire?" +- User says "hooks seem broken" or "context seems stale" + +## When NOT to Use + +- User wants a quick status check (use `ctx-status`) +- User wants to fix drift (use `ctx-drift`) +- User wants to pause hooks (use `ctx-pause`) + +## Diagnostic Playbook + +### Phase 1: Structural Baseline + +```bash +ctx doctor --json +``` + +Parse the JSON output. Note any warnings or errors. + +### Phase 2: Event Log Analysis (if available) + +```bash +ctx system events --json --last 100 +``` + +For specific hooks: +```bash +ctx system events --hook --json --last 20 +``` + +If event logging is not enabled, note: "Enable `event_log: true` +in `.ctxrc` for hook-level diagnostics." + +### Phase 3: Targeted Investigation + +Based on findings, check: +- Hook config for hook registration +- Custom messages: `ctx system message list` +- RC config: read `.ctxrc` +- Reminders: `ctx remind list` + +### Phase 4: Present Findings + +``` +## Doctor Report + +### Structural health +- Summarize ctx doctor results + +### Event analysis (if available) +- Patterns, gaps, or anomalies + +### Suggested actions +- [ ] Actionable items based on findings +``` + +### Phase 5: Suggest, Don't Fix + +Present actionable next steps but do NOT auto-fix anything. + +## Quality Checklist + +- [ ] Ran `ctx doctor` for structural checks +- [ ] Checked event log if available +- [ ] Presented findings in structured format +- [ ] Suggested actions without auto-applying diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-drift/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-drift/SKILL.md index 59cd6f907..c678e8b3d 100644 --- a/internal/assets/integrations/copilot-cli/skills/ctx-drift/SKILL.md +++ b/internal/assets/integrations/copilot-cli/skills/ctx-drift/SKILL.md @@ -1,250 +1,59 @@ --- name: ctx-drift description: "Detect and fix context drift. Use to find stale paths, broken references, and constitution violations in context files." +tools: [bash, read, write, edit, glob, grep] --- Detect context drift at two layers: **structural** (stale paths, missing files, constitution violations) via `ctx drift`, and **semantic** (outdated conventions, superseded decisions, -irrelevant learnings) via agent analysis. The semantic layer is -where the real value is: the CLI cannot do it. +irrelevant learnings) via agent analysis. ## When to Use - At session start to verify context health before working - After refactors, renames, or major structural changes -- When the user asks "is our context clean?", "anything - stale?", or "check for drift" -- Proactively when you notice a path in ARCHITECTURE.md or - CONVENTIONS.md that does not match the actual file tree -- Before a release or milestone to ensure context is accurate +- When the user asks "is our context clean?" or "check for drift" +- Before a release or milestone ## When NOT to Use -- When you just ran `/ctx-status` and everything looked fine - (status already shows drift warnings) -- Repeatedly in the same session without changes in between -- When the user is mid-flow on a task; do not interrupt with - unsolicited maintenance - -## Usage Examples - -```text -/ctx-drift -/ctx-drift (after the refactor) -``` +- When you just ran status and everything looked fine +- Repeatedly in the same session without changes +- Mid-flow when the user is focused on a task ## Execution -Drift detection has two layers: **structural** (programmatic) and -**semantic** (agent-driven). Always do both. - ### Layer 1: Structural Checks -Run the CLI tool for fast, programmatic checks: - ```bash ctx drift ``` -This catches dead paths, missing files, staleness indicators, -and constitution violations. These are necessary but insufficient: -they only detect structural problems. +Catches dead paths, missing files, staleness indicators. ### Layer 2: Semantic Analysis -After the structural check, read the context files yourself and -compare them to what you know about the codebase. This is where -you add real value: the CLI tool cannot do this. - -Check for: - -- **Outdated conventions**: Does CONVENTIONS.md describe patterns - the code no longer follows? Read a few source files in the - relevant area to verify. -- **Superseded decisions**: Does DECISIONS.md contain entries that - were implicitly overridden by later work? Look for decisions - whose rationale no longer applies. -- **Stale architecture descriptions**: Does ARCHITECTURE.md - describe module purposes that have changed? A path can still - exist while its description is wrong. -- **Irrelevant learnings**: Does LEARNINGS.md contain entries - about bugs that were since fixed or patterns that no longer - apply? -- **Contradictions**: Do any context files contradict each other - or contradict the actual code? - -### Reporting - -After both layers, do **not** dump raw output. Instead: - -1. **Summarize findings** by severity (structural warnings, - semantic issues) in plain language -2. **Explain each finding**: what file, what line, why it - matters -3. **Distinguish structural from semantic**: structural issues - can be auto-fixed; semantic issues need the user's judgment -4. **Offer to auto-fix** structural issues: - "I can run `ctx drift --fix` to clean up the dead path - references. Want me to?" -5. **Propose specific edits** for semantic issues: - "CONVENTIONS.md still says 'use fmt.Printf for output' but - we switched to cmd.Printf three weeks ago. Want me to - update it?" -6. **Suggest follow-up commands** when appropriate: - - Many stale paths after a refactor → suggest `ctx sync` - - Heavy task clutter → suggest `ctx compact --archive` - - Old files untouched for weeks → suggest reviewing content - -## Interpreting Results - -| Finding | What It Means | Suggested Action | -|-------------------------------|--------------------------------------------------|------------------------------------------------------| -| Path does not exist | Context references a deleted file/dir | Remove reference or update path | -| Directory is empty | Referenced dir exists but has no files | Remove reference or populate directory | -| Many completed tasks | TASKS.md is cluttered | Run `ctx compact --archive` | -| File not modified in 30+ days | Content may be outdated | Review and update or confirm current | -| Constitution violation | A hard rule may be broken | Fix immediately | -| Missing packages | An `internal/` package is not in ARCHITECTURE.md | Add it with `/ctx-architecture` or document manually | -| Required file missing | A core context file does not exist | Create it with `ctx init` or manually | - -## Auto-Fix - -When the user agrees to auto-fix: - -```bash -ctx drift --fix -``` - -After fixing, run `ctx drift` again to confirm remaining -issues need manual attention. Report what was fixed and what -still needs the user's judgment. - -## Skill Template Drift - -After running `ctx drift`, check whether the project's -installed skills (`.claude/skills/`) match the canonical -templates shipped with `ctx`. - -### Procedure - -1. Create a temp directory and run `ctx init --force` inside - it to get the latest templates: - - ```bash - CTX_TPL_DIR=$(mktemp -d) - cd "$CTX_TPL_DIR" && ctx init --force 2>/dev/null - ``` - -2. Compare each skill in the project against the template: - - ```bash - diff -ru "$CTX_TPL_DIR/.claude/skills/" .claude/skills/ 2>/dev/null - ``` - -3. Clean up the temp directory: - - ```bash - rm -rf "$CTX_TPL_DIR" - ``` - -### Interpreting Skill Drift +After structural check, read context files and compare to the +codebase. Check for: -| Finding | Action | -|--------------------------------------|---------------------------------------------------| -| Skill missing from project | Offer to install: copy from template | -| Skill differs from template | Show the diff; offer to update to latest template | -| Project has extra skills (no match) | These are custom: leave them alone | -| No differences | Skills are up to date; report clean | +- **Outdated conventions**: patterns the code no longer follows +- **Superseded decisions**: entries overridden by later work +- **Stale architecture**: module descriptions that have changed +- **Irrelevant learnings**: entries about fixed bugs +- **Contradictions**: context files contradicting each other -When reporting skill drift, distinguish between: - -- **ctx-managed skills** (present in the template): these - should generally match; differences mean the user's copy - is outdated or was customized intentionally -- **Custom skills** (only in the project): these are user - additions and should not be flagged as drift - -If a skill was intentionally customized, note it and move on. -Offer to update only ctx-managed skills, and always show the -diff before overwriting. - -## Permission Drift - -After checking skills, verify that `.claude/settings.local.json` -has the expected ctx permissions. This file is gitignored, so it -drifts independently from the codebase. - -### Procedure - -1. Read `.claude/settings.local.json` and extract the allow list. - -2. Check for **missing ctx defaults**. Every entry in - `DefaultAllowPermissions()` (defined in - `internal/assets/permissions/allow.txt`) should be present. The current - expected set is: - - - `Bash(ctx:*)`: covers all ctx subcommands - - `Skill(ctx-*)`: one entry per ctx-shipped skill - - To get the authoritative list: - - ```bash - ctx init --force 2>/dev/null # in a temp dir - ``` - - Then compare permissions from the generated - `settings.local.json` against the project's copy. - -3. Check for **stale skill permissions**. If a `Skill(ctx-*)` - entry references a skill that no longer exists in - `.claude/skills/`, flag it. - -4. Check for **missing skill permissions**. If a `ctx-*` skill - exists in `.claude/skills/` but has no corresponding - `Skill(ctx-*)` in the allow list, flag it. - -### Interpreting Permission Drift - -| Finding | Action | -|----------------------------------|---------------------------------------------------------------------| -| Missing `Bash(ctx:*)` | Suggest adding: required for ctx to work | -| Missing `Skill(ctx-*)` entry | Suggest adding: skill will prompt every time | -| Stale `Skill(ctx-*)` entry | Suggest removing: dead reference | -| Granular `Bash(ctx :*)` | Suggest consolidating to `Bash(ctx:*)` | -| One-off / session debris entries | Note as hygiene issue (see `hack/runbooks/sanitize-permissions.md`) | - -### Important - -Do **not** edit `settings.local.json` directly. Report findings -and let the user make changes. This file controls agent -permissions: self-modification is a security concern. Refer -users to `hack/runbooks/sanitize-permissions.md` for the manual cleanup -procedure. - -## Proactive Use - -Run drift detection without being asked when: - -- You load context at session start and notice a path - reference that does not match the file tree -- The user just completed a refactor that renamed or moved - files -- TASKS.md has obviously heavy clutter (20+ completed items - visible when you read it) - -When running proactively, keep the report brief: +### Reporting -> I ran a quick drift check after the refactor. Two stale -> path references in ARCHITECTURE.md. Want me to clean -> them up? +1. Summarize findings by severity +2. Explain each finding: what file, why it matters +3. Distinguish structural from semantic +4. Offer to auto-fix structural: `ctx drift --fix` +5. Propose specific edits for semantic issues ## Quality Checklist -After running drift detection, verify: -- [ ] Summarized findings in plain language (did not just - paste raw CLI output) +- [ ] Summarized findings (did not dump raw output) - [ ] Explained why each finding matters -- [ ] Offered auto-fix for fixable issues before running it -- [ ] Suggested appropriate follow-up commands +- [ ] Offered auto-fix before running it - [ ] Did not run `--fix` without user confirmation diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-implement/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-implement/SKILL.md new file mode 100644 index 000000000..6e13828bb --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-implement/SKILL.md @@ -0,0 +1,129 @@ +--- +name: ctx-implement +description: "Execute a plan step-by-step with verification. Use when you have a plan document and need disciplined, checkpointed implementation." +tools: [bash, read, write, edit, glob, grep] +--- + +Take a plan (inline text, file path, or from the conversation) +and execute it step-by-step with build/test verification between +steps. + +## When to Use + +- When the user provides a plan document or file and says + "implement this" +- When a multi-step task has been planned and needs disciplined + execution +- When the user wants checkpointed progress with verification + at each step +- After `ctx-brainstorm` or plan mode produces an approved plan + +## When NOT to Use + +- For single-step tasks: just do them directly +- When the plan is vague or incomplete: use `ctx-brainstorm` + first to refine it +- When the user wants to explore or discuss, not execute +- When changes are trivial (typo fix, config tweak) + +## Process + +### 1. Load the plan + +- If a file path is provided, read it +- If inline text is provided, use it directly +- If neither, look back in the conversation for the most + recent plan or approved design +- If no plan can be found, ask the user for one + +### 2. Break into steps + +Parse the plan into discrete, checkable steps. Each step +should be: +- **Atomic**: one logical change (a file, a function, a test) +- **Verifiable**: has a clear pass/fail check +- **Ordered**: dependencies respected (create before use, + test after implement) + +Present the step list to the user for confirmation: + +> **Implementation plan** (N steps): +> +> 1. [Step description] - verify: [check] +> 2. [Step description] - verify: [check] +> 3. ... +> +> Ready to start? + +### 3. Execute step-by-step + +For each step: + +1. **Announce** what you're doing (one line) +2. **Think through** the change before writing code +3. **Implement** the change +4. **Verify** with the appropriate check: + - Go code changed → `go build ./cmd/ctx/...` + - Tests affected → `go test ./...` + - Config/template changed → build to verify embeds + - Docs only → no verification needed +5. **Report** step result: pass or fail +6. **If failed**: stop, diagnose, fix, re-verify before + moving to the next step + +### 4. Checkpoint progress + +After every 3-5 steps (or after a significant milestone): +- Summarize what has been completed +- Note any deviations from the plan +- Ask the user if they want to continue, adjust, or stop + +### 5. Wrap up + +After all steps complete: +- Run a final full verification +- Summarize what was implemented +- Note any deviations from the original plan +- Suggest context to persist (decisions, learnings, tasks) + +## Step Verification Map + +| Change type | Verification command | +|--------------------|--------------------------------| +| Go source code | `go build ./cmd/ctx/...` | +| Test files | `go test ./...` | +| Templates/embeds | `go build ./cmd/ctx/...` | +| Makefile | Run the changed target | +| Skill files | Build to verify embed | +| Docs/markdown only | None required | +| Shell scripts | `bash -n script.sh` | + +## Handling Failures + +When a step fails verification: + +1. Read the error output carefully +2. Reason through the failure before attempting a fix +3. Fix the issue in the current step +4. Re-verify the fix +5. Only then move to the next step + +If a step fails repeatedly (3+ attempts), stop and ask the +user for guidance. + +## Quality Checklist + +Before starting: +- [ ] Plan exists and is clear enough to execute +- [ ] Steps are broken down and presented to the user +- [ ] User confirmed readiness to proceed + +During execution: +- [ ] Each step is verified before moving on +- [ ] Failures are fixed in place, not deferred +- [ ] Checkpoints happen every 3-5 steps + +After completion: +- [ ] Final full verification passes +- [ ] Deviations from plan are noted +- [ ] Context persistence is suggested if warranted diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-import-plans/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-import-plans/SKILL.md new file mode 100644 index 000000000..7f72bb741 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-import-plans/SKILL.md @@ -0,0 +1,56 @@ +--- +name: ctx-import-plans +description: "Import plan files into project specs directory. Use to convert external plans into project-tracked specs." +tools: [bash, read, write] +--- + +Import plan files into the project's `specs/` directory. + +## When to Use + +- When plan files exist outside the project (e.g., from AI + tool plan modes) +- When converting external design docs to project specs +- When the user says "import that plan" + +## When NOT to Use + +- Plan is already in `specs/` +- Plan is too vague to be a spec (brainstorm first) + +## Process + +### 1. Locate the plan + +If path provided, read it. Otherwise, check common locations: +- Current conversation context +- Session workspace files + +### 2. Convert to spec format + +Map plan sections to the spec template structure: +- Problem → Problem +- Steps/Tasks → Implementation +- Goals → Happy Path +- Risks → Edge Cases + +### 3. Handle conflicts + +If `specs/{name}.md` already exists: +- Compare contents +- Offer to merge, replace, or rename + +### 4. Write the spec + +Write to `specs/{name}.md`. + +### 5. Create tasks (optional) + +Offer to break the spec into tasks in TASKS.md. + +## Quality Checklist + +- [ ] Spec follows project template structure +- [ ] No conflicts with existing specs +- [ ] File written to correct location +- [ ] Tasks offered if applicable diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich-all/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich-all/SKILL.md new file mode 100644 index 000000000..cbf9396de --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich-all/SKILL.md @@ -0,0 +1,59 @@ +--- +name: ctx-journal-enrich-all +description: "Batch journal pipeline: export unexported sessions then enrich all unenriched entries." +tools: [bash, read, write, edit] +--- + +Full journal pipeline: import sessions and batch-enrich entries. + +## When to Use + +- Backlog of unenriched journal entries +- After many sessions without journal maintenance +- When running periodic journal housekeeping + +## When NOT to Use + +- No journal entries exist +- All entries are already enriched +- Single entry (use `ctx-journal-enrich` instead) + +## Process + +### 1. Import unexported sessions + +```bash +ctx recall export --all +``` + +### 2. List unenriched entries + +```bash +ctx journal list --unenriched +``` + +### 3. Batch enrich + +For each unenriched entry: +1. Read the entry content +2. Generate appropriate frontmatter +3. Write the enriched version +4. Report progress + +For large backlogs (20+ entries), use heuristic enrichment: +derive metadata from filename patterns and entry headings +without reading full content. + +### 4. Report + +``` +Enriched: 15/15 entries +Skipped: 3 (already enriched) +``` + +## Quality Checklist + +- [ ] All unexported sessions imported first +- [ ] Each enriched entry has valid frontmatter +- [ ] Progress reported during batch +- [ ] No entries corrupted or lost diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich/SKILL.md new file mode 100644 index 000000000..d9a27f0f1 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich/SKILL.md @@ -0,0 +1,60 @@ +--- +name: ctx-journal-enrich +description: "Enrich a journal entry with YAML frontmatter metadata. Use to add type, outcome, topics, and technologies to session records." +tools: [bash, read, write, edit] +--- + +Enrich individual journal entries with structured metadata. + +## When to Use + +- After exporting a session to the journal +- When journal entries lack metadata for search/filter +- When `ctx journal` shows unenriched entries + +## When NOT to Use + +- Entry is already fully enriched +- No journal entries exist + +## Process + +### 1. Identify the entry + +If not specified, find unenriched entries: + +```bash +ctx journal list --unenriched +``` + +### 2. Read the entry + +Read the full session content to understand what happened. + +### 3. Generate frontmatter + +Add or update YAML frontmatter with: + +```yaml +--- +type: feature|bugfix|refactor|research|planning|review +outcome: completed|partial|blocked|abandoned +topics: [topic1, topic2] +technologies: [go, typescript, ...] +summary: "One-line summary of the session" +--- +``` + +### 4. Write enriched entry + +Update the file with the new frontmatter while preserving +the body content. + +## Quality Checklist + +- [ ] Frontmatter is valid YAML +- [ ] Type matches the actual work done +- [ ] Outcome is accurate +- [ ] Topics are specific, not generic +- [ ] Summary is one clear sentence +- [ ] Body content is preserved unchanged diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-journal-normalize/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-journal-normalize/SKILL.md new file mode 100644 index 000000000..298f5dc28 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-journal-normalize/SKILL.md @@ -0,0 +1,46 @@ +--- +name: ctx-journal-normalize +description: "Normalize journal source markdown for clean rendering. Use after journal site shows rendering issues: fence nesting, metadata formatting, broken lists." +tools: [bash, read, write, edit] +--- + +Reconstruct journal entries as clean markdown from stripped plain text. + +## When to Use + +- After `ctx journal site` shows rendering issues +- When journal entries have fence nesting problems +- When metadata blocks render as raw `**Key**: value` +- Before running `ctx-journal-enrich` (clean markdown improves extraction) + +## When NOT to Use + +- On entries already normalized (check `.state.json`) +- When the site renders correctly +- On non-journal markdown files + +## Output Rules + +1. **Fences**: Always use backtick fences. Innermost code gets + 3 backticks. Each nesting level adds 1. +2. **Metadata**: `**Key**: value` blocks become collapsed `
`. +3. **Tool output**: Collapse into `
` when > 10 lines. +4. **Lists**: 2-space indent per level. +5. **No invented content**: Every word in output traces to input. + +## Process + +1. **Backup first**: copy journal directory to `.bak` sibling +2. Identify files to normalize (skip already-normalized via `.state.json`) +3. Process files turn-by-turn (not whole file at once) +4. Write back the fixed files +5. Mark normalized: `ctx system mark-journal normalized` +6. Regenerate site: `ctx journal site --build` +7. Report what changed + +## Quality Checklist + +- [ ] Backup created before modifying +- [ ] Already-normalized files skipped +- [ ] No content was invented or lost +- [ ] State file updated for processed entries diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-loop/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-loop/SKILL.md new file mode 100644 index 000000000..0d0edde19 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-loop/SKILL.md @@ -0,0 +1,62 @@ +--- +name: ctx-loop +description: "Generate autonomous iteration loop scripts for headless AI tool runs with configurable completion signals." +tools: [bash, read, write] +--- + +Generate shell scripts for autonomous AI iteration loops. + +## When to Use + +- Setting up CI-driven AI workflows +- When a task needs autonomous iteration with checks +- For batch processing with verification gates + +## When NOT to Use + +- Interactive work (just do it in the session) +- Simple single-run tasks +- When safety checks aren't defined + +## Process + +### 1. Define the loop + +Gather: +- **Command**: what to run each iteration +- **Completion signal**: how to detect "done" (exit code, output pattern, file exists) +- **Max iterations**: safety limit (default: 10) +- **Checkpoint command**: what to run between iterations + +### 2. Generate the script + +```bash +#!/bin/bash +set -euo pipefail +MAX_ITER=${1:-10} +for i in $(seq 1 "$MAX_ITER"); do + echo "=== Iteration $i/$MAX_ITER ===" + # Run the task + {command} + # Check completion + if {completion_check}; then + echo "✅ Complete after $i iterations" + exit 0 + fi + # Checkpoint + {checkpoint} +done +echo "❌ Max iterations reached" +exit 1 +``` + +### 3. Write and verify + +Write to the requested location. Verify with `bash -n`. + +## Quality Checklist + +- [ ] Max iterations has a sane default +- [ ] Completion signal is well-defined +- [ ] Script has `set -euo pipefail` +- [ ] Script passes `bash -n` syntax check diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-next/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-next/SKILL.md index 58181d247..e17e48034 100644 --- a/internal/assets/integrations/copilot-cli/skills/ctx-next/SKILL.md +++ b/internal/assets/integrations/copilot-cli/skills/ctx-next/SKILL.md @@ -1,6 +1,7 @@ --- name: ctx-next description: "Suggest what to work on next. Use when starting a session, finishing a task, or when unsure what to prioritize." +tools: [bash, read, glob, grep] --- Analyze current tasks and recent session activity, then suggest @@ -19,13 +20,6 @@ Analyze current tasks and recent session activity, then suggest - When actively mid-task (don't interrupt flow with suggestions) - When no context directory exists (nothing to analyze) -## Usage Examples - -```text -/ctx-next -/ctx-next (just finished the auth refactor) -``` - ## Process Do all of this **silently**: do not narrate the steps: @@ -35,7 +29,7 @@ Do all of this **silently**: do not narrate the steps: 2. **Check recent sessions** to understand what was just worked on and avoid suggesting already-completed work: ```bash - ctx journal source --limit 3 + ctx recall list --limit 3 ``` 3. **Read the most recent session file** (if any) to understand what was accomplished and what follow-up items were noted @@ -101,41 +95,6 @@ useful)* - If an in-progress task exists, it should almost always be recommendation #1 (don't abandon unfinished work) -## Examples - -### Good Output - -> ### Recommended Next -> -> **1. Fix `block-non-path-ctx` hook** `#priority:high` -> > Still open from yesterday's session. The hook is too -> > aggressive: it blocks `git -C path` commands that don't -> > invoke ctx. Quick fix, clears a blocker. -> -> **2. Add `Context.File(name)` method** `#priority:high` -> > Eliminates 10+ linear scan boilerplate instances across -> > 5 packages. High impact, low effort: good consolidation -> > target. -> -> **3. Topics system (T1.1)** `#priority:medium` -> > Journal site's most impactful remaining feature. Metadata -> > is already in place from the enrichment work. -> -> --- -> -> *Based on 24 pending tasks across 3 phases. Last session: -> doc-drift-cleanup (2026-02-11).* - -### Bad Output - -> "You have many tasks. Here are some options: -> - Do some stuff with hooks -> - Maybe work on tests -> - There's also some docs to write" - -(Too vague, no priorities, no rationale, no connection to -context.) - ## Quality Checklist Before presenting recommendations, verify: diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-pad/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-pad/SKILL.md new file mode 100644 index 000000000..9f4e3ccab --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-pad/SKILL.md @@ -0,0 +1,140 @@ +--- +name: ctx-pad +description: "Manage encrypted scratchpad. Use for short, sensitive one-liners that travel with the project." +tools: [bash] +--- + +Manage the encrypted scratchpad via `ctx pad` commands using +natural language. Translate what the user says into the right +command. + +## When to Use + +- User wants to jot down a quick note, reminder, or sensitive value +- User asks to see, add, remove, edit, or reorder scratchpad entries +- User mentions "scratchpad", "pad", "notes", or "sticky notes" +- User says "jot down", "remember this", "note to self" + +## When NOT to Use + +- For structured tasks (use `ctx add task` instead) +- For architectural decisions (use `ctx add decision` instead) +- For lessons learned (use `ctx add learning` instead) + +## Command Mapping + +| User intent | Command | +|------------------------------------------------------------|--------------------------------------------| +| "show my scratchpad" / "what's on my pad" | `ctx pad` | +| "show me entry 3" / "what's in entry 3" | `ctx pad show 3` | +| "add a note: check DNS" / "jot down: check DNS" | `ctx pad add "check DNS"` | +| "delete the third one" / "remove entry 3" | `ctx pad rm 3` | +| "change entry 2 to ..." / "replace entry 2 with ..." | `ctx pad edit 2 "new text"` | +| "append '-- important' to entry 3" / "add to entry 3: ..." | `ctx pad edit 3 --append "-- important"` | +| "prepend 'URGENT:' to entry 1" | `ctx pad edit 1 --prepend "URGENT:"` | +| "move entry 4 to the top" / "prioritize entry 4" | `ctx pad mv 4 1` | +| "move entry 1 to the bottom" | `ctx pad mv 1 N` (where N = last position) | +| "import my notes from notes.txt" | `ctx pad import notes.txt` | +| "import from stdin" / pipe into pad | `cmd | ctx pad import -` | +| "export all blobs" / "extract blobs to DIR" | `ctx pad export [DIR]` | +| "export blobs, overwrite existing" | `ctx pad export --force [DIR]` | +| "merge entries from another pad" | `ctx pad merge FILE...` | +| "merge with a different key" | `ctx pad merge --key /path/to/key FILE` | + +## Execution + +**List entries:** +```bash +ctx pad +``` + +**Show a single entry (raw text, pipe-friendly):** +```bash +ctx pad show 3 +``` + +**Add an entry:** +```bash +ctx pad add "remember to check DNS config on staging" +``` + +**Remove an entry:** +```bash +ctx pad rm 2 +``` + +**Replace an entry:** +```bash +ctx pad edit 1 "updated note text" +``` + +**Append to an entry:** +```bash +ctx pad edit 3 --append " - this is important" +``` + +**Prepend to an entry:** +```bash +ctx pad edit 1 --prepend "URGENT: " +``` + +**Move an entry:** +```bash +ctx pad mv 3 1 # move entry 3 to position 1 +``` + +**Compose entries (pipe show into edit):** +```bash +ctx pad edit 1 --append "$(ctx pad show 3)" +``` + +**Import lines from a file:** +```bash +ctx pad import notes.txt +``` + +**Import from stdin:** +```bash +grep TODO *.go | ctx pad import - +``` + +**Export blobs to a directory:** +```bash +ctx pad export ./ideas +ctx pad export --dry-run # preview without writing +ctx pad export --force ./backup # overwrite existing files +``` + +**Merge entries from another scratchpad:** +```bash +ctx pad merge worktree/.context/scratchpad.enc +ctx pad merge --key /path/to/other.key foreign.enc +ctx pad merge --dry-run pad-a.enc pad-b.md +``` + +## Interpreting User Intent + +When the user's intent is ambiguous: + +- "update entry 2" with new text → **replace** (full rewrite) +- "add X to entry 2" → **append** (partial update) +- "put X before entry 2's text" → **prepend** +- "prioritize" / "bump up" / "move to top" → **mv N 1** +- "deprioritize" / "move to bottom" → **mv N last** + +When the user says "add": check context: +- "add a note" / "add to my pad" → `ctx pad add` (new entry) +- "add to entry 3" / "add this to the third one" → `ctx pad edit 3 --append` (modify existing) + +## Important Notes + +- Keep the encryption key path (`~/.ctx/.ctx.key`) internal to + `ctx pad` commands: exposing it grants full decryption access + to all pad entries +- Always use `ctx pad` to access entries: reading `scratchpad.enc` + directly yields unreadable ciphertext +- If the user gets a "no key" error, tell them to obtain the + key file from a teammate +- Entries are one-liners; do not add multi-line content +- After modifying, show the updated scratchpad so the user can + verify the change diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-pause/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-pause/SKILL.md new file mode 100644 index 000000000..a0c85ddf4 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-pause/SKILL.md @@ -0,0 +1,47 @@ +--- +name: ctx-pause +description: "Pause context nudge/reminder hooks for the session. Security hooks remain active." +tools: [bash] +--- + +Temporarily pause context nudge and reminder hooks while keeping +security hooks active. + +## When to Use + +- When hooks are too noisy during focused work +- When doing rapid iteration and nudges interrupt flow +- When the user says "pause hooks" or "too many reminders" + +## When NOT to Use + +- At session start (hooks haven't fired yet) +- When the user wants to disable security hooks (not supported) + +## Process + +```bash +ctx system pause-hooks +``` + +This suppresses: +- Ceremony checks (remember, wrap-up) +- Persistence nudges +- Task completion checks +- Journal reminders + +This does NOT suppress: +- Dangerous command blocking +- Context load gate +- Version checks + +## Resuming + +Use `ctx-resume` to re-enable hooks, or they automatically +resume at next session start. + +## Quality Checklist + +- [ ] User confirmed they want to pause +- [ ] Security hooks remain active +- [ ] Informed user how to resume diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-prompt-audit/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-prompt-audit/SKILL.md new file mode 100644 index 000000000..c3547bb14 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-prompt-audit/SKILL.md @@ -0,0 +1,54 @@ +--- +name: ctx-prompt-audit +description: "Analyze session transcripts to identify vague prompts that caused unnecessary clarification cycles." +tools: [bash, read, write] +--- + +Analyze session history to find prompts that led to wasted work +due to ambiguity, and suggest improvements. + +## When to Use + +- After a session with many back-and-forth clarifications +- When improving prompt discipline +- During periodic workflow reviews + +## When NOT to Use + +- No session history exists +- Sessions were straightforward + +## Process + +### 1. Load recent sessions + +```bash +ctx recall list --limit 5 +``` + +### 2. Scan for patterns + +Look for: +- Multiple clarifying questions before work began +- Misunderstood instructions leading to rework +- Vague requests like "fix it" or "make it better" +- Missing context that was discovered mid-task + +### 3. Categorize findings + +| Pattern | Example | Improvement | +|---------|---------|-------------| +| Vague scope | "Fix the tests" | "Fix TestFoo in internal/cli — it's failing on empty input" | +| Missing context | "Add a feature" | "Add JSON output to ctx status (see spec in specs/)" | +| Ambiguous reference | "Update that file" | "Update internal/config/mcp/tool/tool.go" | + +### 4. Present recommendations + +Provide actionable suggestions for clearer prompts. + +## Quality Checklist + +- [ ] At least 3 sessions analyzed +- [ ] Patterns categorized with examples +- [ ] Concrete improvements suggested +- [ ] No session data exposed inappropriately diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-prompt/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-prompt/SKILL.md new file mode 100644 index 000000000..3cd99bc47 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-prompt/SKILL.md @@ -0,0 +1,49 @@ +--- +name: ctx-prompt +description: "Apply, list, and manage saved prompt templates from .context/prompts/. Use when the user asks to apply, list, or create a reusable template like code-review or refactor." +tools: [bash, read, write] +--- + +Apply reusable prompt templates from `.context/prompts/`. + +## When to Use + +- User says "use the code-review prompt" or "apply the refactor template" +- User asks to list, create, or manage prompt templates +- User mentions "prompt template" or "reusable prompt" + +## When NOT to Use + +- For structured context entries (use `ctx add` instead) +- For full workflow automation (use a dedicated skill instead) +- For scratchpad notes (use `ctx pad` instead) + +## Command Mapping + +| User intent | Command | +|----------------------------------|---------------------------------| +| "list my prompts" | `ctx prompt list` | +| "show the code-review prompt" | `ctx prompt show code-review` | +| "create a new prompt" | `ctx prompt add --stdin` | +| "delete the debug prompt" | `ctx prompt rm debug` | + +## Execution + +**When no name is given:** +```bash +ctx prompt list +``` + +**When a name is given:** +```bash +ctx prompt show +``` + +Read the prompt content, then follow the instructions in the +prompt applied to the user's current context. + +## Quality Checklist + +- [ ] Used correct subcommand for user intent +- [ ] Prompt content was applied, not just displayed +- [ ] If prompt not found, suggested `ctx prompt list` diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-recall/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-recall/SKILL.md index 5db979773..2ec6e56b9 100644 --- a/internal/assets/integrations/copilot-cli/skills/ctx-recall/SKILL.md +++ b/internal/assets/integrations/copilot-cli/skills/ctx-recall/SKILL.md @@ -1,6 +1,7 @@ --- name: ctx-recall description: "Browse session history. Use when referencing past discussions or finding context from previous work." +tools: [bash] --- Browse, inspect, and export AI session history. @@ -9,34 +10,53 @@ Browse, inspect, and export AI session history. - When the user asks "what did we do last time?" - When looking for context from previous work sessions -- When exporting sessions to the journal +- When exporting sessions to the journal for enrichment - When searching for a specific session by topic or date ## When NOT to Use -- When the user just wants current context (use ctx-status instead) +- When the user just wants current context (use `ctx-status` or + `ctx-agent` instead) - For modifying session content (recall is read-only) -## Execution +## Subcommands -List recent sessions: +### `ctx recall list` ```bash ctx recall list --limit 5 ``` -Show details of a specific session: +### `ctx recall show` ```bash +ctx recall show ctx recall show --latest -ctx recall show ``` -Export sessions to journal markdown: +### `ctx recall export` +```bash +ctx recall export --all # Export new sessions only +ctx recall export --all --regenerate # Re-export all +``` + +## Typical Workflows + +**"What did we work on recently?"** +```bash +ctx recall list --limit 5 +``` + +**"Export everything to the journal"** ```bash ctx recall export --all ``` -After listing sessions, summarize relevant findings rather than -dumping raw output. +Then suggest `ctx-journal-enrich-all` for enrichment. + +## Quality Checklist + +- [ ] Used the right subcommand for user intent +- [ ] Applied filters if user mentioned project, date, or topic +- [ ] For export, mentioned the normalize/enrich pipeline diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-reflect/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-reflect/SKILL.md new file mode 100644 index 000000000..5f83f3ef0 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-reflect/SKILL.md @@ -0,0 +1,75 @@ +--- +name: ctx-reflect +description: "Reflect on session progress. Use at natural breakpoints, after unexpected behavior, or when shifting to a different task." +tools: [bash, read] +--- + +Pause and reflect on this session. Review what has been +accomplished and identify context worth persisting. + +## When to Use + +- At natural breakpoints (feature complete, bug fixed, task done) +- After unexpected behavior or a debugging detour +- When shifting from one task to a different one +- When the session may end soon +- When the user explicitly asks to reflect + +## When NOT to Use + +- At the very start of a session (nothing to reflect on) +- After trivial changes (a typo fix does not need reflection) +- When the user is in flow: do not interrupt + +## Reflection Checklist + +Step back and reason through the session as a whole before +listing items. + +### 1. Learnings + +- Did we discover any gotchas or unexpected behavior? +- Did we learn something about the codebase or tools? +- Would this help a future session avoid problems? +- Is it specific to this project? + +### 2. Decisions + +- Did we make any architectural or design choices? +- Did we choose between alternatives? What was the trade-off? +- Should the rationale be captured? + +### 3. Tasks + +- Did we complete any tasks? (Mark done in TASKS.md) +- Did we start any tasks not yet finished? +- Should new tasks be added for follow-up work? + +### 4. Session Notes + +- Was this a significant session worth a full snapshot? +- Are there open threads a future session needs to pick up? + +## Output Format + +1. **Summary**: what was accomplished (2-3 sentences) +2. **Suggested persists**: list what should be saved, with + the specific command for each item +3. **Offer**: ask the user which items to persist + +## Persistence Commands + +| What to persist | Command | +|------------------|-----------------------------------------------------------------------| +| Learning | `ctx add learning --context "..." --lesson "..." --application "..."` | +| Decision | `ctx add decision "..."` | +| Task completed | Edit TASKS.md directly | +| New task | `ctx add task "..."` | + +## Quality Checklist + +- [ ] Every suggested persist has a concrete command +- [ ] Learnings are project-specific, not general knowledge +- [ ] Decisions include trade-off rationale +- [ ] No empty checklist categories +- [ ] User is asked before anything is persisted diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md new file mode 100644 index 000000000..a0b8f991b --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md @@ -0,0 +1,69 @@ +--- +name: ctx-remember +description: "Recall project context and present structured readback. Use when the user asks 'do you remember?', at session start, or when context seems lost." +tools: [bash, read] +--- + +Recall project context and present a structured readback as if +remembering, not searching. + +## Before Recalling + +Check that the context directory exists. If it does not, tell the +user: "No context directory found. Run `ctx init` to set up context +tracking, then there will be something to remember." + +## When to Use + +- The user asks "do you remember?", "what were we working on?", + or any memory-related question +- At the start of a session when context is not yet loaded +- When context seems lost or stale mid-session + +## When NOT to Use + +- Context was already loaded this session: don't re-fetch +- Mid-session when actively working and context is fresh +- When asking about a specific past session by name: use + `ctx-recall` instead + +## Process + +Do all of this **silently** — no narration of the steps: + +1. **Load context packet**: + ```bash + ctx agent --budget 4000 + ``` +2. **Read the files** listed in the packet's "Read These Files" + section (TASKS.md, DECISIONS.md, LEARNINGS.md, etc.) +3. **List recent sessions**: + ```bash + ctx recall list --limit 3 + ``` +4. **Present the structured readback** + +## Readback Format + +**Last session**: Topic, date, and what was accomplished. + +**Active work**: Pending and in-progress tasks from TASKS.md. + +**Recent context**: 1-2 recent decisions or learnings. + +**Next step**: Suggest what to work on next or ask for direction. + +## Readback Rules + +- Open directly with the readback: not "I don't have memory" +- Skip preamble like "Let me check": go straight to readback +- Present findings as recall, not discovery +- Be honest about the mechanism only if explicitly asked + +## Quality Checklist + +- [ ] Context packet was loaded +- [ ] Files from the read order were actually read +- [ ] Structured readback has all four sections +- [ ] No narration of the discovery process +- [ ] Readback feels like recall, not a file system tour diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-remind/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-remind/SKILL.md new file mode 100644 index 000000000..1d2c9b806 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-remind/SKILL.md @@ -0,0 +1,46 @@ +--- +name: ctx-remind +description: "Manage session reminders. Use when the user says 'remind me to...' or asks about pending reminders." +tools: [bash] +--- + +Manage session-scoped reminders via `ctx remind` commands. + +## When to Use + +- User says "remind me to..." or "remind me about..." +- User asks "what reminders do I have?" +- User wants to dismiss or clear reminders + +## When NOT to Use + +- For structured tasks with status tracking (use `ctx add task`) +- For sensitive values or quick notes (use `ctx pad`) +- Create a reminder only when the user explicitly says "remind me" + +## Command Mapping + +| User intent | Command | +|----------------------------------|--------------------------------------------| +| "remind me to refactor swagger" | `ctx remind "refactor swagger"` | +| "remind me tomorrow to check CI" | `ctx remind "check CI" --after YYYY-MM-DD` | +| "what reminders do I have?" | `ctx remind list` | +| "dismiss reminder 3" | `ctx remind dismiss 3` | +| "clear all reminders" | `ctx remind dismiss --all` | + +## Natural Language Date Handling + +The CLI only accepts `YYYY-MM-DD` for `--after`. Convert natural +language dates to this format: + +| User says | You run | +|----------------|-------------------------------------------------| +| "next session" | `ctx remind "..."` (no `--after`) | +| "tomorrow" | `ctx remind "..." --after YYYY-MM-DD` | +| "next week" | `ctx remind "..." --after YYYY-MM-DD` (+7 days) | + +## Important Notes + +- Reminders fire **every session** until dismissed: no throttle +- The `--after` flag gates when a reminder starts appearing +- Reminders are stored in `.context/reminders.json` (committed to git) diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-resume/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-resume/SKILL.md new file mode 100644 index 000000000..6a60267c3 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-resume/SKILL.md @@ -0,0 +1,35 @@ +--- +name: ctx-resume +description: "Resume context hooks after a pause." +tools: [bash] +--- + +Re-enable context hooks that were paused with `ctx-pause`. + +## When to Use + +- After a focused work period where hooks were paused +- When the user is ready for nudges and reminders again +- When the user says "resume hooks" + +## When NOT to Use + +- Hooks are not currently paused +- At session start (hooks auto-resume) + +## Process + +```bash +ctx system resume-hooks +``` + +This re-enables all non-security hooks: +- Ceremony checks +- Persistence nudges +- Task completion checks +- Journal reminders + +## Quality Checklist + +- [ ] Hooks were actually paused before resuming +- [ ] Confirmed hooks are active again diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-sanitize-permissions/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-sanitize-permissions/SKILL.md new file mode 100644 index 000000000..e4761062c --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-sanitize-permissions/SKILL.md @@ -0,0 +1,67 @@ +--- +name: ctx-sanitize-permissions +description: "Audit tool permissions for dangerous or overly broad entries. Use to ensure safe agent configuration." +tools: [bash, read, write] +--- + +Audit agent permission configurations for dangerous patterns. + +## When to Use + +- After initial project setup +- When reviewing security posture +- When permissions seem overly broad +- Before sharing a project configuration + +## When NOT to Use + +- No permission config exists +- Already audited recently + +## Categories to Check + +### 1. Hook bypass permissions +Permissions that disable safety hooks entirely. + +### 2. Destructive command permissions +Allow patterns that cover `rm -rf`, `git push --force`, +`git reset --hard`, etc. + +### 3. Injection vectors +Overly broad shell permissions that could allow arbitrary +command execution. + +### 4. Overly broad wildcards +Permissions like `Bash(*)` or `Write(*)` that grant +unrestricted access. + +## Process + +1. Read the permission configuration file +2. Check each entry against the four categories +3. Flag dangerous entries with severity level +4. Propose safer alternatives +5. Apply fixes with user approval + +## Output Format + +``` +## Permission Audit Results + +### 🔴 Critical (N) +1. `Bash(*)` — unrestricted shell access + → Suggest: scope to specific commands + +### 🟡 Warning (N) +1. `Write(/etc/*)` — write access to system dirs + → Suggest: remove or scope to project + +### ✅ Clean (N entries passed) +``` + +## Quality Checklist + +- [ ] All permission entries reviewed +- [ ] Critical items flagged +- [ ] Safer alternatives proposed +- [ ] No changes made without user approval diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-skill-audit/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-skill-audit/SKILL.md new file mode 100644 index 000000000..fbe310653 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-skill-audit/SKILL.md @@ -0,0 +1,78 @@ +--- +name: ctx-skill-audit +description: "Audit skills against prompting best practices. Check for quality, consistency, and common anti-patterns." +tools: [bash, read, glob, grep] +--- + +Audit skill files for quality, consistency, and adherence to +prompting best practices. + +## When to Use + +- After creating or modifying skills +- During periodic quality reviews +- When skills seem to underperform + +## When NOT to Use + +- No skills exist yet +- Just after a fresh skill creation (let it settle first) + +## Audit Dimensions + +### 1. Positive framing +Instructions should say what TO do, not just what NOT to do. + +### 2. Motivation over mandates +Explain WHY a rule exists, not just the rule. + +### 3. Structure +Uses clear sections: When to Use, When NOT to Use, Process, +Quality Checklist. + +### 4. Examples +Includes good and bad examples for clarity. + +### 5. Scope +Skill is focused on one task, not a catch-all. + +### 6. Description quality +Frontmatter description is clear and actionable. + +### 7. Overtriggering guard +"When NOT to Use" section prevents false activations. + +### 8. Phantom references +No references to tools, files, or commands that don't exist. + +### 9. Tool declarations +Tools listed in frontmatter match what the skill actually uses. + +## Process + +1. Glob all skill files: `internal/assets/**/skills/*/SKILL.md` +2. Read each skill +3. Score against the 9 dimensions (pass/fail/partial) +4. Report findings per skill with actionable fixes + +## Output Format + +``` +## Skill Audit Report + +| Skill | Score | Issues | +|-------|-------|--------| +| ctx-implement | 8/9 | Missing bad example | +| ctx-commit | 9/9 | Clean | +| ctx-reflect | 7/9 | Phantom ref to /ctx-update-docs | + +### Details +... +``` + +## Quality Checklist + +- [ ] All skill files scanned +- [ ] Each dimension checked per skill +- [ ] Actionable fixes provided for failures +- [ ] No false positives (verify references exist) diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-skill-creator/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-skill-creator/SKILL.md new file mode 100644 index 000000000..f8b05ac9a --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-skill-creator/SKILL.md @@ -0,0 +1,76 @@ +--- +name: ctx-skill-creator +description: "Create, improve, test, and deploy skills. Full skill lifecycle from intent to working skill file." +tools: [bash, read, write, edit, glob, grep] +--- + +Create new skills or improve existing ones through a structured +workflow. + +## When to Use + +- Creating a new skill from scratch +- Improving an underperforming skill +- Porting a skill from one integration to another + +## When NOT to Use + +- Quick one-off automations (just script it) +- When the need is too vague (brainstorm first) + +## Process + +### 1. Intent capture + +Gather: +- What should this skill do? +- When should it trigger? +- What tools does it need? +- What's the expected output? + +### 2. Draft the SKILL.md + +Use the standard structure: + +```yaml +--- +name: ctx-{name} +description: "..." +tools: [bash, read, write, ...] +--- +``` + +Sections: When to Use, When NOT to Use, Process, Quality Checklist. + +### 3. Validate + +Check against skill audit dimensions: +- Positive framing +- Clear scope +- Good examples +- No phantom references +- Overtriggering guard + +### 4. Test + +If possible, do a dry run of the skill's workflow to verify +it works end-to-end. + +### 5. Deploy + +Write the file to the appropriate skills directory: +- Claude: `internal/assets/claude/skills/{name}/SKILL.md` +- Copilot CLI: `internal/assets/integrations/copilot-cli/skills/{name}/SKILL.md` + +### 6. Build + +Run `go build ./cmd/ctx/...` to verify the embed compiles. + +## Quality Checklist + +- [ ] Frontmatter is complete (name, description, tools) +- [ ] When to Use / When NOT to Use sections exist +- [ ] Process has numbered, actionable steps +- [ ] Quality Checklist at the end +- [ ] No phantom references +- [ ] Build passes with new skill embedded diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-spec/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-spec/SKILL.md new file mode 100644 index 000000000..a8fc9445a --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-spec/SKILL.md @@ -0,0 +1,76 @@ +--- +name: ctx-spec +description: "Scaffold a feature spec from the project template. Use when planning a new feature or when a task references a missing spec." +tools: [bash, read, write] +--- + +Scaffold a new spec from `specs/tpl/spec-template.md` and walk +through each section with the user. + +## When to Use + +- Before implementing a non-trivial feature +- When a task says "Spec: `specs/X.md`" and the file doesn't exist +- When `ctx-brainstorm` produced a validated design that needs + a written artifact +- When the user says "let's spec this out" + +## When NOT to Use + +- Bug fixes or small changes +- When a spec already exists (read it instead) +- When the design is still vague (use `ctx-brainstorm` first) + +## Process + +### 1. Gather the Feature Name + +If not provided, ask. Derive filename: lowercase, hyphens. +Target: `specs/{feature-name}.md` + +### 2. Read the Template + +Read `specs/tpl/spec-template.md`. + +### 3. Walk Through Sections + +Work through each section **one at a time**: + +| Section | Prompt | +|----------------------|---------------------------------------------------------------| +| **Problem** | "What user-visible problem does this solve? Why now?" | +| **Approach** | "How does this work? Where does it fit?" | +| **Happy Path** | "Walk through what happens when everything goes right." | +| **Edge Cases** | "What could go wrong? (empty input, failures, duplicates)" | +| **Validation Rules** | "What input constraints are enforced?" | +| **Error Handling** | "For each error: user message and recovery?" | +| **Interface** | "CLI command? Skill? Both? Flags?" | +| **Implementation** | "Which files change? Key functions? Helpers to reuse?" | +| **Configuration** | "Any .ctxrc keys, env vars, or settings?" | +| **Testing** | "Unit, integration, edge case tests?" | +| **Non-Goals** | "What does this intentionally NOT do?" | + +**Spend extra time on Edge Cases and Error Handling.** + +### 4. Open Questions + +After all sections: +> "Anything unresolved? If not, I'll remove the Open Questions +> section." + +### 5. Write the Spec + +Write to `specs/{feature-name}.md`. + +### 6. Cross-Reference + +- If a Phase exists in TASKS.md, confirm the path matches +- If no tasks exist, offer to create them + +## Quality Checklist + +- [ ] Problem section explains *why*, not just *what* +- [ ] At least 3 edge cases with expected behavior +- [ ] Error handling has user messages and recovery +- [ ] Non-goals are explicit +- [ ] No placeholder text remains diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-status/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-status/SKILL.md index 345e97f6d..14eca349e 100644 --- a/internal/assets/integrations/copilot-cli/skills/ctx-status/SKILL.md +++ b/internal/assets/integrations/copilot-cli/skills/ctx-status/SKILL.md @@ -1,6 +1,7 @@ --- name: ctx-status description: "Show context summary. Use at session start or when unclear about current project state." +tools: [bash] --- Show the current context status: files, token budget, tasks, @@ -9,65 +10,21 @@ and recent activity. ## When to Use - At session start to orient before doing work -- When confused about what is being worked on or what context - exists +- When confused about what's being worked on - To check token usage and context health - When the user asks "what's the state of the project?" ## When NOT to Use -- When you already loaded context via `/ctx-agent` in this - session (status is a subset of what agent provides) -- Repeatedly within the same session without changes in between - -## Usage Examples - -```text -/ctx-status -/ctx-status --verbose -/ctx-status --json -``` +- When you already loaded context via `ctx-agent` in this session +- Repeatedly within the same session without changes ## Flags -| Flag | Short | Default | Purpose | -|-------------|-------|---------|----------------------------------| -| `--json` | | false | Output as JSON (for scripting) | -| `--verbose` | `-v` | false | Include file content previews | - -## What It Shows - -The output has three sections: - -### 1. Overview - -- Context directory path -- Total file count -- Token estimate (sum across all `.md` files in the context directory) - -### 2. Files - -Each `.md` file in the context directory with: - -| Indicator | Meaning | -|-----------|-----------------------------------------| -| check | File has content (loaded) | -| circle | File exists but is empty | - -File-specific summaries: -- `CONSTITUTION.md`: number of invariants -- `TASKS.md`: active and completed task counts -- `DECISIONS.md`: number of decisions -- `GLOSSARY.md`: number of terms -- Others: "loaded" or "empty" - -With `--verbose`: adds token count, byte size, and a 3-line -content preview per file. - -### 3. Recent Activity - -The 3 most recently modified files with relative timestamps -(e.g., "5 minutes ago", "2 hours ago"). +| Flag | Default | Purpose | +|-------------|---------|--------------------------------| +| `--json` | false | Output as JSON (for scripting) | +| `--verbose` | false | Include file content previews | ## Execution @@ -75,25 +32,23 @@ The 3 most recently modified files with relative timestamps ctx status ``` -After running, summarize the key points for the user: +After running, summarize the key points: - How many active tasks remain -- Whether any context files are empty (might need populating) -- Token budget usage (is context lean or bloated?) -- What was recently modified (gives a sense of momentum) +- Whether any context files are empty +- Token budget usage +- What was recently modified ## Interpreting Results -| Observation | Suggestion | -|-------------------------|-------------------------------------------------------------| -| Many empty files | Context is sparse; populate core files (TASKS, CONVENTIONS) | -| High token count (>30k) | Consider `ctx compact` or archiving completed tasks | -| No recent activity | Context may be stale; check if files need updating | -| TASKS.md has 0 active | All work done, or tasks need to be added | +| Observation | Suggestion | +|-------------------------|-------------------------------------------------| +| Many empty files | Populate core files (TASKS, CONVENTIONS) | +| High token count (>30k) | Consider `ctx compact` or archiving tasks | +| No recent activity | Context may be stale; check if files need update | +| TASKS.md has 0 active | All work done, or tasks need to be added | ## Quality Checklist -After running status, verify: -- [ ] Summarized the output for the user (do not just dump - raw output without commentary) -- [ ] Flagged any empty core files that should be populated -- [ ] Noted token budget if it seems high or low +- [ ] Summarized the output (do not just dump raw output) +- [ ] Flagged empty core files +- [ ] Noted token budget if high or low diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-verify/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-verify/SKILL.md new file mode 100644 index 000000000..c0101db64 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-verify/SKILL.md @@ -0,0 +1,52 @@ +--- +name: ctx-verify +description: "Verify before claiming completion. Use before saying work is done, tests pass, or builds succeed." +tools: [bash, read, glob, grep] +--- + +Run the relevant verification command before claiming a result. + +## When to Use + +- Before saying "tests pass", "build succeeds", or "bug fixed" +- Before reporting completion of any task with a testable outcome +- When the user asks "does it work?" or "is it done?" + +## When NOT to Use + +- For documentation-only changes with no testable outcome +- When the user explicitly says "skip verification" +- For exploratory work with no pass/fail criterion + +## Workflow + +1. **Identify** what command proves the claim +2. **Think through** what passing looks like (and false positives) +3. **Run** the command (fresh, not a previous run) +4. **Read** full output; check exit code, count failures +5. **Report** actual results with evidence + +## Claim-to-Evidence Map + +| Claim | Required Evidence | +|-------------------|--------------------------------------------| +| Tests pass | Test command output showing 0 failures | +| Linter clean | `golangci-lint run` showing 0 errors | +| Build succeeds | `go build` exit 0 | +| Bug fixed | Original symptom no longer reproduces | +| All checks pass | `make audit` showing all steps pass | + +## Self-Audit Questions + +Before presenting any artifact as complete: +- What assumptions did I make? +- What did I NOT check? +- Where am I least confident? +- What would a reviewer question first? + +## Quality Checklist + +- [ ] Verification command was run fresh (not reused) +- [ ] Exit code was checked +- [ ] Claim matches evidence (build ≠ tests) +- [ ] If multiple claims, each has its own evidence diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-worktree/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-worktree/SKILL.md new file mode 100644 index 000000000..5686becd4 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-worktree/SKILL.md @@ -0,0 +1,170 @@ +--- +name: ctx-worktree +description: "Manage git worktrees for parallel agent development. Use when splitting work across independent task tracks." +tools: [bash, read, glob] +--- + +Manage git worktrees to parallelize agent work across independent +task tracks. Supports creating, listing, and tearing down worktrees +with ctx-aware guardrails. + +## When to Use + +- User wants to parallelize a backlog across multiple agents +- Multiple independent task tracks with non-overlapping files +- User says "create worktree", "let's parallelize", "split the work" +- 3+ independent tasks that can be worked concurrently + +## When NOT to Use + +- Single task or tightly coupled tasks +- Tasks that touch overlapping files (high merge conflict risk) +- Fewer than 3 independent tasks (overhead exceeds benefit) +- Already inside a worktree (manage from the main checkout only) +- User just wants concurrent sessions in the same tree + +## Operations + +### `create ` + +Create a new worktree as a sibling directory with a `work/` branch. + +**Process:** + +1. **Check count**: refuse if 4 worktrees already exist: + ```bash + git worktree list + ``` + Count lines. If >= 5 (1 main + 4 worktrees), stop and explain + the limit. + +2. **Determine project name** from the current directory basename: + ```bash + basename "$(git rev-parse --show-toplevel)" + ``` + +3. **Create the worktree** as a sibling directory: + ```bash + git worktree add "../-" -b "work/" + ``` + +4. **Verify** the worktree was created: + ```bash + ls "../-" + ``` + +5. **Remind the user**: + > Do NOT run `ctx init` in the worktree. The context + > directory is already tracked in git and will be present. + > Launch a separate session there and work normally. + +### `list` + +Show all active worktrees: + +```bash +git worktree list +``` + +### `teardown ` + +Merge a completed worktree back and clean up. + +**Process:** + +1. **Check for uncommitted changes** in the worktree: + ```bash + git -C "../-" status --porcelain + ``` + If output is non-empty, warn and stop. The user must commit or + discard changes first. + +2. **Merge the work branch** into the current branch: + ```bash + git merge "work/" + ``` + If there are conflicts, stop and help the user resolve them. + TASKS.md conflicts are common: see guidance below. + +3. **Remove the worktree**: + ```bash + git worktree remove "../-" + ``` + +4. **Delete the branch**: + ```bash + git branch -d "work/" + ``` + +5. **Verify** cleanup: + ```bash + git worktree list + git branch | grep "work/" + ``` + +## Guardrails + +- **Max 4 worktrees**: more than 4 parallel tracks makes merge + complexity outweigh productivity gains +- **Sibling directories only**: worktrees go in `../-`, + never inside the project tree +- **`work/` branch prefix**: all worktree branches use `work/` + for easy identification and cleanup +- **No `ctx init` in worktrees**: the context directory is tracked + in git; running init would overwrite shared context files +- **Manage from main checkout only**: create and teardown worktrees + from the main working tree, not from inside a worktree +- **TASKS.md conflict resolution**: when merging, TASKS.md will + often conflict because multiple agents marked different tasks as + complete. Resolution: accept all `[x]` completions from both sides. + No task should go from `[x]` back to `[ ]`. + +## What Works Differently in Worktrees + +The encryption key lives at `~/.ctx/.ctx.key` (user-level, outside +the project). All worktrees on the same machine share this path, so +**`ctx pad` and `ctx notify` work in worktrees automatically**. + +One thing to watch: + +- **Journal enrichment**: `ctx recall export` and `ctx journal enrich` + resolve paths relative to the current working directory. Files + created in a worktree stay in that worktree and are discarded on + teardown. Enrich journals on the main branch after merging: the + JSONL session logs are intact regardless. + +## Task Grouping Guidance + +Before creating worktrees, analyze the backlog to group tasks into +non-overlapping tracks: + +1. **Read TASKS.md** and identify all pending tasks +2. **Estimate blast radius**: which files/directories does each + task touch? +3. **Group by non-overlapping directories**: tasks that touch the + same package or file must go in the same track +4. **Present the grouping** to the user before creating worktrees: + +```text +Proposed worktree groups: + + work/docs : recipe updates, blog post, getting started guide + (touches: docs/) + work/crypto : P3.1-P3.3 encrypted scratchpad infra + (touches: internal/crypto/, internal/config/) + work/pad-cli : P3.4-P3.9 pad CLI commands + (touches: internal/cli/pad/) +``` + +Let the user approve or adjust before proceeding. + +## Quality Checklist + +Before any operation, verify: +- [ ] Worktree count checked (max 4) +- [ ] Branch uses `work/` prefix +- [ ] Worktree is a sibling directory (`../`) +- [ ] User reminded not to run `ctx init` in worktree +- [ ] Uncommitted changes checked before teardown +- [ ] Merge completed before worktree removal +- [ ] Branch deleted after worktree removal diff --git a/internal/assets/integrations/copilot-cli/skills/ctx-wrap-up/SKILL.md b/internal/assets/integrations/copilot-cli/skills/ctx-wrap-up/SKILL.md new file mode 100644 index 000000000..ba764c867 --- /dev/null +++ b/internal/assets/integrations/copilot-cli/skills/ctx-wrap-up/SKILL.md @@ -0,0 +1,121 @@ +--- +name: ctx-wrap-up +description: "End-of-session context persistence ceremony. Use when wrapping up a session to capture learnings, decisions, conventions, and tasks." +tools: [bash, read, write, edit] +--- + +Guide end-of-session context persistence. Gather signal from the +session, propose candidates worth persisting, and persist approved +items via `ctx add`. + +## When to Use + +- At the end of a session, before the user quits +- When the user says "let's wrap up", "save context", "end of + session" + +## When NOT to Use + +- Nothing meaningful happened (only read files, quick lookup) +- The user already persisted everything manually +- Mid-session: use `ctx-reflect` instead + +## Process + +### Phase 1: Gather signal + +Do this **silently**: + +1. Check what changed: + ```bash + git diff --stat + ``` +2. Check commits made this session: + ```bash + git log --oneline -5 + ``` +3. Scan the conversation for: + - Architectural choices or trade-offs + - Gotchas or unexpected behavior + - Patterns established or conventions agreed + - Follow-up work identified + - Tasks completed or progressed + +### Phase 2: Propose candidates + +Think step-by-step about what is worth persisting. For each +candidate ask: +- Is this project-specific or general knowledge? +- Would a future session benefit from knowing this? +- Is this already captured in context files? + +Present candidates grouped by type. Skip empty categories. + +``` +## Session Wrap-Up + +### Learnings (N candidates) +1. **Title** — Context, Lesson, Application + +### Decisions (N candidates) +1. **Title** — Context, Rationale, Consequence + +### Conventions (N candidates) +1. **Convention description** + +### Tasks (N candidates) +1. **Task description** (new | completed | updated) + +Persist all? Or select which to keep? +``` + +### Phase 3: Persist approved candidates + +Wait for user approval. For each approved item: + +| Type | Command | +|-------------|----------------------------------------------------------------------| +| Learning | `ctx add learning "Title" --context "..." --lesson "..." --application "..."` | +| Decision | `ctx add decision "Title" --context "..." --rationale "..." --consequence "..."` | +| Convention | `ctx add convention "Description"` | +| Task (new) | `ctx add task "Description"` | +| Task (done) | Edit TASKS.md to mark complete | + +### Phase 4: Commit (optional) + +After persisting, check for uncommitted changes: + +```bash +git status --short +``` + +If there are uncommitted changes, offer to commit with +`ctx-commit`. + +## Candidate Quality Guide + +### Good candidates + +- Specific gotchas with actionable lessons +- Real trade-offs with rationale +- Patterns codified for consistency + +### Weak candidates (do not propose) + +- General programming knowledge +- Obvious facts from the diff +- Things already in context files + +## Quality Checklist + +Before presenting: +- [ ] Signal was gathered (git diff, git log, conversation scan) +- [ ] Every candidate has complete fields +- [ ] Candidates are project-specific +- [ ] No duplicates with existing context +- [ ] Empty categories are omitted +- [ ] User is asked before persisting + +After persisting: +- [ ] Each `ctx add` command succeeded +- [ ] Uncommitted changes were surfaced diff --git a/specs/copilot-feature-parity-kit.md b/specs/copilot-feature-parity-kit.md new file mode 100644 index 000000000..fa07d7217 --- /dev/null +++ b/specs/copilot-feature-parity-kit.md @@ -0,0 +1,373 @@ +# Copilot Feature Parity Kit + +## Problem + +Claude Code integration has 41 skills, 20+ hooks, a governance/ceremony +system, and deep code intelligence (GitNexus). Copilot CLI has 5 skills +and 4 lifecycle hooks. Copilot VS Code has 45+ slash commands but most +delegate to CLI without agent-level intelligence (workflow orchestration, +proactive nudges, code-aware operations). + +This creates a two-tier experience: Claude users get a full context-aware +AI partner; Copilot users get a context reader. The gap is not in data +access (MCP tools are shared) but in **agent behavior** — the skills, +hooks, and governance that turn raw context into workflow. + +## Approach + +A phased spec kit that brings Copilot CLI and VS Code to parity with +Claude Code. Each phase is independently shippable. Work is organized +into three layers: + +1. **Skills** — Copilot CLI `.github/skills/` and VS Code slash commands +2. **Hooks** — Copilot CLI hook scripts and VS Code event handlers +3. **Governance** — Proactive nudges, ceremony checks, session health + +Architecture principle: **single source of truth**. Skills are authored +as markdown SKILL.md files in `internal/assets/integrations/copilot-cli/skills/` +and deployed by `ctx setup copilot-cli --write`. VS Code commands call +`ctx` CLI or MCP tools — the extension does not duplicate skill logic. + +### Cross-references + +- `specs/copilot-cli-integration.md` — existing feature matrix (context injection, hooks, MCP, recall) +- `specs/vscode-feature-parity.md` — existing layer-by-layer VS Code mapping +- This spec supersedes neither; it fills the **skill + governance gap** they identify. + +--- + +## Phase 1 — Core Workflow Skills (Copilot CLI + VS Code) + +Port the skills that encode the work cycle: pick → implement → commit → reflect. + +### 1.1 Skills to Port + +| # | Claude Skill | Copilot CLI Skill | VS Code Command | Priority | +|---|-------------|-------------------|-----------------|----------| +| 1 | `ctx-next` | `ctx-next/SKILL.md` ✅ exists | `/next` | P0 — already done | +| 2 | `ctx-implement` | `ctx-implement/SKILL.md` | `/implement` | P0 | +| 3 | `ctx-commit` | `ctx-commit/SKILL.md` | `/commit` | P0 | +| 4 | `ctx-reflect` | `ctx-reflect/SKILL.md` | `/reflect` | P0 | +| 5 | `ctx-remember` | `ctx-remember/SKILL.md` | `/remember` | P0 | +| 6 | `ctx-wrap-up` | `ctx-wrap-up/SKILL.md` | `/wrapup` | P0 | +| 7 | `ctx-code-review` | `ctx-code-review/SKILL.md` | `/review` | P1 | +| 8 | `ctx-refactor` | `ctx-refactor/SKILL.md` | `/refactor` | P1 | +| 9 | `ctx-explain` | `ctx-explain/SKILL.md` | `/explain` | P1 | +| 10 | `ctx-brainstorm` | `ctx-brainstorm/SKILL.md` | `/brainstorm` | P1 | +| 11 | `ctx-spec` | `ctx-spec/SKILL.md` | `/spec` | P1 | + +### 1.2 Skill File Format (Copilot CLI) + +Copilot CLI skills live in `.github/skills//SKILL.md`. Format: + +```markdown +--- +name: ctx-implement +description: Execute implementation plan step-by-step with verification +tools: [bash, read, write, edit, glob, grep] +--- + +# ctx-implement + +## When to Use +- User says "implement this", "build it", "start coding" +- A task from TASKS.md is selected for implementation + +## When NOT to Use +- No spec or plan exists (use ctx-spec first) +- Task is ambiguous (use ctx-brainstorm first) + +## Workflow +1. Read the referenced spec from `specs/` +2. Read CONVENTIONS.md for code patterns +3. Break work into chunks, commit after each +4. Run `make lint && make test` after each chunk +5. Mark task done in TASKS.md when complete +6. Offer to record learnings/decisions discovered + +## Quality Gates +- [ ] Spec exists and was read +- [ ] Tests pass after each chunk +- [ ] Lint passes +- [ ] TASKS.md updated +``` + +### 1.3 VS Code Slash Command Wiring + +For each new skill, add to `editors/vscode/package.json` contributes +and handle in `extension.ts`: + +```typescript +case '/implement': + return runCtxCommand(stream, 'implement', request.prompt); +``` + +VS Code commands delegate to `ctx` CLI. The extension provides UI +(progress, follow-ups, markdown rendering) but not logic. + +### 1.4 Files to Create/Modify + +| File | Change | +|------|--------| +| `internal/assets/integrations/copilot-cli/skills/ctx-implement/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-commit/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-reflect/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-remember/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-wrap-up/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-code-review/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-refactor/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-explain/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-brainstorm/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-spec/SKILL.md` | New skill | +| `internal/cli/setup/core/copilot_cli/copilot_cli.go` | Deploy new skills | +| `editors/vscode/package.json` | Add slash commands | +| `editors/vscode/src/extension.ts` | Handle new commands | + +--- + +## Phase 2 — Architecture & Design Skills + +### 2.1 Skills to Port + +| # | Claude Skill | Copilot CLI Skill | VS Code Command | Priority | +|---|-------------|-------------------|-----------------|----------| +| 1 | `ctx-architecture` | `ctx-architecture/SKILL.md` | `/architecture` | P1 | +| 2 | `ctx-architecture-enrich` | `ctx-architecture-enrich/SKILL.md` | — (CLI only) | P2 | +| 3 | `ctx-architecture-failure-analysis` | `ctx-architecture-failure-analysis/SKILL.md` | — (CLI only) | P2 | +| 4 | `ctx-doctor` | `ctx-doctor/SKILL.md` | `/system doctor` ✅ | P1 | + +### 2.2 GitNexus Dependency + +`ctx-architecture-enrich` and `ctx-architecture-failure-analysis` use +GitNexus MCP tools (`mcp__gitnexus__*`). For Copilot CLI: + +- GitNexus MCP server must be registered in `~/.copilot/mcp-config.json` +- Skills should gracefully degrade if GitNexus is unavailable +- Fallback: use `grep`/`go doc` for basic code intelligence + +### 2.3 Files to Create/Modify + +| File | Change | +|------|--------| +| `internal/assets/integrations/copilot-cli/skills/ctx-architecture/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-architecture-enrich/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-architecture-failure-analysis/SKILL.md` | New skill | + +--- + +## Phase 3 — Governance & Proactive Hooks + +The biggest behavioral gap. Claude's hook system fires on every tool +use and user prompt, surfacing nudges for persistence, ceremonies, +and health. Copilot has no equivalent. + +### 3.1 Copilot CLI Hooks to Add + +Extend `.github/hooks/ctx-hooks.json` with richer behavior in existing +hook scripts: + +| Hook | Trigger | Behavior | Claude Equivalent | +|------|---------|----------|-------------------| +| `preToolUse` (enhanced) | Every tool call | Dangerous cmd block + context load gate | `block-non-path-ctx` + `context-load-gate` | +| `postToolUse` (enhanced) | After edit/write | Task completion check + learning nudge | `check-task-completion` + `post-commit` | +| `sessionStart` (enhanced) | Session begin | Load context + version check + reminder relay | `budget-agent` + `check-version` + `check-reminders` | +| `sessionEnd` (enhanced) | Session close | Persistence ceremony + journal capture | `check-ceremonies` + `check-persistence` | + +### 3.2 New Hook Scripts + +``` +.github/hooks/scripts/ +├── ctx-preToolUse.sh # Enhanced: dangerous cmd + context gate +├── ctx-preToolUse.ps1 # PowerShell mirror +├── ctx-postToolUse.sh # Enhanced: task check + learning nudge +├── ctx-postToolUse.ps1 # PowerShell mirror +├── ctx-sessionStart.sh # Enhanced: bootstrap + reminders +├── ctx-sessionStart.ps1 # PowerShell mirror +├── ctx-sessionEnd.sh # Enhanced: ceremony + journal +└── ctx-sessionEnd.ps1 # PowerShell mirror +``` + +### 3.3 Governance Messages + +Port the hook message registry. Each message has: +- **Condition**: when to fire (e.g., "uncompleted tasks > 5") +- **Message**: what to show (e.g., "⚠ 5 tasks pending — run `/next`") +- **Cooldown**: don't repeat within N minutes + +| Message ID | Condition | Copilot Surface | +|------------|-----------|-----------------| +| `ceremony-remember` | Session > 30 min, no recall done | `sessionStart` script output | +| `ceremony-wrapup` | Session > 2 hours, no persist | `sessionEnd` script output | +| `persistence-nudge` | Decision made but not recorded | `postToolUse` script output | +| `task-completion` | File edited matching task description | `postToolUse` script output | +| `version-drift` | `ctx --version` != expected | `sessionStart` script output | +| `reminder-relay` | Pending reminders exist | `sessionStart` script output | + +### 3.4 VS Code Governance + +Map governance to VS Code extension events: + +| Governance | VS Code Mechanism | +|------------|-------------------| +| Ceremony check | `vscode.window.onDidChangeWindowState` (focus loss → prompt) | +| Persistence nudge | `vscode.workspace.onDidSaveTextDocument` (`.context/` watch) | +| Task completion | `onDidSaveTextDocument` → `ctx system check-task-completion` | +| Reminder relay | Status bar item + 5-min timer (already partial) | +| Version check | `ensureCtxAvailable()` version comparison | +| Session ceremony | Extension `deactivate()` → wrap-up prompt | + +### 3.5 Files to Create/Modify + +| File | Change | +|------|--------| +| `internal/assets/integrations/copilot-cli/scripts/ctx-preToolUse.sh` | Enhance with context gate | +| `internal/assets/integrations/copilot-cli/scripts/ctx-preToolUse.ps1` | PowerShell mirror | +| `internal/assets/integrations/copilot-cli/scripts/ctx-postToolUse.sh` | Enhance with task check + nudge | +| `internal/assets/integrations/copilot-cli/scripts/ctx-postToolUse.ps1` | PowerShell mirror | +| `internal/assets/integrations/copilot-cli/scripts/ctx-sessionStart.sh` | Enhance with bootstrap | +| `internal/assets/integrations/copilot-cli/scripts/ctx-sessionStart.ps1` | PowerShell mirror | +| `internal/assets/integrations/copilot-cli/scripts/ctx-sessionEnd.sh` | Enhance with ceremony | +| `internal/assets/integrations/copilot-cli/scripts/ctx-sessionEnd.ps1` | PowerShell mirror | +| `internal/assets/integrations/copilot-cli/ctx-hooks.json` | Updated hook config | +| `editors/vscode/src/extension.ts` | Add governance event handlers | + +--- + +## Phase 4 — Context Health & Maintenance Skills + +### 4.1 Skills to Port + +| # | Claude Skill | Copilot CLI Skill | VS Code Command | Priority | +|---|-------------|-------------------|-----------------|----------| +| 1 | `ctx-consolidate` | `ctx-consolidate/SKILL.md` | `/consolidate` | P2 | +| 2 | `ctx-permission-sanitize` | `ctx-permission-sanitize/SKILL.md` | — | P2 | +| 3 | `ctx-prompt-audit` | `ctx-prompt-audit/SKILL.md` | — | P3 | +| 4 | `ctx-skill-audit` | `ctx-skill-audit/SKILL.md` | — | P3 | +| 5 | `ctx-skill-create` | `ctx-skill-create/SKILL.md` | — | P3 | +| 6 | `ctx-link-check` | `ctx-link-check/SKILL.md` | `/check-links` ✅ | Done | +| 7 | `ctx-pad` | `ctx-pad/SKILL.md` | `/pad` ✅ | Done | + +### 4.2 Files to Create/Modify + +| File | Change | +|------|--------| +| `internal/assets/integrations/copilot-cli/skills/ctx-consolidate/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-permission-sanitize/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-prompt-audit/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-skill-audit/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-skill-create/SKILL.md` | New skill | + +--- + +## Phase 5 — Journal & Documentation Skills + +### 5.1 Skills to Port + +| # | Claude Skill | Copilot CLI Skill | VS Code Command | Priority | +|---|-------------|-------------------|-----------------|----------| +| 1 | `ctx-journal-enrich` | `ctx-journal-enrich/SKILL.md` | `/journal enrich` | P2 | +| 2 | `ctx-journal-enrich-all` | `ctx-journal-enrich-all/SKILL.md` | — | P3 | +| 3 | `ctx-blog` | `ctx-blog/SKILL.md` | `/blog` | P3 | +| 4 | `ctx-blog-changelog` | `ctx-blog-changelog/SKILL.md` | `/changelog` ✅ | Done | +| 5 | `ctx-plan-import` | `ctx-plan-import/SKILL.md` | — | P3 | + +### 5.2 Files to Create/Modify + +| File | Change | +|------|--------| +| `internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-journal-enrich-all/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-blog/SKILL.md` | New skill | +| `internal/assets/integrations/copilot-cli/skills/ctx-plan-import/SKILL.md` | New skill | + +--- + +## Phase 6 — Advanced / Infrastructure Skills + +### 6.1 Skills to Port + +| # | Claude Skill | Copilot CLI Skill | VS Code Command | Priority | +|---|-------------|-------------------|-----------------|----------| +| 1 | `ctx-loop` | `ctx-loop/SKILL.md` | — (N/A for chat UI) | P3 | +| 2 | `ctx-worktree` | `ctx-worktree/SKILL.md` | `/worktree` ✅ | Done | +| 3 | `ctx-pause` / `ctx-resume` | `ctx-pause/SKILL.md` | `/pause` | P3 | + +--- + +## Summary: Parity Scorecard + +### Current State + +| Surface | Skills | Hooks | Governance | Total Score | +|---------|--------|-------|------------|-------------| +| Claude Code | 41 | 20+ | Full | 100% | +| Copilot CLI | 5 | 4 | None | ~15% | +| Copilot VS Code | 45 cmds (CLI delegate) | 6 watchers | Partial | ~40% | + +### After This Spec Kit + +| Surface | Skills | Hooks | Governance | Total Score | +|---------|--------|-------|------------|-------------| +| Claude Code | 41 | 20+ | Full | 100% | +| Copilot CLI | 36 | 4 (enhanced) | Hook-based | ~85% | +| Copilot VS Code | 50+ cmds | 10+ handlers | Event-based | ~90% | + +### Remaining Gap (Intentional) + +These features are Claude Code specific and **not ported**: + +| Feature | Reason | +|---------|--------| +| `UserPromptSubmit` hooks (12 types) | Copilot CLI has no equivalent trigger point | +| `check-context-size` (token budget) | Copilot does not expose token counts | +| `check-knowledge` | Claude Code knowledge graph specific | +| `heartbeat` telemetry | Different telemetry model | +| Plugin system (`.claude-plugin/`) | Claude Code specific packaging | + +--- + +## Edge Cases + +| Case | Expected Behavior | +|------|-------------------| +| Skill references MCP tool not available | Graceful degradation: use CLI fallback | +| GitNexus not registered | Architecture-enrich falls back to grep/ast | +| Hook script timeout (>5s) | Script returns empty, no block | +| Concurrent skill invocation | Each invocation is independent | +| `ctx` binary not on PATH | `sessionStart` hook warns; VS Code auto-downloads | +| `.context/` doesn't exist | Skills prompt `ctx init` | +| Windows vs Unix line endings | Scripts use native endings per platform | + +## Validation Rules + +- Every skill SKILL.md must have: name, description, tools, workflow, quality gates +- Every hook script must have: bash + PowerShell variants +- Every VS Code command must: delegate to CLI, show progress, offer follow-ups +- Skill names must match between Claude and Copilot (e.g., `ctx-implement` in both) + +## Testing + +- **Unit**: Each skill SKILL.md passes `ctx skill audit` (format, completeness) +- **Integration**: `ctx setup copilot-cli --write` deploys all skills + hooks +- **E2E**: Run Copilot CLI session with skills, verify workflow cycle +- **VS Code**: Extension test suite covers new slash commands +- **Cross-platform**: Hook scripts tested on bash (Linux/macOS) and PowerShell (Windows) + +## Non-Goals + +- Replacing Copilot's built-in features (code completion, inline suggestions) +- Porting Claude Code's plugin packaging system +- Real-time token budget monitoring (Copilot doesn't expose this) +- Bidirectional memory sync (separate spec: Copilot memory bridge) +- ACP server mode (separate spec: `specs/copilot-cli-integration.md` Phase 4) + +## Open Questions + +1. **Copilot CLI skill discovery**: Does Copilot CLI auto-discover `.github/skills/` + or do skills need explicit registration? Need to verify with latest CLI docs. +2. **Hook script output rendering**: How does Copilot CLI render hook script + stdout? Markdown? Plain text? This affects governance message formatting. +3. **VS Code command registration limit**: Is there a practical limit on slash + commands in a chat participant? Current 45 → 55+ after this spec. +4. **Skill frontmatter schema**: Does Copilot CLI enforce a specific YAML + frontmatter schema for SKILL.md, or is it freeform markdown?