docs: add /review-pr and /agent-brief documentation

.uf/dewey/learnings/command-docs-1.md

@@ -0,0 +1,9 @@
+---
+tag: command-docs
+category: gotcha
+created_at: 2026-05-02T21:01:24Z
+identity: command-docs-1
+tier: draft
+---
+
+When OpenSpec proposals reference updating a "quick reference table" in common-workflows.md, the spec review should verify whether that table actually exists. The command-docs change referenced a non-existent quick reference table across three artifacts (proposal, spec, tasks), which was caught as a HIGH finding in spec review. The table needed to be created, not updated. Always verify the current state of the target file before writing spec requirements that assume existing content structures.

.uf/dewey/learnings/command-docs-2.md

@@ -0,0 +1,9 @@
+---
+tag: command-docs
+category: pattern
+created_at: 2026-05-02T21:01:29Z
+identity: command-docs-2
+tier: draft
+---
+
+For website documentation changes that document upstream CLI commands, the upstream command files in the unbound-force/unbound-force repo's .opencode/command/ directory are available locally at ../unbound-force/.opencode/command/ and should be read directly before writing website documentation. Dewey does not always have these specific command files indexed. Reading the upstream source ensures content accuracy per Constitution Principle I and prevents fabricating features. The command-docs change successfully used direct file access to verify /review-pr (548 lines) and /agent-brief (406 lines) features before documenting them.

content/docs/getting-started/common-workflows.md

@@ -1,13 +1,26 @@
 ---
 title: "Common Workflows"
-description: "The /unleash autonomous pipeline, /finale shipping workflow, manual feature flows, bug fixes, code reviews, and environment setup."
+description: "Slash command reference and end-to-end workflows — /unleash, /finale, /review-council, /review-pr, /agent-brief, and more."
 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
 weight: 70
 toc: true
 ---
 
+## Quick Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/speckit.specify` | Create a new feature specification (Speckit) |
+| `/opsx-propose <name>` | Create a tactical change with proposal, design, and tasks (OpenSpec) |
+| `/unleash` | Run the full autonomous pipeline: clarify → plan → implement → review → demo |
+| `/cobalt-crush` | Implement an OpenSpec change with convention pack adherence |
+| `/review-council` | Pre-PR review with 5+ Divisor personas in parallel |
+| `/review-pr [N]` | Post-PR review with CI causality analysis and fix branch offering |
+| `/agent-brief` | Create or audit AGENTS.md — the project briefing for AI agents |
+| `/finale` | Stage, commit, push, create PR, watch CI, and return to main |
+
 ## Autonomous Pipeline (`/unleash`)
 
 `/unleash` is the autonomous Speckit pipeline execution command. It takes a spec from draft to demo-ready code in a single command, orchestrating the full pipeline with graceful exit points and full resumability.
@@ -393,6 +406,119 @@ Before delegating to Divisor agents, the review council runs a two-phase CI gate
 
 The council returns **APPROVE** only when all active personas approve. A single REQUEST CHANGES means the council verdict is REQUEST CHANGES. Missing personas (agent files not found) don't block the verdict but are noted in the report.
 
