dotfiles

Guides creation of dubstack agent source files (agent.yaml + frontmatter.md + agent-body.md) through discovery, template selection, and iterative filling. Produces complete vera-cli native agent directories ready for `vera build`. Self-documenting templates teach the fill conversation; the skill orchestrates the process while the templates own the content knowledge. Primary entry point for adding a new agent to dubstack.

D-phase skill for the codesmith implementation workflow. Invokes render-design-doc-skeleton.py to overwrite the design.md placeholder with a tag-aware skeleton grounded in R-phase findings. Runs the always-interactive brain-surgery alignment conversation per Lock 6: agent presents each design section, human stress-tests via Question tool per substantive decision, iterate until aligned. Tracks the foundational-reversal strike counter per Lock 31. May identify multiple architecturally-distinct plans (NOT sub-tickets). Hands off to code-structure when D-phase is locked.

Q↔R loop skill for the codesmith implementation workflow. Applies Kipling structure (What/How/Who/When/Why/Where) × grill-with-docs discipline × per-tag emphasis matrix to derive code-layer questions. Composes research dispatch instructions (in-memory, NOT a written artifact) per the 7 composable research patterns. Dispatches `researcher` across the hide-the-intent boundary — researcher receives questions + scope only, not the ticket. Synthesizes returns into the bundle's research file. Updates CONTEXT.md inline as terms surface. Scaffolds Decision Records when the three-condition gate fires. Loops until five readiness criteria are met (problem scoped, current state mapped, impact understood, edge cases identified, agent can articulate unprompted). Hands off to code-design when readiness is confirmed.

I-phase orchestration skill per Lock 10. Iterates over the locked plan's slices in dependency order. For each slice: invokes worktree-setup (first slice only or once per parallel plan); dispatches `codesmith-worker` subagent with slice scope (plan + slice boundary + verification commands + commit convention + worktree path); awaits PHASE_COMPLETE or NEEDS_DECOMPOSITION; on decomposition triggers mini-replan per Lock 19; on completion invokes `code-verify` for the I-per-slice gate. Owns the plan-as-living-doc's structural sections; worker owns the per-slice log subsections. Tracks decomposition strike count (abort after 3 consecutive on the same slice per Lock 17.2).

Entry-point skill for the codesmith implementation workflow. Detects dual mode (planning vs execution) from initial input shape — ticket reference → planning mode; bundle directory → execution mode. In planning mode: loads the `status: ready` ticket, scaffolds the implementation bundle via scaffold-implementation-bundle.py, transitions ticket status `ready → active`, and hands off to code-grill. In execution mode: loads the existing bundle (ticket + design + structure + plans + optional research), confirms preconditions, and hands off to code-implement. Detects PR mode vs local-only mode based on remote configuration and user confirmation.

P-phase skill for the codesmith implementation workflow. Converts the structural skeleton into per-slice tactical steps (TDD vertical: failing test → minimal impl → green → verify → commit) per Lock 8. Produces one plan doc per plan identified in D-phase. Runs the Parallel-Safety Evaluation per Lock 27 to determine whether multiple plans execute in parallel worktrees or serialize. Spot-check user review; no open questions in the final plan. Hands off to worktree-setup (or directly to code-implement if Work-Tree is bypassed).

S-phase skill for the codesmith implementation workflow. Produces the structural skeleton (the C-header-file analog) per Lock 7. For each plan identified in D-phase, generates the list of files to create/modify with purpose, type/interface/schema signatures, test file structure, and vertical-slice identification. Locks STRUCTURE not tactics — the actual TDD steps (test → impl → green → verify → commit) are P-phase's job. Spot-check user review; hands off to code-plan when structure is locked.

