Running the uf Pipeline Against fullsend (Local Workflow)

[jflowers]

Companion to RFC: Running uf in a FullSend BYOA container.
This document covers the local developer workflow for using unbound-force
tooling to submit PRs to fullsend-ai/fullsend without committing any uf
files into the fullsend repository.

---

Goal

Use the /opsx-propose -> /uf.unleash -> /uf.finale pipeline inside a
local clone of fullsend-ai/fullsend to author specs, implement changes, and
submit PRs upstream -- while keeping all unbound-force scaffolding
(.opencode/, openspec/, .specify/, .uf/, opencode.json) completely
out of version control.

---

Why Not Run at the Org Level?

The initial idea was to run uf init and opencode at the org-level parent
directory (/Users/jflowers/Projects/github/fullsend-ai) and instruct the
agent to write code into the fullsend/ subdirectory.

Scaffolding works -- the org level has no git repo and no conflicting files,
so uf init creates a clean .opencode/, openspec/, .specify/, .uf/,
and .gitignore there with zero collisions.

The pipeline breaks -- all three slash commands (/opsx-propose,
/uf.unleash, /uf.finale) assume CWD is a git repo root:

Command	Git operation that fails at org level
/opsx-propose	git checkout -b opsx/<name> -- no repo at CWD
/uf.unleash	git rev-parse, git diff --name-only main...HEAD -- no repo
/uf.finale	git add ., git commit, git push, gh pr create -- no repo

The "write code in fullsend/" prompt instruction only redirects file
writes; it does not make bare git/gh calls target fullsend/. The
commands have no --target-repo or -C argument and never cd into a
subdirectory. There is no single CWD that satisfies both org-level spec tooling
and fullsend/ git/PR operations.

OpenCode config discovery also stops at the nearest .git boundary. Running
opencode inside fullsend/ would not auto-discover an .opencode/ placed
above the git root (fullsend/.git). The OPENCODE_CONFIG_DIR env var could
bridge this, but .specify/ and openspec/ paths are resolved relative to CWD
by the commands themselves, so they still need to exist inside the repo.

---

Chosen Approach: Run Inside fullsend/ + Local Exclude

Run uf init inside the fullsend clone, then use .git/info/exclude (a
local, untracked ignore file) to hide all uf scaffolding from git. This lets the
pipeline commands work exactly as designed while ensuring nothing uf-related is
ever staged, committed, or included in a PR.

Key Mechanics

• .git/info/exclude behaves identically to .gitignore but is local to
  your clone and never tracked or committed. It hides untracked files/dirs.
• All uf scaffolding (.opencode/, openspec/, .specify/, .uf/,
  opencode.json) is brand-new in fullsend and therefore untracked --
  .git/info/exclude covers them completely.
• uf init also appends to two already-tracked files: .gitignore
  (adds a UF ignore block) and AGENTS.md (adds a Convention Packs section).
  .git/info/exclude cannot mask modifications to tracked files, so those edits
  must be reverted with git restore.

---

Prerequisites

Item	Notes
fullsend clone	~/Projects/github/fullsend-ai/fullsend with remotes: origin = your fork (jflowers/fullsend-ai-fullsend), upstream = fullsend-ai/fullsend
uf CLI	uf version succeeds; installed via Homebrew or release binary
opencode	opencode --version succeeds; installed via npm (opencode-ai)
Go toolchain	Required if you plan to build/test fullsend locally
Optional: dewey, replicator	If on PATH, uf init configures MCP servers in opencode.json; if not, skipped cleanly

---

Setup Steps

1. Initialize uf inside fullsend

cd /Users/jflowers/Projects/github/fullsend-ai/fullsend
uf init --lang go

This creates:

• .opencode/ (agents, commands, skills, convention packs)
• openspec/ (schemas, changes, specs directories)
• .specify/ (config, scripts, templates, constitution)
• .uf/ (dewey, replicator, artifacts -- if those tools are on PATH)
• .gitignore modification (UF ignore block appended)
• AGENTS.md modification (Convention Packs section appended)
• opencode.json (only if dewey/replicator on PATH)

2. Revert changes to tracked files

git restore AGENTS.md .gitignore

This discards uf init's edits to the two tracked files, returning them to their
committed (upstream) state. git status will no longer show them as modified.

Note: fullsend has its own AGENTS.md (7255 bytes, fullsend-specific
conventions) and .gitignore. We do not want to alter either.

3. Add uf patterns to .git/info/exclude

Do not copy from .gitignore. uf init appends a block to .gitignore
that only ignores selective runtime data under .uf/ (databases, caches,
locks, logs) plus .devcontainer/ and legacy dirs. It deliberately leaves
.opencode/, openspec/, .specify/, opencode.json, and the trackable
parts of .uf/ tracked -- because a repo that genuinely adopts uf wants
those committed. Our goal is the opposite: keep everything uf out of
fullsend's git. The blanket list below is a strict superset of uf's granular
block -- the single /.uf/ line already covers every .uf/... rule uf would
add, plus the four top-level items uf intentionally leaves trackable.

