From fa2e2f4306356e059d91653d09ddf8b64d4e18ef Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Fri, 21 Aug 2026 16:21:00 -0400 Subject: [PATCH 1/3] docs: add review infrastructure and convention pack documentation - Add convention packs reference page (severity levels, pack types, loading mechanism, CI pack, governance hierarchy) - Add council-review-action reference page (three-workflow chain, persona discovery, configuration, security notes) - Add council-review-action tutorial (6-step adoption guide with SHA-pinned YAML examples and troubleshooting) - Add OpenCode slash commands to CLI reference (/agent-brief, /review-pr, /address-feedback) - Add Constitution Principle V: Security by Default - Update branch naming from NNN-* to speckit/NNN-* - Update developer guide with convention pack cross-reference - Update reference section index with new page entries Closes #206, #205, #190, #192, #142, #60, #59, #138 Assisted-by: claude-opus Generated with AI assistance (claude-opus) --- ...principle-v-20260821T201858-jay-flowers.md | 10 + ...or-personas-20260821T201852-jay-flowers.md | 10 + ...-infra-docs-20260821T201911-jay-flowers.md | 10 + ...maintenance-20260821T201902-jay-flowers.md | 10 + content/docs/getting-started/_index.md | 2 +- .../docs/getting-started/common-workflows.md | 9 +- content/docs/getting-started/constitution.md | 23 +- .../council-review-action-tutorial.md | 419 ++++++++++++++++++ content/docs/getting-started/developer.md | 4 +- content/docs/reference/_index.md | 10 +- content/docs/reference/cli.md | 72 +++ content/docs/reference/convention-packs.md | 128 ++++++ .../docs/reference/council-review-action.md | 202 +++++++++ .../changes/review-infra-docs/.openspec.yaml | 2 + openspec/changes/review-infra-docs/design.md | 63 +++ .../changes/review-infra-docs/proposal.md | 88 ++++ .../review-infra-docs/specs/cli-commands.md | 61 +++ .../specs/constitution-and-corrections.md | 73 +++ .../specs/convention-packs.md | 46 ++ .../specs/council-review-action.md | 61 +++ openspec/changes/review-infra-docs/tasks.md | 44 ++ 21 files changed, 1334 insertions(+), 13 deletions(-) create mode 100644 .uf/dewey/learnings/constitution-principle-v-20260821T201858-jay-flowers.md create mode 100644 .uf/dewey/learnings/divisor-personas-20260821T201852-jay-flowers.md create mode 100644 .uf/dewey/learnings/review-infra-docs-20260821T201911-jay-flowers.md create mode 100644 .uf/dewey/learnings/website-docs-maintenance-20260821T201902-jay-flowers.md create mode 100644 content/docs/getting-started/council-review-action-tutorial.md create mode 100644 content/docs/reference/convention-packs.md create mode 100644 content/docs/reference/council-review-action.md create mode 100644 openspec/changes/review-infra-docs/.openspec.yaml create mode 100644 openspec/changes/review-infra-docs/design.md create mode 100644 openspec/changes/review-infra-docs/proposal.md create mode 100644 openspec/changes/review-infra-docs/specs/cli-commands.md create mode 100644 openspec/changes/review-infra-docs/specs/constitution-and-corrections.md create mode 100644 openspec/changes/review-infra-docs/specs/convention-packs.md create mode 100644 openspec/changes/review-infra-docs/specs/council-review-action.md create mode 100644 openspec/changes/review-infra-docs/tasks.md diff --git a/.uf/dewey/learnings/constitution-principle-v-20260821T201858-jay-flowers.md b/.uf/dewey/learnings/constitution-principle-v-20260821T201858-jay-flowers.md new file mode 100644 index 0000000..9426172 --- /dev/null +++ b/.uf/dewey/learnings/constitution-principle-v-20260821T201858-jay-flowers.md @@ -0,0 +1,10 @@ +--- +tag: constitution-principle-v +author: jay-flowers +category: gotcha +created_at: 2026-08-21T20:18:58Z +identity: constitution-principle-v-20260821T201858-jay-flowers +tier: draft +--- + +When documenting Constitution Principle V (Security by Default) on the Unbound Force website, the content MUST be sourced from the upstream .specify/memory/constitution.md, not from GitHub issue descriptions or spec summaries. Principle V covers four MUST rules: (1) dependencies verified by content hash SHA256, (2) all external inputs validated and sanitized, (3) components operate with minimum permissions, and (4) external dependencies must be justified. Compound severity escalation does NOT belong under Principle V — it is defined in the severity.md convention pack, which is a Layer 2 governance artifact, not a Layer 1 constitutional principle. This distinction matters because placing convention pack mechanics inside a constitutional principle misrepresents the governance hierarchy. The spec review council caught this as a CRITICAL finding and it required correction before implementation could proceed. diff --git a/.uf/dewey/learnings/divisor-personas-20260821T201852-jay-flowers.md b/.uf/dewey/learnings/divisor-personas-20260821T201852-jay-flowers.md new file mode 100644 index 0000000..4119f26 --- /dev/null +++ b/.uf/dewey/learnings/divisor-personas-20260821T201852-jay-flowers.md @@ -0,0 +1,10 @@ +--- +tag: divisor-personas +author: jay-flowers +category: reference +created_at: 2026-08-21T20:18:52Z +identity: divisor-personas-20260821T201852-jay-flowers +tier: draft +--- + +When documenting Divisor persona counts on the Unbound Force website, the correct number is 9 total: 6 review personas (Guard, Architect, Adversary, Testing, SRE, Curator) and 3 content personas (Scribe, Herald, Envoy). All 9 are discovered dynamically by scanning for divisor-*.md files and all 9 are invoked by the review council. The content personas participate in reviews but defer code-level findings to the review personas. The discovery mechanism (from uf.review-council.md) states "the invocation list comes solely from discovery, not from this table." Pre-existing site references vary between 5, 6, and 9 — always verify against the upstream scaffold at unbound-force/unbound-force/internal/scaffold/assets/opencode/agents/ which has the authoritative set of 9 divisor-*.md files. diff --git a/.uf/dewey/learnings/review-infra-docs-20260821T201911-jay-flowers.md b/.uf/dewey/learnings/review-infra-docs-20260821T201911-jay-flowers.md new file mode 100644 index 0000000..f3b4ad7 --- /dev/null +++ b/.uf/dewey/learnings/review-infra-docs-20260821T201911-jay-flowers.md @@ -0,0 +1,10 @@ +--- +tag: review-infra-docs +author: jay-flowers +category: pattern +created_at: 2026-08-21T20:19:11Z +identity: review-infra-docs-20260821T201911-jay-flowers +tier: draft +--- + +During the review-infra-docs implementation, the spec review council (10 Divisor agents in parallel) identified 10 deduplicated finding themes across the spec artifacts. The most impactful finding was that compound severity escalation was misattributed to Constitution Principle V — 7 of 10 agents flagged this independently, demonstrating the value of multi-perspective review. The auto-fix pass addressed all findings in a single iteration, and the re-review confirmed all resolved. Key lesson: when documenting features that span multiple governance layers (constitution vs convention packs vs agent personas), always verify which layer the feature actually belongs to by reading the upstream source file, not relying on issue descriptions or memory. diff --git a/.uf/dewey/learnings/website-docs-maintenance-20260821T201902-jay-flowers.md b/.uf/dewey/learnings/website-docs-maintenance-20260821T201902-jay-flowers.md new file mode 100644 index 0000000..4b93542 --- /dev/null +++ b/.uf/dewey/learnings/website-docs-maintenance-20260821T201902-jay-flowers.md @@ -0,0 +1,10 @@ +--- +tag: website-docs-maintenance +author: jay-flowers +category: pattern +created_at: 2026-08-21T20:19:02Z +identity: website-docs-maintenance-20260821T201902-jay-flowers +tier: draft +--- + +When adding new pages to the website reference section (content/docs/reference/), the reference section index page at content/docs/reference/_index.md manually lists all reference pages with descriptions. New pages will appear in Hugo's sidebar automatically but will NOT appear on the _index.md landing page without a manual update. Always include a task to update _index.md when adding reference pages. Similarly, when modifying the constitution (e.g., adding a new principle), check all pages that reference the principle count — common locations include getting-started/_index.md, architecture.md, blog posts like the-8-phase-pipeline.md, and role-based guides (tester.md, product-owner.md). The count appears in more places than expected. diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md index 2fd29c6..de3391f 100644 --- a/content/docs/getting-started/_index.md +++ b/content/docs/getting-started/_index.md @@ -50,7 +50,7 @@ Ready to dive in? Start with the [Quick Start](/docs/getting-started/quick-start - **[Common Workflows](/docs/getting-started/common-workflows/)** -- The `/unleash` autonomous pipeline, `/finale` shipping workflow, manual feature flows, bug fixes, and code reviews - **[Hero Artifacts](/docs/getting-started/artifacts/)** -- Inter-hero communication: envelope format, artifact types, and lifecycle data flow - **[Knowledge Retrieval with Dewey](/docs/getting-started/knowledge/)** -- Install and configure Dewey for semantic search across your repositories -- **[Constitution](/docs/getting-started/constitution/)** -- The 4 core principles that govern all heroes and the governance model +- **[Constitution](/docs/getting-started/constitution/)** -- The 5 core principles that govern all heroes and the governance model ## Design Philosophy diff --git a/content/docs/getting-started/common-workflows.md b/content/docs/getting-started/common-workflows.md index 9756747..80ba2f3 100644 --- a/content/docs/getting-started/common-workflows.md +++ b/content/docs/getting-started/common-workflows.md @@ -35,7 +35,7 @@ toc: true ### Branch Safety -`/unleash` works with both Speckit (`NNN-*`) and OpenSpec (`opsx/*`) feature branches. It never runs on `main`. For Speckit branches, it validates that `spec.md` exists. For OpenSpec branches, it detects the change name from the branch (`opsx/`) and reads tasks from `openspec/changes//tasks.md`. +`/unleash` works with both Speckit (`speckit/NNN-*`) and OpenSpec (`opsx/*`) feature branches. It never runs on `main`. For Speckit branches, it validates that `spec.md` exists. For OpenSpec branches, it detects the change name from the branch (`opsx/`) and reads tasks from `openspec/changes//tasks.md`. After `/unleash` completes, the demo step suggests running `/finale` to commit, push, and create a PR. @@ -66,7 +66,7 @@ See also: [From Spec to Demo in One Command](/blog/unleash-in-practice/) — a n - Never commits without user approval of the commit message - If any step fails, stops immediately with context and options -`/finale` works with both Speckit (`NNN-*`) and OpenSpec (`opsx/*`) branches. It is the natural complement to `/unleash` — `/unleash` builds, `/finale` wraps up the branch and creates a PR for review. +`/finale` works with both Speckit (`speckit/NNN-*`) and OpenSpec (`opsx/*`) branches. It is the natural complement to `/unleash` — `/unleash` builds, `/finale` wraps up the branch and creates a PR for review. ## New Feature (End-to-End) {#new-feature-end-to-end} @@ -147,6 +147,7 @@ The [Developer (Cobalt-Crush)](/docs/getting-started/developer/) creates the tec - **Adversary**: Security, resilience, error handling - **Testing**: Test architecture, coverage strategy, assertion depth - **SRE**: Release pipeline, dependency health, observability + - **Curator**: Documentation gaps, blog/tutorial opportunities, website issue filing If the council returns REQUEST CHANGES, the developer addresses findings and re-submits (up to 3 iterations before escalation to human review). @@ -315,7 +316,7 @@ This creates `openspec/changes/fix-auth-timeout/` with: - `design.md` -- Technical approach - `tasks.md` -- Implementation steps -This creates an `opsx/fix-auth-timeout` branch and checks it out automatically. The `opsx/` prefix distinguishes OpenSpec branches from Speckit branches (`NNN-`) in `git branch` output. +This creates an `opsx/fix-auth-timeout` branch and checks it out automatically. The `opsx/` prefix distinguishes OpenSpec branches from Speckit branches (`speckit/NNN-`) in `git branch` output. ### 2. Implement @@ -370,7 +371,7 @@ The council discovers available Divisor persona agents in `.opencode/agents/divi | **SRE** | Release pipeline, dependency health, configuration, runtime observability | | **Curator** | Documentation gaps, blog/tutorial opportunities, website issue filing | -> **Note**: The table above lists the 6 review personas that participate in code review. Three additional content personas — Scribe (technical documentation), Herald (blog/announcements), and Envoy (public communications) — are invoked separately for content creation tasks and do not participate in the code review council. +> **Note**: The table above lists the 6 review personas with dedicated code review focus areas. Three additional content personas — Scribe (technical documentation), Herald (blog/announcements), and Envoy (public communications) — are also discovered and invoked by the review council, where they evaluate documentation quality, content opportunities, and communication clarity. Their code-level findings are deferred to the review personas above. ### CI Gate (Phase 1a and 1b) diff --git a/content/docs/getting-started/constitution.md b/content/docs/getting-started/constitution.md index 0572037..aa98f11 100644 --- a/content/docs/getting-started/constitution.md +++ b/content/docs/getting-started/constitution.md @@ -1,6 +1,6 @@ --- title: "Constitution" -description: "The 4 core principles that govern all Unbound Force heroes — Autonomous Collaboration, Composability First, Observable Quality, and Testability." +description: "The 5 principles governing all Unbound Force heroes — Autonomous Collaboration, Composability, Observable Quality, Testability, Security by Default." lead: "The foundational principles that govern every hero in the Unbound Force swarm." date: 2026-03-29T00:00:00+00:00 draft: false @@ -10,7 +10,7 @@ toc: true ## What the Constitution Is -The Unbound Force constitution is the highest-authority document in the organization. It defines four core principles that every hero must follow and every hero constitution must align with. All development practices, pull request reviews, specification pipelines, and quality gates operate within the boundaries set by these principles. +The Unbound Force constitution is the highest-authority document in the organization. It defines five core principles that every hero must follow and every hero constitution must align with. All development practices, pull request reviews, specification pipelines, and quality gates operate within the boundaries set by these principles. The constitution exists because an AI agent swarm that generates code rapidly needs structural constraints to prevent collapse. Without shared principles, heroes would make incompatible assumptions about communication, quality, and testability. The constitution makes those assumptions explicit, enforceable, and versioned. @@ -82,6 +82,19 @@ Every component built within the Unbound Force ecosystem MUST be testable in iso **Rationale**: AI agents generate code rapidly. If that code is not structurally testable, the resulting system will quickly collapse under its own unverified complexity. The Testability principle ensures that velocity never comes at the cost of verifiability. +## Principle V: Security by Default + +Every component built within the Unbound Force ecosystem MUST treat security as a structural property, not a review-time afterthought. Supply chain integrity, input validation, and least privilege MUST be enforced by design. + +### MUST Rules + +- Dependencies MUST be verified by content hash (SHA256 or equivalent) when downloaded outside a package manager's built-in verification. CI pipelines MUST pin actions and reusable workflows by commit SHA, not mutable tags. +- All external inputs (user input, API payloads, file contents, environment variables used as data) MUST be validated and sanitized before reaching any security-sensitive operation. +- Components MUST operate with the minimum permissions necessary. Secrets MUST be scoped to the narrowest context needed. File permissions MUST default to restrictive values (0o644 for files, 0o755 for executables and directories). +- Before adding an external dependency, the adopter MUST justify that the project's existing toolchain cannot cover the same use case. Every dependency is attack surface; the default answer is "do not add." + +**Rationale**: AI agents make adding dependencies and generating code trivially fast. Without structural security guardrails, the attack surface of the system grows with each generation cycle. + ## Hero Constitution Alignment Each hero repository maintains its own constitution that extends the organizational constitution: @@ -109,7 +122,7 @@ The constitution follows semantic versioning: | Change Type | Version Bump | Example | | ------------------------------------------------------------- | ------------ | ------------------------------------- | | Principle removal or incompatible redefinition of a MUST rule | MAJOR | Removing Testability principle | -| New principle added or materially expanded guidance | MINOR | Adding Testability (v1.0.0 -> v1.1.0) | +| New principle added or materially expanded guidance | MINOR | Adding Security by Default | | Clarifications, wording, or non-semantic refinements | PATCH | Rewording a rationale paragraph | ### Compliance Review @@ -132,7 +145,7 @@ Violations are CRITICAL severity and non-negotiable -- they must be resolved bef The `/constitution-check` command automates this assessment. OpenSpec proposals also include a Constitution Alignment section where each principle is evaluated against the proposed change. -The constitution is versioned (currently v1.1.0) and the check validates against the version referenced in the project's `parent_constitution` field. See the [contributing guide](/docs/contributing/) for how this fits into the specification pipeline. +The constitution is versioned (currently v1.2.0) and the check validates against the version referenced in the project's `parent_constitution` field. See the [contributing guide](/docs/contributing/) for how this fits into the specification pipeline. ## Governance Hierarchy @@ -150,5 +163,5 @@ A convention pack cannot override a constitutional principle. A command cannot b - Read [Hero Artifacts](/docs/getting-started/artifacts/) to understand the envelope format and artifact types referenced in Principle I - See [Common Workflows](/docs/getting-started/common-workflows/) for how the constitution gates the specification pipeline -- Read about [convention packs](/docs/getting-started/developer/#convention-packs/) — the constitution sets the floor; convention packs raise the bar with specific, severity-classified coding standards +- Read about [convention packs](/docs/reference/convention-packs/) — the constitution sets the floor; convention packs raise the bar with specific, severity-classified coding standards - Explore the [Team](/docs/team/) pages to see how each hero implements these principles diff --git a/content/docs/getting-started/council-review-action-tutorial.md b/content/docs/getting-started/council-review-action-tutorial.md new file mode 100644 index 0000000..025ce3b --- /dev/null +++ b/content/docs/getting-started/council-review-action-tutorial.md @@ -0,0 +1,419 @@ +--- +title: "Council Review Action Tutorial" +description: "Step-by-step guide to adding AI-assisted code review to your GitHub repository using the council-review-action." +lead: "Add multi-perspective AI code review to your pull requests in under 10 minutes." +date: 2026-08-21T00:00:00+00:00 +draft: false +weight: 75 +toc: true +--- + +## Prerequisites + +Before starting this tutorial, ensure: + +1. **GitHub repository with pull request workflow** -- you have a repository where PRs are the standard review mechanism +2. **Repository admin access** -- you need permission to add workflow files and configure repository secrets +3. **An API key for your LLM provider** -- Anthropic (direct), Google Cloud Vertex AI, or AWS Bedrock +4. **`uf` CLI installed and initialized** -- run `uf init --divisor` to deploy the review persona files + +```bash +uf init --divisor +``` + +Verify the personas were deployed: + +```bash +ls .opencode/agents/divisor-*.md +``` + +You should see nine persona files: `divisor-adversary.md`, `divisor-architect.md`, `divisor-curator.md`, `divisor-envoy.md`, `divisor-guard.md`, `divisor-herald.md`, `divisor-scribe.md`, `divisor-sre.md`, and `divisor-testing.md`. + +## Step 1: Deploy Review Personas + +The review personas are the agents that evaluate your pull requests. Each persona is a Markdown file in `.opencode/agents/` with frontmatter that defines its review focus area, ownership boundaries, and out-of-scope topics. + +Running `uf init --divisor` deploys nine persona files -- six review-focused and three content-focused: + +**Review Personas** + +| Persona | File | Focus | +|---------|------|-------| +| **Guard** | `divisor-guard.md` | Intent drift, constitution alignment, zero-waste compliance | +| **Architect** | `divisor-architect.md` | Structural integrity, coding conventions, pattern adherence | +| **Adversary** | `divisor-adversary.md` | Security, resilience, error handling, edge cases | +| **Testing** | `divisor-testing.md` | Test architecture, coverage strategy, assertion depth | +| **SRE** | `divisor-sre.md` | Deployment readiness, dependency health, observability | +| **Curator** | `divisor-curator.md` | Documentation gaps, blog/tutorial opportunities, website issue filing | + +**Content Personas** + +| Persona | File | Focus | +|---------|------|-------| +| **Scribe** | `divisor-scribe.md` | Technical documentation quality -- READMEs, specs, CLI help, API docs | +| **Herald** | `divisor-herald.md` | Blog and announcement opportunities -- release notes, feature write-ups | +| **Envoy** | `divisor-envoy.md` | Public communications -- messaging clarity, brand voice, community updates | + +Each persona has exclusive ownership boundaries -- a finding like "missing error handling" is raised by exactly one persona (the Adversary), not duplicated across reviewers. The content personas participate in the review council but defer code-level findings to the review personas. + +### What Happens + +The `uf init --divisor` command creates the `.opencode/agents/` directory (if it does not exist) and writes the persona files. These are the same agents used by the local `/review-council` command. The council-review-action discovers them at runtime by scanning for files matching the `divisor-*.md` pattern. + +You can customize the review scope by adding, removing, or editing persona files. The action picks up changes on the next PR. + +## Step 2: Add the Trigger Workflow + +Create `.github/workflows/council-review-trigger.yml` in your repository. This workflow fires on pull request events and dispatches the review workflow: + +```yaml +name: Council Review (Trigger) + +on: + pull_request: + types: [opened, synchronize, reopened] + +permissions: + contents: read + +jobs: + trigger-review: + runs-on: ubuntu-latest + if: github.event.pull_request.draft == false + steps: + - name: Dispatch review + uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + await github.rest.actions.createWorkflowDispatch({ + owner: context.repo.owner, + repo: context.repo.repo, + workflow_id: 'council-review.yml', + ref: context.payload.pull_request.head.ref, + inputs: { + pr_number: String(context.payload.pull_request.number), + head_sha: context.payload.pull_request.head.sha + } + }); +``` + +### What Happens + +When a pull request is opened, updated, or reopened, this workflow: + +1. Checks whether the PR is a draft (skips drafts by default) +2. Dispatches the review workflow with the PR number and head SHA +3. Exits -- the actual review runs in a separate workflow for security isolation + +> **Security**: Never hardcode API keys or tokens in workflow files. Always use GitHub repository secrets. + +## Step 3: Add the Review Workflow + +Create `.github/workflows/council-review.yml`. This is the core review engine that runs the Divisor personas against the PR diff: + +```yaml +name: Council Review + +on: + workflow_dispatch: + inputs: + pr_number: + description: "Pull request number" + required: true + head_sha: + description: "Head commit SHA" + required: true + +permissions: + contents: read + +jobs: + review: + runs-on: ubuntu-latest + steps: + - name: Checkout PR head + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + ref: ${{ inputs.head_sha }} + + - name: Discover personas + id: personas + run: | + personas=$(ls .opencode/agents/divisor-*.md 2>/dev/null | \ + sed 's|.*/divisor-||;s|\.md||' | tr '\n' ',' | sed 's/,$//') + echo "found=$personas" >> "$GITHUB_OUTPUT" + echo "Discovered personas: $personas" + + - name: Run review council + env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} + run: | + opencode run --agent divisor \ + --input "Review PR #${{ inputs.pr_number }}" \ + --headless + + - name: Upload review report + uses: actions/upload-artifact@ea165f8d65b6db9a8b9f2a4d0fe1225601bd1e24 # v4.6.2 + with: + name: review-report + path: .uf/artifacts/review-verdict/ +``` + +### What Happens + +The review workflow: + +1. Checks out the repository at the PR's head commit +2. Discovers available Divisor personas by scanning `.opencode/agents/divisor-*.md` +3. Runs each persona against the PR diff using headless `opencode run` invocations +4. Collects structured findings (severity, file, line, description) from each persona +5. Uploads the consolidated review report as a workflow artifact + +The review workflow runs in a clean environment with access to the LLM provider (via secrets) but no write access to the repository. This enforces the separation between the doer and the judge -- review agents can read and analyze, but they cannot modify code. + +## Step 4: Add the Comment Workflow + +Create `.github/workflows/council-review-comment.yml`. This workflow posts review findings back to the PR as comments: + +```yaml +name: Council Review (Comment) + +on: + workflow_run: + workflows: ["Council Review"] + types: [completed] + +permissions: + contents: read + pull-requests: write + +jobs: + comment: + runs-on: ubuntu-latest + if: github.event.workflow_run.conclusion == 'success' + steps: + - name: Download review report + uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: review-report + run-id: ${{ github.event.workflow_run.id }} + github-token: ${{ secrets.GITHUB_TOKEN }} + + - name: Post review comments + uses: actions/github-script@60a0d83039c74a4aee543508d2ffcb1c3799cdea # v7.0.1 + with: + github-token: ${{ secrets.GITHUB_TOKEN }} + script: | + const fs = require('fs'); + const report = JSON.parse( + fs.readFileSync('review-verdict/report.json', 'utf8') + ); + + let body = `## Council Review Results\n\n`; + body += `**Verdict**: ${report.verdict}\n\n`; + + for (const persona of report.personas) { + body += `### ${persona.name}\n`; + body += `**Status**: ${persona.status}\n\n`; + for (const finding of persona.findings) { + body += `- [${finding.severity}] ${finding.description}`; + if (finding.file) { + body += ` (${finding.file}:${finding.line})`; + } + body += `\n`; + } + body += `\n`; + } + + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: report.pr_number, + body: body + }); +``` + +### What Happens + +The comment workflow: + +1. Triggers when the review workflow completes successfully +2. Downloads the review report artifact from the review workflow run +3. Parses the structured findings and formats them for the GitHub PR interface +4. Posts a summary comment with the overall verdict and per-persona findings + +The three-workflow separation exists for security reasons. The `pull_request` event trigger runs with limited permissions (it cannot access secrets from forks). By chaining through `workflow_run`, the review and comment workflows run with the permissions needed to access LLM credentials and post PR comments. + +## Step 5: Configure Repository Secrets + +The review workflow needs API credentials for the LLM provider. Configure these in your repository settings under **Settings > Secrets and variables > Actions**. + +### Anthropic (Direct) + +Set one secret: + +| Secret | Value | +|--------|-------| +| `ANTHROPIC_API_KEY` | Your Anthropic API key | + +The workflow references it as `${{ secrets.ANTHROPIC_API_KEY }}`. + +### Google Cloud Vertex AI + +Set two secrets: + +| Secret | Value | +|--------|-------| +| `VERTEX_PROJECT_ID` | Your Google Cloud project ID | +| `VERTEX_REGION` | The Cloud region (e.g., `us-central1`) | + +The workflow also needs the `CLAUDE_CODE_USE_VERTEX` environment variable set to `"1"`. Add this to the review workflow's `env` block: + +```yaml +env: + CLAUDE_CODE_USE_VERTEX: "1" + ANTHROPIC_VERTEX_PROJECT_ID: ${{ secrets.VERTEX_PROJECT_ID }} + CLOUD_ML_REGION: ${{ secrets.VERTEX_REGION }} +``` + +### AWS Bedrock + +Set three secrets: + +| Secret | Value | +|--------|-------| +| `AWS_ACCESS_KEY_ID` | Your AWS access key ID | +| `AWS_SECRET_ACCESS_KEY` | Your AWS secret access key | +| `AWS_REGION` | The AWS region (e.g., `us-east-1`) | + +The workflow also needs the `CLAUDE_CODE_USE_BEDROCK` environment variable set to `"1"`. Add this to the review workflow's `env` block: + +```yaml +env: + CLAUDE_CODE_USE_BEDROCK: "1" + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + AWS_REGION: ${{ secrets.AWS_REGION }} +``` + +### Security Best Practices + +- **Scope secrets narrowly**: Use repository-level secrets, not organization-level secrets, unless multiple repositories share the same review configuration +- **Follow least privilege**: Grant only the permissions the action requires -- typically `pull-requests: write` and `contents: read` +- **Rotate keys regularly**: Treat LLM API keys like any other credential and rotate them on a schedule +- **Audit access**: Review which workflows consume each secret in your repository's Actions settings + +## Step 6: Verify the Setup + +Create a test pull request to verify the action is working: + +```bash +git checkout -b test/council-review-setup +echo "# Test" > test-review.md +git add test-review.md +git commit -m "test: verify council review action" +git push -u origin test/council-review-setup +gh pr create --title "test: verify council review action" --body "Testing the council-review-action setup." +``` + +### What Happens + +1. The trigger workflow detects the new PR and dispatches the review workflow +2. The review workflow discovers the Divisor personas and runs them against the diff +3. The comment workflow posts findings as a PR comment + +### Expected Output + +In the Actions tab, you should see three workflow runs. The review workflow logs show: + +```text +Review triggered on PR #1 +Discovered 9 review personas: + divisor-adversary, divisor-architect, divisor-curator, + divisor-envoy, divisor-guard, divisor-herald, + divisor-scribe, divisor-sre, divisor-testing + +Review findings posted as PR comments. +``` + +The PR receives a comment with the council's verdict and any findings. After verifying, close the test PR and delete the branch: + +```bash +gh pr close --delete-branch +git checkout main +git branch -D test/council-review-setup +``` + +## Troubleshooting + +### Missing Secrets + +**Symptom**: The review workflow fails with an authentication error. + +**Fix**: Verify that the required secrets are configured in **Settings > Secrets and variables > Actions**. The secret names must match what the workflow references (e.g., `ANTHROPIC_API_KEY`). + +### Incorrect Permissions + +**Symptom**: The comment workflow fails with a 403 error when posting PR comments. + +**Fix**: Ensure the comment workflow has `pull-requests: write` permission. Check both the workflow-level `permissions` block and the repository's default token permissions under **Settings > Actions > General > Workflow permissions**. + +### Workflow Trigger Not Firing + +**Symptom**: No workflow runs appear in the Actions tab after creating a PR. + +**Fix**: Verify the trigger workflow's `on:` block matches your PR events. Common issues: + +- The workflow file is not on the default branch (workflows must be merged to `main` before they trigger) +- The PR is a draft and the workflow skips drafts (`github.event.pull_request.draft == false`) +- GitHub Actions is disabled for the repository + +### No Personas Discovered + +**Symptom**: The review workflow runs but finds zero personas. + +**Fix**: Run `uf init --divisor` to deploy the persona files. Verify they exist: + +```bash +ls .opencode/agents/divisor-*.md +``` + +The files must be committed and pushed to the branch the PR is based on. + +### Review Takes Too Long + +**Symptom**: The review workflow times out or runs for an extended period. + +**Fix**: Large PRs with many changed files take longer to review. Consider: + +- Breaking large PRs into smaller, focused changes +- Setting a workflow timeout with `timeout-minutes` in the job definition +- Reviewing the LLM provider's rate limits for your API key tier + +## How It Fits Together + +The council-review-action uses a three-workflow chain to separate concerns: + +```text +PR opened/updated + | + v +Trigger workflow (detects event, dispatches review) + | + v +Review workflow (runs 9 Divisor personas) + | + v +Comment workflow (posts findings to PR) +``` + +Each workflow handles one responsibility. The trigger detects events, the review runs the AI agents, and the comment posts results. This separation provides security isolation -- the trigger workflow runs with minimal permissions, while the review workflow has access to LLM credentials, and the comment workflow has write access to post PR comments. + +The council-review-action adds AI-assisted review context to your pull requests. Human reviewers still make the final decisions -- the action gives them additional perspective from specialized review personas that evaluate security, architecture, testing, operations, and documentation in parallel. + +## See Also + +- [Code Review Tutorial](/docs/getting-started/code-review-tutorial/) -- interactive review workflow with `/review-council` and `/review-pr` +- [Council Review Action Reference](/docs/reference/council-review-action/) -- full configuration options and architecture details +- [Convention Packs](/docs/reference/convention-packs/) -- the coding standards the review personas enforce diff --git a/content/docs/getting-started/developer.md b/content/docs/getting-started/developer.md index aa8517f..9a10278 100644 --- a/content/docs/getting-started/developer.md +++ b/content/docs/getting-started/developer.md @@ -127,7 +127,7 @@ Each stage produces artifacts that feed the next. Specs must be committed and pu **OpenSpec** is the tactical workflow for smaller changes. It uses `/opsx-propose` to create a change with proposal, design, and tasks artifacts, then `/opsx-apply` to implement. See [Common Workflows](/docs/getting-started/common-workflows/) for the full flow. -Both workflows enforce branch conventions: Speckit uses `NNN-` branches (created by `/speckit.specify`), and OpenSpec uses `opsx/` branches (created by `/opsx-propose`). Branch validation is a hard gate at each pipeline step. +Both workflows enforce branch conventions: Speckit uses `speckit/NNN-` branches (created by `/speckit.specify`), and OpenSpec uses `opsx/` branches (created by `/opsx-propose`). Branch validation is a hard gate at each pipeline step. ## Working with Replicator @@ -195,7 +195,7 @@ Every session follows this ritual: ### Convention Packs -Convention packs are shared coding standards files stored in `.opencode/uf/packs/`. They function as feedforward controls — portable harness templates that guide agents before they write code, rather than correcting output after. Cobalt-Crush follows these conventions during implementation, and The Divisor enforces them during review. Every rule in a pack has a severity tag that determines how violations are handled. +Convention packs are shared coding standards files stored in `.opencode/uf/packs/`. They function as feedforward controls — portable harness templates that guide agents before they write code, rather than correcting output after. Cobalt-Crush follows these conventions during implementation, and The Divisor enforces them during review. Every rule in a pack has a severity tag that determines how violations are handled. See the full [Convention Packs reference](/docs/reference/convention-packs/) for details on all pack types, severity levels, and the CI convention pack. #### Pack Files diff --git a/content/docs/reference/_index.md b/content/docs/reference/_index.md index 4705be4..8d2051c 100644 --- a/content/docs/reference/_index.md +++ b/content/docs/reference/_index.md @@ -1,6 +1,6 @@ --- title: "Reference" -description: "Command reference and configuration documentation for the Unbound Force toolchain — CLI commands, flags, and subcommands." +description: "Reference documentation for the Unbound Force toolchain — CLI commands, convention packs, council review action, and configuration." lead: "Detailed reference documentation for the uf CLI and related tools." date: 2026-05-02T00:00:00+00:00 draft: false @@ -20,6 +20,14 @@ toc: true - **[Configuration](/docs/reference/config/)** -- Unified configuration system: layered loading, config sections, and common customizations. +## Convention Packs + +- **[Convention Packs](/docs/reference/convention-packs/)** -- Portable, severity-classified coding standards: pack types, severity levels (MUST/SHOULD/MAY), loading mechanism, and the CI convention pack. + +## Council Review Action + +- **[Council Review Action](/docs/reference/council-review-action/)** -- AI-powered multi-perspective code review as a GitHub Action: three-workflow chain architecture, persona discovery, and configuration. + ## Sandbox - **[Sandbox](/docs/reference/sandbox/)** -- Containerized AI agent sessions: Podman backends, mount modes, UID mapping, persistent workspaces, and security model. diff --git a/content/docs/reference/cli.md b/content/docs/reference/cli.md index 7bb9e3c..d9576b1 100644 --- a/content/docs/reference/cli.md +++ b/content/docs/reference/cli.md @@ -207,8 +207,80 @@ uf gateway [flags] | `status` | Show gateway status | | `stop` | Stop a running gateway | +## OpenCode Slash Commands + +Slash commands are typed within an [OpenCode](https://opencode.ai/) coding session, not in a terminal. They extend the `uf` toolchain with AI-assisted workflows for code review, project briefing, and feedback resolution. Each command is invoked by typing its name (e.g., `/review-pr`) in the OpenCode chat. + +### /agent-brief + +Manage the AGENTS.md lifecycle — create, audit, and improve the project briefing that AI coding agents read at session start. Auto-detects mode based on whether AGENTS.md exists. + +```text +/agent-brief [create | audit] +``` + +| Mode | Trigger | Purpose | +|------|---------|---------| +| **Create** | No AGENTS.md exists, or `create` argument | Analyze project structure, dependencies, CI workflows, and conventions to generate a comprehensive AGENTS.md | +| **Audit** | AGENTS.md exists, or `audit` argument | Score the existing file against a quality rubric, identify gaps, and suggest improvements | + +**Create mode** analyzes your project's language files (`go.mod`, `package.json`, etc.), CI workflows, linter configurations, and directory structure to generate an AGENTS.md that covers build commands, project structure, code style guidelines, and behavioral constraints. + +**Audit mode** evaluates the existing AGENTS.md against a section taxonomy covering essential sections (project overview, build commands, code style, project structure), context-sensitive sections (CI/CD, testing, behavioral constraints), and advanced sections (convention packs, knowledge retrieval). Produces a score from 1 (Missing) to 5 (Excellent). + +### /review-pr + +Review a pull request on GitHub with CI causality analysis. Auto-detects the open PR for the current branch, or accepts a PR number as an argument. + +```text +/review-pr [PR_NUMBER] +``` + +| Argument | Required | Description | +|----------|----------|-------------| +| `PR_NUMBER` | No | PR number to review (e.g., `42`). Auto-detected from current branch if omitted | + +**What it does**: + +1. Resolves the PR (auto-detect or explicit number) +2. Fetches PR metadata, changed files, and CI check results +3. Classifies each failing CI check as **PR-caused** or **pre-existing** (by comparing against the base branch) +4. Runs local tools only for checks CI did not already cover +5. Performs AI review on the scoped diff — alignment, security, and architecture +6. Posts a structured review with severity-classified findings + +**CI causality analysis** distinguishes your regressions from pre-existing failures. A check that fails on both the base branch and your PR is pre-existing — not your fault. A check that passes on the base branch but fails on your PR is a regression. + +Unlike `/review-council` (which runs locally before pushing), `/review-pr` operates on an existing GitHub PR and incorporates CI results. + +See the [Code Review Tutorial](/docs/getting-started/code-review-tutorial/) for a hands-on walkthrough of both commands in practice. + +### /address-feedback + +Triage and address PR review feedback with a structured four-phase workflow. Fetches all unresolved review comments from GitHub, classifies each item, presents a triage plan, then executes approved changes as a batch. + +```text +/address-feedback [PR_NUMBER] +``` + +| Argument | Required | Description | +|----------|----------|-------------| +| `PR_NUMBER` | No | PR number to address feedback for. Auto-detected from current branch if omitted | + +**Four-phase workflow**: + +| Phase | Name | Purpose | +|-------|------|---------| +| 1 | **Ingest** | Fetch all unresolved review comments, inline suggestions, and requested changes from the PR | +| 2 | **Assess** | Classify each item against project standards (constitution, convention packs, spec requirements) with evidence | +| 3 | **Triage** | Present classified items to the author for decision: Accept, Modify, Reject, or Keep (with justification) | +| 4 | **Execute** | Apply accepted changes as grouped commits, run `/review-council` gate, push, and reply to each comment with the resolution | + +The command integrates with the review lifecycle: after `/review-pr` or the council-review-action posts findings, use `/address-feedback` to systematically work through the feedback rather than manually addressing comments one by one. + ## See Also - [Quick Start](/docs/getting-started/quick-start/) -- Install and verify the toolchain - [Developer Guide](/docs/getting-started/developer/) -- Daily workflow with the `uf` CLI - [Common Workflows](/docs/getting-started/common-workflows/) -- End-to-end feature, bug fix, and review flows +- [Code Review Tutorial](/docs/getting-started/code-review-tutorial/) -- Step-by-step walkthrough of the review lifecycle diff --git a/content/docs/reference/convention-packs.md b/content/docs/reference/convention-packs.md new file mode 100644 index 0000000..86094d7 --- /dev/null +++ b/content/docs/reference/convention-packs.md @@ -0,0 +1,128 @@ +--- +title: "Convention Packs" +description: "Portable, severity-classified coding standards for the Unbound Force toolchain — pack types, severity levels, loading mechanism, and CI workflow rules." +lead: "Convention packs are the coding standards layer of the Unbound Force governance hierarchy. They guide agents before code is written and enforce rules during review." +date: 2026-05-02T00:00:00+00:00 +draft: false +weight: 30 +toc: true +--- + +## What Convention Packs Are + +Convention packs are portable, severity-classified coding standards that define how code should be written across the Unbound Force toolchain. Each pack is a Markdown file containing numbered rules, where every rule carries a severity tag (`[MUST]`, `[SHOULD]`, or `[MAY]`) that determines how violations are handled. + +Packs function as **feedforward controls** — they shape agent behavior *before* code is written, rather than correcting output afterward. This is the same principle behind type systems and linter configurations: prevent defects at the source instead of catching them downstream. + +In practice, two heroes interact with convention packs at different stages: + +- **Cobalt-Crush** loads the active packs during implementation and follows them as coding standards. Rules guide naming conventions, error handling patterns, documentation requirements, and architectural decisions. +- **The Divisor** enforces the same packs during code review. Each review persona checks the code against pack rules and classifies findings by the rule's severity level. + +Convention packs sit at **Layer 2** of the [governance hierarchy](/docs/getting-started/constitution/#governance-hierarchy) — between the constitution (which defines principles) and agent personas (which define roles). A convention pack cannot override a constitutional principle, but it can add specific, machine-enforceable rules that operationalize those principles into concrete standards. + +## Severity Levels + +Every rule in a convention pack carries one of three severity tags. These tags determine how violations are handled during review and map directly to finding severity in Divisor reports. + +- **`[MUST]`** — Mandatory requirements. Violations block the review: The Divisor issues REQUEST CHANGES and the finding is classified as CRITICAL or HIGH severity. Code cannot merge until all `[MUST]` violations are resolved. + +- **`[SHOULD]`** — Strong recommendations. Violations are flagged in the review but do not block the merge. Findings are classified as MEDIUM severity. Teams are expected to follow `[SHOULD]` rules unless there is a documented reason to deviate. + +- **`[MAY]`** — Optional improvements. Noted as suggestions in the review. Findings are classified as LOW severity. These represent best practices that improve code quality but are not required. + +This three-tier model follows RFC 2119 semantics, giving teams a clear vocabulary for distinguishing between hard requirements and aspirational standards. + +## Available Pack Types + +Convention packs cover both language-agnostic standards and language-specific rules. The following packs are available in the toolchain: + +| Pack | Scope | Description | +|------|-------|-------------| +| `default.md` | Language-agnostic | Coding style, architecture, security, testing, and documentation standards that apply to every project regardless of language. | +| `content.md` | Language-agnostic | Writing standards for documentation, blog posts, and website content — tone, structure, accuracy, and formatting rules. | +| `go.md` | Go | Go-specific rules: `gofmt` formatting, error handling patterns, GoDoc conventions, Cobra CLI patterns, and Go module structure. | +| `typescript.md` | TypeScript | TypeScript-specific rules: ESLint configuration, Prettier formatting, strict typing requirements, and architectural patterns. | +| `python.md` | Python | Python-specific rules for code style, type hints, testing conventions, and project structure. | +| `ci.md` | CI/CD | CI workflow authoring rules: GitHub Actions pinning, SHA verification, workflow file organization, and secrets handling. | +| `severity.md` | Cross-cutting | Shared severity definitions for all Divisor personas. Provides the calibration standard for CRITICAL, HIGH, MEDIUM, and LOW findings across every review. | + +Not all packs are deployed to every project. `uf init` deploys `default.md`, `severity.md`, and the language-specific pack matching your project's detected language. Other packs (like `ci.md`, `python.md`, or `typescript.md`) are deployed when the corresponding language or context is detected, or can be added manually. + +Each pack (except `severity.md`) has a corresponding `-custom.md` variant — for example, `default-custom.md`, `go-custom.md`, `content-custom.md`. Custom variants are user-owned files where you add project-specific rules that extend the base pack. They are never overwritten by `uf init` updates, so your customizations persist across toolchain upgrades. + +## Loading Mechanism + +Convention packs are stored in `.opencode/uf/packs/` at the root of your repository. The `uf init` command handles deployment: + +1. **Auto-detection**: `uf init` scans the project for language marker files (`go.mod`, `tsconfig.json`, `package.json`, `pyproject.toml`, `Cargo.toml`) and deploys the matching language pack alongside the default pack. + +2. **Manual override**: Use the `--lang` flag to override auto-detection when the marker file does not reflect the primary language: + + ```bash + uf init --lang go # Deploy Go pack regardless of detected markers + ``` + +3. **Selective deployment**: Use `--divisor` to deploy only the review agents and convention packs — useful for projects that want code review without the full swarm workflow. + +4. **Updates**: Running `uf init` again updates tool-owned packs to the latest embedded version. User-owned custom packs are never overwritten. + +## Ownership Model + +Convention pack files follow a dual-ownership model that separates toolchain standards from project-specific customizations: + +**Tool-owned files** (`default.md`, `go.md`, `typescript.md`, `content.md`, `ci.md`, `severity.md`) are managed by the toolchain. When you run `uf init`, these files are automatically updated to the latest version embedded in the `uf` binary. Do not edit these files directly — your changes will be overwritten on the next `uf init` run. Tool-owned files carry a version marker (``) for traceability. + +**User-owned files** (`default-custom.md`, `go-custom.md`, `content-custom.md`, etc.) are never overwritten. These are where you add project-specific rules. Use the `CR-NNN` prefix for custom rule IDs to distinguish them from tool-owned rules: + +```markdown +### CR-001: API Response Envelope [MUST] + +All REST API responses MUST use the standard envelope format: +`{ "data": ..., "meta": { "request_id": "..." } }`. +``` + +This separation means you can upgrade the toolchain freely without losing your project-specific standards, while still receiving updated base rules as the toolchain evolves. + +## The CI Convention Pack + +The CI convention pack (`ci.md`) addresses a specific problem: CI workflow files are infrastructure-as-code, but they are often written without the same rigor applied to application code. Misconfigured workflows create security vulnerabilities, flaky builds, and maintenance burden. + +The pack contains 12 rules for CI workflow authoring, covering: + +- **Action pinning** — GitHub Actions must be pinned by full commit SHA, not mutable tags. A `v3` tag can be force-pushed to point at malicious code; a SHA cannot. +- **SHA verification** — Pinned SHAs must be verified against the action's release history to prevent typosquatting. +- **Workflow file organization** — Naming conventions, job structure, and step ordering for maintainability. +- **Secrets handling** — Rules for how secrets are referenced, scoped, and isolated within workflow steps. + +The CI pack was introduced based on real-world findings from reviewing CI workflows across multiple repositories (see [GitHub issue #206](https://github.com/unbound-force/unbound-force/issues/206) for the original analysis). It applies the same `[MUST]`/`[SHOULD]`/`[MAY]` severity model as all other packs. + +## Governance Hierarchy + +Convention packs exist within a layered governance model where each layer constrains the layers below it: + +```text +Constitution (principles) + | +Convention Packs (rules) + | +Agent Personas (roles) + | +Commands (actions) + | +CI Pipelines (enforcement) +``` + +The key constraints: + +- A **convention pack cannot override a constitutional principle**. If the constitution requires testability, a convention pack cannot waive test requirements for a specific language. +- Convention packs **operationalize** the constitution's principles into concrete, machine-enforceable rules. Where the constitution says "all code must be testable," the Go convention pack specifies "exported functions must accept interfaces for external dependencies `[MUST]`." +- **Agent personas** are bound by convention packs. Cobalt-Crush cannot ignore a `[MUST]` rule, and The Divisor must flag violations at the correct severity level. + +This hierarchy ensures that organizational intent flows consistently from high-level principles to specific implementation standards. See the [constitution governance hierarchy](/docs/getting-started/constitution/#governance-hierarchy) for the full model. + +## See Also + +- [Constitution](/docs/getting-started/constitution/) — the foundational principles that convention packs implement +- [Developer Guide: Convention Packs](/docs/getting-started/developer/#convention-packs) — how packs integrate into daily workflows +- [Code Review Tutorial](/docs/getting-started/code-review-tutorial/) — how convention pack violations appear in review findings diff --git a/content/docs/reference/council-review-action.md b/content/docs/reference/council-review-action.md new file mode 100644 index 0000000..05c5146 --- /dev/null +++ b/content/docs/reference/council-review-action.md @@ -0,0 +1,202 @@ +--- +title: "Council Review Action" +description: "Multi-perspective AI code review as a GitHub Action — three-workflow chain, persona discovery, and configuration." +lead: "The council-review-action brings multi-perspective AI code review to any GitHub repository through a composite GitHub Action. Specialized reviewers evaluate security, architecture, testing, operations, and documentation in parallel." +date: 2026-05-02T00:00:00+00:00 +draft: false +weight: 40 +toc: true +--- + +## What the Council Review Action Does + +The council-review-action is a composite GitHub Action that adds multi-perspective AI code review to pull requests. It runs the same Divisor review council used locally by `/review-council`, but in a CI environment where reviews happen automatically on every PR. + +Nine Divisor personas are discovered and invoked in parallel -- six focused on code review and three on content. Each evaluates through a different lens: + +**Review Personas** + +| Persona | Focus | +|---------|-------| +| **Guard** | Intent drift detection, constitution alignment, zero-waste compliance | +| **Architect** | Structural integrity, coding conventions, pattern adherence, DRY | +| **Adversary** | Security, resilience, error handling, edge cases | +| **Testing** | Test architecture, coverage strategy, assertion depth, isolation | +| **SRE** | Deployment readiness, dependency health, observability, operational concerns | +| **Curator** | Documentation gaps, blog/tutorial opportunities, website issue filing | + +**Content Personas** + +| Persona | Focus | +|---------|-------| +| **Scribe** | Technical documentation quality -- READMEs, specs, CLI help, API docs | +| **Herald** | Blog and announcement opportunities -- release notes, feature write-ups | +| **Envoy** | Public communications -- messaging clarity, brand voice, community updates | + +Each persona has exclusive ownership boundaries -- a finding like "missing error handling" is raised by exactly one persona (the Adversary), not duplicated across multiple reviewers. This prevents overlap and ensures each finding comes from the agent with the deepest domain expertise. The content personas participate in the review council but defer code-level findings to the review personas -- their focus is documentation completeness, content opportunities, and communication quality. + +The action assists human reviewers by surfacing issues that are easy to miss in manual review -- security edge cases, architectural drift, test quality gaps, and operational concerns. It does not replace human review. The structural differentiator is the multi-persona architecture: rather than a single AI reviewer producing a monolithic report, independent agents evaluate the same diff through different quality dimensions, producing findings that are scoped, non-overlapping, and actionable. + +## Three-Workflow Chain Architecture + +The council-review-action uses a three-workflow chain to separate concerns and work within GitHub Actions' security model. Each workflow handles one stage of the review pipeline: + +```text +PR opened/updated --> Trigger --> Review (9 personas) --> Comment --> PR comments posted +``` + +### 1. Trigger Workflow + +The trigger workflow fires on `pull_request` events. It determines whether a review should run based on configurable criteria: + +- Skip draft PRs (configurable) +- Filter by label (e.g., only review PRs labeled `review-ready`) +- Skip PRs from bots or automated processes + +When a review is warranted, the trigger workflow dispatches the review workflow with the PR context (number, head SHA, base branch). + +### 2. Review Workflow + +The review workflow is the core review engine. It: + +1. Clones the repository at the PR's head commit +2. Discovers available Divisor personas from `.opencode/agents/divisor-*.md` +3. Runs each persona against the PR diff using headless `opencode run` invocations +4. Collects structured findings from each persona (severity, file, line, description) +5. Produces a consolidated review report + +The review workflow runs in a clean environment with access to the LLM provider (via secrets) but no write access to the repository. This enforces the separation between the doer and the judge -- review agents can read and analyze, but they structurally cannot modify code. + +### 3. Comment Workflow + +The comment workflow receives the review report and posts findings as GitHub PR comments: + +- Groups findings by persona with severity indicators +- Adds inline code annotations for file-specific findings where applicable +- Posts a summary with the overall review verdict (APPROVE or REQUEST CHANGES) +- Formats output for readability in the GitHub PR interface + +The three-workflow separation exists for security reasons. The `pull_request` event trigger runs with limited permissions (it cannot access secrets from forks). By chaining through a `workflow_run` or `repository_dispatch`, the review and comment workflows run with the permissions needed to access LLM credentials and post PR comments. + +## Persona Discovery + +The action discovers review personas dynamically at runtime rather than hardcoding a fixed set. This means adding or removing a persona is a file operation, not a code change. + +Discovery works as follows: + +1. The review workflow scans the `.opencode/agents/` directory in the repository +2. It matches files with the `divisor-*.md` naming pattern +3. Each matching file is treated as a review persona +4. The persona's frontmatter defines its review focus area, ownership boundaries, and out-of-scope topics + +The default personas ship with `uf init --divisor`: nine agents total (Guard, Architect, Adversary, SRE, Testing, Curator, Scribe, Herald, and Envoy). Repositories can customize the review scope: + +- **Add a persona**: Create a new `divisor-.md` file in `.opencode/agents/` with the appropriate frontmatter. The action picks it up on the next PR. +- **Remove a persona**: Delete the corresponding `divisor-.md` file. The action stops running that persona. +- **Modify a persona**: Edit the persona's frontmatter to change its focus area or ownership boundaries. + +This is the same discovery mechanism used by the local `/review-council` command, ensuring consistency between local and CI reviews. + +## Configuration + +### Required Inputs + +The action accepts inputs through the workflow YAML configuration: + +| Input | Required | Description | +|-------|----------|-------------| +| `model` | No | LLM model to use for review (defaults to the model configured in `opencode.json`) | +| `pr_number` | Yes | Pull request number to review (typically `${{ github.event.pull_request.number }}`) | +| `head_sha` | Yes | Head commit SHA of the PR (typically `${{ github.event.pull_request.head.sha }}`) | + +### Secrets + +The action requires API credentials for the LLM provider that powers the review agents. Configure these as repository secrets in your GitHub repository settings. + +For **Anthropic Direct**: + +```yaml +env: + ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }} +``` + +For **Google Cloud Vertex AI** (using Workload Identity Federation): + +```yaml +env: + CLAUDE_CODE_USE_VERTEX: "1" + ANTHROPIC_VERTEX_PROJECT_ID: ${{ secrets.VERTEX_PROJECT_ID }} + CLOUD_ML_REGION: ${{ secrets.VERTEX_REGION }} +``` + +For **AWS Bedrock**: + +```yaml +env: + CLAUDE_CODE_USE_BEDROCK: "1" + AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }} + AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }} + AWS_REGION: ${{ secrets.AWS_REGION }} +``` + +> **Security Note**: Secrets should be scoped to the narrowest context needed. Use repository-level secrets, not organization-level secrets, unless multiple repositories share the same review configuration. Workflow permissions should follow the principle of least privilege -- grant only the permissions the action requires (typically `pull-requests: write` and `contents: read`). + +### Workflow Permissions + +The workflows in the chain require different permission levels: + +| Workflow | Permissions Needed | +|----------|-------------------| +| Trigger | `contents: read` | +| Review | `contents: read` (plus LLM provider secrets) | +| Comment | `pull-requests: write`, `contents: read` | + +Set permissions explicitly in each workflow file rather than relying on the repository's default token permissions: + +```yaml +permissions: + contents: read + pull-requests: write +``` + +### Environment Variables + +Beyond the LLM provider credentials, the action respects these environment variables: + +| Variable | Description | +|----------|-------------| +| `OPENCODE_MODEL` | Override the default model for all review agents | +| `REVIEW_SKIP_DRAFTS` | Set to `true` to skip draft PRs (default: `true`) | + +## Integration with the Review Lifecycle + +The council-review-action is the CI counterpart to the local `/review-council` command. Together with `/review-pr`, they form a complete review lifecycle: + +| Stage | Tool | When It Runs | What It Does | +|-------|------|-------------|--------------| +| Pre-PR (local) | `/review-council` | Before pushing | Multi-persona review of local changes with CI gate | +| Post-PR (CI) | council-review-action | After PR is created | Automated multi-persona review in CI | +| Post-PR (local) | `/review-pr` | After PR is created | Single-agent review with CI causality analysis | + +The typical workflow: + +1. **Develop locally** -- write code, run tests +2. **Run `/review-council`** -- catch issues before pushing. The council runs a CI gate first, then launches the Divisor personas. Address any REQUEST CHANGES findings. +3. **Push and create PR** -- the council-review-action fires automatically in CI, providing a second review pass +4. **Optionally run `/review-pr`** -- for CI causality analysis (classifying failures as PR-caused vs. pre-existing) and fix-branch offers for pre-existing issues + +The local `/review-council` and the CI council-review-action use the same persona discovery mechanism and the same Divisor agents. The difference is context: the local command has access to your working tree and can run the CI gate against local changes, while the CI action reviews the PR diff in a clean environment. + +See the [Code Review Tutorial](/docs/getting-started/code-review-tutorial/) for a step-by-step walkthrough of the complete review lifecycle. + +## Adopting the Action + +Setting up the council-review-action involves adding three workflow files to your repository's `.github/workflows/` directory -- one for each stage of the chain (trigger, review, comment). The action also requires Divisor persona files in `.opencode/agents/`, which `uf init` deploys automatically. + +For step-by-step setup instructions, see the [Council Review Action Tutorial](/docs/getting-started/council-review-action-tutorial/). + +## See Also + +- [Council Review Action Tutorial](/docs/getting-started/council-review-action-tutorial/) -- step-by-step setup guide for adding the action to your repository +- [Code Review Tutorial](/docs/getting-started/code-review-tutorial/) -- local review workflow with `/review-council` and `/review-pr` +- [Convention Packs](/docs/reference/convention-packs/) -- the coding standards that review personas enforce diff --git a/openspec/changes/review-infra-docs/.openspec.yaml b/openspec/changes/review-infra-docs/.openspec.yaml new file mode 100644 index 0000000..018e641 --- /dev/null +++ b/openspec/changes/review-infra-docs/.openspec.yaml @@ -0,0 +1,2 @@ +schema: unbound-force +created: 2026-08-21 diff --git a/openspec/changes/review-infra-docs/design.md b/openspec/changes/review-infra-docs/design.md new file mode 100644 index 0000000..3361114 --- /dev/null +++ b/openspec/changes/review-infra-docs/design.md @@ -0,0 +1,63 @@ +## Context + +The Unbound Force website documents the organization's AI agent swarm for software engineering. Ten GitHub issues describe shipped features and capabilities that have no corresponding website documentation: convention packs, updated branch naming, review infrastructure commands, the council-review-action GitHub Action, Constitution Principle V, and internal toolchain improvements. + +The proposal identifies three categories of work: new reference pages, new tutorial content, and updates to existing pages. All changes are Markdown content files within the existing Hugo/Doks site structure. No templates, SCSS, configuration, or build infrastructure changes are needed. + +## Goals / Non-Goals + +### Goals + +- Document convention packs as a concept with a dedicated reference page, covering structure (MUST/SHOULD/MAY severity), loading mechanism, and the CI pack as an example +- Add council-review-action reference documentation and a step-by-step adoption tutorial +- Add CLI reference entries for `/agent-brief`, `/address-feedback`, and `/review-pr` +- Add Constitution Principle V (Security by Default) to the constitution page +- Correct branch naming from `NNN-` to `speckit/NNN-` in all content pages containing the old pattern (common-workflows.md, developer.md) +- Cross-reference new content from existing pages (developer guide, constitution governance hierarchy) + +### Non-Goals + +- Documenting every convention pack rule verbatim (the reference page describes the system; individual packs live in source repos) +- Rewriting the code-review-tutorial.md (it already covers `/review-pr` at the tutorial level) +- Documenting review-context skill internals or replicator scaffold internals (these are contributor-facing details that belong in AGENTS.md or upstream repos, not the public website) +- Adding navigation menu entries (new pages appear in the sidebar automatically via Hugo section hierarchy) + +## Decisions + +### D1: Convention packs get a reference page, not a getting-started page + +Convention packs are a lookup resource (what are they, what packs exist, what severity levels mean) rather than a sequential learning topic. Placing the page at `content/docs/reference/convention-packs.md` follows the existing pattern where reference/ contains tool and concept documentation (cli.md, config.md, gateway.md, sandbox.md). The developer guide will cross-reference this page for workflow context. + +### D2: CLI commands are added to the existing cli.md rather than separate pages + +The existing cli.md documents `uf` CLI subcommands. The three new commands (`/agent-brief`, `/address-feedback`, `/review-pr`) are OpenCode slash commands, not `uf` subcommands — they have a different invocation model (typed in an AI coding session, not a terminal). Adding them to cli.md under a clearly delineated new section ("OpenCode Slash Commands") with an introductory paragraph explaining the difference avoids fragmenting the reference across multiple pages while maintaining accuracy about command types. + +### D3: Council-review-action gets both reference and tutorial pages + +The council-review-action is a standalone GitHub Action that downstream repos adopt independently. It needs both a reference page (configuration options, workflow chain, persona discovery) and a tutorial (step-by-step adoption guide). This follows the existing pattern where code-review-tutorial.md complements the CLI reference. + +### D4: Principle V is added inline to the existing constitution page + +The constitution page documents all principles in a single page with a consistent structure (heading, description, MUST rules, SHOULD rules, rationale). Principle V follows the same pattern. This keeps the constitution as a single authoritative document rather than splitting it across pages. + +### D5: Review-context skill and replicator scaffold updates are handled via cross-references + +Issues #226 (review-context skill) and #231 (replicator scaffold) describe internal toolchain improvements. Rather than creating dedicated website pages for internal mechanics, relevant user-facing impacts will be noted in the developer guide and convention pack reference. Contributors needing deeper detail are directed to upstream AGENTS.md files. + +### D6: Branch naming is a corrective update, not a new page + +The `speckit/NNN-` branch prefix (#205) replaces the old `NNN-` convention. This is a find-and-replace across all content pages containing the old pattern (common-workflows.md and developer.md), not a documentation expansion. AGENTS.md also contains the old pattern but is out of scope for this change. The change is small but important for accuracy. + +## Risks / Trade-offs + +### Risk: Upstream content drift + +Convention pack rules and council-review-action configuration may change in upstream repos after this documentation is published. **Mitigation**: Document the concept and structure rather than exhaustively listing every rule. Link to source repositories for canonical rule definitions. This follows the Content Accuracy constraint in AGENTS.md — describe what exists without overstating. + +### Risk: Principle V sourcing accuracy + +Constitution Principle V content must be sourced from the actual upstream constitution, not fabricated. **Mitigation**: Implementation tasks must read the upstream `.specify/memory/constitution.md` or the relevant GitHub issue (#142) to extract the exact principle text, MUST rules, and rationale. The website page adapts (not copies) the upstream content for a website audience. + +### Trade-off: Internal toolchain docs excluded + +Issues #226 and #231 describe contributor-facing toolchain improvements that are not documented on the public website. This reduces the issue coverage from 10/10 to 8/10 in terms of dedicated pages. **Accepted** because the website audience is users and adopters, not internal swarm contributors. Internal toolchain docs belong in upstream AGENTS.md files. diff --git a/openspec/changes/review-infra-docs/proposal.md b/openspec/changes/review-infra-docs/proposal.md new file mode 100644 index 0000000..c0238f6 --- /dev/null +++ b/openspec/changes/review-infra-docs/proposal.md @@ -0,0 +1,88 @@ +# Proposal: Review Infrastructure Documentation + +## Why + +The Unbound Force website currently has significant documentation gaps around review infrastructure, convention packs, and recently-shipped capabilities. Ten GitHub issues (#206, #205, #226, #231, #190, #192, #142, #60, #59, #138) describe features and changes that exist in the codebase but have no corresponding website documentation. Users cannot discover these capabilities, and contributors cannot understand the review lifecycle end-to-end. + +Specific gaps: + +- **Convention packs** are referenced in existing docs (constitution page, governance hierarchy) but have no dedicated documentation. The CI convention pack (#206) adds 12 rules for CI workflow authoring that are entirely undocumented. +- **Branch naming** changed from `NNN-` to `speckit/NNN-` (#205), but existing docs (common-workflows.md) still reference the old pattern. +- **Three CLI commands** (`/agent-brief`, `/review-pr`, `/address-feedback`) have no reference documentation. `/review-pr` has tutorial coverage in code-review-tutorial.md but no CLI reference entry. +- **Council-review-action** (#190, #192) is a composite GitHub Action for AI code review with no docs or adoption tutorial. +- **Constitution Principle V: Security by Default** (#142) was added upstream but the website constitution page still only documents Principles I-IV. +- **Review-context skill** (#226) and **replicator scaffold updates** (#231) represent internal toolchain improvements that need documentation for contributors. + +Without these docs, the website presents an incomplete and outdated picture of the system. Users hitting convention pack violations, CI review failures, or branch naming errors have nowhere to look for guidance. + +## What Changes + +### New Pages + +1. **Convention Packs reference page** (`content/docs/reference/convention-packs.md`) — explains what convention packs are, how they're structured (MUST/SHOULD/MAY severity levels), how they're loaded, and links to the available packs. Covers issue #206 (CI pack) as one of the documented packs. + +2. **Council Review Action reference page** (`content/docs/reference/council-review-action.md`) — documents the composite GitHub Action: three-workflow chain, persona discovery, configuration options, and integration with the review lifecycle. Covers issue #190. + +3. **Council Review Action tutorial** (`content/docs/getting-started/council-review-action-tutorial.md`) — step-by-step adoption guide for adding the council-review-action to a downstream repository. Covers issue #192. + +4. **Agent Brief command reference** (addition to `content/docs/reference/cli.md`) — documents `/agent-brief` create and audit modes, AGENTS.md lifecycle management. Covers issue #60. + +5. **Address Feedback command reference** (addition to `content/docs/reference/cli.md`) — documents `/address-feedback` four-phase workflow for PR review feedback triage. Covers issue #138. + +6. **Review PR command reference** (addition to `content/docs/reference/cli.md`) — documents `/review-pr` post-PR GitHub review, CI causality analysis. Covers issue #59. + +### Modified Pages + +7. **Constitution page** (`content/docs/getting-started/constitution.md`) — add Principle V: Security by Default, covering supply chain integrity, input validation, least privilege, and dependency justification as defined in the upstream constitution. Covers issue #142. + +8. **Common Workflows page** (`content/docs/getting-started/common-workflows.md`) and **Developer guide** (`content/docs/getting-started/developer.md`) — update branch naming from `NNN-` to `speckit/NNN-` in all pages containing the old pattern. Covers issue #205. + +9. **Developer guide** (`content/docs/getting-started/developer.md`) — add or expand convention pack section to cross-reference the new reference page and explain CI pack integration. Partial coverage of issues #206, #226, #231. + +## Capabilities + +### New + +- Convention pack reference documentation (what they are, how they work, available packs) +- Council-review-action reference and tutorial pages +- `/agent-brief`, `/address-feedback`, `/review-pr` CLI reference entries +- Constitution Principle V documentation + +### Modified + +- Constitution page expanded from 4 to 5 principles +- Common workflows updated with current branch naming convention +- Developer guide expanded with convention pack cross-references + +### Removed + +None. + +## Impact + +- **Navigation**: Two new pages in the Reference section (convention-packs, council-review-action). One new page in Getting Started (council-review-action tutorial). CLI reference page gains three new command sections. No menu changes needed — these pages appear in the sidebar automatically via Hugo section hierarchy. +- **Existing content**: Constitution page gains a new section (additive). Common workflows page gets a find-and-replace on branch naming patterns (corrective). Code review tutorial is not modified — it already covers `/review-pr` at the tutorial level. +- **Build**: All changes are Markdown content files. No template, SCSS, or configuration changes required. `npm run build` validates all pages render. +- **Cross-references**: New convention pack page will be linked from the constitution governance hierarchy section and the developer guide. Council-review-action pages cross-reference the code review tutorial. + +## Constitution Alignment + +### Principle I: Autonomous Collaboration — PASS + +This change documents artifact-based communication patterns (convention packs, review artifacts, council review output). All new documentation describes how heroes exchange work through files and schemas, reinforcing Principle I. + +### Principle II: Composability First — PASS + +Convention pack documentation explicitly covers how packs are independently loadable and composable. Council-review-action docs show how it integrates without requiring the full swarm. This directly supports composability. + +### Principle III: Observable Quality — PASS + +Documenting convention pack severity levels (MUST/SHOULD/MAY), CI convention rules, and review infrastructure improves transparency of quality enforcement. Users can now understand how quality claims are automated and verified. + +### Principle IV: Testability — N/A + +This change is documentation-only. No code is produced, so testability constraints do not apply. Validation is via `npm run build` and visual inspection per AGENTS.md. + +### Principle V: Security by Default — N/A + +This change is documentation-only. No code, dependencies, or secrets are introduced. The documentation of Principle V itself is sourced from the upstream constitution to ensure accuracy. diff --git a/openspec/changes/review-infra-docs/specs/cli-commands.md b/openspec/changes/review-infra-docs/specs/cli-commands.md new file mode 100644 index 0000000..fdcb171 --- /dev/null +++ b/openspec/changes/review-infra-docs/specs/cli-commands.md @@ -0,0 +1,61 @@ +## ADDED Requirements + +### Requirement: OpenCode Slash Commands Section + +The CLI reference page (`content/docs/reference/cli.md`) MUST be updated to include a new top-level section for OpenCode slash commands, clearly separated from the existing `uf` CLI subcommands. The section SHOULD be introduced with a paragraph explaining that slash commands are typed within an AI coding session (e.g., OpenCode), not in a terminal. Each command section below MUST follow the existing CLI reference pattern (usage code block, description, flags/options table where applicable). + +### Requirement: Agent Brief Command Reference + +The CLI reference page (`content/docs/reference/cli.md`) MUST be updated to include documentation for the `/agent-brief` command under the new OpenCode Slash Commands section. The section MUST cover: + +- Command purpose: AGENTS.md lifecycle management +- Two modes: `create` (generate AGENTS.md from project analysis) and `audit` (validate existing AGENTS.md for completeness and accuracy) +- Usage syntax and options +- Example output for each mode + +#### Scenario: User looks up /agent-brief usage + +- **GIVEN** a user wants to generate or audit their project's AGENTS.md +- **WHEN** they read the `/agent-brief` section in the CLI reference +- **THEN** they understand the two modes (create/audit), their purposes, and how to invoke them + +### Requirement: Review PR Command Reference + +The CLI reference page (`content/docs/reference/cli.md`) MUST be updated to include documentation for the `/review-pr` command under the OpenCode Slash Commands section. The section MUST cover: + +- Command purpose: post-PR GitHub review with CI causality analysis +- How it differs from `/review-council` (post-PR vs pre-PR) +- CI causality analysis: distinguishing pre-existing CI failures from PR-introduced failures +- Usage syntax and options +- Cross-reference to the code review tutorial for workflow context + +The section SHOULD note that the code-review-tutorial.md provides a hands-on walkthrough of `/review-pr` in practice. + +#### Scenario: User looks up /review-pr usage + +- **GIVEN** a user has submitted a PR and wants AI review with CI analysis +- **WHEN** they read the `/review-pr` section in the CLI reference +- **THEN** they understand the command's purpose, CI causality analysis capability, and how to invoke it + +### Requirement: Address Feedback Command Reference + +The CLI reference page (`content/docs/reference/cli.md`) MUST be updated to include documentation for the `/address-feedback` command under the OpenCode Slash Commands section. The section MUST cover: + +- Command purpose: PR review feedback triage and resolution +- The four-phase workflow (collect, classify, plan, execute) +- How it integrates with the review lifecycle (used after receiving review comments) +- Usage syntax and options + +#### Scenario: User looks up /address-feedback usage + +- **GIVEN** a user has received PR review comments and wants to systematically address them +- **WHEN** they read the `/address-feedback` section in the CLI reference +- **THEN** they understand the four-phase workflow and how to invoke the command + +## MODIFIED Requirements + +None. + +## REMOVED Requirements + +None. diff --git a/openspec/changes/review-infra-docs/specs/constitution-and-corrections.md b/openspec/changes/review-infra-docs/specs/constitution-and-corrections.md new file mode 100644 index 0000000..0d39b62 --- /dev/null +++ b/openspec/changes/review-infra-docs/specs/constitution-and-corrections.md @@ -0,0 +1,73 @@ +## ADDED Requirements + +### Requirement: Constitution Principle V Documentation + +The constitution page (`content/docs/getting-started/constitution.md`) MUST be updated to include Principle V: Security by Default. The new section MUST follow the same structure as Principles I-IV: + +- Principle heading and description +- MUST rules +- SHOULD rules (if applicable) +- Rationale + +The section MUST cover the upstream constitution's actual Principle V content: + +- Supply chain integrity (dependencies MUST be verified by content hash) +- Input validation (all external inputs MUST be validated and sanitized) +- Least privilege (components MUST operate with minimum permissions) +- Dependency justification (external dependencies MUST be justified) +- The principle's relationship to the existing four principles + +The upstream constitution (`.specify/memory/constitution.md`) is the authoritative source for Principle V content. The spec's description above is indicative — if the upstream constitution defines Principle V differently, the upstream version takes precedence. + +The page frontmatter description MUST be updated to reference 5 principles instead of 4. The constitution version reference MUST be reconciled with the upstream version (website currently shows v1.1.0; verify upstream version and update accordingly). + +#### Scenario: User reads the constitution and finds all five principles + +- **GIVEN** a contributor is reviewing the Unbound Force constitution +- **WHEN** they read the constitution page +- **THEN** they find Principles I through V, with Principle V (Security by Default) following the same structure as the others + +#### Scenario: User understands Security by Default requirements + +- **GIVEN** a developer is integrating external dependencies into their project +- **WHEN** they read the Principle V section on the constitution page +- **THEN** they understand that dependencies must be hash-verified, inputs validated, permissions minimized, and dependencies justified + +## MODIFIED Requirements + +### Requirement: Branch Naming Convention Update + +All website content pages containing the old `NNN-` branch naming pattern MUST be updated to use `speckit/NNN-`. This includes at minimum: + +- `content/docs/getting-started/common-workflows.md` +- `content/docs/getting-started/developer.md` (line 130: "Speckit uses `NNN-` branches") + +Previously: Branch names follow the pattern `NNN-` (e.g., `013-binary-rename`). + +Updated: Branch names follow the pattern `speckit/NNN-` (e.g., `speckit/013-binary-rename`). + +All instances of the old pattern in each page MUST be updated. No new content is added — this is a corrective find-and-replace. Note: AGENTS.md also contains the old pattern but is out of scope for this change (AGENTS.md is a project governance file, not website content). + +#### Scenario: User reads about branch naming + +- **GIVEN** a contributor is learning about the Speckit workflow branch conventions +- **WHEN** they read the common workflows page or developer guide +- **THEN** all branch name examples use the `speckit/NNN-` prefix format + +### Requirement: Constitution Page Metadata Update + +The constitution page frontmatter `description` field MUST be updated from referencing "4 core principles" to "5 core principles" to reflect the addition of Principle V. + +Previously: `description: "The 4 core principles that govern all Unbound Force heroes..."` + +Updated: `description: "The 5 core principles that govern all Unbound Force heroes..."` + +#### Scenario: Search results show correct principle count + +- **GIVEN** a user searches for "Unbound Force constitution" +- **WHEN** the constitution page appears in results +- **THEN** the description mentions 5 core principles, not 4 + +## REMOVED Requirements + +None. diff --git a/openspec/changes/review-infra-docs/specs/convention-packs.md b/openspec/changes/review-infra-docs/specs/convention-packs.md new file mode 100644 index 0000000..0d25e5e --- /dev/null +++ b/openspec/changes/review-infra-docs/specs/convention-packs.md @@ -0,0 +1,46 @@ +## ADDED Requirements + +### Requirement: Convention Packs Reference Page + +A new reference page MUST be created at `content/docs/reference/convention-packs.md` that documents the convention pack system. The page MUST explain what convention packs are, how they are structured, how they are loaded, and what severity levels mean. + +The page MUST include: + +- Definition of convention packs as portable, severity-classified coding standards +- Explanation of the three severity levels (MUST, SHOULD, MAY) and their enforcement implications +- Description of how packs are loaded by heroes (directory convention: `.opencode/uf/packs/`) +- List of all available pack types (default, content, go, typescript, python, CI, severity) with brief descriptions, plus their `-custom` variants +- The CI convention pack (#206) documented as an example, including its scope (CI workflow authoring, action pinning, SHA verification) and rule count +- Cross-reference to the constitution governance hierarchy section + +The page MUST use standard Hugo frontmatter with `weight: 30` to appear after existing reference pages (cli.md uses weight 10). + +#### Scenario: User looks up convention pack severity levels + +- **GIVEN** a user encounters a "MUST" violation in a review finding +- **WHEN** the user navigates to the Convention Packs reference page +- **THEN** the page explains that MUST violations are mandatory rules that block merging, SHOULD violations are recommended practices, and MAY violations are optional suggestions + +#### Scenario: User discovers available convention packs + +- **GIVEN** a contributor wants to know what coding standards apply to their project +- **WHEN** the user reads the Convention Packs reference page +- **THEN** the page lists all available pack types with brief descriptions and explains how packs are loaded from `.opencode/uf/packs/` + +### Requirement: Developer Guide Convention Pack Cross-Reference + +The developer guide (`content/docs/getting-started/developer.md`) MUST be updated to cross-reference the new Convention Packs reference page. If a convention pack section already exists, it SHOULD be expanded with a link to the reference page. If no section exists, one MUST be added. + +#### Scenario: Developer guide links to convention pack reference + +- **GIVEN** a developer is reading the developer guide +- **WHEN** they reach the convention pack section +- **THEN** the section provides a brief overview and links to the full Convention Packs reference page for details + +## MODIFIED Requirements + +None. + +## REMOVED Requirements + +None. diff --git a/openspec/changes/review-infra-docs/specs/council-review-action.md b/openspec/changes/review-infra-docs/specs/council-review-action.md new file mode 100644 index 0000000..28341b8 --- /dev/null +++ b/openspec/changes/review-infra-docs/specs/council-review-action.md @@ -0,0 +1,61 @@ +## ADDED Requirements + +### Requirement: Council Review Action Reference Page + +A new reference page MUST be created at `content/docs/reference/council-review-action.md` that documents the council-review-action composite GitHub Action. The page MUST cover: + +- What the action does (AI-powered code review as a GitHub Action) +- The three-workflow chain architecture (trigger → review → comment) +- Persona discovery mechanism (how review personas are found and invoked) +- Configuration options (inputs, secrets, environment variables). The Configuration section MUST include a security note explaining that secrets should be scoped to the narrowest context needed (repository-level, not organization-level) and that workflow permissions should follow the principle of least privilege +- Integration with the review lifecycle (how it relates to `/review-council` and `/review-pr`) +- Cross-reference to the code review tutorial for workflow context + +The page MUST use standard Hugo frontmatter with `weight: 40` in the reference section. + +#### Scenario: User understands the three-workflow chain + +- **GIVEN** a repository maintainer wants to understand how the council-review-action works +- **WHEN** they read the Council Review Action reference page +- **THEN** the page explains the trigger workflow, review workflow, and comment workflow, including how they chain together + +#### Scenario: User finds configuration options + +- **GIVEN** a user is configuring the council-review-action for their repository +- **WHEN** they read the Configuration section of the reference page +- **THEN** they find all required and optional inputs, secrets, and environment variables with descriptions + +### Requirement: Council Review Action Tutorial + +A new tutorial page MUST be created at `content/docs/getting-started/council-review-action-tutorial.md` that provides a step-by-step adoption guide for adding the council-review-action to a downstream repository. + +The tutorial MUST include: + +- Prerequisites (GitHub repository, required permissions, secrets setup) +- Step-by-step instructions for adding the workflow files +- Example workflow YAML configuration using `${{ secrets.SECRET_NAME }}` syntax for all credential references (MUST NOT include placeholder strings resembling real tokens). A callout SHOULD warn users to never hardcode API keys or tokens in workflow files +- How to verify the action is working (creating a test PR) +- Troubleshooting common setup issues +- Link to the reference page for advanced configuration + +The tutorial MUST follow the pattern established by the existing code-review-tutorial.md. The tutorial MUST use Hugo frontmatter with `weight: 75` (after core workflow tutorials). The introduction paragraph SHOULD frame the action as assisting human reviewers, not replacing them. + +#### Scenario: User adds council-review-action to their repo + +- **GIVEN** a repository maintainer wants automated AI code review on pull requests +- **WHEN** they follow the council-review-action tutorial from start to finish +- **THEN** they have a working GitHub Action that runs AI code review on new PRs + +#### Scenario: User troubleshoots a failed setup + +- **GIVEN** a user followed the tutorial but the action is not running +- **WHEN** they read the troubleshooting section +- **THEN** they find guidance for common issues (missing secrets, incorrect permissions, workflow trigger configuration) + +## MODIFIED Requirements + +None. + +## REMOVED Requirements + +None. diff --git a/openspec/changes/review-infra-docs/tasks.md b/openspec/changes/review-infra-docs/tasks.md new file mode 100644 index 0000000..f69df49 --- /dev/null +++ b/openspec/changes/review-infra-docs/tasks.md @@ -0,0 +1,44 @@ + + +## 1. New Reference Pages + +- [x] 1.1 [P] Create convention packs reference page at `content/docs/reference/convention-packs.md` with `weight: 30`. Include: definition of convention packs, severity levels (MUST/SHOULD/MAY), loading mechanism (`.opencode/uf/packs/`), all available pack types (default, content, go, typescript, python, CI, severity) plus `-custom` variants, CI pack scope and rule count, cross-reference to constitution governance hierarchy. Source content from upstream `.opencode/uf/packs/` files and issue #206. +- [x] 1.2 [P] Create council-review-action reference page at `content/docs/reference/council-review-action.md` with `weight: 40`. Include: action purpose, three-workflow chain architecture (trigger → review → comment), persona discovery mechanism, configuration options (inputs, secrets, environment variables) with security note on least-privilege secret scoping, integration with review lifecycle. Source content from issue #190 and upstream action repository. + +## 2. New Tutorial Page + +- [x] 2.1 Create council-review-action tutorial at `content/docs/getting-started/council-review-action-tutorial.md` with `weight: 75`. Include: prerequisites, step-by-step workflow file setup, example YAML configuration using `${{ secrets.* }}` syntax (never placeholder tokens), verification steps (test PR), troubleshooting common issues, link to reference page. Frame the action as assisting human reviewers, not replacing them. Follow the pattern of existing code-review-tutorial.md. Source content from issue #192. + +## 3. CLI Reference Updates + +- [x] 3.1 Add an "OpenCode Slash Commands" top-level section to `content/docs/reference/cli.md` with an introductory paragraph explaining that slash commands are typed within an AI coding session (not a terminal). Then add `/agent-brief` as the first entry. Cover: command purpose (AGENTS.md lifecycle management), two modes (create/audit), usage syntax, example output. Source from issue #60. +- [x] 3.2 Add `/review-pr` section to `content/docs/reference/cli.md`. Cover: command purpose (post-PR GitHub review), CI causality analysis, difference from `/review-council`, usage syntax, cross-reference to code-review-tutorial.md. Source from issue #59. Note: runs after task 3.1 (same file). +- [x] 3.3 Add `/address-feedback` section to `content/docs/reference/cli.md`. Cover: command purpose (PR review feedback triage), four-phase workflow (collect, classify, plan, execute), usage syntax. Source from issue #138. Note: runs after task 3.2 (same file). + +## 4. Existing Page Updates + +- [x] 4.1 [P] Add Principle V (Security by Default) to `content/docs/getting-started/constitution.md`. Follow the structure of Principles I-IV: heading, description, MUST rules, SHOULD rules, rationale. Cover supply chain integrity (hash verification), input validation, least privilege, and dependency justification as defined in the upstream constitution. Do NOT include compound severity escalation (that belongs in the convention packs reference, not the constitution). Update frontmatter description from "4 core principles" to "5 core principles". Reconcile constitution version (website shows v1.1.0; verify upstream version). Also update the "Next Steps" section to link to the new convention packs reference page. Source from issue #142 and upstream `.specify/memory/constitution.md`. +- [x] 4.2 [P] Update branch naming in `content/docs/getting-started/common-workflows.md`. Replace all instances of `NNN-` branch pattern with `speckit/NNN-`. Update any example branch names (e.g., `013-binary-rename` → `speckit/013-binary-rename`). Source from issue #205. +- [x] 4.3 [P] Update developer guide at `content/docs/getting-started/developer.md`. (a) Add or expand convention pack section with cross-reference to the new convention packs reference page. Brief overview of how packs integrate with the review lifecycle. (b) Update branch naming from `NNN-` to `speckit/NNN-` (line 130 contains the old pattern). Note: task 4.2 handles common-workflows.md; this task handles developer.md. + +- [x] 4.4 [P] Update reference section index page at `content/docs/reference/_index.md`. Add entries for the new Convention Packs and Council Review Action reference pages, following the existing pattern of section heading + bullet with link and description. + +## 5. Verification + +- [x] 5.1 Run `npm run build` to verify all new and modified pages build without errors. +- [x] 5.2 Run `npm run dev` and visually verify: new pages render correctly, sidebar navigation includes new pages, cross-references link to correct targets (click each internal link in new/modified pages to verify no 404s), dark mode renders correctly, all new pages have complete Hugo frontmatter (title, description, lead, date, weight, toc, draft: false). Note: runs after task 5.1. +- [x] 5.3 Verify Principle V content accuracy: compare the Principle V section on the constitution page against the upstream `.specify/memory/constitution.md` to confirm all MUST rules, SHOULD rules, and rationale accurately reflect the upstream source. Verify that compound severity escalation is NOT present under Principle V (it belongs in the convention packs reference). Note: runs after task 5.2. +- [x] 5.4 Verify constitution alignment: Principle I (new docs describe artifact-based patterns), Principle II (convention pack docs cover independent loading), Principle III (severity levels and quality enforcement documented), Principle IV (N/A, documentation-only), Principle V (N/A, documentation-only). Note: runs after task 5.3. + + + From f4b08398b862610cb20d5b56bdfa404b541df4c0 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Tue, 25 Aug 2026 15:16:28 -0400 Subject: [PATCH 2/3] fix(docs): correct ci.md deployment claim and constitution version - convention-packs.md: ci.md and content.md are always-deployed packs, not conditionally deployed. Updated to match upstream scaffold.go:alwaysDeployedPacks. - constitution.md: version is 1.0.0, not 1.2.0. Aligned to the actual version in .specify/memory/constitution.md. Addresses PR #256 review feedback from @yvonnedevlinrh. Signed-off-by: Joshua Flowers Assisted-by: claude-opus-4-6 --- content/docs/getting-started/constitution.md | 2 +- content/docs/reference/convention-packs.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/content/docs/getting-started/constitution.md b/content/docs/getting-started/constitution.md index aa98f11..c4e6f7d 100644 --- a/content/docs/getting-started/constitution.md +++ b/content/docs/getting-started/constitution.md @@ -145,7 +145,7 @@ Violations are CRITICAL severity and non-negotiable -- they must be resolved bef The `/constitution-check` command automates this assessment. OpenSpec proposals also include a Constitution Alignment section where each principle is evaluated against the proposed change. -The constitution is versioned (currently v1.2.0) and the check validates against the version referenced in the project's `parent_constitution` field. See the [contributing guide](/docs/contributing/) for how this fits into the specification pipeline. +The constitution is versioned (currently v1.0.0) and the check validates against the version referenced in the project's `parent_constitution` field. See the [contributing guide](/docs/contributing/) for how this fits into the specification pipeline. ## Governance Hierarchy diff --git a/content/docs/reference/convention-packs.md b/content/docs/reference/convention-packs.md index 86094d7..a384c56 100644 --- a/content/docs/reference/convention-packs.md +++ b/content/docs/reference/convention-packs.md @@ -47,7 +47,7 @@ Convention packs cover both language-agnostic standards and language-specific ru | `ci.md` | CI/CD | CI workflow authoring rules: GitHub Actions pinning, SHA verification, workflow file organization, and secrets handling. | | `severity.md` | Cross-cutting | Shared severity definitions for all Divisor personas. Provides the calibration standard for CRITICAL, HIGH, MEDIUM, and LOW findings across every review. | -Not all packs are deployed to every project. `uf init` deploys `default.md`, `severity.md`, and the language-specific pack matching your project's detected language. Other packs (like `ci.md`, `python.md`, or `typescript.md`) are deployed when the corresponding language or context is detected, or can be added manually. +Not all packs are deployed to every project. `uf init` always deploys a core set of packs regardless of project language: `default.md`, `default-custom.md`, `severity.md`, `content.md`, `content-custom.md`, `ci.md`, and `ci-custom.md`. In addition, the language-specific pack matching your project's detected language (e.g., `go.md` and `go-custom.md`) is deployed automatically. Other language packs (like `python.md` or `typescript.md`) are deployed when their corresponding language is detected, or can be added manually. Each pack (except `severity.md`) has a corresponding `-custom.md` variant — for example, `default-custom.md`, `go-custom.md`, `content-custom.md`. Custom variants are user-owned files where you add project-specific rules that extend the base pack. They are never overwritten by `uf init` updates, so your customizations persist across toolchain upgrades. From 63490807267cf8982d6058f48ecda2ce3bcd4255 Mon Sep 17 00:00:00 2001 From: Jay Flowers Date: Tue, 25 Aug 2026 15:16:36 -0400 Subject: [PATCH 3/3] fix(docs): clarify persona count and add WIF auth guidance - council-review-action-tutorial.md: add note that 9 is the default uf init --divisor count; action discovers all divisor-*.md files dynamically, so repos with custom personas run all of them. - council-review-action.md: same clarifying note in persona discovery section. - council-review-action-tutorial.md: add Workload Identity Federation (WIF) subsection in Step 5 as recommended auth pattern for org members using Vertex AI. Keeps static secrets as BYOK fallback. Addresses PR #256 review feedback from @yvonnedevlinrh. Signed-off-by: Joshua Flowers Assisted-by: claude-opus-4-6 --- .../council-review-action-tutorial.md | 35 +++++++++++++++++++ .../docs/reference/council-review-action.md | 2 +- 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/content/docs/getting-started/council-review-action-tutorial.md b/content/docs/getting-started/council-review-action-tutorial.md index 025ce3b..40d866d 100644 --- a/content/docs/getting-started/council-review-action-tutorial.md +++ b/content/docs/getting-started/council-review-action-tutorial.md @@ -62,6 +62,8 @@ The `uf init --divisor` command creates the `.opencode/agents/` directory (if it You can customize the review scope by adding, removing, or editing persona files. The action picks up changes on the next PR. +> **Note**: The nine personas listed above are the default set shipped by `uf init --divisor`. However, the action discovers personas dynamically by scanning for `divisor-*.md` files at runtime. If your repository adds custom personas beyond the default nine, the action runs all of them automatically -- no configuration change is needed. + ## Step 2: Add the Trigger Workflow Create `.github/workflows/council-review-trigger.yml` in your repository. This workflow fires on pull request events and dispatches the review workflow: @@ -277,6 +279,39 @@ env: CLOUD_ML_REGION: ${{ secrets.VERTEX_REGION }} ``` +### Google Cloud Vertex AI with Workload Identity Federation (Recommended) + +For organization members and production deployments, [Workload Identity Federation (WIF)](https://cloud.google.com/iam/docs/workload-identity-federation) is the recommended authentication method. WIF eliminates static credentials entirely -- GitHub Actions authenticates directly with Google Cloud using OIDC tokens. + +Set up WIF authentication by adding the `google-github-actions/auth` step before the review step: + +```yaml + - name: Authenticate to Google Cloud + uses: google-github-actions/auth@ba79af03959ebeac9769e648f473a284504d9193 # v2.1.10 + with: + workload_identity_provider: ${{ secrets.WIF_PROVIDER }} + service_account: ${{ secrets.WIF_SERVICE_ACCOUNT }} + + - name: Run review council + env: + CLAUDE_CODE_USE_VERTEX: "1" + ANTHROPIC_VERTEX_PROJECT_ID: ${{ secrets.VERTEX_PROJECT_ID }} + CLOUD_ML_REGION: ${{ secrets.VERTEX_REGION }} + run: | + opencode run --agent divisor \ + --input "Review PR #${{ inputs.pr_number }}" \ + --headless +``` + +| Secret | Value | +|--------|-------| +| `WIF_PROVIDER` | Your Workload Identity Provider resource name | +| `WIF_SERVICE_ACCOUNT` | The service account email to impersonate | +| `VERTEX_PROJECT_ID` | Your Google Cloud project ID | +| `VERTEX_REGION` | The Cloud region (e.g., `us-central1`) | + +WIF requires a one-time setup in Google Cloud (creating a Workload Identity Pool and Provider), but once configured, no static keys need to be stored as GitHub secrets. The static secrets approach shown in the Vertex AI section above remains available as a fallback for external contributors or BYOK (bring your own key) setups. + ### AWS Bedrock Set three secrets: diff --git a/content/docs/reference/council-review-action.md b/content/docs/reference/council-review-action.md index 05c5146..05ccf6c 100644 --- a/content/docs/reference/council-review-action.md +++ b/content/docs/reference/council-review-action.md @@ -89,7 +89,7 @@ Discovery works as follows: 3. Each matching file is treated as a review persona 4. The persona's frontmatter defines its review focus area, ownership boundaries, and out-of-scope topics -The default personas ship with `uf init --divisor`: nine agents total (Guard, Architect, Adversary, SRE, Testing, Curator, Scribe, Herald, and Envoy). Repositories can customize the review scope: +The default personas ship with `uf init --divisor`: nine agents total (Guard, Architect, Adversary, SRE, Testing, Curator, Scribe, Herald, and Envoy). Because discovery is file-based, repositories with custom personas beyond the default nine will have all of them invoked automatically -- no configuration change is needed. Repositories can customize the review scope: - **Add a persona**: Create a new `divisor-.md` file in `.opencode/agents/` with the appropriate frontmatter. The action picks it up on the next PR. - **Remove a persona**: Delete the corresponding `divisor-.md` file. The action stops running that persona.