Fluzo GitHub Organization and Backlog

Status: Repositories, documentation site, 33 issues and organization Project published Version: 0.2 Date: 2026-09-24 Product owner: Jose Corral Baseline: PRD.md v0.2 and ARCHITECTURE.md v0.1, decisions A01-A10 accepted Language: English for repository documentation, issues, pull requests and project fields

1. Recommendation and Scope

Create a GitHub organization with two initial repositories: fluzo for the implementation and fluzo-docs for product specifications, architecture and the documentation site. Use one organization-level GitHub Project to view work from both. Keep core, runtime, TUI and CLI together in one Cargo workspace inside fluzo.

A crate is a compilation/dependency boundary; a repository is a source-control, contribution and release boundary. Accepted A01/A02 require separable components, not separate repositories. A runtime/TUI change should normally be implementable, reviewed and tested in one pull request. Avoid independent versioning, cross-repository dependency pins and coordinated release trains until there is an actual need.

This document defines repository governance and the initial backlog, not new product features. On 2026-09-24, Jose Corral authorized the public fluzo-labs/fluzo and fluzo-labs/fluzo-docs repositories, documentation publication through mdBook/GitHub Pages, and issue/Project provisioning. The user created the organization; authenticated membership for jmanuelcorral was verified as active administrator. Both repositories, the site, the seed issues and the public Fluzo Delivery Project are published. The account owner supplied the required Project authorization directly through GitHub; no credentials are stored in this repository. See PUBLICATION.md for verified resources and views. This authorization does not approve an application release or implementation work beyond repository/documentation setup.

2. Organization and Repository Map

The selected and created organization is fluzo-labs, administered by jmanuelcorral. Both initial repositories, their backlog and the documentation site are authorized for public visibility. This is not a trademark-clearance claim. The public product name remains Fluzo and the executable remains fluzo; actual feature/plan permissions must still be checked during provisioning.

An optional organization .github repository can later host the organization profile and genuinely shared community templates. It is not needed to build the MVP and must not become a third place for product requirements, implementation work or a copied backlog.

Do not initially create repositories for fluzo-core, fluzo-runtime, fluzo-tui, fluzo-cli, Laya, observability, plugins, memory, or packaging. Keep these as crates, modules, test support or directories in the owning repository as applicable. The existing local directory name fluxcon does not require a GitHub repository with the same name.

2.1 Implementation Repository

Proposed layout, to materialize incrementally rather than create empty directories:

fluzo/
  Cargo.toml
  Cargo.lock
  crates/
    fluzo-core/
    fluzo-runtime/
    fluzo-tui/
    fluzo-cli/
  tests/
    fixtures/
    support/
  observability/
  packaging/arch/
  docs/development/
  .github/workflows/

Compose and its backend configuration live with the runtime instrumentation and integration tests they validate. The PKGBUILD lives with its binary and release workflow. Rust API documentation stays with the code and is generated from doc comments; developer commands and local setup instructions change atomically with the implementation.

2.2 Documentation Repository

Use Markdown and mdBook with GitHub Pages for the first site, as authorized by the user. Tool versions must be pinned and the build checked before publication. No custom domain is configured initially. The repository-root specifications remain canonical; thin mdBook include chapters render them without maintaining duplicate document bodies.

Proposed source layout:

fluzo-docs/
  PRD.md
  ARCHITECTURE.md
  GITHUB_ORGANIZATION.md
  book.toml
  src/
    SUMMARY.md
    index.md
    PRD.md                  # includes the canonical root document
    ARCHITECTURE.md         # includes the canonical root document
    GITHUB_ORGANIZATION.md  # includes the canonical root document
  .github/workflows/

Specifications and future proposals must be clearly distinguished from documentation of implemented/released behavior. Publishing the approved PRD does not make the product usable. The initial site can expose specifications and implementation status; installation/tutorial pages must not advertise nonexistent commands as runnable.

3. Sources of Truth and Cross-Repository Changes

The repository-root PRD.md and ARCHITECTURE.md in fluzo-docs are canonical. They were published from the existing local checkout without moving or duplicating their bodies. There was no earlier Git commit history to migrate. The fluzo implementation repository links to these specifications instead of carrying full copies. The initial immutable baseline and published issue links are recorded in PUBLICATION.md.

An implementation milestone records the exact documentation commit used as its baseline, not just a moving link to main. A specification revision and an application release number are different version spaces. Public guides identify which release or unreleased development state they describe; the site does not silently reinterpret an older release using new defaults.

