agentera 3.0.0-dev.2 → 3.0.0-dev.21

package/dist/capabilities/build/instructions.js

@@ -0,0 +1,5 @@
+// Capability instructions for build
+// Served via `agentera prime --context build --format json`. RFC 2119 modal vocab.
+export const instructions = JSON.parse(String.raw `"# BUILD\n\n**Relentless Execution: Autonomous Loops Iterating Software. Evolve, Refine, Adapt**\n\nGlyph: \u29c9 (protocol ref: SG2).\n\nAn autonomous development loop that evolves any software project one cycle at a time. Decisions grounded in the user's decision profile. Continuity lives in files, not memory.\n\nEach invocation = one cycle. After completing a cycle (orient through log, exit signal reported), **stop**. The next cycle starts only when the user explicitly requests it or switches to \u2388 orchestrate for autonomous multi-task execution. A compaction-continue prompt is not consent to start a new cycle.\n\nWhen offering execution mode choices after plan completion, label \u0060build\u0060 as \"one task, then stop\" and \u2388 orchestrate as \"all tasks autonomously.\"\n\n---\n\n## State artifacts\n\nBuild reads project state and writes progress, TODO, and changelog. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060progress\u0060 | produces | \u0060.agentera/progress.yaml\u0060 |\n| \u0060todo\u0060 | produces_and_consumes | \u0060TODO.md\u0060 |\n| \u0060changelog\u0060 | produces_and_consumes | \u0060CHANGELOG.md\u0060 |\n| \u0060vision\u0060 | consumes | \u0060.agentera/vision.yaml\u0060 |\n| \u0060plan\u0060 | produces_and_consumes | \u0060.agentera/plan.yaml\u0060 |\n| \u0060health\u0060 | consumes | \u0060.agentera/health.yaml\u0060 |\n| \u0060decisions\u0060 | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| \u0060docs\u0060 | consumes | \u0060.agentera/docs.yaml\u0060 |\n| \u0060design\u0060 | consumes | \u0060DESIGN.md\u0060 |\n| \u0060profile\u0060 | consumes | \u0060status.profile\u0060 |\n\n### progress.yaml\n\n\u0060\u0060\u0060yaml\ncycles:\n  - number: N\n    timestamp: YYYY-MM-DD HH:MM\n    type: feat\n    phase: build\n    what: One-line summary of what shipped.\n    inspiration: External source, if any.\n    discovered: Issues or ideas found.\n    verified: Observed output, N/A tag, or rationale.\n    next: Most valuable next work.\n    context:\n      intent: Why this cycle happened.\n      constraints: What had to stay true.\n      unknowns: What remains uncertain.\n      scope: What changed.\narchive: []\n\u0060\u0060\u0060\n\nThe \u0060verified\u0060 field is mandatory for every cycle entry.\n\n### CHANGELOG.md\n\nPublic-facing change history. Keep-a-changelog format. Build appends entries under \u0060## [Unreleased]\u0060 based on commit type: \u0060feat\u0060 \u2192 Added, \u0060refactor/chore\u0060 \u2192 Changed, \u0060fix\u0060 \u2192 Fixed. On version bumps, promote the Unreleased section to a versioned heading.\n\n---\n\n## Workflow phases: The cycle\n\n### Vision bootstrap\n\nIf the vision artifact is absent and \u26e5 vision is not installed, ask the user for project direction inline (one question: \"What does this software make possible?\"). Write the answer to \u0060.agentera/vision.yaml\u0060 and proceed to the cycle. If \u26e5 vision is installed and the artifact is absent, suggest \u26e5 vision and wait for confirmation. In all other cases, skip straight to the cycle.\n\n### The cycle\n\nStep markers: display \u0060\u2500\u2500 step N/8: verb\u0060 before each step.\nSteps: orient, select, research, plan, dispatch, verify, commit, log.\n\n### Step 1: Orient\n\nStart from the Build execution-context seam:\n\n\u0060\u0060\u0060bash\nagentera prime --context build --format json\n\u0060\u0060\u0060\n\nIf \u0060execution_context.source_contract.complete_for_execution_context\u0060 is true, use \u0060execution_context\u0060 and included \u0060capability_context.state\u0060 as normal startup context. Do not read raw plan, progress, TODO, docs, health, decisions, changelog, vision, profile, or design artifacts to re-check selected work, acceptance criteria, constraints, verification expectations, or scope caveats.\n\nIf \u0060execution_context\u0060 is incomplete or caveated, preserve every caveat in the cycle report and run the listed \u0060execution_context.fallback_commands\u0060 before any last-resort raw artifact diagnostic.\n\n#### Decision satisfaction authority\n\nWhen a cycle touches decision satisfaction, agents MAY mark provisional satisfaction with evidence only. Build MUST NOT mark or imply user-confirmed satisfaction; only the user confirms final satisfaction. Missing, compacted, open, provisional, or review-needed satisfaction state remains a caveat and review pressure in the cycle report \u2014 automation MUST NOT reconstruct hidden outcomes or claim it proved user intent.\n\n#### Context consumption\n\nConsume these \u0060execution_context\u0060 fields:\n\n- \u0060work_selection\u0060: selected task or no-plan/completed-plan mode\n- \u0060acceptance_criteria\u0060: exact criteria for this cycle\n- \u0060constraints\u0060: plan constraints and protected-action boundaries\n- \u0060verification_expectations\u0060: expected validation and latest progress evidence\n- \u0060artifact_update_requirements\u0060: plan, TODO, changelog, and progress update obligations\n- \u0060changelog_boundary\u0060: current public-history boundary or fallback\n- \u0060scope_boundary\u0060: artifact-family scope and conservative source-file scope\n\nUse \u0060status.profile\u0060 for profile summary; stale or missing profile is a caveat, not approval to refresh profile state.\n\n#### Project discovery\n\nOn cycle 1 or when unfamiliar with the project:\n\n- Map the directory structure\n- Read dependency manifests and README.md, AGENTS.md\n- Identify build/test/lint commands\n- Read key source files to understand architecture\n\nRun \u0060git log --oneline -20\u0060 for recent changes.\n\nBefore proceeding, list the 3-5 facts that determine this cycle.\n\n**Exit-early stop condition (plan-driven mode only)**: If \u0060.agentera/plan.yaml\u0060 has \u0060header.status: complete\u0060 and every task is complete, perform a **plan-completion sweep** before archiving. A plan with blocked, skipped, or otherwise incomplete tasks is not complete and MUST remain visible for replanning.\n\nSweep checklist:\n\n1. **progress.yaml aggregate cycle entry**: run \u0060agentera state progress append ... --format json\u0060 with a summary of the whole plan.\n2. **CHANGELOG.md plan-level entries**: verify \u0060## [Unreleased]\u0060 covers each completed task's user-facing impact.\n3. **TODO.md milestone advance**: mark each plan task as \u0060## \u2713 Resolved\u0060.\n4. **health.yaml cross-reference**: mention any resolved findings.\n\nAfter the sweep, run \u0060agentera state plan archive --format json\u0060 and report exit signal \u0060complete: plan finished\u0060. The writer preserves immutable archive history and removes the active plan.\n\n### Step 2: Pick work\n\nChoose **one** focused increment. No backlog; decide by reasoning about the gap between vision and codebase, weighted against known issues.\n\nEach cycle: **build toward the vision, or fix something broken?** Consult the decision profile. A critical bug trumps a new feature; a minor nit does not block progress.\n\n**Building toward vision**: Read codebase and vision artifact, identify the gap, pick the smallest increment closing the most valuable part.\n\n**Fixing issues**: Pick from TODO.md by severity (critical > degraded > annoying).\n\n**Optimization-shaped work**: suggest \u2398 optimize for measurable metrics and wait for confirmation instead of silently delegating.\n\nWrite a 1-2 sentence rationale. Scope down aggressively.\n\nCompose a Context block for this cycle: intent, constraints, unknowns, and scope. Keep it \u226480 words.\n\n**Plan unknowns consumption**: If the selected task comes from \u2261 plan and the plan carries \u0060unknowns:\u0060, note in the cycle context which unknowns affect this task and what the execution resolved. Carry unresolved unknowns forward in the progress entry's \u0060context.unknowns\u0060 field.\n\n**Decision gate**: After selecting work, use \u0060agentera state decisions list --limit 20 --format json\u0060 and check whether any \u0060exploratory\u0060 (DL3) entries relate to the selected work area. Preserve returned \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure in the cycle context. If an exploratory decision is found: flag the uncertain foundation, suggest \u2748 discuss to firm up the decision, and wait for confirmation. In autonomous mode, proceed with the work but log the risk.\n\n### Step 3: Seek inspiration\n\nSearch for relevant external approaches before planning.\n\n1. **Assess**: bug fixes rarely benefit from inspiration. New features, architecture decisions, and unfamiliar domains do.\n2. **Search**: 2-3 targeted web queries for libraries, articles, repos, or patterns.\n3. **Analyze**: read promising finds deeply.\n4. **Integrate**: fold applicable patterns into the plan.\n\n### Step 4: Plan\n\nWrite a concrete plan: what changes in which files, expected behavior, verification approach.\n\nRead files you plan to modify before committing to the plan.\n\nKeep small enough for one agent session. Too large? Split and save the rest.\n\n### Step 5: Dispatch\n\nSpawn an implementation sub-agent in a git worktree for isolation. Commit pending artifact changes before branching so the subagent starts from current state (\u0060git status --porcelain\u0060; if empty, skip). Use the runtime-native subagent surface (Task tool, \u0060@agent\u0060 descriptor, etc.) \u2014 never spawn by running \u0060agentera build\u0060 or other capability-name CLI commands.\n\nBefore spawning, run \u0060git rev-list --count origin/main..HEAD\u0060. If count > 0, do not merge the worktree branch \u2014 fetch the diff and apply it to the main checkout.\n\nSubagent prompt:\n\n\u0060\u0060\u0060\nYou are implementing a focused change for [project].\n\n## Task\n[The plan]\n\n## Constraints\n- Implement ONLY what the plan describes. No scope creep.\n- Follow existing code patterns and conventions.\n- Read the files you are modifying before changing them.\n- Verify the change works as described, then run the project's test/build suite.\n- If you encounter a bug unrelated to your task, note it but do not fix it.\n\u0060\u0060\u0060\n\n### Step 6: Verify\n\nVerification has two phases: structural and behavioral. Both MUST pass before commit.\n\n**Phase A, structural verification**:\n\n1. Check the diff: does it match the plan?\n2. Functional check: does the changed behavior work end-to-end?\n3. Run the project's verification suite (test/build/lint).\n\n**Phase B, behavioral verification gate**: observe the new behavior by running the project's primary entrypoint against real project state:\n\n- CLI tool: invoke with realistic arguments\n- Library/SDK: run a smoke driver\n- Web service: send a request to a production-shaped endpoint\n- Skill repo: \u0060agentera check verify eval skills --skill <name>\u0060\n\nIf verification fails: diagnose, spawn a fix agent, re-verify.\n\n**N/A path**: If the cycle has no runnable behavior change, use \u0060N/A: <tag>\u0060 from the allowlist: \u0060docs-only\u0060, \u0060refactor-no-behavior-change\u0060, \u0060chore-dep-bump\u0060, \u0060chore-build-config\u0060, \u0060test-only\u0060.\n\n### Step 7: Commit\n\nCommit with a conventional commit message: \u0060type(scope): summary\u0060.\n\nTypes: \u0060feat\u0060, \u0060fix\u0060, \u0060docs\u0060, \u0060refactor\u0060, \u0060chore\u0060, \u0060test\u0060. Include all related files. MUST NOT commit partial or broken work.\n\nIf the current task is a version bump: read \u0060.agentera/docs.yaml\u0060 for the \u0060versioning\u0060 section. Update every file in \u0060version_files\u0060.\n\n### Step 8: Log\n\n**Before writing**, run \u0060agentera check lint --artifact <artifact> --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\n**Dual-write**: build maintains \u0060.agentera/progress.yaml\u0060 and root \u0060CHANGELOG.md\u0060.\n\n- **TODO.md**: add newly discovered open issues in severity bands with \u0060- [ ]\u0060. Move completed work to \u0060## \u2713 Resolved\u0060 as \u0060- [x]\u0060 with a resolution summary.\n- **progress.yaml**: run \u0060agentera state progress append --type TYPE --phase build --what TEXT --intent TEXT --verified TEXT --format json\u0060. The writer assigns the number, inserts newest-first, validates, compacts, and returns post-write state.\n- **CHANGELOG.md**: append a one-line entry under \u0060## [Unreleased]\u0060.\n\nProgress compaction is writer-owned. When a plan task closes, run \u0060agentera state plan set-status --task N --status complete --format json\u0060 rather than editing the plan directly. TODO.md Resolved compaction follows the same 10/40/50 cap via the validate-artifact hook or \u0060agentera check compact --mode fix\u0060.\n\nThen stop. One cycle complete.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT push to any remote. Local commits only.\n- MUST NOT bypass the project's test/lint/build suite.\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 add placeholder data or functionality.\n- MUST NOT modify files outside the project directory.\n- MUST NOT modify the vision artifact during a cycle \u2014 only during vision bootstrap.\n- One cycle per invocation. MUST NOT attempt multiple cycles.\n\n</critical>\n\n---\n\n## Handling blocked work\n\nIf blocked:\n\n1. Log blocker in TODO.md with context and decision needed\n2. Log skipped attempt in progress.yaml\n3. Pick different work and complete a full cycle 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\u2500\u2500\u2500 \u29c9 build \u00b7 <status> \u2500\u2500\u2500\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060\u25b8\u0060 bullet details below the summary.\n\n- **complete** (EX1): One full cycle completed. Work selected, implemented, verified, committed, artifacts updated.\n- **flagged** (EX2): Cycle completed but with notable issues: verification warnings, scope reduction, or discoveries suggesting next cycle may face blockers.\n- **stuck** (EX3): Cannot complete: the vision artifact is missing and bootstrap can't proceed, all work blocked, or verification suite broken.\n- **waiting** (EX4): No vision artifact and no codebase to infer direction, or user instruction too ambiguous.\n\nBefore reporting any status, inspect the last 3 entries in progress.yaml. If all 3 record failed cycles, stop, log the failure pattern to TODO.md, and surface to the user. Do not attempt a 4th consecutive cycle on the same failing problem.\n\nAfter reporting an exit signal, the cycle is over \u2014 the next cycle requires an explicit user request or \u2388 orchestrate.\n\n---\n\n## Cross-capability integration\n\nBuild is part of a twelve-capability suite.\n\n### Delegates to \u26e5 vision\n\nWhen \u26e5 vision is installed and the vision artifact doesn't exist, suggest \u26e5 vision for deep vision creation. If vision is NOT installed, the vision bootstrap (above) is the standalone fallback.\n\n### Delegates to \u2398 optimize\n\nWhen picked work is optimization-shaped (improving a measurable metric), delegate to optimize.\n\n### Uses \u2b1a research\n\nIn Step 3 (Seek inspiration), search for external approaches. For deeper analysis, use \u0060/agentera research <url>\u0060.\n\n### Reads \u267e profile output\n\nEvery cycle runs the effective profile. Confidence thresholds (CS1-CS5) determine which entries are strong constraints vs suggestions.\n\n### Uses \u2748 discuss for complex decisions\n\nWhen work selection surfaces a decision too complex for inline resolution, suggest \u2748 discuss.\n\n### Consumes \u2261 plan plans\n\nWhen the plan artifact exists with pending tasks, Step 2 reads the plan instead of reasoning from vision. Pick next pending task with satisfied dependencies. Update task status. When \u0060header.status: complete\u0060 and every task is complete, run the plan-completion sweep, archive the plan, and preserve lineage/evidence.\n\n### Reads \u25a4 document output\n\n\u0060.agentera/docs.yaml\u0060 provides artifact path resolution and versioning conventions.\n\n### Reads \u25f0 design output\n\n\u0060DESIGN.md\u0060 provides visual identity context respected when building user-facing features.\n\n### Audited by \u26f6 audit\n\n\u0060.agentera/health.yaml\u0060 findings become candidates for work selection. Run \u26f6 audit every 5-10 cycles.\n"`);
+export default instructions;
+//# sourceMappingURL=instructions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/build/instructions.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,mFAAmF;AACnF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,26gBAA26gB,CAAC,CAAC;AACt+gB,eAAe,YAAY,CAAC"}

