Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (49 loc) · 5.68 KB

AGENTS.md

File metadata and controls

67 lines (49 loc) · 5.68 KB

AI Coworker Configuration

Meta

  • Learn: When a non-obvious constraint causes a failure, leave a concise note here and a detailed comment at the relevant location

  • CLAUDE.md is a symlink to this file, created by pnpm coworker

  • Refer to yourself as "AI Coworker" in docs and comments, not by product or company name

  • Never add AI tool attribution or branding to PR descriptions, commit messages, or code comments

  • Do not install or use gh CLI

  • When a post-plan fix changes a documented decision, update the planning docs in the same commit

  • Copy to clipboard:

    head -c -1 <<'EOF' | wl-copy
content goes here
EOF

PR Workflow

  1. Routine Pre-PR Validation: pnpm check:full, it wipes derived state and regenerates from scratch. If any fork clone has pending work, the wipe is skipped to prevent data loss — re-record or push fork changes first for a clean validation
  2. Open a PR: Run pnpm changeset to generate a changeset entry, then push the branch and present a clickable markdown link [title](url) where the URL is a GitHub compare URL (quick_pull=1). Base branch is master. Prefill "title" (concise, under 70 chars) and "body" (markdown with ## Why and ## Changes sections)
  3. Fetch PR review comments: Use the GitHub REST API via curl. Fetch all three comment types (issue comments, reviews, and inline comments). Categorize feedback by actionability (action required / informational), not by source (human / bot). Reviewers reply asynchronously — poll every minute until comments arrive

Fork Management (fork-scripts/ + *-fork/)

The fork-scripts/ system uses a record/replay mechanism for deterministic builds of external repo forks. Each fork lives in a <name>-fork/ directory with a config.json specifying upstream URL, fork URL, merge refs, and workspace config. Scripts in fork-scripts/ are generic and accept the fork directory as their first argument.

Per-fork directory structure

Each <name>-fork/ contains:

  • config.json — upstream URL, fork URL, refs to merge, cloneDir, workspace include/exclude
  • pins/ — committed to git (manifest + counted resolutions + local patches), regenerated by pnpm fork:record <name>-fork
    • pins/HEAD — expected final SHA after full replay
    • pins/manifest — base SHA + merge refs (TSV, one per line)
    • pins/res-N.resolution — conflict resolution for merge step N (counted format: --- path file headers, CONFLICT ours=N base=M theirs=K resolution=R conflict headers followed by R resolution lines; parser is purely positional — reads counts and skips lines, never inspects content)
    • pins/local-*.patch — local development patches (applied after merges + patch.sh)
  • <cloneDir>/ — not in git — rebuilt from pins on pnpm install

Key behaviors

  • The developer may have pending work in a fork clone. Run pnpm fork:status <name>-fork (exit 0 = safe to wipe, exit 1 = has custom work) before any operation that would destroy it. fork:record, fork:clean, and fork:reset already guard against this automatically
  • .pnpmfile.cjs scans all *-fork/config.json directories and silently rewrites matching dependencies to workspace:* when clones exist. Local fork packages override published ones without any visible change in package.json files
  • pnpm install has a side effect: if <name>-fork/pins/manifest exists but the clone does not, it automatically runs fork-scripts/replay.sh to rebuild from pins. This is intentional
  • fork-scripts/patch.sh rewrites fork package exports to point at .ts source instead of .d.ts, then creates a deterministic git commit (fixed author/date) so record and replay produce the same HEAD hash. This is why imports from fork packages resolve to TypeScript source files — it is not a bug
  • fork-scripts/tsgo-filter.sh is a bash wrapper around tsgo that filters out diagnostics originating from all *-fork/ clone paths. Fork source may not satisfy this repo's strict tsconfig, so the wrapper suppresses those errors while still reporting errors in stack source
  • pnpm fork:save <name>-fork [description] captures local work as a patch in pins/. Patches survive re-records and replays
  • pnpm fork:record regenerates the fork workspace entries in pnpm-workspace.yaml (between @generated markers) from all *-fork/config.json files — manual edits to that section are overwritten on re-record

CCC upstream contributions

Work locally via ccc-fork/ first. Only push to the fork (phroi/ccc) when changes are validated against the stack. Do not open PRs against ckb-devrel/ccc prematurely — keep changes on the fork until they are production-ready and the maintainer decides to upstream.

  1. Develop and test in ccc-fork/ccc/ on the wip branch
  2. When ready, use pnpm fork:push ccc-fork to cherry-pick commits onto a PR branch
  3. Push the PR branch to phroi/ccc for review
  4. Add the PR number to refs in ccc-fork/config.json — order PRs by target branch from upstream to downstream, so each group merges cleanly onto its base before the next layer begins
  5. Run pnpm fork:record ccc-fork and pnpm check:full to verify
  6. Only open an upstream PR against ckb-devrel/ccc when the maintainer explicitly decides to upstream

Reference Repos

reference/ contains read-only clones (project knowledge, dependency sources, etc.) fetched via pnpm reference. To refresh, just re-run pnpm reference. If a task requires knowledge of an external repo not yet cloned, add it to reference/clone.sh and run pnpm reference to fetch it for consultation

Knowledge

  • Always compare CKB scripts using full Script.eq() (codeHash + hashType + args), never just codeHash. Partial comparison silently matches wrong scripts