generate-speakmanai-code

Phase 3 of the SPEAKMAN.AI pipeline — implement a working, locally-runnable codebase from Phase 2 coding contracts. Routes to a language-specific variant based on TECH_STACK.

SKILL.md

GitHub

generate-speakmanai-code — SPEAKMAN.AI Phase 3 Code Generator (Router)

You are executing Phase 3 of the SPEAKMAN.AI delivery pipeline. Your job is to implement a complete, working, locally-runnable codebase from the Phase 2 coding contracts. You write, install, test, and commit — you do not stop at generating files.

Every milestone has a gate: write code → install dependencies → run the validation command → commit on pass, stop on failure. Do not advance past a failed gate.

The implementation details for each language are in a variant skill file. After loading Phase 2 contracts in Step 1, you identify the language, read its variant file, and use its LANG_CONFIG for all language-specific decisions throughout Steps 2–9. The DDD principles, gate mechanics, and commit conventions in this file apply to every language.


Step 0 — Collect Inputs

Ask the user:

"Do you have Phase 2 output files already on disk?

  • Yes → provide the path to the directory that contains a raw/ folder (e.g. D:\git\tutorial\outputs\2026-06-15_my-project)
  • No → provide your Phase 2 SPEAKMAN.AI session ID and I'll fetch the contracts"

"Where should the new project be created? Provide the parent directory path."

"What is the project/repo name? This becomes the directory name."

"What is the tech stack? Provide: language, runtime, framework, database, and any external services. (e.g. Go 1.22, chi, SQLite, JWT auth or JavaScript, Node.js 22, Express + React 18, SQLite)"

"Do you have a style guide or brand reference for the UI? (Used in Milestone 5 — skip if no frontend.)

  • A file path — a Markdown, CSS, or PDF design guide
  • A URL — a brand or design page to mimic
  • None — skip Milestone 5"

Store:

  • PHASE2_SOURCE: local directory path OR session ID
  • PROJECT_ROOT: parent directory where the repo will be created
  • REPO_NAME: directory name for the new repo
  • REPO_PATH: {PROJECT_ROOT}/{REPO_NAME}
  • TECH_STACK: language, runtime, framework(s), database, external services
  • STYLE_SOURCE: a file path, a URL, or none

Step 1 — Load Phase 2 Contracts

Branch A — Local files on disk

If PHASE2_SOURCE is a directory path, set PHASE2_DIR = that path and read:

File Variable Contains
{PHASE2_DIR}/raw/domain_model.txt DOMAIN_MODEL Aggregates, value objects, invariants, repository interfaces
{PHASE2_DIR}/raw/naming_dictionary.txt NAMING_DICT Canonical names, banned synonyms, SQL/JSON/UI forms
{PHASE2_DIR}/raw/use_case_catalog.txt USE_CASES UC-XX IDs, Gherkin scenarios, actors, req_refs
{PHASE2_DIR}/raw/api_schema.txt API_SCHEMA OpenAPI 3.0 — endpoints, request/response schemas, field constraints
{PHASE2_DIR}/raw/database_schema.txt DB_SCHEMA Idempotent DDL — tables, columns, constraints
{PHASE2_DIR}/raw/test_strategy.txt TEST_STRATEGY Per-layer test type, tooling, mock boundaries, T-xxx IDs

If {PHASE2_DIR}/raw/field_definitions.txt exists, read it as FIELD_DEFS. If absent, warn and continue without it.

Branch B — Fetch from SPEAKMAN.AI (uses credits)

If PHASE2_SOURCE is a session ID, call get_outputs(PHASE2_SOURCE) then fetch each contract in parallel via get_output(session_id, agent_id):

Agent ID Variable Filename
RE_DOMAIN_MODEL_SYNTHESIS_V1 DOMAIN_MODEL domain_model.txt
RE_NAMING_CONVENTION_ARCHITECT_V1 NAMING_DICT naming_dictionary.txt
RE_USE_CASE_ANALYST_V1 USE_CASES use_case_catalog.txt
RE_API_SCHEMA_SYNTHESIS_V1 API_SCHEMA api_schema.txt
RE_DATABASE_SCHEMA_DESIGNER_V1 DB_SCHEMA database_schema.txt
RE_TEST_STRATEGIST_V1 TEST_STRATEGY test_strategy.txt
RE_FIELD_DEFINITIONS_CATALOG_V1 FIELD_DEFS field_definitions.txt (optional)

RE_DOMAIN_MODEL_SYNTHESIS_V1 / RE_API_SCHEMA_SYNTHESIS_V1 are synthesis aggregators that merge two upstream sub-agents server-side — fetch them like any other agent, the combined document shape is unchanged.

