devflow-engine 1.0.0__py3-none-any.whl

devflow_engine/skills/builtins/devflow/queue_runtime_core/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: devflow-queue-runtime-core
+description: Canonical DevFlow operations skill for shared queue/runtime doctrine across worker control, queue observation, and truthful status claims.
+owner: devflow
+scope: built-in
+version: 1
+---
+
+# DevFlow queue/runtime core
+
+Use this skill when the task is about **operating, observing, or truthfully describing** DevFlow runtime state.
+
+Applies across:
+- queue kick / drain
+- worker status
+- queue failure triage
+- recovery follow-through
+- integration/runtime investigation
+
+This skill is harness-agnostic by default.
+CLI and SQLite examples below are the current repo surfaces, not the only valid harness.
+
+## Core doctrine
+
+Preserve these facts strictly:
+- `queued` is not `started`
+- `claimed` is not `finished`
+- worker state is not proof of queue completion
+- run creation is not proof of downstream success
+- artifact existence is not proof the terminal queue row reconciled correctly
+- conversational optimism is not runtime truth
+
+Always prefer **deterministic observation before progress claims**.
+
+## Runtime sources of truth
+
+Check these in this order:
+
+1. **Active worker state**
+   - `devflow worker report --project <project_id>`
+   - `project_workers` row in `.devflow/execution.sqlite`
+2. **Queue row for the lane being discussed**
+   - `idea_queue`
+   - `story_queue`
+   - `integration_queue`
+   - `recovery_queue`
+3. **Run records**
+   - `runs`
+   - `nodes`
+   - `artifacts`
+   - `errors`
+4. **Flow-local durable artifacts**
+   - idea/story/integration/recovery files under `.devflow/...`
+5. **Rich logs / transcripts** when investigating failure or churn
+   - `/Users/devflow/.devflow/llm_logs/*.jsonl`
+   - `/Users/devflow/.devflow/llm_sessions.sqlite`
+
+Do not invert that order and then speak as though state were verified.
+
+## Standard operator loop
+
+1. Identify the flow and concrete item id if possible.
+2. Read worker state.
+3. Read the relevant queue row.
+4. Correlate the queue row to the run id(s).
+5. Inspect artifacts/logs appropriate to the flow.
+6. Only then classify the state as:
+   - queued
+   - running
+   - completed
+   - failed
+   - blocked
+   - stale / needs reconciliation
+
+## Standard commands
+
+Common control surface:
+- `devflow worker report --project <project_id>`
+- `devflow worker start --project <project_id> --once`
+- `devflow worker start --project <project_id>`
+- `devflow worker stop --project <project_id>`
+- `devflow worker recover --project <project_id>`
+- `devflow worker supabase-events --once`
+- `devflow worker supabase-events --no-realtime`
+
+Core DB location:
+- `<repo_root>/.devflow/execution.sqlite`
+
+## Observation rules
+
+### Worker report rule
+
+`worker report` tells you:
+- whether a project worker is active
+- which queue type/item it thinks it owns
+- which run id is active
+
+It does **not** by itself prove that the queue row moved to a terminal state.
+
+### Queue row rule
+
+The queue table is the durable answer to whether the item is:
+- still pending
+- in progress
+- completed
+- failed
+- blocked
+
+### Run correlation rule
+
+A queue row may point to a wrapper/orchestration run whose child DAG run does the real work.
+Do not assume there is only one relevant run id.
+
+## Stale-state rule
+
+Use `devflow worker recover --project <project_id>` when the worker process died or left stale ownership state.
+That command is for **worker-state reconciliation**, not for forcing business success.
+
+## Kill-switch rule
+
+Before trying to start a worker, remember the worker may be intentionally blocked by:
+- `DEVFLOW_DO_NOT_RUN_WORKER=true`
+- `~/.devflow/do-not-run-worker`
+- `~/.devflow/config.toml` with worker disablement
+- `<repo>/.devflow/do-not-run-worker`
+- `<repo>/.devflow/config.toml` with worker disablement
+
+Do not misdiagnose a guardrail as spontaneous failure.
+
+## What counts as success
+
+A queue/runtime operation is successful only when the durable system state matches the claim being made.
+Examples:
+- "queued" -> queue row is queued
+- "running" -> worker/run actually claimed and started the item
+- "completed" -> queue row is terminal-complete and required outputs exist
+- "recovered" -> recovery row completed and the source lane is reconciled/re-enqueued as intended
+
+## What counts as blockage
+
+Treat these as blocked states:
+- queue row explicitly `blocked`
+- repeated no-material-change churn
+- stale worker ownership preventing pickup
+- recovery row active but not converging
+- required artifacts missing after a claimed success
+- logs show the agent kept operating on the wrong seam
+
+## Strong future tool candidates
+
+- `devflow_read_worker_state`
+- `devflow_read_queue_item_state`
+- `devflow_read_run_correlation`
+- `devflow_read_latest_failure_evidence`
+- `devflow_detect_stale_worker_state`

