@helmiq/crew 0.1.0

package/defaults/personas/architect.persona.yaml

@@ -0,0 +1,72 @@
+persona:
+  name: architect
+  identity:
+    role: 'Senior Solution Architect'
+  skills:
+    - adr-plan
+    - adr-write
+    - adr-review
+  perception:
+    always_read:
+      - artifact: standards
+        scope: { type: coding-standards }
+      - artifact: architecture
+        scope: { type: solution }
+    per_task:
+      adr-workflow:
+        - artifact: requirements
+          scope: { epic: '{{ .EPIC_ID }}' }
+        - artifact: adr-register
+          scope: {}
+  tasks:
+    adr-workflow:
+      mode: composite
+      trigger: [manual]
+      sub_agents:
+        - name: planner
+          skill: adr-plan
+          reads: [requirements, architecture, adr-register, codebase-structure]
+          produces: decision-plan
+          tools: [read-artifact, read-code]
+
+        - name: writer
+          skill: adr-write
+          reads: [decision-plan, requirements, architecture, adr-register]
+          produces: adr-drafts
+          tools: [read-artifact, write-artifact, read-code]
+
+        - name: reviewer
+          skill: adr-review
+          reads: [adr-drafts, architecture, adr-register]
+          produces: adr-review
+          tools: [read-artifact]
+          gate: 'all ADRs pass quality checks'
+          on_fail: writer
+          max_loops: 2
+
+      published_artifact: adr-summary
+      quality_gate: self-eval
+
+  tools:
+    permitted:
+      - read-artifact
+      - write-artifact
+      - read-code
+    denied:
+      - write-code
+      - git-write
+      - git-operations
+      - shell
+      - send-notifications
+      - write-strategy-artifacts
+    writable_paths:
+      - architecture/decisions/
+
+  cadence:
+    scheduled: []
+    event: []
+
+  evaluation:
+    self_eval_model: claude-sonnet
+    rubric: rubrics/adr.rubric.yaml
+    multi_model: false

package/defaults/personas/engineer.persona.yaml

@@ -0,0 +1,137 @@
+# Engineer Persona Specification
+
+persona:
+  name: engineer
+
+  identity:
+    role: 'Senior Software Engineer'
+
+  skills:
+    - feature-implement
+    - code-implement
+    - implementation-plan
+    - code-review
+    - quality-check
+    - test-write
+    - self-review
+    - pr-author
+
+  perception:
+    always_read:
+      - artifact: standards
+        scope: { type: coding-standards }
+      - artifact: backlog
+        scope: { status: ready }
+
+    per_task:
+      implement-story:
+        - artifact: requirements
+          scope: { epic: '{{ .EPIC_ID }}' }
+        - artifact: design
+          scope: { epic: '{{ .EPIC_ID }}' }
+        - artifact: codebase
+          scope: { paths: '{{ .RELEVANT_PATHS }}' }
+
+      address-feedback:
+        - artifact: review
+          scope: { story: '{{ .STORY_ID }}' }
+        - artifact: codebase
+          scope: { paths: '{{ .RELEVANT_PATHS }}' }
+
+  tasks:
+    implement-story:
+      mode: composite
+      trigger: [manual, scheduled]
+      sub_agents:
+        - name: planner
+          skill: implementation-plan
+          reads: [requirements, design, codebase-structure]
+          produces: implementation-plan
+          tools: [read-artifact]
+
+        - name: implementer
+          skill: code-implement
+          reads: [implementation-plan, codebase]
+          produces: code-changes
+          tools: [code, git, shell]
+
+        - name: test-writer
+          skill: test-write
+          reads: [code-changes, requirements]
+          produces: test-files
+          tools: [code, git, shell]
+
+        - name: quality-checker
+          skill: quality-check
+          reads: [code-changes, test-files]
+          produces: quality-report
+          tools: [shell, code, git]
+          max_iterations: 3
+
+        - name: self-reviewer
+          skill: self-review
+          reads: [code-changes, design, standards]
+          produces: self-review
+          gate: 'no blocking issues'
+          on_fail: implementer
+          max_loops: 2
+
+        - name: pr-author
+          skill: pr-author
+          reads: [code-changes, requirements, self-review]
+          produces: pull-request
+          tools: [git]
+
+      published_artifact: pull-request
+      quality_gate: human-review
+
+    address-feedback:
+      mode: composite
+      trigger: [manual, event]
+      sub_agents:
+        - name: feedback-reader
+          skill: code-review
+          reads: [review, code-changes]
+          produces: feedback-plan
+
+        - name: implementer
+          skill: code-implement
+          reads: [feedback-plan, codebase]
+          produces: code-changes
+          tools: [code, git, shell]
+
+        - name: quality-checker
+          skill: quality-check
+          reads: [code-changes]
+          produces: quality-report
+          tools: [shell, code, git]
+          max_iterations: 3
+
+      published_artifact: code-changes
+      quality_gate: self-eval
+
+  tools:
+    permitted:
+      - read-artifact
+      - write-artifact
+      - code
+      - git-operations
+      - shell
+      - read-delivery-signals
+    denied:
+      - write-strategy-artifacts
+      - write-standards
+      - send-notifications
+
+  cadence:
+    scheduled:
+      - cron: '0 9 * * 1-5'
+        task: implement-story
+    event:
+      - on: review-feedback-received
+        task: address-feedback
+
+  evaluation:
+    self_eval_model: claude-sonnet
+    rubric: rubrics/pull-request.rubric.yaml
+    multi_model: false

