agentera 3.0.0-dev.13 → 3.0.0-dev.14

package/dist/capabilities/document/instructions.js

@@ -1,6 +1,4 @@
-// Source: skills/agentera/capabilities/document/instructions.md (relocated D65)
-// Markdown body lifted verbatim; the JSON literal below round-trips to byte-for-byte
-// equivalence with the deleted file (whitespace allowed to differ at line endings only).
-export const instructions = JSON.parse(String.raw `"# DOCUMENT\n\n**Documentation Origin: Knowledge Unified, Methodology Enforced, Notation Traced. Encode, Record, Archive**\n\nOwns the docs-first workflow: document intended behavior before tests and code. Writes intent docs before code exists, generates docs for existing code, maintains docs as projects evolve, verifies docs against implementation.\n\nTwo modes: **create** and **update**. Context-detected: no feature yet = intent-first; code exists = explore and generate.\n\n---\n\n## Visual identity\n\nGlyph: **▤** (protocol ref: SG8). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOne index file; writes individual doc files across the project.\n\n| Artifact | Purpose | Bootstrap |\n|----------|---------|-----------|\n| \u0060DOCS.md\u0060 | Canonical documentation contract, stored as \u0060.agentera/docs.yaml\u0060 unless mapped otherwise. Conventions, artifact mapping, and documentation index. | Created on first document run. |\n\nUse \u0060agentera describe --format json\u0060 and its \u0060artifact_schemas\u0060 entry for \u0060docs\u0060 to locate the active installed schema; use \u0060artifact_locations\u0060 or \u0060agentera query --list-artifacts --format json\u0060 for mapped artifact paths and raw-access boundaries. Do not search Agentera directories manually. The repository's existing \u0060.agentera/docs.yaml\u0060 shape provides the local structure when editing that artifact. Individual documentation files are written to their mapped locations.\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, prefer the CLI artifact-location contract from \u0060agentera describe --format json\u0060 or \u0060agentera query --list-artifacts --format json\u0060. It resolves \u0060.agentera/docs.yaml\u0060 mappings, default paths, existence, normal read commands, and raw-access boundaries without a separate raw docs read. Raw \u0060.agentera/docs.yaml\u0060 access is reserved for writing or validating the docs artifact itself, corruption diagnostics, or unavailable/incomplete CLI discovery. This applies to all artifact references in this capability, including cross-capability reads (VISION.md, .agentera/progress.yaml, .agentera/decisions.yaml, .agentera/health.yaml).\n\n### Contract values\n\nContract values are inlined where referenced. Visual tokens from protocol: severity arrows VT5-VT8, trend arrows VT12-VT13, progress bar VT18, inline separator VT16 (·), list item VT15 (▸), section divider VT14, flow/target VT17 (→). Skill glyph SG8 for the exit marker. Exit signals EX1-EX4 for the exit marker. Confidence scale CS1-CS5 for decision profile consumption.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference for ambiguous cases or cross-checking.\n\n---\n\n## docs.yaml shape\n\n\u0060\u0060\u0060yaml\nlast_audit: YYYY-MM-DD\nconventions:\n  doc_root: .\n  style: technical, concise\n  auto_gen: []\n  version_files: []\n  semver_policy:\n    feat: minor\n    fix: patch\n    docs/chore/test: no bump\nmapping:\n  - artifact: VISION.md\n    path: .agentera/vision.yaml\n    producers: [vision, build]\nindex:\n  - document: README\n    path: README.md\n    last_updated: YYYY-MM-DD\n    status: current\n\u0060\u0060\u0060\n\n---\n\n## Step 0: Detect context\n\nBefore artifact-backed work, use supported Agentera CLI state first. For final\ndocumentation or metadata synchronization, follow the closeout context startup\ncontract below before reading TODO, docs, changelog, or progress artifacts directly.\n\nDetermine what kind of documentation work is needed:\n\n1. Read DOCS.md (if exists) for current state\n2. Parse user request: specific target or broad \"write/update docs\"?\n3. Check codebase: does the feature exist in code?\n\n| Context | Approach |\n|---------|----------|\n| Feature doesn't exist yet, user wants to document intent | **Intent-first** (conversational) |\n| Code exists, docs don't | **Explore and generate** (autonomous) |\n| Docs exist, may be stale | **Update and verify** (audit-driven) |\n| Broad \"audit the docs\" / \"are docs up to date\" | **Full audit** |\n| No DOCS.md exists | **First-run survey** (convention detection) |\n\n---\n\n## Closeout context startup\n\nCloseout synchronization uses the existing state seam:\n\n\u0060\u0060\u0060bash\nagentera prime --context document --format json\n\u0060\u0060\u0060\n\nWhen the response includes \u0060closeout_context.source_contract.complete_for_closeout_context: true\u0060, use \u0060closeout_context\u0060 as the normal source for:\n\n- artifact mappings\n- version policy\n- TODO blockers\n- changelog and release boundary state\n- progress evidence\n- benchmark evidence or unavailable caveat\n- fallback commands\n- state caveats\n- raw-read policy\n- completeness and non-empty evidence flags\n\nDo not raw-read \u0060TODO.md\u0060, \u0060.agentera/docs.yaml\u0060, \u0060CHANGELOG.md\u0060, or \u0060.agentera/progress.yaml\u0060 merely to reconstruct those fields when the closeout context is complete. Raw artifacts are write targets or last-resort diagnostics, not normal closeout inputs.\n\nWhen closeout context is incomplete or caveated:\n\n1. Preserve every returned caveat, including stale app/profile state, compacted state, missing benchmark evidence, absent local tag/metadata, and no-publication/no-remote state.\n2. Run the listed \u0060closeout_context.fallback_commands\u0060 before any raw artifact read. Expected existing fallbacks are \u0060agentera todo --format json\u0060, \u0060agentera docs --format json\u0060, \u0060agentera progress --format json\u0060, \u0060agentera query changelog --format json\u0060, \u0060agentera query --list-artifacts --format json\u0060, and \u0060agentera decisions --format json\u0060 when listed.\n3. If fallback CLI state is still incomplete, raw reads may be used only as last-resort diagnostics or as explicit write targets after artifact path resolution.\n4. Never hide or reconstruct caveats while preparing docs, changelog, TODO, or progress closeout. Carry them into the final synchronization note.\n\nCloseout context does not approve publication, remote push, installed app refresh, profile refresh, vision edits, or objective-state edits. Treat those fields as recorded evidence or caveats only.\n\n### Decision satisfaction authority\n\nWhen documentation or closeout work touches decision satisfaction, agents may\nmark provisional satisfaction with evidence only. Document must not mark or\nimply user-confirmed final satisfaction; only the user confirms final\nsatisfaction. If decisions are compacted, missing satisfaction state, open,\nprovisional, or review-needed, preserve the caveat and review pressure in docs\nor closeout notes instead of reconstructing hidden outcomes or claiming\nautomation proved intent.\n\n---\n\n## First-run survey (convention detection)\n\nWhen DOCS.md doesn't exist, run a survey first. Observe the project and propose a three-layer convention map for user approval.\n\nStep markers: display \u0060── step N/5: verb\u0060 before each step.\nSteps: explore, propose, handle, audit, write.\n\n### Step 1: Explore structure\n\nDetect documentation conventions:\n\n1. **Doc root**: check docs/, doc/, documentation/, wiki/, or root. Default to root.\n2. **Existing docs**: README, CLAUDE.md, AGENTS.md, CONTRIBUTING.md, API docs, guides\n3. **Auto-generated docs**: TypeDoc, Storybook, OpenAPI/Swagger, GoDoc, Rustdoc, Javadoc. Record each with output path.\n4. **Style**: infer tone, structure patterns, formatting conventions from existing docs\n5. **Skill artifacts**: check \u0060.agentera/docs.yaml\u0060 mappings, root human artifacts, and \u0060.agentera/*.yaml\u0060 agent artifacts\n6. **Version files**: package.json, Cargo.toml, pyproject.toml, plugin.json, etc. Note files and current values. None found = omit versioning from DOCS.md.\n\n### Step 2: Propose conventions\n\nDraft three-layer \u0060.agentera/docs.yaml\u0060 from the artifact schema and observed repository conventions:\n\n1. **Conventions**: doc_root, style, auto_gen from observations. If version files found, populate \u0060version_files\u0060 and ask about semver policy. No version files = omit block.\n2. **Artifact mapping**: paths consistent with project's doc organization\n3. **Index**: all discovered docs (auto-generated = \u0060generated\u0060, existing = \u0060current\u0060)\n\nPresent for user approval.\n\n### Step 3: Handle existing artifacts\n\nIf artifacts exist at root but mapping places them elsewhere:\n\n1. List artifacts that would move\n2. Offer to relocate via \u0060git mv\u0060\n3. If declined, update mapping to match actual locations\n\n### Step 4: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\n- \"Tightening this up...\" · \"Cutting the filler first...\" · \"One more pass...\"\n\n### Step 5: Write DOCS.md\n\nWrite the approved convention map to \u0060.agentera/docs.yaml\u0060. After writing, proceed to the originally requested mode, or stop if the survey was the entire request.\n\nArtifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\n---\n\n## Intent-first mode (docs before code)\n\nDocs-first workflow: document what a feature SHOULD do before building. Docs become the spec.\n\nStep markers: display \u0060── step N/5: verb\u0060 before each step.\nSteps: understand, write, audit, update, suggest.\n\n### Step 1: Understand the intent\n\nBrief conversation (2-4 questions): what, who reads it, what format, what detail level.\n\nRead VISION.md for direction/audience and decision profile per protocol confidence scale (CS1-CS5) conventions for doc style preferences if they exist.\n\n### Step 2: Write the documentation\n\nWrite docs in the appropriate location: project-level (README, CLAUDE.md) to standard paths, feature docs to the project's docs directory, inline docs to source files.\n\n**Principles**: follow DOCS.md style conventions, infer details from existing docs. Write as intended steady state (evergreen, non-temporal). Primary audience first. Concrete examples. DRY across doc files.\n\nWhen presenting drafts, introduce what you wrote and why: what choices you made, what you left out on purpose, what you'd want feedback on. Don't just dump the doc.\n\nPresent draft for approval before writing.\n\n### Step 3: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\n- \"Tightening this up...\" · \"Cutting the filler first...\" · \"One more pass...\"\n\n### Step 4: Update DOCS.md\n\nAdd or update the relevant entry in DOCS.md:\n\n- Document name and path\n- Date written\n- Status: \u0060current\u0060\n\nOutput constraint: ≤15 words per index entry description.\n\nArtifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\n### Step 5: Suggest next steps\n\n- Feature docs: suggest ≡ plan to plan implementation\n- Standalone docs: suggest update mode later for verification\n\n---\n\n## Explore-and-generate mode (docs for existing code)\n\nCode exists, docs don't. Read codebase and generate.\n\nStep markers: display \u0060── step N/5: verb\u0060 before each step.\nSteps: explore, gaps, generate, audit, update.\n\n### Step 1: Explore\n\n1. Map directory structure, read dependency manifests\n2. Read existing docs to see what's already documented\n3. Read key source files: architecture, public APIs, patterns\n4. Read VISION.md, PROGRESS.md, DECISIONS.md, decision profile if they exist; use \u0060agentera decisions --format json\u0060 for normal decision context and carry returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure into documentation scope instead of raw-reading missing historical decision context.\n5. \u0060git log --oneline -20\u0060 for context\n\n**Exit-early stop condition**: If DOCS.md exists with coverage at 100% and no files have changed since the last document audit (\u0060git log --since\u0060 the last audit date in DOCS.md shows no changes), report exit signal \u0060complete\u0060 (EX1): documentation current, and stop.\n\n### Step 2: Identify gaps\n\nCompare what exists against what should be documented: README.md accuracy, CLAUDE.md/AGENTS.md presence, API docs, CLI docs with usage, configuration docs, architectural decision docs.\n\n### Step 3: Generate\n\nWrite docs for gaps, prioritized: (1) README, (2) CLAUDE.md, (3) API/CLI docs, (4) architecture docs. Follow DOCS.md style conventions.\n\nWhen presenting drafts, introduce what you wrote and why: what you learned from the code, what design choices the doc reflects, what you're less sure about. Don't just dump the doc.\n\nPresent drafts for approval.\n\n### Step 4: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\n- \"Tightening this up...\" · \"Cutting the filler first...\" · \"One more pass...\"\n\n### Step 5: Update DOCS.md\n\nCreate or update DOCS.md with all items. Edit specific YAML entries when updating status/dates. If DOCS.md doesn't exist, run first-run survey first.\n\nArtifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\n---\n\n## Update-and-verify mode (audit-driven)\n\nDocs exist but may be out of sync with implementation.\n\nStep markers: display \u0060── step N/6: verb\u0060 before each step.\nSteps: discover, verify, prose-enforce, report, audit, update.\n\n### Step 1: Discover\n\nIdentify all doc files: root (README, CLAUDE.md, etc.), directories (docs/, .github/), config comments. Read DOCS.md for current index. Track auto-generated docs as \u0060generated\u0060. Skip node_modules/, .git/, vendor/.\n\n### Step 2: Verify\n\nCheck each doc file on four dimensions:\n\n- **Gaps**: documented features/APIs/behaviors that don't exist in code\n- **Staleness**: changed signatures, removed features, outdated setup instructions\n- **Redundancies**: duplicated content across doc files\n- **Misalignments**: docs contradict actual code behavior\n\nFor each finding: quote the doc section, reference code location (file:line), explain the discrepancy.\n\n### Step 3: Doc-prose enforcement\n\nCheck all docs indexed in DOCS.md against the 3 self-audit rules:\n\n1. **Read DOCS.md index**: if DOCS.md is absent, run first-run survey to bootstrap it, then continue. Extract tracked docs from the \u0060index\u0060 list. Skip entries with \u0060generated\u0060 or \u0060missing\u0060 status.\n2. **For each doc**, read the file and check against the 3 rules:\n   - **Verbosity overrun**: entry word counts exceeding token budgets for the artifact's scope. Flag entries that exceed budget without compaction.\n   - **Abstraction creep**: sections lacking ≥1 concrete anchor (file path, line number, commit hash, metric value, identifier, direct quote). Flag entries that narrate concepts without evidence.\n   - **Filler accumulation**: scan for banned verbosity patterns: meta-commentary about writing, hedging qualifiers, redundant transitions, self-referential process narration, filler introductions, summary preambles, excessive justification. Flag entries containing banned patterns.\n3. **Surface \u0060[post-audit-flagged]\u0060 entries**: scan each doc for the \u0060[post-audit-flagged]\u0060 marker. Report any flagged entries as warning-level findings.\n4. **Report findings** at standard severity levels:\n   - **critical** (SF1): doc section contradicts code, or instructions that would cause user errors\n   - **warning** (SF2): verbosity above budgets, abstraction creep, accumulated filler patterns, pre-existing \u0060[post-audit-flagged]\u0060 markers\n   - **info** (SF3): minor style issues, single banned pattern in an otherwise clean entry\n\n### Step 4: Report and fix\n\nBy severity: ⇶ critical (VT5, causes user errors), ⇉ warning (VT6, causes confusion), ⇢ info (VT8, cosmetic). For each finding, offer to: fix the doc, file to TODO.md (code is wrong per the docs-first workflow), or skip.\n\n### Step 5: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\n- \"Tightening this up...\" · \"Cutting the filler first...\" · \"One more pass...\"\n\n### Step 6: Update DOCS.md\n\nUpdate the index with:\n\n- ▸ Audit date\n- ▸ Status changes (■ current / ▣ stale / □ missing)\n- ▸ Coverage numbers\n- ▸ Audit log entry\n\n---\n\n## Safety rails\n\n<critical>\n- NEVER modify documentation without explicit user approval. Present drafts and get confirmation.\n- NEVER update docs to match broken code. Per the docs-first workflow, if code diverges from docs, the code is wrong. Document the divergence as an issue in TODO.md.\n- NEVER write temporal documentation (changelogs, \"we recently added...\"). Write as the intended steady state, evergreen and non-temporal.\n- NEVER duplicate information across doc files. Keep it DRY: reference, don't repeat.\n- NEVER write generic filler documentation. Every sentence should be specific to this project. If there's nothing useful to say about a section, omit it.\n- NEVER skip the verification step in update mode. Every doc claim must be checked against code.\n- NEVER auto-generate documentation without reading the code it describes. Understanding precedes documentation.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060▤ document · <status>\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 (VT15) bullet details below the summary.\n\n- **complete** (EX1): Documentation was written, updated, or audited successfully; DOCS.md is current, and all drafted content received user approval before writing.\n- **flagged** (EX2): Documentation tasks completed but gaps remain (e.g., some doc files could not be verified against code, coverage is partial, or the audit found issues that were logged but not yet fixed).\n- **stuck** (EX3): Cannot proceed because a user approval step was declined, a required artifact (VISION.md, source code) is missing or inaccessible, or a contradicting doc-vs-code situation requires a decision the capability should not make autonomously.\n- **waiting** (EX4): The documentation intent is unclear: the target audience, format, or scope of what to document was not specified and cannot be inferred from the codebase or DOCS.md.\n\n---\n\n## Cross-capability integration\n\nDocument is part of a twelve-capability suite. It is the documentation layer and owns the docs-first workflow.\n\n### Document feeds plan (docs-first workflow)\n\nIn the strict docs-first workflow, document writes intent docs first, then plan breaks them into implementation tasks. The docs become the spec that plan's acceptance criteria verify against. When the plan includes documentation tasks, document handles them.\n\n### Document feeds build\n\nWhen document writes intent-first docs for a feature that doesn't exist yet, build implements code to match those docs. The docs are the target state; if code diverges from docs, the code is wrong per the docs-first workflow.\n\n### Document is informed by audit\n\nHEALTH.md findings may include documentation gaps. Audit's architecture alignment dimension can surface undocumented modules or APIs.\n\n### Document is informed by vision\n\nVISION.md sets the project's direction and audience. Document reads it to understand who the documentation is for and what tone to use.\n\n### Document is informed by profile\n\nThe decision profile calibrates documentation style: the user's preferences for detail level, tone, format, and which docs they consider essential.\n\n### Document reads design output\n\nDESIGN.md provides visual identity context that document respects when generating user-facing documentation, ensuring docs match the project's declared aesthetic and voice.\n\n### Document feeds profile\n\nDocumentation decisions (what to document, how, at what depth) are signal for profile's extraction scripts.\n\n---\n\n## Getting started\n\n### Docs-first workflow: document before building\n\n1. ▤ document: write intent docs for the feature (what it should do, how it should work)\n2. ≡ plan: plan the implementation with acceptance criteria derived from the docs\n3. ⧉ build: build to match the docs\n4. ▤ document: update mode to verify docs still match implementation\n\n### Document existing code\n\n1. ▤ document: explore-and-generate mode reads the codebase and writes docs for what exists\n2. Review generated docs for accuracy and completeness\n\n### Audit and maintain\n\n1. ▤ document: update-and-verify mode checks all docs against code\n2. Fix findings or file code issues to TODO.md\n\n### Project bootstrap\n\n1. ⛥ vision: create VISION.md (strategic direction)\n2. ▤ document: create README.md, CLAUDE.md, AGENTS.md (project documentation)\n3. ≡ plan: plan first features\n4. ⧉ build: start building\n"`);
+// Markdown instructions served via agentera prime --context document --format json
+export const instructions = JSON.parse(String.raw `"# DOCUMENT\n\n**Documentation Origin: Knowledge Unified, Methodology Enforced, Notation Traced. Encode, Record, Archive**\n\nOwns the docs-first workflow (DTC: Document, Test, Code): document intended behavior before tests and code, generate docs for existing code, maintain docs as projects evolve, verify docs against implementation.\n\nGlyph: **▤** (protocol ref: SG8). Used in the mandatory exit marker.\n\nTwo modes: **create** and **update**. Context-detected: no feature yet = intent-first; code exists = explore and generate.\n\nLean on \u0060closeout_context.source_contract\u0060 from \u0060agentera prime --context document --format json\u0060 for closeout synchronization startup. Do not re-encode its machine-readable rules in prose. Artifact path resolution is owned by SKILL.md.\n\n---\n\n## State artifacts\n\nDocument writes and reads the docs index and individual doc files across the project.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060docs\u0060 | produces_and_consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060todo\u0060 | produces_and_consumes | \u0060TODO.md\u0060 |\n| \u0060changelog\u0060 | consumes | \u0060CHANGELOG.md\u0060 |\n| \u0060vision\u0060 | consumes | \u0060.agentera/vision.yaml\u0060 |\n| \u0060progress\u0060 | consumes | \u0060.agentera/progress.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060health\u0060 | consumes | \u0060.agentera/health.yaml\u0060 |\n| \u0060design\u0060 | consumes | \u0060DESIGN.md\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n\n### docs.yaml shape\n\n\u0060\u0060\u0060yaml\nlast_audit: YYYY-MM-DD\nconventions:\n  doc_root: .\n  style: technical, concise\n  auto_gen: []\n  version_files: []\n  semver_policy:\n    feat: minor\n    fix: patch\n    docs/chore/test: no bump\nmapping:\n  - artifact: VISION.md\n    path: .agentera/vision.yaml\n    producers: [vision, build]\nindex:\n  - document: README\n    path: README.md\n    last_updated: YYYY-MM-DD\n    status: current\n\u0060\u0060\u0060\n\n### Closeout context\n\nStart from \u0060agentera prime --context document --format json\u0060. When \u0060closeout_context.source_contract.complete_for_closeout_context\u0060 is true, use it for artifact mappings, version policy, TODO blockers, changelog boundary, progress evidence, and benchmark evidence. If incomplete, preserve every caveat and run the listed \u0060fallback_commands\u0060 before any raw artifact read. Raw artifacts are write targets or last-resort diagnostics, not normal closeout inputs.\n\n---\n\n## Workflow phases\n\nMode-split: detect context first, then run the matching workflow.\n\n| Context | Mode |\n|---------|------|\n| No \u0060.agentera/docs.yaml\u0060 exists | First-run survey |\n| Feature doesn't exist yet, user wants to document intent | Intent-first |\n| Code exists, docs don't | Explore-and-generate |\n| Docs exist, may be stale | Update-and-verify |\n| Broad \"audit the docs\" / \"are docs up to date\" | Update-and-verify |\n\nFor final documentation or metadata synchronization, follow the closeout context startup contract above before reading TODO, docs, changelog, or progress artifacts directly.\n\n### First-run survey (convention detection)\n\nStep markers: display \u0060── step N/3: verb\u0060 before each step.\nSteps: explore, propose, write.\n\n### Step 1: Explore structure\n\nDetect documentation conventions:\n\n1. **Doc root**: check docs/, doc/, documentation/, wiki/, or root. Default to root.\n2. **Existing docs**: README, AGENTS.md, CONTRIBUTING.md, API docs, guides\n3. **Auto-generated docs**: TypeDoc, Storybook, OpenAPI/Swagger, GoDoc, Rustdoc, Javadoc. Record each with output path.\n4. **Style**: infer tone, structure patterns, formatting conventions from existing docs\n5. **Version files**: package.json, Cargo.toml, pyproject.toml, etc. Note files and current values. None found = omit versioning from \u0060.agentera/docs.yaml\u0060.\n\n### Step 2: Propose conventions\n\nDraft \u0060.agentera/docs.yaml\u0060 from the artifact schema and observed repository conventions:\n\n1. **Conventions**: doc_root, style, auto_gen from observations. If version files found, populate \u0060version_files\u0060 and ask about semver policy. No version files = omit block.\n2. **Artifact mapping**: paths consistent with project's doc organization\n3. **Index**: all discovered docs (auto-generated = \u0060generated\u0060, existing = \u0060current\u0060)\n\nPresent for user approval. If artifacts exist at root but mapping places them elsewhere, offer to relocate via \u0060git mv\u0060; if declined, update mapping to match actual locations.\n\n### Step 3: Write docs.yaml\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\nWrite the approved convention map to \u0060.agentera/docs.yaml\u0060. After writing, proceed to the originally requested mode, or stop if the survey was the entire request.\n\n### Intent-first mode (docs before code)\n\nDocs-first workflow: document what a feature SHOULD do before building. Docs become the spec.\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: understand, write, update, suggest.\n\n### Step 1: Understand the intent\n\nBrief conversation (2-4 questions): what, who reads it, what format, what detail level.\n\nRead \u0060.agentera/vision.yaml\u0060 for direction/audience. Use decision profile per protocol confidence scale (CS1-CS5) for doc style preferences if available.\n\n### Step 2: Write the documentation\n\nWrite docs in the appropriate location: project-level (README, AGENTS.md) to standard paths, feature docs to the project's docs directory, inline docs to source files.\n\n**Principles**: follow \u0060.agentera/docs.yaml\u0060 style conventions, infer details from existing docs. Write as intended steady state (evergreen, non-temporal). Primary audience first. Concrete examples. DRY across doc files.\n\nWhen presenting drafts, introduce what you wrote and why: what choices you made, what you left out on purpose, what you'd want feedback on. Present draft for approval before writing.\n\n### Step 3: Update docs index\n\nAdd or update the relevant entry in \u0060.agentera/docs.yaml\u0060:\n\n- Document name and path\n- Date written\n- Status: \u0060current\u0060\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n### Step 4: Suggest next steps\n\n- Feature docs: suggest ≡ plan to plan implementation\n- Standalone docs: suggest update-and-verify mode later for verification\n\n### Explore-and-generate mode (docs for existing code)\n\nCode exists, docs don't. Read codebase and generate.\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: explore, gaps, generate, update.\n\n### Step 1: Explore\n\n1. Map directory structure, read dependency manifests\n2. Read existing docs to see what's already documented\n3. Read key source files: architecture, public APIs, patterns\n4. Read \u0060.agentera/vision.yaml\u0060 for direction/audience. Use \u0060agentera state progress --format json\u0060 and \u0060agentera state decisions --format json\u0060 for recent project context; carry returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure into documentation scope instead of raw-reading missing historical context.\n5. \u0060git log --oneline -20\u0060 for context\n\n**Exit-early stop condition**: If \u0060.agentera/docs.yaml\u0060 exists with coverage at 100% and no files have changed since the last document audit (\u0060git log --since\u0060 the last audit date shows no changes), report exit signal \u0060complete\u0060 (EX1): documentation current, and stop.\n\n### Step 2: Identify gaps\n\nCompare what exists against what should be documented: README.md accuracy, AGENTS.md presence, API docs, CLI docs with usage, configuration docs, architectural decision docs.\n\n### Step 3: Generate\n\nWrite docs for gaps, prioritized: (1) README, (2) AGENTS.md, (3) API/CLI docs, (4) architecture docs. Follow \u0060.agentera/docs.yaml\u0060 style conventions.\n\nWhen presenting drafts, introduce what you wrote and why: what you learned from the code, what design choices the doc reflects, what you're less sure about. Present drafts for approval.\n\n### Step 4: Update docs index\n\nCreate or update \u0060.agentera/docs.yaml\u0060 with all items. Edit specific YAML entries when updating status/dates. If \u0060.agentera/docs.yaml\u0060 doesn't exist, run first-run survey first.\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n### Update-and-verify mode (audit-driven)\n\nDocs exist but may be out of sync with implementation.\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: discover, verify, report, update.\n\n### Step 1: Discover\n\nIdentify all doc files: root (README, AGENTS.md, etc.), directories (docs/, .github/), config comments. Read \u0060.agentera/docs.yaml\u0060 for current index. Track auto-generated docs as \u0060generated\u0060. Skip node_modules/, .git/, vendor/.\n\n### Step 2: Verify\n\nCheck each doc file on two dimensions — content accuracy and prose quality.\n\n**Content accuracy** (per doc file):\n\n- **Gaps**: documented features/APIs/behaviors that don't exist in code\n- **Staleness**: changed signatures, removed features, outdated setup instructions\n- **Redundancies**: duplicated content across doc files\n- **Misalignments**: docs contradict actual code behavior\n\nFor each finding: quote the doc section, reference code location (file:line), explain the discrepancy.\n\n**Prose quality**: run \u0060agentera check lint --artifact docs --file <path>\u0060 on each tracked doc. Report any \u0060[post-audit-flagged]\u0060 markers from prior runs. Skip entries with \u0060generated\u0060 or \u0060missing\u0060 status.\n\n### Step 3: Report and fix\n\nSurface findings at standard severity levels (protocol: SF1-SF3):\n\n- **critical** (SF1): doc section contradicts code, or instructions that would cause user errors\n- **warning** (SF2): verbosity above budgets, abstraction creep, accumulated filler patterns, pre-existing \u0060[post-audit-flagged]\u0060 markers\n- **info** (SF3): minor style issues, single banned pattern in an otherwise clean entry\n\nFor each finding, offer to: fix the doc, file to TODO.md (code is wrong per the docs-first workflow), or skip.\n\n### Step 4: Update docs index\n\nUpdate \u0060.agentera/docs.yaml\u0060 with:\n- Audit date\n- Status changes (■ current / ▣ stale / □ missing)\n- Coverage numbers\n\n**Before writing**, run \u0060agentera check lint --artifact docs --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n---\n\n## Safety rails\n\n<critical>\n- MUST NOT write or modify documentation without explicit user approval. Present drafts and get confirmation.\n- MUST NOT update docs to match broken code. Per the docs-first workflow, if code diverges from docs, the code is wrong. Document the divergence as an issue in TODO.md.\n- MUST NOT write temporal documentation (changelogs, \"we recently added...\"). Write as the intended steady state: evergreen and non-temporal.\n- MUST NOT duplicate information across doc files. Keep it DRY: reference, don't repeat.\n- MUST NOT write generic filler documentation. Every sentence MUST be specific to this project. If there's nothing useful to say about a section, omit it.\n- MUST NOT skip the verification step in update mode. Every doc claim MUST be checked against code.\n- MUST NOT auto-generate documentation without reading the code it describes. Understanding precedes documentation.\n- MUST NOT mark or imply user-confirmed decision satisfaction — only the user confirms final satisfaction.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060▤ document · <status>\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): Documentation was written, updated, or audited successfully; docs index is current, and all drafted content received user approval before writing.\n- **flagged** (EX2): Documentation tasks completed but gaps remain (e.g., some doc files could not be verified against code, coverage is partial, or the audit found issues that were logged but not yet fixed).\n- **stuck** (EX3): Cannot proceed because a user approval step was declined, a required artifact is missing or inaccessible, or a contradicting doc-vs-code situation requires a decision the capability should not make autonomously.\n- **waiting** (EX4): The documentation intent is unclear: the target audience, format, or scope of what to document was not specified and cannot be inferred from the codebase or the docs index.\n\n---\n\n## Cross-capability integration\n\nDocument is part of a twelve-capability suite. It is the documentation layer and owns the docs-first workflow.\n\n### Feeds\n\n- **≡ plan**: In the docs-first workflow, document writes intent docs first, then plan breaks them into implementation tasks. The docs become the spec that plan's acceptance criteria verify against. When the plan includes documentation tasks, document handles them.\n- **⧉ build**: When document writes intent-first docs for a feature that doesn't exist yet, build implements code to match those docs. The docs are the target state; if code diverges from docs, the code is wrong per the docs-first workflow.\n- **♾ profile**: Documentation decisions (what to document, how, at what depth) are signal for profile's extraction scripts.\n\n### Informed by\n\n- **❈ discuss**: \u0060.agentera/decisions.yaml\u0060 explains why things are the way they are. Document reads it to understand project context.\n- **⛶ audit**: Health findings may include documentation gaps. Audit's architecture alignment dimension can surface undocumented modules or APIs.\n- **⛥ vision**: \u0060.agentera/vision.yaml\u0060 sets the project's direction and audience. Document reads it to understand who the documentation is for and what tone to use.\n- **◰ design**: \u0060DESIGN.md\u0060 provides visual identity context that document respects when generating user-facing documentation, ensuring docs match the project's declared aesthetic and voice.\n- **♾ profile**: The decision profile calibrates documentation style: the user's preferences for detail level, tone, format, and which docs they consider essential.\n\n### Getting started\n\n**Docs-first workflow**: document before building.\n1. ▤ document: write intent docs for the feature (what it should do, how it should work)\n2. ≡ plan: plan the implementation with acceptance criteria derived from the docs\n3. ⧉ build: build to match the docs\n4. ▤ document: update-and-verify mode to verify docs still match implementation\n\n**Document existing code**: explore-and-generate mode reads the codebase and writes docs for what exists. Review generated docs for accuracy and completeness.\n\n**Project bootstrap**: ⛥ vision → ▤ document (README, AGENTS.md) → ≡ plan → ⧉ build.\n"`);
 export default instructions;
 //# sourceMappingURL=instructions.js.map

