agentera 3.0.0-dev.13 → 3.0.0-dev.15

package/bundle/skills/agentera/capabilities/plan/schemas/validation.yaml

@@ -54,8 +54,35 @@ VALIDATION:
     rule: skip_level_for_trivial_work
     description: >-
       Plan MUST detect skip level for trivial work (single-file change,
-      bug fix, config tweak, < 50 lines) and route directly to /build
-      without producing a PLAN.md.
+      localized defect fix, or config tweak that touches no shared
+      abstraction) and route directly to /build without producing a
+      PLAN.md. LOC count is not a skip signal because small changes to
+      shared exports can ripple across many consumers.
     severity: critical
     checks:
       - "Trivial work routed to /build without plan"
+  7:
+    id: V7
+    rule: full_plan_unknowns_required
+    description: >-
+      Every full plan MUST surface at least one planning-time known-unknown
+      in the `unknowns:` field. Each entry MUST include question,
+      affects_task, and resolve_by. Skip level and light plans are exempt
+      because they do not decompose work into interdependent tasks.
+    severity: warning
+    checks:
+      - "Full plans have a non-empty `unknowns:` list"
+      - "Each unknown entry has question, affects_task, resolve_by fields"
+  8:
+    id: V8
+    rule: adversarial_review_dismissals_persisted
+    description: >-
+      Full plans MUST persist dismissed adversarial-review findings in the
+      artifact's `rejected:` field, each with issue text and rationale, so
+      downstream consumers (build, orchestrate, audit) inherit the
+      adjudication rather than relitigating. V3 enforces the review ran;
+      V8 enforces the dismissal provenance persists.
+    severity: warning
+    checks:
+      - "Full plans with dismissed critic findings have `rejected:` entries"
+      - "Each rejection has issue and rationale fields"

package/bundle/skills/agentera/capabilities/profile/schemas/exit.yaml

@@ -22,8 +22,7 @@ EXIT_CONDITIONS:
     condition: stuck
     description: >-
       Cannot generate or validate a profile because extraction scripts
-      failed entirely, Python is unavailable, or session data sources
-      are unreadable.
+      failed entirely or session data sources are unreadable.
     exit_signal: stuck
   4:
     id: E4

package/bundle/skills/agentera/capabilities/research/schemas/artifacts.yaml

@@ -19,6 +19,6 @@ ARTIFACTS:
     artifact_id: profile
     local_role: consumes
     description: >-
-      Research reads this via the effective profile script to weight
-      applicability judgments. If missing, research proceeds without persona
-      grounding.
+      Research reads the profile via research_context.profile from the prime
+      context to weight applicability judgments. If missing, research proceeds
+      without persona grounding.

package/bundle/skills/agentera/capabilities/vision/schemas/exit.yaml

@@ -3,9 +3,9 @@ EXIT_CONDITIONS:
     id: E1
     condition: complete
     description: >-
-      VISION.md was written (Create/Replace mode) or updated (Refine mode)
-      with explicit user approval. The vision is ambitious, concrete, and
-      structured to sustain autonomous development.
+      The vision artifact was written (Create/Replace mode) or updated
+      (Refine mode) with explicit user approval. The vision is ambitious,
+      concrete, and structured to sustain autonomous development.
     exit_signal: complete
   2:
     id: E2
@@ -14,14 +14,15 @@ EXIT_CONDITIONS:
       The vision was produced but with weaknesses worth surfacing: the user
       settled for a less ambitious or less specific vision than pushed for,
       key sections (personas, principles, direction) are thin due to limited
-      conversation depth, or the vision has unresolved tensions with existing
-      DECISIONS.md entries.
+      conversation depth, or the vision has unresolved tensions with
+      existing decision entries.
     exit_signal: flagged
   3:
     id: E3
     condition: stuck
     description: >-
-      Cannot write VISION.md because the user declined to approve the draft
+      Cannot write the vision artifact because the user declined to approve
+      the draft
       and no actionable revision direction was given, or codebase exploration
       failed in a way that would make the vision unreliable.
     exit_signal: stuck

package/bundle/skills/agentera/capabilities/vision/schemas/triggers.yaml

@@ -18,7 +18,7 @@ TRIGGERS:
     priority: medium
     patterns:
       - "create a vision"
-      - "write VISION.md"
+      - "write the vision"
       - "define the direction"
       - "set the north star"
       - "dream bigger"
@@ -32,14 +32,14 @@ TRIGGERS:
     patterns:
       - "rethink the vision"
       - "refine the vision"
-      - "update VISION.md"
+      - "update the vision"
     confidence_threshold: 50
     disambiguates_against:
       - capability: build
         hint: "vision refines existing project direction; build implements code"
     patterns_regex:
       - "\\brefine\\s+the\\s+vision\\b"
-      - "update\\s+VISION\\.md"
+      - "update\\s+the\\s+vision"
   4:
     id: T4
     description: >-

package/bundle/skills/agentera/capabilities/vision/schemas/validation.yaml

@@ -3,8 +3,8 @@ VALIDATION:
     id: V1
     rule: user_approval_required
     description: >-
-      VISION.md MUST NOT be written or modified without explicit user
-      approval. Present drafts and get confirmation before writing.
+      The vision artifact MUST NOT be written or modified without explicit
+      user approval. Present drafts and get confirmation before writing.
       This applies to both Create and Refine modes.
     severity: critical
     checks:
@@ -14,12 +14,12 @@ VALIDATION:
     id: V2
     rule: no_realisera_modification
     description: >-
-      VISION.md MUST NOT be modified during a build execution cycle.
-      Vision changes happen only in dedicated vision sessions. This
-      prevents vision drift during autonomous development.
+      The vision artifact MUST NOT be modified during a build execution
+      cycle. Vision changes happen only in dedicated vision sessions.
+      This prevents vision drift during autonomous development.
     severity: critical
     checks:
-      - "VISION.md not written during build cycle"
+      - "Vision artifact not written during build cycle"
   3:
     id: V3
     rule: inspirational_tone
@@ -29,7 +29,7 @@ VALIDATION:
       should inspire and guide, not specify.
     severity: warning
     checks:
-      - "VISION.md is aspirational, not prescriptive"
+      - "The vision artifact is aspirational, not prescriptive"
   4:
     id: V4
     rule: codebase_exploration_required

package/dist/capabilities/audit/instructions.js