package/dist/capabilities/design/instructions.js

@@ -0,0 +1,5 @@
+// Capability instructions for design
+// Served via `agentera prime --context design --format json`. RFC 2119 modal vocab.
+export const instructions = JSON.parse(String.raw `"# DESIGN\n\n**Visual Identity: Systematic Unified Aesthetic Language. Render, Establish, Articulate.**\n\nGlyph: ◰ (protocol ref: SG11). The visual steward of DESIGN.md — deep creation through codebase exploration, domain research, and Socratic challenge about aesthetics. Opinionated enough to enforce consistency, flexible enough to evolve, concrete enough for any agent to generate correct UI. Three modes: create, refine, audit.\n\n---\n\n## State artifacts\n\nDesign reads \u0060vision\u0060 for identity coherence and writes DESIGN.md. Artifact path resolution is owned by SKILL.md.\n\n| Artifact | Role | Path |\n|----------|------|------|\n| \u0060design\u0060 | produces_and_consumes | \u0060design_context.design.fallback_command\u0060 |\n| \u0060vision\u0060 | consumes | \u0060design_context.vision.fallback_command\u0060 |\n\n**Startup contract**: trust \u0060design_context\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context design --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\nUse \u0060agentera schema --format json\u0060 for the full design artifact specification (marker syntax, standard sections, YAML token block format, naming conventions). Do not search Agentera directories manually.\n\n### DESIGN.md format\n\nStandard Markdown with structured YAML blocks inside fenced code regions, delineated by HTML comment markers for machine parseability.\n\n\u0060\u0060\u0060markdown\n# [Project Name] Design System\n\n## Philosophy\n[Human prose: design principles, aesthetic rationale, visual personality]\n\n## Colors\n<!-- design:colors -->\n\u0060\u0060\u0060yaml\nbrand-primary: oklch(50% 0.25 25)\nbrand-secondary: oklch(60% 0.15 250)\nbackground: oklch(100% 0 0)\nforeground: oklch(0% 0 0)\n\u0060\u0060\u0060\n\n## Typography\n<!-- design:typography -->\n\u0060\u0060\u0060yaml\ntext-heading:\n  font-family: \"Inter\", sans-serif\n  font-weight: 700\ntext-body:\n  font-family: \"Inter\", sans-serif\n  font-weight: 400\n\u0060\u0060\u0060\n\n## Constraints\n<!-- design:constraints -->\n\u0060\u0060\u0060yaml\naesthetic:\n  - property: box-shadow\n    rule: prohibited\n    reason: \"Depth via borders and contrast, not shadows\"\nstructural:\n  - pattern: arbitrary-values\n    rule: prohibited\n    scope: [colors, spacing]\n\u0060\u0060\u0060\n\u0060\u0060\u0060\n\nStandard sections: \u0060colors\u0060, \u0060font-sizes\u0060, \u0060fonts\u0060, \u0060typography\u0060, \u0060spacing\u0060, \u0060radius\u0060, \u0060shadows\u0060, \u0060theme\u0060, \u0060constraints\u0060, \u0060components\u0060, \u0060tw-merge-preserve\u0060. All optional. Custom sections use the same \u0060design:\u0060 prefix with any name.\n\n---\n\n## Workflow phases\n\nMode-split shape. Three modes: **create**, **refine**, **audit**.\n\nCheck if the host project has a DESIGN.md (resolve via \u0060design_context.design.fallback_command\u0060 or \u0060agentera state query design\u0060). If it does NOT exist, proceed directly to Create mode. If it DOES exist, present the mode choice:\n\n> **Refine**: Evolve the existing design system based on what you've learned. Reads the current DESIGN.md, the codebase state, and recent progress to propose informed updates.\n>\n> **Audit**: Check the current design system for consistency, completeness, and mismatches with the codebase.\n>\n> **Replace**: Start fresh with a deep design conversation. Archives the current DESIGN.md to \u0060.agentera/archive/design-{date}.yaml\u0060 and creates a new one from scratch.\n\nIf Refine, skip to Refine mode. If Audit, skip to Audit mode. If Replace, archive current DESIGN.md, then proceed to Create mode.\n\n### Create mode\n\nStep markers: display \u0060── step N/5: verb\u0060 before each step.\nSteps: explore, research, converse, write, next.\n\n#### Step 1: Explore the codebase\n\nIf code exists, read deeply before asking questions. Arriving informed distinguishes design from a blank-slate design interview.\n\n1. **Map the structure**: directory layout, UI components, pages\n2. **Vision Identity**: declared personality, voice, emotional register from the \u0060vision\u0060 artifact. The visual system coheres with this.\n3. **Existing theme/style files**: CSS properties, Tailwind config, color declarations, font imports, component libraries\n4. **Dependency manifests**: UI framework, component library, CSS approach (determines token format)\n5. **Parent DESIGN.md**: for monorepos, the inherited design system (nested overrides)\n6. **AGENTS.md**: existing design instructions\n7. **Decision profile**: read \u0060design_context.profile.path\u0060 per protocol confidence scale (CS1-CS5) conventions. Aesthetic preferences inform the design conversation. If missing, proceed without persona grounding.\n8. \u0060git log --oneline -20\u0060: recent visual story\n\nSynthesize: \"The project uses X with Y. Palette is Z. Typography is A. Strongest patterns: B. Inconsistencies: C.\" If vision Identity exists, connect it to the visual system.\n\nGreenfield? Skip to Step 2.\n\n#### Step 2: Research the domain\n\nSearch for design context that grounds the identity in what works:\n\n1. **Stack design systems**: Tailwind themes, shadcn/ui, Radix, Material Design. Defaults and customization points.\n2. **Similar projects**: competing tools, adjacent products, established patterns\n3. **State of the art**: recent trends, emerging patterns in similar domains\n4. **Stack constraints**: framework limitations, component library opinions\n\n3-5 targeted searches. Read promising results deeply. Synthesize: \"Common approach is X. Opportunity to differentiate is Y.\"\n\n#### Step 3: The conversation\n\nEngage the user. Ask one question at a time through the runtime's question tool (always include \u0060Done\u0060 option).\n\nFollow a narrative arc, not a checklist. Adapt, but cover:\n\n1. **The philosophy**: \"Based on what I see in the codebase [and vision Identity], here's the visual impression I'd expect: [synthesis]. What should this project FEEL like visually? If someone sees the UI for 3 seconds, what impression should they have? Brutalist? Playful? Clinical? Luxurious?\"\n\n   If vision Identity exists, propose defaults: \"Your identity says 'bold and direct.' That suggests sharp edges, high contrast, no decorative shadows. Does that resonate?\"\n\n   Push beyond generic: \"'Clean and modern' is too vague. Apple-clean with whitespace, or Stripe-clean with dense information hierarchy? Very different.\"\n\n2. **The color strategy**: \"What's the color philosophy? Monochrome with a single punctuation color? Rich and saturated? Muted and professional? What color means 'this is us'?\"\n\n   Be specific: \"Two-color with single accent, or multi-color with semantic meaning? What carries the brand: background or foreground?\"\n\n   Reference existing code colors: \"\u0060#2563eb\u0060 as primary: intentional or inherited?\"\n\n3. **The typography**: \"How should text feel? Monospace for that developer-tool edge? Clean sans-serif for clarity? What's the hierarchy: how do you distinguish a label from a heading from body text?\"\n\n   Push: \"System fonts or custom? Geometric (Inter), humanist (Source Sans), industrial (JetBrains Mono)?\"\n\n4. **The constraints**: \"What MUST NOT happen in this UI? Shadows? Rounded corners? Gradients? Arbitrary values? What are the bright lines?\"\n\n   Maps to \u0060<!-- design:constraints -->\u0060. \"Every constraint prevents a class of visual mismatch.\"\n\n5. **The components**: \"What are the core UI building blocks? Buttons, cards, inputs. What variants does each need? What's the interaction pattern?\"\n\n   Maps to \u0060<!-- design:components -->\u0060. Focus on contracts: \"What props, variants, refusals? This becomes the contract agents build against.\"\n\n#### Step 4: Write DESIGN.md\n\nSynthesize the conversation into a structured design system document.\n\n**Tone**: prose sections opinionated and evocative (why tokens exist, how they relate); YAML blocks precise and machine-parseable.\n\n**Structure**: follow the spec from State artifacts. Every section gets prose + YAML. At minimum:\n\n- **Philosophy**: prose only, the aesthetic rationale\n- **Colors**: \u0060<!-- design:colors -->\u0060 with OKLCH/HSL values and semantic aliases\n- **Typography**: \u0060<!-- design:typography -->\u0060 with composite token definitions\n- **Spacing**: \u0060<!-- design:spacing -->\u0060 with a consistent scale (8pt grid recommended)\n- **Constraints**: \u0060<!-- design:constraints -->\u0060 with aesthetic and structural rules\n- **Components**: \u0060<!-- design:components -->\u0060 with variant contracts (if the project has UI)\n\nAdd \u0060theme\u0060, \u0060radius\u0060, \u0060shadows\u0060, \u0060font-sizes\u0060, \u0060fonts\u0060 as warranted.\n\nUse established scales: OKLCH for colors, 8pt grid for spacing, modular scale for type. No arbitrary values.\n\nRun \u0060agentera check lint --artifact design --text \"<DRAFT>\"\u0060 on the draft before writing. Max 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nPresent draft, get explicit approval before writing. Write the file, then run \u0060agentera check lint --artifact design\u0060 on the written file for structural validation. Fix any errors before presenting the result.\n\n#### Step 5: Next steps\n\n▸ **Set up enforcement**: propose project-local checks for tokens, component usage, and visual mismatches\n▸ **Build to the spec**: use ⧉ build to implement UI that respects the design tokens\n▸ **Document it**: use ▤ document to add the design system to project documentation\n▸ **Refine later**: use ◰ design again to evolve the design as the project matures\n\n### Refine mode\n\nEvolve an existing design system based on what's changed.\n\nStep markers: display \u0060── step N/3: verb\u0060 before each step.\nSteps: read, propose, update.\n\n#### Step 1: Read current state\n\n1. Current DESIGN.md: all token blocks, constraints, prose\n2. Codebase: focused on changes since DESIGN.md was written (git log, new components)\n3. Vision Identity: has the verbal identity evolved?\n4. \u0060progress\u0060 artifact: UI work and inline design decisions\n5. \u0060todo\u0060 artifact: design-related issues\n\n#### Step 2: Propose changes\n\n> Here's what's changed since the design system was written:\n>\n> - New components [A, B] were built that aren't in the component contracts\n> - The color palette is out of sync: [file:line] uses [value] not in the token set\n> - Vision Identity now says [X], and the visual system [does/doesn't] reflect that\n>\n> I'd suggest updating:\n>\n> - [Section]: [what to change and why]\n\nBrief conversation (2-4 exchanges) to refine proposed changes.\n\n#### Step 3: Update DESIGN.md\n\nShow diff with rationale. Get approval. Run \u0060agentera check lint --artifact design --text \"<DRAFT>\"\u0060 on the draft, max 3 revision attempts, flag [post-audit-flagged] if still failing. Write the file, then run \u0060agentera check lint --artifact design\u0060 for structural validation. Fix any errors before presenting.\n\n### Audit mode\n\nTwo-phase check: deterministic validation, then agent-driven code analysis.\n\nStep markers: display \u0060── step N/3: verb\u0060 before each step.\nSteps: validate, check, report.\n\n#### Step 1: Validate structure\n\nRun \u0060agentera check lint --artifact design\u0060 and report structural issues: malformed YAML blocks, missing sections, unresolved references, or token entries without category/name/value.\n\n#### Step 2: Check adherence\n\nScan codebase for design mismatches:\n\n1. **Token usage**: undeclared colors, fonts, or spacing values in code\n2. **Constraint violations**: prohibited properties in use (e.g., shadows when banned)\n3. **Component mismatch**: undeclared variants or prohibited props\n4. **Consistency**: ad-hoc styling on similar elements\n\n#### Step 3: Report\n\nCategorize findings by severity (protocol refs: SF1-SF3 for finding severity):\n\n- ⇶ **Critical** (VT5): tokens in code that don't exist in DESIGN.md (uncontrolled styling)\n- ⇉ **Warning** (VT6): declared tokens not used anywhere (dead tokens), mild inconsistencies\n- ⇢ **Info** (VT8): suggestions for new tokens or constraints based on observed patterns\n\nPresent with file:line references. For each finding, offer to:\n▸ **Fix DESIGN.md**: add missing tokens or constraints\n▸ **File to TODO.md**: if the code is wrong (design is right, code is out of sync)\n▸ **Skip**: intentional or not worth fixing\n\nFor framework-specific enforcement beyond audits, derive checks from the project's stack and record them directly in DESIGN.md or TODO.md.\n\n---\n\n## Safety rails\n\n<critical>\n- MUST NOT modify DESIGN.md without explicit user approval. Present drafts and get confirmation.\n- MUST NOT write design tokens that conflict with vision Identity. If the verbal identity says \"warm and approachable\" and the user wants a cold, brutalist palette, surface the tension explicitly and let the user resolve it.\n- MUST NOT impose aesthetic preferences. The user's taste drives the design. Have opinions, push for specificity, but defer to the user's choices.\n- MUST NOT skip structural validation. Run \u0060agentera check lint --artifact design\u0060 on drafts and after writing; fix errors before presenting.\n- MUST NOT create arbitrary token values. Use established scales (OKLCH for colors, 8pt grid for spacing, modular scale for type). The design system must practice what it preaches.\n- MUST NOT modify code files. Design writes DESIGN.md; build implements it. The separation of declaration and implementation is fundamental.\n- MUST NOT copy or merge suite design (\u0060protocol.yaml\u0060 tokens, app-home \u0060DESIGN.md\u0060, or capability instructions from \u0060prime --context\u0060) into the host project's \u0060DESIGN.md\u0060. Project design describes the host product only.\n- MUST NOT skip the codebase exploration step when code exists. Arriving informed is what makes the conversation productive rather than generic.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion (protocol refs: EX1-EX4).\n\nFormat: \u0060◰ design · <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): DESIGN.md was written (Create/Replace mode), updated (Refine mode), or audited with findings reported (Audit mode). \u0060agentera check lint --artifact design\u0060 passed, and all changes had explicit user approval before writing.\n- **flagged** (EX2): The design system was produced or audited but with issues worth surfacing. Possible causes: lint passed with advisory warnings, the design mismatches vision Identity in ways the user acknowledged, or audit findings were discovered that were neither fixed nor filed to TODO.md.\n- **stuck** (EX3): Cannot write DESIGN.md because the user declined to approve the draft, \u0060agentera check lint\u0060 reports errors that cannot be resolved without user input on the design intent, or the project's UI stack is inaccessible and token defaults cannot be reliably inferred.\n- **waiting** (EX4): The visual identity direction is entirely undefined and the user has not engaged with the design conversation, or the project has no UI layer and DESIGN.md would serve no purpose without clarification of what is being designed.\n\n---\n\n## Cross-capability integration\n\nDesign is the visual identity layer — the capability that defines how the project looks. It reads \u0060vision\u0060 Identity to propose visual tokens coherent with the declared personality; vision reads DESIGN.md in return; neither writes the other's artifact.\n\n### Design feeds build\n\nDESIGN.md's tokens and constraints guide autonomous UI development. When build builds components or pages, it reads DESIGN.md to understand what colors, typography, spacing, and constraints to use. The design system prevents visual mismatches across cycles.\n\n### Design is informed by\n\n- **vision** (Refine mode): when the project vision evolves, design reviews what's changed.\n- **profile**: aesthetic preferences from the decision profile inform the create conversation.\n- **research**: external design system analysis feeds into design's Research step.\n- **progress**: UI work and inline design decisions since the design system was written (Refine mode).\n- **discuss**: when design decisions require deliberation, suggest ❈ discuss before committing. Use it for competing aesthetics, brand evolution, or significant visual pivots.\n- **audit**: when audit checks architecture alignment, design adherence is a relevant dimension.\n- **document**: docs mapping tracks DESIGN.md in the artifact inventory.\n\n### Getting started\n\n- **New project**: ◰ design after ⛥ vision creates the identity, before ⧉ build implements UI.\n- **Existing project**: ◰ design reads existing styles and proposes tokens from what's already there.\n- **Audit**: \u0060/agentera design\u0060 → select \"Audit\" to validate structure and scan for mismatches.\n- **Refine**: \u0060/agentera design\u0060 → select \"Refine\" to review changes and propose updates.\n"`);
+export default instructions;
+//# sourceMappingURL=instructions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/design/instructions.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,oFAAoF;AACpF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,4liBAA4liB,CAAC,CAAC;AACvpiB,eAAe,YAAY,CAAC"}

