Product Requirements Document (PRD): RunWield

Document role: Living central PRD. Product vision, guiding principles, and the relationship between Core, Workspace, and Connect.

Keep this document as current product guidance. Fold lasting requirements from completed feature PRDs here; implementation steps belong in Plans, architectural choices in ADRs, and delivery evidence in Work Records.

Vision & Strategy

RunWield is collaborative software planning with AI.

RunWield helps software teams figure out what to build, shape the work into reviewable Plans, execute approved work through a local open-source harness, and preserve distilled records so future planning starts from what the team already learned.

The product loop is:

ideate -> plan -> execute -> record -> use records to plan better

RunWield should not be positioned as an agent management platform, issue tracker, ticket system, Scrum tool, or generic AI chat product. Agents are implementation partners inside the planning loop, not the product category.

Product Architecture

RunWield Core

RunWield Core is the free local harness and runtime. It owns the canonical local workflow:

• local wld CLI
• interactive TUI
• local web UI clients
• Sessions across TUI, browser, and ACP-compatible external clients
• Router, Ideator, Planner, Architect, Slicer, Engineer, Operator, Reviewer, Tester, and Recorder agents
• local Plans, PRDs, ADRs, and Work Records as markdown artifacts
• local execution, validation, and recovery workflows

Core remains free forever for individual use. Its MIT-licensed CLI, TUI, personal browser Workspace, and ACP server provide the local planning-to-record loop without a RunWield account or subscription. Model providers may charge for usage.

The detailed Core product requirements live in runwield-core-prd.md. This root PRD summarizes Core only enough to place it inside the broader RunWield product architecture.

RunWield Workspace

RunWield Workspace is the personal browser environment included in Core. It serves one owner working across Projects and moving between the TUI, browser, and phone.

Workspace focuses on:

• Plan and Epic boards, review, and workflow actions
• personal Session continuity across screens
• PRD, ADR, and Work Record visibility and knowledge search
• paired-device access and explicit Project registration
• self-hosted encrypted Shared Plan review through capability links

The detailed requirements and maturity of each capability live in runwield-workspace-prd.md.

Target direction: Workspace also becomes an Electron desktop application sharing the browser UI and controlling the independent wld runtime through ACP and extensions. The first delivery is free local work without a Workspace account. Later capabilities add an optional hosted Workspace identity and cloud features, plus access to a runtime on another network machine. Native mobile apps are deferred. These are targets, not available product claims; the owning desktop, identity, and network runtime requirements distinguish their maturity.

RunWield Connect

RunWield Connect is the plugin ecosystem that brings RunWield planning, verification, recovery, Work Records, and memory into external agent hosts such as Claude Code, Codex, OpenCode, and Pi. It begins with first-party plugins built and compatibility-tested by RunWield.

The external host remains the user’s interface and makes every model call. RunWield Core supplies the durable workflow authority and local operations on demand. A user explicitly activates Connect for an individual request; installing a Connect plugin must not alter ordinary host behavior.

Connect is a first-class way to use RunWield, not a deliberately weakened trial of Core or Workspace. Its detailed requirements live in runwield-connect-prd.md. That document retains attached mode and Attached Workflow as internal architectural terms while using RunWield Connect as the public product name.

The Claude Code FEATURE Preview has recorded live acceptance with explicit source and permission limits. The Codex adapter targets desktop and CLI through the native $runwield:run skill and the same Core coordinator; both surfaces remain unqualified for a complete live workflow. Installation, continuation across hosts, and qualification evidence belong to the Connect capabilities and the Codex guide. Available source code does not imply published package or Stable release availability.

When RunWield Core owns the Session and invokes another harness non-interactively, such as Claude Code through claude -p or Antigravity CLI, that harness is an Execution Backend alongside Pi. Execution Backends are Core capabilities, not RunWield Connect plugins or separately branded product modes.

Naming

• RunWield: public product and umbrella brand.
• RunWield Core: free local harness.
• RunWield Connect: plugins for using RunWield workflows inside external agent hosts.
• RunWield Workspace: free personal browser environment included in Core.
• wld: CLI command.
• Wield: acceptable shorthand after context is established.

