ralphctl 0.14.1 → 0.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,113 @@
1
+ ---
2
+ name: ralphctl-domain-driven-design
3
+ description: Domain-modelling skill — align code with the business domain through ubiquitous language, bounded contexts, small aggregates, domain events, and core-domain focus. Use when naming concepts, drawing module or service boundaries, deciding entity vs value object, integrating external systems, or when the code no longer matches how the business talks about itself.
4
+ license: MIT
5
+ ---
6
+
7
+ # Domain-Driven Design
8
+
9
+ > Adapted from [wondelai/skills](https://github.com/wondelai/skills) (MIT), itself distilling
10
+ > Eric Evans' _Domain-Driven Design: Tackling Complexity in the Heart of Software_ (2003).
11
+ > Adapted for ralphctl's harness contract.
12
+
13
+ Framework for tackling software complexity by modeling code around the business domain. The
14
+ greatest risk in software is not technical failure — it is building a model that does not
15
+ reflect how the business actually works.
16
+
17
+ **Core principle: the model is the code; the code is the model.** When domain experts and
18
+ developers speak the same language and that language is directly expressed in the codebase,
19
+ complexity becomes manageable and the system evolves gracefully as the business changes.
20
+
21
+ ## When this applies
22
+
23
+ - **Refine** — name acceptance criteria in the domain's language; a criterion that needs technical jargon to state usually hides an unmodelled concept.
24
+ - **Plan** — draw task boundaries along context and aggregate boundaries, not along technical layers.
25
+ - **Execute** — apply the building blocks below when creating or renaming types, modules, and events.
26
+
27
+ ## 1. Ubiquitous Language
28
+
29
+ A shared, rigorous language between developers and domain experts, used consistently in
30
+ conversation, documentation, and code. Ambiguity is the root cause of most modeling failures —
31
+ when a developer says "order" and an expert means "purchase request," bugs are inevitable.
32
+
33
+ - The language emerges from collaboration, not a glossary bolted on after the fact.
34
+ - If a concept is hard to name, the model is likely wrong — naming difficulty is a design signal.
35
+ - Technical jargon (`DataProcessor` vs. `ClaimAdjudicator`) hides domain logic from the experts who could correct it.
36
+ - Name classes and methods after domain concepts and verbs — `LoanApplication`, `policy.underwrite()`, not `RequestHandler`, `process()`.
37
+ - Organize modules by domain concept (`shipping/`, `billing/`), not technical role (`controllers/`, `services/`).
38
+ - In review, flag `Manager`, `Helper`, `Processor`, `Utils` as naming smells.
39
+
40
+ ## 2. Bounded Contexts and Context Mapping
41
+
42
+ A bounded context is an explicit boundary within which a particular domain model applies. The
43
+ same word ("Customer") can mean different things in different contexts — and that is fine.
44
+ Large systems that force a single unified model inevitably collapse into inconsistency.
45
+
46
+ - A bounded context is not a microservice — it is a linguistic and model boundary that may contain multiple services; start with modules in a monolith.
47
+ - Context boundaries often align with team boundaries (Conway's Law).
48
+ - The Anti-Corruption Layer is the most important defensive pattern — never let a foreign model leak into your core domain; the exception is a deliberately Conformist integration where you accept the upstream model wholesale to save translation cost.
49
+ - Translate external API responses into your own domain objects at the boundary; wrap legacy systems behind an adapter that speaks your domain language.
50
+ - A Shared Kernel couples two teams; keep it small and explicitly governed.
51
+
52
+ ## 3. Entities, Value Objects, and Aggregates
53
+
54
+ Entities have identity that persists across state changes. Value Objects are defined entirely by
55
+ their attributes and are immutable. Aggregates are clusters with a single root that enforces
56
+ consistency boundaries.
57
+
58
+ - Entity test: "Am I the same thing even if all my attributes change?" (a person changes name and address — still the same person).
59
+ - Value Object test: "Am I defined only by my attributes?" (any $10 bill is interchangeable with another).
60
+ - Most things should be Value Objects, not Entities — prefer immutability; replace, never mutate — except where the domain genuinely tracks identity over time.
61
+ - Keep aggregates small (one root plus a minimal cluster); reference other aggregates by ID, not object reference.
62
+ - Immediate consistency only within an aggregate; design for eventual consistency between aggregates.
63
+
64
+ ## 4. Domain Events
65
+
66
+ A domain event captures something that happened that experts care about, named in past tense
67
+ (`OrderPlaced`, `PaymentReceived`) — a fact that has already occurred. Events decouple cause
68
+ from effect: shipping, billing, and notifications each react to `OrderPlaced` independently,
69
+ without the ordering context knowing about them.
70
+
71
+ - Events are immutable facts — once published, they cannot be changed or retracted.
72
+ - Domain events are internal to a bounded context; integration events cross boundaries.
73
+ - Not every state change deserves an event — only publish what the domain cares about.
74
+
75
+ ## 5. Repositories and Factories
76
+
77
+ Repositories provide the illusion of an in-memory collection of domain objects, hiding
78
+ persistence. Factories encapsulate complex creation so aggregates are always born valid — an
79
+ invalid instance becomes unrepresentable.
80
+
81
+ - The repository interface belongs in the domain layer; its implementation belongs in infrastructure.
82
+ - Repository methods speak the ubiquitous language: `findPendingOrders()`, not `getByStatusCode(3)`.
83
+ - Factories are warranted for complex rules or multi-part assembly; a two-field Value Object just needs a constructor.
84
+
85
+ ## 6. Strategic Design and Distillation
86
+
87
+ Not all parts of a system are equally important. Identify the Core Domain — where competitive
88
+ advantage lives — and distinguish it from Supporting Subdomains (necessary, not differentiating)
89
+ and Generic Subdomains (commodity).
90
+
91
+ - Core Domain: invest the deepest modeling. Supporting: build, but don't over-engineer. Generic (auth, email, payments): buy or use off-the-shelf.
92
+ - Revisit what is "core" as the business evolves — today's differentiator may become tomorrow's commodity.
93
+
94
+ ## Common Mistakes
95
+
96
+ | Mistake | Why It Fails | Fix |
97
+ | --------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------- |
98
+ | Technical names, not domain terms | Logic hidden behind `DataManager`; experts can't validate the model | Rename to domain terms; if no domain term exists, the concept may be wrong |
99
+ | One model to rule them all | A single `Customer` class for billing, shipping, and marketing becomes bloated | Bounded contexts: each gets its own `Customer` with only what it needs |
100
+ | Giant aggregates | Concurrency conflicts, slow loads, transactional bottlenecks | Keep aggregates small; reference by ID; eventual consistency between |
101
+ | Anemic domain model | Objects are data bags; rules scatter across services and duplicate | Move behavior into entities and value objects; services orchestrate only |
102
+ | No Anti-Corruption Layer | Foreign models leak in; code couples to external schemas | Wrap every external system behind a translation layer |
103
+ | Bounded context = microservice | Premature extraction; distributed complexity without benefit | A context is a model boundary, not a deployment unit |
104
+ | Skipping domain experts | Developers invent a model that doesn't match reality; expensive rework | Model against the domain vocabulary in the task's source material |
105
+
106
+ ## Quick Diagnostic
107
+
108
+ - Can a domain expert read your class names and understand them? If not — rename to the ubiquitous language.
109
+ - Are bounded context boundaries explicitly defined? If not — draw a context map with translations.
110
+ - Are aggregates small (one root + minimal cluster)? If not — split; reference by ID.
111
+ - Do domain objects contain behavior, not just data? If not — move rules out of services into the model.
112
+ - Is there an Anti-Corruption Layer at every external integration? If not — add a translation layer at the boundary.
113
+ - Have you identified which subdomain is core? If not — classify, and spend the deep modeling there.
@@ -0,0 +1,107 @@
1
+ ---
2
+ name: ralphctl-idea-refinement
3
+ description: Ideation skill — refine a raw, unshaped idea into a sharp, buildable concept through divergent expansion (variation lenses like inversion, simplification, audience shift) followed by convergent stress-testing (user value, feasibility, differentiation), ending in a one-pager with explicit assumptions and a "Not Doing" list. Use when an idea is still vague and multiple directions should be widened before narrowing; once a direction is already concrete, confirming it is the shorter restate-and-agree pass in ralphctl-alignment, not a full ideation cycle.
4
+ license: MIT
5
+ ---
6
+
7
+ # Idea Refinement
8
+
9
+ > Adapted from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) (MIT).
10
+ > Adapted for ralphctl's harness contract.
11
+
12
+ You are an ideation partner. Your job is to refine raw ideas into sharp, actionable concepts
13
+ worth building — through structured divergent and convergent thinking, not a template.
14
+
15
+ ## When this applies
16
+
17
+ - **Ideate** — the primary home: turning a raw prompt or hunch into evaluated, distinct directions.
18
+ - **Refine** — when the input requirement is really an unshaped idea: run a compressed version of the phases below before writing acceptance criteria.
19
+
20
+ ## Philosophy
21
+
22
+ - Simplicity is the ultimate sophistication. Push toward the simplest version that still solves the real problem.
23
+ - Start with the user experience, work backwards to technology.
24
+ - Say no to 1,000 things. Focus beats breadth.
25
+ - Challenge every assumption. "How it's usually done" is not a reason.
26
+ - Show people the future — don't just give them better horses.
27
+
28
+ ## Phase 1 — Understand & Expand (divergent)
29
+
30
+ Take the raw idea and open it up.
31
+
32
+ - **Restate the idea** as a crisp "How Might We" problem statement. This forces clarity on what is actually being solved.
33
+ - **Ask 3-5 sharpening questions** — no more. Who is this for, specifically? What does success look like? What are the real constraints (time, tech, resources)? What's been tried before? Why now? When the session has an interactive channel, ask and wait; when it does not, state the answers you are assuming as explicit assumptions and carry them into Phase 2.
34
+ - **Generate 5-8 idea variations** using these lenses: inversion ("what if we did the opposite?"), constraint removal, audience shift, combination with an adjacent idea, simplification ("the version that's 10x simpler"), the 10x version at massive scale, and the expert lens ("what would domain experts find obvious?"). Pick the lenses that fit the idea — don't run every lens mechanically.
35
+
36
+ When running inside a codebase, scan for relevant context first — existing architecture,
37
+ patterns, constraints, prior art — and ground the variations in what actually exists,
38
+ referencing specific files and patterns when relevant.
39
+
40
+ ## Phase 2 — Evaluate & Converge
41
+
42
+ After reactions to Phase 1 (which ideas resonate, pushback, added context) — or, without an
43
+ interactive channel, after weighing the variations against the stated constraints — shift to
44
+ convergent mode:
45
+
46
+ - **Cluster** the strongest ideas into 2-3 distinct directions. Each direction should feel meaningfully different, not variations on a theme.
47
+ - **Stress-test** each direction against three criteria: user value (painkiller or vitamin?), feasibility (what's the hardest part?), and differentiation (would someone switch from their current solution?).
48
+ - **Surface hidden assumptions.** For each direction, explicitly name what you're betting is true but haven't validated, what could kill the idea, and what you're choosing to ignore (and why that's okay for now). This is where most ideation fails — don't skip it.
49
+
50
+ Be honest, not supportive. If an idea is weak, say so with kindness. A good ideation partner is
51
+ not a yes-machine: push back on complexity, question real value, and point out when the emperor
52
+ has no clothes.
53
+
54
+ ## Phase 3 — Sharpen & Ship
55
+
56
+ Produce a concrete artifact — a markdown one-pager that moves work forward:
57
+
58
+ ```markdown
59
+ # [Idea Name]
60
+
61
+ ## Problem Statement
62
+
63
+ [One-sentence "How Might We" framing]
64
+
65
+ ## Recommended Direction
66
+
67
+ [The chosen direction and why — 2-3 paragraphs max]
68
+
69
+ ## Key Assumptions to Validate
70
+
71
+ - [ ] [Assumption — how to test it]
72
+
73
+ ## MVP Scope
74
+
75
+ [The minimum version that tests the core assumption. What's in, what's out.]
76
+
77
+ ## Not Doing (and Why)
78
+
79
+ - [Thing] — [reason]
80
+
81
+ ## Open Questions
82
+
83
+ - [Question that needs answering before building]
84
+ ```
85
+
86
+ The "Not Doing" list is arguably the most valuable part. Focus is about saying no to good ideas —
87
+ make the trade-offs explicit. Deliver the one-pager through the flow's designated output channel
88
+ rather than inventing a location for it.
89
+
90
+ ## Anti-patterns
91
+
92
+ - **Generating 20+ ideas.** Quality over quantity — 5-8 well-considered variations beat 20 shallow ones.
93
+ - **Yes-machining.** Push back on weak ideas with specificity and kindness.
94
+ - **Skipping "who is this for."** Every good idea starts with a person and their problem.
95
+ - **A plan without surfaced assumptions.** Untested assumptions are the #1 killer of good ideas.
96
+ - **Over-engineering the process.** Three phases, each doing one thing well — resist adding steps.
97
+ - **Listing ideas without a story.** Each variation should have a reason it exists, not just be a bullet point.
98
+ - **Ignoring the codebase.** Inside a project, the existing architecture is a constraint and an opportunity — use it.
99
+
100
+ ## Verification (self-review before finishing)
101
+
102
+ - [ ] A clear "How Might We" problem statement exists.
103
+ - [ ] The target user and success criteria are defined — or the assumed answers are named explicitly.
104
+ - [ ] Multiple directions were explored, not just the first idea.
105
+ - [ ] Hidden assumptions are listed with validation strategies.
106
+ - [ ] A "Not Doing" list makes trade-offs explicit.
107
+ - [ ] The output is a concrete one-pager, not just conversation.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: ralphctl-iterative-review
3
- description: Cross-phase skill — treat AI output as a controlled feedback loop, not a one-shot generation. Run the cheap check after each meaningful change; re-read your own output before signalling completion.
3
+ description: Cross-phase skill — treat AI output as a controlled feedback loop, not a one-shot generation. Run the cheap check after each meaningful change; re-read your own output before signalling completion. For the fuller session workflow — plan-first sequencing plus durable learning capture — see the opt-in ralphctl-cherny-workflow skill.
4
4
  ---
5
5
 
6
6
  # Iterative Review
@@ -0,0 +1,76 @@
1
+ ---
2
+ name: ralphctl-karpathy-guidelines
3
+ description: Behavioural guardrails against four empirical LLM coding failure modes — silent assumptions, over-complication, orthogonal damage to code you don't fully understand, and declaring done without verification. Use when writing, reviewing, or refactoring code to surface assumptions early, keep changes proportionate to the task, and loop until explicit success criteria pass; broader than the implementation-choice ladder in ralphctl-ponytail or the scope checklist in ralphctl-surgical-simplicity (when those are installed), which it complements rather than duplicates.
4
+ ---
5
+
6
+ # Karpathy Guidelines
7
+
8
+ > Distilled from Andrej Karpathy's public commentary on LLM coding pitfalls — his January 2026
9
+ > [X post on agentic coding](https://x.com/karpathy/status/2015883857489522876). Clean-room —
10
+ > concepts only, not copied text.
11
+
12
+ Karpathy's observation, after moving most of his coding to agents: the mistakes agents make are
13
+ not random — they cluster into four recurring failure modes. Each mode below pairs the failure
14
+ with the counter-habit that prevents it. Treat these as standing behavioural rules for every
15
+ coding turn, not a checklist to run once.
16
+
17
+ ## When this applies
18
+
19
+ - **Plan** — modes 1 and 4 dominate: a plan built on an unstated assumption, or with success criteria that can't be checked, fails before any code exists.
20
+ - **Execute** — all four modes: every generation, edit, and refactor is an opportunity to silently assume, over-build, damage bystander code, or stop before verifying.
21
+
22
+ ## Mode 1 — Silent assumptions
23
+
24
+ The failure: making a plausible assumption on the operator's behalf and running with it
25
+ unchecked — not managing your own confusion, not surfacing inconsistencies, not presenting
26
+ trade-offs, not pushing back when the request conflicts with what the code shows.
27
+
28
+ The counter-habit:
29
+
30
+ - When the task is ambiguous, name the ambiguity before acting. With an interactive channel, ask; without one, state the interpretation you chose and why in a `<decision>` or `<note>` signal, then proceed with the least-surprising reading.
31
+ - When the task's description contradicts what you find in the code, surface the contradiction — do not quietly pick a side.
32
+ - When two implementations satisfy the words of the task but differ in consequence, present the trade-off rather than silently committing to one.
33
+ - Push back when the request is likely a mistake. Deference that ships a wrong change is not helpfulness.
34
+
35
+ ## Mode 2 — Over-complication
36
+
37
+ The failure: bloated abstractions, over-general APIs, a thousand lines where a hundred would do —
38
+ and dead code left behind because nothing forced its cleanup.
39
+
40
+ The counter-habit:
41
+
42
+ - Write the simplest version that solves the stated problem. Generality earns its place only when a second concrete caller exists.
43
+ - Prefer one plain function over a class hierarchy, a flag, or a plugin point invented for a future that was never requested.
44
+ - When your change makes code unreachable, delete that code in the same change — dead code you created is your cleanup, not a future task.
45
+ - Re-read your diff asking one question: what can be removed without failing the task?
46
+
47
+ ## Mode 3 — Orthogonal damage
48
+
49
+ The failure: changing or deleting comments, formatting, or neighbouring code that the task never
50
+ asked about — side effects on things you did not fully understand, orthogonal to the goal.
51
+
52
+ The counter-habit:
53
+
54
+ - Preserve comments you did not write unless your change makes them false — then update them, don't drop them.
55
+ - Leave formatting, naming, and structure outside your change's boundary untouched, even when you disagree with it.
56
+ - Never edit code you don't understand just because it sits next to code you do; the exception is when the task itself is to change that code — then understanding it first is the task.
57
+ - If your tooling reformats or rewrites beyond your intended lines, trim the diff back to what the task requires.
58
+
59
+ ## Mode 4 — Unverified completion
60
+
61
+ The failure: declaring the work done because the code looks right, without ever defining what
62
+ "done" means or demonstrating it.
63
+
64
+ The counter-habit:
65
+
66
+ - Before writing code, state the success criteria as checkable predicates — a test that passes, a command that exits cleanly, an observable behaviour.
67
+ - After each meaningful change, run the narrowest check that could falsify it; do not batch many unverified changes and hope.
68
+ - Loop: change → check → compare against the criteria — until the criteria demonstrably pass. "It should work now" is a hypothesis, not a result.
69
+ - Reaching the criteria is your job; the harness owns the final post-task verify gate — arrive at it in a demonstrably clean state rather than certifying completion yourself.
70
+
71
+ ## Self-check before finishing
72
+
73
+ - [ ] Every assumption I made is either confirmed or explicitly surfaced.
74
+ - [ ] Nothing in the diff exists "for later" — every line serves the stated task.
75
+ - [ ] No comment, formatting, or bystander code changed without a task-driven reason.
76
+ - [ ] The success criteria were stated up front and each one has been demonstrated, not assumed.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: ralphctl-minimal-scaffolding
3
- description: Cross-phase skill — question every harness component on every model bump; remove non-load-bearing pieces one at a time with measurement. Complexity drifts upward by default; subtraction requires discipline.
3
+ description: Cross-phase skill — question every harness component on every model bump; remove non-load-bearing pieces one at a time with measurement. Complexity drifts upward by default; subtraction requires discipline. Governs the surrounding harness's own scaffolding, not the task's application code — for code-level minimalism defer to the ralphctl-ponytail, ralphctl-surgical-simplicity, and ralphctl-karpathy-guidelines skills when installed in this session.
4
4
  ---
5
5
 
6
6
  # Minimal Scaffolding
@@ -0,0 +1,86 @@
1
+ ---
2
+ name: ralphctl-ponytail
3
+ description: Anti-over-engineering ladder for choosing HOW to implement something — before writing custom code, climb the rungs in order and stop at the first that holds. Does this need to exist at all (YAGNI) → already in the codebase → standard library → native platform feature → already-installed dependency → one line → minimum code that works. Use when picking an implementation approach or evaluating a new dependency; for keeping the footprint of an already-chosen approach small, defer to the ralphctl-surgical-simplicity skill when installed.
4
+ license: MIT
5
+ ---
6
+
7
+ # Ponytail
8
+
9
+ > Adapted from [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) (MIT).
10
+ > Adapted for ralphctl's harness contract.
11
+
12
+ Be a lazy senior developer. Lazy means efficient, not careless — the posture of someone who has
13
+ seen every over-engineered codebase and been paged at 3am for one. The best code is the code
14
+ never written.
15
+
16
+ ## When this applies
17
+
18
+ - **Plan** — when sizing tasks, prefer the plan whose steps each pass the ladder; a task that
19
+ exists only to build scaffolding "for later" should not exist.
20
+ - **Execute** — every time you are about to write code: new features, fixes, refactors, and
21
+ especially the moment before adding a dependency.
22
+ - **Create PR** — when summarising the change, name what was deliberately skipped and when it
23
+ would be worth adding.
24
+
25
+ ## The ladder
26
+
27
+ Stop at the first rung that holds:
28
+
29
+ 1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
30
+ 2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
31
+ 3. **Standard library does it?** Use it.
32
+ 4. **Native platform feature covers it?** A built-in form control over a widget library, a stylesheet rule over scripted behaviour, a database constraint over application code.
33
+ 5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
34
+ 6. **Can it be one line?** One line.
35
+ 7. **Only then:** the minimum code that works.
36
+
37
+ The ladder is a reflex, not a research project — but it runs _after_ you understand the problem,
38
+ not instead of it. Read the task and the code it touches first, trace the real flow end to end,
39
+ then climb. Two rungs work → take the higher one and move on. The first lazy solution that works
40
+ is the right one — once you actually know what the change has to touch.
41
+
42
+ **Bug fix = root cause, not symptom.** A report names a symptom. Before you edit, find every
43
+ caller of the function you're about to touch. The lazy fix IS the root-cause fix: one guard in
44
+ the shared function is a smaller diff than a guard in every caller — and patching only the path
45
+ the report names leaves every sibling caller still broken. Fix it once, where all callers route
46
+ through.
47
+
48
+ ## Rules
49
+
50
+ - No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
51
+ - No boilerplate, no scaffolding "for later" — later can scaffold for itself.
52
+ - Deletion over addition. Boring over clever — clever is what someone decodes at 3am.
53
+ - Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
54
+ - Complex request? Ship the lazy version and question the rest in a `<note>` signal: "Did X; Y covers it. Need full X? Say so." Never stall on an answer you can default.
55
+ - Two standard-library options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
56
+ - Mark deliberate simplifications with a `ponytail:` comment (`// ponytail: this exists`) — simple reads as intent, not ignorance. Shortcut with a known ceiling (global lock, O(n²) scan, naive heuristic)? The comment names the ceiling and the upgrade path: `// ponytail: global lock, per-account locks if throughput matters`.
57
+
58
+ ## Output
59
+
60
+ Code first. Keep any accompanying explanation to a few short lines: what was skipped, when to
61
+ add it. If the explanation is longer than the code, delete the explanation — every paragraph
62
+ defending a simplification is complexity smuggled back in as prose. Explanation the task
63
+ explicitly asked for (a report, a walkthrough, per-step notes) is not debt — give it in full;
64
+ the rule is only against unrequested prose. Deliberate skips worth remembering belong in a
65
+ `<note>` signal: skipped X, add when Y.
66
+
67
+ ## When NOT to be lazy
68
+
69
+ Never simplify away: input validation at trust boundaries, error handling that prevents data
70
+ loss, security measures, accessibility basics, anything the task explicitly requests. The task
71
+ insists on the full version → build it, no re-arguing.
72
+
73
+ Never lazy about understanding the problem. The ladder shortens the solution, never the reading.
74
+ Trace the whole thing first — every file the change touches, the actual flow — before picking a
75
+ rung. Laziness that skips comprehension to ship a small diff is the dangerous kind: it dresses
76
+ up as efficiency and ships a confident wrong fix. Read fully, then be lazy.
77
+
78
+ Hardware is never the ideal on paper: a real clock drifts, a real sensor reads off. Leave the
79
+ calibration knob, not just less code — the physical world needs tuning a minimal model can't see.
80
+
81
+ Lazy code without its check is unfinished. Non-trivial logic (a branch, a loop, a parser, a
82
+ money/security path) leaves ONE runnable check behind — the smallest thing that fails if the
83
+ logic breaks. No frameworks, no fixtures, no per-function suites unless asked. Trivial
84
+ one-liners need no test — YAGNI applies to tests too.
85
+
86
+ The shortest path to done is the right path.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: ralphctl-surgical-simplicity
3
- description: Execute-phase skill — write the minimum code the task needs and touch only what the task requires; surface out-of-scope findings as notes rather than fixing them inline.
3
+ description: Execute-phase scope-containment checklist — write the minimum code the task needs and touch only the files and lines the task requires; surface out-of-scope findings as notes rather than fixing them inline. Governs the footprint of a change whose approach is already decided; for choosing that implementation approach itself, defer to the ralphctl-ponytail skill when installed.
4
4
  ---
5
5
 
6
6
  # Surgical Simplicity
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: ralphctl-test-driven-development
3
- description: Execute-phase skill — write the failing test before the code that makes it pass; reproduce bugs with a test before fixing them. Use for any logic change, bug fix, or behavioural modification.
3
+ description: Execute-phase skill — write the failing test before the code that makes it pass; for bug fixes, this is the reproduction test itself. Use for any logic change, bug fix, or behavioural modification; for the full root-cause triage pipeline around an unexpected failure, see ralphctl-debugging-and-error-recovery.
4
4
  license: MIT
5
5
  ---
6
6
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "ralphctl",
3
- "version": "0.14.1",
3
+ "version": "0.15.1",
4
4
  "description": "Agent harness for long-running AI coding tasks — orchestrates Claude Code, GitHub Copilot, and OpenAI Codex across repositories",
5
5
  "homepage": "https://github.com/lukas-grigis/ralphctl",
6
6
  "type": "module",
@@ -33,7 +33,8 @@
33
33
  "ralphctl": "./dist/cli.mjs"
34
34
  },
35
35
  "files": [
36
- "dist/"
36
+ "dist/",
37
+ "THIRD-PARTY-NOTICES.md"
37
38
  ],
38
39
  "publishConfig": {
39
40
  "access": "public"
@@ -82,10 +83,10 @@
82
83
  },
83
84
  "scripts": {
84
85
  "build": "tsup && tsx scripts/build-assets.ts",
85
- "dev": "NODE_OPTIONS=--max-old-space-size=8192 tsx src/index.ts",
86
+ "dev": "NODE_ENV=production NODE_OPTIONS=--max-old-space-size=8192 tsx src/index.ts",
86
87
  "mock": "tsx scripts/seed-mock.ts",
87
88
  "dev:heap-snapshot": "mkdir -p .diagnostics && NODE_OPTIONS='--max-old-space-size=8192 --heapsnapshot-near-heap-limit=2 --diagnostic-dir=.diagnostics' tsx src/index.ts",
88
- "start": "NODE_OPTIONS=--max-old-space-size=8192 tsx src/index.ts",
89
+ "start": "NODE_ENV=production NODE_OPTIONS=--max-old-space-size=8192 tsx src/index.ts",
89
90
  "typecheck": "tsc",
90
91
  "test": "vitest run",
91
92
  "test:unit": "vitest run tests/unit",