V-phase verification gate orchestrator per Lock 11. Invoked at four of the five V-gates: D-review (after D locks), P-review (after P locks), I-per-slice (after each slice's commit), final-integration (after all slices). The fifth gate, PR-review, lives inline in pr-cycle. For each gate: selects mandatory + conditional angles from verification-angle-table.md; dispatches `codesmith-validator` with per-gate prompt; receives JSON findings; renders into the bundle's verification.md via render-verification-report.py; handles binary verdict (PROCEED | BLOCKED) with severity-driven blocking; returns loop-back target to the caller when BLOCKED.

Guides creation of dubstack command source files through discovery, type selection, and configuration. Commands are slash-triggered shortcuts — simpler than skills, producing a single .md file. Three types: STANDALONE (self-contained instructions), WRAPPER (thin shell delegating to a skill), AGENT-SPECIFIC (lives in agent subfolder, only available to that agent). Used when adding a slash command to dubstack.

Authoring spec for CONTEXT.md and CONTEXT-MAP.md. Load this when you are about to write to or update a project's vocabulary glossary. Defines glossary-only scope, the single-vs-multi-context layout, opinionated naming rules, the file template, the lazy-create policy, and the inline-update discipline. Reader-side awareness (when to read CONTEXT.md, how to use canonical terms) lives in the shared baseline — see `shared/baseline/context-md-awareness.md`. This skill is the authoring counterpart, loaded only by agents with write authority.

Format and gating rules for Decision Records (DRs) — the immutable audit-grade artifacts that capture hard-to-reverse decisions made during ticket-writing. Use when deciding WHETHER to write a DR (three-condition gate) and HOW to write one (minimal one-paragraph template, optional sections, schema-native frontmatter). Cross-agent: written by ticketsmith during ticket-grill or ticket-design; read by any agent that needs to understand why the system is shaped a certain way.

Extracts reusable patterns, conventions, and knowledge from existing artifacts (code, docs, prompts, conversations) into structured reference materials. The critical skill is PATTERN RECOGNITION — identifying what's reusable beyond the source material, actionable enough to guide future work, and structured for easy retrieval. Used when learning from examples to create templates, guidelines, or patterns; or when distilling a conversation into a teachable refinement.

Squash + rebase + merge + cleanup an implementation worktree into the target branch via worktrunk's `wt merge`. Used at V-completion in local-only mode (no PR cycle applies — no remote, or workflow run local-only). Replaces the PR-open + Gemini-review + human-merge stages of the V-phase with a single local-merge operation that produces the same end-state (code on the target branch, worktree cleaned up).

Automated PR review cycle for codesmith when PR mode applies. Opens the PR, waits for Gemini Code Assist review via the `await_pr_review` tool, dispatches `codesmith-validator` to assess each unresolved thread against the codebase, implements approved fixes via `codesmith-worker`, responds to threads, requests re-review, and loops until Gemini approves or a context-handoff signal fires. Escalates to human for the final merge decision. NEVER auto-merges. Used at V-phase PR-review gate (Lock 11 gate 5) when PR mode applies; pairs with `local-merge` for the non-PR alternative.

Compare two or more alternatives in a structured tradeoff matrix — libraries, technologies, vendors, or approaches. Derives the comparison criteria from the decision context (or accepts caller-supplied criteria), researches each alternative on every criterion in parallel tracks across the hide-the-intent boundary, and builds an evidence-backed matrix where each cell carries a citation. Surfaces per-criterion tradeoffs factually (on X, A leads; on Y, B leads) but does NOT compute weighted scores or declare a winner — which weights matter, and which alternative wins, belongs to the orchestrator. Persists the matrix as a decision-input document. Mode-aware: interactive confirms criteria and reviews the matrix; autonomous returns the matrix path. The right capability for 'Postgres vs Cassandra for our workload', 'Stripe vs Adyen', 'REST vs GraphQL for this API'.

Study one bounded topic in depth — typically within a single source domain — and produce a focused, persisted research write-up. The middle tier between Quick Answer (inline, no persistence) and Comprehensive Investigation (multi-domain, methodology-driven): heavier than a factual lookup, lighter than a full investigation. Decomposes the topic into a few same-domain aspects, dispatches the matching research children in one wave across the hide-the-intent boundary, synthesizes into a focused write-up with citations, and persists it to the thoughts research directory. Mode-aware: interactive reviews the draft once before persisting; autonomous runs to completion and returns the document path. Emits SCOPE_TOO_LARGE recommending escalation to Comprehensive Investigation when the topic turns out to span multiple source domains. The right capability for 'study how our rate limiting works and write it up' or 'study Stripe webhook retry semantics'.

Investigate a complex, multi-faceted question across multiple source domains and produce a persisted, evidence-rich research document. Selects an investigation methodology by question shape (domain / market / technical / codebase / general), decomposes the question into sub-questions, dispatches the six read-only research children in parallel waves across the hide-the-intent boundary, synthesizes findings once into the methodology's section structure, and persists the document to the thoughts research directory with citations, GitHub permalinks, and honest gap-marking. Mode-aware: interactive confirms the investigation plan and reviews sections at checkpoints; autonomous runs to completion and returns the document path. Emits SCOPE_TOO_LARGE with suggested sub-investigations when a question is too broad for a single coherent document. The workhorse for 'reconstruct everything we know about X', 'industry analysis of Y', 'how should we architect Z'.

Hunt for prior work and precedent — has this been done before, and does it apply to us? Searches three precedent sources in parallel: internal codebase (similar implementations to model after), the thoughts archive (prior tickets, decisions, plans, PRs), and external projects (open-source and documented industry patterns via web). Each precedent found is assessed for applicability — what matches our situation, what differs, and a factual transfer-fit class (directly-reusable / adaptable / informative / cautionary-anti-pattern) — then persisted as a precedent register. 'No precedent found' is a valid finding: it tells the caller the work is greenfield. When an external project warrants deep code study, recommends escalation to Scout External Codebase rather than cloning here. Mode-aware: interactive reviews the register; autonomous returns the register path. The right capability for 'has anyone built X before?', 'is there prior art for this pattern?', 'have we solved something like this?'.

Answer one or more focused factual research questions with source citations and return inline — no persisted research document. Dispatches the six read-only research children (codebase-locator, codebase-analyzer, codebase-pattern-finder, thoughts-locator, thoughts-analyzer, web-search-researcher) per question shape, in parallel, across the hide-the-intent boundary. Per-question synthesis: each answer carries file:line / URL / thoughts-alias citations, a confidence level, and an explicit gap note when evidence is thin. Mode-aware: interactive when a user invokes it (clarifies vague questions via the question tool); autonomous when dispatched from a workflow (emits ERROR on malformed dispatch, CLARIFICATION_NEEDED when a question is too vague to compose a child prompt). The fast path for freshness checks, existence checks, and grilling-loop research batches.

Identify what could go wrong with a proposed approach before it bites — an adversarial reconnaissance across the risk categories that apply (security, performance, regulatory, operational, correctness, cost). Selects the relevant risk lenses for the approach, scans each against the approach's own description, our internal exposure (codebase), prior incidents (thoughts archive), and known external risks (web), then builds a risk register: each risk with an evidence-grounded likelihood and impact, and the standard mitigation for its class. Adversarially skeptical — an approach that looks clean still gets its residual and low risks surfaced rather than declared all-clear. States risks and their known mitigations factually; whether and how to remediate is the orchestrator's call. Persists the register as a planning input. Mode-aware. The right capability for 'what could go wrong with this rollout?', 'security risks of this auth design', 'where does this approach break under load?'.

Scout an external open-source codebase for patterns and implementations, and persist the findings to a global, cross-project research catalog. Catalog-first: checks what has already been studied before cloning, so a repeat question reuses prior research instead of re-cloning. When a clone is needed, sets up a disposable .extern/ workspace, shallow-clones the repo, studies it with the read-only codebase children (pattern-finder, analyzer, locator) focused on the study topic, writes a research document to the global extern store, and records the study in the catalog via script. Clones are disposable; research is permanent. Studies code, not the web — invoking the skill is the approval to clone. Mode-aware: interactive confirms cleanup of the workspace; autonomous leaves the clone in place. The right capability for 'study how vercel/next.js implements middleware', or as the deep-study follow-up when Precedent Reconnaissance flags an external project worth reading in depth.

Guides creation of dubstack skill source files (skill.yaml + head.md + skill-overview.md + step files) through discovery, type selection, and section-by-section configuration. Two critical decisions shape every skill: TYPE (workflow / exec / data) and SCRIPTS (script-first mentality — if anything CAN be a script, it probably SHOULD be). Used when creating a new skill for an agent in dubstack.

D-phase skill for the ticket-writing workflow. Runs brain-surgery alignment with the user on the WORK to be done (not the technical solution — at the ticket-writing layer, D designs the work, not the implementation). Loads the Q↔R-ready bundle, drafts a design proposal (artifact chain + decision points + risk), aligns with user via firm checkpoint, handles redirects with the three-strike-foundational-reversal escalation counter from Lock 31, and writes the Design Summary into the ticket body. Hands off to ticket-structure.

Q↔R loop skill for the ticket-writing workflow. Runs iterative grilling against an oriented ticket bundle until the five readiness criteria from QRDSPIV are met. Mode-shifts between brainstorming, research, elicitation, and prototyping. Dispatches research subagents in parallel per the question-shape→subagent table. Updates CONTEXT.md inline via the context-md-format skill. Writes Decision Records via the decision-record-format skill when the three-condition gate fires. Loops back to itself until ready; hands off to ticket-design when readiness is confirmed.

Entry-point skill for the ticket-writing workflow. Runs the 7-step orient flow from spec §5: collects thoughts metadata, reads CONTEXT.md, performs tier-1 codebase orientation, detects the candidate primary tag from the user request, confirms scope with the user at a firm checkpoint, scaffolds the ticket bundle directory via scaffold-bundle.py, and hands off to ticket-grill for the Q↔R loop. Use as the first phase of every ticket-writing session before any grilling begins.

P-phase skill for the ticket-writing workflow. Plans HOW to fill the ticket sections defined by ticket-structure: writing order, per-section subagent dispatch (for sections requiring fresh research), review checkpoints (where to pause for user review during writing — especially Part boundaries for heavy tickets). Reads the Structure Outline; produces a Writing Plan section in the ticket body that ticket-write consumes. P is tactical: sequence, dispatch, and pause points — not content.

Owns the prototyping sub-activity of Q↔R per QRDSPIV. Invoked from ticket-grill (and any future grill-adopting agent) when the gap being explored requires running throwaway code to answer it. Two branches: LOGIC (terminal/minimal runnable for state or business-logic questions) and UI (visual variants for layout/flow/interaction; uses the project's design system if one exists). Prototype code lives at {shared_folder}/tickets/{slug}/prototypes/{name}/; findings are returned to the caller for inclusion in the bundle's research file. Per QRDSPIV: throwaway from day one, one command to run, no persistence by default, skip polish, surface state.

S-phase skill for the ticket-writing workflow. Designs the TICKET ITSELF — sections, numbered Parts for heavy tickets, custom outline for unusual ones. Tag recipe drives the default shape (when Phase 4 references are in place); custom outline applies when the recipe doesn't fit. Reads the Design Summary from ticket-design; produces a Structure Outline section in the ticket body that ticket-plan and ticket-write will consume. Per QRDSPIV §S: 'scope, don't prescribe' — the outline names sections, it doesn't fill them.

V-phase skill for the ticket-writing workflow. Self-reviews the drafted ticket against the severity ladder (Critical/High/Medium/Low); dispatches the ticket-reviewer subagent for fresh-context review on feature/exploration/infrastructure tags (no dispatch for bug/hotfix/chore). Resolves findings inline — self-evident fixes apply directly, ambiguous fixes go through user approval per finding, structural findings loop back to an earlier phase. After approved fixes, surfaces the draft→ready gate as the final user checkpoint.

I-phase skill for the ticket-writing workflow. Drafts the ticket section-by-section per the Writing Plan from ticket-plan. Pre-dispatches all planned subagents in parallel before writing begins (efficiency win); iterates through sections in writing order; pauses at planned checkpoints for user review. Each section follows AGENT-BRIEF discipline: durability over precision (no file paths, no line numbers); behavioral, not procedural; complete acceptance criteria; explicit scope boundaries. Hands off to ticket-verify.

Create the codesmith implementation worktree and branch via worktrunk. Resolves the branch name from the parent ticket's primary tag (per tag-recipes/{tag}.md Branch prefix section) and the parallel-safety determination (single worktree for sequential plans; one worktree per plan for parallel-safe multi-plan). Invokes `wt switch -c <branch>`. Returns the worktree path and branch name to the caller.

Queries, creates, updates, and manages QuickBooks Online data via the qbo CLI. Use when working with QBO entities (invoices, customers, bills, payments, vendors, accounts, items, estimates), running reports, or setting up install, auth, sandbox, and company switching.

Reviews existing tickets for gaps, inconsistencies, and issues with severity classification. This skill should be used when reviewing a ticket document for quality, completeness, and implementer readiness. Provides a structured review workflow with findings categorized by severity (Critical, High, Medium, Low) and specific before/after proposals for fixes.

Brand color discovery and palette generation skill. This skill should be used when helping users create brand color palettes, design systems, or Tailwind color configs. It guides through hue selection (RYB color wheel), chroma/tone decisions, and generates Obsidian-compatible palette reports with APCA accessibility validation. Supports starting from hex color or OKLCH values for refinement workflows. Triggers: "brand colors", "palette", "color scheme", "design system colors", "Tailwind colors", "generate palette from hex", "generate palette from OKLCH", or when users describe brand values that imply color decisions.

Reviews code changes for bugs, security issues, and adherence to codebase patterns. This skill should be used when reviewing diffs, commits, branches, or pull requests. It focuses on finding real bugs (not style nitpicks), verifying code fits existing patterns, and providing actionable feedback with clear severity levels.

The Planner's guide to becoming an orchestrator! Manages the complete implementation lifecycle: worktrees, branches, spawning Implement agents, validation gates, and decomposition triggers. When ready to execute a plan, load this skill.

Planning multiple workstreams? This skill identifies independent workstreams, spawns parallel planners, and analyzes dependencies between resulting plans. Perfect for large features spanning multiple components.

Your bulletproof guide to executing implementation phases! Handles commits, detects when phases are too big, and knows when to bail cleanly. Load this whenever you're implementing a phase - it provides clean commit protocol and signals the orchestrator when things go sideways.

Catch oversized phases BEFORE implementation begins! This skill reviews plans for sizing, dependencies, and completeness - flagging phases that need decomposition before a single line of code is written. Load this when validating plans pre-implementation.

Validates implementation plan execution by verifying success criteria and identifying deviations. This skill should be used after a phase or plan has been implemented and committed. It runs automated checks (tests, types, lint), compares actual changes against the plan's specifications, and generates a validation report documenting what was completed, what deviated, and what needs manual testing.