@kontourai/flow-agents 0.1.1

package/console.telemetry.json

@@ -0,0 +1,176 @@
+{
+  "schema_version": "1.0",
+  "product": {
+    "id": "flow-agents",
+    "name": "Flow Agents"
+  },
+  "recordSources": [
+    {
+      "id": "flow-agents-workflow-state",
+      "label": "Workflow state",
+      "root": "product:flow-agents:.flow-agents",
+      "files": ["state.json"],
+      "attributes": {
+        "taskSlug": "task_slug",
+        "repo": "repo",
+        "project": "project",
+        "runtime": "runtime",
+        "flow": "flow_id",
+        "skill": "skill_id",
+        "agent": "agent_id",
+        "model": "model",
+        "status": "status",
+        "phase": "phase",
+        "outcome": "outcome",
+        "title": "summary",
+        "observedAt": "updated_at"
+      }
+    },
+    {
+      "id": "flow-agents-acceptance",
+      "label": "Acceptance criteria",
+      "root": "product:flow-agents:.flow-agents",
+      "files": ["acceptance.json"],
+      "attributes": {
+        "taskSlug": "task_slug",
+        "repo": "repo",
+        "project": "project",
+        "flow": "flow_id",
+        "skill": "skill_id",
+        "status": "status",
+        "outcome": "goal_fit.status",
+        "title": "summary",
+        "observedAt": "updated_at"
+      }
+    },
+    {
+      "id": "flow-agents-evidence",
+      "label": "Verification evidence",
+      "root": "product:flow-agents:.flow-agents",
+      "files": ["evidence.json"],
+      "attributes": {
+        "taskSlug": "task_slug",
+        "repo": "repo",
+        "project": "project",
+        "runtime": "runtime",
+        "flow": "flow_id",
+        "skill": "skill_id",
+        "agent": "verifier.agent_id",
+        "model": "verifier.model",
+        "status": "verdict",
+        "outcome": "verdict",
+        "title": "summary",
+        "observedAt": "updated_at"
+      }
+    },
+    {
+      "id": "flow-agents-handoffs",
+      "label": "Handoffs",
+      "root": "product:flow-agents:.flow-agents",
+      "files": ["handoff.json"],
+      "attributes": {
+        "taskSlug": "task_slug",
+        "repo": "repo",
+        "project": "project",
+        "runtime": "runtime",
+        "flow": "flow_id",
+        "skill": "skill_id",
+        "agent": "agent_id",
+        "model": "model",
+        "status": "next_action.status",
+        "outcome": "status",
+        "title": "summary",
+        "observedAt": "updated_at"
+      }
+    },
+    {
+      "id": "flow-agents-learning",
+      "label": "Learning records",
+      "root": "product:flow-agents:.flow-agents",
+      "files": ["learning.json"],
+      "attributes": {
+        "taskSlug": "task_slug",
+        "repo": "repo",
+        "project": "project",
+        "flow": "flow_id",
+        "skill": "skill_id",
+        "status": "status",
+        "title": "summary",
+        "observedAt": "updated_at"
+      }
+    }
+  ],
+  "facets": [
+    { "id": "skills", "label": "Skills", "attribute": "skill", "limit": 16 },
+    { "id": "tools", "label": "Tools", "attribute": "toolName", "limit": 16 },
+    { "id": "flows", "label": "Flows", "attribute": "flow", "limit": 16 },
+    { "id": "repositories", "label": "Repositories", "attribute": "repo", "limit": 16 },
+    { "id": "projects", "label": "Projects", "attribute": "project", "limit": 16 },
+    { "id": "runtimes", "label": "Runtimes", "attribute": "runtime", "limit": 12 },
+    { "id": "agents", "label": "Agents", "attribute": "agent", "limit": 16 },
+    { "id": "models", "label": "Models", "attribute": "model", "limit": 16 },
+    { "id": "statuses", "label": "Statuses", "attribute": "status", "limit": 12 },
+    { "id": "outcomes", "label": "Outcomes", "attribute": "outcome", "limit": 12 }
+  ],
+  "flows": [
+    {
+      "id": "builder.shape",
+      "label": "Builder shape",
+      "match": { "attribute": "flow", "includes": "builder.shape" },
+      "titleAttribute": "title",
+      "detailAttributes": {
+        "Project": "project",
+        "Repository": "repo",
+        "Task": "taskSlug",
+        "Status": "status",
+        "Outcome": "outcome",
+        "Phase": "phase",
+        "Skill": "skill",
+        "Agent": "agent",
+        "Model": "model",
+        "Observed": "observedAt"
+      },
+      "limit": 10
+    },
+    {
+      "id": "builder.build",
+      "label": "Builder build",
+      "match": { "attribute": "flow", "includes": "builder.build" },
+      "titleAttribute": "title",
+      "detailAttributes": {
+        "Project": "project",
+        "Repository": "repo",
+        "Task": "taskSlug",
+        "Status": "status",
+        "Outcome": "outcome",
+        "Phase": "phase",
+        "Skill": "skill",
+        "Agent": "agent",
+        "Model": "model",
+        "Observed": "observedAt"
+      },
+      "limit": 10
+    },
+    {
+      "id": "delivery",
+      "label": "Delivery workflows",
+      "match": { "attribute": "skill", "includes": "deliver" },
+      "titleAttribute": "title",
+      "limit": 10
+    },
+    {
+      "id": "verification",
+      "label": "Verification workflows",
+      "match": { "attribute": "skill", "includes": "verify-work" },
+      "titleAttribute": "title",
+      "limit": 10
+    },
+    {
+      "id": "review",
+      "label": "Review workflows",
+      "match": { "attribute": "skill", "includes": "review-work" },
+      "titleAttribute": "title",
+      "limit": 10
+    }
+  ]
+}

