@vpxa/aikit 0.1.347 → 0.1.349

package/scaffold/INSTRUCTIONS.md

@@ -1,273 +0,0 @@
-# Scaffold Instruction Authoring Guide
-
-This folder is the source of truth for generated agent, skill, prompt, hook, and flow instructions. Future edits must improve instruction adherence, platform parity, and token efficiency without removing behavior that makes agents safer or smarter.
-
-Use this guide when changing source instructions in `scaffold/definitions/`, adapters in `scaffold/adapters/`, or generated previews from `node scaffold/generate.mjs`.
-
-## Source Of Truth Map
-
-| Need | Edit |
-| --- | --- |
-| Agent roster, routing metadata, models, skills | [definitions/agents.mjs](definitions/agents.mjs) |
-| Agent body text and mode behavior | [definitions/bodies.mjs](definitions/bodies.mjs) |
-| Shared agent kernels and long protocols | [definitions/protocols.mjs](definitions/protocols.mjs) |
-| Global policies and generated instruction sections | [definitions/policies.mjs](definitions/policies.mjs) |
-| Skill `SKILL.md`, refs, assets, scripts | [definitions/skills/](definitions/skills/) |
-| Prompt templates | [definitions/prompts.mjs](definitions/prompts.mjs) |
-| Platform-specific output shape | [adapters/](adapters/) |
-| Generated preview/output | [_preview/](_preview/) and generated platform folders |
-
-Never treat generated platform files as source. Change definitions/adapters, then regenerate.
-
-## Prime Rules
-
-1. Optimize for adherence, not raw brevity. Short text that loses a gate, protocol, or routing cue is worse.
-2. Compress protocols; do not amputate them. Replace repeated prose with one canonical kernel, coverage map, or progressive reference.
-3. Keep one source of truth per concept. Metadata routes agents/skills; bodies describe behavior; protocols hold reusable operating rules.
-4. Preserve cross-platform parity. Copilot, Codex, Claude Code, Gemini, OpenCode, Zed, IntelliJ, Hermes, and Hermes-agent may format differently, but must carry equivalent semantics.
-5. Make subagents robust with fresh context. Every subagent must know scope, boundaries, output shape, validation duty, and whether it can edit files.
-6. Prefer progressive disclosure. Put hot-path rules in `SKILL.md` or agent body; put deep procedures in refs/scripts/assets.
-7. Reduce `HARD`, `MUST`, and repeated warnings. Use priority only for true gates. Too many absolute rules blur attention.
-8. Preserve exact technical terms. Do not shorten tool names, protocol names, file paths, model names, or error strings.
-
-## Agent Authoring
-
-### Orchestrator
-
-Orchestrator is usually the main agent. It plans, decomposes, dispatches, gates quality, coordinates review, presents outcomes, and protects user intent.
-
-Keep Orchestrator strong on:
-
-- No direct implementation unless explicitly scoped as trivial.
-- Task decomposition with clear ownership, success criteria, and validation.
-- Subagent dispatch envelopes that include task id, scope, constraints, expected output, tool/skill needs, and communication style.
-- Protocol coverage for conversation compression, decision protocol, FORGE quality gates, thinking principles, multi-agent development, presentation, session handoff, and lesson capture.
-- User style propagation. If user activates terse/caveman style or another response style, Orchestrator must embed it in subagent instructions and tell subagents to follow it unless safety clarity needs full prose.
-
-Do not remove Orchestrator protocols only because they cost tokens. If a long protocol is not on the hot path, replace it with a compact coverage map plus reference, not deletion.
-
-### Planner
-
-Planner may run as main agent or subagent. It produces plans, tests, specs, and sequencing. It should not implement unless an explicit flow step says so.
-
-Keep Planner aligned with Orchestrator:
-
-- Accept Orchestrator handoff fields and preserve task id/evidence.
-- Produce actionable steps, validation gates, dependencies, and risk notes.
-- Avoid flow advancement when acting as a subagent unless explicitly authorized.
-
-### Implementation Agents
-
-Implementer, Frontend, Refactor, Debugger, Security, and Documenter often run as subagents. They still need direct-run behavior for users who invoke them alone.
-
-Each implementation agent should state:
-
-- Primary job and non-goals.
-- Whether it may edit files.
-- Which skills to load from metadata.
-- Validation expected before final response.
-- Output shape for main-agent mode and subagent mode.
-- Stop condition when scope is unclear or unsafe.
-
-Do not duplicate full skill tables inside bodies. `definitions/agents.mjs` owns skill routing. Body text may mention critical skill categories only when behavior depends on them.
-
-### Research And Review Agents
-
-Researchers and reviewers must be independent enough to disagree with plans.
-
-Keep:
-
-- Evidence-first output.
-- Assumptions separated from verified claims.
-- No implementation unless explicitly requested.
-- Clear severity/risk ranking for review agents.
-- Complementary lenses across Alpha/Beta variants.
-
-## Skill Authoring
-
-Skills are progressive instructions. `SKILL.md` should be concise enough to load often, but complete enough to route work safely.
-
-Each skill should include:
-
-- When to use it and when not to use it.
-- Required setup or tool preference.
-- Minimal workflow.
-- Output or handoff shape.
-- Validation or quality bar.
-- References/scripts/assets to load only when needed.
-
-Use refs/assets/scripts for detail. Do not delete them for token savings if they support rare but important paths. Token efficiency comes from loading them conditionally.
-
-When adding or renaming a skill:
-
-1. Add or update the module under [definitions/skills/](definitions/skills/).
-2. Export it from [definitions/skills/index.mjs](definitions/skills/index.mjs).
-3. Add metadata references in [definitions/agents.mjs](definitions/agents.mjs) only for agents that should actually load it.
-4. Regenerate and verify generated skill files across relevant platforms.
-
-## Prompt Authoring
-
-Prompts should launch work, not duplicate entire agents.
-
-Good prompts include:
-
-- Goal.
-- Scope and constraints.
-- Required agent/skill/tool path.
-- Acceptance criteria.
-- Validation command or evidence requirement.
-- Output shape.
-
-Avoid:
-
-- Repeating full Orchestrator or protocol bodies.
-- Platform-specific assumptions unless prompt is platform-specific.
-- Open-ended "do your best" wording without success criteria.
-
-## Skill Reference Pattern
-
-Skills follow the [Anthropic skills specification](https://github.com/anthropics/skills/tree/main/skills/skill-creator):
-
-```
-skill-name/
-  SKILL.md              ← main skill body (hot-path instructions)
-  references/           ← deep-dive details, examples, schemas (loaded conditionally)
-  scripts/              ← executable scripts
-  assets/               ← templates, images, static files
-```
-
-In the scaffold system, each skill is a `.mjs` file that exports an array of `{ file, content }` objects:
-
-```js
-export default [
-  { file: 'SKILL.md', content: '...main body...' },
-  { file: 'references/deep-dive.md', content: '...detailed reference...' },
-  { file: 'scripts/helper.mjs', content: '...executable...' },
-];
-```
-
-The `file` field is relative to the skill's output directory. The scaffold `generateSkills` adapter reads these arrays and writes the actual files.
-
-### When to put content in references vs SKILL.md
-
-| Content type | Where | Why |
-|---|---|---|
-| Trigger rules, core workflow, quality bar, output shape | `SKILL.md` | Hot-path — loaded every time the skill is activated |
-| Full examples, detailed step-by-step, format catalogs, schemas | `references/*.md` | Progressive disclosure — loaded only when needed |
-| Executable helpers, transforms, generators | `scripts/*.mjs` | Run, not read |
-| Templates, images, static data | `assets/` | Referenced, not inlined |
-
-### Rules
-
-- `SKILL.md` should be concise enough to load often, complete enough to route work safely.
-- Move deep procedures to refs; do not delete them. Token efficiency comes from loading them conditionally.
-- Protocol refs in `scaffold/definitions/refs/` may use dual exports: a named `const` for inlining into `protocols.mjs` + a `default` array for file generation.
-- Never create hand-written `.md` reference files — `.mjs` is the source of truth.
-
-## Protocol And Kernel Authoring
-
-Shared protocols exist because repeated body text drifts. Keep reusable behavior in [definitions/protocols.mjs](definitions/protocols.mjs).
-
-Use:
-
-- Shared base kernels for generic subagent behavior.
-- Compact role kernels for code, research, review, architecture, docs, and diagnostics.
-- Coverage maps for long protocols that must remain active but do not need full in-body repetition.
-- Full protocol text where generated platform root docs or adapters need it.
-
-Before removing any `sharedProtocols` entry, prove one of these:
-
-- Same protocol is still included by platform-level instructions.
-- Same behavior is represented in a compact coverage map and tested.
-- Protocol is obsolete and no agent relies on it.
-
-If proof is missing, do not remove it.
-
-## Platform Adapter Rules
-
-Adapters may emit different file layouts, but semantic coverage must match.
-
-Watch these risks:
-
-- Copilot may inline shared protocols and generated agent files.
-- Zed, IntelliJ, Hermes, and prompt-style adapters can under-generate bodies if they skip `AGENT_BODIES`.
-- Hermes-agent and Copilot should not emit unused `_shared` files unless generated files reference them.
-- Skill assets may be embedded or copied depending on platform; verify final `SKILL.md` still points to working refs/assets/scripts.
-
-Adapter changes need cross-platform checks, not only Copilot checks.
-
-## Verification Checklist
-
-Run only the commands needed for the change size, but do not skip parity checks after instruction architecture changes.
-
-```bash
-node scaffold/generate.mjs
-```
-
-For instruction source syntax:
-
-```bash
-node -e "import('./scaffold/definitions/agents.mjs')"
-node -e "import('./scaffold/definitions/bodies.mjs')"
-node -e "import('./scaffold/definitions/protocols.mjs')"
-node -e "import('./scaffold/definitions/prompts.mjs')"
-```
-
-For project validation:
-
-```bash
-node scripts/build.mjs
-npx tsc --noEmit
-npx biome check .
-```
-
-Prefer AI Kit wrappers when available:
-
-- `check({})` for typecheck and lint.
-- `test_run({})` for tests.
-- `blast_radius({ changed_files })` for impact.
-- `reindex({})` after source changes that affect indexed knowledge.
-
-Note: root Vitest config may exclude `scaffold/__tests__`. If scaffold tests do not run through `test_run`, use direct Node assertions or update test config intentionally.
-
-## Quality Review Questions
-
-Ask these before finalizing:
-
-- Does each agent know what to do, when to stop, and what output to return?
-- Can each subagent complete its task with only a dispatch envelope and local instructions?
-- Did optimization remove duplication without removing protocol coverage?
-- Are skills routed through metadata instead of duplicated in prose?
-- Are long details progressively disclosed through refs/assets/scripts?
-- Do all platform outputs carry equivalent agent bodies, protocols, skills, and prompts?
-- Did generated files change only because definitions/adapters changed?
-- Is every changed line tied to user value?
-
-## Common Failure Modes
-
-- Optimizing Copilot only and forgetting other platforms.
-- Removing `sharedProtocols` because body text got shorter, then losing FORGE/decision/compression behavior.
-- Adding local skill tables to agent bodies instead of updating metadata.
-- Creating many `HARD RULE` lines until none stand out.
-- Editing generated output and losing changes on next generate.
-- Forgetting to regenerate after changing definitions.
-- Deleting refs/assets/scripts that are rarely loaded but important when triggered.
-- Letting subagent templates grow into long checklists that lose tail instructions.
-
-## Terse Style Propagation
-
-When user requests terse/caveman communication, preserve technical substance and remove filler. Orchestrator must pass the style rule to subagents and require final outputs to follow it.
-
-Safe compression:
-
-- Drop filler, pleasantries, hedging, articles, and repeated setup.
-- Use fragments and short synonyms where meaning is clear.
-- Keep code blocks, tool names, protocol names, file paths, errors, security warnings, irreversible confirmations, and multi-step safety sequences exact.
-
-Pattern:
-
-```text
-[thing] [action] [reason]. [next step].
-```
-
-Do not apply style compression where ambiguity could cause unsafe action or incorrect implementation.