cat >> .git/info/exclude << 'EOF'

# Unbound Force scaffolding (local only, not committed)
/.opencode/
/openspec/
/.specify/
/.uf/
/opencode.json
/opencode.jsonc
EOF

4. Verify clean state

git status

Expected output: nothing uf-related appears. The working tree should look
exactly as it did before uf init, as far as git is concerned.

5. (Optional) Verify opencode loads the config

opencode --version   # confirm it starts and finds .opencode/

When opencode runs inside fullsend/, it discovers the .opencode/ directory
at CWD (project-level config) and loads agents, commands, and skills from there.

---

Daily Workflow

Starting a new change

cd /Users/jflowers/Projects/github/fullsend-ai/fullsend
opencode

Then in the opencode session:

/opsx-propose

This creates openspec/changes/<name>/ (locally, hidden from git by the
exclude) and a feature branch via git checkout -b opsx/<name>.

Implementing

/uf.unleash

Runs the full pipeline: clarify -> plan -> tasks -> spec review -> implement ->
code review -> retro -> demo. Code changes land in fullsend/ on the feature
branch. Spec artifacts stay in openspec/changes/<name>/ (excluded from git).

Submitting the PR

/uf.finale

Stages only git-visible files (code changes), generates a conventional
commit, pushes to origin (your fork), and creates a PR against upstream
(fullsend-ai/fullsend). The uf scaffolding directories are excluded, so
git add . skips them entirely.

---

What Gets PR'd vs What Stays Local

Artifact	Location	Tracked?	In PR?
Source code changes	internal/, cmd/, etc.	Yes	Yes
Test changes	*_test.go, etc.	Yes	Yes
Doc changes	docs/, README.md	Yes	Yes
.opencode/	.opencode/	No (excluded)	No
openspec/	openspec/	No (excluded)	No
.specify/	.specify/	No (excluded)	No
.uf/	.uf/	No (excluded)	No
opencode.json	opencode.json	No (excluded)	No
Spec artifacts	openspec/changes/<name>/	No (excluded)	No

---

Re-running uf init

If you re-run uf init later (e.g., after updating the uf CLI), it will
re-append its blocks to .gitignore and AGENTS.md (idempotent markers
prevent duplication, but the blocks reappear if previously reverted). Fix:

git restore AGENTS.md .gitignore

The .git/info/exclude entries persist across uf init runs -- no need to
re-add them.

---

Caveats and Limitations

Spec artifacts stay local-only

OpenSpec change proposals, designs, and task breakdowns live in
openspec/changes/ which is excluded from git. They won't appear in the PR.
This is intentional (fullsend doesn't use OpenSpec), but it means:

• The PR description should capture the spec rationale inline
• Spec artifacts are only on your local disk (back them up if needed)

fullsend has its own agent conventions

fullsend already has .fullsend/, .claude/, its own AGENTS.md, and
CLAUDE.md. The uf agents/commands/skills loaded from .opencode/ operate
alongside these but do not replace them. If there's a conflict between uf
convention packs and fullsend's own AGENTS.md rules, fullsend's committed
conventions take precedence for PR acceptance.

MCP servers (dewey, replicator)

If dewey and replicator are on your PATH, uf init configures them in
opencode.json. They will activate when opencode starts. This is fine for local
use but be aware:

• Dewey indexes the fullsend codebase into .uf/dewey/ (excluded from git)
• Replicator state goes to .uf/replicator/ (excluded from git)
• Neither affects the PR or the fullsend repo's committed state

The --divisor flag (lighter alternative)

If you only need the Divisor review council (no full pipeline), uf init --divisor deploys only the reviewer agents, /uf.review-council command,
convention packs, and the review-context skill. It skips sub-tool init,
opencode.json, and the AGENTS.md packs section. Same exclude pattern
applies.

---

Quick Reference

# One-time setup
cd /Users/jflowers/Projects/github/fullsend-ai/fullsend
uf init --lang go
git restore AGENTS.md .gitignore
cat >> .git/info/exclude << 'EOF'

# Unbound Force scaffolding (local only, not committed)
/.opencode/
/openspec/
/.specify/
/.uf/
/opencode.json
/opencode.jsonc
EOF
git status  # verify clean

# Per-change workflow
opencode
# /opsx-propose -> /uf.unleash -> /uf.finale

# After re-running uf init
git restore AGENTS.md .gitignore

---

Relationship to the BYOA Plan

This local workflow is independent of the FullSend BYOA integration
described in opencode-fullsend-byoa-plan.md.
The BYOA plan covers running uf agents inside FullSend's sandbox infrastructure
(OpenCodeRuntime, custom image, harness YAML, host scripts). This document
covers using uf tooling locally on your machine to author and submit PRs to
fullsend.

Both can coexist: you use this local workflow to contribute upstream PRs
(including the OpenCodeRuntime implementation itself), while the BYOA plan
describes the end state where uf runs autonomously inside FullSend.