@@ -1,6 +1,4 @@
-// Source: skills/agentera/capabilities/audit/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 `"# AUDIT\n\n**Integrity Navigation: Systematic Pattern Evaluation, Knowledge Tracing. Examine, Report, Advise.**\n\nCodebase health audit: multi-dimensional structural quality evaluation with evidence-based findings, confidence scores, and trajectory tracking. The retrospective counterpart to build's forward motion: is the codebase getting better or just bigger?\n\nEach invocation = one audit. Findings feed build's work selection via TODO.md. Skill introduction: \u0060─── ⛶ audit · audit ───\u0060\n\n---\n\n## Visual identity\n\nGlyph: **⛶** (protocol ref: SG3). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOne file in \u0060.agentera/\u0060, bootstrapped if absent.\n\n| File | Purpose | Bootstrap |\n|------|---------|-----------|\n| \u0060HEALTH.md\u0060 | Canonical health artifact, stored as \u0060.agentera/health.yaml\u0060 unless mapped otherwise. Findings, dimension grades, trajectory. | First audit entry in YAML form. |\n\nUse \u0060agentera describe --format json\u0060 and its \u0060artifact_schemas\u0060 entry for \u0060health\u0060 to locate the active installed schema; do not search Agentera directories manually. Existing health artifacts provide repository-local examples of the shape.\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, check if \u0060.agentera/docs.yaml\u0060 exists. If it has an Artifact Mapping section, use the path specified for each canonical filename. If \u0060.agentera/docs.yaml\u0060 doesn't exist or has no mapping for a given artifact, use the default layout: TODO.md, CHANGELOG.md, and DESIGN.md at the project root; canonical VISION.md at \u0060.agentera/vision.yaml\u0060; other agent-facing artifacts at \u0060.agentera/*.yaml\u0060. This applies to all artifact references in this capability, including cross-capability reads (VISION.md, \u0060.agentera/decisions.yaml\u0060, TODO.md, \u0060.agentera/progress.yaml\u0060).\n\n### Contract\n\nBefore starting, read \u0060references/contract.md\u0060 (at v2 skill location \u0060skills/agentera/references/contract.md\u0060) for authoritative values: token budgets, severity levels, format contracts, and other shared conventions referenced in the steps below. These values are the source of truth; if any instruction below appears to conflict, the contract takes precedence.\n\n### health.yaml\n\nOpen with your read on the codebase before the structured data: what's improving, what's sliding, what surprised you. 1-2 sentences of interpretation, then the grades and findings back it up. The colleague says what they think, then shows the evidence.\n\n\u0060\u0060\u0060yaml\naudits:\n  - number: 1\n    date: YYYY-MM-DD\n    dimensions: [architecture_alignment, test_health]\n    findings_summary: \"X critical, Y warnings, Z info\"\n    overall: stable\n    dimension_grades:\n      - dimension: architecture_alignment\n        grade: B\n    findings:\n      - severity: degraded\n        title: Finding title\n        confidence: 80\n        location: file:line\n        evidence: What was observed.\n        impact: Why this matters.\n        suggested_action: Specific fix or investigation.\n    trends: What improved, degraded, or changed.\n    patterns_observed: De facto architecture patterns.\n\u0060\u0060\u0060\n\n---\n\nStep markers: display \u0060── step N/7: verb\u0060 before each step.\nSteps: orient, select, assess, distill, audit, report, connect.\n\n### Evidence context startup\n\nBefore Step 1, start evaluation state gathering with:\n\n\u0060\u0060\u0060bash\nagentera prime --context audit --format json\n\u0060\u0060\u0060\n\nUse the returned \u0060evidence_context\u0060 before raw plan, progress, docs, health, TODO, or decisions artifacts. If \u0060evidence_context.source_contract.complete_for_evidence_context\u0060 is true, do not read raw PLAN, PROGRESS, DOCS, HEALTH, TODO, or DECISIONS artifacts merely to reconstruct evaluation target, plan criteria, progress verification, docs state, health state, TODO state, protected-state checks, version checks, residual risks, fallback commands, caveats, provenance, or non-empty evidence flags.\n\nIf \u0060evidence_context\u0060 is absent, incomplete, or caveated for a state family you need, run the listed \u0060evidence_context.fallback_commands\u0060 first. If those are unavailable, use \u0060capability_context.state.fallback_commands\u0060 from the same prime response. Raw artifact reads are last-resort diagnostics after listed CLI fallbacks, not normal evaluation startup behavior.\n\nPreserve caveats from \u0060evidence_context.state_family_caveats\u0060, \u0060evidence_context.residual_risks.attributed_items\u0060, \u0060decision_context.caveats\u0060, \u0060protected_state_checks.caveats\u0060, and \u0060version_checks.caveats\u0060 when reporting evaluation results. Do not hide, flatten, or reconstruct stale app/profile state, compacted decisions, protected-state boundaries, unavailable version evidence, absent publication or remote evidence, manual-check states, or residual risks. These caveats calibrate confidence; they are not approval to refresh installed apps, refresh profile state, read or edit \u0060.agentera/vision.yaml\u0060, read or edit objective state, contact remotes or registries, or invent missing history.\n\n### Decision satisfaction authority\n\nWhen an audit touches decision satisfaction, agents may mark provisional\nsatisfaction with evidence only. Audit must not mark, infer, or\nuser-confirm final satisfaction; only the user confirms final satisfaction. If\ndecisions are compacted, missing satisfaction state, open, provisional, or\nreview-needed, preserve the caveat and review pressure in findings and residual\nrisks instead of reconstructing hidden outcomes or claiming automation proved\nintent.\n\n## Step 1: Orient\n\nUse complete \u0060evidence_context\u0060 first for the evaluated target, current plan criteria, latest progress verification, docs state, health state, TODO state, decision caveats, protected-state checks, version checks, and residual risks. Only run listed CLI fallbacks before raw artifact reads when the context is incomplete for the state needed.\n\n1. **Health state**: use \u0060evidence_context.health_state\u0060 for prior audit findings, grades, current-state status, and caveats.\n2. **Protected-state boundary**: use \u0060evidence_context.protected_state_checks\u0060 and preserve any not-checked-by-design caveats instead of reading protected state.\n3. **Decision context**: use \u0060evidence_context.decision_context\u0060 for decision caveats. Findings contradicting deliberate decisions are not findings.\n4. **TODO state**: use \u0060evidence_context.todo_state\u0060 for known problems. Don't re-report unless worsened.\n5. **Progress verification**: use \u0060evidence_context.progress_verification\u0060 for recent-cycle verification and caveats.\n5b. **Change magnitude**: run \u0060git log --stat\u0060 on commits since the last health audit timestamp to estimate total change volume. If the audit timestamp is unavailable, skip; default depth applies.\n5c. **Plan context** (for artifact current-state review): use \u0060evidence_context.evaluation_target\u0060 and \u0060evidence_context.plan_criteria\u0060 for the plan-relative baseline. If the evidence context reports no target, missing criteria, or missing current-state baseline, preserve that caveat; do not reconstruct it from raw plan state during normal startup.\n6. **Decision profile**: use profile/app caveats already attributed in \u0060evidence_context.residual_risks\u0060; stale or unavailable profile state calibrates confidence but is not approval to refresh profile state or read profile directly during startup.\n7. **Project discovery**: map directory structure, read dependency manifests, README, CLAUDE.md, AGENTS.md, identify language/stack/build commands, \u0060git log --oneline -20\u0060\n\nBefore proceeding: in your response, list the key structural facts (module boundaries, dependency patterns, test coverage gaps) you observed. These survive context compaction.\n\n**Exit-early stop condition**: If \u0060git diff\u0060 since the last \u0060evidence_context.health_state\u0060 audit timestamp shows no file changes, report exit signal \u0060complete: no changes since last audit\u0060 and stop.\n\n---\n\n## Step 2: Select dimensions\n\nChoose dimensions based on the codebase and user request. Not every dimension applies; a 200-line CLI doesn't need the same audit as a monorepo.\n\n### Available dimensions\n\n| Dimension | What it evaluates | When to include |\n|-----------|-------------------|-----------------|\n| **Architecture alignment** | Does the code match the stated architecture? Pattern mismatches, module boundary violations, layering breaks. | VISION.md or README describes architecture |\n| **Pattern consistency** | Are patterns used consistently? Naming, error handling, structure, abstractions. | Any codebase with 5+ modules or files |\n| **Coupling health** | Hidden dependencies, circular imports, god modules, inappropriate intimacy. | Any codebase with multiple modules |\n| **Complexity hotspots** | Functions too long, deeply nested, high fan-out, accumulated conditionals. | Any codebase |\n| **Test health** | Coverage gaps, test quality, test-to-code ratio, tests testing behavior vs implementation. | Project has tests |\n| **Dependency health** | Outdated deps, security advisories, unused deps, dep sprawl, pinning discipline. | Project has external dependencies |\n| **Version health** | Unreleased significant changes: \u0060feat\u0060/\u0060fix\u0060 commits since the last version bump. | DOCS.md has a \u0060versioning\u0060 convention block |\n| **Artifact freshness** | Are state artifacts current relative to plan activity or recent development? Protected health dimension label; current prose should call the work artifact current-state review. Detects artifacts that should have been updated but weren't. | Plan context available (PLAN.md with \u0060Created\u0060 date) or PROGRESS.md has entries |\n| **Prose health** | Do artifact entries respect the writing rules? Checks verbosity overruns, abstraction creep, and filler accumulation across all project artifacts. | Project has 3+ artifact files |\n| **Security hygiene** | Hardcoded secrets, dangerous function calls, basic injection patterns. Lightweight regex-based scan, not a replacement for dedicated security tooling. | Any codebase |\n\n### Depth guidance\n\nWhen change magnitude was derived in Step 1, apply advisory depth scaling:\n\n- **Light changes** (roughly ≤5 files, ≤200 lines since last audit): prioritize dimensions most relevant to the changed areas. Skip dimensions with no intersection.\n- **Standard changes** (default): assess all applicable dimensions at normal depth.\n- **Heavy changes** (roughly ≥20 files or architectural-scope commits): assess all applicable dimensions and increase evidence collection depth. Read more files per dimension, trace more dependency paths, check more edge cases.\n\nThese thresholds are guidelines, not hard rules. Use judgment: a 6-file change touching a critical security module warrants thorough depth, while a 25-file rename is light.\n\n**User specified dimensions**: audit only those.\n**Full audit or unspecified**: auto-select all applicable. Report selections before proceeding.\n\n---\n\n## Step 3: Assess\n\nLead the assessment with your overall interpretation: what stands out, what's changed, where attention should go. Then the per-dimension breakdown provides the evidence.\n\nLaunch parallel agents, one per dimension. Each receives the dimension definition, language-specific commands from \u0060references/audit-commands.md\u0060 (at v2 skill location \u0060skills/agentera/references/audit-commands.md\u0060), relevant context files, the confidence scoring rubric, and instructions to return structured findings.\n\n**Before deep analysis**: run the quick checklist for a rapid pass/fail sweep. Dimensions passing all items can be audited at lower priority.\n\n\u0060\u0060\u0060\nYou are auditing the [dimension] health of [project].\n\n## What to evaluate\n[Dimension-specific instructions from below]\n\n## Evidence standard\nEvery finding MUST include:\n- Specific file and line references\n- Quoted code showing the issue\n- Explanation of why it matters\n- Confidence score (0-100)\n\n### Citation standard (WARN and FAIL findings)\nEvery warning or critical finding MUST carry a reproducible anchor:\n- **Health audit findings**: \u0060location: <file>:<line>\u0060 in health.yaml (or \u0060not-applicable: <reason>\u0060 when no file anchor exists)\n- **Orchestrate evaluation reports**: \u0060citation: <file>:<line>\u0060 per row (schema: \u0060agentera.inspekteraEvaluationReport.v1\u0060 in \u0060references/cli/capability-instruction-contract.yaml#evaluator_handoff\u0060)\n- **WARN rows with file:line citations**: include \u0060verify_command\u0060 with the exact \u0060grep\u0060 or \u0060git show\u0060 invocation that reproduces the evidence at the cited line when re-run\n\nProse-only evidence for WARN/FAIL findings is incomplete. The orchestrator treats missing or invalid citations as evaluation failures.\n\n## Presenting findings\nIntroduce each finding conversationally before the structured evidence. The colleague\nsays \"hey, I noticed this\" instead of just dumping a finding card. Lead with why it caught your eye and what it means, then back it up with the evidence block.\n\n## Confidence scoring (protocol: CS1-CS5)\n- 90-100 (CS1): Definitely a real issue. Verified by reading the code. Clear impact.\n- 70-89 (CS2): Very likely a real issue. Strong evidence, but some context might justify it.\n- 50-69 (CS3): Possibly an issue. The pattern is suspicious but could be intentional.\n- 30-49 (CS4): Uncertain. Might be an issue, might be a reasonable tradeoff.\n- 0-29 (CS5): Speculative. Flagging it but wouldn't be surprised if it's fine.\n\n## What is NOT a finding\n- Pre-existing patterns that are consistent and deliberate\n- Things a linter or type checker would catch (assume CI handles those)\n- Subjective style preferences not grounded in stated project principles\n- Known issues already tracked in TODO.md\n- Intentional decisions documented in DECISIONS.md\n\u0060\u0060\u0060\n\n### Architecture alignment\n\nCompare codebase to stated architecture:\n\n- Read VISION.md (or README.md architecture section) for intended structure\n- Map actual module boundaries, dependency graph, data flow\n- Identify mismatches from stated architecture\n- Check layering and boundary cleanliness\n- Extract \"Patterns Observed\": de facto architecture independent of documentation\n\nNo documented architecture? Extract and report de facto; note absence as a finding.\n\n### Pattern consistency\n\nCheck consistency across the codebase:\n\n- Error handling (returns vs throws vs error types)\n- Naming (singular vs plural, prefixes, casing)\n- Module structure and layout similarity\n- Competing abstractions for the same concept\n- Duplicated logic that should be shared\n- Config handling (env vars vs files vs flags)\n\nFocus on inconsistencies between similar things, not whether the chosen pattern is \"best.\"\n\n### Coupling health\n\nEvaluate coupling and dependency structure:\n\n- Map import graphs, identify circular dependencies\n- Find god modules (too many dependents or dependencies)\n- Check for inappropriate intimacy (reaching into internals)\n- Evaluate interface width: narrow boundaries or exposing everything?\n- Check hidden coupling via shared mutable state, global config, side effects\n\nUse language tools (\u0060go list\u0060, \u0060madge\u0060, import analysis). If unavailable, trace imports manually on highest-risk modules.\n\n### Complexity hotspots\n\nFind accumulating complexity:\n\n- Long functions (generally 50+ lines), deep nesting (3+ levels)\n- High fan-out, growing switch/match statements, many parameters (5+)\n- Files growing cycle over cycle (check git history)\n\nPrioritize high-change files: frequently modified + complex = high risk.\n\n### Test health\n\nEvaluate test suite quality and coverage:\n\n- Run coverage tools if available, otherwise estimate from file analysis\n- Identify critical paths with no coverage\n- Check: testing behavior or implementation? Excessive mocking? Brittle assertions?\n- Evaluate test naming: can you understand what failed from the name alone?\n- Check test-to-code ratio per major module\n- Check test proportionality against contract: default is one pass + one fail per testable unit. Flag under-testing and over-testing.\n\nDon't just report a number. Identify the *highest-risk* coverage gaps.\n\n### Dependency health\n\nEvaluate dependency management:\n\n- Outdated deps (package manager audit/outdated commands)\n- Known security vulnerabilities (npm audit, safety check, govulncheck)\n- Unused deps (installed but not imported)\n- Dep sprawl relative to project scope\n- Pinning discipline (pinned or floating?)\n- Vendored vs remote consistency\n\n### Version health\n\nOnly run this dimension if DOCS.md exists and contains a \u0060versioning\u0060 convention block. Skip entirely if the convention is absent.\n\n- Read DOCS.md \u0060Conventions.versioning\u0060 to identify the version file(s) and bump trigger rules\n- Run \u0060git log --oneline\u0060 to find \u0060feat\u0060 and \u0060fix\u0060 commits since the last modification date of the version file(s)\n- Count unbumped \u0060feat\u0060/\u0060fix\u0060 commits and note the age of the oldest one\n- Severity: warning (SF2) if 1-4 unbumped commits or age ≤ 7 days; critical (SF1) if 5+ unbumped commits or age > 7 days\n- If no \u0060feat\u0060/\u0060fix\u0060 commits have landed since the last bump, this dimension is healthy with no finding\n\n### Artifact current-state review\n\nEvaluates whether state artifacts are current relative to plan activity or recent development. The persisted health dimension label remains \u0060Artifact freshness\u0060; current prose should call the work artifact current-state review. Uses the staleness convention from contract.\n\n**With plan context** (PLAN.md has a created date and task execution history):\n\n- Read the plan's \u0060Created\u0060 date from its HTML comment metadata\n- Identify which capabilities were dispatched during the plan by scanning task entries and PROGRESS.md cycle logs\n- For each dispatched capability, look up its expected artifacts in the contract staleness detection mapping\n- Check each expected artifact's last modification date: \u0060git log -1 --format=%aI -- <path>\u0060\n- An artifact is **stale** if its last modification predates the plan's creation date AND the capability that owns it was dispatched at least once during the plan\n- Severity: warning (SF2, confidence 70+). Plan-relative staleness carries causal evidence.\n- Artifacts that a capability reads but does not produce are not staleness candidates\n\n**Without plan context** (no PLAN.md, or PLAN.md has no created date):\n\n- Fall back to PROGRESS.md recency: an artifact is potentially stale if it was not modified since the most recent PROGRESS.md cycle entry date\n- If PROGRESS.md has no entries (fresh project), no staleness check applies\n- Severity: info (SF3, confidence 50-60). The fallback is advisory, not authoritative.\n\n**Handling**: stale artifact findings are reported like any other dimension finding but noted as context for the next plan cycle, not as blocking errors.\n\n### Prose health\n\nEvaluate artifact prose quality against the three Self-Audit Protocol rules. Use routine CLI state first for artifact-backed context, including \u0060agentera decisions --format json\u0060 for DECISIONS.md. Preserve returned decision \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 pressure; raw decision artifact reads are for artifact-quality inspection, corruption diagnostics, or CLI defects, not normal post-CLI context recovery. Read all project artifacts (PROGRESS.md, DECISIONS.md, PLAN.md, HEALTH.md, TODO.md, CHANGELOG.md, VISION.md, DESIGN.md, DOCS.md) and check each entry when the prose-health audit explicitly requires raw artifact prose.\n\n**Rule 1: Verbosity overrun**: approximate word count per entry. Compare against per-entry budgets. Entries exceeding their budget by 50%+ are findings.\n\n**Rule 2: Abstraction creep**: scan each entry for ≥1 concrete anchor (file path with extension, line number, commit hash with 7+ hex chars, metric value with unit, identifier such as function/class/variable name, direct quote in quotes attributed to a source). Entries with zero concrete anchors are findings.\n\n**Rule 3: Filler accumulation**: scan each entry against banned verbosity patterns. Flag entries containing: meta-commentary about writing, hedging qualifiers, redundant transitions, self-referential process narration, filler introductions, summary preambles, excessive justification.\n\n### Security hygiene\n\nLightweight regex-based scan for common security anti-patterns. This is a surface-level check, not a replacement for dedicated security analysis. Always recommend specialized tools for comprehensive coverage.\n\n**What to scan**:\n\n- **Hardcoded secrets**: API key patterns, password assignments, token strings in source, private keys in files\n- **Dangerous function calls**: \u0060eval()\u0060 on variables or user input, \u0060exec()\u0060 with string concatenation, subprocess/os.system with unsanitized input\n- **Basic injection patterns**: SQL string concatenation, unsanitized shell command construction\n\n**How to scan**: Use Grep with targeted patterns across the codebase. Focus on source files, not vendored dependencies, build artifacts, or lock files. Exclude \u0060.git/\u0060, \u0060node_modules/\u0060, \u0060vendor/\u0060, \u0060__pycache__/\u0060, and similar directories.\n\n**Severity assignment**:\n\n- Hardcoded secrets: warning (SF2, confidence 75-90)\n- Dangerous function calls: warning (SF2) or critical (SF1) depending on user input flow\n- Injection patterns: warning (SF2, confidence 60-80)\n\n**Scope limitation notice**: every security hygiene finding MUST include a footer recommending dedicated security tools for comprehensive analysis.\n\n---\n\n## Step 4: Distill\n\nAfter all agents complete:\n\n1. **Filter**: discard findings below 50 confidence. Mark 50-69 as \"info\" (SF3) regardless of apparent severity.\n2. **Deduplicate**: merge by preference: (1) fullest context, (2) most evidence-rich dimension, (3) most recent. Preserve complementary evidence from discarded findings.\n3. **Cross-reference** against DECISIONS.md and TODO.md using \u0060agentera decisions --format json\u0060 for normal decision context:\n   - Matches known decision → discard or downgrade to info (SF3)\n   - Matches known issue → \"already tracked\", skip\n   - Genuinely new → include at full severity\n4. **Grade** each dimension:\n   - **A**: No critical/warning findings. **B**: No critical, some warnings.\n   - **C**: 1-2 critical or many warnings. **D**: Multiple critical.\n   - **F**: Pervasive critical findings.\n5. **Trajectory**: compare to prior HEALTH.md: improved (VT12), degraded (VT13), stable dimensions. Calculate overall trajectory.\n\n---\n\n## Step 5: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns table).\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\"Tightening this up...\" · \"Cutting the filler first...\" · \"One more pass...\"\n\n---\n\n## Step 6: Report\n\nAssess each dimension in your response. Write ONLY grade, trajectory marker, and finding summary per dimension to HEALTH.md. No reasoning in the artifact; the conversation preserves analysis, the artifact preserves conclusions.\n\nOutput constraint per contract token budgets. Letter grade + ≤3 sentences justification per dimension.\n\nWhen updating existing HEALTH.md entries (e.g., updating patterns observed), edit the specific YAML entry rather than rewriting unrelated history. Append new audit entries.\n\nWrite the audit results to \u0060HEALTH.md\u0060 using its resolved YAML path (append new audit, keep prior audits for trajectory history) and present to the user.\n\nAfter writing a new audit entry to HEALTH.md, apply the schema COMPACTION rules before writing if thresholds are exceeded: keep 10 full audits, keep up to 40 one-line archive entries, and drop beyond 50 total.\n\nArtifact writing follows contract Artifact Writing Conventions: banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\n### Report structure\n\n\u0060\u0060\u0060markdown\n## Audit N · YYYY-MM-DD\n\n**Dimensions assessed**: [list]\n**Findings**: X critical, Y warnings, Z info (N filtered by confidence)\n**Overall trajectory**: ⮉ improving | stable | ⮋ degrading vs Audit N-1\n**Grades**: Architecture [B] | Patterns [A] | Coupling [C] | Complexity [B] | Tests [D] | Deps [A] | Security [A]\n\n### [Dimension Name]: [Grade]\n\n#### ⇶ [Finding title], critical (confidence: N/100)\n#### ⇉ [Finding title], warning (confidence: N/100)\n#### ⇢ [Finding title], info (confidence: N/100)\n- **Location**: \u0060file:line\u0060 (or module/package)\n- **Evidence**: [quoted code or structural observation]\n- **Impact**: [what breaks, degrades, or risks]\n- **Suggested action**: [specific fix, investigation, or refactor]\n\n[Repeat for each finding, ordered by severity then confidence]\n\n### Trends vs Audit N-1\n- **Improved**: [what got better and why]\n- **Degraded**: [what got worse and why]\n- **New findings**: [issues not present in prior audit]\n- **Resolved**: [prior findings no longer present]\n\n### Patterns Observed\n[De facto architecture patterns extracted, the \"what IS\" independent of what's stated.]\n- Module structure: [how code is organized]\n- Error handling: [predominant pattern]\n- Testing approach: [how tests are structured]\n- Dependency patterns: [how deps are managed]\n\u0060\u0060\u0060\n\n---\n\n## Step 7: Connect\n\nFeed actionable findings into the suite:\n\n1. **TODO.md**: for each critical finding not already tracked, offer to add under the appropriate severity section.\n   Severity mapping (protocol: SM1-SM3): critical (SF1) → \u0060## ⇶ Critical\u0060 (SI1), warning (SF2) → \u0060## ⇉ Degraded\u0060 (SI2), info (SF3) → \u0060## ⇢ Annoying\u0060 (SI4). Each entry is a checkbox line: \u0060- [ ] [finding description]\u0060. Get user confirmation before writing.\n   Output constraint per contract token budgets.\n2. **VISION.md**: if architecture has intentionally evolved past stated architecture, suggest updating via ❈ discuss.\n3. **Present findings** and ask if the user wants to: file to TODO.md, deliberate via ❈ discuss, deep-dive on a dimension, or investigate a specific finding.\n\n---\n\n## Safety rails\n\n<critical>\n\n- NEVER modify code. Audit audits; other capabilities fix.\n- NEVER file issues to TODO.md without explicit user confirmation.\n- NEVER present speculative findings (confidence < 50) as definitive problems.\n- NEVER ignore DECISIONS.md context. If a finding contradicts a deliberate decision,\n  it is not a finding but an implementation of that decision. Discard or downgrade.\n- NEVER report known issues already tracked in TODO.md as new findings.\n- NEVER flag subjective style preferences as findings unless they violate stated principles\n  in VISION.md, CLAUDE.md, or the decision profile.\n- NEVER run destructive commands or install packages. Read-only assessment.\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─── ⛶ audit · status ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): All selected audit dimensions were assessed, findings were synthesized, grades were assigned, HEALTH.md was updated, and the user was presented with actionable results.\n- **flagged** (EX2): The audit completed but with notable caveats: one or more dimensions had to be skipped due to missing tooling, confidence was too low to grade a dimension reliably, or critical findings were discovered that require urgent attention beyond the audit scope.\n- **stuck** (EX3): Cannot complete the audit because the project is inaccessible, required language tooling is unavailable and manual analysis is not feasible, or filing findings to TODO.md was declined by the user and the results cannot be safely surfaced any other way.\n- **waiting** (EX4): The audit target is ambiguous: no project was identified, the codebase is too incomplete to assess meaningfully, or the user's request specifies dimensions that cannot be evaluated without additional information.\n\n---\n\n## Cross-capability integration\n\nAudit is part of a twelve-capability suite. It is the feedback loop, the capability that tells build whether its work is making things better.\n\n### Audit feeds ⧉ build\n\nCritical and warning findings filed to TODO.md become candidates for build's work selection. The severity mapping ensures structural problems compete fairly with feature work. The \"Patterns Observed\" section helps build understand the codebase's de facto architecture when planning changes.\n\n### Audit feeds ❈ discuss\n\nWhen the audit reveals an architecture mismatch, suggest ❈ discuss before fixes begin.\n\nUse it when code has moved past stated architecture or competing patterns need a decision.\n\n### Audit feeds ≡ plan\n\nWhen the audit reveals multiple related structural issues, suggest ≡ plan to create a remediation plan. The plan's acceptance criteria give audit concrete targets to verify in the next audit.\n\n### Audit feeds ⎘ optimize\n\nWhen a dimension grade is poor and the improvement is measurable (test coverage, dependency count, complexity score), the finding can become an optimization objective. Suggest ⎘ optimize when the metric and direction are clear.\n\n### Audit reads ⧉ build output\n\nPROGRESS.md tells audit what was built recently. Recent changes are higher-priority audit targets because they're the most likely source of regressions or pattern breaks. Cycle count since last audit signals when a health check is overdue.\n\n### Audit reads ❈ discuss output\n\nDECISIONS.md explains why things are the way they are. Findings that contradict deliberate decisions are not findings. This prevents audit from flagging intentional tradeoffs as problems.\n\n### Audit reads ◰ design output\n\nDESIGN.md provides visual identity constraints that audit can audit for consistency, checking whether the codebase respects the declared design tokens and patterns.\n\n### Audit is informed by ♾ profile\n\nThe decision profile calibrates what \"healthy\" means for this user. A user who values simplicity over flexibility will have different complexity thresholds than one who values extensibility. High-confidence quality preferences from the profile weight the grading.\n\n---\n\n## Getting started\n\n### First audit\n\n1. \u0060/agentera audit\u0060: runs a full audit across all applicable dimensions, bootstraps HEALTH.md\n2. Review findings, file critical ones to TODO.md\n3. \u0060/agentera build\u0060: next cycle picks up the filed issues and starts fixing\n\n### Periodic health checks\n\nRun ⛶ audit every 5-10 build cycles, or when:\n\n- A major feature was added\n- Significant refactoring occurred\n- The codebase \"feels\" harder to work in\n- Before a major architectural decision (to understand current state)\n\nStatus mirrors this cadence through hybrid audit staleness: \u0060agentera prime\u0060 marks a health audit stale when days since the latest audit date reach \u0060AGENTERA_AUDIT_MAX_AGE_DAYS\u0060 (default 30) or progress cycles after that audit date reach \u0060AGENTERA_AUDIT_MAX_CYCLES\u0060 (default 10). Either axis exceeding its threshold is enough; when progress is absent, time-only evaluation still applies.\n\n### Targeted audits\n\n\u0060\u0060\u0060\n/agentera audit architecture coupling\n\u0060\u0060\u0060\n\nSpecify dimensions to narrow the audit scope. Useful after specific kinds of changes.\n\n### After an audit\n\n- **Good grades (A/B)**: Celebrate. Keep building.\n- **Mixed grades (C)**: File the critical findings, deliberate on the warnings.\n- **Poor grades (D/F)**: Consider pausing feature work. Use ❈ discuss to deliberate on priorities, then ⧉ build to fix the structural problems before building more.\n"`);
+// Markdown instructions served via agentera prime --context audit --format json
+export const instructions = JSON.parse(String.raw `"# AUDIT\n\n**Integrity Navigation: Systematic Pattern Evaluation, Knowledge Tracing. Examine, Report, Advise.**\n\nCodebase health audit: multi-dimensional structural quality evaluation with evidence-based findings, confidence scores, and trajectory tracking. The retrospective counterpart to build's forward motion: is the codebase getting better or just bigger? Each invocation = one audit. Findings feed build's work selection via TODO.md.\n\nGlyph: **⛶** (protocol ref: SG3). Used in the mandatory exit marker.\n\nLean on \u0060evidence_context.source_contract\u0060 from \u0060agentera prime --context audit --format json\u0060 for evaluation startup. Do not re-encode its machine-readable rules in prose.\n\n---\n\n## State artifacts\n\n| Artifact | Role | Path |\n|----------|------|------|\n| health | produces_and_consumes | \u0060.agentera/health.yaml\u0060 |\n| todo | produces_and_consumes | TODO.md |\n| decisions | consumes | \u0060.agentera/decisions.yaml\u0060 |\n| progress | consumes | \u0060.agentera/progress.yaml\u0060 |\n| plan | consumes | \u0060.agentera/plan.yaml\u0060 |\n| docs | consumes | \u0060.agentera/docs.yaml\u0060 |\n| vision | consumes (protected) | \u0060.agentera/vision.yaml\u0060 |\n| design | consumes (optional) | DESIGN.md |\n| profile | consumes | Profile state from \u0060evidence_context.residual_risks\u0060 |\n\n### health.yaml shape\n\n\u0060\u0060\u0060yaml\naudits:\n  - number: 1\n    date: YYYY-MM-DD\n    dimensions: [architecture_alignment, test_health]\n    findings_summary: \"X critical, Y warnings, Z info\"\n    overall: stable\n    dimension_grades:\n      - dimension: architecture_alignment\n        grade: B\n    findings:\n      - severity: degraded\n        title: Finding title\n        confidence: 80\n        location: file:line\n        evidence: What was observed.\n        impact: Why this matters.\n        suggested_action: Specific fix or investigation.\n    trends: What improved, degraded, or changed.\n    patterns_observed: De facto architecture patterns.\n\u0060\u0060\u0060\n\nEvery finding MUST include \u0060location\u0060, \u0060evidence\u0060, \u0060impact\u0060, \u0060suggested_action\u0060, and \u0060confidence\u0060. WARN and FAIL findings MUST carry a reproducible anchor: \u0060location: <file>:<line>\u0060 (or \u0060not-applicable: <reason>\u0060). WARN rows with file:line citations SHOULD include \u0060verify_command\u0060 — the exact \u0060grep\u0060 or \u0060git show\u0060 invocation that reproduces the evidence at the cited line. Prose-only evidence for WARN/FAIL findings is incomplete.\n\n### Evidence context startup\n\nStart with \u0060agentera prime --context audit --format json\u0060. Use the returned \u0060evidence_context\u0060 for prior audit findings, known issues, decision caveats, protected-state boundaries, version checks, progress verification, and residual risks. If \u0060evidence_context\u0060 is absent or caveated for a state family you need, run the listed \u0060fallback_commands\u0060 first. Raw artifact reads are last-resort diagnostics, not normal startup behavior. Preserve caveats — they calibrate confidence, not approval to refresh state, read vision, edit objective state, or contact remotes.\n\n---\n\n## Workflow phases\n\nLinear: orient, select, assess, distill, report, connect.\n\n### Step 1: Orient\n\nUse \u0060evidence_context\u0060 for prior audits, decisions, TODO, and progress. Then project discovery: map directory structure, read dependency manifests, README, AGENTS.md, identify language/stack/build commands, \u0060git log --oneline -20\u0060.\n\nDerive change magnitude: \u0060git log --stat\u0060 on commits since the last audit timestamp to estimate total change volume. If the audit timestamp is unavailable, skip; default depth applies.\n\nList key structural facts (module boundaries, dependency patterns, test coverage gaps) in your response. These survive context compaction.\n\n**Exit-early stop condition**: if \u0060git diff\u0060 since the last audit timestamp shows no file changes, report \u0060─── ⛶ audit · complete ───\u0060 with \"no changes since last audit\" and stop.\n\n### Step 2: Select dimensions\n\nChoose dimensions based on the codebase and user request. Not every dimension applies; a 200-line CLI does not need the same audit as a monorepo.\n\n#### Available dimensions\n\n| Dimension | What it evaluates | When to include |\n|-----------|-------------------|-----------------|\n| Architecture alignment | Does the code match stated architecture? Pattern mismatches, module boundary violations, layering breaks. | \u0060.agentera/vision.yaml\u0060 or README describes architecture |\n| Pattern consistency | Are patterns used consistently? Naming, error handling, structure, abstractions. | Any codebase with 5+ modules or files |\n| Coupling health | Hidden dependencies, circular imports, god modules, inappropriate intimacy. | Any codebase with multiple modules |\n| Complexity hotspots | Functions too long, deeply nested, high fan-out, accumulated conditionals. | Any codebase |\n| Test health | Coverage gaps, test quality, test-to-code ratio, behavior vs implementation testing. | Project has tests |\n| Dependency health | Outdated deps, security advisories, unused deps, dep sprawl, pinning discipline. | Project has external dependencies |\n| Version health | Unreleased significant changes: \u0060feat\u0060/\u0060fix\u0060 commits since last version bump. | \u0060.agentera/docs.yaml\u0060 has a \u0060versioning\u0060 convention block |\n| Artifact freshness | Are state artifacts current relative to plan activity or recent development? Detects artifacts that should have been updated but weren't. | Plan context available or progress has entries |\n| Prose health | Do artifact entries respect writing rules? Verbosity overruns, abstraction creep, filler. | Project has 3+ artifact files |\n| Security hygiene | Hardcoded secrets, dangerous calls, injection patterns. Lightweight regex scan. | Any codebase |\n\n#### Depth guidance\n\nWhen change magnitude was derived in Step 1, apply advisory depth scaling:\n\n- **Light changes** (roughly ≤5 files, ≤200 lines since last audit): prioritize dimensions most relevant to changed areas. Skip dimensions with no intersection.\n- **Standard changes** (default): assess all applicable dimensions at normal depth.\n- **Heavy changes** (roughly ≥20 files or architectural-scope commits): assess all applicable dimensions and increase evidence depth.\n\nThese thresholds are guidelines, not hard rules. A 6-file change touching a critical security module warrants thorough depth.\n\n**User-specified dimensions**: audit only those. **Full audit or unspecified**: auto-select all applicable. Report selections before proceeding.\n\n### Step 3: Assess\n\nFor each selected dimension, run analysis and produce structured findings. Every finding MUST include: specific file and line references, quoted code or structural observation, explanation of why it matters, and confidence score (0-100, protocol: CS1-CS5).\n\nFor parallel analysis, use subagents — one per dimension. Each agent receives the dimension definition, relevant context files, and instructions to return findings matching the health.yaml finding shape.\n\n#### Version health\n\nOnly run if \u0060.agentera/docs.yaml\u0060 contains a \u0060versioning\u0060 convention block. Skip entirely if absent.\n\n- Read the \u0060versioning\u0060 convention to identify version file(s) and bump trigger rules\n- Run \u0060git log --oneline\u0060 to find \u0060feat\u0060 and \u0060fix\u0060 commits since the last modification date of the version file(s)\n- Count unbumped \u0060feat\u0060/\u0060fix\u0060 commits and note the age of the oldest one\n- Severity: warning (SF2) if 1-4 unbumped commits or age ≤ 7 days; critical (SF1) if 5+ unbumped commits or age > 7 days\n- If no \u0060feat\u0060/\u0060fix\u0060 commits since the last bump, this dimension is healthy with no finding\n\n#### Artifact freshness\n\nEvaluates whether state artifacts are current relative to plan activity or recent development.\n\n**With plan context** (\u0060.agentera/plan.yaml\u0060 has a created date and task history):\n\n- Read the plan's \u0060Created\u0060 date from its metadata\n- Identify dispatched capabilities by scanning task entries and progress cycle logs\n- For each dispatched capability, look up its expected artifacts in the staleness convention\n- Check each expected artifact's last modification: \u0060git log -1 --format=%aI -- <path>\u0060\n- An artifact is **stale** if its last modification predates the plan's creation date AND the owning capability was dispatched at least once during the plan\n- Severity: warning (SF2, confidence 70+). Plan-relative staleness carries causal evidence.\n- Artifacts that a capability reads but does not produce are not staleness candidates\n\n**Without plan context**:\n\n- Fall back to progress recency: an artifact is potentially stale if not modified since the most recent progress cycle entry date\n- If progress has no entries (fresh project), no staleness check applies\n- Severity: info (SF3, confidence 50-60). Advisory, not authoritative.\n\nStale artifact findings are reported like any other dimension finding but noted as context for the next plan cycle, not as blocking errors.\n\n#### Prose health\n\nEvaluate artifact prose quality against the three Self-Audit Protocol rules:\n\n- **Rule 1: Verbosity overrun** — approximate word count per entry. Entries exceeding their budget by 50%+ are findings.\n- **Rule 2: Abstraction creep** — scan each entry for ≥1 concrete anchor (file path, line number, commit hash 7+ hex chars, metric value with unit, identifier, direct quote). Entries with zero concrete anchors are findings.\n- **Rule 3: Filler accumulation** — flag entries with: meta-commentary about writing, hedging qualifiers, redundant transitions, self-referential process narration, filler introductions, summary preambles, excessive justification.\n\nUse \u0060agentera state decisions --format json\u0060 for decision artifact prose context; preserve returned caveats. Read all project artifacts (\u0060.agentera/progress.yaml\u0060, \u0060.agentera/decisions.yaml\u0060, \u0060.agentera/plan.yaml\u0060, \u0060.agentera/health.yaml\u0060, TODO.md, CHANGELOG.md, \u0060.agentera/vision.yaml\u0060, DESIGN.md, \u0060.agentera/docs.yaml\u0060) when this dimension requires raw artifact prose inspection.\n\n#### Security hygiene\n\nLightweight regex-based scan for common security anti-patterns. Surface-level check, not a replacement for dedicated security analysis.\n\nScan for hardcoded secrets (API key patterns, token strings, private keys), dangerous function calls (\u0060eval()\u0060 on variables, \u0060exec()\u0060 with string concatenation, subprocess with unsanitized input), and injection patterns (SQL string concatenation, unsanitized shell construction). Use Grep across source files; exclude \u0060.git/\u0060, \u0060node_modules/\u0060, \u0060vendor/\u0060, \u0060__pycache__/\u0060.\n\n- Hardcoded secrets: warning (SF2, confidence 75-90)\n- Dangerous function calls: warning (SF2) or critical (SF1) depending on user input flow\n- Injection patterns: warning (SF2, confidence 60-80)\n\nEvery security hygiene finding MUST include a footer recommending dedicated security tools.\n\n### Step 4: Distill\n\nAfter analysis completes:\n\n1. **Filter**: discard findings below 50 confidence. Mark 50-69 as \"info\" (SF3) regardless of apparent severity.\n2. **Deduplicate**: merge by preference: (1) fullest context, (2) most evidence-rich dimension, (3) most recent. Preserve complementary evidence from discarded findings.\n3. **Cross-reference** against \u0060.agentera/decisions.yaml\u0060 and TODO.md (via \u0060agentera state decisions --format json\u0060):\n   - Matches known decision → discard or downgrade to info (SF3)\n   - Matches known issue → \"already tracked\", skip\n   - Genuinely new → include at full severity\n4. **Grade** each dimension: **A** (no critical/warning), **B** (no critical, some warnings), **C** (1-2 critical or many warnings), **D** (multiple critical), **F** (pervasive critical).\n5. **Trajectory**: compare to prior audit — improving (VT12), degrading (VT13), stable. Calculate overall trajectory.\n\n### Step 5: Report\n\nRun \u0060agentera check lint --artifact health\u0060 on the draft entry before writing. Max 3 revision attempts. Flag with \u0060[post-audit-flagged]\u0060 if still failing.\n\nWrite the audit entry with \u0060agentera state health append --input PATH --format json\u0060 (or \u0060--input -\u0060 for YAML/JSON stdin). The writer assigns the audit number, validates the candidate and final compacted bytes, and applies shared retention before publishing. No reasoning in the artifact; the conversation preserves analysis, the artifact preserves conclusions.\n\nWhen updating existing entries, edit the specific YAML entry rather than rewriting unrelated history.\n\nCompaction is writer-owned; do not hand-compact the health artifact before or after the command.\n\n#### Report structure\n\n\u0060\u0060\u0060markdown\n## Audit N · YYYY-MM-DD\n\n**Dimensions assessed**: [list]\n**Findings**: X critical, Y warnings, Z info (N filtered by confidence)\n**Overall trajectory**: ⮉ improving | stable | ⮋ degrading vs Audit N-1\n**Grades**: Architecture [B] | Patterns [A] | Coupling [C] | Complexity [B] | Tests [D] | Deps [A] | Security [A]\n\n### [Dimension Name]: [Grade]\n\n#### ⇶ [Finding title], critical (confidence: N/100)\n#### ⇉ [Finding title], warning (confidence: N/100)\n#### ⇢ [Finding title], info (confidence: N/100)\n- **Location**: \u0060file:line\u0060 (or module/package)\n- **Evidence**: [quoted code or structural observation]\n- **Impact**: [what breaks, degrades, or risks]\n- **Suggested action**: [specific fix, investigation, or refactor]\n\n### Trends vs Audit N-1\n- **Improved**: [what got better and why]\n- **Degraded**: [what got worse and why]\n- **New findings**: [issues not present in prior audit]\n- **Resolved**: [prior findings no longer present]\n\n### Patterns Observed\n[De facto architecture patterns extracted — the \"what IS\" independent of what's stated.]\n\u0060\u0060\u0060\n\n### Step 6: Connect\n\nFeed actionable findings into the suite:\n\n1. **TODO.md**: for each critical finding not already tracked, offer to add under the appropriate severity section. Severity mapping (protocol: SM1-SM3): critical (SF1) → \u0060## ⇶ Critical\u0060 (SI1), warning (SF2) → \u0060## ⇉ Degraded\u0060 (SI2), info (SF3) → \u0060## ⇢ Annoying\u0060 (SI4). Each entry: \u0060- [ ] [finding description]\u0060. Get user confirmation before writing.\n2. **\u0060.agentera/vision.yaml\u0060**: if architecture has intentionally evolved past stated architecture, suggest updating via discuss.\n3. **Present findings** and ask if the user wants to: file to TODO.md, deliberate via discuss, deep-dive on a dimension, or investigate a specific finding.\n\n---\n\n## Safety rails\n\n<critical>\n\n- MUST NOT modify source code. Audit audits; other capabilities fix.\n- MUST NOT file findings to TODO.md without explicit user confirmation.\n- MUST NOT present speculative findings (confidence < 50) as definitive problems.\n- MUST NOT flag findings that contradict deliberate decisions documented in \u0060.agentera/decisions.yaml\u0060. A deliberate decision is an implementation of intent, not a finding. Discard or downgrade.\n- MUST NOT report issues already tracked in TODO.md as new findings.\n- MUST NOT flag subjective style preferences as findings unless they violate stated principles in \u0060.agentera/vision.yaml\u0060, AGENTS.md, or the decision profile.\n- MUST NOT run destructive commands or install packages. Read-only assessment.\n- MUST NOT mark, infer, or user-confirm decision satisfaction — only the user confirms final satisfaction.\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─── ⛶ audit · <status> ───\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 bullet details below the summary.\n\n- **complete** (EX1): All selected dimensions assessed, findings synthesized, grades assigned, \u0060health\u0060 artifact updated, actionable results presented.\n- **flagged** (EX2): Completed with notable caveats — dimensions skipped due to missing tooling, confidence too low to grade reliably, or critical findings require urgent attention beyond audit scope.\n- **stuck** (EX3): Cannot complete — project inaccessible, required language tooling unavailable and manual analysis not feasible, or filing to TODO.md declined with no safe way to surface results.\n- **waiting** (EX4): The audit target is ambiguous — no project identified, codebase too incomplete to assess, or dimensions requested cannot be evaluated without additional information.\n\n---\n\n## Cross-capability integration\n\nAudit is the feedback loop: it tells build whether its work is making things better.\n\n### Feeds\n\n- **⧉ build**: Critical and warning findings filed to TODO.md become candidates for build's work selection. \"Patterns Observed\" helps build understand the codebase's de facto architecture when planning changes.\n- **❈ discuss**: When an architecture mismatch is found, suggest discuss before fixes begin.\n- **≡ plan**: When multiple related structural issues are found, suggest plan for a remediation plan.\n- **⎘ optimize**: When a dimension grade is poor and the improvement is measurable (test coverage, dependency count, complexity score), suggest optimize.\n\n### Reads\n\n- **⧉ build output**: \u0060.agentera/progress.yaml\u0060 tells audit what was built recently. Recent changes are higher-priority audit targets.\n- **❈ discuss output**: \u0060.agentera/decisions.yaml\u0060 explains why things are the way they are. Findings that contradict deliberate decisions are not findings.\n- **◰ design output**: DESIGN.md provides identity constraints that audit can check for consistency.\n\n### Informed by\n\n- **♾ profile**: The decision profile calibrates what \"healthy\" means for this user. High-confidence quality preferences weight the grading.\n\n### Getting started\n\n**First audit**: \u0060/agentera audit\u0060 runs a full audit across all applicable dimensions, bootstraps \u0060health\u0060 artifact. Review findings, file critical ones to TODO.md, then \u0060/agentera build\u0060 picks them up.\n\n**Periodic health checks**: run audit every 5-10 build cycles, or when a major feature was added, significant refactoring occurred, the codebase feels harder to work in, or before a major architectural decision.\n\nStaleness detection: \u0060agentera prime\u0060 marks a health audit stale when \u0060AGENTERA_AUDIT_MAX_AGE_DAYS\u0060 (default 30) or \u0060AGENTERA_AUDIT_MAX_CYCLES\u0060 (default 10) since the last audit is exceeded. Either axis exceeding its threshold triggers staleness; when progress is absent, time-only evaluation still applies.\n\n**Targeted audits**: specify dimensions to narrow scope — \u0060/agentera audit architecture coupling\u0060.\n\n**After an audit**: Good grades (A/B) — keep building. Mixed (C) — file criticals, deliberate on warnings. Poor (D/F) — consider pausing feature work; use discuss for priorities, then build for structural fixes.\n\n### Orchestrate evaluation\n\nWARN and FAIL findings used by orchestrate evaluation reports MUST carry \u0060citation: <file>:<line>\u0060 per row (schema: \u0060agentera.inspekteraEvaluationReport.v1\u0060 in \u0060references/cli/capability-instruction-contract.yaml#evaluator_handoff\u0060)."`);
 export default instructions;
 //# sourceMappingURL=instructions.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/audit/instructions.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,2tgCAA2tgC,CAAC,CAAC;AACtxgC,eAAe,YAAY,CAAC"}
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/audit/instructions.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,uwmBAAuwmB,CAAC,CAAC;AACl0mB,eAAe,YAAY,CAAC"}

