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

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

@@ -0,0 +1,71 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact_id: plan
+    local_role: produces_and_consumes
+    description: >-
+      Orchestrate consumes plan task queue state through
+      `agentera prime --context orchestrate --format json` before raw
+      artifact access, then updates status (pending -> complete/blocked) only
+      when resolving a task. Failed evaluator results are recorded through the
+      retry-safe typed `record-evaluation` mutation before retry or blocking.
+  2:
+    id: A2
+    artifact_id: progress
+    local_role: consumes
+    description: >-
+      Orchestrate consumes progress verification state from the returned
+      orchestration context first, then bounded `agentera state progress list
+      --limit 20 --format json` fallback output. Exact detail uses `state
+      progress get --number N`; raw reads are diagnostic-only for corruption or
+      CLI-defect investigation.
+  3:
+    id: A3
+    artifact_id: health
+    local_role: consumes
+    description: >-
+      Orchestrate consumes returned health state first after plan completion to
+      decide whether to start a new plan cycle; bounded `agentera state health
+      list --limit 20 --format json` and exact `state health get --number N`
+      are the fallback contracts. Raw reads are diagnostic-only for corruption
+      or CLI-defect investigation.
+  4:
+    id: A4
+    artifact_id: todo
+    local_role: produces
+    description: >-
+      Orchestrate consumes TODO caveats from CLI startup context and writes
+      blocked task logging only when a task exhausts its retry budget.
+  5:
+    id: A5
+    artifact_id: decisions
+    local_role: consumes
+    description: >-
+      Orchestrate consumes included decision context or bounded
+      `agentera state decisions list --limit 20 --format json` discovery and
+      exact `state decisions get --number N` retrieval, preserving firm
+      constraints, exploratory uncertainties, and compacted-entry caveats.
+      Raw reads are diagnostic-only for corruption or CLI-defect investigation.
+  6:
+    id: A6
+    artifact_id: vision
+    local_role: consumes
+    description: >-
+      Orchestrate consumes returned vision state or missing-state caveats during
+      bootstrap when chaining research for vision-gap analysis.
+  7:
+    id: A7
+    artifact_id: profile
+    local_role: consumes
+    description: >-
+      Orchestrate consumes returned profile status and caveats first for persona
+      context. If missing or stale, it proceeds without refreshing profile
+      state and preserves the caveat.
+  8:
+    id: A8
+    artifact_id: docs
+    local_role: consumes
+    description: >-
+      Orchestrate uses docs mapping from CLI startup context first to resolve
+      project-local artifact mappings before any diagnostic-only raw artifact
+      read or artifact write.

package/bundle/skills/agentera/capabilities/{orkestrera → orchestrate}/schemas/exit.yaml

@@ -3,7 +3,7 @@ EXIT_CONDITIONS:
     id: E1
     condition: complete
     description: >-
-      All PLAN.md tasks are complete, the health check passed, and the
+      All plan tasks are complete, the health check passed, and the
       orchestration session concluded with all planned work finished.
     exit_signal: complete
   2:
@@ -18,7 +18,7 @@ EXIT_CONDITIONS:
     id: E3
     condition: stuck
     description: >-
-      Cannot proceed. PLAN.md has circular dependencies preventing any task
+      Cannot proceed. The plan has circular dependencies preventing any task
       from becoming eligible, no target capabilities are available to
       delegate, or file access prevents reading or updating artifacts.
       The exit marker explains what is blocking progress.
@@ -27,8 +27,9 @@ EXIT_CONDITIONS:
     id: E4
     condition: waiting
     description: >-
-      No PLAN.md exists and the bootstrap chain cannot proceed because
-      VISION.md is absent and the user has not confirmed how to create one,
-      or a dispatched capability returned waiting status requiring user input.
-      The waiting bullet identifies the specific decision needed.
+      No plan exists and the bootstrap chain cannot proceed because the
+      vision artifact is absent and the user has not confirmed how to
+      create one, or a dispatched capability returned waiting status
+      requiring user input. The waiting bullet identifies the specific
+      decision needed.
     exit_signal: waiting

package/bundle/skills/agentera/capabilities/{orkestrera → orchestrate}/schemas/triggers.yaml