Avoid public phrasing such as “Wield AI” because it risks brand collision and points toward the wrong category.

Core Philosophies

• Planning is the category: RunWield should own AI-native/collaborative software planning, not agent management.
• Plan-by-Default: Material work starts with a Plan unless it is explicitly a bounded operation or quick fix.
• Artifacts over traces: Durable team knowledge lives in Plans, PRDs, ADRs, and Work Records, not raw chat logs.
• Private working space: In-between user/agent conversations are private-first. Artifacts persist; chat minutia does not become shared project knowledge by default.
• Local-first core: Core artifacts are repo-local markdown first. Workspace enhances collaboration and cross-project knowledge search while preserving independent local use.
• Distilled memory: Future planning should use approved/final records and rationale, not noisy intermediate debate.
• Owner control: The user chooses when to share artifacts, approve work, and execute it.

Core Objects

Plan

The Plan is the central product object.

A Plan connects:

• product or technical intent
• the proposed approach
• review and approval state
• execution readiness
• validation outcome
• links to related PRDs, ADRs, and later Work Records through derived references

Plans are prospective: they describe what the team intends to do and how.

Plans remain markdown files with stable front matter in Core. Workspace can provide richer collaboration, but must not erase the repo-local Plan model. Optional external Ticket links preserve user-identified demand provenance for navigation; RunWield still does not make external trackers mandatory, fetch Ticket data, or synchronize Ticket lifecycle state.

PRD

PRDs capture user needs, product intent, scope, and capability-organized requirements with acceptance scenarios. Each capability has one owning PRD; current, target, and deferred behavior stay distinct. They are first-class planning inputs that RunWield agents can create or refine within the user’s document conventions.

ADR

ADRs remain the authoritative artifact for architecture and technical decisions. Work Records and Plans may reference ADRs, but should not become a parallel technical-decision authority.

Work Record

Work Records are retrospective planning-memory artifacts: what completed work produced, why it matters, deferred scope, and lessons worth retrieving. They link to source Plans and preserve the actual completion confidence. They do not replace ADRs, raw conversations, or Git’s commit history. Detailed generation, backfill, retrieval, and external-record scope belong to Core Work records.

Capability Ownership

These five documents are this project’s living PRDs. The product-family capabilities below own shared product promises; each surface document owns its detailed behavior. A reference adds context, not another independently maintained copy.

Owning PRD	Capability scope
RunWield	Reviewed intent, consistent cross-surface outcomes, durable knowledge, public documentation, independent adoption and privacy
Core	Routing, Plan review/lifecycle, execution, validation, recovery, Sessions, context, records, customization, PRD authoring
Workspace	Local boards and sharing, attention, browser/phone journeys, target desktop/identity/network access, Project access and search
Connect	External-host opt-in, host model ownership, host compatibility, privacy, setup and recovery
ACP	Client Sessions, target Workspace access, negotiated interactions, Telegram reference journey, recovery and conformance

Workspace owns Personal usage and outcomes, including its owner-only browser report and Project access. Core owns the measurement and reporting rules.

When behavior changes, update the owning capability and its acceptance scenarios in the same implementation change. Other PRDs and Plans link to that owner. Proposed additions, changes, and removals stay labeled until reconciled with actual delivery; unmet intent is retained explicitly. Keep the five-document ownership rule in this project’s AGENTS.md; bundled guidance supports any user’s PRD structure.

Capability Requirements

• Reviewed intent and proportional work
• Consistent workflow outcomes across surfaces
• Durable capability requirements and planning memory
• Public documentation
• Independent adoption and private working space

Reviewed intent and proportional work

Scope and maturity: Lasting product promise. Core’s capability sections distinguish the current baseline and follow-up scope.

Requirement: Review material intent before implementation.

Users can clarify ideas, review intended changes while revision is cheap, and receive a level of planning appropriate to the work. Inquiry and bounded operations stay lightweight; material planned work is reviewed before execution; large projects become independently deliverable children. Work Kind preserves whether planned work is a bug, feature, refactor, maintenance, or documentation.