package/dist/capabilities/discuss/instructions.js

@@ -0,0 +1,6 @@
+// Capability instructions for discuss (canonical per D57; D65 relocated from .md to .ts)
+// Served via `agentera prime --context discuss --format json`. RFC 2119 modal vocab per D71.
+// Rewritten per Decision 82 (D80 six-section spine, D79 direct-contract, D81 voice delegation).
+export const instructions = JSON.parse(String.raw `"# DISCUSS\n\n**Reflective Engagement: Socratic Observation Nexus. Examine, Reason, Arbitrate**\n\nGlyph: **❈** (protocol ref: SG4). Structured deliberation via Socratic questioning. Decisions captured as artifacts the suite consumes. The user thinks; discuss asks the right questions, challenges assumptions, and ensures sound reasoning before action.\n\nOne deliberation per invocation. The user controls when it ends.\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, run with a neutral operational stance: describe behavior, not personality.\n\n---\n\n## State artifacts\n\nDiscuss reads prior decisions and profile for context, writes decisions as its primary product, and touches vision/objective/todo only as protected follow-through.\n\n| Artifact | Role | Source |\n|---|---|---|\n| decisions | produces/consumes | \u0060agentera state decisions list --limit 20 --format json\u0060 |\n| profile | consumes | \u0060deliberation_context.profile.path\u0060 (session start) |\n| vision, objective, todo | protected writes | \u0060protected_write_boundaries\u0060 (confirmation required) |\n| docs | consumes | \u0060deliberation_context.docs_mapping\u0060 (path resolution) |\n\n**Startup contract**: trust \u0060deliberation_context\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context discuss --format json\u0060. Use the included state families first; run listed \u0060fallback_commands\u0060 before any raw decisions artifact read. Do not manually locate schemas or defensively raw-read state the CLI already serves. Artifact path resolution is owned by SKILL.md; visual-token families (VT/SI/EX/SG/PH/DL) by \u0060skills/agentera/protocol.yaml\u0060.\n\n### decisions.yaml\n\n\u0060\u0060\u0060yaml\ndecisions:\n  - number: N\n    date: \"YYYY-MM-DD\"\n    question: what was being decided\n    context: relevant constraints, triggers, or prior decisions\n    alternatives:\n      - name: Option A\n        description: Tradeoffs.\n        status: chosen\n      - name: Option B\n        description: Tradeoffs.\n        status: rejected\n    choice: what was chosen\n    reasoning: the key insight or tradeoff that resolved it\n    confidence: firm\n    feeds_into: [vision]\n\u0060\u0060\u0060\n\nPreserve the semantic top-level fields exactly (\u0060question\u0060, \u0060context\u0060, \u0060alternatives\u0060, \u0060choice\u0060, \u0060reasoning\u0060, \u0060confidence\u0060, \u0060feeds_into\u0060). Each alternative has \u0060name\u0060, \u0060status\u0060 (chosen or rejected), and optional \u0060description\u0060.\n\nNumbering, insertion order, validation, and compaction are writer-owned. Discover the live contract with \u0060agentera state decisions explain --verb append --format json\u0060; append with \u0060agentera state decisions append ... --format json\u0060.\n\n---\n\n## The deliberation loop\n\nConversational-loop shape: scratchpad plus per-turn question loop; no linear progression. The loop runs until the user picks Done.\n\n### Startup\n\n1. Read the served \u0060deliberation_context\u0060 from \u0060agentera prime --context discuss --format json\u0060 — prior decisions (avoid re-deliberation), profile path for high-confidence entries, docs mapping. If a needed family is missing or CLI state is incomplete, run the listed \u0060fallback_commands\u0060 before raw reads.\n2. If a topic was provided: name what reaching the end of this deliberation looks like — the decision to lock, the understood-shape, or the resolved tension. It fixes scope; every question serves it. Then read just enough codebase context to ask informed questions (not a research binge); acknowledge high-confidence profile entries so settled ground isn't re-litigated. Reflect understanding in 1-2 sentences, then ask the first question through the runtime-native question tool. For \u0060discuss <topic>\u0060, that question is the first user-facing action after the reflection.\n3. If no topic was provided: ask what's on their mind.\n\n### Per turn\n\nAsk every user-facing deliberation question through the runtime-native question tool; concrete tool availability belongs to the active host runtime. **One question per turn, no exceptions; every question includes a \u0060Done\u0060 option.** This overrides the routing layer's generic status/handoff question-tool gate. If the user asks for a recommendation, put a provisional recommendation in the question text, then offer accept / challenge / alternative / stop. Don't ask about \"depth\" or \"mode.\" Read the room.\n\nAfter each answer, show a short scratchpad:\n\n\u0060\u0060\u0060\n── scratchpad\n\nDecision: one-liner framing of what's being decided, updated as understanding evolves\n\nConstraints:\n▸ hard requirements that any option must satisfy\n\nRuled out:\n▸ what this decision is explicitly not about — fixed by the destination, not by sharpness\n\nOptions:\n▸ the options being considered · emerging pros/cons\n\nCrux: the key tension or uncertainty that needs to resolve for the decision to land\n\u0060\u0060\u0060\n\n5-8 bullets max. Drop items that stop being relevant.\n\n**Questions** should do one of these (≤15 words each): **Clarify** (\"When you say X, do you mean A or B?\"), **Dig deeper** (\"What's driving that?\"), **Reframe** (\"From the user's perspective instead?\"), **Challenge** (\"Is that actually true, or always been done?\"), **Connect** (\"That sounds like the same tension as Y.\"), **Unstick** (\"If you had to decide right now, what would you pick?\"), **Scope** (\"What's in and what's out?\"), **Constrain** (\"What must NOT happen?\"), **Tradeoff** (\"You can't have both X and Y. Which do you optimize for?\").\n\n**Steering**:\n- When more than one thread is open, fan across them before going deep on one — a tangent often hides the real crux off to the side.\n- When verbal exchange is slow on a visual/structural/API-shaped decision, ask the user to rough out a sketch, outline, or stub you can react to. You never produce the artifact — you ask for it and question what it reveals.\n\nWhen the decision involves code, read files or search the web for better questions — just enough context. When the profile has signal, skip settled ground.\n\n**Pushback discipline** — honest friction, don't let vague answers slide:\n- **Demand specifics.** \"What does 'better' look like? What would you measure?\"\n- **Name hidden assumptions.** \"That assumes X — based on something you've seen, or a hunch?\"\n- **Reframe imprecise framing.** \"I think the real question is Y, not X.\"\n- **Don't lower the bar.** \"Earlier you wanted Z. This gives half. Is half enough?\"\n\n**Pressure-test committed directions** — when the user leans toward a consequential direction, challenge before offering alternatives: (1) name 1-3 context-specific blind spots; (2) present serious alternatives with concrete win conditions; (3) make the call with explicit confidence (DL1-DL3).\n\n**Red-flag phrasing banned** (weakens the challenge): \"That sounds reasonable\", \"Either way is fine\", \"It depends\" without naming the variable, \"There is no wrong answer here\", \"Both options are valid\" when one conflicts with constraints.\n\n**Satisfaction authority** — when deliberation touches decision satisfaction, capture provisional satisfaction with evidence only. 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 the scratchpad or decision note instead of reconstructing hidden outcomes or claiming automation proved intent.\n\n### When the user picks \"Done\"\n\nProduce something actionable.\n\n1. **Summarize**: where we landed (2-3 sentences), key insight, confidence (DL1/DL2/DL3).\n2. **Readiness check**: name any remaining fog — what's still unphrasable or unverified. A decision is ready to land when the remaining unknowns are sharp answerable questions, not fog you can't yet phrase. If fog remains and you're calling it firm (DL1), surface that as a tension to resolve before landing; provisional (DL2) or exploratory (DL3) may land with the fog named. The user still controls when to land — this names the tax, doesn't block the exit.\n3. **Offer to capture and connect** (relevant only): Log it → new numbered decision entry (always offered); Feed into vision (direction/scope/principles); Feed into objective (what to optimize); File to todo (surfaced tech debt); Just wrap up.\n4. **Pre-write self-audit**: run \u0060agentera check lint --artifact decisions --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060) on the draft entry to catch verbosity overruns, abstraction creep, and filler. Max 3 revision attempts; flag \u0060[post-audit-flagged]\u0060 if still failing.\n5. **Write artifacts**: append the chosen decision, confidence, and rationale through \u0060agentera state decisions append ... --format json\u0060. Update satisfaction only through \u0060agentera state decisions update --number N ...\u0060. vision / objective / todo — brief follow-up, draft presented for approval per \u0060protected_write_boundaries\u0060.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT make the decision for the user. Discuss helps them think; it does not decide.\n- MUST NOT skip to implementation. The pull to *just do the work* is the signal you've reached deliberation's edge — surface it and hand off to build, plan, or research. Discuss deliberates; it does not deliver.\n- MUST NOT modify vision, objective, or todo artifacts (the \u0060protected_write_boundaries\u0060) without explicit user confirmation. Present drafts; get approval.\n- MUST NOT ask compound questions. One question per turn, with a Done option.\n- MUST NOT fabricate or imply user-confirmed final decision satisfaction. Only the user confirms final satisfaction; provisional satisfaction requires evidence. Preserve compacted, missing, open, or review-needed satisfaction as caveats.\n- MUST NOT ignore the decision profile. Acknowledge high-confidence entries; treat low-confidence entries as hypotheses.\n- MUST NOT dismiss a user's stated concern. Explore 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: \u0060─── ❈ discuss · <status> ───\u0060 followed by a one-sentence summary. For flagged, stuck, and waiting, add a \u0060▸\u0060 (VT15) bullet below the summary naming what needs attention.\n\n- **complete** (EX1): Deliberation reached a conclusion the user acted on; artifacts written with approval; confidence captured.\n- **flagged** (EX2): Deliberation concluded but unresolved or provisional; significant tensions unresolved; or the conclusion contradicts prior decisions without acknowledgment.\n- **stuck** (EX3): Cannot proceed — topic requires inaccessible external research, or a protected write failed.\n- **waiting** (EX4): No topic provided and the user hasn't responded, or deliberation surfaced that a different capability is needed first and the user hasn't confirmed how to proceed.\n\n---\n\n## Cross-capability integration\n\nDiscuss is the deliberation layer.\n\n- **Feeds ⧉ build**: direction decisions captured in vision; decision entries whose \u0060feeds_into\u0060 names vision give build reasoning context.\n- **Feeds ⎘ optimize**: what-to-optimize decisions captured in the objective artifact, resolved via optimize's active-objective inference.\n- **Triggers ⬚ research**: during deliberation, if external research is needed — \"Sounds like we need to research X with ⬚ research?\"\n- **Informed by ♾ profile**: read at session start; high-confidence entries acknowledged, low-confidence treated as hypotheses.\n- **Feeds ♾ profile**: the decisions artifact is high-signal input for profile's extraction scripts.\n- **Feeds ≡ plan**: when deliberation concludes with a decision to build something, the natural next step is ≡ plan.\n- **Triggered by ⛶ audit**: when audits reveal an architecture mismatch, audit suggests ❈ discuss to think through the response.\n\n**When to invoke** (inverse of feeds-into): run \u0060/agentera discuss\u0060 before a build session (think through direction before vision), before an optimize session (which metric matters and why, before the objective artifact), after a research analysis (evaluate which recommendations to adopt), or standalone whenever something complex needs thinking through.\n"`);
+export default instructions;
+//# sourceMappingURL=instructions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/discuss/instructions.ts"],"names":[],"mappings":"AAAA,yFAAyF;AACzF,6FAA6F;AAC7F,gGAAgG;AAChG,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,gzYAAgzY,CAAC,CAAC;AAC32Y,eAAe,YAAY,CAAC"}