package/dist/capabilities/build/instructions.js

@@ -1,6 +1,5 @@
-// Source: skills/agentera/capabilities/build/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 `"# BUILD\n\n**Relentless Execution: Autonomous Loops Iterating Software. Evolve, Refine, Adapt**\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. \\u0060/loop\\u0060 handles recurrence.\\n\\n### Cycle boundary\\n\\nAfter completing one cycle (orient through log, exit signal reported), **stop**. Do not auto-continue to the next plan task. The next cycle starts when the user invokes it explicitly — via \\u0060/loop\\u0060, a new \\u0060build\\u0060 session, or by switching to ⎈ 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 \\u201cone task, then stop\\u201d and ⎈ orchestrate as \\u201call tasks autonomously.\\u201d\\n\\n---\\n\\n## Visual identity\n\nGlyph: **⧉** (protocol ref: SG2). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nFour artifacts, bootstrapped if absent. TODO.md and CHANGELOG.md stay at project root; canonical VISION.md and PROGRESS.md are stored as \u0060.agentera/vision.yaml\u0060 and \u0060.agentera/progress.yaml\u0060 unless mapped otherwise.\n\n| File | Purpose | Bootstrap |\n|------|---------|-----------|\n| \u0060VISION.md\u0060 | Canonical vision artifact. North star, direction, principles, aspirations. | Via inline brainstorm session (see below), written to \u0060.agentera/vision.yaml\u0060 by default. |\n| \u0060TODO.md\u0060 | Tech debt, bugs, discrepancies. | \u0060# TODO\\n\\n## ⇶ Critical\\n\\n## ⇉ Degraded\\n\\n## → Normal\\n\\n## ⇢ Annoying\\n\\n## Resolved\\n\u0060 |\n| \u0060CHANGELOG.md\u0060 | Public change history. | \u0060# Changelog\\n\\n## [Unreleased]\\n\u0060 |\n| \u0060PROGRESS.md\u0060 | Canonical progress artifact. Operational cycle log. | First cycle entry in \u0060.agentera/progress.yaml\u0060 by default. |\n\nUse \u0060agentera schema --format json\u0060 and its \u0060artifact_schemas\u0060 entries for \u0060vision\u0060 and \u0060progress\u0060 to locate the active installed schemas; do not search Agentera directories manually. Top-level \u0060agentera describe\u0060 is a migration alias.\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, check if \u0060.agentera/docs.yaml\u0060 exists. If it has an Artifact Mapping section, use the path specified for each canonical filename (VISION.md, TODO.md, .agentera/progress.yaml, etc.). If \u0060.agentera/docs.yaml\u0060 doesn't exist or has no mapping for a given artifact, use the default layout: TODO.md, CHANGELOG.md, and DESIGN.md at the project root; canonical VISION.md at \u0060.agentera/vision.yaml\u0060; other agent-facing artifacts at \u0060.agentera/*.yaml\u0060.\n\n### Contract values\n\nContract values are inlined where referenced. Visual tokens from protocol: severity arrows VT5-VT8 (⇶/⇉/→/⇢), status tokens VT1-VT4 (■/▣/□/▨), list item VT15 (▸), inline separator VT16 (·), section divider VT14, flow/target VT17 (→). Skill glyphs SG1-SG12 for cross-capability references. Exit signals EX1-EX4 for the exit marker. Severity issue levels SI1-SI4 for TODO classification. Decision labels DL1-DL3 for DECISIONS.md entries. Confidence scale CS1-CS5 with thresholds for profile consumption.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference for ambiguous cases or cross-checking.\n\n### vision.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. A constitution, not a backlog.\n\n\u0060\u0060\u0060yaml\nproject_name: Project Name\nnorth_star: The dream. What this software makes possible.\npersonas:\n  - name: Specific persona\n    description: Their day, frustrations, and workflow.\nprinciples:\n  - name: Principle name\n    description: What it means and what it resists.\ndirection: Where this project is heading.\nidentity:\n  personality: Product personality.\n  voice: Communication style.\n  emotional_register: How it should feel to use.\n  naming: Naming conventions.\ntension: The hardest strategic tension.\n\u0060\u0060\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 → Added, \u0060refactor/chore\u0060 → Changed, \u0060fix\u0060 → Fixed. On version bumps, promote the Unreleased section to a versioned heading.\n\n---\n\n## Brainstorm: bootstrapping or refining the vision artifact\n\nThis runs in two situations:\n\n1. **The vision artifact doesn't exist**: the first time build runs on a project\n2. **User explicitly asks** to refine the vision\n\nIn all other cases, skip straight to the cycle.\n\nThe sharp colleague, here to build. Brief, focused conversation. One question at a time. Push for ambition.\n\n1. **Understand the dream**: \"Not what the software does, but what does it make possible?\"\n2. **Find the people**: \"Who reaches for this? Describe a person: their day, their frustrations.\"\n3. **Find the principles**: \"What principles guide every decision?\" If a decision profile exists, propose principles from it.\n4. **Set the direction**: \"Where is this heading? Not features, but capabilities.\"\n5. **Write the vision artifact**: synthesize into an aspirational north star. Present for approval.\n\nArtifact writing follows contract Section 24 conventions: banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\n---\n\n## The cycle\n\nSkill introduction: \u0060─── ⧉ build · cycle N ───\u0060\n\nStep markers: display \u0060── step N/9: verb\u0060 before each step.\nSteps: orient, select, research, plan, spawn, verify, commit, audit, log.\n\n### Step 1: Orient\n\nStart from the supported 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,\nuse \u0060execution_context\u0060 and included \u0060capability_context.state\u0060 as normal startup context. Do\nnot read raw PLAN, PROGRESS, TODO, DOCS, HEALTH, DECISIONS, CHANGELOG, VISION,\nPROFILE, or DESIGN artifacts just to re-check selected work, acceptance\ncriteria, constraints, verification expectations, artifact update requirements,\nprogress logging requirements, changelog boundary, or scope caveats.\n\nIf \u0060execution_context\u0060 is incomplete or caveated, preserve every caveat in the\ncycle report and run the listed \u0060execution_context.fallback_commands\u0060 before any\nlast-resort raw artifact diagnostic. Raw artifact reads are last-resort\ndiagnostics, not normal Build startup behavior.\n\nFor progress fallback specifically, use \u0060npx -y agentera state progress --format json\u0060\nor the installed app equivalent from the returned fallback command; the routine\nprogress command owns startup progress state.\n\n### Decision satisfaction authority\n\nWhen a cycle touches decision satisfaction, agents may mark provisional\nsatisfaction with evidence only. Build must not mark or imply\nuser-confirmed satisfaction; only the user confirms final satisfaction. If\ndecisions are compacted, missing satisfaction state, open, provisional, or\nreview-needed, preserve the caveat and review pressure in the cycle report\ninstead of reconstructing hidden outcomes or claiming automation proved intent.\n\n1. **execution_context.work_selection**: selected task or no-plan/completed-plan mode\n2. **execution_context.acceptance_criteria**: exact criteria for this cycle\n3. **execution_context.constraints**: plan constraints and protected-action boundaries\n4. **execution_context.verification_expectations**: expected validation and latest progress evidence\n5. **execution_context.artifact_update_requirements**: plan, TODO, changelog, and progress update obligations\n6. **execution_context.changelog_boundary**: current public-history boundary or fallback\n7. **execution_context.scope_boundary**: artifact-family scope and conservative source-file scope\n8. **source_contract.capability_context**: missing state families and CLI fallback commands\n9. **profile summary**: use \u0060status.profile\u0060; stale or missing profile is a caveat, not approval to refresh profile state.\n\n10. **Project discovery** (cycle 1 or when unfamiliar):\n    - Map the directory structure\n    - Read dependency manifests\n    - Read README.md, CLAUDE.md, AGENTS.md if they exist\n    - Identify build/test/lint commands\n    - Read key source files to understand architecture\n\n11. \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 PLAN.md 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 a successfully completed plan and must remain visible for replanning or follow-up. This stop condition does NOT apply in vision-driven mode.\n\nSweep checklist:\n\n1. **PROGRESS.md aggregate cycle entry**: insert a newest-first cycle entry summarizing 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 Resolved.\n4. **HEALTH.md cross-reference**: mention any resolved findings.\n\nAfter the sweep, archive PLAN.md to \u0060.agentera/archive/PLAN-{date}-{slug}.yaml\u0060, preserve lineage/evidence in the archive or next plan's \u0060previous_plan_archived\u0060, remove the active \u0060.agentera/plan.yaml\u0060, and report exit signal \u0060complete: plan finished\u0060.\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 doesn't block progress.\n\n**Building toward vision:** Read codebase + VISION.md, 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 ⎘ optimize for measurable metrics and\nwait 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 ≤80 words.\n\n**Decision gate**: After selecting work, use \u0060agentera decisions --format json\u0060 and check whether any \u0060exploratory\u0060 (DL3) entries in DECISIONS.md 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 instead of raw-reading missing historical context. If an exploratory decision is found: flag the uncertain foundation, suggest ❈ discuss to firm up the decision, and wait for confirmation before invoking it. In autonomous mode, proceed with the work but log the risk instead of silently delegating to discuss.\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. If the docs-first workflow should update intent docs before tests and code, include that.\n\nKeep small enough for one agent session. Too large? Split and save the rest.\n\n### Step 5: Dispatch\n\n**Pre-spawn Git commit**: before creating the worktree, commit any pending artifact changes so the subagent branches from current state.\n\n1. Run \u0060git status --porcelain\u0060. If empty, skip to spawn.\n2. Stage only the artifact files this session wrote.\n3. Commit with \u0060chore(build): checkpoint before worktree dispatch\u0060.\n4. If pre-commit hooks reject: fix, re-stage, retry. If retry fails, abort spawn.\n\n**Stale-base awareness**: Before spawning, run \u0060git rev-list --count origin/main..HEAD\u0060. If count > 0, do not merge the worktree branch. Fetch the sub-agent's diff and apply it to the main checkout.\n\nRuntime subagent mechanisms:\n\n| Runtime | Substrate | Limitation |\n|---------|-----------|------------|\n| Claude Code | Task tool with worktree-aware prompt | Native in-session spawn. |\n| OpenCode | \u0060@<capability>\u0060 descriptors from \u0060~/.config/opencode/agents/*.md\u0060 or a host Task subagent | Same working tree unless this step explicitly creates and targets a manual git worktree. |\n| Codex CLI | \u0060~/.codex/agents/*.toml\u0060 descriptors plus \u0060[agents]\u0060 limits | Agentera setup installs descriptor files; do not write legacy \u0060[agents.<name>]\u0060 config blocks. |\n| Copilot CLI | User-driven \u0060/fleet\u0060 or equivalent host action | No guaranteed programmatic in-session spawn. |\n\nNever spawn workers by running unsupported capability-name CLI commands such as \u0060agentera build\u0060; use the runtime-native subagent surface with the implementation prompt below.\n\nSpawn an implementation sub-agent in a worktree with:\n\n- The plan from step 4\n- Relevant context files\n- Clear constraint: implement the plan and nothing else\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**: After implementation:\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: \u0060npx -y agentera 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\nOnce verified, commit 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. Never commit partial or broken work. Never push to remote.\n\nIf the current task is a version bump: read DOCS.md for the \u0060versioning\u0060 section. Update every file in \u0060version_files\u0060.\n\n### Step 8: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation.\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\n### Step 9: Log\n\n**Dual-write**: build maintains the resolved PROGRESS.md YAML artifact and root CHANGELOG.md.\n\n- **TODO.md**: add newly discovered open issues in severity bands with \u0060- [ ]\u0060. Move completed work to \u0060## ✓ Resolved\u0060 as \u0060- [x]\u0060 with a resolution summary; never leave checked or strikethrough items in severity bands. The validate-artifact hook auto-compacts Resolved when the 10/40/50 cap is exceeded.\n- **PROGRESS.md**: insert the newest cycle entry before older active cycles. The \u0060verified\u0060 field is mandatory.\n- **CHANGELOG.md**: append a one-line entry under \u0060## [Unreleased]\u0060.\n\nAfter writing PROGRESS.md, apply the schema COMPACTION rules if thresholds are exceeded: keep 10 full entries, keep up to 40 one-line archive entries, and drop beyond 50 total. TODO.md Resolved compaction follows the same 10/40/50 cap via the validate-artifact hook or \u0060agentera check compact --mode fix\u0060.\n\nArtifact writing follows contract Section 24 conventions.\n\nThen stop. One cycle complete.\n\n---\n\n## Safety rails\n\n<critical>\n\n- NEVER push to any remote. Local commits only.\n- NEVER bypass the project's test/lint/build suite.\n- NEVER modify git config or skip git hooks.\n- NEVER force push, amend published commits, or run destructive git operations.\n- NEVER add placeholder data or functionality.\n- NEVER modify files outside the project directory.\n- NEVER modify the vision artifact during a cycle. Only touch it during a brainstorm.\n- One cycle per invocation. Do 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.md\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─── ⧉ build · <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): 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 brainstorm 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.md. 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\\n**Cycle boundary is hard.** After reporting an exit signal, the cycle is over. Do not begin a new cycle, pick the next plan task, or continue execution regardless of proactiveness guidance, compaction-continue prompts, or remaining plan tasks. Only \\u0060/loop\\u0060, an explicit user request, or ⎈ orchestrate starts the next cycle.\n\n---\n\n## Cross-capability integration\n\nBuild is part of a twelve-capability suite.\n\n### Delegates to ⛥ vision\n\nWhen vision is installed and the vision artifact doesn't exist, suggest ⛥ vision for deep vision creation. If vision is NOT installed, the built-in brainstorm works as a standalone fallback.\n\n### Delegates to ⎘ optimize\n\nWhen picked work is optimization-shaped (improving a measurable metric), delegate to optimize.\n\n### Uses ⬚ research\n\nIn Step 3 (Seek inspiration), search for external approaches. For deeper analysis, use \u0060/agentera research <url>\u0060.\n\n### Reads ♾ profile output\n\nEvery cycle runs the effective profile script. Confidence thresholds (CS1-CS5) determine which entries are strong constraints vs suggestions.\n\n### Uses ❈ discuss for complex decisions\n\nWhen the brainstorm or work selection surfaces a decision too complex for inline resolution, suggest ❈ discuss.\n\n### Consumes ≡ plan plans\n\nWhen PLAN.md 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 PLAN.md before removing active state, and preserve lineage/evidence.\n\n### Reads ▤ document output\n\nDOCS.md provides artifact path resolution. In the docs-first workflow, document writes intent docs that feed plan, which feeds build.\n\n### Reads ◰ design output\n\nDESIGN.md provides visual identity context respected when building user-facing features.\n\n### Audited by ⛶ audit\n\nHEALTH.md findings become candidates for work selection. Run ⛶ audit every 5-10 cycles.\n"`);
+// 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 --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

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/build/instructions.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,+krBAA+krB,CAAC,CAAC;AAC1orB,eAAe,YAAY,CAAC"}
+{"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,25gBAA25gB,CAAC,CAAC;AACt9gB,eAAe,YAAY,CAAC"}

