vault: session notes 2026-06-30
This commit is contained in:
parent
cf38276bf1
commit
dcaae00d95
|
|
@ -0,0 +1,43 @@
|
|||
---
|
||||
type: convention
|
||||
title: [Human-readable title]
|
||||
summary: [1-2 sentences answering "When I encounter X, what rule should I follow, and why?"]
|
||||
tags:
|
||||
- type/convention
|
||||
- domain/[field]
|
||||
- tool/[tool] # if tool-specific
|
||||
- client/[client] # if client-specific
|
||||
- project/[project] # if project-specific
|
||||
scope: [global|project|client]
|
||||
last_updated: YYYY-MM-DD
|
||||
date: YYYY-MM-DD # creation date — set once, never updated
|
||||
related:
|
||||
- [note-slug] # cross-links to companion notes; omit if none
|
||||
source: [project name] # project that spawned the note
|
||||
---
|
||||
|
||||
# [Convention Name]
|
||||
|
||||
## Purpose
|
||||
<!-- 1–2 sentences: what recurring decision or situation this convention governs and why it matters. Do NOT restate the summary. -->
|
||||
|
||||
## Core Principles
|
||||
<!-- 3–7 principles, each stated as a rule PLUS its rationale ("do X because Y"), not a bare directive. Number them. -->
|
||||
|
||||
**1. [Principle stated as a rule].**
|
||||
[Rationale — why this rule exists and what following it buys you.]
|
||||
|
||||
## Patterns
|
||||
<!-- Concrete ways the principles show up in practice — what to do, with named techniques or short examples. -->
|
||||
|
||||
**[Pattern name].** [What to do, concretely.]
|
||||
|
||||
## Anti-Patterns
|
||||
<!-- Concrete things this convention forbids, each with the tell that flags it. What to avoid, not the principles restated. -->
|
||||
|
||||
- **[Smell / thing to avoid]** → [why it is wrong, or what to do instead]
|
||||
|
||||
## Exceptions
|
||||
<!-- Known cases where the convention does NOT apply, or applies differently. Omit the section only if there are genuinely none. -->
|
||||
|
||||
**[Case].** [Why the convention bends or does not apply here.]
|
||||
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
type: howto
|
||||
title: [Human-readable title]
|
||||
summary: [1-2 sentences answering "How do I accomplish X?" — the task this note covers]
|
||||
tags:
|
||||
- type/howto
|
||||
- domain/[field]
|
||||
- tool/[tool] # if tool-specific
|
||||
- client/[client] # if client-specific
|
||||
- project/[project] # if project-specific
|
||||
scope: [global|project|client]
|
||||
last_updated: YYYY-MM-DD
|
||||
date: YYYY-MM-DD # creation date — set once, never updated
|
||||
update_note: experience-driven # keep ONLY if steps involve UIs/APIs that change frequently; otherwise delete this line
|
||||
related:
|
||||
- [note-slug] # cross-links to companion notes; omit if none
|
||||
source: [project name] # project that spawned the note
|
||||
---
|
||||
|
||||
# [Task Name]
|
||||
|
||||
## Opening
|
||||
<!-- One paragraph. Do NOT restate the summary — give the when-to-reach-for-this trigger and any framing the steps assume. No background theory. -->
|
||||
|
||||
## Prerequisites
|
||||
<!-- Checkbox list of what must be true/installed/obtained before starting; each item independently verifiable. -->
|
||||
|
||||
- [ ] ...
|
||||
- [ ] ...
|
||||
|
||||
## Steps
|
||||
<!-- Numbered steps. Each step = context (why/when this step) → action (the command or change) → expected result (what success looks like). -->
|
||||
|
||||
### Step 1: [action]
|
||||
|
||||
## Verification
|
||||
<!-- End-to-end confirmation the whole procedure worked — concrete checks/commands and their expected output (distinct from per-step expected results). -->
|
||||
|
||||
## Gotchas
|
||||
<!-- Known failure modes and surprises, each with how to recognize it and how to recover. Omit the section only if there are genuinely none. -->
|
||||
|
||||
## Related
|
||||
<!-- Wikilinks to companion notes, one line each on why it is relevant. -->
|
||||
|
||||
- [[note-slug]] — why it is relevant
|
||||
|
|
@ -0,0 +1,110 @@
|
|||
---
|
||||
type: reference
|
||||
subtype: pattern/framework # REQUIRED — set to exactly one of: pattern/framework | api-integration | role-definitions | design-rules
|
||||
title: [Human-readable title]
|
||||
summary: [1-2 sentences answering "what facts do I need to look up to make a decision / integrate / understand roles?"]
|
||||
tags:
|
||||
- type/reference
|
||||
- domain/[field]
|
||||
- tool/[tool] # if tool-specific
|
||||
- client/[client] # if client-specific
|
||||
- project/[project] # if project-specific
|
||||
scope: [global|project|client]
|
||||
last_updated: YYYY-MM-DD
|
||||
date: YYYY-MM-DD # creation date — set once, never updated
|
||||
last_reviewed: YYYY-MM-DD # REQUIRED if subtype is api-integration (mutable facts: auth, endpoints, schema); otherwise delete this line
|
||||
related:
|
||||
- [note-slug] # cross-links to companion notes; omit if none
|
||||
source: [project name] # project that spawned the note
|
||||
---
|
||||
|
||||
# [Reference Title]
|
||||
|
||||
## Purpose
|
||||
<!-- One or two sentences: what this reference covers and the decision / integration / role-understanding it supports. Do NOT restate the summary; do NOT add background theory. -->
|
||||
|
||||
<!-- ============================================================
|
||||
CHOOSE YOUR SUB-TYPE — keep ONE block below, delete the other
|
||||
three AND this selector. Match the block to the `subtype` set in
|
||||
frontmatter. Each block lists its body sections.
|
||||
|
||||
pattern/framework → Core Principles · Decision Framework · Patterns · Anti-Patterns · Known Limitations
|
||||
api-integration → Setup · Authentication · Schema / Data Model · Operations · Gotchas (REQUIRES last_reviewed)
|
||||
role-definitions → Roles · Inputs & Outputs · Phases · Boundaries
|
||||
design-rules → Rules / Standards · Examples · Exceptions
|
||||
============================================================ -->
|
||||
|
||||
<!-- ===== VARIANT: pattern/framework ===== -->
|
||||
|
||||
## Core Principles
|
||||
<!-- The 1–3 foundational ideas every pattern below rests on, each as a statement plus why it holds. Lets the reader reason about cases the patterns don't name. -->
|
||||
|
||||
## Decision Framework
|
||||
<!-- When to choose what — a flowchart, decision tree, or table mapping situation → choice. This is the section the reader scans first to pick an approach. -->
|
||||
|
||||
## Patterns
|
||||
<!-- Named patterns, each with: when to use it, why it works, and (optional) a short example. One sub-heading per pattern. -->
|
||||
|
||||
### [Pattern name]
|
||||
<!-- When → why → optional short example. -->
|
||||
|
||||
## Anti-Patterns
|
||||
<!-- What to avoid, each with the tell that flags it and the fix. Not the principles restated. -->
|
||||
|
||||
- **[Anti-pattern / smell]** → [why it is wrong, or what to do instead]
|
||||
|
||||
## Known Limitations
|
||||
<!-- Boundary / version-sensitive caveats: where the framework stops applying or depends on a tool's current behavior. Omit only if genuinely none. -->
|
||||
|
||||
<!-- ===== VARIANT: api-integration ===== -->
|
||||
<!-- REQUIRES `last_reviewed` in frontmatter — these are mutable facts that drift. -->
|
||||
|
||||
## Setup
|
||||
<!-- Prerequisites and connection steps to get the integration working: accounts, base URLs, SDK/version, env vars. Enough to go from zero to a first call. -->
|
||||
|
||||
## Authentication
|
||||
<!-- Auth method (key / OAuth / token), where credentials live, and how tokens are obtained/refreshed. The reader configures auth from this alone. -->
|
||||
|
||||
## Schema / Data Model
|
||||
<!-- The entities, key fields, and types the integration exposes. What the reader maps their data to. Tables work well here. -->
|
||||
|
||||
## Operations
|
||||
<!-- The common operations / endpoints with their purpose and minimal usage shape (params in, result out). The reader picks the right call from this. -->
|
||||
|
||||
## Gotchas
|
||||
<!-- Rate limits, quirks, breaking-change history, and version-sensitive behavior. The reader avoids the pitfall before hitting it. Omit only if genuinely none. -->
|
||||
|
||||
<!-- ===== VARIANT: role-definitions ===== -->
|
||||
|
||||
## Roles
|
||||
<!-- Each role/agent and its one-line responsibility. One sub-heading or list item per role. The reader assigns work from this. -->
|
||||
|
||||
- **[Role]** — [responsibility in one line]
|
||||
|
||||
## Inputs & Outputs
|
||||
<!-- What each role consumes and produces, so handoffs wire up correctly. A table (role · input · output) works well. -->
|
||||
|
||||
## Phases
|
||||
<!-- The ordered phases/sequence and which role acts in each. The reader sequences the workflow from this. -->
|
||||
|
||||
## Boundaries
|
||||
<!-- What each role does NOT do — the edges that prevent overlap or overreach. Omit only if genuinely none. -->
|
||||
|
||||
<!-- ===== VARIANT: design-rules ===== -->
|
||||
<!-- This is LOOKUP material (established standards/values), not behavioral rules-with-rationale — that is the `convention` type. Keep entries as facts to conform to, not principles to internalize. -->
|
||||
|
||||
## Rules / Standards
|
||||
<!-- The established standards as directives or values to conform to (e.g., the spacing scale, the naming format, the allowed set). The reader checks their work against these. -->
|
||||
|
||||
- **[Rule / standard]** — [the value or directive]
|
||||
|
||||
## Examples
|
||||
<!-- Concrete correct applications of the standards — what conformance looks like. The reader mirrors these. -->
|
||||
|
||||
## Exceptions
|
||||
<!-- Where the standards do not apply or apply differently. Omit only if genuinely none. -->
|
||||
|
||||
## Related
|
||||
<!-- Wikilinks to companion notes, one line each on why it is relevant. Keep this section in whichever variant you choose. -->
|
||||
|
||||
- [[note-slug]] — why it is relevant
|
||||
|
|
@ -17,6 +17,8 @@ update_note: experience-driven
|
|||
|
||||
This guide sets up the Airtable MCP server in a Claude Code project using **project-local scope** — so MCP only loads when you're working in this project, not every session. Use it whenever you're starting a new project that reads or writes Airtable data via Claude Code.
|
||||
|
||||
This note is flagged `update_note: experience-driven` — when a session follows these steps and finds a discrepancy (API changes, UI shifts, scope updates), update the steps rather than relying on a review date. The frontmatter contract in `vault-conventions.md` documents this pattern.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [ ] Claude Code CLI installed and working (`claude --version`)
|
||||
|
|
@ -83,6 +85,8 @@ Replace `YOUR_PROD_BASE_ID` with the actual production base ID (format: `appXXXX
|
|||
|
||||
### Step 3: Add project-assets reference doc
|
||||
|
||||
**Customization Point**: Adapt the file path and structure below to match your project's conventions. This step captures project-specific Airtable configuration that may differ from project to project.
|
||||
|
||||
Create `docs/reference/project-assets.md` to track discovered table IDs and field conventions — Airtable table IDs change if tables are recreated, so document them as you find them:
|
||||
|
||||
```markdown
|
||||
|
|
|
|||
|
|
@ -7,7 +7,8 @@ tags:
|
|||
- tool/tailwind
|
||||
- domain/design
|
||||
- domain/dev
|
||||
scope: global
|
||||
- project/design-mode
|
||||
scope: project
|
||||
last_updated: 2026-06-27
|
||||
---
|
||||
|
||||
|
|
@ -36,9 +37,7 @@ Target Design (inspiration)
|
|||
↓
|
||||
[3] Iterate ──→ 2-3 rounds until reference matches target
|
||||
↓
|
||||
[4] /componentize ──→ Style base components (future capability)
|
||||
↓
|
||||
[5] /design ──→ Uses config + components + style guide for creative freedom
|
||||
[4] /design ──→ Uses config + style guide for creative freedom
|
||||
```
|
||||
|
||||
## Steps
|
||||
|
|
@ -99,8 +98,6 @@ Once the foundation artifacts are stable, use `/design` for new UI work:
|
|||
|
||||
The command uses `tailwind.config.js` (tokens) + `style-guide.md` (usage intent) as constraints, giving creative freedom within the established design language.
|
||||
|
||||
For component work, `/componentize` (future capability) styles base components so they inherit config tokens automatically.
|
||||
|
||||
**Expected result:** New UI output that looks consistent with the extracted design system without manually specifying colors or spacing.
|
||||
|
||||
## Validation Checkpoints
|
||||
|
|
@ -141,20 +138,8 @@ Replace the CDN script tags with `<link rel="stylesheet" href="dist/styles.css">
|
|||
|---------|---------|
|
||||
| `/design-to-html` | Screenshot + CSS → three foundation artifacts |
|
||||
| `/design` | Description + theme → new UI (uses config + style guide) |
|
||||
| `/componentize` | Style base components using theme tokens (future) |
|
||||
| `python tools/compress-styles.py` | Compress raw CSS before passing to design-to-html |
|
||||
|
||||
## Project Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `CLAUDE.md` | Pipeline overview for Claude Code sessions |
|
||||
| `process-guide.md` | Quick reference (source of this howto) |
|
||||
| `style-guide-template.md` | Template for style guides |
|
||||
| `tailwind-config-template.js` | Template for Tailwind config |
|
||||
| `tools/compress-styles.py` | CSS compression tool |
|
||||
| `projects/[name]/` | Per-project artifact folder |
|
||||
|
||||
## Tips
|
||||
|
||||
- **Config is palette, style guide is instructor** — config says *what* values exist; style guide says *when and why* to use them
|
||||
|
|
|
|||
|
|
@ -1,14 +1,16 @@
|
|||
---
|
||||
type: reference
|
||||
subtype: cookbook
|
||||
subtype: pattern/framework
|
||||
title: Agent Orchestration Cookbook
|
||||
summary: Concrete implementation examples for multi-agent orchestration — prompt templates, token budgets, error recovery, and common gotchas. Companion to the patterns hub.
|
||||
tags:
|
||||
- type/reference
|
||||
- domain/ai-agents
|
||||
- domain/orchestration
|
||||
- tool/claude-code
|
||||
scope: global
|
||||
last_updated: 2026-06-27
|
||||
last_reviewed: 2026-06-30
|
||||
related:
|
||||
- reference/agent-orchestration-patterns
|
||||
---
|
||||
|
|
@ -17,6 +19,8 @@ related:
|
|||
|
||||
**Purpose**: Concrete examples, prompt templates, and gotchas for implementing the patterns in [[reference/agent-orchestration-patterns]].
|
||||
|
||||
**Note:** Tool behavior (especially the Task tool) is version-sensitive and may change with Claude Code updates. Verify agent capabilities against current Claude Code documentation before adapting these examples to production systems.
|
||||
|
||||
## Phase Templates
|
||||
|
||||
### Phase 1 — Inventory Agent Prompt
|
||||
|
|
@ -207,16 +211,7 @@ Keep agents **flat** — peers, not hierarchies. Nested agents (agent spawns age
|
|||
|
||||
---
|
||||
|
||||
## Glossary
|
||||
|
||||
| Term | Definition |
|
||||
|---|---|
|
||||
| Tool Tax | Fixed ~20–25K token overhead per agent before any work is done |
|
||||
| Specialist | An agent that processes multiple similar items, paying tool tax once |
|
||||
| Batch | Group of agents spawned in parallel (5–8 max to respect rate limits) |
|
||||
| Manifest | JSON file tracking completed/pending/failed items for recovery |
|
||||
| Flattened | Orchestration where agents are peers at one level, not nested |
|
||||
| Idempotent | Safe to re-run — check-before-modify prevents double-processing |
|
||||
**Glossary terms** are defined in the companion patterns note: [[reference/agent-orchestration-patterns]].
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -7,8 +7,10 @@ tags:
|
|||
- type/reference
|
||||
- domain/ai-agents
|
||||
- domain/orchestration
|
||||
- tool/claude-code
|
||||
scope: global
|
||||
last_updated: 2026-06-27
|
||||
last_reviewed: 2026-06-30
|
||||
related:
|
||||
- reference/agent-orchestration-cookbook
|
||||
---
|
||||
|
|
@ -140,6 +142,8 @@ Return: {"status": "updated|skipped|ambiguous", "changes": [...]}
|
|||
|
||||
## Known Limitations
|
||||
|
||||
**Note:** Task tool behavior is version-sensitive and may change with tool updates. Verify tool capabilities in current Claude Code documentation before relying on the patterns below in production systems.
|
||||
|
||||
- Task tool does **not** return agent IDs programmatically (visible in UI only).
|
||||
- No API to list active/completed agents.
|
||||
- `resume` parameter requires manual ID tracking — not suitable for automated orchestration.
|
||||
|
|
|
|||
Loading…
Reference in New Issue