ArdenZC/codex-work-skills

Lesson Plan Generator Skill 2.2.1

This is the sole complete behavior specification for this Skill. Other agent entry points should only read this file and general-prompt.md, do not duplicate another set of fields or generation rules. Currently supports Windows and macOS. The model is responsible for understanding the materials and producing the complete Content 2.2 JSON; Python is only used for deterministic validation, formatting, and template mapping, and cannot replace the model's creative writing. 2.2.1 is a revision of the Lesson / WorkOrder delivery contract; it does not modify the Word template, content quality algorithms, or WorkOrder scoring contract.

Task Entry and Intake Runtime 2.1.1

At the start of a task, first read the current session, uploaded files, and available course materials: competency map, chapter task breakdown, curriculum standards, textbook table of contents, existing lesson plans, and the user-specified Word template. Before formal planning, you must enter INTAKE_PENDING, organizing your current understanding into a single, centralized confirmation of course basic information in Chinese; even if the information has been inferred from the session or attachments, you must display it and request user confirmation once. After confirmation, enter INTAKE_CONFIRMED and proceed directly to material retrieval, course-level outline, Content 2.2, QA, and DOCX.

The user interface should only use Chinese labels; do not expose internal field names as questions. The essential course basics to be confirmed in one go are: course name, major, target audience, total hours. The confirmation summary must also include the following non-blocking information: theory hours, practice hours, theory-practice organization method, default single lesson hours (2 hours), textbook used, auxiliary reference materials, and whether to generate practical task work orders simultaneously.

When information is missing for the four core fields, display "To be supplemented" in the same confirmation summary; total hours can only accept facts explicitly provided by the user. If the major or target audience is only inferred by the Agent, it must be marked with "Current understanding / Please modify if incorrect." When theory/practice breakdown, organization method, or practical task work order preference is not explicitly provided, it must display "To be confirmed" and cannot be automatically completed with 50/50, integrated, or "No." default_hours=2 can only be used to estimate the number of sessions based on 2 hours per session; it cannot be used to infer the theory/practice ratio. For internal field mapping and state rules, see docs/intake-contract-v2.1.1.json; the user interface only displays "Auxiliary reference materials," while the internal state still uses auxiliary_references; do not use that English key as a user question.

The first response should look like:

Let me first confirm the basic course information:
- Course Name: "Advanced Data Structures"
- Major: Current understanding / Please modify if incorrect
- Target Audience: Current understanding / Please modify if incorrect
- Total Hours: 40
- Theory Hours: To be confirmed
- Practice Hours: To be confirmed
- Theory-Practice Organization Method: To be confirmed (Options: All Theory / All Practice / Segmented Integration / Mixed)
- Single Lesson Hours: Default 2 hours
- Textbook Used: Not specified (If you have a designated textbook, please let me know; we can proceed without one)
- Auxiliary Reference Materials: Not specified
- Generate Practical Task Work Orders: To be confirmed
Is the above information correct? If any adjustments are needed, please tell me all at once.

The textbook is recommended, not required: if a file or book title is provided, display it directly; if not provided, it cannot block generation. When practice_work_orders is not provided, keep it as "To be confirmed"; only after the user explicitly chooses will the decision be made whether to invoke the WorkOrder Skill. When explicitly set to false, practice hours are still included in the total course hours, but no Practice Task Contract, handoff, WorkOrder, or additional practice-side files are generated. When explicitly set to true, after completing the Lesson QA/DOCX and Practice Task Contract handoff, the Lesson Agent detects and invokes the available WorkOrder Skill. The WorkOrder Agent then creates the complete Content V1, executes QA, and generates the work order, delivering everything together. If the WorkOrder Skill is unavailable, only the Lesson and handoff are delivered, with a clear message stating: "The Practical Task Work Order Generator is currently unavailable. The practical task data file has been saved and can be used to continue generation when the generator becomes available." Do not fabricate a work order DOCX.

Before the intake is confirmed, do not determine the number or names of projects, the structure of theory/practice sessions, the number of practical tasks, content for each lesson, or generate a DOCX; unless the user has explicitly provided the relevant facts. After one confirmation, do not ask again about the outline, project names, tasks per lesson, scoring, templates, output directory, or "whether to start generating DOCX". Use the default template and default output rules directly. Only stop again if the user actively changes requirements, if there is a direct conflict in the confirmed information that cannot be reasonably resolved, or if a security/file overwrite issue requires user decision.