package/dist/capabilities/document/instructions.js

@@ -0,0 +1,4 @@
+// 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 list --limit 20 --format json\u0060 and \u0060agentera state decisions list --limit 20 --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

@@ -0,0 +1 @@
+{"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,ypfAAypf,CAAC,CAAC;AACptf,eAAe,YAAY,CAAC"}

package/dist/capabilities/index.js

@@ -0,0 +1,38 @@
+// Capability instruction barrel (D65).
+// Re-exports each capability's prose constant as a named export plus a
+// CAPABILITY_INSTRUCTIONS lookup keyed by capability name. The CLI loader
+// imports this barrel from `../capabilities/index.js` so source-mode (vitest)
+// and dist-mode (npm install) resolve the same path.
+import { instructions as statusInstructions } from "./status/instructions.js";
+import { instructions as visionInstructions } from "./vision/instructions.js";
+import { instructions as discussInstructions } from "./discuss/instructions.js";
+import { instructions as researchInstructions } from "./research/instructions.js";
+import { instructions as planInstructions } from "./plan/instructions.js";
+import { instructions as buildInstructions } from "./build/instructions.js";
+import { instructions as optimizeInstructions } from "./optimize/instructions.js";
+import { instructions as auditInstructions } from "./audit/instructions.js";
+import { instructions as documentInstructions } from "./document/instructions.js";
+import { instructions as profileInstructions } from "./profile/instructions.js";
+import { instructions as designInstructions } from "./design/instructions.js";
+import { instructions as orchestrateInstructions } from "./orchestrate/instructions.js";
+export const CAPABILITY_INSTRUCTIONS = {
+    status: statusInstructions,
+    vision: visionInstructions,
+    discuss: discussInstructions,
+    research: researchInstructions,
+    plan: planInstructions,
+    build: buildInstructions,
+    optimize: optimizeInstructions,
+    audit: auditInstructions,
+    document: documentInstructions,
+    profile: profileInstructions,
+    design: designInstructions,
+    orchestrate: orchestrateInstructions,
+};
+export function capabilityInstructionModulePath(capability) {
+    return `packages/cli/src/capabilities/${capability}/instructions.ts`;
+}
+export function capabilityStartupCommand(capability) {
+    return `agentera prime --context ${capability} --format json`;
+}
+//# sourceMappingURL=index.js.map