A scope/security/defaults change starts with an explicit specification/design review in fluzo-docs, linked to any implementation issue/PR in fluzo. Merge the approved design first or record an explicit dependency; do not require mutually blocking PRs. Pure implementation corrections inside the approved contract do not need a new PRD version. Behavior-facing changes include a guide follow-up or linked documentation PR before release. Use commit/tag links when recording acceptance evidence.

Keep this organization plan in fluzo-docs. The seeded backlog below records the imported scope; the live issues and Project fields own delivery status, assignees and dependency triage. Do not maintain a second Markdown status board.

4. Organization-Level Project

The public organization-level Fluzo Delivery Project contains the existing 33 issues from both linked repositories. Projects provide views over repository issues, not another repository or duplicate tasks. The MVP board groups work by Status; an All issues table and six focused views provide alternative ways to inspect the same backlog.

Use these initial fields without duplicating information already supplied by GitHub:

Use built-in repository, labels, assignees and linked-PR information rather than manually copied text fields. Keep the field set small. Add iterations or dates only when there is an actual delivery cadence, not speculative deadlines for an unimplemented MVP.

Recommended views are: MVP board grouped by status; Ready ordered by priority/dependency; blocked work; TUI/design review; runtime/security; documentation; and Post-MVP. Filters distinguish a prototype demonstration from completed runtime behavior. A successful demo is not a release-ready task engine.

All eight views are provisioned and linked in PUBLICATION.md. Priority, Delivery, Area, Status and Blocked were initialized from the seed metadata and current issue/dependency state. Size remains unset until actual triage, and no people were assigned automatically. Blocked is a planning snapshot: review it and Ready when prerequisites change; this setup does not install a scheduler or claim continuous dependency-field automation. The empty Post-MVP view does not introduce future issues or release gates.

GitHub repository milestones are repository-scoped. Use the Project's Delivery field for the shared cross-repository milestones, and reserve repository milestones for concrete release tracking where useful. Application tags, PRD versions and architecture document versions must not be inferred from each other.

4.1 Issues, Epics and Pull Requests

Repository issues own deliverables. An epic is an umbrella issue containing child issues or an explicit checklist of links, not a second copy of the same acceptance criteria. Use native parent/dependency relationships when available; a Depends on section with qualified issue links is sufficient otherwise. Do not depend on a paid feature merely to track blockers.

File application behavior, testing and packaging work in fluzo. File specification, guide/site and governance work in fluzo-docs. A bug reported in the wrong repository is triaged/transferred or linked to its owner, not silently duplicated. Use Discussions for open-ended product/design discussion if enabled; a decision affecting delivery must be summarized in a linked issue or design PR.

Adopt a small label vocabulary: type:feature, type:bug, type:design, type:spike, type:docs, type:chore, plus a limited area:* set matching the ownership boundaries. Keep priority/status in Project fields, not conflicting labels. good first issue and help wanted are added only when a maintainer has scoped the work sufficiently.

Each ready issue contains:

Goal / user or engineering outcome
Owning repository and area
PRD sections, architecture decision IDs and baseline revision
In scope / explicitly out of scope
Acceptance criteria with observable results
Verification profile and evidence to attach
Dependencies and linked design decisions
Security, privacy and performance risks where applicable
Documentation impact

Ready means the outcome and test strategy are clear, required design decisions are resolved, dependencies permit starting, and the issue fits a reviewable increment. Done means the implementation or document is merged, applicable checks/evidence are attached, and documentation is current. A spike is Done when it reports its experiment, limitations and a recorded decision, not when it quietly adds production behavior. A blocked or skipped required validation is not a pass.

Use short-lived branches and small PRs into main. Link every implementation PR to the owning issue and its design references. Use automatic issue-closing keywords only when all of that issue's acceptance criteria are satisfied; completing one child must not close an epic. Cross-repository changes link to one another explicitly, with an order of integration and no circular merge dependency.

Limit active work initially to one implementation slice plus, if useful, one independent documentation/review task. The Project is for actual status, not a reason to start every milestone at once. No particular person or agent is automatically assigned by this draft.

5. Governance, Permissions and Automation

5.1 Ownership and Review

Jose Corral is the initial product owner and proposed organization owner, subject to confirming the GitHub account. Do not infer the account handle from a local username. Require strong account authentication and keep recovery credentials outside repositories/issues. Add another trusted recovery owner when one is available; do not create fictitious teams or grant owner access to automation merely for convenience.

Use least-privilege repository roles and default member access. Teams such as Maintainers or Docs are optional when there are actual collaborators, not required scaffolding. CODEOWNERS should identify real maintainers for configuration, runtime/security, release workflows and documentation as staffing permits. Code ownership aids review; it is not an authorization boundary for agent execution.