package/dist/capabilities/document/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/document/instructions.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,y9sBAAy9sB,CAAC,CAAC;AACphtB,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/document/instructions.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,ynfAAynf,CAAC,CAAC;AACprf,eAAe,YAAY,CAAC"}

package/dist/capabilities/optimize/instructions.js

@@ -1,6 +1,5 @@
-// Source: skills/agentera/capabilities/optimize/instructions.md (relocated D65)
-// Markdown body lifted verbatim; the JSON literal below round-trips to byte-for-byte
-// equivalence with the deleted file (whitespace allowed to differ at line endings only).
-export const instructions = JSON.parse(String.raw `"# OPTIMIZE\n\n**Objective Pursuit: Targeted Iterative Measurement. Experiment, Record, Advance.**\n\nMetric-driven optimization: improve any measurable property one experiment at a time. User defines the objective, agent writes an eval harness, harness becomes the immutable judge. Improve + pass regression = keep; everything else is discarded.\n\nEach invocation = one experiment. \u0060/loop\u0060 handles recurrence.\n\n---\n\n## Visual identity\n\nGlyph: **⎘** (protocol ref: SG7). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nThree artifacts per objective, under \u0060.agentera/optimize/<objective-name>/\u0060, bootstrapped if absent.\n\n| Artifact | Purpose | Bootstrap |\n|----------|---------|-----------|\n| \u0060.agentera/optimize/<objective-name>/objective.yaml\u0060 | What we're optimizing, why, how we measure it, and what \"done\" looks like. | Via inline brainstorm session with the user (see below). |\n| \u0060.agentera/optimize/<objective-name>/harness\u0060 | Eval script that measures the metric. Locked after user approval. | Written by the agent during brainstorm, approved by the user. |\n| \u0060.agentera/optimize/<objective-name>/experiments.yaml\u0060 | Log of every experiment: what was tried, what the metric said, kept or discarded. | First experiment entry in YAML form. |\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, check if \u0060.agentera/docs.yaml\u0060 exists. If it has an Artifact Mapping section, use the path specified for each canonical filename. If \u0060.agentera/docs.yaml\u0060 doesn't exist or has no mapping for a given artifact, use the default layout: TODO.md, CHANGELOG.md, and DESIGN.md at the project root; canonical VISION.md at \u0060.agentera/vision.yaml\u0060; other agent-facing artifacts at \u0060.agentera/*.yaml\u0060. This applies to all artifact references in this capability, including cross-capability reads (\u0060.agentera/decisions.yaml\u0060). objective.yaml and experiments.yaml are NOT resolved via the docs.yaml mapping; they always live under \u0060.agentera/optimize/<objective-name>/\u0060 for whichever objective is active.\n\n### Contract\n\nBefore starting, read \u0060references/contract.md\u0060 (at v2 skill location \u0060skills/agentera/references/contract.md\u0060) for authoritative values: token budgets, severity levels, format contracts, and other shared conventions referenced in the steps below. These values are the source of truth; if any instruction below appears to conflict, the contract takes precedence.\n\n### Benchmark context source contract\n\nFor benchmark-oriented optimization work, start from:\n\n\u0060\u0060\u0060bash\nagentera prime --context optimize --format json\n\u0060\u0060\u0060\n\nUse \u0060benchmark_context\u0060 before direct retained startup benchmark file access. If \u0060benchmark_context.source_contract.complete_for_benchmark_context\u0060 is true, do not read \u0060latest-report.json\u0060, \u0060latest-report.md\u0060, or \u0060runs.jsonl\u0060 during normal Optimize startup. Use the bounded fields in \u0060benchmark_context.latest_report\u0060, \u0060benchmark_context.history_summary\u0060, \u0060benchmark_context.runtime_coverage\u0060, \u0060benchmark_context.state_access_metrics\u0060, \u0060benchmark_context.token_impact\u0060, \u0060benchmark_context.comparison\u0060, \u0060benchmark_context.recommendation\u0060, and \u0060benchmark_context.manual_refresh\u0060 instead.\n\nIf benchmark_context is incomplete, follow \u0060benchmark_context.fallback_commands\u0060 and \u0060benchmark_context.manual_refresh\u0060 first. Direct reads of retained benchmark files are last-resort diagnostics only, and must preserve the context caveats rather than reconstructing hidden state. Never run \u0060mage bench:startupState\u0060 automatically; it is manual-only.\n\nWhen reporting benchmark evidence, preserve caveats about manual-only execution, missing or malformed retained evidence, empty local history, runtime coverage degradation, missing token estimates, non-comparable previous rows, and privacy boundaries. Do not expose raw transcripts, raw corpus files, raw intermediates, raw runtime store paths, raw session IDs, private salts, generated salted hashes, raw benchmark report bodies, or full local benchmark paths.\n\n### objective.yaml\n\nEvergreen. Created via brainstorm on first run, refined only when the user explicitly asks. Outside those two cases, the agent reads it but never writes it. Typical structure:\n\n\u0060\u0060\u0060yaml\ntarget: Optimization target name\nstatus: active\nobjective: >-\n  Precise metric, current value, and target value, for example reduce p95\n  latency of /api/search from 320ms to under 100ms.\nwhy: >-\n  What changes when the target is hit, who benefits, and what tradeoffs matter.\nmeasurement:\n  command: .agentera/optimize/<objective-name>/harness\n  metric: p95_latency_ms\n  direction: lower\n  baseline: 320\n  target: 100\n  budget:\n    runs: 5\n    time_limit: 10m\nconstraints:\n  - Existing tests must pass.\n  - Public API must not change.\nscope:\n  included: [api/search]\n  excluded: [public_api]\n\u0060\u0060\u0060\n\nThe objective must be precise enough to measure, constraints clear enough to enforce, and scope defined enough to prevent wandering.\n\nFixed budgets are part of the measurement contract, not experiment strategy. Keep them in objective.yaml and the locked harness. Do not store budget state in root artifacts, registries, symlinks, or DOCS.md mappings. experiments.yaml records the budget actually used only when that evidence matters to interpret the result.\n\n### \u0060.agentera/optimize/<objective-name>/harness\u0060\n\nScript that measures the metric and outputs structured JSON. Written during brainstorm, approved by the user, then **locked**. Never modified during optimization cycles.\n\nWraps the project's own tooling (test runners, benchmarks, linters) and translates output into a consistent format. The project's tooling is the source of truth.\n\n**Before writing a harness**, inspect the project's existing test, benchmark, lint, or measurement commands. The Agentera app currently ships only the shared contract reference, so harness specifics come from project tooling and the objective's measurement fields.\n\n**Output contract** (minimal):\n\n\u0060\u0060\u0060json\n{\"metric\": <number>, \"direction\": \"higher\"|\"lower\"}\n\u0060\u0060\u0060\n\n**Output contract** (with optional fields for richer signal):\n\n\u0060\u0060\u0060json\n{\"metric\": 85.5, \"direction\": \"higher\", \"unit\": \"%\", \"detail\": \"42/50 tests passing\", \"breakdown\": [{\"name\": \"unit\", \"value\": 95.0}, {\"name\": \"integration\", \"value\": 60.0}]}\n\u0060\u0060\u0060\n\nThe harness is the **immutable ground truth**, separating measurement from optimization. If wrong, the user must explicitly ask to rebuild it.\n\n### experiments.yaml\n\nWhen presenting experiment results, open with your interpretation of what happened before the structured data. \"Here's what I tried and what it told us\"; then the metrics table backs it up. Call out surprises, dead ends, and what the result changes about the approach.\n\n\u0060\u0060\u0060yaml\nexperiments:\n  - number: N\n    timestamp: YYYY-MM-DD HH:MM\n    hypothesis: What we expected to improve and why.\n    method: The approach taken to test the hypothesis.\n    change: One-line summary of the code change.\n    metric:\n      before: 320\n      after: 250\n      direction: lower\n      verdict: better\n    regression: pass\n    status: kept\n    commit: <hash>\n    inspiration: External source, if any.\n    conclusion: What the experiment taught.\n    next: What the result suggests trying next.\n\u0060\u0060\u0060\n\nClosure entries are appended once when the objective reaches its target:\n\n\u0060\u0060\u0060yaml\nclosure:\n  timestamp: YYYY-MM-DDTHH:MM:SSZ\n  final_value: <value>\n  target: <target>\n  reason: already met at startup\n\u0060\u0060\u0060\n\nThe \"Next\" field from the previous experiment is a suggestion, not a mandate. Re-evaluate fresh each cycle based on the full experiment history.\n\n### Experiment history analyzer contract\n\n\u0060npx -y agentera experiments\u0060 is the read-only summary layer for rich experiments.yaml records. It must inspect the active objective directory only. The command never creates root objective artifacts, registries, symlinks, DOCS.md fixed mappings, or sidecar ledgers.\n\n---\n\n## Brainstorm: bootstrapping or refining the objective\n\nThis runs in two situations:\n\n1. **objective.yaml doesn't exist**: the first time optimize runs on a project\n2. **User explicitly asks** to refine the objective (e.g., \"change the target\", \"update objective.yaml\")\n\nIn all other cases, skip straight to the cycle.\n\n### How the brainstorm works\n\nThe sharp colleague figuring out what to optimize. One question at a time, push for precision, push back on vague targets. Call out when an objective is too fuzzy to measure or when constraints are missing.\n\n1. **Objective**: \"What metric, current value, target?\" If code exists, run existing test/bench/lint commands first.\n2. **Motivation**: \"Why does this matter? What breaks at current value? What's possible at target?\"\n3. **Constraints**: \"What must NOT break? Off-limits files? Resource limits?\" If a decision profile exists, propose constraints from it.\n4. **Scope**: \"Which parts to focus on? Where are the biggest gains?\" Read codebase to propose informed boundaries.\n5. **Pre-write self-audit**: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n6. **Write objective.yaml**: synthesize into a precise charter. Write to \u0060.agentera/optimize/<objective-name>/objective.yaml\u0060. Present for approval.\n7. **Write the eval harness**: use the project's own tooling and the objective's measurement fields. Write \u0060.agentera/optimize/<objective-name>/harness\u0060 so it outputs JSON with at least \u0060metric\u0060 and \u0060direction\u0060. Present, explain, get approval, run once to establish baseline.\n\nArtifact writing follows contract Artifact Writing Conventions: banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\nWhen **refining**, read current objective.yaml, show proposed changes with rationale, get confirmation. If the harness changes, the user must approve the new version. After brainstorm, proceed to experiment 1.\n\n---\n\n## The cycle\n\nSkill introduction: \u0060─── ⎘ optimize · experiment N ───\u0060\n\nStep markers: display \u0060── step N/8: verb\u0060 before each step.\nSteps: orient, analyze, hypothesize, implement, measure, decide, audit, log.\n\n### Step 1: Orient\n\n**Benchmark context**: for benchmark-oriented work, use \u0060benchmark_context\u0060 from \u0060agentera prime --context optimize --format json\u0060 before direct retained benchmark files. Raw benchmark file reads are last-resort diagnostics.\n\n**Active-objective inference**: before reading any per-objective artifact, determine which objective is active by inspecting \u0060.agentera/optimize/\u0060:\n\n- If no objective subdirectories exist, keep the existing new-objective path: run the brainstorm.\n- For each objective subdirectory with an objective.yaml, classify it as closed before any active selection when \u0060status: closed\u0060. Do not reopen closed objectives.\n- If the user explicitly names a closed objective, load its objective.yaml and experiments.yaml read-only for context, summarize that it is closed, and ask before defining successor work.\n- If one or more objective subdirectories exist and all are closed, ask the user for a successor objective.\n- If only one non-closed subdirectory exists, use it.\n- If multiple non-closed subdirectories exist, run \u0060git log -1 --format=%aI -- .agentera/optimize/<name>/experiments.yaml\u0060 for each and pick the one with the most recent modification timestamp.\n- If the result is ambiguous, ask the user to specify the active objective by name.\n\nAll subsequent references to objective.yaml, experiments.yaml, and harness refer to the files under \u0060.agentera/optimize/<active-objective-name>/\u0060.\n\n1. **experiments.yaml**: last 5 experiments only (check for plateau patterns)\n2. **objective.yaml**: the metric, target, constraints, and scope\n3. **Decision profile**: read \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 directly when it exists. Apply confidence thresholds per contract profile consumption conventions. If missing, proceed without persona grounding but flag it.\n4. **Project discovery** (experiment 1 or when unfamiliar): map directory structure within scope, read dependency manifests, and read README.md, CLAUDE.md, AGENTS.md.\n5. \u0060git log --oneline -20\u0060 for recent changes\n\nBefore experimenting: in your response, list the current baseline, target, status, and constraints from objective.yaml.\n\n**Objective closure procedure**: when closing an objective, update objective.yaml with canonical closed state: \u0060status: closed\u0060, \u0060closed_at: <ISO-8601 UTC timestamp>\u0060, \u0060final_value: <value>\u0060, \u0060target: <target>\u0060, and \u0060reason: <reason>\u0060. Append one experiments.yaml closure entry. Do not append duplicates.\n\n**Exit-early stop condition**: If objective.yaml or experiments.yaml evidence shows the target is already met and the objective is not already closed, run the objective closure procedure with reason \u0060already met at startup\u0060, report exit signal \u0060complete: objective achieved\u0060, and stop before Analyze.\n\n### Step 2: Analyze\n\nRun two things:\n\n**2a. Experiment history analysis**: if experiments.yaml has prior entries, run:\n\n\u0060\u0060\u0060bash\nnpx -y agentera experiments\n\u0060\u0060\u0060\n\nOutputs recent experiment status counts, metric deltas, conclusions, and next-step notes.\n\n**2b. Current metric**: run the eval harness to get the baseline for this experiment:\n\n\u0060\u0060\u0060bash\nchmod +x .agentera/optimize/<objective-name>/harness && .agentera/optimize/<objective-name>/harness\n\u0060\u0060\u0060\n\nParse the JSON output. Record the current metric as the baseline.\n\n**Plateau detection**: if \u0060plateau_detected: true\u0060 (no improvement in 3+ experiments), flag explicitly. Consider a radically different approach, ⬚ research, or escalate to the user.\n\n### Step 3: Hypothesize\n\nFormulate a single, focused hypothesis.\n\nEffort-bias check: if one hypothesis took more effort to construct, reset before selection. Choose by experiment history, expected metric impact, risk, constraints, and smallest falsifiable test; construction effort is not evidence.\n\n1. **Review history**: what's been tried, what worked, what failed?\n2. **Seek inspiration**: for non-trivial domains, 2-3 targeted web queries for techniques, libraries, or patterns.\n3. **Formulate**: \"I expect [change] to improve the metric because [reasoning].\" Must be falsifiable.\n\nBe conservative early; escalate if conservative approaches plateau.\n\n### Step 4: Implement\n\n**Pre-spawn Git commit**: before creating the worktree, commit any pending artifact changes so the subagent branches from current state.\n\n1. Run \u0060git status --porcelain\u0060. If empty, skip to spawn.\n2. Stage only the artifact files this session wrote.\n3. Commit with \u0060chore(optimize): checkpoint before worktree dispatch\u0060. Do not pass \u0060--no-verify\u0060.\n4. If pre-commit hooks reject the commit: fix and retry. If retry also fails, abort the spawn.\n\n**Stale-base awareness**: some harnesses create the worktree branch from \u0060origin/main\u0060 rather than local \u0060HEAD\u0060. Before spawning, run \u0060git rev-list --count origin/main..HEAD\u0060. If the count is greater than zero, the worktree will be based on a stale commit. Proceed with spawn, but in Step 5 do NOT merge the worktree branch: fetch the diff and apply it to the main checkout. Re-run the eval harness in the main checkout.\n\nRuntime subagent mechanisms:\n\n| Runtime | Substrate | Limitation |\n|---------|-----------|------------|\n| Claude Code | Task tool with worktree-aware prompt | Native in-session spawn. |\n| OpenCode | \u0060@<capability>\u0060 descriptors from \u0060~/.config/opencode/agents/*.md\u0060 or a host Task subagent | Same working tree unless this step explicitly creates and targets a manual git worktree. |\n| Codex CLI | \u0060~/.codex/agents/*.toml\u0060 descriptors plus \u0060[agents]\u0060 limits | Agentera setup installs descriptor files; do not write legacy \u0060[agents.<name>]\u0060 config blocks. |\n| Copilot CLI | User-driven \u0060/fleet\u0060 or equivalent host action | No guaranteed programmatic in-session spawn. |\n\nNever spawn workers by running unsupported capability-name CLI commands such as \u0060agentera optimize\u0060; use the runtime-native subagent surface with the experiment prompt below.\n\nSpawn an implementation sub-agent in a worktree (\u0060isolation: \"worktree\"\u0060) with:\n\n- The hypothesis from step 3\n- Relevant context files (objective.yaml, recent experiments, source files being modified)\n- Clear constraint: implement the hypothesis and nothing else\n\n\u0060\u0060\u0060\nYou are implementing one optimization experiment for [project].\n\n## Hypothesis\n[The hypothesis]\n\n## Context\n- Current metric: [value] ([unit])\n- Target: [target value]\n- Scope: [files/modules in scope from objective.yaml]\n\n## Constraints\n- Implement ONLY what the hypothesis describes. No scope creep.\n- Do NOT modify the eval harness at .agentera/optimize/<objective-name>/harness.\n- Do NOT modify objective.yaml or experiments.yaml.\n- Follow existing code patterns and conventions.\n- Read the files you are modifying before changing them.\n- Keep the change as small as possible while testing the hypothesis.\n- If you encounter a bug unrelated to your task, note it but do not fix it.\n\u0060\u0060\u0060\n\nWait for the implementation agent to complete before proceeding.\n\n### Step 5: Measure\n\nAfter implementation completes, run two checks in sequence:\n\n**5a. Regression check**: run the project's existing test/build/lint suite. If the regression check fails, **stop here**. The experiment is discarded. Do not run the eval harness. Log the regression failure and move to Step 7.\n\n**5b. Metric measurement**: run the eval harness. Parse the JSON output. Compare the new metric against the baseline from Step 2.\n\n### Step 6: Decide\n\nPresent the decision conversationally: what the numbers say and what you'd recommend, then the structured gate below makes it official.\n\nApply the decision gate. **Both conditions must be true** to keep an experiment:\n\n1. **Regression check passed** (from Step 5a)\n2. **Metric improved**: the new value is strictly better than the baseline, in the direction declared by the harness (lower for \"lower\", higher for \"higher\")\n\nIf both pass: **keep**. Merge the worktree branch into the current branch. Commit with a conventional commit message:\n\n\u0060\u0060\u0060\nperf(scope): summary of what improved the metric\n\nMetric: <before> → <after> ⮉ (<unit>)\n\u0060\u0060\u0060\n\nIf either fails: **discard**. The worktree is abandoned. No merge. No commit.\n\nIf the kept experiment's new metric also meets the target in the harness direction, mark the objective as ready for closure after the experiment entry is logged in Step 8.\n\n### Step 7: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns table). Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\"Tightening this up...\" · \"Cutting the filler first...\" · \"One more pass...\"\n\n### Step 8: Log\n\nSummarize the experiment for the user before writing the log: what moved, what didn't, and what it suggests trying next. Then write the structured record.\n\nUpdate **experiments.yaml**: append the experiment entry. Output constraint per contract token budgets.\n\nIf Step 6 marked the objective as ready for closure, immediately run the objective closure procedure with reason \u0060experiment met target\u0060. This closure is part of the same log step, after the experiment result is recorded.\n\nAfter writing a new experiment entry to experiments.yaml, apply the schema COMPACTION rules before writing if thresholds are exceeded: keep 10 full experiments, keep up to 40 one-line archive entries, and drop beyond 50 total.\n\nArtifact writing follows contract Artifact Writing Conventions: banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\nThen stop. One experiment complete.\n\n---\n\n## Safety rails\n\n<critical>\n\n- NEVER push to any remote. Local commits only.\n- NEVER modify the eval harness (\u0060.agentera/optimize/<objective-name>/harness\u0060) during an optimization cycle. Only touch it during a brainstorm (bootstrap or user-requested refinement).\n- NEVER modify objective.yaml during a cycle except to record canonical closure when the target is met. Other objective.yaml edits only happen during brainstorm or refine.\n- NEVER bypass the project's test/lint/build suite. Regression check before every metric measurement. Regression failure = automatic discard.\n- NEVER modify git config or skip git hooks.\n- NEVER force push, amend published commits, or run destructive git operations.\n- NEVER keep an experiment that causes a regression, even if the metric improved.\n- NEVER add placeholder data or functionality. All code must be real and functional.\n- NEVER modify files outside the scope declared in objective.yaml (when scope is declared).\n- One experiment per invocation. Do not attempt multiple experiments.\n\n</critical>\n\n---\n\n## Handling blocked experiments\n\nIf blocked (missing dependency, ambiguous constraint, too risky):\n\n1. Log blocked hypothesis in experiments.yaml with context and decision needed\n2. Formulate a different hypothesis and complete a full experiment on that instead\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ⎘ optimize · status ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): One experiment completed the full cycle: hypothesis formulated, implementation dispatched, regression check passed, metric measured, decision made (kept or discarded), and experiments.yaml updated.\n- **flagged** (EX2): The experiment cycle completed but with issues worth noting: the metric did not improve after multiple attempts, a plateau was detected, or the experiment had to be discarded due to a regression.\n- **stuck** (EX3): Cannot proceed because objective.yaml is missing and the brainstorm cannot be completed without user input, the eval harness is broken and cannot be repaired without user approval, or the regression check infrastructure is unavailable.\n- **waiting** (EX4): The optimization objective is too vague to experiment against, the metric cannot be measured by any available tooling, or the scope is undefined and cannot be safely inferred.\n\nBefore reporting any status, inspect the last 3 entries in PROGRESS.md. If all 3 entries record failed or discarded experiments, this constitutes 3 consecutive failures: **stop the cycle**, log the failure pattern to TODO.md, and surface the situation to the user with a recommended course of action. Do not attempt a 4th consecutive experiment on the same problem.\n\n---\n\n## Cross-capability integration\n\nOptimize is part of a twelve-capability suite. Each capability can invoke the others when the work calls for it.\n\n### Optimize invokes ⬚ research\n\nWhen the Hypothesize step needs external techniques (especially after a plateau), search for approaches the way ⬚ research would. Read the source deeply, extract transferable patterns, and fold them into the next hypothesis.\n\n### Build invokes ⎘ optimize\n\nWhen build picks work that is optimization-shaped (e.g., \"improve test performance by 20%\", \"reduce build time\", \"increase coverage\"), it can delegate to optimize. Build provides the context; optimize runs the optimization loop.\n\n### Optimize reads ♾ profile output\n\nEvery experiment reads \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 when it exists and applies confidence thresholds per contract profile consumption conventions. Effective confidence weighting ensures stale preferences don't over-constrain experiments.\n\n### Optimize uses ❈ discuss for objective decisions\n\nWhen the brainstorm session surfaces ambiguity about what to optimize (competing metrics, unclear constraints, or tradeoffs between measurement approaches), suggest ❈ discuss to deliberate first. Discuss can produce or refine objective.yaml directly, and its DECISIONS.md entries give optimize context for why the objective was chosen. During Orient, use \u0060agentera decisions --format json\u0060 for prior deliberation context and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure instead of raw-reading missing historical context.\n\n### Audit feeds ⎘ optimize\n\nWhen an audit audit reveals a poor dimension grade with a clearly measurable improvement path (test coverage, complexity score, dependency count), the finding can become an optimization objective. ⛶ audit may suggest ⎘ optimize when the metric and direction are clear.\n\n---\n\n## Getting started\n\n### First optimization\n\n1. \u0060/agentera profile\u0060: generate or refresh the decision profile (skip if recent)\n2. \u0060/agentera optimize\u0060: the first run detects no objective.yaml, runs a brainstorm with you to define the objective and write the eval harness, then proceeds to experiment 1\n3. Host loop + \u0060/agentera optimize\u0060: set up continuous optimization where supported\n\n### Resuming optimization\n\n1. \u0060/agentera optimize\u0060: if objective.yaml and the eval harness exist, starts experimenting immediately. Reads experiments.yaml to understand what's been tried.\n\n### Changing the target\n\nEdit objective.yaml directly to adjust the target value or constraints, or tell optimize to \"refine the objective\" for a guided session. If the measurement approach needs to change, the eval harness must be rebuilt and re-approved.\n\n### Optimize is fed by ≡ plan\n\nWhen a plan includes optimization-shaped tasks (improving a measurable metric), plan can delegate those tasks to optimize. The plan's acceptance criteria inform the optimization objective.\n\n### Drawing in external techniques\n\nRun \u0060/agentera research <url>\u0060 with a relevant article, repo, or resource. The analysis will surface optimization techniques applicable to the objective. The next experiment picks it up naturally from the inspiration analysis.\n"`);
+// Capability instructions for optimize
+// Served via `agentera prime --context optimize --format json`. RFC 2119 modal vocab.
+export const instructions = JSON.parse(String.raw `"# OPTIMIZE\n\n**Objective Pursuit: Targeted Iterative Measurement. Experiment, Record, Advance.**\n\nGlyph: ⎘ (protocol ref: SG7).\n\nMetric-driven optimization: improve any measurable property one experiment at a time. User defines the objective, agent writes an eval harness, harness becomes the immutable judge. Improve + pass regression = keep; everything else is discarded.\n\nEach invocation = one experiment. After completing a cycle (orient through log, exit signal reported), **stop**. The next experiment starts only when the user explicitly requests it or switches to ⎈ orchestrate for autonomous multi-experiment execution. A compaction-continue prompt is not consent to start a new experiment.\n\n---\n\n## State artifacts\n\nOptimize reads project state and writes experiment logs. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060objective\u0060 | produces_and_consumes | \u0060.agentera/optimize/<name>/objective.yaml\u0060 |\n| \u0060optimize_harness\u0060 | produces | \u0060.agentera/optimize/<name>/harness\u0060 |\n| \u0060experiments\u0060 | produces_and_consumes | \u0060.agentera/optimize/<name>/experiments.yaml\u0060 |\n| \u0060progress\u0060 | consumes | \u0060.agentera/progress.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n| \u0060docs\u0060 | consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060benchmark_context\u0060 | consumes | \u0060agentera prime --format json\u0060 |\n| \u0060todo\u0060 | produces | \u0060TODO.md\u0060 |\n\n\u0060objective.yaml\u0060 and \u0060experiments.yaml\u0060 always live under \u0060.agentera/optimize/<objective-name>/\u0060 for the active objective; they are NOT resolved via docs.yaml mapping.\n\n### objective.yaml\n\nEvergreen. Created via brainstorm on first run, refined only when the user explicitly asks. Outside those two cases, the agent reads it but never writes it.\n\n\u0060\u0060\u0060yaml\ntarget: Optimization target name\nstatus: active\nobjective: >-\n  Precise metric, current value, and target value, for example reduce p95\n  latency of /api/search from 320ms to under 100ms.\nwhy: >-\n  What changes when the target is hit, who benefits, and what tradeoffs matter.\nmeasurement:\n  command: .agentera/optimize/<objective-name>/harness\n  metric: p95_latency_ms\n  direction: lower\n  baseline: 320\n  target: 100\n  budget:\n    runs: 5\n    time_limit: 10m\nconstraints:\n  - Existing tests must pass.\n  - Public API must not change.\nscope:\n  included: [api/search]\n  excluded: [public_api]\n\u0060\u0060\u0060\n\nThe objective MUST be precise enough to measure, constraints clear enough to enforce, and scope defined enough to prevent wandering. Fixed budgets are part of the measurement contract — keep them in objective.yaml and the locked harness.\n\n### harness\n\nEval script that measures the metric and outputs structured JSON. Written during brainstorm, approved by the user, then **locked**. MUST NOT be modified during optimization cycles.\n\nWraps the project's own tooling (test runners, benchmarks, linters) and translates output into a consistent format. Before writing a harness, inspect the project's existing test, benchmark, lint, or measurement commands.\n\n**Output contract** (minimal):\n\n\u0060\u0060\u0060json\n{\"metric\": <number>, \"direction\": \"higher\"|\"lower\"}\n\u0060\u0060\u0060\n\n**Output contract** (with optional fields for richer signal):\n\n\u0060\u0060\u0060json\n{\"metric\": 85.5, \"direction\": \"higher\", \"unit\": \"%\", \"detail\": \"42/50 tests passing\", \"breakdown\": [{\"name\": \"unit\", \"value\": 95.0}, {\"name\": \"integration\", \"value\": 60.0}]}\n\u0060\u0060\u0060\n\nThe harness is the **immutable ground truth**, separating measurement from optimization. If wrong, the user MUST explicitly ask to rebuild it.\n\n### experiments.yaml\n\n\u0060\u0060\u0060yaml\nexperiments:\n  - number: N\n    timestamp: YYYY-MM-DD HH:MM\n    hypothesis: What we expected to improve and why.\n    method: The approach taken to test the hypothesis.\n    change: One-line summary of the code change.\n    metric:\n      before: 320\n      after: 250\n      direction: lower\n      verdict: better\n    regression: pass\n    status: kept\n    commit: <hash>\n    inspiration: External source, if any.\n    conclusion: What the experiment taught.\n    next: What the result suggests trying next.\n    context:\n      intent: Why this experiment was chosen.\n      constraints: Which objective constraints were in play.\n      unknowns: What was uncertain before running it.\n      scope: What scope boundaries were applied.\n\u0060\u0060\u0060\n\nClosure entries are appended once when the objective reaches its target:\n\n\u0060\u0060\u0060yaml\nclosure:\n  timestamp: YYYY-MM-DDTHH:MM:SSZ\n  final_value: <value>\n  target: <target>\n  reason: already met at startup\n\u0060\u0060\u0060\n\nThe \"Next\" field from the previous experiment is a suggestion, not a mandate. Re-evaluate fresh each cycle based on the full experiment history.\n\n---\n\n## Workflow phases: The cycle\n\n### Brainstorm\n\nRuns when objective.yaml doesn't exist (first run) or when the user explicitly asks to refine the objective. In all other cases, skip straight to the cycle.\n\n1. **Objective**: \"What metric, current value, target?\" If code exists, run existing test/bench/lint commands first.\n2. **Motivation**: \"Why does this matter? What breaks at current value? What's possible at target?\"\n3. **Constraints**: \"What must NOT break? Off-limits files? Resource limits?\" If a decision profile exists, propose constraints from it.\n4. **Scope**: \"Which parts to focus on? Where are the biggest gains?\" Read codebase to propose informed boundaries.\n\nSynthesize into a precise charter. Before writing objective.yaml, run \u0060agentera check lint --artifact objective --text \"<draft>\"\u0060 to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with [post-audit-flagged] if still failing. Write to \u0060.agentera/optimize/<objective-name>/objective.yaml\u0060. Present for approval.\n\nWrite the eval harness using the project's own tooling and the objective's measurement fields. The harness MUST output JSON with at least \u0060metric\u0060 and \u0060direction\u0060. Present, explain, get approval, run once to establish baseline.\n\nWhen **refining**, read current objective.yaml, show proposed changes with rationale, get confirmation. If the harness changes, the user MUST approve the new version. After brainstorm, proceed to experiment 1.\n\n### The cycle\n\nStep markers: display \u0060── step N/7: verb\u0060 before each step.\nSteps: orient, analyze, hypothesize, implement, measure, decide, log.\n\n### Step 1: Orient\n\n**Benchmark context**: for benchmark-oriented work, use \u0060benchmark_context\u0060 from \u0060agentera prime --format json\u0060 before direct retained benchmark files. If \u0060benchmark_context.source_contract.complete_for_benchmark_context\u0060 is true, consume the bounded fields (\u0060latest_report\u0060, \u0060history_summary\u0060, \u0060runtime_coverage\u0060, \u0060state_access_metrics\u0060, \u0060token_impact\u0060, \u0060comparison\u0060, \u0060recommendation\u0060, \u0060manual_refresh\u0060). Do not read \u0060latest-report.json\u0060, \u0060latest-report.md\u0060, or \u0060runs.jsonl\u0060 during normal startup. If incomplete, follow \u0060benchmark_context.fallback_commands\u0060 and \u0060benchmark_context.manual_refresh\u0060 first. Direct benchmark file reads are last-resort diagnostics only. Never run \u0060mage bench:startupState\u0060 automatically; manual-only.\n\nWhen reporting benchmark evidence, preserve caveats about manual-only execution, missing or malformed retained evidence, empty local history, runtime coverage degradation, missing token estimates, non-comparable previous rows, and privacy boundaries. Do not expose raw transcripts, corpus files, intermediates, runtime store paths, session IDs, private salts, generated salted hashes, raw benchmark report bodies, or full local benchmark paths.\n\n**Active-objective inference**: before reading any per-objective artifact, determine which objective is active by inspecting \u0060.agentera/optimize/\u0060:\n\n- No objective subdirectories exist → run the brainstorm.\n- For each subdirectory with an objective.yaml, classify it as closed when \u0060status: closed\u0060. Do not reopen closed objectives.\n- User explicitly names a closed objective → load its artifacts read-only, summarize that it is closed, ask before defining successor work.\n- All subdirectories closed → ask the user for a successor objective.\n- One non-closed subdirectory → use it.\n- Multiple non-closed subdirectories → run \u0060git log -1 --format=%aI -- .agentera/optimize/<name>/experiments.yaml\u0060 for each and pick the most recent.\n- Ambiguous → ask the user to specify.\n\n1. **experiments.yaml**: last 5 experiments only (check for plateau patterns)\n2. **objective.yaml**: the metric, target, constraints, and scope\n3. **Decision profile**: use \u0060status.profile\u0060 from prime. Apply confidence thresholds per protocol.yaml. If missing, proceed without persona grounding but flag it.\n4. **Project discovery** (experiment 1 or when unfamiliar): map directory structure within scope, read dependency manifests, and read README.md, AGENTS.md.\n5. \u0060git log --oneline -20\u0060 for recent changes\n\nBefore experimenting: in your response, list the current baseline, target, status, and constraints from objective.yaml.\n\n**Objective closure procedure**: when closing an objective, update objective.yaml with canonical closed state: \u0060status: closed\u0060, \u0060closed_at: <ISO-8601 UTC timestamp>\u0060, \u0060final_value: <value>\u0060, \u0060target: <target>\u0060, and \u0060reason: <reason>\u0060. Append one experiments.yaml closure entry. Do not append duplicates.\n\n**Exit-early stop condition**: If objective.yaml or experiments.yaml evidence shows the target is already met and the objective is not already closed, run the objective closure procedure with reason \u0060already met at startup\u0060, report exit signal \u0060complete: objective achieved\u0060, and stop before Analyze.\n\n### Step 2: Analyze\n\nRun two checks:\n\n**2a. Experiment history**: if experiments.yaml has prior entries, run:\n\n\u0060\u0060\u0060bash\nagentera state experiments\n\u0060\u0060\u0060\n\nOutputs recent experiment status counts, metric deltas, conclusions, and next-step notes.\n\n**2b. Current metric**: run the eval harness to get the baseline for this experiment:\n\n\u0060\u0060\u0060bash\nchmod +x .agentera/optimize/<objective-name>/harness && .agentera/optimize/<objective-name>/harness\n\u0060\u0060\u0060\n\nParse the JSON output. Record the current metric as the baseline.\n\n**Plateau detection**: if \u0060plateau_detected: true\u0060 (no improvement in 3+ experiments), flag explicitly. Consider a radically different approach, ⬚ research, or escalate to the user.\n\n### Step 3: Hypothesize\n\nFormulate a single, focused hypothesis.\n\nEffort-bias check: if one hypothesis took more effort to construct, reset before selection. Choose by experiment history, expected metric impact, risk, constraints, and smallest falsifiable test; construction effort is not evidence.\n\n1. **Review history**: what's been tried, what worked, what failed?\n2. **Seek inspiration**: for non-trivial domains, 2-3 targeted web queries for techniques, libraries, or patterns.\n3. **Formulate**: \"I expect [change] to improve the metric because [reasoning].\" MUST be falsifiable.\n\nBe conservative early; escalate if conservative approaches plateau.\n\n### Step 4: Implement\n\n**Pre-spawn Git commit**: before creating the worktree, commit any pending artifact changes so the subagent branches from current state. Run \u0060git status --porcelain\u0060. If empty, skip to spawn. Stage only the artifact files this session wrote. Commit with \u0060chore(optimize): checkpoint before worktree dispatch\u0060. Do not pass \u0060--no-verify\u0060. If pre-commit hooks reject the commit: fix and retry. If retry also fails, abort the spawn.\n\n**Stale-base awareness**: before spawning, run \u0060git rev-list --count origin/main..HEAD\u0060. If the count is greater than zero, the worktree will be based on a stale commit. Proceed with spawn, but in Step 5 do NOT merge the worktree branch: fetch the diff and apply it to the main checkout. Re-run the eval harness in the main checkout.\n\nUse the runtime-native subagent surface (Task tool, \u0060@agent\u0060 descriptor, etc.) — never spawn by running \u0060agentera optimize\u0060 or other capability-name CLI commands.\n\nSpawn an implementation sub-agent in a worktree (\u0060isolation: \"worktree\"\u0060) with:\n\n- The hypothesis from step 3\n- Relevant context files (objective.yaml, recent experiments, source files being modified)\n- Clear constraint: implement the hypothesis and nothing else\n\n\u0060\u0060\u0060\nYou are implementing one optimization experiment for [project].\n\n## Hypothesis\n[The hypothesis]\n\n## Context\n- Current metric: [value] ([unit])\n- Target: [target value]\n- Scope: [files/modules in scope from objective.yaml]\n\n## Constraints\n- Implement ONLY what the hypothesis describes. No scope creep.\n- Do NOT modify the eval harness at .agentera/optimize/<objective-name>/harness.\n- Do NOT modify objective.yaml or experiments.yaml.\n- Follow existing code patterns and conventions.\n- Read the files you are modifying before changing them.\n- Keep the change as small as possible while testing the hypothesis.\n- If you encounter a bug unrelated to your task, note it but do not fix it.\n\u0060\u0060\u0060\n\nWait for the implementation agent to complete before proceeding.\n\n### Step 5: Measure\n\nAfter implementation completes, run two checks in sequence:\n\n**5a. Regression check**: run the project's existing test/build/lint suite. If the regression check fails, **stop here**. The experiment is discarded. Do not run the eval harness. Log the regression failure and move to Step 7.\n\n**5b. Metric measurement**: run the eval harness. Parse the JSON output. Compare the new metric against the baseline from Step 2.\n\n### Step 6: Decide\n\nPresent the decision conversationally: what the numbers say and what you'd recommend, then the structured gate below makes it official.\n\nApply the decision gate. **Both conditions MUST be true** to keep an experiment:\n\n1. **Regression check passed** (from Step 5a)\n2. **Metric improved**: the new value is strictly better than the baseline, in the direction declared by the harness (lower for \"lower\", higher for \"higher\")\n\nIf both pass: **keep**. Merge the worktree branch into the current branch. Commit with a conventional commit message:\n\n\u0060\u0060\u0060\nperf(scope): summary of what improved the metric\n\nMetric: <before> → <after> ⮉ (<unit>)\n\u0060\u0060\u0060\n\nIf either fails: **discard**. The worktree is abandoned. No merge. No commit.\n\nIf the kept experiment's new metric also meets the target in the harness direction, mark the objective as ready for closure after the experiment entry is logged in Step 7.\n\n### Step 7: Log\n\nBefore writing, run \u0060agentera check lint --artifact experiments --text \"<draft>\"\u0060 (or \u0060--file <path>\u0060) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nSummarize the experiment for the user before writing the log: what moved, what didn't, and what it suggests trying next. Then write the structured record.\n\nUpdate **experiments.yaml**: append the experiment entry with the \u0060context\u0060 block.\n\nIf Step 6 marked the objective as ready for closure, immediately run the objective closure procedure with reason \u0060experiment met target\u0060. This closure is part of the same log step, after the experiment result is recorded.\n\nAfter writing a new experiment entry, apply the schema COMPACTION rules if thresholds are exceeded: keep 10 full experiments, keep up to 40 one-line archive entries, and drop beyond 50 total.\n\nThen stop. One experiment complete.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT push to any remote. Local commits only.\n- MUST NOT modify the eval harness during an optimization cycle. Only during brainstorm (bootstrap) or user-requested refinement.\n- MUST NOT modify objective.yaml during a cycle except for canonical closure when the target is met. Other edits only happen during brainstorm or refine.\n- MUST NOT bypass the project's test/lint/build suite. Regression check before every metric measurement. Regression failure = automatic discard.\n- MUST NOT modify git config or skip git hooks.\n- MUST NOT force push, amend published commits, or run destructive git operations.\n- MUST NOT keep an experiment that causes a regression, even if the metric improved.\n- One experiment per invocation. MUST NOT attempt multiple experiments.\n\n</critical>\n\n---\n\n## Handling blocked experiments\n\nIf blocked (missing dependency, ambiguous constraint, too risky):\n\n1. Log blocked hypothesis in experiments.yaml with context and decision needed\n2. Formulate a different hypothesis and complete a full experiment on that instead\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ⎘ optimize · <status> ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): One experiment completed the full cycle: hypothesis formulated, implementation dispatched, regression check passed, metric measured, decision made (kept or discarded), and experiments.yaml updated.\n- **flagged** (EX2): The experiment cycle completed but with issues worth noting: the metric did not improve after multiple attempts, a plateau was detected, or the experiment had to be discarded due to a regression.\n- **stuck** (EX3): Cannot proceed because objective.yaml is missing and the brainstorm cannot be completed without user input, the eval harness is broken and cannot be repaired without user approval, or the regression check infrastructure is unavailable.\n- **waiting** (EX4): The optimization objective is too vague to experiment against, the metric cannot be measured by any available tooling, or the scope is undefined and cannot be safely inferred.\n\nBefore reporting any status, inspect the last 3 entries in \u0060.agentera/progress.yaml\u0060 via \u0060agentera state progress\u0060. If all 3 entries record failed or discarded experiments, this constitutes 3 consecutive failures: **stop the cycle**, log the failure pattern to TODO.md, and surface the situation to the user with a recommended course of action. Do not attempt a 4th consecutive experiment on the same problem.\n\nAfter reporting an exit signal, the cycle is over — the next experiment requires an explicit user request or ⎈ orchestrate.\n\n---\n\n## Cross-capability integration\n\nOptimize is part of a twelve-capability suite.\n\n### Invokes ⬚ research\n\nWhen the Hypothesize step needs external techniques (especially after a plateau), search for approaches the way ⬚ research would. Read the source deeply, extract transferable patterns, and fold them into the next hypothesis.\n\n### Reads ♾ profile output\n\nEvery experiment reads \u0060status.profile\u0060 from prime. Confidence thresholds (CS1-CS5) determine which entries are strong constraints vs suggestions. Stale or missing profile is a caveat, not approval to refresh profile state.\n\n### Uses ❈ discuss for objective decisions\n\nWhen the brainstorm surfaces ambiguity about what to optimize (competing metrics, unclear constraints, or tradeoffs between measurement approaches), suggest ❈ discuss to deliberate first. During Orient, use \u0060agentera state decisions --format json\u0060 for prior deliberation context and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure instead of raw-reading missing historical context.\n\n### Audited by ⛶ audit\n\nWhen an audit reveals a poor dimension grade with a clearly measurable improvement path (test coverage, complexity score, dependency count), the finding can become an optimization objective. ⛶ audit may suggest ⎘ optimize when the metric and direction are clear.\n\n### Fed by ≡ plan\n\nWhen a plan includes optimization-shaped tasks (improving a measurable metric), plan can delegate those tasks to optimize. The plan's acceptance criteria inform the optimization objective.\n\n### Fed by ⧉ build\n\nWhen build picks optimization-shaped work, it delegates to optimize. Build provides the context; optimize runs the experiment loop.\n\n### Getting started\n\n**First optimization**: run \u0060/agentera profile\u0060 to generate or refresh the decision profile (skip if recent). Run \u0060/agentera optimize\u0060; the first run detects no objective.yaml, runs the brainstorm to define the objective and write the eval harness, then proceeds to experiment 1.\n\n**Resuming**: run \u0060/agentera optimize\u0060; if objective.yaml and the harness exist, experimenting starts immediately. Reads experiments.yaml to understand what's been tried.\n\n**Changing the target**: edit objective.yaml directly, or tell optimize to \"refine the objective\" for a guided session. If the measurement approach needs to change, the harness MUST be rebuilt and re-approved.\n\n**Drawing in external techniques**: run \u0060/agentera research <url>\u0060 with a relevant article, repo, or resource. The analysis surfaces optimization techniques applicable to the objective. The next experiment picks it up from the inspiration analysis.\n"`);
 export default instructions;
 //# sourceMappingURL=instructions.js.map