package/dist/capabilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/capabilities/index.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,uEAAuE;AACvE,0EAA0E;AAC1E,8EAA8E;AAC9E,qDAAqD;AACrD,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,YAAY,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,YAAY,IAAI,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5E,OAAO,EAAE,YAAY,IAAI,oBAAoB,EAAE,MAAM,4BAA4B,CAAC;AAClF,OAAO,EAAE,YAAY,IAAI,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChF,OAAO,EAAE,YAAY,IAAI,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC9E,OAAO,EAAE,YAAY,IAAI,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAExF,MAAM,CAAC,MAAM,uBAAuB,GAA2B;IAC7D,MAAM,EAAE,kBAAkB;IAC1B,MAAM,EAAE,kBAAkB;IAC1B,OAAO,EAAE,mBAAmB;IAC5B,QAAQ,EAAE,oBAAoB;IAC9B,IAAI,EAAE,gBAAgB;IACtB,KAAK,EAAE,iBAAiB;IACxB,QAAQ,EAAE,oBAAoB;IAC9B,KAAK,EAAE,iBAAiB;IACxB,QAAQ,EAAE,oBAAoB;IAC9B,OAAO,EAAE,mBAAmB;IAC5B,MAAM,EAAE,kBAAkB;IAC1B,WAAW,EAAE,uBAAuB;CACrC,CAAC;AAEF,MAAM,UAAU,+BAA+B,CAAC,UAAkB;IAChE,OAAO,iCAAiC,UAAU,kBAAkB,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,UAAkB;IACzD,OAAO,4BAA4B,UAAU,gBAAgB,CAAC;AAChE,CAAC"}

package/dist/capabilities/optimize/instructions.js

@@ -0,0 +1,5 @@
+// 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 --context optimize --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. Use the selected objective's stable \u0060header.id\u0060 as \u0060OBJECTIVE_ID\u0060. Read experiment history with \u0060agentera state experiments list --objective OBJECTIVE_ID [--limit N] [--cursor TOKEN] --format json\u0060, fetch exact detail with \u0060agentera state experiments get --objective OBJECTIVE_ID --number N --format json\u0060, and publish only through \u0060agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json\u0060. Lists use opaque snapshot cursors, report whole-entry omissions, and preserve full, summary-only, or unavailable detail without fabricating archive history.\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\nObjective closure is recorded once in \u0060objective.yaml\u0060; do not hand-edit \u0060experiments.yaml\u0060 or append a separate closure record. The last published experiment already records the result that met the target.\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 --context optimize --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. **Experiment history**: run \u0060agentera state experiments list --objective OBJECTIVE_ID --limit 5 --format json\u0060; use exact \u0060get\u0060 only when full detail is needed and preserve returned compatibility, provenance, omission, and detail-availability fields.\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. Do not append a separate experiments closure entry; the objective document owns closure state.\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 list --objective OBJECTIVE_ID --limit 5 --format json\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\nWrite the schema-valid experiment entry without its CLI-owned \u0060number\u0060 field to a temporary YAML/JSON input, then run \u0060agentera state experiments publish --objective OBJECTIVE_ID --number N --input EXPERIMENT.yaml --format json\u0060. The writer validates identity and schema, durably publishes immutable full detail, atomically updates the bounded projection, and makes byte-equivalent retries idempotent.\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\nDo not compact or rewrite experiment history manually; publication owns the immutable archive and 10/40/50 projection.\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. Publish a schema-valid discarded experiment record with the blocker in its conclusion and context\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 the experiment published through the typed writer.\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 list --limit 20 --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 bounded experiment history with objective-scoped list/get commands.\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

@@ -0,0 +1 @@
+{"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,uztBAAuztB,CAAC,CAAC;AACl3tB,eAAe,YAAY,CAAC"}

package/dist/capabilities/orchestrate/instructions.js