Protect main against deletion and force pushes and require PRs and the applicable CI checks once those checks actually exist. In a single-maintainer project, do not require a different-person approval that makes every PR impossible to merge; retain a recorded self-review and CI evidence. Once a second reviewer is available, require one peer approval and relevant owner review for sensitive paths. Any emergency bypass is explicit and documented, not the normal workflow. Confirm ruleset/environment features against the selected GitHub plan before claiming them as enforced.

Provide contribution instructions, a code of conduct, PR/issue templates, a security-reporting route, and MIT license text with Copyright (c) 2026 Jose Corral. Project-authored docs use the same license unless separately agreed; third-party screenshots, artwork and dependencies keep their licenses. Security disclosures and secrets do not belong in public issues. If private vulnerability reporting is unavailable, document a reviewed contact route before public launch.

5.2 CI and Release Boundaries

Ordinary test runs use isolated configuration and fixture-only network destinations. Dependency/image downloads are prepared separately; this is not a promise of offline bootstrapping. Do not run untrusted fork code on a personal workstation, inference server or a runner carrying deployment credentials. Keep any hardware-specific/manual validation separate from untrusted PR execution.

Default workflow token permissions are read-only. Give deployment/release jobs only the permissions they need; Pages may require scoped Pages/OIDC permissions without a broadly privileged personal token. Pin actions and dependency/tool versions appropriately and update them through reviewed PRs. Never use a privileged PR workflow to check out and execute untrusted changes with secrets. Provider credentials are not an organization-wide secret required for building Fluzo.

As checks are introduced, add stable named required gates for completed slices. Do not claim unimplemented test layers are passing by installing empty workflows. Code-generation artifacts and documentation builds record source revisions; generated files do not become an alternative editable source of truth.

Release artifacts belong to fluzo; the documentation site belongs to fluzo-docs. Publishing or creating tags is an explicit maintainer action/workflow, not an automatic consequence of approving this organization plan. AUR publishing is post-MVP even though the source PKGBUILD is a required deliverable. Do not commit model weights, recorded private conversations, .fluzodrive/, real credentials, or machine-specific .fluzo settings into either repository.

6. Seed Backlog

The following briefs were imported as 33 GitHub issues, with the seed-to-issue mapping in PUBLICATION.md. GitHub issues and Project fields now own delivery status, assignees and dependency triage; this table retains the seed scope, not a second status board. No assignees were selected automatically. The MVP milestone is present in each repository, and Delivery/Priority fields are populated in the shared Project. Dependencies mean prerequisite accepted behavior, not permission to bypass a safety gate. Milestones are exit checkpoints; independent work may start earlier when its prerequisites are satisfied.

These entries seed the backlog rather than replace PRD section 53. Before marking a delivery issue Ready, split it if necessary and expand its acceptance criteria using the linked specification sections. Before calling the backlog complete, map every MVP acceptance requirement to an owning issue and evidence; omit no requirement just because it is not a row below.

6.1 M0: Organization and Documentation Setup

6.2 M1: Foundation

6.3 M2: Visual Prototype

UI-02 design and acceptance ownership

UI-02 D0 reconciles the selected FLUZO identity and the staged prototype boundary in PRD sections 29.2.1, 29.2.2 and 29.4. The existing visual reference remains unchanged; creation of refinement issues is not authorization to alter appearance or behavior. Control catalogs, safe ranges and new defaults require separate explicit review before implementation. This is a requirement-ownership map, not a second delivery-status table; GitHub remains authoritative for current state and dependencies.

M2 component review may use the isolated runtime-shaped fixtures defined in PRD 29.4 without waiting for real Laya or the native agent. This does not remove the complete simulator-based demo, integrated screen review or later runtime requirements. An implementation owner is not evidence that a requirement passed. Missing mandatory evidence remains a blocker at its applicable gate; closing children alone cannot establish parent or release acceptance.

The product-owner-approved D0 catalog split makes extra pulse controls, manual logo selection, additional palettes and density/tool variants optional, without removing responsive layout, readable state transitions or tool expansion. Notification safety bounds remain mandatory; only duplicate duration/stack controls in the Developer Menu become optional, not the normal editing path for supported persistent settings. Shared persistence, accurate effective-state metadata, consent/capacity checks and acceptance evidence remain required. PRD 29.3.1 records the agreed in-app duration, visibility, retention and text bounds together with overflow, duplicate, expiry and resize behavior. C2 owns their implementation evidence; numerical approval does not approve the eventual presentation or establish runtime safety. This documentation update changes no issue bodies, dependency edges or Project fields and marks no phase complete. Reconcile only affected issue criteria in a separately authorized update; do not implement optional features merely to satisfy older issue wording.

