mirror of
https://github.com/affaan-m/everything-claude-code.git
synced 2026-03-30 13:43:26 +08:00
Merge origin/main into Xabilimon1/main
This commit is contained in:
Affaan Mustafa
178
skills/agent-payment-x402/SKILL.md
Normal file
178
skills/agent-payment-x402/SKILL.md
Normal file
@@ -0,0 +1,178 @@
|
||||
---
|
||||
name: agent-payment-x402
|
||||
description: Add x402 payment execution to AI agents — per-task budgets, spending controls, and non-custodial wallets via MCP tools. Use when agents need to pay for APIs, services, or other agents.
|
||||
origin: community
|
||||
---
|
||||
|
||||
# Agent Payment Execution (x402)
|
||||
|
||||
Enable AI agents to make autonomous payments with built-in spending controls. Uses the x402 HTTP payment protocol and MCP tools so agents can pay for external services, APIs, or other agents without custodial risk.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use when: your agent needs to pay for an API call, purchase a service, settle with another agent, enforce per-task spending limits, or manage a non-custodial wallet. Pairs naturally with cost-aware-llm-pipeline and security-review skills.
|
||||
|
||||
## How It Works
|
||||
|
||||
### x402 Protocol
|
||||
x402 extends HTTP 402 (Payment Required) into a machine-negotiable flow. When a server returns `402`, the agent's payment tool automatically negotiates price, checks budget, signs a transaction, and retries — no human in the loop.
|
||||
|
||||
### Spending Controls
|
||||
Every payment tool call enforces a `SpendingPolicy`:
|
||||
- **Per-task budget** — max spend for a single agent action
|
||||
- **Per-session budget** — cumulative limit across an entire session
|
||||
- **Allowlisted recipients** — restrict which addresses/services the agent can pay
|
||||
- **Rate limits** — max transactions per minute/hour
|
||||
|
||||
### Non-Custodial Wallets
|
||||
Agents hold their own keys via ERC-4337 smart accounts. The orchestrator sets policy before delegation; the agent can only spend within bounds. No pooled funds, no custodial risk.
|
||||
|
||||
## MCP Integration
|
||||
|
||||
The payment layer exposes standard MCP tools that slot into any Claude Code or agent harness setup.
|
||||
|
||||
> **Security note**: Always pin the package version. This tool manages private keys — unpinned `npx` installs introduce supply-chain risk.
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"agentpay": {
|
||||
"command": "npx",
|
||||
"args": ["agentwallet-sdk@6.0.0"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Available Tools (agent-callable)
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
| `get_balance` | Check agent wallet balance |
|
||||
| `send_payment` | Send payment to address or ENS |
|
||||
| `check_spending` | Query remaining budget |
|
||||
| `list_transactions` | Audit trail of all payments |
|
||||
|
||||
> **Note**: Spending policy is set by the **orchestrator** before delegating to the agent — not by the agent itself. This prevents agents from escalating their own spending limits. Configure policy via `set_policy` in your orchestration layer or pre-task hook, never as an agent-callable tool.
|
||||
|
||||
## Examples
|
||||
|
||||
### Budget enforcement in an MCP client
|
||||
|
||||
When building an orchestrator that calls the agentpay MCP server, enforce budgets before dispatching paid tool calls.
|
||||
|
||||
> **Prerequisites**: Install the package before adding the MCP config — `npx` without `-y` will prompt for confirmation in non-interactive environments, causing the server to hang: `npm install -g agentwallet-sdk@6.0.0`
|
||||
|
||||
```typescript
|
||||
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
||||
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
|
||||
|
||||
async function main() {
|
||||
// 1. Validate credentials before constructing the transport.
|
||||
// A missing key must fail immediately — never let the subprocess start without auth.
|
||||
const walletKey = process.env.WALLET_PRIVATE_KEY;
|
||||
if (!walletKey) {
|
||||
throw new Error("WALLET_PRIVATE_KEY is not set — refusing to start payment server");
|
||||
}
|
||||
|
||||
// Connect to the agentpay MCP server via stdio transport.
|
||||
// Whitelist only the env vars the server needs — never forward all of process.env
|
||||
// to a third-party subprocess that manages private keys.
|
||||
const transport = new StdioClientTransport({
|
||||
command: "npx",
|
||||
args: ["agentwallet-sdk@6.0.0"],
|
||||
env: {
|
||||
PATH: process.env.PATH ?? "",
|
||||
NODE_ENV: process.env.NODE_ENV ?? "production",
|
||||
WALLET_PRIVATE_KEY: walletKey,
|
||||
},
|
||||
});
|
||||
const agentpay = new Client({ name: "orchestrator", version: "1.0.0" });
|
||||
await agentpay.connect(transport);
|
||||
|
||||
// 2. Set spending policy before delegating to the agent.
|
||||
// Always verify success — a silent failure means no controls are active.
|
||||
const policyResult = await agentpay.callTool({
|
||||
name: "set_policy",
|
||||
arguments: {
|
||||
per_task_budget: 0.50,
|
||||
per_session_budget: 5.00,
|
||||
allowlisted_recipients: ["api.example.com"],
|
||||
},
|
||||
});
|
||||
if (policyResult.isError) {
|
||||
throw new Error(
|
||||
`Failed to set spending policy — do not delegate: ${JSON.stringify(policyResult.content)}`
|
||||
);
|
||||
}
|
||||
|
||||
// 3. Use preToolCheck before any paid action
|
||||
await preToolCheck(agentpay, 0.01);
|
||||
}
|
||||
|
||||
// Pre-tool hook: fail-closed budget enforcement with four distinct error paths.
|
||||
async function preToolCheck(agentpay: Client, apiCost: number): Promise<void> {
|
||||
// Path 1: Reject invalid input (NaN/Infinity bypass the < comparison)
|
||||
if (!Number.isFinite(apiCost) || apiCost < 0) {
|
||||
throw new Error(`Invalid apiCost: ${apiCost} — action blocked`);
|
||||
}
|
||||
|
||||
// Path 2: Transport/connectivity failure
|
||||
let result;
|
||||
try {
|
||||
result = await agentpay.callTool({ name: "check_spending" });
|
||||
} catch (err) {
|
||||
throw new Error(`Payment service unreachable — action blocked: ${err}`);
|
||||
}
|
||||
|
||||
// Path 3: Tool returned an error (e.g., auth failure, wallet not initialised)
|
||||
if (result.isError) {
|
||||
throw new Error(
|
||||
`check_spending failed — action blocked: ${JSON.stringify(result.content)}`
|
||||
);
|
||||
}
|
||||
|
||||
// Path 4: Parse and validate the response shape
|
||||
let remaining: number;
|
||||
try {
|
||||
const parsed = JSON.parse(
|
||||
(result.content as Array<{ text: string }>)[0].text
|
||||
);
|
||||
if (!Number.isFinite(parsed?.remaining)) {
|
||||
throw new TypeError("missing or non-finite 'remaining' field");
|
||||
}
|
||||
remaining = parsed.remaining;
|
||||
} catch (err) {
|
||||
throw new Error(
|
||||
`check_spending returned unexpected format — action blocked: ${err}`
|
||||
);
|
||||
}
|
||||
|
||||
// Path 5: Budget exceeded
|
||||
if (remaining < apiCost) {
|
||||
throw new Error(
|
||||
`Budget exceeded: need $${apiCost} but only $${remaining} remaining`
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
main().catch((err) => {
|
||||
console.error(err);
|
||||
process.exitCode = 1;
|
||||
});
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Set budgets before delegation**: When spawning sub-agents, attach a SpendingPolicy via your orchestration layer. Never give an agent unlimited spend.
|
||||
- **Pin your dependencies**: Always specify an exact version in your MCP config (e.g., `agentwallet-sdk@6.0.0`). Verify package integrity before deploying to production.
|
||||
- **Audit trails**: Use `list_transactions` in post-task hooks to log what was spent and why.
|
||||
- **Fail closed**: If the payment tool is unreachable, block the paid action — don't fall back to unmetered access.
|
||||
- **Pair with security-review**: Payment tools are high-privilege. Apply the same scrutiny as shell access.
|
||||
- **Test with testnets first**: Use Base Sepolia for development; switch to Base mainnet for production.
|
||||
|
||||
## Production Reference
|
||||
|
||||
- **npm**: [`agentwallet-sdk`](https://www.npmjs.com/package/agentwallet-sdk)
|
||||
- **Merged into NVIDIA NeMo Agent Toolkit**: [PR #17](https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples/pull/17) — x402 payment tool for NVIDIA's agent examples
|
||||
- **Protocol spec**: [x402.org](https://x402.org)
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
name: benchmark
|
||||
description: Use this skill to measure performance baselines, detect regressions before/after PRs, and compare stack alternatives.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Benchmark — Performance Baseline & Regression Detection
|
||||
|
||||
## When to Use
|
||||
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
name: browser-qa
|
||||
description: Use this skill to automate visual testing and UI interaction verification using browser automation after deploying features.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Browser QA — Automated Visual Testing & Interaction
|
||||
|
||||
## When to Use
|
||||
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
name: canary-watch
|
||||
description: Use this skill to monitor a deployed URL for regressions after deploys, merges, or dependency upgrades.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Canary Watch — Post-Deploy Monitoring
|
||||
|
||||
## When to Use
|
||||
|
||||
147
skills/ck/SKILL.md
Normal file
147
skills/ck/SKILL.md
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
name: ck
|
||||
description: Persistent per-project memory for Claude Code. Auto-loads project context on session start, tracks sessions with git activity, and writes to native memory. Commands run deterministic Node.js scripts — behavior is consistent across model versions.
|
||||
origin: community
|
||||
version: 2.0.0
|
||||
author: sreedhargs89
|
||||
repo: https://github.com/sreedhargs89/context-keeper
|
||||
---
|
||||
|
||||
# ck — Context Keeper
|
||||
|
||||
You are the **Context Keeper** assistant. When the user invokes any `/ck:*` command,
|
||||
run the corresponding Node.js script and present its stdout to the user verbatim.
|
||||
Scripts live at: `~/.claude/skills/ck/commands/` (expand `~` with `$HOME`).
|
||||
|
||||
---
|
||||
|
||||
## Data Layout
|
||||
|
||||
```
|
||||
~/.claude/ck/
|
||||
├── projects.json ← path → {name, contextDir, lastUpdated}
|
||||
└── contexts/<name>/
|
||||
├── context.json ← SOURCE OF TRUTH (structured JSON, v2)
|
||||
└── CONTEXT.md ← generated view — do not hand-edit
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Commands
|
||||
|
||||
### `/ck:init` — Register a Project
|
||||
```bash
|
||||
node "$HOME/.claude/skills/ck/commands/init.mjs"
|
||||
```
|
||||
The script outputs JSON with auto-detected info. Present it as a confirmation draft:
|
||||
```
|
||||
Here's what I found — confirm or edit anything:
|
||||
Project: <name>
|
||||
Description: <description>
|
||||
Stack: <stack>
|
||||
Goal: <goal>
|
||||
Do-nots: <constraints or "None">
|
||||
Repo: <repo or "none">
|
||||
```
|
||||
Wait for user approval. Apply any edits. Then pipe confirmed JSON to save.mjs --init:
|
||||
```bash
|
||||
echo '<confirmed-json>' | node "$HOME/.claude/skills/ck/commands/save.mjs" --init
|
||||
```
|
||||
Confirmed JSON schema: `{"name":"...","path":"...","description":"...","stack":["..."],"goal":"...","constraints":["..."],"repo":"..." }`
|
||||
|
||||
---
|
||||
|
||||
### `/ck:save` — Save Session State
|
||||
**This is the only command requiring LLM analysis.** Analyze the current conversation:
|
||||
- `summary`: one sentence, max 10 words, what was accomplished
|
||||
- `leftOff`: what was actively being worked on (specific file/feature/bug)
|
||||
- `nextSteps`: ordered array of concrete next steps
|
||||
- `decisions`: array of `{what, why}` for decisions made this session
|
||||
- `blockers`: array of current blockers (empty array if none)
|
||||
- `goal`: updated goal string **only if it changed this session**, else omit
|
||||
|
||||
Show a draft summary to the user: `"Session: '<summary>' — save this? (yes / edit)"`
|
||||
Wait for confirmation. Then pipe to save.mjs:
|
||||
```bash
|
||||
echo '<json>' | node "$HOME/.claude/skills/ck/commands/save.mjs"
|
||||
```
|
||||
JSON schema (exact): `{"summary":"...","leftOff":"...","nextSteps":["..."],"decisions":[{"what":"...","why":"..."}],"blockers":["..."]}`
|
||||
Display the script's stdout confirmation verbatim.
|
||||
|
||||
---
|
||||
|
||||
### `/ck:resume [name|number]` — Full Briefing
|
||||
```bash
|
||||
node "$HOME/.claude/skills/ck/commands/resume.mjs" [arg]
|
||||
```
|
||||
Display output verbatim. Then ask: "Continue from here? Or has anything changed?"
|
||||
If user reports changes → run `/ck:save` immediately.
|
||||
|
||||
---
|
||||
|
||||
### `/ck:info [name|number]` — Quick Snapshot
|
||||
```bash
|
||||
node "$HOME/.claude/skills/ck/commands/info.mjs" [arg]
|
||||
```
|
||||
Display output verbatim. No follow-up question.
|
||||
|
||||
---
|
||||
|
||||
### `/ck:list` — Portfolio View
|
||||
```bash
|
||||
node "$HOME/.claude/skills/ck/commands/list.mjs"
|
||||
```
|
||||
Display output verbatim. If user replies with a number or name → run `/ck:resume`.
|
||||
|
||||
---
|
||||
|
||||
### `/ck:forget [name|number]` — Remove a Project
|
||||
First resolve the project name (run `/ck:list` if needed).
|
||||
Ask: `"This will permanently delete context for '<name>'. Are you sure? (yes/no)"`
|
||||
If yes:
|
||||
```bash
|
||||
node "$HOME/.claude/skills/ck/commands/forget.mjs" [name]
|
||||
```
|
||||
Display confirmation verbatim.
|
||||
|
||||
---
|
||||
|
||||
### `/ck:migrate` — Convert v1 Data to v2
|
||||
```bash
|
||||
node "$HOME/.claude/skills/ck/commands/migrate.mjs"
|
||||
```
|
||||
For a dry run first:
|
||||
```bash
|
||||
node "$HOME/.claude/skills/ck/commands/migrate.mjs" --dry-run
|
||||
```
|
||||
Display output verbatim. Migrates all v1 CONTEXT.md + meta.json files to v2 context.json.
|
||||
Originals are backed up as `meta.json.v1-backup` — nothing is deleted.
|
||||
|
||||
---
|
||||
|
||||
## SessionStart Hook
|
||||
|
||||
The hook at `~/.claude/skills/ck/hooks/session-start.mjs` must be registered in
|
||||
`~/.claude/settings.json` to auto-load project context on session start:
|
||||
|
||||
```json
|
||||
{
|
||||
"hooks": {
|
||||
"SessionStart": [
|
||||
{ "hooks": [{ "type": "command", "command": "node \"~/.claude/skills/ck/hooks/session-start.mjs\"" }] }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The hook injects ~100 tokens per session (compact 5-line summary). It also detects
|
||||
unsaved sessions, git activity since last save, and goal mismatches vs CLAUDE.md.
|
||||
|
||||
---
|
||||
|
||||
## Rules
|
||||
- Always expand `~` as `$HOME` in Bash calls.
|
||||
- Commands are case-insensitive: `/CK:SAVE`, `/ck:save`, `/Ck:Save` all work.
|
||||
- If a script exits with code 1, display its stdout as an error message.
|
||||
- Never edit `context.json` or `CONTEXT.md` directly — always use the scripts.
|
||||
- If `projects.json` is malformed, tell the user and offer to reset it to `{}`.
|
||||
44
skills/ck/commands/forget.mjs
Normal file
44
skills/ck/commands/forget.mjs
Normal file
@@ -0,0 +1,44 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* ck — Context Keeper v2
|
||||
* forget.mjs — remove a project's context and registry entry
|
||||
*
|
||||
* Usage: node forget.mjs [name|number]
|
||||
* stdout: confirmation or error
|
||||
* exit 0: success exit 1: not found
|
||||
*
|
||||
* Note: SKILL.md instructs Claude to ask "Are you sure?" before calling this script.
|
||||
* This script is the "do it" step — no confirmation prompt here.
|
||||
*/
|
||||
|
||||
import { rmSync } from 'fs';
|
||||
import { resolve } from 'path';
|
||||
import { resolveContext, readProjects, writeProjects, CONTEXTS_DIR } from './shared.mjs';
|
||||
|
||||
const arg = process.argv[2];
|
||||
const cwd = process.env.PWD || process.cwd();
|
||||
|
||||
const resolved = resolveContext(arg, cwd);
|
||||
if (!resolved) {
|
||||
const hint = arg ? `No project matching "${arg}".` : 'This directory is not registered.';
|
||||
console.log(`${hint}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const { name, contextDir, projectPath } = resolved;
|
||||
|
||||
// Remove context directory
|
||||
const contextDirPath = resolve(CONTEXTS_DIR, contextDir);
|
||||
try {
|
||||
rmSync(contextDirPath, { recursive: true, force: true });
|
||||
} catch (e) {
|
||||
console.log(`ck: could not remove context directory — ${e.message}`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Remove from projects.json
|
||||
const projects = readProjects();
|
||||
delete projects[projectPath];
|
||||
writeProjects(projects);
|
||||
|
||||
console.log(`✓ Context for '${name}' removed.`);
|
||||
24
skills/ck/commands/info.mjs
Normal file
24
skills/ck/commands/info.mjs
Normal file
@@ -0,0 +1,24 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* ck — Context Keeper v2
|
||||
* info.mjs — quick read-only context snapshot
|
||||
*
|
||||
* Usage: node info.mjs [name|number]
|
||||
* stdout: compact info block
|
||||
* exit 0: success exit 1: not found
|
||||
*/
|
||||
|
||||
import { resolveContext, renderInfoBlock } from './shared.mjs';
|
||||
|
||||
const arg = process.argv[2];
|
||||
const cwd = process.env.PWD || process.cwd();
|
||||
|
||||
const resolved = resolveContext(arg, cwd);
|
||||
if (!resolved) {
|
||||
const hint = arg ? `No project matching "${arg}".` : 'This directory is not registered.';
|
||||
console.log(`${hint} Run /ck:init to register it.`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log('');
|
||||
console.log(renderInfoBlock(resolved.context));
|
||||
143
skills/ck/commands/init.mjs
Normal file
143
skills/ck/commands/init.mjs
Normal file
@@ -0,0 +1,143 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* ck — Context Keeper v2
|
||||
* init.mjs — auto-detect project info and output JSON for Claude to confirm
|
||||
*
|
||||
* Usage: node init.mjs
|
||||
* stdout: JSON with auto-detected project info
|
||||
* exit 0: success exit 1: error
|
||||
*/
|
||||
|
||||
import { readFileSync, existsSync } from 'fs';
|
||||
import { resolve, basename } from 'path';
|
||||
import { readProjects } from './shared.mjs';
|
||||
|
||||
const cwd = process.env.PWD || process.cwd();
|
||||
const projects = readProjects();
|
||||
|
||||
const output = {
|
||||
path: cwd,
|
||||
name: null,
|
||||
description: null,
|
||||
stack: [],
|
||||
goal: null,
|
||||
constraints: [],
|
||||
repo: null,
|
||||
alreadyRegistered: !!projects[cwd],
|
||||
};
|
||||
|
||||
function readFile(filename) {
|
||||
const p = resolve(cwd, filename);
|
||||
if (!existsSync(p)) return null;
|
||||
try { return readFileSync(p, 'utf8'); } catch { return null; }
|
||||
}
|
||||
|
||||
function extractSection(md, heading) {
|
||||
const re = new RegExp(`## ${heading}\\n([\\s\\S]*?)(?=\\n## |$)`);
|
||||
const m = md.match(re);
|
||||
return m ? m[1].trim() : null;
|
||||
}
|
||||
|
||||
// ── package.json ──────────────────────────────────────────────────────────────
|
||||
const pkg = readFile('package.json');
|
||||
if (pkg) {
|
||||
try {
|
||||
const parsed = JSON.parse(pkg);
|
||||
if (parsed.name && !output.name) output.name = parsed.name;
|
||||
if (parsed.description && !output.description) output.description = parsed.description;
|
||||
|
||||
// Detect stack from dependencies
|
||||
const deps = Object.keys({ ...(parsed.dependencies || {}), ...(parsed.devDependencies || {}) });
|
||||
const stackMap = {
|
||||
next: 'Next.js', react: 'React', vue: 'Vue', svelte: 'Svelte', astro: 'Astro',
|
||||
express: 'Express', fastify: 'Fastify', hono: 'Hono', nestjs: 'NestJS',
|
||||
typescript: 'TypeScript', prisma: 'Prisma', drizzle: 'Drizzle',
|
||||
'@neondatabase/serverless': 'Neon', '@upstash/redis': 'Upstash Redis',
|
||||
'@clerk/nextjs': 'Clerk', stripe: 'Stripe', tailwindcss: 'Tailwind CSS',
|
||||
};
|
||||
for (const [dep, label] of Object.entries(stackMap)) {
|
||||
if (deps.includes(dep) && !output.stack.includes(label)) {
|
||||
output.stack.push(label);
|
||||
}
|
||||
}
|
||||
if (deps.includes('typescript') || existsSync(resolve(cwd, 'tsconfig.json'))) {
|
||||
if (!output.stack.includes('TypeScript')) output.stack.push('TypeScript');
|
||||
}
|
||||
} catch { /* malformed package.json */ }
|
||||
}
|
||||
|
||||
// ── go.mod ────────────────────────────────────────────────────────────────────
|
||||
const goMod = readFile('go.mod');
|
||||
if (goMod) {
|
||||
if (!output.stack.includes('Go')) output.stack.push('Go');
|
||||
const modName = goMod.match(/^module\s+(\S+)/m)?.[1];
|
||||
if (modName && !output.name) output.name = modName.split('/').pop();
|
||||
}
|
||||
|
||||
// ── Cargo.toml ────────────────────────────────────────────────────────────────
|
||||
const cargo = readFile('Cargo.toml');
|
||||
if (cargo) {
|
||||
if (!output.stack.includes('Rust')) output.stack.push('Rust');
|
||||
const crateName = cargo.match(/^name\s*=\s*"(.+?)"/m)?.[1];
|
||||
if (crateName && !output.name) output.name = crateName;
|
||||
}
|
||||
|
||||
// ── pyproject.toml ────────────────────────────────────────────────────────────
|
||||
const pyproject = readFile('pyproject.toml');
|
||||
if (pyproject) {
|
||||
if (!output.stack.includes('Python')) output.stack.push('Python');
|
||||
const pyName = pyproject.match(/^name\s*=\s*"(.+?)"/m)?.[1];
|
||||
if (pyName && !output.name) output.name = pyName;
|
||||
}
|
||||
|
||||
// ── .git/config (repo URL) ────────────────────────────────────────────────────
|
||||
const gitConfig = readFile('.git/config');
|
||||
if (gitConfig) {
|
||||
const repoMatch = gitConfig.match(/url\s*=\s*(.+)/);
|
||||
if (repoMatch) output.repo = repoMatch[1].trim();
|
||||
}
|
||||
|
||||
// ── CLAUDE.md ─────────────────────────────────────────────────────────────────
|
||||
const claudeMd = readFile('CLAUDE.md');
|
||||
if (claudeMd) {
|
||||
const goal = extractSection(claudeMd, 'Current Goal');
|
||||
if (goal && !output.goal) output.goal = goal.split('\n')[0].trim();
|
||||
|
||||
const doNot = extractSection(claudeMd, 'Do Not Do');
|
||||
if (doNot) {
|
||||
const bullets = doNot.split('\n')
|
||||
.filter(l => /^[-*]\s+/.test(l))
|
||||
.map(l => l.replace(/^[-*]\s+/, '').trim());
|
||||
output.constraints = bullets;
|
||||
}
|
||||
|
||||
const stack = extractSection(claudeMd, 'Tech Stack');
|
||||
if (stack && output.stack.length === 0) {
|
||||
output.stack = stack.split(/[,\n]/).map(s => s.replace(/^[-*]\s+/, '').trim()).filter(Boolean);
|
||||
}
|
||||
|
||||
// Description from first section or "What This Is"
|
||||
const whatItIs = extractSection(claudeMd, 'What This Is') || extractSection(claudeMd, 'About');
|
||||
if (whatItIs && !output.description) output.description = whatItIs.split('\n')[0].trim();
|
||||
}
|
||||
|
||||
// ── README.md (description fallback) ─────────────────────────────────────────
|
||||
const readme = readFile('README.md');
|
||||
if (readme && !output.description) {
|
||||
// First non-header, non-badge, non-empty paragraph
|
||||
const lines = readme.split('\n');
|
||||
for (const line of lines) {
|
||||
const trimmed = line.trim();
|
||||
if (trimmed && !trimmed.startsWith('#') && !trimmed.startsWith('!') && !trimmed.startsWith('>') && !trimmed.startsWith('[') && trimmed !== '---' && trimmed !== '___') {
|
||||
output.description = trimmed.slice(0, 120);
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ── Name fallback: directory name ─────────────────────────────────────────────
|
||||
if (!output.name) {
|
||||
output.name = basename(cwd).toLowerCase().replace(/\s+/g, '-');
|
||||
}
|
||||
|
||||
console.log(JSON.stringify(output, null, 2));
|
||||
41
skills/ck/commands/list.mjs
Normal file
41
skills/ck/commands/list.mjs
Normal file
@@ -0,0 +1,41 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* ck — Context Keeper v2
|
||||
* list.mjs — portfolio view of all registered projects
|
||||
*
|
||||
* Usage: node list.mjs
|
||||
* stdout: ASCII table of all projects + prompt to resume
|
||||
* exit 0: success exit 1: no projects
|
||||
*/
|
||||
|
||||
import { readProjects, loadContext, today, CONTEXTS_DIR } from './shared.mjs';
|
||||
import { renderListTable } from './shared.mjs';
|
||||
|
||||
const cwd = process.env.PWD || process.cwd();
|
||||
const projects = readProjects();
|
||||
const entries = Object.entries(projects);
|
||||
|
||||
if (entries.length === 0) {
|
||||
console.log('No projects registered. Run /ck:init to get started.');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Build enriched list sorted alphabetically by contextDir
|
||||
const enriched = entries
|
||||
.map(([path, info]) => {
|
||||
const context = loadContext(info.contextDir);
|
||||
return {
|
||||
name: info.name,
|
||||
contextDir: info.contextDir,
|
||||
path,
|
||||
context,
|
||||
lastUpdated: info.lastUpdated,
|
||||
};
|
||||
})
|
||||
.sort((a, b) => a.contextDir.localeCompare(b.contextDir));
|
||||
|
||||
const table = renderListTable(enriched, cwd, today());
|
||||
console.log('');
|
||||
console.log(table);
|
||||
console.log('');
|
||||
console.log('Resume which? (number or name)');
|
||||
198
skills/ck/commands/migrate.mjs
Normal file
198
skills/ck/commands/migrate.mjs
Normal file
@@ -0,0 +1,198 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* ck — Context Keeper v2
|
||||
* migrate.mjs — convert v1 (CONTEXT.md + meta.json) to v2 (context.json)
|
||||
*
|
||||
* Usage:
|
||||
* node migrate.mjs — migrate all v1 projects
|
||||
* node migrate.mjs --dry-run — preview without writing
|
||||
*
|
||||
* Safe: backs up meta.json to meta.json.v1-backup, never deletes data.
|
||||
* exit 0: success exit 1: error
|
||||
*/
|
||||
|
||||
import { readFileSync, writeFileSync, existsSync, renameSync } from 'fs';
|
||||
import { resolve } from 'path';
|
||||
import { readProjects, writeProjects, saveContext, today, shortId, CONTEXTS_DIR } from './shared.mjs';
|
||||
|
||||
const isDryRun = process.argv.includes('--dry-run');
|
||||
|
||||
if (isDryRun) {
|
||||
console.log('ck migrate — DRY RUN (no files will be written)\n');
|
||||
}
|
||||
|
||||
// ── v1 markdown parsers ───────────────────────────────────────────────────────
|
||||
|
||||
function extractSection(md, heading) {
|
||||
const re = new RegExp(`## ${heading}\\n([\\s\\S]*?)(?=\\n## |$)`);
|
||||
const m = md.match(re);
|
||||
return m ? m[1].trim() : null;
|
||||
}
|
||||
|
||||
function parseBullets(text) {
|
||||
if (!text) return [];
|
||||
return text.split('\n')
|
||||
.filter(l => /^[-*\d]\s/.test(l.trim()))
|
||||
.map(l => l.replace(/^[-*\d]+\.?\s+/, '').trim())
|
||||
.filter(Boolean);
|
||||
}
|
||||
|
||||
function parseDecisionsTable(text) {
|
||||
if (!text) return [];
|
||||
const rows = [];
|
||||
for (const line of text.split('\n')) {
|
||||
if (!line.startsWith('|') || line.match(/^[|\s-]+$/)) continue;
|
||||
const cols = line.split('|').map(c => c.trim()).filter((c, i) => i > 0 && i < 4);
|
||||
if (cols.length >= 1 && !cols[0].startsWith('Decision') && !cols[0].startsWith('_')) {
|
||||
rows.push({ what: cols[0] || '', why: cols[1] || '', date: cols[2] || '' });
|
||||
}
|
||||
}
|
||||
return rows;
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse "Where I Left Off" which in v1 can be:
|
||||
* - Simple bullet list
|
||||
* - Multi-session blocks: "Session N (date):\n- bullet\n"
|
||||
* Returns array of session-like objects {date?, leftOff}
|
||||
*/
|
||||
function parseLeftOff(text) {
|
||||
if (!text) return [{ leftOff: null }];
|
||||
|
||||
// Detect multi-session format: "Session N ..."
|
||||
const sessionBlocks = text.split(/(?=Session \d+)/);
|
||||
if (sessionBlocks.length > 1) {
|
||||
return sessionBlocks
|
||||
.filter(b => b.trim())
|
||||
.map(block => {
|
||||
const dateMatch = block.match(/\((\d{4}-\d{2}-\d{2})\)/);
|
||||
const bullets = parseBullets(block);
|
||||
return {
|
||||
date: dateMatch?.[1] || null,
|
||||
leftOff: bullets.length ? bullets.join('\n') : block.replace(/^Session \d+.*\n/, '').trim(),
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
// Simple format
|
||||
const bullets = parseBullets(text);
|
||||
return [{ leftOff: bullets.length ? bullets.join('\n') : text.trim() }];
|
||||
}
|
||||
|
||||
// ── Main migration ─────────────────────────────────────────────────────────────
|
||||
|
||||
const projects = readProjects();
|
||||
let migrated = 0;
|
||||
let skipped = 0;
|
||||
let errors = 0;
|
||||
|
||||
for (const [projectPath, info] of Object.entries(projects)) {
|
||||
const contextDir = info.contextDir;
|
||||
const contextDirPath = resolve(CONTEXTS_DIR, contextDir);
|
||||
const contextJsonPath = resolve(contextDirPath, 'context.json');
|
||||
const contextMdPath = resolve(contextDirPath, 'CONTEXT.md');
|
||||
const metaPath = resolve(contextDirPath, 'meta.json');
|
||||
|
||||
// Already v2
|
||||
if (existsSync(contextJsonPath)) {
|
||||
try {
|
||||
const existing = JSON.parse(readFileSync(contextJsonPath, 'utf8'));
|
||||
if (existing.version === 2) {
|
||||
console.log(` ✓ ${contextDir} — already v2, skipping`);
|
||||
skipped++;
|
||||
continue;
|
||||
}
|
||||
} catch { /* fall through to migrate */ }
|
||||
}
|
||||
|
||||
console.log(`\n → Migrating: ${contextDir}`);
|
||||
|
||||
try {
|
||||
// Read v1 files
|
||||
const contextMd = existsSync(contextMdPath) ? readFileSync(contextMdPath, 'utf8') : '';
|
||||
let meta = {};
|
||||
if (existsSync(metaPath)) {
|
||||
try { meta = JSON.parse(readFileSync(metaPath, 'utf8')); } catch {}
|
||||
}
|
||||
|
||||
// Extract fields from CONTEXT.md
|
||||
const description = extractSection(contextMd, 'What This Is') || extractSection(contextMd, 'About') || null;
|
||||
const stackRaw = extractSection(contextMd, 'Tech Stack') || '';
|
||||
const stack = stackRaw.split(/[,\n]/).map(s => s.replace(/^[-*]\s+/, '').trim()).filter(Boolean);
|
||||
const goal = (extractSection(contextMd, 'Current Goal') || '').split('\n')[0].trim() || null;
|
||||
const constraintRaw = extractSection(contextMd, 'Do Not Do') || '';
|
||||
const constraints = parseBullets(constraintRaw);
|
||||
const decisionsRaw = extractSection(contextMd, 'Decisions Made') || '';
|
||||
const decisions = parseDecisionsTable(decisionsRaw);
|
||||
const nextStepsRaw = extractSection(contextMd, 'Next Steps') || '';
|
||||
const nextSteps = parseBullets(nextStepsRaw);
|
||||
const blockersRaw = extractSection(contextMd, 'Blockers') || '';
|
||||
const blockers = parseBullets(blockersRaw).filter(b => b.toLowerCase() !== 'none');
|
||||
const leftOffRaw = extractSection(contextMd, 'Where I Left Off') || '';
|
||||
const leftOffParsed = parseLeftOff(leftOffRaw);
|
||||
|
||||
// Build sessions from parsed left-off blocks (may be multiple)
|
||||
const sessions = leftOffParsed.map((lo, idx) => ({
|
||||
id: idx === leftOffParsed.length - 1 && meta.lastSessionId
|
||||
? meta.lastSessionId.slice(0, 8)
|
||||
: shortId(),
|
||||
date: lo.date || meta.lastUpdated || today(),
|
||||
summary: idx === leftOffParsed.length - 1
|
||||
? (meta.lastSessionSummary || 'Migrated from v1')
|
||||
: `Session ${idx + 1} (migrated)`,
|
||||
leftOff: lo.leftOff,
|
||||
nextSteps: idx === leftOffParsed.length - 1 ? nextSteps : [],
|
||||
decisions: idx === leftOffParsed.length - 1 ? decisions : [],
|
||||
blockers: idx === leftOffParsed.length - 1 ? blockers : [],
|
||||
}));
|
||||
|
||||
const context = {
|
||||
version: 2,
|
||||
name: contextDir,
|
||||
path: meta.path || projectPath,
|
||||
description,
|
||||
stack,
|
||||
goal,
|
||||
constraints,
|
||||
repo: meta.repo || null,
|
||||
createdAt: meta.lastUpdated || today(),
|
||||
sessions,
|
||||
};
|
||||
|
||||
if (isDryRun) {
|
||||
console.log(` description: ${description?.slice(0, 60) || '(none)'}`);
|
||||
console.log(` stack: ${stack.join(', ') || '(none)'}`);
|
||||
console.log(` goal: ${goal?.slice(0, 60) || '(none)'}`);
|
||||
console.log(` sessions: ${sessions.length}`);
|
||||
console.log(` decisions: ${decisions.length}`);
|
||||
console.log(` nextSteps: ${nextSteps.length}`);
|
||||
migrated++;
|
||||
continue;
|
||||
}
|
||||
|
||||
// Backup meta.json
|
||||
if (existsSync(metaPath)) {
|
||||
renameSync(metaPath, resolve(contextDirPath, 'meta.json.v1-backup'));
|
||||
}
|
||||
|
||||
// Write context.json + regenerated CONTEXT.md
|
||||
saveContext(contextDir, context);
|
||||
|
||||
// Update projects.json entry
|
||||
projects[projectPath].lastUpdated = today();
|
||||
|
||||
console.log(` ✓ Migrated — ${sessions.length} session(s), ${decisions.length} decision(s)`);
|
||||
migrated++;
|
||||
} catch (e) {
|
||||
console.log(` ✗ Error: ${e.message}`);
|
||||
errors++;
|
||||
}
|
||||
}
|
||||
|
||||
if (!isDryRun && migrated > 0) {
|
||||
writeProjects(projects);
|
||||
}
|
||||
|
||||
console.log(`\nck migrate: ${migrated} migrated, ${skipped} already v2, ${errors} errors`);
|
||||
if (isDryRun) console.log('Run without --dry-run to apply.');
|
||||
if (errors > 0) process.exit(1);
|
||||
36
skills/ck/commands/resume.mjs
Normal file
36
skills/ck/commands/resume.mjs
Normal file
@@ -0,0 +1,36 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* ck — Context Keeper v2
|
||||
* resume.mjs — full project briefing
|
||||
*
|
||||
* Usage: node resume.mjs [name|number]
|
||||
* stdout: bordered briefing box
|
||||
* exit 0: success exit 1: not found
|
||||
*/
|
||||
|
||||
import { existsSync } from 'fs';
|
||||
import { resolveContext, renderBriefingBox } from './shared.mjs';
|
||||
|
||||
const arg = process.argv[2];
|
||||
const cwd = process.env.PWD || process.cwd();
|
||||
|
||||
const resolved = resolveContext(arg, cwd);
|
||||
if (!resolved) {
|
||||
const hint = arg ? `No project matching "${arg}".` : 'This directory is not registered.';
|
||||
console.log(`${hint} Run /ck:init to register it.`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const { context, projectPath } = resolved;
|
||||
|
||||
// Attempt to cd to the project path
|
||||
if (projectPath && projectPath !== cwd) {
|
||||
if (existsSync(projectPath)) {
|
||||
console.log(`→ cd ${projectPath}`);
|
||||
} else {
|
||||
console.log(`⚠ Path not found: ${projectPath}`);
|
||||
}
|
||||
}
|
||||
|
||||
console.log('');
|
||||
console.log(renderBriefingBox(context));
|
||||
210
skills/ck/commands/save.mjs
Normal file
210
skills/ck/commands/save.mjs
Normal file
@@ -0,0 +1,210 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* ck — Context Keeper v2
|
||||
* save.mjs — write session data to context.json, regenerate CONTEXT.md,
|
||||
* and write a native memory entry.
|
||||
*
|
||||
* Usage (regular save):
|
||||
* echo '<json>' | node save.mjs
|
||||
* JSON schema: { summary, leftOff, nextSteps[], decisions[{what,why}], blockers[], goal? }
|
||||
*
|
||||
* Usage (init — first registration):
|
||||
* echo '<json>' | node save.mjs --init
|
||||
* JSON schema: { name, path, description, stack[], goal, constraints[], repo? }
|
||||
*
|
||||
* stdout: confirmation message
|
||||
* exit 0: success exit 1: error
|
||||
*/
|
||||
|
||||
import { readFileSync, mkdirSync, writeFileSync } from 'fs';
|
||||
import { resolve } from 'path';
|
||||
import {
|
||||
readProjects, writeProjects, loadContext, saveContext,
|
||||
today, shortId, gitSummary, nativeMemoryDir, encodeProjectPath,
|
||||
CONTEXTS_DIR, CURRENT_SESSION,
|
||||
} from './shared.mjs';
|
||||
|
||||
const isInit = process.argv.includes('--init');
|
||||
const cwd = process.env.PWD || process.cwd();
|
||||
|
||||
// ── Read JSON from stdin ──────────────────────────────────────────────────────
|
||||
let input;
|
||||
try {
|
||||
const raw = readFileSync(0, 'utf8').trim();
|
||||
if (!raw) throw new Error('empty stdin');
|
||||
input = JSON.parse(raw);
|
||||
} catch (e) {
|
||||
console.error(`ck save: invalid JSON on stdin — ${e.message}`);
|
||||
console.log('Expected schema (save): {"summary":"...","leftOff":"...","nextSteps":["..."],"decisions":[{"what":"...","why":"..."}],"blockers":["..."]}');
|
||||
console.log('Expected schema (--init): {"name":"...","path":"...","description":"...","stack":["..."],"goal":"...","constraints":["..."]}');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// INIT MODE: first-time project registration
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
if (isInit) {
|
||||
const { name, path: projectPath, description, stack, goal, constraints, repo } = input;
|
||||
|
||||
if (!name || !projectPath) {
|
||||
console.log('ck init: name and path are required.');
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const projects = readProjects();
|
||||
|
||||
// Derive contextDir (lowercase, spaces→dashes, deduplicate)
|
||||
let contextDir = name.toLowerCase().replace(/\s+/g, '-').replace(/[^a-z0-9-]/g, '');
|
||||
let suffix = 2;
|
||||
const existingDirs = Object.values(projects).map(p => p.contextDir);
|
||||
while (existingDirs.includes(contextDir) && projects[projectPath]?.contextDir !== contextDir) {
|
||||
contextDir = `${contextDir.replace(/-\d+$/, '')}-${suffix++}`;
|
||||
}
|
||||
|
||||
const context = {
|
||||
version: 2,
|
||||
name: contextDir,
|
||||
displayName: name,
|
||||
path: projectPath,
|
||||
description: description || null,
|
||||
stack: Array.isArray(stack) ? stack : (stack ? [stack] : []),
|
||||
goal: goal || null,
|
||||
constraints: Array.isArray(constraints) ? constraints : [],
|
||||
repo: repo || null,
|
||||
createdAt: today(),
|
||||
sessions: [],
|
||||
};
|
||||
|
||||
saveContext(contextDir, context);
|
||||
|
||||
// Update projects.json
|
||||
projects[projectPath] = {
|
||||
name,
|
||||
contextDir,
|
||||
lastUpdated: today(),
|
||||
};
|
||||
writeProjects(projects);
|
||||
|
||||
console.log(`✓ Project '${name}' registered.`);
|
||||
console.log(` Use /ck:save to save session state and /ck:resume to reload it next time.`);
|
||||
process.exit(0);
|
||||
}
|
||||
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
// SAVE MODE: record a session
|
||||
// ─────────────────────────────────────────────────────────────────────────────
|
||||
const projects = readProjects();
|
||||
const projectEntry = projects[cwd];
|
||||
|
||||
if (!projectEntry) {
|
||||
console.log("This project isn't registered yet. Run /ck:init first.");
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
const { contextDir } = projectEntry;
|
||||
let context = loadContext(contextDir);
|
||||
|
||||
if (!context) {
|
||||
console.log(`ck: context.json not found for '${contextDir}'. The install may be corrupted.`);
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
// Get session ID from current-session.json
|
||||
let sessionId;
|
||||
try {
|
||||
const sess = JSON.parse(readFileSync(CURRENT_SESSION, 'utf8'));
|
||||
sessionId = sess.sessionId || shortId();
|
||||
} catch {
|
||||
sessionId = shortId();
|
||||
}
|
||||
|
||||
// Check for duplicate (re-save of same session)
|
||||
const existingIdx = context.sessions.findIndex(s => s.id === sessionId);
|
||||
|
||||
const { summary, leftOff, nextSteps, decisions, blockers, goal } = input;
|
||||
|
||||
// Capture git activity since the last session
|
||||
const lastSessionDate = context.sessions?.[context.sessions.length - 1]?.date;
|
||||
const gitActivity = gitSummary(cwd, lastSessionDate);
|
||||
|
||||
const session = {
|
||||
id: sessionId,
|
||||
date: today(),
|
||||
summary: summary || 'Session saved',
|
||||
leftOff: leftOff || null,
|
||||
nextSteps: Array.isArray(nextSteps) ? nextSteps : (nextSteps ? [nextSteps] : []),
|
||||
decisions: Array.isArray(decisions) ? decisions : [],
|
||||
blockers: Array.isArray(blockers) ? blockers.filter(Boolean) : [],
|
||||
...(gitActivity ? { gitActivity } : {}),
|
||||
};
|
||||
|
||||
if (existingIdx >= 0) {
|
||||
// Update existing session (re-save)
|
||||
context.sessions[existingIdx] = session;
|
||||
} else {
|
||||
context.sessions.push(session);
|
||||
}
|
||||
|
||||
// Update goal if provided
|
||||
if (goal && goal !== context.goal) {
|
||||
context.goal = goal;
|
||||
}
|
||||
|
||||
// Save context.json + regenerate CONTEXT.md
|
||||
saveContext(contextDir, context);
|
||||
|
||||
// Update projects.json timestamp
|
||||
projects[cwd].lastUpdated = today();
|
||||
writeProjects(projects);
|
||||
|
||||
// ── Write to native memory ────────────────────────────────────────────────────
|
||||
try {
|
||||
const memDir = nativeMemoryDir(cwd);
|
||||
mkdirSync(memDir, { recursive: true });
|
||||
|
||||
const memFile = resolve(memDir, `ck_${today()}_${sessionId.slice(0, 8)}.md`);
|
||||
const decisionsBlock = session.decisions.length
|
||||
? session.decisions.map(d => `- **${d.what}**: ${d.why || ''}`).join('\n')
|
||||
: '- None this session';
|
||||
const nextBlock = session.nextSteps.length
|
||||
? session.nextSteps.map((s, i) => `${i + 1}. ${s}`).join('\n')
|
||||
: '- None recorded';
|
||||
const blockersBlock = session.blockers.length
|
||||
? session.blockers.map(b => `- ${b}`).join('\n')
|
||||
: '- None';
|
||||
|
||||
const memContent = [
|
||||
`---`,
|
||||
`name: Session ${today()} — ${session.summary}`,
|
||||
`description: Key decisions and outcomes from ck session ${sessionId.slice(0, 8)}`,
|
||||
`type: project`,
|
||||
`source: ck`,
|
||||
`sessionId: ${sessionId}`,
|
||||
`---`,
|
||||
``,
|
||||
`# Session: ${session.summary}`,
|
||||
``,
|
||||
`## Decisions`,
|
||||
decisionsBlock,
|
||||
``,
|
||||
`## Left Off`,
|
||||
session.leftOff || '—',
|
||||
``,
|
||||
`## Next Steps`,
|
||||
nextBlock,
|
||||
``,
|
||||
`## Blockers`,
|
||||
blockersBlock,
|
||||
``,
|
||||
...(gitActivity ? [`## Git Activity`, gitActivity, ``] : []),
|
||||
].join('\n');
|
||||
|
||||
writeFileSync(memFile, memContent, 'utf8');
|
||||
} catch (e) {
|
||||
// Non-fatal — native memory write failure should not block the save
|
||||
process.stderr.write(`ck: warning — could not write native memory entry: ${e.message}\n`);
|
||||
}
|
||||
|
||||
console.log(`✓ Saved. Session: ${sessionId.slice(0, 8)}`);
|
||||
if (gitActivity) console.log(` Git: ${gitActivity}`);
|
||||
console.log(` See you next time.`);
|
||||
387
skills/ck/commands/shared.mjs
Normal file
387
skills/ck/commands/shared.mjs
Normal file
@@ -0,0 +1,387 @@
|
||||
/**
|
||||
* ck — Context Keeper v2
|
||||
* shared.mjs — common utilities for all command scripts
|
||||
*
|
||||
* No external dependencies. Node.js stdlib only.
|
||||
*/
|
||||
|
||||
import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from 'fs';
|
||||
import { resolve, basename } from 'path';
|
||||
import { homedir } from 'os';
|
||||
import { spawnSync } from 'child_process';
|
||||
import { randomBytes } from 'crypto';
|
||||
|
||||
// ─── Paths ────────────────────────────────────────────────────────────────────
|
||||
|
||||
export const CK_HOME = resolve(homedir(), '.claude', 'ck');
|
||||
export const CONTEXTS_DIR = resolve(CK_HOME, 'contexts');
|
||||
export const PROJECTS_FILE = resolve(CK_HOME, 'projects.json');
|
||||
export const CURRENT_SESSION = resolve(CK_HOME, 'current-session.json');
|
||||
export const SKILL_FILE = resolve(homedir(), '.claude', 'skills', 'ck', 'SKILL.md');
|
||||
|
||||
// ─── JSON I/O ─────────────────────────────────────────────────────────────────
|
||||
|
||||
export function readJson(filePath) {
|
||||
try {
|
||||
if (!existsSync(filePath)) return null;
|
||||
return JSON.parse(readFileSync(filePath, 'utf8'));
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function writeJson(filePath, data) {
|
||||
const dir = resolve(filePath, '..');
|
||||
mkdirSync(dir, { recursive: true });
|
||||
writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
|
||||
}
|
||||
|
||||
export function readProjects() {
|
||||
return readJson(PROJECTS_FILE) || {};
|
||||
}
|
||||
|
||||
export function writeProjects(projects) {
|
||||
writeJson(PROJECTS_FILE, projects);
|
||||
}
|
||||
|
||||
// ─── Context I/O ──────────────────────────────────────────────────────────────
|
||||
|
||||
export function contextPath(contextDir) {
|
||||
return resolve(CONTEXTS_DIR, contextDir, 'context.json');
|
||||
}
|
||||
|
||||
export function contextMdPath(contextDir) {
|
||||
return resolve(CONTEXTS_DIR, contextDir, 'CONTEXT.md');
|
||||
}
|
||||
|
||||
export function loadContext(contextDir) {
|
||||
return readJson(contextPath(contextDir));
|
||||
}
|
||||
|
||||
export function saveContext(contextDir, data) {
|
||||
const dir = resolve(CONTEXTS_DIR, contextDir);
|
||||
mkdirSync(dir, { recursive: true });
|
||||
writeJson(contextPath(contextDir), data);
|
||||
writeFileSync(contextMdPath(contextDir), renderContextMd(data), 'utf8');
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve which project to operate on.
|
||||
* @param {string|undefined} arg — undefined = cwd match, number string = alphabetical index, else name search
|
||||
* @param {string} cwd
|
||||
* @returns {{ name, contextDir, projectPath, context } | null}
|
||||
*/
|
||||
export function resolveContext(arg, cwd) {
|
||||
const projects = readProjects();
|
||||
const entries = Object.entries(projects); // [path, {name, contextDir, lastUpdated}]
|
||||
|
||||
if (!arg) {
|
||||
// Match by cwd
|
||||
const entry = projects[cwd];
|
||||
if (!entry) return null;
|
||||
const context = loadContext(entry.contextDir);
|
||||
if (!context) return null;
|
||||
return { name: entry.name, contextDir: entry.contextDir, projectPath: cwd, context };
|
||||
}
|
||||
|
||||
// Collect all contexts sorted alphabetically by contextDir
|
||||
const sorted = entries
|
||||
.map(([path, info]) => ({ path, ...info }))
|
||||
.sort((a, b) => a.contextDir.localeCompare(b.contextDir));
|
||||
|
||||
const asNumber = parseInt(arg, 10);
|
||||
if (!isNaN(asNumber) && String(asNumber) === arg) {
|
||||
// Number-based lookup (1-indexed)
|
||||
const item = sorted[asNumber - 1];
|
||||
if (!item) return null;
|
||||
const context = loadContext(item.contextDir);
|
||||
if (!context) return null;
|
||||
return { name: item.name, contextDir: item.contextDir, projectPath: item.path, context };
|
||||
}
|
||||
|
||||
// Name-based lookup: exact > prefix > substring (case-insensitive)
|
||||
const lower = arg.toLowerCase();
|
||||
let match =
|
||||
sorted.find(e => e.name.toLowerCase() === lower) ||
|
||||
sorted.find(e => e.name.toLowerCase().startsWith(lower)) ||
|
||||
sorted.find(e => e.name.toLowerCase().includes(lower));
|
||||
|
||||
if (!match) return null;
|
||||
const context = loadContext(match.contextDir);
|
||||
if (!context) return null;
|
||||
return { name: match.name, contextDir: match.contextDir, projectPath: match.path, context };
|
||||
}
|
||||
|
||||
// ─── Date helpers ─────────────────────────────────────────────────────────────
|
||||
|
||||
export function today() {
|
||||
return new Date().toISOString().slice(0, 10);
|
||||
}
|
||||
|
||||
export function daysAgoLabel(dateStr) {
|
||||
if (!dateStr) return 'unknown';
|
||||
const diff = Math.floor((Date.now() - new Date(dateStr)) / 86_400_000);
|
||||
if (diff === 0) return 'Today';
|
||||
if (diff === 1) return '1 day ago';
|
||||
return `${diff} days ago`;
|
||||
}
|
||||
|
||||
export function stalenessIcon(dateStr) {
|
||||
if (!dateStr) return '○';
|
||||
const diff = Math.floor((Date.now() - new Date(dateStr)) / 86_400_000);
|
||||
if (diff < 1) return '●';
|
||||
if (diff <= 5) return '◐';
|
||||
return '○';
|
||||
}
|
||||
|
||||
// ─── ID generation ────────────────────────────────────────────────────────────
|
||||
|
||||
export function shortId() {
|
||||
return randomBytes(4).toString('hex');
|
||||
}
|
||||
|
||||
// ─── Git helpers ──────────────────────────────────────────────────────────────
|
||||
|
||||
function runGit(args, cwd) {
|
||||
try {
|
||||
const result = spawnSync('git', ['-C', cwd, ...args], {
|
||||
timeout: 3000,
|
||||
stdio: 'pipe',
|
||||
encoding: 'utf8',
|
||||
});
|
||||
if (result.status !== 0) return null;
|
||||
return result.stdout.trim();
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
export function gitLogSince(projectPath, sinceDate) {
|
||||
if (!sinceDate) return null;
|
||||
return runGit(['log', '--oneline', `--since=${sinceDate}`], projectPath);
|
||||
}
|
||||
|
||||
export function gitSummary(projectPath, sinceDate) {
|
||||
const log = gitLogSince(projectPath, sinceDate);
|
||||
if (!log) return null;
|
||||
const commits = log.split('\n').filter(Boolean).length;
|
||||
if (commits === 0) return null;
|
||||
|
||||
// Count unique files changed: use a separate runGit call to avoid nested shell substitution
|
||||
const countStr = runGit(['rev-list', '--count', 'HEAD', `--since=${sinceDate}`], projectPath);
|
||||
const revCount = countStr ? parseInt(countStr, 10) : commits;
|
||||
const diff = runGit(['diff', '--shortstat', `HEAD~${Math.min(revCount, 50)}..HEAD`], projectPath);
|
||||
|
||||
if (diff) {
|
||||
const filesMatch = diff.match(/(\d+) file/);
|
||||
const files = filesMatch ? parseInt(filesMatch[1]) : '?';
|
||||
return `${commits} commit${commits !== 1 ? 's' : ''}, ${files} file${files !== 1 ? 's' : ''} changed`;
|
||||
}
|
||||
return `${commits} commit${commits !== 1 ? 's' : ''}`;
|
||||
}
|
||||
|
||||
// ─── Native memory path encoding ──────────────────────────────────────────────
|
||||
|
||||
export function encodeProjectPath(absolutePath) {
|
||||
// "/Users/sree/dev/app" -> "-Users-sree-dev-app"
|
||||
return absolutePath.replace(/\//g, '-');
|
||||
}
|
||||
|
||||
export function nativeMemoryDir(absolutePath) {
|
||||
const encoded = encodeProjectPath(absolutePath);
|
||||
return resolve(homedir(), '.claude', 'projects', encoded, 'memory');
|
||||
}
|
||||
|
||||
// ─── Rendering ────────────────────────────────────────────────────────────────
|
||||
|
||||
/** Render the human-readable CONTEXT.md from context.json */
|
||||
export function renderContextMd(ctx) {
|
||||
const latest = ctx.sessions?.[ctx.sessions.length - 1] || null;
|
||||
const lines = [
|
||||
`<!-- Generated by ck v2 — edit context.json instead -->`,
|
||||
`# Project: ${ctx.displayName ?? ctx.name}`,
|
||||
`> Path: ${ctx.path}`,
|
||||
];
|
||||
if (ctx.repo) lines.push(`> Repo: ${ctx.repo}`);
|
||||
const sessionCount = ctx.sessions?.length || 0;
|
||||
lines.push(`> Last Session: ${ctx.sessions?.[sessionCount - 1]?.date || 'never'} | Sessions: ${sessionCount}`);
|
||||
lines.push(``);
|
||||
lines.push(`## What This Is`);
|
||||
lines.push(ctx.description || '_Not set._');
|
||||
lines.push(``);
|
||||
lines.push(`## Tech Stack`);
|
||||
lines.push(Array.isArray(ctx.stack) ? ctx.stack.join(', ') : (ctx.stack || '_Not set._'));
|
||||
lines.push(``);
|
||||
lines.push(`## Current Goal`);
|
||||
lines.push(ctx.goal || '_Not set._');
|
||||
lines.push(``);
|
||||
lines.push(`## Where I Left Off`);
|
||||
lines.push(latest?.leftOff || '_Not yet recorded. Run /ck:save after your first session._');
|
||||
lines.push(``);
|
||||
lines.push(`## Next Steps`);
|
||||
if (latest?.nextSteps?.length) {
|
||||
latest.nextSteps.forEach((s, i) => lines.push(`${i + 1}. ${s}`));
|
||||
} else {
|
||||
lines.push(`_Not yet recorded._`);
|
||||
}
|
||||
lines.push(``);
|
||||
lines.push(`## Blockers`);
|
||||
if (latest?.blockers?.length) {
|
||||
latest.blockers.forEach(b => lines.push(`- ${b}`));
|
||||
} else {
|
||||
lines.push(`- None`);
|
||||
}
|
||||
lines.push(``);
|
||||
lines.push(`## Do Not Do`);
|
||||
if (ctx.constraints?.length) {
|
||||
ctx.constraints.forEach(c => lines.push(`- ${c}`));
|
||||
} else {
|
||||
lines.push(`- None specified`);
|
||||
}
|
||||
lines.push(``);
|
||||
|
||||
// All decisions across sessions
|
||||
const allDecisions = (ctx.sessions || []).flatMap(s =>
|
||||
(s.decisions || []).map(d => ({ ...d, date: s.date }))
|
||||
);
|
||||
lines.push(`## Decisions Made`);
|
||||
lines.push(`| Decision | Why | Date |`);
|
||||
lines.push(`|----------|-----|------|`);
|
||||
if (allDecisions.length) {
|
||||
allDecisions.forEach(d => lines.push(`| ${d.what} | ${d.why || ''} | ${d.date || ''} |`));
|
||||
} else {
|
||||
lines.push(`| _(none yet)_ | | |`);
|
||||
}
|
||||
lines.push(``);
|
||||
|
||||
// Session history (most recent first)
|
||||
if (ctx.sessions?.length > 1) {
|
||||
lines.push(`## Session History`);
|
||||
const reversed = [...ctx.sessions].reverse();
|
||||
reversed.forEach(s => {
|
||||
lines.push(`### ${s.date} — ${s.summary || 'Session'}`);
|
||||
if (s.gitActivity) lines.push(`_${s.gitActivity}_`);
|
||||
if (s.leftOff) lines.push(`**Left off:** ${s.leftOff}`);
|
||||
});
|
||||
lines.push(``);
|
||||
}
|
||||
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/** Render the bordered briefing box used by /ck:resume */
|
||||
export function renderBriefingBox(ctx, meta = {}) {
|
||||
const latest = ctx.sessions?.[ctx.sessions.length - 1] || {};
|
||||
const W = 57;
|
||||
const pad = (str, w) => {
|
||||
const s = String(str || '');
|
||||
return s.length > w ? s.slice(0, w - 1) + '…' : s.padEnd(w);
|
||||
};
|
||||
const row = (label, value) => `│ ${label} → ${pad(value, W - label.length - 7)}│`;
|
||||
|
||||
const when = daysAgoLabel(ctx.sessions?.[ctx.sessions.length - 1]?.date);
|
||||
const sessions = ctx.sessions?.length || 0;
|
||||
const shortSessId = latest.id?.slice(0, 8) || null;
|
||||
|
||||
const lines = [
|
||||
`┌${'─'.repeat(W)}┐`,
|
||||
`│ RESUMING: ${pad(ctx.displayName ?? ctx.name, W - 12)}│`,
|
||||
`│ Last session: ${pad(`${when} | Sessions: ${sessions}`, W - 16)}│`,
|
||||
];
|
||||
if (shortSessId) lines.push(`│ Session ID: ${pad(shortSessId, W - 14)}│`);
|
||||
lines.push(`├${'─'.repeat(W)}┤`);
|
||||
lines.push(row('WHAT IT IS', ctx.description || '—'));
|
||||
lines.push(row('STACK ', Array.isArray(ctx.stack) ? ctx.stack.join(', ') : (ctx.stack || '—')));
|
||||
lines.push(row('PATH ', ctx.path));
|
||||
if (ctx.repo) lines.push(row('REPO ', ctx.repo));
|
||||
lines.push(row('GOAL ', ctx.goal || '—'));
|
||||
lines.push(`├${'─'.repeat(W)}┤`);
|
||||
lines.push(`│ WHERE I LEFT OFF${' '.repeat(W - 18)}│`);
|
||||
const leftOffLines = (latest.leftOff || '—').split('\n').filter(Boolean);
|
||||
leftOffLines.forEach(l => lines.push(`│ • ${pad(l, W - 7)}│`));
|
||||
lines.push(`├${'─'.repeat(W)}┤`);
|
||||
lines.push(`│ NEXT STEPS${' '.repeat(W - 12)}│`);
|
||||
const steps = latest.nextSteps || [];
|
||||
if (steps.length) {
|
||||
steps.forEach((s, i) => lines.push(`│ ${i + 1}. ${pad(s, W - 8)}│`));
|
||||
} else {
|
||||
lines.push(`│ —${' '.repeat(W - 5)}│`);
|
||||
}
|
||||
const blockers = latest.blockers?.length ? latest.blockers.join(', ') : 'None';
|
||||
lines.push(`│ BLOCKERS → ${pad(blockers, W - 13)}│`);
|
||||
if (latest.gitActivity) {
|
||||
lines.push(`│ GIT → ${pad(latest.gitActivity, W - 13)}│`);
|
||||
}
|
||||
lines.push(`└${'─'.repeat(W)}┘`);
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/** Render compact info block used by /ck:info */
|
||||
export function renderInfoBlock(ctx) {
|
||||
const latest = ctx.sessions?.[ctx.sessions.length - 1] || {};
|
||||
const sep = '─'.repeat(44);
|
||||
const lines = [
|
||||
`ck: ${ctx.displayName ?? ctx.name}`,
|
||||
sep,
|
||||
];
|
||||
lines.push(`PATH ${ctx.path}`);
|
||||
if (ctx.repo) lines.push(`REPO ${ctx.repo}`);
|
||||
if (latest.id) lines.push(`SESSION ${latest.id.slice(0, 8)}`);
|
||||
lines.push(`GOAL ${ctx.goal || '—'}`);
|
||||
lines.push(sep);
|
||||
lines.push(`WHERE I LEFT OFF`);
|
||||
(latest.leftOff || '—').split('\n').filter(Boolean).forEach(l => lines.push(` • ${l}`));
|
||||
lines.push(`NEXT STEPS`);
|
||||
(latest.nextSteps || []).forEach((s, i) => lines.push(` ${i + 1}. ${s}`));
|
||||
if (!latest.nextSteps?.length) lines.push(` —`);
|
||||
lines.push(`BLOCKERS`);
|
||||
if (latest.blockers?.length) {
|
||||
latest.blockers.forEach(b => lines.push(` • ${b}`));
|
||||
} else {
|
||||
lines.push(` • None`);
|
||||
}
|
||||
return lines.join('\n');
|
||||
}
|
||||
|
||||
/** Render ASCII list table used by /ck:list */
|
||||
export function renderListTable(entries, cwd, todayStr) {
|
||||
// entries: [{name, contextDir, path, context, lastUpdated}]
|
||||
// Sorted alphabetically by contextDir before calling
|
||||
const rows = entries.map((e, i) => {
|
||||
const isHere = e.path === cwd;
|
||||
const latest = e.context?.sessions?.[e.context.sessions.length - 1] || {};
|
||||
const when = daysAgoLabel(latest.date);
|
||||
const icon = stalenessIcon(latest.date);
|
||||
const statusLabel = icon === '●' ? '● Active' : icon === '◐' ? '◐ Warm' : '○ Stale';
|
||||
const sessId = latest.id ? latest.id.slice(0, 8) : '—';
|
||||
const summary = (latest.summary || '—').slice(0, 34);
|
||||
const displayName = ((e.context?.displayName ?? e.name) + (isHere ? ' <-' : '')).slice(0, 18);
|
||||
return {
|
||||
num: String(i + 1),
|
||||
name: displayName,
|
||||
status: statusLabel,
|
||||
when: when.slice(0, 10),
|
||||
sessId,
|
||||
summary,
|
||||
};
|
||||
});
|
||||
|
||||
const cols = {
|
||||
num: Math.max(1, ...rows.map(r => r.num.length)),
|
||||
name: Math.max(7, ...rows.map(r => r.name.length)),
|
||||
status: Math.max(6, ...rows.map(r => r.status.length)),
|
||||
when: Math.max(9, ...rows.map(r => r.when.length)),
|
||||
sessId: Math.max(7, ...rows.map(r => r.sessId.length)),
|
||||
summary: Math.max(12, ...rows.map(r => r.summary.length)),
|
||||
};
|
||||
|
||||
const hr = `+${'-'.repeat(cols.num + 2)}+${'-'.repeat(cols.name + 2)}+${'-'.repeat(cols.status + 2)}+${'-'.repeat(cols.when + 2)}+${'-'.repeat(cols.sessId + 2)}+${'-'.repeat(cols.summary + 2)}+`;
|
||||
const cell = (val, width) => ` ${val.padEnd(width)} `;
|
||||
const headerRow = `|${cell('#', cols.num)}|${cell('Project', cols.name)}|${cell('Status', cols.status)}|${cell('Last Seen', cols.when)}|${cell('Session', cols.sessId)}|${cell('Last Summary', cols.summary)}|`;
|
||||
|
||||
const dataRows = rows.map(r =>
|
||||
`|${cell(r.num, cols.num)}|${cell(r.name, cols.name)}|${cell(r.status, cols.status)}|${cell(r.when, cols.when)}|${cell(r.sessId, cols.sessId)}|${cell(r.summary, cols.summary)}|`
|
||||
);
|
||||
|
||||
return [hr, headerRow, hr, ...dataRows, hr].join('\n');
|
||||
}
|
||||
224
skills/ck/hooks/session-start.mjs
Normal file
224
skills/ck/hooks/session-start.mjs
Normal file
@@ -0,0 +1,224 @@
|
||||
#!/usr/bin/env node
|
||||
/**
|
||||
* ck — Context Keeper v2
|
||||
* session-start.mjs — inject compact project context on session start.
|
||||
*
|
||||
* Injects ~100 tokens (not ~2,500 like v1).
|
||||
* SKILL.md is injected separately (still small at ~50 lines).
|
||||
*
|
||||
* Features:
|
||||
* - Compact 5-line summary for registered projects
|
||||
* - Unsaved session detection → "Last session wasn't saved. Run /ck:save."
|
||||
* - Git activity since last session
|
||||
* - Goal mismatch detection vs CLAUDE.md
|
||||
* - Mini portfolio for unregistered directories
|
||||
*/
|
||||
|
||||
import { readFileSync, writeFileSync, existsSync } from 'fs';
|
||||
import { resolve } from 'path';
|
||||
import { homedir } from 'os';
|
||||
import { spawnSync } from 'child_process';
|
||||
|
||||
const CK_HOME = resolve(homedir(), '.claude', 'ck');
|
||||
const PROJECTS_FILE = resolve(CK_HOME, 'projects.json');
|
||||
const CURRENT_SESSION = resolve(CK_HOME, 'current-session.json');
|
||||
const SKILL_FILE = resolve(homedir(), '.claude', 'skills', 'ck', 'SKILL.md');
|
||||
|
||||
// ─── Helpers ──────────────────────────────────────────────────────────────────
|
||||
|
||||
function readJson(p) {
|
||||
try { return JSON.parse(readFileSync(p, 'utf8')); } catch { return null; }
|
||||
}
|
||||
|
||||
function daysAgo(dateStr) {
|
||||
if (!dateStr) return 'unknown';
|
||||
const diff = Math.floor((Date.now() - new Date(dateStr)) / 86_400_000);
|
||||
if (diff === 0) return 'today';
|
||||
if (diff === 1) return '1 day ago';
|
||||
return `${diff} days ago`;
|
||||
}
|
||||
|
||||
function stalenessIcon(dateStr) {
|
||||
if (!dateStr) return '○';
|
||||
const diff = Math.floor((Date.now() - new Date(dateStr)) / 86_400_000);
|
||||
return diff < 1 ? '●' : diff <= 5 ? '◐' : '○';
|
||||
}
|
||||
|
||||
function gitLogSince(projectPath, sinceDate) {
|
||||
if (!sinceDate || !existsSync(resolve(projectPath, '.git'))) return null;
|
||||
try {
|
||||
const result = spawnSync(
|
||||
'git',
|
||||
['-C', projectPath, 'log', '--oneline', `--since=${sinceDate}`],
|
||||
{ timeout: 3000, stdio: 'pipe', encoding: 'utf8' },
|
||||
);
|
||||
if (result.status !== 0) return null;
|
||||
const output = result.stdout.trim();
|
||||
const commits = output.split('\n').filter(Boolean).length;
|
||||
return commits > 0 ? `${commits} commit${commits !== 1 ? 's' : ''} since last session` : null;
|
||||
} catch { return null; }
|
||||
}
|
||||
|
||||
function extractClaudeMdGoal(projectPath) {
|
||||
const p = resolve(projectPath, 'CLAUDE.md');
|
||||
if (!existsSync(p)) return null;
|
||||
try {
|
||||
const md = readFileSync(p, 'utf8');
|
||||
const m = md.match(/## Current Goal\n([\s\S]*?)(?=\n## |$)/);
|
||||
return m ? m[1].trim().split('\n')[0].trim() : null;
|
||||
} catch { return null; }
|
||||
}
|
||||
|
||||
// ─── Session ID from stdin ────────────────────────────────────────────────────
|
||||
|
||||
function readSessionId() {
|
||||
try {
|
||||
const raw = readFileSync(0, 'utf8');
|
||||
return JSON.parse(raw).session_id || null;
|
||||
} catch { return null; }
|
||||
}
|
||||
|
||||
// ─── Main ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
function main() {
|
||||
const cwd = process.env.PWD || process.cwd();
|
||||
const sessionId = readSessionId();
|
||||
|
||||
// Load skill (always inject — now only ~50 lines)
|
||||
const skill = existsSync(SKILL_FILE) ? readFileSync(SKILL_FILE, 'utf8') : '';
|
||||
|
||||
const projects = readJson(PROJECTS_FILE) || {};
|
||||
const entry = projects[cwd];
|
||||
|
||||
// Read previous session BEFORE overwriting current-session.json
|
||||
const prevSession = readJson(CURRENT_SESSION);
|
||||
|
||||
// Write current-session.json
|
||||
try {
|
||||
writeFileSync(CURRENT_SESSION, JSON.stringify({
|
||||
sessionId,
|
||||
projectPath: cwd,
|
||||
projectName: entry?.name || null,
|
||||
startedAt: new Date().toISOString(),
|
||||
}, null, 2), 'utf8');
|
||||
} catch { /* non-fatal */ }
|
||||
|
||||
const parts = [];
|
||||
if (skill) parts.push(skill);
|
||||
|
||||
// ── REGISTERED PROJECT ────────────────────────────────────────────────────
|
||||
if (entry?.contextDir) {
|
||||
const contextFile = resolve(CK_HOME, 'contexts', entry.contextDir, 'context.json');
|
||||
const context = readJson(contextFile);
|
||||
|
||||
if (context) {
|
||||
const latest = context.sessions?.[context.sessions.length - 1] || {};
|
||||
const sessionDate = latest.date || context.createdAt;
|
||||
const sessionCount = context.sessions?.length || 0;
|
||||
const displayName = context.displayName ?? context.name;
|
||||
|
||||
// ── Compact summary block (~100 tokens) ──────────────────────────────
|
||||
const summaryLines = [
|
||||
`ck: ${displayName} | ${daysAgo(sessionDate)} | ${sessionCount} session${sessionCount !== 1 ? 's' : ''}`,
|
||||
`Goal: ${context.goal || '—'}`,
|
||||
latest.leftOff ? `Left off: ${latest.leftOff.split('\n')[0]}` : null,
|
||||
latest.nextSteps?.length ? `Next: ${latest.nextSteps.slice(0, 2).join(' · ')}` : null,
|
||||
].filter(Boolean);
|
||||
|
||||
// ── Unsaved session detection ─────────────────────────────────────────
|
||||
if (prevSession?.sessionId && prevSession.sessionId !== sessionId) {
|
||||
// Check if previous session ID exists in sessions array
|
||||
const alreadySaved = context.sessions?.some(s => s.id === prevSession.sessionId);
|
||||
if (!alreadySaved) {
|
||||
summaryLines.push(`⚠ Last session wasn't saved — run /ck:save to capture it`);
|
||||
}
|
||||
}
|
||||
|
||||
// ── Git activity ──────────────────────────────────────────────────────
|
||||
const gitLine = gitLogSince(cwd, sessionDate);
|
||||
if (gitLine) summaryLines.push(`Git: ${gitLine}`);
|
||||
|
||||
// ── Goal mismatch detection ───────────────────────────────────────────
|
||||
const claudeMdGoal = extractClaudeMdGoal(cwd);
|
||||
if (claudeMdGoal && context.goal &&
|
||||
claudeMdGoal.toLowerCase().trim() !== context.goal.toLowerCase().trim()) {
|
||||
summaryLines.push(`⚠ Goal mismatch — ck: "${context.goal.slice(0, 40)}" · CLAUDE.md: "${claudeMdGoal.slice(0, 40)}"`);
|
||||
summaryLines.push(` Run /ck:save with updated goal to sync`);
|
||||
}
|
||||
|
||||
parts.push([
|
||||
`---`,
|
||||
`## ck: ${displayName}`,
|
||||
``,
|
||||
summaryLines.join('\n'),
|
||||
].join('\n'));
|
||||
|
||||
// Instruct Claude to display compact briefing at session start
|
||||
parts.push([
|
||||
`---`,
|
||||
`## ck: SESSION START`,
|
||||
``,
|
||||
`IMPORTANT: Display the following as your FIRST message, verbatim:`,
|
||||
``,
|
||||
'```',
|
||||
summaryLines.join('\n'),
|
||||
'```',
|
||||
``,
|
||||
`After the block, add one line: "Ready — what are we working on?"`,
|
||||
`If you see ⚠ warnings above, mention them briefly after the block.`,
|
||||
].join('\n'));
|
||||
|
||||
return parts;
|
||||
}
|
||||
}
|
||||
|
||||
// ── NOT IN A REGISTERED PROJECT ────────────────────────────────────────────
|
||||
const entries = Object.entries(projects);
|
||||
if (entries.length === 0) return parts;
|
||||
|
||||
// Load and sort by most recent
|
||||
const recent = entries
|
||||
.map(([path, info]) => {
|
||||
const ctx = readJson(resolve(CK_HOME, 'contexts', info.contextDir, 'context.json'));
|
||||
const latest = ctx?.sessions?.[ctx.sessions.length - 1] || {};
|
||||
return { name: info.name, path, lastDate: latest.date || '', summary: latest.summary || '—', ctx };
|
||||
})
|
||||
.sort((a, b) => (b.lastDate > a.lastDate ? 1 : -1))
|
||||
.slice(0, 3);
|
||||
|
||||
const miniRows = recent.map(p => {
|
||||
const icon = stalenessIcon(p.lastDate);
|
||||
const when = daysAgo(p.lastDate);
|
||||
const name = p.name.padEnd(16).slice(0, 16);
|
||||
const whenStr = when.padEnd(12).slice(0, 12);
|
||||
const summary = p.summary.slice(0, 32);
|
||||
return ` ${name} ${icon} ${whenStr} ${summary}`;
|
||||
});
|
||||
|
||||
const miniStatus = [
|
||||
`ck — recent projects:`,
|
||||
` ${'PROJECT'.padEnd(16)} S ${'LAST SEEN'.padEnd(12)} LAST SESSION`,
|
||||
` ${'─'.repeat(68)}`,
|
||||
...miniRows,
|
||||
``,
|
||||
`Run /ck:list · /ck:resume <name> · /ck:init to register this folder`,
|
||||
].join('\n');
|
||||
|
||||
parts.push([
|
||||
`---`,
|
||||
`## ck: SESSION START`,
|
||||
``,
|
||||
`IMPORTANT: Display the following as your FIRST message, verbatim:`,
|
||||
``,
|
||||
'```',
|
||||
miniStatus,
|
||||
'```',
|
||||
].join('\n'));
|
||||
|
||||
return parts;
|
||||
}
|
||||
|
||||
const parts = main();
|
||||
if (parts.length > 0) {
|
||||
console.log(JSON.stringify({ additionalContext: parts.join('\n\n---\n\n') }));
|
||||
}
|
||||
@@ -62,9 +62,16 @@ analyze_observations() {
|
||||
analysis_count=$(wc -l < "$analysis_file" 2>/dev/null || echo 0)
|
||||
echo "[$(date)] Using last $analysis_count of $obs_count observations for analysis" >> "$LOG_FILE"
|
||||
|
||||
# Use relative path from PROJECT_DIR for cross-platform compatibility (#842).
|
||||
# On Windows (Git Bash/MSYS2), absolute paths from mktemp may use MSYS-style
|
||||
# prefixes (e.g. /c/Users/...) that the Claude subprocess cannot resolve.
|
||||
analysis_relpath=".observer-tmp/$(basename "$analysis_file")"
|
||||
|
||||
prompt_file="$(mktemp "${observer_tmp_dir}/ecc-observer-prompt.XXXXXX")"
|
||||
cat > "$prompt_file" <<PROMPT
|
||||
Read ${analysis_file} and identify patterns for the project ${PROJECT_NAME} (user corrections, error resolutions, repeated workflows, tool preferences).
|
||||
IMPORTANT: You are running in non-interactive --print mode. You MUST use the Write tool directly to create files. Do NOT ask for permission, do NOT ask for confirmation, do NOT output summaries instead of writing. Just read, analyze, and write.
|
||||
|
||||
Read ${analysis_relpath} and identify patterns for the project ${PROJECT_NAME} (user corrections, error resolutions, repeated workflows, tool preferences).
|
||||
If you find 3+ occurrences of the same pattern, you MUST write an instinct file directly to ${INSTINCTS_DIR}/<id>.md using the Write tool.
|
||||
Do NOT ask for permission to write files, do NOT describe what you would write, and do NOT stop at analysis when a qualifying pattern exists.
|
||||
|
||||
@@ -117,11 +124,19 @@ PROMPT
|
||||
max_turns=10
|
||||
fi
|
||||
|
||||
# Prevent observe.sh from recording this automated Haiku session as observations
|
||||
# Ensure CWD is PROJECT_DIR so the relative analysis_relpath resolves correctly
|
||||
# on all platforms, not just when the observer happens to be launched from the project root.
|
||||
cd "$PROJECT_DIR" || { echo "[$(date)] Failed to cd to PROJECT_DIR ($PROJECT_DIR), skipping analysis" >> "$LOG_FILE"; rm -f "$prompt_file" "$analysis_file"; return; }
|
||||
|
||||
# Prevent observe.sh from recording this automated Haiku session as observations.
|
||||
# Pass prompt via -p flag instead of stdin redirect for Windows compatibility (#842).
|
||||
ECC_SKIP_OBSERVE=1 ECC_HOOK_PROFILE=minimal claude --model haiku --max-turns "$max_turns" --print \
|
||||
--allowedTools "Read,Write" \
|
||||
< "$prompt_file" >> "$LOG_FILE" 2>&1 &
|
||||
-p "$(cat "$prompt_file")" >> "$LOG_FILE" 2>&1 &
|
||||
claude_pid=$!
|
||||
# prompt_file content was already expanded by the shell; remove early to avoid
|
||||
# leaving stale temp files during the (potentially long) analysis window.
|
||||
rm -f "$prompt_file"
|
||||
|
||||
(
|
||||
sleep "$timeout_seconds"
|
||||
@@ -135,7 +150,7 @@ PROMPT
|
||||
wait "$claude_pid"
|
||||
exit_code=$?
|
||||
kill "$watchdog_pid" 2>/dev/null || true
|
||||
rm -f "$prompt_file" "$analysis_file"
|
||||
rm -f "$analysis_file"
|
||||
|
||||
if [ "$exit_code" -ne 0 ]; then
|
||||
echo "[$(date)] Claude analysis failed (exit $exit_code)" >> "$LOG_FILE"
|
||||
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
name: design-system
|
||||
description: Use this skill to generate or audit design systems, check visual consistency, and review PRs that touch styling.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Design System — Generate & Audit Visual Systems
|
||||
|
||||
## When to Use
|
||||
|
||||
716
skills/git-workflow/SKILL.md
Normal file
716
skills/git-workflow/SKILL.md
Normal file
@@ -0,0 +1,716 @@
|
||||
---
|
||||
name: git-workflow
|
||||
description: Git workflow patterns including branching strategies, commit conventions, merge vs rebase, conflict resolution, and collaborative development best practices for teams of all sizes.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Git Workflow Patterns
|
||||
|
||||
Best practices for Git version control, branching strategies, and collaborative development.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- Setting up Git workflow for a new project
|
||||
- Deciding on branching strategy (GitFlow, trunk-based, GitHub flow)
|
||||
- Writing commit messages and PR descriptions
|
||||
- Resolving merge conflicts
|
||||
- Managing releases and version tags
|
||||
- Onboarding new team members to Git practices
|
||||
|
||||
## Branching Strategies
|
||||
|
||||
### GitHub Flow (Simple, Recommended for Most)
|
||||
|
||||
Best for continuous deployment and small-to-medium teams.
|
||||
|
||||
```
|
||||
main (protected, always deployable)
|
||||
│
|
||||
├── feature/user-auth → PR → merge to main
|
||||
├── feature/payment-flow → PR → merge to main
|
||||
└── fix/login-bug → PR → merge to main
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- `main` is always deployable
|
||||
- Create feature branches from `main`
|
||||
- Open Pull Request when ready for review
|
||||
- After approval and CI passes, merge to `main`
|
||||
- Deploy immediately after merge
|
||||
|
||||
### Trunk-Based Development (High-Velocity Teams)
|
||||
|
||||
Best for teams with strong CI/CD and feature flags.
|
||||
|
||||
```
|
||||
main (trunk)
|
||||
│
|
||||
├── short-lived feature (1-2 days max)
|
||||
├── short-lived feature
|
||||
└── short-lived feature
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Everyone commits to `main` or very short-lived branches
|
||||
- Feature flags hide incomplete work
|
||||
- CI must pass before merge
|
||||
- Deploy multiple times per day
|
||||
|
||||
### GitFlow (Complex, Release-Cycle Driven)
|
||||
|
||||
Best for scheduled releases and enterprise projects.
|
||||
|
||||
```
|
||||
main (production releases)
|
||||
│
|
||||
└── develop (integration branch)
|
||||
│
|
||||
├── feature/user-auth
|
||||
├── feature/payment
|
||||
│
|
||||
├── release/1.0.0 → merge to main and develop
|
||||
│
|
||||
└── hotfix/critical → merge to main and develop
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- `main` contains production-ready code only
|
||||
- `develop` is the integration branch
|
||||
- Feature branches from `develop`, merge back to `develop`
|
||||
- Release branches from `develop`, merge to `main` and `develop`
|
||||
- Hotfix branches from `main`, merge to both `main` and `develop`
|
||||
|
||||
### When to Use Which
|
||||
|
||||
| Strategy | Team Size | Release Cadence | Best For |
|
||||
|----------|-----------|-----------------|----------|
|
||||
| GitHub Flow | Any | Continuous | SaaS, web apps, startups |
|
||||
| Trunk-Based | 5+ experienced | Multiple/day | High-velocity teams, feature flags |
|
||||
| GitFlow | 10+ | Scheduled | Enterprise, regulated industries |
|
||||
|
||||
## Commit Messages
|
||||
|
||||
### Conventional Commits Format
|
||||
|
||||
```
|
||||
<type>(<scope>): <subject>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
### Types
|
||||
|
||||
| Type | Use For | Example |
|
||||
|------|---------|---------|
|
||||
| `feat` | New feature | `feat(auth): add OAuth2 login` |
|
||||
| `fix` | Bug fix | `fix(api): handle null response in user endpoint` |
|
||||
| `docs` | Documentation | `docs(readme): update installation instructions` |
|
||||
| `style` | Formatting, no code change | `style: fix indentation in login component` |
|
||||
| `refactor` | Code refactoring | `refactor(db): extract connection pool to module` |
|
||||
| `test` | Adding/updating tests | `test(auth): add unit tests for token validation` |
|
||||
| `chore` | Maintenance tasks | `chore(deps): update dependencies` |
|
||||
| `perf` | Performance improvement | `perf(query): add index to users table` |
|
||||
| `ci` | CI/CD changes | `ci: add PostgreSQL service to test workflow` |
|
||||
| `revert` | Revert previous commit | `revert: revert "feat(auth): add OAuth2 login"` |
|
||||
|
||||
### Good vs Bad Examples
|
||||
|
||||
```
|
||||
# BAD: Vague, no context
|
||||
git commit -m "fixed stuff"
|
||||
git commit -m "updates"
|
||||
git commit -m "WIP"
|
||||
|
||||
# GOOD: Clear, specific, explains why
|
||||
git commit -m "fix(api): retry requests on 503 Service Unavailable
|
||||
|
||||
The external API occasionally returns 503 errors during peak hours.
|
||||
Added exponential backoff retry logic with max 3 attempts.
|
||||
|
||||
Closes #123"
|
||||
```
|
||||
|
||||
### Commit Message Template
|
||||
|
||||
Create `.gitmessage` in repo root:
|
||||
|
||||
```
|
||||
# <type>(<scope>): <subject>
|
||||
#
|
||||
# Types: feat, fix, docs, style, refactor, test, chore, perf, ci, revert
|
||||
# Scope: api, ui, db, auth, etc.
|
||||
# Subject: imperative mood, no period, max 50 chars
|
||||
#
|
||||
# [optional body] - explain why, not what
|
||||
# [optional footer] - Breaking changes, closes #issue
|
||||
```
|
||||
|
||||
Enable with: `git config commit.template .gitmessage`
|
||||
|
||||
## Merge vs Rebase
|
||||
|
||||
### Merge (Preserves History)
|
||||
|
||||
```bash
|
||||
# Creates a merge commit
|
||||
git checkout main
|
||||
git merge feature/user-auth
|
||||
|
||||
# Result:
|
||||
# * merge commit
|
||||
# |\
|
||||
# | * feature commits
|
||||
# |/
|
||||
# * main commits
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Merging feature branches into `main`
|
||||
- You want to preserve exact history
|
||||
- Multiple people worked on the branch
|
||||
- The branch has been pushed and others may have based work on it
|
||||
|
||||
### Rebase (Linear History)
|
||||
|
||||
```bash
|
||||
# Rewrites feature commits onto target branch
|
||||
git checkout feature/user-auth
|
||||
git rebase main
|
||||
|
||||
# Result:
|
||||
# * feature commits (rewritten)
|
||||
# * main commits
|
||||
```
|
||||
|
||||
**Use when:**
|
||||
- Updating your local feature branch with latest `main`
|
||||
- You want a linear, clean history
|
||||
- The branch is local-only (not pushed)
|
||||
- You're the only one working on the branch
|
||||
|
||||
### Rebase Workflow
|
||||
|
||||
```bash
|
||||
# Update feature branch with latest main (before PR)
|
||||
git checkout feature/user-auth
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
|
||||
# Fix any conflicts
|
||||
# Tests should still pass
|
||||
|
||||
# Force push (only if you're the only contributor)
|
||||
git push --force-with-lease origin feature/user-auth
|
||||
```
|
||||
|
||||
### When NOT to Rebase
|
||||
|
||||
```
|
||||
# NEVER rebase branches that:
|
||||
- Have been pushed to a shared repository
|
||||
- Other people have based work on
|
||||
- Are protected branches (main, develop)
|
||||
- Are already merged
|
||||
|
||||
# Why: Rebase rewrites history, breaking others' work
|
||||
```
|
||||
|
||||
## Pull Request Workflow
|
||||
|
||||
### PR Title Format
|
||||
|
||||
```
|
||||
<type>(<scope>): <description>
|
||||
|
||||
Examples:
|
||||
feat(auth): add SSO support for enterprise users
|
||||
fix(api): resolve race condition in order processing
|
||||
docs(api): add OpenAPI specification for v2 endpoints
|
||||
```
|
||||
|
||||
### PR Description Template
|
||||
|
||||
```markdown
|
||||
## What
|
||||
|
||||
Brief description of what this PR does.
|
||||
|
||||
## Why
|
||||
|
||||
Explain the motivation and context.
|
||||
|
||||
## How
|
||||
|
||||
Key implementation details worth highlighting.
|
||||
|
||||
## Testing
|
||||
|
||||
- [ ] Unit tests added/updated
|
||||
- [ ] Integration tests added/updated
|
||||
- [ ] Manual testing performed
|
||||
|
||||
## Screenshots (if applicable)
|
||||
|
||||
Before/after screenshots for UI changes.
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] Code follows project style guidelines
|
||||
- [ ] Self-review completed
|
||||
- [ ] Comments added for complex logic
|
||||
- [ ] Documentation updated
|
||||
- [ ] No new warnings introduced
|
||||
- [ ] Tests pass locally
|
||||
- [ ] Related issues linked
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
### Code Review Checklist
|
||||
|
||||
**For Reviewers:**
|
||||
|
||||
- [ ] Does the code solve the stated problem?
|
||||
- [ ] Are there any edge cases not handled?
|
||||
- [ ] Is the code readable and maintainable?
|
||||
- [ ] Are there sufficient tests?
|
||||
- [ ] Are there security concerns?
|
||||
- [ ] Is the commit history clean (squashed if needed)?
|
||||
|
||||
**For Authors:**
|
||||
|
||||
- [ ] Self-review completed before requesting review
|
||||
- [ ] CI passes (tests, lint, typecheck)
|
||||
- [ ] PR size is reasonable (<500 lines ideal)
|
||||
- [ ] Related to a single feature/fix
|
||||
- [ ] Description clearly explains the change
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
### Identify Conflicts
|
||||
|
||||
```bash
|
||||
# Check for conflicts before merge
|
||||
git checkout main
|
||||
git merge feature/user-auth --no-commit --no-ff
|
||||
|
||||
# If conflicts, Git will show:
|
||||
# CONFLICT (content): Merge conflict in src/auth/login.ts
|
||||
# Automatic merge failed; fix conflicts and then commit the result.
|
||||
```
|
||||
|
||||
### Resolve Conflicts
|
||||
|
||||
```bash
|
||||
# See conflicted files
|
||||
git status
|
||||
|
||||
# View conflict markers in file
|
||||
# <<<<<<< HEAD
|
||||
# content from main
|
||||
# =======
|
||||
# content from feature branch
|
||||
# >>>>>>> feature/user-auth
|
||||
|
||||
# Option 1: Manual resolution
|
||||
# Edit file, remove markers, keep correct content
|
||||
|
||||
# Option 2: Use merge tool
|
||||
git mergetool
|
||||
|
||||
# Option 3: Accept one side
|
||||
git checkout --ours src/auth/login.ts # Keep main version
|
||||
git checkout --theirs src/auth/login.ts # Keep feature version
|
||||
|
||||
# After resolving, stage and commit
|
||||
git add src/auth/login.ts
|
||||
git commit
|
||||
```
|
||||
|
||||
### Conflict Prevention Strategies
|
||||
|
||||
```bash
|
||||
# 1. Keep feature branches small and short-lived
|
||||
# 2. Rebase frequently onto main
|
||||
git checkout feature/user-auth
|
||||
git fetch origin
|
||||
git rebase origin/main
|
||||
|
||||
# 3. Communicate with team about touching shared files
|
||||
# 4. Use feature flags instead of long-lived branches
|
||||
# 5. Review and merge PRs promptly
|
||||
```
|
||||
|
||||
## Branch Management
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
```
|
||||
# Feature branches
|
||||
feature/user-authentication
|
||||
feature/JIRA-123-payment-integration
|
||||
|
||||
# Bug fixes
|
||||
fix/login-redirect-loop
|
||||
fix/456-null-pointer-exception
|
||||
|
||||
# Hotfixes (production issues)
|
||||
hotfix/critical-security-patch
|
||||
hotfix/database-connection-leak
|
||||
|
||||
# Releases
|
||||
release/1.2.0
|
||||
release/2024-01-hotfix
|
||||
|
||||
# Experiments/POCs
|
||||
experiment/new-caching-strategy
|
||||
poc/graphql-migration
|
||||
```
|
||||
|
||||
### Branch Cleanup
|
||||
|
||||
```bash
|
||||
# Delete local branches that are merged
|
||||
git branch --merged main | grep -v "^\*\|main" | xargs -n 1 git branch -d
|
||||
|
||||
# Delete remote-tracking references for deleted remote branches
|
||||
git fetch -p
|
||||
|
||||
# Delete local branch
|
||||
git branch -d feature/user-auth # Safe delete (only if merged)
|
||||
git branch -D feature/user-auth # Force delete
|
||||
|
||||
# Delete remote branch
|
||||
git push origin --delete feature/user-auth
|
||||
```
|
||||
|
||||
### Stash Workflow
|
||||
|
||||
```bash
|
||||
# Save work in progress
|
||||
git stash push -m "WIP: user authentication"
|
||||
|
||||
# List stashes
|
||||
git stash list
|
||||
|
||||
# Apply most recent stash
|
||||
git stash pop
|
||||
|
||||
# Apply specific stash
|
||||
git stash apply stash@{2}
|
||||
|
||||
# Drop stash
|
||||
git stash drop stash@{0}
|
||||
```
|
||||
|
||||
## Release Management
|
||||
|
||||
### Semantic Versioning
|
||||
|
||||
```
|
||||
MAJOR.MINOR.PATCH
|
||||
|
||||
MAJOR: Breaking changes
|
||||
MINOR: New features, backward compatible
|
||||
PATCH: Bug fixes, backward compatible
|
||||
|
||||
Examples:
|
||||
1.0.0 → 1.0.1 (patch: bug fix)
|
||||
1.0.1 → 1.1.0 (minor: new feature)
|
||||
1.1.0 → 2.0.0 (major: breaking change)
|
||||
```
|
||||
|
||||
### Creating Releases
|
||||
|
||||
```bash
|
||||
# Create annotated tag
|
||||
git tag -a v1.2.0 -m "Release v1.2.0
|
||||
|
||||
Features:
|
||||
- Add user authentication
|
||||
- Implement password reset
|
||||
|
||||
Fixes:
|
||||
- Resolve login redirect issue
|
||||
|
||||
Breaking Changes:
|
||||
- None"
|
||||
|
||||
# Push tag to remote
|
||||
git push origin v1.2.0
|
||||
|
||||
# List tags
|
||||
git tag -l
|
||||
|
||||
# Delete tag
|
||||
git tag -d v1.2.0
|
||||
git push origin --delete v1.2.0
|
||||
```
|
||||
|
||||
### Changelog Generation
|
||||
|
||||
```bash
|
||||
# Generate changelog from commits
|
||||
git log v1.1.0..v1.2.0 --oneline --no-merges
|
||||
|
||||
# Or use conventional-changelog
|
||||
npx conventional-changelog -i CHANGELOG.md -s
|
||||
```
|
||||
|
||||
## Git Configuration
|
||||
|
||||
### Essential Configs
|
||||
|
||||
```bash
|
||||
# User identity
|
||||
git config --global user.name "Your Name"
|
||||
git config --global user.email "your@email.com"
|
||||
|
||||
# Default branch name
|
||||
git config --global init.defaultBranch main
|
||||
|
||||
# Pull behavior (rebase instead of merge)
|
||||
git config --global pull.rebase true
|
||||
|
||||
# Push behavior (push current branch only)
|
||||
git config --global push.default current
|
||||
|
||||
# Auto-correct typos
|
||||
git config --global help.autocorrect 1
|
||||
|
||||
# Better diff algorithm
|
||||
git config --global diff.algorithm histogram
|
||||
|
||||
# Color output
|
||||
git config --global color.ui auto
|
||||
```
|
||||
|
||||
### Useful Aliases
|
||||
|
||||
```bash
|
||||
# Add to ~/.gitconfig
|
||||
[alias]
|
||||
co = checkout
|
||||
br = branch
|
||||
ci = commit
|
||||
st = status
|
||||
unstage = reset HEAD --
|
||||
last = log -1 HEAD
|
||||
visual = log --oneline --graph --all
|
||||
amend = commit --amend --no-edit
|
||||
wip = commit -m "WIP"
|
||||
undo = reset --soft HEAD~1
|
||||
contributors = shortlog -sn
|
||||
```
|
||||
|
||||
### Gitignore Patterns
|
||||
|
||||
```gitignore
|
||||
# Dependencies
|
||||
node_modules/
|
||||
vendor/
|
||||
|
||||
# Build outputs
|
||||
dist/
|
||||
build/
|
||||
*.o
|
||||
*.exe
|
||||
|
||||
# Environment files
|
||||
.env
|
||||
.env.local
|
||||
.env.*.local
|
||||
|
||||
# IDE
|
||||
.idea/
|
||||
.vscode/
|
||||
*.swp
|
||||
*.swo
|
||||
|
||||
# OS files
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
logs/
|
||||
|
||||
# Test coverage
|
||||
coverage/
|
||||
|
||||
# Cache
|
||||
.cache/
|
||||
*.tsbuildinfo
|
||||
```
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Starting a New Feature
|
||||
|
||||
```bash
|
||||
# 1. Update main branch
|
||||
git checkout main
|
||||
git pull origin main
|
||||
|
||||
# 2. Create feature branch
|
||||
git checkout -b feature/user-auth
|
||||
|
||||
# 3. Make changes and commit
|
||||
git add .
|
||||
git commit -m "feat(auth): implement OAuth2 login"
|
||||
|
||||
# 4. Push to remote
|
||||
git push -u origin feature/user-auth
|
||||
|
||||
# 5. Create Pull Request on GitHub/GitLab
|
||||
```
|
||||
|
||||
### Updating a PR with New Changes
|
||||
|
||||
```bash
|
||||
# 1. Make additional changes
|
||||
git add .
|
||||
git commit -m "feat(auth): add error handling"
|
||||
|
||||
# 2. Push updates
|
||||
git push origin feature/user-auth
|
||||
```
|
||||
|
||||
### Syncing Fork with Upstream
|
||||
|
||||
```bash
|
||||
# 1. Add upstream remote (once)
|
||||
git remote add upstream https://github.com/original/repo.git
|
||||
|
||||
# 2. Fetch upstream
|
||||
git fetch upstream
|
||||
|
||||
# 3. Merge upstream/main into your main
|
||||
git checkout main
|
||||
git merge upstream/main
|
||||
|
||||
# 4. Push to your fork
|
||||
git push origin main
|
||||
```
|
||||
|
||||
### Undoing Mistakes
|
||||
|
||||
```bash
|
||||
# Undo last commit (keep changes)
|
||||
git reset --soft HEAD~1
|
||||
|
||||
# Undo last commit (discard changes)
|
||||
git reset --hard HEAD~1
|
||||
|
||||
# Undo last commit pushed to remote
|
||||
git revert HEAD
|
||||
git push origin main
|
||||
|
||||
# Undo specific file changes
|
||||
git checkout HEAD -- path/to/file
|
||||
|
||||
# Fix last commit message
|
||||
git commit --amend -m "New message"
|
||||
|
||||
# Add forgotten file to last commit
|
||||
git add forgotten-file
|
||||
git commit --amend --no-edit
|
||||
```
|
||||
|
||||
## Git Hooks
|
||||
|
||||
### Pre-Commit Hook
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-commit
|
||||
|
||||
# Run linting
|
||||
npm run lint || exit 1
|
||||
|
||||
# Run tests
|
||||
npm test || exit 1
|
||||
|
||||
# Check for secrets
|
||||
if git diff --cached | grep -E '(password|api_key|secret)'; then
|
||||
echo "Possible secret detected. Commit aborted."
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### Pre-Push Hook
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# .git/hooks/pre-push
|
||||
|
||||
# Run full test suite
|
||||
npm run test:all || exit 1
|
||||
|
||||
# Check for console.log statements
|
||||
if git diff origin/main | grep -E 'console\.log'; then
|
||||
echo "Remove console.log statements before pushing."
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
```
|
||||
# BAD: Committing directly to main
|
||||
git checkout main
|
||||
git commit -m "fix bug"
|
||||
|
||||
# GOOD: Use feature branches and PRs
|
||||
|
||||
# BAD: Committing secrets
|
||||
git add .env # Contains API keys
|
||||
|
||||
# GOOD: Add to .gitignore, use environment variables
|
||||
|
||||
# BAD: Giant PRs (1000+ lines)
|
||||
# GOOD: Break into smaller, focused PRs
|
||||
|
||||
# BAD: "Update" commit messages
|
||||
git commit -m "update"
|
||||
git commit -m "fix"
|
||||
|
||||
# GOOD: Descriptive messages
|
||||
git commit -m "fix(auth): resolve redirect loop after login"
|
||||
|
||||
# BAD: Rewriting public history
|
||||
git push --force origin main
|
||||
|
||||
# GOOD: Use revert for public branches
|
||||
git revert HEAD
|
||||
|
||||
# BAD: Long-lived feature branches (weeks/months)
|
||||
# GOOD: Keep branches short (days), rebase frequently
|
||||
|
||||
# BAD: Committing generated files
|
||||
git add dist/
|
||||
git add node_modules/
|
||||
|
||||
# GOOD: Add to .gitignore
|
||||
```
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Task | Command |
|
||||
|------|---------|
|
||||
| Create branch | `git checkout -b feature/name` |
|
||||
| Switch branch | `git checkout branch-name` |
|
||||
| Delete branch | `git branch -d branch-name` |
|
||||
| Merge branch | `git merge branch-name` |
|
||||
| Rebase branch | `git rebase main` |
|
||||
| View history | `git log --oneline --graph` |
|
||||
| View changes | `git diff` |
|
||||
| Stage changes | `git add .` or `git add -p` |
|
||||
| Commit | `git commit -m "message"` |
|
||||
| Push | `git push origin branch-name` |
|
||||
| Pull | `git pull origin branch-name` |
|
||||
| Stash | `git stash push -m "message"` |
|
||||
| Undo last commit | `git reset --soft HEAD~1` |
|
||||
| Revert commit | `git revert HEAD` |
|
||||
245
skills/healthcare-cdss-patterns/SKILL.md
Normal file
245
skills/healthcare-cdss-patterns/SKILL.md
Normal file
@@ -0,0 +1,245 @@
|
||||
---
|
||||
name: healthcare-cdss-patterns
|
||||
description: Clinical Decision Support System (CDSS) development patterns. Drug interaction checking, dose validation, clinical scoring (NEWS2, qSOFA), alert severity classification, and integration into EMR workflows.
|
||||
origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Healthcare CDSS Development Patterns
|
||||
|
||||
Patterns for building Clinical Decision Support Systems that integrate into EMR workflows. CDSS modules are patient safety critical — zero tolerance for false negatives.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Implementing drug interaction checking
|
||||
- Building dose validation engines
|
||||
- Implementing clinical scoring systems (NEWS2, qSOFA, APACHE, GCS)
|
||||
- Designing alert systems for abnormal clinical values
|
||||
- Building medication order entry with safety checks
|
||||
- Integrating lab result interpretation with clinical context
|
||||
|
||||
## How It Works
|
||||
|
||||
The CDSS engine is a **pure function library with zero side effects**. Input clinical data, output alerts. This makes it fully testable.
|
||||
|
||||
Three primary modules:
|
||||
|
||||
1. **`checkInteractions(newDrug, currentMeds, allergies)`** — Checks a new drug against current medications and known allergies. Returns severity-sorted `InteractionAlert[]`. Uses `DrugInteractionPair` data model.
|
||||
2. **`validateDose(drug, dose, route, weight, age, renalFunction)`** — Validates a prescribed dose against weight-based, age-adjusted, and renal-adjusted rules. Returns `DoseValidationResult`.
|
||||
3. **`calculateNEWS2(vitals)`** — National Early Warning Score 2 from `NEWS2Input`. Returns `NEWS2Result` with total score, risk level, and escalation guidance.
|
||||
|
||||
```
|
||||
EMR UI
|
||||
↓ (user enters data)
|
||||
CDSS Engine (pure functions, no side effects)
|
||||
├── Drug Interaction Checker
|
||||
├── Dose Validator
|
||||
├── Clinical Scoring (NEWS2, qSOFA, etc.)
|
||||
└── Alert Classifier
|
||||
↓ (returns alerts)
|
||||
EMR UI (displays alerts inline, blocks if critical)
|
||||
```
|
||||
|
||||
### Drug Interaction Checking
|
||||
|
||||
```typescript
|
||||
interface DrugInteractionPair {
|
||||
drugA: string; // generic name
|
||||
drugB: string; // generic name
|
||||
severity: 'critical' | 'major' | 'minor';
|
||||
mechanism: string;
|
||||
clinicalEffect: string;
|
||||
recommendation: string;
|
||||
}
|
||||
|
||||
function checkInteractions(
|
||||
newDrug: string,
|
||||
currentMedications: string[],
|
||||
allergyList: string[]
|
||||
): InteractionAlert[] {
|
||||
if (!newDrug) return [];
|
||||
const alerts: InteractionAlert[] = [];
|
||||
for (const current of currentMedications) {
|
||||
const interaction = findInteraction(newDrug, current);
|
||||
if (interaction) {
|
||||
alerts.push({ severity: interaction.severity, pair: [newDrug, current],
|
||||
message: interaction.clinicalEffect, recommendation: interaction.recommendation });
|
||||
}
|
||||
}
|
||||
for (const allergy of allergyList) {
|
||||
if (isCrossReactive(newDrug, allergy)) {
|
||||
alerts.push({ severity: 'critical', pair: [newDrug, allergy],
|
||||
message: `Cross-reactivity with documented allergy: ${allergy}`,
|
||||
recommendation: 'Do not prescribe without allergy consultation' });
|
||||
}
|
||||
}
|
||||
return alerts.sort((a, b) => severityOrder(a.severity) - severityOrder(b.severity));
|
||||
}
|
||||
```
|
||||
|
||||
Interaction pairs must be **bidirectional**: if Drug A interacts with Drug B, then Drug B interacts with Drug A.
|
||||
|
||||
### Dose Validation
|
||||
|
||||
```typescript
|
||||
interface DoseValidationResult {
|
||||
valid: boolean;
|
||||
message: string;
|
||||
suggestedRange: { min: number; max: number; unit: string } | null;
|
||||
factors: string[];
|
||||
}
|
||||
|
||||
function validateDose(
|
||||
drug: string,
|
||||
dose: number,
|
||||
route: 'oral' | 'iv' | 'im' | 'sc' | 'topical',
|
||||
patientWeight?: number,
|
||||
patientAge?: number,
|
||||
renalFunction?: number
|
||||
): DoseValidationResult {
|
||||
const rules = getDoseRules(drug, route);
|
||||
if (!rules) return { valid: true, message: 'No validation rules available', suggestedRange: null, factors: [] };
|
||||
const factors: string[] = [];
|
||||
|
||||
// SAFETY: if rules require weight but weight missing, BLOCK (not pass)
|
||||
if (rules.weightBased) {
|
||||
if (!patientWeight || patientWeight <= 0) {
|
||||
return { valid: false, message: `Weight required for ${drug} (mg/kg drug)`,
|
||||
suggestedRange: null, factors: ['weight_missing'] };
|
||||
}
|
||||
factors.push('weight');
|
||||
const maxDose = rules.maxPerKg * patientWeight;
|
||||
if (dose > maxDose) {
|
||||
return { valid: false, message: `Dose exceeds max for ${patientWeight}kg`,
|
||||
suggestedRange: { min: rules.minPerKg * patientWeight, max: maxDose, unit: rules.unit }, factors };
|
||||
}
|
||||
}
|
||||
|
||||
// Age-based adjustment (when rules define age brackets and age is provided)
|
||||
if (rules.ageAdjusted && patientAge !== undefined) {
|
||||
factors.push('age');
|
||||
const ageMax = rules.getAgeAdjustedMax(patientAge);
|
||||
if (dose > ageMax) {
|
||||
return { valid: false, message: `Exceeds age-adjusted max for ${patientAge}yr`,
|
||||
suggestedRange: { min: rules.typicalMin, max: ageMax, unit: rules.unit }, factors };
|
||||
}
|
||||
}
|
||||
|
||||
// Renal adjustment (when rules define eGFR brackets and eGFR is provided)
|
||||
if (rules.renalAdjusted && renalFunction !== undefined) {
|
||||
factors.push('renal');
|
||||
const renalMax = rules.getRenalAdjustedMax(renalFunction);
|
||||
if (dose > renalMax) {
|
||||
return { valid: false, message: `Exceeds renal-adjusted max for eGFR ${renalFunction}`,
|
||||
suggestedRange: { min: rules.typicalMin, max: renalMax, unit: rules.unit }, factors };
|
||||
}
|
||||
}
|
||||
|
||||
// Absolute max
|
||||
if (dose > rules.absoluteMax) {
|
||||
return { valid: false, message: `Exceeds absolute max ${rules.absoluteMax}${rules.unit}`,
|
||||
suggestedRange: { min: rules.typicalMin, max: rules.absoluteMax, unit: rules.unit },
|
||||
factors: [...factors, 'absolute_max'] };
|
||||
}
|
||||
return { valid: true, message: 'Within range',
|
||||
suggestedRange: { min: rules.typicalMin, max: rules.typicalMax, unit: rules.unit }, factors };
|
||||
}
|
||||
```
|
||||
|
||||
### Clinical Scoring: NEWS2
|
||||
|
||||
```typescript
|
||||
interface NEWS2Input {
|
||||
respiratoryRate: number; oxygenSaturation: number; supplementalOxygen: boolean;
|
||||
temperature: number; systolicBP: number; heartRate: number;
|
||||
consciousness: 'alert' | 'voice' | 'pain' | 'unresponsive';
|
||||
}
|
||||
interface NEWS2Result {
|
||||
total: number; // 0-20
|
||||
risk: 'low' | 'low-medium' | 'medium' | 'high';
|
||||
components: Record<string, number>;
|
||||
escalation: string;
|
||||
}
|
||||
```
|
||||
|
||||
Scoring tables must match the Royal College of Physicians specification exactly.
|
||||
|
||||
### Alert Severity and UI Behavior
|
||||
|
||||
| Severity | UI Behavior | Clinician Action Required |
|
||||
|----------|-------------|--------------------------|
|
||||
| Critical | Block action. Non-dismissable modal. Red. | Must document override reason to proceed |
|
||||
| Major | Warning banner inline. Orange. | Must acknowledge before proceeding |
|
||||
| Minor | Info note inline. Yellow. | Awareness only, no action required |
|
||||
|
||||
Critical alerts must NEVER be auto-dismissed or implemented as toast notifications. Override reasons must be stored in the audit trail.
|
||||
|
||||
### Testing CDSS (Zero Tolerance for False Negatives)
|
||||
|
||||
```typescript
|
||||
describe('CDSS — Patient Safety', () => {
|
||||
INTERACTION_PAIRS.forEach(({ drugA, drugB, severity }) => {
|
||||
it(`detects ${drugA} + ${drugB} (${severity})`, () => {
|
||||
const alerts = checkInteractions(drugA, [drugB], []);
|
||||
expect(alerts.length).toBeGreaterThan(0);
|
||||
expect(alerts[0].severity).toBe(severity);
|
||||
});
|
||||
it(`detects ${drugB} + ${drugA} (reverse)`, () => {
|
||||
const alerts = checkInteractions(drugB, [drugA], []);
|
||||
expect(alerts.length).toBeGreaterThan(0);
|
||||
});
|
||||
});
|
||||
it('blocks mg/kg drug when weight is missing', () => {
|
||||
const result = validateDose('gentamicin', 300, 'iv');
|
||||
expect(result.valid).toBe(false);
|
||||
expect(result.factors).toContain('weight_missing');
|
||||
});
|
||||
it('handles malformed drug data gracefully', () => {
|
||||
expect(() => checkInteractions('', [], [])).not.toThrow();
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
Pass criteria: 100%. A single missed interaction is a patient safety event.
|
||||
|
||||
### Anti-Patterns
|
||||
|
||||
- Making CDSS checks optional or skippable without documented reason
|
||||
- Implementing interaction checks as toast notifications
|
||||
- Using `any` types for drug or clinical data
|
||||
- Hardcoding interaction pairs instead of using a maintainable data structure
|
||||
- Silently catching errors in CDSS engine (must surface failures loudly)
|
||||
- Skipping weight-based validation when weight is not available (must block, not pass)
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Drug Interaction Check
|
||||
|
||||
```typescript
|
||||
const alerts = checkInteractions('warfarin', ['aspirin', 'metformin'], ['penicillin']);
|
||||
// [{ severity: 'critical', pair: ['warfarin', 'aspirin'],
|
||||
// message: 'Increased bleeding risk', recommendation: 'Avoid combination' }]
|
||||
```
|
||||
|
||||
### Example 2: Dose Validation
|
||||
|
||||
```typescript
|
||||
const ok = validateDose('paracetamol', 1000, 'oral', 70, 45);
|
||||
// { valid: true, suggestedRange: { min: 500, max: 4000, unit: 'mg' } }
|
||||
|
||||
const bad = validateDose('paracetamol', 5000, 'oral', 70, 45);
|
||||
// { valid: false, message: 'Exceeds absolute max 4000mg' }
|
||||
|
||||
const noWeight = validateDose('gentamicin', 300, 'iv');
|
||||
// { valid: false, factors: ['weight_missing'] }
|
||||
```
|
||||
|
||||
### Example 3: NEWS2 Scoring
|
||||
|
||||
```typescript
|
||||
const result = calculateNEWS2({
|
||||
respiratoryRate: 24, oxygenSaturation: 93, supplementalOxygen: true,
|
||||
temperature: 38.5, systolicBP: 100, heartRate: 110, consciousness: 'voice'
|
||||
});
|
||||
// { total: 13, risk: 'high', escalation: 'Urgent clinical review. Consider ICU.' }
|
||||
```
|
||||
159
skills/healthcare-emr-patterns/SKILL.md
Normal file
159
skills/healthcare-emr-patterns/SKILL.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
name: healthcare-emr-patterns
|
||||
description: EMR/EHR development patterns for healthcare applications. Clinical safety, encounter workflows, prescription generation, clinical decision support integration, and accessibility-first UI for medical data entry.
|
||||
origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Healthcare EMR Development Patterns
|
||||
|
||||
Patterns for building Electronic Medical Record (EMR) and Electronic Health Record (EHR) systems. Prioritizes patient safety, clinical accuracy, and practitioner efficiency.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Building patient encounter workflows (complaint, exam, diagnosis, prescription)
|
||||
- Implementing clinical note-taking (structured + free text + voice-to-text)
|
||||
- Designing prescription/medication modules with drug interaction checking
|
||||
- Integrating Clinical Decision Support Systems (CDSS)
|
||||
- Building lab result displays with reference range highlighting
|
||||
- Implementing audit trails for clinical data
|
||||
- Designing healthcare-accessible UIs for clinical data entry
|
||||
|
||||
## How It Works
|
||||
|
||||
### Patient Safety First
|
||||
|
||||
Every design decision must be evaluated against: "Could this harm a patient?"
|
||||
|
||||
- Drug interactions MUST alert, not silently pass
|
||||
- Abnormal lab values MUST be visually flagged
|
||||
- Critical vitals MUST trigger escalation workflows
|
||||
- No clinical data modification without audit trail
|
||||
|
||||
### Single-Page Encounter Flow
|
||||
|
||||
Clinical encounters should flow vertically on a single page — no tab switching:
|
||||
|
||||
```
|
||||
Patient Header (sticky — always visible)
|
||||
├── Demographics, allergies, active medications
|
||||
│
|
||||
Encounter Flow (vertical scroll)
|
||||
├── 1. Chief Complaint (structured templates + free text)
|
||||
├── 2. History of Present Illness
|
||||
├── 3. Physical Examination (system-wise)
|
||||
├── 4. Vitals (auto-trigger clinical scoring)
|
||||
├── 5. Diagnosis (ICD-10/SNOMED search)
|
||||
├── 6. Medications (drug DB + interaction check)
|
||||
├── 7. Investigations (lab/radiology orders)
|
||||
├── 8. Plan & Follow-up
|
||||
└── 9. Sign / Lock / Print
|
||||
```
|
||||
|
||||
### Smart Template System
|
||||
|
||||
```typescript
|
||||
interface ClinicalTemplate {
|
||||
id: string;
|
||||
name: string; // e.g., "Chest Pain"
|
||||
chips: string[]; // clickable symptom chips
|
||||
requiredFields: string[]; // mandatory data points
|
||||
redFlags: string[]; // triggers non-dismissable alert
|
||||
icdSuggestions: string[]; // pre-mapped diagnosis codes
|
||||
}
|
||||
```
|
||||
|
||||
Red flags in any template must trigger a visible, non-dismissable alert — NOT a toast notification.
|
||||
|
||||
### Medication Safety Pattern
|
||||
|
||||
```
|
||||
User selects drug
|
||||
→ Check current medications for interactions
|
||||
→ Check encounter medications for interactions
|
||||
→ Check patient allergies
|
||||
→ Validate dose against weight/age/renal function
|
||||
→ If CRITICAL interaction: BLOCK prescribing entirely
|
||||
→ Clinician must document override reason to proceed past a block
|
||||
→ If MAJOR interaction: display warning, require acknowledgment
|
||||
→ Log all alerts and override reasons in audit trail
|
||||
```
|
||||
|
||||
Critical interactions **block prescribing by default**. The clinician must explicitly override with a documented reason stored in the audit trail. The system never silently allows a critical interaction.
|
||||
|
||||
### Locked Encounter Pattern
|
||||
|
||||
Once a clinical encounter is signed:
|
||||
- No edits allowed — only an addendum (a separate linked record)
|
||||
- Both original and addendum appear in the patient timeline
|
||||
- Audit trail captures who signed, when, and any addendum records
|
||||
|
||||
### UI Patterns for Clinical Data
|
||||
|
||||
**Vitals Display:** Current values with normal range highlighting (green/yellow/red), trend arrows vs previous, clinical scoring auto-calculated (NEWS2, qSOFA), escalation guidance inline.
|
||||
|
||||
**Lab Results Display:** Normal range highlighting, previous value comparison, critical values with non-dismissable alert, collection/analysis timestamps, pending orders with expected turnaround.
|
||||
|
||||
**Prescription PDF:** One-click generation with patient demographics, allergies, diagnosis, drug details (generic + brand, dose, route, frequency, duration), clinician signature block.
|
||||
|
||||
### Accessibility for Healthcare
|
||||
|
||||
Healthcare UIs have stricter requirements than typical web apps:
|
||||
- 4.5:1 minimum contrast (WCAG AA) — clinicians work in varied lighting
|
||||
- Large touch targets (44x44px minimum) — for gloved/rushed interaction
|
||||
- Keyboard navigation — for power users entering data rapidly
|
||||
- No color-only indicators — always pair color with text/icon (colorblind clinicians)
|
||||
- Screen reader labels on all form fields
|
||||
- No auto-dismissing toasts for clinical alerts — clinician must actively acknowledge
|
||||
|
||||
### Anti-Patterns
|
||||
|
||||
- Storing clinical data in browser localStorage
|
||||
- Silent failures in drug interaction checking
|
||||
- Dismissable toasts for critical clinical alerts
|
||||
- Tab-based encounter UIs that fragment the clinical workflow
|
||||
- Allowing edits to signed/locked encounters
|
||||
- Displaying clinical data without audit trail
|
||||
- Using `any` type for clinical data structures
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Patient Encounter Flow
|
||||
|
||||
```
|
||||
Doctor opens encounter for Patient #4521
|
||||
→ Sticky header shows: "Rajesh M, 58M, Allergies: Penicillin, Active Meds: Metformin 500mg"
|
||||
→ Chief Complaint: selects "Chest Pain" template
|
||||
→ Clicks chips: "substernal", "radiating to left arm", "crushing"
|
||||
→ Red flag "crushing substernal chest pain" triggers non-dismissable alert
|
||||
→ Examination: CVS system — "S1 S2 normal, no murmur"
|
||||
→ Vitals: HR 110, BP 90/60, SpO2 94%
|
||||
→ NEWS2 auto-calculates: score 8, risk HIGH, escalation alert shown
|
||||
→ Diagnosis: searches "ACS" → selects ICD-10 I21.9
|
||||
→ Medications: selects Aspirin 300mg
|
||||
→ CDSS checks against Metformin: no interaction
|
||||
→ Signs encounter → locked, addendum-only from this point
|
||||
```
|
||||
|
||||
### Example 2: Medication Safety Workflow
|
||||
|
||||
```
|
||||
Doctor prescribes Warfarin for Patient #4521
|
||||
→ CDSS detects: Warfarin + Aspirin = CRITICAL interaction
|
||||
→ UI: red non-dismissable modal blocks prescribing
|
||||
→ Doctor clicks "Override with reason"
|
||||
→ Types: "Benefits outweigh risks — monitored INR protocol"
|
||||
→ Override reason + alert stored in audit trail
|
||||
→ Prescription proceeds with documented override
|
||||
```
|
||||
|
||||
### Example 3: Locked Encounter + Addendum
|
||||
|
||||
```
|
||||
Encounter #E-2024-0891 signed by Dr. Shah at 14:30
|
||||
→ All fields locked — no edit buttons visible
|
||||
→ "Add Addendum" button available
|
||||
→ Dr. Shah clicks addendum, adds: "Lab results received — Troponin elevated"
|
||||
→ New record E-2024-0891-A1 linked to original
|
||||
→ Timeline shows both: original encounter + addendum with timestamps
|
||||
```
|
||||
207
skills/healthcare-eval-harness/SKILL.md
Normal file
207
skills/healthcare-eval-harness/SKILL.md
Normal file
@@ -0,0 +1,207 @@
|
||||
---
|
||||
name: healthcare-eval-harness
|
||||
description: Patient safety evaluation harness for healthcare application deployments. Automated test suites for CDSS accuracy, PHI exposure, clinical workflow integrity, and integration compliance. Blocks deployments on safety failures.
|
||||
origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Healthcare Eval Harness — Patient Safety Verification
|
||||
|
||||
Automated verification system for healthcare application deployments. A single CRITICAL failure blocks deployment. Patient safety is non-negotiable.
|
||||
|
||||
> **Note:** Examples use Jest as the reference test runner. Adapt commands for your framework (Vitest, pytest, PHPUnit, etc.) — the test categories and pass thresholds are framework-agnostic.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Before any deployment of EMR/EHR applications
|
||||
- After modifying CDSS logic (drug interactions, dose validation, scoring)
|
||||
- After changing database schemas that touch patient data
|
||||
- After modifying authentication or access control
|
||||
- During CI/CD pipeline configuration for healthcare apps
|
||||
- After resolving merge conflicts in clinical modules
|
||||
|
||||
## How It Works
|
||||
|
||||
The eval harness runs five test categories in order. The first three (CDSS Accuracy, PHI Exposure, Data Integrity) are CRITICAL gates requiring 100% pass rate — a single failure blocks deployment. The remaining two (Clinical Workflow, Integration) are HIGH gates requiring 95%+ pass rate.
|
||||
|
||||
Each category maps to a Jest test path pattern. The CI pipeline runs CRITICAL gates with `--bail` (stop on first failure) and enforces coverage thresholds with `--coverage --coverageThreshold`.
|
||||
|
||||
### Eval Categories
|
||||
|
||||
**1. CDSS Accuracy (CRITICAL — 100% required)**
|
||||
|
||||
Tests all clinical decision support logic: drug interaction pairs (both directions), dose validation rules, clinical scoring vs published specs, no false negatives, no silent failures.
|
||||
|
||||
```bash
|
||||
npx jest --testPathPattern='tests/cdss' --bail --ci --coverage
|
||||
```
|
||||
|
||||
**2. PHI Exposure (CRITICAL — 100% required)**
|
||||
|
||||
Tests for protected health information leaks: API error responses, console output, URL parameters, browser storage, cross-facility isolation, unauthenticated access, service role key absence.
|
||||
|
||||
```bash
|
||||
npx jest --testPathPattern='tests/security/phi' --bail --ci
|
||||
```
|
||||
|
||||
**3. Data Integrity (CRITICAL — 100% required)**
|
||||
|
||||
Tests clinical data safety: locked encounters, audit trail entries, cascade delete protection, concurrent edit handling, no orphaned records.
|
||||
|
||||
```bash
|
||||
npx jest --testPathPattern='tests/data-integrity' --bail --ci
|
||||
```
|
||||
|
||||
**4. Clinical Workflow (HIGH — 95%+ required)**
|
||||
|
||||
Tests end-to-end flows: encounter lifecycle, template rendering, medication sets, drug/diagnosis search, prescription PDF, red flag alerts.
|
||||
|
||||
```bash
|
||||
tmp_json=$(mktemp)
|
||||
npx jest --testPathPattern='tests/clinical' --ci --json --outputFile="$tmp_json" || true
|
||||
total=$(jq '.numTotalTests // 0' "$tmp_json")
|
||||
passed=$(jq '.numPassedTests // 0' "$tmp_json")
|
||||
if [ "$total" -eq 0 ]; then
|
||||
echo "No clinical tests found" >&2
|
||||
exit 1
|
||||
fi
|
||||
rate=$(echo "scale=2; $passed * 100 / $total" | bc)
|
||||
echo "Clinical pass rate: ${rate}% ($passed/$total)"
|
||||
```
|
||||
|
||||
**5. Integration Compliance (HIGH — 95%+ required)**
|
||||
|
||||
Tests external systems: HL7 message parsing (v2.x), FHIR validation, lab result mapping, malformed message handling.
|
||||
|
||||
```bash
|
||||
tmp_json=$(mktemp)
|
||||
npx jest --testPathPattern='tests/integration' --ci --json --outputFile="$tmp_json" || true
|
||||
total=$(jq '.numTotalTests // 0' "$tmp_json")
|
||||
passed=$(jq '.numPassedTests // 0' "$tmp_json")
|
||||
if [ "$total" -eq 0 ]; then
|
||||
echo "No integration tests found" >&2
|
||||
exit 1
|
||||
fi
|
||||
rate=$(echo "scale=2; $passed * 100 / $total" | bc)
|
||||
echo "Integration pass rate: ${rate}% ($passed/$total)"
|
||||
```
|
||||
|
||||
### Pass/Fail Matrix
|
||||
|
||||
| Category | Threshold | On Failure |
|
||||
|----------|-----------|------------|
|
||||
| CDSS Accuracy | 100% | **BLOCK deployment** |
|
||||
| PHI Exposure | 100% | **BLOCK deployment** |
|
||||
| Data Integrity | 100% | **BLOCK deployment** |
|
||||
| Clinical Workflow | 95%+ | WARN, allow with review |
|
||||
| Integration | 95%+ | WARN, allow with review |
|
||||
|
||||
### CI/CD Integration
|
||||
|
||||
```yaml
|
||||
name: Healthcare Safety Gate
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
safety-gate:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: '20'
|
||||
- run: npm ci
|
||||
|
||||
# CRITICAL gates — 100% required, bail on first failure
|
||||
- name: CDSS Accuracy
|
||||
run: npx jest --testPathPattern='tests/cdss' --bail --ci --coverage --coverageThreshold='{"global":{"branches":80,"functions":80,"lines":80}}'
|
||||
|
||||
- name: PHI Exposure Check
|
||||
run: npx jest --testPathPattern='tests/security/phi' --bail --ci
|
||||
|
||||
- name: Data Integrity
|
||||
run: npx jest --testPathPattern='tests/data-integrity' --bail --ci
|
||||
|
||||
# HIGH gates — 95%+ required, custom threshold check
|
||||
# HIGH gates — 95%+ required
|
||||
- name: Clinical Workflows
|
||||
run: |
|
||||
TMP_JSON=$(mktemp)
|
||||
npx jest --testPathPattern='tests/clinical' --ci --json --outputFile="$TMP_JSON" || true
|
||||
TOTAL=$(jq '.numTotalTests // 0' "$TMP_JSON")
|
||||
PASSED=$(jq '.numPassedTests // 0' "$TMP_JSON")
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
echo "::error::No clinical tests found"; exit 1
|
||||
fi
|
||||
RATE=$(echo "scale=2; $PASSED * 100 / $TOTAL" | bc)
|
||||
echo "Pass rate: ${RATE}% ($PASSED/$TOTAL)"
|
||||
if (( $(echo "$RATE < 95" | bc -l) )); then
|
||||
echo "::warning::Clinical pass rate ${RATE}% below 95%"
|
||||
fi
|
||||
|
||||
- name: Integration Compliance
|
||||
run: |
|
||||
TMP_JSON=$(mktemp)
|
||||
npx jest --testPathPattern='tests/integration' --ci --json --outputFile="$TMP_JSON" || true
|
||||
TOTAL=$(jq '.numTotalTests // 0' "$TMP_JSON")
|
||||
PASSED=$(jq '.numPassedTests // 0' "$TMP_JSON")
|
||||
if [ "$TOTAL" -eq 0 ]; then
|
||||
echo "::error::No integration tests found"; exit 1
|
||||
fi
|
||||
RATE=$(echo "scale=2; $PASSED * 100 / $TOTAL" | bc)
|
||||
echo "Pass rate: ${RATE}% ($PASSED/$TOTAL)"
|
||||
if (( $(echo "$RATE < 95" | bc -l) )); then
|
||||
echo "::warning::Integration pass rate ${RATE}% below 95%"
|
||||
fi
|
||||
```
|
||||
|
||||
### Anti-Patterns
|
||||
|
||||
- Skipping CDSS tests "because they passed last time"
|
||||
- Setting CRITICAL thresholds below 100%
|
||||
- Using `--no-bail` on CRITICAL test suites
|
||||
- Mocking the CDSS engine in integration tests (must test real logic)
|
||||
- Allowing deployments when safety gate is red
|
||||
- Running tests without `--coverage` on CDSS suites
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Run All Critical Gates Locally
|
||||
|
||||
```bash
|
||||
npx jest --testPathPattern='tests/cdss' --bail --ci --coverage && \
|
||||
npx jest --testPathPattern='tests/security/phi' --bail --ci && \
|
||||
npx jest --testPathPattern='tests/data-integrity' --bail --ci
|
||||
```
|
||||
|
||||
### Example 2: Check HIGH Gate Pass Rate
|
||||
|
||||
```bash
|
||||
tmp_json=$(mktemp)
|
||||
npx jest --testPathPattern='tests/clinical' --ci --json --outputFile="$tmp_json" || true
|
||||
jq '{
|
||||
passed: (.numPassedTests // 0),
|
||||
total: (.numTotalTests // 0),
|
||||
rate: (if (.numTotalTests // 0) == 0 then 0 else ((.numPassedTests // 0) / (.numTotalTests // 1) * 100) end)
|
||||
}' "$tmp_json"
|
||||
# Expected: { "passed": 21, "total": 22, "rate": 95.45 }
|
||||
```
|
||||
|
||||
### Example 3: Eval Report
|
||||
|
||||
```
|
||||
## Healthcare Eval: 2026-03-27 [commit abc1234]
|
||||
|
||||
### Patient Safety: PASS
|
||||
|
||||
| Category | Tests | Pass | Fail | Status |
|
||||
|----------|-------|------|------|--------|
|
||||
| CDSS Accuracy | 39 | 39 | 0 | PASS |
|
||||
| PHI Exposure | 8 | 8 | 0 | PASS |
|
||||
| Data Integrity | 12 | 12 | 0 | PASS |
|
||||
| Clinical Workflow | 22 | 21 | 1 | 95.5% PASS |
|
||||
| Integration | 6 | 6 | 0 | PASS |
|
||||
|
||||
### Coverage: 84% (target: 80%+)
|
||||
### Verdict: SAFE TO DEPLOY
|
||||
```
|
||||
145
skills/healthcare-phi-compliance/SKILL.md
Normal file
145
skills/healthcare-phi-compliance/SKILL.md
Normal file
@@ -0,0 +1,145 @@
|
||||
---
|
||||
name: healthcare-phi-compliance
|
||||
description: Protected Health Information (PHI) and Personally Identifiable Information (PII) compliance patterns for healthcare applications. Covers data classification, access control, audit trails, encryption, and common leak vectors.
|
||||
origin: Health1 Super Speciality Hospitals — contributed by Dr. Keyur Patel
|
||||
version: "1.0.0"
|
||||
---
|
||||
|
||||
# Healthcare PHI/PII Compliance Patterns
|
||||
|
||||
Patterns for protecting patient data, clinician data, and financial data in healthcare applications. Applicable to HIPAA (US), DISHA (India), GDPR (EU), and general healthcare data protection.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Building any feature that touches patient records
|
||||
- Implementing access control or authentication for clinical systems
|
||||
- Designing database schemas for healthcare data
|
||||
- Building APIs that return patient or clinician data
|
||||
- Implementing audit trails or logging
|
||||
- Reviewing code for data exposure vulnerabilities
|
||||
- Setting up Row-Level Security (RLS) for multi-tenant healthcare systems
|
||||
|
||||
## How It Works
|
||||
|
||||
Healthcare data protection operates on three layers: **classification** (what is sensitive), **access control** (who can see it), and **audit** (who did see it).
|
||||
|
||||
### Data Classification
|
||||
|
||||
**PHI (Protected Health Information)** — any data that can identify a patient AND relates to their health: patient name, date of birth, address, phone, email, national ID numbers (SSN, Aadhaar, NHS number), medical record numbers, diagnoses, medications, lab results, imaging, insurance policy and claim details, appointment and admission records, or any combination of the above.
|
||||
|
||||
**PII (Non-patient-sensitive data)** in healthcare systems: clinician/staff personal details, doctor fee structures and payout amounts, employee salary and bank details, vendor payment information.
|
||||
|
||||
### Access Control: Row-Level Security
|
||||
|
||||
```sql
|
||||
ALTER TABLE patients ENABLE ROW LEVEL SECURITY;
|
||||
|
||||
-- Scope access by facility
|
||||
CREATE POLICY "staff_read_own_facility"
|
||||
ON patients FOR SELECT TO authenticated
|
||||
USING (facility_id IN (
|
||||
SELECT facility_id FROM staff_assignments
|
||||
WHERE user_id = auth.uid() AND role IN ('doctor','nurse','lab_tech','admin')
|
||||
));
|
||||
|
||||
-- Audit log: insert-only (tamper-proof)
|
||||
CREATE POLICY "audit_insert_only" ON audit_log FOR INSERT
|
||||
TO authenticated WITH CHECK (user_id = auth.uid());
|
||||
CREATE POLICY "audit_no_modify" ON audit_log FOR UPDATE USING (false);
|
||||
CREATE POLICY "audit_no_delete" ON audit_log FOR DELETE USING (false);
|
||||
```
|
||||
|
||||
### Audit Trail
|
||||
|
||||
Every PHI access or modification must be logged:
|
||||
|
||||
```typescript
|
||||
interface AuditEntry {
|
||||
timestamp: string;
|
||||
user_id: string;
|
||||
patient_id: string;
|
||||
action: 'create' | 'read' | 'update' | 'delete' | 'print' | 'export';
|
||||
resource_type: string;
|
||||
resource_id: string;
|
||||
changes?: { before: object; after: object };
|
||||
ip_address: string;
|
||||
session_id: string;
|
||||
}
|
||||
```
|
||||
|
||||
### Common Leak Vectors
|
||||
|
||||
**Error messages:** Never include patient-identifying data in error messages thrown to the client. Log details server-side only.
|
||||
|
||||
**Console output:** Never log full patient objects. Use opaque internal record IDs (UUIDs) — not medical record numbers, national IDs, or names.
|
||||
|
||||
**URL parameters:** Never put patient-identifying data in query strings or path segments that could appear in logs or browser history. Use opaque UUIDs only.
|
||||
|
||||
**Browser storage:** Never store PHI in localStorage or sessionStorage. Keep PHI in memory only, fetch on demand.
|
||||
|
||||
**Service role keys:** Never use the service_role key in client-side code. Always use the anon/publishable key and let RLS enforce access.
|
||||
|
||||
**Logs and monitoring:** Never log full patient records. Use opaque record IDs only (not medical record numbers). Sanitize stack traces before sending to error tracking services.
|
||||
|
||||
### Database Schema Tagging
|
||||
|
||||
Mark PHI/PII columns at the schema level:
|
||||
|
||||
```sql
|
||||
COMMENT ON COLUMN patients.name IS 'PHI: patient_name';
|
||||
COMMENT ON COLUMN patients.dob IS 'PHI: date_of_birth';
|
||||
COMMENT ON COLUMN patients.aadhaar IS 'PHI: national_id';
|
||||
COMMENT ON COLUMN doctor_payouts.amount IS 'PII: financial';
|
||||
```
|
||||
|
||||
### Deployment Checklist
|
||||
|
||||
Before every deployment:
|
||||
- No PHI in error messages or stack traces
|
||||
- No PHI in console.log/console.error
|
||||
- No PHI in URL parameters
|
||||
- No PHI in browser storage
|
||||
- No service_role key in client code
|
||||
- RLS enabled on all PHI/PII tables
|
||||
- Audit trail for all data modifications
|
||||
- Session timeout configured
|
||||
- API authentication on all PHI endpoints
|
||||
- Cross-facility data isolation verified
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Safe vs Unsafe Error Handling
|
||||
|
||||
```typescript
|
||||
// BAD — leaks PHI in error
|
||||
throw new Error(`Patient ${patient.name} not found in ${patient.facility}`);
|
||||
|
||||
// GOOD — generic error, details logged server-side with opaque IDs only
|
||||
logger.error('Patient lookup failed', { recordId: patient.id, facilityId });
|
||||
throw new Error('Record not found');
|
||||
```
|
||||
|
||||
### Example 2: RLS Policy for Multi-Facility Isolation
|
||||
|
||||
```sql
|
||||
-- Doctor at Facility A cannot see Facility B patients
|
||||
CREATE POLICY "facility_isolation"
|
||||
ON patients FOR SELECT TO authenticated
|
||||
USING (facility_id IN (
|
||||
SELECT facility_id FROM staff_assignments WHERE user_id = auth.uid()
|
||||
));
|
||||
|
||||
-- Test: login as doctor-facility-a, query facility-b patients
|
||||
-- Expected: 0 rows returned
|
||||
```
|
||||
|
||||
### Example 3: Safe Logging
|
||||
|
||||
```typescript
|
||||
// BAD — logs identifiable patient data
|
||||
console.log('Processing patient:', patient);
|
||||
|
||||
// GOOD — logs only opaque internal record ID
|
||||
console.log('Processing record:', patient.id);
|
||||
// Note: even patient.id should be an opaque UUID, not a medical record number
|
||||
```
|
||||
229
skills/laravel-plugin-discovery/SKILL.md
Normal file
229
skills/laravel-plugin-discovery/SKILL.md
Normal file
@@ -0,0 +1,229 @@
|
||||
---
|
||||
name: laravel-plugin-discovery
|
||||
description: Discover and evaluate Laravel packages via LaraPlugins.io MCP. Use when the user wants to find plugins, check package health, or assess Laravel/PHP compatibility.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Laravel Plugin Discovery
|
||||
|
||||
Find, evaluate, and choose healthy Laravel packages using the LaraPlugins.io MCP server.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User wants to find Laravel packages for a specific feature (e.g. "auth", "permissions", "admin panel")
|
||||
- User asks "what package should I use for..." or "is there a Laravel package for..."
|
||||
- User wants to check if a package is actively maintained
|
||||
- User needs to verify Laravel version compatibility
|
||||
- User wants to assess package health before adding to a project
|
||||
|
||||
## MCP Requirement
|
||||
|
||||
LaraPlugins MCP server must be configured. Add to your `~/.claude.json` mcpServers:
|
||||
|
||||
```json
|
||||
"laraplugins": {
|
||||
"type": "http",
|
||||
"url": "https://laraplugins.io/mcp/plugins"
|
||||
}
|
||||
```
|
||||
|
||||
No API key required — the server is free for the Laravel community.
|
||||
|
||||
## MCP Tools
|
||||
|
||||
The LaraPlugins MCP provides two primary tools:
|
||||
|
||||
### SearchPluginTool
|
||||
|
||||
Search packages by keyword, health score, vendor, and version compatibility.
|
||||
|
||||
**Parameters:**
|
||||
- `text_search` (string, optional): Keyword to search (e.g. "permission", "admin", "api")
|
||||
- `health_score` (string, optional): Filter by health band — `Healthy`, `Medium`, `Unhealthy`, or `Unrated`
|
||||
- `laravel_compatibility` (string, optional): Filter by Laravel version — `"5"`, `"6"`, `"7"`, `"8"`, `"9"`, `"10"`, `"11"`, `"12"`, `"13"`
|
||||
- `php_compatibility` (string, optional): Filter by PHP version — `"7.4"`, `"8.0"`, `"8.1"`, `"8.2"`, `"8.3"`, `"8.4"`, `"8.5"`
|
||||
- `vendor_filter` (string, optional): Filter by vendor name (e.g. "spatie", "laravel")
|
||||
- `page` (number, optional): Page number for pagination
|
||||
|
||||
### GetPluginDetailsTool
|
||||
|
||||
Fetch detailed metrics, readme content, and version history for a specific package.
|
||||
|
||||
**Parameters:**
|
||||
- `package` (string, required): Full Composer package name (e.g. "spatie/laravel-permission")
|
||||
- `include_versions` (boolean, optional): Include version history in response
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Finding Packages
|
||||
|
||||
When the user wants to discover packages for a feature:
|
||||
|
||||
1. Use `SearchPluginTool` with relevant keywords
|
||||
2. Apply filters for health score, Laravel version, or PHP version
|
||||
3. Review the results with package names, descriptions, and health indicators
|
||||
|
||||
### Evaluating Packages
|
||||
|
||||
When the user wants to assess a specific package:
|
||||
|
||||
1. Use `GetPluginDetailsTool` with the package name
|
||||
2. Review health score, last updated date, Laravel version support
|
||||
3. Check vendor reputation and risk indicators
|
||||
|
||||
### Checking Compatibility
|
||||
|
||||
When the user needs Laravel or PHP version compatibility:
|
||||
|
||||
1. Search with `laravel_compatibility` filter set to their version
|
||||
2. Or get details on a specific package to see its supported versions
|
||||
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
### Example: Find Authentication Packages
|
||||
|
||||
```
|
||||
SearchPluginTool({
|
||||
text_search: "authentication",
|
||||
health_score: "Healthy"
|
||||
})
|
||||
```
|
||||
|
||||
Returns packages matching "authentication" with healthy status:
|
||||
- spatie/laravel-permission
|
||||
- laravel/breeze
|
||||
- laravel/passport
|
||||
- etc.
|
||||
|
||||
### Example: Find Laravel 12 Compatible Packages
|
||||
|
||||
```
|
||||
SearchPluginTool({
|
||||
text_search: "admin panel",
|
||||
laravel_compatibility: "12"
|
||||
})
|
||||
```
|
||||
|
||||
Returns packages compatible with Laravel 12.
|
||||
|
||||
### Example: Get Package Details
|
||||
|
||||
```
|
||||
GetPluginDetailsTool({
|
||||
package: "spatie/laravel-permission",
|
||||
include_versions: true
|
||||
})
|
||||
```
|
||||
|
||||
Returns:
|
||||
- Health score and last activity
|
||||
- Laravel/PHP version support
|
||||
- Vendor reputation (risk score)
|
||||
- Version history
|
||||
- Brief description
|
||||
|
||||
### Example: Find Packages by Vendor
|
||||
|
||||
```
|
||||
SearchPluginTool({
|
||||
vendor_filter: "spatie",
|
||||
health_score: "Healthy"
|
||||
})
|
||||
```
|
||||
|
||||
Returns all healthy packages from vendor "spatie".
|
||||
|
||||
---
|
||||
|
||||
## Filtering Best Practices
|
||||
|
||||
### By Health Score
|
||||
|
||||
| Health Band | Meaning |
|
||||
|-------------|---------|
|
||||
| `Healthy` | Active maintenance, recent updates |
|
||||
| `Medium` | Occasional updates, may need attention |
|
||||
| `Unhealthy` | Abandoned or infrequently maintained |
|
||||
| `Unrated` | Not yet assessed |
|
||||
|
||||
**Recommendation**: Prefer `Healthy` packages for production applications.
|
||||
|
||||
### By Laravel Version
|
||||
|
||||
| Version | Notes |
|
||||
|---------|-------|
|
||||
| `13` | Latest Laravel |
|
||||
| `12` | Current stable |
|
||||
| `11` | Still widely used |
|
||||
| `10` | Legacy but common |
|
||||
| `5`-`9` | Deprecated |
|
||||
|
||||
**Recommendation**: Match the target project's Laravel version.
|
||||
|
||||
### Combining Filters
|
||||
|
||||
```typescript
|
||||
// Find healthy, Laravel 12 compatible packages for permissions
|
||||
SearchPluginTool({
|
||||
text_search: "permission",
|
||||
health_score: "Healthy",
|
||||
laravel_compatibility: "12"
|
||||
})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Response Interpretation
|
||||
|
||||
### Search Results
|
||||
|
||||
Each result includes:
|
||||
- Package name (e.g. `spatie/laravel-permission`)
|
||||
- Brief description
|
||||
- Health status indicator
|
||||
- Laravel version support badges
|
||||
|
||||
### Package Details
|
||||
|
||||
The detailed response includes:
|
||||
- **Health Score**: Numeric or band indicator
|
||||
- **Last Activity**: When the package was last updated
|
||||
- **Laravel Support**: Version compatibility matrix
|
||||
- **PHP Support**: PHP version compatibility
|
||||
- **Risk Score**: Vendor trust indicators
|
||||
- **Version History**: Recent release timeline
|
||||
|
||||
---
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
| Scenario | Recommended Approach |
|
||||
|----------|---------------------|
|
||||
| "What package for auth?" | Search "auth" with healthy filter |
|
||||
| "Is spatie/package still maintained?" | Get details, check health score |
|
||||
| "Need Laravel 12 packages" | Search with laravel_compatibility: "12" |
|
||||
| "Find admin panel packages" | Search "admin panel", review results |
|
||||
| "Check vendor reputation" | Search by vendor, check details |
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Always filter by health** — Use `health_score: "Healthy"` for production projects
|
||||
2. **Match Laravel version** — Always check `laravel_compatibility` matches the target project
|
||||
3. **Check vendor reputation** — Prefer packages from known vendors (spatie, laravel, etc.)
|
||||
4. **Review before recommending** — Use GetPluginDetailsTool for a comprehensive assessment
|
||||
5. **No API key needed** — The MCP is free, no authentication required
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `laravel-patterns` — Laravel architecture and patterns
|
||||
- `laravel-tdd` — Test-driven development for Laravel
|
||||
- `laravel-security` — Laravel security best practices
|
||||
- `documentation-lookup` — General library documentation lookup (Context7)
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: laravel-verification
|
||||
description: Verification loop for Laravel projects: env checks, linting, static analysis, tests with coverage, security scans, and deployment readiness.
|
||||
description: "Verification loop for Laravel projects: env checks, linting, static analysis, tests with coverage, security scans, and deployment readiness."
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
name: product-lens
|
||||
description: Use this skill to validate the "why" before building, run product diagnostics, and convert vague ideas into specs.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Product Lens — Think Before You Build
|
||||
|
||||
## When to Use
|
||||
|
||||
78
skills/repo-scan/SKILL.md
Normal file
78
skills/repo-scan/SKILL.md
Normal file
@@ -0,0 +1,78 @@
|
||||
---
|
||||
name: repo-scan
|
||||
description: Cross-stack source code asset audit — classifies every file, detects embedded third-party libraries, and delivers actionable four-level verdicts per module with interactive HTML reports.
|
||||
origin: community
|
||||
---
|
||||
|
||||
# repo-scan
|
||||
|
||||
> Every ecosystem has its own dependency manager, but no tool looks across C++, Android, iOS, and Web to tell you: how much code is actually yours, what's third-party, and what's dead weight.
|
||||
|
||||
## When to Use
|
||||
|
||||
- Taking over a large legacy codebase and need a structural overview
|
||||
- Before major refactoring — identify what's core, what's duplicate, what's dead
|
||||
- Auditing third-party dependencies embedded directly in source (not declared in package managers)
|
||||
- Preparing architecture decision records for monorepo reorganization
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Fetch only the pinned commit for reproducibility
|
||||
mkdir -p ~/.claude/skills/repo-scan
|
||||
git init repo-scan
|
||||
cd repo-scan
|
||||
git remote add origin https://github.com/haibindev/repo-scan.git
|
||||
git fetch --depth 1 origin 2742664
|
||||
git checkout --detach FETCH_HEAD
|
||||
cp -r . ~/.claude/skills/repo-scan
|
||||
```
|
||||
|
||||
> Review the source before installing any agent skill.
|
||||
|
||||
## Core Capabilities
|
||||
|
||||
| Capability | Description |
|
||||
|---|---|
|
||||
| **Cross-stack scanning** | C/C++, Java/Android, iOS (OC/Swift), Web (TS/JS/Vue) in one pass |
|
||||
| **File classification** | Every file tagged as project code, third-party, or build artifact |
|
||||
| **Library detection** | 50+ known libraries (FFmpeg, Boost, OpenSSL…) with version extraction |
|
||||
| **Four-level verdicts** | Core Asset / Extract & Merge / Rebuild / Deprecate |
|
||||
| **HTML reports** | Interactive dark-theme pages with drill-down navigation |
|
||||
| **Monorepo support** | Hierarchical scanning with summary + sub-project reports |
|
||||
|
||||
## Analysis Depth Levels
|
||||
|
||||
| Level | Files Read | Use Case |
|
||||
|---|---|---|
|
||||
| `fast` | 1-2 per module | Quick inventory of huge directories |
|
||||
| `standard` | 2-5 per module | Default audit with full dependency + architecture checks |
|
||||
| `deep` | 5-10 per module | Adds thread safety, memory management, API consistency |
|
||||
| `full` | All files | Pre-merge comprehensive review |
|
||||
|
||||
## How It Works
|
||||
|
||||
1. **Classify the repo surface**: enumerate files, then tag each as project code, embedded third-party code, or build artifact.
|
||||
2. **Detect embedded libraries**: inspect directory names, headers, license files, and version markers to identify bundled dependencies and likely versions.
|
||||
3. **Score each module**: group files by module or subsystem, then assign one of the four verdicts based on ownership, duplication, and maintenance cost.
|
||||
4. **Highlight structural risks**: call out dead-weight artifacts, duplicated wrappers, outdated vendored code, and modules that should be extracted, rebuilt, or deprecated.
|
||||
5. **Produce the report**: return a concise summary plus the interactive HTML output with per-module drill-down so the audit can be reviewed asynchronously.
|
||||
|
||||
## Examples
|
||||
|
||||
On a 50,000-file C++ monorepo:
|
||||
- Found FFmpeg 2.x (2015 vintage) still in production
|
||||
- Discovered the same SDK wrapper duplicated 3 times
|
||||
- Identified 636 MB of committed Debug/ipch/obj build artifacts
|
||||
- Classified: 3 MB project code vs 596 MB third-party
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Start with `standard` depth for first-time audits
|
||||
- Use `fast` for monorepos with 100+ modules to get a quick inventory
|
||||
- Run `deep` incrementally on modules flagged for refactoring
|
||||
- Review the cross-module analysis for duplicate detection across sub-projects
|
||||
|
||||
## Links
|
||||
|
||||
- [GitHub Repository](https://github.com/haibindev/repo-scan)
|
||||
@@ -1,3 +1,9 @@
|
||||
---
|
||||
name: safety-guard
|
||||
description: Use this skill to prevent destructive operations when working on production systems or running agents autonomously.
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Safety Guard — Prevent Destructive Operations
|
||||
|
||||
## When to Use
|
||||
|
||||
@@ -47,6 +47,19 @@ ALWAYS write tests first, then implement code to make tests pass.
|
||||
- Browser automation
|
||||
- UI interactions
|
||||
|
||||
### 4. Git Checkpoints
|
||||
- If the repository is under Git, create a checkpoint commit after each TDD stage
|
||||
- Do not squash or rewrite these checkpoint commits until the workflow is complete
|
||||
- Each checkpoint commit message must describe the stage and the exact evidence captured
|
||||
- Count only commits created on the current active branch for the current task
|
||||
- Do not treat commits from other branches, earlier unrelated work, or distant branch history as valid checkpoint evidence
|
||||
- Before treating a checkpoint as satisfied, verify that the commit is reachable from the current `HEAD` on the active branch and belongs to the current task sequence
|
||||
- The preferred compact workflow is:
|
||||
- one commit for failing test added and RED validated
|
||||
- one commit for minimal fix applied and GREEN validated
|
||||
- one optional commit for refactor complete
|
||||
- Separate evidence-only commits are not required if the test commit clearly corresponds to RED and the fix commit clearly corresponds to GREEN
|
||||
|
||||
## TDD Workflow Steps
|
||||
|
||||
### Step 1: Write User Journeys
|
||||
@@ -87,6 +100,29 @@ npm test
|
||||
# Tests should fail - we haven't implemented yet
|
||||
```
|
||||
|
||||
This step is mandatory and is the RED gate for all production changes.
|
||||
|
||||
Before modifying business logic or other production code, you must verify a valid RED state via one of these paths:
|
||||
- Runtime RED:
|
||||
- The relevant test target compiles successfully
|
||||
- The new or changed test is actually executed
|
||||
- The result is RED
|
||||
- Compile-time RED:
|
||||
- The new test newly instantiates, references, or exercises the buggy code path
|
||||
- The compile failure is itself the intended RED signal
|
||||
- In either case, the failure is caused by the intended business-logic bug, undefined behavior, or missing implementation
|
||||
- The failure is not caused only by unrelated syntax errors, broken test setup, missing dependencies, or unrelated regressions
|
||||
|
||||
A test that was only written but not compiled and executed does not count as RED.
|
||||
|
||||
Do not edit production code until this RED state is confirmed.
|
||||
|
||||
If the repository is under Git, create a checkpoint commit immediately after this stage is validated.
|
||||
Recommended commit message format:
|
||||
- `test: add reproducer for <feature or bug>`
|
||||
- This commit may also serve as the RED validation checkpoint if the reproducer was compiled and executed and failed for the intended reason
|
||||
- Verify that this checkpoint commit is on the current active branch before continuing
|
||||
|
||||
### Step 4: Implement Code
|
||||
Write minimal code to make tests pass:
|
||||
|
||||
@@ -97,12 +133,24 @@ export async function searchMarkets(query: string) {
|
||||
}
|
||||
```
|
||||
|
||||
If the repository is under Git, stage the minimal fix now but defer the checkpoint commit until GREEN is validated in Step 5.
|
||||
|
||||
### Step 5: Run Tests Again
|
||||
```bash
|
||||
npm test
|
||||
# Tests should now pass
|
||||
```
|
||||
|
||||
Rerun the same relevant test target after the fix and confirm the previously failing test is now GREEN.
|
||||
|
||||
Only after a valid GREEN result may you proceed to refactor.
|
||||
|
||||
If the repository is under Git, create a checkpoint commit immediately after GREEN is validated.
|
||||
Recommended commit message format:
|
||||
- `fix: <feature or bug>`
|
||||
- The fix commit may also serve as the GREEN validation checkpoint if the same relevant test target was rerun and passed
|
||||
- Verify that this checkpoint commit is on the current active branch before continuing
|
||||
|
||||
### Step 6: Refactor
|
||||
Improve code quality while keeping tests green:
|
||||
- Remove duplication
|
||||
@@ -110,6 +158,11 @@ Improve code quality while keeping tests green:
|
||||
- Optimize performance
|
||||
- Enhance readability
|
||||
|
||||
If the repository is under Git, create a checkpoint commit immediately after refactoring is complete and tests remain green.
|
||||
Recommended commit message format:
|
||||
- `refactor: clean up after <feature or bug> implementation`
|
||||
- Verify that this checkpoint commit is on the current active branch before considering the TDD cycle complete
|
||||
|
||||
### Step 7: Verify Coverage
|
||||
```bash
|
||||
npm run test:coverage
|
||||
|
||||
Reference in New Issue
Block a user