package/context/base-rules.md

@@ -0,0 +1,17 @@
+# Base Agent Rules
+
+The following are rules that ALL agents should follow, regardless of specialty. These apply across all projects!
+
+## Guidance
+- If useful in the future, consider adding a note to the agents memory file (AGENTS.md) for the given project. If the content is repeatable debugging steps, consider detailing the approach in separate documentation (ie docs/<approach>.md) and linking to it with a description from the memory file (ie. AGENTS.md)
+
+
+## Guardrails
+- NEVER guess at syntax or APIs — look it up or research it using available tools or specialized agents (ListAgents).
+- ALWAYS assume your training data is outdated. Confirm your knowledge with available tools (ie. web) to ensure information is up-to-date.
+- NEVER take destructive git actions without checking history (ie. `git diff` -- if available) first OR ensuring files are recoverable from source control in their current state -- use minimal roll backs via source control or ensure files are fully in context for immediate recovery if no source control is available
+- NEVER remove code just to make things compile UNLESS part of a larger TODO plan that will bring it back - if you cannot complete a task as described surface that to the user
+- NEVER "fallback" to a simpler implementation just to keep moving forward. ALWAYS check with the user before recommending "simpler" solutions because of repeated issues caused in trying to accomplish the task at hand
+- ALWAYS cleanup any temporary files or configurations created for debugging purposes. 
+- ALWAYS check with user before committing IF there are any doubts about what should or should not be considered safe in the STAGED changes in source control
+- ALWAYS plan a given task for completeness as well as prioritized for parallelization. If tasks can be independently executed, run them in parallel 

package/context/code-review-standards.md

@@ -0,0 +1,62 @@
+# Code Review Standards
+
+Standards for ALL agents to follow when reviewing or writing code.
+
+## Review Checklist
+
+- [ ] Readable, well-named variables/functions
+- [ ] Functions < 50 lines
+- [ ] Files < 800 lines
+- [ ] Nesting < 4 levels
+- [ ] Errors handled at every level — never silently swallowed
+- [ ] No hardcoded secrets or credentials
+- [ ] No debug statements (`console.log`, `debugger`, `print`)
+- [ ] Tests exist for new/changed logic
+- [ ] Coverage >= 80%
+
+## Severity Levels
+
+| Severity | Scope | Action |
+|---|---|---|
+| CRITICAL | Security vulnerabilities, data loss, auth bypass | BLOCK — must fix before merge |
+| HIGH | Bugs, broken logic, missing error handling | WARN — should fix before merge |
+| MEDIUM | Maintainability, duplication, unclear naming | INFO — fix when practical |
+| LOW | Style, formatting, minor conventions | NOTE — optional |
+
+## Mandatory Review Triggers
+
+- After writing or modifying code
+- Before commits to shared branches
+- Security-sensitive changes (auth, payments, user data)
+- Architectural changes (new services, schema changes, API contracts)
+
+## Security Review Triggers
+
+Review with extra scrutiny when changes touch:
+- Authentication / authorization logic
+- User input handling or validation
+- Database queries (especially dynamic/constructed)
+- File system operations
+- External API calls or webhook handlers
+- Cryptographic operations
+- Payment or billing code
+
+## Common Issues to Catch
+
+### Security
+- Hardcoded credentials or API keys
+- SQL injection (unsanitized input in queries)
+- XSS (unescaped user content in HTML)
+- Path traversal (unsanitized file paths)
+- CSRF (missing token validation on state-changing requests)
+
+### Code Quality
+- Functions or files exceeding size limits
+- Deep nesting (> 4 levels) — extract helper functions
+- Missing error handling or silent catch blocks
+- Direct mutation of shared state — use immutable patterns
+
+### Performance
+- N+1 queries — batch or join instead
+- Missing pagination on list endpoints
+- Unbounded queries (no LIMIT, no max results)