@@ -3,11 +3,15 @@ TRIGGERS:
     id: T1
     description: >-
       Direct invocation by name or slash command. Matches when the user
-      explicitly requests orkestrera.
+      explicitly requests orchestrate.
     priority: high
     patterns:
-      - "orkestrera"
-      - "/orkestrera"
+      - "orchestrate"
+      - "/orchestrate"
+    confidence_threshold: 60
+    borderline_band: 10
+    patterns_regex:
+      - "\\b/orchestrate\\b"
   2:
     id: T2
     description: >-
@@ -21,6 +25,10 @@ TRIGGERS:
       - "keep going until done"
       - "run through the plan"
       - "build everything"
+    confidence_threshold: 55
+    disambiguates_against:
+      - capability: build
+        hint: "orchestrate runs the whole plan autonomously; build executes one development cycle"
   3:
     id: T3
     description: >-
@@ -32,6 +40,7 @@ TRIGGERS:
       - "orchestrate"
       - "orchestrate skills"
       - "multi-cycle"
+    confidence_threshold: 50
   4:
     id: T4
     description: >-
@@ -40,3 +49,7 @@ TRIGGERS:
     priority: medium
     patterns:
       - "autonomous plan execution"
+    confidence_threshold: 50
+    disambiguates_against:
+      - capability: build
+        hint: "orchestrate chains multi-cycle execution; build runs a single cycle"

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

@@ -0,0 +1,120 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: must_not_read_source
+    description: >-
+      Orchestrate MUST NOT read implementation source code. It dispatches
+      capabilities; it does not implement. Artifact files (`.agentera/*.yaml`,
+      `TODO.md`) are state records, not source code; raw reads are last-resort
+      after CLI context and listed fallback commands. This rule verifies the
+      instructions explicitly state the source-code read prohibition.
+    severity: critical
+    checks:
+      - "orchestrate instructions (packages/cli/src/capabilities/orchestrate/instructions.ts) contains MUST NOT read implementation source code"
+  2:
+    id: V2
+    rule: evaluation_gate_required
+    description: >-
+      Every completed task MUST be verified by audit before being marked
+      complete. The orchestrator MUST NOT skip evaluation. This rule verifies
+      the instructions contain the must-not-skip-evaluation safety rail.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains MUST NOT skip evaluation"
+  3:
+    id: V3
+    rule: retry_budget_enforced
+    description: >-
+      No task may be retried more than 2 times. After the second failure,
+      the task must be marked blocked. This rule verifies the retry budget
+      is stated in the instructions and safety rails.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains retry a task more than 2 times"
+  4:
+    id: V4
+    rule: exit_marker_required
+    description: >-
+      Every orchestrate invocation MUST emit an exit marker. The marker uses
+      the canonical glyph ⎈ (SG12) in the format ⎈ orchestrate · <status>
+      where status is one of EX1-EX4.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains exit marker with glyph ⎈ (SG12)"
+      - "orchestrate instructions references exit signals EX1-EX4"
+  5:
+    id: V5
+    rule: orchestrator_read_only_artifacts
+    description: >-
+      The orchestrator reads artifacts and updates plan task statuses and
+      TODO.md blocked entries. It does NOT write to progress, changelog,
+      or any other capability-owned artifact. This rule verifies the
+      artifacts schema reflects this constraint.
+    severity: warning
+    checks:
+      - "progress is consumes only (not produces)"
+      - "health is consumes only (not produces)"
+      - "decisions is consumes only (not produces)"
+      - "vision is consumes only (not produces)"
+  6:
+    id: V6
+    rule: orchestration_context_first
+    description: >-
+      Orchestrate startup and evaluation MUST use
+      `agentera prime --context orchestrate --format json` and the
+      returned orchestration context before raw plan, progress, health, TODO,
+      or decisions artifact reads.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains agentera prime --context orchestrate --format json"
+      - "orchestrate instructions contains complete_for_orchestration_context"
+      - "orchestrate instructions contains no raw plan, progress, health, TODO, or decisions reads"
+  7:
+    id: V7
+    rule: cli_fallback_before_raw_read
+    description: >-
+      When orchestration context is incomplete, Orchestrate MUST run listed
+      fallback commands before any raw artifact read.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains run listed fallback commands"
+      - "orchestrate instructions contains last-resort diagnostics"
+  8:
+    id: V8
+    rule: caveats_preserved_for_evaluation
+    description: >-
+      Orchestrate MUST preserve compacted-decision, stale health/profile/app,
+      missing-state, and retry-state provenance caveats when handing a task to
+      audit.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains compacted decision caveats"
+      - "orchestrate instructions contains stale health/profile/app caveats"
+      - "orchestrate instructions contains retry-state provenance"
+  9:
+    id: V9
+    rule: satisfaction_authority_boundary
+    description: >-
+      When Orchestrate touches decision satisfaction, it may pass through or request
+      provisional satisfaction with evidence but MUST NOT user-confirm satisfaction.
+      Missing, compacted, open, provisional, or review-needed satisfaction state
+      remains a caveat and review pressure; automation must not reconstruct hidden
+      outcomes or claim it proved user intent.
+    severity: critical
+    checks:
+      - "Provisional satisfaction requires evidence"
+      - "Only the user confirms final satisfaction"
+      - "Missing or compacted satisfaction caveats are preserved"
+  10:
+    id: V10
+    rule: audit_citation_required
+    description: >-
+      Orchestrate Step 3 Surface 2 audit delegation MUST require a
+      citation: <file>:<line> (or not-applicable: <reason>) for every FAIL
+      finding, and require verify_command for FAIL rows with file:line
+      citations. Authority: references/cli/capability-instruction-contract.yaml#evaluator_handoff.
+    severity: critical
+    checks:
+      - "orchestrate instructions contains citation: `<file>:<line>` OR `not-applicable: <reason>`"
+      - "orchestrate instructions contains verify_command"
+      - "orchestrate instructions contains evaluator_handoff.output_requirements"

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

