Kotlin SDK API Proposal

.claude/skills/implement-change.md

@@ -0,0 +1,42 @@
+# Implement Change Skill
+
+Implement a change based on a detailed plan from the change-planner agent.
+
+## Usage
+
+```
+/implement-change <phase>.<change>
+```
+
+Examples:
+- `/implement-change 1.1.1` - Implement Phase 1.1, Change 1
+- `/implement-change 2.3.5` - Implement Phase 2.3, Change 5
+
+## Behavior
+
+1. Read the change plan from `kotlin/phases/changes/phase-X.Y-change-N.md`
+2. Verify dependencies are met
+3. Create new files as specified
+4. Modify existing files as specified
+5. Implement all unit tests
+6. Verify code compiles and tests pass
+7. Report summary of changes
+
+## Prerequisites
+
+The change plan must exist. Run `/plan-change X.Y.N` first if needed.
+
+## Output
+
+- Production code files (created/modified)
+- Test files
+- Summary of what was done
+- Any deviations from plan with justification
+
+## Quality Gates
+
+The agent will verify:
+- Code compiles without warnings
+- All new tests pass
+- Existing tests still pass
+- Acceptance criteria from plan are met

.claude/skills/implement.md

@@ -0,0 +1,62 @@
+# Implement Skill
+
+Fully implement a change from a phase plan, orchestrating planning and implementation.
+
+## Usage
+
+```
+/implement <phase>.<change>
+```
+
+Examples:
+- `/implement 1.1.1` - Implement Phase 1.1, Change 1
+- `/implement 2.3.5` - Implement Phase 2.3, Change 5
+
+## Behavior
+
+This skill orchestrates the full implementation workflow:
+
+1. **Validate** - Check dependencies are met
+2. **Plan** - Generate detailed implementation plan (change-planner)
+3. **Review** - Verify plan is feasible and complete
+4. **Implement** - Write code and tests (change-implementer)
+5. **Verify** - Ensure compilation and tests pass
+6. **Retry** - Replan or fix if issues encountered
+
+## Automatic Recovery
+
+The orchestrator handles failures automatically:
+
+| Issue | Action |
+|-------|--------|
+| Plan incomplete | Replan with feedback (up to 2x) |
+| Compilation error | Fix and retry (up to 3x) |
+| Test failure | Diagnose and fix or replan |
+| Blocking issue | Stop and report |
+
+## Output
+
+- Completed implementation with passing tests
+- Change plan document at `kotlin/phases/changes/phase-X.Y-change-N.md`
+- Summary of files created/modified
+- Verification report
+
+## Prerequisites
+
+- Phase plan must exist at `kotlin/phases/phase-X.Y-detailed.md`
+- Prior changes in the phase should be complete
+
+## Workflow Visualization
+
+```
+/implement 1.1.3
+     │
+     ▼
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│ Plan Change │ ──▶ │ Implement   │ ──▶ │ Verify      │
+│             │     │             │     │             │
+└─────────────┘     └─────────────┘     └─────────────┘
+     ▲                    │                    │
+     │                    │                    │
+     └────── replan ──────┴─────── fix ────────┘
+```

.claude/skills/plan-change.md

@@ -0,0 +1,40 @@
+# Plan Change Skill
+
+Create a detailed implementation plan for a single change from a phase plan.
+
+## Usage
+
+```
+/plan-change <phase>.<change>
+```
+
+Examples:
+- `/plan-change 1.1.1` - Plan Phase 1.1, Change 1
+- `/plan-change 2.3.5` - Plan Phase 2.3, Change 5
+
+## Behavior
+
+1. Read the phase plan from `kotlin/phases/phase-X.Y-detailed.md`
+2. Read SDK proposal docs and relevant source code
+3. Validate the change is feasible
+4. Design the simplest, most readable implementation
+5. Specify complete test coverage
+6. Write output to `kotlin/phases/changes/phase-X.Y-change-N.md`
+
+## Output Contents
+
+The implementation plan includes:
+
+- **Feasibility validation** - Confirm change is possible
+- **File changes** - Exact files to create/modify with code skeletons
+- **Test specifications** - Complete unit test definitions
+- **Acceptance criteria** - Checklist for completion
+- **Implementation notes** - Gotchas, patterns, references
+
+## Requirements
+
+The output must be **self-contained**. A developer should be able to implement the change using only:
+- This document
+- The SDK source code
+
+No need to consult proposal documents or other planning materials.