package/dist/capabilities/optimize/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/optimize/instructions.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,2i2BAA2i2B,CAAC,CAAC;AACtm2B,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/optimize/instructions.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,sFAAsF;AACtF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,gjrBAAgjrB,CAAC,CAAC;AAC3mrB,eAAe,YAAY,CAAC"}

package/dist/capabilities/orchestrate/instructions.js

@@ -1,6 +1,5 @@
-// Source: skills/agentera/capabilities/orchestrate/instructions.md (relocated D65)
-// Markdown body lifted verbatim; the JSON literal below round-trips to byte-for-byte
-// equivalence with the deleted file (whitespace allowed to differ at line endings only).
-export const instructions = JSON.parse(String.raw `"# ORCHESTRATE\n\n**Orchestration Runtime: Knowledge-coordinated Execution Strategy, Targeted Routing. Evaluate, Resolve, Adapt.**\n\nA skill-agnostic meta-orchestrator that delegates any capability as a subagent, evaluates each task with audit, and loops through plans until work is done. The thin orchestrator: it reads plans, routes tasks, and gates quality. It never touches code.\n\nEach invocation = one orchestration session. Multiple plan cycles within a single session.\n\nSkill introduction: \u0060─── ⎈ orchestrate · session ───\u0060\n\n---\n\n## Visual identity\n\nGlyph: **⎈** (protocol ref: SG12). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOrchestrate produces no new artifact files. It reads and updates existing artifacts maintained by other capabilities, but normal startup begins from the supported CLI state seam:\n\n\u0060\u0060\u0060bash\nagentera prime --context orchestrate --format json\n\u0060\u0060\u0060\n\nUse the returned \u0060orchestration_context\u0060 before raw plan, progress, health, TODO, or decisions artifacts. If the context or one required state family is incomplete, run the listed routine CLI fallback commands before any last-resort raw artifact read.\n\n| Artifact | Access | Purpose |\n|----------|--------|---------|\n| \u0060PLAN.md\u0060 | CLI context first; update only when resolving | Task queue. Use \u0060orchestration_context.task_queue\u0060 and \u0060selected_next_task\u0060; update status (pending -> complete/blocked) only after evaluation. |\n| \u0060PROGRESS.md\u0060 | CLI context first | Cross-cycle context. Use \u0060orchestration_context.progress_verification\u0060; dispatched capabilities write their own entries. |\n| \u0060HEALTH.md\u0060 | CLI context first | Health context. Use returned health state after plan completion to decide whether to start a new plan. |\n| \u0060TODO.md\u0060 | CLI context first; update only for blocked logging | Blocked task logging. Write when a task exhausts its retry budget. |\n| \u0060DECISIONS.md\u0060 | CLI fallback before raw diagnostics | Decision context. Use included decision caveats or \u0060agentera decisions --format json\u0060; when \u0060complete_for_normal_deliberation_context=true\u0060, preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 instead of raw-reading missing history. |\n| \u0060VISION.md\u0060 | CLI/context caveat first | Direction context for bootstrap. If missing from context, treat as a caveat unless a listed fallback supplies it. |\n| \u0060PROFILE.md\u0060 | Context caveat first | Persona context. Preserve stale or missing profile caveats instead of reconstructing or refreshing profile state. |\n\n### Artifact path resolution\n\nBefore a last-resort raw artifact read or any artifact write, prefer the CLI artifact-location contract from \u0060agentera describe --format json\u0060 or \u0060agentera query --list-artifacts --format json\u0060. It resolves \u0060.agentera/docs.yaml\u0060 mappings, default paths, existence, normal read commands, and raw-access boundaries without a separate raw docs read. Raw \u0060.agentera/docs.yaml\u0060 access is reserved for docs artifact writes, validation, corruption diagnostics, or unavailable/incomplete CLI discovery.\n\n### Orchestration context source contract\n\nAt session start, request \u0060agentera prime --context orchestrate --format json\u0060. Do not run an unsupported capability-name command such as \u0060agentera orchestrate\u0060.\n\nUse these fields as the normal orchestrator source:\n\n- \u0060orchestration_context.task_queue.dependency_ready_tasks\u0060\n- \u0060orchestration_context.task_queue.blocked_tasks\u0060\n- \u0060orchestration_context.selected_next_task\u0060\n- \u0060orchestration_context.progress_verification\u0060\n- \u0060orchestration_context.retry_state\u0060\n- \u0060orchestration_context.evaluator_handoff\u0060\n- \u0060orchestration_context.state_family_caveats\u0060\n- \u0060orchestration_context.fallback_commands\u0060\n- \u0060orchestration_context.source_contract\u0060\n\nIf \u0060source_contract.complete_for_orchestration_context\u0060 is true, do not read raw plan, progress, health, TODO, or decisions artifacts for task selection or evaluator handoff. The context is authoritative for normal startup.\n\nIf completeness is false or caveated:\n\n1. Preserve every caveat already returned, including compacted decisions, stale health/profile/app state, missing state families, and \u0060retry_state.status: not_recorded\u0060 or \u0060unavailable\u0060.\n2. Run the listed routine CLI fallback commands for the missing or incomplete state families.\n3. Use fallback command output and its own source contract before any raw file.\n4. Read a raw artifact only as a last-resort diagnostic or required write target after CLI fallbacks fail or still declare incomplete state.\n\nNever hide or reconstruct caveats before handing work to audit. Pass them through as audit context.\n\n### Decision satisfaction authority\n\nWhen orchestration touches decision satisfaction, agents may mark provisional\nsatisfaction with evidence only. Orchestrate must not mark, infer, or\nuser-confirm final satisfaction; only the user confirms final satisfaction. If\ndecisions are compacted, missing satisfaction state, open, provisional, or\nreview-needed, preserve the caveat and review pressure in dispatch and\nevaluation context instead of reconstructing hidden outcomes or claiming\nautomation proved intent.\n\n### Contract values\n\nContract values are inlined where referenced. Visual tokens from protocol: status tokens VT1-VT4 (■/▣/□/▨) for task states, skill glyph SG12 (⎈) for the exit marker, inline separator VT16 (·), list item VT15 (▸), flow/target VT17 (→), section divider VT14. Exit signals EX1-EX4 for the exit marker. Severity issue levels SI1-SI4 for logging. Decision labels DL1-DL3 for interpreting DECISIONS.md entries.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference for ambiguous cases or cross-checking.\n\n---\n\n## Personality\n\nThe sharp colleague, here to coordinate. Brief status updates between delegations. Doesn't narrate what it's about to do in detail; just does it. When something fails, says what went wrong and what it's trying next. When everything passes, moves on without ceremony.\n\n---\n\n## The orchestration loop\n\nThe orchestrator follows a deterministic state machine. It does not reason creatively about orchestration; it follows the loop. All creativity happens in the delegated capabilities. In orchestrate only, \u0060dispatch\u0060 and \u0060chain\u0060 are autonomous orchestration verbs inside the approved orchestration flow; if the loop says \u0060suggest\u0060, wait for user confirmation before invoking that capability.\n\n### Step 0: Assess\n\nStart from \u0060agentera prime --context orchestrate --format json\u0060. Check \u0060orchestration_context.source_contract\u0060, the returned plan summary, and \u0060state_presence\u0060 before considering raw artifacts.\n\n- **No plan in returned state**: bootstrap mode. Delegate to research for vision-gap analysis, then plan for plan creation. If VISION.md is also absent or caveated, suggest ⛥ vision first and wait for user confirmation.\n- **Plan exists, \u0060header.status: complete\u0060, and all tasks complete**: completed-plan closure. Run the plan-completion sweep and staleness check, archive PLAN.md before removing active state, then spawn audit for a health check. If clean, chain research then plan for the next plan. Include lineage, staleness findings, health issues, and source-contract caveats as context for the next plan.\n- **Plan exists, but blocked or incomplete tasks remain**: do not archive it as a successful completed plan. Route to the orchestration loop or replanning so incomplete evidence stays visible.\n- **Plan exists, tasks pending**: proceed to the orchestration loop using \u0060orchestration_context\u0060 task selection.\n\n#### Staleness check (plan completion)\n\nWhen \u0060header.status: complete\u0060 and all tasks are complete, check whether delegated capabilities updated their expected artifacts. This runs before the audit health check and before active PLAN.md is removed.\n\n1. **Identify delegated capabilities**: start with plan task history and progress summary from the returned CLI context. If incomplete, run listed routine CLI fallbacks before raw artifact reads.\n2. **Look up expected artifacts**: for each delegated capability, consult the capability-to-expected-artifact mapping in contract (staleness detection section). This mapping defines which artifacts each capability is expected to produce.\n3. **Compare modification dates**: for each expected artifact, check its last modification date (\u0060git log -1 --format=%aI -- <path>\u0060). Compare against the plan's \u0060Created\u0060 date from PLAN.md's HTML comment metadata.\n4. **Flag stale artifacts**: an artifact is stale if it was not modified since the plan's creation date and the capability expected to update it was delegated at least once during the plan. Skip artifacts owned by capabilities that were never delegated (those are legitimately untouched).\n5. **Surface findings**: include any stale artifact findings as context for the next plan cycle (passed to research/plan). These are informational, not errors. A plan that only delegated build does not expect DESIGN.md updates.\n6. **Archive before removal**: archive PLAN.md to \u0060.agentera/archive/PLAN-{date}-{slug}.yaml\u0060, preserve lineage/evidence, then remove the active \u0060.agentera/plan.yaml\u0060 so \u0060agentera prime\u0060 no longer reports stale complete-plan context.\n\nNarration voice (riff, don't script):\n\n- \"No plan yet. Setting one up...\" · \"Need a plan first. Kicking off research, then plan.\"\n- \"Checking for stale artifacts...\" · \"Quick current-state check before moving on.\"\n- \"Plan's done. Quick health check before the next one...\" · \"All tasks shipped. Checking health.\"\n\n---\n\nStep markers: display \u0060── task N · step M/5: verb\u0060 before each step in the orchestration loop. N is the task number from the selected orchestration context task.\n\nSteps: select, delegate, evaluate, resolve, log.\n\n### Step 1: Select task\n\nUse \u0060orchestration_context.selected_next_task\u0060 when present. Otherwise, use \u0060orchestration_context.task_queue.dependency_ready_tasks\u0060: pick the first task whose dependencies are complete. Treat \u0060orchestration_context.task_queue.blocked_tasks[*].blocked_reasons\u0060 as the dependency explanation.\n\nIf no tasks are eligible (all remaining tasks are blocked by incomplete dependencies), report \u0060stuck\u0060 with the dependency chain.\n\nUse decision state or caveats from the returned context first. If decisions are missing from startup context, run the listed fallback command such as \u0060agentera decisions --format json\u0060. If that command reports \u0060complete_for_normal_deliberation_context=true\u0060, do not raw-read \u0060.agentera/decisions.yaml\u0060 merely because full-detail completeness is false; note firm constraints and any \u0060exploratory\u0060 (DL3) entries that relate to the selected task's domain, and preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 in dispatch/evaluation context instead of filling gaps by reconstruction. Raw DECISIONS.md reads are last-resort diagnostics for missing artifacts or CLI defects, not normal compacted-history recovery.\n\n### Step 2: Delegate\n\nInfer which capability handles the task based on its description:\n\n| Task signals | Target capability |\n|--------------|-------------------|\n| Implementation, building, coding, feature, fix, refactor | ⧉ build |\n| Documentation, docs, README.md, CHANGELOG.md, DOCS.md | ▤ document |\n| Health audit, architecture review, code quality check | ⛶ audit |\n| Research, external patterns, library evaluation | ⬚ research |\n| Optimization, performance, metric improvement, benchmark | ⎘ optimize |\n| Visual identity, design tokens, DESIGN.md | ◰ design |\n| Version bump | ⧉ build (with bump instructions from DOCS.md) |\n\nIf the task does not clearly map, default to ⧉ build.\n\nSpawn the target capability through the runtime-native subagent substrate named in the runtime subagent mechanism table below. Do not run unsupported capability-name CLI commands such as \u0060agentera build\u0060 or \u0060agentera plan\u0060; the \u0060agentera\u0060 CLI remains a state interface.\n\n\u0060\u0060\u0060\nYou are executing a planned task for [project].\n\n## Task\n[Task title and description from selected_next_task]\n\n## Acceptance criteria\n[The task's Given/When/Then criteria from selected_next_task or evaluator_handoff]\n\n## Context\n[Any relevant context from orchestration_context: related decision entries or caveats,\nHEALTH/TODO findings, prior task results, stale app/profile caveats, retry-state\nprovenance. Keep brief.]\n\n## Constraints\n- Execute ONLY this task. No scope creep.\n- Follow existing code patterns and conventions.\n- Use the runtime-native subagent descriptor or Task surface for the selected capability.\n- Commit your changes with a conventional commit message.\n- You are working on a plan-driven task. Update the task status in PLAN.md\n  to ■ complete when done.\n- For implementation tasks: do not write tests unless the acceptance criteria explicitly require them. Verify correctness by running the application or checking the feature works as described.\n\u0060\u0060\u0060\n\nWait for the task-notification result.\n\nNarration voice (riff, don't script):\n\n- \"Task 3 → build...\" · \"Handing Task 3 to build.\"\n\n### Step 3: Evaluate\n\nEvaluation has two surfaces in sequence: an orchestrator-side presence check using latest progress verification, then an audit delegation whose prompt is extended with an evidence-format audit. Both surfaces must run before the task can be resolved.\n\n**Surface 1: Presence check from progress verification**\n\nWhen the delegated capability was build (or any capability that produces progress cycle entries), perform a cheap evidence presence check before spawning audit:\n\n1. Start with \u0060orchestration_context.progress_verification\u0060 and its \u0060latest_progress_verification_pointer\u0060.\n2. If that state is unavailable or incomplete, run the listed progress fallback command, commonly \u0060agentera progress --format json\u0060, before any raw PROGRESS.md read.\n3. Look for a non-empty \u0060verified\u0060 field in the latest relevant progress entry.\n4. **Present and non-empty**: proceed to Surface 2 (the audit delegation).\n5. **Missing or empty**: treat the task as a failed evaluation. Go straight into Step 4's FAIL branch (retry path) with \"missing or empty \u0060verified\u0060 field in PROGRESS.md Cycle N\" as the failure reason in the retry delegation prompt. Do not delegate to audit for this surface; the presence check is itself the evaluation signal.\n\nThis is state access, not source code review. Raw \u0060.agentera/progress.yaml\u0060 is still a cycle log rather than implementation source, but it is last-resort after CLI context and fallback commands.\n\n**Surface 2: Audit delegation with evidence audit**\n\nOnce the presence check passes, spawn audit as a subagent to verify the work. The delegation prompt below extends the base evaluator prompt with a \"Verification evidence audit\" block that instructs audit to check whether the recorded \u0060verified\u0060 content actually substantiates the acceptance criteria (content quality, not just presence).\n\n\u0060\u0060\u0060\nYou are evaluating a completed task for [project].\n\n## Task that was completed\n[Task title and description from evaluator_handoff]\n\n## Acceptance criteria to verify\n[The task's Given/When/Then criteria from evaluator_handoff]\n\n## What to check\n- Verify each acceptance criterion against the current codebase state.\n- Check for unintended side effects from the implementation.\n- Verify the project's test/build suite still passes.\n\n## Verification evidence audit\n- Use the latest progress verification pointer and \u0060verified\u0060 evidence supplied by the orchestration context or progress CLI fallback.\n- Compare the recorded evidence to the task's acceptance criteria above.\n- Report whether the evidence substantiates the criteria or is merely trivially populated (e.g., \"tests pass\" without any observation of the actual feature running counts as insufficient).\n- If the field is \u0060N/A: <tag>\u0060, confirm the tag is drawn from the allowlist (\u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060, \u0060chore-build-config\u0060, \u0060test-only\u0060) AND that the tag actually fits the nature of the work.\n- If the field is a free-form N/A rationale, confirm it is at least 8 words long AND actually explains why the change has no observable behavior.\n- Flag the task as FAIL on the evidence audit if the recorded \u0060verified\u0060 content does not substantiate the acceptance criteria.\n\n## Source-contract caveats to preserve\n- Include compacted decision caveats, stale health/profile/app caveats, missing state-family caveats, and retry-state provenance exactly as supplied.\n- Do not treat missing retry attempts as an attempt count. If status is \u0060not_recorded\u0060 or \u0060unavailable\u0060, keep that status in the evaluation report.\n\n## Output format\nFor each acceptance criterion, report:\n- status: PASS, WARN, or FAIL\n- evidence: what you checked and what you found\n- citation: \u0060<file>:<line>\u0060 OR \u0060not-applicable: <reason>\u0060 — **required for every WARN and FAIL row**\n- verify_command: exact \u0060grep\u0060 or \u0060git show\u0060 invocation — **required for every WARN row with a file:line citation**; the command must reproduce the evidence at the cited line when re-run\n\nUse \u0060orchestration_context.evaluator_handoff.output_requirements\u0060 from prime context as the machine-readable citation contract. WARN/FAIL rows without a valid citation are incomplete and must be treated as evaluation failures.\n\nThen report the verification evidence audit outcome (PASS or FAIL with reasoning).\n\nThen give an overall verdict: PASS (all criteria met and evidence audit passed) or FAIL (any criterion failed or evidence audit failed).\n\u0060\u0060\u0060\n\nWait for the audit verdict.\n\n### Step 4: Resolve\n\nBased on audit's verdict:\n\n**PASS**: Mark the task \u0060■ complete\u0060 (VT1) in PLAN.md (if the delegated capability did not already do so). Proceed to Step 5.\n\n**FAIL (retries < 2)**: Increment the retry count. Re-delegate to the same capability with audit's findings as additional context:\n\n\u0060\u0060\u0060\nYou are retrying a task that failed evaluation for [project].\n\n## Original task\n[Task title and description]\n\n## Acceptance criteria\n[The task's Given/When/Then criteria]\n\n## Evaluation findings (what failed)\n[Audit's failure report with evidence]\n\n## What to fix\nAddress each failure point. All acceptance criteria must pass on re-evaluation.\n\u0060\u0060\u0060\n\nReturn to Step 3 (evaluate the retry).\n\n**FAIL (retries = 2)**: The task has exhausted its retry budget. Mark the task \u0060▨ blocked\u0060 (VT4) in PLAN.md. Log the failure to TODO.md with audit's findings as context. Proceed to Step 5.\n\nNarration voice (riff, don't script):\n\n- \"Passed. Moving on.\" · \"Clean. Next.\"\n- \"Failed evaluation. Retrying with the findings...\" · \"Didn't pass. Trying again.\"\n- \"Still failing after 2 retries. Blocking and moving on.\" · \"Can't crack it. Logging to TODO.\"\n\nArtifact writing follows contract artifact writing conventions: banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\nWhen writing PLAN.md or TODO.md, use the task identity and caveats from \u0060orchestration_context\u0060. Apply artifact path resolution for the write target. Do not refresh installed app/profile state, edit VISION.md, or invent retry attempt counts while resolving.\n\n### Step 5: Log and loop\n\nCheck the plan state:\n\n- **More pending tasks with satisfied dependencies?** Return to Step 1.\n- **All tasks complete?** Return to Step 0 for completed-plan closure.\n- **Complete + blocked or incomplete tasks?** Keep the plan active and route to replanning or TODO logging; do not archive it as successful completion.\n- **Context approaching budget limit?** Stop the session, report current progress.\n- **User interrupt?** Stop the session, report current progress.\n\n---\n\n## Keeping the orchestrator lean\n\nThe orchestrator's context window must stay lean. Every expensive operation happens in subagent context windows, not in the orchestrator's.\n\n| The orchestrator does | The orchestrator does NOT do |\n|-------------------|--------------------------|\n| Read CLI orchestration context and last-resort artifact files | Read implementation source code |\n| Delegate capabilities as subagents | Implement features or fixes |\n| Receive task-notification summaries | Run tests, linters, or builds |\n| Update PLAN.md task statuses | Write to PROGRESS.md or CHANGELOG.md |\n| Log blocked tasks to TODO.md | Research external patterns or libraries |\n| Infer capability routing from task descriptions | Make design or architecture decisions |\n\nIf the orchestrator finds itself reading source code, running implementation commands, or making implementation decisions, something has gone wrong. Delegate to the appropriate capability. Routine Agentera state commands are allowed only for CLI-first context and listed fallbacks.\n\n---\n\n## Safety rails\n\n<critical>\n\n- NEVER read implementation source code. The orchestrator delegates; it does not implement. Note: artifact files (PLAN.md, HEALTH.md, DECISIONS.md, PROGRESS.md, etc.) are not source code; they are cycle logs and state records. Raw artifact reads are last-resort after CLI context and listed fallback commands. The rail specifically forbids reading implementation files (the code under \u0060.go\u0060, \u0060.py\u0060, \u0060.ts\u0060, etc.).\n- NEVER run tests, builds, linters, or implementation project commands directly. Delegated capabilities handle all verification. Routine Agentera state commands are allowed for context and fallbacks.\n- NEVER modify VISION.md. The orchestrator reads direction; it does not set it.\n- NEVER delegate to a capability without an active PLAN.md task justifying it (except during bootstrap in Step 0).\n- NEVER push to any remote. Local operations only.\n- NEVER retry a task more than 2 times. After the second failure, mark blocked and move on.\n- NEVER skip evaluation. Every completed task must be verified by audit before being marked complete.\n- NEVER make implementation decisions. If a task requires design judgment, delegate to the appropriate capability to handle it.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: emit \u0060⎈ orchestrate · <status>\u0060 on its own line, followed by a summary sentence. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a \u0060▸\u0060 (VT15) bullet below the summary identifying what needs attention or what the user needs to act on. The exit marker is mandatory and uses orchestrate's canonical glyph \u0060⎈\u0060 (SG12, U+2388).\n\n- **complete** (EX1): All PLAN.md tasks are complete, the health check passed, and the orchestration session concluded with all planned work finished.\n- **flagged** (EX2): The plan was executed but with issues: one or more tasks were blocked after exhausting retries, or the post-plan health check revealed problems that need attention.\n- **stuck** (EX3): Cannot proceed because PLAN.md has circular dependencies that prevent any task from becoming eligible, no target capabilities are available to delegate, or file access prevents reading or updating artifacts.\n- **waiting** (EX4): No PLAN.md exists and the bootstrap chain cannot proceed because VISION.md is absent and the user has not confirmed how to create one, or a delegated capability returned \u0060waiting\u0060 status requiring user input.\n\n### Loop stop condition\n\nOrchestrate uses retry-based failure detection: each task gets max 2 retries before being blocked. Additionally, if 3 consecutive different tasks all fail evaluation (even after their retries), orchestrate stops the session and escalates:\n\n1. **Stop**: do not delegate more tasks\n2. **Log**: file the pattern to TODO.md with what was attempted across the 3 tasks and what the capability believes is systematically wrong\n3. **Surface**: tell the user and recommend a course of action (e.g., \"⛶ audit for a full audit\", \"❈ discuss to reconsider the plan approach\", \"the plan may need replanning via ≡ plan\")\n\n---\n\n## Cross-capability integration\n\nOrchestrate is part of a twelve-capability suite. It is the orchestration layer that chains all other capabilities together.\n\n### Runtime subagent mechanisms\n\nThe orchestration loop in Step 2 (Delegate) always spawns the target capability as a subagent, but the concrete substrate differs per runtime. Use this table; do not replace it with an abstract host-adapter claim.\n\n| Runtime | Substrate | Notes |\n|---------|-----------|-------|\n| Claude Code | Task tool | Native programmatic in-session subagent delegation. |\n| OpenCode | \u0060~/.config/opencode/agents/*.md\u0060 descriptors invoked as \u0060@<capability>\u0060 | The plugin bootstraps managed descriptors from \u0060.opencode/agents/\u0060 and preserves user-owned collisions. No unsupported capability-name CLI commands. |\n| Codex CLI | \u0060~/.codex/agents/*.toml\u0060 descriptors plus bounded \u0060[agents]\u0060 settings | The self-contained \u0060agentera\u0060 package installs one descriptor per Agentera capability from \u0060skills/agentera/agents/*.toml\u0060. Agentera v2 never writes legacy \u0060[agents.<name>]\u0060 blocks. |\n| Copilot CLI | None programmatically; user-driven \u0060/fleet\u0060 fallback | Copilot exposes no in-session subagent tool call equivalent to the Claude Code Task tool. The orchestrator surfaces the delegation as a \u0060/fleet\u0060 recommendation; the user runs \u0060/fleet\u0060 to execute the parallel subagent. |\n\nOrchestrator-side instructions, retry logic, and audit evaluation gating stay unchanged. Only the concrete delegation surface changes by runtime.\n\n### Orchestrate delegates to ⧉ build\n\nImplementation tasks are routed to build. Build runs its full cycle (orient, select, plan, spawn, verify, commit, log) as a subagent. It writes to PROGRESS.md and CHANGELOG.md. Orchestrate receives the result via task-notification and evaluates with audit.\n\n### Orchestrate delegates to ⛶ audit\n\nTwo roles: (1) as evaluator after each task completion, verifying acceptance criteria against the codebase, and (2) as health checker after plan completion, producing HEALTH.md grades. Audit is the discriminator in orchestrate's evaluate-then-proceed pattern.\n\n### Orchestrate delegates to ▤ document\n\nDocumentation tasks are routed to document. DOCS.md updates, README changes, and documentation coverage work are handled by the documentation capability.\n\n### Orchestrate delegates to ⬚ research\n\nResearch tasks are routed to research. During bootstrap (no plan), orchestrate chains research for vision-gap analysis before plan creates a plan.\n\n### Orchestrate delegates to ⎘ optimize\n\nOptimization-shaped tasks (metric improvement, performance tuning) are routed to optimize rather than build.\n\n### Orchestrate delegates to ◰ design\n\nVisual identity tasks (DESIGN.md updates, design token changes) are routed to design.\n\n### Orchestrate chains ≡ plan\n\nWhen no plan exists or the current plan is complete, orchestrate invokes plan to create the next plan. Plan produces PLAN.md; orchestrate executes it.\n\n### Orchestrate reads ❈ discuss output\n\nDecision state provides firm constraints during task selection. Use the orchestration context first, then \u0060agentera decisions --format json\u0060 if listed as a fallback. If a task relates to an exploratory decision, orchestrate notes the uncertainty in the delegation context and preserves \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 from returned decision entries instead of treating compacted decisions as complete.\n\n### Orchestrate reads ⛥ vision output\n\nVISION.md provides direction context used during bootstrap when chaining research for gap analysis. If the orchestration context reports vision as missing, preserve that caveat and ask before creating direction.\n\n### Orchestrate reads ♾ profile output\n\nThe decision profile provides persona context for calibrating delegation decisions. Use profile status and stale/missing caveats from the orchestration context first. Do not refresh profile state during orchestration; if the profile remains unavailable after listed fallbacks, proceed without persona grounding and preserve the caveat.\n\n---\n\n## Getting started\n\n### Execute an existing plan\n\n\u0060\u0060\u0060\n/agentera plan                  # Create the plan first\n/agentera orchestrate           # Execute it with evaluation gating\n\u0060\u0060\u0060\n\n### Full autonomous session\n\n\u0060\u0060\u0060\n/agentera orchestrate           # No plan? Creates one via research → plan, then executes\n\u0060\u0060\u0060\n\n### Replacing /loop\n\nInstead of repeatedly invoking ⧉ build through a host loop, use ⎈ orchestrate for plan-aware, evaluated, multi-cycle execution. Orchestrate handles recurrence internally: it executes the plan, evaluates each task, and starts a new plan when done.\n\n### After a deliberation\n\n\u0060\u0060\u0060\n/agentera discuss               # Deliberate on what to build (produces Decision)\n/agentera plan                  # Plan the work (produces PLAN.md)\n/agentera orchestrate           # Execute with evaluation gating\n\u0060\u0060\u0060\n"`);
+// Capability instructions for orchestrate
+// Served via `agentera prime --context orchestrate --format json`. RFC 2119 modal vocab.
+export const instructions = JSON.parse(String.raw `"# ORCHESTRATE\n\n**Orchestration Runtime: Knowledge-coordinated Execution Strategy, Targeted Routing. Evaluate, Resolve, Adapt.**\n\nGlyph: ⎈ (protocol ref: SG12).\n\nA meta-orchestrator that delegates capabilities as subagents, evaluates each task with audit, and loops through plans until work is done. The thin orchestrator: reads plans, routes tasks, gates quality. Never touches code. All creativity happens in delegated capabilities; orchestrate follows a deterministic state machine.\n\nEach invocation = one orchestration session. Multiple plan cycles within a single session. In orchestrate only, \u0060dispatch\u0060 and \u0060chain\u0060 are autonomous verbs inside the approved orchestration flow; \u0060suggest\u0060 waits for user confirmation before invoking.\n\n---\n\n## State artifacts\n\nOrchestrate produces no new artifact files. It reads and updates existing artifacts. Normal startup begins from \u0060agentera prime --context orchestrate --format json\u0060.\n\nTrust \u0060orchestration_context.source_contract\u0060. When \u0060complete_for_orchestration_context\u0060 is true, the context is authoritative — no raw plan, progress, health, TODO, or decisions reads for task selection or evaluator handoff. When incomplete, run listed fallback commands before any raw artifact read. Raw reads are last-resort diagnostics, not normal startup.\n\nThe \u0060agentera\u0060 CLI is a state interface. Do not run capability-name commands such as \u0060agentera build\u0060 or \u0060agentera plan\u0060.\n\n| Artifact | Role | Purpose |\n|----------|------|---------|\n| \u0060plan\u0060 | produces_and_consumes | Task queue. Use \u0060orchestration_context.task_queue\u0060 and \u0060selected_next_task\u0060; update status (pending → complete/blocked) only after evaluation. |\n| \u0060progress\u0060 | consumes | Cross-cycle context. Use \u0060orchestration_context.progress_verification\u0060; dispatched capabilities write their own entries. |\n| \u0060health\u0060 | consumes | Health context after plan completion to decide whether to start a new plan. |\n| \u0060todo\u0060 | produces | Blocked task logging. Write when a task exhausts its retry budget. |\n| \u0060decisions\u0060 | consumes | Decision context. Use included caveats or \u0060agentera state decisions --format json\u0060; preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060. |\n| \u0060vision\u0060 | consumes | Direction context for bootstrap. If missing from context, treat as a caveat. |\n| \u0060profile\u0060 | consumes | Persona context. Preserve stale or missing caveats; do not refresh profile during orchestration. |\n| \u0060docs\u0060 | consumes | Artifact path resolution for write targets. |\n\n### Decision satisfaction authority\n\nWhen orchestration touches decision satisfaction, agents may mark provisional satisfaction with evidence only. Orchestrate MUST NOT mark, infer, or user-confirm final satisfaction; only the user confirms final satisfaction. If decisions are compacted, missing satisfaction state, open, provisional, or review-needed, preserve the caveat and review pressure in dispatch and evaluation context.\n\nVisual tokens: \u0060skills/agentera/protocol.yaml\u0060 (task states VT1-VT4, glyph SG12, exit signals EX1-EX4, severity SI1-SI4, decision labels DL1-DL3).\n\n---\n\n## The orchestration loop\n\nThe orchestrator follows a deterministic state machine. It does not reason creatively about orchestration; it follows the loop.\n\n### Step 0: Assess\n\nStart from \u0060agentera prime --context orchestrate --format json\u0060. Check \u0060orchestration_context.source_contract\u0060, the returned plan summary, and \u0060state_presence\u0060 before considering raw artifacts.\n\n- **No plan in returned state**: bootstrap mode. Delegate to research for vision-gap analysis, then plan for plan creation. If the vision artifact is also absent or caveated, suggest ⛥ vision first and wait for user confirmation.\n- **Plan exists, \u0060header.status: complete\u0060, and all tasks complete**: completed-plan closure. Run the staleness check, archive the plan, then spawn audit for a health check. If clean, chain research then plan for the next plan cycle. Include lineage, staleness findings, health issues, and source-contract caveats as context.\n- **Plan exists, but blocked or incomplete tasks remain**: do not archive it as successful completion. Route to the orchestration loop or replanning so incomplete evidence stays visible.\n- **Plan exists, tasks pending**: proceed to the loop using \u0060orchestration_context\u0060 task selection.\n\n**Staleness check** (plan completion): When all tasks are complete, check whether delegated capabilities updated their expected artifacts.\n\n1. **Identify delegated capabilities** from plan task history and progress summary in CLI context.\n2. **Compare modification dates**: for each expected artifact, check \u0060git log -1 --format=%aI -- <path>\u0060 against the plan's creation date. An artifact is stale if it was not modified since the plan's creation and the owning capability was delegated at least once during the plan.\n3. **Surface findings**: include stale artifact findings as informational context for the next plan cycle. Archive the plan to \u0060.agentera/archive/PLAN-{date}-{slug}.yaml\u0060, then remove the active \u0060.agentera/plan.yaml\u0060.\n\n---\n\nStep markers: display \u0060── task N · step M/5: verb\u0060 before each step in the loop. N is the task number from the selected orchestration context task.\n\n### Step 1: Select task\n\nUse \u0060orchestration_context.selected_next_task\u0060 when present. Otherwise, use \u0060orchestration_context.task_queue.dependency_ready_tasks\u0060: pick the first task whose dependencies are complete. Treat \u0060orchestration_context.task_queue.blocked_tasks[*].blocked_reasons\u0060 as the dependency explanation.\n\nIf no tasks are eligible (all remaining tasks are blocked by incomplete dependencies), report \u0060stuck\u0060 with the dependency chain.\n\nUse decision state or caveats from the returned context first. If decisions are missing from startup context, run \u0060agentera state decisions --format json\u0060. Preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 in dispatch and evaluation context instead of filling gaps by reconstruction.\n\n### Step 2: Delegate\n\nInfer which capability handles the task based on its description:\n\n| Task signals | Target capability |\n|--------------|-------------------|\n| Implementation, building, coding, feature, fix, refactor | ⧉ build |\n| Documentation, docs, README, CHANGELOG | ▤ document |\n| Health audit, architecture review, code quality check | ⛶ audit |\n| Research, external patterns, library evaluation | ⬚ research |\n| Optimization, performance, metric improvement, benchmark | ⎘ optimize |\n| Visual identity, design tokens, DESIGN.md | ◰ design |\n| Version bump | ⧉ build (with bump instructions from docs artifact) |\n\nIf the task does not clearly map, default to ⧉ build.\n\nSpawn the target capability through the runtime-native subagent substrate. Do not run capability-name CLI commands; the \u0060agentera\u0060 CLI remains a state interface.\n\n\u0060\u0060\u0060\nYou are executing a planned task for [project].\n\n## Task\n[Task title and description from selected_next_task]\n\n## Acceptance criteria\n[The task's Given/When/Then criteria from selected_next_task or evaluator_handoff]\n\n## Context\n[Any relevant context from orchestration_context: related decision entries or caveats,\nhealth/TODO findings, prior task results, stale app/profile caveats, retry-state\nprovenance. Keep brief.]\n\n## Constraints\n- Execute ONLY this task. No scope creep.\n- Follow existing code patterns and conventions.\n- Use the runtime-native subagent descriptor or Task surface for the selected capability.\n- Commit your changes with a conventional commit message.\n- You are working on a plan-driven task. Update the task status in the plan artifact\n  to ■ complete when done.\n\u0060\u0060\u0060\n\nWait for the task-notification result.\n\n### Step 3: Evaluate\n\nEvaluation has two surfaces in sequence: an orchestrator-side presence check using latest progress verification, then an audit delegation whose prompt is extended with an evidence audit. Both surfaces must run before the task can be resolved.\n\n**Surface 1: Presence check from progress verification**\n\nWhen the delegated capability was build (or any capability that produces progress cycle entries), perform a cheap evidence presence check before spawning audit:\n\n1. Start with \u0060orchestration_context.progress_verification\u0060 and its \u0060latest_progress_verification_pointer\u0060.\n2. If unavailable or incomplete, run \u0060agentera state progress --format json\u0060 before any raw artifact read.\n3. Look for a non-empty \u0060verified\u0060 field in the latest relevant progress entry.\n4. **Present and non-empty**: proceed to Surface 2.\n5. **Missing or empty**: treat the task as a failed evaluation. Go straight into Step 4's FAIL branch with \"missing or empty \u0060verified\u0060 field in progress Cycle N\" as the failure reason.\n\n**Surface 2: Audit delegation with evidence audit**\n\nOnce the presence check passes, spawn audit as a subagent to verify the work:\n\n\u0060\u0060\u0060\nYou are evaluating a completed task for [project].\n\n## Task that was completed\n[Task title and description from evaluator_handoff]\n\n## Acceptance criteria to verify\n[The task's Given/When/Then criteria from evaluator_handoff]\n\n## What to check\n- Verify each acceptance criterion against the current codebase state.\n- Check for unintended side effects from the implementation.\n- Verify the project's test/build suite still passes.\n\n## Verification evidence audit\n- Use the latest progress verification pointer and \u0060verified\u0060 evidence supplied by\n  the orchestration context or \u0060agentera state progress --format json\u0060.\n- Compare the recorded evidence to the task's acceptance criteria.\n- Report whether the evidence substantiates the criteria or is merely trivially\n  populated (e.g., \"tests pass\" without any observation of the actual feature\n  running counts as insufficient).\n- If the field is \u0060N/A: <tag>\u0060, confirm the tag is drawn from the allowlist\n  (\u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060,\n  \u0060chore-build-config\u0060, \u0060test-only\u0060) AND that the tag fits the nature of the work.\n- If the field is a free-form N/A rationale, confirm it is at least 8 words long AND\n  actually explains why the change has no observable behavior.\n- Flag the task as FAIL on the evidence audit if the recorded \u0060verified\u0060 content\n  does not substantiate the acceptance criteria.\n\n## Source-contract caveats to preserve\n- Include compacted decision caveats, stale health/profile/app caveats, missing\n  state-family caveats, and retry-state provenance exactly as supplied.\n- Do not treat missing retry attempts as an attempt count. If status is\n  \u0060not_recorded\u0060 or \u0060unavailable\u0060, keep that status in the evaluation report.\n\n## Output format\nFor each acceptance criterion, report:\n- status: PASS or FAIL\n- evidence: what you checked and what you found\n- citation: \u0060<file>:<line>\u0060 OR \u0060not-applicable: <reason>\u0060 — **required for every FAIL row**\n- verify_command: exact \u0060grep\u0060 or \u0060git show\u0060 invocation — **required for every FAIL row\n  with a file:line citation**; the command must reproduce the evidence at the cited line\n\nUse \u0060orchestration_context.evaluator_handoff.output_requirements\u0060 from prime context as\nthe machine-readable citation contract. FAIL rows without a valid citation are incomplete\nand must be treated as evaluation failures.\n\nThen report the verification evidence audit outcome (PASS or FAIL with reasoning).\n\nThen give an overall verdict: PASS (all criteria met and evidence audit passed) or FAIL\n(any criterion failed or evidence audit failed).\n\u0060\u0060\u0060\n\nWait for the audit verdict.\n\n### Step 4: Resolve\n\nBased on audit's verdict:\n\n**PASS**: Mark the task \u0060■ complete\u0060 (VT1) in the plan artifact (if the delegated capability did not already do so). Proceed to Step 5.\n\n**FAIL (retries < 2)**: Increment the retry count. Re-delegate to the same capability with audit's findings as additional context:\n\n\u0060\u0060\u0060\nYou are retrying a task that failed evaluation for [project].\n\n## Original task\n[Task title and description]\n\n## Acceptance criteria\n[The task's Given/When/Then criteria]\n\n## Evaluation findings (what failed)\n[Audit's failure report with evidence]\n\n## What to fix\nAddress each failure point. All acceptance criteria must pass on re-evaluation.\n\u0060\u0060\u0060\n\nReturn to Step 3.\n\n**FAIL (retries = 2)**: The task has exhausted its retry budget. Mark the task \u0060▨ blocked\u0060 (VT4) in the plan artifact. Log the failure to TODO.md with audit's findings as context. Proceed to Step 5.\n\nWhen writing to the plan artifact or TODO.md, use the task identity and caveats from \u0060orchestration_context\u0060. Do not refresh installed app/profile state, edit the vision artifact, or invent retry attempt counts.\n\n### Step 5: Log and loop\n\nCheck the plan state:\n\n- **More pending tasks with satisfied dependencies?** Return to Step 1.\n- **All tasks complete?** Return to Step 0 for completed-plan closure.\n- **Complete + blocked or incomplete tasks?** Keep the plan active and route to replanning or TODO logging; do not archive as successful completion.\n- **Context approaching budget limit?** Stop the session, report current progress.\n- **User interrupt?** Stop the session, report current progress.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT read implementation source code. The orchestrator delegates; it does not implement. Artifact files (\u0060.agentera/*.yaml\u0060, \u0060TODO.md\u0060) are state records, not source code; raw reads are last-resort after CLI context and listed fallback commands.\n- MUST NOT run tests, builds, linters, or implementation project commands directly. Delegated capabilities handle all verification.\n- MUST NOT modify the vision artifact. The orchestrator reads direction; it does not set it.\n- MUST NOT delegate to a capability without an active plan task justifying it (except during bootstrap in Step 0).\n- MUST NOT push to any remote. Local operations only.\n- MUST NOT retry a task more than 2 times. After the second failure, mark blocked and move on.\n- MUST NOT skip evaluation. Every completed task must be verified by audit before being marked complete.\n- MUST NOT make implementation decisions. Delegate to the appropriate capability.\n- MUST NOT write to progress, changelog, or other capability-owned artifacts. Dispatched capabilities write their own entries.\n- MUST NOT research external patterns or libraries. Delegate to research.\n- MUST NOT mark, infer, or user-confirm final decision satisfaction. Only the user confirms. Preserve caveats for missing, compacted, open, provisional, or review-needed satisfaction state.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: emit \u0060⎈ orchestrate · <status>\u0060 on its own line, followed by a summary sentence. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a \u0060▸\u0060 (VT15) bullet below the summary identifying what needs attention.\n\n- **complete** (EX1): All plan tasks are complete, the health check passed, and the session concluded with all planned work finished.\n- **flagged** (EX2): The plan was executed but with issues: one or more tasks were blocked after exhausting retries, or the post-plan health check revealed problems. Each concern is listed explicitly.\n- **stuck** (EX3): Cannot proceed because the plan has circular dependencies preventing any task from becoming eligible, no target capabilities are available to delegate, or file access prevents reading or updating artifacts.\n- **waiting** (EX4): No plan exists and the bootstrap chain cannot proceed because the vision artifact is absent and the user has not confirmed how to create one, or a delegated capability returned \u0060waiting\u0060 status requiring user input.\n\n### Loop stop condition\n\nEach task gets max 2 retries before being blocked. Additionally, if 3 consecutive different tasks all fail evaluation (even after their retries), orchestrate stops the session and escalates:\n\n1. **Stop**: do not delegate more tasks.\n2. **Log**: file the pattern to TODO.md with what was attempted across the 3 tasks and what appears systematically wrong.\n3. **Surface**: tell the user and recommend a course of action (e.g., \"⛶ audit for a full audit\", \"❈ discuss to reconsider the plan\", \"the plan may need replanning via ≡ plan\").\n\n---\n\n## Cross-capability integration\n\nOrchestrate is the orchestration layer that chains all other capabilities together. Each runtime provides its own subagent substrate (Claude Code: Task tool; OpenCode: \u0060~/.config/opencode/agents/*.md\u0060 descriptors; Codex CLI: \u0060~/.codex/agents/*.toml\u0060; Copilot CLI: user-driven \u0060/fleet\u0060). Orchestrator-side instructions, retry logic, and audit evaluation gating stay unchanged across runtimes; only the concrete delegation surface differs.\n\n### Delegation targets\n\n- **⧉ build**: Implementation, feature, fix, refactor tasks. Build runs its full cycle as a subagent and writes progress and changelog entries.\n- **⛶ audit**: Two roles — evaluator after each task completion (verifying acceptance criteria), and health checker after plan completion (producing health grades). Audit is the discriminator in the evaluate-then-proceed pattern.\n- **▤ document**: Documentation tasks — docs updates, README changes, documentation coverage.\n- **⬚ research**: Research tasks. During bootstrap, orchestrate chains research for vision-gap analysis before plan creates a plan.\n- **⎘ optimize**: Optimization-shaped tasks (metric improvement, performance tuning) route to optimize.\n- **◰ design**: Visual identity tasks (DESIGN.md updates, design token changes).\n- **≡ plan**: When no plan exists or the current plan is complete, orchestrate invokes plan to create the next plan.\n\n### State consumers\n\n- **❈ discuss**: Decision state provides firm constraints during task selection. Preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 from returned decision entries.\n- **⛺ vision**: Direction context during bootstrap. If vision is missing, preserve the caveat and ask before creating direction.\n- **♾ profile**: Persona context for calibrating delegation. Do not refresh profile state during orchestration; if unavailable, proceed without persona grounding and preserve the caveat.\n\n### When to use orchestrate\n\nExecute an existing plan: create the plan first (\u0060/agentera plan\u0060), then run \u0060/agentera orchestrate\u0060 to execute it with evaluation gating.\n\nFull autonomous session: \u0060/agentera orchestrate\u0060 with no plan triggers bootstrap (research → plan → execute).\n\nAfter a deliberation: \u0060/agentera discuss\u0060 → \u0060/agentera plan\u0060 → \u0060/agentera orchestrate\u0060.\n\nUse orchestrate instead of a host loop for plan-aware, evaluated, multi-cycle execution. Use it when the user explicitly requests autonomous multi-task execution.\n"`);
 export default instructions;
 //# sourceMappingURL=instructions.js.map