@@ -0,0 +1,63 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact_id: plan
+    local_role: produces_and_consumes
+    description: >-
+      Current plan with tasks, dependencies, and behavioral acceptance criteria.
+      Its active position is derived from the docs-mapped current-plan path,
+      not persisted lifecycle status. Plan writes this during the planning
+      session and may read existing plan context before replacing or refining it.
+  2:
+    id: A2
+    artifact_id: plan_archive
+    local_role: produces
+    description: >-
+      Immutable, non-executable history created when a plan is complete or
+      explicitly force-archived. Forced archival preserves an unfinished
+      plan's open status rather than claiming completion.
+  3:
+    id: A3
+    artifact_id: vision
+    local_role: consumes
+    description: >-
+      Plan reads this during Orient to understand project direction and
+      align the plan with the vision.
+  4:
+    id: A4
+    artifact_id: decisions
+    local_role: consumes
+    description: >-
+      Plan reads firm (DL1) entries only as hard constraints for planning.
+  5:
+    id: A5
+    artifact_id: todo
+    local_role: consumes
+    description: >-
+      Plan reads this to identify related known
+      issues that the plan should address.
+  6:
+    id: A6
+    artifact_id: health
+    local_role: consumes
+    description: >-
+      Plan reads this to factor structural issues into the plan.
+  7:
+    id: A7
+    artifact_id: progress
+    local_role: consumes
+    description: >-
+      Plan reads this to understand what was built recently.
+  8:
+    id: A8
+    artifact_id: profile
+    local_role: consumes
+    description: >-
+      Plan reads this to calibrate planning depth and pattern preferences.
+  9:
+    id: A9
+    artifact_id: docs
+    local_role: consumes
+    description: >-
+      Plan reads this first to resolve project-local artifact mappings and
+      reads the versioning block for version bump task generation.

package/bundle/skills/agentera/capabilities/{planera → plan}/schemas/exit.yaml

@@ -4,8 +4,8 @@ EXIT_CONDITIONS:
     condition: complete
     description: >-
       PLAN.md was written and approved (or skip level confirmed), the
-      adversarial review ran for full plans, and the handoff to realisera
-      or orkestrera was suggested.
+      adversarial review ran for full plans, and the handoff to build
+      or orchestrate was suggested.
     exit_signal: complete
   2:
     id: E2

