citypaul

citypaul/.dotfiles

Agent Claude Code

This directory contains specifications for specialized Claude Code agents that work together to maintain code quality, documentation, and development workflow.

citypaul/.dotfiles

Agent Claude Code

Use this agent proactively when making significant architectural decisions and reactively to document architectural choices after they're made. Invoke when evaluating technology options, making foundational decisions, or discovering undocumented architectural choices.

citypaul/.dotfiles

Agent Claude Code

Use this agent to create or review maintained developer-facing documentation. It routes document shape, lifecycle, evidence, and ownership through the canonical technical-writing and expectations skills instead of imposing one template on every page.

citypaul/.dotfiles

Agent Claude Code

Use this agent when completed work reveals a durable, non-obvious constraint or practice that may need to be captured. It routes each learning to its actual owner rather than putting every insight in CLAUDE.md.

citypaul/.dotfiles

Agent Claude Code

Tracks progress through significant work using the repository's declared planning workflow, including vertical-slice or explicitly selected reduction-program plans and optional stacked-PR delivery maps. Use at the start of planned work, to update progress, and at the end to merge learnings.

citypaul/.dotfiles

Agent Claude Code

Use this agent to assess bounded refactoring opportunities after GREEN or another passing proportionate preservation baseline. Invoke when that baseline is established or when weighing whether an abstraction adds value. Mutation testing verifies the accumulated result later at the end-of-phase PR-readiness gate.…

citypaul/.dotfiles

Agent Claude Code

Use this agent to verify TDD process compliance for new or changed observable behavior during fast RED-GREEN-REFACTOR increments and the separate end-of-phase mutation gate. Invoke when users plan to implement behavior, when checking that behavior tests preceded implementation, before committing behavior-changing…

citypaul/.dotfiles

Agent Claude Code

Review changed TypeScript for evidence-backed type-safety defects. Use when defining types or schemas, or before committing TypeScript changes. Scope: type safety only; use the TDD or refactoring agents, or the panel-review skill (/panel-review), for their respective concerns.

citypaul/.dotfiles

Agent Claude Code

Read-only audit of an existing deployable service against the applicable Twelve-Factor principles. Use for deployment-readiness or infrastructure reviews; do not apply the method wholesale to libraries, CLIs, desktop apps, or embedded software.

citypaul/.dotfiles

Agent Claude Code

Read-only tracing of a user-facing use case through entry points, policy, domain logic, persistence, integrations, asynchronous work, and observable results. Use to explain an existing flow or find evidence-backed implementation gaps before changing it.

citypaul/.dotfiles

Command Claude Code

Continue after a merged independent PR or advance and sync a dependent PR stack.

citypaul/.dotfiles

Command Claude Code

Create a vertical-slice or selected reduction plan in the repository's planning workflow - no code changes.

citypaul/.dotfiles

Command Claude Code

One-shot project onboarding - detect tech stack, create CLAUDE.md, hooks, and commands.

citypaul/.dotfiles

Hook Claude Code

Runs after a tool call finishes for Write, Edit and NotebookEdit tool calls, running an inline shell check. From citypaul/.dotfiles.

citypaul/.dotfiles

Settings file Claude Code

Agent settings declaring 1 hook event (PostToolUse).

citypaul/.dotfiles

Skill Claude CodeCodex

WHEN deciding whether a PR, branch, diff, or current implementation satisfies an authoritative issue, specification, or decision contract; NOT for improving the written artifact, reconstructing meetings, general code review, or implementing fixes. Returns a read-only criterion-by-criterion proof and acceptance verdict.

citypaul/.dotfiles

Skill Claude CodeCodex

Stable consumer-facing API and interface design patterns. Use when designing REST endpoints, cross-team boundaries, or any externally consumed or versioned service contract. Covers contract-first development, error semantics (RFC 9457), REST conventions, pagination, idempotency, rate limiting, and backward…

citypaul/.dotfiles

Skill Claude CodeCodex

Decide whether a system needs a backend-for-frontend, how many, and what each one may own: adoption signals and honest costs, one-experience-one-BFF granularity with frontend-team ownership, the shape-don't-decide rule, upstream aggregation with partial-failure and resilience budgets, identity-keyed BFF caching…

citypaul/.dotfiles

Skill Claude CodeCodex

Design and protect browser-facing BFF and backend HTTP entry points: an explicit public/protected access classification for every production route, a composition-prepared endpoint registrar that installs session, Origin, Fetch Metadata, CSRF, and content-type policy by construction, provider-free authorization inside…

citypaul/.dotfiles

Skill Claude CodeCodex

Use when modifying existing code that lacks tests and you need to document its actual current behavior before making changes -- the legacy code dilemma where you need tests to refactor safely but the code was not written for testability. Specifically for understanding and pinning down what code currently does, not…

citypaul/.dotfiles

Skill Claude CodeCodex

Systematic CI/CD failure diagnosis using hypothesis-first investigation, local reproduction, and environment delta analysis. Use when a CI pipeline, GitHub Actions workflow, or build job fails; when tests pass locally but fail in CI; when diagnosing flaky tests, timeouts, or red pipelines; or when the user says "CI is…

citypaul/.dotfiles

Skill Claude CodeCodex

Unix-composable CLI design patterns. Use when building CLI tools, designing command trees, implementing output layers, or testing CLI behavior. Covers stream separation (stdout/stderr), format flags (--json/--plain), exit codes, TTY detection, composability, and error design. Language-agnostic principles; TypeScript…

citypaul/.dotfiles

Skill Claude CodeCodex

Design and evaluate deep modules: cohesive responsibility behind a small, stable caller-facing contract, with information hiding, justified seams, explicit effects, dependency strategy, and behavior-focused tests. Use when designing or changing an in-process module or package contract, consolidating shallow…

citypaul/.dotfiles

Skill Claude CodeCodex

WHEN diagnosing a reproducible or observable software failure outside a CI-pipeline-specific workflow; NOT for speculative cleanup, general code review, or speculative behavior changes presented as fixes. Preserves evidence, tests one causal hypothesis at a time, and fixes the owning boundary only when requested…