Language Tutorial Template

This page defines the required structure for a PACE language tutorial. Every tutorial in the Language Stack Tutorials section must include all sections listed here. Sections marked optional may be omitted if genuinely not applicable to the language.

Naming and location

File: src/content/docs/tutorials/<language-slug>.md (e.g. kotlin.md, elixir.md)
Title format: PACE with <Language> (<Framework>) — e.g. PACE with Kotlin (Spring Boot)
Sidebar order: assign the next available integer after existing language tutorials

Required frontmatter

---
title: PACE with <Language> (<Framework>)
description: Configure PACE for a <Language> <Framework> project using <test tool> and <build tool>.
sidebar:
  order: <N>
---

Required sections (in order)

Intro paragraph

One paragraph. State what FORGE will write, what GATE will run, and what SENTINEL audits. Do not repeat the title.

Prerequisites

Bullet list: language runtime version, build tool version, test framework version, PACE API key requirement.

Project layout

Fenced code block (no language tag — renders as plain text) showing the assumed directory structure, with inline comments marking the pace/ subdirectory and test directory.

1 — Install PACE

Standard PACE installation. Use this exact block:

# From your repo root
git clone https://github.com/pace-framework-org/pace-framework-starter pace
cd pace
python -m venv .venv && source .venv/bin/activate
pip install PyYAML jsonschema anthropic

2 — Configure for <Language>

Full pace.config.yaml with:

product.name, product.description, product.github_org
source.dirs — at minimum one source dir and one test dir with language: set
tech.primary_language, tech.ci_system, tech.test_command, tech.build_command
platform.ci: local ← always ci:, never type:
llm.provider: anthropic, llm.model: claude-sonnet-4-6

Follow with a test command variants table covering: default, specific directory, with coverage, with parallelism, any common framework variant.

3 — FORGE hints for <Language>

Show an extended product.description YAML block with 4–6 language-specific hints. Cover:

Where business logic lives vs controllers/handlers
Preferred injection pattern (constructor, DI container, etc.)
Preferred test mocking library
Code style rule (linter name + max line length)
Any language-specific footgun FORGE commonly hits (e.g. nullable types, ESM/CJS, lifetime annotations)

4 — Set credentials

export ANTHROPIC_API_KEY="sk-ant-..."

5 — Write a <Language> sprint plan

plan.yaml must use the v3 stories format:

release: v1.0

stories:
  - id: story-1
    title: "..."
    status: pending
    acceptance_criteria:
      - "..."
    out_of_scope:
      - "..."

  - id: story-2
    ...

  - id: story-3
    ...

Use exactly 3 stories that form a coherent vertical slice: domain model → service layer → HTTP endpoint. Each story’s final AC must include <test-command> exits 0.

Do not use the legacy days: format.

6 — Run Day 1

Standard run command:

cd pace
python pace/orchestrator.py --day 1

What FORGE does with <Language>

Numbered list of 5 steps FORGE takes (read config file → read source → write files → run build → run tests). Follow with a text fenced block showing a realistic FORGE terminal output.

What SENTINEL checks for <Language>

Bullet list of 6–8 language-specific security checks with the category in bold: **Injection**, **Deserialization**, **Secrets**, etc.

7 — Test coverage

Show the configuration file change (e.g. pom.xml, pyproject.toml, jest.config.js, Cargo.toml) and the updated test_command that enforces a minimum threshold (80%). Note what happens when coverage drops below the threshold (GATE HOLDs).

8 — Linter and formatter

Show the build_command that runs the linter. Include the minimal config file for the linter. State what the FORGE hint in product.description should say.

9 — Database testing patterns

Two sub-sections:

In-memory / embedded — fast unit tests with no external dependency (H2, SQLite, pg-mem, etc.)
Testcontainers — real engine for integration tests, with a note on marking/excluding slow tests

Include a product.description hint telling FORGE which pattern to use.

10 — Mock patterns

Show the preferred mocking library with a minimal working example (mock setup → call service → assert expectation). Include the product.description hint that guides FORGE to use this library.

11 — Multi-day sprint (Day 2 builds on Day 1)

One paragraph explaining the SCRIBE → engineering.md → FORGE feedback loop. Show a text fenced block of FORGE output on Day 2 reading engineering.md and referencing Day 1 types.

12 — Advisory clearance story

Show a complete plan.yaml clearance story entry. List 3–4 common SENTINEL advisories specific to this language with their fixes.

13 — CI build caching

GitHub Actions YAML snippet showing the correct cache action for this language’s package manager. Note any caveats (e.g. lock file required, cache key format).

14 — Advanced config (optional)

Language-specific section: multi-module/workspace setups, framework variants (NestJS, Django, Rails engines), monorepo tooling. Omit if not applicable.

15 — Windows notes

One paragraph covering Windows-specific differences: activation command, PATH setup, any commands that differ on Windows vs Unix.

Common issues

4–5 issues in bold-title format:

**`command: not found`**
Explanation and fix.

**FORGE writes to wrong namespace/package**
Explanation and fix.

Checklist before submitting

All code blocks have language tags (yaml, bash, java, go, etc.)
plan.yaml uses v3 stories: format (not days:)
platform.ci: local (not platform.type:)
python pace/orchestrator.py --day 1 (not PACE_DAY=1 python ...)
llm.model: claude-sonnet-4-6
No occurrences of “nolapse” anywhere in the file
Sidebar order does not duplicate an existing entry
Astro/Starlight admonitions used where appropriate (:::note, :::tip, :::caution)
New file added to astro.config.mjs sidebar under Language Stack Tutorials