Practices & Tooling (engineering)

> Provenance: SKILL_AUTHORING.md, .agents/skills/ws-senior-developer/SKILL.md, .agents/skills/ws-fable-method/SKILL.md, .agents/skills/ws-megabrain/SKILL.md, package.json engines, living synthesis of specs 0008, 0011, 0025, 0042, 0055, 0058, 0063, 0072, 0074, 0084, 0085, 0086, 0090, 0099-us-358, 0110-us-378, 0112-us-381, 0114-patterns-generator-shared-hub-output, 0160-explicit-knowledge-chain.

Feature [edit]

Engineering practices keep agent diffs surgical and the toolchain uniform across the skill package. ws-senior-developer enforces scope control, surgical diff hygiene, anti-reinvention stops, ambiguity gates, and pre-ship proof, and as of 0.4.30 it consolidates the retired ws-karpathy-guidelines micro-diff contract; the karpathy-guidelines invocation alias and the rules.karpathyGuidelines compatibility pointer still resolve to it. ws-tdah shapes replies action-first for operational clarity and owns the wait-what grounded re-pitch flow that repairs comprehension failures by scoping the missing premise first and then rewriting it in ASD-STE100 Simplified Technical English with project nouns from stack docs or codebase symbols, preserving the action-first shape with a state line, numbered steps, and one concrete next step. ws-fable-method runs an evidence-based investigate loop before mutating work. All packaged skills follow SKILL_AUTHORING.md progressive-disclosure rules: three tiers, tool-first bodies, and zero sediment. ws-megabrain handles spec-optional vibe coding by routing through capped specialists instead of duplicating companion prose. The runtime standard is Node 22 .cjs helpers with a native PowerShell config editor on Windows and per-skill symlinks into host skill directories on global installs.

How it works [edit]

Surgical scope means touching only what the request requires, matching existing style, and ensuring every changed line traces to the request. Orphans created by the change are removed; unrelated dead code may be mentioned but is not deleted opportunistically. Parallel writers follow git-ownership.md: a session stages only the paths it owns, leaves a foreign dirty tree in place, and never runs a whole-tree reset, checkout --, restore, clean, or stash. refresh_baseline.cjs may move baselineCommit forward only. It stops when the new range overlaps a path this session did not edit. New helper scripts must be Node .cjs; reappearing .py helpers or leftover .pyc/.pyo bytecode fail ws-check-harness critically, and the test suite runs with Python absent from PATH. Bash survives only as thin host adapters that exec Node per tools.md launcher rules.

The PowerShell config editor (Edit-WorkflowSkillsConfig.ps1) preserves _comment* keys and unmodeled JSON fields, writes UTF-8 two-space JSON atomically after a .bak backup with a dirty guard, and exits cleanly on non-Windows or headless hosts by pointing operators at ws-configure-project. Megabrain defers whenever Spec-to-PR owns the session, reads at most two specialist references after mode selection or user-gate, and cancels cleanly when a gate dismisses.

The wait-what re-pitch triggers on explicit slash, hyphen, and spaced forms plus natural lost-me phrasing, and it treats the signal as a comprehension failure rather than a length complaint. The procedure requires naming the unstated premise before rewriting, then restating it in short direct ASD-STE100 sentences in the active voice with grounded project nouns. Every-turn directives forbid invented abstractions and stacked acronyms on one side and forbid caveman clipping that drops required causality on the other, so compression never degrades into pompous abstraction or cryptic telegram fragments. Companion EXAMPLES.md calibrates the flow with a before reject, a caveman reject, and a grounded after version of the same context, and the opt-out table documents the triggers while keeping the skill active.

Guardrail boundaries are skill-owned rather than dispatch-only: pipeline step skills declare their writable paths and forbid self-commit or push, keep a one-line Contract pointer for shared gates, and remain enforceable in standalone or lite runs where build_dispatch_context.cjs does not inject context. That injector inlines enhancing ## Subagent contract sections from ws-senior-developer, ws-tdah, and ws-self-learning and caps each section at 40 lines.

Gate prompts stay portable through a three-option ceiling: no single user-gate question carries more than 3 options, because some hosts reject larger structured choices. Menus with more candidates chunk instead of truncating — the resume gate asks intent first (resume versus start fresh) and then pages unfinished workflows at most 3 per question with More… navigation so every candidate stays reachable. Cancel remains a dismiss action rather than a numbered option on capped hosts, and coordinator-surfaced gates in ws-spec-to-pr-distributed step-baton runs follow the same chunking.