package/bundle/skills/agentera/capabilities/{planera → plan}/schemas/triggers.yaml

@@ -3,11 +3,15 @@ TRIGGERS:
     id: T1
     description: >-
       Direct invocation by name or slash command. Matches when the user
-      explicitly requests planera for structured planning.
+      explicitly requests plan for structured planning.
     priority: high
     patterns:
-      - "planera"
-      - "/planera"
+      - "plan"
+      - "/plan"
+    confidence_threshold: 60
+    borderline_band: 10
+    patterns_regex:
+      - "\\b/plan\\b"
   2:
     id: T2
     description: >-
@@ -21,6 +25,10 @@ TRIGGERS:
       - "decompose this"
       - "spec this out"
       - "plan before building"
+    confidence_threshold: 50
+    disambiguates_against:
+      - capability: build
+        hint: "plan structures work into tasks before coding; build implements the work"
   3:
     id: T3
     description: >-
@@ -32,3 +40,7 @@ TRIGGERS:
       - "how should we build this"
       - "multi-step feature"
       - "this is too big for one cycle"
+    confidence_threshold: 50
+    disambiguates_against:
+      - capability: build
+        hint: "plan sizes work before implementation; build runs the development cycle"

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

@@ -0,0 +1,89 @@
+VALIDATION:
+  1:
+    id: V1
+    rule: behavioral_acceptance_criteria
+    description: >-
+      All acceptance criteria MUST be behavioral (Given/When/Then format)
+      and MUST NOT reference implementation details (class names, API
+      endpoints, database tables, function names, line numbers).
+    severity: critical
+    checks:
+      - "Acceptance criteria use Given/When/Then format"
+      - "No implementation details in acceptance criteria"
+  2:
+    id: V2
+    rule: coherent_lifecycle_scope
+    description: >-
+      Full plans MUST keep all tasks within a coherent lifecycle boundary.
+      Split plans only when work crosses a real lifecycle or coherence boundary.
+    severity: critical
+    checks:
+      - "Tasks stay within one coherent lifecycle boundary"
+      - "Splits follow real lifecycle or coherence boundaries"
+  3:
+    id: V3
+    rule: adversarial_review_required
+    description: >-
+      Full plans MUST undergo adversarial review. The critic MUST find at
+      least one issue. "Looks good" is not acceptable. Skip level and
+      light plans are exempt.
+    severity: critical
+    checks:
+      - "Adversarial review ran for full plans"
+  4:
+    id: V4
+    rule: plan_final_state_sync
+    description: >-
+      Every full plan MUST end with a "final state sync" task that depends
+      on all prior tasks. This ensures aggregate plan-level CHANGELOG.md,
+      PROGRESS.md, and TODO.md updates.
+    severity: critical
+    checks:
+      - "Full plan has final state sync task as last task"
+  5:
+    id: V5
+    rule: test_proportionality_target
+    description: >-
+      Tasks that include writing tests MUST have a proportionality target
+      in their acceptance criteria. Default: one pass + one fail per
+      testable unit. Override only with explicit rationale.
+    severity: warning
+    checks:
+      - "Test tasks state proportionality target"
+  6:
+    id: V6
+    rule: skip_level_for_trivial_work
+    description: >-
+      Plan MUST detect skip level for trivial work (single-file change,
+      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/{profilera → profile}/schemas/artifacts.yaml

@@ -5,14 +5,14 @@ ARTIFACTS:
     local_role: produces_and_consumes
     description: >-
       Decision profile with per-entry confidence scoring, permanence
-      classification, and temporal metadata. Profilera writes this in both Full
+      classification, and temporal metadata. Profile writes this in both Full
       and Validate modes, then reads it for validation and update context.
   2:
     id: A2
     artifact_id: decisions
     local_role: consumes
     description: >-
-      Profilera treats this as a high-signal source for extraction scripts.
+      Profile treats this as a high-signal source for extraction scripts.
       Each decision entry captures
       reasoning, tradeoffs, and confidence, making deliberation sessions
       one of the richest inputs for decision profile generation.

package/bundle/skills/agentera/capabilities/{profilera → profile}/schemas/exit.yaml

@@ -12,7 +12,8 @@ EXIT_CONDITIONS:
     condition: flagged
     description: >-
       Profile generation or validation completed but with data quality
-      issues: extraction failed for one or more sources, prediction
+      issues: available runtime history was skipped without explicit
+      acceptance, extraction failed for one or more sources, prediction
       accuracy was below 3/5, or significant unresolved tensions were
       found.
     exit_signal: flagged
@@ -21,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/{profilera → profile}/schemas/triggers.yaml

@@ -3,11 +3,12 @@ TRIGGERS:
     id: T1
     description: >-
       Direct invocation by name or slash command. Matches when the user
-      explicitly requests profilera.
+      explicitly requests profile.
     priority: high
     patterns:
-      - "profilera"
-      - "/profilera"
+      - "profile"
+      - "/profile"
+    confidence_threshold: 55
   2:
     id: T2
     description: >-
@@ -19,6 +20,7 @@ TRIGGERS:
       - "generate decision profile"
       - "rebuild my profile"
       - "regenerate profile"
+    confidence_threshold: 45
   3:
     id: T3
     description: >-
@@ -31,6 +33,7 @@ TRIGGERS:
       - "validate my profile"
       - "check my profile"
       - "quick profile check"
+    confidence_threshold: 45
   4:
     id: T4
     description: >-
@@ -43,3 +46,4 @@ TRIGGERS:
       - "mine my sessions"
       - "decision patterns"
       - "review my decision history"
+    confidence_threshold: 45

package/bundle/skills/agentera/capabilities/{profilera → profile}/schemas/validation.yaml

@@ -37,9 +37,9 @@ VALIDATION:
     id: V4
     rule: read_only_sources
     description: >-
-      Profilera MUST NOT modify session history, memory files, or config
+      Profile MUST NOT modify session history, memory files, or config
       files. It reads these sources for extraction but never writes to them.
-      The only artifact profilera produces is PROFILE.md.
+      The only artifact profile produces is PROFILE.md.
     severity: critical
     checks:
       - "No writes to session history files"

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

@@ -0,0 +1,24 @@
+ARTIFACTS:
+  1:
+    id: A1
+    artifact_id: todo
+    local_role: produces
+    description: >-
+      Open problems by severity. Research writes actionable findings here
+      (with user confirmation), classifying each by severity per protocol
+      SF1-SF3. Build picks up changes automatically in its next cycle.
+  2:
+    id: A2
+    artifact_id: vision
+    local_role: produces
+    description: >-
+      Research may refine project direction with user confirmation when the
+      analysis shifts thinking about the project's direction.
+  3:
+    id: A3
+    artifact_id: profile
+    local_role: consumes
+    description: >-
+      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/{inspirera → research}/schemas/triggers.yaml

@@ -3,11 +3,12 @@ TRIGGERS:
     id: T1
     description: >-
       Direct invocation by name or slash command. Matches when the user
-      explicitly requests inspirera.
+      explicitly requests research.
     priority: high
     patterns:
-      - "inspirera"
-      - "/inspirera"
+      - "research"
+      - "/research"
+    confidence_threshold: 55
   2:
     id: T2
     description: >-
@@ -21,6 +22,7 @@ TRIGGERS:
       - "is this relevant to"
       - "what can I take from this"
       - "should I adopt"
+    confidence_threshold: 45
   3:
     id: T3
     description: >-
@@ -32,3 +34,7 @@ TRIGGERS:
       - "review this repo for ideas"
       - "anything worth stealing from"
       - "how does this compare to what I'm doing"
+    confidence_threshold: 45
+    disambiguates_against:
+      - capability: audit
+        hint: "research reviews external resources for ideas; audit reviews the local codebase for health"

package/bundle/skills/agentera/capabilities/{inspirera → research}/schemas/validation.yaml

@@ -3,8 +3,8 @@ VALIDATION:
     id: V1
     rule: read_only_target
     description: >-
-      Inspirera MUST NOT modify code in the target project. It analyzes
-      and maps concepts; other capabilities (realisera, optimera)
+      Research MUST NOT modify code in the target project. It analyzes
+      and maps concepts; other capabilities (build, optimize)
       implement changes. The only writes are to TODO.md and VISION.md,
       and only with explicit user confirmation.
     severity: critical