AGENT SKILL

bulletin

Prepare, render, verify, and approval-finalize a weekly worship bulletin in a church folder. Use when the user asks to build or prepare a bulletin, save weekly clergy assignments, change bulletin preferences, inspect bulletin history, or finalize a reviewed bulletin.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 0
Forks
0

01 前言 Front Matter

name
bulletin
description
Prepare, render, verify, and approval-finalize a weekly worship bulletin in a church folder. Use when the user asks to build or prepare a bulletin, save weekly clergy assignments, change bulletin preferences, inspect bulletin history, or finalize a reviewed bulletin.

02 资源文件 83

03 SKILL.md 正文

Weekly Bulletin

Work inside the church's private folder. For a Handbuilt production run, use this skill's production interface instead of calling renderer scripts directly. The pastor may choose a local skill, custom editing, or another tool, including after starting this workflow. Follow that request without requiring plugin approval. Read Workspace customization for edits beyond supported settings and handling existing reviewed files.

Read Worship text and source records when a private or locally formatted prayer or reading text is needed. Read Source import and inventory when this week's input draws on a bulletin imported during onboarding; check validate_for_production before relying on that import. Read Service design and scoped bulletin decisions when resuming saved service work, adding a recurring service, changing a reusable part, or reviewing a scope or layout question.

The public production interface has four operations: orient, produce, revise, and finalize.

Before changing church-local CLAUDE.md or AGENTS.md, and when asked to recover their earlier text, follow Instruction recovery. Plugin updates preserve these files; never replace them with a newer scaffold.

0. Confirm the bulletin runtime

Before interviewing the pastor or staging a bulletin, run the app-loaded adapter once to select and verify the workflow:

"<app-loaded-plugin-root>/bin/handbuilt-python" "<app-loaded-plugin-root>/tools/church_workflow.py" \
  --church-folder "<church-folder>" start bulletin

The launcher renders and checks a temporary sample PDF. If it does not report ready, stop before production and follow the reported repair detail in handbook/runtime-setup.md. Use setup for missing managed packages; repair native tools or rendering libraries when those failed. Repeat start bulletin after repair. Do not ask the pastor to manage packages or use global Python. Passing this computer check does not replace the actual bulletin's checks.

Read the exact skill path returned by start. Use the returned launcher prefix, including its selected plugin root and managed Python, for every orient, produce, revise, and finalize operation in this task. Run start once per task and do not repeat it after reading the returned skill. For a supporting script with no adapter operation, use the returned runtime_python and returned skill path, never an app-cache path. The normal church-folder/handbuilt.py start bulletin command remains valid for a person checking the connection manually. If the connection is missing, repair it through onboarding. A missing connection does not prevent the pastor from choosing another tool.

1. Orient

Run the operation with the exact prefix returned by start:

<launcher-prefix> bulletin orient --date <YYYY-MM-DD>

Use the result to propose defaults from approved bulletin history and available music assets. History means an item appeared in an approved bulletin. Do not claim it was sung, read, or announced during the service.

Verify the lectionary day and selected citations against a published calendar. Record each reading source with label, location, and verified_on.

1a. Guide ongoing service design

When the request concerns a saved service or reusable worship practice, follow the service-design reference before resolving weekly input. Inspect the installed workflow's returned capabilities and state, including any selected service.service_id, service.occurrence_id, and catalog data it actually supports. Use --service-id <id> with orient for a named service and --occurrence-id <id> when that service happens twice on one date. Recover the saved service, usual parts, pending dated work, and unresolved decisions before asking the pastor to repeat an answer.

Recommend the closest existing service or reusable part first. Keep the requested edit at the scope the pastor named: this occurrence, the recurring service, or church defaults. If the request is ambiguous, ask one scope question before a shared write. Read the saved state back after an authorized change and state what future services inherit. Use the scoped settings commands in the service-design reference for recurring changes; keep dated exceptions in the bulletin input.

During review, connect wording and layout recommendations to participation, including finding a response, following a direction, reading music, and handling page turns. Use the rendered proof and source comparison. A passing render does not establish readable music or complete content.

2. Resolve the service

Recover the service date, standing settings, known people, and existing weekly material before asking for more. Use the saved layout without reopening that choice unless the pastor requests a change. Present a short summary that the returning pastor can correct.

An incomplete partial draft is not proof that a weekly choice is unknown. Inspect existing packages for the same date, service, and occurrence before asking again. Describe which dated choices you recovered and let the pastor correct them. Do not silently carry another week's assignments, music, or announcements into a new date.

The agent retrieves the appointed readings, collect, and proper preface from verified sources using the saved lectionary and worship practice. The pastor supplies local decisions such as music, announcements, petitions, special service changes, and unresolved assignments. Ask at most three focused questions at a time, preferably one. Explain what the next answer enables. Do not hand the pastor a checklist of liturgical texts to gather when the agent can verify and retrieve them.