@@ -0,0 +1,10 @@
+// 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 list --limit 20 --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 with \u0060agentera state plan archive --format json\u0060. The writer owns immutable archive naming and active-plan removal.\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 list --limit 20 --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 list --limit 20 --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 list --limit 20 --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. Orchestrate changes plan lifecycle state only through \u0060agentera state plan set-status ...\u0060 and \u0060agentera state plan archive\u0060.\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 active runtime provides its registry-declared subagent substrate: OpenCode: \u0060OpenCode .opencode/agents single primary agent (D73)\u0060; Codex CLI: \u0060Codex ~/.codex/agents TOML descriptors\u0060; Cursor IDE and cursor-agent are one Cursor identity: \u0060Cursor .cursor/agents single agent descriptor (D73)\u0060; Copilot CLI: \u0060Copilot CLI host-managed dispatch\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}
+
+## Evaluation Retry State
+
+After every evaluator verdict, persist it with \`agentera state plan record-evaluation --task N --attempt-id ID --verdict {pass,fail} --provenance SOURCE --format json\`. A failed verdict also requires \`--failure-evidence\`. Reuse the same stable attempt ID after an interrupted retry; the writer owns attempt counts, retains the latest failure evidence and provenance, and blocks the task after its second failed evaluation. Do not reconstruct retry state from conversation memory or modify decision satisfaction.
+`;
+//# sourceMappingURL=instructions.js.map

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

@@ -0,0 +1 @@
+{"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,gtnBAAgtnB,CAAC,CAAC;AAC3wnB,eAAe,GAAG,YAAY;;;;;CAK7B,CAAC"}

package/dist/capabilities/plan/instructions.js

@@ -0,0 +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: 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 list --limit 20 --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) runs \u0060agentera state plan archive --format json\u0060. The writer owns immutable archive naming, crash-consistent closeout, and active-plan removal. 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, task-coherence rule, 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 list --limit 20 --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**: Ordered tasks, each one build cycle, within a coherent lifecycle boundary. Split only when work crosses a real lifecycle or coherence boundary. 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: Validate and publish\n\nOptionally run \u0060agentera check lint --artifact plan --file PATH --strict --format json\u0060 for early draft feedback. The typed writer is the sole publication gate: it validates strict prose lint and schema against the final candidate before publishing.\n\nSave the approved complete plan document to temporary YAML/JSON input and run \u0060agentera state plan create --input PATH --format json\u0060 (or \u0060--input -\u0060). The writer validates the final bytes, archives a complete predecessor, injects lineage, and publishes to the docs-mapped path. Replacing an incomplete predecessor requires the approved \u0060--force\u0060 override.\n\n#### Light plan format\n\n\u0060\u0060\u0060yaml\nheader:\n  level: light\n  created: 2026-07-13\n  status: open\n  title: \"Plan: Short Title\"\nwhat: Deliver one bounded outcome.\nwhy: Keep the work ready for one build cycle.\nconstraints: Preserve the stated delivery boundary.\noverall_acceptance: GIVEN the plan is published WHEN build reads it THEN the next task is clear.\nscope:\n  included: [bounded outcome]\n  excluded: [unrelated work]\ntasks:\n  - number: 1\n    name: Deliver outcome\n    depends_on: []\n    status: pending\n    acceptance:\n      - GIVEN the work is complete WHEN behavior is checked THEN the outcome is available.\nsurprises: []\n\u0060\u0060\u0060\n\n#### Full plan format\n\nOmit \u0060rejected:\u0060 when no critic finding is dismissed; never write an empty \u0060rejected: []\u0060 section.\n\n\u0060\u0060\u0060yaml\nheader:\n  level: full\n  created: 2026-07-13\n  status: open\n  reviewed: 2026-07-13\n  critic_issues: \"1 found, 0 addressed, 1 dismissed\"\n  title: \"Plan: Short Title\"\nwhat: Deliver a validated multi-task outcome.\nwhy: Keep dependent work behaviorally ordered.\nconstraints: Preserve the stated delivery boundary.\noverall_acceptance: GIVEN all tasks complete WHEN the plan is evaluated THEN the intended outcome is available.\nscope:\n  included: [validated outcome]\n  excluded: [unrelated work]\n  deferred: []\ndesign: Sequence observable outcomes without prescribing implementation.\nunknowns:\n  - question: \"Will the dependent outcome remain necessary after task 1?\"\n    affects_task: 2\n    resolve_by: \"Use task 1 evidence before beginning task 2.\"\nrejected:\n  - issue: \"Specify an implementation library in task acceptance.\"\n    rationale: \"Behavioral acceptance remains implementation-independent.\"\ntasks:\n  - number: 1\n    name: Establish outcome\n    depends_on: []\n    status: pending\n    acceptance:\n      - GIVEN the first task completes WHEN behavior is checked THEN its outcome is available.\n  - number: 2\n    name: Verify dependent outcome\n    depends_on: [\"1\"]\n    status: pending\n    acceptance:\n      - GIVEN task 1 completes WHEN the dependent behavior is checked THEN its outcome is available.\nsurprises: []\n\u0060\u0060\u0060\n\n### Step 5: 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 keep all tasks within a coherent lifecycle boundary. Split only at real lifecycle or coherence boundaries; do not split solely to satisfy an arbitrary task count.\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

@@ -0,0 +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,yygBAAyygB,CAAC,CAAC;AACp2gB,eAAe,YAAY,CAAC"}

package/dist/capabilities/profile/instructions.js

@@ -0,0 +1,5 @@
+// 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 active-runtime Coverage Audit as 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 active runtime IDs are exactly \u0060opencode\u0060, \u0060codex\u0060, \u0060cursor\u0060, and \u0060copilot\u0060. Cursor Agent CLI storage is a Cursor source product, never a separate runtime identity. Apply \u0060--no-codex\u0060, \u0060--no-opencode\u0060, \u0060--no-copilot\u0060, or \u0060--no-cursor\u0060 only when the user selects a partial active-runtime corpus; available skipped sources require \u0060--accept-coverage-gap\u0060.\n\nClaude Code is not a supported runtime. Its transcript parser is available only as an explicit historical importer:\n\n\u0060\u0060\u0060bash\nagentera report refresh --consent local-history --import-source claude\n\u0060\u0060\u0060\n\nBefore that opt-in, warn that transcripts can contain secrets, file contents, and command output. The import is local and read-only. Every imported record is labeled \u0060source_class=historical_import\u0060, \u0060source_product=claude-code\u0060, and \u0060active_runtime=false\u0060; default active analytics exclude it. Never describe imported records as Claude support, health, installation, or active-runtime coverage. Use \u0060agentera report --sources all\u0060 only when the user explicitly asks for historical/all-source analysis, and keep provenance visible.\n\nThe extractor writes instruction documents, history prompts, conversation turns, tool calls, and project config signals. Read the corpus metadata to confirm bounded source-family counts without displaying transcript contents. If an active source fails, proceed with bounded degradation evidence; if historical import fails, report only the importer failure and do not turn it into runtime health.\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 list --limit 20 --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

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/profile/instructions.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,qFAAqF;AACrF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,qlkBAAqlkB,CAAC,CAAC;AAChpkB,eAAe,YAAY,CAAC"}

package/dist/capabilities/research/instructions.js

