Implementation Plan: [Feature Name]

Phase 9 Artifact — This plan enables vertical slice delivery per ENGINEERING.SOP.md.

Purpose

[Brief description of what this feature delivers and why it matters. 1-2 sentences.]

Pre-Flight Validation

STOP. Before writing this plan, validate all input specifications. Each checkbox must pass.

ADR Validation

If any ADR check fails: Create or fix the ADR before proceeding. See develop-software.md § Step 2.

PRD Validation

If any PRD check fails: Create or fix the PRD before proceeding. See develop-software.md § Step 3.

SDS Validation

If any SDS check fails: Run just sds-validate <file> and fix errors. See develop-software.md § Step 4.

SEA-DSL Validation

If any SEA™ check fails: Run just sea-validate <file> and fix errors. Reference SEA-DSL language docs.

Pipeline Verification

1
2
3
4
# Run full pipeline to verify all specs compile
just pipeline <context-name>

# Expected: All steps pass, manifest generated

• Pipeline completes without errors
• <ctx>.manifest.json generated
• just regen-check <ctx>.manifest.json passes (determinism)

Provenance Chain

Establish complete traceability from ADR → PRD → SDS → Implementation.

graph TD
    ADR[ADR-###: Decision Title] --> PRD1[PRD-###: Requirement 1]
    ADR --> PRD2[PRD-###: Requirement 2]
    PRD1 --> SDS1[SDS: Entity/Flow A]
    PRD2 --> SDS2[SDS: Entity/Flow B]
    SDS1 --> C1[Cycle C1A: Implementation]
    SDS2 --> C2[Cycle C2A: Implementation]

    style ADR fill:#e1f5ff
    style PRD1 fill:#fff4e1
    style PRD2 fill:#fff4e1
    style SDS1 fill:#e8f5e9
    style SDS2 fill:#e8f5e9

Implementation Order

Required sequence per ENGINEERING.SOP.md Phase 9. Do not skip steps.

For each vertical slice:

1. Domain model + invariants — Entities, value objects, policies
2. Use case / application logic — Commands, queries, handlers
3. Ports — Interfaces + fake implementations
4. Adapters — Real implementations
5. Wiring — API/UI integration
6. Observability — Telemetry hooks (sea.domain, sea.concept)
7. Tests — Unit, integration, E2E as appropriate
8. Feature flag — If rollout risk exists

Proposed Cycles (Worktree-First)

Each cycle = one branch + one worktree. Waves enable parallel work.

Starting a Cycle

1
2
3
4
5
6
7
# Creates branch + worktree in one command
just cycle-start 9 1 A entity-order

# Output:
#   Branch: cycle/p9-c1A-entity-order
#   Worktree: ../SEA-p9-c1A
#   cd ../SEA-p9-c1A

Wave 1 (Parallel — can run simultaneously in separate worktrees)

• C1A: [Description of what this cycle implements]
  • Worktree: ../SEA-p9-c1A
  • Implements: Entity X from SDS
  • Satisfies: PRD-### REQ-###
  • Generator: just generator-bc <ctx> (if new context)
  • Files: [list files created/modified]
• C1B: [Description]
  • Worktree: ../SEA-p9-c1B
  • Implements: Flow Y from SDS
  • Satisfies: PRD-### REQ-###
  • Files: [list files]

Wave 2 (Depends on Wave 1 — start after Wave 1 PRs merged)

• C2AA: [Description]
  • Worktree: ../SEA-p9-c2AA
  • Implements: Adapter for Port Z
  • Satisfies: PRD-### REQ-###
  • Depends on: C1A, C1B
  • Files: [list files]

Worktree Lifecycle

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 1. Start cycle (creates branch + worktree)
just cycle-start 9 1 A entity-order
cd ../SEA-p9-c1A

# 2. Do work in the worktree
just pipeline <ctx>
just test
git add . && git commit -m "feat: implement Entity X"

# 3. Complete cycle (pushes, prepares for PR)
just cycle-complete 9 1 A

# 4. Create PR from worktree
gh pr create --base dev

# 5. After PR merged, cleanup
cd /path/to/main/SEA™
just cycle-worktree-remove 9 1 A

# Or clean all merged worktrees at once
just worktrees-clean

Nx Generators to Use

From develop-software.md § Generators.

Expected Filetree After Implementation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
libs/<context>/
├── domain/
│   └── src/
│       ├── index.ts
│       └── lib/
│           ├── <entity>.ts          # [SDS: Entity X]
│           └── <value-object>.ts    # [SDS: VO Y]
├── ports/
│   └── src/
│       └── lib/
│           └── <port>.port.ts       # [SDS: Port Z]
├── adapters/
│   └── src/
│       └── lib/
│           ├── <adapter>.adapter.ts # Real implementation
│           └── <adapter>.fake.ts    # Fake for testing
└── application/
    └── src/
        └── lib/
            ├── <command>.handler.ts # [SDS: Flow Command]
            └── <query>.handler.ts   # [SDS: Flow Query]

Validation & Verification

Per develop-software.md § CI/CD Gates.

Pre-Merge Checks

• just spec-guard passes
• just test passes
• just nx-run workspace check passes
• git diff --exit-code (repo clean after generation)

Post-Implementation Verification

• All generated code passes type checking
• Unit tests cover domain invariants
• Integration tests verify adapter behavior
• Telemetry emits correct semantic context
• Feature flag (if used) tested in both states

Dependencies Introduced

Only list if this plan introduces NEW dependencies.

If adding dependencies, complete the Dependency Review Checklist.

Risks & Mitigations

Open Questions

Document 1-3 unresolved items that need clarification before or during implementation.

1. [Question about unclear requirement or design decision]
2. [Question about integration with existing systems]

References

Do not duplicate content from these documents. Read them for full context.