choiyounggi · choiyounggi · Aug 21, 2026 · Aug 21, 2026
@@ -12,11 +12,11 @@ follow the cross-pointers in their index or take the next matching seeded domain
 | Domain | Status | Route here when |
 |--------|--------|-----------------|
 | [databases](wiki/databases/index.md) | **seeded** | Designing schemas/tables/keys, choosing or evaluating indexes, writing or optimizing queries, choosing transaction/isolation behavior, surveying live data to derive a rule, verifying additive migrations |
-| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, call-site enumeration before a contract change, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, consuming LLM APIs (completion validation, context budgeting), MAPE-aligned point-prediction calibration, consuming external-API responses, externally-owned defaults, object-storage references, sync-vs-async integration choice, WebSocket/SSE connection lifecycle) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps, packaging data files with `importlib.resources`) |
+| [backend](wiki/backend/index.md) | **seeded** | Server-side application code — language-agnostic (`common/`: API contracts, call-site enumeration before a contract change, idempotency, JWT, timeouts/retries, caching, jobs, transactions in app code, shared state/pools, errors, consuming LLM APIs (completion validation, context budgeting), authoring agent-facing artifacts (binding instruction text, agent tool-surface granularity/parity), MAPE-aligned point-prediction calibration, consuming external-API responses, externally-owned defaults, object-storage references, sync-vs-async integration choice, WebSocket/SSE connection lifecycle) plus stack subtrees: `java/` (JPA, Spring proxies, JVM threads/memory), `node/` (event loop, promises, runtime validation, shutdown), `python/` (GIL/asyncio, pydantic, WSGI/ASGI workers, language traps, packaging data files with `importlib.resources`) |
 | [frontend](wiki/frontend/index.md) | **seeded** | Web UI code: state placement, rendering performance, in-UI data fetching (races, infinite scroll), auth token handling, forms, XSS-safe output, accessibility, agent-facing tool surfaces (WebMCP) |
