Feature Build

Feature Build Workflow

One skill for the full lifecycle of a feature: create it, restructure it, expose it via API, or sunset it — all following DDD layers with rule checks per phase and a review loop.

ARGUMENTS: — mode ∈ new | refactor | api | deprecate. e.g. new wallet savings, refactor marketing notification, api catalog, deprecate payments legacy-checkout.

Pick your mode

| If you are… | Mode | Jump to | |-------------|------|---------| | Building a brand-new feature across DDD layers | NEW | [Mode NEW](#mode-new) | | Restructuring existing code into DDD / fixing drift | REFACTOR | [Mode REFACTOR](#mode-refactor) | | Adding an endpoint or integrating a third-party API | API | [Mode API](#mode-api) | | Safely sunsetting a feature / endpoint / module | DEPRECATE | [Mode DEPRECATE](#mode-deprecate) |

• ❌ Quick bug fix → use /fix-bug
• ❌ Don't know the right approach yet → /research-explore (WEB or SPIKE) first
• ❌ Multi-step task you want to run as a tracked checklist loop → /feature-track

Read Architecture First (all modes)

Detect stack via ~/.claude/architecture/_shared/stack-detection.md. Load ddd-architecture.md + the stack doc — extract directory layout, layer rules, forbidden imports, check scripts before any code. Severity definitions live in ~/.claude/architecture/_shared/severity-levels.md.

---

---

Mode NEW

Build a new feature following DDD layers with rule checks per phase and a final review loop until score ≥ B.

When to use

• ✅ Feature spans multiple DDD layers (domain + app + infra)
• ✅ The approach is well-understood (no major research / prototype needed)
• ✅ You want automated architecture review at the end
• ❌ Restructuring existing code → use Mode REFACTOR
• ❌ Adding only an endpoint → use Mode API

Workflow

1 PLAN → 2 DOMAIN → 3 INFRA → 4 APP → 5 WIRE → 6 TESTS → REVIEW LOOP

Phase 1: PLAN

1.1 Read a reference module

Pick the smallest existing module in the project as a template. Read ALL its files end-to-end:

• entities, value objects, events, ports, usecases
• service, handler, DTOs, listeners
• infrastructure store/API
• registration in router/provider/registry

1.2 Plan the feature

Present to the user:

## Feature Plan: {domain}/{feature}

### Entities + fields
- `{Entity}` — {field: type, with constraint}
- ...

### Value Objects
- `{Status}` — states: {list}, transitions: {list}
- ...

### Endpoints / screens / commands
| Method | Path | Purpose |
|--------|------|---------|
| POST | /api/v1/wallets/:id/savings | Open savings account |

### Domain events
| Event | Triggered when | Listeners |
|-------|----------------|-----------|
| `SavingsAccountOpened` | After Account.open() succeeds | NotificationListener |

### Business rules
- Cannot open savings if main balance /dev/null && echo PASS || echo NEED SETUP
ls {eventbus_path}/ 2>/dev/null && echo PASS || echo NEED SETUP

If FAIL → set up foundation before continuing.

Gate

• [ ] Shared domain types exist
• [ ] Event infrastructure exists (if domain raises events)

Phase 1: ANALYZE

Goal: read ALL source files in the old module before touching anything.

Read

• All files in the module dir
• Related models / types / enums
• Routes / providers / screens for this module
• Existing tests (CRITICAL — used in Phase 5)

Output to user

## Refactor Plan: {module} → {domain}

### Current state
- Entities/models: {list with fields}
- Usecases (functions): {list with 1-line logic summary}
- DTOs: {list}
- Cross-module calls: {list}
- Side-effects: {notifications / SSE / analytics / async jobs}
- External deps: {DB, cache, messaging}
- Endpoints/screens: {list with method + path}
- Test files: {list with case counts}

### Proposed DDD structure
- Value objects to extract: {list}
- Entities: {list}
- Events: {list}
- Ports: {list}
- Usecases: {list}
- Listeners: {list}

Gate

• [ ] All module files read
• [ ] Plan presented to user
• [ ] User CONFIRMED before continuing

Phase 2: DOMAIN LAYER

Create domain/{domain}/ (or add to existing). Order: VO → entities → events → ports → usecases.

• Value Objects (valueobjects/) — extract typed values (status strings, rates, amounts). Immutable + behavior methods. Stdlib imports only.
• Entities (entities/) — convert old models. Constructor + behavior methods + event collection. Add mappers to/from persistence. No framework imports.
• Events (events/) — one file per event. Extract from existing direct side-effect calls.
• Ports (ports/) — one file per interface. Store ports (persistence), adapter ports (external services). Platform-agnostic naming (URLParser not ShopeeURLParser). No infra imports.
• UseCases (usecases/) — extract business logic from old controllers/handlers/services. Import from ports/. Split by concern, ≤200 lines/file. No infra imports.

Gate

{build_domain} && echo PASS || echo FAIL
{grep_forbidden in domain/} && echo FAIL || echo PASS
{cross_domain_check} && echo FAIL || echo PASS

Phase 3: INFRASTRUCTURE LAYER

• Implement port interfaces from domain/{domain}/ports/
• Mapper functions: domain entity ↔ persistence model
• Compile-time interface check (where supported)
• NO business logic
• Keep existing persistence models in place

Gate

• [ ] Infra build passes
• [ ] All port interfaces implemented

Phase 4: APPLICATION LAYER

4.1 Listeners (extract side-effects)

CRITICAL: Side-effects (notifications, SSE, analytics, jobs) MUST NOT be called directly in usecases or infra. Flow must be: entity collects event → usecase dispatches → listener handles.

• One file per event listener
• Register in event bus

4.2 Service

• Thin wrapper, delegates to usecases. No business logic.

4.3 Handler / Controller / Screen

• Registration / wiring function
• Thin: parse → service → return
• DTOs in separate file
• All endpoints must match the old paths + methods

Gate

• [ ] App build passes
• [ ] Every old endpoint has a new handler at the same path

Phase 5: TESTS

CRITICAL: read old tests first, copy every scenario. Do not lose coverage.

1. Read all old test files
2. List all test cases + business scenarios
3. Write domain tests covering all of them

What to test

• Entities — behavior methods, edge cases, business rules (pure, no mocks)
• UseCases — happy + error paths, validation, event collection (mock ports)
• Value Objects — transitions, calculations, edge cases (pure)

Gate

• [ ] Old test count ≤ new test count
• [ ] Every old scenario covered
• [ ] {test_command} passes

Phase 6: INTEGRATION & CLEANUP

6.1 Wire up the new module

• Add registration calls in router / provider / registry
• Remove old module registrations
• Endpoints/screens match old paths

6.2 Remove old module

• Delete old directory only after build + tests pass
• Do NOT delete shared models/types other modules still use

Gate

{full_build} && echo PASS || echo FAIL
test -d {old_module_path} && echo "FAIL: still there" || echo PASS
grep -r "{old_import_path}" --include="*.{ext}" . && echo "FAIL: stale imports" || echo PASS

Review Loop (REFACTOR)

After Phase 6, call /review-code architect {stack} {domain}. Loop until score ≥ B.

LOOP:
  1. /review-code architect {stack} {domain}
  2. IF violations severity ≥ MEDIUM:
       fix all → full build → all tests → GOTO 1
  3. IF score ≥ B → BREAK

Final Report (REFACTOR)

## Refactor Complete: {module} → {domain}

### Changes
- Files created: {N}, modified: {N}, deleted: {N}

### Endpoints preserved
| Old path | New handler | Status |
|----------|-------------|--------|

### Domain events introduced
| Event | Listener(s) |
|-------|-------------|

### Tests
- Files: {N}, cases: {M} — all old scenarios migrated: YES

### Review score: {A/B}
- Build / Lint / Domain purity / Old module removed / No stale imports / Tests: all PASS

---

---

Mode API

End-to-end workflow for designing, implementing, testing, and documenting APIs — both internal endpoints and third-party integrations.

When to use

• ✅ Adding a new REST / GraphQL endpoint to your service
• ✅ Integrating a third-party API (Stripe, OpenAI, etc.) into the system
• ✅ Replacing or upgrading an existing API integration
• ❌ Just need a one-off HTTP call in a script → use Bash directly
• ❌ Need to research which API to use → use /research-explore (WEB) first
• ❌ Building a whole new domain → use Mode NEW (which covers the API surface as Phase 4)

Workflow

DESIGN → IMPLEMENT → TEST → DOCUMENT → REVIEW LOOP

Before any phase, also read existing API conventions in the project (look at 1–2 existing endpoints as reference).

Phase 1: DESIGN

Goal: lock the API contract before writing any code.

Actions

1. Identify API type: REST / GraphQL / gRPC / third-party client
2. Define contract:

• Endpoints / operations (method + path)
• Request / response schema (use real types from domain entities)
• Auth method
• Error codes per endpoint
• Pagination (cursor or offset) — pick ONE, apply to all list endpoints
• Idempotency keys for POST/PUT (if applicable)

1. Write the contract as OpenAPI 3.0 (REST) or GraphQL SDL

Minimal OpenAPI skeleton

openapi: 3.0.0
info: { title: , version: 1.0.0 }
servers: [{ url: https://api.example.com/v1 }]
components:
  securitySchemes:
    BearerAuth: { type: http, scheme: bearer }
  schemas:
    Error: { type: object, properties: { code: { type: string }, message: { type: string } } }
paths:
  /resource:
    post:
      summary: Create resource
      security: [{ BearerAuth: [] }]
      requestBody: { content: { application/json: { schema: { $ref: '#/components/schemas/CreateInput' } } } }
      responses:
        '201': { description: Created, content: { application/json: { schema: { $ref: '#/components/schemas/Resource' } } } }
        '400': { description: Validation error, content: { application/json: { schema: { $ref: '#/components/schemas/Error' } } } }

Gate

• [ ] Endpoints listed in a table (method, path, auth, purpose)
• [ ] Request / response schemas defined
• [ ] Error codes listed (with stable string codes, not just HTTP status)
• [ ] Pagination strategy chosen (cursor preferred)
• [ ] User CONFIRMED contract before continuing

Phase 2: IMPLEMENT

Goal: implement the contract per stack conventions, respecting DDD layers.

Layered placement (DDD)

| Concern | Layer | Notes | |---------|-------|-------| | Route definition | application/ports/http/ | Thin handler: parse → service → respond | | Request / Response DTOs | application/ports/http/dto/ | NOT domain types | | Validation | Handler or domain (depending on stack) | Reject bad input before reaching usecase | | Business logic | domain/{domain}/usecases/ | NEVER in the handler | | External API client | infrastructure/adapters/ | Implements a port in domain/{domain}/ports/ | | Auth check | Middleware / decorator | NOT inline in handler |

Standard error response

All endpoints return errors in the same shape:

{ "error": { "code": "STRING", "message": "human-readable", "details": {} } }

code is stable across versions; message may change. Map domain errors → HTTP codes in ONE place (middleware / interceptor).

Standard pagination (cursor)

GET /resource?cursor=&limit=
→
{
  "data": [...],
  "pagination": { "next_cursor": "..." | null }
}

Gate

• [ ] Routes registered in router / app module
• [ ] Handler is thin (parse → service → respond)
• [ ] Business logic in usecase, not handler
• [ ] External calls go through infrastructure adapter
• [ ] Auth + validation in middleware, not handler
• [ ] Build passes: {stack_build_command}

Phase 3: TEST

Goal: verify the contract holds and breaks safely.

Test layers

| Layer | Type | What | |-------|------|------| | Handler | Unit | Validation, error mapping (mock service) | | UseCase | Unit | Business logic (mock port) | | Adapter (external API) | Integration | Real HTTP call to sandbox OR contract test with nock / WireMock | | End-to-end | Integration | Full request → response, real DB |

Mandatory test cases per endpoint

• [ ] Happy path
• [ ] Auth failure (missing / invalid token)
• [ ] Validation failure (each required field missing)
• [ ] Permission failure (valid token, wrong scope)
• [ ] Not found (where applicable)
• [ ] Rate limit / quota (where applicable)
• [ ] Idempotency (POST with same key returns same response)

Gate

• [ ] All mandatory cases covered
• [ ] Tests pass: {stack_test_command}
• [ ] Error response shape verified in tests

Phase 4: DOCUMENT

Goal: update API docs so consumers can use it without reading code.

What to update

1. OpenAPI spec committed to repo (openapi.yaml or per-resource files)
2. API.md — append the new endpoint(s) (or use /docs-sync for full re-author)
3. CHANGELOG.md — note breaking / additive changes
4. README.md — if this changes quick-start

Endpoint doc entry (minimal)

### POST /resource

Create a resource. Idempotent via `Idempotency-Key` header.

**Auth:** Bearer

**Request**  `{ "field": "value" }`

**Response 201**  `{ "id": "...", "field": "value" }`

**Errors**
| Code | HTTP | Meaning |
|------|------|---------|
| `invalid_field` | 400 | `field` failed validation |
| `unauthorized` | 401 | Token missing or invalid |
| `already_exists` | 409 | Same idempotency key with different body |

Gate

• [ ] OpenAPI spec updated and lints
• [ ] API.md entry added
• [ ] CHANGELOG entry
• [ ] At least 1 example request runs successfully (curl / Postman)

Review Loop (API)

Run /review-code architect for the touched domain. Loop until score ≥ B.

LOOP:
  1. /review-code architect {stack} {domain}
  2. Fix violations → re-run tests + build → GOTO 1 (until score ≥ B)

Final Report (API)

## API Integration Complete

### Endpoints Added / Changed
| Method | Path | Purpose |
|--------|------|---------|

### Files Created
- `application/ports/http/resource_handler.{ext}`
- `domain/{domain}/usecases/create_resource.{ext}`
- `infrastructure/adapters/{external_service}.{ext}` (if applicable)

### Tests
- {N} test files, {M} test cases — handler, usecase, adapter, e2e

### Documentation
- [x] OpenAPI spec updated  [x] API.md entry added  [x] CHANGELOG entry

### Review Score: {A/B}

---

---

Mode DEPRECATE

Safely sunset a feature, API, or module without breaking users. Built around a timeline (T-90 → T+30) and the principle that announce → warn → migrate → remove → monitor.

When to use

• ✅ Sunsetting a public API endpoint, SDK method, or user-facing feature
• ✅ Removing an internal module that other domains depend on
• ✅ Migrating consumers from v1 → v2 of anything
• ❌ Just deleting unused dead code (no consumers) → just delete in PR with explanation
• ❌ Renaming an internal helper → just rename, no deprecation needed
• ❌ Removing a feature behind a flag with 0 users → just remove the flag

Workflow

IDENTIFY → PLAN → MIGRATE → REMOVE → VERIFY
   ↓        ↓        ↓         ↓        ↓
 announce  warn   migrate   remove   monitor
 (T-90)  (T-60)  (T-30)     (T-0)   (T+30)

Deprecation Strategy

| Strategy | When | Timeline | |----------|------|----------| | Soft | Internal API, replacement available, low usage | Announce → warn → migrate → remove (1–3 months) | | Hard | Security issue, breaking infra change | Announce + remove fast (days to weeks, with mitigation) | | Versioned | Public API, breaking change | Run v1 + v2 side-by-side, sunset v1 over months/years |

Phase 1: IDENTIFY

Goal: know what you're removing and who depends on it.

Actions

1. Define the target: feature / endpoint / module / class / metho

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: phuthuycoding
• Source: phuthuycoding/moicle
• License: MIT

Install and usage instructions live in the source repository linked above.