@vector-workshop/agentic-flow

Agentic Flow

Agentic Flow is an explicit, removable Agentic host adapter for the complete Superpowers workflow plus a lazily loaded ECC domain-knowledge catalog. Superpowers v6.1.1 is the exact process authority; Flow does not define a competing planning, implementation, review, verification, or branch-completion lifecycle.

Current package version: 0.2.3. Runtime support: Agentic/OpenCode plugin API >=1.17.20, verified against the Agentic 0.4.89 / OpenCode v1.18.3 baseline, Bun host runtime, and Node.js >=20 for the CLI.

Product contract

• Activation is explicit: select the flow primary agent or run /flow <task>.
• All 14 vendored Superpowers skills retain their upstream workflow graph and mandatory gates.
• Agentic only supplies tool, session, permission, model, and named-subagent mappings.
• ECC contributes domain reference only; its workflows, hooks, memory, and orchestration are excluded.
• Default Agentic agents remain isolated from Flow skills and ECC tools.
• Agentic/OpenCode core source is not modified.

Upstream workflow fidelity

For Superpowers subagent-driven development, Agentic Flow preserves:

1. a fresh implementer for every task;
2. upstream task briefs, report files, per-task commits, SHA review packages, and .superpowers/sdd/progress.md recovery ledger;
3. one task-scoped combined spec-compliance and code-quality review after every task;
4. the upstream fix and re-review loop;
5. one broad whole-branch final review;
6. verification-before-completion before any success claim;
7. the exact finishing-a-development-branch menu, user choice, confirmation, and cleanup rules.

The upstream implementer, task-reviewer, and final-reviewer prompt templates are embedded verbatim behind thin Agentic adapters. Namespacing (flow-superpowers-*) and host tool/agent mapping are the only workflow-facing transformations. See TRANSFORM_CONTRACTS.tsv and docs/conformance.md.

Included capabilities

Capability	Implementation
Engineering workflow	All 14 Superpowers v6.1.1 skills
Domain knowledge	All 278 ECC 2.0.0 canonical skills audited; 235 domain skills included; 43 workflow/platform entries recorded and excluded
Primary mode	flow
Upstream core roles	fast/standard/strong implementers, standard/strong task reviewers, strong final reviewer
Parallel problem domains	fresh flow-parallel-worker agents with disjoint write surfaces and no Git delivery permissions
Model fallback roles	flow-*-fallback core role mirrors that inherit the active session model
Optional host helpers	flow-architect, flow-verifier
Reconnaissance	Agentic native explore and general
Domain retrieval	confidence-aware bounded routing plus flow_domain_search, flow_domain_load, flow_domain_read, flow_domain_skip, flow_domain_list
Read-only review evidence	flow_review_diff with validated immutable commit IDs; no reviewer shell
Diagnostics	flow_diagnostics, CLI doctor, CLI status
Quality gates	Static upstream-conformance audit and deterministic tests; optional six-dimension live diagnostics

Exact upstream commits are locked in UPSTREAMS.json.

Development installation

cd engines/agentic/plugins/agentic-flow
bun install --ignore-scripts
bun run prepack
bun run src/cli.ts install \
  --plugin-spec "file:///absolute/path/to/engines/agentic/plugins/agentic-flow/dist/index.js"

The installer follows AGENTIC_CONFIG, AGENTIC_CONFIG_DIR, and XDG_CONFIG_HOME, then Agentic's normal global config candidates. It preserves JSONC comments and config symlinks, serializes concurrent updates, verifies the source did not change before writing, creates a timestamped backup, atomically updates the target, upgrades/deduplicates registrations while preserving tuple options, refuses malformed input, and creates the adjacent agentic-flow.jsonc only when missing.

For the public npm release:

agentic-flow install --plugin-spec "@vector-workshop/agentic-flow@0.2.3"

Pinning the exact version keeps installations reproducible across upstream updates.

Activation

After restarting Agentic:

• press Tab until flow is selected; or
• run /flow implement the complex feature.

