# Coworker

> Phase-based coworker for end-to-end project setup. Guides through specification, API design, and code generation with review after each phase. Use this skill when a new project needs to be set up from scratch or when the developer wants to be guided through the complete workflow. Also for "start a new project", "coworker", "guide me through the setup", "I need a new project", or "set up a project end-to-end".

- Skill: `mgoericke/coworker-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mgoericke/coworker-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mgoericke/coworker-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: mgoericke (https://skillmd.com/u/mgoericke)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/mgoericke/coworker-2

---


# Coworker Skill

Phase-based coworker for end-to-end setup of new projects.
Orchestrates the existing skills in the right order – with review
and feedback opportunity after each phase.

> **Philosophy:** A good coworker thinks ahead, suggests the next steps,
> and leaves the developer in control. Each phase has a clear outcome.
> Nothing happens without confirmation.

---

## What This Skill Does

1. **Guides through phases** – Specification, API design, code generation
2. **Orchestrates existing skills** – Uses `spec-feature`, `openapi`, `java-scaffold`
3. **Review after each phase** – Check results, give feedback, adjust or continue
4. **Flexibly skip** – Phases can be skipped if artifacts already exist

## How to Use

```
Start the coworker for a new project
```

```
I need a new project for an order service
```

```
Coworker: set up a new project
```

---

## Instructions

> **Before every execution**:
> 1. Check `.claude/lessons-learned.md`
> 2. Check if artifacts already exist (`specs/`, `api/`, `pom.xml`)

### Overview: The Phases

```
Phase 1: Project context           → Fundamental decisions (framework, name, scope)
         ↓ Confirmation
Phase 2: Specify feature            → specs/<feature>.md
         ↓ Review & confirmation
Phase 3: Design API                 → api/<service>.yaml
         ↓ Review & confirmation
Phase 4: Generate code              → Java project with BCE, tests, Docker, infra
         ↓ Review & confirmation
Phase 5: Summary                    → What was created, next steps
```

---

### Step 0 – Inventory check

Before starting, check what already exists:

- Is there a `pom.xml`? → Project already exists, phases 1+4 may be skippable
- Are there files in `specs/`? → Phase 2 may be skippable
- Are there files in `api/`? → Phase 3 may be skippable

Communicate the result to the user:

```
Inventory check:
  Project:  ✅ exists (order-service, Spring Boot)
  Specs:    ❌ none found
  API Spec: ❌ none found

Recommendation: Start with Phase 2 (specify feature).
```

Or for an empty project:

```
Inventory check:
  Project:  ❌ no project found
  Specs:    ❌ none found
  API Spec: ❌ none found

Recommendation: Start with Phase 1 (project context).
```

---

### Phase 1 – Project Context

**Goal:** Make the fundamental decisions before getting started.

**Ask with `AskUserQuestion`:**

#### Question 1 – Project name and purpose

| # | Question | Hint |
|---|----------|------|
| 1 | **Project name** | Short name, e.g. `order-service` |
| 2 | **What should the project do?** | One sentence – used for spec and docs |

#### Question 2 – Framework

```
Which framework should be used?
```

Options:
- **Spring Boot (Recommended)** – Spring Boot 4.x with Spring AMQP, Actuator, Flyway
- **Quarkus** – Quarkus 3.31+ with SmallRye, MicroProfile Health, Flyway

#### Question 3 – Services

```
What services does the project need?
```

Options (multiSelect):
- **PostgreSQL** – Relational database
- **RabbitMQ** – Messaging / event communication
- **Keycloak** – Authentication and authorization

**Phase transition:**

```
Phase 1 completed ✅

  Project:   order-service
  Framework: Spring Boot
  Services:  PostgreSQL, RabbitMQ

  Next phase: Specify feature
  → The spec-feature conducts an interview and creates a spec file.

Continue with Phase 2?
```

Confirm via `AskUserQuestion`:
- **Continue with Phase 2** – Specify feature
- **Skip Phase 2** – Go directly to Phase 3 (design API)
- **Stop here** – Continue later

---

### Phase 2 – Specify Feature

**Goal:** Create a business specification before writing code.

**Delegation to `spec-feature`:**

Execute the `spec-feature` – with the project context from Phase 1 as prior knowledge.
The skill conducts its own interview (4 question groups) and creates `specs/<feature>.md`.

**After completion:**

```
Phase 2 completed ✅

  Created: specs/order-creation.md

  Summary:
    Feature: Create and manage orders
    Actors: Customer, Admin
    Endpoints: 5 (CRUD + status change)
    Messaging: OrderCreatedEvent to RabbitMQ

  Next phase: Design API
  → The openapi creates an OpenAPI spec based on the feature spec.

Continue with Phase 3?
```

Via `AskUserQuestion`:
- **Continue with Phase 3** – Create API spec
- **Repeat Phase 2** – Specify another feature
- **Skip Phase 3** – Go directly to Phase 4 (generate code)
- **Stop here** – Continue later

---

### Phase 3 – Design API

**Goal:** Create an OpenAPI spec that defines the API contract.

**Delegation to `openapi` (Mode A: Create new spec):**

Execute the `openapi` in "Create new spec" mode.
Pass along the information from Phase 1 (framework, services) and Phase 2 (feature spec) as context.

If endpoints and data models were already defined in Phase 2, offer them as suggestions
instead of asking again.

**After completion:**

```
Phase 3 completed ✅

  Created: api/order-service.yaml (OpenAPI 3.1.0)

  Schemas:   CreateOrderRequest, OrderResponse, ErrorResponse
  Endpoints: 5
    GET    /api/v1/orders
    POST   /api/v1/orders
    GET    /api/v1/orders/{id}
    PUT    /api/v1/orders/{id}
    DELETE /api/v1/orders/{id}

  Next phase: Generate code
  → The java-scaffold creates the project, the openapi generates code from the spec.

Continue with Phase 4?
```

Via `AskUserQuestion`:
- **Continue with Phase 4** – Generate project and code
- **Repeat Phase 3** – Adjust API spec
- **Stop here** – Continue later

---

### Phase 4 – Generate Code

**Goal:** Create the runnable project – structure, code, infra, tests.

This phase combines two skills:

**Step 4a – Project scaffolding (java-scaffold):**
- `pom.xml`, BCE package structure, Flyway, Docker, health checks
- `docker-compose.yml` with the selected services from Phase 1
- Taikai architecture tests
- `renovate.json`, `.gitignore`

**Step 4b – Code from API spec (openapi, Mode C):**
- DTOs in `entity/dto/` from the OpenAPI spec
- REST controllers/resources in `boundary/rest/`
- Service stubs in `control/`

**After completion:**

```
Phase 4 completed ✅

  Generated:
    ✅ pom.xml             – Spring Boot, PostgreSQL, Spring AMQP
    ✅ BCE package structure – boundary/, control/, entity/
    ✅ Taikai tests         – Architecture rules as unit tests
    ✅ Flyway               – db/migration/ with initial migration
    ✅ Health check          – /actuator/health
    ✅ Dockerfile            – Multi-stage build
    ✅ docker-compose.yml    – PostgreSQL, RabbitMQ
    ✅ REST endpoints        – 5 endpoints from the API spec
    ✅ DTOs                  – 3 records with validation
    ✅ Service stubs         – Business logic placeholders

  Start with:
    docker compose up -d && ./mvnw spring-boot:run

Continue with Phase 5 (summary)?
```

---

### Phase 5 – Summary and Next Steps

**Goal:** Overview of everything created and recommendations for next steps.

```
Project order-service – Setup completed ✅

Created artifacts:
  specs/order-creation.md          – Feature specification
  api/order-service.yaml           – OpenAPI 3.1.0 spec
  pom.xml                          – Spring Boot 4.x project
  src/main/java/...                – BCE structure with 5 endpoints
  src/test/java/...                – Architecture tests
  docker-compose.yml               – PostgreSQL, RabbitMQ
  Dockerfile                       – Multi-stage build

Recommended next steps:
  1. docker compose up -d           – Start infrastructure
  2. ./mvnw spring-boot:run         – Start application
  3. Implement service stubs        – Business logic in control/
  4. Adjust Flyway migrations       – Tables for entities
  5. /review                  – Run code review
  6. /doc                     – Create project documentation
```

---

## Phase Control

### Skipping Phases

The coworker automatically detects which phases can be skipped:

| If present | Phase skippable |
|------------|----------------|
| `pom.xml` | Phase 1 + 4a (scaffolding) |
| `specs/*.md` | Phase 2 (spec) |
| `api/*.yaml` | Phase 3 (API design) |
| Classes in `boundary/rest/` | Phase 4b (code from spec) |

### Repeating Phases

Each phase can be repeated – e.g. to specify another feature
or extend the API spec. The coworker asks explicitly after each phase.

### Stopping and Resuming

The coworker can be stopped after each phase. On the next invocation,
the inventory check (Step 0) detects where the developer left off.

---

## References

| File | Description |
|------|-------------|
| `.claude/lessons-learned.md` | Findings and corrections |
| `.claude/skills/spec-feature/SKILL.md` | Feature specification (Phase 2) |
| `.claude/skills/openapi/SKILL.md` | API design + code generation (Phase 3 + 4b) |
| `.claude/skills/java-scaffold/SKILL.md` | Project scaffolding (Phase 4a) |
| `.claude/skills/review/SKILL.md` | Code review (recommended next step) |
| `.claude/skills/doc/SKILL.md` | Project documentation (recommended next step) |

---

## Conventions

- **Language:** English in code, documentation language follows user preference
- **Phase transitions:** Always confirm via `AskUserQuestion`
- **Delegation:** Use existing skills, don't duplicate their logic
- **Pass context forward:** Pass information from earlier phases into later phases
- **Co-Author:** `@author Co-Author: Claude (claude-sonnet-4-6, Anthropic) – generated via coworker`

### Position in Workflow

```
[coworker]          < Orchestrates the entire workflow
        │
        ├── [spec-feature]     Phase 2
        ├── [openapi]          Phase 3 + 4b
        ├── [java-scaffold]    Phase 4a
        │
        └── recommends afterwards:
            ├── [review]       Code review
            └── [doc]          Documentation
```