If the pastor asks only to prepare assignments or pauses before production, save the dated work and stop at that boundary. Explain the sourcing you will do when work resumes, then ask only for the next missing local decision. For example: "I have the clergy assignments. When we build the bulletin, I will verify the readings and prayers. Do you have this week's music selections?"

Before resolving the weekly input, read the worship_profile path in church.yaml (normally worship/profile.yaml). Present its standing worship choices, their source or tradition pack, and any unresolved values. Resolve the profile through the worship-resolution module before constructing the weekly bulletin input:

<runtime.python> <skill-dir>/scripts/worship_resolution.py \
  --church-folder <church-folder> --weekly-input <weekly-overrides.json>

Its result supplies context for review; human approval remains a separate step. If the result is needs_input, inspect the listed reasons. Retrieve and check missing public worship text when a reliable source is available, then save its private source copy and provenance. Ask the pastor for unresolved choices, conflicts, or local and licensed material that the agent cannot obtain. Rerun resolution before producing. Use a recurring service's saved default_variant when present. Otherwise, the weekly caller supplies service.variant as the configured variant id when a profile declares service variants. Carry forward an already confirmed choice without asking again. Read back its exact name and confirmation policy, then resolve the private order file. An unknown, unsafe, missing, cyclic, or service-plan-mismatched variant is needs_input with an actionable reason. Never infer a variant from a date, denomination, history, or renderer default.

For an ordinary service, the caller must supply service.variant: none when variants are configured. The resolved object records that explicit choice at liturgy.service_variant; selected variants also record their private order file chain and confirmation policy at liturgy.service_variant_provenance.

Use the bundled Sunday library before fetching standard worship text. Standard BCP selections need no private source path or pastor-supplied URL. Read only the chosen collect, preface, or psalm entry. A private override still requires its own verification. For Lutheran licensed material, help prepare a reusable private source from the church's permitted material rather than asking the pastor to build technical files.

Resolve weekly liturgy fields explicitly. Never infer a Eucharistic Prayer, Lord's Prayer form, Prayers of the People form, or local communion welcome from denomination or history. Labs supplies general-blessing as the standing fallback. A church may select a private named blessing in its worship profile or for one week. Other missing required choices block production until resolved.

Standing worship preferences are saved in worship/profile.yaml. The profile supports traditional, custom, or omitted doxology; a confirmed psalm format and response starting side; continuous or repeated prayer labels; and concise or source rubrics. A blank psalm format remains unresolved until the church chooses one. A custom doxology uses the private sources.doxology text path. The optional standing church.yaml.bulletin.doxology_music entry uses the same fields as a hymn block. Copy it to service_music.doxology only when a weekly input omits that slot. A weekly service_music.doxology: null means there is no doxology music that week.

Complete lyrics are private church content. Labs does not determine whether a church may print material it supplies and does not require a permission record. Derive lyric_columns from text length and proof results; it is a layout proof value that the agent determines during visual review. Copyrighted lyrics must never enter the public Labs repository or its fixtures.

The weekly bulletin workflow stages church.yaml.bulletin.footer into the companion brand.bulletin_footer. It consumes church.yaml.leadership and carries church.yaml.bulletin.include_serving_today and church.yaml.bulletin.serving_roles into options, where the role list filters the Serving Today section. It renders private lyrics supplied by the church without applying a Labs permission policy. The public repository contains synthetic lyric fixtures only.

Keep the distinction between standing setup and this week's service explicit. The church profile may supply the reusable service book, prayer forms, roster, footer, recurring role slots, and selected bulletin template. The weekly input supplies the date, readings, hymns, preacher, celebrant, petitions, announcements, and Serving Today assignments. Resolve a person from the maintained leadership.clergy_and_staff roster only on one exact case-insensitive role match, with a first-name shortcut only when it is unique after printed titles are removed. Ambiguous or missing matches need a pastor's choice. Never save a weekly assignment into the standing roster.

merge_back_page is a weekly approval question, never an inferred default. When a merge is proposed, the result and receipt must show a mandatory visual-review warning and the signature pages, sides, sheets, and blanks. The pastor must explicitly approve that week's merge before finalization.

Read Weekly input and its linked field schema before preparing the production JSON. Use those contracts rather than reading the Python implementation to discover ordinary input fields. The input adds:

  • top-level template: classic or modern
  • a source record on each reading
  • music image paths relative to the church folder or its music/ directory
  • resolved liturgy values, including the worship profile reference and any local licensed liturgy sources

Never type a reading, a psalm, the collect, or the preface into the file, a command, or a message. Name each one and let the tool copy the words from their source, as Weekly input describes. Retyped scripture can be stopped by the AI app's safeguards in the middle of the pastor's bulletin, and it risks a changed word.

