diff --git a/addyosmani/.claude/skills/api-and-interface-design/SKILL.md b/addyosmani/.claude/skills/api-and-interface-design/SKILL.md index 3e2e37f..ce58d72 100644 --- a/addyosmani/.claude/skills/api-and-interface-design/SKILL.md +++ b/addyosmani/.claude/skills/api-and-interface-design/SKILL.md @@ -196,7 +196,9 @@ The unique constraint *is* the mechanism. A store that cannot enforce uniqueness ```typescript if (existing.requestHash !== hash(req.body)) { - return res.status(422).json({ error: 'idempotency key reused with a different payload' }); + return res.status(422).json({ + error: { code: 'IDEMPOTENCY_KEY_REUSED', message: 'Idempotency key reused with a different payload' }, + }); } ``` diff --git a/addyosmani/.claude/skills/ci-cd-and-automation/SKILL.md b/addyosmani/.claude/skills/ci-cd-and-automation/SKILL.md index 118456f..531bb8f 100644 --- a/addyosmani/.claude/skills/ci-cd-and-automation/SKILL.md +++ b/addyosmani/.claude/skills/ci-cd-and-automation/SKILL.md @@ -184,7 +184,7 @@ Agent fixes → pushes → CI runs again **Key patterns:** ``` -Lint failure → Agent runs `npm run lint --fix` and commits +Lint failure → Agent runs `npm run lint -- --fix` and commits Type error → Agent reads the error location and fixes the type Test failure → Agent follows debugging-and-error-recovery skill Build error → Agent checks config and dependencies @@ -263,9 +263,12 @@ jobs: runs-on: ubuntu-latest steps: - name: Rollback deployment + env: + VERSION: ${{ inputs.version }} run: | - # Deploy the specified previous version - npx vercel rollback ${{ inputs.version }} + # Deploy the specified previous version. Pass the input through env, + # never interpolate it into the script (shell injection). + npx vercel rollback "$VERSION" ``` ## Environment Management @@ -313,7 +316,7 @@ When the pipeline exceeds 10 minutes, apply these strategies in order of impact: ``` Slow CI pipeline? ├── Cache dependencies -│ └── Use actions/cache or setup-node cache option for node_modules +│ └── Use the setup-node cache option (or actions/cache) for the package manager cache, not node_modules ├── Run jobs in parallel │ └── Split lint, typecheck, test, build into separate parallel jobs ├── Only run what changed diff --git a/addyosmani/.claude/skills/code-simplification/SKILL.md b/addyosmani/.claude/skills/code-simplification/SKILL.md index 239b284..c4f794a 100644 --- a/addyosmani/.claude/skills/code-simplification/SKILL.md +++ b/addyosmani/.claude/skills/code-simplification/SKILL.md @@ -1,6 +1,6 @@ --- name: code-simplification -description: Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity. +description: Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity. Use when asked to simplify, clean up, or reduce the nesting of a function or module that already works, even when the code is pasted inline and nothing else needs to change. --- # Code Simplification diff --git a/addyosmani/.claude/skills/constraint-driven-development/SKILL.md b/addyosmani/.claude/skills/constraint-driven-development/SKILL.md index 3028719..e4f9f5d 100644 --- a/addyosmani/.claude/skills/constraint-driven-development/SKILL.md +++ b/addyosmani/.claude/skills/constraint-driven-development/SKILL.md @@ -113,7 +113,7 @@ Last reviewed: 2026-08-08 by @addy |-----------|------|-----------|---------| | Types | Zero type errors | `tsc --noEmit` | every edit | | Lint | Zero errors from our config | `biome check` | every edit | -| Secrets | No secrets in source | `gitleaks detect --redact` | every edit | +| Secrets | No secrets in source | `gitleaks dir . --redact` | every edit | | Coverage | Changed lines ≥ 80% covered | `vitest run --coverage` + git diff | task end, CI | | Security: code | No high findings | `semgrep scan --config p/default` | CI | | Security: deps | Nothing at high or above | `osv-scanner scan source -r .` | CI | @@ -148,10 +148,10 @@ Picking a dimension means installing something. Don't leave the user with a numb | Types (TS) | tsc | already there | `tsc --noEmit` | any error | | Types (Python) | mypy | `pip install mypy` | `mypy .` | any error | | Lint | your existing config | already there | `eslint .` / `biome check` / `ruff check` | any error | -| Coverage (JS) | your test runner | already there | `vitest run --coverage` (or `jest --coverage`) | coverage of changed lines | +| Coverage (JS) | your test runner | Vitest: `npm i -D @vitest/coverage-v8`; Jest: already there | `vitest run --coverage` (or `jest --coverage`) | coverage of changed lines | | Coverage (Python) | pytest-cov | `pip install pytest-cov` | `pytest --cov --cov-report=lcov` | same | | Security: code | Semgrep | `pipx install semgrep` | `semgrep scan --config p/default --config p/owasp-top-ten` | any high finding | -| Security: secrets | gitleaks | `brew install gitleaks` | `gitleaks detect --redact --no-banner` | any finding | +| Security: secrets | gitleaks | `brew install gitleaks` | `gitleaks dir . --redact --no-banner` | any finding | | Security: dependencies | osv-scanner | `brew install osv-scanner` | `osv-scanner scan source -r .` | high or above | | Performance: page | Lighthouse | `npm i -D lighthouse` | `lighthouse $URL --output=json --quiet` | LCP, CLS, performance score | | Performance: bundle | size-limit | `npm i -D size-limit` | `size-limit --json` | per-entry byte budget | @@ -172,7 +172,7 @@ Add each one to the project's own script so it's reproducible without an agent: ```json { "scripts": { - "check:fast": "tsc --noEmit && eslint . && gitleaks detect --redact --no-banner", + "check:fast": "tsc --noEmit && eslint . && gitleaks dir . --redact --no-banner", "check:task": "npm run check:fast && vitest run --coverage", "check:full": "npm run check:task && semgrep scan --config p/default && osv-scanner scan source -r ." } diff --git a/addyosmani/.claude/skills/constraint-driven-development/references/floor-guard.md b/addyosmani/.claude/skills/constraint-driven-development/references/floor-guard.md index 0fa8a69..6ba8b6d 100644 --- a/addyosmani/.claude/skills/constraint-driven-development/references/floor-guard.md +++ b/addyosmani/.claude/skills/constraint-driven-development/references/floor-guard.md @@ -123,8 +123,8 @@ const ruleKey = (t) => { const isException = (t) => /^\| *(W|E)\d+ *\|/.test(t.trim()); const MIN_BEFORE = /(>=|>|≥|at least|minimum|\bmin\b|no less than|not fall|not drop)\s*$/; const MAX_BEFORE = /(<=|<|≤|at most|maximum|\bmax\b|no more than|under|below|not grow|not exceed)\s*$/; -const MIN_AFTER = /^\s*\S*\s*(or more|or higher|must not fall|must not drop)/; -const MAX_AFTER = /^\s*\S*\s*(or less|or lower|must not grow|must not exceed)/; +const MIN_AFTER = /^\s*\S*\s*(?:\|\s*)?(or more|or higher|must not fall|must not drop)/; +const MAX_AFTER = /^\s*\S*\s*(?:\|\s*)?(or less|or lower|must not grow|must not exceed)/; const thresholds = (t) => { const out = [], re = /\d+(?:\.\d+)?/g; let m; diff --git a/addyosmani/.claude/skills/context-engineering/SKILL.md b/addyosmani/.claude/skills/context-engineering/SKILL.md index fb8bb5f..20b0b9a 100644 --- a/addyosmani/.claude/skills/context-engineering/SKILL.md +++ b/addyosmani/.claude/skills/context-engineering/SKILL.md @@ -50,7 +50,7 @@ Create a rules file that persists across sessions. This is the highest-leverage ## Commands - Build: `npm run build` - Test: `npm test` -- Lint: `npm run lint --fix` +- Lint: `npm run lint -- --fix` - Dev: `npm run dev` - Type check: `npx tsc --noEmit` diff --git a/addyosmani/.claude/skills/debugging-and-error-recovery/SKILL.md b/addyosmani/.claude/skills/debugging-and-error-recovery/SKILL.md index 356da20..13c1a43 100644 --- a/addyosmani/.claude/skills/debugging-and-error-recovery/SKILL.md +++ b/addyosmani/.claude/skills/debugging-and-error-recovery/SKILL.md @@ -81,7 +81,7 @@ npm test -- --grep "test name" npm test -- --verbose # Run in isolation (rules out test pollution) -npm test -- --testPathPattern="specific-file" --runInBand +npm test -- specific-file --runInBand ``` ### Step 2: Localize diff --git a/addyosmani/.claude/skills/deprecation-and-migration/SKILL.md b/addyosmani/.claude/skills/deprecation-and-migration/SKILL.md index 7bf884c..8789d4e 100644 --- a/addyosmani/.claude/skills/deprecation-and-migration/SKILL.md +++ b/addyosmani/.claude/skills/deprecation-and-migration/SKILL.md @@ -145,6 +145,11 @@ class LegacyTaskService implements OldTaskAPI { const task = this.newService.findById(String(id)); return this.toOldFormat(task); } + + // Translate the new shape back into what old consumers expect + private toOldFormat(task: Task): OldTask { + return { id: Number(task.id), title: task.title, done: task.status === 'done' }; + } } ``` @@ -157,7 +162,7 @@ function getTaskService(userId: string): TaskService { if (featureFlags.isEnabled('new-task-service', { userId })) { return new NewTaskService(); } - return new LegacyTaskService(); + return new OldTaskService(); } ``` diff --git a/addyosmani/.claude/skills/documentation-and-adrs/SKILL.md b/addyosmani/.claude/skills/documentation-and-adrs/SKILL.md index ecc28ce..eff8fdd 100644 --- a/addyosmani/.claude/skills/documentation-and-adrs/SKILL.md +++ b/addyosmani/.claude/skills/documentation-and-adrs/SKILL.md @@ -111,8 +111,9 @@ Comment the *why*, not the *what*: counter += 1; // GOOD: Explains non-obvious intent -// Rate limit uses a sliding window — reset counter at window boundary, -// not on a fixed schedule, to prevent burst attacks at window edges +// Rate limit uses a fixed window that opens on the first request after the +// previous one expires, not on a clock schedule. Known gap: a client can spend +// the full limit just before a reset and again just after (2x in a moment) if (now - windowStart > WINDOW_SIZE_MS) { counter = 0; windowStart = now; diff --git a/addyosmani/.claude/skills/frontend-ui-engineering/SKILL.md b/addyosmani/.claude/skills/frontend-ui-engineering/SKILL.md index 3c77256..6319718 100644 --- a/addyosmani/.claude/skills/frontend-ui-engineering/SKILL.md +++ b/addyosmani/.claude/skills/frontend-ui-engineering/SKILL.md @@ -79,20 +79,20 @@ export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) { ```tsx // Container: handles data export function TaskListContainer() { - const { tasks, isLoading, error, refetch } = useTasks(); + const { tasks, isLoading, error, refetch, toggleTask, deleteTask } = useTasks(); if (isLoading) return ; if (error) return ; if (tasks.length === 0) return ; - return ; + return ; } // Presentation: handles rendering -export function TaskList({ tasks }: { tasks: Task[] }) { +export function TaskList({ tasks, onToggle, onDelete }: { tasks: Task[] } & Pick) { return (
    - {tasks.map(task => )} + {tasks.map(task => )}
); } @@ -234,7 +234,7 @@ function Dialog({ isOpen, onClose }: DialogProps) { ```tsx // Don't show blank screens -function TaskList({ tasks }: { tasks: Task[] }) { +function TaskList({ tasks, onCreateTask }: { tasks: Task[]; onCreateTask: () => void }) { if (tasks.length === 0) { return (
@@ -272,7 +272,7 @@ Test at these breakpoints: 320px, 768px, 1024px, 1440px. // Skeleton loading (not spinners for content) function TaskListSkeleton() { return ( -
+
{Array.from({ length: 3 }).map((_, i) => (
))} diff --git a/addyosmani/.claude/skills/idea-refine/SKILL.md b/addyosmani/.claude/skills/idea-refine/SKILL.md index c35e693..e2a2be0 100644 --- a/addyosmani/.claude/skills/idea-refine/SKILL.md +++ b/addyosmani/.claude/skills/idea-refine/SKILL.md @@ -28,8 +28,10 @@ Refines raw ideas into sharp, actionable concepts worth building through structu This skill is primarily an interactive dialogue. Invoke it with an idea, and the agent will guide you through the process. ```bash -# Optional: Initialize the ideas directory -bash skills/idea-refine/scripts/idea-refine.sh +# Optional. Run from the project root so this creates ./docs/ideas. +# is the directory that contains this SKILL.md +# (for example .agents/skills/idea-refine or .cursor/skills/idea-refine). +bash /scripts/idea-refine.sh ``` ## Output diff --git a/addyosmani/.claude/skills/performance-optimization/SKILL.md b/addyosmani/.claude/skills/performance-optimization/SKILL.md index ff57eab..296cf3f 100644 --- a/addyosmani/.claude/skills/performance-optimization/SKILL.md +++ b/addyosmani/.claude/skills/performance-optimization/SKILL.md @@ -205,8 +205,8 @@ Lighthouse Performance score: ≥ 90 # Bundle size check npx bundlesize --config bundlesize.config.json -# Lighthouse CI -npx lhci autorun +# Lighthouse CI. The CLI package is @lhci/cli; unscoped `lhci` on npm is not it. +npx --package=@lhci/cli lhci autorun ``` ## See Also diff --git a/addyosmani/.claude/skills/security-and-hardening/references/hardening-patterns.md b/addyosmani/.claude/skills/security-and-hardening/references/hardening-patterns.md index e5fba73..dbccfbf 100644 --- a/addyosmani/.claude/skills/security-and-hardening/references/hardening-patterns.md +++ b/addyosmani/.claude/skills/security-and-hardening/references/hardening-patterns.md @@ -65,6 +65,11 @@ const clean = DOMPurify.sanitize(userInput); // Always check authorization, not just authentication app.patch('/api/tasks/:id', authenticate, async (req, res) => { const task = await taskService.findById(req.params.id); + if (!task) { + return res.status(404).json({ + error: { code: 'NOT_FOUND', message: 'Task not found' } + }); + } // Check that the authenticated user owns this resource if (task.ownerId !== req.user.id) { diff --git a/addyosmani/.claude/skills/source-driven-development/SKILL.md b/addyosmani/.claude/skills/source-driven-development/SKILL.md index 2704f0e..fb94d0f 100644 --- a/addyosmani/.claude/skills/source-driven-development/SKILL.md +++ b/addyosmani/.claude/skills/source-driven-development/SKILL.md @@ -158,8 +158,9 @@ form submission state. React 19 replaced the manual isPending/setIsPending pattern with this hook. Source: https://react.dev/blog/2024/12/05/react-19#actions -"useTransition now supports async functions [...] to handle -pending states automatically" +"In React 19, we're adding support for using async functions in +transitions to handle pending states, errors, forms, and optimistic +updates automatically." ``` **Citation rules:** diff --git a/addyosmani/.claude/skills/spec-driven-development/SKILL.md b/addyosmani/.claude/skills/spec-driven-development/SKILL.md index f54426b..3fcc536 100644 --- a/addyosmani/.claude/skills/spec-driven-development/SKILL.md +++ b/addyosmani/.claude/skills/spec-driven-development/SKILL.md @@ -89,7 +89,7 @@ Don't silently fill in ambiguous requirements. The spec's entire purpose is to s ``` Build: npm run build Test: npm test -- --coverage - Lint: npm run lint --fix + Lint: npm run lint -- --fix Dev: npm run dev ``` diff --git a/addyosmani/skills-lock.json b/addyosmani/skills-lock.json index 86795c9..350d811 100644 --- a/addyosmani/skills-lock.json +++ b/addyosmani/skills-lock.json @@ -5,7 +5,7 @@ "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/api-and-interface-design/SKILL.md", - "computedHash": "8bdbf1fca81bef9258d7e0d9726f933f25677ec8537792e084a3fb7c54acf2ba" + "computedHash": "0d823e9ff32f529f21492a3fd7635fc75b43ff1eb1788d4be0974bfa42e22ae3" }, "browser-testing-with-devtools": { "source": "addyosmani/agent-skills", @@ -17,7 +17,7 @@ "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/ci-cd-and-automation/SKILL.md", - "computedHash": "578b098a7d2352ccdac8b8abdc40eb6803538e81cf8382f138da6188a655087c" + "computedHash": "f655c44b80ec36532fa058f7b94e7463330b8ccacda35eba05d85c677a4f6a7d" }, "code-review-and-quality": { "source": "addyosmani/agent-skills", @@ -29,37 +29,37 @@ "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/code-simplification/SKILL.md", - "computedHash": "7973e746e8e2ea5004d520da970c15a106824b8d6be1bcff48908aec021f3677" + "computedHash": "e4c1f0c12274be9981e1301bfbb9b3112b63e2209413071728b132c9b4ee2f5b" }, "constraint-driven-development": { "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/constraint-driven-development/SKILL.md", - "computedHash": "7cdf20ff7d27eb3103b206033a1d87af7afe4a648162f09cd382fc8e3cb9a42b" + "computedHash": "e7edf3955e685b52c078ca313b518266bd33bab5510358c9f323c0fa21558946" }, "context-engineering": { "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/context-engineering/SKILL.md", - "computedHash": "807434a4b178635a5539a1da241815ba7228f00b71f8e3ccd529472ce3bcaf80" + "computedHash": "e02e84c9af9e5ba8b22161cc2c60517062a13bcc7d4e8763478257cae992e137" }, "debugging-and-error-recovery": { "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/debugging-and-error-recovery/SKILL.md", - "computedHash": "6f437bc609eb8d0dc7f4768c17c9aeb85c9c7632bc36703af9f1367ffb47237a" + "computedHash": "b6888f4fa9b5d683b6ac912a881c57e2ba521e5b1099d9340413538efb23cb84" }, "deprecation-and-migration": { "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/deprecation-and-migration/SKILL.md", - "computedHash": "0d7b2002e250c02a260f6bc502d7a798ab8e8ca0c020c54d7b0f16053935c72c" + "computedHash": "5b6d695fac255087957d27b7006d5aba2dcafbfed0dd3bae93b10ae3a7547568" }, "documentation-and-adrs": { "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/documentation-and-adrs/SKILL.md", - "computedHash": "f1bd038e74194364c1dcdb3dd0a72194ffd3ca9d3a103c125ca1a62e801a0cc4" + "computedHash": "85db994c5d2853bbd9ebdb8542e43d92b7229918a0c70126f0e94280ea1ceeec" }, "doubt-driven-development": { "source": "addyosmani/agent-skills", @@ -71,7 +71,7 @@ "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/frontend-ui-engineering/SKILL.md", - "computedHash": "49bb6ccfc41753bdd679f368ce75629ae9d424c5b8abc33faf949a4a55f919a1" + "computedHash": "22ee43d0367d2c3f611585eead5f0c413bcefa947da34b25a4935726ed76533e" }, "git-workflow-and-versioning": { "source": "addyosmani/agent-skills", @@ -83,7 +83,7 @@ "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/idea-refine/SKILL.md", - "computedHash": "77739c4f6a29c0fad465a30bab9e862445a3f1b0f92808ffcd541fa02ed0637b" + "computedHash": "f4400771e231aeaa6d954cc41ea5845b71d96d8f4d1df5e312849cd75bff97dd" }, "incremental-implementation": { "source": "addyosmani/agent-skills", @@ -107,7 +107,7 @@ "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/performance-optimization/SKILL.md", - "computedHash": "a2cdba94ff8f898183b3d5af736272dc439826083723b17a88782e75d2351530" + "computedHash": "276aec00aaabae98f4bd6d565745378b498e0d11688315f32179587746b93805" }, "planning-and-task-breakdown": { "source": "addyosmani/agent-skills", @@ -119,7 +119,7 @@ "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/security-and-hardening/SKILL.md", - "computedHash": "32a1243d6eb45fd342c1f4e9f9ee5f1651a1e9fdccb86dcbbbee5d6f455ed362" + "computedHash": "dbab1f4697ece5cab24a90911ae052320d8f8b191324df7f836aa42344699b89" }, "shipping-and-launch": { "source": "addyosmani/agent-skills", @@ -131,13 +131,13 @@ "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/source-driven-development/SKILL.md", - "computedHash": "d1923bb807f7db157a794f07a590ca639b3789b2f1a5eabef993f8df24791e2a" + "computedHash": "1397b7866630cda47bb5659d1ebb250012ca930c8217bf12b78200345f3328f6" }, "spec-driven-development": { "source": "addyosmani/agent-skills", "sourceType": "github", "skillPath": "skills/spec-driven-development/SKILL.md", - "computedHash": "90a53ee823e49fd1518a01e6cf64968d4848bce3fc0b0115b1c19b7e5a87a5ca" + "computedHash": "6ecb6a4920d1ae2ce03b81d69a06e3855008c669082afd830bf2c49a5b44abf6" }, "test-driven-development": { "source": "addyosmani/agent-skills", diff --git a/mattpocock/.claude/skills/chief-of-staff/SKILL.md b/mattpocock/.claude/skills/chief-of-staff/SKILL.md index 6dbdd4d..8ea0f46 100644 --- a/mattpocock/.claude/skills/chief-of-staff/SKILL.md +++ b/mattpocock/.claude/skills/chief-of-staff/SKILL.md @@ -19,7 +19,7 @@ Harness-permitting, you will suggest recurring schedules which can help in achie All work should be done in subagents. Protect your context window. -Use background agents so you can stay in active dialogue with the user. +Use background agents so you can stay in active dialogue with the user. Start every subagent with a fresh context window. Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: research notes, previous commits, wiki pages, and others. Don't duplicate information already available via pointers. diff --git a/mattpocock/.claude/skills/code-review/SKILL.md b/mattpocock/.claude/skills/code-review/SKILL.md index 373a4f2..83183e0 100644 --- a/mattpocock/.claude/skills/code-review/SKILL.md +++ b/mattpocock/.claude/skills/code-review/SKILL.md @@ -8,7 +8,7 @@ Two-axis review of the diff between `HEAD` and a fixed point the user supplies: - **Standards**: does the code conform to this repo's documented coding standards? - **Spec**: does the code faithfully implement the originating issue / spec? -Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. +Both axes run as **parallel sub-agents** so they don't pollute each other's context, then this skill aggregates their findings. Start every sub-agent with a fresh context window. The issue tracker should have been provided to you. If not, tell the user to run `/setup-matt-pocock-skills`. diff --git a/mattpocock/.claude/skills/codebase-design/DESIGN-IT-TWICE.md b/mattpocock/.claude/skills/codebase-design/DESIGN-IT-TWICE.md index d099013..aebdc9f 100644 --- a/mattpocock/.claude/skills/codebase-design/DESIGN-IT-TWICE.md +++ b/mattpocock/.claude/skills/codebase-design/DESIGN-IT-TWICE.md @@ -18,7 +18,7 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th ### 2. Spawn sub-agents -Spawn 3+ sub-agents in parallel. Each must produce a **radically different** interface for the deepened module. +Spawn 3+ sub-agents in parallel, each with a fresh context window. Each must produce a **radically different** interface for the deepened module. Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: diff --git a/mattpocock/.claude/skills/grilling/SKILL.md b/mattpocock/.claude/skills/grilling/SKILL.md index df69d99..d2f09a1 100644 --- a/mattpocock/.claude/skills/grilling/SKILL.md +++ b/mattpocock/.claude/skills/grilling/SKILL.md @@ -25,6 +25,6 @@ Word each question so "yes" accepts your recommended answer. Each round the user answers reshapes the tree: settled decisions push the frontier outward and unblock questions that depended on them. Recompute the frontier and ask the next round. A question whose answer depends on another question still open in this round belongs to a _later_ round, not this one. -Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait. +Finding _facts_ is your job, never the user's. When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent with a fresh context window to find it; don't ask the user for anything you could look up yourself. Don't block on it: a running exploration is an unsettled prerequisite, so only the questions downstream of it wait for the sub-agent to report; ask the rest of the frontier now. The _decisions_ are the user's: put each to them and wait. The session is done when the frontier is empty: every branch of the design tree visited, nothing left silently assumed. Do not act on it until the user confirms you have reached a shared understanding. diff --git a/mattpocock/.claude/skills/implement-spec/SKILL.md b/mattpocock/.claude/skills/implement-spec/SKILL.md index 1839237..73d36c2 100644 --- a/mattpocock/.claude/skills/implement-spec/SKILL.md +++ b/mattpocock/.claude/skills/implement-spec/SKILL.md @@ -12,6 +12,8 @@ The goal is the entire spec implemented on a single **integration branch**, with The tickets are not a list of steps. They are a **task graph** with blocking relationships between them. This means there is always a **frontier** of tickets which are ready to be grabbed. +Start every subagent with a fresh context window. + Communication to and from subagents should be sparse. Communicate primarily through **context pointers**: to the spec, tickets, research notes, and previous commits. Don't duplicate information already available via pointers. **Implementer subagents** should be run in the background where possible for maximum concurrency. @@ -24,7 +26,7 @@ Communication to and from subagents should be sparse. Communicate primarily thro 3. Create the integration branch. If the issue tracker closes work through PRs, or the user asks for one, open a draft PR after the first merge in step 5 (a branch with no commits ahead of main can't open one), marked as closing the spec and tickets. -4. Use **implementer subagents** to implement each ticket, each in its own worktree on its own branch. Each implementer subagent: +4. Use a fresh **implementer subagent** for each ticket, each in its own worktree on its own branch. Each implementer subagent: - confirms its worktree is based on the integration branch before starting, and resets onto it if not; - calls the Skill tool with `tdd` to build the ticket; - merges the integration branch tip into its own branch before reporting done @@ -33,7 +35,7 @@ Communication to and from subagents should be sparse. Communicate primarily thro 6. If this changes the **frontier** of available tickets, kick off more **implementer subagents** to work on the new tickets. This allows for maximum concurrency. -7. Once all tickets are complete, call the Skill tool with `code-review` on the integration branch. Fix all issues raised by the code review in a single **implementer subagent**. +7. Once all tickets are complete, call the Skill tool with `code-review` on the integration branch. Fix all issues raised by the code review in a single fresh **implementer subagent**. 8. If a draft PR exists, mark it ready for review. Otherwise, resolve each ticket the way the issue tracker closes work, and report the integration branch. diff --git a/mattpocock/.claude/skills/improve-codebase-architecture/SKILL.md b/mattpocock/.claude/skills/improve-codebase-architecture/SKILL.md index 44cc7d3..f1eabb5 100644 --- a/mattpocock/.claude/skills/improve-codebase-architecture/SKILL.md +++ b/mattpocock/.claude/skills/improve-codebase-architecture/SKILL.md @@ -24,7 +24,7 @@ This command is _informed_ by the project's domain model and built on a shared d Read the project's domain glossary (`GLOSSARY.md`) and any ADRs in the area you're touching first. -Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction: +Then spawn a sub-agent with a fresh context window to walk the codebase. Don't follow rigid heuristics; explore organically and note where you experience friction: - Where does understanding one concept require bouncing between many small modules? - Where are modules **shallow**, with an interface nearly as complex as the implementation? diff --git a/mattpocock/.claude/skills/research/SKILL.md b/mattpocock/.claude/skills/research/SKILL.md index fecee97..ffc9eb8 100644 --- a/mattpocock/.claude/skills/research/SKILL.md +++ b/mattpocock/.claude/skills/research/SKILL.md @@ -3,7 +3,7 @@ name: research description: Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent. --- -Spin up a **background agent** to do the research, so you keep working while it reads. +Spin up a **background agent** to do the research, so you keep working while it reads. Start it with a fresh context window. Its job: diff --git a/mattpocock/.claude/skills/wayfinder/SKILL.md b/mattpocock/.claude/skills/wayfinder/SKILL.md index e28cf30..975d6bf 100644 --- a/mattpocock/.claude/skills/wayfinder/SKILL.md +++ b/mattpocock/.claude/skills/wayfinder/SKILL.md @@ -112,7 +112,7 @@ User invokes with a loose idea. 2. **Map the frontier.** Grill again, **breadth-first** this time: fan out across the whole space rather than deep on any one thread, surfacing the open decisions and the first steps takeable now. **If this surfaces no fog** (the way to the destination is already clear, the whole journey small enough for one session), you don't need a map. Stop and ask the user how they'd like to proceed. 3. **Create the map** (label `wayfinder:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into **Not yet specified**. 4. **Create the tickets you can specify now** as child issues of the map, then wire blocking edges in a **second pass** (issues need ids before they can reference each other). Write cross-references in that pass too, with real ids: a placeholder `#` auto-links to an unrelated issue. Wiring sorts them into the frontier and the blocked; everything you can't yet specify stays in the fog: the **Not yet specified** section. -5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent that calls the Skill tool with "research" to resolve it in parallel, capturing its findings on a throwaway `research/` branch with a context pointer from the ticket. Push the branch but open no PR: it is never merged. +5. **Fire the research subagents.** For each `research` ticket you just created, spin up a subagent with a fresh context window that calls the Skill tool with "research" to resolve it in parallel, capturing its findings on a throwaway `research/` branch with a context pointer from the ticket. Push the branch but open no PR: it is never merged. 6. Stop: charting is one session's work; it hand-resolves nothing. ### Work through the map diff --git a/mattpocock/skills-lock.json b/mattpocock/skills-lock.json index d01d06b..cdd3ba6 100644 --- a/mattpocock/skills-lock.json +++ b/mattpocock/skills-lock.json @@ -11,7 +11,7 @@ "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/in-progress/chief-of-staff/SKILL.md", - "computedHash": "29e2444f8f030cefff1670f347e17cc839d3711aa904831a55cc1ac5475ec1c0" + "computedHash": "34a606e582e2021a552296f08268f8fe4c2f96e70428d20157f0dc001e708892" }, "claude-handoff": { "source": "mattpocock/skills", @@ -23,13 +23,13 @@ "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/code-review/SKILL.md", - "computedHash": "57cfd4ceb011f05e58a1a4f4cad3b2e03419d371f8990f4bcb32ff0d435a039f" + "computedHash": "c2745e2be960b82b9fddd82cf45265f42431e7b045c403f297b25f0f311e9210" }, "codebase-design": { "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/codebase-design/SKILL.md", - "computedHash": "b2888e4f4e8c0af3bfd557575a64b905c44e6248c3101d72077816882b3a92b9" + "computedHash": "aa11a96c08451f4ff86052d5da94004a8c97bb4ea41b2ac8a4300c189f66c89c" }, "diagnosing-bugs": { "source": "mattpocock/skills", @@ -65,7 +65,7 @@ "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/productivity/grilling/SKILL.md", - "computedHash": "ef1641a2047b71b60f1942cd35efb47d3afc9d584dff5a0b01f8c7db923aaa08" + "computedHash": "e40cc1d348f6d935e28f1e24474302d7368f0a400429271a43b35fe154891dc5" }, "handoff": { "source": "mattpocock/skills", @@ -83,13 +83,13 @@ "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/implement-spec/SKILL.md", - "computedHash": "f0db7dafd236fff9dc40da566cb72bbad6802674f64617b06959b00a436c7d5b" + "computedHash": "0ccc13c6766b0e5f55229c8f1252d004090da70e6610b4c324cd245970fcb3f1" }, "improve-codebase-architecture": { "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/improve-codebase-architecture/SKILL.md", - "computedHash": "ac2c94885f34ff8492dc12aa4543182f661f32ea1722b8d6b6c2c7045af33ae3" + "computedHash": "f768cb44209e0d30e3449b8f95ea3dc8293093f73cfe02127d530db43412cf76" }, "loop-me": { "source": "mattpocock/skills", @@ -119,7 +119,7 @@ "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/research/SKILL.md", - "computedHash": "c8c1cba327a6f824b554cd978079a3dadd7406d73174f8fb9bfef58824691970" + "computedHash": "5d85b64ecceed6b3f6d5996dc8af07180be8d1ff11ef3d26eda2acff078fbd39" }, "retro": { "source": "mattpocock/skills", @@ -197,7 +197,7 @@ "source": "mattpocock/skills", "sourceType": "github", "skillPath": "skills/engineering/wayfinder/SKILL.md", - "computedHash": "71d1296ae9f1ea0397f385f72d11ca3473827f5d067df4d06c58eb03377a57ce" + "computedHash": "22338d9356ef84430c5ca916f2632f226583d9d7366433f62bfde5b1b6781e9e" }, "wizard": { "source": "mattpocock/skills",