@@ -0,0 +1,6 @@
+// Capability instructions for research (canonical per D57; D65 relocated from .md to .ts)
+// Served via `agentera prime --context research --format json`. RFC 2119 modal vocab per D71.
+// Rewritten per Decision 83 (D80 six-section spine, D79 direct-contract, D81 voice delegation).
+export const instructions = JSON.parse(String.raw `"# RESEARCH\n\n**Insight Navigation: Source Pattern Identification and Resonance. Evaluate, Reframe, Assimilate**\n\nGlyph: **\u2b1a** (protocol ref: SG10). Analyze an external resource and map its ideas to a target project. Output a structured markdown analysis the user can navigate and act on.\n\nVoice: adopt the conversational voice declared in the project's vision artifact \u0060identity.voice\u0060 field when available \u2014 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\nNo dedicated state file. Reads the user's decision profile; writes to other capabilities' artifacts with confirmation.\n\n| Artifact | Role | Source |\n|---|---|---|\n| profile | consumes | \u0060research_context.profile\u0060 (via \u0060agentera prime --context research --format json\u0060) |\n| todo | produces | \u0060research_context.write_boundaries\u0060 |\n| vision | produces | \u0060research_context.write_boundaries\u0060 |\n\n**Startup contract**: trust \u0060research_context\u0060 and \u0060raw_artifact_read_policy\u0060 from \u0060agentera prime --context research --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. Artifact path resolution is owned by SKILL.md; visual-token families (VT/SI/EX/SG/PH) by \u0060skills/agentera/protocol.yaml\u0060.\n\n---\n\n## Workflow phases\n\nLinear shape: five steps with a named checkpoint between source reading and target exploration.\n\nAt each step, display \u0060\u2500\u2500 step N: verb\u0060 before starting that step's work.\n\n### Step 1: Identify source, target, and motivation\n\nFrom the user's message, extract:\n\n- **Source**: the external resource \u2014 could be a URL (GitHub repo, article, docs, HN thread), a local file path, a concept name (\"research the actor model\"), or a verbal approach description\n- **Target**: the user's project, which could be any of:\n  - A **GitHub repo URL** \u2192 explore via available remote-access tools\n  - A **local path** or project name \u2192 explore via filesystem tools\n  - The **current working directory** \u2192 if the user says \"my project\" / \"what I'm building\" without a URL, and they're clearly working in a project, treat cwd as the target\n  - **Absent** \u2192 if truly no target is implied, skip Steps 3\u20134 and do source-only analysis\n- **Motivation**: what the user is trying to learn or decide. Common flavors:\n  - **Adoption evaluation** \u2014 \"should I use this?\"\n  - **Idea extraction** \u2014 \"what can I learn from this?\"\n  - **Comparison** \u2014 \"how does this compare to what I'm doing?\"\n  - **Curiosity** \u2014 \"what's interesting about this?\"\n\nThe motivation shapes the analysis framing throughout.\n\n---\n\n### Step 2: Read the source\n\nRead deeply, form opinions as you go. Not a data-collection pass.\n\n#### GitHub repos\n\nUse available remote-access tools to explore the repository deeply:\n\n1. List root directory structure\n2. Read README\n3. Read key source directories until you understand: core abstractions, design patterns, notable primitives, dependencies, clever approaches worth borrowing\n\nGo deep and don't stop at the README. If available tools cannot access the repository, fall back to public pages or note the limitation.\n\n#### Articles, blog posts, docs pages\n\nFetch full content. Extract core thesis, named concepts/patterns, code samples, and referenced tools. If paywalled, try reader-mode variant; if that fails, note the limitation.\n\n#### Hacker News threads\n\nRead both the linked article and top comments. HN comments often contain the most useful distillation. Treat as signal.\n\n#### Known libraries\n\nFor well-known libraries, also check documentation databases for up-to-date docs beyond the README.\n\n#### Concept names or verbal descriptions\n\nWhen no URL is provided, draw on training data, docs, and web search to reconstruct the concept. State the sources you used.\n\n---\n\n### Transferable concepts checkpoint\n\nBefore proceeding to target analysis, surface 3\u20135 most transferable concepts from the source. These survive if the source file reads are cleared.\n\nThis is a checkpoint: the user can redirect here before you spend time mapping concepts to a project they don't need. If no target was identified in Step 1, skip to Step 5 and deliver source-only analysis using these concepts.\n\n---\n\n### Step 3: Read the target project\n\nChoose the exploration strategy based on the target type identified in Step 1.\n\n#### Local projects (current directory or local path)\n\nCommon case. Use filesystem tools (faster, includes uncommitted work):\n\n1. Map the directory structure by listing files matching relevant extensions (e.g. \u0060**/*.{ts,go,py,rs}\u0060)\n2. Read README.md if one exists\n3. Check dependency manifests (\u0060package.json\u0060, \u0060go.mod\u0060, \u0060Cargo.toml\u0060, \u0060pyproject.toml\u0060, etc.)\n4. Search for patterns, imports, or abstractions relevant to the source's concepts\n5. Read key source files to understand architecture and current patterns\n\n#### Remote GitHub repos\n\nUse available remote-access tools:\n\n1. List the root directory structure\n2. Read the README\n3. Read dependency manifests and key source files\n\n#### Build understanding of\n\nLanguage, stack, dependencies, architecture, patterns, and problems being solved.\n\n#### Check for existing usage\n\nDoes the target already use the source (or a fork/alternative)?\n\n- **Already using**: \"Getting the most out of it?\" Focus on underused features and better patterns.\n- **Using alternative**: \"Worth switching?\" Compare approaches and migration cost.\n- **Not using**: \"Should you adopt?\" This is the default framing.\n\n---\n\n### Step 4: Map concepts to the target\n\nWith both source and target understood, reason about adaptation \u2014 not replacement. How do these ideas *augment* the target's existing conventions and processes?\n\nFor each transferable concept:\n\n- What is the source doing that the target should adapt?\n- Abstractions that simplify current complexity?\n- Patterns the target implements manually or poorly?\n- Primitives worth borrowing or adapting?\n- Source doing something the target does, but better?\n- Fundamentally incompatible? Say so clearly.\n- Adoption cost: one-file change or multi-sprint evolution?\n\nFraming: research is about getting inspired and adapting ideas into what already exists, without replacing existing conventions or processes \u2014 only augmenting them.\n\n---\n\n### Step 5: Deliver the analysis\n\nOpen with your take before the structured sections: what excited you, what surprised you, what the user should care about most. The structured analysis follows, but the human read comes first.\n\nWrite a **structured markdown analysis**. If no target was given, skip the Applicability Matrix and deliver source-only transferable concepts (see \"No target given\" below).\n\n#### Output format\n\n\u0060\u0060\u0060\u0060markdown\n# [Source Name] \u2192 [Target Name]: Cross-Pollination Analysis\n\n## TL;DR\nOne or two sentences. Is this worth pursuing? What's the strongest single takeaway?\n\n## Source Overview\nBrief summary of what the source does and its core design philosophy.\n\n## Key Concepts\n\n### [Concept Name]\nWhat it is, why it's interesting, and where/how it concretely adapts to the target.\n\n### [Concept Name]\nSection repeats for each significant concept (typically 2\u20135).\n\nReasoning about adaptation SHOULD live in the response text, not the matrix.\nThe Applicability Matrix MUST contain only conclusions, not reasoning chains.\nEach matrix cell MUST be \u226415 words.\n\n## Applicability Matrix\n\n| Concept | How it adapts to [Target] | Effort | Partially present? |\n|---------|---------------------------|--------|---------------------|\n| ...     | specific adaptation approach    | Low/Med/High | Yes/No + what exists |\n\n## What Doesn't Apply\nHonest assessment of concepts/patterns that look interesting but don't fit, and why.\nBeing clear about what *not* to adopt is as valuable as the recommendations.\n\n## Recommended Next Steps\n\u25b8 [action] \u00b7 [specific file or module]\n\u25b8 [action] \u00b7 [specific file or module]\nSteps SHOULD be ordered by value/effort ratio.\n\u0060\u0060\u0060\u0060\n\n**Tone**: direct, technically fluent. Skip empty sections. Lead with highest signal.\n\nRead more files, not fewer. Shallow reads produce shallow analysis. Large repos: focus on modules most relevant to the concept, not everything. Explore source and target concurrently where possible. Always use available remote-access tools for GitHub URLs.\n\nOffer to go deeper: prototype an adaptation, explore a concept with code, compare alternatives.\n\n#### No target given\n\nSurface transferable concepts in general terms. Skip Applicability Matrix. Ask if the user wants to map to a specific project.\n\n---\n\n## Safety rails\n\n<critical>\n- Research MUST NOT modify code in the target project. It analyzes and maps concepts; other capabilities (build, optimize) implement changes. The only writes are to TODO.md and VISION.md, and only with explicit user confirmation.\n- Research MUST NOT write to TODO.md or VISION.md without explicit user confirmation. Present findings and get approval before filing.\n- Research MUST NOT present shallow analysis as deep insight. If the source was not read thoroughly, say so.\n- Research MUST NOT recommend adoption without assessing fit. Every recommendation must consider the target project's constraints, stack, and principles.\n- Research MUST NOT fabricate source content. Quote actual code and text from the source.\n</critical>\n\n---\n\n## Exit signals\n\nReport one of these statuses at workflow completion.\n\nFormat: emit \u0060\u2b1a research \u00b7 <status>\u0060 on its own line, followed by a one-sentence summary. For \u0060flagged\u0060, \u0060stuck\u0060, and \u0060waiting\u0060, add a \u25b8 bullet below the summary identifying what needs attention.\n\n- **complete**: Source was read deeply, target project was explored (if provided), concept mapping was completed, and a structured analysis with applicability matrix and recommended next steps was delivered.\n- **flagged**: Analysis completed but with limitations worth surfacing: the source was paywalled or truncated, the target project was inaccessible, or key concepts could not be fully assessed for fit.\n- **stuck**: Cannot proceed because the source URL is inaccessible and no fallback content is available, or the target project specified does not exist and cannot be located.\n- **waiting**: The source link was not provided or is malformed, or the target project is genuinely ambiguous and neither the current directory nor context resolves it.\n\n---\n\n## Cross-capability integration\n\nResearch is part of a twelve-capability suite. Its analysis feeds naturally into the other capabilities.\n\n### Feeding into build\n\nAdd actionable findings to the project's TODO.md, classifying each by severity per protocol SF1-SF3. Or refine vision's direction if the inspiration shifts thinking. The next build cycle picks up the changes automatically.\n\n### Feeding into optimize\n\nWhen the source contains optimization techniques (performance patterns, algorithm improvements, caching strategies), optimize can draw on the analysis for its next experiment.\n\n### Informed by profile\n\nThe user's decision profile, when available via \u0060research_context.profile\u0060, grounds applicability judgments in the user's patterns. Use effective confidence to weight judgments.\n\n### Feeding into vision\n\nWhen the analysis shifts thinking about the project's direction (a new paradigm, a competitor's approach, or a user need not yet captured), the findings can inform vision refinement. Suggest \u26e5 vision to revisit the project direction with the new context.\n\n### Feeding into plan\n\nWhen the analysis recommends adapting patterns or libraries, plan can incorporate those recommendations into a plan's design section and task decomposition.\n\n### Feeding into discuss\n\nWhen the analysis surfaces recommendations that require deliberation (competing approaches, unclear adoption cost, or tradeoffs the user needs to resolve), suggest \u2748 discuss to think it through before acting. Discuss can evaluate which recommendations are actually worth adopting and capture the reasoning in decisions.\n\n### Getting started\n\nAnalyze a GitHub repo:\n\n\u0060\u0060\u0060\n/agentera research https://github.com/org/repo\n\u0060\u0060\u0060\n\nReads the repo, maps its patterns to your current project.\n\nAnalyze an article or docs page:\n\n\u0060\u0060\u0060\n/agentera research https://example.com/blog/interesting-approach\n\u0060\u0060\u0060\n\nExtracts transferable concepts and assesses applicability.\n\nAfter analysis, file actionable findings to TODO.md for \u29c9 build to pick up, or refine vision if the research shifts your project's direction.\n"`);
+export default instructions;
+//# sourceMappingURL=instructions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/research/instructions.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,8FAA8F;AAC9F,gGAAgG;AAChG,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,27ZAA27Z,CAAC,CAAC;AACt/Z,eAAe,YAAY,CAAC"}

package/dist/capabilities/status/instructions.js

