Skip to content

feat: Copilot governance engine, VS Code extension, and recall parser #45

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
bilersan wants to merge 6 commits into
base: main
Choose a base branch
from
Open

feat: Copilot governance engine, VS Code extension, and recall parser #45

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
a42f698
fix: Windows cross-platform compatibility
bilersan Mar 17, 2026
8cd24be
feat: add Copilot Chat session parser for recall
bilersan Mar 17, 2026
5fd63c5
feat: VS Code extension with MCP integration and detection ring
bilersan Mar 17, 2026
0e17a20
feat: MCP governance engine with detection ring integration
bilersan Mar 17, 2026
eb95695
fix(vscode): resolve Insiders dual extension host hang
bilersan Mar 17, 2026
ce018c9
fix: CI failures and marketplace readiness
bilersan Mar 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
171 changes: 96 additions & 75 deletions .context/AGENT_PLAYBOOK.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@ never come cleanly.
## Invoking ctx

Always use `ctx` from PATH:
```bash
ctx status # ✓ correct
ctx agent # ✓ correct
```
ctx status # ✔ correct
ctx agent # ✔ correct
./dist/ctx # ✗ avoid hardcoded paths
go run ./cmd/ctx # ✗ avoid unless developing ctx itself
```

Check with `which ctx` if unsure whether it's installed.
If unsure whether it's installed, run `ctx --version` in a terminal.

## Context Readback

Expand All @@ -40,21 +40,6 @@ This applies to debugging too — reason through the cause before reaching
for a fix. Rushing to code before reasoning is the most common source of
wasted work.

### Chunk and Checkpoint Large Tasks

For work spanning many files or steps, break it into independently
verifiable chunks. After each chunk:

1. **Commit** — save progress to git so nothing is lost
2. **Persist** — record learnings or decisions discovered during the chunk
3. **Verify** — run tests or `make lint` before moving on

Track progress via TASKS.md checkboxes. If context runs low mid-task,
persist a progress note (what's done, what's next, what assumptions
remain) before continuing in a new window. The `check-context-size`
hook warns at 80% usage — treat that as a signal to checkpoint, not
to rush.

## Session Lifecycle

A session follows this arc:
Expand All @@ -64,15 +49,14 @@ A session follows this arc:
Not every session uses every step — a quick bugfix skips reflection, a
research session skips committing — but the full flow is:

<!-- drift-check: ls internal/assets/claude/skills/ctx-remember internal/assets/claude/skills/ctx-status internal/assets/claude/skills/ctx-next internal/assets/claude/skills/ctx-implement internal/assets/claude/skills/ctx-commit internal/assets/claude/skills/ctx-reflect 2>&1 | grep -c skills/ -->
| Step | What Happens | Skill / Command |
|-------------|----------------------------------------------------|------------------|
| **Load** | Recall context, present structured readback | `/ctx-remember` |
| **Orient** | Check context health, surface issues | `/ctx-status` |
| **Pick** | Choose what to work on | `/ctx-next` |
| **Work** | Write code, fix bugs, research | `/ctx-implement` |
| **Commit** | Commit with context capture | `/ctx-commit` |
| **Reflect** | Surface persist-worthy items from this session | `/ctx-reflect` |
| Step | What Happens | Command |
|-------------|----------------------------------------------------|----------------------|
| **Load** | Recall context, present structured readback | `ctx recall list` |
| **Orient** | Check context health, surface issues | `ctx status` |
| **Pick** | Choose what to work on | Read TASKS.md |
| **Work** | Write code, fix bugs, research | — |
| **Commit** | Commit with context capture | `git commit` |
| **Reflect** | Surface persist-worthy items from this session | Update context files |

### Context Health at Session Start

Expand All @@ -88,57 +72,38 @@ Surface problems worth mentioning:

One sentence is enough — don't turn startup into a maintenance session.

### Context Window Limits

The `check-context-size` hook (`ctx system check-context-size`) monitors
context window usage and warns when it exceeds 80%. When you see this
warning or sense context is running long:

- **Persist progress**: write what's done and what's left to TASKS.md
or a progress note
- **Checkpoint state**: commit work-in-progress so a fresh session can
pick up cleanly
- **Summarize**: leave a breadcrumb for the next window — the current
task, open questions, and next step

Context compaction happens automatically, but the next window loses
nuance. Explicit persistence is cheaper than re-discovery.

### Conversational Triggers

Users rarely invoke skills explicitly. Recognize natural language:

<!-- drift-check: ls internal/assets/claude/skills/ctx-remember internal/assets/claude/skills/ctx-status internal/assets/claude/skills/ctx-next internal/assets/claude/skills/ctx-commit internal/assets/claude/skills/ctx-reflect internal/assets/claude/skills/ctx-add-decision internal/assets/claude/skills/ctx-add-learning internal/assets/claude/skills/ctx-add-convention internal/assets/claude/skills/ctx-add-task 2>&1 | grep -c skills/ -->
| User Says | Action |
|-------------------------------------------------|--------------------------------------------------------|
| "Do you remember?" / "What were we working on?" | `/ctx-remember` |
| "How's our context looking?" | `/ctx-status` |
| "What should we work on?" | `/ctx-next` |
| "Commit this" / "Ship it" | `/ctx-commit` |
| "The rate limiter is done" / "We finished that" | `ctx tasks complete` (match to TASKS.md) |
| "What did we learn?" | `/ctx-reflect` |
| "Save that as a decision" | `/ctx-add-decision` |
| "That's worth remembering" / "Any gotchas?" | `/ctx-add-learning` |
| "Record that convention" | `/ctx-add-convention` |
| "Add a task for that" | `/ctx-add-task` |
| "Sync memory" / "What's in auto memory?" | `ctx memory sync` / `ctx memory status` |
| "Import from memory" | `ctx memory import --dry-run` then `ctx memory import` |
| "Let's wrap up" | Reflect → persist outstanding items → present together |
| User Says | Action |
|-----------|--------|
| "Do you remember?" / "What were we working on?" | Read TASKS.md, DECISIONS.md, LEARNINGS.md; run `ctx recall list` |
| "How's our context looking?" | Run `ctx status` |
| "What should we work on?" | Read TASKS.md, pick highest priority |
| "Commit this" / "Ship it" | `git commit`, update TASKS.md |
| "The rate limiter is done" / "We finished that" | Mark done in TASKS.md |
| "What did we learn?" | Review session work, offer to update LEARNINGS.md |
| "Save that as a decision" | Add entry to DECISIONS.md |
| "That's worth remembering" / "Any gotchas?" | Add entry to LEARNINGS.md |
| "Record that convention" | Add entry to CONVENTIONS.md |
| "Add a task for that" | Add entry to TASKS.md |
| "Let's wrap up" | Reflect → persist outstanding items → present together |

## Proactive Persistence

**Don't wait to be asked.** Identify persist-worthy moments in real time:

| Event | Action |
|--------------------------------------------|-------------------------------------------------------------------|
| Completed a task | Mark done in TASKS.md, offer to add learnings |
| Chose between design alternatives | Offer: *"Worth recording as a decision?"* |
| Hit a subtle bug or gotcha | Offer: *"Want me to add this as a learning?"* |
| Finished a feature or fix | Identify follow-up work, offer to add as tasks |
| Resolved a tricky debugging session | Capture root cause before moving on |
| Multi-step task or feature complete | Suggest reflection: *"Want me to capture what we learned?"* |
| Session winding down | Offer: *"Want me to capture outstanding learnings or decisions?"* |
| Shipped a feature or closed batch of tasks | Offer blog post or journal site rebuild |
| Event | Action |
|-------|--------|
| Completed a task | Mark done in TASKS.md, offer to add learnings |
| Chose between design alternatives | Offer: *"Worth recording as a decision?"* |
| Hit a subtle bug or gotcha | Offer: *"Want me to add this as a learning?"* |
| Finished a feature or fix | Identify follow-up work, offer to add as tasks |
| Resolved a tricky debugging session | Capture root cause before moving on |
| Multi-step task or feature complete | Suggest reflection: *"Want me to capture what we learned?"* |
| Session winding down | Offer: *"Want me to capture outstanding learnings or decisions?"* |
| Shipped a feature or closed batch of tasks | Offer blog post or journal site rebuild |

**Self-check**: periodically ask yourself — *"If this session ended
right now, would the next session know what happened?"* If no, persist
Expand Down Expand Up @@ -171,11 +136,9 @@ user. These apply unless the user overrides them for the session

- **At design decisions**: always present 2+ approaches with
trade-offs before committing — don't silently pick one
- **At completion claims**: run `/ctx-verify` — it maps claims to
evidence (e.g., "tests pass" requires 0-failure output, "build
succeeds" requires exit 0). At minimum, answer the self-audit
questions: What did I assume? What didn't I check? Where am I
least confident? What would a reviewer question?
- **At completion claims**: run self-audit questions (What did I
assume? What didn't I check? Where am I least confident? What
would a reviewer question?) before reporting done
- **At ambiguous moments**: ask the user rather than inferring
intent — a quick question is cheaper than rework
- **When producing artifacts**: flag assumptions and uncertainty
Expand Down Expand Up @@ -245,3 +208,61 @@ Before writing or modifying CLI code (`internal/cli/**/*.go`):
3. **Use cmd methods for output** — `cmd.Printf`, `cmd.Println`,
not `fmt.Printf`, `fmt.Println`
4. **Follow docstring format** — see CONVENTIONS.md, Documentation section

---

## Context Anti-Patterns

Avoid these common context management mistakes:

### Stale Context

Context files become outdated and misleading when ARCHITECTURE.md
describes components that no longer exist, or CONVENTIONS.md patterns
contradict actual code. **Solution**: Update context as part of
completing work, not as a separate task. Run `ctx drift` periodically.

### Context Sprawl

Information scattered across multiple locations — same decision in
DECISIONS.md and a session file, conventions split between
CONVENTIONS.md and code comments. **Solution**: Single source of
truth for each type of information. Use the defined file structure.

### Implicit Context

Relying on knowledge not captured in artifacts — "everyone knows we
don't do X" but it's not in CONSTITUTION.md, patterns followed but
not in CONVENTIONS.md. **Solution**: If you reference something
repeatedly, add it to the appropriate file.

### Over-Specification

Context becomes so detailed it's impossible to maintain — 50+ rules
in CONVENTIONS.md, every minor choice gets a DECISIONS.md entry.
**Solution**: Keep artifacts focused on decisions that affect behavior
and alignment. Not everything needs documenting.

### Context Avoidance

Not using context because "it's faster to just code." Same mistakes
repeated across sessions, decisions re-debated because prior decisions
weren't found. **Solution**: Reading context is faster than
re-discovering it. 5 minutes reading saves 50 minutes of wasted work.

---

## Context Validation Checklist

### Quick Check (Every Session)
- [ ] TASKS.md reflects current priorities
- [ ] No obvious staleness in files you'll reference
- [ ] Recent history reviewed via `ctx recall list`

### Deep Check (Weekly or Before Major Work)
- [ ] CONSTITUTION.md rules still apply
- [ ] ARCHITECTURE.md matches actual structure
- [ ] CONVENTIONS.md patterns match code
- [ ] DECISIONS.md has no superseded entries unmarked
- [ ] LEARNINGS.md gotchas still relevant
- [ ] Run `ctx drift` and address warnings
Loading
Loading