From 159252ec2da7d3a92e99644126506efe06889c26 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Fri, 21 Aug 2026 13:57:20 -0400 Subject: [PATCH 1/3] docs: add uf setup / uf init lifecycle section to Common Workflows - Document the full uf setup install cascade, uf init 12-step scaffolding process, sub-tool initialization (Group A/B), --force re-initialization, guardrail injection, and stale command warnings - Add troubleshooting subsection for common issues (Dewey hang, stale refs, RPM 404 errors) - Add cross-reference links from Quick Start and Developer Guide - Source content from 8 resolved GitHub issues (#203, #210, #211, #222, #223, #225, #236, #245) - Include OpenSpec change artifacts (proposal, design, spec, tasks) Assisted-by: claude-opus-4 Generated with AI assistance (claude-opus-4) --- .../docs/getting-started/common-workflows.md | 86 ++++++++++++++++++- content/docs/getting-started/developer.md | 2 +- content/docs/getting-started/quick-start.md | 2 +- .../changes/uf-init-setup-docs/.openspec.yaml | 2 + openspec/changes/uf-init-setup-docs/design.md | 55 ++++++++++++ .../changes/uf-init-setup-docs/proposal.md | 77 +++++++++++++++++ .../specs/lifecycle-docs.md | 71 +++++++++++++++ openspec/changes/uf-init-setup-docs/tasks.md | 44 ++++++++++ 8 files changed, 336 insertions(+), 3 deletions(-) create mode 100644 openspec/changes/uf-init-setup-docs/.openspec.yaml create mode 100644 openspec/changes/uf-init-setup-docs/design.md create mode 100644 openspec/changes/uf-init-setup-docs/proposal.md create mode 100644 openspec/changes/uf-init-setup-docs/specs/lifecycle-docs.md create mode 100644 openspec/changes/uf-init-setup-docs/tasks.md diff --git a/content/docs/getting-started/common-workflows.md b/content/docs/getting-started/common-workflows.md index 7ca6644..e18dfc6 100644 --- a/content/docs/getting-started/common-workflows.md +++ b/content/docs/getting-started/common-workflows.md @@ -1,6 +1,6 @@ --- title: "Common Workflows" -description: "The /uf.unleash autonomous pipeline, /uf.finale shipping workflow, manual feature flows, bug fixes, code reviews, and environment setup." +description: "The /uf.unleash autonomous pipeline, /uf.finale shipping workflow, manual feature flows, bug fixes, code reviews, environment setup, and uf setup / uf init lifecycle." lead: "End-to-end workflows that show how all five heroes collaborate across the development lifecycle." date: 2026-03-22T00:00:00+00:00 draft: false @@ -629,6 +629,90 @@ Then run the full autonomous pipeline: /uf.unleash ``` +## `uf setup` / `uf init` Lifecycle {#uf-setup-uf-init-lifecycle} + +The [Environment Setup](#environment-setup) section above covers the quick path: install, setup, verify, start. This section explains what `uf setup` and `uf init` actually do under the hood -- useful when troubleshooting, re-initializing an existing project, or understanding how the toolchain is assembled. + +### `uf setup`: Install Cascade + +`uf setup` installs the [four tool categories](#2-run-setup) listed in the Environment Setup section above, in order. As a final step, `uf init` runs automatically to scaffold the project. + +Setup detects your platform and adjusts the installation method accordingly: + +- **macOS with Homebrew**: installs via `brew install` where packages are available +- **Fedora/RHEL with dnf**: installs via `dnf` for tools available in Fedora repos (e.g., Podman). Tools without native packages (Ollama, DevPod) fall back to their official curl installers with an interactive confirmation prompt +- **Other platforms**: falls back to curl-based installers or version manager installs (goenv, nvm, fnm) + +Existing installations are detected and skipped. Use `--dry-run` to preview what would be installed without making changes. + +#### RPM Version Resolution (Fedora/RHEL) + +On dnf-based systems, `uf setup` resolves companion tool versions (Gaze, Replicator) independently. Rather than using the `uf` binary's own build-time version for all companion RPM URLs -- which could cause 404 errors when tool versions diverge -- each companion tool's latest release is resolved independently via `gh release view`. The resolved tag is validated for repository format, semver format, and length bounds. + +This means `gh` CLI must be installed before Gaze and Replicator on dnf-based systems. `uf setup` handles this ordering automatically, but if you see RPM 404 errors during manual installation, verify that `gh` is installed and has network access. + +### `uf init`: Project Scaffolding + +`uf init` is the final step of `uf setup`. It can also be run independently to initialize or re-initialize a project. The init process performs a 12-step scaffolding sequence: + +- Creates `.uf/config.yaml` for [workflow configuration](/docs/getting-started/common-workflows/#workflow-configuration) +- Deploys agents, commands, convention packs, and templates into the project +- Injects command-specific guardrails for Speckit and execution commands (4 variants: `speckit.implement`, `speckit.constitution`, `speckit.taskstoissues`, and general execution/utility) +- Injects STOP HERE blocks for 6 spec-phase Speckit commands to enforce phase boundaries +- Manages scaffold comment deduplication on re-runs to prevent duplicate injections +- Cleans up legacy `unbound/packs/` directories from older versions +- Performs sub-tool initialization (see below) + +Init is idempotent -- running it multiple times on the same project is safe. Branch enforcement and guardrail injection are split into independent checks, so partial re-runs complete correctly. + +### Sub-tool Initialization + +After scaffolding, `uf init` initializes companion tools concurrently. Five sub-tools -- Dewey, Gaze, Replicator, Specify, and OpenSpec -- are initialized in parallel via independent goroutines, reducing wall-clock time from ~90-120 seconds (sequential) to ~30-60 seconds. + +Sub-tools are divided into two groups: + +| Group | Tools | Notes | +| ----- | ----- | ----- | +| **Group A** | Dewey | Handles indexing and embedding generation. Receives `--no-embeddings` during init to avoid blocking. | +| **Group B** | Specify, Replicator, OpenSpec, Gaze | Standard initialization with no special flags. | + +Dewey indexing no longer blocks other tool initialization. When Dewey is available, `uf init` runs `dewey init` + `dewey index --no-embeddings`. For full embedding generation, run `dewey index` separately after init completes. + +### Re-initialization (`--force`) + +`uf init --force` re-initializes all sub-tools across both Group A and Group B. This is useful when a tool's configuration has become corrupted, or after upgrading `uf` to pick up new init steps. + +Without `--force`, init only initializes tools that have not been initialized before. With `--force`: + +- All sub-tools are re-initialized regardless of current state +- Tools that support `--force` receive the flag via their CLI +- The init summary shows "re-initialized" vs. "initialized" for each tool to distinguish fresh vs. forced initialization + +Prior to v0.16.0, `--force` only re-initialized Group A (Dewey), silently skipping Group B tools. This was fixed so that `--force` now covers all sub-tools. + +### Guardrail Injection + +`uf init` injects command-specific guardrails into your project's agent configuration. There are four guardrail variants, each tailored to a different command category: + +- **`speckit.implement`** -- guardrails for the implementation phase +- **`speckit.constitution`** -- guardrails for constitution management +- **`speckit.taskstoissues`** -- guardrails for task-to-issue conversion +- **Execution/utility** -- guardrails for general execution commands + +On re-runs, `uf init` self-corrects: correctness markers in the injected content allow init to detect outdated guardrails and replace them with the current version. This means upgrading `uf` and running `uf init` automatically updates your project's guardrails without manual intervention. + +### Stale Command Warnings + +After the `uf.*` namespace migration, running `uf init` on an existing project scans agent markdown files for references to old-name commands (the pre-`uf.*` namespace). If stale references are found, init emits warnings with actionable output identifying which files contain outdated command names. Update the flagged files to use the current `uf.*` namespace. + +### Troubleshooting + +**Dewey indexing hangs on `uf init --force`**: The `--force` flag passes `--no-embeddings` to Dewey's index command, so Dewey should not trigger full embedding generation during init. If Dewey appears to hang, it may be performing the initial workspace indexing on a large repository (~2300+ pages). Wait for it to complete, or cancel and run `dewey index` separately with `--no-embeddings` to skip the embedding generation pass. For full embedding generation (required for semantic search), run `dewey index` independently after init completes -- this runs Ollama with the Granite embedding model and can take several minutes depending on workspace size. + +**Stale command references after upgrade**: After upgrading `uf`, run `uf init` to trigger the stale command reference scan. If warnings appear, update the referenced files to use the `uf.*` namespace. The warning output identifies exact file paths and the old command names found. + +**RPM 404 errors on Fedora/RHEL**: If `uf setup` fails to download companion tool RPMs, verify that `gh` CLI is installed and has network access. Each companion tool's version is resolved independently via `gh release view`, so a missing or unauthenticated `gh` CLI will cause resolution failures. Run `gh auth status` to check authentication, and `gh release view --repo unbound-force/` to test version resolution manually. + ## Next Steps - [Developer Guide](/docs/getting-started/developer/) -- Daily workflow, Speckit, Replicator, and Cobalt-Crush diff --git a/content/docs/getting-started/developer.md b/content/docs/getting-started/developer.md index 7416406..fd1036b 100644 --- a/content/docs/getting-started/developer.md +++ b/content/docs/getting-started/developer.md @@ -18,7 +18,7 @@ brew install unbound-force/tap/unbound-force uf setup ``` -`uf setup` detects your existing version managers (goenv, nvm, fnm, Homebrew) and installs through them: +`uf setup` detects your existing version managers (goenv, nvm, fnm, Homebrew) and installs through them. For a detailed breakdown of what setup and init do under the hood, see [uf setup / uf init Lifecycle](/docs/getting-started/common-workflows/#uf-setup-uf-init-lifecycle). - **Core tools** -- OpenCode (AI coding environment), Gaze (quality analysis), Mx F (manager hero), GitHub CLI - **Development tools** -- Node.js, OpenSpec CLI, Replicator (multi-agent coordination) diff --git a/content/docs/getting-started/quick-start.md b/content/docs/getting-started/quick-start.md index 1cd7db7..8701fe3 100644 --- a/content/docs/getting-started/quick-start.md +++ b/content/docs/getting-started/quick-start.md @@ -26,7 +26,7 @@ On **Fedora/RHEL** without Homebrew, install `uf` from the RPM package, then run - **Knowledge layer** -- Ollama (local model runtime), Dewey (semantic search), IBM Granite embedding model - **Project scaffolding** -- agents, commands, convention packs, templates, workflow configuration, and `.gitignore` management via `uf init` -Setup detects your platform and version managers (goenv, nvm, fnm, Homebrew, dnf) and installs through them. Use `--dry-run` to preview what would be installed without making changes. +Setup detects your platform and version managers (goenv, nvm, fnm, Homebrew, dnf) and installs through them. Use `--dry-run` to preview what would be installed without making changes. For a detailed breakdown of what setup and init do under the hood, see [uf setup / uf init Lifecycle](/docs/getting-started/common-workflows/#uf-setup-uf-init-lifecycle). ## Verify diff --git a/openspec/changes/uf-init-setup-docs/.openspec.yaml b/openspec/changes/uf-init-setup-docs/.openspec.yaml new file mode 100644 index 0000000..018e641 --- /dev/null +++ b/openspec/changes/uf-init-setup-docs/.openspec.yaml @@ -0,0 +1,2 @@ +schema: unbound-force +created: 2026-08-21 diff --git a/openspec/changes/uf-init-setup-docs/design.md b/openspec/changes/uf-init-setup-docs/design.md new file mode 100644 index 0000000..bb3745b --- /dev/null +++ b/openspec/changes/uf-init-setup-docs/design.md @@ -0,0 +1,55 @@ +## Context + +The website currently documents `uf setup` and `uf init` in fragmented mentions across Quick Start, Developer Guide, and Common Workflows. Users can figure out how to run the commands but lack understanding of what happens inside -- the 12-step init process, sub-tool concurrency, `--force` re-initialization groups, guardrail injection, and troubleshooting. + +Eight resolved GitHub issues (#203, #210, #211, #222, #223, #225, #236, #245) contain operational knowledge about these commands that exists only in issue/PR descriptions. The proposal calls for a dedicated lifecycle section on the Common Workflows page, plus cross-references from Quick Start and Developer Guide. + +Per the proposal's constitution alignment: this change is documentation-only (N/A for Autonomous Collaboration, Observable Quality, Testability; PASS for Composability First since it documents the composable nature of sub-tool initialization). + +## Goals / Non-Goals + +### Goals +- Add a comprehensive `uf init` / `uf setup` lifecycle section to Common Workflows that explains what each command does, how sub-tool initialization works, `--force` behavior, and common issues. +- Add cross-references from Quick Start and Developer Guide to the new section. +- Source all technical details from resolved GitHub issues and existing documentation -- no fabrication. +- Maintain the existing page structure and navigation (no new pages, no menu changes). + +### Non-Goals +- CLI reference documentation (flags, exit codes, full option listing) -- that belongs in the reference section, not getting-started. +- Documenting the internal Go implementation of `uf init` or `uf setup`. +- Documenting `uf doctor` in more depth (already covered adequately in Quick Start and Developer Guide). +- Creating a separate dedicated page -- the lifecycle section fits naturally within Common Workflows alongside the existing Environment Setup section. + +## Decisions + +### D1: Add section to Common Workflows rather than creating a new page + +**Rationale**: Common Workflows already has an "Environment Setup" section (lines 396-465) that covers Install CLI, Run Setup, Verify, and Start Working. The lifecycle section extends this existing content with deeper operational detail. A separate page would fragment the setup documentation further when the goal is consolidation. The Common Workflows page already serves as the "how things work end-to-end" reference. + +**Placement**: Insert the new lifecycle section immediately after the existing "Environment Setup" section and before "Next Steps". This keeps the learning progression: quick setup steps first, then detailed lifecycle for users who want to understand more. + +### D2: Organize by command (`uf setup` then `uf init`) rather than by feature + +**Rationale**: Users encounter `uf setup` first (it calls `uf init` as its final step). Organizing by command matches the user's mental model: "I ran setup, then init happened -- what did each do?" Feature-based organization (e.g., "guardrails", "sub-tools") would require users to already know the architecture. + +### D3: Include a troubleshooting subsection within the lifecycle section + +**Rationale**: The three most common issues (Dewey hang on `--force`, stale command references, RPM version resolution on Fedora) are directly caused by lifecycle behavior. Placing troubleshooting adjacent to the lifecycle explanation connects the problem to the cause. A separate troubleshooting page would lose this context. + +### D4: Cross-references use inline links, not callout boxes + +**Rationale**: Quick Start and Developer Guide already have dense content. A callout box ("Want to learn more about setup? See...") would add visual weight. An inline link within existing prose is less disruptive and follows the pattern already used on these pages. + +## Risks / Trade-offs + +### Common Workflows page length +Adding ~150-200 lines to an already 465-line page. **Mitigation**: The page has `toc: true`, so the new section appears in the table of contents for direct navigation. The Doks theme handles long pages well with its sticky TOC sidebar. + +### Content sourced from issues may go stale +Issue details reflect the state at PR merge time. Future changes to `uf init`/`uf setup` could make the documentation inaccurate. **Mitigation**: The documentation describes behavior at a conceptual level (e.g., "sub-tools initialize concurrently") rather than implementation details (e.g., "goroutines with errgroup"). This makes it more resilient to internal refactoring. The website documentation gate (AGENTS.md) requires a website issue when user-facing CLI behavior changes. + +### Fedora/RHEL details may not apply to most users +`uf setup` RPM version resolution (#236) is platform-specific. **Mitigation**: Platform-specific details are in a clearly labeled subsection so macOS/Homebrew users can skip them. + +### Overlap with `init-setup-error-docs` OpenSpec change +The sibling OpenSpec change `init-setup-error-docs` also modifies `content/docs/getting-started/developer.md`, adding error output notes to the "Sub-Tool Initialization" section. This change (task 2.2) adds a cross-reference link in the Prerequisites section, which is a different section of the same file. The two changes are complementary -- the lifecycle section in Common Workflows provides operational context that complements the error output notes in the Developer Guide. No content duplication or merge conflict is expected, but implementers should verify line numbers if the sibling change lands first. diff --git a/openspec/changes/uf-init-setup-docs/proposal.md b/openspec/changes/uf-init-setup-docs/proposal.md new file mode 100644 index 0000000..8883614 --- /dev/null +++ b/openspec/changes/uf-init-setup-docs/proposal.md @@ -0,0 +1,77 @@ +## Why + +The `uf init` and `uf setup` commands are the entry point to the entire Unbound Force toolchain. Today, users encounter these commands in scattered mentions across Quick Start, Developer Guide, and Common Workflows pages -- but there is no dedicated documentation that explains the full lifecycle: what `uf setup` installs, what `uf init` scaffolds, how `--force` re-initialization works, idempotency guarantees, sub-tool initialization order, and troubleshooting. + +Eight resolved GitHub issues (#203, #210, #211, #222, #223, #225, #236, #245) document significant changes to these commands since launch -- concurrent sub-tool initialization, `--force` behavior for all sub-tool groups, independent RPM version resolution, command-specific guardrails, and stale command reference warnings. None of this operational knowledge has been documented on the website. + +Users who hit issues during setup or init (e.g., Dewey indexing hangs, `--force` not re-initializing Group B tools, stale command references after a version upgrade) have no documentation to reference. This creates support burden and slows onboarding. + +## What Changes + +### New content on the existing Common Workflows page + +Add a dedicated **`uf init` / `uf setup` Lifecycle** section to the Common Workflows page that covers: + +- **`uf setup` install cascade**: What tools get installed, in what order, how platform detection works (Homebrew vs dnf vs curl fallback), and what `--dry-run` does. +- **`uf init` scaffolding lifecycle**: The 12-step initialization process -- what each step does, what files it creates/modifies, and how idempotency works on re-runs. +- **Sub-tool initialization**: Concurrent initialization of Dewey, Gaze, Replicator, Specify, and OpenSpec -- what each does, Group A vs Group B classification, and how `--force` affects each group. +- **Re-initialization (`--force`)**: When to use it, what it does for each sub-tool group, the "re-initialized" vs "initialized" output distinction. +- **Guardrail injection**: Command-specific guardrails (speckit.implement, speckit.constitution, speckit.taskstoissues, execution/utility) and how self-correction works on re-runs. +- **Troubleshooting**: Common issues (Dewey hang on `--force`, stale command references, RPM version resolution failures on Fedora/RHEL) with solutions. + +### Updates to existing pages + +- **Quick Start**: Add a cross-reference link to the new lifecycle section for users who want deeper understanding. +- **Developer Guide**: Add a cross-reference link from the Prerequisites section to the lifecycle section. + +## Capabilities + +### New Capabilities +- `uf-init-lifecycle-docs`: Dedicated documentation section covering the full `uf init` / `uf setup` lifecycle with troubleshooting guidance. + +### Modified Capabilities +- `quick-start-page`: Gains a cross-reference to the lifecycle section for deeper reading. +- `developer-guide-page`: Gains a cross-reference from the Prerequisites section. + +### Removed Capabilities +- None. + +## Impact + +- **Files modified**: `content/docs/getting-started/common-workflows.md` (new section), `content/docs/getting-started/quick-start.md` (cross-reference), `content/docs/getting-started/developer.md` (cross-reference). +- **Navigation**: No menu changes needed -- the new content lives within an existing page. +- **Build**: No template, SCSS, or configuration changes. Content-only. + +## Constitution Alignment + +Assessed against the Unbound Force org constitution. + +### I. Autonomous Collaboration + +**Assessment**: N/A + +This change is documentation-only. It does not modify artifact formats, hero communication patterns, or runtime coupling between tools. + +### II. Composability First + +**Assessment**: PASS + +The documentation describes `uf init` and `uf setup` as composable operations -- each sub-tool is independently initializable, `uf init` is idempotent, and the `--force` flag works per-group. The documentation reinforces the composability principle by explaining how tools function independently. + +### III. Observable Quality + +**Assessment**: N/A + +This change does not produce machine-parseable output or modify provenance metadata. It documents tools that already satisfy this principle. + +### IV. Testability + +**Assessment**: N/A + +This change is static Markdown content. Validation is `npm run build` (build succeeds) and visual review (content renders correctly in both light and dark mode). + +### V. Security by Default + +**Assessment**: N/A + +This change is static Markdown content. No dependencies, external inputs, or file permissions are affected. diff --git a/openspec/changes/uf-init-setup-docs/specs/lifecycle-docs.md b/openspec/changes/uf-init-setup-docs/specs/lifecycle-docs.md new file mode 100644 index 0000000..01cf44a --- /dev/null +++ b/openspec/changes/uf-init-setup-docs/specs/lifecycle-docs.md @@ -0,0 +1,71 @@ +## ADDED Requirements + +### Requirement: uf-setup-lifecycle-section + +The Common Workflows page (`content/docs/getting-started/common-workflows.md`) MUST include a "uf setup / uf init Lifecycle" section that documents the full initialization lifecycle. + +The section MUST cover: +1. What `uf setup` installs and in what order (install cascade) +2. Platform detection behavior (Homebrew, dnf, curl fallback) +3. The `--dry-run` flag for previewing changes +4. What `uf init` scaffolds (the 12-step process at a conceptual level) +5. Sub-tool initialization (concurrent execution of Dewey, Gaze, Replicator, Specify, OpenSpec) +6. Group A vs Group B sub-tool classification +7. The `--force` flag behavior for re-initialization across both groups +8. Command-specific guardrail injection and self-correction on re-runs +9. Stale command reference detection and warnings after upgrades +10. A troubleshooting subsection covering common issues + +The section SHOULD be placed after the existing "Environment Setup" section and before "Next Steps". + +#### Scenario: User reads lifecycle section after running uf setup +- **GIVEN** a user has run `uf setup` and wants to understand what happened +- **WHEN** they navigate to the Common Workflows page and scroll to the lifecycle section +- **THEN** they find an organized explanation of the setup install cascade, init scaffolding steps, sub-tool initialization, and `--force` re-initialization behavior + +#### Scenario: User encounters Dewey hang during uf init --force +- **GIVEN** a user runs `uf init --force` and Dewey indexing appears to hang +- **WHEN** they check the troubleshooting subsection +- **THEN** they find an explanation that `--force` passes `--no-embeddings` to Dewey and guidance to run `dewey index` separately if full embedding generation is needed + +#### Scenario: User sees stale command reference warnings +- **GIVEN** a user upgrades `uf` and runs `uf init` on an existing project +- **WHEN** they see warnings about stale command references to pre-`uf.*` namespace commands +- **THEN** they find in the troubleshooting subsection an explanation that init detects and warns about old-name commands, with guidance to update agent markdown files + +### Requirement: uf-setup-rpm-resolution-docs + +The lifecycle section MUST document that on Fedora/RHEL (dnf-based) systems, `uf setup` resolves companion tool RPM versions independently via `gh release view` rather than using the `uf` binary's own version. + +The documentation SHOULD note that `gh` CLI must be installed before Gaze and Replicator on dnf-based systems. + +#### Scenario: Fedora user encounters RPM 404 errors +- **GIVEN** a Fedora user runs `uf setup` and gets 404 errors when downloading companion tool RPMs +- **WHEN** they check the troubleshooting subsection +- **THEN** they find an explanation that RPM versions are resolved independently per tool, and guidance to verify `gh` CLI is installed and has network access + +### Requirement: quick-start-cross-reference + +The Quick Start page (`content/docs/getting-started/quick-start.md`) MUST include an inline cross-reference link to the lifecycle section for users who want to understand the setup process in more depth. + +#### Scenario: Quick Start reader wants more detail +- **GIVEN** a user is reading the Quick Start page +- **WHEN** they reach the `uf setup` section +- **THEN** they find a link to the Common Workflows lifecycle section for deeper understanding + +### Requirement: developer-guide-cross-reference + +The Developer Guide page (`content/docs/getting-started/developer.md`) MUST include an inline cross-reference link from the Prerequisites section to the lifecycle section. + +#### Scenario: Developer Guide reader wants init details +- **GIVEN** a user is reading the Developer Guide Prerequisites section +- **WHEN** they see the `uf setup` command +- **THEN** they find a link to the Common Workflows lifecycle section for the full initialization details + +## MODIFIED Requirements + +_None._ + +## REMOVED Requirements + +_None._ diff --git a/openspec/changes/uf-init-setup-docs/tasks.md b/openspec/changes/uf-init-setup-docs/tasks.md new file mode 100644 index 0000000..a07bd1d --- /dev/null +++ b/openspec/changes/uf-init-setup-docs/tasks.md @@ -0,0 +1,44 @@ + + +## 1. Add Lifecycle Section to Common Workflows + +- [x] 1.1 Add a "uf setup / uf init Lifecycle" section to `content/docs/getting-started/common-workflows.md` after the existing "Environment Setup" section's `### 4. Start Working` subsection and before `## Next Steps`. The section MUST include: + - **`uf setup` Install Cascade**: What tools get installed, the four categories (Core tools, Development tools, Knowledge layer, Project scaffolding), platform detection behavior (Homebrew vs dnf vs curl fallback), and the `--dry-run` flag. Source: Quick Start lines 22-29, issues #236. + - **`uf init` Scaffolding**: What `uf init` does as the final step of setup -- creates `.uf/config.yaml`, deploys agents/commands/convention packs/templates, and performs sub-tool initialization. Mention the 12-step process at a conceptual level (not step-by-step implementation): file scaffolding, guardrail injection, STOP HERE blocks, scaffold comment deduplication, legacy directory cleanup. Source: issues #222, #223. + - **Sub-tool Initialization**: Concurrent initialization of Dewey, Gaze, Replicator, Specify, and OpenSpec via independent goroutines. Group A (Dewey) vs Group B (Specify, Replicator, OpenSpec, Gaze) classification. Note that Dewey indexing no longer blocks other tools. Source: issue #203, #245. + - **Re-initialization (`--force`)**: What `--force` does -- re-initializes ALL sub-tools (both Group A and Group B). Tools supporting `--force` receive the flag. Init summary shows "re-initialized" vs "initialized". Previously only Group A was re-initialized; this was fixed in v0.16.0. Source: issues #211, #245. + - **Guardrail Injection**: Command-specific guardrails (4 variants: speckit.implement, speckit.constitution, speckit.taskstoissues, execution/utility). Self-correction on re-runs via correctness markers. Source: issue #223. + - **Stale Command Warnings**: After `uf` namespace migration, `uf init` scans agent markdown files for references to old-name commands and warns with actionable output. Source: issue #225. + +- [x] 1.2 Add a "Troubleshooting" subsection within the lifecycle section covering: + - **Dewey indexing hangs on `--force`**: `--force` passes `--no-embeddings` to Dewey. Run `dewey index` separately for full embedding generation. Source: issue #211. + - **Stale command references after upgrade**: `uf init` warns about old-name commands. Update agent markdown files to use `uf.*` namespace. Source: issue #225. + - **RPM 404 errors on Fedora/RHEL**: Companion tool versions resolved independently via `gh release view`. Verify `gh` CLI is installed and has network access. Source: issue #236. + +## 2. Add Cross-References + +- [x] 2.1 [P] Add an inline cross-reference link in `content/docs/getting-started/quick-start.md` within the `uf setup` section (around line 22-29) pointing to the new lifecycle section in Common Workflows. Use the pattern: "For a detailed breakdown of what setup and init do under the hood, see [uf setup / uf init Lifecycle](/docs/getting-started/common-workflows/#uf-setup--uf-init-lifecycle)." + +- [x] 2.2 [P] Add an inline cross-reference link in `content/docs/getting-started/developer.md` within the Prerequisites section (around line 14-26) pointing to the new lifecycle section. Use the same link pattern. + +## 3. Verify + +- [x] 3.1 Run `npm run build` and confirm no build errors. +- [x] 3.2 Run `npm run dev` and visually verify: + - The new lifecycle section renders correctly on the Common Workflows page + - The table of contents includes the new section heading + - The cross-reference links from Quick Start and Developer Guide resolve correctly + - Both light and dark mode render correctly +- [x] 3.3 Verify constitution alignment: confirm that no changes introduce runtime coupling, mandatory dependencies, or non-composable behavior (all PASS/N/A per proposal). + + From 928445c412086c42b177a6e5343843cfcfe1cd03 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Mon, 24 Aug 2026 12:46:58 -0400 Subject: [PATCH 2/3] docs: add structured PR descriptions, AI attribution, and --no-embeddings Incorporates content from PRs #232 and #244: - Structured PR descriptions, PR template detection, AI attribution sections added to common-workflows.md /finale documentation - --no-embeddings flag documented in uf init Dewey initialization across common-workflows.md, developer.md, and cli.md - Additional guardrails (PR approval, --body-file) added to /finale - Session lifecycle table updated to mention structured description --- .../docs/getting-started/common-workflows.md | 26 +++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/content/docs/getting-started/common-workflows.md b/content/docs/getting-started/common-workflows.md index e18dfc6..5ab203a 100644 --- a/content/docs/getting-started/common-workflows.md +++ b/content/docs/getting-started/common-workflows.md @@ -58,6 +58,32 @@ See also: [From Spec to Demo in One Command](/blog/unleash-in-practice/) — a n | 7 | **Return to Main** | `git checkout main && git pull`. | | 8 | **Summary** | Displays completion report: branch, commit, PR, checks, status. | +### Structured PR Descriptions + +When `/finale` creates a PR, it generates a structured body with these sections: + +- **Summary** — what the change does and why, derived from the branch's commit history and spec artifacts +- **How to Test** — concrete steps a reviewer can follow to verify the change +- **How to Demo** — how to demonstrate the feature to stakeholders +- **Key Files Changed** — the most important files with brief descriptions of what changed in each + +Each section contains substantive content. For trivial changes, `/finale` writes brief notes rather than fabricating detail to fill the template. + +If unresolved findings from `/review-council` exist, `/finale` adds a **Known Issues** section listing them. This section is omitted when no review was run or all findings were resolved. + +The PR body ends with an attribution footer: `This PR was generated by /finale (AI-assisted).` + +### PR Template Detection + +If the repository contains a PR template (`.github/PULL_REQUEST_TEMPLATE.md`), `/finale` detects it and maps its generated sections to the template's headings using case-insensitive matching. When a template heading matches a generated section (e.g., a template heading containing "summary" maps to the Summary section), `/finale` fills in that section. Unmatched template sections are preserved as-is. If no template is found, `/finale` uses its default section format. + +### AI Attribution + +`/finale` adds AI attribution in two places: + +- **Commit message** — an `Assisted-by: ` [git trailer](https://git-scm.com/docs/git-interpret-trailers) and a `Generated with AI assistance ()` footer line are appended to the commit message. The model name is a cleaned version of the model identifier (provider prefixes, routing suffixes, and version digits are stripped). The user can edit or remove the attribution during the commit message approval step. +- **PR body** — an attribution footer appears as the last line of the PR description. + ### Guardrails - Never runs on `main` From 7689c5ca7af43269098a13bbb6d7343eeeff3a27 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Tue, 1 Sep 2026 16:23:24 -0400 Subject: [PATCH 3/3] fix(docs): remove duplicate PR descriptions section and trim description Remove the second "### Structured PR Descriptions" heading and its content (lines 97-112) which duplicated the existing section at line 61. Hugo was emitting duplicate TOC anchors. Also trim the frontmatter description from 181 to 151 characters to stay within Hugo's 160-char SEO limit. Addresses PR #251 review feedback from @yvonnedevlinrh. Signed-off-by: Jay Flowers Assisted-by: claude-opus-4-6 --- .../docs/getting-started/common-workflows.md | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) diff --git a/content/docs/getting-started/common-workflows.md b/content/docs/getting-started/common-workflows.md index 5ab203a..f16c5a8 100644 --- a/content/docs/getting-started/common-workflows.md +++ b/content/docs/getting-started/common-workflows.md @@ -1,6 +1,6 @@ --- title: "Common Workflows" -description: "The /uf.unleash autonomous pipeline, /uf.finale shipping workflow, manual feature flows, bug fixes, code reviews, environment setup, and uf setup / uf init lifecycle." +description: "The /uf.unleash autonomous pipeline, /uf.finale shipping workflow, manual feature flows, bug fixes, code reviews, and environment setup." lead: "End-to-end workflows that show how all five heroes collaborate across the development lifecycle." date: 2026-03-22T00:00:00+00:00 draft: false @@ -94,23 +94,6 @@ If the repository contains a PR template (`.github/PULL_REQUEST_TEMPLATE.md`), ` - Uses `--body-file` instead of inline `--body` to safely handle AI-generated content containing shell metacharacters - If any step fails, stops immediately with context and options -### Structured PR Descriptions - -When creating a PR, `/uf.finale` generates a structured body with four sections: - -| Section | Content | -| -------------------- | ----------------------------------------------------------------------- | -| **Summary** | What changed and why, derived from the diff and commit messages. | -| **How to Test** | Steps to verify the changes locally. | -| **How to Demo** | Steps to demonstrate the feature to stakeholders. | -| **Key Files Changed**| List of modified files grouped by purpose. | - -**PR template detection**: If the repository contains `.github/PULL_REQUEST_TEMPLATE.md`, `/uf.finale` reads the template and maps its generated content into the template's sections instead of using the default structure. - -**Review council integration**: If a `/uf.review-council` report exists from a prior run, known issues are included in the PR body under a **Known Issues** section. - -**AI attribution**: Every PR created by `/uf.finale` includes an AI attribution footer in the PR body and an `AI-assisted-by: /uf.finale` git trailer in the commit metadata. - ### Conflict Recovery When the push step (step 4) fails because the remote branch has diverged, `/uf.finale` enters conflict recovery mode and presents five options: