diff --git a/.agents/scripts/instructions.test.ts b/.agents/scripts/instructions.test.ts new file mode 100644 index 0000000..1449a29 --- /dev/null +++ b/.agents/scripts/instructions.test.ts @@ -0,0 +1,172 @@ +// Instructions that name files or commands that don't exist send agents in circles. This checks +// every path, link and `npm run` script named in the agent-facing docs, and the skills' shape. + +import { existsSync, lstatSync, readdirSync, readFileSync, readlinkSync } from 'node:fs' +import { basename, dirname, join, relative, resolve } from 'node:path' +import { describe, expect, it } from 'vitest' +import { git } from './lib/git.ts' +import { REPO_ROOT } from './lib/test-repo.ts' +import { AGENT_DOCS } from './lib/tree.ts' + +const SKILLS_DIR = join(REPO_ROOT, '.agents/skills') +const skills = readdirSync(SKILLS_DIR).filter((name) => !name.startsWith('.')) + +function markdownFiles(dir: string): string[] { + return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => { + const path = join(dir, entry.name) + if (entry.isDirectory()) return markdownFiles(path) + return entry.name.endsWith('.md') ? [path] : [] + }) +} + +// The same list that makes verify treat these docs as code, so a doc checked here can't be +// skipped there as docs-only. +const DOCS = [ + ...[...AGENT_DOCS].map((path) => join(REPO_ROOT, path)), + ...markdownFiles(join(REPO_ROOT, '.agents')), +] + +const tracked = git(REPO_ROOT, ['ls-files', '--cached', '--others', '--exclude-standard']) + .stdout.split('\n') + .filter(Boolean) +const scripts = Object.keys( + ( + JSON.parse(readFileSync(join(REPO_ROOT, 'package.json'), 'utf8')) as { + scripts: Record + } + ).scripts, +) + +const ROOTED = /^(src|scripts|docs|\.agents|\.github|\.claude|\.codex|\.cursor)\// +const FILE_NAME = /^[\w.-]+\.(md|json|ts|tsx|js|cjs|mjs|sh|yml|yaml)$/ +// A path relative to the document, like `references/test-rules.md` in a skill. +const RELATIVE_FILE = /^[\w.-]+(\/[\w.-]+)+\.(md|json|ts|sh)$/ +// Output and state that exist only after a build or run. +const GENERATED = /^(\.tmp|tmp|dist|node_modules)(\/|$)/ + +type Reference = { path: string; line?: number } + +/** Paths named in backticks, with an optional `:line`. Placeholders (``, `*`) are skipped. */ +function namedPaths(text: string): Reference[] { + return [...text.matchAll(/`([^`\s]+)`/g)] + .map((match) => match[1] ?? '') + .filter((value) => !/[<>*{}]/.test(value) && !GENERATED.test(value)) + .map((value) => { + const [, path = value, line] = value.match(/^(.*?):(\d+)$/) ?? [] + return { path, line: line ? Number(line) : undefined } + }) + .filter(({ path }) => ROOTED.test(path) || FILE_NAME.test(path) || RELATIVE_FILE.test(path)) +} + +// CODEBASE.md names files relative to the folder its section describes (`lib/refs.ts`, +// `users.ts` in the src/lib/ catalog), so short paths resolve against these too. +const BASES = ['', 'src/', 'src/lib/', 'src/commands/'] + +/** The repository path a reference names, or why it doesn't resolve. */ +function resolveReference(path: string, doc: string): string | { problem: string } { + if (!ROOTED.test(path) && path.includes('/')) { + const local = relative(REPO_ROOT, resolve(dirname(doc), path)) + if (existsSync(join(REPO_ROOT, local))) return local + } + if (ROOTED.test(path)) { + return existsSync(join(REPO_ROOT, path)) ? path : { problem: 'does not exist' } + } + const based = BASES.map((base) => `${base}${path}`).find((candidate) => + existsSync(join(REPO_ROOT, candidate)), + ) + if (based) return based + if (path.includes('/')) return { problem: 'does not exist' } + const matches = tracked.filter((candidate) => basename(candidate) === path) + if (matches.length === 1) return matches[0] ?? path + return { + problem: matches.length === 0 ? 'does not exist' : `is ambiguous: ${matches.join(', ')}`, + } +} + +function brokenReferences(text: string, doc: string): string[] { + return namedPaths(text).flatMap(({ path, line }) => { + const resolved = resolveReference(path, doc) + if (typeof resolved !== 'string') return [`${path} ${resolved.problem}`] + if (line === undefined) return [] + const full = join(REPO_ROOT, resolved) + if (lstatSync(full).isDirectory()) return [`${path}:${line} names a line in a folder`] + const lines = readFileSync(full, 'utf8').split('\n').length + return line > lines ? [`${path}:${line} is past the end (${lines} lines)`] : [] + }) +} + +/** Backticked names in the bullet list under a heading. */ +function listedUnder(text: string, heading: string): string[] { + const section = text.split(heading)[1]?.split(/\n#{1,3} /)[0] ?? '' + return [...section.matchAll(/^- `([\w-]+)`/gm)].map((match) => match[1] ?? '') +} + +describe.each(DOCS.map((path) => [relative(REPO_ROOT, path), path]))('%s', (_name, path) => { + const text = readFileSync(path, 'utf8') + + it('names only files and lines that exist', () => { + expect(brokenReferences(text, path)).toEqual([]) + }) + + it('links only to files that exist', () => { + const links = [...text.matchAll(/\]\(([^)#\s]+)(#[^)]*)?\)/g)] + .map((match) => match[1] ?? '') + .filter((link) => !/^[a-z]+:/.test(link)) + expect(links.filter((link) => !existsSync(resolve(dirname(path), link)))).toEqual([]) + }) + + it('names only npm scripts that exist', () => { + const named = [...text.matchAll(/npm run (?:--silent )?([\w:-]+)/g)].map((m) => m[1] ?? '') + expect(named.filter((script) => !scripts.includes(script))).toEqual([]) + }) +}) + +describe.each(skills)('skill %s', (skill) => { + const file = join(SKILLS_DIR, skill, 'SKILL.md') + const text = readFileSync(file, 'utf8') + const frontmatter = text.match(/^---\n([\s\S]*?)\n---\n/)?.[1] ?? '' + + it('has a name matching its folder and a description that says when to use it', () => { + expect(frontmatter).toMatch(new RegExp(`^name: ${skill}$`, 'm')) + const description = frontmatter.match(/^description: (.+)$/m)?.[1] ?? '' + expect(description).toContain('Use when') + expect(description.length).toBeLessThan(400) + }) + + it('is linked for Claude Code', () => { + const link = join(REPO_ROOT, '.claude/skills', skill) + expect(lstatSync(link).isSymbolicLink()).toBe(true) + expect(resolve(dirname(link), readlinkSync(link))).toBe(join(SKILLS_DIR, skill)) + }) +}) + +it('lists every skill in AGENTS.md, and only those', () => { + const text = readFileSync(join(REPO_ROOT, 'AGENTS.md'), 'utf8') + expect(listedUnder(text, '## Skills').toSorted()).toEqual(skills.toSorted()) +}) + +it('names only test helpers that the fixtures, global-args or @doist/cli-core/testing export', async () => { + const skill = readFileSync(join(SKILLS_DIR, 'write-tests/SKILL.md'), 'utf8') + const section = skill.split('## Helpers')[1]?.split('\n## ')[0] ?? '' + const named = [...section.matchAll(/`(\w+)`/g)].map((match) => match[1] ?? '') + const fixtures = join(REPO_ROOT, 'src/lib/__fixtures__') + const sources = [ + ...readdirSync(fixtures).map((file) => join(fixtures, file)), + join(REPO_ROOT, 'src/lib/global-args.ts'), + ] + const local = sources.flatMap((file) => + [ + ...readFileSync(file, 'utf8').matchAll( + /^export (?:async )?(?:function|const|type) (\w+)/gm, + ), + ].map((match) => match[1]), + ) + const shared = Object.keys(await import('@doist/cli-core/testing')) + expect(named.length).toBeGreaterThan(5) + expect(named.filter((name) => !local.includes(name) && !shared.includes(name))).toEqual([]) +}) + +it('has no Claude Code skill link without a skill behind it', () => { + const links = readdirSync(join(REPO_ROOT, '.claude/skills')) + expect(links.toSorted()).toEqual(skills.toSorted()) +}) diff --git a/.agents/scripts/lib/tree.test.ts b/.agents/scripts/lib/tree.test.ts index ddde543..ef10bb2 100644 --- a/.agents/scripts/lib/tree.test.ts +++ b/.agents/scripts/lib/tree.test.ts @@ -2,7 +2,14 @@ import { rmSync, utimesSync } from 'node:fs' import { join } from 'node:path' import { afterEach, beforeEach, describe, expect, it } from 'vitest' import { createTempRepo, type TempRepo } from './test-repo.ts' -import { changedPaths, changedSince, classify, codeFingerprint, snapshot } from './tree.ts' +import { + changedCodePaths, + changedPaths, + changedSince, + classify, + codeFingerprint, + snapshot, +} from './tree.ts' let repo: TempRepo @@ -60,16 +67,35 @@ describe('snapshot', () => { }) describe('codeFingerprint', () => { - it('ignores docs and files only CI reads, and nothing else', () => { + it('ignores edits to docs and files only CI reads, and nothing else', () => { const before = codeFingerprint(snapshot(repo.dir)) repo.write('README.md', 'changed\n') - repo.write('docs/guide.md', 'new\n') repo.write('renovate.json', '{}\n') repo.write('.github/CODEOWNERS', '* @example\n') expect(codeFingerprint(snapshot(repo.dir))).toBe(before) - repo.write('src/prompt.md', 'markdown the server could load\n') + repo.write('src/prompt.md', 'markdown the CLI could load\n') expect(codeFingerprint(snapshot(repo.dir))).not.toBe(before) }) + + it('changes when a doc is added or deleted, since the agent docs may name it', () => { + const before = codeFingerprint(snapshot(repo.dir)) + repo.write('docs/guide.md', 'new\n') + expect(codeFingerprint(snapshot(repo.dir))).not.toBe(before) + rmSync(join(repo.dir, 'docs/guide.md')) + expect(codeFingerprint(snapshot(repo.dir))).toBe(before) + rmSync(join(repo.dir, 'README.md')) + expect(codeFingerprint(snapshot(repo.dir))).not.toBe(before) + }) +}) + +describe('changedCodePaths', () => { + it('counts a deleted doc, but not an edited or added one', () => { + const before = snapshot(repo.dir) + repo.write('docs/guide.md', 'new\n') + expect(changedCodePaths(before, snapshot(repo.dir))).toEqual([]) + rmSync(join(repo.dir, 'README.md')) + expect(changedCodePaths(before, snapshot(repo.dir))).toEqual(['README.md']) + }) }) describe('classify', () => { @@ -78,8 +104,11 @@ describe('classify', () => { ['CHANGELOG.md', 'docs'], ['docs/SPEC.md', 'docs'], ['CONTRIBUTING.md', 'docs'], - ['CODEBASE.md', 'docs'], ['docs/icon.md', 'docs'], + ['AGENTS.md', 'code'], + ['CODEBASE.md', 'code'], + ['docs/agents.md', 'code'], + ['.agents/skills/verify/SKILL.md', 'code'], ['.github/PULL_REQUEST_TEMPLATE.md', 'docs'], ['LICENSE', 'docs'], ['.github/workflows/lint.yml', 'code'], diff --git a/.agents/scripts/lib/tree.ts b/.agents/scripts/lib/tree.ts index 6e8d165..b8a0220 100644 --- a/.agents/scripts/lib/tree.ts +++ b/.agents/scripts/lib/tree.ts @@ -2,7 +2,7 @@ // made in the same second, and hashing in-process writes nothing to git's object store. import { createHash } from 'node:crypto' -import { lstatSync, readFileSync, readlinkSync } from 'node:fs' +import { existsSync, lstatSync, readFileSync, readlinkSync } from 'node:fs' import { join } from 'node:path' import { git } from './git.ts' @@ -44,17 +44,23 @@ export const CHECKED_WORKFLOWS = [ '.github/workflows/test.yml', ] +/** Agent instructions outside .agents/. instructions.test.ts checks every reference in them. */ +export const AGENT_DOCS = new Set(['AGENTS.md', 'CODEBASE.md', 'docs/agents.md']) + /** The kind of file, as far as local checks are concerned. */ export type FileKind = 'docs' | 'unchecked' | 'code' /** - * - docs: prose no check reads. Markdown under src/ is excluded, since it could be loaded at runtime. + * - docs: prose no check reads. Markdown under src/ is excluded, since it could be loaded at runtime, + * and so are the agent instructions, which a test reads. * - unchecked: files only CI or GitHub reads (Renovate, other .github/ config). Local verification * cannot vouch for them. * - code: everything else, including config, lockfiles, the generated skill and tests. */ export function classify(path: string): FileKind { if (path.startsWith('.github/workflows/')) return 'code' + // .agents/scripts/instructions.test.ts checks every reference in these. + if (AGENT_DOCS.has(path) || path.startsWith('.agents/')) return 'code' // `npm run check:skill-sync` compares it with src/lib/skills/content.ts. if (path.startsWith('skills/')) return 'code' if (path.startsWith('.github/')) return path.endsWith('.md') ? 'docs' : 'unchecked' @@ -64,21 +70,31 @@ export function classify(path: string): FileKind { return 'code' } +const present = (files: Snapshot, path: string) => + files[path] !== undefined && files[path] !== 'missing' + /** * Hash of every file local checks read, so editing docs, or files only CI reads, after a pass - * keeps it valid. + * keeps it valid. Docs count by name: the agent docs may name one, so adding, renaming or deleting + * a doc means checking again. */ export function codeFingerprint(files: Snapshot): string { const hash = createHash('sha256') for (const path of Object.keys(files).sort()) { - if (classify(path) === 'code') hash.update(`${path}\0${files[path]}\n`) + const kind = classify(path) + if (kind === 'code') hash.update(`${path}\0${files[path]}\n`) + else if (kind === 'docs' && present(files, path)) hash.update(`${path}\0doc\n`) } return hash.digest('hex') } /** Changed files local checks read. */ export function changedCodePaths(before: Snapshot, after: Snapshot): string[] { - return changedPaths(before, after).filter((path) => classify(path) === 'code') + return changedPaths(before, after).filter( + (path) => + classify(path) === 'code' || + (classify(path) === 'docs' && present(before, path) && !present(after, path)), + ) } export function changedPaths(before: Snapshot, after: Snapshot): string[] { @@ -86,6 +102,15 @@ export function changedPaths(before: Snapshot, after: Snapshot): string[] { return [...paths].filter((path) => before[path] !== after[path]).sort() } +/** + * Whether a file that differs from the default branch needs the checks: code, or a doc that was + * deleted or renamed, since the agent docs may name it. + */ +export function needsChecks(root: string, path: string): boolean { + const kind = classify(path) + return kind === 'code' || (kind === 'docs' && !existsSync(join(root, path))) +} + /** Files that differ from `base`: committed, staged, unstaged and untracked. */ export function changedSince(root: string, base: string): string[] { const diff = git(root, ['diff', '--name-only', '-z', '--no-renames', base]) diff --git a/.agents/scripts/lib/verify.test.ts b/.agents/scripts/lib/verify.test.ts index 8336dea..0b402a9 100644 --- a/.agents/scripts/lib/verify.test.ts +++ b/.agents/scripts/lib/verify.test.ts @@ -1,4 +1,4 @@ -import { existsSync, readFileSync } from 'node:fs' +import { existsSync, readFileSync, rmSync } from 'node:fs' import { join } from 'node:path' import { afterEach, beforeEach, describe, expect, it } from 'vitest' import { readVerified, stateDir, writeVerified } from './state.ts' @@ -173,6 +173,11 @@ describe('what counts as a change', () => { expect(await verify([pass('lint')])).toEqual({ ok: true, recorded: true }) }) + it('runs the checks when a doc is deleted, since the agent docs may name it', async () => { + rmSync(join(repo.dir, 'README.md')) + expect(await verify([pass('lint')])).toEqual({ ok: true, recorded: true }) + }) + it('has nothing to check for a docs-only change', async () => { repo.write('README.md', 'changed\n') const result = await verify([fail('lint')]) diff --git a/.agents/scripts/lib/verify.ts b/.agents/scripts/lib/verify.ts index c42f197..4efd280 100644 --- a/.agents/scripts/lib/verify.ts +++ b/.agents/scripts/lib/verify.ts @@ -3,7 +3,14 @@ import { createWriteStream, mkdirSync, readFileSync } from 'node:fs' import { join, relative } from 'node:path' import { cleanGitEnv, git } from './git.ts' import { clearVerified, stateDir, writeVerified } from './state.ts' -import { changedCodePaths, changedSince, classify, codeFingerprint, snapshot } from './tree.ts' +import { + changedCodePaths, + changedSince, + classify, + codeFingerprint, + needsChecks, + snapshot, +} from './tree.ts' export type Step = { name: string @@ -36,7 +43,9 @@ export async function runVerify(options: VerifyOptions): Promise { out(`No ${baseName} branch found, so checking the whole tree.`) } else { const changes = changedSince(root, base) - const kinds = new Set(changes.map(classify)) + const kinds = new Set( + changes.map((path) => (needsChecks(root, path) ? 'code' : classify(path))), + ) if (changes.length > 0 && !kinds.has('code')) { if (kinds.has('unchecked')) { const unchecked = changes.filter((path) => classify(path) === 'unchecked') diff --git a/.agents/skills/add-command/SKILL.md b/.agents/skills/add-command/SKILL.md index 34b0aab..be314f3 100644 --- a/.agents/skills/add-command/SKILL.md +++ b/.agents/skills/add-command/SKILL.md @@ -41,7 +41,7 @@ src/commands// - **Subcommand files**: Export one async action handler + any option interfaces. Use `../../lib/` for lib imports. No Commander imports (only index.ts uses Commander). - **helpers.ts**: Only needed when multiple subcommands share a utility/constant. -Single-subcommand commands (e.g., `channel.ts`, `inbox.ts`) remain as flat files. +Single-subcommand commands (e.g., `react.ts`, `inbox.ts`) remain as flat files. ### Adding a subcommand to an existing command @@ -128,7 +128,7 @@ const commands: Record Promise<(p: Command) => void>]> = ## 4. Accessibility (`src/lib/output.ts`) -The CLI supports accessible mode via `isAccessible()` (checks `TDC_ACCESSIBLE=1` or `--accessible` flag). When adding output that uses color or visual elements, consider whether information is conveyed **only** by color or decoration. +The CLI supports accessible mode via `isAccessible()` from `src/lib/global-args.ts` (checks `TDC_ACCESSIBLE=1` or `--accessible` flag). When adding output that uses color or visual elements, consider whether information is conveyed **only** by color or decoration. ### When to add accessible alternatives @@ -145,16 +145,16 @@ The CLI supports accessible mode via `isAccessible()` (checks `TDC_ACCESSIBLE=1` ### Pattern ```typescript -import { isAccessible } from '../lib/output.js' +import { isAccessible } from '../lib/global-args.js' const a11y = isAccessible() const prefix = a11y ? '[!] ' : '' console.log(chalk.yellow(`${prefix}Warning: thread is archived`)) ``` -## 5. Tests (`src/__tests__/.test.ts`) +## 5. Tests (next to the command, e.g. `src/commands//.test.ts`) -Tests mock the API layer directly using `vi.mock` and `vi.hoisted`. Follow the existing pattern in test files like `thread.test.ts` or `conversation.test.ts`. +Tests mock the API layer directly using `vi.mock` and `vi.hoisted`. Follow the existing pattern in test files like `thread.test.ts` or `conversation.test.ts`. The `write-tests` skill has the helpers and the quality bar. ### Test setup pattern @@ -223,7 +223,7 @@ This builds the project and regenerates `skills/comms-cli/SKILL.md` from the com ## 8. Verify ```bash -npm run type-check -npm test -npm run lint:check +npm run verify ``` + +Then follow the `verify` skill to prove the command does what was asked. diff --git a/.agents/skills/build-feature/SKILL.md b/.agents/skills/build-feature/SKILL.md new file mode 100644 index 0000000..62ff839 --- /dev/null +++ b/.agents/skills/build-feature/SKILL.md @@ -0,0 +1,39 @@ +--- +name: build-feature +description: Builds a new command, flag or behaviour in thin test-first slices, after settling the open decisions with the owner. Use when asked to "add", "build", "implement", "support" or "create" something, such as a new command, subcommand or flag. +--- + +# Build a feature + +## 1. Read the closest existing feature + +Find the command most like the one you are building and read it with its test: `src/commands/status/set.ts` for a write with `--json` and `--full`, `src/commands/inbox.ts` for a list, `src/commands/msg/delete.ts` for a destructive write behind `--yes`. For a new command or subcommand, `add-command` is the checklist of every file to touch. Read the rules in `AGENTS.md`. Done when you can name the file you will copy patterns from. + +## 2. Settle decisions in one round + +List what the request leaves open: command and flag names (consistent verbs and flags across entities), positional argument or named flag, the human and `--json` output, error codes, `--dry-run` and `--yes`, behaviour under a read-only token, and whether private channels change the answer. Ask the owner all of them at once, each with your recommendation. Don't ask what the code can answer. Done when every decision has an answer. + +## 3. Write "done" as checkable behaviours + +Write each behaviour as a command and the expected result, for example: "`tdc msg delete 200 --yes` calls `deleteMessage('200')` and prints `Message 200 deleted.`". Each becomes a test. Done when a test could pass or fail on every one. + +## 4. Build in thin slices, test first + +For each behaviour: write its test at the public interface (`program.parseAsync(['node', 'tdc', ...])`), see it fail, make it pass, run its test file. Follow `write-tests`. Done when every behaviour from step 3 has a passing test you saw fail. + +## 5. Update everything the change touches + +| You changed | Also update | +| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| A command, subcommand or flag | `SKILL_CONTENT` in `src/lib/skills/content.ts`, then `npm run sync:skill` | +| Called a new SDK method | `API_SPINNER_MESSAGES` in `src/lib/api.ts`; a read-only one goes in `KNOWN_SAFE_API_METHODS` (`src/lib/permissions.ts`) | +| A mutating command | `--json` through `MutationOptions` (`src/lib/options.ts`) and `formatJson()`, as "JSON output on mutating commands" in `AGENTS.md` says | +| Output that uses colour or symbols | An `--accessible` alternative (`isAccessible()` from `src/lib/global-args.ts`); never an id and a name told apart by colour alone | +| A new error code | The `ErrorCode` type in `src/lib/errors.ts` | +| Structure (new folder or helper) | `CODEBASE.md` | + +Done when each row that applies is handled. + +## 6. Verify and report + +Follow `verify`. If the feature needs restructuring first, do that as a separate change with `refactor`. diff --git a/.agents/skills/fix-bug/SKILL.md b/.agents/skills/fix-bug/SKILL.md new file mode 100644 index 0000000..b19d9ce --- /dev/null +++ b/.agents/skills/fix-bug/SKILL.md @@ -0,0 +1,40 @@ +--- +name: fix-bug +description: Fixes a bug by reproducing it in a failing test first, then making the smallest change that turns it green. Use when something is "broken", "wrong", "fails", "doesn't work", throws an error, or a user or issue reports a bug. +--- + +# Fix a bug + +## 1. Restate the symptom + +Write down what happens, what should happen, and the command that triggers it (`tdc `). If the report is vague, restate it to the owner and ask before going further. Done when the symptom fits in one sentence. + +## 2. Reproduce it in a test + +Write a test that fails on the exact symptom, at the lowest layer that shows it: + +- a helper in `src/lib/` → its `*.test.ts` next to it; +- a command's flags, API calls or output → the command's test, through `program.parseAsync(['node', 'tdc', ...])` with a mocked `getCommsClient`; +- the entry point (argv handling, the early spinner, parse errors) → `src/index.test.ts`. + +Follow `write-tests` for helpers and the quality bar. Run the test and see it fail **for the reason in step 1**, not a typo or a missing mock. Done when the failure message describes the bug. + +## 3. Find the root cause + +Trace from the symptom to the first place the data goes wrong. Name it with `path:line`. A fix at the symptom (a special case, a retry, a try/catch) is not a root cause. Done when you can say why the code does what it does. + +## 4. Make the smallest fix + +Change only what the root cause needs. Note other bugs you find for a separate fix; don't fix them here. Restructuring goes to `refactor`, as its own change. + +## 5. Prove the fix is needed + +Undo the fix: the test fails. Restore it: the test passes. Then `npm run verify`. Done when you have seen both and verify prints `Verified.` + +## When it doesn't work + +After three fixes that didn't turn the test green, stop. Your model of the bug is wrong. Re-read the failing output, question the test, and list what you have ruled out before trying again. Tell the owner if you're stuck. + +## Report + +Use the `verify` report format. Include the test name, the root cause line, and the undo/restore result. diff --git a/.agents/skills/learn/SKILL.md b/.agents/skills/learn/SKILL.md new file mode 100644 index 0000000..1cdef18 --- /dev/null +++ b/.agents/skills/learn/SKILL.md @@ -0,0 +1,34 @@ +--- +name: learn +description: Turns a correction or a repeated mistake into the strongest structure that prevents it, and proves it catches the mistake. Use when the owner says "don't do that again", "remember this", "you keep doing X", or a review finds the same problem twice. +--- + +# Learn from a mistake + +## 1. Name the mistake + +Write the mistake as a check: "a command reads `.data` on a batch result", not "be careful with batch calls". Done when a script could, in principle, detect it. + +## 2. Pick the strongest structure that holds it + +In this order, take the first that works: + +1. **A type** the compiler rejects. +2. **A lint rule** in `.oxlintrc.json`. +3. **A test** that scans the code or checks a contract across it, like `src/lib/oauth-client-metadata.test.ts`, which checks the published OAuth metadata against the code. +4. **A script check** in `.agents/scripts/` (verify, a hook). +5. **A line in `AGENTS.md` or a skill**, only if nothing above can hold it. + +A rule already written down that still got broken skips straight to 1–4. Done when you can say why the stronger options don't fit. + +## 3. Prove it catches the mistake + +Make the mistake on purpose. The new structure must fail on it. Remove it: it passes. Run `npm run verify`. Done when you have seen both. + +## 4. Delete what it replaces + +Remove instruction lines the new check makes redundant, in `AGENTS.md` or the skills. Update the rules table in `docs/agents.md`: the rule, what holds it, and how certain it is. + +## 5. Ship it on its own + +One small pull request for the new structure, titled `chore:` or `test:` so it does not release. Done when its diff contains only this rule. diff --git a/.agents/skills/refactor/SKILL.md b/.agents/skills/refactor/SKILL.md new file mode 100644 index 0000000..a45e0e4 --- /dev/null +++ b/.agents/skills/refactor/SKILL.md @@ -0,0 +1,32 @@ +--- +name: refactor +description: Changes the structure of code without changing its behaviour, with the current behaviour pinned by tests first. Use when asked to "refactor", "clean up", "simplify", "extract", "rename", "move" or "deduplicate" code, or when another task needs restructuring first. +--- + +# Refactor + +A refactor changes structure, not behaviour. Bugs included: if you find one, note it for a separate fix and keep it as it is. + +## 1. Pin the current behaviour + +Find the tests that cover the code at its public interface: the command run through `program.parseAsync(['node', 'tdc', ...])`, or the exported helper. Where a behaviour has no test, add one that passes **now**, asserting what the code does today. Run them. Done when every behaviour you will touch has a passing test. + +## 2. Delete dead code first + +Remove code nothing reaches, if you can prove it: no caller (`rg` for every name, including the lazy command registry in `src/index.ts` and `scripts/`). Run the tests. Done when they pass. + +## 3. Move one concept at a time + +Make one structural change, run the pinned tests, repeat. Migrate every caller and delete the old API; no shims left behind. Command names, flags, `--json` output shapes and error codes are what people's scripts and agents rely on, and `SKILL_CONTENT` documents them: keep them, or stop and ask (changing them is a breaking `feat!:` release). Done when the tests pass after each step and no caller uses the old shape. + +## 4. Leave the tests alone + +Existing tests may change how they reach the code: import paths, names, call sites. They may not change their inputs or their assertions, including every expected output string. If an expected value changes, the behaviour changed: stop and say so. + +## 5. Keep it only if it reads better + +Name what got easier to read or change. If you can't, revert. Done when you can say it in one sentence. + +## 6. Verify + +`npm run verify`, then report with the `verify` format. Say which tests pinned the behaviour, and confirm `git diff` shows no change to any test input or assertion. diff --git a/.agents/skills/verify/SKILL.md b/.agents/skills/verify/SKILL.md new file mode 100644 index 0000000..31c3b0f --- /dev/null +++ b/.agents/skills/verify/SKILL.md @@ -0,0 +1,57 @@ +--- +name: verify +description: Proves a change works before it is called done, and reports the evidence on a ladder from "said" to "ran". Use when you are about to say "done", "fixed", "works" or "ready", when asked to check or test a change, or before opening a pull request. +--- + +# Verify a change + +## 1. Run the checks + +```bash +npm run verify +``` + +It runs every check CI runs (about ten seconds) and records the pass. Fix every failure; never weaken a check to pass it. Done when it prints `Verified.`, or says only docs changed and there is nothing to check. + +## 2. Prove the change itself + +The checks prove nothing broke. Now prove the change does what was asked, with the proof its kind needs: + +| Change | Proof | +| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Command behaviour (flags → API call → output) | A test next to the command that runs `program.parseAsync(['node', 'tdc', ...])` and fails without the change (see `src/commands/msg/msg.test.ts`). Undo the change once and see it fail. | +| A helper in `src/lib/` | A test next to it that calls the exported function. | +| `--json` / `--ndjson` output | `JSON.parse` the captured output and assert the whole shape with `toEqual`. Scripts and agents read it. | +| Errors and exit codes | Assert the `CliError` code, and the JSON error output under `--json`. | +| A command or flag added, renamed or removed | `SKILL_CONTENT` in `src/lib/skills/content.ts` updated and `npm run sync:skill` run; verify's skill-sync step checks the result. `node dist/index.js --help` shows the change. | +| A real Comms answer | `npm run build`, then `node dist/index.js `, only on a test workspace. Check `node dist/index.js auth status` first. Ask before writes. | +| Terminal output (colours, spinners, a11y) | Run the command in a real terminal, with and without `--accessible`. Read it as a screen reader would: names first, ids after, no meaning carried by colour alone. | +| Agent tooling (`.agents/scripts`) | Its tests in throwaway repos, plus one real run of the hook or command. | +| Docs only | Every path and command named exists (`ls`, `npm run`). | + +Check the proof can fail: undo the change and see the test fail, or run the scenario that used to break. Done when you have seen it fail and then pass. A refactor is the exception: its proof is the pinned tests passing before and after (see `refactor`). + +## 3. Report the evidence + +Rate every claim on this ladder: + +1. **said:** stated without looking. +2. **cited:** the line that shows it (`path:line`). +3. **traced:** followed the code path through each call. +4. **ran:** a test or command executed the code and showed the result. +5. **seen:** observed in the running CLI, in a real terminal or against a real workspace. + +Claims about behaviour ("fixed", "works", "safe", "no regressions") need **ran** or higher. A fact the code shows needs **cited**. Anything lower goes under **Not verified**, with why. + +For a change to code others rely on (shared helpers in `src/lib/`, command registration and global flags in `src/index.ts`, an `@doist/cli-core` or `@doist/comms-sdk` upgrade), name the one fact that makes it safe, and how you proved it. + +Report format: + +``` +What changed: +Verified: +- — ran: , +Not verified: +- — +Safe because: , (only for shared code) +``` diff --git a/.agents/skills/write-tests/SKILL.md b/.agents/skills/write-tests/SKILL.md new file mode 100644 index 0000000..8a6c1e5 --- /dev/null +++ b/.agents/skills/write-tests/SKILL.md @@ -0,0 +1,30 @@ +--- +name: write-tests +description: Writes or changes tests in this repository to its quality bar, with the right helpers and layer. Use when adding, fixing or reviewing tests, when a change "needs a test", or when deciding whether a test may change. +--- + +# Write tests + +## Where tests live + +- Next to the code: `src/lib/refs.ts` → `src/lib/refs.test.ts`. A command group has one test file (`src/commands/thread/thread.test.ts`). Vitest, globals on. +- Command tests mock the Comms client, never the SDK: `getCommsClient` from `src/lib/api.ts` is swapped through `vi.hoisted` and `vi.mock('../../lib/api.js', …)`, keeping the rest of the module with `importOriginal`, and each test hands it a fake client built for that test. Build the program with `createTestProgram(registerXxxCommand)`, run `program.parseAsync(['node', 'tdc', ...])`, and capture output with `captureConsole()`. Read `src/commands/msg/msg.test.ts` for the shape. +- `src/index.test.ts` imports the entry point with its dependencies mocked, for argv handling and the early spinner. +- `vi.mock('chalk')` uses the manual mock in `src/__mocks__/chalk.ts`, which makes styling a passthrough so tests read plain text. +- Agent tooling tests live in `.agents/scripts/` and run copies of the tools in throwaway repos (`.agents/scripts/lib/test-repo.ts`). + +## Helpers + +From `src/lib/__fixtures__/accounts.ts`: `STORED_ALAN`, `STORED_ELLIE`, `ACCOUNT_ALAN`, `ACCOUNT_ELLIE`. From `@doist/cli-core/testing`: `createTestProgram`, `captureConsole`, `captureStream`, `describeEmptyMachineOutput` (the shared check that `--json` and `--ndjson` print nothing extra for an empty result). Reset global flag state between tests with `resetGlobalArgs` from `src/lib/global-args.ts`. + +## The quality bar + +Read [references/test-rules.md](references/test-rules.md) before writing or reviewing a test. In short: a test counts only if it can fail. It asserts outcomes, takes expected values from outside the code under test, mocks only real boundaries, and you saw it fail once. + +Done when each new test has failed once for the right reason, and then passes. + +## When an existing test may change + +- **The behaviour changed on purpose** (a feature or a fix): change the assertions that describe it, and say which in the report. +- **A refactor:** only how the test reaches the code (imports, names, call sites). Never its inputs or assertions, including expected output strings. +- **Never** to make a failing check pass without a behaviour change: no `.skip`, no deleted test, no looser matcher (`toEqual` → `toMatchObject`, exact arguments → `toHaveBeenCalled()`). diff --git a/.agents/skills/write-tests/references/test-rules.md b/.agents/skills/write-tests/references/test-rules.md new file mode 100644 index 0000000..4340689 --- /dev/null +++ b/.agents/skills/write-tests/references/test-rules.md @@ -0,0 +1,55 @@ +# Test rules + +Calibrated on this repository's tests (about 1,200 in `src/`, November 2026). Each rule says what to flag and what is fine, because a rule that flags good tests teaches agents to damage them. + +## 1. It can fail + +You saw the test fail once: before the fix, or with the feature undone. A test that has never failed may be testing nothing. + +## 2. It asserts outcomes + +Assert what the user sees or what reaches the API: `toHaveBeenCalledWith()`, the exact output line, the parsed `--json` output. Flag an assertion that cannot tell right from wrong. + +| Flag | Fine | +| -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `toHaveBeenCalled()` as the only evidence the behaviour happened: nothing checks the arguments or output | `toHaveBeenCalled()` next to assertions on the arguments or output, when those carry the test's point (`src/commands/thread/thread.test.ts:1118`) | +| | `.not.toHaveBeenCalled()`: proves a call did **not** happen (about 190 in this repo, e.g. `msg delete` without `--yes` never reaches `deleteMessage`, `src/commands/msg/msg.test.ts:106`) | +| `toBeDefined()` / `toBeTruthy()` as the last word on a value | The same as a guard right before reading the value's fields (`src/commands/auth/auth.test.ts:353`) | +| A test whose only assertion is that no error was thrown, when the behaviour is a result | `resolves.not.toThrow()` when accepting the input **is** the behaviour (a validator that must not reject) | + +Judge a test by its point, the behaviour its name describes. A weak assertion beside the ones that carry that point is fine. + +## 3. Expected values come from outside the code under test + +Write the expected value out as literals (a lookup table or `it.each` rows are fine), or build it from fixtures. Flag an expectation that calls the code under test, or recomputes the answer the way the code does (the same formatter, string building or mapping function). + +## 4. Mock only real boundaries + +The real boundary here is the Comms API: `getCommsClient` from `src/lib/api.ts`, mocked with `vi.hoisted` and handed a fake client per test, the standard pattern in every command test. Also boundaries: I/O seams (`src/lib/config.ts`, `src/lib/auth.ts`, `src/lib/input.ts`, `src/lib/markdown.ts`, `node:fs/promises`, `chalk`) and the clock (`vi.useFakeTimers` with `vi.setSystemTime`). `vi.doMock` after `vi.resetModules()` is for modules with import-time side effects (`src/index.test.ts`) or a per-test config path (`src/commands/update/update.test.ts:13`). + +| Flag | Fine | +| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| A **new** `vi.mock` of an internal module that holds logic (refs, output, search helpers), to make setup easier | The boundaries above. Existing mocks of `src/lib/refs.ts` that pin a resolved id (`src/commands/msg/msg.test.ts:13`): tolerated, not a pattern to copy | +| Mocking the function the test is about, or one that computes its expected value | | + +New tests should prefer feeding the fake client over mocking an internal module. + +## 5. No skipped or focused tests + +None exist today. `.only` fails in CI (`CI=true`, which `npm run verify` sets too). Don't add `.skip`, `.todo` or `xit` to get green. Fine: `it.skipIf` for a platform or permission the test cannot run under, with a comment saying so. + +## 6. No fixed sleeps + +There are none. Use fake timers (`src/commands/status/status.test.ts:43`) or wait on the event. Fine: a real wait a fake clock cannot drive, or a short one that proves something did **not** happen. + +## 7. No snapshots + +None exist: tests assert exact output strings or parse JSON output and compare it with `toEqual` (`src/commands/react.test.ts:69`). Keep it that way. A new snapshot records whatever the output is the first time it runs, so it proves nothing about what the output should be. + +## 8. Reading source files is for contracts + +Fine: a test that reads source or config to enforce a rule across the codebase (`src/lib/oauth-client-metadata.test.ts:11` checks the published OAuth metadata against the code; `.agents/scripts/lib/steps.test.ts` reads the workflows). Flag a test that reads a source file to check one function's behaviour; call the function instead. + +## 9. No real user data + +Fixtures use made-up names, emails and IDs (cli-core's fictional accounts, `example.com`). This repository is public: no real people, workspace IDs or internal hosts copied from an account. diff --git a/.claude/skills/add-command b/.claude/skills/add-command new file mode 120000 index 0000000..3daf199 --- /dev/null +++ b/.claude/skills/add-command @@ -0,0 +1 @@ +../../.agents/skills/add-command \ No newline at end of file diff --git a/.claude/skills/add-command/SKILL.md b/.claude/skills/add-command/SKILL.md deleted file mode 100644 index a2077b3..0000000 --- a/.claude/skills/add-command/SKILL.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -name: add-command -description: Guide for adding new CLI commands or subcommands to comms-cli. Use when implementing new SDK endpoints, adding subcommands to existing command groups, or extending CLI functionality. ---- - -See [/.agents/skills/add-command/SKILL.md](../../../.agents/skills/add-command/SKILL.md) for the full guide. diff --git a/.claude/skills/build-feature b/.claude/skills/build-feature new file mode 120000 index 0000000..e35029d --- /dev/null +++ b/.claude/skills/build-feature @@ -0,0 +1 @@ +../../.agents/skills/build-feature \ No newline at end of file diff --git a/.claude/skills/fix-bug b/.claude/skills/fix-bug new file mode 120000 index 0000000..c702683 --- /dev/null +++ b/.claude/skills/fix-bug @@ -0,0 +1 @@ +../../.agents/skills/fix-bug \ No newline at end of file diff --git a/.claude/skills/learn b/.claude/skills/learn new file mode 120000 index 0000000..30dc6e7 --- /dev/null +++ b/.claude/skills/learn @@ -0,0 +1 @@ +../../.agents/skills/learn \ No newline at end of file diff --git a/.claude/skills/refactor b/.claude/skills/refactor new file mode 120000 index 0000000..dc7a9b2 --- /dev/null +++ b/.claude/skills/refactor @@ -0,0 +1 @@ +../../.agents/skills/refactor \ No newline at end of file diff --git a/.claude/skills/verify b/.claude/skills/verify new file mode 120000 index 0000000..326bc3f --- /dev/null +++ b/.claude/skills/verify @@ -0,0 +1 @@ +../../.agents/skills/verify \ No newline at end of file diff --git a/.claude/skills/write-tests b/.claude/skills/write-tests new file mode 120000 index 0000000..97c92c4 --- /dev/null +++ b/.claude/skills/write-tests @@ -0,0 +1 @@ +../../.agents/skills/write-tests \ No newline at end of file diff --git a/.tmp/agents/verified.json b/.tmp/agents/verified.json index 1ee013a..37f7f7f 100644 --- a/.tmp/agents/verified.json +++ b/.tmp/agents/verified.json @@ -1,5 +1,5 @@ { - "fingerprint": "22b68f6e37748075465ac6d2d5838af71407510d54edde729baa3a8543b2f37c", - "head": "ac817c81c8414539e8d3befe94ab94f9018a979f", - "at": "2026-11-05T11:19:06.264Z" + "fingerprint": "eae8377bebc1fb5699671b110c9eb1b24ae0a416b3ee4644193a4725c3a554ee", + "head": "81d004c744d4ec8c799d15c6d20c75d3964de1b9", + "at": "2026-11-05T11:20:19.623Z" } diff --git a/AGENTS.md b/AGENTS.md index 1ca0080..819e3ac 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,18 @@ This file provides guidance to AI coding agents when working with code in this r - **Never weaken a check to pass it.** Don't skip, delete or loosen tests, edit lint, type or test config to get green, or use `--no-verify`. If a check looks wrong, say so and stop. - **Report honestly:** what ran, what it showed, and what you did not verify. +## Skills + +Use the matching skill without being asked. They live in `.agents/skills/` (Claude Code reads them through `.claude/skills/`). + +- `verify`: before saying a change is done, fixed or ready. +- `fix-bug`: something is broken or wrong. +- `build-feature`: a new command, flag or behaviour. +- `add-command`: the checklist of files to touch for a new command or subcommand. +- `refactor`: changing structure without changing behaviour. Other tasks send restructuring here, as a separate change. +- `write-tests`: writing or changing tests; `.agents/skills/write-tests/references/test-rules.md` is the quality bar. +- `learn`: after a correction, to turn it into a check. + ## Commands ```bash @@ -48,7 +60,7 @@ This is a TypeScript CLI (`tdc`) for Comms messaging, built with Commander.js. **Entry point**: `src/index.ts` registers all commands with Commander. -**Commands** (`src/commands/`): Commands with multiple subcommands use a folder-based structure (`src/commands//index.ts`) where the index file exports a `register*Command(program)` function and wires Commander subcommands to handler functions in sibling files. Single-command files remain as flat files (`src/commands/.ts`). Each subcommand handler file exports one async action function and imports from `../../lib/`. An optional `helpers.ts` holds shared constants/utilities used by multiple subcommands. Commands support `--json`, `--ndjson`, and `--full` flags for machine-readable output. +**Commands** (`src/commands/`): Commands with multiple subcommands use a folder-based structure (`src/commands//index.ts`) where the index file exports a `register*Command(program)` function and wires Commander subcommands to handler functions in sibling files. Single-command files remain as flat files (`src/commands/.ts`). Each subcommand handler file exports one async action function and imports from `../../lib/`. An optional `src/commands//helpers.ts` holds shared constants/utilities used by multiple subcommands. Commands support `--json`, `--ndjson`, and `--full` flags for machine-readable output. **Lib** (`src/lib/`): @@ -68,13 +80,6 @@ This is a TypeScript CLI (`tdc`) for Comms messaging, built with Commander.js. - **Named flag aliases**: Where commands accept positional `[workspace-ref]`, the `--workspace` flag is also accepted. Error if both positional and flag are provided - **JSON output on mutating commands**: Mutating commands (create, update, delete, archive) should support `--json` output where it provides scripting value. Commands that return an object from the API (create/update) should also support `--full`. Commands where the API returns void should output a minimal status object (e.g. `{ id, deleted: true }` or `{ id, isArchived: true }`). Extend `MutationOptions` in `src/lib/options.ts` (which already includes `json` and `full`) rather than adding these fields ad hoc. Use `formatJson()` from `src/lib/output.ts` for the output. See `src/commands/status/set.ts` as the reference implementation. - **Spinner messages**: When adding new SDK method calls, add a corresponding entry in the `API_SPINNER_MESSAGES` map in `src/lib/api.ts`. Every user-facing API call should have a spinner message so the CLI shows progress feedback. -- **Batch API responses**: When calling `client.batch(...)`, never access `.data` directly on a batch result. Use these helpers from `src/lib/api.ts`: - - `assertBatchData(response, label)` — single result; throws `CliError` on any failure (including `data: null`). Use for primary data the command can't render without (e.g. the thread itself). - - `getOptionalBatchData(response, label)` — tolerant single result; returns `data` (or `null`) on success, throws only on real API errors (`code >= 400`). Use when `data: null` with a success code is a valid empty state (e.g. `getUnread` returning null for "no unread threads"). Callers typically chain `?? []` / `?? defaultValue`. - - `buildBatchNameMap(ids, responses, label)` — strict parallel lookup; use when every id must resolve (e.g. channels). - - `buildOptionalBatchNameMap(ids, responses, label)` — tolerant parallel lookup; skips entries with `data: null` and a success code (e.g. deleted users) but still throws on real API errors. Callers must fall back via `userMap.get(id) ?? \`user:${id}\``. Use for user lookups so a single missing user doesn't abort the whole command. - - See `src/commands/inbox.ts` and `src/commands/channel/threads.ts` (mix of strict primary + tolerant unread) and `src/commands/thread/view.ts` (tolerant user map) for reference. ## Error Handling diff --git a/CODEBASE.md b/CODEBASE.md index 81f489f..ab7a272 100644 --- a/CODEBASE.md +++ b/CODEBASE.md @@ -29,9 +29,11 @@ come from `@doist/cli-core`. │ # check-semantic-pull-request, issue-automation, │ # update-comms-sdk ├─ .agents/ -│ ├─ skills/ # Skills for agents working on this repo (add-command) +│ ├─ skills/ # Skills for agents working on this repo (verify, fix-bug, +│ │ # build-feature, add-command, refactor, write-tests, learn) │ └─ scripts/ # Agent tooling (verify, git hook branch guard) and its │ # tests. Not published, unlike scripts/ +├─ .claude/skills/ # Links to .agents/skills/, where Claude Code finds them ├─ docs/agents.md # How the agent tooling fits together ├─ AGENTS.md # Prescriptive rules (definition of done, build cmds, JSON flag, │ # skill-sync, errors) @@ -255,7 +257,7 @@ see a per-command `--user`). - **Build:** `tsc -p tsconfig.build.json` → `dist/` (then `chmod +x`). Two-tsconfig setup: `tsconfig.json` includes tests (type-check/IDE); `tsconfig.build.json` - excludes `*.test.ts`/`.spec.ts` and `__mocks__`. + excludes `*.test.ts`/`*.spec.ts` and `__mocks__`. - **Verify:** `npm run verify` — every check the pull-request workflows run, with one shared build, in about fifteen seconds (`.agents/scripts/verify.ts`). Records a pass in `.tmp/agents/`. @@ -280,7 +282,7 @@ agent command reference. When commands/flags change: 2. `npm run build && npm run sync:skill` → writes `skills/comms-cli/SKILL.md`. 3. `tdc skill update claude-code` (and other installed agents) propagates it. 4. `check-skill-sync.yml` runs `npm run check:skill-sync` on PRs — fails if - `SKILL.md` is out of sync with `content.ts`. + `skills/comms-cli/SKILL.md` is out of sync with `content.ts`. ## Running the CLI directly (no install) diff --git a/docs/agents.md b/docs/agents.md index 4e27c30..ba8c9db 100644 --- a/docs/agents.md +++ b/docs/agents.md @@ -7,20 +7,25 @@ This repository is set up so coding agents prove their work before they call it 1. **Git hooks** run for everyone, people and agents alike, on every commit and push. 2. **`npm run verify`** runs every CI check locally and records a pass. 3. **`AGENTS.md`** tells agents what done means. Claude Code reads it through `CLAUDE.md`; Codex and other agents read it directly. +4. **Skills** in `.agents/skills/` give step-by-step procedures for recurring work. They load only when a task needs them. ## Rules and what holds them -| Rule | Held by | Certainty | -| --------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | -| No commits on `main` | `pre-commit` and `commit-msg` → `.agents/scripts/branch-guard.sh` | Enforced locally; `--no-verify` skips it | -| No pushes to `main` | `pre-push` → `branch-guard.sh`; the "Protect default branch" ruleset | Enforced on GitHub | -| Committed files are linted and formatted | `pre-commit` (lefthook, staged files only); CI | Enforced in CI | -| Type check passes before a commit | `pre-commit`; CI | Enforced in CI | -| Tests pass before a push | `pre-push`; CI | Enforced in CI | -| Agent tooling never ships in the npm package | `.agents/scripts/package-contents.test.ts` | Enforced in CI | -| `npm run verify` runs what CI runs | `.agents/scripts/lib/steps.test.ts` compares it with the pull-request workflows | Enforced in CI | -| Run `npm run verify` before calling work done | `AGENTS.md` | Asked | -| Never weaken a check to pass it | `AGENTS.md` | Asked | +| Rule | Held by | Certainty | +| ------------------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | +| No commits on `main` | `pre-commit` and `commit-msg` → `.agents/scripts/branch-guard.sh` | Enforced locally; `--no-verify` skips it | +| No pushes to `main` | `pre-push` → `branch-guard.sh`; the "Protect default branch" ruleset | Enforced on GitHub | +| Committed files are linted and formatted | `pre-commit` (lefthook, staged files only); CI | Enforced in CI | +| Type check passes before a commit | `pre-commit`; CI | Enforced in CI | +| Tests pass before a push | `pre-push`; CI | Enforced in CI | +| Agent tooling never ships in the npm package | `.agents/scripts/package-contents.test.ts` | Enforced in CI | +| `npm run verify` runs what CI runs | `.agents/scripts/lib/steps.test.ts` compares it with the pull-request workflows | Enforced in CI | +| Run `npm run verify` before calling work done | `AGENTS.md` | Asked | +| Never weaken a check to pass it | `AGENTS.md` | Asked | +| Instructions name only files, links and scripts that exist | `.agents/scripts/instructions.test.ts` | Enforced in CI | +| Every skill says when to use it and is linked for Claude Code | `.agents/scripts/instructions.test.ts` | Enforced in CI | +| Use the matching skill for each task | `AGENTS.md` | Asked | +| Tests meet the quality bar | `.agents/skills/write-tests/references/test-rules.md` | Asked | "Enforced in CI" means a pull request cannot merge without it. A local hook alone is a speed bump: `git commit --no-verify` skips it. @@ -41,7 +46,7 @@ The release workflow commits and pushes to `main` from GitHub Actions, and `npm One command, every check the pull-request workflows run (`lint.yml`, `test.yml`, `check-skill-sync.yml`): lint, format, both type checks, all tests, the build and the skill sync check. It takes about fifteen seconds, so it always checks the whole tree. Picking only the affected tests would save a few seconds and add a way to miss something. - **Before the checks** it stops if Node is older than `package.json` requires, or if `node_modules` does not match the lockfile, transitive dependencies included (npm's own record of what it installed, `node_modules/.package-lock.json`, against `package-lock.json`). Both make checks fail, or pass, for reasons unrelated to your change. -- **Only docs changed** since the branch left `main`: it says there is nothing to check. The generated `skills/comms-cli/SKILL.md` counts as code, since `npm run check:skill-sync` reads it. +- **Only docs changed** since the branch left `main`: it says there is nothing to check. The agent instructions (`AGENTS.md`, `CODEBASE.md`, `docs/agents.md`, `.agents/`) count as code, since a test checks every reference in them, and so does the generated `skills/comms-cli/SKILL.md`, which `npm run check:skill-sync` reads. Deleting or renaming a doc counts as code too, since the agent docs may name it; adding one after a pass means running verify again. - **Only CI files changed** (Renovate, `.github/` config other than workflows): it says no local check reads them. Every workflow counts as code, since a local test compares verify with the three above and checks no other workflow runs commands on pull requests. - **Order:** every check starts together, except the skill sync check, which imports from `dist/` and so waits for the build. - **`CI=true`** is set for the build, the tests and the skill sync check, as GitHub Actions sets it. Variables that change what the CLI does (`COMMS_API_TOKEN`, `COMMS_AS_URL`, `COMMS_BASE_URL`, `COMMS_INCLUDE_PRIVATE_CHANNELS`, `TWIST_AUTH_TOKEN`, `TWIST_BASE_URL`, `TDC_ACCESSIBLE`, `TDC_SPINNER`, `FORCE_COLOR`) are removed, with a note, since CI never sets them. A real token or server never reaches the tests. @@ -52,10 +57,29 @@ One command, every check the pull-request workflows run (`lint.yml`, `test.yml`, If a pull-request workflow gains a step, `.agents/scripts/lib/steps.test.ts` fails until verify gains it too, or says why it can't. +## Skills + +Each skill is a short procedure with a check at the end of every step. Agents load one when the task matches its description. + +| Skill | For | Ends with | +| --------------- | -------------------------------------- | ------------------------------------------------------------------- | +| `verify` | Any change about to be called done | `npm run verify`, proof matched to the change, an evidence report | +| `fix-bug` | Something broken | A test that failed on the symptom, the root cause, undo/restore | +| `build-feature` | A new command, flag or behaviour | Decisions settled up front, test-first slices, a "touches X" map | +| `add-command` | A new command or subcommand | Every file a command touches: spinner text, permissions, skill text | +| `refactor` | Structure changes, behaviour unchanged | Pinned tests, no changed test inputs or assertions | +| `write-tests` | Writing or changing tests | Tests that failed once, meeting the test rules | +| `learn` | A correction from you | A type, lint rule, test or script check that catches the mistake | + +The evidence report rates each claim: **said**, **cited** (a line), **traced** (followed the code), **ran** (a test or command executed it), **seen** (in the running CLI). "Fixed" or "safe" needs **ran**. Anything less is listed under "Not verified". + +The test rules were measured against this repository's tests first, so they accept the patterns that are fine here: `.not.toHaveBeenCalled()` for dry runs and confirmation gates, `toBeDefined()` as a guard, and the `getCommsClient` mock every command test uses. There are no snapshot tests, and the rules keep it that way. + ## Where the tooling lives -- `.agents/scripts/` holds scripts and their tests. It is not under `scripts/` because `scripts/` ships in the npm package. -- The tooling runs straight from TypeScript with Node's type stripping, so it only uses erasable syntax (`.agents/scripts/tsconfig.json` enforces this). `npm run type-check` covers it, and `npm run check` lints it. +- `.agents/scripts/` holds scripts and their tests, next to the skills. It is not under `scripts/` because `scripts/` ships in the npm package. +- Skills live in `.agents/skills/`, where Codex reads them. Claude Code reads them through the symlinks in `.claude/skills/`; a test keeps the two in step. +- The tooling runs straight from TypeScript with Node's type stripping, so it only uses erasable syntax (`.agents/scripts/tsconfig.json` enforces this). `npm run type-check` covers it, and `npm run lint:check` lints it. - Tests run in `npm test` and CI. They copy the tools into throwaway git repositories and never touch your checkout. A test helper clears the variables git exports to hooks, since `npm test` itself runs inside `pre-push`. ## Releases