Stats

Actions

Available In

Tags

pragmatic-dev-toolkit

Claude Code plugin codifying the flat & pragmatic dev workflow: workflow skills for alignment, execution and diagnosis; YAGNI/QA/security/doc/design/prompt reviewers; self-gated hooks. Companion to scaffold-kit.

Product Engineer harness — infrastructure for the engineer to crystallize intent (/draft-idea, /triage), execute with discipline (/run-plan + reviewer per block), and anchor decisions (ADRs, plans, NOTES). Code is the canonical source of truth; doctrine records intent rather than generating it — contrasting deliberately with spec-first/generative approaches like github/spec-kit (see ADR-037).

What's inside

Component

Type

What it does

/draft-idea

Skill

Structured elicitation of IDEA.md (the product_direction role) via a multi-turn interview covering problem, persona, constraints, success criteria, and discarded alternatives. Upstream of /triage — invoke when the idea is still vague. Probe-canonical dual mode: absent → one-shot full (with a maturity gate in mature projects — semver ≥ 1.0.0 — that routes feature-shaped intents to /triage); present → section-by-section update via enum.

/note [--to <target>] <content>

Skill

Appends a timestamped note to .claude/local/NOTES.md (local-gitignored store extending ADR-047 to a non-role category per ADR-054 § Decisão (a)). Captures cross-session and cross-project context for the dev-solo workflow. Cross-project read is conversational — Claude resolves the path from context and operator confirms; no auto-discovery, no companion read skill. Cross-project write via /note --to <project-or-path> <content> (ADR-054 § Decisão (b)): resolves names through $PROJECTS_DIR with absolute-path fallback; target must be initialized for local mode (refusal otherwise). Intra-project, /triage and /next consult the store at step 1 as supplementary context (informational, non-blocking). Complements the native CC memory; does not replace it.

/triage

Skill

Aligns intent, surfaces gaps, decides which artifact (backlog line, plan, ADR, domain/design update) is needed before implementing. Without an argument, delegates to /next.

/next

Skill

Session orientation: reads the backlog, checks the codebase for what's already implemented, and suggests the top three impact candidates for triage. The top 3 mixes ## Próximos with plans carrying Status: Pendente under a cap-2 composition rule (BACKLOG keeps ≥1 slot). Pending validations from merged plans and Status: Abortado / residual Pendente plans are shown as separate informational blocks (not competing in the top 3).

/new-adr

Skill

Creates a new ADR in docs/decisions/ with auto-numbering and a standardized template. Pre-creation step 3.5 surfaces the admission policy filter (ADR-045 § Decisão parte 2) as an informational prompt — 3 outcomes (ADR Recommended / canonical doctrine (e.g. CLAUDE.md for mechanism, philosophy.md or project equivalent for epistemic) for stabilized understanding / git log for process evolution) with primary heuristics + tie-breaking criteria; redirects "stabilized understanding" or "process evolution" away from ADR creation. The template carries a 3-field temporal-revision metadata block (**Próxima revisão:**, **Cadência:**, **Critério de erosão auditável:**) between **Status:** and ## Origem; step 4.5 prompts the operator in plain prose for the substantive Critério (tri-state Goodhart guard rejecting cosmetic placeholders) while the other two fields auto-fill with canonical defaults (currentDate + 6 months, trimestral) per ADR-065.

/run-plan

Skill

Executes a plan from docs/plans/<slug>.md in an isolated worktree, with Conventional Commits micro-commits, per-block reviewer dispatch, manual validation gate when applicable, and a push/PR suggestion at the end. When the plan enumerates manual validation scenarios that are programmatically verifiable (smoke runs, fixture-based checks, textual comparisons), /run-plan offers to execute them on your behalf and defers the rest for human validation — reducing friction when the mechanical subset is coverable without interaction.

/debug <symptom>

Skill

Diagnoses root cause via scientific method (reproduce → isolate → hypothesize → evidence). Produces a diagnosis, not a fix — operator chooses revert / direct patch / /triage next. Stack-agnostic.