Ref-003: SEA™ Forge Developer Experience (DX) System

Document Type

Reference / Developer Experience (DX) Specification

Purpose

Defines the comprehensive developer experience system for SEA™ Forge, including VS Code integration, Git hooks, CI/CD workflows, and the canonical tooling patterns that enable novice-friendly, hallucination-resistant development.

Design Principles

  1. Single Command — Common workflows should be one command
  2. Auto-Detection — Tool selection (devbox/mise/direct) should be automatic
  3. Fail Early — Catch errors before expensive pipeline stages
  4. Novice-Friendly — Clear diagnostics with copy-pasteable fixes
  5. Agent-Safe — Enforce “no handwritten runtime code” automatically

1. Canonical Commands

The “One Button” Experience

Command Purpose
nx run workspace:check Doctor + affected codegen
nx run workspace:check-all Doctor + full codegen
nx run specs-<ctx>:all Full pipeline for one context
python tools/sea_new_context.py <ctx> Scaffold new context

Per-Context Targets

1
2
3
4
5
6
7

nx run specs-orders:sea:ast        # SEA™ → AST
nx run specs-orders:sea:lint       # AST → lint
nx run specs-orders:sea:ir         # AST → IR
nx run specs-orders:sea:manifest   # IR → manifest
nx run specs-orders:codegen        # manifest → code
nx run specs-orders:determinism    # regen check
nx run specs-orders:all            # all of the above

2. VS Code Integration

Task Configuration (.vscode/tasks.json)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "SEA™: Generate Context (Nx)",
      "type": "shell",
      "command": "nx run specs-${input:ctx}:all",
      "problemMatcher": [],
      "group": { "kind": "build", "isDefault": true }
    },
    {
      "label": "SEA™: Generate Affected Contexts",
      "type": "shell",
      "command": "nx run workspace:codegen-affected",
      "problemMatcher": [],
      "group": "build"
    },
    {
      "label": "SEA™: New Context Scaffold",
      "type": "shell",
      "command": "python tools/sea_new_context.py ${input:ctx}",
      "problemMatcher": []
    },
    {
      "label": "SEA™: Workspace Check",
      "type": "shell",
      "command": "nx run workspace:check",
      "problemMatcher": [],
      "group": "build"
    },
    {
      "label": "SEA™: Enable Git Hooks",
      "type": "shell",
      "command": "bash tools/enable_githooks.sh",
      "problemMatcher": []
    }
  ],
  "inputs": [
    {
      "id": "ctx",
      "type": "promptString",
      "description": "Bounded context name (e.g., orders, inventory, billing)",
      "default": "orders"
    }
  ]
}

3. Git Hooks

Pre-commit Hook (.githooks/pre-commit)

