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.2.0 is the exact process authority; Flow does not define a competing planning, implementation, review, verification, or branch-completion lifecycle.

Current package version: 0.2.9. Runtime support: Agentic/OpenCode plugin API >=1.17.20, verified against the Agentic 1.0.10 / OpenCode v1.18.11 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 and custom non-Flow agents remain isolated from Flow roles, 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.2.0 skills | | Domain knowledge | All 281 ECC 2.1.0 canonical skills audited; 236 domain skills included; 45 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 declared read scopes, disjoint write surfaces or explicit read-only lanes, 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 | required upstream review-package plus authoritative flow_review_diff validation of 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/[email protected]"

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 task dispatch to every registered Flow role and fallback role, all flow-superpowers-* skills, and all Flow tools. Runtime guards independently reject internal-role dispatch and native Flow-skill loads from non-Flow or unknown agents, including agents registered after Flow's configuration hook. Direct /flow-superpowers-* slash-command expansion is always rejected because the host command projection bypasses native skill permissions; use /flow <task> instead. The host may still display those globally discovered skills until it gains agent-aware command filtering. Flow role agents are hidden from user @ autocomplete and remain callable by flow. 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. Once Flow is explicitly selected, it automatically applies the upstream parallel-agent workflow when a substantive task contains two or more independent problem domains; the user does not need to request multiple agents again. An explicit user opt-out forces sequential execution, while an explicit request for multiple agents forces an assessment but cannot waive independence or safety requirements. maxParallel applies only to those problem-domain workers; SDD implementers remain sequential through their task review and fix/re-review gate. Before parallel dispatch, every lane declares its read scope and either an exclusive write surface or no writes. Read-only audit lanes may inspect overlapping immutable source concurrently; writing lanes must have disjoint 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 | declared exclusive surface or read-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. Every SDD implementer/reviewer dispatch declares an absolute Git WORKTREE_ROOT that Flow validates against the session repository before creating the child session; reviewer dispatches also declare BASE_SHA, HEAD_SHA, and each permitted REVIEW_ARTIFACT. Reviewers deny both edit and shell, retain the upstream review-package as required context, and use flow_review_diff as the authoritative validated ancestor-range evidence with Git external-diff and textconv disabled. The runtime guard rejects relative reviewer read/search paths and confines absolute paths to the declared worktree or exact declared artifact files, preventing the inherited parent-session directory from silently becoming review evidence. 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.

Flow role and fallback agents are internal orchestration endpoints, not standalone user modes. They are omitted from @ autocomplete, and non-Flow agents cannot dispatch them through task. This prevents a bare role call from bypassing the task brief, SDD review sequence, ECC routing, and parallel-write coordination. hidden is a discoverability boundary rather than an authorization primitive; the configuration permission matrix and order-independent runtime dispatch guard jointly enforce model-initiated delegation isolation.

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, 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.