package/defaults/personas/persona-spec.schema.yaml

@@ -0,0 +1,149 @@
+# Persona Specification Schema
+#
+# Defines the structure for all persona YAML files. A persona is a fully
+# specified delivery role with identity, skills, perception, tasks, tools,
+# cadence, and evaluation. Skills from `@helmiq/crew-skills` supply prompt content
+# resolved at load time.
+
+schema:
+  name: persona-spec
+  version: '0.1'
+
+# Top-level structure
+# persona:
+#   name: string (required)       Unique persona identifier
+#   identity: Identity (required)
+#   skills: array[string] (required)
+#   perception: Perception (required)
+#   tasks: map[string, Task] (required)
+#   tools: ToolPermissions (required)
+#   cadence: Cadence (required)
+#   evaluation: EvaluationConfig (required)
+
+fields:
+  # Identity -- who the persona is
+  persona.name:
+    type: string
+    required: true
+    description: >
+      Unique persona identifier (e.g., "engineer", "reviewer", "pm").
+      Used as the key for config resolution and run metadata.
+
+  persona.identity.role:
+    type: string
+    required: true
+    description: Human-readable role title (e.g., "Senior Software Engineer").
+
+  # Skills -- prompt content from @helmiq/crew-skills
+  persona.skills:
+    type: array[string]
+    required: true
+    description: >
+      Skill names from the `@helmiq/crew-skills` package that this persona uses.
+      The runtime resolves each skill name to its `.prompt.md` content at load time.
+
+  # Perception -- what artifacts the persona reads
+  persona.perception.always_read:
+    type: array[ContextRef]
+    required: false
+    description: Artifacts read on every task regardless of task type.
+
+  persona.perception.per_task:
+    type: map[string, array[ContextRef]]
+    required: true
+    description: >
+      Per-task context scope declarations. Keys are task names defined
+      in persona.tasks; values are arrays of ContextRef.
+
+  # ContextRef structure:
+  #   artifact: string (required)   Artifact type identifier
+  #   scope: map[string, string]    Scope filters; values may use {{ .VAR }} per ADR-0002
+  #   sections: array[string]       Named sections to extract
+  #   when: string                  Conditional expression evaluated at runtime
+
+  # Tasks -- what the persona can do
+  # Each task is either simple (single LLM call) or composite (sub-agent chain).
+
+  # Simple task fields:
+  #   mode: "simple" (required)
+  #   trigger: array[TriggerType] (required)    manual | scheduled | event
+  #   skill: string (required)                 Skill name (resolved to .prompt.md in @helmiq/crew-skills)
+  #   reads: array[string]                      Named artifacts this task reads
+  #   produces: string (required)               Named artifact this task outputs
+  #   tools: array[string]                      Tool subset (restricts persona-level)
+  #   published_artifact: string                Which output is published
+  #   quality_gate: QualityGateType             self-eval | human-review | multi-model
+
+  # Composite task fields (per ADR-0001):
+  #   mode: "composite" (required)
+  #   trigger: array[TriggerType] (required)
+  #   sub_agents: array[SubAgent] (required)    Ordered pipeline
+  #   published_artifact: string (required)     Which sub-agent output is published
+  #   quality_gate: QualityGateType
+
+  # SubAgent fields (per ADR-0001):
+  #   name: string (required)          Unique within the task
+  #   skill: string (required)         Skill name (resolved to .prompt.md in @helmiq/crew-skills)
+  #   reads: array[string] (required)  Named artifacts or work products
+  #   produces: string (required)      Named work product
+  #   tools: array[string]             Tool subset; inherits persona.tools.permitted if omitted
+  #   max_iterations: integer          Retry count on failure
+  #   gate: string                     Gate condition after completion
+  #   on_fail: string                  Jump-back target (must reference earlier sub-agent name)
+  #   max_loops: integer               Cap on jump-back cycles
+
+  # Tools -- security boundary
+  persona.tools.permitted:
+    type: array[string]
+    required: true
+    description: Tools this persona may use. Only these are provided to the LLM.
+
+  persona.tools.denied:
+    type: array[string]
+    required: true
+    description: Tools explicitly denied. Never provided to the LLM regardless of prompt.
+
+  # Cadence -- when the persona runs
+  persona.cadence.scheduled:
+    type: array[ScheduleEntry]
+    required: false
+    description: Cron-triggered tasks.
+    # ScheduleEntry: { cron: string, task: string }
+
+  persona.cadence.event:
+    type: array[EventEntry]
+    required: false
+    description: Event-triggered tasks.
+    # EventEntry: { on: string, task: string }
+
+  # Evaluation -- quality assurance
+  persona.evaluation.self_eval_model:
+    type: string
+    required: false
+    description: >
+      Model alias for self-evaluation. Overrides the project default model
+      in Phase 1; overrides the activity default per ADR-0003 hierarchy
+      in later phases.
+
+  persona.evaluation.rubric:
+    type: string
+    required: true
+    description: File path to the evaluation rubric.
+
+  persona.evaluation.multi_model:
+    type: boolean
+    required: false
+    default: false
+    description: Enable multi-model evaluation (Phase 5).
+
+# Validation constraints (enforced by Zod in Epic 1)
+constraints:
+  - on_fail must reference a name earlier in the sub_agents array (no forward jumps, no self-reference)
+  - tools in a sub-agent must be a subset of persona.tools.permitted
+  - evaluation.self_eval_model must be a model alias in the project LLM provider registry
+  - template variables ({{ .VAR }}) are only permitted in scope values, sections, and sub-agent reads
+  - all skill names in persona.skills, task skill, and sub-agent skill must resolve to a .prompt.md file in the skills package
+
+enums:
+  TriggerType: [manual, scheduled, event]
+  QualityGateType: [self-eval, human-review, multi-model]

