agentera 0.0.0 → 3.0.0-dev.0

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

@@ -0,0 +1,342 @@
+# Plan Artifact Schema
+#
+# Active work plan maintained by planera. Each plan captures what will be built,
+# why, constraints, scope boundaries, design approach, tasks with dependencies
+# and acceptance criteria, overall acceptance, and surprises.
+#
+# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
+# following capability_schema_contract.yaml and protocol.yaml conventions.
+#
+# ── Field-by-field mapping: v1 PLAN.md → v2 plan.yaml ──
+#
+# v1 Field                              v2 Field               v2 ID
+# ─────────────────────────────────────────────────────────────────────
+# <!-- Level: light/full -->            HEADER.level           PL1
+# <!-- Created: date -->                HEADER.created         PL2
+# <!-- Status: active/completed -->     HEADER.status          PL3
+# <!-- Reviewed: date -->               HEADER.reviewed        PL4
+# <!-- Critic issues: N found... -->    HEADER.critic_issues   PL5
+# <!-- Revised: description -->         HEADER.revised         PL6
+# # Plan: <title>                       HEADER.title           PL7
+# ## What                               PLAN.what              PL8
+# ## Why                                PLAN.why               PL9
+# ## Constraints                        PLAN.constraints       PL10
+# ## Scope / **In**: <list>             SCOPE.included         PL11
+# ## Scope / **Out**: <list>            SCOPE.excluded         PL12
+# ## Scope / **Deferred**: <list>       SCOPE.deferred         PL13
+# ## Design                             PLAN.design            PL14
+# ### Task N: <name>                    TASK.number            PL15
+# (task name from heading)              TASK.name              PL16
+# **Depends on**: <text>                TASK.depends_on        PL17
+# **Status**: <status>                  TASK.status            PL18
+# **Acceptance**: <criteria list>       TASK.acceptance        PL19
+# ## Overall Acceptance                 PLAN.overall_acceptance PL20
+# ## Surprises                          PLAN.surprises         PL21
+#
+# Protocol references:
+#   status visual tokens: VT1-VT4 (protocol.yaml VISUAL_TOKENS)
+#   list item marker: VT15 (protocol.yaml VISUAL_TOKENS)
+
+meta:
+  name: plan
+  version: "1.0.0"
+  description: >-
+    Active work plan. Produced by planera and updated by plan executors.
+    Consumed by capabilities that inspect or execute plan state.
+  artifact_type: agent_facing
+  path: ".agentera/plan.yaml"
+  producer: [orkestrera, planera, realisera]
+  consumers: [hej, inspektera, orkestrera, planera, realisera]
+  format: yaml
+
+GROUP_PREFIXES:
+  BUDGET: PB
+  HEADER: PH
+  PLAN: PL
+  SCOPE: PS
+  TASK: PT
+  VALIDATION: PV
+
+BUDGET:
+  1:
+    id: PB1
+    scope: per_task_entry
+    max_words: 100
+    description: >-
+      Maximum words per task entry. Budgets are guidelines, not hard
+      blockers.
+  2:
+    id: PB2
+    scope: full_file
+    max_words: 2500
+    description: >-
+      Maximum words for the full file. If a write would exceed this
+      budget, compact the plan (merge completed tasks, defer scope).
+
+HEADER:
+  1:
+    id: PH1
+    field: level
+    type: string
+    required: true
+    description: >-
+      Plan detail level. 'light' for small scoped work; 'full' for
+      multi-task plans with explicit acceptance criteria and review.
+    validation:
+      - "Must be one of: light, full"
+  2:
+    id: PH2
+    field: created
+    type: string
+    format: "YYYY-MM-DD"
+    required: true
+    description: "Date the plan was created."
+    validation:
+      - "Must match YYYY-MM-DD format"
+  3:
+    id: PH3
+    field: status
+    type: string
+    required: true
+    description: >-
+      Plan lifecycle status. Active plans are being executed; complete
+      plans are candidates for archival.
+    validation:
+      - "Must be one of: active, complete"
+  4:
+    id: PH4
+    field: reviewed
+    type: string
+    format: "YYYY-MM-DD"
+    required: false
+    description: >-
+      Date the plan was last reviewed via adversarial critic pass.
+      Absent for light-level plans that skip review.
+  5:
+    id: PH5
+    field: critic_issues
+    type: string
+    required: false
+    description: >-
+      Summary of critic review findings. Format: 'N found, M addressed,
+      K dismissed'. Absent for light-level plans or pre-review state.
+  6:
+    id: PH6
+    field: revised
+    type: string
+    required: false
+    description: >-
+      Description of what was revised after critic review. Absent for
+      light-level plans or pre-review state.
+  7:
+    id: PH7
+    field: title
+    type: string
+    required: true
+    description: >-
+      Short plan title. Used in archive naming and plan listing.
+      Format: 'Plan: <descriptive name>'.
+    validation:
+      - "Non-empty string"
+
+PLAN:
+  1:
+    id: PL8
+    field: what
+    type: string
+    required: true
+    description: >-
+      What the plan will build or accomplish. Plain-language summary
+      of the plan's scope and deliverables.
+    validation:
+      - "Non-empty string"
+  2:
+    id: PL9
+    field: why
+    type: string
+    required: true
+    description: >-
+      Why this plan exists. References decisions, vision, or constraints
+      that motivate the work.
+    validation:
+      - "Non-empty string"
+  3:
+    id: PL10
+    field: constraints
+    type: string
+    required: false
+    description: >-
+      Hard constraints governing plan execution. References decision
+      labels (firm/provisional/exploratory) and project-level rules.
+  4:
+    id: PL14
+    field: design
+    type: string
+    required: false
+    description: >-
+      Design approach for the plan. Describes the strategy, patterns,
+      and structural decisions. Required for full-level plans.
+  5:
+    id: PL20
+    field: overall_acceptance
+    type: string
+    required: false
+    description: >-
+      Plan-level acceptance criteria. Criteria that span multiple tasks
+      and must hold when the entire plan is complete.
+  6:
+    id: PL21
+    field: surprises
+    type: string
+    required: false
+    description: >-
+      Runtime surprises discovered during plan execution. Populated
+      by realisera when reality diverges from plan. Default: empty.
+  7:
+    id: PL22
+    field: previous_plan_archived
+    type: string
+    required: false
+    description: >-
+      Path to the previous active plan archived when this plan was created.
+      Preserves plan lineage without changing lifecycle status.
+
+SCOPE:
+  1:
+    id: PS11
+    field: included
+    type: list[string]
+    required: true
+    description: >-
+      Work items and surfaces in scope. Each entry names a deliverable,
+      file, or system boundary that the plan covers.
+    validation:
+      - "At least one entry required"
+  2:
+    id: PS12
+    field: excluded
+    type: list[string]
+    required: true
+    description: >-
+      Work items explicitly out of scope. Prevents scope creep by
+      recording what was considered and deferred.
+  3:
+    id: PS13
+    field: deferred
+    type: list[string]
+    required: false
+    description: >-
+      Work items deferred to a future plan. Distinguished from
+      excluded items by having acknowledged future intent.
+
+TASK:
+  1:
+    id: PT15
+    field: number
+    type: integer
+    required: true
+    description: >-
+      Task number within the plan. Sequential, starting from 1.
+      May include a descriptive name (e.g., 'Task 2: Shared Protocol').
+    validation:
+      - "Must be a positive integer"
+      - "Must be unique within the plan"
+  2:
+    id: PT16
+    field: name
+    type: string
+    required: true
+    description: >-
+      Short descriptive name for the task. Appears in task headings
+      and progress tracking.
+    validation:
+      - "Non-empty string"
+  3:
+    id: PT17
+    field: depends_on
+    type: list[string]
+    required: false
+    description: >-
+      Task dependencies. References task numbers or names that must
+      complete before this task can start. Empty for root tasks.
+  4:
+    id: PT18
+    field: status
+    type: string
+    required: true
+    description: >-
+      Task execution status. Uses visual tokens from protocol.yaml
+      VISUAL_TOKENS (VT1-VT4) for display.
+    validation:
+      - "Must be one of: complete, in_progress, pending, blocked"
+  5:
+    id: PT19
+    field: acceptance
+    type: list[string]
+    required: false
+    description: >-
+      Acceptance criteria for this task. Each entry is a GIVEN/WHEN/THEN
+      statement that must hold for the task to be considered complete.
+      Required for full-level plans.
+
+VALIDATION:
+  1:
+    id: PV1
+    rule: unique_task_numbers
+    severity: error
+    description: >-
+      Task numbers must be unique within a plan and sequential.
+    checks:
+      - "All task numbers are unique"
+      - "Task numbers are sequential starting from 1"
+  2:
+    id: PV2
+    rule: required_fields
+    severity: error
+    description: >-
+      The plan must have: level, created, status, title, what, why,
+      scope.included, scope.excluded, and at least one task. Each task
+      must have number, name, and status.
+    checks:
+      - "level is present and is 'light' or 'full'"
+      - "created is present and matches YYYY-MM-DD"
+      - "status is present and is 'active' or 'completed'"
+      - "title is present and non-empty"
+      - "what is present and non-empty"
+      - "why is present and non-empty"
+      - "scope.included has at least one entry"
+      - "scope.excluded is present (may be empty list)"
+      - "tasks has at least one entry"
+      - "each task has number, name, and status"
+  3:
+    id: PV3
+    rule: full_level_requirements
+    severity: error
+    description: >-
+      Full-level plans must have: design, reviewed, parseable non-zero
+      critic_issues, and acceptance criteria on each task.
+    checks:
+      - "design is present for full-level plans"
+      - "reviewed is present for full-level plans"
+      - "critic_issues is present and records at least one found issue for full-level plans"
+      - "each task has acceptance criteria for full-level plans"
+  4:
+    id: PV4
+    rule: dependency_references
+    severity: error
+    description: >-
+      Task depends_on references must point to valid task numbers
+      within the same plan.
+    checks:
+      - "Each dependency references an existing task number"
+      - "No circular dependency chains"
+  5:
+    id: PV5
+    rule: word_budget
+    severity: advisory
+    description: >-
+      Advisory check. Per-task entry should be <=100 words; full file
+      should be <=2500 words.
+    checks:
+      - "Per-task word count <= 100"
+      - "Total file word count <= 2500"