Every configured non-Flow agent—including build, plan, general, explore, and custom agents whose names happen to start with flow-—explicitly denies all flow-superpowers-* skills and Flow tools. The upstream global OpenCode bootstrap is not loaded; its content is active only inside the exact registered Flow agent set.

Configuration

Precedence, lowest to highest:

1. built-in defaults;
2. $XDG_CONFIG_HOME/opencode/agentic-flow.jsonc (or ~/.config/opencode/...);
3. $XDG_CONFIG_HOME/agentic/agentic-flow.jsonc (or ~/.config/agentic/...);
4. the directory beside AGENTIC_CONFIG, when set;
5. AGENTIC_CONFIG_DIR/agentic-flow.jsonc, when set;
6. project .opencode/agentic-flow.jsonc;
7. project .agentic/agentic-flow.jsonc;
8. plugin tuple options in agentic.json(c).

{
  "$schema": "/absolute/path/to/agentic-flow.schema.json",
  "enabled": true,
  "maxDomainSearchResults": 10,
  "maxParallel": 3,
  "allowBackground": false,
  "allowCommit": true,
  "allowPush": false,
  "autoDetectStack": true,
  "domainModules": [],
  "excludedDomainSkills": [],
  "roleModels": {}
}

allowCommit is fixed true in upstream-exact mode:

• per-task commits and SHA-based review packages are mandatory SDD mechanics;
• allowPush=false keeps push unavailable by default; set it to true only when you want the exact finishing-workflow push option to be available behind normal Agentic permission checks.

roleModels is optional. When a role is not set, Flow leaves its model field absent so it inherits the active session model, including a model selected at launch or switched by the user; it does not copy the static host default into role definitions. If a configured subagent role model fails because its provider/model is unavailable, quota-limited, timed out, or rejected by the host, Flow may retry architect, implementer, task-reviewer, final-reviewer, or verifier once with its matching flow-*-fallback agent, which also has no model field. Fallback is not used for code failures, review findings, unclear specs, or test failures.

roleModels.orchestrator is different: that model is needed before Flow can execute any retry tool. Agentic's plugin API has no safe post-failure turn-replay hook, so an orchestrator provider failure cannot be automatically retried by this plugin. Leave orchestrator unset when active-session inheritance is required. Flow does not recommend or select a provider/model matrix; users may keep every role inherited or explicitly map any role themselves.

Core SDD roles and flow-parallel-worker are forced to fresh foreground calls at runtime: any task_id is removed and background is set to false. allowBackground=false applies the foreground rule to optional task calls as well. maxParallel applies only to dispatching-parallel-agents problem-domain workers; SDD implementers remain sequential through their task review and fix/re-review gate. Before parallel dispatch, Flow must prove disjoint write surfaces and mutable resources. Shared barrel/index, manifest, lock, route/config, generated, database, device, and build state moves to one later sequential integration task. Parallel workers cannot stage or commit. The ceiling remains prompt-enforced rather than a plugin semaphore because a failed tool has no guaranteed plugin-finally callback. A non-empty domainModules is a validated ECC module allowlist; exclusions are validated against the included catalog.

On OpenCode v1.18.3 and later, keep the host subagent_depth at its default 1 for standard Flow use. The primary flow orchestrator can still dispatch first-level roles, while implementers and reviewers cannot recursively launch more subagents. Raise it only for an intentional custom nested-agent design after evaluating recursion, permission, cost, and write-conflict risks.

Agentic's task schema cannot pass a model per call, so Flow exposes model-tiered agent types that preserve upstream selection semantics:

• mechanical/complete-spec work → flow-implementer-fast;
• integration/judgment work → flow-implementer-standard;
• architecture-heavy work → flow-implementer-strong;
• ordinary task review → flow-task-reviewer-standard;
• subtle/high-risk task review → flow-task-reviewer-strong;
• whole-branch review → flow-final-reviewer on the strong model.
• configured subagent-model infrastructure failure → matching flow-*-fallback role once, inheriting the active session model.

There is intentionally no profile option. quality, balanced, or economy policies must not add, remove, batch, or skip upstream Superpowers gates.

Roles and permissions