-| [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting), per-environment/path-valued config, multi-agent orchestration (worker liveness signals, shared run state, tmux pane delivery, completion gates, worktree-isolated workers) |
-| [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, cases/assertions, test data, mock decisions, flaky tests (release-process quality → qa) |
-| [qa](wiki/qa/index.md) | **seeded** | Release-quality process: release gates, regression scoping, bug reports, severity/priority triage, exploratory testing (guarded-path coverage, override matrices), scope-purity gates, sourcing deliverable documents from generated artifacts, verifying the quantitative claims in a document before publishing it, automated verification of document deliverables (spec/RFC gates) (writing automated test code → testing) |
+| [infrastructure](wiki/infrastructure/index.md) | **seeded** | CI/CD pipelines, secrets in build/deploy, container image builds, rollout/rollback strategy, observability (logs/metrics/alerting), per-environment/path-valued config, multi-agent orchestration (worker liveness signals, shared run state, tmux pane delivery, completion gates, worktree-isolated workers, autonomous ask-vs-rule decisions) |
+| [testing](wiki/testing/index.md) | **seeded** | Writing or structuring automated tests: level choice, test-before-code ordering, cases/assertions, cross-layer effect scoping, test data, mock decisions, flaky tests (release-process quality → qa) |
+| [qa](wiki/qa/index.md) | **seeded** | Release-quality process: release gates, regression scoping, bug reports, severity/priority triage, evidence for completion claims, acting on code-review feedback, adversarial review of high-risk diffs, exploratory testing (guarded-path coverage, override matrices), scope-purity gates, sourcing deliverable documents from generated artifacts, verifying the quantitative claims in a document before publishing it, automated verification of document deliverables (spec/RFC gates) (writing automated test code → testing) |
 | [debugging](wiki/debugging/index.md) | **seeded** | Diagnosing a failure — finding what is wrong and why: reproducing, bisection, hypothesis testing, traces/logs, intermittent failures (fixing the diagnosed fault → its owning domain) |
 | [security](wiki/security/index.md) | **seeded** | Trust-boundary decisions: input validation, session-vs-token auth choice, per-resource authorization (IDOR), secrets hygiene, dependency trust, PII handling, in-session agent tool exposure (prompt-injection blast radius), the author identity a commit publishes to a public repository, host-compromise triage / incident response (verifying assumed security agents, identifying masquerading processes) (XSS rendering → frontend; CI secrets → infrastructure; JWT implementation → backend/frontend auth) |
 | [platforms](wiki/platforms/index.md) | **seeded** | OS-level differences breaking code across macOS/Linux/Windows: shell portability, BSD-vs-GNU CLI, filesystem case/line endings, Unicode normalization in text/file-name matching, commands inspected before execution, background services/cron, invoking prompt-capable CLIs non-interactively, toolchain version pinning |

@@ -95,3 +95,4 @@ Append-only. Format: `## [YYYY-MM-DD] <ingest|revise|lint|gap|contradiction|drif
 ## [2026-08-20] ingest | Frontend visual-design knowledge (2 new pages, NEW category frontend/design). frontend/design/anti-slop-visual-design (field-tested — distilled from hallmark skill v1.1.0, which encodes Anthropic's frontend-design skill + Claude cookbook frontend-aesthetics consensus: decision order with structure-before-visuals as the core claim — the AI tell is structural repetition, not color choice; OKLCH token discipline with the one-accent ≤3% rule and no-pure-extremes; roman-headings + display/body pairing typography; transform/opacity-only motion with the 8-state interactive floor; fabricated-metrics honesty rule; a tells table covering gradient heroes, equal 3-column grids, 100vh centered heroes, genre-blind nav/footer fingerprints, redrawn browser/phone chrome, Lottie/Three.js shortcuts, lazy-loaded LCP, and eyebrow-label decoration). frontend/design/html-in-canvas (verified — WICG html-in-canvas draft: layoutsubtree / drawElementImage / texElementImage2D / copyElementImageToTexture / paint-event API surface, the mandatory returned-transform hit-test sync, the dual DOM+pixels model, and a progressive-enhancement-only stance; status live-checked this session against the WICG repo and the blink-dev intent thread — behind chrome://flags/#canvas-draw-element since Chrome 138 (Dec 2025) dev trial, Origin Trial since Chrome 148 (May 2026)). frontend/index.md routing intro extended with visual-design scope and a new design section. Prohibition-lint directive count unchanged at 71; structure checks 244 pages / 13 indexes / 0 findings.
 ## [2026-08-21] ingest | frontend/design/responsive-layout (verified — 1 new page). Mobile-responsive layout contract for viewport-range UI: exact viewport meta with zoom left enabled (~980px virtual-viewport mechanism; user-scalable=no blocks the ≥2× WCAG zoom and iOS ignores it — MDN Viewport_meta_element), mobile-first min-width layering with content-driven breakpoints (web.dev responsive-web-design-basics), intrinsic grids repeat(auto-fit, minmax()) before media queries (web.dev patterns) and @container with intrinsic fallback (MDN), touch targets 24px AA SC 2.5.8 / 44px AAA SC 2.5.5 with the 24px-circle spacing exception (W3C Understanding docs), clamp() fluid type gated on a 200%-zoom check (1.4.4, web.dev min-max-clamp), srcset/sizes + width/height CLS reservation (MDN img), the min-width:auto→min-content overflow mechanism fixed by minmax(0,1fr) (MDN min-width), and edge cases for 100vh-vs-dvh/svh, hover:none long-tap emulation, and viewport-fit=cover + env(safe-area-inset) (WebKit blog). 320px no-horizontal-scroll final gate = SC 1.4.10. All 14 cited URLs live-fetched and verified this session by a research subagent; Apple HIG 44pt / Material 48dp figures deliberately NOT cited (JS-rendered pages unverifiable — WCAG carries the target-size claims); rem-vs-px media-query sub-claim omitted as unverified. related links added both ways (anti-slop-visual-design, accessibility/interactive-elements, performance/bundle-and-assets). frontend/index.md design section +1 row, routing intro extended with responsive-layout scope.
 ## [2026-08-21] revise | frontend/design/anti-slop-visual-design +2 sources / +5 directive rows / +1 edge case (theme-defaults reinforcement). Primary source added: Anthropic Engineering "Improving frontend design through Skills" (claude.com/blog, 2025-11-12; live-fetched — the velog.io/@xxziiko post the contributor supplied is its Korean translation, cross-checked as matching). New Anthropic-backed material: named avoid-list of training-data default fonts (Inter/Roboto/Open Sans/Lato/system) with the distributional-convergence mechanism, feel-category font taxonomy (code/editorial/technical), second-order convergence warning (Space Grotesk as "the new Inter" — vary the escape choice per project), quantified extreme-contrast thresholds (weight 100–200 vs 800–900, 3×+ size jumps), dominant-field + sharp-accent palette framing with IDE-theme/cultural-aesthetic inspiration, domain-derived aesthetic direction folded into the tone-extreme step (non-generic direction reframed as the DEFAULT), motion-budget allocation (one staggered page-load orchestration over scattered micro-interactions), and a right-altitude edge case for writing reusable design guidance (axes + decision logic, no hex hardcoding, no "make it look good"). Aurora-blob Instead-of row reconciled with Anthropic's atmospheric-background endorsement: the tell is ungrounded decoration on a neutral page, theme-earned depth passes. Impeccable README (github.com/pbakaus/impeccable, live-fetched) adds gray-text-on-colored-background and bounce/elastic-easing anti-patterns; tistory.com/1624's deeper Impeccable quotes NOT ingested (cited SKILL.md path 404s — repo restructured; command vocabulary unstable 17→23, only README-level rules taken). Also deliberately skipped: 16px body floor and "adapt don't delete" (third-party, no mechanism, unverifiable primary). frontend/index.md load-when extended (theme direction as default, LLM design-guidance authoring). Prohibition directives unchanged at 71; structure 252/13/0; body 85 lines.
+## [2026-08-22] ingest | Methodology transplant from two retired plugins (superpowers 6.3.0, compound-engineering 2.63.1) — 8 new pages, 3 amended pages, 4 domain indexes + root INDEX updated. Both plugins were disabled locally for context-budget reasons; their full skill/agent inventories were read and gap-analyzed against the wiki before ingest, so only triggers the wiki did not already own were taken (systematic-debugging's phases, verify-RED mutation proof, and status-vs-artifact distrust were all found already covered — by debugging/methodology, testing/quality/tests-that-cannot-fail, and infrastructure/agent-orchestration/control-signals-vs-primary-artifacts respectively — and were NOT duplicated). New: testing/strategy/failing-test-first (Canon TDD ordering, verify-RED for the expected reason, mirror-assertion ban, delete-code-written-before-its-test; also repairs verify-the-fix's previously unresolvable "failing-test-first rule: wiki/testing/" pointer), testing/strategy/cross-layer-effect-tests (CE "System-Wide Test Check": trace two levels out, real-chain requirement, orphaned-state case, sibling-surface parity, error-strategy alignment, explicit skip condition), qa/process/completion-claims (fresh-evidence gate, claim→evidence table incl. subagent self-report distrust routed to control-signals, hedge-word markers), qa/process/evaluating-review-feedback (verify-findings-before-implementing, clarify-all-before-any, YAGNI usage grep, performative-agreement replacement, resweep handoff; Google eng-practices cited for facts-over-opinion and over-engineering vigilance), qa/process/adversarial-change-review (depth calibration by size/risk; four scenario-construction techniques — assumption violation, composition, cascade, abuse; scenario-named findings; advisory-to-human routing), infrastructure/agent-orchestration/autonomous-decision-rulings (four stop-and-ask categories vs rule-and-record with cost-if-wrong ledger; ledger-over-memory resume), backend/common/llm/binding-instructions-for-agents (baseline-fails-first wording tests, form-matched-to-failure table incl. the measured prohibition-backfire result for wrong-shape failures, nuance-clause degradation, description-as-trigger-only), backend/common/api-design/agent-tool-granularity (UI/agent parity capability map, tools-as-primitives vs workflow-shaped tools, CRUD completeness, explicit completion signal, shared data space, composition test). Amended: debugging/methodology/hypothesis-testing +2 edge rows (3-failed-fixes architecture circuit breaker; instrument-every-boundary-then-run-once) + superpowers source; databases/data-survey/surveying-live-data-for-a-rule +1 edge row (hand-transcribed mapping tables verified entry-by-entry — transposed entries survive spot checks) + CE data-migration-expert source; debugging/methodology/verify-the-fix regression-test row now links [testing-strategy-failing-test-first], related +failing-test-first +completion-claims. Related links added both ways (tests-that-cannot-fail, test-level-choice, unattended-worker-questions, control-signals-vs-primary-artifacts, defect-class-resweep-after-review, frontend agent-facing-tool-surfaces). Deliberately skipped as already-covered or out-of-layer: superpowers brainstorming/writing-plans/executing-plans (workflow layer — wiki-plan/loop-implement own it), using-git-worktrees mechanics (partially covered by worktree-isolated-workers; native-tool preference is harness-specific), dispatching-parallel-agents (orchestrate skill), CE frontend-design (frontend/design/anti-slop-visual-design already ingested from hallmark), CE ce:compound/ce:review pipeline mechanics (dev-loop's ingest/review skills own the equivalent), CE Rails-specific personas.
@@ -0,0 +1,67 @@
+---
+id: backend-common-api-design-agent-tool-granularity
+domain: backend
+category: api-design
+applies_to: [general]
+confidence: field-tested
+sources:
+  - https://github.com/EveryInc/compound-engineering-plugin
+  - https://www.anthropic.com/engineering/building-effective-agents
+last_verified: 2026-08-22
+related: [frontend-agent-interfaces-agent-facing-tool-surfaces, backend-common-llm-binding-instructions-for-agents]
+---
+
+# Choosing the Tool Surface an In-App LLM Agent Calls
+
+## When this applies
+
+Adding agent capabilities to an application — an MCP server, a
+function-calling tool list, plugin tools; deciding between exposing a
+workflow function and exposing primitives; an agent cannot perform an action
+the UI offers; reviewing a tool list for an agent feature.
+
+## Do this
+
+1. Build a capability map — every UI action paired with its agent-tool
+   equivalent — and close the gaps: an action reachable in the UI but not by
+   the agent caps the agent at chatbot, answering questions about work it
+   cannot do.
+2. Expose atomic primitives (create/read/update/delete/list, send, search)
+   and implement features as prompts that compose them in an agent loop.
+   Business workflow baked into one tool (`process_feedback` doing
+   categorize + prioritize + store + notify in code) fixes every decision at
+   build time — expose `store_item` and `send_message`, and let the prompt
+   own the workflow.
+3. Complete each resource's CRUD: a tool set that can create but not list,
+   update, or delete strands the agent mid-task, in a state only a human can
+   clean up.
+4. End agent tasks with an explicit completion tool (`complete_task`) rather
+   than heuristic detection (silence, phrase matching) — heuristics
+   misclassify pauses as completions and completions as pauses.
+5. Run the agent in the user's own data space, and reflect agent-caused
+   changes in the UI as they happen — a sandboxed copy or a silent mutation
+   both read as "the agent is broken" to the user watching the screen.
+6. Before shipping, run the composition test: ask the agent for an in-domain
+   outcome you never explicitly built. With primitives and parity in place it
+   composes a path or fails visibly; with workflow-shaped tools it can only
+   do what was anticipated.
+
+## Edge cases
+
+| Case | Then |
+|------|------|
+| The upstream API is large or changes often | Generate the tool list from the API's schema instead of hand-maintaining a static mapping that drifts |
+| A composed flow is frequent and latency-sensitive | Add a domain-level tool for that observed pattern, and keep the primitives it composes — the shortcut is an optimization, not a replacement |
+| An action is dangerous to run autonomously | Gate it behind an approval step that states its reason in the tool result — an unexplained refusal reads as a bug and invites workarounds |
+
+## Instead of
+
+| If you are about to | Do this instead | Why |
+|---------------------|-----------------|-----|
+| Bolt a chat agent onto a finished UI as a router to hardcoded flows | Build the capability map and primitive tools alongside the feature | A router caps capability at exactly the flows someone anticipated |
+| Add one convenience tool per product feature | Expose primitives; ship features as prompts | With workflow-shaped tools every new feature needs new code; with primitives it needs a new prompt |
+
+## Sources
+
+- https://github.com/EveryInc/compound-engineering-plugin — agent-native-architecture skill: parity capability map, tools-as-primitives with the `process_feedback` counter-example, CRUD completeness, explicit completion signal, named anti-patterns (agent-as-router, sandbox isolation, silent actions); field-tested in the plugin authors' shipped products
+- https://www.anthropic.com/engineering/building-effective-agents — agent-computer interface guidance: invest in tool definitions and keep tools simple and composable