| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 6 | 6 | 0% |
| Commands | 2 | 4 | 8 | 14% |
| Section tags | 3 | 4 | 5 | 25% |
What each file covers
Sections
0 shared · 6 only in A · 6 only in B- − AGENTS.md
- − Workflow
- − Coding Standards
- − Adding a New Tool — Checklist
- − Dependencies
- − Anti-Patterns to Avoid
- + CI Workflow Review Guidelines
- + Security
- + Prefer explicit permissions scoping
- + Node.js Version Requirements
- + Package Manager
- + Build and Test Order
Commands
2 shared · 4 only in A · 8 only in B- − pnpm run check
- − pnpm lint && pnpm build
- − pnpm run link
- − pnpm run test:watch
- + pnpm
- + npm ci
- + yarn
- + pnpm-lock.yaml
- + pnpm install --frozen-lockfile
- + pnpm/action-setup@v4
- + pnpm run build
- + tsc
- pnpm test
- node:sqlite
Section tags
3 shared · 4 only in A · 5 only in B- − lint-format
- − testing-strategy
- − dependencies
- − do-not
- + setup
- + build
- + git-pr
- + security
- + deployment
- test
- code-style
- agent-behaviour
Line diff
yigitkonur/cli-continues · AGENTS.md
@@ −1 @@
1# AGENTS.md
2
3Agent behavior instructions for `continues` — the cross-tool AI session handoff CLI. Read `CLAUDE.md` for architecture, types, and the step-by-step guide for adding a new parser. This file covers workflow, coding standards, and anti-patterns.
4
5## Workflow
6
7- **Before any commit**: run `pnpm run check` (`pnpm lint && pnpm build`). Fix all Biome errors; warnings are advisory.
8- **After changing a parser or fixture**: run `pnpm test` and confirm all tests pass. Do not commit with failing tests.
9- **After adding a new tool**: run `pnpm run link` to test the global `continues` / `cont` binary locally.
10- **Never run** `pnpm run test:watch`, `e2e-conversions.test.ts`, `real-e2e-full.ts`, or `stress-test.ts` in CI — these require live session files on the developer's machine.
11
12## Coding Standards
13
14- **ESM-only**: all local imports must end in `.js`, even for `.ts` source files (e.g., `import { foo } from './foo.js'`).
15- **No `any`**: Biome reports `noExplicitAny` as a warning. Avoid it; document the reason if unavoidable.
16- **Exit codes**: set `process.exitCode = N` rather than calling `process.exit(N)`.
17- **Logging**: use `logger` from `src/logger.ts` for all diagnostic output. Never use bare `console.log`/`console.warn`/`console.error` in library code. TUI display goes through `@clack/prompts` or `chalk` via the display layer.
18- **Error types**: throw typed errors from `src/errors.ts` on user-facing paths, not bare `new Error()`.
19- **Tool activity**: use `SummaryCollector` from `src/utils/tool-summarizer.ts` in every parser. Do not build `ToolUsageSummary[]` arrays manually.
20- **JSONL**: use the shared streaming helpers in `src/utils/jsonl.ts`, never `fs.readFileSync` + `split('\n')`.
21- **SQLite** (OpenCode, Crush parsers): use built-in `node:sqlite` — do not add third-party SQLite dependencies.
22- **Biome rules in force**: `noEmptyBlockStatements` (error), `noUnusedImports` (error), `useConst` (error). Empty `catch {}` blocks fail the linter; use `catch (err) { logger.debug(...) }` instead.
23
24## Adding a New Tool — Checklist
25
26All five steps are required. Missing any one is a bug. See `CLAUDE.md` for detailed implementation guidance.
27
281. Add tool name to `TOOL_NAMES` in `src/types/tool-names.ts`
292. Create `src/parsers/<tool>.ts` exporting `parse<Tool>Sessions()` and `extract<Tool>Context()`
303. Register in `src/parsers/registry.ts` (the completeness assertion throws at module load if missing)
314. Add `create<Tool>Fixture()` in `src/__tests__/fixtures/index.ts`
325. Add conversion test cases in `src/__tests__/unit-conversions.test.ts`
33
34## Dependencies
35
36- **`@clack/prompts`** — all interactive TUI prompts and spinners. Do not use `readline` or `inquirer`.
37- **`chalk`** — terminal color. Chalk v4 is installed (CommonJS compat import); do not upgrade to v5+ (ESM-only).
38- **`commander`** — CLI argument parsing.
39- **`ora`** — non-interactive spinners.
40- **`yaml`** — YAML parsing for Copilot sessions.
41- **`zod`** — runtime schema validation. Use `z.safeParse()` where failures are recoverable.
42- Do not add new runtime dependencies without strong justification. The install footprint is intentionally small.
43
44## Anti-Patterns to Avoid
45
46- **Writing to tool storage directories** — the tool is read-only. Any write to `~/.claude/`, `~/.codex/`, etc. is a severe bug.
47- **`exec()` with string interpolation** — always use `spawn()` with an argument array in `resume.ts`. Session IDs and paths can contain shell metacharacters.
48- **`fs.readFileSync`/`fs.writeFileSync` in parsers** — these block the event loop. Use async fs APIs or shared streaming helpers.
49- **Duplicating parser-helpers** — `cleanSummary`, `extractRepoFromCwd`, `homeDir` live in `src/utils/parser-helpers.ts`. Import them; do not reimplement.
50- **Hardcoding tool names** — derive from `TOOL_NAMES` or `SessionSource`. Never write `if (tool === 'claude' || tool === 'codex' || ...)`.
51- **Importing `node:sqlite` outside OpenCode/Crush parsers** — SQLite is only needed for those two tools. Do not spread this dependency.
52- **Embedding secrets in handoff markdown** — `.continues-handoff.md` is written to project directories and may be committed or read by other AI tools.
53
yigitkonur/cli-continues · .github/instructions/ci.instructions.md
@@ +1 @@
1---
2applyTo: ".github/workflows/**/*.{yml,yaml}"
3---
4
5# CI Workflow Review Guidelines
6
7## Security
8
9- Pin action versions to at least a named tag (`actions/checkout@v4`); prefer full commit SHA for security-critical actions
10- Set `permissions` explicitly on any job that needs elevated access (e.g., `pull-requests: write`) — do not rely on repository-wide defaults
11- Never print secret values to logs — use GitHub's secret masking for dynamic secrets
12
13```yaml
14# Prefer explicit permissions scoping
15permissions:
16 pull-requests: write
17 contents: read
18```
19
20## Node.js Version Requirements
21
22- Node 22 is the minimum supported version (`engines.node >= 22.0.0` in `package.json`)
23- The CI matrix must include at least Node 22 and the latest even-numbered LTS — do not drop below 22
24- `node:sqlite` (built-in, Node 22.5+) is used by OpenCode and Crush parsers — do not add third-party SQLite packages
25
26## Package Manager
27
28- Use `pnpm` exclusively — not `npm ci` or `yarn` — to stay consistent with `pnpm-lock.yaml`
29- Always run `pnpm install --frozen-lockfile` in CI to prevent accidental lockfile mutations
30- Use `pnpm/action-setup@v4` for pnpm setup
31
32## Build and Test Order
33
34- Run `pnpm run build` (TypeScript compile) before `pnpm test` — `tsc` validates type correctness; test failures may be caused by type errors caught at build time
35- The `test-quality` job posts a PR comment summarizing test counts and flags source-file changes without corresponding test changes — do not remove this job without an equivalent replacement
36- The `test-quality` job should only run on `pull_request` events (not push to `main`)
37
@@ −1 +1 @@
1−# AGENTS.md
1+---
2+applyTo: ".github/workflows/**/*.{yml,yaml}"
3+---
24
3−Agent behavior instructions for `continues` — the cross-tool AI session handoff CLI. Read `CLAUDE.md` for architecture, types, and the step-by-step guide for adding a new parser. This file covers workflow, coding standards, and anti-patterns.
5+# CI Workflow Review Guidelines
46
5−## Workflow
7+## Security
68
7−- **Before any commit**: run `pnpm run check` (`pnpm lint && pnpm build`). Fix all Biome errors; warnings are advisory.
8−- **After changing a parser or fixture**: run `pnpm test` and confirm all tests pass. Do not commit with failing tests.
9−- **After adding a new tool**: run `pnpm run link` to test the global `continues` / `cont` binary locally.
10−- **Never run** `pnpm run test:watch`, `e2e-conversions.test.ts`, `real-e2e-full.ts`, or `stress-test.ts` in CI — these require live session files on the developer's machine.
9+- Pin action versions to at least a named tag (`actions/checkout@v4`); prefer full commit SHA for security-critical actions
10+- Set `permissions` explicitly on any job that needs elevated access (e.g., `pull-requests: write`) — do not rely on repository-wide defaults
11+- Never print secret values to logs — use GitHub's secret masking for dynamic secrets
1112
12−## Coding Standards
13+```yaml
14+# Prefer explicit permissions scoping
15+permissions:
16+ pull-requests: write
17+ contents: read
18+```
1319
14−- **ESM-only**: all local imports must end in `.js`, even for `.ts` source files (e.g., `import { foo } from './foo.js'`).
15−- **No `any`**: Biome reports `noExplicitAny` as a warning. Avoid it; document the reason if unavoidable.
16−- **Exit codes**: set `process.exitCode = N` rather than calling `process.exit(N)`.
17−- **Logging**: use `logger` from `src/logger.ts` for all diagnostic output. Never use bare `console.log`/`console.warn`/`console.error` in library code. TUI display goes through `@clack/prompts` or `chalk` via the display layer.
18−- **Error types**: throw typed errors from `src/errors.ts` on user-facing paths, not bare `new Error()`.
19−- **Tool activity**: use `SummaryCollector` from `src/utils/tool-summarizer.ts` in every parser. Do not build `ToolUsageSummary[]` arrays manually.
20−- **JSONL**: use the shared streaming helpers in `src/utils/jsonl.ts`, never `fs.readFileSync` + `split('\n')`.
21−- **SQLite** (OpenCode, Crush parsers): use built-in `node:sqlite` — do not add third-party SQLite dependencies.
22−- **Biome rules in force**: `noEmptyBlockStatements` (error), `noUnusedImports` (error), `useConst` (error). Empty `catch {}` blocks fail the linter; use `catch (err) { logger.debug(...) }` instead.
20+## Node.js Version Requirements
2321
24−## Adding a New Tool — Checklist
22+- Node 22 is the minimum supported version (`engines.node >= 22.0.0` in `package.json`)
23+- The CI matrix must include at least Node 22 and the latest even-numbered LTS — do not drop below 22
24+- `node:sqlite` (built-in, Node 22.5+) is used by OpenCode and Crush parsers — do not add third-party SQLite packages
2525
26−All five steps are required. Missing any one is a bug. See `CLAUDE.md` for detailed implementation guidance.
26+## Package Manager
2727
28−1. Add tool name to `TOOL_NAMES` in `src/types/tool-names.ts`
29−2. Create `src/parsers/<tool>.ts` exporting `parse<Tool>Sessions()` and `extract<Tool>Context()`
30−3. Register in `src/parsers/registry.ts` (the completeness assertion throws at module load if missing)
31−4. Add `create<Tool>Fixture()` in `src/__tests__/fixtures/index.ts`
32−5. Add conversion test cases in `src/__tests__/unit-conversions.test.ts`
28+- Use `pnpm` exclusively — not `npm ci` or `yarn` — to stay consistent with `pnpm-lock.yaml`
29+- Always run `pnpm install --frozen-lockfile` in CI to prevent accidental lockfile mutations
30+- Use `pnpm/action-setup@v4` for pnpm setup
3331
34−## Dependencies
32+## Build and Test Order
3533
36−- **`@clack/prompts`** — all interactive TUI prompts and spinners. Do not use `readline` or `inquirer`.
37−- **`chalk`** — terminal color. Chalk v4 is installed (CommonJS compat import); do not upgrade to v5+ (ESM-only).
38−- **`commander`** — CLI argument parsing.
39−- **`ora`** — non-interactive spinners.
40−- **`yaml`** — YAML parsing for Copilot sessions.
41−- **`zod`** — runtime schema validation. Use `z.safeParse()` where failures are recoverable.
42−- Do not add new runtime dependencies without strong justification. The install footprint is intentionally small.
43−
44−## Anti-Patterns to Avoid
45−
46−- **Writing to tool storage directories** — the tool is read-only. Any write to `~/.claude/`, `~/.codex/`, etc. is a severe bug.
47−- **`exec()` with string interpolation** — always use `spawn()` with an argument array in `resume.ts`. Session IDs and paths can contain shell metacharacters.
48−- **`fs.readFileSync`/`fs.writeFileSync` in parsers** — these block the event loop. Use async fs APIs or shared streaming helpers.
49−- **Duplicating parser-helpers** — `cleanSummary`, `extractRepoFromCwd`, `homeDir` live in `src/utils/parser-helpers.ts`. Import them; do not reimplement.
50−- **Hardcoding tool names** — derive from `TOOL_NAMES` or `SessionSource`. Never write `if (tool === 'claude' || tool === 'codex' || ...)`.
51−- **Importing `node:sqlite` outside OpenCode/Crush parsers** — SQLite is only needed for those two tools. Do not spread this dependency.
52−- **Embedding secrets in handoff markdown** — `.continues-handoff.md` is written to project directories and may be committed or read by other AI tools.
34+- Run `pnpm run build` (TypeScript compile) before `pnpm test` — `tsc` validates type correctness; test failures may be caused by type errors caught at build time
35+- The `test-quality` job posts a PR comment summarizing test counts and flags source-file changes without corresponding test changes — do not remove this job without an equivalent replacement
36+- The `test-quality` job should only run on `pull_request` events (not push to `main`)
5337