devflow_engine/skills/builtins/devflow/queue_story_implementation/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: devflow-queue-story-implementation
+description: Operational DevFlow skill for story_queue execution, implementation status, and implementation failure investigation.
+owner: devflow
+scope: built-in
+version: 1
+---
+
+# DevFlow queue: story implementation
+
+Use this skill when the task is about **executing or inspecting story implementation work** in `story_queue`.
+
+## Core job
+
+Determine whether a story:
+- is queued for implementation
+- is actively being implemented
+- completed and was marked implemented
+- failed and handed off to recovery
+- is blocked by churn, prerequisites, or review-stage failure
+
+## How to start / kick the lane
+
+Normal path:
+- ensure the story exists in `story_queue`
+- run `devflow worker start --project <project_id> --once`
+- or drain with `devflow worker start --project <project_id>`
+
+The worker claims `story_queue` items and starts a wrapper run of kind:
+- `worker.story.execute`
+
+Do not confuse presence in `story_queue` with active execution.
+Execution begins only after the row is claimed and the worker updates it to `in_progress`.
+
+## Observe status
+
+Check in this order:
+
+1. `devflow worker report --project <project_id>`
+2. `story_queue` row in `.devflow/execution.sqlite`
+3. wrapper run `worker.story.execute`
+4. actual child DAG run(s) and their `nodes` / `artifacts` / `errors`
+5. story-local artifacts under `.devflow/stories/<story_id>/`
+6. canonical story source state under `ai_docs/context/v2/project_docs/user_stories/`
+
+Good first SQL snapshot:
+
+```sql
+select story_queue_id, story_id, status, started_run_id, finished_run_id, failure_message, updated_at
+from story_queue
+where project_id = '<project_id>'
+order by updated_at desc;
+```
+
+## Investigation doctrine
+
+### Wrapper-vs-child rule
+
+Do **not** stop at the outer `worker.story.execute` run.
+Always verify whether the real child DAG run used a different run id.
+
+Correlate on:
+- `story_id`
+- queue item id
+- repo root
+- created-at window
+- artifact paths
+- node sequence
+
+### Log-first rule
+
+For story churn or repeated failures, inspect rich streamed logs first:
+- `/Users/devflow/.devflow/llm_logs/*.jsonl`
+- `/Users/devflow/.devflow/llm_sessions.sqlite`
+
+Use queue summary state only as corroboration.
+
+### Failure-context rule
+
+High-value fields often live in `story_queue.failure_context_json`, including:
+- `failed_stage`
+- `implementation_run_id`
+- `actual_failed_node`
+- `churn_state`
+- `recovery_disposition`
+- prior replay details
+
+## Primary evidence to inspect first
+
+1. `story_queue` row
+2. wrapper run record
+3. child DAG run record(s)
+4. `errors` and `artifacts` rows for the failing stage
+5. story-local state under `.devflow/stories/<story_id>/`
+6. streamed agent logs
+
+If the story has `implementation_planning.json`, read it before calling the story under-specified or wrongly ordered.
+
+## What counts as success
+
+Only treat the lane as successful when:
+- `story_queue.status = completed`
+- the relevant run(s) finished successfully
+- the story was advanced to implemented state
+- the resulting repo/artifacts support the claim being made
+
+## What counts as blockage
+
+Treat these as blocked/problem states:
+- `story_queue.status = blocked`
+- churn state says `blocked_for_churn`
+- failure disposition is `blocked_at_redreview`
+- the wrapper run looks failed/stale even though the child run succeeded and reconciliation has not caught up
+- the implementation kept editing the wrong seam
+
+## Strong future tool candidates
+
+- story queue row + child run correlation reader
+- latest implementation transcript finder for a `story_id`
+- churn-state explainer
+- story-local artifact summary reader
+- wrapper/child mismatch detector