Detailed owners: Core request routing, Plan review, and Epic decomposition and hold. Workspace may also offer direct actions into Ideator, Planner, or Architect when the user already knows the artifact they need.

Acceptance scenarios:

• Given a user exploring an idea, when they clarify product intent, the result can inform a capability-organized PRD and later a reviewed Plan without prematurely starting implementation.
• Given a small bounded fix versus a broad migration, when each is routed, the fix receives proportionate checks while the migration receives architecture and independently reviewed child work.

Consistent workflow outcomes across surfaces

Scope and maturity: Lasting product promise; availability depends on the surface’s stated delivery scope.

Requirement: Preserve approval and completion meaning across surfaces.

Users receive the same meaning of approval, execution, validation, recovery, and completion through every supported RunWield surface. Core supports independent local use. Personal Workspace supports the same owner moving between screens. Connect preserves the external host’s conversation and model ownership. ACP exposes a RunWield-owned Session through an external client. Core Execution Backends are another way to run turns inside Core, not Connect.

Detailed owners: Core Session continuity, Plan lifecycle, and execution, validation, and recovery. Surface-specific constraints and maturity belong in the ownership table below. Unsupported host or client behavior must be disclosed without weakening shared completion claims.

A delivery workflow concludes only after confirmed publication or deliberate user abandonment. Internal failures are intermediate conditions RunWield repairs automatically, hidden from the user. Waiting for a real user decision or external prerequisite preserves the workflow. The detailed requirements and scenarios belong to Core execution and recovery above.

Acceptance scenarios:

• Given an approved Plan saved for later on one screen, when the user opens another supported surface, it remains approved for later rather than starting implicitly.
• Given locally validated work whose target publication failed, when any surface shows its outcome, it reports the ongoing delivery and automatic recovery without claiming success or treating the failed attempt as a conclusion.
• Given a supported same-owner continuation, when the user changes screens, an idle open screen does not force a separate conversation or reserve the work.

Durable capability requirements and planning memory

Scope and maturity: Lasting product promise; capability authoring guidance is agreed here.

Requirement: Keep requirements and reusable outcomes discoverable.

Users can find what a capability must do in its owning PRD, why architecture was chosen in an ADR, what work is planned in a Plan, and what completed work taught the team in a Work Record. Requirements stay organized by capability with named observable outcomes and acceptance scenarios. Shared requirements have one owner and references; current, target, and deferred behavior remain distinct. A Plan or record is not proof that an unmet target already works.

Project artifacts remain repository-owned Markdown and usable outside RunWield. They survive surface changes without conversion to proprietary document-only storage. Work Records distill results and lessons rather than becoming raw review logs or replacing Git’s commit history. Operational memory remains separate from these durable artifacts.

Detailed owners: Core capability-organized product requirements, Work records, and project context. Workspace owns durable knowledge search.

Acceptance scenarios:

• Given a changed capability, when its implementation is delivered, its owning PRD and scenarios are reconciled in the same change and references remain useful without hunting through old Plans.
• Given an unimplemented proposal, when someone reads the living PRD, target scope stays distinguishable from current behavior.
• When a user plans related work later, relevant eligible records are available with their completion confidence, without treating raw transcript debate as settled requirements.

Independent adoption and private working space

Scope and maturity: Lasting product promise.

Requirement: Support independent use without exposing private conversations.

Users can adopt Core, Workspace, or Connect for the value each provides. Core remains independently useful locally; Connect is a supported destination rather than a deliberately weakened trial. Workspace earns adoption through browser continuity, Plan review, and knowledge search.

Working conversations remain private-first. Shared knowledge comes from deliberate artifacts and synthesized outcomes. RunWield does not impose job-title roles, external trackers, or forge pull-request review as universal prerequisites.

Detailed owners: Connect first-class use, artifact privacy, and Workspace Shared Plan collaboration.

Acceptance scenarios:

• Given a developer who uses only local Core or stays in Connect, when they perform supported work, feasible capabilities are not withheld merely to force Workspace adoption.
• Given a shared artifact, when another permitted person reads it, they do not automatically receive the author’s private conversation.
• Given a user sharing a Plan, reviewer access does not grant access to the owner’s other Projects or Sessions.

Public documentation

Scope and maturity: Current. docs.runwield.dev is deployed from the release-aligned documentation branch.

Requirement: Find usable instructions. Users can search and navigate a public manual for installing, using, configuring, and troubleshooting RunWield. Internal PRDs, Plans, audits, research, and product proposals do not appear as manual pages or search results.

Requirement: Read documentation for the latest Stable release. The public manual identifies and describes the latest Stable release. Candidate and unreleased main behavior does not replace those instructions.

Requirement: Correct documentation independently. Maintainers can correct the current Stable manual without publishing or changing a product release. Corrections remain present when the next Stable release updates the manual.

Requirement: Release the manual with Stable. A Stable release publishes its qualified manual archive and deploys that manual without operator recovery. docs/stable gains one commit per Stable release. Retries reuse that commit; independent corrections remain supported.

Shared requirements: Core installation and updates owns truthful package availability. Core execution, validation, and recovery remains authoritative for product delivery and recovery.

Acceptance scenarios:

• Given a new user, when they open the documentation home, they can reach installation, first-use, configuration, and troubleshooting guidance without navigating internal product records.
• Given a Candidate or an unreleased change on main, when it changes documentation, the public manual continues to identify and describe the latest Stable release.
• Given an error in Stable documentation, when a reviewed correction is published, the manual changes while the Stable product tag and assets remain unchanged; the correction is retained in the next Stable manual.
• Given a Candidate release, when publication succeeds, no docs asset is attached, docs/stable gains no commit, and the live manual stays on the latest Stable.
• Given a Stable release, when publication succeeds, its qualified manual archive is published with the binaries and deployed from docs/stable without rebuilding; a correction made during qualification is preserved.
• Given a retried Stable publication, when docs deployment runs again, it reuses the release merge commit and docs/stable gains no new commit.
• Given a failed or stale documentation deployment, when publication stops or is retried, the last valid manual remains live and an older release cannot replace a newer one.

Delivery and References

Core delivers the useful local planning-to-record loop. Personal Workspace makes that work usable from a browser and phone. Connect brings the same workflow to supported external agent hosts. Each capability owner distinguishes current delivery from proposed work.

The linked Core, Workspace, and Connect PRDs define their release outcomes. Architecture is recorded in ADRs; implementation work is tracked in Plans.

Living Product Requirements

These five PRDs own current product intent: RunWield summarizes the product, Core owns shared local behavior, Workspace owns browser and collaboration journeys, Connect owns external-host use, and ACP owns external-client compatibility and chat-channel integration. Feature PRDs explore unfinished proposals. After delivery, fold lasting requirements and meaningful unresolved scope into the appropriate living PRD, update references, and remove the completed feature PRD. Git history preserves its earlier text; Work Records preserve delivery evidence. Completion does not make historical implementation restrictions current product policy.

Product Non-Goals

• Do not frame RunWield as agent fleet management.
• Do not compete through issue-tracker, ticket, Scrum, or Agile vocabulary.
• Do not persist raw chat traces as team planning memory by default.
• Do not make Git, GitHub, pull requests, or any external tracker mandatory artifact schema concepts.
• Do not treat forge pull requests as the default human review loop; forge-hosted review is an opt-in per repository or team.
• Do not treat Work Records as the audit history of the target branch; the git log owns commit-level history.

Success Metrics

Core metrics:

• speed to first useful Plan
• percentage of planned work reaching verification
• percentage of verified planned work producing Work Records
• quality of recovered context when resuming Plans
• reduction in repeated planning questions caused by missing history

Workspace metrics:

• successful Session start and TUI → phone → TUI continuation with both screens left open

• user effort required to resume work remotely

• Plan review cycle time

• percentage of new Plans using retrieved Work Records, PRDs, or ADRs

• cross-project retrieval usefulness as rated by users

• Work Record edit/override rate after Recorder generation