Skill: Migrate To BCE

Objective

Guide safe, incremental migration of an existing project to Boundary-Control-Entity architecture. This skill owns the migration workflow: discovery, target component model, migration plan, and convergence steps. Technology-specific implementation, build, tests, and framework idioms belong to composed stack skills.

Use this skill with a BCE architecture skill when available. Use SBCE or SDD4J when the migration also needs capability specs, requirement traceability, or spec-driven convergence. When reverse engineering migrated BCs into SBCE or SDD4J specs, also backfill the generated requirement IDs into the corresponding migrated BC tests so the specs and tests are traceable from the start.

Core Rule

For any BCE migration request, produce a migration plan before editing code unless the user explicitly says a plan already exists and asks to execute a specific step.

The plan is important because migrating to BCE changes ownership boundaries, not just folders. A safe migration must identify business responsibilities first, then move behavior without changing observable behavior.

Operating Modes

Classify the user request into one mode:

• assess: inspect the current architecture and explain BCE migration fit.
• plan: create a migration plan with proposed business components and steps.
• apply: execute one approved migration step from an existing plan.
• verify: check whether migrated code follows the plan and BCE rules.

Default to plan when the user asks to migrate, port, convert, or refactor to BCE. Default to assess when the user asks whether BCE fits or asks for advice only.

Discovery Workflow

Before planning, inspect the repository enough to understand its shape:

• Read project guidance files such as AGENTS.md, CLAUDE.md, architecture docs, README files, and package/module conventions.
• Identify the build system, source roots, test roots, and major modules.
• Identify current architectural style: package-by-layer, package-by-feature, MVC, hexagonal, CRUD services, scripts, monolith, or mixed layout.
• Identify externally visible entry points: APIs, CLIs, UI routes, jobs, message handlers, controllers, resources, handlers, or exported functions.
• Identify domain nouns, use cases, persistent entities, repositories, services, policies, and integrations.
• Identify existing tests and the command that verifies behavior.
• Identify test files that exercise each source file, entry point, use case, or component, including unit, integration, system, contract, and characterization tests.

Use the smallest investigation that can support a credible plan. Do not rewrite or move files during discovery.

Migration Documentation

For long-running BCE migrations, create a .bce-migration directory in the project root to track progress and decisions:

.bce-migration/
├── plan.md     # Migration plan + component catalog + decisions
└── journal.md  # Progress journal with chronological entries

plan.md should contain:

• Current architecture assessment
• Proposed business components with status tracking table
• Package naming decisions and architectural decisions
• Migration strategy and sequencing rationale
• Detailed step-by-step migration plan
• Risk assessment and mitigation checks
• Recommended first step

journal.md should contain chronological entries:

## [YYYY-MM-DD] - Step N: Component Name Migration
- Status: [In Progress/Completed/Blocked]
- Changes made: [list files moved/modified]
- Tests run: [command and result]
- Issues encountered: [any problems and resolutions]
- Decisions made: [architectural decisions during this step]
- Next steps: [what needs to happen next]

Create this documentation structure during the plan mode before any code changes. Update journal.md after each migration step in apply mode. This provides traceability, enables pause/resume capability, and creates a permanent record of the migration for collaboration and future reference.

Subagent Delegation

For medium or large repositories, delegate read-only discovery to an exploration subagent when the harness supports subagents. Ask it to return source roots, test roots, major modules, entrypoints, domain nouns, use cases, persistence artifacts, existing tests, verification commands, likely BCE component candidates, and uncertainty notes. The subagent must not edit files, move code, update tests, run destructive commands, or make migration decisions.

After applying a migration slice, a read-only review subagent may independently check for obsolete technical-layer packages, directly associated tests that were not moved, empty-package cleanup candidates, BCE structure drift, and missing verification evidence. The main agent owns the migration plan, user questions, final component boundaries, all edits, verification commands, and final reporting.

BCE Target Model

Use these BCE rules for migration decisions:

• A business component is named after a business responsibility, capability, or shared domain concern.
• A component may have boundary, control, and entity layers, but not every component needs every layer.
• Boundary owns external entry points, protocol adapters, UI/event adapters, facades, authorization wrappers, transactions, and request/response mapping.
• Control owns procedural business logic, orchestration, policies, and use-case coordination.
• Entity owns domain state, invariants, value objects, domain behavior, and persistence-facing domain objects where applicable.
• Shared technical utilities are not business components unless they carry reusable domain or protocol semantics.
• Avoid naming components after technical layers such as controller, service, repository, dto, util, or config.

