Prepare the tools your project needs¶

Start with the task, then enable the tools it needs. A product conversation, an implementation worker and an application health probe have different permissions. Adding a provider to the catalog does not authorize an account, grant a project or prove that a tool call worked.

The native agent registry has twelve handlers. The factory's own MCP server has 96 operator tools for the authenticated API. Those operator tools manage factory resources; they are not automatically available inside an implementation worker.

Follow the phase boundary¶

Use the lifecycle explorer to inspect the selected repository, phase, participant and actual execution binding.

Phase	What executes	Tool setup
Product, design and architecture	A tool-free dialogue produces proposals for owner review.	Select the task's model profile and attach reviewed documents or images. External design tools are not dispatched by this dialogue.
Prepare	Factory services retain approved contracts, source and execution settings.	Connect the native SCM application and keep required flycanon retrieval ready.
Implement	One coding provider edits the component; optional documentation guidance uses the same worker.	Grant confined source tools and any configured command, browser, search or external-MCP capability.
Verify	The factory executes repository checks independently of the worker.	Configure real test, lint, type, build and selected policy-gate commands in the execution profile.
Assurance and checkpoint	Optional independent review uses a fresh source copy; the factory retains the verified tree.	Select the reviewer separately. Evidence must refer to the same verified source.
Publication	The native SCM integration publishes the branch and review request after an explicit action.	Use a current release permission and the native repository connection. GitHub MCP read access cannot publish.
Deploy and observe	Explicit target commands, health probes and metric observations retain their own receipts.	Configure the target and application independently. A Grafana or Sentry template does not enable monitoring.
Maintain	An explicitly requested maintenance run follows implementation and verification again.	Keep the incident, source, checks and tool settings associated with that run.

Use checks and dependencies that match the selected pyfly or larafly profile and the actual product frontend. A tool grant cannot install those dependencies.

The seven editable instruction roles are product manager, technical lead, architect, implementer, QA, security and documentation. Most bind to deterministic factory services. Only implementer and optional documentation guidance bind to the run's coding worker at implement; they do not start separate model sessions. Roles and skills explains the fixed bindings and project overrides.

Configure the native capabilities¶

The implementer starts with list_files, read_file, write_file, search_text, edit_lines and git_diff. Commands, browser checks, internet search and external MCP require additional role grants and their actual executors. Saving a role request does not install a missing executor.

Capability	Prerequisite	Check before starting work
Files, line edits and diffs	A confined component workspace and the frozen role grant.	Paths, current file hashes and the component diff are readable; credential paths remain excluded.
Commands and tests	A frozen runner profile, explicit tool grant and the required dependencies.	The exact image or trusted host can execute the project's declared checks. Docker selection never falls back to host execution.
Visual QA	A native browser image, matching Playwright binaries, a declared container-loopback application and browser role grants.	Test the actual journey, viewport, theme and approved reference. Screenshot attachment also requires verified model image input.
Internet research	An authorized Brave or Tavily key, domain restrictions, repository search capability and role grant.	Review the explicit connection-test result and retained citations. Testing consumes that provider's allowance.
Knowledge and memory	The managed flycanon services, authenticated tenant/workspaces, embeddings and admitted sources.	Inspect cited retrieval and memory. Missing required knowledge blocks generation.
External MCP	An executable approved adapter, server credential, schema review and active project/repository/role grant.	Inspect the provider-specific prerequisites below and the actual invocation receipt.

Flycanon retrieval and verified per-repository memory are factory services. Native knowledge_lookup also checks repository-scoped references and eligible local outcomes when its role grant and frozen learning policy permit it. Semantic similarity supplies candidates; source, version, freshness and verified receipts determine reuse. The learning guide separates this local path from projected-namespace retrieval and future sharing between projects.

Debugging and profiling currently use configured command arguments and the systematic-debugging instructions. A product image may include its chosen debugger, profiler or scanner, but forge does not supply a dedicated interactive debugger, profiler report parser or universal security-scanner adapter. Keep diagnostic dependencies, time limits and outputs explicit. Opening a host debugger port is not part of this setup.

Signing in to forge identifies the operator. Authorizing a provider grants access to that provider's resources. A factory session, SCM application token and external-tool token have separate audiences and permissions; none substitutes for another.

Connection	Current authorization path
Factory sign-in	Native pyfly Keycloak OIDC authorization code with S256 PKCE, encrypted PostgreSQL attempts/sessions and single-use browser state.
GitLab SCM	Application authorization code with S256 PKCE and refresh. Current grant/state storage is owner-private configuration, separate from the login session tables.
Bitbucket SCM	The configured OAuth consumer uses authorization code with refresh or its configured client-credentials flow. It is separate from GitLab's PKCE implementation.
GitHub external MCP	The current fixed adapter accepts a server-held token. It does not implement a browser OAuth connection flow.
Figma external MCP	Vendor client approval and OAuth are required; neither is implemented by the blocked template.
Sentry external MCP	Upstream supports MCP OAuth or its explicit Sentry token mode. The factory has no admitted OAuth/scoped tool adapter.
Grafana external MCP	The future managed-server contract must declare its caller authentication and target account separately. No generic OAuth connection or executable adapter is admitted.
Native Playwright, local flycanon and search	Browser execution has no vendor login. Flycanon uses its scoped service authentication; Brave/Tavily use their selected API keys. These paths do not acquire an OAuth account by installing a template.

See factory identity and SCM application setup for the implemented flows. Direct coding-provider and Bridge configuration is separate from external MCP authorization.

Required external OAuth connection flow¶

Providers that require OAuth need a complete control-plane connection flow before they can be enabled. This is an implementation requirement, not an available connection wizard contract in the current MCP adapter.

Register the approved application. Admit the provider's issuer, authorization/token endpoints, protected resource, scopes and client ID. Keep any client secret write-only. The exact callback must belong to the configured forge origin; provider discovery must not grant permission to an arbitrary URL. A changed issuer, token host or client registration needs a newly admitted matching credential; an old client secret cannot be forwarded to that new host.
Authorize in the browser. Bind an expiring, single-use PostgreSQL attempt to the current actor, browser and connection revision. Require S256 PKCE. A provider error, changed connection, mismatched issuer or consumed state must leave the connection unavailable.
Retain the grant privately. Encrypt tokens server-side and validate the granted scopes, token type, expiry and resource binding according to the admitted provider contract. Login-session tokens must never be copied into the provider grant or project image.
Manage its lifetime. Record refresh/rotation intents and outcomes under a shared database fence. A lost token response requires reauthorization or explicit reconciliation; rotating refresh tokens cannot be blindly replayed. Recheck current actor, project and tool authority, and make disconnect/revocation stop future calls.
Expose the same controls to clients. The API, SDK, CLI, factory MCP and visual wizard must share readiness, authorization, reconnect and disconnect behavior. OAuth completion still needs exact schema review and the selected project/tool grant.

The foundation must reuse public pyfly OAuth acquisition and PKCE APIs, factory identity/current-access checks and PostgreSQL persistence. The pinned framework still needs a reviewed public refresh/resource/client-authentication extension before a general external OAuth flow can be claimed; private transport calls are not a supported substitute. It must preserve existing login/SCM flows and queued configuration revisions. It does not create vendor client approval, enable unsupported tools or register accounts automatically.

The MCP authorization specification describes protected-resource metadata, authorization-server discovery and resource-bound access. S256 PKCE and the OAuth security best current practice inform the connection controls. Until this flow and the provider adapter are qualified, keep the affected connector at its prerequisite state.

GitHub¶

Current boundary: four repository-read tools are admitted at the fixed https://api.githubcopilot.com/mcp/readonly endpoint: get_file_contents, get_commit, list_commits and list_branches. Native GitHub App installation is a separate SCM connection.

Obtain an authorized credential that can read the selected repository. Check the organization's token policies and any required approval.
Save it through the connection wizard or private key-file CLI flow. Credentials stay in the control plane.
Discover the server's actual schemas and review their exact digest. Discovery performs a remote request; it does not execute or grant a tool.
Grant the registered repository, exact tools and implementation role, then enable the worker's external_mcp capability. Inspect a real run receipt before claiming live acceptance.

The adapter checks owner and repo against the registered source and rejects private file paths. It accepts bounded text results and rejects binary blocks or resource fetching. Upstream's remote-server documentation describes the read-only endpoint. A factory-level catalog state still needs the selected project's grant; there is no global permission to every repository.

Figma¶

Current boundary: a blocked template. forge has no admitted Figma OAuth connection or project-scoped design adapter.

Check whether Figma has approved the factory as an allowed client. Support for an existing editor does not approve a new forge client.
Obtain the authorized user's consent through a future reviewed OAuth integration. Copying an editor's token into another client is not that integration.
Define the product, journey, file, node and reviewed design revision that the adapter may read.
Admit the actual schemas and retained design artifacts through a scoped adapter before enabling agent calls. Until then, attach reviewed design files through the product's existing file/reference workflow.

Figma's installation guide requires catalog admission or its new-client waitlist and OAuth. Its tool reference separates metadata and variables from canvas writes, generative tools and asset downloads. Binary screenshots and temporary asset URLs need a separate bounded artifact adapter; forge's text-only MCP adapter cannot silently fetch them.

Sentry¶

Current boundary: a blocked template. Saving an account token does not provide a scoped, non-enriched issue adapter.

Choose the approved Sentry organization/project and the account permissions required for that scope.
Review the authentication mode. Upstream distinguishes an explicit Sentry token using Sentry-Bearer from an MCP OAuth access token using Bearer.
Review the server version and the exact permitted tools. Skill filtering alone does not prove that a selected tool avoids enrichment or embedded model calls.
Qualify a metadata-only adapter with current project checks, bounded results and retained receipts before enabling it. Continue using native application health/incident records while this prerequisite remains unmet.

The official toolkit documents the token modes and skill filters. In the reviewed source, get_issue_details includes Seer/enrichment paths even when exposed through the inspection skill. forge does not admit that call. A narrow release-metadata adapter is a candidate for further review; it is not implemented by the current template.

Grafana¶

Current boundary: a blocked template. forge accepts neither an arbitrary managed-server URL nor an executable dashboard adapter.

Select an approved authenticated HTTPS MCP deployment and keep its caller credential separate from the Grafana target service account.
Restrict the target account to the intended organization, folders and dashboards. Define those targets in a future reviewed grant contract.
Restrict the managed server to reviewed metadata tools. Upstream provides --disable-write and --disable-query; those flags still require tool-by-tool review.
Qualify the exact server identity, schemas, current target access and bounded metadata results before admitting calls.

Grafana's MCP documentation explains that disabling queries does not block every route that can reach a datasource, including rendering. A first metadata adapter could read one granted dashboard summary. It must reject general API requests, rendering and datasource query tools until those have separate reviewed contracts. Native metrics/health observation does not depend on this MCP template.

Playwright¶

Current boundary: use the native isolated BrowserRunner. An external stdio server or developer browser profile is not admitted.

Build the declared browser image with matching Playwright packages and binaries. See the official Docker guide.
Configure the project's local startup command and literal container-loopback origin in its browser profile.
Grant browser_check or browser_journey to the native implementation role. Keep the journey, expected states, viewport/theme and references explicit.
Execute the declared journey, inspect DOM diagnostics and the actual screenshots, and retain the source-bound evidence. Multimodal comparison requires verified model image input.

The supported profile uses Docker network none, a fresh context and restricted project-origin requests. Fonts, APIs or databases outside that container will not load. Upstream Playwright MCP is not a security boundary; installing it does not replace the factory's runner controls. Full application-network orchestration needs separate acceptance.

Understand what the evidence proves¶

Native search and external MCP use the PostgreSQL tool broker, which records intent and budget before the effect. An unknown remote result requires explicit reconciliation and cannot be blindly replayed. Commands and browser execution use their own effect journals and evidence records. Confined source reads, writes and diffs are guarded, but are not each recorded as individual ToolBroker invocations.

Operator search requests and schema discovery are explicit administrative actions; they are distinct from a run's frozen tool permissions and budget. A returned schema or an enabled connection is not a successful project task. Use the tool evidence guide and run activity to inspect actual execution.

Apply skills without installing hidden tools¶

The seven community adaptations are instruction text with pinned source revisions, content hashes and license receipts. They cover thinking, TDD, systematic debugging, evidence-first review, frontend design, browser QA and Humanizer. Superpowers and Humanizer adaptations use MIT licenses; the selected Anthropic skills have their own Apache-2.0 receipts. See the provenance table.

Role and dialogue snapshots retain the selected instructions. Deterministic roles display instruction metadata; implementation and dialogue bindings apply their selected prompt text. Enabling frontend or browser guidance does not install Figma, Playwright binaries or a model account. Executable quality gates are a separate policy kind with reviewed command arrays and real passing results.