If the user explicitly chooses "All Theory," normalize to theory_hours=total_hours, practice_hours=0, delivery_mode=theory_only, and set practical task work orders to false. If the user explicitly chooses "All Practice," normalize to theory_hours=0, practice_hours=total_hours, delivery_mode=practice_only. Other breakdowns must satisfy theory_hours + practice_hours = total_hours; if not equal, report the conflict first and do not start the outline.

Material retrieval prioritizes textbooks/course materials provided by the user and user-specified textbooks. When internet access is available, search for official publisher or school pages, standards/guidelines, official technical documentation, and verifiable public literature. When only a book title is given, only write verified authors, publishers, ISBN, edition, or year. If the network is unavailable, proceed normally; do not interrupt generation because of a lack of internet.

• After the user allows reasonable inference, fill in projects, tasks, teaching content, evaluation, and pre-generated reflections according to project-based teaching.
• The final DOCX must not contain internal annotations such as "insufficient materials, inference, AI, QA, similarity, confidence."

Even without task materials, a course-level outline must be formed first, and then lesson-by-lesson content generated. The outline must include at least: lesson_id, unit, task, lesson_type, hours, theory_hours, practice_hours, prior_learning, capability_stage, deliverable, next_bridge, and practice_task_ids. Long courses can be generated internally in batches of 4 to 6 lessons, but the final unified QA must be done with the complete course context.

Content Contract V2.2

The default template is assets/templates/lesson-plan/v1.1.2/template.docx.

The default production input is content_contract_version: "2.2", which is independent of the Word template version; the runtime can also read "2.1" and "2.0". The default Word template is lesson-plan v1.1.2, and support is continued for v1.0 legacy-coordinate, v1.1.0/v1.1.1 semantic-bookmark, and legacy compatibility template paths; old sparse JSON is no longer produced.

Required course-level fields:

content_contract_version, course_name, major, audience,
default_hours, total_hours, delivery_plan, course_materials,
reference_pool, artifact_plan, outline, lessons

Each 2.2 theory lesson must directly provide:

lesson_id, unit, task, lesson_type, hours, theory_hours, practice_hours,
progression, reference_ids, practice_task_ids,
student_analysis, teaching_content, goals,
key_point, difficult_point, teaching_methods, resources,
implementation, evaluation, reflection

2.0 input still reads the references object within the lesson; 2.1 compatible input retains the original lesson semantics. 2.2 only selects sources through reference_ids from the course-level reference_pool, and each theory Lesson must have at least 1 reference. In 2.2, the Lesson DOCX only carries theory: sum(lesson.hours) == theory_hours, all Lessons have lesson_type=theory and practice_hours=0; practice is not included in the Lesson DOCX. Practical work enters the Practice Task Contract / WorkOrder handoff only when artifact_plan.practice_work_orders=true; when false, no contract or task IDs should be carried, and practice_task_ids should only retain the schema-required empty array. practice_task_ids indicates the practical tasks associated with the theory lesson, not that a practical Lesson DOCX should be generated. delivery_plan supports theory_only, practice_only, split_lessons, integrated_lessons, and hybrid, and must satisfy theory_hours + practice_hours == total_hours. integrated only describes artifact-level integrated theory-practice organization; it does not stuff practice hours into the Lesson DOCX, nor does it fix a 1+1 ratio.

default_hours is the default hours per lesson that the Agent uses when creating each lesson slot; an explicitly provided hours for a specific lesson can override it, and default_hours is not required to equal the sum of all lessons.hours. default_hours, total_hours, and each lesson's hours must be positive integers representing hours: numeric values can be 1, 2, 4, 12, etc.; strings can be "1", "2", "2.0". Blank strings, fractions, zero, negative numbers, NaN, or Infinity are not accepted. unit uses project-based names (e.g., "Project 1..."). progression includes prior_lesson_id, specific prior_learning, capability_stage, deliverable, and next_bridge. capability_stage can only use: Cognition, Understanding, Imitation, Independence, Integration, Optimization, Transfer; it does not need to be mechanically linear. The first lesson's prior_lesson_id must be null; subsequent lessons can only reference already-appearing prior lessons. For four or more lessons, not all capability stages can be identical.

student_analysis (base/problems/strategies), three types of goals, and teaching_content must each have at least two items; the key and difficult points each require content and strategy; teaching_methods must have at least two items, and resources at least two. In 2.2, theory Lessons' reference_ids cannot be empty; empty references cause immediate failure. A purely practical course may have no Lesson DOCX; only when the explicit choice is made to generate practical work orders must the practice hours be expressed via a Practice Task handoff. When the choice is to not generate, no handoff is created, and no theory lessons can be fabricated.

Each lesson's implementation must be provided completely and in fixed order for the following nine IDs, with label, minutes, modality, content, teacher_actions, student_actions, and objective all coming from JSON:

