Minimum Viable Change: A hello command that outputs "hello world" following Shipwright conventions.

Implicit Requirements (from codebase analysis):

• Must follow bash 3.2 compatibility constraints
• Must use Shipwright's command structure (scripts/sw-hello.sh)
• Must include proper help text and error handling
• Must be registered in CLI router
• Must include automated tests
• Must follow VERSION management pattern

Acceptance Criteria:

1. ✓ shipwright hello outputs "hello world"
2. ✓ shipwright hello --help displays usage information
3. ✓ Command integrates with existing CLI router
4. ✓ Test suite passes: npm test includes sw-hello-test.sh
5. ✓ No existing commands/tests broken
6. ✓ Bash 3.2 compatible with no external dependencies beyond jq, curl

Files: scripts/sw-hello.sh, scripts/sw-hello-test.sh, update scripts/sw, update package.json

Pros:

• Consistent with all 100+ existing Shipwright commands
• Reuses help system, logging, error handling
• Clean separation of concerns
• Testable in isolation
• Follows established patterns exactly

Trade-offs:

• Slightly more code than minimal solution
• Minimal complexity increase (4 small files)
• Blast radius: Only touches CLI router registration

Files: Only update scripts/sw

Pros:

• Fewer files
• Direct execution

Trade-offs:

• Breaks Shipwright conventions (inconsistent with 100+ existing commands)
• No automatic help system
• Harder to test
• Makes router harder to maintain
• Rejected: Creates technical debt

Task 1 (Independent): Examine CLI router pattern → read scripts/sw Task 2 (Depends on 1): Examine command script pattern → read scripts/sw-status.sh or similar Task 3 (Depends on 2): Create scripts/sw-hello.sh Task 4 (Depends on 3): Create scripts/sw-hello-test.sh Task 5 (Depends on 1): Update scripts/sw router with hello command registration Task 6 (Depends on 4, 5): Update package.json to register test Task 7 (Depends on 6): Run tests locally to verify Task 8 (Depends on 7): Verify no existing tests broken

Step 1: Read CLI router to understand dispatch pattern

• File: scripts/sw
• Look for: How commands are registered, help handling, dispatch mechanism

Step 2: Read existing command to understand structure

• File: scripts/sw-ps.sh (simple example) or scripts/sw-status.sh
• Look for: VERSION variable, set -euo pipefail, help text, output functions, event logging

Step 3: Create scripts/sw-hello.sh

#!/usr/bin/env bash
VERSION="2.0.0" # Match package.json version
set -euo pipefail
# Source help text and output functions if available
# (Pattern from other commands)
main() {
 local arg="${1:-}"
 
 case "$arg" in
 --help|-h)
 show_help
 exit 0
 ;;
 *)
 echo "hello world"
 exit 0
 ;;
 esac
}
show_help() {
 cat <<EOF
Usage: shipwright hello [OPTIONS]

Print 'hello world' to standard output.

OPTIONS:
 -h, --help Show this help message

EXAMPLES:
 shipwright hello
 sw hello

EOF
}
main "$@"

Step 4: Create scripts/sw-hello-test.sh

#!/usr/bin/env bash
# Test suite for sw-hello command
test_hello_basic() {
 output=$("$scripts_dir/sw-hello.sh")
 if [[ "$output" == "hello world" ]]; then
 PASS "$test: basic output"
 else
 FAIL "$test: expected 'hello world', got '$output'"
 fi
}
test_hello_help() {
 output=$("$scripts_dir/sw-hello.sh" --help)
 if [[ "$output" =~ "Usage: shipwright hello" ]]; then
 PASS "$test: help text"
 else
 FAIL "$test: help text not found"
 fi
}
# Run tests
test_hello_basic
test_hello_help

Step 5: Update scripts/sw router

• Locate the command dispatch section
• Add hello command registration following existing pattern (e.g., where ps, status are defined)
• Example pattern:

hello)
 exec "$script_dir/sw-hello.sh" "$@"
 ;;

Step 6: Update package.json

• Add test entry to scripts section:

"test:sw-hello": "bash scripts/sw-hello-test.sh",

• Add to main test suite (if applicable)

Step 7: Run new test suite

npm test sw-hello

Verify: PASS count > 0, FAIL count = 0

Step 8: Run full test suite

npm test

Verify: No regressions in existing tests

• Read CLI router (scripts/sw) to understand command dispatch pattern
• Read reference command (scripts/sw-ps.sh or scripts/sw-status.sh) to understand structure
• Create scripts/sw-hello.sh with proper bash structure, VERSION, help text
• Create scripts/sw-hello-test.sh with basic and help text tests
• Update scripts/sw to register hello command in router
• Update package.json to register test in npm test suite
• Run hello test locally - verify basic and help text work
• Run full test suite - verify no existing tests broken
• Manual integration test: shipwright hello outputs "hello world"
• Manual integration test: shipwright hello --help shows help text

✓ Functionality

• shipwright hello outputs exactly "hello world" to stdout
• shipwright hello --help displays usage text
• Exit code is 0 on success

✓ Code Quality

• Follows Bash 3.2 compatibility (no associative arrays, no lowercase expansion)
• Uses set -euo pipefail at top of script
• VERSION variable matches package.json
• Proper error handling with meaningful messages

✓ Integration

• Command registered in scripts/sw router
• No changes to existing commands
• Help text follows Shipwright conventions

✓ Testing

• Test file created (scripts/sw-hello-test.sh)
• At least 2 tests: basic output, help text
• Registered in package.json
• npm test includes new test suite
• All tests pass locally

✓ Verification

• No existing tests broken
• Manual CLI test: ./scripts/sw hello works
• Manual CLI test via CLI: shipwright hello works (if CLI registered)

Unit Tests (scripts/sw-hello-test.sh):

1. Test basic output: sw-hello.sh outputs "hello world"
2. Test help flag: sw-hello.sh --help contains usage text
3. Test exit codes: Success returns 0

Integration Tests:

1. Manual: shipwright hello from root directory
2. Manual: ./scripts/sw hello from root directory
3. Verify: Works with --help, -h flags

Regression Tests:

• Run full npm test to ensure existing commands not affected
• Run existing test suites for router-related functionality

Consistency: Matches all 100+ existing Shipwright commands—low cognitive load for future maintainers.

Low Blast Radius: Only touches CLI router registration + new files, no changes to shared code.

Maintainability: Self-contained command with dedicated test suite, follows established patterns exactly.

Scalability: Foundation for future hello-world-like commands using identical structure.