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.claude/skills/generate-speakmanai-code/SKILL.md
GitHubgenerate-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 authorJavaScript, 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_columnvalues - Field names in the returned domain object follow NAMING_DICT canonical /
json_fieldvalues
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 /healthwith 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/maxLengthon string fields at the API boundary - Enforce
minimum/maximumon 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.