# Feature Build > Feature lifecycle workflow — build new DDD features, refactor existing code into DDD, add/integrate APIs, or deprecate features. Stack-aware with phase-based checks and a review loop. Use when user says "implement feature", "add feature", "build feature", "create feature", "new feature", "refactor", "clean up", "improve code", "restructure", "migrate to ddd", "refactor ddd", "integrate api", "add… - **Type:** Skill - **Install:** `agentstack add skill-phuthuycoding-moicle-build` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [phuthuycoding](https://agentstack.voostack.com/s/phuthuycoding) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [phuthuycoding](https://github.com/phuthuycoding) - **Source:** https://github.com/phuthuycoding/moicle/tree/master/assets/skills/feature/build ## Install ```sh agentstack add skill-phuthuycoding-moicle-build ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # 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: ```markdown ## 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 ```markdown ## 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 ```bash {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 ```bash {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) ```markdown ## 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) 3. Write the contract as **OpenAPI 3.0** (REST) or **GraphQL SDL** ### Minimal OpenAPI skeleton ```yaml 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: ```json { "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) ```markdown ### 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) ```markdown ## 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](https://github.com/phuthuycoding) - **Source:** [phuthuycoding/moicle](https://github.com/phuthuycoding/moicle) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-phuthuycoding-moicle-build - Seller: https://agentstack.voostack.com/s/phuthuycoding - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.