package/bundle/skills/agentera/schemas/artifacts/progress.yaml

@@ -0,0 +1,325 @@
+# Progress Artifact Schema
+#
+# Cycle-by-cycle operational log for realisera. Each entry records what happened
+# in one development cycle: phase, work done, commit, discoveries, verification,
+# next steps, and context envelope.
+#
+# Structural pattern: UPPER_CASE groups with numbered entries and stable IDs,
+# following capability_schema_contract.yaml and protocol.yaml conventions.
+#
+# ── Field-by-field mapping: v1 PROGRESS.md → v2 progress.yaml ──
+#
+# v1 Field                              v2 Field               v2 ID
+# ─────────────────────────────────────────────────────────────────────
+# ## Cycle N · date · type-prefix       CYCLE.number           PR1
+# (date from heading)                   CYCLE.timestamp        PR2
+# (type-prefix from heading)            CYCLE.type             PR3
+# **Phase**: <phase>                    CYCLE.phase            PR4
+# **What**: <text>                      CYCLE.what             PR5
+# **Commit**: <hash/N/A>                CYCLE.commit           PR6
+# **Inspiration**: <text>               CYCLE.inspiration      PR7
+# **Discovered**: <text>                CYCLE.discovered       PR8
+# **Verified**: <text>                  CYCLE.verified         PR9
+# **Next**: <text>                      CYCLE.next             PR10
+# **Context**: <text>                   CYCLE.context          PR11
+# (intent from Context)                 CONTEXT.intent         PT1
+# (constraints from Context)            CONTEXT.constraints    PT2
+# (unknowns from Context)               CONTEXT.unknowns       PT3
+# (scope from Context)                  CONTEXT.scope          PT4
+# ## Archived Cycles                    (implicit section)     —
+# - Cycle N (date): summary            ARCHIVE.summary        PA1
+#
+# Protocol references:
+#   phase: PH1-PH5 (protocol.yaml PHASES)
+#   type: conventional commit prefix (feat/fix/docs/refactor/chore/test)
+
+meta:
+  name: progress
+  version: "1.0.0"
+  description: >-
+    Cycle-by-cycle operational log. Produced by realisera. Consumed by
+    capabilities that need recent work history and verification evidence.
+  artifact_type: agent_facing
+  path: ".agentera/progress.yaml"
+  producer: realisera
+  consumers: [dokumentera, hej, inspektera, optimera, orkestrera, planera, realisera, visionera, visualisera]
+  format: yaml
+
+GROUP_PREFIXES:
+  BUDGET: PB
+  COMPACTION: PX
+  CYCLE: PR
+  CONTEXT: PT
+  ARCHIVE: PA
+  VALIDATION: PV
+
+BUDGET:
+  1:
+    id: PB1
+    scope: per_cycle_entry
+    max_words: 500
+    description: >-
+      Maximum words per cycle entry. Budgets are guidelines, not hard
+      blockers; a 510-word entry is fine, a 1200-word entry signals
+      missing output constraints.
+  2:
+    id: PB2
+    scope: full_file
+    max_words: 3000
+    description: >-
+      Maximum words for the full file. If a write would exceed this
+      budget, compact first (see COMPACTION group).
+
+COMPACTION:
+  1:
+    id: PX1
+    rule: uniform_10_40_50
+    description: >-
+      Growing artifacts follow a uniform 10/40/50 rule: 10 full-detail
+      entries, 40 one-line archive entries, drop beyond 50 total.
+  2:
+    id: PX2
+    full_detail:
+      max_entries: 10
+      selection: "10 most recent cycles"
+      format: "Standard cycle entry format (all fields)"
+    description: >-
+      The 10 most recent cycles are kept in full detail with all fields.
+  3:
+    id: PX3
+    one_line_archive:
+      max_entries: 40
+      selection: "Cycles 11 through 50"
+      format: "Cycle N (YYYY-MM-DD): <=15-word summary"
+      fields: [number, timestamp, summary]
+    description: >-
+      Cycles 11 through 50 are collapsed to one-line format under the
+      archive section. One-line summaries preserve cycle number, date,
+      and work-type, enough for trend analysis by consuming skills.
+  4:
+    id: PX4
+    dropped:
+      threshold: 50
+      action: "Removed entirely"
+    description: >-
+      Cycles older than 50 are dropped entirely.
+  5:
+    id: PX5
+    trigger: "When realisera writes a new cycle entry"
+    description: >-
+      Compaction runs when the producing skill writes a new entry.
+      If >10 full-detail entries exist, collapse the oldest to one-line.
+      If >40 one-line entries exist, drop the oldest.
+  6:
+    id: PX6
+    archive_section:
+      heading: "Archived Cycles"
+      placement: "Below recent cycles"
+    description: >-
+      Archive entries sit below the recent cycles section.
+
+CYCLE:
+  1:
+    id: PR1
+    field: number
+    type: integer
+    required: true
+    description: >-
+      Monotonically increasing cycle number. One greater than the
+      highest cycle number in active and archived entries. Do not
+      reuse or renumber except when repairing artifact corruption.
+    validation:
+      - "Must be a positive integer"
+      - "Must be unique across active and archived entries"
+      - "Must be one greater than the previous highest"
+  2:
+    id: PR2
+    field: timestamp
+    type: string
+    format: "YYYY-MM-DD HH:MM"
+    required: true
+    description: "When the cycle was recorded."
+    validation:
+      - "Must match YYYY-MM-DD HH:MM format"
+  3:
+    id: PR3
+    field: type
+    type: string
+    required: true
+    description: >-
+      Conventional commit prefix extracted from the work done.
+      One of: feat, fix, docs, refactor, chore, test.
+    validation:
+      - "Must be one of: feat, fix, docs, refactor, chore, test"
+  4:
+    id: PR4
+    field: phase
+    type: string
+    required: true
+    description: >-
+      Which ISS-19 phase the cycle belongs to. References protocol.yaml
+      PHASES (PH1-PH5).
+    protocol_ref: PHASES
+    validation:
+      - "Must be one of: envision, deliberate, plan, build, audit"
+  5:
+    id: PR5
+    field: what
+    type: string
+    required: true
+    description: "What was done in this cycle. Prose summary of work performed."
+    validation:
+      - "Non-empty string"
+  6:
+    id: PR6
+    field: commit
+    type: string
+    required: true
+    description: >-
+      Git commit that contains the product change for this cycle—not the commit
+      that last edited progress metadata. Use `pending` until that hash is known;
+      then the product commit hash, optionally with subject (e.g.
+      `abc1234 Speed up pytest suite`). Use `N/A: …` when no product commit was
+      made.
+    validation:
+      - "Non-empty string"
+      - "Use `pending` until the product-change commit hash is known; do not amend solely to backfill this field"
+      - >-
+        Hashes that do not resolve as commit objects in the local clone (another
+        machine's copy, shallow CI checkout, or not yet fetched) are intentionally
+        not flagged by progress validation or `agentera check backfill`; reconcile
+        with a full clone or forward-fill once the product commit exists locally
+  7:
+    id: PR7
+    field: inspiration
+    type: string
+    required: false
+    description: >-
+      What prompted this cycle. References to active plan tasks,
+      decisions, or conventions that drove the work.
+  8:
+    id: PR8
+    field: discovered
+    type: string
+    required: false
+    description: >-
+      Unexpected findings during the cycle. Things learned that were
+      not known before starting.
+  9:
+    id: PR9
+    field: verified
+    type: string
+    required: false
+    description: >-
+      Evidence that the work was verified. Test commands run, validation
+      passed, manual checks performed.
+  10:
+    id: PR10
+    field: next
+    type: string
+    required: false
+    description: >-
+      What should happen next. Guidance for subsequent cycles.
+      Explicit about scope boundaries to prevent scope creep.
+  11:
+    id: PR11
+    field: context
+    type: map
+    required: true
+    description: >-
+      Context envelope capturing intent, constraints, unknowns, and
+      scope for this cycle. Contains sub-fields defined in CONTEXT group.
+
+CONTEXT:
+  1:
+    id: PT1
+    field: intent
+    parent: CYCLE.context
+    type: string
+    required: true
+    description: "What this cycle set out to accomplish."
+  2:
+    id: PT2
+    field: constraints
+    parent: CYCLE.context
+    type: string
+    required: false
+    description: "Boundaries: what was explicitly out of scope or constrained."
+  3:
+    id: PT3
+    field: unknowns
+    parent: CYCLE.context
+    type: string
+    required: false
+    description: "Things not known at cycle start. May be 'none'."
+  4:
+    id: PT4
+    field: scope
+    parent: CYCLE.context
+    type: string
+    required: false
+    description: "Files and surfaces modified or affected."
+
+ARCHIVE:
+  1:
+    id: PA1
+    field: summary
+    type: string
+    required: true
+    description: >-
+      One-line archive entry for a compacted cycle. Format:
+      'Cycle N (YYYY-MM-DD): <=15-word summary'.
+      Preserves cycle number, date, and work-type for trend analysis.
+    validation:
+      - "Must include cycle number"
+      - "Must include date in YYYY-MM-DD format"
+      - "Summary portion must be <=15 words"
+
+VALIDATION:
+  1:
+    id: PV1
+    rule: unique_cycle_numbers
+    severity: error
+    description: >-
+      Active cycle entries must have unique numbers and remain descending
+      by cycle number, newest first. Do not reuse or renumber except when
+      repairing artifact corruption.
+    checks:
+      - "All cycle numbers are unique across active and archived entries"
+      - "Active entries are in descending order by cycle number"
+  2:
+    id: PV2
+    rule: required_fields
+    severity: error
+    description: >-
+      Each full-detail cycle entry must have: number, timestamp, type,
+      phase, what, commit, and context (with intent).
+    checks:
+      - "number is present and is a positive integer"
+      - "timestamp is present and matches YYYY-MM-DD HH:MM"
+      - "type is present and is a valid commit prefix"
+      - "phase is present and is a valid phase name"
+      - "what is present and non-empty"
+      - "commit is present"
+      - "context is present with intent sub-field"
+  3:
+    id: PV3
+    rule: compaction_thresholds
+    severity: warning
+    description: >-
+      Warn if the file exceeds compaction thresholds: >10 full-detail
+      entries or >40 one-line archive entries.
+    checks:
+      - "Full-detail entries <= 10"
+      - "One-line archive entries <= 40"
+      - "Total entries <= 50"
+  4:
+    id: PV4
+    rule: word_budget
+    severity: advisory
+    description: >-
+      Advisory check. Per-cycle entry should be <=500 words; full file
+      should be <=3000 words. Budgets are guidelines, not hard blockers.
+    checks:
+      - "Per-cycle word count <= 500"
+      - "Total file word count <= 3000"