package/dist/capabilities/design/instructions.js

@@ -1,5 +1,5 @@
-// Source: D65 capability instruction module (design)
-// Markdown body embedded as JSON for prime --context and eval surfaces.
-export const instructions = JSON.parse(String.raw `"# DESIGN\n\n**Visual Identity: Systematic Unified Aesthetic Language. Render, Establish, Articulate.**\n\nThe 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.\n\nThree modes: **create**, **refine**, **audit**.\n\n---\n\n## Visual identity\n\nGlyph: **\u25f0** (protocol ref: SG11). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOne file in \u0060.agentera/\u0060.\n\n| Artifact | Purpose | Bootstrap |\n|----------|---------|-----------|\n| \u0060DESIGN.md\u0060 | Visual identity. Colors, typography, spacing, constraints, components, themes. An agent-readable design system. | Created via deep design conversation. |\n\nUse this prose plus \u0060agentera describe --format json\u0060 and its \u0060artifact_schemas\u0060 entry for \u0060design\u0060 as the active design artifact specification; do not search Agentera directories manually. The design schema covers \u0060<!-- design:X -->\u0060 marker syntax, standard sections, YAML token block format, and naming conventions.\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, check if \u0060.agentera/docs.yaml\u0060 exists. If it has an Artifact Mapping section, use the path specified for each canonical filename (.agentera/design.yaml, etc.). If \u0060.agentera/docs.yaml\u0060 doesn't exist or has no mapping for a given artifact, use the default layout: TODO.md, CHANGELOG.md, and DESIGN.md at the project root; canonical VISION.md at \u0060.agentera/vision.yaml\u0060; other agent-facing artifacts at \u0060.agentera/*.yaml\u0060. This applies to all artifact references in this capability, including cross-capability reads (VISION.md, .agentera/decisions.yaml, PROFILE.md).\n\n### Contract values\n\nContract values are inlined where referenced. Visual tokens from protocol: severity arrows VT5-VT8, trend arrows VT12-VT13, progress bar VT18, inline separator VT16 (\u00b7), list item VT15 (\u25b8), section divider VT14, flow/target VT17 (\u2192). Skill glyph SG11 for the exit marker. Exit signals EX1-EX4 for the exit marker. Confidence scale CS1-CS5 for decision profile consumption.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference for ambiguous cases or cross-checking.\n\n---\n\n## DESIGN.md format (condensed)\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\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\nUse this section and \u0060skills/agentera/references/contract.md\u0060 as the active specification for token block formats, theme mappings, component contracts, naming conventions, and monorepo nesting rules.\n\n---\n\n## Step 0: Startup gate and detect mode\n\nBefore any design work:\n\n1. Run \u0060agentera prime --context design --format json\u0060. Use included state families first; run listed \u0060fallback_commands\u0060 before raw artifact reads.\n2. Read the host project's \u0060DESIGN.md\u0060 via docs mapping or \u0060agentera state query design\u0060. It is the **project design authority** for this repository's own product (UI, CLI, or docs). Do not read, copy, or merge suite design sources into it. Suite chrome uses \u0060protocol.yaml\u0060, \u0060agentera prime --context\u0060 capability prose (D65), and v2 app-home \u0060DESIGN.md\u0060 when present \u2014 not the host project's design artifact.\n\n**If DESIGN.md does NOT exist**: Proceed to **Create** mode (Step 1).\n\n**If DESIGN.md exists**: Present the mode choice.\n\nNarration voice (riff, don't script):\n\n- \"Design system's already in place. Evolve it, audit it, or start fresh?\" \u00b7 \"Found your visual identity. Refine, check for mismatches, or clean slate?\"\n\nOffer:\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 and creates a new one from scratch.\n\nIf **Refine**, skip to Refine mode.\nIf **Audit**, skip to Audit mode.\nIf **Replace**, archive current DESIGN.md to \u0060.agentera/archive/design-{date}.yaml\u0060, then proceed to Create mode.\n\n---\n\n## Create mode\n\nStep markers: display \u0060\u2500\u2500 step N/7: verb\u0060 before each step.\nSteps: explore, research, converse, audit, write, validate, 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.md Identity section**: declared personality, voice, emotional register. The visual system must cohere 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. **CLAUDE.md, AGENTS.md**: existing design instructions\n7. **Decision profile**: read \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 (default: \u0060$XDG_DATA_HOME/agentera/PROFILE.md\u0060) directly 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.md 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 question tool\n(\u0060AskUserQuestion\u0060, always include \u0060Done\u0060 option).\n\n**Personality**: the sharp colleague, here to design, not collect requirements. Exacting about details: \"That's good, but what if the palette was braver?\"\n\nFollow a narrative arc, not a checklist. Adapt, but cover:\n\n1. **The philosophy**: \"Based on what I see in the codebase [and the VISION.md 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.md 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 should NEVER 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: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\n- \"Tightening this up...\" \u00b7 \"Cutting the filler first...\" \u00b7 \"One more pass...\"\n\n### Step 5: 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. 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. Present draft, get explicit approval before writing.\n\nArtifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\n### Step 6: Validate\n\nValidate the written file against the \u0060DESIGN.md\u0060 structure described in this capability. Agentera v2 does not ship a standalone design validator; fix malformed sections, missing token fields, or unresolved references before presenting.\n\n### Step 7: Next steps\n\n\u25b8 **Set up enforcement**: propose project-local checks for tokens, component usage, and visual mismatches; no separate Agentera enforcement reference ships in v2\n\u25b8 **Build to the spec**: use \u29c9 build to implement UI that respects the design tokens\n\u25b8 **Document it**: use \u25a4 document to add the design system to project documentation\n\u25b8 **Refine later**: use \u25f0 design again to evolve the design as the project matures\n\n---\n\n## Refine mode\n\nEvolve an existing design system based on what's changed.\n\nStep markers: display \u0060\u2500\u2500 step N/4: verb\u0060 before each step.\nSteps: read, propose, audit, 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.md Identity: has verbal identity evolved?\n4. PROGRESS.md: UI work and inline design decisions\n5. TODO.md: 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.md 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: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns (per-artifact budget), abstraction creep (>=1 concrete anchor), and filler accumulation (banned patterns).\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\nNarration voice (riff, don't script):\n\n- \"Tightening this up...\" \u00b7 \"Cutting the filler first...\" \u00b7 \"One more pass...\"\n\n### Step 4: Update DESIGN.md\n\nShow diff with rationale. Get approval. Run validation after writing.\n\nArtifact writing follows contract Section 24 (Artifact Writing Conventions): banned verbosity patterns, 25-word sentence cap, preferred vocabulary, and lead-with-conclusion structure.\n\n---\n\n## Audit mode\n\nTwo-phase check: deterministic validation (script), then agent-driven code analysis.\n\nStep markers: display \u0060\u2500\u2500 step N/3: verb\u0060 before each step.\nSteps: validate, check, report.\n\n### Step 1: Validate structure\n\nInspect \u0060DESIGN.md\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- \u21f6 **Critical** (VT5): tokens in code that don't exist in DESIGN.md (uncontrolled styling)\n- \u21c9 **Warning** (VT6): declared tokens not used anywhere (dead tokens), mild inconsistencies\n- \u21e2 **Info** (VT8): suggestions for new tokens or constraints based on observed patterns\n\nPresent with file:line references. For each finding, offer to:\n\u25b8 **Fix DESIGN.md**: add missing tokens or constraints\n\u25b8 **File to TODO.md**: if the code is wrong (design is right, code is out of sync)\n\u25b8 **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- NEVER modify DESIGN.md without explicit user approval. Present drafts and get confirmation.\n- NEVER write design tokens that conflict with VISION.md 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- NEVER impose aesthetic preferences. The user's taste drives the design. Have opinions, push for specificity, but defer to the user's choices.\n- NEVER skip the validation step after writing DESIGN.md. Inspect the structure and fix any errors before presenting the result.\n- NEVER create arbitrary token values. Use established scales (8pt grid for spacing, modular type scale for font sizes, OKLCH for perceptual color uniformity). The design system must practice what it preaches.\n- NEVER modify code files. Design writes DESIGN.md; build implements it. The separation of declaration and implementation is fundamental.\n- NEVER copy or merge suite design (\u0060protocol.yaml\u0060 tokens, v2 app-home \u0060DESIGN.md\u0060, or capability instruction modules from \u0060prime --context\u0060) into the host project's \u0060DESIGN.md\u0060. Project design describes the host product only.\n- NEVER skip the codebase exploration (Step 1) 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\u25f0 design \u00b7 <status>\u0060 followed by a summary sentence.\nFor flagged, stuck, and waiting: add \u0060\u25b8\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). Validation script ran without errors, 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: validation passed but with advisory warnings, the design mismatches VISION.md 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, the validation script 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 part of a twelve-capability suite. It is the visual identity layer, the capability that defines how the project looks.\n\n### Design reads vision output\n\nVISION.md's Identity section declares the verbal personality (bold, warm, playful, etc.). Design reads this to propose visual tokens coherent with the declared identity. If Identity says \"industrial and direct,\" design proposes sharp edges and monospace type. 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 document\n\nDOCS.md tracks DESIGN.md in the artifact mapping. Document may document the design system as part of project documentation.\n\n### Design is informed by audit\n\nWhen audit audits architecture alignment or pattern consistency, design system adherence is a relevant dimension. Future integration may include design-specific audit dimensions.\n\n### Design is informed by profile\n\nThe decision profile captures aesthetic preferences, specifically the user's established patterns around visual design, typography choices, and UI conventions. Design reads these as defaults during the create conversation.\n\n### Design is informed by research\n\nWhen research analyzes external design systems or visual patterns, the findings can feed into design's research step or refine mode. External design references enrich the conversation.\n\n### Design is informed by discuss\n\nWhen design decisions require deliberation, suggest \u2748 discuss before committing. Use it for competing aesthetics, brand evolution, or significant visual pivots.\n\n---\n\n## Getting started\n\n### New project: design before building\n\n1. \u26e5 vision: create VISION.md with Identity section (who the project IS)\n2. \u25f0 design: create DESIGN.md (how it LOOKS), coherent with the Identity\n3. \u29c9 build: build UI to the design spec\n\n### Existing project: capture the visual identity\n\n1. \u25f0 design: reads existing styles, proposes tokens from what's already there\n2. Review and refine the generated DESIGN.md\n3. Set up enforcement from project-local checks\n\n### Audit existing design\n\n\u0060\u0060\u0060\n\n/agentera design\n\n\u0060\u0060\u0060\n\nSelect \"Audit\" mode. Validates structure and scans code for mismatches.\n\n### Refine after evolution\n\n\u0060\u0060\u0060\n\n/agentera design\n\n\u0060\u0060\u0060\n\nSelect \"Refine\" mode. Reviews what's changed and proposes design system updates.\n"`);
+// 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

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/design/instructions.ts"],"names":[],"mappings":"AAAA,qDAAqD;AACrD,wEAAwE;AACxE,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,mmrBAAmmrB,CAAC,CAAC;AAC9prB,eAAe,YAAY,CAAC"}
+{"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

@@ -1,6 +1,6 @@
-// Source: skills/agentera/capabilities/discuss/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 `"# DISCUSS\n\n**Reflective Engagement: Socratic Observation Nexus. Examine, Reason, Arbitrate**\n\nStructured deliberation via Socratic questioning. Decisions captured as artifacts the suite consumes. The user thinks; the capability asks the right questions, challenges assumptions, and ensures sound reasoning before action.\n\nEach invocation = one deliberation. The user controls when it ends.\n\nSkill introduction: \u0060─── ❈ discuss · deliberation ───\u0060\n\n---\n\n## Visual identity\n\nGlyph: **❈** (protocol ref: SG4). Used in the mandatory exit marker.\n\n---\n\n## State artifacts\n\nOne file in \u0060.agentera/\u0060, bootstrapped if absent.\n\n| File | Purpose | Bootstrap |\n|------|---------|-----------|\n| \u0060DECISIONS.md\u0060 | Canonical decision artifact, stored as \u0060.agentera/decisions.yaml\u0060 unless mapped otherwise. What was decided, alternatives considered, and why. | First decision entry in YAML form. |\n\nUse \u0060agentera describe --format json\u0060 and its \u0060artifact_schemas\u0060 entry for \u0060decisions\u0060 to locate the active installed schema; do not search Agentera directories manually. Existing decisions artifacts provide repository-local examples of the shape.\n\n### Artifact path resolution\n\nBefore reading or writing any artifact, check if \u0060.agentera/docs.yaml\u0060 exists. If it has an Artifact Mapping section, use the path specified for each canonical filename. If \u0060.agentera/docs.yaml\u0060 doesn't exist or has no mapping for a given artifact, use the default layout: TODO.md, CHANGELOG.md, and DESIGN.md at the project root; canonical VISION.md at \u0060.agentera/vision.yaml\u0060; other agent-facing artifacts at \u0060.agentera/*.yaml\u0060.\n\nWhen feeding a decision into OBJECTIVE.md, write to the active objective's file at \u0060.agentera/optimize/<objective-name>/objective.yaml\u0060 using optimize's active-objective inference.\n\n### Contract values\n\nContract values are inlined where referenced. Visual tokens from protocol: confidence markers VT9-VT11 (━/─/┄), list item VT15 (▸), inline separator VT16 (·), section divider VT14. Skill glyphs SG1-SG12 for cross-capability references. Exit signals EX1-EX4 for the exit marker. Decision labels DL1-DL3 for confidence field. Severity issue levels SI1-SI4 for TODO entries.\n\n\u0060references/contract.md\u0060 (at the v2 skill location \u0060skills/agentera/references/contract.md\u0060) remains available as a full-spec reference.\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.md]\n\u0060\u0060\u0060\n\nCompatibility rule: preserve 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\nThe \"Confidence\" field signals how settled the decision is:\n\n- **firm** (DL1): the user is committed; other capabilities treat this as a constraint\n- **provisional** (DL2): best current answer, open to revision if evidence changes\n- **exploratory** (DL3): a direction to try, explicitly expected to be revisited\n\nDecision numbering: \u0060N = highest existing decision number + 1\u0060. Insert in the active section before the \u0060archive:\u0060 list; if no archive exists, append at end of file. Active entries and archive entries must remain in ascending order by \u0060number\u0060.\n\n---\n\n## Personality\n\nThe sharp colleague, here to help you think, not consult.\n\n- Short sentences. Direct. \"Huh, interesting.\" \"Wait, back up.\" \"OK so what I'm hearing is...\"\n- Reflect back before asking the next question. This is the core move.\n- Challenge assumptions gently. If something's taken for granted, poke at it.\n- Celebrate insights. One question at a time; let the user think.\n\n---\n\n## Interaction rules\n\n- Once routed to discuss, ask every user-facing deliberation question through\n  the runtime-native question tool: Claude Code \u0060AskUserQuestion\u0060, OpenCode\n  \u0060question\u0060, Copilot \u0060ask_user\u0060, and Codex \u0060request_user_input\u0060.\n  **One per turn, no exceptions.** This overrides the routing layer's\n  generic status/handoff question-tool gate.\n- Every question includes a \u0060Done\u0060 option.\n- If the user asks for a recommendation, provide a provisional recommendation\n  in the question text, then ask whether to accept it, challenge it, choose an\n  alternative, or stop.\n- Don't ask about \"depth\" or \"mode.\" Read the room.\n\n---\n\n## Starting a session\n\n### If a topic is provided\n\n1. Read relevant codebase context (enough to ask informed questions, not a research binge)\n2. If decision profile exists, read \u0060$AGENTERA_PROFILE_DIR/PROFILE.md\u0060 directly. Check for high-confidence entries and surface them.\n3. Run \u0060agentera decisions --format json\u0060 for prior decision context. Use the returned \u0060entries\u0060 and \u0060source_contract\u0060 as sufficient for normal deliberation, including capability startup fallback.\n4. Reflect your understanding in 1-2 sentences\n5. Ask the first question through the runtime-native question tool; for\n   \u0060discuss <topic>\u0060, this is the first user-facing action after the reflection.\n\n### Decision context source contract\n\nFor normal startup and deliberation, \u0060agentera decisions --format json\u0060 is the\ndecision context source. The JSON result includes active and archive entries,\ntop-level \u0060source_contract\u0060 guidance, and per-decision \u0060context_complete\u0060,\n\u0060missing_fields\u0060, \u0060compacted\u0060, and \u0060caveats\u0060 fields.\n\n- When \u0060source_contract.complete_for_returned_decisions\u0060 is true, reference the returned decisions without defensively reading raw \u0060.agentera/decisions.yaml\u0060.\n- When a returned decision is compacted or incomplete, surface the missing context as a decision caveat and continue with only the structured fields present.\n- Do not reconstruct absent historical reasoning, alternatives, confidence, or downstream references during normal deliberation.\n- Read the raw decision artifact only for explicit artifact repair/corruption work or after the CLI itself reports an unavailable/defective state path.\n- When source_contract reports \u0060complete_for_normal_deliberation_context=true\u0060, do not raw-read \u0060.agentera/decisions.yaml\u0060 merely because \u0060complete_for_decision_context\u0060 is false; preserve \u0060missing_fields\u0060, \u0060compacted\u0060, \u0060caveats\u0060, and \u0060satisfaction.review_needed\u0060 in downstream handoffs.\n\n### Decision satisfaction authority\n\nWhen deliberation touches decision satisfaction, agents may mark provisional\nsatisfaction with evidence only. Discuss must not mark or imply user-confirmed\nfinal satisfaction unless the user explicitly confirms it in the current\ndeliberation; only the user confirms final satisfaction. If decisions are\ncompacted, missing satisfaction state, open, provisional, or review-needed,\npreserve the caveat and review pressure in the scratchpad or decision note\ninstead of reconstructing hidden outcomes or claiming automation proved intent.\n\n### If no topic is provided\n\nAsk what's on their mind.\n\n---\n\n## Running state\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\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---\n\n## Asking good questions\n\nQuestions should do one of these:\n\n- **Clarify**: \"When you say X, do you mean A or B?\"\n- **Dig deeper**: \"What's driving that? What happens if that's wrong?\"\n- **Reframe**: \"What if you looked at this from the user's perspective instead?\"\n- **Challenge**: \"Is that actually true, or is it just how it's always been done?\"\n- **Connect**: \"That sounds like the same tension as Y. Is there a link?\"\n- **Unstick**: \"If you had to decide right now with what you know, what would you pick?\"\n- **Scope**: \"What's in and what's out? Where do you draw the line?\"\n- **Constrain**: \"What absolutely must NOT happen?\"\n- **Tradeoff**: \"You can't have both X and Y at this scale. Which do you optimize for?\"\n\nOutput constraint: ≤15 words per question.\n\n### When the decision involves code\n\nRead files or search the web for better questions, but just enough context.\n\n### When the decision profile has signal\n\nSkip settled ground. Don't re-ask what the profile answers with high confidence.\n\n### Pushback discipline\n\nHonest friction. Don't let vague answers slide.\n\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.** \"Let me restate: 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\n\nWhen the user leans toward a consequential direction, challenge before offering alternatives:\n\n1. Name 1-3 context-specific blind spots first.\n2. Then present serious alternatives with concrete win conditions.\n3. Make the call with explicit confidence (DL1-DL3).\n\nRed-flag phrasing is banned:\n\n- \"That sounds reasonable.\"\n- \"Either way is fine.\"\n- \"It depends\" without naming the deciding variable.\n- \"There is no wrong answer here.\"\n- \"Both options are valid\" when one conflicts with constraints.\n\n---\n\n## When the user picks \"Done\"\n\nProduce something actionable.\n\n### Step 1: Summarize the decision\n\nBrief, casual: where we landed (2-3 sentences), key insight, confidence (DL1/DL2/DL3).\n\n### Step 2: Offer to capture and connect\n\nRelevant options only:\n\n- **Log it**: add a new numbered entry to \u0060DECISIONS.md\u0060 (always offered)\n- **Feed into VISION.md**: if about direction/scope/principles\n- **Feed into OBJECTIVE.md**: if about what to optimize\n- **File to TODO.md**: if surfaced tech debt\n- **Just wrap up**: no artifacts needed\n\n### Step 3: Pre-write self-audit\n\nPre-write self-audit: run \u0060agentera check lint --artifact <ARTIFACT> --text \"<DRAFT>\"\u0060 (or \u0060--file <PATH>\u0060; schema names such as \u0060decisions\u0060 auto-resolve the artifact file when no input is given) on the draft entry to check verbosity overruns, abstraction creep, and filler accumulation.\nMax 3 revision attempts. Flag with [post-audit-flagged] if still failing.\n\n### Step 4: Write artifacts\n\nFor any option the user selects:\n\n- **DECISIONS.md**: write chosen decision, confidence, and rationale per contract token budgets. Compute next decision number before writing. Apply the schema COMPACTION rules before writing if thresholds are exceeded: keep 10 full decisions, keep up to 40 one-line archive entries, and drop beyond 50 total.\n- **VISION.md / OBJECTIVE.md**: brief follow-up. Present draft for approval.\n- **TODO.md**: standard format (severity, context, impact).\n\nArtifact writing follows contract Section 24 conventions.\n\n---\n\n## Safety rails\n\n<critical>\n\n- NEVER make the decision for the user. Your job is to help them think, not to decide.\n- NEVER skip to implementation. Discuss deliberates; other capabilities build.\n- NEVER modify VISION.md, OBJECTIVE.md, or TODO.md without explicit user confirmation.\n- NEVER ask compound questions. One question per turn.\n- NEVER ignore the decision profile. If high-confidence entries exist, acknowledge them.\n- NEVER 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 summary sentence.\nFor flagged, stuck, and waiting: add \u0060▸\u0060 (VT15) bullet details.\n\n- **complete** (EX1): Deliberation reached a conclusion; artifacts written with user approval; decision confidence captured.\n- **flagged** (EX2): Deliberation concluded but decision remains unresolved or provisional; significant tensions unresolved; conclusion contradicts prior decisions.\n- **stuck** (EX3): Cannot proceed: topic requires inaccessible external research, or artifact write failed.\n- **waiting** (EX4): No topic provided and user hasn't responded, or surfaced that a different capability is needed first.\n\n---\n\n## Cross-capability integration\n\nDiscuss is the deliberation layer.\n\n### Feeds into ⧉ build\n\nDecisions about project direction captured in VISION.md. DECISIONS.md entries with \u0060Feeds into: VISION.md\u0060 give build reasoning context.\n\n### Feeds into ⎘ optimize\n\nDecisions about what to optimize captured in OBJECTIVE.md at \u0060.agentera/optimize/<objective-name>/objective.yaml\u0060.\n\n### Triggers ⬚ research\n\nDuring deliberation, if the user needs external research: \"Sounds like we need to research X with ⬚ research?\"\n\n### Informed by ♾ profile\n\nIf a decision profile exists, read it at session start. High-confidence entries acknowledged; low-confidence entries treated as hypotheses.\n\n### Feeds ♾ profile\n\nDECISIONS.md is a high-signal source for profile's extraction scripts.\n\n### Feeds ≡ plan\n\nWhen deliberation concludes with a decision to build something, the natural next step is ≡ plan.\n\n### Triggered by ⛶ audit\n\nWhen audits reveal an architecture mismatch, audit suggests ❈ discuss to think through the response.\n\n---\n\n## Getting started\n\n### Before a build session\n\nRun \u0060/agentera discuss\u0060 to think through project direction before creating VISION.md.\n\n### Before an optimize session\n\nRun \u0060/agentera discuss\u0060 to think through what metric matters and why before creating OBJECTIVE.md.\n\n### After an research analysis\n\nRun \u0060/agentera discuss\u0060 to evaluate which recommendations to adopt.\n\n### Standalone\n\nRun \u0060/agentera discuss\u0060 whenever you need to think through something complex.\n"`);
+// 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 --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 (e.g., Claude Code \u0060AskUserQuestion\u0060, OpenCode \u0060question\u0060, Copilot \u0060ask_user\u0060, Codex \u0060request_user_input\u0060 — guidance examples, not schema authority). **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

@@ -1 +1 @@
-{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../../src/capabilities/discuss/instructions.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,qFAAqF;AACrF,yFAAyF;AACzF,MAAM,CAAC,MAAM,YAAY,GAAW,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAA,ujdAAujd,CAAC,CAAC;AAClnd,eAAe,YAAY,CAAC"}
+{"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,85YAA85Y,CAAC,CAAC;AACz9Y,eAAe,YAAY,CAAC"}