before_class_preparation
task_introduction
operation_demonstration
task_implementation
task_extension
project_practice
peer_review
lesson_summary
after_class_improvement

Before-class preparation and after-class improvement are extracurricular stages; the minutes of the seven middle stages must strictly equal hours * 45. Each extracurricular stage is allowed 0 minutes, but cannot exceed max(60, hours * 45), and the total of the two extracurricular stages cannot exceed 2 * hours * 45. Error messages must specify the lesson ID, stage, actual, and limit. operation_demonstration is a semantic slot; it can be displayed as method demonstration, case analysis, or skill demonstration in courses like nursing, accounting, or mechanics.

Evaluation must explicitly provide evaluation.score between 85 and 96, using 0.5 step increments, and provide canonical 13 criterion IDs with per-lesson remarks. Each remark must have substantial content. All Content V2 template versions uniformly enforce a contract upper limit of no more than 48 meaningful characters; the manifest can only tighten this further, and exceeding the limit must cause failure, not truncation. When no score is specified, it is recommended to naturally concentrate between 88 and 94, but not all be 90, any short-period cycle, strictly increasing or decreasing. score_breakdown() is only responsible for deterministically splitting the explicit total score into the existing table rows; Python does not create remarks, does not use three sets of fixed remark cycles, or mechanical score fallback. Reflection must explicitly provide summary, innovation, and improvement. Pre-reflection generation before class is allowed, but it must produce differences centered around this lesson's tasks, key/difficult points, organization, expected performance, problems, and linkage to the next lesson.

In 2.2, course_materials.textbook separately represents the textbook; it can be an object or null. It will not automatically be written into the Word references cell by default. Before generating lesson-by-lesson content, the Agent forms a course_reference_pool / reference_catalog planning concept. The persisted field is still reference_pool, not a new JSON contract field. Each entry must have reference_id, reference_type, an identifiable specific title, source_kind, source_region (domestic/foreign/unknown), and corresponding evidence. Lessons only write reference_ids. allow_textbook_as_reference defaults to false; only when explicitly set to true is the textbook allowed to enter the references. references only represents literature/documents that can be read, consulted, cited, or used as the basis for the course, including monographs, curriculum/teaching standards, national/industry/occupational standards, guidelines/specifications, papers, public literature, official technical documentation, official product manuals, and formal teaching documents provided by the user. resources represents tools, equipment, environments, and materials used during teaching implementation, such as MySQL Workbench, database servers, PPTs, projectors, nursing models, virtual machines, training task sheets, and case datasets; these cannot be written into references just to fill up the count. Each lesson typically selects 1–3 references; course-level valid references can be reused.

source_kind retains provided, generic, and verified_public; provided requires evidence from the user's actual materials; verified_public requires a URL or locatable official source; generic can only use specific document semantics and must not fabricate detailed bibliographic information. Vague placeholder text such as "Unified Modeling Language related public documents," "Related online resources," or "Related public literature" is prohibited, as is guessing authors, ISBNs, publishers, editions, years, or standard numbers. Domestic sources take priority: user-provided materials, domestic publications/monographs, resources from domestic universities, national/industry/occupational standards, and domestic authoritative documents are preferred over foreign classics. A domestic proportion below 70% is only a quality warning, not a hard fail; international standards/classics or insufficient domestic sources allow supplementing with foreign sources. Full repetition of references across lessons is allowed; this is reference_reusable, which explicitly exits the exact/item/sentence/field/structural/frequency/whole-course anti-repetition hard-fail. Duplicate IDs or duplicate content within the same lesson still trigger a hard-fail. Repetition of references is not a problem of lesson plan body repetition. Fabricating different textbooks, authors, ISBNs, publishers, standard numbers, or public literature to reduce the course repetition rate is prohibited. Repeating the same textbook 18 times is better than fabricating 18 different textbooks. Evidence is only used for input and QA; the DOCX only writes the formal citation text, not the evidence metadata.

Practice Task Contract V1

Only when artifact_plan.practice_work_orders=true, the 2.2 input must provide a practice_task_contract with version 1.0 and granularity: "per_task". Practice hours must be a positive even number. Task fields are: task_id, project_id, title, lesson_ids, practice_hours, scenario, objectives, required_inputs, tools_or_materials, steps, deliverables, acceptance_criteria, safety_or_compliance. Each Practice Task is fixed at 2 hours; the number of tasks is strictly equal to practice_hours / 2. Each task corresponds to one WorkOrder; project_id is only used for grouping and cannot be used to re-plan granularity. lesson_ids are the theory Lesson IDs that provide theoretical preparation/prerequisite knowledge, which can span multiple lessons; for purely practical courses with no theory Lesson, it is an empty array. When practice_work_orders=false, no contract or handoff is allowed, and all practice_task_ids must remain an empty array. When true, the Lesson is only responsible for generating and QA-ing the canonical handoff, which is then consumed by the detected WorkOrder Skill through Agent orchestration; the Lesson Python generator must not subprocess-call the WorkOrder Python, nor automatically map it into work order text. When the WorkOrder Skill is unavailable, only the practice-task-contract.json handoff is output, with a clear unavailable status; do not fabricate a practice work order DOCX.

