sea-context-init

name	sea-context-init
description	Initialize a new SEA bounded context with proper structure, templates, and governance. Creates complete bounded context scaffolding.
disable-model-invocation	true

SEA Context Initialization

Initialize a new SEA bounded context with complete project structure, configuration, templates, and governance compliance.

When to Use

Invoke when:

• Starting a new bounded context
• Creating a new domain area
• Scaffolding a new service
• Setting up a new feature module

Usage

User invokes with:

• "Initialize a new bounded context for X"
• "Create a new context called Y"
• "Scaffold a new domain for Z"

Context Structure

A SEA bounded context includes:

apps/{context-name}/
├── src/
│   ├── gen/              # Generated handlers (DO NOT EDIT)
│   ├── domain/           # Domain logic
│   ├── application/      # Application services
│   ├── infrastructure/   # External integrations
│   └── interfaces/       # API interfaces
├── spec/                 # Context specification
├── tests/                # Context tests
├── package.json
├── tsconfig.json
└── README.md

Initialization Process

Step 1: Validate Context Name

# Validate name follows conventions
# - kebab-case
# - 3-30 characters
# - Alphanumeric + hyphens only
# - Must start with letter

CONTEXT_NAME="$1"

if ! echo "$CONTEXT_NAME" | grep -qE '^[a-z][a-z0-9-]{2,29}$'; then
  echo "❌ Invalid context name: $CONTEXT_NAME"
  echo "Context names must be:"
  echo "  - kebab-case"
  echo "  - 3-30 characters"
  echo "  - Start with a letter"
  echo "  - Alphanumeric + hyphens only"
  exit 1
fi

echo "✅ Context name validated: $CONTEXT_NAME"

Step 2: Create Directory Structure

# Create context directories
mkdir -p "apps/$CONTEXT_NAME"/{src/{gen,domain,application,infrastructure,interfaces},spec,tests}

echo "✅ Created directory structure"

Step 3: Generate Configuration Files

package.json:

{
  "name": "@sea/$CONTEXT_NAME",
  "version": "0.1.0",
  "private": true,
  "type": "module",
  "scripts": {
    "build": "tsc",
    "test": "vitest",
    "lint": "eslint src"
  },
  "dependencies": {
    "@sprime01/sea": "workspace:*"
  }
}

tsconfig.json:

{
  "extends": "../../tsconfig.base.json",
  "compilerOptions": {
    "outDir": "./dist",
    "rootDir": "./src",
    "composite": true
  },
  "include": ["src/**/*"],
  "references": []
}

Step 4: Create Specification Template

spec/context.yaml:

# SEA Bounded Context Specification

context:
  name: $CONTEXT_NAME
  version: 0.1.0
  status: draft

domain:
  # Domain definition
  # What bounded problem this context solves

capabilities:
  # Business capabilities provided
  - name: Example Capability
    description: Description of capability

api_surface:
  # API contracts
  endpoints: []
  events: []
  schemas: []

boundaries:
  # Context boundaries
  owns: []
  publishes: []
  subscribes: []

Step 5: Create README Template

README.md:

# $CONTEXT_NAME Context

## Purpose
{What this bounded context does}

## Domain
{Domain description}

## Capabilities
- {Capability 1}
- {Capability 2}

## API Surface
{API documentation link}

## Governance
- Spec: [spec/context.yaml](spec/context.yaml)
- Generated code: [src/gen/](src/gen/) - DO NOT EDIT
- Handlers: Regenerate via `just pipeline $CONTEXT_NAME`

## Development
\`\`\`bash
# Install
pnpm install

# Build
pnpm build

# Test
pnpm test

# Lint
pnpm lint
\`\`\`

Step 6: Create Guardrails

.SEA-PROTECTED file in src/gen/:

# ⚠️  GENERATED CODE ZONE - DO NOT EDIT ⚠️
#
# All files in this directory are automatically generated
# from the SEA specification (spec/context.yaml).
#
# To modify behavior:
# 1. Edit spec/context.yaml
# 2. Run: just pipeline $CONTEXT_NAME
# 3. Generated handlers will be updated
#
# Manual edits will be overwritten.

Step 7: Initialize Git

# Create initial commit
git add "apps/$CONTEXT_NAME"
git commit -m "feat: initialize $CONTEXT_NAME bounded context"

Step 8: Register with Workspace

Update nx.json or workspace configuration:

{
  "projects": {
    "$CONTEXT_NAME": "apps/$CONTEXT_NAME"
  }
}

Validation Checklist

After initialization, verify:

• Directory structure created
• package.json configured
• tsconfig.json extends base
• Spec template created
• README.md with documentation
• .SEA-PROTECTED in src/gen/
• Registered in workspace
• Git commit created

Quick Start Example

# Initialize new context
sea-context-init user-management

# Output:
# ✅ Context name validated: user-management
# ✅ Created directory structure
# ✅ Generated configuration files
# ✅ Created spec template
# ✅ Generated README
# ✅ Created guardrails
# ✅ Registered in workspace
# ✅ Git commit created
#
# Next steps:
# 1. Edit apps/user-management/spec/context.yaml
# 2. Run: just pipeline user-management
# 3. Implement domain logic in src/domain/

Integration

• Integrates with nx-workspace for project registration
• Integrates with sea-generator-first for handler generation
• Integrates with governance-validation for CALM compliance
• Integrates with spec-guardian for generated code protection

Output

After initialization:

## SEA Context Initialized

**Context**: {name}
**Location**: apps/{name}/
**Spec**: apps/{name}/spec/context.yaml
**Status**: ready for development

### Structure Created
- src/domain/ - Domain logic
- src/application/ - Application services
- src/infrastructure/ - External integrations
- src/interfaces/ - API interfaces
- src/gen/ - Generated handlers (PROTECTED)
- spec/ - Context specification
- tests/ - Context tests

### Next Steps
1. Edit spec/context.yaml with domain definition
2. Run: just pipeline {name}
3. Implement domain logic
4. Write tests in tests/