6.4 M3: Diagnostics and Storage

6.5 M4: Safe Execution

6.6 M5: Native Agent

6.7 M6: Integration and Release

6.8 Example of an Expanded Issue

RUN-05 illustrates the intended level of detail before a brief becomes Ready:

Title: Enforce per-process model and pool admission
Repository: fluzo
References: PRD 43.1-43.3; architecture A04, sections 5.3 and 8.2
Dependencies: DAT-01, FND-02, SIM-01

Goal:
All requests from one runtime respect configured local ceilings without
blocking the UI or coordinating unrelated Fluzo instances.

Acceptance:
- Model and pool capacity are admitted atomically.
- Streaming holds capacity through completion or recorded uncertainty.
- Local foreground queues are bounded and cancellable.
- Shadow observations cannot consume foreground-reserved capacity.
- A lower limit drains existing requests without resetting consumption.
- Two processes in different workspaces retain independent ceilings.
- HTTP 429/capacity rejection emits a clear failure and sends no retry.
- Tests use the local simulator and record overlapping-request maxima.

Not included:
Cross-process server locks, rate-limit scheduling, load balancing,
automatic failover, or live-model performance benchmarks.

Evidence:
Commands, scenario versions, observed maxima, cancellation/error outcomes,
and UI responsiveness checks linked from the implementation PR.

7. Deferred Work and Repository Extraction

Keep worktrees, active Laya plan decisions, ACP/MCP, third-party extension loading, sandboxing, long-term memory, macOS and native Windows in a distinct Post-MVP view. They may have research/design issues, but are not prerequisites for the first release. Cross-instance inference coordination and provider rate-limit management are explicitly excluded by A04 and must not reappear as automatic roadmap tasks.

Extract a repository only after there is an independently useful component, an actual maintainer/consumer boundary, a stable-enough contract, and evidence that independent releases reduce rather than increase coordination. Also account for licensing/security review, release/test ownership and downstream compatibility. A trait, a Cargo crate, or an optional feature flag alone is not a reason to split source control.

Likely future cases are externally distributed extensions with separate owners, a genuinely reusable standalone library, or a separately delivered service if B is explicitly approved. Even then, runtime extraction can first mean another executable in the same repository; process separation does not imply repository separation. Laya remains a built-in replaceable adapter in the MVP, not a separate Fluzo-maintained model repository.

Organization .github, package-manager distribution repositories or a domain/site repository are added only when their channel actually exists. AUR maintenance does not require a second general source repository now, and a future macOS package channel does not justify creating an empty tap today.

8. Provisioning and Migration Sequence

1. Approve this topology, organization handle, visibility, owner account and initial documentation-site choice. Check name availability and feature/plan constraints without interpreting them as legal clearance.
2. Obtain explicit authorization to create the organization and the two repositories. Account authentication, billing, 2FA and recovery inputs remain under the user's control; never request secrets in chat.
3. Record the current local Git state and choose an import strategy before moving anything. Preserve uncommitted work; do not reset, force-push, rewrite existing history, rename the checkout or replace remotes implicitly. Authorize any history-preserving extraction separately.
4. Transfer the canonical docs with reviewed path/link changes, then establish code-repository pointers and the baseline revision record. Publish no private model URLs, credentials or local telemetry in the process.
5. Add feasible repository protections and contribution/security policies. Register required CI checks only once their workflows can actually execute. Create the organization Project and the minimal label/field conventions.
6. Import the seed issues and record a mapping from provisional IDs to real issue URLs. Create prerequisites first or resolve all references after import. Add project membership and dependency links without inventing issue numbers or mass-assigning work.
7. Build and validate the docs site before an authorized Pages deployment; verify its public/private behavior. Leave implementation features clearly marked as planned.
8. Start the first executable slice from M1/M2 and review the prototype with simulated data. Expand the next set of issue briefs only when their design and dependencies are understood.

Provisioning is idempotent in intent: inspect existing resources before creating/updating them and report conflicts rather than deleting an organization/repository/Project. The published importer detects existing seed IDs and preserves issue bodies/states; native dependency updates only add missing links. Provisioning within the agreed resources is user-authorized; deleting resources, changing visibility, publishing runtime releases or rewriting history requires separate authorization.

9. Confirmed Decisions

No new PRD scope revision is needed merely to choose GitHub hosting and issue organization. If the repository plan introduces extra runtime features, mandatory cloud services or new release gates beyond the approved contracts, stop and review those changes explicitly.