Missing music scans are allowed as a labeled title-only fallback. Unverified readings and unresolved example text block production.

3. Produce a review package

Include the church's provided logo on both Classic and Modern front pages. Read brand.json and use the existing local mark or banner. If onboarding recorded only a logo URL, the agent retrieves the confirmed image, saves it under the church's private brand/ folder, and replaces the rendering path in logo.mark or logo.banner with that local path. Keep source provenance in the church's onboarding notes. Do not ask the pastor to supply the same logo again when it can be recovered. A missing or unreadable configured logo blocks production until repaired; a church with no provided logo may use its name alone. During visual review, check the logo on the sequential PDF's first page and on the corresponding outer booklet cover, including legibility and proportions.

Save the resolved input to a temporary JSON file, then run:

<launcher-prefix> bulletin produce --input <resolved-bulletin.json>

Production renders the selected template, creates the 11x17 booklet, runs the automated quality gate, stores artifacts in the dated week folder, and writes a production receipt. A successful result is ready_for_review, not approved or print-ready.

For a supplied-bulletin reproduction, compare each source section with the rendered output before closeout. Check supplied prayer paragraphs and local petitions, music titles, lyrics, notation, credits, and recurring information. A field saved in JSON is not evidence that it printed. Inspect the PDFs and their extracted text. Recover an available supplied image before accepting a missing-image fallback. Explain any unsupported content and obtain the pastor's choice before deliberately omitting it; a receipt does not establish content completeness. Broad layout changes do not authorize removing words.

