Imported from jonasyr/-german-logic-puzzle-generator (AGENTS.md). Install upstream with npx skills add jonasyr/-german-logic-puzzle-generator. Copyright stays with the author.

AI Coding Agent Guide

Name: -german-logic-puzzle-generator
Author: jonasyr

Welcome to the Logic Puzzle Generator repository! This document contains essential instructions and context for AI coding agents operating on this codebase.

1. Core Documentation & Terms of Use

Primary Source of Truth: Always read README.md before designing, modifying, or extending features. It documents the complete public API surface, core concepts (Nominal vs. Ordinal categories, clue types, proof chains, red herrings, difficulty estimation), and architectural guidelines.
AI Disclosure & Liability: Refer to the AI Disclosure & Liability Policy in README.md. Any generated code, algorithms, or modifications must adhere to MIT license requirements and maintain strict solvability and determinism guarantees.

2. Codebase Architecture

The core engine is located under src/:

File / Directory	Description
`src/types.ts`	Fundamental types: `CategoryConfig`, `CategoryType`, `ClueType`, `TargetFact`, `ProofStep`, `RedHerringOptions`, etc.
`src/engine/Generator.ts`	Core puzzle generator, heuristic scoring, forward search, backtracking, and red herring synthesis.
`src/engine/Solver.ts`	Forward-chaining deduction engine, clue applicators, and contradiction checker.
`src/engine/LogicGrid.ts`	Possibility matrix representation and elimination tracking.
`src/engine/GenerativeSession.ts`	Stateful session manager for interactive, step-by-step puzzle creation and live proof-chain editing.
`src/engine/Clue.ts`	Class hierarchy for all clue variants (Binary, Ordinal, Superlative, Unary, Between, Adjacency, Cross-Ordinal, Disjunction, Arithmetic).
`src/engine/determinism.ts`	Seeded PRNG helpers, engine-agnostic stable sort, and Fisher-Yates shuffle.
`src/index.ts`	Public package export barrel.
`src/germanBooklet.ts`	Configurable German booklet generator (themes, difficulty, seeds, palette) with per-puzzle verification.
`src/german.ts`	German clue formatter driven by a `GermanClueLanguage` wording object.
`tools/generate_german_pdf.py`	ReportLab renderer for the printable booklet (dynamic grid, dynamic solution table, palette from JSON).
`server/index.ts`	Dependency-free HTTP server: static web app plus `/api/options`, `/api/booklet`, `/api/pdf`.
`webapp/`	Vanilla HTML/CSS/JS front end (start → settings → preview/PDF → play).
`webapp/playLogic.js`	Pure scoring rules of the interactive grid, shared with the test suite.

3. Engineering & Quality Standards

Determinism: The engine is strictly deterministic across platforms (Node, V8, React Native Hermes, browsers). Never use Math.random() or unseeded sorting. Always use the seeded PRNG (mulberry32) and helpers from determinism.ts.
Backward Compatibility: Any new feature (e.g., Red Herrings) must be opt-in and default to 0 / disabled, ensuring existing API consumers experience zero behavioral regressions.
Comprehensive Testing:
- Tests live in test/.
- Run npm test before submitting any change.
- Every new feature, option, or bugfix must be covered with unit tests, boundary tests, and regression tests.
Build & Type Checking:
- Run npm run build to verify TypeScript compilation (tsc) and definition emission.

4. Release & Deployment Workflows

Releases and site deployments are automated via GitHub Actions in .github/workflows/:

NPM Package Release (.github/workflows/npm-publish.yml):
- Triggered on push to the main branch.
- Inspects package.json. If the version field has been incremented (e.g., 1.3.8 -> 1.4.0), the workflow runs tests, builds the distribution, and automatically publishes the new package version to NPM.
- How to release: Bump the "version" field in package.json, commit, and push to main.
Interactive Demo Site Deployment (.github/workflows/deploy-site.yml):
- Triggered on push to main when changes touch src/** or site/**.
- Automatically builds the web application in site/ and deploys the latest version to GitHub Pages (gh-pages branch).

{ "ocm": "1", "id": "jonasyr-german-logic-puzzle-generator-german-logic-puzzl-21ea63", "kind": "skill", "name": "-german-logic-puzzle-generator", "description": "Welcome to the **Logic Puzzle Generator** repository! This document contains essential instructions and context for AI coding agents operating on this codebase.", "publisher": "jonasyr", "version": "1.0.0", "capabilities": { "domains": [ "general" ], "tags": [ "skill-md", "github-agents" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "Welcome to the **Logic Puzzle Generator** repository! This document contains essential instructions and context for AI coding agents operating on this codebase." ], "primary": false, "metadata": { "source": { "provider": "github-agents", "repository": "https://github.com/jonasyr/-german-logic-puzzle-generator", "path": "AGENTS.md", "ref": "b03a226f1810ba7229583dc486751937eafc16aa", "url": "https://github.com/jonasyr/-german-logic-puzzle-generator/blob/b03a226f1810ba7229583dc486751937eafc16aa/AGENTS.md", "key": "jonasyr/-german-logic-puzzle-generator/AGENTS.md" } }, "instructions": "# AI Coding Agent Guide\n\nWelcome to the **Logic Puzzle Generator** repository! This document contains essential instructions and context for AI coding agents operating on this codebase.\n\n---\n\n## 1. Core Documentation & Terms of Use\n\n- **Primary Source of Truth**: Always read [`README.md`](./README.md) before designing, modifying, or extending features. It documents the complete public API surface, core concepts (Nominal vs. Ordinal categories, clue types, proof chains, red herrings, difficulty estimation), and architectural guidelines.\n- **AI Disclosure & Liability**: Refer to the *AI Disclosu", "cost": { "context_tokens": 1157 } }

-german-logic-puzzle-generator

About

AI Coding Agent Guide

1. Core Documentation & Terms of Use

2. Codebase Architecture

3. Engineering & Quality Standards

4. Release & Deployment Workflows

Use it

Manifest

Reviews