.claude/skills/plan-phase.md

@@ -0,0 +1,63 @@
+# Plan Phase Skill
+
+Break down a phase of the Kotlin SDK implementation into detailed, self-contained changes.
+
+## Usage
+
+```
+/plan-phase <phase>
+```
+
+Examples:
+- `/plan-phase 1.1` - Plan "Java SDK Refactoring"
+- `/plan-phase 2.1` - Plan "Typed Activity Stubs"
+
+## Behavior
+
+1. Read the implementation plan from `kotlin/implementation-plan.md`
+2. Read context from `kotlin/sdk-api.md` and `kotlin/sdk-implementation.md`
+3. For the specified phase, produce a detailed breakdown where each item:
+   - Is a self-contained, submittable PR
+   - Includes full test coverage
+   - Has clear dependencies on prior items
+   - Can be reviewed and merged independently
+
+## Output Format
+
+Write the detailed plan to `kotlin/phases/phase-X.Y-detailed.md` with this structure:
+
+```markdown
+# Phase X.Y: [Name] - Detailed Plan
+
+## Overview
+Brief description of what this phase accomplishes.
+
+## Prerequisites
+Any required setup or prior phases.
+
+## Changes
+
+### Change 1: [Title]
+**Summary:** One-line description
+
+**Scope:**
+- Files to add/modify
+- Public API changes (if any)
+
+**Tests:**
+- Unit tests required
+- Integration tests required
+
+**Dependencies:** None | Change N
+
+---
+(repeat for each change)
+```
+
+## Guidelines
+
+- **Atomic**: Each change does ONE thing
+- **Testable**: Every change includes tests
+- **Ordered**: Dependencies flow forward only
+- **Compilable**: Code compiles after each change
+- **No Design**: Don't go into implementation details - just scope and structure

CLAUDE.md

@@ -0,0 +1,62 @@
+# Claude Instructions for Kotlin SDK Proposals
+
+## Repository Purpose
+
+This repository contains API proposals and design documentation for the Temporal Kotlin SDK.
+
+## Adding Open Questions
+
+When proposing new API features that need discussion before implementation:
+
+1. **Add to the central document**: Add a new section to `kotlin/open-questions.md` with:
+   - Clear problem statement
+   - Proposed solution with code examples
+   - Benefits and trade-offs
+   - Status marked as "Decision needed"
+
+2. **Add inline sections**: In the relevant proposal document (e.g., `activities/definition.md`), add an "Open Questions (Decision Needed)" section at the end with:
+   - Brief summary of the proposal
+   - Link to full discussion: `[Full discussion](../open-questions.md#section-anchor)`
+
+3. **Update the README**: Ensure `kotlin/open-questions.md` is linked in the Reference section of `kotlin/README.md`
+
+### Example Format
+
+In `open-questions.md`:
+```markdown
+## Feature Name
+
+**Status:** Decision needed
+
+### Problem Statement
+[Describe what problem this solves]
+
+### Proposal
+[Code examples showing proposed API]
+
+### Benefits
+- [List benefits]
+
+### Trade-offs
+- [List trade-offs]
+
+### Related Sections
+- [Link to relevant proposal docs]
+```
+
+In the relevant proposal doc:
+```markdown
+## Open Questions (Decision Needed)
+
+### Feature Name
+
+**Status:** Decision needed | [Full discussion](../open-questions.md#feature-name)
+
+[Brief summary and code example]
+```
+
+## Commit Style
+
+Follow concise commit message style:
+- First line: Brief summary of change
+- Body: Additional context if needed