package/defaults/personas/reviewer.persona.yaml

@@ -0,0 +1,47 @@
+persona:
+  name: reviewer
+  identity:
+    role: 'Senior Code Reviewer'
+  skills:
+    - code-review
+  perception:
+    always_read:
+      - artifact: standards
+        scope: { type: coding-standards }
+    per_task:
+      review-pr:
+        - artifact: pr-diff
+          scope: { story: '{{ .STORY_ID }}' }
+        - artifact: design
+          scope: { epic: '{{ .EPIC_ID }}' }
+        - artifact: requirements
+          scope: { epic: '{{ .EPIC_ID }}' }
+        - artifact: review
+          scope: { story: '{{ .STORY_ID }}' }
+          when: 're-review'
+  tasks:
+    review-pr:
+      mode: simple
+      trigger: [manual, event]
+      skill: code-review
+      produces: review-report
+      tools: [read-artifact, read-code, git-read, shell]
+      quality_gate: self-eval
+  tools:
+    permitted:
+      - read-artifact
+      - write-artifact
+      - read-code
+      - git-read
+      - shell
+    denied:
+      - write-code
+      - git-write
+  cadence:
+    event:
+      - on: pr-created
+        task: review-pr
+  evaluation:
+    self_eval_model: claude-sonnet
+    rubric: rubrics/code-review.rubric.yaml
+    multi_model: false

package/defaults/rubrics/adr.rubric.yaml