+### Post-PR Review (`/review-pr`)
+
+`/review-pr` is the post-PR counterpart to `/review-council`. Where `/review-council` reviews code locally before a PR exists, `/review-pr` reviews a pull request after it has been created — using CI results, PR metadata, and the full diff.
+
+```text
+/review-pr        # auto-detect PR from current branch
+/review-pr 42     # review a specific PR by number
+```
+
+**Requires**: The `gh` CLI must be installed and authenticated (`gh auth login`).
+
+#### How It Works
+
+1. **Resolve PR** — auto-detects the open PR for the current branch, or accepts a PR number as argument
+2. **Fetch metadata** — retrieves PR title, description, changed files, and branch info via `gh`
+3. **CI check results** — fetches CI/CD check status and classifies any failures
+4. **Local tool pre-flight** — runs project-specific tools (linters, tests) only for checks not already covered by CI
+5. **Scoped diff** — fetches the PR diff, skipping lock files, auto-generated code, and binary files
+6. **Locate spec** — finds the associated specification (Speckit or OpenSpec) for intent alignment
+7. **AI review** — applies judgment to what deterministic tools cannot check: alignment, security, and constitution compliance
+8. **Report** — structured output with severity-classified findings
+
+#### CI Causality Analysis
+
+When CI checks fail, `/review-pr` determines whether each failure was caused by the PR or is a pre-existing issue on the base branch:
+
+| Base Branch | PR Check | Classification |
+|-------------|----------|----------------|
+| Pass | Fail | **PR-caused** — the PR introduced the failure |
+| Fail | Fail | **Pre-existing** — failure exists independently of the PR |
+| No data | Fail | **Unknown** — treated as PR-caused (conservative) |
+
+**PR-caused failures** are reported as HIGH or CRITICAL findings with the specific change that likely caused the failure.
+
+**Pre-existing failures** are reported separately and do not block the PR verdict. After the review, `/review-pr` offers to create a fix branch (`fix/pr-<N>-<check-name>`) with a proposed resolution for each pre-existing failure. This fix branch is created locally — you review it and push when ready. The fix branch offer includes a dirty-tree guard (won't create if uncommitted changes exist) and a collision check (won't overwrite an existing branch).
+
+#### In-line PR Comments
+
+If HIGH or CRITICAL findings are found, `/review-pr` offers to post them as in-line comments on the PR so the author sees them in context. Comments are always shown for your approval before posting. A cap of 15 in-line comments prevents noisy reviews — findings beyond the cap are consolidated into a summary comment.
+
+#### `/review-council` vs `/review-pr`
+
+| Aspect | `/review-council` | `/review-pr` |
+|--------|-------------------|-------------|
+| **When** | Before the PR — during implementation | After the PR — during review |
+| **Scope** | Full codebase review against AGENTS.md | Single PR review against spec and PR intent |
+| **Agent model** | 5+ Divisor personas in parallel | Single agent with structured phases |
+| **CI integration** | Runs CI commands locally (Phase 1a) | Reads CI results from the PR, runs local tools only for gaps |
+| **Output** | APPROVE / REQUEST CHANGES verdict | Structured report with severity-classified findings |
+| **Fix offering** | Iterates fixes in-session (up to 3 rounds) | Offers fix branches for pre-existing CI failures |
+| **Gaze integration** | Phase 1b quality analysis (if available) | Not included — uses CI results instead |
+
+**Decision guide**: Use `/review-council` while developing (before pushing), use `/review-pr` after the PR is open. They complement each other — `/review-council` catches issues early, `/review-pr` validates the PR in context with CI data.
+
+## Project Context Management (`/agent-brief`)
+
+`/agent-brief` manages the AGENTS.md lifecycle — the project briefing that AI coding agents read at the start of every session. AGENTS.md is the API contract between humans and AI agents: it tells agents how to build, test, and lint the project, what conventions to follow, and what constraints to respect.
+
+```text
+/agent-brief           # auto-detect: create if missing, audit if exists
+/agent-brief create    # force create mode (overwrite existing)
+/agent-brief audit     # force audit mode (read-only evaluation)
+```
+
+### Create Mode
+
+When no AGENTS.md exists (or forced with `create`), `/agent-brief` analyzes the project and generates a complete AGENTS.md from actual project signals:
+
+**Project signals analyzed**:
+- `go.mod`, `package.json`, `Cargo.toml`, `pyproject.toml` — language and dependencies
+- `Makefile`, `.github/workflows/` — build, test, lint commands (CI files are the source of truth)
+- `.golangci.yml`, `ruff.toml`, `.eslintrc*` — linter configuration
+- `README.md`, `LICENSE`, `.git/config` — project description and context
+- `.specify/memory/constitution.md`, `specs/`, `openspec/` — governance and spec framework
+
+The generated file has two tiers:
+- **Tier 1 sections** (filled from project data): Project Overview, Build & Test Commands, Project Structure, Code Conventions, Technology Stack
+- **Tier 1C sections** (context-sensitive, only generated when triggers are detected): Constitution/Governance, Specification Framework
+- **Tier 2 sections** (stubs with TODO guidance): Architecture, Testing Conventions, Git & Workflow, Behavioral Constraints
+
+The generated content is always shown for review before writing. Tier 2 stubs include detailed comments explaining what to fill and why it matters.
+
+### Audit Mode
+
+When AGENTS.md already exists, `/agent-brief` evaluates it against a section taxonomy and produces a quality score.
+
+**5-tier scoring rubric**:
+
+| Score | Criteria |
+|-------|----------|
+| **Excellent** | 5/5 Tier 1 + 4/4 Tier 2 + all applicable Tier 1C |
+| **Strong** | 5/5 Tier 1 + 2-3/4 Tier 2 |
+| **Adequate** | 4-5/5 Tier 1 |
+| **Weak** | 2-3/5 Tier 1 |
+| **Missing** | 0-1/5 Tier 1 |
+
+If Tier 1C sections are applicable (triggers detected) but missing, the score is downgraded by one level.
+
+The audit report includes section coverage, quality metrics (line count, build code blocks, staleness checks), and specific improvement suggestions with generated content for missing sections. You can apply suggestions interactively.
+
+### Bridge File Management
+
+After creating or auditing AGENTS.md, `/agent-brief` verifies cross-tool bridge files:
+
+- **CLAUDE.md** — should contain `@AGENTS.md` to import the project context into Claude Code sessions
+- **.cursorrules** — should reference AGENTS.md for Cursor IDE integration
+
+Bridge file creation is owned by `uf init`. If bridge files are missing or misconfigured, `/agent-brief` reports the status and suggests running `uf init` to create them.
+
+### Doctor Integration
+
+`uf doctor` includes deterministic structural checks for AGENTS.md quality as part of its 7-area health check. These checks verify section presence, build code blocks, directory tree accuracy, constitution references, and spec framework documentation — the same checks that `/agent-brief audit` runs, available as a quick pass/warn/fail diagnostic.
+
 ## Environment Setup
 
 The one-time setup for a new developer or a new project.