The current 2.2 complete rules are in docs/content-contract-v2.md; examples/tasks-v21.example.json is retained as a 2.1 compatibility example, and examples/tasks.example.json is retained as a 2.0 compatibility example. Field descriptions are in docs/content-contract-v2.md and docs/practice-task-contract-v1.md; machine constraints are in schemas/lesson-plan-input.schema.json and the repository canonical schemas/shared/practice-task-contract.schema.json; schemas/practice-task-contract.schema.json is only a compatibility entry point.

Python and Agent Boundary

The Agent is responsible for course-level planning and all lesson-by-lesson teaching content. The generator only does schema validation, numbering, line breaks, minute formatting, field mapping, and template writing. The V2 formal path must not call the old generated_lesson_fields, implementation_cell_values, reflection_cell_values, must not use flows[:3], nor create content based on missing fields. If the content exceeds the manifest's max_chars or max_paragraphs, it must fail, pointing out the lesson, field, actual chars, and limit; no truncation or silent deletion is allowed.

Generation and QA Order

Read materials -> One-time confirmation of basic course information
  -> Course outline
  -> Content V2.2 JSON
  -> Input Contract QA
  -> Content Quality QA
  -> Template QA
  -> candidate DOCX generation
  -> Output Structure + Content-to-DOCX Fidelity QA
  -> optional LibreOffice render smoke
  -> atomic commit to final output and external QA report
  -> when practice_work_orders=true, detect and call WorkOrder Skill Agent, then unify Lesson + WorkOrder delivery
  -> Agent representative-page visual inspection

Use scripts/generate_lesson_plans.py to generate. All DOCXs are first written to a candidate directory that is a sibling of the final output directory; after Content QA, Template QA, output structure/bookmark/format protection, content fidelity QA, and the requested render smoke pass, they are swapped into the final output directory. When --qa-report is explicitly specified, the external report is first staged in its sibling directory and committed together with the output directory; if any swap fails, both the old output and old report are restored. A non-empty output directory requires --backup-existing; if the swap fails, the old directory must be restored. After a successful commit, stdout only reports the DOCX paths that actually exist in the output directory. No additional confirmation is requested for generating the DOCX after the course basic information is confirmed. The Agent's representative page visual inspection is an acceptance step after the commit; if overflow, truncation, abnormal pagination, or blank pages are found, the V2 content should be rewritten and regenerated transactionally using --backup-existing. qa-report.json only writes the report, not into the DOCX.

The standalone scripts/content_quality.py must run deterministically locally, without calling online APIs, embeddings, or model services. It checks for existing text repetition, structural similarity after entity masking, duplicate long sentences, old clichés, completeness, intra-lesson coherence, progression coherence, score patterns, density of 13 evaluation remarks, and non-IT contamination. This round only adds the 2.2 required references check, source-region statistics, and theory/practice handoff check; it does not change the existing repetition, progression, scoring, or implementation coherence algorithms. non_it_contamination and its scope metadata only detect IT default words injected into the output by the template or generator, not present in the input; it is not a general course classifier. Diagnostics only retain limited snippets and stable SHA-256 hashes, not output entire sections of user text. All detectors share a single reuse policy: narrative_strict, terminology_reusable, resource_reusable, reference_reusable, fixed_rubric_reusable, and ignore. Teaching methods, necessary resources, valid references, and fixed rubrics for attendance/compliance/habits can record reuse evidence but do not hard-fail. References allow full repetition across lessons and fully exit the exact/item/sentence/field/structural/frequency/whole-course anti-repetition hard-fail. Exact duplicate references within the same lesson and obvious pure tool/equipment references must hard-fail. Short-course terminology exemptions must not enter narrative fields. Do not fabricate references to reduce the course repetition rate.

For progression, both artifact inheritance and forward transition must be supported simultaneously by lexical/coherence evidence and substantive_anchor evidence. Generic actions like "design, operate, analyze, inspect, process, implement" cannot independently serve as anchors. Non-adjacent prior_lesson_id is still allowed. If the physical sequence chain is a review, the report must set requires_agent_review=true and list from/to/reason/score/declared_prior. The Agent's final acceptance cannot silently ignore the physical sequence review; if the actual teaching order cannot be explained, the progression must be rewritten.

