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

package/dist/builtin/workflows/skills/impeccable/scripts/surface-brief.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { resolveProjectRoot } from './context.mjs';
+import {
+  listSurfaceBriefs,
+  resolveSurfaceBrief,
+  surfaceBriefPathForTarget,
+  writeSurfaceBrief,
+} from './lib/surface-briefs.mjs';
+
+function summary(brief, projectRoot) {
+  return {
+    slug: brief.slug,
+    path: path.relative(projectRoot, brief.path).split(path.sep).join('/'),
+    primaryTarget: brief.primaryTarget,
+    relatedTargets: brief.relatedTargets,
+  };
+}
+
+function main(argv) {
+  const [command, target, bodyFile, ...relatedTargets] = argv;
+  const projectRoot = resolveProjectRoot(process.cwd(), target ? { targetPath: target } : {});
+  if (command === 'path') {
+    const filePath = surfaceBriefPathForTarget(target, { projectRoot });
+    if (!filePath) throw new Error('surface brief path requires a concrete target');
+    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\n`);
+    return;
+  }
+  if (command === 'list') {
+    process.stdout.write(`${JSON.stringify(listSurfaceBriefs(projectRoot).map((brief) => summary(brief, projectRoot)), null, 2)}\n`);
+    return;
+  }
+  if (command === 'read') {
+    const result = resolveSurfaceBrief(projectRoot, target || null);
+    if (result.brief) {
+      process.stdout.write(result.brief.text);
+      return;
+    }
+    if (result.candidates.length) process.stderr.write(`${JSON.stringify(result.candidates.map((brief) => summary(brief, projectRoot)), null, 2)}\n`);
+    process.exit(2);
+  }
+  if (command === 'write') {
+    if (!target || !bodyFile) throw new Error('usage: surface-brief.mjs write <primary-target> <body-file>');
+    const filePath = writeSurfaceBrief({
+      projectRoot,
+      primaryTarget: target,
+      relatedTargets,
+      body: fs.readFileSync(bodyFile, 'utf-8'),
+    });
+    process.stdout.write(`${path.relative(process.cwd(), filePath) || filePath}\n`);
+    return;
+  }
+  throw new Error('usage: surface-brief.mjs <path|list|read|write> [target] [body-file] [related-target ...]');
+}
+
+function isMainModule() {
+  if (!process.argv[1]) return false;
+  try {
+    return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(process.argv[1]);
+  } catch {
+    return import.meta.url === pathToFileURL(process.argv[1]).href;
+  }
+}
+
+if (isMainModule()) {
+  try {
+    main(process.argv.slice(2));
+  } catch (error) {
+    process.stderr.write(`${error?.message || error}\n`);
+    process.exit(1);
+  }
+}

package/dist/builtin/workflows/skills/prompt-engineer/SKILL.md

@@ -1,263 +1,68 @@
 ---
 name: prompt-engineer
-description: Create, improve, or optimize prompts using best practices.
+description: Create, improve, optimize, evaluate, or troubleshoot prompts for GPT-5.6, Claude Opus 5, and Claude Fable 5.
 ---
 
 # Prompt Engineering Skill
 
-This skill provides comprehensive guidance for creating effective prompts for language models using proven best practices. Use this skill whenever working on prompt design, optimization, or troubleshooting.
+Create or revise prompts for current models. Optimize for the intersection of GPT-5.6, Claude Opus 5, and Claude Fable 5 unless the user names one target.
 
-## Overview
+## Use This Skill For
 
-Apply proven prompt engineering techniques to create high-quality, reliable prompts that produce consistent, accurate outputs while minimizing hallucinations and implementing appropriate security measures.
-
-## When to Use This Skill
-
-Trigger this skill when users request:
-
-- Help writing a prompt for a specific task
-- Improving an existing prompt that isn't performing well
-- Making outputs more consistent, accurate, or secure
-- Creating system prompts for specialized roles
-- Implementing specific techniques (chain-of-thought, multishot, XML tags)
-- Reducing hallucinations or errors in outputs
-- Debugging prompt performance issues
+- Writing task, system, agent, or tool prompts
+- Improving consistency, accuracy, security, structure, or cost
+- Migrating legacy prompts to current models
+- Selecting examples, XML structure, prompt chains, or model effort
+- Diagnosing prompt regressions or tool-routing failures
 
 ## Workflow
 
-### Step 1: Understand Requirements
-
-Ask clarifying questions to understand:
-
-- **Task goal**: What should the prompt accomplish?
-- **Use case**: One-time use, API integration, or production system?
-- **Constraints**: Output format, length, style, tone requirements
-- **Quality needs**: Consistency, accuracy, security priorities
-- **Complexity**: Simple task or multi-step workflow?
-
-### Step 2: Identify Applicable Techniques
-
-Based on requirements, determine which techniques to apply:
-
-**Core techniques (for all prompts):**
-
-- Be clear and direct
-- Use XML tags for structure
-
-**Specialized techniques:**
-
-- **Role-specific expertise** → System prompts
-- **Complex reasoning** → Chain of thought
-- **Format consistency** → Multishot prompting
-- **Multi-step tasks** → Prompt chaining
-- **Long documents** → Long context tips
-- **Deep analysis** → Extended thinking
-- **Factual accuracy** → Hallucination reduction
-- **Output consistency** → Consistency techniques
-- **Security concerns** → Jailbreak mitigation
-
-### Step 3: Load Relevant References
-
-Read the appropriate reference file(s) based on techniques needed:
-
-**For basic prompt improvement:**
-
-```
-Read references/core_prompting.md
-```
-
-Covers: clarity, system prompts, XML tags
-
-**For complex tasks:**
-
-```
-Read references/advanced_patterns.md
-```
-
-Covers: chain of thought, multishot, chaining, long context, extended thinking
-
-**For specific quality issues:**
-
-```
-Read references/quality_improvement.md
-```
-
-Covers: hallucinations, consistency, security
-
-### Step 4: Design the Prompt
-
-Apply techniques from references to create the prompt structure:
-
-**Basic Template:**
-
-```
-[System prompt - optional, for role assignment]
-
-<context>
-Relevant background information
-</context>
-
-<instructions>
-Clear, specific task instructions
-Use numbered steps for multi-step tasks
-</instructions>
-
-<examples>
-  <example>
-    <input>Sample input</input>
-    <output>Expected output</output>
-  </example>
-  [2-4 more examples if using multishot]
-</examples>
-
-<output_format>
-Specify exact format (JSON, XML, markdown, etc.)
-</output_format>
-
-[Actual task/question]
-```
-
-**Key Design Principles:**
-
-1. **Clarity**: Be explicit and specific
-2. **Structure**: Use XML tags to organize
-3. **Examples**: Provide 3-5 concrete examples for complex formats
-4. **Context**: Give relevant background
-5. **Constraints**: Specify output requirements clearly
-
-### Step 5: Add Quality Controls
-
-Based on quality needs, add appropriate safeguards:
-
-**For factual accuracy:**
-
-- Grant permission to say "I don't know"
-- Request quote extraction before analysis
-- Require citations for claims
-- Limit to provided information sources
-
-**For consistency:**
-
-- Provide explicit format specifications
-- Use response prefilling
-- Include diverse examples
-- Consider prompt chaining
-
-**For security:**
-
-- Add harmlessness screening
-- Establish clear ethical boundaries
-- Implement input validation
-- Use layered protection
-
-### Step 6: Optimize and Test
-
-**Optimization checklist:**
-
-- [ ] Could someone with minimal context follow the instructions?
-- [ ] Are all terms and requirements clearly defined?
-- [ ] Is the desired output format explicitly specified?
-- [ ] Are examples diverse and relevant?
-- [ ] Are XML tags used consistently?
-- [ ] Is the prompt as concise as possible while remaining clear?
-
-**Testing approach:**
-
-- Run prompt multiple times with varied inputs
-- Check consistency across runs
-- Verify outputs match expected format
-- Test edge cases
-- Validate quality controls work
-
-### Step 7: Iterate Based on Results
-
-**Debugging process:**
-
-1. Identify failure points
-2. Review relevant reference material
-3. Apply appropriate techniques
-4. Test and measure improvement
-5. Repeat until satisfactory
-
-**Common Issues and Solutions:**
-
-| Issue                   | Solution                                    | Reference              |
-| ----------------------- | ------------------------------------------- | ---------------------- |
-| Inconsistent format     | Add examples, use prefilling                | quality_improvement.md |
-| Hallucinations          | Add uncertainty permission, quote grounding | quality_improvement.md |
-| Missing steps           | Break into subtasks, use chaining           | advanced_patterns.md   |
-| Wrong tone              | Add role to system prompt                   | core_prompting.md      |
-| Misunderstands task     | Add clarity, provide context                | core_prompting.md      |
-| Complex reasoning fails | Add chain of thought                        | advanced_patterns.md   |
-
-## Important Principles
-
-**Progressive Disclosure**
-Start with core techniques and add advanced patterns only when needed. Don't over-engineer simple prompts.
-
-**Documentation**
-When delivering prompts, explain which techniques were used and why. This helps users understand and maintain them.
-
-**Validation**
-Always validate critical outputs, especially for high-stakes applications. No prompting technique eliminates all errors.
-
-**Experimentation**
-Prompt engineering is iterative. Small changes can have significant impacts. Test variations and measure results.
-
-## Quick Reference Guide
-
-### Technique Selection Matrix
-
-| User Need                     | Primary Technique       | Reference File         |
-| ----------------------------- | ----------------------- | ---------------------- |
-| Better clarity                | Be clear and direct     | core_prompting.md      |
-| Domain expertise              | System prompts          | core_prompting.md      |
-| Organized structure           | XML tags                | core_prompting.md      |
-| Complex reasoning             | Chain of thought        | advanced_patterns.md   |
-| Format consistency            | Multishot prompting     | advanced_patterns.md   |
-| Multi-step process            | Prompt chaining         | advanced_patterns.md   |
-| Long documents (100K+ tokens) | Long context tips       | advanced_patterns.md   |
-| Deep analysis                 | Extended thinking       | advanced_patterns.md   |
-| Reduce false information      | Hallucination reduction | quality_improvement.md |
-| Consistent outputs            | Consistency techniques  | quality_improvement.md |
-| Security/safety               | Jailbreak mitigation    | quality_improvement.md |
-
-### When to Combine Techniques
-
-- **Structured analysis**: XML tags + Chain of thought
-- **Consistent formatting**: Multishot + Response prefilling
-- **Complex workflows**: Prompt chaining + XML tags
-- **Factual reports**: Quote grounding + Citation verification
-- **Production systems**: System prompts + Input validation + Consistency techniques
-
-## Resources
-
-This skill includes three comprehensive reference files:
-
-### references/core_prompting.md
-
-Essential techniques for all prompts:
-
-- Being clear and direct
-- System prompts and role assignment
-- Using XML tags effectively
-
-### references/advanced_patterns.md
-
-Sophisticated techniques for complex tasks:
-
-- Chain of thought prompting
-- Multishot prompting
-- Prompt chaining
-- Long context handling
-- Extended thinking
-
-### references/quality_improvement.md
-
-Techniques for specific quality issues:
-
-- Reducing hallucinations
-- Increasing consistency
-- Mitigating jailbreaks and prompt injections
-
-Load these files as needed based on the workflow steps above.
+1. Establish the user-visible outcome, audience, use case, model family, authorization boundaries, required output, and representative failure cases. Ask only for information whose absence would materially change the prompt.
+2. Read the relevant references below.
+3. Delete obsolete or redundant guidance before adding text.
+4. Shape complex prompts as `Role · Goal · Success criteria · Constraints · Tools · Output · Stop rules`; omit sections that do not change behavior.
+5. Test one surgical change at a time on representative inputs. Compare task success, output validity, tool behavior, latency, tokens, and cost.
+6. Deliver the revised prompt plus a brief change summary and validation plan. Keep the response focused: lead with the prompt or outcome, retain decisions and caveats, and omit background that does not change the user's next action.
+
+## Progressive Disclosure
+
+| Read | When | Covers |
+| --- | --- | --- |
+| `references/core_prompting.md` | Creating or repairing any prompt | Clarity, context, roles, success criteria, constraints, output contracts, examples, XML, grounding |
+| `references/advanced_patterns.md` | Building agents, tool workflows, long-context prompts, chains, or model-specific variants | GPT-5.6, Claude Opus 5, Claude Fable 5, tool routing, stopping, delegation, adaptive thinking |
+| `references/quality_improvement.md` | Optimizing, evaluating, securing, or troubleshooting a prompt | Delete-first workflow, evals, hallucination reduction, consistency, security, regression diagnosis |
+
+Use the exact instruction `Read references/core_prompting.md`, `Read references/advanced_patterns.md`, or `Read references/quality_improvement.md` when loading one of these files.
+
+## Cross-Model Baseline
+
+- State the destination and completion bar; leave routine path selection to the model.
+- Give relevant context and a short reason for important constraints.
+- Reserve `ALWAYS`, `NEVER`, `MUST`, and `only` for safety rules, required fields, forbidden actions, and other true invariants. Use decision rules for judgment calls.
+- Specify user-facing or machine-consumed output length, sections, format, and validation requirements.
+- Use consistent descriptive XML tags when a prompt mixes instructions, context, examples, or documents. Tags are optional for simple prompts.
+- Use 3–5 relevant, diverse examples when examples measurably improve format, tone, or edge-case behavior; remove examples that do not change behavior.
+- For high-stakes or grounded work, require claims to cite available evidence, permit uncertainty, and define what happens when evidence is missing.
+- Do not prefill the final assistant response: Claude 4.6 and later return a 400 error. Use explicit format instructions, structured outputs, tools, or post-processing instead.
+- Do not request internal reasoning as response text. On Claude Fable 5 this can trigger `reasoning_extraction` and force fallback; request conclusions, evidence, observed behavior, citations, or validation results instead.
+- In instruction text, prefer “consider,” “evaluate,” or “assess” over “think” and its variants, especially for configurations with model thinking disabled.
+
+## Quick Selection Guide
+
+| Need | Primary approach | Reference |
+| --- | --- | --- |
+| Better clarity or tone | Outcome, audience, context, specific role | `references/core_prompting.md` |
+| Reliable shape | Explicit output contract, schema, relevant examples | `references/core_prompting.md` |
+| Complex autonomous task | Agentic structure plus success and stop rules | `references/advanced_patterns.md` |
+| Tool-choice failures | Context-dependent routing and prerequisite rules | `references/advanced_patterns.md` |
+| Long documents | Documents first, query last, source metadata | `references/advanced_patterns.md` |
+| Deep analysis | Adaptive thinking and calibrated effort | `references/advanced_patterns.md` |
+| Multi-stage workflow | Focused prompt chain with explicit handoffs | `references/advanced_patterns.md` |
+| Hallucinations | Evidence scope, citations, uncertainty behavior | `references/quality_improvement.md` |
+| Inconsistent output | Schema, examples, parser validation | `references/quality_improvement.md` |
+| Security or injection risk | Policy boundaries, input controls, layered defenses | `references/quality_improvement.md` |
+| Excess cost or latency | Delete-first optimization and effort sweep | `references/quality_improvement.md` |
+
+## Invariants
+
+Prompting reduces but does not eliminate errors. Validate critical outputs with domain-appropriate checks, especially in high-stakes applications. Preserve safety, business, evidence, permission, and downstream parser constraints while optimizing.