AGENTS.md

This file provides guidance to coding agents (Claude Code, opencode, and other Agent Skills–compatible tools) when working with code in this repository. CLAUDE.md is a symlink to this file.

What This Is

Inkstone (硯台) is a Claude Code plugin — a collection of agent skills for creative and design workflows. It is installed via the Claude Code plugin marketplace (/plugin marketplace add augchan42/inkstone). There is no build step and no dependencies to install. The repo is almost entirely Markdown skill definitions, plus one piece of runtime shell: a Stop hook (hooks/) that enforces the plan-review-loop skill's lifecycle.

Repository Structure

.claude-plugin/
  plugin.json          # Plugin manifest — name, version, "skills": "./skills"
  marketplace.json     # Marketplace listing metadata
hooks/
  hooks.json           # Auto-discovered by Claude Code — registers the Stop hook
  stop-hook.sh         # Enforces plan-review-loop completion; no-op when no loop is active
agents/
  inkstone-lane-reviewer.md # Read/search-only lane reviewer; host captures findings
skills/
  <skill-name>/
    SKILL.md           # Skill definition (frontmatter + instructions)
    *.md               # Optional reference files loaded by the skill
examples/
  prompt-examples.md   # Validated reference prompts for ink painting & tech-noir modes
docs/adr/
  0001-*.md            # Decisions about Inkstone's skill architecture and boundaries
hkoscon-2026/
  hkoscon-2026-talk.html  # Self-contained static talk deck + image assets
  DEPLOY.md               # How to (re)deploy the deck to Vercel

How Skills Work

Each skill is a SKILL.md with YAML frontmatter (name, description, user-invocable, argument-hint) followed by the full instruction set that Claude Code receives when the skill is invoked. Skills have no runtime code — they are prompt engineering documents that define behavior through instructions, examples, and rules.

When a skill has companion reference files (e.g., blakean-scene/blakean-reference.md, ui-ux-architect/audit-dimensions.md), the SKILL.md instructs the agent to read them at execution time.

The rationale for keeping implementation verification separate from adversarial review is in ADR-0001.

Adding a New Skill

1. Create skills/<skill-name>/SKILL.md with the required frontmatter (name must match the directory name)
2. No plugin.json edit needed — "skills": "./skills" auto-discovers every subdirectory (Claude Code, opencode, and the Agent Skills spec all scan the folder)
3. Add it to the skills table in README.md under the appropriate category
4. Bump the version in plugin.json if publishing
5. Validate with ./validate-skills.sh (checks frontmatter against the Agent Skills spec)

Skills by Category

Creative

• verse-to-prompt — Converts classical Chinese verse into 50-60 word image generation prompts. Three modes: ink painting (default), stipple (--stipple, the production matrix skin — reuses the ink scene and only swaps the render suffix per ADR-173), and tech-noir (--tech-noir, an experimental CRT cyberpunk reinterpretation). Enforces 7 mandatory composition rules, 5 style categories, content safety substitution patterns, and disambiguation rules for ambiguous English words.
• image-to-scene — Converts ink paintings into video generation motion prompts — 5 motion categories, 6 motion rules, Seedance 2.0 API reference, and a QwenCloud Token Plan (HappyHorse 1.1) section — endpoint, the async-header 403, measured credit cost, and where the runner code lives (8bitoracle-next, not sixlines-ios).
• create-explanation — Generates bilingual (English + Traditional Chinese) scholarly explanations of classical Chinese oracular verses. English 100-150 words, Chinese 150-200 characters.
• blakean-scene — Converts abstract symbolic concepts into 240-280 word Blakean embodied scene prompts using an 8-layer prompt architecture and 8 compositional patterns. Reads blakean-reference.md for pattern details.
• gloss-drift-audit — Verifies translations and derived image prompts after a source text is corrected — separates hash staleness from meaning error and orders the fixes so only changed rows get re-rendered.
• shaughnessy-iching — Interprets a Zhouyi (I Ching) hexagram or line in Edward Shaughnessy's de-mythologized late–Western Zhou register — divination-manual reading, not wisdom classic. Provenance-flagged, interpret-only (no casting).

