porada/domfiles / .agents/skills/shell-integration
shell-integration
VerifiedUse this skill whenever the resolved task scope includes shell code—including `domlib`, Fish configuration, `home/.local/bin` scripts, and `.hooks`—or adds or reconsiders a command entrypoint in this repository, including whether a Git helper should be a plain alias or a `home/.local/bin/git-*` script. Do not use it merely because the task runs terminal commands.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.6 KB |
| references/command-form-and-location.md | markdown | 1.9 KB |
| references/domlib-integration.md | markdown | 3.2 KB |
| references/shared-helper-design.md | markdown | 5.3 KB |
| references/validate-shell-changes.md | markdown | 2.4 KB |
references/shared-helper-design.md
View on GitHub# Shared Helper Design
## Keep Responsibilities Reusable
- Keep entrypoints focused on command-specific bounds and output behavior.
- Define shared defaults in the helper that owns their behavior. Callers accepting a default must omit the corresponding argument instead of repeating its value.
- When a loop computes a reusable value, prefer a named helper that returns the result rather than placing the loop at a call site with a trailing here document redirection. Retain loop redirection when POSIX scope or failure handling requires it and extraction would not improve clarity.
## Align Cross-Shell Helper Contracts
- The POSIX helper named exactly `__` uses the established Fish counterpart `__domfiles_print_and_run`. The helper named exactly `__domfiles` has no automatic Fish counterpart name. For any other `domlib` helper, replace the leading `__` with `__domfiles_`, leaving names that already begin with `__domfiles_` unchanged.
- Treat paired POSIX and Fish helpers as peer implementations of a shared contract. Neither implementation governs the other.
- Keep their accepted inputs, `stdout` and `stderr` behavior, return statuses, side effects, defaults, failure conditions, validation timing, and adjacent contract documentation semantically aligned wherever both shells can support the same behavior.
- Use shell-native implementations without weakening the shared contract. A preferred idiom does not take precedence when it requires lossy normalization, including command substitution that changes significant whitespace or record boundaries. Allow a shell-specific contract difference when native behavior has no equivalent in the other shell or a settled project decision intentionally selects different behavior. Document each accepted difference and its rationale in [cross-shell helper differences](../../../PROJECT.md#cross-shell-helper-differences), and keep the remainder of the pair’s contract aligned.
- When either helper changes, inspect its counterpart. During an authorized change, update the implementations, contract documentation, and documented differences as needed to keep the pair accurate. During a review, audit, or diagnosis, report required alignment without editing either helper or its documentation.
## Port Helpers Between Shells
1. Inventory the source helper’s direct and transitive behavior before implementing its counterpart, including wrapper dispatch, command resolution, environment variables, failure conditions, suppression, and call sites.
2. Establish a bounded comparison across the shared contract surface defined in [Align Cross-Shell Helper Contracts](#align-cross-shell-helper-contracts).
3. Resolve each mismatch as aligned behavior or an accepted shell-specific difference before implementation. Do not infer that a transitive behavior should be retained or dropped.
4. When command form changes, follow [Command Form and Location](command-form-and-location.md), then migrate call sites and contract documentation with the implementation.
5. Exercise both counterparts with the same bounded case matrix and compare their observable contracts before considering the port complete. When applicable, cover input shape and content boundaries such as argument cardinality, empty values, letter case variants, leading and trailing whitespace, and embedded and trailing newlines, plus interaction and outcome boundaries such as EOF, retries, and failure propagation.
## Document Helper Contracts
- Begin standard output contracts with `Prints …`, predicates with `Returns success …`, and side effect contracts with a direct action verb.
- Describe the semantic contract rather than narrating implementation. Include non-obvious inputs, outputs, or fallback behavior only when their omission would mislead. Repeat a source-owned value only when the contract would not make sense without it. See [`domlib` Helper Contracts](../../../PROJECT.md#domlib-helper-contracts) for intentional comment choices and their rationale.
- Give every `domlib` function one adjacent natural language contract comment. Do not use `@param` or `@returns` tags.
- Let command-shaped wrappers rely on ordinary command semantics implied by their names rather than restating them.
- Name `$1`, `$@`, and other positional parameters only when their positions clarify the contract.
- Treat domfiles as an unformatted plural noun, parallel to “dotfiles,” when it denotes the repository or managed configuration. Code-format `domfiles` only when it denotes the CLI command.
- Wrap comment prose at 80 columns while preserving ordinary sentence flow across continuation lines. Use internal punctuation between sentences.
## Review Difficult Contracts
- Treat difficulty explaining a helper in a concise contract comment as a signal to review its design. Flag comments that need unrelated clauses, counterintuitive parameter positions, or implementation walkthroughs rather than broadening the comment.
- Review whether option-bearing helpers place options before operands. Across related helper families, review subject and object positions for consistency.
- Record refactor signals separately from rename signals. When both are within the resolved scope, resolve refactors before renaming. Do not force a refactor for an intentional overload documented in [`domlib` Helper Contracts](../../../PROJECT.md#domlib-helper-contracts).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |