Construct a playable themed crossword

Implementation guide · untested

Source-supported actions are attributed evidence. Proposed steps, prompts, synthetic examples and checks are original editorial guidance; the workflow has not been run.

Why this agent / simpler alternative

Agent contribution

An agent can turn an audience brief into candidate answers and varied clues, keep the clue inventory aligned with a generated grid, and explain rejected theme choices. The useful judgment is editorial: familiar vocabulary, fair definitions and consistent difficulty.

Simpler alternative

For a one-off classroom puzzle with a fixed word list, use a conventional crossword maker and write the clues yourself. If only a word-matching exercise is needed, a worksheet avoids interactive-player setup.

Unsuitable when

The puzzle is an assessment whose answer key must remain secret, the audience needs unsupported scripts or languages, or nobody can judge clue accuracy and appropriateness.

Source-supported scope

The repository describes grid construction, clue writing and JSON/player assembly. It supplies a recipe, not independent solvability or audience-quality measurements.

Setup — required, optional and unknown

Required

1. An operator-approved isolated output folder and a reviewed copy of the repository; installation and execution need separate authorization.

2. An editor who can judge audience vocabulary, clue fairness and release rights.

3. A way to inspect JSON and preview a local HTML artifact without publishing it.

Optional

1. A small answer whitelist and a forbidden-terms list for the intended audience.

2. A second person for a blind solve and an accessibility check.

Unknown

1. Supported host/runtime versions and current installation behavior have not been tested.

2. French or bilingual fill quality, classroom accessibility and target-device behavior are unverified.

Inputs and access

1. Name

   Puzzle brief

   Format

   Text: theme, audience, size, difficulty, spelling convention and destination

   Source or owner

   Commissioning editor or educator

   Access scope

   Only the supplied brief

   Permission needed

   Owner authorizes use of the theme and any private event details.

2. Name

   Candidate answer ledger

   Format

   CSV: answer_id, display_form, normalized_form, letter_count, reason, evidence_url

   Source or owner

   Editor-supplied terms plus proposed original candidates

   Access scope

   Approved vocabulary and public fact references

   Permission needed

   Confirm use of restricted names or curriculum material.

3. Name

   Release constraints

   Format

   Text: excluded topics, licence notices, answer-key visibility and distribution audience

   Source or owner

   Publisher or educator

   Access scope

   This puzzle only

   Permission needed

   Publishing is a separate decision after review.

Documented source actions

1. 1

   Choose answers and call build_grid.py.

   Input: Theme, size; Python and repository skill

   Output: solution.json and numbered entries

   Checkpoint: Inspect weakest fill.

   Source: Workflow, steps 1–3 ↗

2. 2

   Write clues.json.

   Input: Entries

   Output: Across/Down clues

   Checkpoint: One clue per entry.

   Source: Workflow, step 4 ↗

3. 3

   Run assemble.py.

   Input: Solution and clues

   Output: crossword.json; index.html

   Checkpoint: Assembly checks clues and grid agreement; independent check unknown.

   Source: Workflow, step 5 ↗

Proposed implementation steps — unexecuted

1. 1

   Create brief.json with audience, allowed topics, spelling policy, title and a new output location. Decide whether the deliverable is private practice or intended for public distribution. Record unresolved constraints before selecting words.

   Input: Puzzle brief and release constraints

   Output: Approved editorial brief and unresolved-questions list

   Checkpoint: The owner can identify the intended solver and permitted distribution audience; do not build around private details without permission.

2. 2

   Create at least two possible theme sets. Normalize spaces and punctuation in a separate column, count letters, and keep the readable form beside it. Mark every name or factual term with a supplied reference. Present a preferred set and a fallback that relaxes theme density.

   Input: Brief and candidate answer ledger

   Output: Theme-set comparison with normalized lengths and fallback choice

   Checkpoint: Every answer meets the intended spelling policy; unsupported trivia is removed or flagged for editor verification.

3. 3

   For a later authorized local trial, record the source revision, requested parameters and a run identifier before construction. Retain the constructor output as an intermediate artifact rather than immediately overwriting it on another attempt. Compare the returned answer inventory with the theme ledger.

   Input: Chosen theme set and reviewed repository

   Output: Candidate grid, run record and theme-inclusion check

   Checkpoint: An actual returned grid is required before proceeding; a plausible-looking text drawing is insufficient. Stop at the approved compute limit.

4. 4

   Maintain a clue review sheet keyed by direction and number. For each clue, record the intended answer, factual support when needed, possible alternative answers and editorial review state. Read the clues without viewing the answers, then inspect crossings to resolve avoidable ambiguity.

   Input: Candidate entries and audience brief

   Output: Clue inventory and ambiguity queue

   Checkpoint: No unreviewed factual clues; no answer accidentally disclosed by another clue unless deliberately approved as a puzzle device.

5. 5

   Prepare the package in the isolated folder. Perform an independent cross-check of cell coordinates, numbering, crossing letters and answer lengths. Open the candidate player locally, enter a partial solution, reload and test navigation with the intended input method.

   Input: Reviewed clues and candidate grid

   Output: Candidate package and structural/player checklist

   Checkpoint: Every clue points to the intended cells, no clipped clue text, and the reviewer distinguishes structural validity from an enjoyable puzzle.