@@ -0,0 +1,48 @@
+# Architecture Decision Record Evaluation Rubric
+
+rubric:
+  artifact_type: adr-summary
+  scoring_scale: 10
+  pass_threshold: 7
+
+  criteria:
+    - name: ADRs follow project template
+      weight: blocking
+      description: >
+        Each ADR follows the structure in architecture/decisions/adr-template.md:
+        context and problem statement, decision drivers, considered options,
+        decision outcome with rationale, consequences, and confirmation method.
+        Score 7+ if template structure is complete. Score below 7 if any
+        required section is missing or empty.
+
+    - name: Options analysis is balanced
+      weight: blocking
+      description: >
+        Each ADR presents at least two genuinely distinct options with
+        substantive pros and cons. The analysis does not set up a straw-man
+        for the preferred option. Score 7+ if options are balanced and
+        viable. Score below 7 if analysis is one-sided or options are trivially
+        different.
+
+    - name: Rationale is justified by analysis
+      weight: blocking
+      description: >
+        The decision outcome follows logically from the stated decision
+        drivers and options analysis. The rationale references specific
+        pros/cons that drove the choice, not just assertions. Score 7+ if
+        rationale is evidence-based. Score below 7 if the decision feels
+        predetermined or unjustified.
+
+    - name: Consequences are documented
+      weight: important
+      description: >
+        Both positive consequences (benefits) and negative consequences
+        (trade-offs) are documented. Consequences are specific to the project,
+        not generic. Score 7+ if consequences are concrete and actionable.
+
+    - name: No contradictions with existing ADRs
+      weight: important
+      description: >
+        New ADRs do not contradict existing accepted ADRs without explicitly
+        noting the supersession. Related ADRs are referenced where applicable.
+        Score 7+ if consistent. Score below 7 if contradictions exist.

package/defaults/rubrics/code-review.rubric.yaml

@@ -0,0 +1,39 @@
+# Code Review Evaluation Rubric
+
+rubric:
+  artifact_type: code-review
+  scoring_scale: 10
+  pass_threshold: 7
+
+  criteria:
+    - name: Acceptance criteria addressed
+      weight: blocking
+      description: >
+        The review verifies whether the PR satisfies all acceptance criteria
+        from the story. Score 7+ if coverage is thorough. Score below 7 if
+        acceptance criteria are not checked.
+
+    - name: Blocking issues are substantive
+      weight: blocking
+      description: >
+        Any blocking findings identify real defects or standard violations,
+        not stylistic preferences. Score 7+ if findings are substantive.
+        Score below 7 if blocking issues are trivial or unsubstantiated.
+
+    - name: Verdict is justified
+      weight: blocking
+      description: >
+        The approve/changes-requested verdict is supported by the findings.
+        Score 7+ if the verdict logically follows from the review content.
+
+    - name: Suggestions are actionable
+      weight: important
+      description: >
+        Non-blocking suggestions include enough context for the engineer
+        to act on them without further clarification.
+
+    - name: Review covers design compliance
+      weight: advisory
+      description: >
+        The review checks whether the implementation matches the technical
+        design and architecture decisions.

package/defaults/rubrics/pull-request.rubric.yaml

@@ -0,0 +1,40 @@
+# Pull Request Evaluation Rubric
+
+rubric:
+  artifact_type: pull-request
+  scoring_scale: 10
+  pass_threshold: 7
+
+  criteria:
+    - name: Tests cover acceptance criteria
+      weight: blocking
+      description: >
+        All acceptance criteria from the story have corresponding test cases.
+        Score 7+ if coverage is complete. Score below 7 if any acceptance
+        criterion lacks a test.
+
+    - name: Code follows existing patterns
+      weight: blocking
+      description: >
+        Implementation follows the codebase's established architecture,
+        naming conventions, and module structure. Score 7+ if patterns are
+        respected. Score below 7 if the code introduces inconsistent
+        approaches.
+
+    - name: No security vulnerabilities introduced
+      weight: blocking
+      description: >
+        No secrets in code, no unsafe input handling, no new attack surfaces.
+        Score 7+ if clean. Score below 7 if any security concern is found.
+
+    - name: PR description links to story and design
+      weight: important
+      description: >
+        PR description references the story ID, acceptance criteria, and
+        relevant design decisions. Score 7+ if traceability is clear.
+
+    - name: Code is readable and maintainable
+      weight: advisory
+      description: >
+        Code is well-structured, appropriately commented where non-obvious,
+        and easy to understand for a new contributor.

package/dist/actions/actions.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=actions.test.d.ts.map

package/dist/actions/actions.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.test.d.ts","sourceRoot":"","sources":["../../src/actions/actions.test.ts"],"names":[],"mappings":""}