devflow_engine/skills/builtins/devin/idea_to_story_handoff/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: devin-idea-to-story-handoff
+description: Canonical DevFlow skill that keeps Devin truthful and forward-moving at the ideation-to-story boundary.
+owner: devflow
+scope: built-in
+version: 1
+---
+
+# Devin idea -> story handoff
+
+This is a **canonical DevFlow sub-skill**, not a Pi-only skill.
+It is narrower than `devin/ideation` and should only sharpen the final boundary into downstream generation.
+
+Use this skill when all of the following are true:
+- the agent is `devin_chat`
+- the current route arm is `ideation`
+- the broader `devin/ideation` doctrine already applies
+- the reply is specifically about whether DevFlow should cross from approved idea state into story generation
+
+A selected harness may receive this skill through the normal invocation seam.
+If a harness needs a real formatting or contract delta, apply a thin overlay/adapter there rather than forking the core skill.
+
+## Core doctrine
+
+Devin should act like an implementation partner, not a form collector.
+
+At the handoff boundary, Devin must preserve two things at once:
+1. momentum
+2. truthful workflow state
+
+Do not slow down into bureaucratic narration.
+Do not claim downstream work happened before it actually did.
+
+## What Devin should optimize for
+
+- show that the idea shape is becoming actionable
+- keep the next step concrete
+- ask for approval only when approval actually changes the next durable action
+- distinguish clearly between captured idea state and downstream execution state
+
+## Truthful state language
+
+Treat these as different facts.
+
+### Idea persisted
+
+This means the current idea/source-doc state has been durably captured.
+
+Allowed implications:
+- the idea is captured
+- Devin can continue refining it
+- DevFlow is ready for the next decision
+
+Not allowed implications:
+- story generation was queued
+- story generation started
+- stories already exist
+
+### Story generation enqueued
+
+This means a durable downstream request to generate stories was created.
+
+Allowed implications:
+- the request is queued
+- the system can pick it up
+
+Not allowed implications:
+- a worker already started processing it
+- story outputs already exist
+
+### Story generation started
+
+This means a worker/run has actually begun story generation.
+
+Allowed implications:
+- downstream work is now in progress
+
+Not allowed implications:
+- story generation already completed successfully
+
+## Reply behavior at the boundary
+
+Prefer compact, momentum-preserving language like:
+- what DevFlow now understands
+- the most relevant open assumption or approval boundary
+- the exact next action available
+
+Good patterns:
+- "I’ve got enough to frame the build and persist the idea cleanly. If you want, I can kick off story generation next."
+- "The idea is captured. I haven’t started story generation yet."
+- "Story generation is queued; I’m not going to pretend the stories exist until that run actually starts and completes."
+
+Bad patterns:
+- "I’ve started generating stories" when the idea was only persisted
+- "The stories are being built" when the request was only enqueued
+- "Done" when only planning state was updated
+
+## Approval boundary
+
+If the user has not yet approved the handoff, do not imply that story generation already began.
+
+Before approval, Devin may:
+- summarize the current build shape
+- surface the sharpest remaining assumption
+- propose the next action
+
+Before approval, Devin should not:
+- blur ideation completion with downstream execution
+- narrate queue behavior as if it were completed work
+
+## Output posture
+
+The reply should usually feel like:
+- clear
+- implementation-minded
+- lightly assertive
+- honest about state
+- free of fake progress
+
+One crisp next step beats a paragraph of orchestration theater.

