@bastani/atomic 0.9.18-alpha.5 → 0.9.18-alpha.7

package/dist/builtin/workflows/skills/prompt-engineer/references/gpt_5_6.md

@@ -0,0 +1,58 @@
+# GPT-5.6 prompting and migration
+
+Use this reference for the GPT-5.6 family. Guidance checked on September 5, 2026 against [OpenAI's GPT-5.6 guide](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6). Keep these defaults separate from [GPT-6 Astra](gpt_6_astra.md) and [GPT-5.5](gpt_5_5.md).
+
+## Start with the workload and a lean contract
+
+The `gpt-5.6` alias routes to `gpt-5.6-sol` for flagship capability. The guide positions `gpt-5.6-terra` for a balance of quality and price and `gpt-5.6-luna` for efficient, high-volume work. Evaluate the chosen variant on the actual workload; these API names do not establish availability in an agent's configured catalog.
+
+State the outcome, success criteria, domain context, approval boundaries, and required evidence. Let the model choose routine steps. When simplifying a working prompt, remove one group of repeated instructions, examples, or tools at a time and rerun the same cases. Keep examples that encode product requirements or correct a measured gap. Check context growth across long sessions as well as initial prompt size.
+
+OpenAI reports roughly 10–15% higher scores, 41–66% fewer total tokens, and 33–67% lower cost for leaner prompts in a sample of internal coding-agent evaluations. These are workload-dependent observations, not expected gains for every application.
+
+## Define action boundaries once
+
+Distinguish answering, reviewing, or diagnosing from implementing. Name authorized local work and the final action separately. Repeated "ask first" rules can block expected progress; missing approval for an external, destructive, costly, or scope-expanding action still matters.
+
+```text
+For review requests, inspect the relevant materials and report findings without editing. For requests to fix or build, make the requested local changes and run relevant non-destructive checks. Continue work already authorized in this conversation. Ask before actions outside that authority, including destructive operations or unapproved external writes. Stop when the requested result and required checks are complete, or name the blocking decision.
+```
+
+## Control brevity without losing content
+
+GPT-5.6 tends to be more concise than GPT-5.5. Reevaluate inherited "keep it short" instructions if answers lose evidence, caveats, or next steps. Set `text.verbosity` to `low`, `medium`, or `high` for the request default, then specify task-specific length and required content.
+
+```text
+Lead with the conclusion. Retain required facts, decisions, evidence, material caveats, and the next action. Trim introductions, repetition, generic reassurance, and secondary detail first. Acknowledge a reported problem specifically; omit generic praise and sign-offs.
+```
+
+## Effort, pro mode, and state
+
+Use Responses for reasoning, tool-calling, and multi-turn work. Verify provider and SDK support before adopting these controls.
+
+| Control | Guidance |
+| --- | --- |
+| Reasoning effort | Supported values are `none`, `low`, `medium`, `high`, `xhigh`, and `max`; the default is `medium`. Preserve the current GPT-5.5/5.4 effort on migration, then compare one level lower. If starting at `none`, retain that latency baseline and test `low` for reasoning or tool work. |
+| Higher effort | Use `high` or `xhigh` for measured quality gains. Reserve `max` for the hardest quality-first work; compare it against `xhigh` rather than assuming more effort is better. |
+| Pro mode | Keep the selected model and set `reasoning.mode: "pro"`; do not invent a separate Pro model slug. Effort is independent and defaults to `medium` in standard and pro modes. Pro increases latency and bills the aggregated model work. Compare it with standard mode at the same model and effort. |
+| Persisted reasoning | GPT-5.6 defaults to `all_turns`. Omit `reasoning.context` or use `auto`, and inspect the effective response value. Use `all_turns` for stable goals and `current_turn` when earlier reasoning is no longer relevant. |
+| Continuations | With `all_turns`, use `previous_response_id`. For manual history, preserve prior user inputs and every response output item. With `store: false` or Zero Data Retention, replay the returned encrypted reasoning items. |
+| Caching | Implicit caching remains available. Cache writes cost 1.25 times uncached input; track `cached_tokens` and `cache_write_tokens`. Use explicit breakpoints or `prompt_cache_options.mode: "explicit"` when useful, and replace `prompt_cache_retention` with `prompt_cache_options.ttl`. |
+
+Pro mode is an API setting, not a request to narrate private reasoning or generate several visible answers. Keep the same outcome-focused prompt and compare completeness, evidence, cost, and latency.
+
+## Choose programmatic tool calling by task shape
+
+Use Programmatic Tool Calling for a bounded stage that filters, joins, ranks, deduplicates, aggregates, or validates large tool results into a smaller structured result. Multiple calls alone do not justify it. Prefer direct calls when one call is enough, outputs are small, each result changes the next decision, approval is needed, or citations/native artifacts must remain visible.
+
+Name the eligible tools, documented input/output fields, output schema, evidence requirements, retry/concurrency limits, and stop condition. If return shapes are unknown, inspect them through direct calls first. When combining routes, define one handoff and prohibit duplicate completed actions.
+
+The application must enable `programmatic_tool_calling`, opt tools in through `allowed_callers`, handle `program` and `program_output` items, and preserve `call_id` and `caller` linkage. Validate both the program's result and the final assistant answer; correct records are insufficient if the answer drops a required citation or caveat. Consult the [PTC guide](https://developers.openai.com/api/docs/guides/tools-programmatic-tool-calling) before implementation.
+
+The Responses multi-agent beta can coordinate independent workstreams and synthesize results. Treat it separately from an agent harness's own subagents. Prompt text does not enable hosted PTC, pro mode, persisted reasoning, or multi-agent support in Atomic.
+
+## Images and streaming safeguards
+
+With `original` or `auto` image detail, GPT-5.6 preserves dimensions unless a side exceeds 65,535 pixels, then scales to that limit. Images still over the 30,000-patch limit are rejected rather than resized to fit. Choose detail deliberately and validate image size, latency, and token cost; do not carry GPT-5.5's image limits forward.
+
+The guide notes real-time cyber/biology safeguards can refuse requests or pause generation for several seconds. Handle refusals and streaming delays honestly; do not treat them as a reason to evade safeguards. For individual end users, send a stable, privacy-preserving `safety_identifier` as described in the [safety guide](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).

package/dist/builtin/workflows/skills/prompt-engineer/references/gpt_6_astra.md

@@ -0,0 +1,58 @@
+# GPT-6 Astra prompting and migration
+
+Use this reference when targeting `gpt-6-astra`, migrating a prompt to Astra, or diagnosing early stops, excessive verification, or conflicting skills. Keep other model variants separate. Guidance checked on September 5, 2026 against [OpenAI's model guide](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-6-astra).
+
+## Define completion and permission once
+
+Astra follows detailed instructions closely and may ask questions where earlier models made assumptions. Define the intended finished result, including implementation, inspection, repairs, and any authorized final action. Treat action requests such as "can you fix this" as requests to do the work. Continue through work already authorized by the conversation; ask when a missing decision would materially change the result or permission is actually absent.
+
+Before asking for final approval, prepare the authorized, reversible work so the user can review a concrete result. Do not turn this into blanket permission for destructive actions, publication, deployment, or external mutations. Preserve higher-priority policy, repository requirements, and explicit user boundaries.
+
+Adapt this example to the real environment:
+
+```text
+Implement the requested fix and verify the affected behavior. The local tests use disposable fixtures and have no production access. Run them, repair failures caused by this change, and rerun affected checks without asking again. Complete the repository's required checks. Stop when the requested behavior and required checks pass, or when a specific missing decision or permission blocks progress. Prepare a reviewable diff; deployment is not authorized.
+```
+
+If exploration beyond the first implementation is intended, name the questions to explore and the stopping condition. Avoid an automatic "pause after first implementation" rule unless that review gate is needed.
+
+## Audit instructions that change behavior
+
+Astra is sensitive to skills and repository instruction files. Check the relevant loaded instructions for conflicting completion rules, stale model workarounds, mandatory broad research, or approval language that blocks already-authorized work. Use the instruction audit in [quality_improvement.md](quality_improvement.md) when these symptoms appear.
+
+Explicit user preferences override advisory skill defaults, subject to system/developer instructions and real authorization requirements. A skill cannot grant permission or override higher-priority policy. When a skill causes an unexpected pause or scope change, identify its exact `SKILL.md` path, quote the instruction, and distinguish its requirement from your interpretation. Do not silently remove binding constraints in the name of brevity.
+
+## Calibrate testing and delegation
+
+Run checks appropriate to the change and all required repository checks. Broaden or repeat them only after a new change, a failure, or an unresolved concern. Avoid tests that merely repeat implementation text for reversible, low-impact edits. Keep regression tests that exercise behavior and failure modes.
+
+Astra may delegate less than desired. When the application supports collaboration, explicitly allow independent tasks to run in parallel if that saves time or improves quality. Give each delegate a bounded objective, ownership, and expected evidence; respect the harness's concurrency limits. Keep dependent work sequential and synthesize results before acting. Claude-specific delegation damping is not an Astra default. Inter-agent messages should be legible to humans, with proper spacing and clear identifiers.
+
+## Control writing directly
+
+Astra tends toward detailed, formatted responses. Specify the audience, necessary detail, and output shape instead of assuming the concise defaults of GPT-5.6. Prefer a clear first sentence and short paragraphs. Use lists or tables when they help comparison or sequence. Use familiar words and concrete verbs; remove stock conclusions, repeated slogans, unnecessary contrasts, and technical jargon that does not help the reader. Preserve consequential caveats and validation evidence.
+
+```text
+Lead with the result. Use short, plain paragraphs and include only the evidence, caveats, and next action needed by this reader. Use a list only for parallel items. Avoid canned headings such as "Bottom line" and unnecessary contrasts such as "This isn't X, it's Y."
+```
+
+## API migration checks
+
+These are API capabilities, not promises that every agent harness exposes them. Verify the SDK, provider, and request path before adding parameters.
+
+| Area | Astra migration rule |
+| --- | --- |
+| Model and effort | Set `model: "gpt-6-astra"`. Preserve existing effective reasoning effort; when migrating from `none` or `minimal`, start with `low` and evaluate. Astra does not support `none`. Use `reasoning.effort` in Responses or `reasoning_effort` in Chat Completions. |
+| Tools | Use Responses for tool calling. Astra supports Chat Completions, but tool calling requires Responses. |
+| Sampling and log probabilities | Remove `temperature`, `top_p`, and `top_logprobs`. Remove Chat Completions `logprobs`; remove `message.output_text.logprobs` from Responses `include`. |
+| Cache migration | From GPT-5.5 or earlier, replace `prompt_cache_retention` with `prompt_cache_options.ttl: "30m"`. Review cache boundaries and cache-write billing in the [caching guide](https://developers.openai.com/api/docs/guides/prompt-caching#summary-of-model-differences). |
+| Changing effort | In supported standard single-agent requests, use a `configuration_update` input item to change effort without changing request-level `reasoning.effort` and the cached prompt prefix. The update persists until replaced. Check the [compatibility limits](https://developers.openai.com/api/docs/guides/reasoning#change-reasoning-mid-conversation) first. |
+| EU data residency | Use Standard processing. Astra does not support `service_tier: "fast"` or `"priority"` with EU data residency. Fast mode has no latency SLA. |
+
+Async tools can free the model to handle independent work while a tool runs. Mark a supported function or custom tool `async: true`; the application still executes the tool, manages pending work, and returns its result with the original `call_id`. Do not assume dependency ordering or cancellation happens automatically. See [async tool calling](https://developers.openai.com/api/docs/guides/async-tool-calling).
+
+Mid-turn steering over Responses WebSockets can carry revised instructions into a continuation while preserving completed work. Reconcile completed actions, pending tool results, and the new scope rather than repeating side effects. Consult the [steering event flow](https://developers.openai.com/api/docs/guides/steering) before implementing it. Prompt text alone does not enable async execution or steering in Atomic or another harness.
+
+## Check the change on representative cases
+
+Compare a normal task, an early-stop case, and a permission boundary case. Check whether the agent completes authorized work, asks only blocking questions, runs the required checks without repetitive expansion, and respects forbidden actions. For API migrations, also validate the request payload and tool-result flow. Keep prompt edits, model changes, and effort experiments separate so failures have an identifiable cause. Do not claim a measured improvement without running the comparison.

package/dist/builtin/workflows/skills/prompt-engineer/references/quality_improvement.md

@@ -4,12 +4,12 @@ Optimize against representative behavior, not prompt aesthetics. Preserve user-v
 
 ## Delete-First Workflow
 
-OpenAI measured leaner system prompts scoring roughly 10–15% higher on internal coding-agent evals while using 41–66% fewer total tokens and costing 33–67% less. Results vary, but the direction is clear: deletion is the default edit.
+OpenAI's [GPT-5.6 guide](gpt_5_6.md) reports leaner system prompts scoring roughly 10–15% higher on internal coding-agent evals while using 41–66% fewer total tokens and costing 33–67% less. Treat these as workload-specific measurements. Test deletions against your own baseline.
 
 ### Delete
 
 - repeated statements of the same rule;
-- generic self-verification nagging and legacy verifier scaffolding;
+- generic self-verification reminders that duplicate the target model's behavior without improving measured outcomes;
 - over-triggering absolutes such as “use this tool in every case” when routing depends on context;
 - step-by-step process narration for behavior the model already performs;
 - examples that do not alter measured behavior;
@@ -37,6 +37,19 @@ Reserve absolute language for true invariants. Convert judgment calls into condi
 
 Do not rewrite a working prompt stack and change effort, model, and tools simultaneously; that makes causality impossible to identify.
 
+## Audit accumulated skills and repository instructions
+
+The following audit distills [Eric Provencher's advice on X](https://x.com/pvncher/status/2095991462416490862), read September 5, 2026. It is practitioner guidance for instruction maintenance, not an API specification or a measured guarantee for every model or harness.
+
+- Keep skill descriptions short and specific about when to load them. Prefer "Plan and validate database migrations" to "Use for anything involving databases." Too many broad or competing descriptions make routing harder. Provencher reports that Codex truncates descriptions when too many skills are installed; do not assume Atomic has the same truncation behavior.
+- Keep a multi-purpose skill's root file a small router. Put task-specific procedures and scripts in references, and load only the branch needed. This saves context and avoids unrelated instructions changing the task.
+- Revisit inherited recipes after model upgrades. Replace rigid itineraries for routine judgment with outcomes, necessary dependencies, and completion criteria. Evaluate changes across the models used by repository contributors; guidance that helps Sol or Luna may overconstrain Astra.
+- Review `AGENTS.md` requirements in proportion to the task. A typo fix rarely needs a full repository map or a stack of design documents. Keep contextual pointers current and retain required pre-edit inspection and repository checks; propose changes to binding instructions rather than silently ignoring them.
+- Make permission boundaries concrete. If the environment actually uses disposable local fixtures with no production access, authorize running and repairing those tests as one workflow. Do not generalize that permission to production or publication, and do not ask again at every already-authorized step.
+- Define completion before work starts, including running the implementation, inspecting results, and repairing failures when requested. A first-pass review gate is a deliberate stopping point; remove an accidental gate only when authorized. For broader exploration, state what to investigate and where to stop.
+
+Treat each audit change as a hypothesis. Compare representative tasks, including a small edit and a real approval boundary, before removing a rule globally. OpenAI's [Astra guide](gpt_6_astra.md) adds model-specific advice for excessive testing, early stops, and instruction conflicts.
+
 ## Evaluation Contract
 
 Choose cases that represent normal traffic, hard edge cases, missing evidence, tool failures, and adversarial inputs. Measure:
@@ -66,7 +79,7 @@ For long agent runs, ground status as well as final claims:
 Before reporting progress, audit each claim against a tool result from this session. Report failed, skipped, or unverified work plainly, and call work complete only when the cited validation supports it.
 ```
 
-This compact evidence rule replaces repeated requests to recheck work. Anthropic reports that grounding progress against tool results nearly eliminated fabricated status reports in its tests.
+This evidence rule helps reduce unsupported progress claims; it does not replace required verification. The [Fable 5 guide](claude_fable_5.md) reports benefits from grounding status and separately recommends independent verification for long work. Keep those distinct from Opus 5's advice to remove redundant self-checks.
 
 ## Consistent Output
 
@@ -105,6 +118,7 @@ Safety invariants may use `NEVER` or `MUST`; stylistic preferences and tool judg
 | Agent stops early | Permission boundary is vague or final plan substitutes for action | Define authorized actions and completion/blocker stop rules |
 | Agent overbuilds | Scope and success criteria are broad | Name the requested scope and exclude unrelated features or refactors |
 | Too much delegation | No size or independence threshold | Add delegation damping and a concurrency cap |
+| Too little delegation on Astra | No explicit permission or independence rule | Allow bounded parallel work when it saves time or improves quality |
 | Long visible answer | No explicit output length contract | Specify preserved content, omissions, sections, and word limit |
 | High latency/cost | Excess prompt text or effort | Delete first, then compare one lower effort level |
 | Long-context miss | Query precedes large documents | Put documents first and query last; Anthropic measured up to ~30% improvement |
@@ -112,7 +126,7 @@ Safety invariants may use `NEVER` or `MUST`; stylistic preferences and tool judg
 
 ## Model and Effort Regression Checks
 
-Preserve the current model and effort as the baseline before tuning. For GPT-5.6, test the same reasoning effort and one level lower. For Claude Opus 5 and Claude Fable 5, start from `high`, then compare lower levels where quality holds and higher levels only for capability-sensitive work.
+Preserve the current model and effort as the baseline before tuning. Read the relevant page from the [model table](../SKILL.md#model-guides) for migration defaults and supported controls. Effort names do not imply equal reasoning volume across models. Compare lower levels where quality holds and higher levels only where the gain justifies cost; do not silently change thinking defaults, output budgets, or API compatibility.
 
 Effort is not a substitute for missing success criteria, routing, dependencies, validation, or stop rules. On Opus 5, effort does not reliably control visible response length; use an explicit length and shape contract.