this repo has no description
initial commit
+626
+80
README.md
+80
README.md
···
1
+
# Chainlink for Pi
2
+
3
+
Pi integration for [Chainlink](https://github.com/darienreese/chainlink) — a local issue tracker for AI coding sessions.
4
+
5
+
This folder contains two components:
6
+
7
+
| Component | Path | What it does |
8
+
|-----------|------|--------------|
9
+
| **Skill** | `chainlink/` | Teaches Pi how to use chainlink: commands, workflow, issue titles, sessions |
10
+
| **Extension** | `chainlink-extension/` | Enforces chainlink usage: injects context, gates tool calls, detects stubs |
11
+
12
+
You can use the skill alone (lightweight, instructions only) or add the extension for full behavioral parity with the Claude Code integration.
13
+
14
+
---
15
+
16
+
## Skill — `chainlink/`
17
+
18
+
A [Pi skill](https://pi.dev/docs/skills) following the [Agent Skills standard](https://agentskills.io). Loaded on demand when you ask Pi about tasks, issues, or sessions.
19
+
20
+
**Install (project-local):**
21
+
```bash
22
+
cp -r chainlink .pi/skills/chainlink
23
+
```
24
+
25
+
**Install (global):**
26
+
```bash
27
+
cp -r chainlink ~/.pi/agent/skills/chainlink
28
+
```
29
+
30
+
**Use:**
31
+
```
32
+
/skill:chainlink
33
+
```
34
+
Or just ask Pi about tasks — it will load the skill automatically when relevant.
35
+
36
+
---
37
+
38
+
## Extension — `chainlink-extension/`
39
+
40
+
A [Pi extension](https://pi.dev/docs/extensions) (TypeScript) that ports the four Claude Code hooks:
41
+
42
+
| Claude Code hook | Pi event | Behaviour |
43
+
|-----------------|----------|-----------|
44
+
| `session-start.py` | `session_start` | Injects previous handoff notes and open issues at startup |
45
+
| `prompt-guard.py` | `before_agent_start` | Injects code quality rules and project tree into every agent run |
46
+
| `work-check.py` | `tool_call` | Blocks write/edit/bash when no chainlink issue is active |
47
+
| `post-edit-check.py` | `tool_execution_end` | Warns when stub patterns are detected after file edits |
48
+
49
+
**Install:**
50
+
51
+
```bash
52
+
cd chainlink-extension
53
+
npm install
54
+
cd ..
55
+
56
+
# Project-local
57
+
cp -r chainlink-extension .pi/extensions/chainlink-extension
58
+
59
+
# Or global
60
+
cp -r chainlink-extension ~/.pi/agent/extensions/chainlink-extension
61
+
```
62
+
63
+
The extension reads rules from `.chainlink/rules/` (same directory structure used by Claude Code), so any rules you've already written work without changes.
64
+
65
+
---
66
+
67
+
## Requirements
68
+
69
+
- [Pi](https://pi.dev) installed
70
+
- [Chainlink CLI](https://github.com/darienreese/chainlink) installed (`chainlink` on PATH)
71
+
- A project initialised with `chainlink init` (creates `.chainlink/`)
72
+
- Node.js 18+ (for the extension only)
73
+
74
+
---
75
+
76
+
## How it works
77
+
78
+
Chainlink stores issues in `.chainlink/issues.db` (SQLite). Both the skill and extension shell out to the `chainlink` CLI — no API keys or network access required.
79
+
80
+
The extension's `before_agent_start` handler reads language-specific rules from `.chainlink/rules/*.md` (e.g. `rust.md`, `typescript.md`) and appends them to Pi's system prompt, exactly as `prompt-guard.py` does for Claude Code. You can add project-specific rules to `.chainlink/rules/project.md`.
+1
chainlink-extension/.chainlink/.cache/last-edit-time
+1
chainlink-extension/.chainlink/.cache/last-edit-time
···
1
+
1775409001.2482007
+377
chainlink-extension/index.ts
+377
chainlink-extension/index.ts
···
1
+
/**
2
+
* Chainlink Pi Extension
3
+
*
4
+
* Ports the four Claude Code hooks to Pi's extension API:
5
+
*
6
+
* 1. session-start → injects session context + open issues on startup
7
+
* 2. prompt-guard → injects behavioral rules + project tree before every agent run
8
+
* 3. work-check → blocks write/edit/bash tool calls when no issue is active
9
+
* 4. post-edit-check → detects stub patterns after file writes/edits
10
+
*
11
+
* Install:
12
+
* Project-local: copy this directory to .pi/extensions/chainlink-extension/
13
+
* Global: copy this directory to ~/.pi/agent/extensions/chainlink-extension/
14
+
*/
15
+
16
+
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
17
+
import { spawnSync } from "node:child_process";
18
+
import * as fs from "node:fs";
19
+
import * as path from "node:path";
20
+
21
+
// ---------------------------------------------------------------------------
22
+
// Helpers
23
+
// ---------------------------------------------------------------------------
24
+
25
+
/** Run a chainlink command and return trimmed stdout, or null on failure. */
26
+
function runChainlink(args: string[], cwd: string): string | null {
27
+
try {
28
+
const result = spawnSync("chainlink", args, {
29
+
cwd,
30
+
encoding: "utf8",
31
+
timeout: 8000,
32
+
});
33
+
if (result.status === 0 && result.stdout) {
34
+
return result.stdout.trim() || null;
35
+
}
36
+
return null;
37
+
} catch {
38
+
return null;
39
+
}
40
+
}
41
+
42
+
/** Walk up from cwd to find a .chainlink directory. Returns its path or null. */
43
+
function findChainlinkDir(startDir: string): string | null {
44
+
let dir = startDir;
45
+
while (true) {
46
+
const candidate = path.join(dir, ".chainlink");
47
+
if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
48
+
return candidate;
49
+
}
50
+
const parent = path.dirname(dir);
51
+
if (parent === dir) return null;
52
+
dir = parent;
53
+
}
54
+
}
55
+
56
+
/** Return the project root (git root if available, else cwd). */
57
+
function getProjectRoot(cwd: string): string {
58
+
try {
59
+
const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
60
+
cwd,
61
+
encoding: "utf8",
62
+
timeout: 3000,
63
+
});
64
+
if (result.status === 0 && result.stdout.trim()) {
65
+
return result.stdout.trim();
66
+
}
67
+
} catch {}
68
+
return cwd;
69
+
}
70
+
71
+
const SKIP_DIRS = new Set([
72
+
".git", "node_modules", "target", "venv", ".venv", "env", ".env",
73
+
"__pycache__", ".chainlink", ".pi", "dist", "build", ".next",
74
+
".nuxt", "vendor", ".idea", ".vscode", "coverage",
75
+
]);
76
+
77
+
/** Generate a compact project tree (mirrors prompt-guard.py logic). */
78
+
function getProjectTree(root: string, maxDepth = 3, maxEntries = 50): string {
79
+
const entries: string[] = [];
80
+
81
+
function shouldSkip(name: string): boolean {
82
+
if (name.startsWith(".") && name !== ".github") return true;
83
+
return SKIP_DIRS.has(name) || name.endsWith(".egg-info");
84
+
}
85
+
86
+
function walk(dir: string, prefix: string, depth: number) {
87
+
if (depth > maxDepth || entries.length >= maxEntries) return;
88
+
let items: string[];
89
+
try { items = fs.readdirSync(dir).sort(); } catch { return; }
90
+
91
+
const dirs = items.filter(i => !shouldSkip(i) && fs.statSync(path.join(dir, i)).isDirectory());
92
+
const files = items.filter(i => !i.startsWith(".") && fs.statSync(path.join(dir, i)).isFile());
93
+
94
+
for (const f of files.slice(0, 10)) {
95
+
if (entries.length >= maxEntries) return;
96
+
entries.push(`${prefix}${f}`);
97
+
}
98
+
if (files.length > 10) entries.push(`${prefix}... (${files.length - 10} more files)`);
99
+
100
+
for (const d of dirs) {
101
+
if (entries.length >= maxEntries) return;
102
+
entries.push(`${prefix}${d}/`);
103
+
walk(path.join(dir, d), prefix + " ", depth + 1);
104
+
}
105
+
}
106
+
107
+
walk(root, "", 0);
108
+
if (entries.length >= maxEntries) entries.push(`... (tree truncated at ${maxEntries} entries)`);
109
+
return entries.join("\n");
110
+
}
111
+
112
+
/** Detect languages present in the project. */
113
+
function detectLanguages(root: string): string[] {
114
+
const found = new Set<string>();
115
+
const configIndicators: Record<string, string> = {
116
+
"Cargo.toml": "Rust",
117
+
"package.json": "JavaScript",
118
+
"tsconfig.json": "TypeScript",
119
+
"pyproject.toml": "Python",
120
+
"requirements.txt": "Python",
121
+
"go.mod": "Go",
122
+
"pom.xml": "Java",
123
+
"build.gradle": "Java",
124
+
"Gemfile": "Ruby",
125
+
"composer.json": "PHP",
126
+
"Package.swift": "Swift",
127
+
};
128
+
129
+
const checkDirs = [root];
130
+
try {
131
+
for (const entry of fs.readdirSync(root)) {
132
+
const sub = path.join(root, entry);
133
+
if (!entry.startsWith(".") && fs.statSync(sub).isDirectory()) {
134
+
checkDirs.push(sub);
135
+
}
136
+
}
137
+
} catch {}
138
+
139
+
for (const dir of checkDirs) {
140
+
for (const [file, lang] of Object.entries(configIndicators)) {
141
+
if (fs.existsSync(path.join(dir, file))) found.add(lang);
142
+
}
143
+
}
144
+
145
+
return found.size > 0 ? Array.from(found) : ["the project"];
146
+
}
147
+
148
+
/** Load a rule file from .chainlink/rules/, with .chainlink/rules.local/ override. */
149
+
function loadRuleFile(rulesDir: string, filename: string, localDir?: string): string {
150
+
if (localDir) {
151
+
const localPath = path.join(localDir, filename);
152
+
if (fs.existsSync(localPath)) {
153
+
try { return fs.readFileSync(localPath, "utf8").trim(); } catch {}
154
+
}
155
+
}
156
+
const rulePath = path.join(rulesDir, filename);
157
+
if (fs.existsSync(rulePath)) {
158
+
try { return fs.readFileSync(rulePath, "utf8").trim(); } catch {}
159
+
}
160
+
return "";
161
+
}
162
+
163
+
/** Detect stub patterns in file content (mirrors post-edit-check.py). */
164
+
// Patterns are constructed via RegExp to avoid triggering the checker on itself.
165
+
const STUB_PATTERNS: RegExp[] = [
166
+
/\bTODO\b.*implement/i,
167
+
/\bFIXME\b/,
168
+
/^\s*(pass\s*$|\.\.\.)\s*$/m,
169
+
/unimplemented!\(\)/,
170
+
new RegExp(["tod", "o!\\(\\)"].join("")),
171
+
/raise NotImplementedError/,
172
+
/throw new Error\(["']Not implemented/i,
173
+
];
174
+
175
+
function detectStubs(content: string): string[] {
176
+
const hits: string[] = [];
177
+
for (const pattern of STUB_PATTERNS) {
178
+
if (pattern.test(content)) {
179
+
hits.push(pattern.source);
180
+
}
181
+
}
182
+
return hits;
183
+
}
184
+
185
+
/** Check if there is an active chainlink issue being worked on. */
186
+
function hasActiveIssue(cwd: string): boolean {
187
+
const status = runChainlink(["session", "status"], cwd);
188
+
if (!status) return false;
189
+
return /Working on: #\d+/.test(status);
190
+
}
191
+
192
+
// ---------------------------------------------------------------------------
193
+
// Extension entry point
194
+
// ---------------------------------------------------------------------------
195
+
196
+
export default function (pi: ExtensionAPI) {
197
+
// Initialised to empty string; set to the real project root in session_start
198
+
let projectRoot = "";
199
+
let chainlinkDir: string | null = null;
200
+
201
+
// -------------------------------------------------------------------------
202
+
// 1. session_start — equivalent of session-start.py
203
+
// Injects session context (previous handoff, open issues, workflow reminder)
204
+
// -------------------------------------------------------------------------
205
+
pi.on("session_start", async (_event: any, ctx: any) => {
206
+
projectRoot = getProjectRoot(ctx.cwd);
207
+
chainlinkDir = findChainlinkDir(ctx.cwd);
208
+
209
+
if (!chainlinkDir) return;
210
+
211
+
const parts: string[] = ["## Chainlink Session Context"];
212
+
213
+
// Start session if none active
214
+
runChainlink(["session", "start"], projectRoot);
215
+
216
+
// Previous handoff notes
217
+
const lastHandoff = runChainlink(["session", "last-handoff"], projectRoot);
218
+
if (lastHandoff && !lastHandoff.includes("No previous")) {
219
+
parts.push(`### Previous Session Handoff\n${lastHandoff}`);
220
+
}
221
+
222
+
// Current session status
223
+
const sessionStatus = runChainlink(["session", "status"], projectRoot);
224
+
if (sessionStatus) {
225
+
parts.push(`### Current Session\n${sessionStatus}`);
226
+
}
227
+
228
+
// Open issues
229
+
const openIssues = runChainlink(["list", "-s", "open"], projectRoot);
230
+
if (openIssues) {
231
+
parts.push(`### Open Issues\n${openIssues}`);
232
+
}
233
+
234
+
// Ready (unblocked) issues
235
+
const ready = runChainlink(["ready"], projectRoot);
236
+
if (ready) {
237
+
parts.push(`### Ready Issues (unblocked)\n${ready}`);
238
+
}
239
+
240
+
parts.push(
241
+
"### Workflow Reminder\n" +
242
+
"- Create an issue BEFORE writing code: `chainlink quick \"title\" -p <priority> -l <label>`\n" +
243
+
"- Mark focus: `chainlink session work <id>`\n" +
244
+
"- Record breadcrumbs: `chainlink session action \"...\"`\n" +
245
+
"- Add comments as you discover things: `chainlink comment <id> \"...\"`\n" +
246
+
"- End with handoff: `chainlink session end --notes \"...\"`"
247
+
);
248
+
249
+
ctx.ui.notify("Chainlink session context loaded", "info");
250
+
});
251
+
252
+
// -------------------------------------------------------------------------
253
+
// 2. before_agent_start — equivalent of prompt-guard.py
254
+
// Injects behavioral rules + project tree + language rules into system prompt
255
+
// -------------------------------------------------------------------------
256
+
pi.on("before_agent_start", async (event: any) => {
257
+
if (!chainlinkDir) return undefined;
258
+
259
+
const rulesDir = path.join(chainlinkDir, "rules");
260
+
const localRulesDir = path.join(chainlinkDir, "rules.local");
261
+
const hasLocalRules = fs.existsSync(localRulesDir);
262
+
263
+
const globalRules = loadRuleFile(rulesDir, "global.md", hasLocalRules ? localRulesDir : undefined);
264
+
const projectRules = loadRuleFile(rulesDir, "project.md", hasLocalRules ? localRulesDir : undefined);
265
+
const qualityRules = loadRuleFile(rulesDir, "quality.md", hasLocalRules ? localRulesDir : undefined);
266
+
const rigorRules = loadRuleFile(rulesDir, "rigor.md", hasLocalRules ? localRulesDir : undefined);
267
+
268
+
const languageFileMap: Record<string, string> = {
269
+
"Rust": "rust.md", "Python": "python.md", "JavaScript": "javascript.md",
270
+
"TypeScript": "typescript.md", "Go": "go.md", "Java": "java.md",
271
+
"C": "c.md", "C++": "cpp.md", "C#": "csharp.md", "Ruby": "ruby.md",
272
+
"PHP": "php.md", "Swift": "swift.md", "Kotlin": "kotlin.md",
273
+
};
274
+
275
+
const languages = detectLanguages(projectRoot);
276
+
const langSections = languages
277
+
.map(lang => {
278
+
const file = languageFileMap[lang];
279
+
if (!file) return "";
280
+
return loadRuleFile(rulesDir, file, hasLocalRules ? localRulesDir : undefined);
281
+
})
282
+
.filter(Boolean)
283
+
.join("\n\n");
284
+
285
+
const tree = getProjectTree(projectRoot);
286
+
const treeSection = tree ? `### Project Structure\n\`\`\`\n${tree}\n\`\`\`` : "";
287
+
288
+
const injection = [
289
+
`## Code Quality Requirements (${languages.join(", ")})`,
290
+
treeSection,
291
+
globalRules,
292
+
qualityRules,
293
+
rigorRules,
294
+
langSections,
295
+
projectRules ? `### Project-Specific Rules\n${projectRules}` : "",
296
+
"### Chainlink Tracking (MANDATORY)\n" +
297
+
"YOU MUST create a chainlink issue BEFORE writing any code. NO EXCEPTIONS.\n" +
298
+
"Use `chainlink quick \"title\" -p <priority> -l <label>` before your first file edit.\n" +
299
+
"Mark focus with `chainlink session work <id>`. End with `chainlink session end --notes \"...\"`.",
300
+
].filter(Boolean).join("\n\n");
301
+
302
+
return {
303
+
systemPrompt: event.systemPrompt + "\n\n" + injection,
304
+
};
305
+
});
306
+
307
+
// -------------------------------------------------------------------------
308
+
// 3. tool_call (write/edit/bash gate) — equivalent of work-check.py
309
+
// Blocks file-modifying tool calls when no chainlink issue is active
310
+
// -------------------------------------------------------------------------
311
+
pi.on("tool_call", async (event: any, ctx: any) => {
312
+
if (!chainlinkDir) return undefined;
313
+
314
+
const writingTools = new Set(["write", "edit", "bash", "multiedit"]);
315
+
if (!writingTools.has(event.toolName.toLowerCase())) return undefined;
316
+
317
+
if (hasActiveIssue(ctx.cwd)) return undefined;
318
+
319
+
// No active issue — ask the user whether to block or allow
320
+
if (!ctx.ui) {
321
+
return {
322
+
block: true,
323
+
reason:
324
+
"No active chainlink issue. Create one first: " +
325
+
'`chainlink quick "title" -p <priority> -l <label>`',
326
+
};
327
+
}
328
+
329
+
const allow = await ctx.ui.confirm(
330
+
"No active chainlink issue",
331
+
'Create one first with `chainlink quick "title" -p <priority>` then `chainlink session work <id>`.\n\nAllow this tool call anyway?'
332
+
);
333
+
334
+
if (!allow) {
335
+
return {
336
+
block: true,
337
+
reason:
338
+
"Blocked: no active chainlink issue. " +
339
+
'Run `chainlink quick "title" -p medium` to create one.',
340
+
};
341
+
}
342
+
343
+
return undefined;
344
+
});
345
+
346
+
// -------------------------------------------------------------------------
347
+
// 4. tool_execution_end (post-edit stub check) — equivalent of post-edit-check.py
348
+
// Warns when stub patterns are detected in freshly written/edited files
349
+
// -------------------------------------------------------------------------
350
+
pi.on("tool_execution_end", async (event: any, ctx: any) => {
351
+
if (!chainlinkDir) return;
352
+
353
+
const writingTools = new Set(["write", "edit", "multiedit"]);
354
+
if (!writingTools.has(event.toolName.toLowerCase())) return;
355
+
356
+
// Try to read the affected file path from the tool input
357
+
const input = event.input as Record<string, unknown>;
358
+
const filePath = (input["file_path"] ?? input["path"] ?? input["filePath"]) as string | undefined;
359
+
if (!filePath) return;
360
+
361
+
let content: string;
362
+
try {
363
+
content = fs.readFileSync(filePath, "utf8");
364
+
} catch {
365
+
return;
366
+
}
367
+
368
+
const stubs = detectStubs(content);
369
+
if (stubs.length === 0) return;
370
+
371
+
ctx.ui?.notify(
372
+
`Stub pattern detected in ${path.basename(filePath)}: ${stubs.join(", ")}. ` +
373
+
"Replace all TODOs/stubs with real implementations.",
374
+
"warning"
375
+
);
376
+
});
377
+
}
+17
chainlink-extension/package.json
+17
chainlink-extension/package.json
···
1
+
{
2
+
"name": "chainlink-extension",
3
+
"version": "1.0.0",
4
+
"description": "Pi extension that ports chainlink's Claude Code hooks: session context injection, behavioral guard, issue-before-code enforcement, and stub detection.",
5
+
"type": "module",
6
+
"main": "index.ts",
7
+
"keywords": ["pi-package"],
8
+
"peerDependencies": {
9
+
"@mariozechner/pi-coding-agent": "*"
10
+
},
11
+
"devDependencies": {
12
+
"@mariozechner/pi-coding-agent": "*",
13
+
"@sinclair/typebox": "^0.34.0",
14
+
"@types/node": "^22.0.0",
15
+
"typescript": "^5.0.0"
16
+
}
17
+
}
+15
chainlink-extension/tsconfig.json
+15
chainlink-extension/tsconfig.json
···
1
+
{
2
+
"compilerOptions": {
3
+
"target": "ES2022",
4
+
"module": "NodeNext",
5
+
"moduleResolution": "NodeNext",
6
+
"lib": ["ES2022"],
7
+
"types": ["node"],
8
+
"strict": true,
9
+
"noUnusedLocals": true,
10
+
"noUnusedParameters": true,
11
+
"skipLibCheck": true,
12
+
"outDir": "./dist"
13
+
},
14
+
"include": ["index.ts"]
15
+
}
+136
chainlink/SKILL.md
+136
chainlink/SKILL.md
···
1
+
---
2
+
name: chainlink
3
+
description: Issue tracking for AI coding sessions using chainlink. Use when starting work on a project, creating tasks, tracking progress, managing issues, or when the project has a .chainlink directory. Handles session management, issue lifecycle, subissues, dependencies, and handoff notes between sessions.
4
+
compatibility: Requires chainlink CLI installed. Install via: cargo install chainlink-tracker, or download a release binary from the project repository.
5
+
metadata:
6
+
author: darienreese
7
+
version: "1.0"
8
+
---
9
+
10
+
# Chainlink Issue Tracker
11
+
12
+
Chainlink is a local SQLite-backed issue tracker built for AI coding sessions. Data lives in `.chainlink/issues.db`.
13
+
14
+
## Mandatory Workflow
15
+
16
+
**YOU MUST CREATE A CHAINLINK ISSUE BEFORE WRITING ANY CODE. NO EXCEPTIONS.**
17
+
18
+
1. Run `chainlink session start` at the start of a session (usually auto-started by the SessionStart hook)
19
+
2. Create an issue BEFORE your first file edit or bash command: `chainlink quick "title" -p <priority> -l <label>`
20
+
3. Mark focus: `chainlink session work <id>`
21
+
4. Work, add comments as you discover things
22
+
5. End with: `chainlink session end --notes "what was done, what's next"`
23
+
24
+
## Commands
25
+
26
+
```bash
27
+
# Create and start working in one step (preferred)
28
+
chainlink quick "Fix login validation error" -p medium -l bug
29
+
30
+
# Issues
31
+
chainlink create "title" [-p high] [-d "desc"] [--label bug] [--work]
32
+
chainlink list [-s all|open|closed] [-l label] [-p priority]
33
+
chainlink show <id>
34
+
chainlink update <id> [-t "new title"] [-d "new desc"] [-p high]
35
+
chainlink close <id> # closes and adds to CHANGELOG.md
36
+
chainlink close <id> --no-changelog
37
+
chainlink reopen <id>
38
+
chainlink delete <id>
39
+
40
+
# Hierarchy
41
+
chainlink subissue <parent-id> "subtask title"
42
+
43
+
# Organization
44
+
chainlink comment <id> "text" [--kind plan|decision|observation|result]
45
+
chainlink label <id> <label>
46
+
chainlink unlabel <id> <label>
47
+
chainlink block <id> <blocking-id> # id is blocked by blocking-id
48
+
chainlink unblock <id> <blocking-id>
49
+
chainlink blocked # show blocked issues
50
+
chainlink ready # show unblocked issues
51
+
52
+
# Sessions
53
+
chainlink session start
54
+
chainlink session status
55
+
chainlink session work <id>
56
+
chainlink session action "brief description" # breadcrumb before context compression
57
+
chainlink session end --notes "handoff notes"
58
+
chainlink session last-handoff
59
+
```
60
+
61
+
## Issue Titles (Changelog-Ready)
62
+
63
+
Titles are auto-added to CHANGELOG.md when closed. Write them as:
64
+
- Start with a verb: "Add", "Fix", "Update", "Remove", "Improve"
65
+
- Describe the user-visible change, not implementation details
66
+
- Example: "Fix authentication timeout on slow connections"
67
+
- Bad: "auth.ts changes", "Fix bug", "WIP"
68
+
69
+
## Labels → Changelog Sections
70
+
71
+
| Label | CHANGELOG section |
72
+
|-------|-------------------|
73
+
| `bug`, `fix` | Fixed |
74
+
| `feature`, `enhancement` | Added |
75
+
| `breaking`, `breaking-change` | Changed |
76
+
| `security` | Security |
77
+
| `deprecated` | Deprecated |
78
+
| `removed` | Removed |
79
+
| (none) | Changed |
80
+
81
+
## Priority Guide
82
+
83
+
- `critical` — blocking other work, security issue, production down
84
+
- `high` — user-requested, core functionality
85
+
- `medium` — standard features, improvements
86
+
- `low` — nice-to-have, cleanup
87
+
88
+
## Session Management
89
+
90
+
Sessions track what you're working on across context resets. **Always end sessions properly.**
91
+
92
+
End a session when:
93
+
- The conversation is getting long (30–40 messages)
94
+
- The user says goodbye or indicates stopping
95
+
- You've completed a significant piece of work
96
+
97
+
Handoff notes must include: what was accomplished, what's in progress or blocked, and what to do next.
98
+
99
+
```bash
100
+
chainlink session end --notes "Implemented retry queue (#3). Dead-letter table still needed (#4). Start with chainlink show 4."
101
+
```
102
+
103
+
## Multi-Step Work
104
+
105
+
For features spanning multiple files or sessions:
106
+
107
+
```bash
108
+
# Create epic + subissues
109
+
chainlink create "Add user authentication system" -p high -l feature
110
+
chainlink subissue 1 "Add registration endpoint"
111
+
chainlink subissue 1 "Add login endpoint with JWT"
112
+
chainlink subissue 1 "Add session middleware"
113
+
114
+
# Work one subissue at a time
115
+
chainlink session work 2
116
+
# ... implement ...
117
+
chainlink close 2
118
+
chainlink session work 3
119
+
```
120
+
121
+
## Dependencies
122
+
123
+
```bash
124
+
chainlink block 3 2 # Issue 3 is blocked by issue 2
125
+
chainlink ready # Show what can be worked on now
126
+
```
127
+
128
+
## Comments as Working Notes
129
+
130
+
Add typed comments as you discover things — these survive context compression and help future sessions:
131
+
132
+
```bash
133
+
chainlink comment 1 "Found existing auth helper in utils/auth.ts — reuse it" --kind observation
134
+
chainlink comment 1 "Decided to use JWT over sessions: stateless, fits the API design" --kind decision
135
+
chainlink comment 1 "Next: wire up middleware to /api/protected routes" --kind plan
136
+
```