feat: scheduler_task_import — external task bridge (CF integration) #5

New issue

Open

opened 2026-07-05 18:33:44 -07:00 by pyr0ball · 0 comments

pyr0ball commented

2026-07-05 18:33:44 -07:00

Collaborator

Context

CircuitForge (CF) wants to push tasks generated by CF products (starting with Kiwi, a pantry tracker) into Focus Flow so users have one calm place to see executive-function tasks. This is separate from #2 (LLM assistant) — this ticket is about a generic external-task-import surface, not natural language parsing.

Full design: circuitforge-plans/shared/superpowers/specs/2026-07-05-focus-flow-task-bridge-design.md (private CF repo, ask Alan for the relevant section if needed).

Proposed scope

New package packages/scheduler_task_import (AGPL-3.0, matching the rest of this repo):

Local HTTP (Hypertext Transfer Protocol) listener bound to 127.0.0.1 only, configurable port
Generates a pairing token on first run, shown in Focus Flow's own settings so a user can manually paste it into the external product's settings (no auto-discovery, explicit user consent each time)
POST /import/tasks — accepts one or more tasks in the schema below, upserts by external_id (idempotent)
On completion or deletion of an externally-sourced task, POSTs {external_id, status, completed_at} back to a per-source callback_url
Follows the existing repository/adapter pattern in scheduler_persistence (AGENTS.md section 2) — scheduler_core should not import this package directly, keep it swappable like the other adapters

Task schema (schema_version 1)

{
  "schema_version": 1,
  "source_product": "kiwi",
  "external_id": "kiwi:item:1234",
  "title": "Use up milk",
  "notes": "Opened 2026-07-01",
  "due_at": "2026-07-07T00:00:00Z",
  "kind": "flexible",
  "status": "active"
}

kind will always be "flexible" from external sources in v1 — never "inflexible", "critical", "locked", or "surprise". External products should never be able to inject urgency into your scheduler's UX.

status is "active" or "cancelled" (source-side deletion/update should cancel the task, not just stop pushing updates).

Privacy note

Everything stays on 127.0.0.1, no CF server touches this data. No cloud variant is in scope for this ticket.

License note

This package is AGPL-3.0, written by you or a contributor under this repo's normal AGENTS.md workflow. CF is not contributing code directly to this ticket, just the schema/contract above and a Kiwi-side implementation in Kiwi's own repo. Happy to talk through the contract or adjust it if anything here doesn't fit your architecture.

## Context CircuitForge (CF) wants to push tasks generated by CF products (starting with Kiwi, a pantry tracker) into Focus Flow so users have one calm place to see executive-function tasks. This is separate from #2 (LLM assistant) — this ticket is about a generic external-task-import surface, not natural language parsing. Full design: `circuitforge-plans/shared/superpowers/specs/2026-07-05-focus-flow-task-bridge-design.md` (private CF repo, ask Alan for the relevant section if needed). ## Proposed scope New package `packages/scheduler_task_import` (AGPL-3.0, matching the rest of this repo): - Local HTTP (Hypertext Transfer Protocol) listener bound to `127.0.0.1` only, configurable port - Generates a pairing token on first run, shown in Focus Flow's own settings so a user can manually paste it into the external product's settings (no auto-discovery, explicit user consent each time) - `POST /import/tasks` — accepts one or more tasks in the schema below, upserts by `external_id` (idempotent) - On completion or deletion of an externally-sourced task, POSTs `{external_id, status, completed_at}` back to a per-source `callback_url` - Follows the existing repository/adapter pattern in `scheduler_persistence` (AGENTS.md section 2) — `scheduler_core` should not import this package directly, keep it swappable like the other adapters ## Task schema (schema_version 1) ```json { "schema_version": 1, "source_product": "kiwi", "external_id": "kiwi:item:1234", "title": "Use up milk", "notes": "Opened 2026-07-01", "due_at": "2026-07-07T00:00:00Z", "kind": "flexible", "status": "active" } ``` `kind` will always be `"flexible"` from external sources in v1 — never `"inflexible"`, `"critical"`, `"locked"`, or `"surprise"`. External products should never be able to inject urgency into your scheduler's UX. `status` is `"active"` or `"cancelled"` (source-side deletion/update should cancel the task, not just stop pushing updates). ## Privacy note Everything stays on `127.0.0.1`, no CF server touches this data. No cloud variant is in scope for this ticket. ## License note This package is AGPL-3.0, written by you or a contributor under this repo's normal AGENTS.md workflow. CF is not contributing code directly to this ticket, just the schema/contract above and a Kiwi-side implementation in Kiwi's own repo. Happy to talk through the contract or adjust it if anything here doesn't fit your architecture.