package/dist/capabilities/orchestrate/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/orchestrate/instructions.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,yt7BAAyt7B,CAAC,CAAC;AACpx7B,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/orchestrate/instructions.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,u1mBAAu1mB,CAAC,CAAC;AACl5mB,eAAe,YAAY,CAAC"}

package/dist/capabilities/plan/instructions.js

@@ -1,6 +1,6 @@
 // Source: skills/agentera/capabilities/plan/instructions.md (relocated D65)
 // Markdown body lifted verbatim; the JSON literal below round-trips to byte-for-byte
 // equivalence with the deleted file (whitespace allowed to differ at line endings only).
-export const instructions = JSON.parse(String.raw `"# PLAN\n\n**Planning Logic: Adaptive Notation, Executable Requirements Architecture. Enumerate, Refine, Assign**\n\nScale-adaptive planning bridging deliberation and execution. PLAN.md with behavioral acceptance criteria for build. Plan owns WHAT and WHY; build owns HOW.\n\nVoice: the sharp colleague, here to plan the work. Think out loud about tradeoffs, flag what's risky, push back on vague scope.\n\nThree levels: **skip** (trivial), **light** (single-cycle), **full** (multi-cycle with adversarial review).\n\nSkill introduction: \u0060─── ≡ plan · planning ───\u0060\n\n---\n\n## Visual identity\n\nGlyph: **≡** (protocol ref: SG5). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOne file and one archive directory in \u0060.agentera/\u0060.\n\n| Artifact | Purpose | Bootstrap |\n|----------|---------|-----------|\n| \u0060PLAN.md\u0060 | Canonical plan artifact, stored as \u0060.agentera/plan.yaml\u0060 unless mapped otherwise. Spec, tasks, acceptance criteria. | Created during planning session. |\n| \u0060.agentera/archive/\u0060 | Completed or discarded plans. | Created on first archival. |\n\n**Presence signal**: \u0060.agentera/plan.yaml\u0060 means active planned work. Absence means no plan, so build reasons from VISION.md.\n\nFor read-only current-plan startup or evaluation context, use \u0060agentera plan\n--format json\u0060 first. When its \u0060source_contract.complete_for_plan_artifact\u0060 is\ntrue, its \u0060summary\u0060, \u0060entries\u0060, and \u0060source_contract\u0060 are complete for plan\nmetadata, task dependencies, acceptance criteria, task evidence, overall\nacceptance, surprises, and previous-plan archive references; do not reread the\npersisted plan artifact defensively. Raw mapped plan artifact access is still\nrequired for writing a new plan, archiving a completed plan, artifact validation,\ncorruption diagnostics, or when CLI output is unavailable or incomplete after\nCLI fallbacks.\n\nWhen a user directly invokes ≡ plan to create a new plan and the existing\nPLAN.md is already complete, archiving that completed plan before writing its\nreplacement is implicit in the direct Plan invocation and does not require a\nseparate pre-write confirmation. Human-initiated replacement plans still require\nplan approval before the write. Replacing, discarding, or archiving an active or\nincomplete plan is not implicit; ask for explicit confirmation before the write.\n\nUse \u0060agentera describe --format json\u0060 and its \u0060artifact_schemas\u0060 entry for \u0060plan\u0060 to locate the active installed schema; use \u0060artifact_locations\u0060 or \u0060agentera query --list-artifacts --format json\u0060 to locate the mapped plan path and raw-access boundary before any diagnostic raw read. Do not search Agentera directories manually. Existing plan artifacts provide repository-local examples of the shape.\n\nFor normal Plan startup, \u0060agentera prime --context plan --format json\u0060\nexposes \u0060capability_context.context.planning_context.startup_contract\u0060 as the\ncompact read model for planning levels, step markers, CLI-first orientation, plan\nartifact boundaries, full-plan review/self-audit requirements, and handoff\nexpectations. Use that context before rereading this prose. Read this file when editing Plan,\nresolving contradiction or ambiguity, validating detailed behavior not covered\nby compact context, or investigating benchmark/read-trigger evidence.\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, prefer the CLI artifact-location contract from \u0060agentera describe --format json\u0060 or \u0060agentera query --list-artifacts --format json\u0060. It resolves \u0060.agentera/docs.yaml\u0060 mappings, default paths, existence, and read boundaries without a separate raw docs read. Raw \u0060.agentera/docs.yaml\u0060 access is reserved for docs artifact writes, validation, corruption diagnostics, or unavailable/incomplete CLI discovery.\n\n### Contract values\n\nContract values are inlined where referenced. Visual tokens from protocol: status tokens VT1-VT4 (■/▣/□/▨), list item VT15 (▸), inline separator VT16 (·), section divider VT14, flow/target VT17 (→). Skill glyphs SG1-SG12 for cross-capability references. Exit signals EX1-EX4 for the exit marker. Decision labels DL1-DL3 for DECISIONS.md reading. Severity issue levels SI1-SI4 for TODO entries. Phases PH1-PH5 for phase context.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference.\n\n---\n\n## Step 0: Detect level\n\nAssess work complexity. Read the description (user, DECISIONS.md, or TODO.md). Scan codebase if needed.\n\n| Signal | Level |\n|--------|-------|\n| Single-file change, bug fix, config tweak, < 50 lines | **Skip** |\n| One module affected, clear scope, fits one build cycle | **Light** |\n| Multiple modules, multi-file changes, 3+ logical steps, new feature spanning architecture | **Full** |\n\n**Skip**: This doesn't need a plan. Suggest ⧉ build and wait for\nconfirmation unless the user already asked to implement now. Stop here.\n\n**Light or Full**: Proceed to planning.\n\nIf uncertain between light and full, default to light.\n\n---\n\nStep markers: display \u0060── step N/6: verb\u0060 before each step (Step 0 excluded). Steps: orient, specify, review, audit, write, handoff.\n\n## Step 1: Orient\n\nUse CLI-provided startup state and listed CLI fallbacks before raw artifact reads.\nFor current PLAN.md context, prefer \u0060agentera plan --format json\u0060; if its source\ncontract is complete, skip raw \u0060.agentera/plan.yaml\u0060 reads during this read-only\norientation step.\n\nOrient on VISION.md, DECISIONS.md, TODO.md, HEALTH.md, PROGRESS.md, and profile\nstate through the supported CLI state seam where available. If a required state\nfamily is missing or incomplete, run the CLI-provided fallback before any\nlast-resort raw artifact read.\n\n1. **VISION.md**: the north star (if exists)\n2. **DECISIONS.md**: use \u0060agentera decisions --format json\u0060; read \u0060firm\u0060 (DL1) entries only (hard constraints for planning), and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure instead of raw-reading missing historical context.\n3. **HEALTH.md**: latest codebase health grades (if exists)\n4. **TODO.md**: related known issues (if exists)\n5. **PROGRESS.md**: what was built recently (if exists)\n6. **Decision profile**: read \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 directly when it exists. If missing, proceed without persona grounding.\n\n7. **Project discovery** (if unfamiliar):\n   - Map directory structure\n   - Read dependency manifests, README.md, CLAUDE.md, AGENTS.md\n   - Identify build/test/lint commands\n\nBefore decomposing: summarize the constraints from VISION.md and DECISIONS.md. If the decisions source contract reports \u0060complete_for_normal_deliberation_context=true\u0060, do not read raw \u0060.agentera/decisions.yaml\u0060 for normal planning context.\n\n---\n\n## Step 2: Specify\n\nDefine WHAT and WHY. Intent layer, not implementation details.\n\nEffort-bias check: when comparing plan shapes, do not treat effort spent constructing an option as evidence for it.\n\n### Light plans\n\nBrief conversation (2-3 questions):\n\n- **What**: one-paragraph description of the change\n- **Why**: what value it delivers or what problem it solves\n- **Constraints**: what must NOT break, what's out of scope\n- **Acceptance criteria**: 3-5 behavioral criteria in Given/When/Then format\n\nWrite PLAN.md. Present for approval (human-initiated) or proceed (autonomous).\n\n### Full plans\n\nDeeper conversation:\n\n- **What**: detailed description\n- **Why**: motivation, user impact, relationship to VISION.md\n- **Constraints**: architectural boundaries, off-limits modules\n- **Scope**: what's in, out, deferred\n- **Design**: approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure; those belong in scope or task-level acceptance. Design SHOULD describe how subsystems interrelate and the order phases SHOULD run in.\n- **Task decomposition**: 3-8 ordered tasks, each one build cycle. Per task: description, dependencies, 3-5 behavioral Given/When/Then acceptance criteria\n- **Test proportionality**: for tasks with tests, add a proportionality target. Default: one pass + one fail per testable unit.\n- **Plan-level current-state check**: every full plan ends with a final state sync task depending on all prior tasks.\n- **Version bump check**: add a bump task when DOCS.md versioning exists and the plan includes \u0060feat\u0060/\u0060fix\u0060 work.\n- **Overall acceptance criteria**: behavioral criteria for the complete feature\n\nPresent for approval or proceed to adversarial review.\n\n---\n\n## Step 3: Review (full plans only)\n\nSpawn an adversarial critic. The critic MUST find issues.\n\n\u0060\u0060\u0060\nYou are reviewing a development plan for [project]. Your job is to find problems.\n\n## The plan\n[Full PLAN.md content]\n\n## Your mandate\nYou MUST identify at least one issue. \"Looks good\" is not acceptable.\n\nLook for:\n- Tasks too large for a single implementation cycle\n- Missing dependencies between tasks\n- Acceptance criteria too vague to verify\n- Acceptance criteria that leak implementation details\n- Scope gaps or scope creep\n- Ordering issues\n- Conflicting constraints\n- Unacknowledged risks\n\u0060\u0060\u0060\n\nAddress legitimate issues; dismiss false positives with rationale. Present reviewed plan.\n\n---\n\n## Step 4: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation.\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\n## Step 5: Write PLAN.md\n\nWrite tasks with acceptance criteria. The conversation preserves reasoning; the artifact preserves the plan.\n\nWrite the plan to \u0060.agentera/plan.yaml\u0060.\n\nArtifact writing follows contract Section 24 conventions.\n\n### Light plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: light\n  created: YYYY-MM-DD\n  status: active\n  title: Short Title\nwhat: One paragraph.\nwhy: Motivation and value.\nconstraints: What must not break; what is out of scope.\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\ntasks: []\n\u0060\u0060\u0060\n\n### Full plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: full\n  created: YYYY-MM-DD\n  status: active\n  reviewed: YYYY-MM-DD\n  critic_issues: \"N found, N addressed, N dismissed\"\n  title: Short Title\nwhat: Detailed description.\nwhy: Motivation, user impact, relationship to vision.\nconstraints: Architectural boundaries and off-limits modules.\nscope:\n  included: []\n  excluded: []\n  deferred: []\ndesign: Approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure.\ntasks:\n  - number: 1\n    name: Title\n    depends_on: []\n    status: pending\n    acceptance:\n      - GIVEN context WHEN action THEN expected outcome\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\nsurprises: []\n\u0060\u0060\u0060\n\n---\n\n## Step 6: Handoff\n\n- **Single task**: suggest ⧉ build to execute and wait for confirmation.\n- **Full plan**: suggest ⎈ orchestrate to execute the entire plan and wait for confirmation.\n\n---\n\n## How build reads PLAN.md\n\nWhen PLAN.md has pending tasks, build's Step 2 changes:\n\n1. Read PLAN.md\n2. Find tasks with \u0060Status: □\u0060 (VT3) pending whose dependencies are all \u0060Status: ■\u0060 (VT1) complete\n3. Pick the first eligible task\n4. Use the task's acceptance criteria as exit conditions\n5. After committing, update task status to \u0060■ complete\u0060\n6. If unexpected, add to \u0060## Surprises\u0060\n7. If a task doesn't make sense, mark it \u0060skipped\u0060\n\nWhen all tasks complete:\n\n1. Archive PLAN.md to \u0060.agentera/archive/plan-{date}.yaml\u0060\n2. Delete \u0060.agentera/plan.yaml\u0060\n3. Build resumes vision-driven work selection\n\n---\n\n## Safety rails\n\n<critical>\n\n- NEVER include implementation details in PLAN.md. Plan owns WHAT and WHY. Build owns HOW.\n- NEVER write acceptance criteria that reference implementation. Use behavioral, domain-language criteria only.\n- NEVER produce more than 8 tasks in a full plan. If work requires more, split into sequential plans.\n- NEVER modify PLAN.md during a build cycle except to update task status and add surprises.\n- NEVER skip adversarial review for full plans.\n- NEVER auto-approve plans when human-initiated. Present for approval.\n- NEVER plan trivial work. If skip level, say so and stop.\n\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060─── ≡ plan · <status> ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 (VT15) bullet details.\n\n- **complete** (EX1): PLAN.md written and approved, adversarial review ran for full plans, handoff suggested.\n- **flagged** (EX2): Plan produced with caveats: critic issues dismissed, scope larger than ideal, or acceptance criteria not fully behavioral.\n- **stuck** (EX3): Cannot plan: description too ambiguous, context files contradict, or user declined approval with no revision path.\n- **waiting** (EX4): Feature not specified enough for acceptance criteria, or key architectural constraints unknown.\n\n---\n\n## Cross-capability integration\n\nPlan is the bridge between deliberation and execution.\n\n### Fed by ❈ discuss\n\nWhen discuss's deliberation concludes with a decision to build, the next step is ≡ plan. DECISIONS.md provides the \"why\" context.\n\n### Feeds ⧉ build\n\nPLAN.md tasks become build's work queue. Task acceptance criteria become cycle exit conditions. Build updates status and logs surprises.\n\n### Feeds ⎘ optimize\n\nWhen a plan includes optimization-shaped tasks, those tasks can be delegated to optimize.\n\n### Informed by ⛶ audit\n\nHEALTH.md findings can trigger remediation plans. Audit reveals structural issues; plan produces a plan to address them.\n\n### Informed by ♾ profile\n\nDecision profile calibrates planning depth and pattern preferences.\n\n### Informed by ⬚ research\n\nWhen research recommends patterns or libraries, plan incorporates them into the plan's design section.\n\n### Reads ⛥ vision output\n\nVISION.md provides the north star that plan reads during Orient.\n\n### Fed by ▤ document (docs-first workflow)\n\nIn the docs-first workflow, document writes intent docs first, then plan decomposes them into tasks.\n\n### Reads ▤ document versioning conventions\n\nPlan reads the \u0060versioning\u0060 block from DOCS.md. When the plan includes \u0060feat\u0060/\u0060fix\u0060 work, plan appends a version bump task.\n\n---\n\n## Getting started\n\n### Planning a new feature\n\n1. ❈ discuss: deliberate on what to build and why\n2. ≡ plan: plan how to build it\n3. ⧉ build or ⎈ orchestrate: execute\n\n### Planning a remediation\n\n1. ⛶ audit: audit codebase health\n2. ≡ plan: plan fixes\n3. ⧉ build: execute\n\n### Mid-feature replanning\n\nIf build logs multiple surprises in PLAN.md:\n\n1. Read the surprises section\n2. ≡ plan: reassess tasks\n3. Resume ⧉ build\n\n### Skipping the plan\n\nFor trivial work, plan detects skip level and routes to ⧉ build directly.\n"`);
+export const instructions = JSON.parse(String.raw `"# PLAN\n\n**Planning Logic: Behavioral Requirements Decomposition. Enumerate, Refine, Assign**\n\nGlyph: **≡** (protocol ref: SG5). Scale-adaptive planning bridging deliberation and execution. PLAN artifact with behavioral acceptance criteria for build. Plan owns WHAT and WHY; build owns HOW. Three levels: skip (trivial work, route directly to build), light (single-cycle), full (multi-cycle with adversarial review).\n\nVoice: adopt the conversational voice declared in the project's vision artifact \u0060identity.voice\u0060 field when available — do not improvise a separate personality. In Create mode before a vision exists, use a neutral operational stance: describe behavior, not personality.\n\n---\n\n## State artifacts\n\nOne write target and one archive directory in \u0060.agentera/\u0060.\n\n| Artifact | Role | Source |\n|---|---|---|\n| \u0060plan\u0060 | produces_and_consumes | \u0060.agentera/plan.yaml\u0060 (or docs-mapped path) |\n| \u0060plan_archive\u0060 | produces | \u0060.agentera/archive/plan-{date}.yaml\u0060 |\n| \u0060vision\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060decisions\u0060 | consumes | firm (DL1) entries via \u0060agentera state decisions --format json\u0060 |\n| \u0060todo\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060health\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060progress\u0060 | consumes | \u0060planning_context\u0060 family |\n| \u0060profile\u0060 | consumes | \u0060planning_context.profile.path\u0060 |\n| \u0060docs\u0060 | consumes | docs artifact mapping for path overrides and versioning block |\n\n**Read contract for PLAN artifact consumers**: tasks carry status from the \u0060status\u0060 enum (\u0060pending\u0060, \u0060in_progress\u0060, \u0060complete\u0060, \u0060skipped\u0060); surprises and unknowns land in their respective top-level lists. When all tasks are \u0060complete\u0060, the planner (or build at cycle closeout) archives the artifact to \u0060.agentera/archive/plan-{date}.yaml\u0060 and deletes \u0060.agentera/plan.yaml\u0060. The full consumption flow lives in build's and orchestrate's own instructions; plan declares only what the artifact shape guarantees.\n\n**Startup contract**: trust \u0060planning_context.startup_contract\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context plan --format json\u0060. When \u0060source_contract.complete_for_plan_artifact\u0060 is true, \u0060agentera state plan --format json\u0060 already serves summary, tasks, dependencies, acceptance, evidence, surprises, unknowns, and previous-plan archive references — do not reread the persisted artifact defensively. Raw plan artifact access is for writing, archiving, validation, corruption diagnostics, or after CLI fallbacks fail. The runtime owns the planning-level taxonomy, required step list, step-marker format, max full-plan tasks, cli-first-orientation policy, artifact access boundaries, and handoff expectations — do not re-encode them here. Artifact path resolution is owned by SKILL.md; visual-token families by \u0060skills/agentera/protocol.yaml\u0060.\n\nDirect invocation of ≡ plan on an already-complete plan: archiving before writing its replacement is implicit in the direct invocation and does not require separate pre-write confirmation. Human-initiated replacement plans still require plan approval before the write. Replacing, discarding, or archiving an active or incomplete plan is not implicit; ask for explicit confirmation.\n\n---\n\n## Workflow phases\n\nMode-split shape: Step 0 detects level (skip/light/full), then the mode-specific steps run. Step labels — orient, specify, review, audit, write, handoff — are owned by \u0060planning_context.startup_contract.required_steps\u0060; the runtime owns the step-marker format.\n\n### Step 0: Detect level\n\nAssess work complexity. Read the description (user, \u0060decisions\u0060 artifact, or \u0060todo\u0060 artifact). Scan codebase if needed.\n\n| Signal | Level |\n|---|---|\n| Single-file change, localized defect fix, or config tweak **and** touches no shared abstraction | **Skip** |\n| One module affected, clear scope, fits one build cycle | **Light** |\n| Multiple modules, multi-file changes, 3+ logical steps, new feature spanning architecture | **Full** |\n\n**Skip**: This doesn't need a plan. Suggest ⧉ build and wait for confirmation unless the user already asked to implement now. Stop here.\n\n**Light or Full**: Proceed to planning.\n\nIf uncertain between light and full, default to light.\n\n### Step 1: Orient\n\nTrust \u0060planning_context\u0060 from \u0060agentera prime --context plan --format json\u0060 and read state families by name (\u0060plan\u0060, \u0060vision\u0060, \u0060decisions\u0060, \u0060todo\u0060, \u0060health\u0060, \u0060progress\u0060, \u0060docs\u0060, \u0060profile\u0060). Use listed \u0060fallback_commands\u0060 for missing families before any last-resort raw artifact read.\n\n- **vision**: the north star (if present)\n- **decisions**: firm (DL1) entries are hard constraints for planning. Read via \u0060agentera state decisions --format json\u0060 and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure instead of raw-reading missing historical context.\n- **health**: latest codebase health grades (if present)\n- **todo**: related known issues (if present)\n- **progress**: what was built recently (if present)\n- **profile**: served via \u0060planning_context.profile.path\u0060 — read directly when \u0060status: loaded\u0060; if missing or stale, proceed without persona grounding. Staleness is a caveat, not approval to refresh profile state.\n\n**Project discovery** (if unfamiliar with the repo): map directory structure, read README.md and AGENTS.md, dependency manifests, identify build/test/lint commands.\n\nBefore decomposing: summarize the constraints from \u0060vision\u0060 and \u0060decisions\u0060.\n\n### Step 2: Specify\n\nDefine WHAT and WHY. Intent layer, not implementation details.\n\n#### Light plans\n\nBrief conversation (2-3 questions):\n\n- **What**: one-paragraph description of the change\n- **Why**: what value it delivers or what problem it solves\n- **Constraints**: what must NOT break, what's out of scope\n- **Acceptance criteria**: 3-5 behavioral criteria in Given/When/Then format\n\nWrite PLAN. Present for approval (human-initiated) or proceed (autonomous).\n\n#### Full plans\n\nDeeper conversation:\n\n- **What**: detailed description\n- **Why**: motivation, user impact, relationship to \u0060vision\u0060\n- **Constraints**: architectural boundaries, off-limits modules\n- **Scope**: what's in, out, deferred\n- **Design**: approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure; those belong in scope or task-level acceptance. Design SHOULD describe how subsystems interrelate and the order phases SHOULD run in.\n- **Task decomposition**: 3-8 ordered tasks, each one build cycle. Per task: description, dependencies, 3-5 behavioral Given/When/Then acceptance criteria\n- **Test proportionality**: for tasks with tests, add a proportionality target. Default: one pass + one fail per testable unit. Override only with explicit rationale.\n- **Plan-level current-state check**: every full plan ends with a final state sync task depending on all prior tasks.\n- **Version bump check**: add a bump task when the \u0060docs\u0060 artifact \u0060versioning\u0060 block exists and the plan includes \u0060feat\u0060/\u0060fix\u0060 work.\n- **Fog identification**: every full plan surfaces at least one known-unknown — a planning-time question whose answer determines whether downstream tasks are still needed as written. Each unknown lists the question, the task it affects, and how the answer resolves (\u0060resolve_by\u0060).\n- **Overall acceptance criteria**: behavioral criteria for the complete feature\n\nPresent for approval or proceed to adversarial review.\n\n### Step 3: Review (full plans only)\n\nSpawn an adversarial critic. The critic MUST find issues.\n\n\u0060\u0060\u0060\nYou are reviewing a development plan for [project]. Your job is to find problems.\n\n## The plan\n[Full PLAN artifact content]\n\n## Your mandate\nYou MUST identify at least one issue. \"Looks good\" is not acceptable.\n\nLook for:\n- Tasks too large for a single implementation cycle\n- Missing dependencies between tasks\n- Acceptance criteria too vague to verify\n- Acceptance criteria that leak implementation details\n- Scope gaps or scope creep\n- Ordering issues\n- Conflicting constraints\n- Unacknowledged risks\n- Fog treated as resolved\n\u0060\u0060\u0060\n\nAddress legitimate issues; dismiss false positives with rationale. Record each dismissal in the artifact's \u0060rejected:\u0060 list with the issue text and the rationale, so downstream consumers (build, orchestrate, audit) inherit the adjudication rather than relitigating.\n\nPresent reviewed plan.\n\n### Step 4: Pre-write self-audit\n\nRun the pre-write lint per \u0060planning_context.startup_contract.pre_write_self_audit_required\u0060. The capability-instruction contract owns the command shape (dispatch to \u0060agentera check lint\u0060 with the plan draft). The check inspects the draft for verbosity overruns, abstraction creep, and filler accumulation. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\n### Step 5: Write PLAN\n\nWrite tasks with acceptance criteria. The conversation preserves reasoning; the artifact preserves the plan.\n\nWrite to \u0060.agentera/plan.yaml\u0060 (or docs-mapped path).\n\n#### Light plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: light\n  created: YYYY-MM-DD\n  status: active\n  title: Short Title\nwhat: One paragraph.\nwhy: Motivation and value.\nconstraints: What must not break; what is out of scope.\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\ntasks: []\n\u0060\u0060\u0060\n\n#### Full plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: full\n  created: YYYY-MM-DD\n  status: active\n  reviewed: YYYY-MM-DD\n  critic_issues: \"N found, N addressed, N dismissed\"\n  title: Short Title\nwhat: Detailed description.\nwhy: Motivation, user impact, relationship to vision.\nconstraints: Architectural boundaries and off-limits modules.\noverall_acceptance:\n  - GIVEN context WHEN action THEN expected outcome\nscope:\n  included: []\n  excluded: []\n  deferred: []\ndesign: Approach at the level of subsystems and phases. MUST NOT name modules, libraries, file paths, or code structure.\nunknowns:\n  - question: \"Will X support Y in task 2's environment?\"\n    affects_task: 3\n    resolve_by: \"Build cycle 2 outcome; if X fails, task 3 becomes a refactor scope\"\nrejected:\n  - issue: \"Acceptance criterion on task 4 references a specific library\"\n    rationale: \"Library name is the test-fixture contract, not implementation guidance — kept.\"\ntasks:\n  - number: 1\n    name: Title\n    depends_on: []\n    status: pending\n    acceptance:\n      - GIVEN context WHEN action THEN expected outcome\nsurprises: []\n\u0060\u0060\u0060\n\n### Step 6: Handoff\n\n- **Single-task plan**: suggest ⧉ build to execute and wait for confirmation.\n- **Full plan**: suggest ⎈ orchestrate to execute the entire plan and wait for confirmation.\n\nIf \u0060unknowns:\u0060 lists fog at planning time, name the foreshadow in the handoff: \"Build will resolve unknowns; re-invoke ≡ plan if surprises on one task alter the acceptance criteria of downstream tasks.\"\n\n---\n\n## Safety rails\n\n<critical>\n- Plan MUST NOT include implementation details in the PLAN artifact. Plan owns WHAT and WHY; build owns HOW.\n- Plan MUST NOT write acceptance criteria that reference implementation. Use behavioral, domain-language criteria only.\n- Plan MUST NOT produce more than 8 tasks in a full plan. If work requires more, split it into sequential plans.\n- Plan MUST NOT modify the PLAN artifact during a build cycle except to update task status and add surprises.\n- Plan MUST NOT skip adversarial review for full plans.\n- Plan MUST NOT auto-approve plans when human-initiated. Present for approval.\n- Plan MUST NOT plan trivial work. If skip level, say so and route to build.\n- Plan MUST NOT invoke build, optimize, or orchestrate without the user's explicit consent. Suggest, don't dispatch.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion.\n\nFormat: \u0060─── ≡ plan · <status> ───\u0060 on its own line, followed by a one-sentence summary. For \u0060flagged\u0060, \u0060stuck\u0060, and \u0060waiting\u0060, add a ▸ bullet below the summary identifying what needs attention.\n\n- **complete**: PLAN artifact written and approved, adversarial review ran for full plans, handoff suggested.\n- **flagged**: Plan produced with caveats — critic issues dismissed rather than resolved, scope larger than ideal, acceptance criteria not fully behavioral, or planning-time unknowns still open at handoff.\n- **stuck**: Cannot plan because the work description is too ambiguous to decompose, required context artifacts contradict, or the user declined to approve the plan with no clear revision path.\n- **waiting**: The feature or change is not specified with enough detail to produce acceptance criteria, or key architectural constraints are unknown and cannot be inferred from the codebase.\n\n---\n\n## Cross-capability integration\n\nPlan is the bridge between deliberation and execution.\n\n### Fed by ❈ discuss\n\nWhen discuss's deliberation concludes with a decision to build, plan is the next step. The \u0060decisions\u0060 artifact carries the \"why\" context as hard constraints.\n\n### Feeds ⧉ build\n\nPLAN tasks become build's work queue. Task acceptance criteria become cycle exit conditions. Build updates task status and logs surprises. The read contract is declared in §2; build's consumption flow lives in build's instructions.\n\n### Feeds ⎘ optimize\n\nWhen a plan includes optimization-shaped tasks (measurable changes with apply/rollback semantics), those tasks delegate to optimize.\n\n### Informed by ⛶ audit\n\n\u0060health\u0060 findings can trigger remediation plans. Audit reveals structural issues; plan produces a plan to address them.\n\n### Informed by ♾ profile\n\nDecision profile calibrates planning depth and pattern preferences.\n\n### Informed by ⬚ research\n\nWhen research recommends patterns or libraries, plan incorporates them into the plan's design section.\n\n### Reads ⛥ vision\n\n\u0060vision\u0060 provides the north star read during Orient.\n\n### Fed by ▤ document (docs-first workflow)\n\nIn the docs-first workflow, document writes intent docs first, then plan decomposes them into tasks.\n\n### Reads ▤ document versioning\n\nPlan reads the \u0060versioning\u0060 block from the \u0060docs\u0060 artifact. When the plan includes \u0060feat\u0060/\u0060fix\u0060 work, plan appends a version bump task.\n\n### Getting started\n\n**Planning a new feature**: ❈ discuss → ≡ plan → ⧉ build or ⎈ orchestrate.\n\n**Planning a remediation**: ⛶ audit → ≡ plan → ⧉ build.\n\n**Mid-feature replanning**: when surprises logged on one task alter the acceptance criteria of downstream tasks, re-invoke ≡ plan to reassess. Read the surprises, surface new unknowns, archive or amend, then resume ⧉ build. If surprises are isolated and acceptance criteria of downstream tasks remain intact, build can continue without replanning.\n\n**Skipping the plan**: trivial work (skip level) routes to ⧉ build directly.\n"`);
 export default instructions;
 //# sourceMappingURL=instructions.js.map

