Specification: Local Development Tooling

Implementation specification for Part 3 of Component Preparation. Requirements: requirements.md. Verification: verification.md.

Pre-conditions

• Parts 1 and 2 are complete and committed
• All checks pass on the current branch

Current State

Per the analysis, most deliverables already exist:

Deliverable	Status
tools/dev-local.sh	implemented (120 lines)
dev:local npm script	implemented (package.json line 8)
README.md local dev docs	implemented (lines 265-300)
dev-local Makefile target	not implemented
CLAUDE.md local dev docs	needs verification

Implementation Steps

Step 1: Verify CLAUDE.md State

Check whether CLAUDE.md already documents the dev:local workflow. If it does, mark REQ-LT-005 as already met and skip Step 3.

grep -n 'dev:local\|dev-local\|dev:local' CLAUDE.md

Step 2: Add Makefile Target

Add a dev-local target to the Makefile:

dev-local: ## Local dev with @arda-cards packages (npm link + webpack)
  npm run dev:local

Ensure it appears in the help output (the ## comment is the convention for self-documenting targets in this project’s Makefile).

(REQ-LT-003)

Step 3: Update CLAUDE.md (if needed)

If Step 1 found that the dev:local workflow is not documented, add a section covering:

• Sibling directory layout requirement
• npm run dev:local / make dev-local commands
• Custom port: npm run dev:local -- 3001
• --webpack constraint (Turbopack incompatible with symlinks)
• npm install restores registry versions (breaks links)

(REQ-LT-005)

Step 4: Update README.md (if needed)

Verify the README mentions the Makefile target. If not, add make dev-local alongside the existing npm run dev:local reference.

Step 5: Run All Checks

npm run lint
npx tsc --noEmit
npx jest --no-coverage --watchAll=false --forceExit
npm run build

All must exit 0 (REQ-LT-006).

Step 6: Update CHANGELOG

Add entry under [Unreleased]:

### Added

- Added `dev-local` Makefile target for local development with
  `@arda-cards` packages

(REQ-LT-007)

Step 7: Commit

Stage all changes and commit.

Quality Guidelines

• Do not modify tools/dev-local.sh — it is already implemented and working.
• Do not modify package.json beyond what is strictly required.
• Makefile target must use tabs for indentation (Make requirement).

Acceptance Checklist

• make dev-local invokes npm run dev:local
• CLAUDE.md documents the dev:local workflow
• README.md mentions make dev-local
• CHANGELOG updated
• All checks pass

Open Questions and Decisions

#	Question	Options	Recommendation	Decision
1	Should the Makefile target support port forwarding (e.g., make dev-local PORT=3001)?	a) Support via variable, b) Keep simple — use npm script for custom port	Keep simple — npm run dev:local -- 3001 already works; adding Make variable adds complexity for minimal benefit	pending

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved