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

Current package version: 0.3.3. Runtime support: Agentic/OpenCode plugin API >=1.17.20 <2, verified with @chunklib/[email protected] and @opencode-ai/[email protected], 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.
• The flow orchestrator may delegate only to capability-bound Flow roles; general, explore, and custom agents are not escape paths from the controlled chain.
• 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 normal task, or one fresh implementer for an upstream-approved small same-shape batch;
2. a plan-scoped .superpowers/sdd/<plan-basename>/ workspace and recovery ledger, spec-bound rulings, task/batch briefs, report files, commits, and SHA review packages;
3. one task-scoped combined spec-compliance and code-quality review after every normal task or approved batch, including file-by-file batch verification and one ledger completion per covered plan 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.3.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 and scoped re-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 | | Delegation boundary | capability-bound Flow roles only; no general, explore, or custom-agent bypass | | 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 hash-bound upstream review package plus authoritative flow_review_diff validation of canonical commit/tree IDs and a clean code snapshot; 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 /path/to/agentic-flow
bun install --ignore-scripts
bun run prepack
bun run src/cli.ts install \
  --plugin-spec "file:///absolute/path/to/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 "@chunklib/[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": "https://unpkg.com/@chunklib/[email protected]/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:

• task or approved-batch 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. If a configured role model is unavailable, the orchestrator may make one model-directed retry with its matching flow-*-fallback agent. That dispatch must record FALLBACK_FROM_ROLE and FALLBACK_REASON; the plugin API cannot automatically replay or guarantee the retry. 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.

All internal Flow roles are forced to foreground calls. Initial implementers and fix rounds 4–5 are fresh; fix rounds 1–3 alone may resume the exact same parent-owned implementer session with FIX_ROUND and its original task_id. Reviewers and scoped re-reviewers are always fresh. allowBackground remains a compatibility field but cannot enable background execution in the controlled chain. Every parallel lane declares absolute READ_SCOPE and WRITE_SURFACE markers; runtime enforces a per-turn maxParallel budget, rejects mutable overlap, confines native reads/writes, and disables worker shell. Shared integration, tests that create outputs, commits, and review remain sequential SDD work.

User-level configuration is a security/privacy ceiling. Project and inline configuration may only tighten activation, command exposure, stack detection, concurrency/search bounds, delivery/background policy, and domain selection; they cannot choose roleModels, raise a user limit, enable push/background behavior that the user disabled, or remove user exclusions.

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;
• ordinary/subtle scoped fix re-review → flow-task-rereviewer-{standard,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, or skip upstream Superpowers gates or invent batches outside its exact small same-shape exception.

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 task or approved same-shape-batch upstream implementer selected by complexity | | flow-task-reviewer-{standard,strong} | no | no | fresh task or approved-batch spec + quality gate selected by risk | | flow-task-rereviewer-{standard,strong} | no | no | fresh, finding-scoped review after one fix round | | 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 |

Every internal dispatch receives a cryptographically random, short-lived, single-use parent capability bound to its exact role, worktree and scopes; direct selection of a hidden role is rejected. Reserved-role permissions are default-deny and cannot be widened by user agent overrides. Implementer native file tools and shell workdir are confined to WORKTREE_ROOT; obvious shell wrappers, ambient/home paths, alternate Git worktrees and wrapped push are rejected. Parallel workers have no shell and may write only through native tools inside their exclusive surfaces.

Reviewer dispatches bind canonical BASE_SHA/HEAD_SHA, require current HEAD and a clean code tree, and hash every exact REVIEW_ARTIFACT. WORKTREE_ROOT must be the session root itself or an in-root linked worktree such as .worktrees/<name>; sibling and external worktrees are rejected. Artifacts may exist only under .superpowers/sdd in that bound worktree. The role contract requires its bound flow_review_diff, and runtime blocks native reads until that call succeeds; every later read/LSP call revalidates HEAD, raw worktree state and artifact hashes. Other plans' SDD artifacts are not readable through ambient worktree scope. Because the host has no final-response veto hook, a no-tool reviewer verdict is not verified evidence and the orchestrator must reject and retry it.

Implementer and verifier shell commands still execute project code. A project script or nested executable may perform effects that cannot be inferred from its command name, so Flow's path, command, and Git checks are policy controls rather than an OS sandbox. Likewise, allowPush controls whether the Flow primary exposes the upstream user-selected push path; it is not a network, credential, or repository authorization boundary. Use host permissions plus filesystem/network isolation and repository-side controls when those guarantees are required.

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. hidden is only discoverability; the one-time capability, exact parent check, default-deny permission matrix and path hooks provide authorization.

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 user text and task-relevant detected stack evidence and exposes at most three candidates. Repeated query tokens are deduplicated. Only high-confidence task-relevant mappings create a gate before delegation, file mutation, or a shell command that the small structural grammar cannot prove read-only. A load satisfies the gate only when it is an original routed candidate or an exact result of the latest search; skip is accepted only after the latest refined search returns no candidates. Empty new turns clear stale routing, while explicit 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

doctor validates the installed Flow package, registration, assets, options, and model-role configuration without requiring a local Agentic source checkout. 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 prepack
bun run release:verify

Host compatibility is a separate explicit gate. Point it at an installed or freshly isolated Agentic executable; it never reads a sibling source repository implicitly:

bun run compat:agentic -- /absolute/path/to/agentic

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.