@@ -0,0 +1,5 @@
+// Capability instructions for status (canonical per D57; D65 relocated from .md to .ts)
+// Served via `agentera prime --context status --format json`. RFC 2119 modal vocab per D71.
+export const instructions = JSON.parse(String.raw `"# STATUS\n\n**Holistic Entry Junction. Orient, Route, Activate**\n\nSingle entry point to the agentera suite. Detects fresh vs returning, delivers a situational briefing, routes to the right capability. Same path on first install and the 100th session.\n\nGlyph: **⌂** (SG1). Status reads suite state through \u0060agentera prime\u0060 and writes nothing. A bare user message of exactly \u0060/agentera\u0060 invokes this capability; it does not fall back to conversational smalltalk.\n\nStatus MUST source state from \u0060agentera prime --format json\u0060 and write nothing. The \u0060source_contract.capability_startup\u0060 field declares whether prime is complete for capability startup; when complete, status MUST NOT run separate artifact queries or raw \u0060.agentera/*.yaml\u0060 reads. If prime fails or reports incomplete state, fall back to commands listed in \u0060source_contract.cli_fallback\u0060 as a last resort.\n\n---\n\n## Dashboard rendering\n\nStatus owns the prime dashboard contract. SKILL.md and other surfaces delegate here.\n\n\u0060\u0060\u0060text\n┌─┐┌─┐┌─┐┌┐┌┌─┐┌─┐┬─┐┌─┐\n├─┤│ ┬├┤ │││ │ ├┤ ├┬┘├─┤\n┴ ┴└─┘└─┘┘└┘ ┴ └─┘┴└─┴ ┴\n\n─── status ─────────────────────────────\n\n  ⛶ health    [⮉|⮋] [grade] ([worst dimension: grade])\n  ⇶ todo      N critical · M degraded · J annoying\n  ≡ plan      [██████▓░░░] N/M tasks\n  ⎘ optim     [metric] [current] → [target]\n  ♾ profile   [loaded | not found]\n\n  [1-2 sentence narrative read: what shipped, what's moving, what needs eyes.\n  Interpretation, not metrics. Closes the status section before attention.]\n\n─── attention ──────────────────────────\n\n  ⇶ [critical items, triple arrow for critical]\n  ⇉ [degraded items, double arrow for degraded]\n  → [normal items, single arrow for normal]\n  ⇢ [annoying items, dashed arrow for annoying]\n\n─── next ───────────────────────────────\n\n  suggested → [glyph] [capability] ([reason])\n\u0060\u0060\u0060\n\nBuild the dashboard from \u0060agentera prime --format json\u0060 output. Source labels such as \u0060mode:\u0060, \u0060profile:\u0060, \u0060v1_migration:\u0060, \u0060health:\u0060, \u0060todo:\u0060, \u0060plan:\u0060, \u0060objective:\u0060, \u0060attention:\u0060, \u0060next_action:\u0060, \u0060source_contract:\u0060, and the \u0060app.status\u0060 installed-app status object are parsing aids, not dashboard lines. Do not relay raw CLI lines as the user-facing briefing.\n\n**Output constraint**: ≤120 words total briefing, ≤15 words per routing suggestion.\n\n**Exit marker**: after the closing code fence of the dashboard, emit \u0060⌂ status · <status>\u0060 on its own line, followed by a one-sentence summary of what you delivered. For \u0060waiting\u0060, \u0060flagged\u0060, or \u0060stuck\u0060, add a \u0060▸\u0060 bullet below the summary identifying what the user needs to decide or act on next. The exit marker MUST appear on every invocation regardless of mode (fresh welcome or returning briefing).\n\n**Formatting rules**:\n- Each status line uses the skill glyph that owns that data\n- Severity arrows (VT5-VT8) mark attention items by urgency\n- Trend arrows (VT12/VT13) show health trajectory; derive ⮉/⮋ from \u0060health.degrading\u0060 (false→⮉, true→⮋); omit when no audit history\n- Progress bars (VT18) show plan completion visually\n- The inline separator (VT16) joins counts on a single line\n- Lead with status metrics, then the narrative read inside the status section\n- The narrative read is colleague interpretation; metric lines above it are evidence\n- The todo summary line lists critical, degraded, and annoying counts only; normal-priority items belong in attention with → (SI3), not on the summary line\n- Omit any line whose source artifact is missing\n- Omit any section that would be empty (e.g., no attention items = no attention section)\n\nVisual token IDs live in \u0060skills/agentera/protocol.yaml\u0060; see VT, SI, EX, SG, PH families.\n\n---\n\n## Briefing\n\nUse the \u0060mode\u0060 field from \u0060agentera prime\u0060 to detect fresh vs returning:\n\n- **Fresh** (\u0060mode: fresh\u0060): render welcome language; lead with the suggested capability from \u0060next_action\u0060. Do not enumerate the full suite unless asked.\n- **Returning** (\u0060mode: returning\u0060): render the dashboard template above using \u0060mode\u0060, \u0060profile\u0060, \u0060health\u0060, \u0060todo\u0060, \u0060plan\u0060, \u0060objective\u0060, \u0060attention\u0060, and \u0060next_action\u0060 fields.\n\nNarration voice: warm, brief, unscripted.\n\n### Project integration rendering\n\nWhen \u0060project_integration.recommendation\u0060 is \u0060upgrade\u0060:\n1. Render the plain-language \u0060project_integration.message\u0060.\n2. Show \u0060project_integration.dry_run_command\u0060 preview; state that it changes nothing.\n3. Ask before running \u0060project_integration.apply_command\u0060.\n\nWhen \u0060recommendation\u0060 is \u0060stay\u0060, do not suggest upgrade.\n\n### App status rendering\n\nRender \u0060app.status\u0060 as a status line only when it is not \u0060up_to_date\u0060. Use the plain-language \u0060project_integration.message\u0060 if present. Status MUST NOT teach install-recovery procedure — that belongs to the upgrade capability and \u0060agentera doctor\u0060.\n\n### Profile rendering\n\nRender \u0060profile.status\u0060 (\u0060loaded\u0060 or \u0060not found\u0060). Render \u0060profile.suggested_action\u0060 or a missing-profile attention item only when prime supplies one.\n\n### Attention items\n\nPriority order with severity arrows (SI1-SI4):\n\n- ⇶ (SI1) Critical issues, degrading health dimensions\n- ⇉ (SI2) Blocked/overdue plan tasks, stale artifacts, overdue health audits (prime \u0060health.stale=true\u0060), loop stop-condition triggers\n- → (SI3) Standard work: features, improvements, routine tasks\n- ⇢ (SI4) Unresolved exploratory decisions\n\nA clean bill of health is useful — say so when nothing is flagged.\n\n---\n\n## Routing suggestion\n\nThe routing suggestion MUST name the artifact item it would act on. A skill name without a concrete object is not a valid suggestion.\n\nValid objects: \u0060PLAN Task N: <title>\u0060, \u0060TODO: <item>\u0060, \u0060DECISION N follow-up\u0060, \u0060OBJECTIVE: <metric>\u0060, or \u0060VISION refresh\u0060.\n\n**Priority order** (SG codes are internal protocol references; never render them in user-facing handoff labels):\n\n- Active PLAN with pending tasks → suggest ⎈ orchestrate for the first unblocked pending task.\n- Critical or degrading health → suggest ⛶ audit or ⧉ build for the named finding.\n- Stale health audit (CLI \u0060health.stale=true\u0060) with no higher-priority work → suggest ⛶ audit for \u0060HEALTH: Audit N stale\u0060.\n- Active non-closed OBJECTIVE with stalled or missing metric evidence → suggest ⎘ optimize for that metric.\n- todo open items → select the highest-severity open item, then route by shape: narrow one-cycle todo items suggest ⧉ build; contract-shaped, multi-surface, dependency-heavy, migration, schema, metadata, validation, or acceptance-risky todo items suggest ≡ plan first. Prefer items that unlock product evidence or future plans.\n- Pending decisions follow-up → suggest ❈ discuss for the named unresolved decision.\n- Vision exists but no plan, objective, decision follow-up, or TODO work is active → suggest ≡ plan.\n- No vision, no executable follow-ups, and no active plan → suggest ⛥ vision to choose a direction.\n\nDo not let \u0060healthy + plan complete → ⛥\u0060 override active TODO, OBJECTIVE, DECISIONS, or a newer active PLAN. A completed plan means \"look for the next executable follow-up,\" not automatically \"refresh vision.\"\n\n### Routing posture\n\n- Present one concrete suggestion and let the user choose. Coercion MUST NOT occur.\n- Do not list generic skill options unless the user asks for the full menu.\n- The waiting bullet should ask whether to run the named action, not ask the user to pick from skills.\n- On the initial status brief, use a free-form continuation prompt rather than a native question menu unless the user asked for bounded choices or the suggested next step is a state-changing Proceed/Cancel handoff.\n- Mid-conversation, use the native question tool only for at least two meaningful non-terminal next actions or a consequential Proceed/Cancel decision; \u0060Done\u0060 and free-form/custom answer affordances do not count as alternatives.\n- State-changing handoffs are consequential Proceed/Cancel decisions even when there is only one suggested action. State-changing means the proposed next step may write artifacts, edit code, run optimization or orchestration cycles, apply migrations, refresh app/runtime state, or otherwise mutate project/runtime state.\n- Use the behavior rule first, with common examples such as ⧉ build, ≡ plan when creating or updating plans, ▤ document when writing docs, ⎘ optimize when running or applying optimization cycles, and ⎈ orchestrate when dispatching cycles.\n- For one non-mutating suggested action, clear free-form acceptance such as \u0060yes\u0060, \u0060start\u0060, \u0060do it\u0060, or \u0060run <capability>\u0060 confirms that suggestion. Ambiguous replies get one clarifying question.\n\nUnclear mapping? Ask **one** clarifying question. Compound questions MUST NOT occur.\n\n---\n\n## Safety rails\n\n<critical>\n- NEVER execute implementation work. Status orients and routes; it MUST NOT build, audit, plan, or decide.\n- NEVER dump full artifact contents verbatim. Summarize concisely; the user can read the files themselves.\n- NEVER skip the briefing in returning mode. The user needs context before choosing a direction.\n- NEVER assume what the user wants without asking. Present the suggestion, then wait for confirmation.\n- NEVER modify any state artifact. Status is strictly read-only.\n- NEVER route to a capability without the user's consent. Suggest, don't force.\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⌂ status · <status>\u0060 on its own line below the dashboard's closing code fence, followed by a one-sentence summary of what was delivered. For \u0060flagged\u0060 (EX2), \u0060stuck\u0060 (EX3), and \u0060waiting\u0060 (EX4), add a \u0060▸\u0060 (VT15) bullet below the summary identifying what the user needs to decide or act on next. The exit marker MUST appear on every invocation regardless of mode and uses status's canonical glyph \u0060⌂\u0060 (SG1, U+2302).\n\n- **complete** (EX1): Briefing delivered (or welcome shown in fresh mode) and user successfully routed to a capability.\n- **flagged** (EX2): Briefing delivered but critical attention items were found: critical issues, degrading health, loop stop-condition triggers. Each concern MUST be listed explicitly.\n- **stuck** (EX3): Cannot orient: the working directory is not a code project, no readable files exist, or permissions prevent scanning.\n- **waiting** (EX4): Briefing or welcome delivered, suggestion made, awaiting user input on which direction to take.\n\n---\n\n## Cross-capability integration\n\nStatus is the suite entry point. It reads other capabilities' artifacts, produces no artifact, and outputs only a briefing plus routing suggestion.\n"`);
+export default instructions;
+//# sourceMappingURL=instructions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/status/instructions.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,4FAA4F;AAC5F,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,ikWAAikW,CAAC,CAAC;AAC5nW,eAAe,YAAY,CAAC"}