6. 6

   Give a second reviewer a blind-solve copy. Record confusing clues and unwanted terms, revise only those items, and repeat the affected checks. Deliver a release checklist and files to the owner; retain publishing as a separately approved action.

   Input: Candidate package, checklist and licence notices

   Output: Reviewed local puzzle package, change log and release decision

   Checkpoint: Owner accepts clue quality and disclosure of the answer key; unresolved critical issues block public release.

Original starter prompt — proposed

Origin

editorial_proposal

Text

Prepare a draft crossword plan for {audience} on {theme}, using {size} and {difficulty}. Work only from {approved_terms} and {brief}. First return two theme sets with normalized letter counts, a clue-review schema and a local build/check plan for {output_folder}. Flag factual uncertainty and excluded terms. Before any installation or script execution, show the proposed commands and scope for approval. Do not publish or distribute anything. After an authorized build, distinguish structural checks from editorial taste and provide all unresolved issues.

Placeholders

1. audience

2. theme

3. size

4. difficulty

5. approved_terms

6. brief

7. output_folder

Limitations

Original planning prompt; it does not establish that any theme can be filled or grant execution/publication permission.

Synthetic worked example — not an agent run

Status

synthetic

Label

Invented clue-review fragment, not a generated grid or successful playtest

Content

Theme

Coffee break

Audience

Adult beginners

Review rows

1. Entry id

   candidate_A

   Answer

   LATTE

   Letter count

   5

   Draft clue

   Espresso drink with steamed milk

   Placement

   not assigned

   Review state

   editor review pending

2. Entry id

   candidate_B

   Answer

   MOCHA

   Letter count

   5

   Draft clue

   Coffee drink with chocolate

   Placement

   not assigned

   Review state

   editor review pending

Grid status

not constructed

Release status

blocked pending build and review

Artifact url

Not specified.

Costs and effort — unmeasured

Verified prices

Setup work

1. Review the skill and licence notices; establish a safe output location and a human clue reviewer.

2. Prepare the audience brief and reusable clue-review sheet.

Recurring work

1. Evaluate theme sets, inspect unusual fill, review facts, perform a blind solve and check the final package.

Unknowns

1. Model charges, construction retries and human editing time have not been measured.

2. A conventional puzzle tool may require less setup for occasional use; no savings claim is established.

Failure modes

1. Signal

   Theme entries are missing, altered or incompatible with the returned grid.

   Consequence

   A nominally themed puzzle no longer satisfies the brief.

2. Signal

   Several clues have multiple equally plausible answers or require obscure vocabulary.

   Consequence

   Structural correctness conceals a frustrating or unfair solving experience.

3. Signal

   The player opens but clue selection, reload or keyboard navigation fails.

   Consequence

   The files are present without being usable by the intended audience.

4. Signal

   A public assessment package exposes its solution.

   Consequence

   The activity cannot provide answer secrecy.

Recovery steps

1. Trigger

   Construction produces no acceptable candidate within the approved limit.

   Action

   Retain the failure record and propose the lower-density theme set; ask the editor to accept any changed brief before another trial.

   Stop condition

   No authorized alternative or compute allowance remains.

2. Trigger

   A clue fails editorial or blind-solve review.

   Action

   Revise that clue in the review sheet, recheck its answer and affected crossings, and repeat the targeted solve.

   Stop condition

   The fact cannot be verified or the clue cannot be made fair without changing the approved theme.

3. Trigger

   Player checks fail.

   Action

   Keep the reviewed data and issue log; offer a static review copy while diagnosing the local packaging path.

   Stop condition

   Do not label the result playable until the intended-device checks pass.

Source-observed and proposed approval boundaries

Source observed

User approval behavior is unspecified.

Editorial recommendations

1. Approve any third-party code installation or execution before trying it.

2. Approve the actual release files, licence notices and public audience after clue review.

3. Use loopback-only preview if a local server is later authorized; do not expose the directory publicly.

Unexecuted validation plan

Fixture

Unexecuted proposal: one 7-by-7 coffee-themed brief, a short approved vocabulary ledger, one deliberately ambiguous clue and one deliberately missing clue in a disposable candidate copy.

Acceptance checks

1. Theme terms and letter counts match the approved ledger.

2. All crossing letters, numbering and clue references agree; missing-clue fixture is detected.

3. An independent solver can navigate, enter letters and reload on the intended device.

4. Ambiguity is logged rather than silently declared correct.

5. No original files are overwritten and no publishing occurs.

Stop conditions

1. No valid candidate within the approved run budget.

2. Unresolved rights, harmful audience content or an answer-secrecy requirement.

3. Failed player checks or any mismatch between answer inventory and final grid.

Executed

No

Limits

1. No workflow, installation, player preview or blind solve was performed for this guide.

2. The source documents embedded solutions; secrecy needs a different delivery design.

3. Source publication date remains unknown. Generic agent capabilities do not establish compatibility.

4. Canadian spelling choices are editorial inputs; French-language construction is unverified.

Guide source links

https://github.com/tallmaro/crossword-creator ↗
documented_steps; approval_boundaries.source_observed

https://github.com/tallmaro/crossword-creator/blob/main/skills/crossword-creator/SKILL.md ↗
documented_steps; approval_boundaries.source_observed