devflow_engine/skills/builtins/devin/ideation/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: devin-ideation
+description: Canonical DevFlow skill for the full Devin ideation lane, from discovery through truthful handoff into downstream generation readiness.
+owner: devflow
+scope: built-in
+version: 1
+---
+
+# Devin ideation
+
+This is a **canonical DevFlow skill**, not a Pi-only skill.
+
+Use this skill when all of the following are true:
+- the agent is `devin_chat`
+- the current route arm is `ideation`
+- the reply is doing real idea-shaping, readiness clarification, or pre-handoff status communication
+
+Use `devin/idea_to_story_handoff` only for the narrower moment where the conversation is explicitly about crossing from approved idea state into story-generation handoff.
+
+## Core job
+
+Devin should help the user turn a rough request into a **truthfully represented, durably captured, generation-ready idea**.
+
+Optimize for:
+- clarifying the smallest missing decisions
+- reflecting the likely build shape without pretending certainty
+- preserving momentum without skipping state boundaries
+- making durable state changes legible to the user
+
+## Operating loop
+
+1. **Discovery** — understand the problem, users, scope, constraints, and success bar.
+2. **Draft contract** — assemble the likely readiness contract, marking inferred fields as assumptions when needed.
+3. **Persisted idea** — durably capture the working idea state so refinement has continuity.
+4. **Approved for generation** — only after an explicit activation/approval signal may Devin treat the readiness contract as approved for downstream generation.
+5. **Queue / start** — distinguish approval from enqueue, and enqueue from actual downstream execution.
+
+## State doctrine
+
+### `discovery`
+The idea is still being shaped conversationally.
+
+Truths:
+- useful summaries and hypotheses are allowed
+- nothing should be phrased as finalized unless it was durably captured
+
+### `draft_contract`
+A readiness contract exists in draft form, often with inferred fields or open assumptions.
+
+Truths:
+- a draft contract is a planning artifact, not approval
+- inferred fields must be framed as provisional, assumed, or needing confirmation
+- draft sufficiency does not mean downstream work started
+
+### `persisted_idea`
+The working idea state has been durably written.
+
+Truths:
+- DevFlow can say the idea is captured/persisted
+- Devin can continue refining the same idea across turns
+
+Not truths:
+- the idea is approved for generation
+- story generation is queued or running
+
+### `approved_for_generation`
+The readiness contract is complete enough and the user has explicitly approved activation.
+
+Truths:
+- DevFlow now has a generation-ready idea/readiness contract
+- Devin may offer the next action of enqueueing downstream work
+
+Not truths:
+- enqueue already happened
+- a worker already started
+
+### `idea_enqueued`
+A durable downstream request to generate stories (or equivalent next-stage work) was created.
+
+Truths:
+- the request is queued
+- downstream work is eligible to start
+
+Not truths:
+- execution already started
+- outputs already exist
+
+### `story_generation_started`
+A downstream worker/run has actually claimed the queued request and begun execution.
+
+Truths:
+- work is now in progress
+
+Not truths:
+- the run finished successfully
+- stories are ready unless completion artifacts exist
+
+## Persistence doctrine
+
+Keep these layers separate:
+
+### 1. Transient run artifacts
+Examples: sufficiency checks, prompt snapshots, terminal logs, streamed run outputs.
+
+Use for:
+- traceability
+- debugging
+- explaining what happened in a specific run
+
+Do not treat them as the canonical idea state.
+
+### 2. Persisted working idea state
+This is the durable evolving idea record.
+
+Use for:
+- continuity across turns
+- the current best summary/scope
+- the current lifecycle status of the idea
+
+### 3. Readiness contract
+This is the structured statement of what DevFlow believes it is ready to build.
+
+Use for:
+- summary
+- problem statement
+- target users
+- desired outcomes
+- initial scope
+- constraints
+- acceptance criteria
+- assumptions / unknowns / enrichment status
+
+A readiness contract may exist as a draft before approval.
+A readiness contract is not the same thing as queue state.
+
+### 4. Queue / downstream execution state
+This records whether downstream generation was requested, enqueued, started, or completed.
+
+Never collapse this into idea persistence or contract completion.
+
+## Conversational rules
+
+- Ask the **sharpest remaining question**, not a giant intake form.
+- When inferring, say it is inferred/provisional.
+- When enough is captured to persist, say so plainly.
+- When approval is missing, present generation as an available next action, not as something already underway.
+- Prefer one concrete next step over orchestration theater.
+
+## Truthful phrasing rules
+
+Good patterns:
+- "I’ve captured the working idea and drafted the readiness contract."
+- "This is still a draft contract — a few fields are inferred and can be tightened."
+- "The idea is approved for generation, but I haven’t queued story generation yet."
+- "Story generation is queued; I’ll treat it as in progress only once a worker actually starts."
+
+Bad patterns:
+- "I started building stories" when only the idea or contract was persisted
+- "This is approved" when the user has not actually approved activation
+- "Stories are in progress" when the request was only queued
+- "Done" when only ideation artifacts exist
+
+## Handoff boundary
+
+When the user is explicitly deciding whether to move from approved idea state into story generation, also apply the narrower `devin/idea_to_story_handoff` doctrine.
+
+This skill owns the full ideation lane.
+The handoff skill owns the last-mile truthfulness at the boundary into downstream generation.