Runs on git commit if any specs/** files changed:

  1. Parse SEA™ to AST for each changed context
  2. Run flow linter on AST
  3. Block commit on lint errors

Pre-push Hook (.githooks/pre-push)

Runs on git push:

  1. Execute nx run workspace:codegen-affected
  2. Verify repo is clean after generation

Enable Hooks

1

bash tools/enable_githooks.sh

This script runs:

1

git config core.hooksPath .githooks

4. Canonical SEA™ Wrapper

tools/ci/run_sea.sh

Auto-detects SEA™ CLI availability:

1
2
3
4
5
6
7
8
9
10

#!/usr/bin/env bash
set -euo pipefail

if [[ -f devbox.json ]] && command -v devbox &>/dev/null; then
  exec devbox run -- sea "$@"
elif [[ -f mise.toml || -f .mise.toml ]] && command -v mise &>/dev/null; then
  exec mise exec -- sea "$@"
else
  exec sea "$@"
fi

All Nx targets, hooks, and CI use this wrapper for consistent behavior.

5. Affected Mode Runner

tools/run_codegen_affected.sh

Detects changed contexts and runs only those:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

#!/usr/bin/env bash
set -euo pipefail

BASE=${1:-origin/main}
CHANGED=$(git diff --name-only "$BASE"...HEAD -- 'specs/**')

for ctx in $(echo "$CHANGED" | sed -n 's|specs/\([^/]*\)/.*|\1|p' | sort -u); do
  if nx show project "specs-$ctx" &>/dev/null; then
    echo "Running: specs-$ctx"
    nx run "specs-$ctx:all"
  else
    echo "Warning: No Nx project for context '$ctx'. Run: python tools/sea_new_context.py $ctx"
  fi
done

6. Doctor Script

tools/doctor.sh

Validates environment prerequisites:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

#!/usr/bin/env bash
set -euo pipefail

echo "=== SEA™ Forge Doctor ==="

# Check SEA™ CLI
if tools/ci/run_sea.sh --version &>/dev/null; then
  echo "✅ SEA™ CLI: $(tools/ci/run_sea.sh --version)"
else
  echo "❌ SEA™ CLI not found"
  exit 1
fi

# Check Python
if python --version &>/dev/null; then
  echo "✅ Python: $(python --version)"
else
  echo "❌ Python not found"
  exit 1
fi

# Check Nx
if npx nx --version &>/dev/null; then
  echo "✅ Nx: $(npx nx --version)"
else
  echo "❌ Nx not found"
  exit 1
fi

# Check jsonschema
if python -c "import jsonschema" &>/dev/null; then
  echo "✅ jsonschema module"
else
  echo "❌ jsonschema not installed. Run: pip install jsonschema"
  exit 1
fi

echo ""
echo "Environment ready! Run: nx run workspace:check"

7. CI Workflow

.github/workflows/ci.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74

name: CI

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate-and-generate:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      # Allowed-file-changes gate
      - name: Allowed file change gate
        if: github.event_name == 'pull_request'
        run: |
          CHANGED=$(git diff --name-only origin/${{ github.base_ref }}...HEAD)
          echo "$CHANGED" | while read -r f; do
            if [[ "$f" =~ ^specs/ ]] ||
               [[ "$f" =~ ^tools/ ]] ||
               [[ "$f" =~ /src/gen/ ]] ||
               [[ "$f" == "nx.json" ]] ||
               [[ "$f" == ".github/workflows/ci.yml" ]]; then
              continue
            fi
            echo "Disallowed change: $f" && exit 1
          done

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install deps (bun/pnpm/npm auto-detect)
        run: |
          if [ -f bun.lockb ]; then
            curl -fsSL https://bun.sh/install | bash
            ~/.bun/bin/bun install --frozen-lockfile
          elif [ -f pnpm-lock.yaml ]; then
            corepack enable && pnpm install --frozen-lockfile
          else
            npm ci
          fi

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"

      - name: Install Python deps
        run: pip install jsonschema

      - name: Run doctor + affected codegen
        run: NX_BASE="origin/${{ github.base_ref }}" npx nx run workspace:check

      - name: Ensure repo clean after generation
        run: |
          git status --porcelain
          test -z "$(git status --porcelain)" || exit 1

      - name: Upload artifacts on failure
        if: failure()
        uses: actions/upload-artifact@v4
        with:
          name: pipeline-artifacts
          path: |
            specs/**/*.ast.json
            specs/**/*.ir.json
            specs/**/*.manifest.json

8. Workspace Nx Project

tools/nx/workspace/project.json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

{
  "name": "workspace",
  "$schema": "../../node_modules/nx/schemas/project-schema.json",
  "projectType": "library",
  "targets": {
    "codegen-affected": {
      "executor": "nx:run-commands",
      "options": {
        "command": "tools/run_codegen_affected.sh ${NX_BASE:-origin/main}"
      }
    },
    "codegen-all": {
      "executor": "nx:run-commands",
      "options": {
        "command": "npx nx run-many -t all --projects $(npx nx show projects | grep '^specs-')"
      }
    },
    "check": {
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "bash tools/doctor.sh",
          "tools/run_codegen_affected.sh ${NX_BASE:-origin/main}"
        ],
        "parallel": false
      }
    },
    "check-all": {
      "executor": "nx:run-commands",
      "options": {
        "commands": [
          "bash tools/doctor.sh",
          "npx nx run-many -t all --projects $(npx nx show projects | grep '^specs-')"
        ],
        "parallel": false
      }
    }
  }
}

9. Nx Registration

nx.json Updates

1
2
3
4
5
6

{
  "projects": {
    "workspace": "tools/nx/workspace",
    "specs-orders": "tools/nx/specs-orders"
  }
}

10. Agent Policy (AGENTS.md)

The DX system enforces agent constraints via:

  1. Allowed-file-changes gate in CI
  2. Pre-commit lint preventing malformed flows
  3. Regen determinism check preventing manual edits

Allowed Edit Directories

Forbidden Edit Directories

11. Summary

The SEA™ Forge DX system provides:

Feature Benefit
One-command workflows Novice-friendly
Auto-detection Works across environments
Pre-commit hooks Fail early
CI gates Prevent hallucinations
VS Code tasks IDE integration
Artifact upload Debug failures easily