Design / UX

• ui-ux-architect — UI/UX audit judged from the rendered page, with Jobs/Ive design philosophy. Web: capture.mjs (Playwright) records screenshots, visible text and measurements at 360/768/1440 per theme; native: mobile-mcp. Repo design rules before taste, CONFIRMED/PLAUSIBLE/INCONCLUSIVE verdicts, report-only unless fixes are approved. Design-only scope.
• design-dna — Extracts an abstract visual/motion blueprint (design DNA) from reference websites, or researches award-winning references from a vibe description. Observes and abstracts only — never implements.
• motion-craft — Implements professional web animations in a target repo against an approved design blueprint or explicit motion direction. Plans by default; modifies code only on explicit implement authority.
• upgrade-site — Orchestrates a full website design upgrade: snapshot → reference research via design-dna → direction synthesis → gap scoring → prioritized plan → implementation dispatch to motion-craft → verification.

Engineering Process

• deliver-change — Thin wrapper for deepen-task, implementation and verify-change. Substantial visual deliverables use critic-loop with two independent critics: Claude Code CLI, Opus 5.5 or later via the existing subscription, and Codex CLI, gpt-6-astra at ultra reasoning effort. Explicit user/project reviewer settings override these defaults; unavailable selected routes remain incomplete. Adversarial code review stays opt-in (--review); --no-review controls that code stage only. Preserves separate evidence and reviewer inputs, repair authority, and the three-attempt checkpoint. Discovers dependencies from their installed paths, not the target repo's cwd.
• verify-change — Guides the implementation agent through behavior-to-check mapping, executable verification, and an evidence handoff for a specific code state. Reports gaps and recovery notes. Does not call Codex or perform adversarial review; codex-review remains separate. Adapted from Addy Osmani's verification-first guidance.
• codex-review — Independent code review of any git scope. scripts/resolve-scope.sh turns any argument form — bare (auto-detect), HEAD~3, a range, a merge commit (auto-resolved to <sha>^1 <sha>), --commit, --pr N, --staged, trailing paths — into one concrete git diff invocation, so review scope is never a hardcoded constant. Lanes come from review-lanes.md plus the target repo's own .claude/code-review-lanes.md plus --focus. Reviewer is Codex CLI (plain codex exec with --output-last-message, never codex exec review), then opencode (opencode run --pure --agent inkstone-reviewer, report-scoped writes), then context-blind subagents; reviewer-backends.md holds the mechanics, shared with plan-review-loop. Reviewers write findings while leaving reviewed source unchanged; the artifact records tool and model. Every finding gets an explicit ACCEPTED / DECLINED / PRE-EXISTING disposition. An accepted critical/high finding also names its ENCODE check — the test, lint rule or script that catches the class — or says why none can; loop mode refuses a serious fix without --encode. No hook, no hidden state — one invocation, start to finish. Opt-in loop mode (--loop <id>, loop-mode.md, scripts/rounds.py): a decisions.md before round 1, later rounds review only the increment with earlier declines and repairs as context, findings recorded as JSON, and a stop rule (rounds.py verdict). Round records under reviews/<id>/ are the only state.
• plan-review-loop — Adversarial review loop for implementation plans: locate or author the plan, then an independent multi-lane review (zero-context executability; grounding & traceability against the repo and the source spec; task structure & risk) via Codex CLI, opencode or context-blind subagents, then address findings with judgment. The source spec is reviewed transitively via the traceability lane. Supports superpowers plans (docs/superpowers/plans/), planning-with-files task_plan.md, Kiro tasks.md. Reviews land in reviews/plan-review-<id>.md; state in .claude/plan-review-loop.local.md; cancel argument clears an active loop. Completion is enforced by the Stop hook in hooks/.
• critic-loop — Independent critic loop for generated work that is not code or a plan (images, renders, ASCII or canvas art, video stills and frames, covers, copy). A rubric is written before round 1 (rubrics.md has starters); each round a fresh critic, chosen from codex-review/reviewer-backends.md and given the images, first gives a blind read (what it sees, before the brief), then a scored verdict listing every gap (critic-prompt.md). The producer dispositions every finding. Stop rules: pass at the threshold (default 8) with no blocking condition; a stall (no full-point gain in 2 rounds, or the same gap twice) forces a rethink; a failed rethink stops and asks the owner; a round limit. Records under reviews/critic/<id>/; no hook. Batches get one fresh critic per item.

