From d4ff742e42832e889a4a3b10f6e8820f0a738010 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Wed, 6 May 2026 06:38:24 -0500 Subject: fix(commands): drop leftover name: frontmatter from converted commands The conversion commit ran sed -i to strip the name: line, but the staged version from git mv was captured before the sed ran. Result: the commit shipped the original frontmatter, and the sed cleanup was sitting in the working tree. This commit lands the cleanup that should have been in aa69245. --- .claude/commands/arch-decide.md | 1 - .claude/commands/arch-design.md | 1 - .claude/commands/arch-document.md | 1 - .claude/commands/arch-evaluate.md | 1 - .claude/commands/brainstorm.md | 1 - .claude/commands/c4-analyze.md | 1 - .claude/commands/c4-diagram.md | 1 - .claude/commands/codify.md | 1 - .claude/commands/create-v2mom.md | 1 - .claude/commands/finish-branch.md | 1 - .claude/commands/prompt-engineering.md | 1 - .claude/commands/review-code.md | 1 - .claude/commands/start-work.md | 1 - 13 files changed, 13 deletions(-) diff --git a/.claude/commands/arch-decide.md b/.claude/commands/arch-decide.md index b0078fb..b0b35b8 100644 --- a/.claude/commands/arch-decide.md +++ b/.claude/commands/arch-decide.md @@ -1,5 +1,4 @@ --- -name: arch-decide description: Create, update, and manage Architecture Decision Records (ADRs) that capture significant technical decisions — context, options, chosen approach, consequences. Five template variants (MADR, Nygard, Y-statement, lightweight, RFC). Covers ADR lifecycle (proposed → accepted → deprecated / superseded), review process, and adr-tools automation. Use when documenting an architectural choice, reviewing past decisions, or establishing a decision process. Part of the architecture suite (arch-design / arch-decide / arch-document / arch-evaluate + c4-analyze / c4-diagram for notation-specific diagramming). --- diff --git a/.claude/commands/arch-design.md b/.claude/commands/arch-design.md index 744b8d0..2d52ba3 100644 --- a/.claude/commands/arch-design.md +++ b/.claude/commands/arch-design.md @@ -1,5 +1,4 @@ --- -name: arch-design description: Shape the architecture of a new or restructured software project through structured intake (quality attributes, stakeholders, constraints, scale, change drivers), then propose candidate architectural paradigms with honest trade-off analysis and a recommended direction. Paradigm-agnostic — evaluates options across layered, hexagonal, microservices, event-driven, CQRS, modular-monolith, serverless, pipe-and-filter, DDD, and others. Outputs a brief at `.architecture/brief.md` that downstream skills (arch-decide, arch-document, arch-evaluate) read. Use when starting a new project or service, restructuring an existing one, choosing a tech stack, or formalizing architecture before implementation. Do NOT use for bug fixing, code review, small feature additions, documenting an existing architecture (use arch-document), evaluating an existing architecture against a brief (use arch-evaluate), or recording specific individual decisions (use arch-decide). Part of the architecture suite (arch-design / arch-decide / arch-document / arch-evaluate + c4-analyze / c4-diagram for notation-specific diagramming). --- diff --git a/.claude/commands/arch-document.md b/.claude/commands/arch-document.md index 24a3720..178e847 100644 --- a/.claude/commands/arch-document.md +++ b/.claude/commands/arch-document.md @@ -1,5 +1,4 @@ --- -name: arch-document description: Produce a complete arc42-structured architecture document from a project's architecture brief and ADRs. Generates all twelve arc42 sections (Introduction & Goals, Constraints, Context & Scope, Solution Strategy, Building Block View, Runtime View, Deployment View, Crosscutting Concepts, Architecture Decisions, Quality Requirements, Risks & Technical Debt, Glossary). Dispatches to the c4-analyze and c4-diagram skills for building-block, container, and context diagrams. Outputs one file per section under `docs/architecture/`. Use when formalizing an architecture that already has a brief + ADRs, preparing documentation for a review, onboarding new engineers, or satisfying a compliance requirement. Do NOT use for shaping a new architecture (use arch-design), recording individual decisions (use arch-decide), auditing code against an architecture (use arch-evaluate), or for simple systems where a brief alone suffices. Part of the architecture suite (arch-design / arch-decide / arch-document / arch-evaluate + c4-analyze / c4-diagram for notation-specific diagramming). --- diff --git a/.claude/commands/arch-evaluate.md b/.claude/commands/arch-evaluate.md index f1c3391..6024b79 100644 --- a/.claude/commands/arch-evaluate.md +++ b/.claude/commands/arch-evaluate.md @@ -1,5 +1,4 @@ --- -name: arch-evaluate description: Audit an existing codebase against its stated architecture brief and ADRs. Runs framework-agnostic checks (cyclic dependencies, stated-layer violations, public API drift) that work on any language without setup, and opportunistically invokes language-specific linters (dependency-cruiser for TypeScript, import-linter for Python, go vet + depguard for Go) when they're already configured in the repo — augmenting findings, never replacing. Produces a report with severity levels (error / warning / info) and pointers to the relevant brief section or ADR for each violation. Use when auditing conformance before a release, during code review, when an architecture is suspected to have drifted, or as a pre-merge CI gate. Do NOT use for designing an architecture (use arch-design), recording decisions (use arch-decide), or producing documentation (use arch-document). Part of the architecture suite (arch-design / arch-decide / arch-document / arch-evaluate + c4-analyze / c4-diagram for notation-specific diagramming). --- diff --git a/.claude/commands/brainstorm.md b/.claude/commands/brainstorm.md index b47523f..b18d606 100644 --- a/.claude/commands/brainstorm.md +++ b/.claude/commands/brainstorm.md @@ -1,5 +1,4 @@ --- -name: brainstorm description: Refine a vague idea into a validated design through structured one-question-at-a-time dialogue, diverse option exploration (three conventional + three tail samples), and chunked validation (200-300 words at a time). Produces `docs/design/.md` as the output artifact. Use when shaping a new feature, service, or workflow before implementation begins — or when a "we should probably…" idea needs to become concrete enough to build. Do NOT use for mechanical well-defined work (renames, reformats, dependency bumps), for system-level architecture choices (use arch-design), for recording a single decision that has already been made (use arch-decide), or for debugging an existing error (use root-cause-trace or debug). Synthesized from the Agentic-Context-Engineering / SDD brainstorm pattern — probabilistic diversity sampling originated there. --- diff --git a/.claude/commands/c4-analyze.md b/.claude/commands/c4-analyze.md index ab8986b..1e20985 100644 --- a/.claude/commands/c4-analyze.md +++ b/.claude/commands/c4-analyze.md @@ -1,5 +1,4 @@ --- -name: c4-analyze description: Analyze a codebase or git repo and generate C4 architecture diagrams (System Context, Container, Component). Use when the user wants to visualize or document the architecture of an existing project. Dispatched by arch-document for building-block and container views; usable standalone for quick architecture visualization. Part of the architecture suite (arch-design / arch-decide / arch-document / arch-evaluate + c4-analyze / c4-diagram for notation-specific diagramming). argument-hint: "[path-or-container-name]" --- diff --git a/.claude/commands/c4-diagram.md b/.claude/commands/c4-diagram.md index 15948e4..3979966 100644 --- a/.claude/commands/c4-diagram.md +++ b/.claude/commands/c4-diagram.md @@ -1,5 +1,4 @@ --- -name: c4-diagram description: Generate C4 architecture diagrams from a textual description of a software system. Use when the user describes a system they want to diagram, or wants to create architecture diagrams for a planned/proposed system. Dispatched by arch-document for context and container views; usable standalone when the system is described in prose rather than existing code. Part of the architecture suite (arch-design / arch-decide / arch-document / arch-evaluate + c4-analyze / c4-diagram for notation-specific diagramming). argument-hint: "[description or diagram level]" --- diff --git a/.claude/commands/codify.md b/.claude/commands/codify.md index 4a0b5e6..414d831 100644 --- a/.claude/commands/codify.md +++ b/.claude/commands/codify.md @@ -1,5 +1,4 @@ --- -name: codify description: Codify concrete, actionable insights from recent session work into the project's `CLAUDE.md` so they survive across sessions and compound over time. Harvests patterns that worked, anti-patterns that bit, API gotchas, specific thresholds, and verification checks. Filters against quality gates (atomic, evidence-backed, non-redundant, verifiable, safe, stable). Writes into a dedicated `## Codified Insights` section rather than scattering entries. Use after a productive session, a bug fix that revealed a non-obvious pattern, or an explicit review where you want learnings preserved as rules. Supports `--dry-run` to preview, `--max=N` to cap output, `--target=` to write elsewhere, `--section=` to override the destination section. Flags insights that look cross-project and suggests promotion to `~/code/rulesets/claude-rules/` instead. Do NOT use for session wrap-up / progress summaries (not insights), for private personal context (auto-memory handles that, not a tracked file), or for formal rules that belong in `.claude/rules/`. Informed by Agentic Context Engineering (ACE, arXiv:2510.04618) — grow-and-refine without context collapse. --- diff --git a/.claude/commands/create-v2mom.md b/.claude/commands/create-v2mom.md index 9d2beef..f1add2f 100644 --- a/.claude/commands/create-v2mom.md +++ b/.claude/commands/create-v2mom.md @@ -1,5 +1,4 @@ --- -name: create-v2mom description: Create a V2MOM (Vision, Values, Methods, Obstacles, Metrics) strategic framework for any project, goal, or domain — personal infrastructure, business strategy, health goals, financial planning, software development, career planning, or life goals. Walks the user through the five sections in order: Vision first (aspirational picture of success), then Values (2-4 principles that guide decisions), Methods (4-7 prioritized approaches with concrete actions), Obstacles (honest personal and external challenges), and Metrics (measurable outcomes, not vanity metrics). Includes an optional task-migration phase that consolidates an existing todo list under the defined Methods. Use when the user asks to create a V2MOM, build a strategic plan, set goals for a significant project, or apply ruthless prioritization without an existing framework. Do NOT use for simple todo lists, single-decision prompts (use /arch-decide), quick task brainstorming (use /brainstorm), or daily/weekly planning of routine tasks. Produces a document that becomes the project's decision-making source of truth. --- diff --git a/.claude/commands/finish-branch.md b/.claude/commands/finish-branch.md index 0903010..b65a7f0 100644 --- a/.claude/commands/finish-branch.md +++ b/.claude/commands/finish-branch.md @@ -1,5 +1,4 @@ --- -name: finish-branch description: Complete a feature branch with a forced-choice menu of outcomes (merge locally / push + open PR / keep as-is / discard). Runs verification before offering options (tests, lint, typecheck per the project's conventions — delegates to `verification.md`). Requires typed confirmation for destructive deletion (no accidental work loss). Handles git worktree cleanup correctly: tears down for merge and discard, preserves for keep and push (where the worktree may still be needed for follow-up review or fixes). References existing rules for commit conventions (`commits.md`), review discipline (`review-code`), and verification (`verification.md`) — this skill is the workflow scaffold, not a re-teach of the underlying standards. Use when implementation is complete and you need to wrap up a branch. Do NOT use for mid-development merges (that's normal git flow), for the wrap-up *of a whole session* (different scope — session-end is narrative + handoff, not branch integration), for creating a new branch (no skill for that — just `git checkout -b`), or when review hasn't happened yet (run `/review-code` first, then this). --- diff --git a/.claude/commands/prompt-engineering.md b/.claude/commands/prompt-engineering.md index d566286..f2c240a 100644 --- a/.claude/commands/prompt-engineering.md +++ b/.claude/commands/prompt-engineering.md @@ -1,5 +1,4 @@ --- -name: prompt-engineering description: Craft prompts (commands, hooks, skill descriptions, sub-agent instructions, system prompts, one-shot requests to other LLMs) that do what they're meant to and resist common failure modes. Covers four moves that determine whether a prompt holds up: classify the prompt type (discipline-enforcing / guidance / collaborative / reference) to pick the right tone and techniques; apply the persuasion framework appropriate to that type (seven principles from Meincke et al. 2025, including which to avoid — notably Liking, which breeds sycophancy); match task fragility to degrees of freedom (high/medium/low); and spend the context window like a shared resource. Also contains a brief reference for classical techniques (few-shot, chain-of-thought, system prompts, templates). Use both in design mode (asking for help writing a new prompt from scratch) and critique mode (paste a draft, get it rewritten to resist common failure modes). Do NOT use for prose editing unrelated to LLM prompts (use a writing skill), for implementing application code that uses an LLM (different scope), or for content moderation / prompt-injection defense (adjacent but separate domain). --- diff --git a/.claude/commands/review-code.md b/.claude/commands/review-code.md index 1bb2bde..e7f4e18 100644 --- a/.claude/commands/review-code.md +++ b/.claude/commands/review-code.md @@ -1,5 +1,4 @@ --- -name: review-code description: Review code changes against engineering standards. Accepts a PR number, a SHA range (BASE..HEAD), the current branch's diff against main, staged changes, or a described scope ("the last 3 commits"). Audits CLAUDE.md adherence (reads root + per-directory CLAUDE.md), intent-vs-delivery (when given a plan/ADR/ticket), security, testing (TDD evidence + three-category coverage), conventions (conventional commits + no AI attribution), root-cause discipline, architecture (layering + scope), API contracts. Produces a structured report — Strengths, per-criterion PASS/WARN/FAIL, per-issue Critical/Important/Minor severity — ending with an explicit verdict (Approve / Request Changes / Needs Discussion) plus 1-2 sentence reasoning. Self-filters low-confidence findings; never flags pre-existing issues, lint/typecheck issues (CI handles those), or changes on unmodified lines. Use before merging a PR, before pushing a branch, or when reviewing a teammate's work. Do NOT use for proposing features (use brainstorm or arch-design), drafting implementation (use start-work or add-tests), standalone security audits (use security-check), or narrow style-only checks (a linter handles those). --- diff --git a/.claude/commands/start-work.md b/.claude/commands/start-work.md index 311476d..d3d9349 100644 --- a/.claude/commands/start-work.md +++ b/.claude/commands/start-work.md @@ -1,5 +1,4 @@ --- -name: start-work description: Pick up a task (Linear ticket, GitHub issue, todo.org task, or a described scope) and take it through Claim, Justify, Approach, Implement, Verify, and Hand-off. Three user-approval gates separate the phases. The Justify gate covers benefits, costs, engineer/user impact, urgency, effort, alternatives, and a ticket-quality check. The Approach gate covers root cause, risk, refactor prerequisites, test strategy (unit, integration, e2e, pairwise, characterization), migration and backwards-compat, feature-flag question, commit decomposition, and branch name. Implementation uses TDD (red, green, edge cases, refactor audit of every touched file). The audit walks the whole of each touched file against a language-agnostic checklist; every finding is either fixed on this branch or filed as a ticket — nothing is silently dropped. A verify phase exercises the feature end-to-end in the local environment (Playwright against localhost for web projects, scripted manual test otherwise) before the final gate confirms readiness and hands off to the Review-and-Publish flow in commits.md. Use when starting work on a specific task where both "should we" and "how exactly" are worth deliberating. Do NOT use for open-ended bug investigation without a clear target (use debug first), for architectural paradigm exploration (use arch-design), for architectural decision recording (use arch-decide), when the task is trivial and obvious (just do it), or when requirements are still being shaped (use brainstorm). --- -- cgit v1.2.3