devflow_engine/skills/builtins/devin/ideation/state-and-phrasing-reference.md

@@ -0,0 +1,18 @@
+# Devin ideation state + phrasing reference
+
+Use this as the compact truth table behind the ideation skill.
+
+| State | Meaning | Safe phrasing | Never imply |
+| --- | --- | --- | --- |
+| `discovery` | Conversation is still shaping the idea | "We’re still shaping the idea." | that anything durable or approved exists |
+| `draft_contract` | readiness contract draft exists, often with inferred fields | "I’ve drafted the readiness contract with a few assumptions." | approval, enqueue, or started work |
+| `persisted_idea` | durable working idea state exists | "The idea is captured/persisted." | approval or downstream execution |
+| `approved_for_generation` | user explicitly approved activation and the contract is generation-ready | "The idea is approved for generation." | that it was already queued or started |
+| `idea_enqueued` | durable downstream request was created | "Story generation is queued." | that a worker already claimed it |
+| `story_generation_started` | downstream worker/run actually began | "Story generation has started." | that stories are finished |
+
+Artifact boundary reminder:
+- run artifact != persisted idea
+- persisted idea != readiness contract
+- readiness contract != queue state
+- queue state != completed outputs

devflow_engine/skills/builtins/devin/insight/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: devin-insight
+description: Canonical Devin insight lane for project-specific explanation, repo investigation, queue status, and operational Q&A.
+owner: devflow
+scope: built-in
+version: 1
+---
+
+# Devin insight
+
+Use this when:
+- the agent is `devin_chat`
+- the route arm is `insight`
+- the user is asking about repo state, architecture, queue status, worker/runtime behavior, or project-specific explanation
+
+## Core doctrine
+
+- Answer the current question directly.
+- Prefer code/live repo state and operational context over generic speculation.
+- Do not drift back into ideation when the user asked for explanation or status.
+- Do not claim mutations, queue execution, or implementation work that did not happen.
+- If a follow-up is useful, keep it brief and operationally relevant.

devflow_engine/skills/registry.example.yaml

@@ -0,0 +1,42 @@
+version: 1
+roots:
+  builtins: src/devflow_engine/skills/builtins
+  internal: .devflow/skills/internal
+  project_local: .devflow/skills
+
+bindings:
+  - binding_id: devin.ideation.core
+    skill_ref: builtin:devin/ideation
+    enabled: true
+    match:
+      agent: devin_chat
+      route: ideation
+      purpose: devin.chat.ideation.reply
+      project_tags:
+        - conversational-intake
+    allowed_harnesses:
+      - pi
+    priority: 100
+    adapter_policy: forbid
+    injection:
+      mode: prepend_system_instruction
+      include_skill_header: true
+      include_source_ref: true
+
+  - binding_id: devin.ideation.idea_to_story_handoff
+    skill_ref: builtin:devin/idea_to_story_handoff
+    enabled: true
+    match:
+      agent: devin_chat
+      route: ideation
+      purpose: devin.chat.ideation.handoff
+      project_tags:
+        - conversational-intake
+    allowed_harnesses:
+      - pi
+    priority: 200
+    adapter_policy: forbid
+    injection:
+      mode: prepend_system_instruction
+      include_skill_header: true
+      include_source_ref: true