package/context/coding-standards.md

@@ -0,0 +1,42 @@
+# Coding Standards
+
+Standards for ALL agents to follow when writing code.
+
+## Immutability
+
+Always create new objects — never mutate existing ones.
+- Prevents side effects and hidden state bugs
+- Safe for concurrent access without locks
+- Use spread operators, `Object.freeze`, or immutable data structures
+
+## File Organization
+
+- Many small files > few large files
+- Typical file: 200–400 lines. Hard max: 800 lines
+- Organize by feature/domain, not by type (e.g., `auth/` not `controllers/`)
+- One export per file when practical — colocate related helpers
+
+## Error Handling
+
+- Handle errors at every level — never silently swallow
+- UI: user-friendly messages, no stack traces
+- Server-side: detailed context (what failed, input state, upstream cause)
+- Fail fast on unrecoverable errors — don't limp along with bad state
+- Always clean up resources (connections, file handles) in finally blocks
+
+## Input Validation
+
+- Validate at system boundaries (API endpoints, CLI args, file reads, external data)
+- Use schema-based validation where available (Zod, JSON Schema, etc.)
+- Fail fast with clear error messages — include what was wrong and what's expected
+- Never trust external data — validate type, range, format, and length
+
+## Code Quality Checklist
+
+- [ ] Readable, well-named (variables, functions, files)
+- [ ] Functions < 50 lines
+- [ ] Files < 800 lines
+- [ ] Nesting < 4 levels deep
+- [ ] Errors handled properly at every level
+- [ ] No hardcoded values (secrets, URLs, magic numbers)
+- [ ] Immutable patterns used — no direct mutation of shared state

package/context/common/orchestrators.md

@@ -0,0 +1,12 @@
+# Orchestrator Agents
+
+You are an orchestrator agent designed for tasks that require a human-in-the-loop. 
+
+ALWAYS keep strict adherence to the following.
+
+## Guidelines
+- Be honest about your limitations rather than producing mediocre results.
+- IF the user asks about functionality that you don't have access to, list the available subagents to see if we can delegate the request. NEVER assume you have access to a subagent without first looking at your available subagents.
+- ALWAYS be thorough! Remember, you are the brains of the operation
+  - When opportunities arise to parallelize instructions to a subagent make a plan. 
+  - Don't immediately give up until multiple avenues have been explored and let the user know what you tried and why, including any relevant citations

package/context/common/subagents.md

@@ -0,0 +1,28 @@
+# Subagent Guidelines
+
+You are a subagent — a specialist invoked by an orchestrator to complete a focused task. Follow these rules strictly.
+
+## No Guessing
+- NEVER fabricate, assume, or infer information you don't have
+- If your tools return no results, say so — do not fill gaps with speculation
+- If the orchestrator's request is ambiguous or missing critical details, push back immediately with a clear description of what you need before proceeding
+
+## Insufficient Context Handoff
+When the orchestrator has not provided enough detail to complete the task:
+1. Do NOT attempt a partial or best-effort answer
+2. Respond with exactly what is missing and why you need it
+3. If the missing context is something the orchestrator should already have, say so directly
+
+Example: "I cannot complete this request — I need the account name and time period to search. Please provide these and re-delegate."
+
+## Out-of-Scope Requests
+If the request falls outside your area of expertise:
+1. State clearly that the request is outside your scope
+2. Suggest which type of agent would be better suited (if you know)
+3. Do NOT attempt the work anyway
+
+## Response Quality
+- Be concise and factual
+- Include dates and sources when available
+- Structure responses so the orchestrator can act on them immediately
+- If results are partial, clearly label what was found vs what was not