Prefer preserving existing names when they already express a responsibility. Rename only when the current name is misleading or purely technical.

Test Migration Rule

Tests are part of BCE convergence, but usually move last within each migration slice.

For each approved migration step:

1. Move production code first.
2. Update imports, configuration, registration, and wiring until the project compiles.
3. Run the relevant tests to confirm behavior is preserved before relocating tests when feasible.
4. Move the directly associated tests to mirror the new BCE component and layer when the project uses mirrored test packages or component ownership.
5. Identify source and test packages or directories that became empty because of the migration slice.
6. Double-check each candidate directory/package to confirm it is still empty immediately before removal, then remove only confirmed-empty candidates.
7. Run the relevant or full verification command again after test relocation and empty-package cleanup.

Empty-package cleanup is part of migration convergence because obsolete package shells make the architecture look transitional after the code has moved. Before deleting anything, check candidates twice: first when identifying empty packages/directories after the move, and again immediately before removal to ensure no files, hidden files, resource files, package markers, or concurrent changes appeared. Remove only directories/packages that are confirmed empty by this second check and are owned by the migrated source or test roots. Do not remove generated output, build directories, vendor directories, resource directories with meaningful non-code files, or intentionally reserved package markers unless the project-local convention says they are disposable.

A migration slice is not complete until:

• production code is under the intended BCE component and layer,
• directly associated tests are under the corresponding BCE test package when local conventions allow it,
• obsolete source/test packages or directories emptied by the move have been double-checked as empty and removed,
• the project compiles,
• and the relevant or full test suite passes.

Do not report a BCE migration step as complete if tests still live in obsolete technical-layer packages, unless a stronger project-local test convention explicitly requires that layout.

Spec Reverse Engineering Prompt

When sbce or sdd4j skills are available in the environment, add one explicit post-migration decision point after BCE code and tests are green:

• Ask whether the user wants to reverse engineer the migrated business components into capability specs, preparing the project to use SBCE or SDD4J workflows.

Do not generate specs automatically. Ask one focused question and offer the available options:

• use sbce when the user wants one capability spec per business component and spec-driven BCE convergence,
• use sdd4j when the user wants Java package-info.java capability specs, EARS requirements, or traceable requirement tests,
• skip spec reverse engineering for now.

If the user chooses spec reverse engineering, compose this skill with the selected spec workflow skill and treat the generated specs as a separate follow-up migration step. Preserve the already-green BCE migration state.

During that follow-up step, include traceability backfill for the tests of each migrated business component:

• Assign or preserve stable requirement IDs in the generated SBCE or SDD4J spec according to the selected workflow's conventions.
• Map each generated requirement ID to the migrated tests that already cover that behavior.
• Add those IDs to the respective tests using the project's existing traceability style, such as parameterized test row labels, display names, method names, comments, assertion messages, or test metadata.
• Prefer the traceability format required by sdd4j-ears-tests or ears-tests when those skills are used.
• Do not change test semantics while adding IDs. If a migrated behavior has no matching test, report the missing coverage instead of inventing a passing test unless the user asked to add tests.
• Re-run the relevant test command after adding IDs to confirm the traceability edit did not break verification.

Migration Plan Output

When producing a plan, use this structure and write it to .bce-migration/plan.md:

## BCE Migration Plan

### Current Shape
[Brief description of the current architecture and verification command if known.]

### Proposed Business Components
| Component | Responsibility | Status | Boundary | Control | Entity | Source Evidence |
| --- | --- | --- | --- | --- | --- | --- |

### Package Naming Decision
[Chosen package naming pattern with rationale]

### Migration Strategy
[Incremental strategy and sequencing rationale.]

### Steps
1. [Small, behavior-preserving migration step.]
2. [Next step.]

### Risks And Checks
| Risk | Check |
| --- | --- |

### Recommended First Step
[The smallest useful step to apply if the user wants to continue.]

Keep the plan concrete. Reference actual packages, directories, files, classes, modules, or routes discovered in the repository. Include a status column in the components table to track migration progress (Not Started, In Progress, Completed).

Planning Heuristics

Create steps that are small enough to verify independently:

• Start with one low-risk component or one vertical slice, not the whole codebase.
• Prefer moving code before renaming code when both are needed.
• Prefer introducing component directories/packages before changing behavior.
• Preserve public APIs, routes, CLI commands, data formats, database schemas, and persisted data unless the user approves a breaking change.
• Keep adapters at the edge and business rules in control/entity layers.
• Leave mixed or transitional layouts explicit rather than pretending the migration is complete.
• When tests are weak, add characterization tests or document manual checks before moving risky behavior.
• Treat tests as part of the migration unit. Moving production code without moving its directly associated tests is incomplete when tests mirror source structure or component ownership.
• Prefer moving tests after production code is stable in the new package, so behavior failures and test-package relocation failures are not mixed together.
• After each move, identify packages or directories that became empty in the source and test roots, then double-check each candidate immediately before deleting it so cleanup is safe and does not remove concurrent or meaningful files.

Do not create compatibility shims unless there is a concrete need: external consumers, persisted data, shipped behavior, or explicit user requirement.

Applying A Migration Step

Only apply code changes when the user asks to execute a plan or a specific migration step.

When applying:

1. Restate the selected step briefly.
2. Add a new entry to .bce-migration/journal.md with status "In Progress".
3. Inspect the touched files before editing.
4. Move or refactor the minimum code needed for that step.
5. Preserve behavior and public contracts.
6. Update imports, package/module declarations, registration/configuration, and wiring affected by the move.
7. Run the relevant formatter/build/tests when available to confirm production behavior is still preserved.
8. Move directly associated tests to the corresponding BCE component/layer test package when local conventions allow mirrored tests.
9. Identify source/test packages or directories that became empty as a direct result of the move.
10. Double-check each candidate directory/package immediately before removal and remove only candidates still confirmed empty.
11. Run the relevant or full verification command again after test relocation and empty-package cleanup.
12. Update the journal.md entry with status "Completed", changes made, test results, issues encountered, and decisions made.
13. Update the component status in .bce-migration/plan.md.
14. If sbce or sdd4j skills are available and the migrated BCE slice is green, ask whether to reverse engineer migrated BCs into capability specs for SBCE or SDD4J.
15. When the user chooses spec reverse engineering, generate the selected spec artifacts and add the generated requirement IDs to the respective tests of the migrated BCs.
16. Report what changed, what was verified, what tests moved, what empty packages/directories were double-checked and removed, the user's spec reverse-engineering decision when asked, which requirement IDs were added to tests, and what remains transitional.

If the repository has uncommitted unrelated changes, do not revert or rewrite them. Work around them unless they directly conflict with the selected step.

Verification

For verify mode, check both structure and behavior:

• Components are named after responsibilities.
• boundary, control, and entity appear only inside business components.
• External entry points live in boundary or call a boundary facade when one is justified.
• Procedural business logic is not stranded in controllers, handlers, DTOs, repositories, config classes, or root packages.
• Domain state and invariants are in entity types where the stack supports that shape.
• Cross-component dependencies are intentional and minimal.
• Tests or documented checks cover the migrated behavior.
• Migrated production code has matching migrated tests in the corresponding BCE test package when local conventions allow mirrored tests.
• Packages or directories emptied by migrated source/test moves have been double-checked as empty immediately before removal.
• The project compiles and the relevant or full test suite passes after production-code relocation, test relocation, and empty-package cleanup.
• If migrated BCs were reverse engineered into SBCE or SDD4J specs, generated requirement IDs appear in the corresponding migrated BC tests using the selected workflow's traceability convention.
• When sbce or sdd4j skills are available, the user has been asked whether to reverse engineer migrated BCs into specs, or the report explicitly notes that this follow-up was not requested.

Report gaps as actionable follow-up steps. Do not silently expand the migration scope while verifying.

Composition

Compose this skill with:

• bce for detailed Boundary-Control-Entity architectural rules when available.
• sbce when the user wants one capability spec per business component, spec-driven BCE convergence, or reverse engineering migrated BCs into capability specs with test IDs.
• sdd4j and sdd4j-bce for Java projects using package-info.java specs, EARS requirements, traceable tests, or reverse engineering migrated Java BCE components into co-located specs with test IDs.
• ears-tests or sdd4j-ears-tests when generated requirement IDs need to be represented in table-driven or grep-traceable tests.
• The relevant stack skill for language, framework, build, test, and runtime conventions.

This skill does not override stronger project-local instructions in AGENTS.md or an existing architecture decision record. Surface conflicts and ask one focused question when the migration target is ambiguous.