After deterministic QA passes and the atomic commit is completed, the Agent must also review each lesson internally: what this lesson adds compared to the previous one, what knowledge or output from the previous lesson it uses, what it produces, and how the next lesson will use that output. This review is not written into the DOCX. When --render is requested, the Python report only indicates render.scope=smoke; the page count method is a lightweight pdf_page_object_regex. It is not equivalent to visual QA or pagination verification, nor does it prove the absence of overflow, truncation, abnormal pagination, or table deformation. The Agent should check the first lesson, the most content-dense lesson, and the last lesson; for courses reaching 12 hours, also check 1–2 middle lessons, focusing on clipping, overflow, overlap, blank pages, abnormal row height, and table boundaries. After the actual check, use scripts/record_visual_inspection.py to explicitly write a standalone visual-inspection.json file. This file records the representative pages, checks, notes, associated qa-report, output fingerprint, and timestamp. Python will not automatically claim visual pass. If visual inspection fails, modify the V2 JSON and regenerated transactionally with --backup-existing, then re-inspect.

The default output QA reads the original V2 JSON, calculates the expected via a pure formatter, and then compares against semantic bookmarks or v1.0 coordinates; it does not re-invoke content creation functions. Template layout, 70 semantic bookmarks, bookmark IDs/names, fingerprint, v1.0/v1.1 compatibility, and canonical binaries are all protected. If LibreOffice is present on the machine, use --render for a render smoke test; if no renderer is available, structural QA still passes, and the report marks render.status=not_executed. Conclusions about real pagination, overflow, and visual layout only come from the Agent's representative page check.

The adapter installation semantic is fixed as: the default is instruction-only adapter install, which only installs project rules and minimal instructions, without copying the full runtime, and does not commit the target project to being able to independently execute the generator. Only appending --copy-engine results in a full runnable project-local Lesson engine. When the target project needs to directly call .lesson-plan-docx-generator/scripts/generate_lesson_plans.py, --copy-engine must be used. visual-inspection.json is an Agent visual inspection attestation for the current generated DOCX/QA state, representing the Agent's representative page check of the current generated DOCX/QA state, not a cryptographic proof of the inspected PDF/image.

Path preflight is executed before mkdir, generation, move, backup, or delete, protecting the Skill root, input JSON, schemas, selected/custom template, manifest, canonical/compatibility package, scripts, and tests, and rejecting ancestor, descendant, resolved symlink, and Windows lexical/8.3 alias overlaps. Do not write output to a protected directory or custom template package.

Commands

Windows:

python scripts/generate_lesson_plans.py `
  --tasks-json tasks.json `
  --output-dir output `
  --render

macOS:

python3 scripts/generate_lesson_plans.py \
  --tasks-json tasks.json \
  --output-dir output \
  --render

Standalone validation output:

scripts/validate_template.py --json
scripts/validate_output.py --input-json tasks.json --output-dir output --render
scripts/validate_visual_inspection.py --output-dir output --qa-report output/qa-report.json --evidence output/visual-inspection.json

Manual installation and dependency check (the installer does not automatically modify the Python environment):

python scripts/install.py --skills-dir <skills-dir>
python <skills-dir>\lesson-plan-docx-generator\scripts\check_dependencies.py

check_dependencies.py is a read-only check for docx, yaml, jsonschema; if missing, it prompts pip install -r requirements.txt. The Agent production flow prohibits the use of --skip-template-validation or --skip-output-validation. These two compatibility parameters can only be used in controlled testing when LESSON_ALLOW_UNSAFE_VALIDATION_SKIP=1 is explicitly set, and must be clearly marked as skipped in the report. Input contracts, content quality, and path protection cannot be skipped. Temporary JSONs, PDFs, images, and candidate directories are cleaned up after the task ends; generated DOCXs are not committed.

Template Files

assets/templates/lesson-plan/v1.1.2/template.docx
assets/templates/lesson-plan/v1.1.2/manifest.yaml
assets/templates/lesson-plan/v1.1.1/template.docx
assets/templates/lesson-plan/v1.1.1/manifest.yaml
assets/templates/lesson-plan/v1.0.0/template.docx
assets/templates/lesson-plan/v1.0.0/manifest.yaml
schemas/lesson-plan-input.schema.json
scripts/content_contract.py
scripts/content_quality.py
scripts/generate_lesson_plans.py
scrip

…

[truncated for translation]