Advisory

• oss-licence-audit — Manifest-based open-source licence inventory (SBOM-style) with copyleft triage. Deterministic Node script reads package.json, lockfile presence, and node_modules (pnpm + flat layouts), classifies each licence (permissive / weak / strong / network copyleft), and prints flags plus a lawyer handoff. Inventory, never a legal opinion; gaps stated out loud. npm-only in v1.

Productivity

• deepen-task — Reframes a task or prompt around missing expert work, primary evidence, concrete methods, and independent validation. Depth is the default; altitude and range are applied when useful. Rewrites a prompt when requested, or applies the method to the requested work; preserves constraints. Adapted from Felix Rieseberg's ambition framework.
• marketing-clarity — Clarifies marketing messages, website copy and company introductions when readers cannot readily understand the offer or its value. Includes sentence-completion exercises and worked examples. Credits Alexander Payne and his brother Eliot Payne; adapted from Eliot's Marketing Clarity Workshop at The Marketing Common Room.
• unslop — Cuts AI tells from any writing: 33 numbered rules (content, language, style, filler, jargon, plain speech). Rule numbers are stable ids. disable-model-invocation: true, so only the user runs it. Copied from Lauren Tan's pstack (MIT); the licence is in skills/unslop/LICENSE. An inkstone section says a house style guide wins on conflict.
• media-kit — Interactive multi-phase workflow: interview → write bios (4 lengths) → crop/process photos → generate page → bundle zip.
• swapping-pptx-templates — Re-renders an existing .pptx deck's content into a different template/theme — OOXML rebuild with a silent-CJK-corruption guard, baked-in-background hazard detection, and adversarial visual QA.
• arxiv-search — Queries the arXiv API (Atom XML) by topic, author, or paper ID. No auth needed.
• analyze-variation — Measures sentence- and post-length variation across a batch of social copy/drafts — deterministic Node script flags metronomic rhythm and same-size posts.
• voice-calibration — Interactive voice profiling via live terminal prompts. Asks 8 writing prompts (4 general, 4 domain-specific), collects raw typed responses, and distills a reusable voice profile capturing sentence rhythm, rhetorical habits, vocabulary, and tonal signature. Profiles saved to skills/voice-calibration/profiles/.

Web / App Store / Video

• nextjs-i18n-seo — Diagnoses and fixes the 307→301 redirect bug in Next.js App Router i18n middleware that kills PageRank transfer.
• vercel-build-speed — Cuts Vercel build times for Next.js App Router projects. Measure per-phase from the build log first, then attack prerendered page count, duplicated type checking, per-page console.log, and Turbopack-era dead config (webpack(), @next/bundle-analyzer, unrecognized keys). Encodes the counter-intuitive findings: asset bytes are a near-worthless build-time lever, clone time is not proportional to tree size, and an invalid vercel.json key silently produces no deployment at all.
• market-pulse — App Store market overview via web search — competitor movements, trending keywords, Apple featuring, new releases. No paid API subscriptions needed.
• video-to-shorts — Turns a long video into vertical shorts. Transcribes with word timings, scores candidate moments, then renders from a JSON edit list with scripts/build-short.py: hook first, a cut to each speaker (attributed from the mic channels, not the picture), punch-ins, tightened pauses, word-timed captions, a name lower third, a held ending with a fade and a logo end card, and speed variants at -14 LUFS. The editing rules are in references/retention-edit.md and references/two-speaker.md. Cross-platform (macOS/Linux/WSL); stops at an upload-ready mp4.