openspec/changes/command-docs/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: unbound-force
+created: 2026-05-02

openspec/changes/command-docs/design.md

@@ -0,0 +1,41 @@
+## Context
+
+The website's `common-workflows.md` is the primary location for slash command documentation. It already covers `/unleash`, `/finale`, and `/review-council` in detail. Two new commands need to be added: `/review-pr` (post-PR review) and `/agent-brief` (AGENTS.md lifecycle). Both are already shipped and documented in `.opencode/command/*.md` in the `unbound-force` repo.
+
+## Goals / Non-Goals
+
+### Goals
+- Add `/review-pr` documentation to the Code Review section of `common-workflows.md`
+- Add `/agent-brief` documentation to `common-workflows.md` as a "Project Context Management" section
+- Create a comparison table for `/review-council` vs `/review-pr`
+- Update the quick reference table with both commands
+- Document CI causality analysis (PR-caused vs pre-existing failure classification)
+
+### Non-Goals
+- Tutorial-style code review walkthrough (tracked in issue #66: Code Review Tutorial)
+- Detailed AGENTS.md best practices guide (tracked in issue #65: AGENTS.md Best Practices Blog Post)
+- Modifying existing `/review-council` documentation
+
+## Decisions
+
+1. **`/review-pr` in Code Review section**: Natural placement — it's the post-PR counterpart to `/review-council`. Add after the existing `/review-council` content with a comparison table.
+
+2. **`/agent-brief` in common-workflows**: Add as its own section — "Project Context Management". It's a workflow command, not a reference page. Placement in `common-workflows.md` is definitive for this change.
+
+3. **Comparison table from upstream AGENTS.md**: The `unbound-force/unbound-force` repo's AGENTS.md already has a review command comparison table. Adapt it for the website audience (less technical, more "when to use which").
+
+4. **CI causality analysis as a subsection**: This is `/review-pr`'s differentiating feature. Give it a dedicated subsection with a clear explanation of "PR-caused" vs "pre-existing" classification.
+
+## Risks / Trade-offs
+
+- **Risk**: `common-workflows.md` may become too long. The page is currently 465 lines; these additions may push it to ~650-700 lines. If total page length exceeds 700 lines after implementation, extract `/agent-brief` to its own page as a follow-up change. For this change, inline placement is preferred for discoverability.
+- **Trade-off**: `/agent-brief` could be a separate page. Chose inline — it's more discoverable in the workflows page and keeps all workflow commands in one place.
+
+## Content Sources
+
+Authoritative upstream source files for documentation content:
+- `/review-pr`: `unbound-force/unbound-force/.opencode/command/review-pr.md`
+- `/agent-brief`: `unbound-force/unbound-force/.opencode/command/agent-brief.md`
+- Comparison table: `unbound-force/unbound-force/AGENTS.md` (review command comparison section)
+
+All documented features (5-tier scoring rubric, CI causality analysis, 15-comment cap, etc.) must be verified against these upstream files at implementation time.

openspec/changes/command-docs/proposal.md

@@ -0,0 +1,53 @@
+## Why
+
+Two significant slash commands — `/review-pr` and `/agent-brief` — have shipped but are not documented on the website. `/review-pr` is the post-PR review counterpart to the already-documented `/review-council`, and `/agent-brief` manages the AGENTS.md lifecycle that is foundational to AI agent effectiveness.
+
+This change addresses GitHub issues #59 (`/review-pr`) and #60 (`/agent-brief`).
+
+## What Changes
+
+1. **`/review-pr` documentation**: Add to the Code Review section of `common-workflows.md` — command description, comparison table with `/review-council`, CI causality analysis explanation, fix branch offering.
+
+2. **`/agent-brief` documentation**: Add to `common-workflows.md` as a "Project Context Management" section — command description, create vs audit modes, 5-tier scoring rubric, context-sensitive section detection, bridge file management.
+
+3. **Quick reference table updates**: Add both commands to the quick reference table in `common-workflows.md`.
+
+## Capabilities
+
+### New Capabilities
+- `/review-pr` documentation in the Code Review section
+- `/agent-brief` documentation for AGENTS.md lifecycle management
+- Comparison table: `/review-council` vs `/review-pr` — when to use each
+
+### Modified Capabilities
+- `docs/getting-started/common-workflows`: Code Review section expanded, quick reference table updated
+
+### Removed Capabilities
+- None
+
+## Impact
+
+- 1 existing page modified (`common-workflows.md`) — Code Review section expanded, Project Context Management section added, quick reference table created
+- GitHub issues: [#59](https://github.com/unbound-force/website/issues/59), [#60](https://github.com/unbound-force/website/issues/60)
+
+## Constitution Alignment
+
+Assessed against the Unbound Force website project constitution (`.specify/memory/constitution.md`).
+
+### I. Content Accuracy
+
+**Assessment**: PASS
+
+Both commands are already shipped and documented in `.opencode/command/*.md` in the `unbound-force/unbound-force` repo. Content will be sourced from the upstream command files (`review-pr.md` and `agent-brief.md`) and cross-referenced with Dewey. Factual claims (5-tier scoring rubric, CI causality analysis, etc.) must be verified against the current shipped state before writing.
+
+### II. Minimal Footprint
+
+**Assessment**: PASS
+
+Adds Markdown content to an existing page (`common-workflows.md`). No custom HTML, CSS, JavaScript, or new dependencies. A quick reference table will be created to improve discoverability — this is standard Markdown with no custom layout.
+
+### III. Visitor Clarity
+
+**Assessment**: PASS
+
+Makes two undocumented commands discoverable. The comparison table (`/review-council` vs `/review-pr`) helps visitors choose the right review command for their situation. The quick reference table provides at-a-glance command discovery. Placement in `common-workflows.md` keeps all workflow commands in one location.

openspec/changes/command-docs/specs/commands.md

@@ -0,0 +1,69 @@
+## ADDED Requirements
+
+### Requirement: review-pr-docs
+
+The website MUST document the `/review-pr` command in the Code Review section of `common-workflows.md`.
+
+#### Scenario: user reads review-pr documentation
+
+- **GIVEN** a user visits the Common Workflows page
+- **WHEN** they read the Code Review section
+- **THEN** `/review-pr` MUST be documented with: purpose, usage syntax (`/review-pr [N]`), auto-detection from current branch, `gh` CLI requirement, CI causality analysis, fix branch offering
+- **AND** a comparison table with `/review-council` MUST be present (see requirement `review-pr-comparison-table` for table details)
+
+### Requirement: review-pr-causality-docs
+
+The `/review-pr` documentation MUST explain CI causality analysis.
+
+#### Scenario: user understands failure classification
+
+- **GIVEN** a user reads the CI causality section
+- **WHEN** they review how failures are classified
+- **THEN** the difference between "PR-caused" and "pre-existing" failures MUST be explained
+- **AND** the fix branch offering for pre-existing failures MUST be documented
+
+### Requirement: review-pr-comparison-table
+
+The Code Review section MUST include a comparison table showing when to use `/review-council` vs `/review-pr`.
+
+#### Scenario: user decides which review command to use
+
+- **GIVEN** a user wants to review code
+- **WHEN** they read the comparison table
+- **THEN** the table MUST cover at minimum: timing (pre-PR vs post-PR), scope, agent model, and use cases
+- **AND** a decision guide MUST help users pick the right command for their situation
+
+### Requirement: agent-brief-docs
+
+The website MUST document the `/agent-brief` command.
+
+#### Scenario: user reads agent-brief documentation
+
+- **GIVEN** a user visits the relevant documentation page
+- **WHEN** they read the `/agent-brief` section
+- **THEN** both modes MUST be documented: create (generates AGENTS.md from project signals including go.mod, package.json, Makefile, CI config, README) and audit (scores existing AGENTS.md with deterministic structural checks)
+- **AND** the 5-tier scoring rubric (Excellent/Strong/Adequate/Weak/Missing) MUST be described with tier names
+- **AND** context-sensitive section detection (constitution, spec framework) MUST be explained
+- **AND** bridge file management MUST document which files are created (CLAUDE.md, .cursorrules), when they are created vs validated, and their purpose
+- **AND** doctor integration (`uf doctor` structural checks) MUST be documented
+
+### Requirement: quick-reference-table
+
+A quick reference table MUST be created in `common-workflows.md` listing all documented slash commands with brief descriptions.
+
+#### Scenario: user scans quick reference
+
+- **GIVEN** a user reads `common-workflows.md`
+- **WHEN** they look for a summary of available commands
+- **THEN** a quick reference table MUST be present listing all documented commands
+- **AND** `/review-pr [N]` MUST be included with brief description
+- **AND** `/agent-brief` MUST be included with brief description
+- **AND** existing documented commands (`/unleash`, `/finale`, `/review-council`, `/speckit.specify`, `/opsx-propose`, `/cobalt-crush`) MUST also be included
+
+## MODIFIED Requirements
+
+_None._
+
+## REMOVED Requirements
+
+_None._