package/context/contracts/artifact-contract.md

@@ -0,0 +1,182 @@
+# Workflow Artifact Contract
+
+Workflow artifacts are the durable handoff surface between orchestrators, workers, verifiers, hooks, evals, and future sessions.
+
+## Artifact Root
+
+Use the task artifact root defined by the active distribution's bundle instructions. This source repo has a historical default task root, but distributions may substitute their own root during export.
+
+Do not hard-code a different root inside a skill or agent when the distribution has already defined one.
+
+In this source tree, `.flow-agents/<slug>/` is the local runtime/session state root by default. Exported agent bundles may map the runtime root to a distribution-specific path through their bundle instructions; treat those paths as local runtime roots, not durable product documentation.
+
+The artifact root is local working memory unless a workflow explicitly promotes or publishes it:
+
+- Keep active plans, handoffs, sidecars, temporary evidence, verifier notes, and parallel-worker progress in the runtime root.
+- When in-progress planning must be reviewable across people or sessions, promote the durable summary, decisions, and evidence pointers into docs, source, schemas, or provider records.
+- Archive completed local records under `<artifact-root>/<slug>/archive/<date>/` when they are useful for audit or recovery but should not remain the active session.
+- Promote stable decisions, usage guidance, release notes, and accepted architecture changes into durable docs such as `docs/`, ADRs, changelogs, or provider-backed descriptions/comments.
+- Publish provider records only through the provider adapter or explicit publish-change step. Provider records may link back to local artifacts, but they do not make local runtime files durable by themselves.
+- Do not commit local workflow runtime roots such as `.flow-agents/<slug>/` as durable policy unless a repository-specific contract explicitly says that artifact is promoted.
+- Do not commit local workflow runtime roots such as `.flow-agents/<slug>/`; final acceptance must promote durable content before merge.
+
+## Required Artifact Types
+
+### Structured Sidecars
+
+Markdown artifacts remain the human-readable handoff surface. JSON sidecars are the machine-readable recovery and gate surface. When a workflow creates or updates the corresponding information, write the sidecar beside the Markdown artifacts in `.flow-agents/<slug>/`.
+
+Draft sidecars:
+
+- `state.json` follows `schemas/workflow-state.schema.json`
+- `acceptance.json` follows `schemas/workflow-acceptance.schema.json`
+- `evidence.json` follows `schemas/workflow-evidence.schema.json`
+- `handoff.json` follows `schemas/workflow-handoff.schema.json`
+- `critique.json` follows `schemas/workflow-critique.schema.json`
+- `release.json` follows `schemas/workflow-release.schema.json`
+- `learning.json` follows `schemas/workflow-learning.schema.json`
+
+Sidecar rules:
+
+- Keep `schema_version` at `1.0` until the schema changes incompatibly.
+- Keep `task_slug` stable across all sidecars for a workflow.
+- Prefer `npm run workflow:sidecar --` for creating and updating sidecars. If a harness cannot run the writer, produce equivalent JSON and validate it with `npm run workflow:validate-artifacts --`.
+- Use `npm run workflow:sidecar -- ensure-session` when available to create or select the current `.flow-agents/<slug>/` session artifact before substantial work starts.
+- Update `state.json` at phase transitions.
+- Create or update `acceptance.json` when planning defines or changes acceptance criteria.
+- Create or update `evidence.json` when verification or evidence-gate records proof.
+- Create or update `handoff.json` when work pauses, blocks, delegates, or hands off to a future session.
+- Use `npm run workflow:sidecar -- advance-state` when available to keep `state.json` and `handoff.json` synchronized during phase transitions.
+- Runtime `state.json` and `handoff.json` writes from the sidecar writer must pass through the transition guard. Flow owns transition semantics; Flow Agents enforces runtime sidecar transitions through an interim Flow Definition-compatible adapter until Flow core provides the authoritative validator.
+- Rejected runtime transitions must fail closed before mutating `state.json` or `handoff.json` and should append diagnostics to `transition-diagnostics.jsonl` beside the workflow sidecars. Route-back attempt counts, when applicable, belong in `transition-attempts.json` rather than `state.json`.
+- Create or update the configured critique artifact/sink when a reviewer, critique subagent, or human review pass evaluates the workflow; locally this is materialized as `critique.json`.
+- Create or update `release.json` when release-readiness records a merge, release, deploy, hold, or rollback decision.
+- Create or update `learning.json` when a learning review turns completed work, repeated friction, or accepted critique into system improvements.
+- Do not let sidecars silently contradict the Markdown artifact. If they disagree, the sidecar is the machine-readable gate input and the Markdown summary should be corrected.
+- Record `NOT_VERIFIED` in sidecars as `not_verified`; do not omit uncertain checks.
+- For substantial work, critique findings must be `fixed`, `accepted`, `deferred`, or `false_positive` before marking critique `pass`; open findings block a pass.
+- Treat sidecars as authoritative gate inputs. Temporary verifier-local mismatch notes are observations only; before terminal delivery, the orchestrator must update or reconcile `acceptance.json`, `evidence.json`, `release.json`, and the final Markdown summary so stale mismatch notes are superseded by final evidence or release validation.
+
+Evidence reference rules:
+
+- `acceptance.criteria[].evidence_refs`, `evidence.checks[].artifact_refs`, and `evidence.external_evidence[].ref` use structured evidence reference objects. Legacy bare strings are not part of the schema contract.
+- Every evidence reference has `kind`; allowed kinds are `source`, `command`, `artifact`, `provider`, and `external`.
+- Source evidence references identify the code or documentation that supports an implementation-behavior claim and include `file`, `line_start`, `line_end`, and `excerpt`. Include `url` when a provider permalink is known.
+- Provider source URLs should be immutable GitHub blob URLs pinned to a commit SHA, for example `https://github.com/<owner>/<repo>/blob/<commit-sha>/<path>#L12-L24`. Do not use branch-relative blob URLs for final provider, PR, issue, closure, or release comments.
+- Before a commit/provider permalink exists, local `file` plus line fields and `excerpt` are acceptable temporary evidence. Evidence Gate should treat those refs as publish-change inputs and prefer upgrading them to immutable provider URLs before release or closure.
+- Command and test proof may use `kind: "command"` with `excerpt`, `summary`, or `url` for the relevant log/artifact. Behavior acceptance claims should cite both command/test proof and source evidence unless source evidence is not applicable.
+- If source evidence is not applicable, record the reason as a gap, `not_verified`, or accepted gap rather than replacing source evidence with broad prose.
+
+Provider, PR, issue, closure, and final acceptance comments that claim implementation behavior must include an `Acceptance Evidence` table:
+
+| AC id | Status | Command/Test Evidence | Source Evidence / Permalinks | Gaps |
+| --- | --- | --- | --- | --- |
+
+Each row maps one acceptance criterion id to its status, concrete command/test evidence, source refs or immutable provider permalinks, and any `NOT_VERIFIED` or accepted gaps. A prose-only summary is not enough for clean closure when behavior is claimed.
+
+Canonical vocabulary:
+
+`state.phase` is the canonical lifecycle vocabulary for machine-readable workflow state. It does not include review as a phase; review-work is represented by the required critique artifact/sink for the workflow, with `critique.json` as the current local sidecar materialization.
+
+| Field | Values |
+| --- | --- |
+| `state.status` | `new`, `planning`, `planned`, `in_progress`, `blocked`, `verifying`, `verified`, `needs_decision`, `not_verified`, `failed`, `delivered`, `accepted`, `archived` |
+| `state.phase` | `idea`, `backlog`, `pickup`, `planning`, `execution`, `verification`, `goal_fit`, `evidence`, `release`, `learning`, `done` |
+| `next_action.status` | `continue`, `needs_user`, `blocked`, `done` |
+| `acceptance.criteria[].status` | `pending`, `pass`, `fail`, `not_verified`, `accepted_gap` |
+| `acceptance.goal_fit.status` | `pending`, `pass`, `fail`, `not_verified`, `accepted_gap` |
+| `evidence.verdict` | `pass`, `partial`, `fail`, `not_verified` |
+| `evidence.checks[].status` | `pass`, `fail`, `not_verified`, `skip` |
+| `critique.status` | `pending`, `pass`, `fail`, `not_required` |
+| `critique.critiques[].verdict` | `pass`, `comment`, `fail`, `not_verified` |
+| `critique.critiques[].findings[].severity` | `critical`, `high`, `medium`, `low`, `info` |
+| `critique.critiques[].findings[].status` | `open`, `accepted`, `fixed`, `deferred`, `false_positive` |
+| `learning.status` | `pending`, `learned`, `followup_required`, `blocked` |
+| `learning.records[].outcome` | `success`, `failure`, `mixed`, `unknown` |
+| `learning.records[].routing[].target` | `rule`, `skill`, `power`, `agent`, `eval`, `doc`, `backlog`, `knowledge`, `none` |
+| `release.decision` | `merge`, `release`, `deploy`, `hold`, `rollback_required` |
+| `release.gates[].status` | `pass`, `hold`, `not_required`, `not_verified` |
+| `release.rollback_plan.status` | `ready`, `not_required`, `missing` |
+
+Sidecar ownership by phase:
+
+- Planning owns initial `state.json`, `acceptance.json`, and `handoff.json`.
+- Execution updates progress in the Markdown session artifact and uses `advance-state` when available to update `state.json` or `handoff.json` when work blocks, pauses, or changes phase.
+- Verification owns `evidence.json` check details and criterion status updates in `acceptance.json`.
+- Critique reviewers own the configured critique artifact/sink findings and resolution state; locally this is materialized as `critique.json`.
+- Release reviewers own `release.json` gate decisions and operational readiness records.
+- Learning reviewers own `learning.json` routing into durable improvements.
+- Evidence Gate owns final evidence assessment, residual gaps, and next-step handoff updates.
+- Release Readiness owns release/final-acceptance state after evidence passes.
+
+Final-state reconciliation:
+
+- Verifiers may report that local Markdown and sidecars disagree when they inspect a workflow before orchestration has finished.
+- The terminal delivery state must be based on the final sidecars plus final orchestrator evidence, not on an earlier verifier-local warning.
+- If the final sidecars still disagree with the Markdown artifact, the workflow cannot be treated as a clean pass.
+- If the orchestrator updates the sidecars and records final validation, the final summary should name the reconciled sidecars and supersede earlier mismatch notes instead of carrying both as equal truth.
+
+### Session
+
+The session artifact is the recovery point for the overall workflow.
+
+Required fields or sections:
+- title
+- branch
+- worktree
+- created
+- status
+- type
+- iteration when the workflow can loop
+- plan reference
+- execution progress
+- verification report
+- goal fit status when delivery is involved
+- final acceptance status when merge, release, or durable documentation is involved
+
+### Plan
+
+The plan artifact is the source of truth for implementation.
+
+Required frontmatter:
+```yaml
+---
+role: plan
+parent: <session basename>
+created: <ISO date>
+---
+```
+
+Required sections:
+- `## Plan`
+- `## Definition Of Done`
+- implementation waves
+
+### Review Or Verification
+
+Review and verification artifacts are report-only evidence. They must not contain fixes applied by the reviewer or verifier.
+
+Review artifacts feed the configured critique artifact/sink, locally materialized as `critique.json`, and describe code, security, architecture, standards, or maintainability findings. Verification artifacts feed `evidence.json` and describe build/test/runtime proof mapped to acceptance criteria. Do not collapse critique findings and evidence checks into one gate unless a legacy workflow has no separate review stage.
+
+Required frontmatter:
+```yaml
+---
+role: review
+parent: <session basename>
+created: <ISO date>
+verdict: PASS | PARTIAL | FAIL | NOT_VERIFIED
+---
+```
+
+Required sections:
+- commands or checks run
+- evidence mapped to acceptance criteria
+- failures or gaps
+- verdict
+
+## Continuity Rules
+
+- Update the session artifact at each phase transition.
+- Preserve links from session to plan, review, verification, final docs, and archived artifacts.
+- Record `NOT_VERIFIED` explicitly. Do not convert it to PASS or hide it in a summary.
+- Treat artifacts as working memory until final acceptance; promote durable decisions and usage notes to long-lived docs after merge or acceptance.