Conference Slides (hkoscon-2026/)

hkoscon-2026/ holds the "Teaching Taste to an Agent" talk deck — a self-contained static HTML file plus image assets, separate from the plugin itself. It's deployed to Vercel at https://hkoscon-2026-inkstone.vercel.app/ and is not git auto-deployed: pushing to main does not update the live site. To (re)deploy, follow hkoscon-2026/DEPLOY.md.

Key Domain Knowledge

The ink painting skills encode methodology from generating 4,096 unique images for SixLines.online using fal-ai/z-image/turbo. Core insight: style is not a suffix — appending "Chinese ink painting style" to a prompt fails; instead, prompts must read like the caption under an ink painting, with painterly metaphors woven throughout. Same principle applies to tech-noir mode.

Content safety substitutions exist because 52 of 4,096 images failed generation filters. Violence from ancient texts is depicted through atmosphere and aftermath, never the act itself.

The Stop Hook (hooks/)

hooks/hooks.json is auto-discovered by Claude Code (no plugin.json field needed) and runs hooks/stop-hook.sh on every Stop event, in every project where inkstone is installed. Conventions, mirrored from the review-loop plugin this design is based on:

• Fast no-op: the first check is for .claude/plan-review-loop.local.md; absent → immediate {} (omit decision; Codex rejects "approve" for Stop hooks). The hook must stay cheap because it fires on every stop.
• Coexistence: if .claude/review-loop.local.md (the hamel-review/review-loop plugin's state) exists, approve immediately — that plugin's own stop hook drives the stop cycle. Never double-block. The plan-review-loop setup script also refuses to start while that loop is active.
• Phase contract: locate/review → block until the review file exists; addressing → block until ## Disposition is in the review file, then approve + clean up (the skill sets phase: confirm before dispositioning when a critical finding was fixed, so this completion rule only fires when no confirmation is owed); confirm → block until ## Confirmation is in the review file, then approve + clean up.
• Fail-open: on any error, malformed state, invalid review_id (validated against ^[0-9]{8}-[0-9]{6}-[0-9a-f]{6}$ to prevent path traversal), or exhausted block budget (at most 2 blocks per phase without a phase transition, tracked via hook_blocks/hook_block_phase in the state file, enforced only under stop_hook_active), clean up state and approve — never trap the user.
• JSON-only stdout, cross-platform shell (macOS + Linux), timestamped telemetry to .claude/plan-review-loop.log.
• After modifying stop-hook.sh, re-test every path with piped hook-input JSON: no-state, defer-to-original, review-phase block, block-budget fail-open, addressing block (no disposition), addressing approve (with disposition), confirm block (no verdict), confirm approve (with ## Confirmation), invalid review_id, active: false, unknown phase. Verify each output with jq . and run python3 hooks/test_stop_hook.py to check the Stop output contract and lifecycle behavior.

Conventions

• Prompts target 50-60 words (verse-to-prompt) or 240-280 words (blakean-scene) — stay within these ranges
• End ink painting prompts with "Chinese ink painting."; stipple (matrix skin) prompts reuse the ink scene and end with the luminous-stipple suffix ("Golden age science fiction stipple illustration, … phosphor-green and amber palette on black."); tech-noir prompts end with "phosphor-green tech-noir illustration, CRT scanlines, flat deep blacks, stylized graphic art, not photorealistic."
• Disambiguation is mandatory: write "crane bird" not "crane", "swallow bird" not "swallow", etc.
• Traditional Chinese (繁體中文) is used in bilingual outputs, not Simplified
• Bio writing avoids year counts ("enterprise architecture background" not "12 years of...")