Effect

This codebase uses Effect for typed, composable TypeScript services, schemas, and workflows.

Source Of Truth

Use the current Effect v4 / effect-smol source, not memory or older Effect v2/v3 examples.

1. If .opencode/references/effect-smol is missing, clone https://github.com/Effect-TS/effect-smol there. Do this in the project, not in the skill folder.
2. Search .opencode/references/effect-smol for exact APIs, examples, tests, and naming patterns before answering or implementing Effect-specific code.
3. Also inspect existing repo code for local house style before introducing new patterns.
4. Prefer answers and implementations backed by specific source files or nearby repo examples.

Guidelines

• Prefer current Effect v4 APIs and project-local patterns over old blog posts, examples, or package-memory guesses.
• Use Effect.gen(function* () { ... }) for multi-step workflows.
• Use Effect.fn("Name") or Effect.fnUntraced(...) for named effects when adding reusable service methods or important workflows.
• Prefer Effect Schema for API and domain data shapes. Use branded schemas for IDs and Schema.TaggedErrorClass for typed domain errors when modeling new error surfaces.
• Keep HTTP handlers thin: decode input, read request context, call services, and map transport errors. Put business rules in services.
• In Effect service code, prefer Effect-aware platform abstractions and dependencies over ad hoc promises where the surrounding code already does so.
• Keep layer composition explicit. Avoid broad hidden provisioning that makes missing dependencies hard to see.
• In tests, prefer the repo's existing Effect test helpers and live tests for filesystem, git, child process, locks, or timing behavior.
• Do not introduce any, non-null assertions, unchecked casts, or older Effect APIs just to satisfy types.
• Do not answer from memory. Verify against .opencode/references/effect-smol or nearby code first.

Testing Patterns

• Use testEffect(...) from packages/opencode/test/lib/effect.ts for tests that exercise Effect services, layers, runtime context, scoped resources, or platform integrations.
• Use it.live(...) for filesystem, git repositories, HTTP servers, sockets, child processes, locks, real time, and other live platform behavior.
• Run tests from package directories such as packages/opencode; never run package tests from the repo root.
• Prefer explicit test layers over ad hoc managed runtimes. Keep dependency provisioning visible in the test file.
• Use scoped fixtures and finalizers for resources that must be cleaned up, including temporary directories, flags, databases, fibers, servers, and global state.

What I do

• Commit Architect: Create atomic commits, detect commit styles, order by dependencies
• Rebase Surgeon: Rewrite history, resolve conflicts, squash/fixup commits
• History Archaeologist: Find when/where changes were introduced using pickaxe, blame, bisect

Mode Detection

Analyze the user's request to determine operation mode:

COMMIT MODE

Core Principle: Multiple Commits by Default

ONE COMMIT = AUTOMATIC FAILURE

Split Criteria

Split commits when:

• Different directories/modules → SPLIT
• Different component types (model/service/view) → SPLIT
• Can be reverted independently → SPLIT
• Different concerns (UI/logic/config/test) → SPLIT
• New file vs modification → SPLIT

Style Detection (MANDATORY)

Before making commits, analyze git log -30 to detect:

Language: Count Korean vs English commits, use majority.

Style Types:

Detection: If 50%+ match semantic pattern (^(feat|fix|chore|refactor|docs|test|ci|style|perf|build)(\(.+\))?:), use SEMANTIC. Otherwise use majority style.

MANDATORY OUTPUT before committing:

STYLE DETECTION RESULT
======================
Analyzed: 30 commits from git log

Language: [KOREAN | ENGLISH]
Style: [SEMANTIC | PLAIN | SENTENCE | SHORT]

Reference examples from repo:
  1. "actual commit message from log"
  2. "actual commit message from log"
  3. "actual commit message from log"

All commits will follow: [LANGUAGE] + [STYLE]

Implementation + Test Pairing (MANDATORY)

Test files MUST be in the same commit as implementation:

Dependency Ordering

Commit in this order:

• Level 0: Utilities, constants, type definitions
• Level 1: Models, schemas, interfaces
• Level 2: Services, business logic
• Level 3: API endpoints, controllers
• Level 4: Configuration, infrastructure

Commit Plan (MANDATORY OUTPUT)

Before executing commits, output:

COMMIT PLAN
===========
Files changed: N
Minimum commits required: M
Planned commits: K
Status: K >= M (PASS) | K < M (FAIL - must split more)

COMMIT 1: [message in detected style]
  - path/to/file1
  Justification: [why these files MUST be together]

COMMIT 2: [message in detected style]
  - path/to/file2
  Justification: [why these files MUST be together]

Anti-Patterns (AUTOMATIC FAILURE)

• NEVER make one giant commit (3+ files → 2+ commits)
• NEVER default to semantic commits — detect from git log first
• NEVER separate test from implementation — same commit always
• NEVER group by file type — group by feature/module
• NEVER rewrite pushed history without explicit permission
• NEVER leave working directory dirty — complete all changes
• NEVER skip JUSTIFICATION — explain why files are grouped
• NEVER use vague grouping reasons — "related to X" is NOT valid

REBASE MODE

Rebase Strategies

Safety Rules

• NEVER rebase main/master
• Always stash dirty working directory first
• Use --force-with-lease instead of --force
• Check if commits are local-only before aggressive rewrite

Autosquash Workflow

MERGE_BASE=$(git merge-base HEAD main 2>/dev/null || git merge-base HEAD master)
GIT_SEQUENCE_EDITOR=: git rebase -i --autosquash $MERGE_BASE

Conflict Resolution

1. Identify conflicting files: git status | grep "both modified"
2. For each conflict: Read the file, understand both versions (HEAD vs incoming)
3. Resolve by editing file, remove conflict markers (<<<<, ====, >>>>)
4. Stage resolved files: git add <resolved-file>
5. Continue rebase: git rebase --continue
6. If stuck or confused: git rebase --abort (safe rollback)

Recovery Procedures

HISTORY SEARCH MODE

Search Types

-S vs -G Difference

• -S "foo": Finds commits where COUNT of "foo" changed → Use for "when was X added/removed"
• -G "foo": Finds commits where DIFF contains "foo" → Use for "what commits touched lines containing X"

Git Bisect Workflow

git bisect start
git bisect bad              # Mark current (has bug)
git bisect good v1.0.0      # Mark known good
# Git checks middle commit. Test it, then:
git bisect good   # if OK
git bisect bad    # if bug exists
# Repeat until git finds the culprit
git bisect reset  # Return to original state

Present Results

SEARCH QUERY: "<what user asked>"
SEARCH TYPE: <PICKAXE | REGEX | BLAME | BISECT | FILE_LOG>
COMMAND USED: git log -S "..." ...

RESULTS:
  Commit       Date           Message
  ---------    ----------     --------------------------------
  abc1234      2024-06-15     feat: add discount calculation

MOST RELEVANT COMMIT: abc1234
DETAILS:
  Author: John Doe <john@example.com>
  Date: 2024-06-15
  Files changed: 3

Universal Rules

Supported Workflows

• Git Flow (feature → develop → main)
• GitHub Flow (feature → main)
• Trunk-based Development
• Forking Workflow
• Any custom workflow

Reminders

• ALWAYS detect commit style from repository history before making commits
• ALWAYS create multiple atomic commits instead of one giant commit
• ALWAYS pair test files with their implementation in the same commit
• ALWAYS justify file groupings with specific, concrete reasons
• ALWAYS check branch state before aggressive history rewrites
• NEVER assume semantic commits — detect actual style first
• NEVER rebase shared/pushed branches without coordination

What I do

• Manage Git Flow branching strategy (feature → develop → main)
• Enforce mandatory user approval before any merge
• Run verification checks (LSP diagnostics, build, tests) before merge
• Support multiple project types: software, firmware, documentation, web
• Provide standardized merge workflows with clear communication templates