Workflow state hygiene requires nested telemetry maps to serialize as YAML mappings rather than Python-repr strings, duplicate completedSteps entries to union-sort, step artifact status to equal the per-step result through one derivation path, and file-list flags to accumulate only created, modified, and deleted. Git cleanup detaches worktrees and deletes only uswf-* tags, never protected branches; failures must not throw unhandled or corrupt telemetry.

Single-session CLI-harness runs bind host capabilities once and never re-probe mid-run. At bootstrap the run resolves the structured-choice binding (native choice tool versus markdown fallback) and the dispatch binding (native child agents versus background runner versus inline-isolated Tier 3) a single time and logs both, and it records the host-declared command-execution posture once at session start. Under a declared no-approval posture, routine shell recipes run quietly with non-interactive subject flags while every step-boundary user-gate stays intact, and the ship flow auto-resolves head, base, remote, provider, commit title, stage set, and consumer prepare obligations before asking about genuine ambiguity only. Approval bypass affects command execution alone and never waives workflow planning or converts normal mode into autoMode; when the host declares no posture, the run assumes approval is required. The shipped skill contract stays agent- and IDE-neutral throughout the adaptation.

Consumer projects gain their own generated skills without hand-writing boilerplate. A skill generator scaffolds a project-local skill from a short brief, seeds its body through seed_generated_skill.cjs under the shared hub output, and keeps the generated contract consistent with the harness layout so the new skill resolves through the same {skillsRoot} tokens. Self-learning feeds the same track: pattern runs compile into a stored project-patterns body under the shared hub, and later generations build on that persisted knowledge instead of starting blank.

Every skill edit consults the dependency graph first. Before changing a skill contract, the author reads bin/skill-dependencies.json plus package membership to identify callers and callees, verifies their inputs, outputs, scripts, and file conventions still hold against the change, and either updates them atomically in the same change or records explicit follow-ups. Integrity data regenerates and the harness checks run over the whole affected skill set in the same effort, so a change to one skill cannot silently leave a dependent contract inconsistent.

Investigations walk an explicit knowledge chain in order for every factual claim: codebase, then project docs, then MCP sources, then web. Earlier links are preferred over later ones, so citing a later link when an earlier link grounds the claim is a skipped-link violation, while an unreachable MCP server is a stated gap rather than a skipped link. Every factual claim cites the chain link that grounds it with a path, document, or URL reference; claims with no grounding source carry the UNCERTAIN marker and are never presented as observed fact. Reports close with a per-claim source table (Claim | Chain link | Reference | Uncertain), and a report without that table is returned for completion.

The harness closes with an opt-in retrospective. When config.json sets retro.enabled to explicit true, the standard and lite orchestrators run ws-retro once after the run's ship phase (before the optional proof-of-work step) without ever blocking close, ship, merge, or fix-PR convergence. The skill re-derives friction signals from workflow state, telemetry, and step artifacts, ranks candidates most-severe-first, and requires each candidate to cite a specific run moment plus exactly one destination category: memory, harness directive, reviewer standard, automated check, navigation pointer, or no-op deletion. validate_candidates.cjs rejects ungrounded or malformed candidates before presentation; approved memory entries persist through the ws-self-learning contract, environment edits apply only after user-gate approval, and auto runs propose without writing.

Backend [edit]

Authoring guidance lives in SKILL_AUTHORING.md. Megabrain exposes Router and Domain tables in SKILL.md with references/*.md specialists and REVERSE.md for archaeology-only flows. Shared runtime scripts under ws-shared/runtime/scripts/ include unified workflow git cleanup and autoload configuration helpers. package.json declares engines.node >= 22 with zero npm runtime dependencies for skill scripts.

ws-senior-developer carries Core Directives 1–6, the §5 Code review proof checklist, the ## Subagent contract that dispatch injects, and the stop ws-senior-developer / stop ws-karpathy-guidelines opt-outs. The 0.4.30 consolidation removed the standalone skill folder, its evals, and its dependency-graph entry while CATALOG.md, FEATURES.md, autoload rows, and the evals generator now point at the merged skill.

The WinForms config editor supports PowerShell 5.1 and 7+, themed tabs, hybrid layout with search, and description precedence _comment_<prop> over JSON schema over fallback strings. Recent editor work extends control coverage to proof-of-work switches and delivery-artifact flags with matching types, ranges, and section groupings, keeps diagnostic-only runs write-free, and always targets an explicit isolated -ConfigPath from tests so the repository hub is never touched. Recent fixes consolidated state serialization, artifact stamping, file-list accumulation, doctor ESM and --json contracts, and provider canonical tables with explicit launcher prefixes in skill bodies.