Save every fetched file to {PROJECT_ROOT}/outputs/YYYY-MM-DD_{slug}/raw/ so future runs use Branch A and incur no further credit cost.


Step 1c — Select Language Variant

Derive VARIANT from TECH_STACK:

If TECH_STACK contains… VARIANT
"JavaScript", "Node.js", "TypeScript" js
"Python", "FastAPI", "Flask", "Django" python
"Java", "Spring", "Quarkus", "Kotlin" java
"Go", "Golang" go

If no match, ask the user which registered variant to use and list the available ones.

Read the variant file. The variant SKILL.md is a sibling directory to this skill:

{this skill's parent directory}/generate-speakmanai-code-{VARIANT}/SKILL.md

For example, if this skill is at C:\Users\davidis\.claude\skills\generate-speakmanai-code\SKILL.md, the Go variant is at C:\Users\davidis\.claude\skills\generate-speakmanai-code-go\SKILL.md.

Read the variant SKILL.md in full and extract LANG_CONFIG — the complete set of language-specific constants and implementation guides defined in that file.

If the file is not found, stop and report:

"No variant found for '{VARIANT}'. Available variants: js, go, python. To add a new language stack, see CONTRIBUTING.md in the generate-speakmanai-code skill directory."


Derive shared variables

After reading LANG_CONFIG:

  • DIR_SKELETON: apply LANG_CONFIG.DIR_SKELETON_LAYOUT to the aggregate names from DOMAIN_MODEL. Substitute {aggregate} with the lowercased aggregate name in each pattern. Include all entries marked "always present" in LANG_CONFIG.

  • DEPENDENCIES: apply LANG_CONFIG.DEPENDENCIES_DERIVATION rules against TECH_STACK, API_SCHEMA, DOMAIN_MODEL, USE_CASES, and TEST_STRATEGY.

  • CODING_STANDARDS: LANG_CONFIG.CODING_STANDARDS verbatim. All canonical names from NAMING_DICT take precedence over any inferred name.

  • VALIDATION_GATE: LANG_CONFIG.VALIDATION_GATE verbatim.


Step 2 — Scaffold Project

2a — Create directory structure

Create every directory from DIR_SKELETON. No implementation code yet.

Create .gitignore at the repo root using LANG_CONFIG.GITIGNORE_ENTRIES.

Create any scaffold files required by LANG_CONFIG.SCAFFOLD_FILES (build-tool entry points, not application code).

2b — Create manifest files

Create one manifest file per service in DIR_SKELETON per LANG_CONFIG.SCAFFOLD_CONFIG. (The manifest format differs by language: package.json for Node.js, go.mod + Makefile for Go, pom.xml for Java, etc. — follow LANG_CONFIG.SCAFFOLD_CONFIG exactly.)

Wire build commands so every milestone validation target is defined. The root-level top-level test command (npm test, make test, mvn test, etc.) must invoke all per-service test suites sequentially.

After creating manifests, install all declared dependencies in each service:

LANG_CONFIG.MILESTONE_GATES.install   ← run in each service directory

This install step runs once at scaffold time. Re-run it in any service directory whenever new dependencies are added, before re-running the affected gate.

2c — Create environment files

For each service that reads environment variables, create:

  • An example env file (.env.example, config.example.yaml, or equivalent per LANG_CONFIG) — variable names with placeholder values and inline comments
  • A working dev env file — generated secrets (see LANG_CONFIG.SECRET_GENERATION_CMD), non-conflicting port defaults, inter-service URLs, CORS origin

Do NOT commit the working dev env file — it must be in .gitignore.

2d — Git init and initial commit

git init {REPO_PATH}

Stage all scaffold files (manifests, example env files, .gitignore, directory structure):

chore: initialise repository structure

Do NOT commit dev env files.


Step 3 — Milestone 1: Domain Layer

What to write

From DOMAIN_MODEL, implement every aggregate root, child entity, and value object following LANG_CONFIG.DOMAIN_IMPLEMENTATION_GUIDE for language-specific patterns.

Domain layer absolute rules — no exceptions, regardless of language:

  • Zero imports of database drivers, HTTP libraries, file I/O, or any side-effecting module
  • All functions/methods are pure and synchronous
  • Every public export is documented (JSDoc, GoDoc, Javadoc, docstring per LANG_CONFIG)
  • Invariant violations surface as a domain error carrying code: VALIDATION_ERROR — never HTTP status codes
  • Repository interfaces (contracts) live in the application interfaces layer, not in domain

Repository interfaces: defined per LANG_CONFIG.REPO_INTERFACE_PATTERN (JSDoc @typedef, Go interface, Java interface, Python Protocol, etc.).

Write domain unit tests covering every invariant and every value object per LANG_CONFIG.DOMAIN_TEST_GUIDE. Include at least one failing case and one passing case per invariant.

Gate

If new dependencies were added: LANG_CONFIG.MILESTONE_GATES.install (in each affected service).

Run LANG_CONFIG.MILESTONE_GATES.domain.

  • Pass: commit: "feat: implement domain layer — entities, value objects, invariants"
  • Fail: surface the full test output. Fix, re-run. Do not commit. Do not continue.

Step 4 — Milestone 2: Application Layer

What to write

From USE_CASES, implement one use case per UC-XX following LANG_CONFIG.APPLICATION_IMPLEMENTATION_GUIDE.

Application layer absolute rules:

  • Repositories are injected — never imported directly from infrastructure
  • Never import from the interface layer
  • Every mutation use case writes an audit log entry — not optional
  • Business errors are domain error codes (NOT_FOUND, UNAUTHORIZED, CONFLICT, VALIDATION_ERROR) — never HTTP status codes

Write application unit tests per LANG_CONFIG.APPLICATION_TEST_GUIDE:

  • Inject stubbed / mocked repository interfaces
  • Cover every happy path and every unhappy path from USE_CASES
  • Verify audit log repository is called on every mutation

Gate

If new dependencies were added: LANG_CONFIG.MILESTONE_GATES.install (in each affected service).

Run LANG_CONFIG.MILESTONE_GATES.application.

  • Pass: commit: "feat: implement application layer — use cases {UC-01} to {UC-XX}"
  • Fail: fix, re-run. Do not continue.

Step 5 — Milestone 3: Infrastructure Layer

What to write

From DB_SCHEMA, implement per LANG_CONFIG.INFRASTRUCTURE_IMPLEMENTATION_GUIDE:

  • A database connection module — singleton, initialised once at startup
  • A migration runner — executes the full DDL idempotently on startup
  • One repository implementation per aggregate root, mapping DB columns ↔ domain fields per NAMING_DICT (sql_column → domain field name)

Infrastructure rules:

  • NOT_FOUND: when a query returns no row, surface as domain error code: NOT_FOUND
  • CONFLICT: when a unique constraint is violated, surface as domain error code: CONFLICT
  • Boolean columns: convert DB representation ↔ language boolean correctly
  • Column names in SQL follow NAMING_DICT sql_column values
  • Field names in the returned domain object follow NAMING_DICT canonical / json_field values

Write infrastructure integration tests per LANG_CONFIG.INFRASTRUCTURE_TEST_GUIDE:

  • Use a real in-memory database (LANG_CONFIG.LOCAL_DB_TEST) — no mocks
  • Run migrations before each test suite
  • Test every repository method; test constraint violations produce correct domain error codes

Gate

If new dependencies were added: LANG_CONFIG.MILESTONE_GATES.install (in each affected service).

Run LANG_CONFIG.MILESTONE_GATES.infrastructure.

  • Pass: commit: "feat: implement infrastructure layer — repositories and schema migrations"
  • Fail: fix, re-run. Do not continue.

Step 6 — Milestone 4: Interface Layer

What to write

Implement the HTTP interface, optional BFF layer, and optional frontend SPA following LANG_CONFIG.INTERFACE_IMPLEMENTATION_GUIDE.

Backend — non-negotiable interface rules (apply regardless of language):

  • Error handler returns a static string for any unhandled error (status 500) — never forward the raw error message or stack trace to the client
  • Log every unhandled error before responding — silent 500s make production debugging impossible
  • GET /health with no auth requirement — expected by every load balancer and uptime monitor
  • Boolean request fields must be validated as strict boolean type — no coercions that silently accept strings or integers
  • All inter-service URLs come from environment variables — never hardcoded

Field Definitions Catalog enforcement (when FIELD_DEFS is present):

  • Enforce minLength / maxLength on string fields at the API boundary
  • Enforce minimum / maximum on numeric fields
  • Enforce pattern (regex) on string fields where specified
  • Enforce allowedValues (enum) on constrained fields — VALIDATION_ERROR for out-of-range
  • If a field has no constraint entry in FIELD_DEFS, flag as [DECISION REQUIRED]

Domain error → HTTP status mapping (universal):

Domain error code HTTP status
NOT_FOUND 404
UNAUTHORIZED 401
CONFLICT 409
VALIDATION_ERROR 422
unhandled 500 (static message)

Domain event wiring:

  • For every event published by a use case that has a catalog consumer in USE_CASES, wire a subscriber in the composition root invoking the consuming use case
  • A published event with a catalog consumer but no subscriber is an incomplete implementation — the downstream effect silently never happens
  • The subscriber must not throw back into the publisher's request path — log and swallow

BFF layer (if LANG_CONFIG.BFF_PRESENT is true):

  • Stateless, logic-free proxy — no business logic
  • Forwards method, path, headers (especially Authorization), and body verbatim
  • Returns backend response verbatim; returns 502 on network failure
  • See LANG_CONFIG.BFF_IMPLEMENTATION for the language-specific proxy pattern

Frontend SPA (if a SPA framework is in TECH_STACK):

  • All API calls through the BFF — never directly to the backend
  • No business logic in components — only presentation and API calls
  • All service URLs from environment variables

UI completeness rule:

  • Every USE_CASES operation must be reachable from the UI
  • Create forms include inputs for every field the API accepts (required AND optional)
  • List views display all fields meaningful to the user
  • Each list item has controls for every single-resource operation defined in API_SCHEMA
  • Destructive actions require explicit user confirmation before the API call
  • Edit forms pre-populate all current field values

Styling (Milestone 4 default — Milestone 5 applies the real design system):

  • One stylesheet, no external framework
  • Apply at minimum: centered max-width layout, consistent font, distinct button styles, form field spacing, basic table/card structure

Write interface integration tests per LANG_CONFIG.INTERFACE_TEST_GUIDE.

Gate

If new dependencies were added: LANG_CONFIG.MILESTONE_GATES.install (in each affected service).

Run LANG_CONFIG.MILESTONE_GATES.interface.

  • Pass: commit: "feat: implement interface layer — API, BFF proxy, SPA"
  • Fail: fix, re-run. Do not continue.

Step 7 — Milestone 5: UI Styling

Skip if STYLE_SOURCE is none, or if there is no frontend in DIR_SKELETON.

Extract the design system from STYLE_SOURCE (file or URL) — palette, typography, component patterns, layout tokens. Rewrite the frontend stylesheet as a full design system with CSS custom properties. Update all pages to use the design system classes.

Design system rules:

  • CSS custom properties for every palette value — no hardcoded hex in component rules
  • Inline style props only for values derivable only at runtime
  • The stylesheet must stand alone: removing all inline styles must leave the UI visually correct

Gate

Run LANG_CONFIG.MILESTONE_GATES.ui_build.

  • Pass: commit: "style: apply {brand/source} design system to all frontend pages"
  • Fail: fix, re-run. Do not continue.

Step 8 — Milestone 6: E2E

From TEST_STRATEGY, implement one test file per use case covering every Gherkin scenario marked as E2E, following LANG_CONFIG.E2E_IMPLEMENTATION_GUIDE.

Chain dependent use cases through the API — no database seeding at journey seams:

  • Obtain values produced by one use case from the producing endpoint's real API response
  • Database seeding only allowed for preconditions no in-scope use case can create

Primary-journey tests:

  • For every actor flow in USE_CASES (ordered UC sequence), implement at least one journey test running the full sequence through the API

Gate

If new dependencies were added: LANG_CONFIG.MILESTONE_GATES.install (in each affected service).

Run LANG_CONFIG.MILESTONE_GATES.e2e, then immediately run VALIDATION_GATE.

  • Pass (both green): commit: "feat: E2E acceptance tests — all UC-01 to UC-XX scenarios passing"
  • Fail: fix, re-run. Do not commit a broken state.

Step 9 — Report

Project       : {REPO_NAME}
Location      : {REPO_PATH}
Language      : {VARIANT} (variant: generate-speakmanai-code-{VARIANT})
Commits       : 7 (initial scaffold + 6 milestones)
Validation    : {VALIDATION_GATE} — PASS

To run locally:
  {LANG_CONFIG.RUN_LOCALLY_INSTRUCTIONS}

List any [DECISION REQUIRED] items. If there are none, say so.

Then say: "Phase 3 complete. All milestone gates passed and committed. Proceed to Phase 4 (Terraform / cloud deployment) when ready."


Rules

  • Never advance past a failed gate. Fix the failure, re-run, confirm green before committing.
  • All names come from NAMING_DICT. Canonical name for identifiers, sql_column for DB columns, json_field for API fields. Unknown names → [DECISION REQUIRED].
  • No invented business rules. Decisions not in Phase 2 contracts → [DECISION REQUIRED].
  • Domain layer stays pure. No I/O, no side effects. No exceptions.
  • Application layer never imports infrastructure. Repositories always injected.
  • Tests pass before committing. The git log must only contain passing states.
  • Dev env file is never committed. Only the example file goes into git.
  • LANG_CONFIG is authoritative for all language-specific decisions.