Production also runs the booklet print gate before imposition. The print mode comes from options.print_mode (booklet, duplex, or single; booklet when unset), and options.allow_blank_inside_cover says whether page 2 may be left blank on purpose. Both may be saved once as standing preferences under bulletin in church.yaml; a weekly option overrides them. In booklet mode the page-by-page PDF must already be a multiple of 4 pages, with no padding blank and the back page last. No hymn or prayer may continue across a page turn, and the opening hymn prints whole. No line of a text said together (the Creed, the Lord's Prayer, a confession) may wrap, and no heading may sit at the foot of a page with its text overleaf. A missing font or picture blocks in every print mode. When a rule fails, production fits the bulletin with small, bounded changes: a blank inside cover, looser line spacing, slightly larger type, music at 95% to 100%, or one section starting a new page. It never changes wording or order. Larger type is kept only when no said line wraps: a said text that would wrap stays at the theme's size, and one that still wraps prints its speaker label above the text. A piece of music split over two pages moves onto one page when it fits at the church's smallest music scale or larger.

Two standing settings under bulletin in church.yaml bound fitting: body_size (for example 12pt; fitting never sets body type above it, and 13pt is the ceiling when unset) and music_min_scale (for example 0.85; the smallest a piece of music may print to stay on one page, 95% when unset). orient returns them as print_settings, and the receipt records them.

Show the pastor the sequential PDF and booklet PDF, and explain any warnings. Keep the receipt for your own later steps; a pastor never needs to open it. Before asking for approval, state these in plain words:

  • fit_summary, when it is not empty. It names every layout adjustment, for example "To fold into 16 pages, page 2 is left blank and line spacing is a little looser." The receipt lists the same steps in fit_adjustments.
  • Each page_fill_warning: which pages are only partly full. These are allowed but are worth a look.
  • Each entry in open_items: bracketed text that will print and looks like a blank nobody filled in, such as [Name of the person to remember]. Its field, when present, says where the words live. Ask the pastor to supply the wording, then revise. If the brackets belong there, the pastor can say so; see step 5. Verse numbers, markings such as [Alleluia], and optional words in the shipped liturgy are not open items.

When production returns blocked with booklet_fit_failed, tell the pastor the error's one sentence. The bulletin needs a change the pastor chooses, such as fewer words, a different hymn, or a shorter announcement. Do not hand-edit the rendered HTML, force page breaks, or add blank pages to reach a page count; a re-render erases hand edits, and blanks print in the wrong place.

Human review is required before finalization. Printing or sending requires separate explicit authorization.

4. Revise a review package

If review requests a change, keep the prior package explicit and revise it with the fourth public operation:

<launcher-prefix> bulletin revise \
  --prior-run <prior-bulletin-production-receipt.json> \
  --input <revision-input.json>

The prior receipt must be an exact path to an unapproved ready_for_review package. The revision input may contain only the changed fields. The workflow deep-merges it with the prior source-safe config, then renders a temporary staged config. The saved bulletin-config.json retains church-relative music and private liturgy source paths for the next revision.

A pastor naming a heading means the large line printed at the top of that part, not the small label beside it. To reword the psalm's heading, revise readings.psalm.heading.

The replacement is rendered and verified before the files the prior run made move to a recoverable .revisions/ folder. Files the church or agent added to the week folder (a README, a photo, a script) stay where they are; the result and receipt list them as preserved_files. A church file that sits exactly where the new package writes is archived too and named in a warning. The new receipt links the predecessor run, receipt hash, archive location, and source-config digest. Repeating the same revision is idempotent. An ordinary revision can never change an approved package or an approved history entry; step 6 covers an error found after approval.

Legacy version 1 receipts are read without modification. Staged music is recovered only when exactly one matching private source can be verified. A missing or ambiguous source blocks revision and requires fresh source paths.

5. Finalize only after approval

Create approval JSON containing production_run_id, approved_by, and the reviewed artifact hashes from the production receipt. An optional note and approved_at may be included. If the receipt lists open_items, finalization is refused until each one is filled in by a revision or the pastor confirms it should print as written. Record that confirmation by listing each item's exact text in confirmed_open_items. Never add it without asking the pastor. Then run:

<launcher-prefix> bulletin finalize \
  --receipt <bulletin-production-receipt.json> --approval <approval.json>

Finalization verifies that reviewed artifacts have not changed, writes the approval receipt, and updates approved bulletin history. If review requests a change, revise through a new production run rather than finalizing the old one.

6. Correct an error found after approval

When a pastor finds a mistake in an approved bulletin, make a correction. Use this only when the pastor has asked to change the approved bulletin:

<launcher-prefix> bulletin revise --correct-approved \
  --prior-run <approved-bulletin-production-receipt.json> \
  --input <changed-fields.json>

Tell the pastor what happens, in these words:

  • The approved bulletin is kept exactly as it was, with its approval, under .revisions/ beside the week's folder. The result's corrects_approved gives its location.
  • The week's folder now holds a corrected bulletin to review. It is not final yet. Until it is approved, approved history still names the earlier bulletin.
  • Review the corrected bulletin, then finalize it as in step 5. Further changes before approval use an ordinary revision of the corrected bulletin.
  • The pastor decides whether to reprint or resend. Copies already handed out do not change.

Without --correct-approved, a revision of an approved bulletin is refused.

Boundaries

  • Private church data and licensed music stay in the church folder.
  • Only approved receipts update history.
  • Keep local template adaptations in the church folder; installed plugin edits may be lost on update. The stock renderer does not automatically load local templates. Use the selected local workflow to apply and verify them.
  • Do not call a generated package print-ready before human approval.

The separate doxology setting applies to the Episcopal service plan. In the Lutheran service plan, keep any doxology within the church's verified local order or Great Thanksgiving text so it is not printed twice.

04 同仓库更多 Skills

stephenfsetzer
stephenfsetzer/handbuilt-church-labs

sermon-video

Prepare a sermon video, parish thumbnail, captions, and playable review page from a full service on YouTube, Vimeo, another public embedded player, or a local recording. Use for clipping and preparing recorded sermons, not writing sermons.

★ 0
stephenfsetzer
stephenfsetzer/handbuilt-church-labs

sermon-research

Run or resume the portable sermon research workflow from passage selection through verified readings and a cited research brief. Use when a pastor asks for sermon research or when a weekly sermon research automation invokes the workflow.

★ 0
stephenfsetzer
stephenfsetzer/handbuilt-church-labs

sermon-reflection

Help a pastor turn sermon research into their own sermon. Draws out the pastor's thinking one question at a time, opens a page for them to write or speak their reflections for as long as they need, then lightly edits their writing into a sermon that still sounds like them, with an optional large-type speaker's copy. Use when a pastor finishes research and says they are ready to reflect, wants to start writing, asks for help with their sermon draft, or asks for a speaker's copy.

★ 0
stephenfsetzer
stephenfsetzer/handbuilt-church-labs

onboarding

Set up my Church Command Center: create or resume a private church folder through website discovery and worship setup. Use when a pastor asks to set up their Church Command Center or church workspace, get started, run onboarding, check saved setup, or update standing church preferences.

★ 0
stephenfsetzer
stephenfsetzer/handbuilt-church-labs

finance-report

Build the monthly finance report for the vestry or church council, a two-page PDF in the church's brand, from QuickBooks. Use when a pastor or treasurer asks to build or run the finance report, the vestry or council finance report, or this month's board finance packet. Read-only in QuickBooks. Finance onboarding comes first for a church that has not finished it.

★ 0
stephenfsetzer
stephenfsetzer/handbuilt-church-labs

finance-onboarding

Set up a church's finances for board reporting, in four stages that end with the monthly finance report locked in. Use when a pastor or treasurer asks to set up the church's finances, look at the books, get ready for a vestry or council finance report, or check where finance setup stands. Read-only in QuickBooks and every other finance system.

★ 0