Sigil: Sigil Development

• creating a new sigil,
• converting a draft workflow into a sigil,
• continuing from an Invoke handoff that targets sigil creation or revision,
• revising an existing sigil's behavior contract,
• adding observability or telemetry to a sigil,
• adding a post-run hook that summarizes the latest sigil request into JSON telemetry,
• selecting or installing a repository-local observability package for a consuming repository,
• reflecting on accumulated usage signals,
• improving Quality Bar, Anti-Patterns, templates, or output contracts after evidence shows gaps.

• sigil name or candidate capability,
• target tier or suspected tier,
• problem statement,
• current README.md, SKILL.md, templates, or draft notes,
• examples of successful or failed usage,
• generated outputs from prior sigil runs,
• experiment harness files under development/,
• known workflow gaps, repeated confusion, or review comments,
• desired telemetry threshold, if different from defaults.

• invoke owns early discovery, definition, design, planning, and handoff packets.
• sigil-development owns sigil contract mutation, experiment harness, validation, observability, reflection, iteration, and promotion readiness.
• spellcraft owns composed multi-sigil spell workflows.
• task-session owns bounded execution from approved work-pack tasks or SWUs.
• experiment-harness owns repeatable test mechanics, realistic prompts, live Codex examples, validation reports, and telemetry emission for reusable sigils.

When the input is an Invoke handoff, consume the handoff as source context, then take lifecycle ownership of the sigil. Do not send the user back to Invoke unless the handoff is missing the target intent, scope, or artifact objective needed to proceed.

When implementation work is delegated through Task Session and the codex-goal adapter:

1. Sigil Development owns the lifecycle work-pack and promotion decision.
2. Task Session selects one ready task/SWU and checks gates.
3. The Codex Goal adapter generates or hands off one native /goal.
4. Codex executes the bounded runtime goal.
5. Task Session reviews the result against the original task/SWU and syncs work-pack evidence.
6. Experiment Harness runs or validates the artifact-local examples/regimes.
7. Sigil Development consumes the experiment report, observability signal, and reflection trigger state before marking lifecycle progress.

Required runtime evidence shape:

runtime: codex
adapter: codex-goal
source_swu: <id>
result: pass | flag | block | interrupted
files_touched:
  - <path>
validation:
  - <command or review evidence>
experiment_harness:
  status: pass | flag | block | not_run
  report: <path or none>
remaining_blockers:
  - <blocker or none>
lifecycle_owner_next_step: validate | observe | reflect | iterate | promote

A sigil implementation SWU is not lifecycle-complete until runtime evidence is reviewed and the relevant experiment harness state is updated or explicitly blocked.

<tier>/<sigil-name>/

If draft planning artifacts are needed, colocate them under:

<tier>/<sigil-name>/development/

If adding observability, create or update templates under:

<tier>/<sigil-name>/templates/

If reflecting on a sigil, produce a reflection report using templates/reflection-report.md or a sigil-local equivalent.

Observer subagent scope:

1. Inspect the target sigil files and usage outputs.
2. Generate telemetry signals using the usage telemetry schema.
3. Identify workflow gaps, quality failures, anti-pattern hits, and output-contract drift.
4. Recommend reflection triggers and iteration candidates.
5. Return findings only; do not edit files directly unless explicitly delegated.

If no subagent mechanism is available, run the observer pass as a separate clearly labeled analysis step and preserve the same report structure.

Telemetry should capture:

• sigil name and tier,
• execution mode,
• generated output count,
• Quality Bar pass/fail/partial status,
• Anti-Patterns observed or avoided,
• workflow gaps,
• output-contract drift,
• user correction or clarification signals,
• observer recommendations,
• reflection trigger state.

Use templates/usage-telemetry.md as the default schema reference.

Use framework/observability/SIGIL-OBSERVABILITY-HOOK.md as the default hook pattern when a sigil needs to summarize the latest request and save it as JSON telemetry.

Use framework/observability/REPOSITORY-PACKAGE.md and the observability-setup sigil when a consuming repository needs local telemetry storage.

• Manual trigger: the user asks to reflect, review, improve, tune, or iterate the sigil.
• Usage threshold: the sigil reaches 5 meaningful executions unless a sigil-local threshold overrides it.
• Output threshold: the sigil produces or modifies 10 artifacts since the last reflection.
• Gap threshold: 3 related workflow gaps are observed.
• Severe gap: 1 severe workflow gap appears, such as repeated wrong invocation, unreviewable output, invalid Quality Bar, missing Anti-Pattern, or unsafe scope expansion.

Reflection must produce:

• signal summary,
• patterns found,
• proposed changes,
• changes explicitly rejected,
• updated thresholds if needed,
• next review trigger.

Use templates/reflection-report.md as the default report shape.

• produce or update a self-contained sigil folder when in design or update mode,
• initialize or preserve an experiment harness for reusable sigils,
• treat Codex Goal evidence as SWU execution evidence, not as reusable-behavior validation,
• require experiment harness evidence or a named block before promotion readiness,
• define observability signals for any sigil that will be reused,
• define a post-run JSON hook when usage history is needed for later reflection,
• use an observer subagent or clearly labeled observer pass when generating telemetry or reflection,
• preserve the distinction between usage evidence, observer inference, and applied edits,
• define manual, threshold-based, and gap-based reflection triggers,
• validate markdown links and product-neutral wording before completion,
• return the next lifecycle step for the sigil.

• treating sigil creation as complete when no observability or reflection path exists,
• allowing the observer subagent to edit the sigil without synthesis and review,
• collecting telemetry that cannot inform an iteration decision,
• reflecting on anecdote without usage evidence or an explicit manual trigger,
• changing the core contract of a sigil without naming the evidence that justifies it,
• using thresholds as rigid bureaucracy when a severe gap needs immediate reflection,
• storing vague gap notes that cannot be connected to a Quality Bar, Anti-Pattern, process step, or output contract.

## Sigil Development Result

- Target sigil: <name>
- Mode: new | update | observe | reflect
- Tier: formulae | transmutations | arcana
- Files changed: <paths>
- Observer pass: subagent | local fallback | not needed
- Telemetry updated: yes | no | not applicable
- Reflection trigger state: none | manual | usage-threshold | output-threshold | gap-threshold | severe-gap
- Iteration decision: no change | targeted update | reflection required
- Validation: <checks performed>
- Next lifecycle step: <step>