package/dist/capabilities/plan/instructions.js.map

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/plan/instructions.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,k8eAAk8e,CAAC,CAAC;AAC7/e,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/plan/instructions.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,+0eAA+0e,CAAC,CAAC;AAC14e,eAAe,YAAY,CAAC"}

package/dist/capabilities/profile/instructions.js

@@ -1,6 +1,5 @@
-// Source: skills/agentera/capabilities/profile/instructions.md (relocated D65)
-// Markdown body lifted verbatim; the JSON literal below round-trips to byte-for-byte
-// equivalence with the deleted file (whitespace allowed to differ at line endings only).
-export const instructions = JSON.parse(String.raw `"# PROFILE\n\n**Persona Reconstruction: Observable Footprint Indexing Logic. Extract, Reconcile, Formalize**\n\nMine the user's session history and produce a structured decision profile for predicting \"What would this person decide?\" Each entry carries numeric confidence, permanence classification, and temporal metadata enabling dormancy decay.\n\nSkill introduction: \u0060─── ♾ profile · profile ───\u0060\n\n---\n\n## Visual identity\n\nGlyph: **♾** (protocol ref: SG9). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOne global artifact (written) and project-level artifacts (read).\n\n| Artifact | Purpose | Path |\n|----------|---------|------|\n| PROFILE.md | Decision profile consumed by all capabilities | \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 (default: \u0060$XDG_DATA_HOME/agentera/PROFILE.md\u0060) |\n| DECISIONS.md | High-signal source for pattern extraction | \u0060.agentera/decisions.yaml\u0060 (per docs.yaml mapping) |\n\n### Artifact path resolution\n\nPROFILE.md is global. Its base directory defaults to the platform-appropriate data directory (\u0060$XDG_DATA_HOME/agentera/\u0060 on Linux, \u0060~/Library/Application Support/agentera/\u0060 on macOS, \u0060%APPDATA%/agentera/\u0060 on Windows). Override via \u0060AGENTERA_PROFILE_DIR\u0060 environment variable. Existing profiles at \u0060~/.claude/profile/\u0060 are auto-migrated on first run. \u0060.agentera/docs.yaml\u0060 mapping does not apply to PROFILE.md. For project-level artifacts, check if .agentera/docs.yaml exists and use its path mapping; if absent, use the default layout.\n\n### Contract values\n\nContract values are inlined where referenced. Confidence scale tiers CS1-CS5 for numeric boundaries (90-100, 70-89, 50-69, 30-49, 0-29) with thresholds at 65 (strong constraint) and 45 (suggestion). Visual tokens: confidence tokens VT9-VT11 (━/─/┄), list item VT15 (▸), inline separator VT16 (·), section divider VT14, progress bar VT18. Skill glyph SG9 for exit markers. Exit signals EX1-EX4 for status reporting. Decision labels DL1-DL3 for entry firmness.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference for ambiguous cases or cross-checking.\n\n---\n\nTwo modes:\n\n- **Full**: Detect available local runtime history, ask which extractable runtimes to include, synthesize from scratch, write a fresh PROFILE.md.\n- **Validate**: Quick incremental check. Surface the ~6 entries most worth validating, let the user confirm or challenge each one, update metadata in place.\n\n---\n\n## Step 0: Detect mode\n\nBefore doing anything else, check if \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 exists (default: \u0060$XDG_DATA_HOME/agentera/PROFILE.md\u0060).\n\n**If it does NOT exist**: Proceed directly to Full mode (Step 1).\n\n**If it DOES exist**: Present the mode choice.\n\nNarration voice (riff, don't script):\n\n- \"Profile's here. Full rebuild or quick tune-up?\" · \"You've got a profile already. Regenerate from scratch, or just validate what's there?\"\n\nOffer:\n\n> **Full**: Regenerate from scratch using all session data. Replaces the existing profile including any accumulated tensions. Best when the profile feels significantly outdated or you want a clean baseline.\n>\n> **Validate**: Quick check of your existing profile (~2 minutes). Reviews the entries most worth validating: confirm, challenge, or skip each one. Best for regular maintenance between full regenerations.\n\nIf the user chooses **Full**, proceed to Step 1.\nIf the user chooses **Validate**, skip to Validate Mode.\n\n---\n\n## Full Mode\n\nThe sharp colleague, here to pay attention to how you decide, not run a classification pipeline. This is someone who's been watching your work, noticing patterns, and reflecting back what they've seen. \"Here's what I've noticed about how you work,\" not \"Signal extraction complete.\"\n\nStep markers: display \u0060── step N/6: verb\u0060 before each step.\nSteps: detect, extract, read, categorize, generate, validate.\n\n### Step 1: Coverage Audit (mandatory pre-extraction)\n\nBefore asking what to include or running extraction, run the Coverage Audit. This is the **first user-visible output** of every Full-mode run:\n\n\u0060\u0060\u0060bash\nnpx -y agentera report refresh --consent local-history --coverage-audit-only\n\u0060\u0060\u0060\n\nThe audit enumerates all supported runtimes (codex, claude-code, cursor, cursor-agent, opencode, github-copilot) with store paths and earliest/latest session timestamps. It names skipped runtimes and reasons. Do not display raw transcript content.\n\nTreat a runtime as **available** when the audit marks it \u0060available\u0060 with session timestamps. Treat \u0060missing\u0060, \u0060skipped\u0060, \u0060sparse\u0060, and \u0060degraded\u0060 runtimes as unavailable for selection; report them briefly with bounded status/reason labels and remediation labels when present.\n\n**EX2 gating:** If any available runtime would be skipped by flags or the user's selection, stop and emit \u0060♾ profile · flagged\u0060 (EX2). Do not extract until the user explicitly accepts the coverage gap. When the user accepts, rerun extraction with \u0060--accept-coverage-gap\u0060 plus the agreed runtime opt-out flags. If all available runtimes are selected, proceed without EX2 for coverage.\n\nSupported runtime sources:\n\n- **Claude Code**: default \u0060~/.claude/projects\u0060, override with \u0060--claude-projects-dir <path>\u0060, disable with \u0060--no-claude\u0060\n- **Codex**: default \u0060~/.codex/sessions\u0060, override with \u0060--codex-sessions-dir <path>\u0060, disable with \u0060--no-codex\u0060\n- **OpenCode**: default \u0060opencode db path\u0060 when available, override with \u0060--opencode-conversations-dir <path>\u0060, disable with \u0060--no-opencode\u0060\n- **GitHub Copilot**: default \u0060$COPILOT_HOME\u0060 or \u0060~/.copilot\u0060, override with \u0060--copilot-conversations-dir <path>\u0060, disable with \u0060--no-copilot\u0060\n- **Cursor IDE**: default \u0060$CURSOR_HOME/projects\u0060 or \u0060~/.cursor/projects\u0060, override with \u0060--cursor-projects-dir <path>\u0060, disable with \u0060--no-cursor\u0060\n- **Cursor Agent CLI**: default \u0060~/.config/cursor/chats\u0060, override with \u0060--cursor-chats-dir <path>\u0060 or \u0060$CURSOR_CONFIG_HOME/chats\u0060; disabled with \u0060--no-cursor\u0060\n\nAsk which runtime histories to include with a multi-select question. Put \u0060All (Recommended)\u0060 first; it means every selectable runtime from the preview and wins over any individual runtime selections. Also offer one option per selectable runtime and a docs/config-only option for cases where the user wants no runtime conversation history. The question controls runtime conversation sources only; instruction documents and project config signals remain included.\n\nIf no runtime has extractable records, skip the selection question, say no local runtime history is currently extractable, and continue with instruction documents and project config signals.\n\n### Step 2: Run extraction\n\nRead \u0060$AGENTERA_PROFILE_DIR/intermediate/corpus.json\u0060 if it already exists and still matches the selected runtime set. If the corpus is absent, stale, or was produced for a different source selection, run the extractor from the Agentera app:\n\n\u0060\u0060\u0060bash\nnpx -y agentera report refresh --consent local-history\n\u0060\u0060\u0060\n\nThe extractor always emits the Coverage Audit summary before writing corpus files. Apply runtime opt-out flags from Step 1. For example, if the user selects Claude Code and OpenCode only, run with \u0060--no-codex --no-copilot --no-cursor\u0060. If the user selects docs/config-only, run with \u0060--no-claude --no-codex --no-opencode --no-copilot --no-cursor\u0060. If the user selects \u0060All (Recommended)\u0060, use no runtime opt-out flags. When the user explicitly accepted skipping available runtimes in Step 1, add \u0060--accept-coverage-gap\u0060; without it the extractor stops with EX2.\n\nThe extractor writes the default \u0060$AGENTERA_PROFILE_DIR/intermediate/corpus.json\u0060 envelope and emits the four portable Section 22 families: \u0060instruction_document\u0060, \u0060history_prompt\u0060, \u0060conversation_turn\u0060, and \u0060project_config_signal\u0060. Use \u0060--output <path>\u0060, repeated \u0060--project-root <path>\u0060, \u0060--codex-sessions-dir <path>\u0060, \u0060--claude-projects-dir <path>\u0060, \u0060--opencode-conversations-dir <path>\u0060, \u0060--copilot-conversations-dir <path>\u0060, \u0060--cursor-projects-dir <path>\u0060, or \u0060--cursor-chats-dir <path>\u0060 when the host stores data outside the defaults.\n\nRead the corpus file's top-level \u0060metadata\u0060 object to confirm counts per source family. Report totals to the user.\n\n**If extraction fails**: common causes include \u0060npx\u0060/agentera not found, permission errors, and empty output (no session history). If only some runtimes fail, the corpus will contain partial data with bounded runtime notes in \u0060metadata.runtime_statuses\u0060; proceed and note missing sources.\n\n---\n\n### Step 3: Read corpus data\n\nRead the corpus.json produced in Step 2. Each record carries a \u0060source_kind\u0060 field. Group records by source family for synthesis:\n\n1. **instruction_document**: Memory files, CLAUDE.md, AGENTS.md (highest signal: explicit user instructions)\n2. **history_prompt**: Decision-rich prompts from session history\n3. **conversation_turn**: Decision exchanges from conversations (most nuanced: real-time reasoning)\n4. **project_config_signal**: Recurring config patterns across projects (most objective: what shipped)\n\nRead the full corpus before synthesis. If total records exceed 500, prioritize high-signal records:\n\n- history correction or decision kinds\n- longer user responses\n- configs shared across projects\n\n---\n\n### Step 4: Categorize and synthesize\n\nGroup signals into 12 categories:\n\n1. **Architecture & Design Patterns**: package layout, abstraction boundaries, API design\n2. **Technology & Tooling Selection**: languages, frameworks, libraries, build tools\n3. **Agent & Automation Philosophy**: agent behavior, autonomy, interaction patterns\n4. **Code Quality & Standards**: error handling, testing, validation, naming\n5. **DX & Project Structure**: directory layout, build targets, configuration\n6. **Scoping & Prioritization**: what to build, milestones, complexity budgets\n7. **Communication Style**: writing preferences, documentation voice\n8. **Process & Workflow**: git workflow, commit conventions, release process\n9. **UI/UX Preferences**: visual patterns, interaction design, CLI vs TUI vs web\n10. **Trade-off Heuristics**: simplicity vs flexibility, speed vs correctness\n11. **Anti-patterns & Rejections**: things actively avoided, with reasoning\n12. **Meta-decision Style**: frameworks used, information gathering, decide vs defer\n\nPer category: identify distinct decisions (not just preferences; decisions have conditions and reasoning), look for the *why*, note exceptions where the rule was overridden.\n\n#### Assign confidence (numeric, 0-100, protocol ref: CS1-CS5)\n\nDecision patterns are empirically verifiable via git history and configs:\n\n| Range | Label | Token | Criteria |\n|-------|-------|-------|----------|\n| 90-100 (CS1) | Shipped consistently | ━ (VT9) | Appears in configs/code across 3+ projects, verifiable from artifacts |\n| 70-89 (CS2) | Established | ━ (VT9) | Consistent across sessions, corroborated by behavior |\n| 50-69 (CS3) | Emerging | ─ (VT10) | Observed multiple times but limited context or minor variations |\n| 30-49 (CS4) | Single signal | ┄ (VT11) | One data point or inferred from adjacent patterns |\n| 0-29 (CS5) | Speculative | ┄ (VT11) | No direct evidence, extrapolated from related decisions |\n\n**Bias check**: Confidence is earned through evidence, not assigned by how insightful the decision sounds. A pithy design principle observed once is 30, not 75.\n\n#### Assign permanence class\n\nPermanence captures domain *stability*, independent of confidence. You can be highly confident about something that will change (85, situational) or uncertain about something deep (35, stable).\n\n| Class | Domain | Timescale |\n|-------|--------|-----------|\n| **stable** | Architecture principles, design patterns, meta-decision heuristics | Decade |\n| **durable** | Tooling choices, code standards, process conventions, DX preferences | Year |\n| **situational** | Current project priorities, active initiative choices, recent tech stack picks | Month |\n\nDefault permanence mapping by category:\n\n- Architecture & Design Patterns, Meta-decision Style → stable\n- Technology & Tooling, Code Quality & Standards, Process & Workflow, DX & Project Structure,\n  Communication Style, Trade-off Heuristics, Anti-patterns → durable\n- Scoping & Prioritization, UI/UX Preferences → situational (unless clearly long-standing)\n- Agent & Automation Philosophy → durable (unless project-specific)\n\nOverride the default when the evidence suggests otherwise.\n\n#### Set dates\n\n- **first**: Earliest timestamp from the source data that evidences this decision\n- **refresh date**: Set to today's date (the generation date)\n- **challenged**: Set to \u0060—\u0060 (none yet on a fresh profile)\n\n#### Identify tensions\n\nLook for cross-category patterns and contradictions: stated principle vs shipped code, conflicts between categories, \"Exceptions\" suggesting a weaker rule. Record contradictions in the Tensions section rather than smoothing them into a coherent narrative.\n\n---\n\n### Step 5: Generate the profile\n\nOutput constraint: ≤30 words per signal, ≤15 words per evidence line.\n\nWrite the decision profile to \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060.\n\nIf a previous version exists: copy to \u0060$AGENTERA_PROFILE_DIR/history/PROFILE-{timestamp}.md\u0060, generate new version, show change summary (added, updated, removed).\n\nWhen presenting the profile, frame it as a colleague reflecting on what they've observed, not a system delivering results. Open with what stood out, what surprised you, where the user is most consistent and where they contradict themselves. The structured profile follows, but the human read comes first.\n\n#### Profile format\n\n\u0060\u0060\u0060markdown\n# Decision Profile: [User Name]\n\n<!-- Generated: {date} | Data: {date range from earliest to latest timestamp} | Validated: — -->\n<!-- Sources: {N} memory files, {N} history prompts, {N} conversation exchanges, {N} configs -->\n<!-- Decay parameters: stable λ=0.001, durable λ=0.005, situational λ=0.015 -->\n<!-- Formula: effective_conf = conf × e^(-λ × days_since_confirmed), floor 20 -->\n<!-- Regenerate with /agentera profile -->\n\n## How to Use This Profile\n\nThis profile captures decision-making patterns extracted from {N} months of sessions across {N} projects. Each entry carries inline metadata:\n\n\u0060━ conf:75 | perm:durable | first:2026-01-15 | confirmed:2026-03-28 | challenged:—\u0060\n\n- **conf** (0-100): Evidence-based confidence. 90+ shipped consistently (CS1), 70-89\n  established (CS2), 50-69 emerging (CS3), 30-49 single signal (CS4), 0-29 speculative (CS5).\n  Line weight tokens: ━ (VT9) high (90-100), ─ (VT10) medium (50-89), ┄ (VT11) low (0-49).\n- **perm**: How stable the decision domain is. stable (decade), durable (year),\n  situational (month).\n- **dates**: When the decision was first observed, refreshed,\n  and last challenged.\n- **Generated / Validated**: Full rebuild date vs last validate-mode\n  maintenance date in the header comment. \u0060agentera prime\u0060 treats the\n  profile as fresh through the newer of the two.\n\nWhen consuming this profile, compute effective confidence using the decay formula.\nStale situational entries carry less weight than fresh stable ones.\n\n**When the profile is silent**: If a situation isn't covered, look for the closest trade-off\nheuristic or meta-decision pattern. When truly uncertain, ask.\n\n## Decision-Making Philosophy\n\n[2-3 paragraphs describing the meta-patterns: how this person approaches decisions, what\nframeworks they use, their risk posture, when they decide quickly vs deliberate, what\ninformation they seek before deciding]\n\n## [Category Name]\n\n### [Decision Name]\n\u0060━ conf:75 | perm:durable | first:2026-01-15 | confirmed:2026-03-28 | challenged:—\u0060\n\n- ▸ **Rule**: [Imperative statement an agent can follow directly]\n- ▸ **When**: [Specific conditions or triggers for this rule]\n- ▸ **Why**: [The reasoning, the value or concern that drives this]\n- ▸ **Exceptions**: [Known cases where this was overridden, or \"None observed\"]\n\n[Repeat for each decision in the category. Order by confidence (highest first).]\n\n[Repeat for all 12 categories. Skip categories with no signal.]\n\n## Tensions\n\nEach entry records a contradiction or divergence found during profile generation or challenged during validation. Default status is **unresolved**. Resist the urge to wrap tensions in resolution narratives. Some tensions are real and persistent.\n\n### YYYY-MM-DD: [Short description]\n\n**Decision affected**: [which decision was contradicted]\n**What happened**: [what was observed or said that didn't fit]\n**Status**: unresolved\n\u0060\u0060\u0060\n\n#### Writing guidelines\n\n- Write rules as imperatives (\"Use X\" not \"[Name] prefers X\")\n- Be specific (\"when building Go CLIs\" not \"when building things\")\n- Always include the *why* because agents need reasoning for edge cases\n- Don't duplicate CLAUDE.md. This covers decision *patterns*, not project instructions\n- Omit categories with <2 decisions (insufficient signal)\n- Every entry MUST have inline metadata after the ### heading\n\n---\n\n### Step 6: Validate predictions\n\nPick 5 decision-rich prompts NOT used to create profile entries. For each: predict what the profile would recommend, check against what happened. Report accuracy (e.g., \"4/5\"). Below 3/5: identify categories needing more signal, note in profile header.\n\n---\n\n## Validate Mode\n\nQuick incremental check (~2 minutes). Same colleague voice: you're checking in on what you noticed before, not running a diagnostic. \"Still true? Let me know.\"\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: select, present, apply, write.\n\n### Step V1: Run smart selection\n\nIdentify which entries are most worth checking by reading \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 directly and prioritizing high-confidence, stale, or tension-heavy entries. If PROFILE.md is missing, fall back to Full mode.\n\n### Step V2: Present entries for validation\n\nPresent entries one at a time: decision name, rule text, reason surfaced, stored vs effective confidence. Ask: **Confirm**, **Challenge**, or **Skip**.\n\n### Step V3: Apply updates\n\nFor each response:\n\n- **Confirm**: Bump \u0060conf\u0060 by 5 (cap at 95). Update \u0060confirmed\u0060 to today's date.\n- **Challenge**: Soften \u0060conf\u0060 by 10 (floor at 10). Update \u0060challenged\u0060 to today's date.\n  Append a tension entry to the \u0060## Tensions\u0060 section:\n\n  \u0060\u0060\u0060\n  ### {today}: {decision name} challenged during validation\n  **Decision affected**: {decision name}\n  **What happened**: Challenged by user during validation\n  **Status**: unresolved\n  \u0060\u0060\u0060\n\n- **Skip**: No changes to this entry.\n\n### Step V4: Write and report\n\nUpdate the first header comment before writing PROFILE.md:\n\n- Set \u0060Validated:\u0060 to today's date.\n- Preserve \u0060Generated:\u0060 unchanged (last full rebuild date).\n- If the profile predates \u0060Validated:\u0060, append \u0060| Validated: {today}\u0060 to that comment line.\n- If \u0060Validated:\u0060 already exists, replace its date.\n\nWrite updated PROFILE.md. Report: \"Reviewed {N} entries: {N} accepted, {N} challenged, {N} skipped.\" Mention challenged entries by name.\n\n---\n\n## Safety rails\n\n<critical>\n- NEVER fabricate decision patterns. Every profile entry must be grounded in observed evidence from session history, memory files, configs, or conversation data.\n- NEVER assign confidence higher than the evidence warrants. A single data point is 30-49 (CS4), not 70+, regardless of how insightful the decision sounds.\n- NEVER smooth over contradictions. When evidence conflicts, record tensions rather than forcing a coherent narrative.\n- NEVER modify the user's session history, memory files, or config files. Profile reads these sources; it never writes to them.\n- NEVER share profile contents with external services or include them in commits.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: emit \u0060♾ profile · <status>\u0060 on its own line, followed by a one-sentence summary. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a ▸ (VT15) bullet below the summary identifying what needs attention. The exit marker uses profile's canonical glyph ♾ (SG9, U+267E).\n\n- **complete** (EX1): PROFILE.md was written (Full mode) or updated (Validate mode). Metadata changes were applied, prediction accuracy was assessed, and changes were summarized.\n- **flagged** (EX2): Profile generation or validation completed but with data quality issues: available runtime history was skipped without explicit acceptance, extraction failed for one or more sources, prediction accuracy was below 3/5, or significant tensions were found that could not be resolved from available evidence.\n- **stuck** (EX3): Cannot generate or validate a profile because the extraction scripts failed entirely, Python is unavailable, or \u0060~/.claude/\u0060 is unreadable and no session data can be accessed.\n- **waiting** (EX4): The user chose Validate mode but PROFILE.md lacks valid metadata. A Full mode run needs user approval, or the requested mode is ambiguous.\n\n---\n\n## Cross-capability integration\n\nProfile is part of a twelve-capability suite. The decision profile it produces is consumed by the other capabilities.\n\n### Consumed by build\n\nBuild runs the effective profile script in its Orient step to get a confidence-weighted summary table. High effective confidence entries are treated as strong constraints; low effective confidence entries are treated as suggestions. Full rules are read from PROFILE.md when needed for detailed reasoning.\n\n### Consumed by optimize\n\nOptimize runs the effective profile script to calibrate experimentation style: how aggressive to be, how much complexity is acceptable, what trade-offs the user prefers. Effective confidence weighting ensures stale preferences don't over-constrain experiments.\n\n### Consumed by research\n\nResearch can run the effective profile script to inform applicability judgments: what patterns the user favors, what they resist, how to weigh recommendations. High-confidence entries strongly constrain recommendations; low-confidence entries are treated as tendencies.\n\n### Consumed by discuss\n\nDiscuss reads the decision profile at the start of every deliberation. High-confidence entries in the relevant domain are acknowledged upfront to prevent re-deliberating settled preferences. Low-confidence entries are surfaced as hypotheses worth testing during the conversation.\n\n### Fed by discuss\n\nDECISIONS.md (maintained by discuss) is a high-signal source for profile's extraction scripts. Each decision entry captures reasoning, tradeoffs, and confidence, making deliberation sessions one of the richest inputs for decision profile generation. For normal read-only extraction, prefer \u0060agentera decisions --format json\u0060 and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure rather than raw-reading missing historical context.\n\n### Consumed by audit\n\nAudit reads the decision profile to calibrate what \"healthy\" means for this user. Quality preferences, complexity tolerance, and pattern priorities from the profile weight the grading and determine which findings matter most.\n\n### Consumed by plan\n\nPlan reads the decision profile during its Orient step to calibrate planning depth, pattern preferences, and constraint priorities.\n\n### Profile consumption\n\nAll consuming capabilities read \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 directly when it exists. Confidence thresholds and dormancy notes are kept in the profile itself so the guidance remains editable and portable.\n\n---\n\n## Getting started\n\n### First profile generation\n\n\u0060\u0060\u0060\n/agentera profile\n\u0060\u0060\u0060\n\nFull extraction across all sources. Produces \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060.\n\n### Regular validation\n\n\u0060\u0060\u0060\n/agentera profile validate\n\u0060\u0060\u0060\n\nQuick confidence refresh without full regeneration. Run weekly or per-session.\n\n### Using the profile in other capabilities\n\nAll capabilities may read the profile directly when \u0060PROFILE.md\u0060 exists. No manual steps needed; just ensure PROFILE.md exists.\n\n---\n\n## Notes on depth vs speed\n\n- Extraction scripts handle I/O; Claude's job is synthesis, not parsing.\n- Large intermediate files: use subagents to read in parallel.\n- Signal hierarchy: crystallized.json (highest: memory + CLAUDE.md), conversation exchanges (most nuanced: real-time reasoning), config patterns (most objective: what shipped).\n- Validate mode: weekly/per-session. Full mode: monthly or when significantly stale.\n"`);
+// Capability instructions for profile
+// Served via `agentera prime --context profile --format json`. RFC 2119 modal vocab.
+export const instructions = JSON.parse(String.raw `"# PROFILE\n\n**Persona Reconstruction: Observable Footprint Indexing Logic. Extract, Reconcile, Formalize**\n\nGlyph: ♾ (protocol ref: SG9).\n\nMine the user's session history and produce a structured decision profile for predicting \"What would this person decide?\" Each entry carries numeric confidence, permanence classification, and temporal metadata enabling dormancy decay. The profile is consumed by all capabilities via \u0060status.profile\u0060.\n\n---\n\n## State artifacts\n\nProfile reads the user's corpus and decisions; writes PROFILE.md. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060profile\u0060 | produces_and_consumes | \u0060profile_context.profile.path\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060profile_context.decisions.fallback_command\u0060 |\n\n**Startup contract**: trust \u0060profile_context\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context profile --format json\u0060. Use the included state families first; run listed \u0060fallback_commands\u0060 before any raw artifact read. Do not manually locate schemas or defensively raw-read state the CLI already serves. Visual-token families (VT/SI/EX/SG/PH) by \u0060skills/agentera/protocol.yaml\u0060.\n\n### Profile format\n\nOutput constraint: ≤30 words per signal, ≤15 words per evidence line.\n\n\u0060\u0060\u0060markdown\n# Decision Profile: [User Name]\n\n<!-- Generated: {date} | Data: {date range from earliest to latest timestamp} | Validated: — -->\n<!-- Sources: {N} memory files, {N} history prompts, {N} conversation exchanges, {N} configs -->\n<!-- Decay parameters: stable λ=0.001, durable λ=0.005, situational λ=0.015 -->\n<!-- Formula: effective_conf = conf × e^(-λ × days_since_confirmed), floor 20 -->\n<!-- Regenerate with /agentera profile -->\n\n## How to Use This Profile\n\nThis profile captures decision-making patterns extracted from {N} months of sessions across {N} projects. Each entry carries inline metadata:\n\n\u0060━ conf:75 | perm:durable | first:2026-01-15 | confirmed:2026-03-28 | challenged:—\u0060\n\n- **conf** (0-100): Evidence-based confidence. 90+ shipped consistently (CS1), 70-89\n  established (CS2), 50-69 emerging (CS3), 30-49 single signal (CS4), 0-29 speculative (CS5).\n  Line weight tokens: ━ (VT9) high (90-100), ─ (VT10) medium (50-89), ┄ (VT11) low (0-49).\n- **perm**: How stable the decision domain is. stable (decade), durable (year),\n  situational (month).\n- **dates**: When the decision was first observed, refreshed,\n  and last challenged.\n- **Generated / Validated**: Full rebuild date vs last validate-mode\n  maintenance date in the header comment. \u0060agentera prime\u0060 treats the\n  profile as fresh through the newer of the two.\n\nWhen consuming this profile, compute effective confidence using the decay formula.\nStale situational entries carry less weight than fresh stable ones.\n\n**When the profile is silent**: If a situation isn't covered, look for the closest trade-off\nheuristic or meta-decision pattern. When truly uncertain, ask.\n\n## Decision-Making Philosophy\n\n[2-3 paragraphs describing the meta-patterns: how this person approaches decisions, what\nframeworks they use, their risk posture, when they decide quickly vs deliberate, what\ninformation they seek before deciding]\n\n## [Category Name]\n\n### [Decision Name]\n\u0060━ conf:75 | perm:durable | first:2026-01-15 | confirmed:2026-03-28 | challenged:—\u0060\n\n- ▸ **Rule**: [Imperative statement an agent can follow directly]\n- ▸ **When**: [Specific conditions or triggers for this rule]\n- ▸ **Why**: [The reasoning, the value or concern that drives this]\n- ▸ **Exceptions**: [Known cases where this was overridden, or \"None observed\"]\n\n[Repeat for each decision in the category. Order by confidence (highest first).]\n\n[Repeat for all 12 categories. Skip categories with no signal.]\n\n## Tensions\n\nEach entry records a contradiction or divergence found during profile generation or challenged during validation. Default status is **unresolved**. Resist the urge to wrap tensions in resolution narratives. Some tensions are real and persistent.\n\n### YYYY-MM-DD: [Short description]\n\n**Decision affected**: [which decision was contradicted]\n**What happened**: [what was observed or said that didn't fit]\n**Status**: unresolved\n\u0060\u0060\u0060\n\n**Writing guidelines**:\n\n- Write rules as imperatives (\"Use X\" not \"[Name] prefers X\")\n- Be specific (\"when building Go CLIs\" not \"when building things\")\n- Always include the *why* because agents need reasoning for edge cases\n- Don't duplicate AGENTS.md. This covers decision *patterns*, not project instructions\n- Omit categories with <2 decisions (insufficient signal)\n- Every entry MUST have inline metadata after the ### heading\n\n---\n\n## Workflow phases\n\nMode-split shape. Two modes: **Full** (regenerate from scratch) and **Validate** (quick incremental check).\n\nCheck if \u0060profile_context.profile.path\u0060 resolves to an existing file. If it does NOT exist, proceed directly to Full mode. If it DOES exist, present the mode choice:\n\n> **Full**: Regenerate from scratch using all session data. Replaces the existing profile including any accumulated tensions. Best when the profile feels significantly outdated or you want a clean baseline.\n>\n> **Validate**: Quick check of your existing profile (~2 minutes). Reviews the entries most worth validating: confirm, challenge, or skip each one. Best for regular maintenance between full regenerations.\n\n### Full Mode\n\nStep markers: display \u0060── step N/4: verb\u0060 before each step.\nSteps: extract, read, synthesize, generate.\n\n#### Step 1: Coverage and extraction\n\nRun the Coverage Audit — the first user-visible output of every Full-mode run:\n\n\u0060\u0060\u0060bash\nagentera report refresh --consent local-history --coverage-audit-only\n\u0060\u0060\u0060\n\nThe audit enumerates all supported runtimes (codex, claude-code, cursor, cursor-agent, opencode, github-copilot) with store paths and earliest/latest session timestamps. It names skipped runtimes and reasons. Do not display raw transcript content.\n\nTreat a runtime as **available** when the audit marks it \u0060available\u0060 with session timestamps. Treat \u0060missing\u0060, \u0060skipped\u0060, \u0060sparse\u0060, and \u0060degraded\u0060 runtimes as unavailable for selection; report them briefly with bounded status/reason labels and remediation labels when present.\n\n**EX2 gating**: If any available runtime would be skipped by flags or the user's selection, stop and emit \u0060♾ profile · flagged\u0060 (EX2). Do not extract until the user explicitly accepts the coverage gap. When the user accepts, rerun extraction with \u0060--accept-coverage-gap\u0060 plus the agreed runtime opt-out flags. If all available runtimes are selected, proceed without EX2 for coverage.\n\nSupported runtime sources:\n\n- **Claude Code**: default \u0060~/.claude/projects\u0060, override with \u0060--claude-projects-dir <path>\u0060, disable with \u0060--no-claude\u0060\n- **Codex**: default \u0060~/.codex/sessions\u0060, override with \u0060--codex-sessions-dir <path>\u0060, disable with \u0060--no-codex\u0060\n- **OpenCode**: default opencode db path when available, override with \u0060--opencode-conversations-dir <path>\u0060, disable with \u0060--no-opencode\u0060\n- **GitHub Copilot**: default \u0060$COPILOT_HOME\u0060 or \u0060~/.copilot\u0060, override with \u0060--copilot-conversations-dir <path>\u0060, disable with \u0060--no-copilot\u0060\n- **Cursor IDE**: default \u0060$CURSOR_HOME/projects\u0060 or \u0060~/.cursor/projects\u0060, override with \u0060--cursor-projects-dir <path>\u0060, disable with \u0060--no-cursor\u0060\n- **Cursor Agent CLI**: default \u0060~/.config/cursor/chats\u0060, override with \u0060--cursor-chats-dir <path>\u0060 or \u0060$CURSOR_CONFIG_HOME/chats\u0060; disabled with \u0060--no-cursor\u0060\n\nAsk which runtime histories to include with a multi-select question. Put \u0060All (Recommended)\u0060 first; it means every selectable runtime from the preview and wins over any individual runtime selections. Also offer one option per selectable runtime and a docs/config-only option for cases where the user wants no runtime conversation history. The question controls runtime conversation sources only; instruction documents and project config signals remain included.\n\nIf no runtime has extractable records, skip the selection question, say no local runtime history is currently extractable, and continue with instruction documents and project config signals.\n\nRun extraction with the selected runtime flags:\n\n\u0060\u0060\u0060bash\nagentera report refresh --consent local-history\n\u0060\u0060\u0060\n\nApply runtime opt-out flags from the selection. For example, if the user selects Claude Code and OpenCode only, run with \u0060--no-codex --no-copilot --no-cursor\u0060. If the user selects docs/config-only, run with all \u0060--no-<runtime>\u0060 flags. If the user selects \u0060All (Recommended)\u0060, use no runtime opt-out flags. When the user explicitly accepted skipping available runtimes, add \u0060--accept-coverage-gap\u0060.\n\nThe extractor writes the corpus envelope and emits four portable Section 22 families: \u0060instruction_document\u0060, \u0060history_prompt\u0060, \u0060conversation_turn\u0060, and \u0060project_config_signal\u0060. Use \u0060--output <path>\u0060, repeated \u0060--project-root <path>\u0060, or runtime-specific \u0060--<source>-dir <path>\u0060 flags when the host stores data outside defaults.\n\nRead the corpus file's top-level \u0060metadata\u0060 object to confirm counts per source family. Report totals to the user.\n\n**If extraction fails**: common causes include agentera not found, permission errors, and empty output (no session history). If only some runtimes fail, the corpus will contain partial data with bounded runtime notes in \u0060metadata.runtime_statuses\u0060; proceed and note missing sources.\n\n#### Step 2: Read corpus data\n\nRead the corpus produced in Step 1. Each record carries a \u0060source_kind\u0060 field. Group records by source family for synthesis:\n\n1. **instruction_document**: Memory files, AGENTS.md (highest signal: explicit user instructions)\n2. **history_prompt**: Decision-rich prompts from session history\n3. **conversation_turn**: Decision exchanges from conversations (most nuanced: real-time reasoning)\n4. **project_config_signal**: Recurring config patterns across projects (most objective: what shipped)\n\nRead the full corpus before synthesis. If total records exceed 500, prioritize high-signal records:\n\n- history correction or decision kinds\n- longer user responses\n- configs shared across projects\n\n#### Step 3: Categorize and synthesize\n\nGroup signals into 12 categories:\n\n1. **Architecture & Design Patterns**: package layout, abstraction boundaries, API design\n2. **Technology & Tooling Selection**: languages, frameworks, libraries, build tools\n3. **Agent & Automation Philosophy**: agent behavior, autonomy, interaction patterns\n4. **Code Quality & Standards**: error handling, testing, validation, naming\n5. **DX & Project Structure**: directory layout, build targets, configuration\n6. **Scoping & Prioritization**: what to build, milestones, complexity budgets\n7. **Communication Style**: writing preferences, documentation voice\n8. **Process & Workflow**: git workflow, commit conventions, release process\n9. **UI/UX Preferences**: visual patterns, interaction design, CLI vs TUI vs web\n10. **Trade-off Heuristics**: simplicity vs flexibility, speed vs correctness\n11. **Anti-patterns & Rejections**: things actively avoided, with reasoning\n12. **Meta-decision Style**: frameworks used, information gathering, decide vs defer\n\nPer category: identify distinct decisions (not just preferences; decisions have conditions and reasoning), look for the *why*, note exceptions where the rule was overridden.\n\n**Assign confidence** (numeric, 0-100, protocol ref: CS1-CS5)\n\nDecision patterns are empirically verifiable via git history and configs:\n\n| Range | Label | Token | Criteria |\n|-------|-------|-------|----------|\n| 90-100 (CS1) | Shipped consistently | ━ (VT9) | Appears in configs/code across 3+ projects, verifiable from artifacts |\n| 70-89 (CS2) | Established | ━ (VT9) | Consistent across sessions, corroborated by behavior |\n| 50-69 (CS3) | Emerging | ─ (VT10) | Observed multiple times but limited context or minor variations |\n| 30-49 (CS4) | Single signal | ┄ (VT11) | One data point or inferred from adjacent patterns |\n| 0-29 (CS5) | Speculative | ┄ (VT11) | No direct evidence, extrapolated from related decisions |\n\n**Bias check**: Confidence is earned through evidence, not assigned by how insightful the decision sounds. A pithy design principle observed once is 30, not 75.\n\n**Assign permanence class**\n\nPermanence captures domain *stability*, independent of confidence. You can be highly confident about something that will change (85, situational) or uncertain about something deep (35, stable).\n\n| Class | Domain | Timescale |\n|-------|--------|-----------|\n| **stable** | Architecture principles, design patterns, meta-decision heuristics | Decade |\n| **durable** | Tooling choices, code standards, process conventions, DX preferences | Year |\n| **situational** | Current project priorities, active initiative choices, recent tech stack picks | Month |\n\nDefault permanence mapping by category:\n\n- Architecture & Design Patterns, Meta-decision Style → stable\n- Technology & Tooling, Code Quality & Standards, Process & Workflow, DX & Project Structure, Communication Style, Trade-off Heuristics, Anti-patterns → durable\n- Scoping & Prioritization, UI/UX Preferences → situational (unless clearly long-standing)\n- Agent & Automation Philosophy → durable (unless project-specific)\n\nOverride the default when the evidence suggests otherwise.\n\n**Set dates**\n\n- **first**: Earliest timestamp from the source data that evidences this decision\n- **refresh date**: Set to today's date (the generation date)\n- **challenged**: Set to \u0060—\u0060 (none yet on a fresh profile)\n\n**Identify tensions**\n\nLook for cross-category patterns and contradictions: stated principle vs shipped code, conflicts between categories, \"Exceptions\" suggesting a weaker rule. Record contradictions in the Tensions section rather than smoothing them into a coherent narrative.\n\n#### Step 4: Generate the profile and validate\n\nWrite the decision profile to \u0060profile_context.profile.path\u0060 following the Profile format template above.\n\nIf a previous version exists: copy to the \u0060history/\u0060 subdirectory alongside PROFILE.md, generate new version, show change summary (added, updated, removed).\n\n**Prediction validation**\n\nPick 5 decision-rich prompts NOT used to create profile entries. For each: predict what the profile would recommend, check against what happened. Report accuracy (e.g., \"4/5\").\n\nBelow 3/5: identify categories needing more signal, note in profile header, and emit \u0060♾ profile · flagged\u0060 (EX2) — the profile is written but signal quality is insufficient.\n\n---\n\n### Validate Mode\n\nQuick incremental check. Step markers: display \u0060── step N/3: verb\u0060 before each step.\nSteps: select, present, apply.\n\n#### Step V1: Select entries\n\nIdentify which entries are most worth checking by reading PROFILE.md directly and prioritizing high-confidence, stale, or tension-heavy entries. If PROFILE.md is missing, fall back to Full mode.\n\n#### Step V2: Present entries for validation\n\nPresent entries one at a time: decision name, rule text, reason surfaced, stored vs effective confidence. Ask: **Confirm**, **Challenge**, or **Skip**.\n\n#### Step V3: Apply updates and write\n\nFor each response:\n\n- **Confirm**: Bump \u0060conf\u0060 by 5 (cap at 95). Update \u0060confirmed\u0060 to today's date.\n- **Challenge**: Soften \u0060conf\u0060 by 10 (floor at 10). Update \u0060challenged\u0060 to today's date.\n  Append a tension entry to the \u0060## Tensions\u0060 section:\n\n  \u0060\u0060\u0060\n  ### {today}: {decision name} challenged during validation\n  **Decision affected**: {decision name}\n  **What happened**: Challenged by user during validation\n  **Status**: unresolved\n  \u0060\u0060\u0060\n\n- **Skip**: No changes to this entry.\n\nUpdate the header comment before writing:\n\n- Set \u0060Validated:\u0060 to today's date.\n- Preserve \u0060Generated:\u0060 unchanged (last full rebuild date).\n- If \u0060Validated:\u0060 already exists, replace its date; otherwise append \u0060| Validated: {today}\u0060.\n\nWrite updated PROFILE.md. Report: \"Reviewed {N} entries: {N} accepted, {N} challenged, {N} skipped.\" Mention challenged entries by name.\n\n---\n\n## Safety rails\n\n<critical>\n- MUST NOT fabricate decision patterns. Every profile entry MUST be grounded in observed evidence from session history, memory files, configs, or conversation data.\n- MUST NOT assign confidence higher than the evidence warrants. A single data point is 30-49 (CS4), not 70+, regardless of how insightful the decision sounds.\n- MUST NOT smooth over contradictions. When evidence conflicts, record tensions rather than forcing a coherent narrative.\n- MUST NOT modify the user's session history, memory files, or config files. Profile reads these sources; it never writes to them.\n- MUST NOT share profile contents with external services or include them in commits.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: emit \u0060♾ profile · <status>\u0060 on its own line, followed by a one-sentence summary. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a ▸ (VT15) bullet below the summary identifying what needs attention. The exit marker uses profile's canonical glyph ♾ (SG9, U+267E).\n\n- **complete** (EX1): PROFILE.md was written (Full mode) or updated (Validate mode). Metadata changes were applied, prediction accuracy was assessed (Full mode), and changes were summarized.\n- **flagged** (EX2): Profile generation or validation completed but with data quality issues: available runtime history was skipped without explicit acceptance, extraction failed for one or more sources, prediction accuracy was below 3/5, or significant tensions were found that could not be resolved from available evidence.\n- **stuck** (EX3): Cannot generate or validate a profile because extraction scripts failed entirely or session data sources are unreadable.\n- **waiting** (EX4): The user chose Validate mode but PROFILE.md lacks valid metadata. A Full mode run needs user approval, or the requested mode is ambiguous.\n\n---\n\n## Cross-capability integration\n\n### Consumption contract\n\nAll capabilities consume the profile via \u0060status.profile\u0060 from their prime context. Confidence thresholds: 65+ for strong constraint, below 45 for suggestion. Effective confidence decays over time using the formula and parameters declared in the Profile format template (§2). High effective confidence entries are treated as strong constraints; low as suggestions. Full rules are read from PROFILE.md when needed for detailed reasoning.\n\n### Consumed by\n\n- **build** — confidence-weighted summary table in Orient step; high confidence as strong constraints\n- **optimize** — calibrates experimentation style and trade-off preferences\n- **research** — informs applicability judgments; high confidence constrains recommendations\n- **discuss** — reads profile at start of every deliberation; high-confidence entries acknowledged upfront\n- **audit** — calibrates quality bar and which findings matter for this user\n- **plan** — calibrates planning depth and constraint priorities in Orient step\n\n### Fed by\n\n- **discuss** — \u0060decisions\u0060 artifact is a high-signal extraction source. Prefer \u0060agentera state decisions --format json\u0060 and preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure rather than raw-reading missing historical context.\n\n### Getting started\n\nFirst profile generation:\n\n\u0060\u0060\u0060\n/agentera profile\n\u0060\u0060\u0060\n\nFull extraction across all sources. Produces PROFILE.md at \u0060profile_context.profile.path\u0060.\n\nRegular validation:\n\n\u0060\u0060\u0060\n/agentera profile validate\n\u0060\u0060\u0060\n\nQuick confidence refresh without full regeneration. Run weekly or per-session.\n\nUsing the profile in other capabilities: automatic — all capabilities read \u0060status.profile\u0060 from their prime context. No manual steps needed; just ensure PROFILE.md exists."`);
 export default instructions;
 //# sourceMappingURL=instructions.js.map