Core Rules

NEVER Auto-Merge (CRITICAL)

NEVER merge to develop/main without explicit user permission.

Before any merge operation, ALWAYS ask:

"Feature complete. Do you approve merging to develop/main? (yes/no/test first)"

Feature Branch Only

• Create feature branches from develop/main
• Never commit directly to primary branches
• Branch naming: feature/description, fix/description, hotfix/description

Verification Before Merge

Before requesting merge approval, verify:

1. Feature implementation complete
2. All changes committed to feature branch
3. Code self-reviewed
4. LSP diagnostics checked (no new errors for code projects)
5. Build verification passed (if applicable)
6. Documentation updated if needed
7. Tests added/updated for new functionality

User Approval Workflow

1. Complete feature implementation in feature branch
2. Run verification checks (LSP diagnostics, build, tests)
3. Notify user with status and options:
   • Test it - Run verification checks / Request manual test
   • Approve merge - Merge to target branch (requires verification to pass)
   • Request changes - Make adjustments
   • Do not merge - Keep in feature branch
4. WAIT for user response
5. If "Test it" → Perform verification, if tests fail → Fix issues, go back to step 3
6. If "Approve merge" → Merge to target branch
7. If "Do not merge" → Stop, await further instruction

Project Type Adaptation

Software Projects

• Verification: LSP diagnostics, Build check, Unit tests
• Documentation: Code comments, README updates, API docs

Firmware Projects

• Verification: LSP diagnostics, Compilation check, Hardware test
• Documentation: Code comments, Hardware specs, Pin mappings

Documentation Projects

• Verification: Markdown linting, Link checking, Formatting
• Documentation: Self-verification, Cross-references

Web Projects

• Verification: LSP diagnostics, Build check, E2E tests
• Documentation: README, API docs, Deployment guides

Merge Command Template

git checkout {target_branch} && git merge --no-ff {branch_name} -m "Merge {branch_name}: {description}"

Target Branches

• develop - For ongoing development work (Git Flow)
• main - For production-ready changes (GitHub Flow / trunk-based)
• master - Legacy main branch name

Communication Templates

Feature Ready

Feature [{feature_name}] is complete on branch [{branch_name}].

Summary:
- {key_changes}

Verification Status:
- [ ] Code quality: {status}
- [ ] Build/Tests: {status}
- [ ] Documentation: {status}

Next steps:
1. Review code: git diff {base_branch}...{branch_name}
2. Choose action:
   • 'Test it' - I'll run verification checks / Request manual test
   • 'Approve merge' - Merge to {base_branch} (requires verification to pass)
   • 'Request changes' - I'll make adjustments
   • 'Do not merge' - Keep in feature branch

Awaiting your instruction.

Test Results

Verification Results for [{branch_name}]:

Code Quality: {PASS/FAIL}
Build Status: {PASS/FAIL/N/A}
Tests: {PASS/FAIL/N/A}

Manual Test (if performed):
{user_feedback}

Ready for merge approval?

Merge Complete

Successfully merged [{branch_name}] to {target_branch}.

Commit: {commit_hash}
Message: {commit_message}

Summary:
{changes_summary}

Error Handling

Accidental Merge Prevention

• Double-check user intent before executing merge command
• If merged without permission: Immediately notify user, offer to revert

Test Failure

• Stop merge process, fix issues, re-request approval
• Communication: "Verification failed: {failure_details}. Issues fixed. Please re-verify."

Build Failure

• Fix build errors before requesting merge
• Cannot request merge with build errors

Reminders

• When user asks to implement a feature: Create feature branch, do NOT merge automatically
• When feature is complete: Ask user for approval, do NOT assume approval
• When user says "test it": Run verification checks first, then request manual test if needed
• When user says "do not merge": Respect immediately, do not argue
• When user says "merge approved": Verify all checks passed before executing merge
• After merge: Notify user with commit details and summary
• Always check for the appropriate target branch (develop vs main) based on project structure