Role	Writes	Commits	Purpose
flow	native/delegated	coordinates	hosts the exact upstream workflow
flow-parallel-worker	exclusive surface only	no	parallel independent problem-domain work before sequential integration
flow-implementer-{fast,standard,strong}	yes	yes	fresh one-task upstream implementer selected by complexity
flow-task-reviewer-{standard,strong}	no	no	fresh per-task spec + quality gate selected by risk
flow-final-reviewer	no	no	fresh whole-branch final review
flow-architect	no	no	optional consultant, never an automatic lifecycle stage
flow-verifier	no	no	optional evidence runner, never a replacement verification gate

Parallel workers deny Git staging, commits, push, branch switching, merge/rebase/reset/clean and must stay inside the dispatch's exclusive write surface. Direct git push is denied to SDD implementers. Reviewers deny both edit and shell, and inspect only a validated ancestor BASE_SHA..HEAD_SHA through flow_review_diff, which disables Git external-diff and textconv execution. The optional verifier has a default-deny shell allowlist limited to common test/typecheck/lint/build runners. All roles remain subject to repository instructions, Agentic permissions, filesystem sandboxing, and user approvals; worker/implementer shell access is intentionally broad enough to build arbitrary projects and is not an OS sandbox.

ECC domain behavior

ECC descriptions are not injected into every prompt. For each non-lightweight, substantive Flow request, the plugin performs a local metadata-only route from the user text and detected project stack and exposes at most three candidates. Initial stack detection stays at the session root; when a completed native read reveals a recognized manifest such as a nested or explicitly targeted pubspec.yaml, Cargo.toml, or package.json, Flow merges that authorized evidence into the current task and refreshes its route without recursively scanning unrelated directories. Only high-confidence stack mappings or catalog scores create a gate before task delegation, file-edit tools, or recognized mutating shell commands. Low-confidence lexical candidates are advisory and never block execution. A poor high-confidence match must be refined with flow_domain_search; if no returned domain genuinely applies, flow_domain_skip records the reason and releases the gate only after that search. Empty new turns do not guess, and continuation turns retain the previous route/load state.

Genuine typo and simple file-operation requests remain exempt. This makes retrieval observable and fail-closed where evidence is strong without forcing irrelevant knowledge or loading the full catalog.

Exact loads and referenced reads remain on demand. A bundled reference can be read only after its domain was loaded in the current Flow task. Reads reject traversal and symlink escape, allow only text-like files, cap output at 128 KiB, prepend a workflow-authority wrapper, and never auto-execute bundled scripts. SUPERPOWERS_DISABLE_TELEMETRY=1 is injected into shell environments.

flow_diagnostics reports the effective per-session stack plus the completed ECC search, load, reference-read, skip, and dynamic-manifest evidence for the current task. This receipt is diagnostic only; it does not add a Flow lifecycle or persist private task state.

The complete classification is vendor/ecc/catalog.json; included files carry SHA-256 hashes verified by bun run audit-assets.

Operations

agentic-flow status
agentic-flow doctor
agentic-flow uninstall

Uninstall removes only plugin registration and preserves agentic-flow.jsonc.

Verification

bun run typecheck
bun test
bun run build
bun run audit-assets
bun run audit-superpowers
bun run eval:validate
bun run smoke:agentic
bun run prepack

Live provider evaluation is explicit because it consumes quota:

bun run eval:live -- --model provider/model

It uses a disposable project, isolated config/data/state/cache roots, disabled Agentmemory, no --auto, a clean-worktree invariant, credential redaction, and a mode-0600 report. Exit 2 means credentials/quota/model/timeout blocked the run; exit 1 means a behavioral expectation or runtime/plugin execution failed.

Live evaluation is an optional compatibility and diagnostic tool. It is not a release gate, does not define a supported-model list, and does not override the user's model choice.

See docs/architecture.md, docs/conformance.md, docs/maintenance.md, and docs/security.md.

License

Agentic Flow code is MIT; see LICENSE. Vendored material remains under its original MIT or Apache-2.0 terms; see THIRD_PARTY_NOTICES.md.