Update to Clara

{
  "description": "Use internally when Clara receives a new or materially reframed advisory assignment and must turn the natural request into a reviewable assignment contract and generation handoff. Use the public task label \"Plan an advisory assignment\" when naming it; this is not generic prompt polishing and is not a legal, tax, compliance, or jurisdiction workflow.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 285
    },
    {
      "relative_path": "references/advisory-contract.md",
      "size_in_bytes": 7017
    }
  ],
  "name": "advisory-brief-planner",
  "skill_md_contents": "---\nname: advisory-brief-planner\ndescription: Use internally when Clara receives a new or materially reframed advisory assignment and must turn the natural request into a reviewable assignment contract and generation handoff. Use the public task label \"Plan an advisory assignment\" when naming it; this is not generic prompt polishing and is not a legal, tax, compliance, or jurisdiction workflow.\n---\n\n<!-- CLARA_OPENAI_ONBOARDING_BEGIN -->\nOnboarding is optional. Continue ordinary professional work immediately,\nincluding direct specialist invocation, without checking or completing a local\nonboarding profile. Missing, unfinished, inaccessible or corrupt onboarding state,\nor unavailable voice/window controls, must never block ordinary work. Do not\nautomatically start, resume or repeatedly offer onboarding.\nOnly for a user-requested tutorial or a native teaching handoff, read\n`../clara/references/local-onboarding.md`. A verified paired lesson worker\nexecutes only its bound lesson and token; never bypass tutorial validation.\nTutorial profiles, progress, examples and feedback remain local; never send a\nchange request, stamp a tutorial receipt or call hosted interviews for a tutorial.\nCurrent user requests take precedence over saved preferences.\n<!-- CLARA_OPENAI_ONBOARDING_END -->\n\n## Output Location Rule\n\nNever write run outputs inside this Git workspace, `static/shared`,\n`protected_downloads`, or another published folder. Write them in the user's\nassignment or case folder, or in a sibling output folder chosen for the run.\n\n# Plan an advisory assignment\n\nThis workflow is Clara's internal planning stage for a new advisory assignment\nor a material change to an existing one. The user describes the work naturally.\nDo not ask whether to optimize a prompt and do not make the user select a skill.\n\nUse this workflow directly when the user asks to define, plan, scope, or hand\noff an advisory assignment. Use it internally before substantial advisory\ngeneration when the current request has no reviewed assignment contract. Do not\nrerun it for a narrow continuation whose existing contract is still current, or\nreplace a specialist workflow's own accepted intake contract merely to add\nceremony.\n\nThe planner owns only the assignment contract. After handoff, the selected\n`clara:*` workflow is the procedural authority. For a durable advisory case,\nhandoff normally goes to `clara:advisory-case-director`; bounded specialist\nevidence gates, validation, presentation review, and professional approval\nboundaries remain in force.\n\n## Meaning and mechanical boundary\n\nClara uses model-led judgement to understand the assignment and choose:\n\n- the decision, purpose, audience, and deliverable;\n- included and excluded scope;\n- the evidence and data plan;\n- assumptions and material unresolved questions;\n- the analytical approach and success criteria;\n- the existing Clara workflow that should execute the work;\n- validation, correction, and professional-judgement policies; and\n- the generation instructions handed to that workflow.\n\nDo not add or use a keyword classifier for assignment meaning, workflow\nselection, source strategy, scope, or analytical framing. Do not make any\nhidden model API call. Clara performs the semantic work in the active host\nmodel session.\n\nThe local helper is deterministic because schema validation, exact ID\nreferences, declared workflow availability, literal source anchors, declared\ndate and number values, hashes, and stable JSON packaging are mechanically\nverifiable. It inventories recognizable dates, numbers, URLs, and question\nsentences from supplied UTF-8 source text for observation only. The inventory\ndoes not decide which source details are material and is not a completeness\ngate. The helper never calls a model API and does not certify the contract's\nadvisory quality.\n\n## Required artifact\n\nThe canonical cross-workflow artifact is always:\n\n```text\nadvisory_contract.json\n```\n\nIt uses `schema_version: \"1.0\"`. Its exact structure and stable meanings are\ndefined in `references/advisory-contract.md` and\n`../../contracts/advisory_contract.v1.schema.json` from this skill directory.\nRead the reference completely before drafting the contract.\n\nThe following semantic fields are required at the top level and must retain\ntheir declared meanings: `decision`, `purpose`, `audience`,\n`deliverable_type`, `output_language`, `scope_included`, `scope_excluded`,\n`available_inputs`, `evidence_requirements`, `analysis_plan`, `assumptions`,\n`unresolved_questions`, `success_criteria`, `selected_clara_workflow`,\n`validation_profile`, `validation_scope`, `correction_policy`, and\n`professional_judgement_policy`.\n\nThe contract also carries exact `source_facts`, `explicit_questions`, a\n`generation_handoff`, and a model-led conformance review. Preserve every\nmaterial fact, date, number, entity, constraint, and explicit question from the\nassignment and selected inputs. Do not replace real identities or figures with\ngeneric placeholders when they are material to the advisory work.\n\n## Conversational intake\n\nAsk only for an unresolved choice that would materially change the work. Normal\nmaterial choices include the decision to support, intended reader, deliverable,\nmeaningful scope boundary, output language, unavailable controlling evidence,\nor a professional constraint. Prefer at most three short questions with a\nreason. If a gap can responsibly remain a provisional assumption or a visible\nevidence requirement, record it and continue.\n\nUse chat for free-form intake. In Plan mode, use a native choice only when two\nor three discrete options genuinely change the assignment. Do not build a local\nHTML UI for ordinary assignment planning. Do not ask the user to type\n`continue`; proceed once material choices are resolved unless the next action\nis external, destructive, approval-sensitive, or separately requires consent.\n\n## Codex-Native Run UX\n\nReuse the assignment details already supplied. Summarize the decision, scope,\noutput destination, and unresolved material choices when the user needs to\nreview them. Choose prose, a table, or a checklist according to the task;\nformatting is not an additional intake gate.\n\nDefault output policy: create `draft_advisory_contract.json`, the validated\n`advisory_contract.json`, and `advisory_contract_validation.json` in the user's\nassignment or case folder. These standard artifacts are not choices to propose\nfor a durable Codex or Cowork run. Do not edit generated ZIPs; repository\npackages are rebuilt only during an explicitly requested plugin release task.\n\nExplain the evidence and consequence of unresolved material choices without\nturning supplied facts or workflow selection into a menu. Continue independent\nauthorized preparation while awaiting an answer. At delivery, link the\ncontract and validation report, with status, selected Clara workflow,\nunresolved questions, and next action. When a durable run needs a\ncompact audit index, create `codex_run_review.md` beside the artifacts and link\nthe source inputs, contract, validation report, and handoff.\n\n## Workflow\n\n1. Read the user's assignment and the exact selected inputs. When durable file\n   tools are available, preserve the natural assignment text as one UTF-8 file\n   in the run folder so literal anchors can be checked.\n2. Read `../clara/references/workflow-catalog.md` and choose the narrowest\n   supported handoff with model-led judgement. Use\n   `clara:advisory-case-director` for a durable advisory case that must evolve\n   across several contributions. It must not point back to\n   `clara:advisory-brief-planner` or to developer governance.\n3. Identify only material unresolved questions. Ask when they block responsible\n   handoff; otherwise state and record provisional assumptions.\n4. Draft `draft_advisory_contract.json` against the published schema. Use stable\n   input and step IDs. `available_inputs` describes current, planned, and\n   missing inputs without requiring physical local paths in the canonical\n   contract.\n5. Copy or faithfully summarize all material facts into `source_facts`, with an\n   exact `source_anchor` and the corresponding `input_id`. For each declared\n   `date` or `number`, also record `literal_value` exactly as recognized in that\n   anchor, such as `2027-01-15` or `EUR 12.5`. Preserve every explicit source\n   question verbatim in `explicit_questions`. The model-led review owns the\n   completeness and materiality of facts, dates, numbers, entities, constraints,\n   and questions; the whole-source inventory is not a keyword completeness\n   classifier.\n6. Write a generation handoff whose `workflow` exactly matches\n   `selected_clara_workflow`. Name the objective, input IDs, instructions, and\n   expected outputs, include every input referenced by evidence requirements,\n   analysis steps, source facts, or explicit questions, and keep\n   `preserve_specialist_authority: true`.\n7. Review the source assignment, contract, and handoff semantically. Complete\n   every `model_review` dimension honestly. A contract cannot be\n   `ready_for_handoff` unless every dimension conforms and no blocking question\n   remains.\n8. From the Clara root, run the declared dependency check, then package the\n   contract. Bind each available UTF-8 source whose literal anchors should be\n   checked with a repeated `--source` argument:\n\n```bash\npython scripts/check_dependencies.py\npython scripts/managed_python_runtime.py run scripts/validate_advisory_contract.py \\\n  <run-folder>/draft_advisory_contract.json \\\n  --output-dir <run-folder> \\\n  --source assignment=/path/to/assignment.md \\\n  --source input-2=/path/to/selected-notes.md\n```\n\nThe helper writes `advisory_contract.json` only after validation passes and\nalways writes the current `advisory_contract_validation.json` when the output\nfolder is writable. If a later attempt fails, it moves the prior canonical file\nto a content-hashed `advisory_contract.previous-<hash>.json` recovery path so a\ndownstream workflow cannot consume it as the current contract. If declared\nliteral preservation fails, repair the draft and repeat both semantic review\nand deterministic validation. Do not dismiss a mismatched declared literal\nbecause the intended meaning seems close.\n\n9. Show a compact review summary with the decision, deliverable, scope,\n   assumptions, blocking questions, selected workflow, and validation status.\n   If the user asked only for planning, stop with the reviewed contract. If the\n   user asked Clara to execute the assignment, read the selected specialist\n   skill completely and pass it `advisory_contract.json`; do not replace its\n   process with the planner's analysis plan.\n\n## States and completion\n\n- `ready_for_handoff`: every model-review dimension conforms and no blocking\n  material question remains.\n- `needs_clarification`: at least one unresolved question blocks a responsible\n  handoff.\n- `partial`: a useful contract exists, but evidence or review remains incomplete\n  without necessarily blocking the next bounded step.\n\nCompletion requires a reviewed `advisory_contract.json`, a passing\n`advisory_contract_validation.json`, and a handoff to an existing supported\nClara workflow. File existence alone is not completion. The downstream\nworkflow's completion rules still apply to the advisory output.\n\n## Data boundary\n\nThe active Codex or Cowork model may read the natural assignment, selected\nsource material, and the complete contract, including real names, dates,\nfigures, entities, constraints, assumptions, questions, evidence needs, and\nprofessional judgement policies. No automatic anonymisation or\npseudonymisation is applied because exact facts and identities can be material.\n\nThe validator reads only the draft JSON and explicitly bound UTF-8 source files\nlocally, writes the canonical contract and validation report locally, and does\nnot call a model or external service. This planner does not itself perform web\nresearch, use a connector, upload files, send a communication, publish an\nartifact, or transmit the contract beyond the selected model account. Any such\nroute belongs to the selected downstream Clara workflow and its own data\nboundary.\n\nAfter substantive use of this workflow, read and follow the `Plugin Improvement Feedback` section in `../clara/SKILL.md`.\n"
}