diff --git a/.github/settings.yml b/.github/settings.yml new file mode 100644 index 0000000..ba9432a --- /dev/null +++ b/.github/settings.yml @@ -0,0 +1,34 @@ +_extends: .github + +repository: + has_wiki: true + +# Website-specific labels for content pipeline +labels: + - name: blog + color: e4e669 + description: Blog post opportunity + + - name: docs + color: 0075ca + description: Documentation updates needed + + - name: tutorial + color: '7057ff' + description: Tutorial opportunity + +# No PR-triggered CI — branch protection without status checks +branches: + - name: main + protection: + required_pull_request_reviews: + required_approving_review_count: 1 + dismiss_stale_reviews: true + require_code_owner_reviews: true + dismissal_restrictions: + users: [] + teams: [] + required_status_checks: null + enforce_admins: false + required_linear_history: false + restrictions: null diff --git a/.uf/dewey/learnings/documentation-patterns-20260821T212320-jay-flowers.md b/.uf/dewey/learnings/documentation-patterns-20260821T212320-jay-flowers.md deleted file mode 100644 index dd8dbf3..0000000 --- a/.uf/dewey/learnings/documentation-patterns-20260821T212320-jay-flowers.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -tag: documentation-patterns -author: jay-flowers -category: pattern -created_at: 2026-08-21T21:23:20Z -identity: documentation-patterns-20260821T212320-jay-flowers -tier: draft ---- - -When updating command references that describe CI behavior (like "CI hard gate"), the change must propagate to ALL pages that mention that behavior, not just the primary documentation page. In the slash command docs update (August 2026), the common-workflows.md page was correctly updated from "hard gate" to "soft gate with causality analysis" per issue #221, but the quality-gates.md page and unleash-in-practice.md blog post still described a "hard gate." The code review caught this inconsistency. The pattern: when a behavioral change affects terminology used across multiple pages, grep for the old terminology across the entire content directory, not just the files listed in the task. A verification sweep for old terminology should be standard practice after any behavioral documentation update. diff --git a/.uf/dewey/learnings/documentation-patterns-20260821T212332-jay-flowers.md b/.uf/dewey/learnings/documentation-patterns-20260821T212332-jay-flowers.md deleted file mode 100644 index 4264bfa..0000000 --- a/.uf/dewey/learnings/documentation-patterns-20260821T212332-jay-flowers.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -tag: documentation-patterns -author: jay-flowers -category: pattern -created_at: 2026-08-21T21:23:32Z -identity: documentation-patterns-20260821T212332-jay-flowers -tier: draft ---- - -When adding new command documentation sections to a reference page like common-workflows.md, always include at minimum a code example showing basic invocation syntax. During the slash command docs update (August 2026), new sections for /forge, /forge:status, /org, /inbox, and /handoff were initially added as single descriptive paragraphs without any example invocations. The code review flagged this as a task-orientation gap — a reader encountering these commands for the first time needs to see how to invoke them. Additionally, new command sections need cross-references from at least one other page (like the developer guide's session lifecycle table) to be discoverable. Isolated documentation that only exists on one page may never be found by readers navigating through other entry points. diff --git a/.uf/dewey/learnings/namespace-migration-20260821T212310-jay-flowers.md b/.uf/dewey/learnings/namespace-migration-20260821T212310-jay-flowers.md deleted file mode 100644 index da1d983..0000000 --- a/.uf/dewey/learnings/namespace-migration-20260821T212310-jay-flowers.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -tag: namespace-migration -author: jay-flowers -category: gotcha -created_at: 2026-08-21T21:23:10Z -identity: namespace-migration-20260821T212310-jay-flowers -tier: draft ---- - -During the slash command namespace migration (opsx/slash-command-docs-update, August 2026), the code review council caught a critical gap: frontmatter fields (title, description, lead) in documentation pages were not being updated alongside body content. The initial implementation preserved blog post frontmatter as an explicit design decision (D6), but this exemption was incorrectly extended to docs pages like code-review-tutorial.md. Frontmatter fields in docs pages are user-facing — they appear in SEO metadata, social media previews, and page headers — and must be updated when command names change. Blog post frontmatter is a more nuanced case: the slug field controls the URL, so titles can be updated safely if the slug is explicitly set. The lesson is that "preserve frontmatter" should be scoped precisely (blog titles that generate URLs vs. docs page metadata that is purely descriptive) rather than applied as a blanket rule. diff --git a/.uf/dewey/learnings/vision-roadmap-pages-20260831T142223-jay-flowers.md b/.uf/dewey/learnings/vision-roadmap-pages-20260831T142223-jay-flowers.md deleted file mode 100644 index d0ffdeb..0000000 --- a/.uf/dewey/learnings/vision-roadmap-pages-20260831T142223-jay-flowers.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -tag: vision-roadmap-pages -author: jay-flowers -category: pattern -created_at: 2026-08-31T14:22:23Z -identity: vision-roadmap-pages-20260831T142223-jay-flowers -tier: draft ---- - -When adapting source Markdown documents (like VISION.md or ROADMAP.md) from an upstream repository for publication as Hugo/Doks website pages, the heading-level adaptation strategy matters. For this website's Doks theme, the frontmatter `title` field generates the H1, so body content must start at H2. When the source document uses H1 as its title and H2 for sections, the body sections can be preserved at H2 — no shift needed for the section headings. Only the H1 title line is removed (replaced by frontmatter). Hugo's `_index.md` convention should be used for section landing pages (content/docs/section/_index.md). Cross-references between source documents (e.g., `[VISION.md](VISION.md)`) must be rewritten to Hugo routes (e.g., `[Vision](/docs/vision/)`), while external links (GitHub issues, discussions) that already use full URLs can be preserved as-is. Menu entries in menus.en.toml require both `[[docs]]` entries (for sidebar navigation with identifiers) and `[[main]]` entries (for top navbar), with weight values controlling ordering in each independently. diff --git a/.uf/dewey/learnings/vision-roadmap-pages-20260831T142229-jay-flowers.md b/.uf/dewey/learnings/vision-roadmap-pages-20260831T142229-jay-flowers.md deleted file mode 100644 index 1930e73..0000000 --- a/.uf/dewey/learnings/vision-roadmap-pages-20260831T142229-jay-flowers.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -tag: vision-roadmap-pages -author: jay-flowers -category: pattern -created_at: 2026-08-31T14:22:29Z -identity: vision-roadmap-pages-20260831T142229-jay-flowers -tier: draft ---- - -For documentation-only changes on the Unbound Force website (Hugo/Doks), the code review phase is straightforward because the only CI gate is `hugo --minify --gc` (the build command). There are no test suites, linters, or other local tools to run. The review focuses on: (1) content fidelity — verifying the website adaptation matches the source document verbatim where substance is concerned, (2) Hugo conventions — correct frontmatter fields, heading levels starting at H2, _index.md for sections, (3) navigation configuration — proper weight ordering and identifier fields in menus.en.toml, and (4) build success — npm run build exits 0 with no new warnings. Pre-existing warnings about description lengths on tag/category pages are harmless and unrelated to content changes. diff --git a/AGENTS.md b/AGENTS.md index 88be0b7..45288f0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -187,13 +187,13 @@ Before marking any implementation task complete or declaring a PR ready, agents ### Review Council as PR Prerequisite -Before submitting a pull request, agents **must** run `/uf.review-council` and resolve all REQUEST CHANGES findings until all reviewers return APPROVE. There must be **minimal to no code changes** between the council's APPROVE verdict and the PR submission — the council reviews the final code, not a draft that changes afterward. +Before submitting a pull request, agents **must** run `/review-council` and resolve all REQUEST CHANGES findings until all reviewers return APPROVE. There must be **minimal to no code changes** between the council's APPROVE verdict and the PR submission — the council reviews the final code, not a draft that changes afterward. Workflow: 1. Complete all implementation tasks 2. Run CI checks locally (build, test, vet) -3. Run `/uf.review-council` — fix any findings, re-run until APPROVE +3. Run `/review-council` — fix any findings, re-run until APPROVE 4. Commit, push, and submit PR immediately after council APPROVE 5. Do NOT make further code changes between APPROVE and PR submission diff --git a/assets/scss/common/_custom.scss b/assets/scss/common/_custom.scss index 5da1c4c..0973bd3 100644 --- a/assets/scss/common/_custom.scss +++ b/assets/scss/common/_custom.scss @@ -94,7 +94,7 @@ } } -// Featured card — visually prominent /uf.unleash card +// Featured card — visually prominent /unleash card .feature-card-featured { border-left: 4px solid var(--bs-primary); text-align: left; diff --git a/config/_default/menus/menus.en.toml b/config/_default/menus/menus.en.toml index ead124c..7a5cfb7 100644 --- a/config/_default/menus/menus.en.toml +++ b/config/_default/menus/menus.en.toml @@ -1,15 +1,3 @@ -[[docs]] - name = "Vision" - weight = 5 - identifier = "vision" - url = "/docs/vision/" - -[[docs]] - name = "Roadmap" - weight = 6 - identifier = "roadmap" - url = "/docs/roadmap/" - [[docs]] name = "Getting Started" weight = 10 @@ -46,16 +34,6 @@ identifier = "contributing" url = "/docs/contributing/" -[[main]] - name = "Vision" - url = "/docs/vision/" - weight = 2 - -[[main]] - name = "Roadmap" - url = "/docs/roadmap/" - weight = 3 - [[main]] name = "Blog" url = "/blog/" diff --git a/content/blog/dewey-curator-blog.md b/content/blog/dewey-curator-blog.md index 4d7d19d..348247d 100644 --- a/content/blog/dewey-curator-blog.md +++ b/content/blog/dewey-curator-blog.md @@ -90,4 +90,4 @@ Dewey v3.0.0's knowledge compilation was the largest single feature in the proje We are not overclaiming the maturity of these features. Knowledge compilation is new. The resolution strategies are the first iteration. Trust tiers work, but the workflow of reviewing and promoting content is still being refined through real usage across the Unbound Force swarm. What shipped is a foundation — a sound architecture that can evolve, not a finished product. -If you want to try these features, the [knowledge getting-started guide](/docs/getting-started/knowledge/) covers the CLI commands and configuration for compilation, linting, and trust tiers. The [Dewey project page](/docs/projects/dewey/) has the full feature overview, including the 50 MCP tools available across 12 categories. +If you want to try these features, the [knowledge getting-started guide](/docs/getting-started/knowledge/) covers the CLI commands and configuration for compilation, linting, and trust tiers. The [Dewey project page](/docs/projects/dewey/) has the full feature overview, including the 48 MCP tools available across 12 categories. diff --git a/content/blog/dewey-vs-karpathy.md b/content/blog/dewey-vs-karpathy.md index e03bf96..0dc6321 100644 --- a/content/blog/dewey-vs-karpathy.md +++ b/content/blog/dewey-vs-karpathy.md @@ -76,7 +76,7 @@ These approaches are not competing — they solve different parts of the same pr **The compiled wiki becomes a Dewey source.** If you use Karpathy's approach to maintain a curated research wiki, that wiki is a folder of markdown files. Dewey indexes markdown files. Point a Dewey disk source at your compiled wiki and every agent in your swarm can search it. -**Dewey's `store_learning` is a primitive compilation step.** When the [/uf.unleash](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash) pipeline completes a task, its retrospective step stores a narrative learning in Dewey via `store_learning`. These learnings accumulate over sessions and surface via semantic search in future sessions. This is not full LLM-driven compilation — it is a single learning per session, not a synthesized wiki — but it serves the same purpose: the system remembers what it learned. +**Dewey's `store_learning` is a primitive compilation step.** When the [/unleash](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash) pipeline completes a task, its retrospective step stores a narrative learning in Dewey via `store_learning`. These learnings accumulate over sessions and surface via semantic search in future sessions. This is not full LLM-driven compilation — it is a single learning per session, not a synthesized wiki — but it serves the same purpose: the system remembers what it learned. **The ideal system could use both.** Karpathy's LLM-as-librarian for active knowledge synthesis on curated research. Dewey for cross-repo semantic search on the full organizational knowledge base. The compiled wiki feeds into the searchable index. diff --git a/content/blog/five-principles-every-ai-agent-harness-discovers.md b/content/blog/five-principles-every-ai-agent-harness-discovers.md index db3f5d1..9bd19ed 100644 --- a/content/blog/five-principles-every-ai-agent-harness-discovers.md +++ b/content/blog/five-principles-every-ai-agent-harness-discovers.md @@ -49,7 +49,7 @@ This is not a suggestion — it is enforced. If an agent attempts to write code The enforcement mechanisms are concrete: - Branch naming conventions gate pipeline entry - All spec artifacts must be committed before implementation begins (the Spec Commit Gate) -- The [/uf.unleash](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash) command has six defined exit points where human judgment is required +- The [/unleash](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash) command has six defined exit points where human judgment is required Liu's article describes plan/execute separation as a two-phase concern. Unbound Force has eight phases with hard gates between them — significantly more granular than anything described in the three teams. diff --git a/content/blog/sandbox-isolation.md b/content/blog/sandbox-isolation.md index b302084..29c07c2 100644 --- a/content/blog/sandbox-isolation.md +++ b/content/blog/sandbox-isolation.md @@ -61,12 +61,12 @@ You are now inside the sandbox. The TUI looks identical to a normal OpenCode ses Run any workflow command as usual: ```text -/uf.unleash +/unleash ``` The agent reads your spec, plans the implementation, writes code, runs tests, and reviews its own work — all inside the container. Every file modification, every `git commit`, every test run happens in the container's overlay filesystem. Your host repo is untouched. -When `/uf.unleash` finishes, detach from the sandbox with `Ctrl+C` or let it complete naturally. +When `/unleash` finishes, detach from the sandbox with `Ctrl+C` or let it complete naturally. ### 3. Extract Changes diff --git a/content/blog/the-8-phase-pipeline.md b/content/blog/the-8-phase-pipeline.md index 05bbdd9..f6dc18c 100644 --- a/content/blog/the-8-phase-pipeline.md +++ b/content/blog/the-8-phase-pipeline.md @@ -102,4 +102,4 @@ This granularity is expensive. Eight phases mean more artifacts, more reviews, m But for complex features — the kind that involve multiple files, architectural decisions, and coordination across components — the eight-phase pipeline prevents a specific class of failures: cascading errors from uncheckpointed decisions. Every decision point becomes a review point. Every review point becomes an opportunity to catch mistakes before they compound. -The [/uf.unleash](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash) command orchestrates all eight phases with six defined exit points where human judgment is required. See the [operational walkthrough](/blog/unleash-in-practice/) for how the pipeline works in practice. +The [/unleash](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash) command orchestrates all eight phases with six defined exit points where human judgment is required. See the [operational walkthrough](/blog/unleash-in-practice/) for how the pipeline works in practice. diff --git a/content/blog/unleash-in-practice.md b/content/blog/unleash-in-practice.md index e9f074a..888d80c 100644 --- a/content/blog/unleash-in-practice.md +++ b/content/blog/unleash-in-practice.md @@ -1,6 +1,6 @@ --- -title: "From Spec to Demo in One Command: How /uf.unleash Works" -description: "Most AI coding workflows need a human pressing 'next' at every step. /uf.unleash runs the entire pipeline — from spec to demo-ready code — autonomously." +title: "From Spec to Demo in One Command: How /unleash Works" +description: "Most AI coding workflows need a human pressing 'next' at every step. /unleash runs the entire pipeline — from spec to demo-ready code — autonomously." lead: "One command. Eight stages. The swarm handles clarification, planning, implementation, testing, and review autonomously." slug: "unleash-in-practice" date: 2026-03-31T00:00:00+00:00 @@ -31,25 +31,25 @@ Each step requires a human to invoke the next command, evaluate the output, and The question is not whether each step is valuable — it is. The question is whether a human needs to be the one pressing "next" at every transition. -## What /uf.unleash Does +## What /unleash Does -`/uf.unleash` is a single command that takes a Speckit specification and runs the entire pipeline autonomously — from clarification through implementation, testing, review, and demo. It handles the transitions, evaluates the outputs, and makes the proceed/stop decisions at each stage. +`/unleash` is a single command that takes a Speckit specification and runs the entire pipeline autonomously — from clarification through implementation, testing, review, and demo. It handles the transitions, evaluates the outputs, and makes the proceed/stop decisions at each stage. -When it encounters something that genuinely requires human judgment — an unanswerable question, a critical spec finding, a persistent code review issue — it exits cleanly with context about what happened and what to do next. When you re-run `/uf.unleash`, it detects which stages are complete and resumes from where it left off. +When it encounters something that genuinely requires human judgment — an unanswerable question, a critical spec finding, a persistent code review issue — it exits cleanly with context about what happened and what to do next. When you re-run `/unleash`, it detects which stages are complete and resumes from where it left off. -The result: you write a spec, run `/uf.unleash`, and come back to demo-ready code with a summary of what was built and how to verify it. +The result: you write a spec, run `/unleash`, and come back to demo-ready code with a summary of what was built and how to verify it. ## The Pipeline -`/uf.unleash` orchestrates these stages in sequence: +`/unleash` orchestrates these stages in sequence: ### 1. Clarify The pipeline scans your spec for `[NEEDS CLARIFICATION]` markers — questions that were flagged during specification but not answered. -If [Dewey](/docs/getting-started/knowledge/) (the swarm's knowledge retrieval system) is available, `/uf.unleash` attempts to resolve each question automatically by searching across your organization's documentation, GitHub issues, and related specs. Questions that Dewey can answer are resolved silently and recorded in the spec. +If [Dewey](/docs/getting-started/knowledge/) (the swarm's knowledge retrieval system) is available, `/unleash` attempts to resolve each question automatically by searching across your organization's documentation, GitHub issues, and related specs. Questions that Dewey can answer are resolved silently and recorded in the spec. -Questions that Dewey cannot answer are collected and presented to you as an exit point. You answer them in the spec and re-run `/uf.unleash`. +Questions that Dewey cannot answer are collected and presented to you as an exit point. You answer them in the spec and re-run `/unleash`. If Dewey is not configured, all clarification questions exit for human input. The pipeline is the same — you answer more questions yourself. @@ -92,7 +92,7 @@ If Replicator worktrees are not available, parallel tasks fall back to sequentia Runs the Divisor review council in code review mode. This includes: -- CI soft gate with causality analysis (lint, vulnerability checks — pre-existing failures are informational) +- CI hard gate (lint, vulnerability checks) - Gaze quality analysis (if installed) — contract coverage, CRAP scores - The Divisor review council evaluating the implementation @@ -112,36 +112,36 @@ Presents structured output: - **How to verify** — steps from the quickstart or acceptance scenarios - **Key files changed** — grouped by directory - **Test results** — pass/fail summary -- **Next steps** — run `/uf.finale` to ship, or `/speckit.clarify` to iterate +- **Next steps** — run `/finale` to ship, or `/speckit.clarify` to iterate ## Where It Pauses -`/uf.unleash` is autonomous, not unattended. It exits cleanly at five specific points where human judgment is needed: +`/unleash` is autonomous, not unattended. It exits cleanly at five specific points where human judgment is needed: | Exit Point | Why It Pauses | What You Do | | --------------------------- | --------------------------------------------- | ------------------------------------------------- | -| Unanswerable clarification | Dewey could not resolve a spec question | Answer the question in spec.md, re-run `/uf.unleash` | -| HIGH/CRITICAL spec findings | Review council found serious spec issues | Run `/speckit.clarify`, re-run `/uf.unleash` | -| Build/test failure | CI commands failed after a phase | Fix the failure, re-run `/uf.unleash` | -| Merge conflict | Parallel workers produced conflicting changes | Resolve conflicts, re-run `/uf.unleash` | -| Exhausted code review | 3 review iterations without full approval | Fix remaining findings, re-run `/uf.unleash` | +| Unanswerable clarification | Dewey could not resolve a spec question | Answer the question in spec.md, re-run `/unleash` | +| HIGH/CRITICAL spec findings | Review council found serious spec issues | Run `/speckit.clarify`, re-run `/unleash` | +| Build/test failure | CI commands failed after a phase | Fix the failure, re-run `/unleash` | +| Merge conflict | Parallel workers produced conflicting changes | Resolve conflicts, re-run `/unleash` | +| Exhausted code review | 3 review iterations without full approval | Fix remaining findings, re-run `/unleash` | -Every exit message tells you what happened, what to do next, and how to resume. Re-running `/uf.unleash` after fixing the issue skips all completed stages and picks up exactly where it left off. +Every exit message tells you what happened, what to do next, and how to resume. Re-running `/unleash` after fixing the issue skips all completed stages and picks up exactly where it left off. ## The Complete Loop -`/uf.unleash` builds. [`/uf.finale`](/docs/getting-started/common-workflows/#end-of-branch-workflow-finale) ships. +`/unleash` builds. [`/finale`](/docs/getting-started/common-workflows/#end-of-branch-workflow-finale) ships. -After `/uf.unleash` presents demo instructions, run `/uf.finale` to automate the end-of-branch workflow: stage all changes, generate a conventional commit message, push, create a PR, watch CI checks, and return to `main`. The PR stays open for human review. The full developer loop is two commands: +After `/unleash` presents demo instructions, run `/finale` to automate the end-of-branch workflow: stage all changes, generate a conventional commit message, push, create a PR, watch CI checks, and return to `main`. The PR stays open for human review. The full developer loop is two commands: ```text -/uf.unleash # spec → demo-ready code -/uf.finale # commit → push → PR → main +/unleash # spec → demo-ready code +/finale # commit → push → PR → main ``` ## Every Tool Is Optional -`/uf.unleash` is designed for graceful degradation. Every external tool it uses has a fallback: +`/unleash` is designed for graceful degradation. Every external tool it uses has a fallback: | Tool | If Available | If Not Available | | ---------- | ------------------------------------- | ------------------------------ | @@ -154,7 +154,7 @@ The pipeline works with all four tools, with none of them, or with any combinati ## Where It Works Best -`/uf.unleash` works best for well-scoped features with clear specifications — the kind of work where a senior developer could describe the approach in a few sentences. Complex cross-cutting refactors, ambiguous requirements, and large-scale architectural changes still benefit from the step-by-step [Speckit commands](/docs/getting-started/developer/#working-with-speckit) where you control each transition. The exit-and-resume design means you can start with `/uf.unleash` and drop to manual control if the pipeline pauses at a point where you want finer-grained direction. +`/unleash` works best for well-scoped features with clear specifications — the kind of work where a senior developer could describe the approach in a few sentences. Complex cross-cutting refactors, ambiguous requirements, and large-scale architectural changes still benefit from the step-by-step [Speckit commands](/docs/getting-started/developer/#working-with-speckit) where you control each transition. The exit-and-resume design means you can start with `/unleash` and drop to manual control if the pipeline pauses at a point where you want finer-grained direction. ## Getting Started @@ -174,7 +174,7 @@ Create a feature specification: Describe what you want to build. Then unleash the swarm: ```text -/uf.unleash +/unleash ``` See the [Quick Start guide](/docs/getting-started/quick-start/) for detailed installation and setup instructions, or read the [Common Workflows](/docs/getting-started/common-workflows/) reference for the full pipeline documentation. diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md index cef3c1b..2fd29c6 100644 --- a/content/docs/getting-started/_index.md +++ b/content/docs/getting-started/_index.md @@ -47,7 +47,7 @@ Ready to dive in? Start with the [Quick Start](/docs/getting-started/quick-start - **[Tester](/docs/getting-started/tester/)** -- Gaze quality analysis, CRAP scores, coverage ratchets, CI integration - **[Product Owner](/docs/getting-started/product-owner/)** -- Muti-Mind backlog management, priority scoring, acceptance decisions - **[Product Manager](/docs/getting-started/product-manager/)** -- Mx F metrics, dashboards, coaching, retrospectives -- **[Common Workflows](/docs/getting-started/common-workflows/)** -- The `/uf.unleash` autonomous pipeline, `/uf.finale` shipping workflow, manual feature flows, bug fixes, and code reviews +- **[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 diff --git a/content/docs/getting-started/architecture.md b/content/docs/getting-started/architecture.md index 7d32e4e..1e6e66c 100644 --- a/content/docs/getting-started/architecture.md +++ b/content/docs/getting-started/architecture.md @@ -40,7 +40,7 @@ Unbound Force layers governance at five levels, from most authoritative to most 3. **Agent personas** — Individual agent configurations that define each hero's role, capabilities, tool access, and behavioral constraints. Personas are bound by convention packs and the constitution but specialize them for a specific function (development, testing, review, documentation). -4. **Commands** — Slash commands (`/uf.unleash`, `/uf.review-council`, `/speckit.implement`) that orchestrate multi-step workflows. Commands define the sequence of operations, exit points, and handoff protocols. They operate within the constraints set by personas, packs, and the constitution. +4. **Commands** — Slash commands (`/unleash`, `/review-council`, `/speckit.implement`) that orchestrate multi-step workflows. Commands define the sequence of operations, exit points, and handoff protocols. They operate within the constraints set by personas, packs, and the constitution. 5. **CI pipelines** — Automated checks (linters, test suites, vulnerability scanners) that enforce computational constraints. CI is the final enforcement layer — if code passes all higher layers but fails CI, it does not ship. @@ -91,7 +91,7 @@ The phases enforce a strict progression: - You cannot implement before spec review passes - All spec artifacts must be committed before implementation begins (Spec Commit Gate) -Phase boundaries are enforced rules, not suggestions. If an agent attempts to make code changes during the planning phase, it triggers a process violation and must stop. The [common workflows page](/docs/getting-started/common-workflows/) describes the full pipeline in detail, including the `/uf.unleash` command that orchestrates all eight phases with six defined exit points where human judgment is required. +Phase boundaries are enforced rules, not suggestions. If an agent attempts to make code changes during the planning phase, it triggers a process violation and must stop. The [common workflows page](/docs/getting-started/common-workflows/) describes the full pipeline in detail, including the `/unleash` command that orchestrates all eight phases with six defined exit points where human judgment is required. This separation applies at two levels: the Speckit pipeline separates planning from execution at the feature level, and [OpenSpec](/docs/getting-started/common-workflows/#bug-fix-tactical) provides a lighter workflow for tactical changes that still separates proposal from implementation. diff --git a/content/docs/getting-started/code-review-tutorial.md b/content/docs/getting-started/code-review-tutorial.md index 927e880..a9be681 100644 --- a/content/docs/getting-started/code-review-tutorial.md +++ b/content/docs/getting-started/code-review-tutorial.md @@ -1,7 +1,7 @@ --- title: "Code Review Tutorial" -description: "Step-by-step walkthrough of the complete code review lifecycle — /uf.review-council before pushing, /uf.review-pr after creating a PR." -lead: "Two commands, one review lifecycle. Use /uf.review-council to validate locally before pushing, then /uf.review-pr to review the PR with CI results." +description: "Step-by-step walkthrough of the complete code review lifecycle — /review-council before pushing, /review-pr after creating a PR." +lead: "Two commands, one review lifecycle. Use /review-council to validate locally before pushing, then /review-pr to review the PR with CI results." date: 2026-05-03T00:00:00+00:00 draft: false weight: 72 @@ -13,7 +13,7 @@ toc: true Before starting this tutorial, ensure: 1. **`uf init` completed** — your project has Divisor review agents deployed (`.opencode/agents/divisor-*.md`) -2. **`gh` CLI installed and authenticated** — `/uf.review-pr` uses `gh` to fetch PR metadata and CI results +2. **`gh` CLI installed and authenticated** — `/review-pr` uses `gh` to fetch PR metadata and CI results ```bash which gh && gh auth status @@ -21,14 +21,14 @@ which gh && gh auth status If `gh` is not installed, get it from [cli.github.com](https://cli.github.com/). If not authenticated, run `gh auth login`. -## Step 1: Pre-PR Review with `/uf.review-council` {#step-1-pre-pr-review-with-review-council} +## Step 1: Pre-PR Review with `/review-council` -Before you push your changes and create a PR, run `/uf.review-council` to catch issues locally: +Before you push your changes and create a PR, run `/review-council` to catch issues locally: ```text -/uf.review-council -/uf.review-council [N] # optionally specify a PR number -/uf.review-council code [N] # explicitly select code review mode +/review-council +/review-council [N] # optionally specify a PR number +/review-council code [N] # explicitly select code review mode ``` When a PR number is provided, the council posts its consolidated findings as a GitHub PR review after completing the local review. Without a PR number, the review runs locally only. @@ -37,7 +37,7 @@ When a PR number is provided, the council posts its consolidated findings as a G The review council runs in two phases: -**Phase 1: CI Soft Gate** — runs your project's build, test, and lint commands (derived from `.github/workflows/`). When a check fails, the council determines whether the failure is *new* (introduced by your branch) or *pre-existing* (already broken on `main`). New failures block the review — no point reviewing code that introduces regressions. Pre-existing failures are reported as informational findings but do not block. The council checks the `main` baseline via the GitHub CI API first, falling back to a temporary git worktree if API data is unavailable. +**Phase 1: CI Gate** — runs your project's build, test, and lint commands (derived from `.github/workflows/`). If the build fails, the review stops immediately. This is a hard gate — no point reviewing code that does not compile. **Phase 2: Divisor Review** — launches 5+ review personas in parallel, each with a different focus: @@ -73,7 +73,7 @@ If any persona returns **REQUEST CHANGES**, the council verdict is REQUEST CHANG ### Optional: Post to GitHub -When a PR exists for your branch, `/uf.review-council` can post its consolidated findings as a GitHub PR review. The council detects an open PR automatically via `gh pr view`, or you can specify a PR number explicitly with `/uf.review-council N`. +When a PR exists for your branch, `/review-council` can post its consolidated findings as a GitHub PR review. The council detects an open PR automatically via `gh pr view`, or you can specify a PR number explicitly with `/review-council N`. **How it works**: After all personas complete their local review, the council aggregates their findings into a single GitHub review with per-persona sections. The council verdict maps to a GitHub review event: @@ -91,14 +91,14 @@ When a PR exists for your branch, `/uf.review-council` can post its consolidated Before posting, the council asks for **human confirmation**. No review is posted without your explicit approval. -**Graceful degradation**: If `gh` is not installed, not authenticated, or no PR exists for the current branch, `/uf.review-council` runs the full local review without errors. GitHub posting is strictly optional — the local review workflow is unchanged. +**Graceful degradation**: If `gh` is not installed, not authenticated, or no PR exists for the current branch, `/review-council` runs the full local review without errors. GitHub posting is strictly optional — the local review workflow is unchanged. ## Step 2: Push and Create a PR Once the review council approves, push your changes and create a PR: ```bash -/uf.finale +/finale ``` Or manually: @@ -108,23 +108,23 @@ git push -u origin my-branch gh pr create --title "feat: add user auth" --body "..." ``` -## Step 3: Post-PR Review with `/uf.review-pr` {#step-3-post-pr-review-with-review-pr} +## Step 3: Post-PR Review with `/review-pr` After the PR is created and CI has run, review the PR: ```text -/uf.review-pr +/review-pr ``` This auto-detects the open PR for your current branch. To review a specific PR (including someone else's): ```text -/uf.review-pr 42 +/review-pr 42 ``` ### What Happens -`/uf.review-pr` runs a structured review informed by CI results: +`/review-pr` runs a structured review informed by CI results: 1. **Resolve PR** — auto-detect or use the provided PR number 2. **Fetch metadata** — title, description, changed files, branch info @@ -135,7 +135,6 @@ This auto-detects the open PR for your current branch. To review a specific PR ( 7. **Spec alignment** — locate the associated spec for intent checking 8. **AI review** — judgment on alignment, security, and architecture 9. **Structured report** — severity-classified findings -10. **Verdict posting** — posts the verdict as a GitHub PR review for all outcomes (APPROVE, REQUEST_CHANGES, or COMMENT) ### Expected Output @@ -167,7 +166,7 @@ Verdict: 2 findings (1 HIGH, 1 MEDIUM) When CI checks fail on your PR, the key question is: *did my changes cause this?* -`/uf.review-pr` answers this by checking whether the same check also fails on the base branch: +`/review-pr` answers this by checking whether the same check also fails on the base branch: | Base Branch | PR Check | Classification | |-------------|----------|----------------| @@ -177,11 +176,11 @@ When CI checks fail on your PR, the key question is: *did my changes cause this? **PR-caused failures** are reported as HIGH or CRITICAL findings. These are your regressions. -**Pre-existing failures** are reported separately and do not block the PR verdict. They are not your problem — but `/uf.review-pr` can help fix them. +**Pre-existing failures** are reported separately and do not block the PR verdict. They are not your problem — but `/review-pr` can help fix them. ## Step 5: Fix Branches for Pre-existing Failures -When pre-existing failures are found, `/uf.review-pr` offers to create a fix branch: +When pre-existing failures are found, `/review-pr` offers to create a fix branch: ```text I identified 1 pre-existing CI failure: @@ -204,34 +203,34 @@ The two review commands fit into the standard development workflow: ```text /speckit.specify # define the work ↓ -/uf.unleash # implement autonomously +/unleash # implement autonomously ↓ -/uf.review-council # validate locally (pre-PR) +/review-council # validate locally (pre-PR) ↓ -/uf.finale # commit, push, create PR +/finale # commit, push, create PR ↓ -/uf.review-pr # review with CI data (post-PR) +/review-pr # review with CI data (post-PR) ↓ Merge # after reviewer approval ``` -You can use either command independently — they do not depend on each other. But together they catch issues at two different points: before the code leaves your machine and after it runs through CI. Additionally, `/uf.review-council N` can optionally post its findings to an existing PR, bridging the pre-PR and post-PR stages when you want multi-persona review results visible on the PR itself. +You can use either command independently — they do not depend on each other. But together they catch issues at two different points: before the code leaves your machine and after it runs through CI. Additionally, `/review-council N` can optionally post its findings to an existing PR, bridging the pre-PR and post-PR stages when you want multi-persona review results visible on the PR itself. ## Decision Table | Situation | Command | Why | |-----------|---------|-----| -| Before pushing | `/uf.review-council` | Catch issues locally with 5+ parallel reviewers | -| Post council findings to a PR | `/uf.review-council N` | Multi-persona local review with findings posted as a GitHub PR review | -| After creating a PR | `/uf.review-pr` | Review with CI results and causality analysis | -| Reviewing someone else's PR | `/uf.review-pr 42` | Works on any PR by number | -| CI failed, unsure if my fault | `/uf.review-pr` | Causality classification separates your regressions from noise | -| Want maximum coverage | Both in sequence | `/uf.review-council` pre-push, `/uf.review-pr` post-PR | +| Before pushing | `/review-council` | Catch issues locally with 5+ parallel reviewers | +| Post council findings to a PR | `/review-council N` | Multi-persona local review with findings posted as a GitHub PR review | +| After creating a PR | `/review-pr` | Review with CI results and causality analysis | +| Reviewing someone else's PR | `/review-pr 42` | Works on any PR by number | +| CI failed, unsure if my fault | `/review-pr` | Causality classification separates your regressions from noise | +| Want maximum coverage | Both in sequence | `/review-council` pre-push, `/review-pr` post-PR | -> **`/uf.review-council N` vs `/uf.review-pr N`**: Both target a specific PR, but they serve different purposes. `/uf.review-council N` runs the full multi-persona local review and posts the aggregated findings to the PR. `/uf.review-pr N` fetches CI results, performs causality analysis (PR-caused vs pre-existing failures), and reviews the PR diff with that context. Use `/uf.review-council N` when you want the council's multi-persona review visible on the PR; use `/uf.review-pr N` when you need CI-aware review with causality classification. +> **`/review-council N` vs `/review-pr N`**: Both target a specific PR, but they serve different purposes. `/review-council N` runs the full multi-persona local review and posts the aggregated findings to the PR. `/review-pr N` fetches CI results, performs causality analysis (PR-caused vs pre-existing failures), and reviews the PR diff with that context. Use `/review-council N` when you want the council's multi-persona review visible on the PR; use `/review-pr N` when you need CI-aware review with causality classification. ## See Also -- [Common Workflows](/docs/getting-started/common-workflows/) -- `/uf.review-council` vs `/uf.review-pr` comparison table and full command reference +- [Common Workflows](/docs/getting-started/common-workflows/) -- `/review-council` vs `/review-pr` comparison table and full command reference - [Quick Start](/docs/getting-started/quick-start/) -- Install and verify the toolchain - [Developer Guide](/docs/getting-started/developer/) -- Daily workflow with the `uf` CLI diff --git a/content/docs/getting-started/common-workflows.md b/content/docs/getting-started/common-workflows.md index 7ca6644..3509289 100644 --- a/content/docs/getting-started/common-workflows.md +++ b/content/docs/getting-started/common-workflows.md @@ -1,6 +1,6 @@ --- title: "Common Workflows" -description: "The /uf.unleash autonomous pipeline, /uf.finale shipping workflow, manual feature flows, bug fixes, code reviews, and environment setup." +description: "The /unleash autonomous pipeline, /finale shipping workflow, manual feature flows, bug fixes, code reviews, and environment setup." lead: "End-to-end workflows that show how all five heroes collaborate across the development lifecycle." date: 2026-03-22T00:00:00+00:00 draft: false @@ -8,9 +8,9 @@ weight: 70 toc: true --- -## Autonomous Pipeline (`/uf.unleash`) {#autonomous-pipeline-unleash} +## Autonomous Pipeline (`/unleash`) -`/uf.unleash` is the autonomous Speckit pipeline execution command. It takes a spec from draft to demo-ready code in a single command, orchestrating the full pipeline with graceful exit points and full resumability. +`/unleash` is the autonomous Speckit pipeline execution command. It takes a spec from draft to demo-ready code in a single command, orchestrating the full pipeline with graceful exit points and full resumability. ### The Pipeline @@ -21,7 +21,7 @@ toc: true | 3 | **Tasks** | Delegates to Cobalt-Crush to generate `tasks.md` via `/speckit.tasks` | | 4 | **Spec Review** | Runs the review council in Spec Review Mode. Auto-fixes LOW/MEDIUM findings. Exits on HIGH/CRITICAL. | | 5 | **Implement** | Parses `tasks.md` for phases. `[P]` parallel tasks run via Replicator worktrees (up to 4 concurrent workers). Phase checkpoints run CI commands derived from `.github/workflows/`. | -| 6 | **Code Review** | Runs the review council in Code Review Mode. Includes Phase 1a CI soft gate with causality analysis, Phase 1b Gaze quality analysis, and Divisor agent reviews. Up to 3 fix iterations. | +| 6 | **Code Review** | Runs the review council in Code Review Mode. Includes Phase 1a CI hard gate, Phase 1b Gaze quality analysis, and Divisor agent reviews. Up to 3 fix iterations. | | 7 | **Retrospective** | Analyzes the session and stores learnings in Dewey semantic memory. | | 8 | **Demo** | Presents structured demo instructions: what was built, how to verify, key files changed, and next steps. | @@ -35,15 +35,15 @@ toc: true ### Branch Safety -`/uf.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 (`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 `/uf.unleash` completes, the demo step suggests running `/uf.finale` to commit, push, and create a PR. +After `/unleash` completes, the demo step suggests running `/finale` to commit, push, and create a PR. See also: [From Spec to Demo in One Command](/blog/unleash-in-practice/) — a narrative walkthrough of the pipeline. -## End-of-Branch Workflow (`/uf.finale`) {#end-of-branch-workflow-finale} +## End-of-Branch Workflow (`/finale`) -`/uf.finale` automates the end-of-branch workflow — one command to stage, commit, push, create a PR, watch CI, and return to main. The PR stays open for human review. +`/finale` automates the end-of-branch workflow — one command to stage, commit, push, create a PR, watch CI, and return to main. The PR stays open for human review. ### The 8-Step Workflow @@ -51,9 +51,9 @@ See also: [From Spec to Demo in One Command](/blog/unleash-in-practice/) — a n | ---- | --------------------------- | ----------------------------------------------------------------------------------- | | 1 | **Branch Safety Gate** | Verifies not on `main`. Notes the branch name. | | 2 | **Check for Changes** | Inspects working tree. If clean, checks for unpushed commits or existing PR. | -| 3 | **Generate Commit Message** | Analyzes staged changes, generates conventional commit message, shows for approval. Appends [AI attribution](#structured-pr-descriptions) to the commit. | +| 3 | **Generate Commit Message** | Analyzes staged changes, generates conventional commit message, shows for approval. | | 4 | **Push to Remote** | Sets upstream if needed (`git push -u origin `). | -| 5 | **Create or Find PR** | Creates PR via `gh pr create` with a [structured PR body](#structured-pr-descriptions), or finds an existing one. Respects [PR templates](#structured-pr-descriptions) when present. | +| 5 | **Create or Find PR** | Creates PR via `gh pr create` or finds existing one. | | 6 | **Watch CI Checks** | `gh pr checks --watch`. Stops on failure with options. | | 7 | **Return to Main** | `git checkout main && git pull`. | | 8 | **Summary** | Displays completion report: branch, commit, PR, checks, status. | @@ -64,46 +64,13 @@ See also: [From Spec to Demo in One Command](/blog/unleash-in-practice/) — a n - Never merges the PR — creates PRs for review, not for immediate merge - Never stages secret files (`.env`, `credentials.json`, `*.key`, `*.pem`) without warning - Never commits without user approval of the commit message -- Never creates a PR without user approval -- Uses `--body-file` instead of inline `--body` to safely handle AI-generated content containing shell metacharacters - If any step fails, stops immediately with context and options -### Structured PR Descriptions - -When creating a PR, `/uf.finale` generates a structured body with four sections: - -| Section | Content | -| -------------------- | ----------------------------------------------------------------------- | -| **Summary** | What changed and why, derived from the diff and commit messages. | -| **How to Test** | Steps to verify the changes locally. | -| **How to Demo** | Steps to demonstrate the feature to stakeholders. | -| **Key Files Changed**| List of modified files grouped by purpose. | - -**PR template detection**: If the repository contains `.github/PULL_REQUEST_TEMPLATE.md`, `/uf.finale` reads the template and maps its generated content into the template's sections instead of using the default structure. - -**Review council integration**: If a `/uf.review-council` report exists from a prior run, known issues are included in the PR body under a **Known Issues** section. - -**AI attribution**: Every PR created by `/uf.finale` includes an AI attribution footer in the PR body and an `AI-assisted-by: /uf.finale` git trailer in the commit metadata. - -### Conflict Recovery - -When the push step (step 4) fails because the remote branch has diverged, `/uf.finale` enters conflict recovery mode and presents five options: - -| Option | Name | Description | -| ------ | -------------------------- | ------------------------------------------------------------------------------------------------ | -| 1 | **Retry** | Attempts the push again (useful if the conflict was transient). | -| 2 | **Manual Resolution** | Prints step-by-step instructions for resolving conflicts locally with `git pull --rebase`. | -| 3 | **Abort** | Stops the workflow and returns to the shell without changes. | -| 4 | **Force Push** | Overwrites the remote branch (`git push --force-with-lease`). Use with caution. | -| 5 | **AI-Assisted Resolution** | Spawns a sub-agent to merge the target branch, identify conflicts, and resolve them with AI. | - -The AI-assisted option (5) spawns a `cobalt-crush-dev` sub-agent that merges the target branch into your feature branch, analyzes the intent of both sides using the diff context, resolves conflict markers programmatically, and creates a merge commit. After resolution, the normal push flow resumes. If the sub-agent cannot resolve the conflicts, `/uf.finale` falls back to manual resolution instructions. - -`/uf.finale` works with both Speckit (`NNN-*`) and OpenSpec (`opsx/*`) branches. It is the natural complement to `/uf.unleash` — `/uf.unleash` builds, `/uf.finale` wraps up the branch and creates a PR for review. +`/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. ## New Feature (End-to-End) {#new-feature-end-to-end} -> For autonomous execution of this entire workflow in one command, use [`/uf.unleash`](#autonomous-pipeline-unleash). The manual flow below gives you step-by-step control over each stage. +> For autonomous execution of this entire workflow in one command, use [`/unleash`](#autonomous-pipeline-unleash). The manual flow below gives you step-by-step control over each stage. The full hero lifecycle for a new feature follows six stages. Each stage is owned by a specific hero, and each produces artifacts consumed by the next. Every stage has an **execution mode** -- either `[human]` (driven by the operator) or `[swarm]` (run autonomously by the agent swarm). @@ -151,8 +118,8 @@ The [Developer (Cobalt-Crush)](/docs/getting-started/developer/) creates the tec - Generate tasks: `/speckit.tasks` - Run cross-artifact analysis: `/speckit.analyze` - Validate checklists: `/speckit.checklist` -- Execute implementation: `/speckit.implement` or `/uf.cobalt-crush` -- For parallel work: use `/uf.unleash` which handles parallel task execution automatically +- Execute implementation: `/speckit.implement` or `/cobalt-crush` +- For parallel work: use `/unleash` which handles parallel task execution automatically - Mark each task `[x]` in tasks.md as it completes - Run tests after each phase checkpoint @@ -173,7 +140,7 @@ The [Developer (Cobalt-Crush)](/docs/getting-started/developer/) creates the tec [The Divisor](/docs/team/the-divisor/) reviews the code through its specialized personas. -- Invoke the review council: `/uf.review-council` +- Invoke the review council: `/review-council` - Review personas evaluate in parallel: - **Guard**: Intent drift, constitution alignment, zero-waste - **Architect**: Coding conventions, pattern adherence, DRY @@ -330,74 +297,6 @@ This context is automatic -- heroes query Dewey's MCP tools as part of their nor Dewey operates on a [3-tier graceful degradation](/docs/getting-started/knowledge/#graceful-degradation) model: full semantic search when Dewey and Ollama are available, structured graph queries when only the knowledge graph is indexed, and direct file reads when Dewey is not configured. Every hero functions at all three tiers -- Dewey enriches the workflow but never blocks it. -## Issue Triage (`/uf.triage-issue`) - -`/uf.triage-issue` evaluates a GitHub issue through 5 Divisor agents, each assessing the issue from a different perspective. The agents produce a consolidated triage recommendation with classification, severity, priority, and suggested labels. - -```text -/uf.triage-issue 42 -/uf.triage-issue owner/repo#42 -``` - -### Triage Agents - -| Agent | Focus Area | -| -------------- | ----------------------------------------------------------------- | -| **Architect** | Architectural impact, design implications, scope assessment | -| **Adversary** | Security risks, attack surface, resilience concerns | -| **Guard** | Intent alignment, scope discipline, duplicate detection | -| **SRE** | Operational impact, deployment risk, monitoring implications | -| **Testing** | Testability, regression risk, coverage gaps | - -### Classification Categories - -Each agent classifies the issue into one of 7 categories: **bug**, **feature**, **enhancement**, **question**, **opinion**, **duplicate**, or **needs-info**. The agents' assessments are aggregated into a final triage verdict with a consolidated severity, priority recommendation, and suggested labels. - -### Human-Gated Label Mutations - -Label changes are gated behind a confirmation prompt — the command never adds or removes labels on the issue automatically. After presenting the triage verdict, `/uf.triage-issue` asks for explicit approval before applying any label mutations to the GitHub issue. - -## Swarm Coordination (`/forge`) - -`/forge` orchestrates parallel task execution across isolated git worktrees. It decomposes a task into subtasks, spawns worker agents in separate worktrees, and coordinates their execution with file reservation to prevent conflicts. Use `/forge` when you have multiple independent tasks that can be implemented concurrently by separate agents. - -```text -/forge "implement auth module and dashboard widget" -``` - -## Swarm Status (`/forge:status`) - -`/forge:status` (a subcommand of `/forge`) checks the status of an active swarm execution. It reports progress for each spawned worker — including completion percentage, files touched, and any blockers — so you can monitor parallel work without switching between worktrees. - -```text -/forge:status -``` - -## Work Item Management (`/org`) - -`/org` queries and manages work items in the org database. It supports tasks, bugs, features, epics, and chores with priority scoring and dependency tracking. Use `/org` to list open items, filter by status or type, create new work items, or check what's ready to pick up next. - -```text -/org # list open items -/org --ready # show unblocked items -``` - -## Agent Inbox (`/inbox`) - -`/inbox` checks the inter-agent communications inbox for messages from other agents in the swarm. Messages include progress updates, blockers, context broadcasts, and coordination signals. Use `/inbox` at session start to catch up on activity from parallel workers or previous sessions. - -```text -/inbox -``` - -## Session Handoff (`/handoff`) - -`/handoff` ends the current work session with structured handoff notes for the next session. It captures what was accomplished, what's in progress, any blockers encountered, and recommended next steps. The handoff notes are persisted so the next session can resume with full context. - -```text -/handoff -``` - ## Bug Fix (Tactical) For bug fixes and small changes (fewer than 3 user stories), use the OpenSpec tactical workflow instead of the full Speckit pipeline. @@ -423,17 +322,17 @@ This creates an `opsx/fix-auth-timeout` branch and checks it out automatically. Invoke Cobalt-Crush to implement with convention pack adherence: ```text -/uf.cobalt-crush +/cobalt-crush ``` -`/uf.cobalt-crush` detects the active OpenSpec change and implements the tasks through the `cobalt-crush-dev` agent, which loads [convention packs](/docs/getting-started/developer/#convention-packs) and applies the project's coding standards. This gives you the quality enforcement that a bare `/opsx-apply` would skip. Before proceeding, it validates that you are on the correct `opsx/` branch. +`/cobalt-crush` detects the active OpenSpec change and implements the tasks through the `cobalt-crush-dev` agent, which loads [convention packs](/docs/getting-started/developer/#convention-packs) and applies the project's coding standards. This gives you the quality enforcement that a bare `/opsx-apply` would skip. Before proceeding, it validates that you are on the correct `opsx/` branch. ### 3. Review Run the review council to validate the fix: ```text -/uf.review-council +/review-council ``` The Divisor personas review the changes. Address any REQUEST CHANGES findings. @@ -455,8 +354,8 @@ The review council brings multiple specialized perspectives to every code review ### Invoking the Council ```text -/uf.review-council -/uf.review-council 42 # optionally specify a PR number +/review-council +/review-council 42 # optionally specify a PR number ``` The council discovers available Divisor persona agents in `.opencode/agents/divisor-*.md` and launches all of them in parallel. When a PR number is provided, the council posts its consolidated findings as a GitHub PR review after the local review completes. Without a PR number, the review runs locally only. See the [Code Review Tutorial](/docs/getting-started/code-review-tutorial/#optional-post-to-github) for the full GitHub posting workflow. @@ -478,26 +377,13 @@ The council discovers available Divisor persona agents in `.opencode/agents/divi Before delegating to Divisor agents, the review council runs a two-phase CI gate: -**Phase 1a — CI Soft Gate with Causality Analysis**: Derives build, test, vet, lint, and vulnerability check commands from `.github/workflows/` files and executes them locally. When a check fails, the council determines whether the failure is *new* (introduced by your branch) or *pre-existing* (already broken on `main`): - -| Your Branch | `main` Baseline | Classification | Effect | -| ----------- | --------------- | -------------- | ------ | -| Fail | Pass | **New failure** | Blocks the review — fix before proceeding | -| Fail | Fail | **Pre-existing** | Informational only — does not block | -| Fail | No data | **Unknown** | Treated as new (conservative) | - -To establish the `main` baseline, the council uses a two-tier strategy: - -1. **GitHub CI API** — checks recent CI results for the `main` branch via the GitHub API. This is fast and requires no local work. -2. **Git worktree fallback** — if the API returns no data (no recent runs, no `gh` CLI, private repo restrictions), the council creates a temporary worktree of `main`, runs the same commands locally, and compares results. The worktree is cleaned up automatically. - -Pre-existing failures appear in an informational section of the council report. They are visible but do not count toward the verdict. New failures (regressions your branch introduced) remain blocking — the review stops before invoking Divisor agents. +**Phase 1a — CI Hard Gate**: Derives build, test, vet, lint, and vulnerability check commands from `.github/workflows/` files and executes them locally. Any non-zero exit code is a gate failure — the review stops before invoking Divisor agents. This ensures the code compiles, tests pass, and static analysis is clean before spending review tokens. **Phase 1b — Conditional Gaze Quality Analysis**: If Gaze is installed, runs `gaze report` to generate CRAP scores, contract coverage, and quality findings. The results are passed as context to Divisor agents — the Testing persona uses Gaze data as evidence for coverage assessment. If Gaze is not installed, Phase 1b is skipped with an informational note. ### The Review Loop -1. Phase 1a CI gate must pass (only new failures block — pre-existing failures are informational) +1. Phase 1a CI gate must pass before reviews begin 2. All personas review in parallel and return APPROVE or REQUEST CHANGES 3. If any persona returns REQUEST CHANGES, the developer addresses the findings 4. All personas re-review after fixes @@ -508,62 +394,7 @@ Pre-existing failures appear in an informational section of the council report. The council returns **APPROVE** only when all active personas approve. A single REQUEST CHANGES means the council verdict is REQUEST CHANGES. When all personas approve but one or more include advisory findings (LOW-severity observations), the verdict is **APPROVE WITH ADVISORIES**. Missing personas (agent files not found) don't block the verdict but are noted in the report. -When posting to GitHub via `/uf.review-council N`, the council verdict maps to a GitHub review event: APPROVE maps to `APPROVE`, REQUEST CHANGES maps to `REQUEST_CHANGES`, and APPROVE WITH ADVISORIES maps to `COMMENT` (ensuring advisory findings are visible on the PR without blocking merge). - -### GitHub Review Posting - -After the council reaches a verdict, it can post the consolidated findings as a GitHub PR review. This bridges local review quality with the PR conversation on GitHub. - -```text -/uf.review-council [PR-number] -``` - -The optional PR number argument targets a specific PR. If omitted, the council auto-detects the open PR for your current branch. - -**How it works**: - -1. The council completes its normal review (CI gate + Divisor personas) -2. If a PR is detected, the council offers to post findings as a GitHub review -3. All persona findings are aggregated into a single review with per-persona sections -4. The council asks for **human confirmation** before posting — it never posts automatically - -**Verdict mapping**: - -| Council Verdict | GitHub Review State | When | -| --------------- | ------------------- | ---- | -| APPROVE | `APPROVE` | All personas approve | -| REQUEST CHANGES | `REQUEST_CHANGES` | Any persona returns REQUEST CHANGES with HIGH/CRITICAL findings | -| Mixed (LOW/MEDIUM only) | `COMMENT` | Findings exist but none are HIGH or CRITICAL | - -**Pre-posting checks**: Before offering to post, the council verifies the PR exists, the branch matches, and you have write permissions to the repository. - -**Graceful degradation**: If the `gh` CLI is not installed, the PR is not found, or permissions are insufficient, the review proceeds normally without posting. The council report is still displayed locally — GitHub posting is an optional enhancement, not a requirement. - -### Post-PR Review (`/uf.review-pr`) - -`/uf.review-pr` reviews a pull request with full CI context — fetching check results, classifying failures by causality, and running a scoped diff review informed by what CI already validated. - -```text -/uf.review-pr -``` - -This auto-detects the open PR for your current branch. To review a specific PR (including someone else's): - -```text -/uf.review-pr 42 -``` - -**What it does**: - -1. Resolves the PR and fetches metadata (title, description, changed files) -2. Retrieves CI check results and classifies each failure as PR-caused or pre-existing (causality analysis) -3. Runs local tool checks only for what CI did not already cover -4. Fetches the scoped diff and performs an AI review with severity-classified findings -5. Posts the verdict as a GitHub PR review - -**Verdict posting for all outcomes**: The verdict posting step runs for every review outcome — APPROVE, REQUEST_CHANGES, and COMMENT verdicts are all posted to the PR. Previously, verdict posting was skipped when a review had only MEDIUM/LOW findings or zero findings. Now, clean reviews receive an explicit APPROVE post on the PR, giving the author clear signal that the review passed. - -**CI causality analysis**: When CI checks fail, `/uf.review-pr` determines whether your PR caused the failure or whether it was pre-existing on the base branch. Pre-existing failures are reported separately and do not block the verdict. See the [Code Review Tutorial](/docs/getting-started/code-review-tutorial/#step-3-post-pr-review-with-review-pr) for a full walkthrough with example output. +When posting to GitHub via `/review-council N`, the council verdict maps to a GitHub review event: APPROVE maps to `APPROVE`, REQUEST CHANGES maps to `REQUEST_CHANGES`, and APPROVE WITH ADVISORIES maps to `COMMENT` (ensuring advisory findings are visible on the PR without blocking merge). ## Environment Setup @@ -626,7 +457,7 @@ Open OpenCode and start with the Speckit pipeline for a new feature: Then run the full autonomous pipeline: ```text -/uf.unleash +/unleash ``` ## Next Steps diff --git a/content/docs/getting-started/constitution.md b/content/docs/getting-started/constitution.md index 1adb142..0572037 100644 --- a/content/docs/getting-started/constitution.md +++ b/content/docs/getting-started/constitution.md @@ -130,7 +130,7 @@ The Constitution Check is a mandatory gate at the planning phase. Before impleme Violations are CRITICAL severity and non-negotiable -- they must be resolved before implementation proceeds. -The `/uf.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-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. @@ -141,7 +141,7 @@ The constitution sits at the top of a layered governance model. Each layer const 1. **Constitution** — core principles (this document) 2. **Convention packs** — portable coding standards (MUST/SHOULD/MAY rules) 3. **Agent personas** — individual hero configurations and behavioral constraints -4. **Commands** — workflow orchestration (`/uf.unleash`, `/uf.review-council`, `/speckit.*`) +4. **Commands** — workflow orchestration (`/unleash`, `/review-council`, `/speckit.*`) 5. **CI pipelines** — automated deterministic checks A convention pack cannot override a constitutional principle. A command cannot bypass a convention pack rule. This layered model ensures that organizational intent flows consistently from principles to implementation. The constitution and governance model are decay-resistant — they encode organizational values and process rules that persist regardless of how AI model capabilities evolve. diff --git a/content/docs/getting-started/developer.md b/content/docs/getting-started/developer.md index 7416406..416c6a4 100644 --- a/content/docs/getting-started/developer.md +++ b/content/docs/getting-started/developer.md @@ -81,15 +81,15 @@ For features that need architectural planning: 3. **Unleash** (build mode): The swarm takes it from here -- clarification, planning, implementation, testing, and review ```text - /uf.unleash + /unleash ``` - If `/uf.unleash` pauses (unanswerable question, spec finding, build failure), fix the issue and re-run. If the spec needs refinement, run `/speckit.clarify` then `/uf.unleash` again. + If `/unleash` pauses (unanswerable question, spec finding, build failure), fix the issue and re-run. If the spec needs refinement, run `/speckit.clarify` then `/unleash` again. 4. **Finale** (build mode): Wrap up -- commit, push, and create a PR for review ```text - /uf.finale + /finale ``` ### Small Tasks (Tactical) @@ -107,20 +107,20 @@ For bug fixes and changes that don't need the full Speckit pipeline: 3. **Implement** (build mode): Invoke Cobalt-Crush to implement with convention pack adherence ```text - /uf.cobalt-crush + /cobalt-crush ``` - `/uf.cobalt-crush` delegates to the `cobalt-crush-dev` agent, which loads [convention packs](/docs/getting-started/developer/#convention-packs) and applies the project's coding standards. This gives you the quality enforcement that a bare `/opsx-apply` would skip. + `/cobalt-crush` delegates to the `cobalt-crush-dev` agent, which loads [convention packs](/docs/getting-started/developer/#convention-packs) and applies the project's coding standards. This gives you the quality enforcement that a bare `/opsx-apply` would skip. 4. **Finale** (build mode): Ship it ```text - /uf.finale + /finale ``` ## Working with Speckit -Speckit is the strategic specification pipeline for features that need architectural planning. For autonomous execution of the entire pipeline, run [`/uf.unleash`](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash) -- it handles clarification, planning, implementation, testing, and review in a single command, pausing only when human judgment is needed. +Speckit is the strategic specification pipeline for features that need architectural planning. For autonomous execution of the entire pipeline, run [`/unleash`](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash) -- it handles clarification, planning, implementation, testing, and review in a single command, pausing only when human judgment is needed. For step-by-step control, use the individual commands: @@ -155,11 +155,11 @@ Both workflows enforce branch conventions: Speckit uses `NNN-` branc ### Replicator + Speckit Integration -When a `tasks.md` file exists from the Speckit pipeline, Replicator uses it as the authoritative task decomposition instead of generating its own. It maps each phase to an epic and respects the `[P]` parallel markers and phase dependencies. The `/uf.unleash` command orchestrates this automatically. +When a `tasks.md` file exists from the Speckit pipeline, Replicator uses it as the authoritative task decomposition instead of generating its own. It maps each phase to an epic and respects the `[P]` parallel markers and phase dependencies. The `/unleash` command orchestrates this automatically. ### Parallel Workers -When `/uf.unleash` encounters `[P]`-marked tasks, Replicator spawns parallel workers in dedicated git worktrees. Each worker: +When `/unleash` encounters `[P]`-marked tasks, Replicator spawns parallel workers in dedicated git worktrees. Each worker: 1. Calls `swarmmail_reserve()` to lock their files 2. Implements their subtask @@ -196,16 +196,15 @@ This prevents conflicts when multiple workers are active. Reservations auto-rele Every session follows this ritual: -| Step | Command | Purpose | -| ----------- | ------------------------------------- | --------------------------------------- | -| **Start** | `/speckit.specify` or `/opsx-propose` | Define the work | -| **Work** | `/uf.unleash` or `/uf.cobalt-crush` | Execute the work | -| **Monitor** | `/forge:status` or `/inbox` | Check parallel work or agent messages | -| **End** | `/uf.finale` or `/handoff` | Ship the PR or hand off to next session | +| Step | Command | Purpose | +| --------- | ------------------------------------- | --------------------------------------- | +| **Start** | `/speckit.specify` or `/opsx-propose` | Define the work | +| **Work** | `/unleash` or `/cobalt-crush` | Execute the work | +| **End** | `/finale` | Commit, push, create PR for review | ## Cobalt-Crush Persona -[Cobalt-Crush](/docs/team/cobalt-crush/) is the developer persona -- the Engineering Core of the swarm. When you invoke `/speckit.implement` or `/uf.cobalt-crush`, you're working with an agent that follows six core principles: +[Cobalt-Crush](/docs/team/cobalt-crush/) is the developer persona -- the Engineering Core of the swarm. When you invoke `/speckit.implement` or `/cobalt-crush`, you're working with an agent that follows six core principles: - **Clean Code**: Single-purpose functions, intent-revealing names, no dead code - **SOLID**: Applied at function, type, and package levels @@ -277,7 +276,7 @@ Custom rules are loaded by Cobalt-Crush during implementation and by all Divisor Cobalt-Crush integrates with two feedback systems: - **Gaze feedback**: After writing code, checks `.uf/artifacts/quality-report/` for quality findings. High CRAP scores trigger complexity reduction; low contract coverage triggers test improvements. -- **Divisor feedback**: Before submitting for review, validates against a pre-review checklist. After review, addresses findings by persona and severity (CRITICAL and HIGH first). The review council also supports posting its consolidated findings as a GitHub PR review via `/uf.review-council N` — see the [Code Review Tutorial](/docs/getting-started/code-review-tutorial/#optional-post-to-github) for details. +- **Divisor feedback**: Before submitting for review, validates against a pre-review checklist. After review, addresses findings by persona and severity (CRITICAL and HIGH first). The review council also supports posting its consolidated findings as a GitHub PR review via `/review-council N` — see the [Code Review Tutorial](/docs/getting-started/code-review-tutorial/#optional-post-to-github) for details. ### Gatekeeping Value Protection @@ -359,16 +358,16 @@ After completion, `uf init` shows a summary with file dispositions (`+` created, ## Session Ritual -The most important habit: **always end your session properly**. The daily workflow follows a specify → unleash → finale loop. When you are done working, run `/uf.finale` to commit, push, and create a PR for review: +The most important habit: **always end your session properly**. The daily workflow follows a specify → unleash → finale loop. When you are done working, run `/finale` to commit, push, and create a PR for review: ```text -/uf.finale # commit → push → PR → main +/finale # commit → push → PR → main ``` -`/uf.finale` handles the full end-of-branch workflow: staging changes, generating a conventional commit message with AI attribution, pushing to remote, creating a PR with a [structured description](/docs/getting-started/common-workflows/#structured-pr-descriptions), watching CI checks, and returning to `main`. The PR stays open for human review — `/uf.finale` never merges. The session is not complete until `git push` succeeds — this ensures your work items, semantic memory learnings, and file reservation state are available for your next session and for other team members who may pick up where you left off. +`/finale` handles the full end-of-branch workflow: staging changes, generating a conventional commit message, pushing to remote, creating a PR, watching CI checks, and returning to `main`. The PR stays open for human review — `/finale` never merges. The session is not complete until `git push` succeeds — this ensures your work items, semantic memory learnings, and file reservation state are available for your next session and for other team members who may pick up where you left off. ## Next Steps - Read the [Common Workflows](/docs/getting-started/common-workflows/) page to understand how your work flows through the full hero lifecycle - Explore the [Cobalt-Crush](/docs/team/cobalt-crush/) team page for the full persona details -- Run `uf doctor` to verify your environment, then try `/uf.unleash` on your first feature +- Run `uf doctor` to verify your environment, then try `/unleash` on your first feature diff --git a/content/docs/getting-started/knowledge.md b/content/docs/getting-started/knowledge.md index dafe8e5..1963da1 100644 --- a/content/docs/getting-started/knowledge.md +++ b/content/docs/getting-started/knowledge.md @@ -44,28 +44,8 @@ RPM packages are available for both `amd64` and `arm64` architectures. The binar The `granite-embedding:30m` model is IBM's Granite Embedding — a 63 MB model licensed under Apache 2.0 with full training data transparency. It runs locally via Ollama; no data leaves your machine. -> **Note**: macOS Homebrew cask install issues that affected v3.1.0 and v3.2.0 (SHA-256 mismatch errors) have been fixed. If you previously encountered install failures, retry with the latest version. - Pulling the embedding model is recommended but not strictly required to start using Dewey. If the model is not available, Dewey continues in keyword-only mode — structured graph queries, tag lookups, and keyword search all work. Semantic search becomes available once the model is pulled. See [Graceful Degradation](#graceful-degradation) for details. -### RPM (Fedora, RHEL, CentOS) - -RPM packages are published with every Dewey release on GitHub, available for both `amd64` and `arm64` architectures. Download the package for your platform from the [latest release](https://github.com/unbound-force/dewey/releases/latest) and install: - -```bash -sudo dnf install ./dewey__linux_amd64.rpm -``` - -The RPM installs the `dewey` binary to `/usr/bin/dewey`. - -### Install from Source - -If pre-built packages are not available for your platform, install from source: - -```bash -go install github.com/unbound-force/dewey/v3@latest -``` - ### Embedding Model Alignment The Unbound Force swarm and Dewey are aligned on the same embedding model (IBM Granite `granite-embedding:30m`). To ensure consistency for processes spawned outside of `uf setup` (e.g., `dewey serve`, manual `replicator init`), add these environment variables to your shell profile (`~/.zshrc` or `~/.bashrc`): @@ -82,12 +62,8 @@ export DEWEY_CHUNK_MAX_CHARS=12288 | `OLLAMA_EMBED_DIM` | `256` | Embedding vector dimension | | `DEWEY_CHUNK_MAX_CHARS` | `12288` | Maximum chunk size (in characters) for embedding. Overrides the `embedding.max_chunk_chars` config value when set. | | `DEWEY_EMBEDDING_ENDPOINT` | — | Overrides the Ollama endpoint for embedding requests. Takes highest precedence (see [Endpoint Resolution](#endpoint-resolution) below). | -| `DEWEY_SYNTHESIS_ENDPOINT` | — | Overrides the Ollama endpoint for synthesis (compilation, curation) requests. Fallback chain: `DEWEY_SYNTHESIS_ENDPOINT` → `OLLAMA_HOST` → `http://localhost:11434`. | -| `DEWEY_AUTHOR` | — | Author tag for learning identities (e.g., `alice`). Used in CI or shared environments to attribute learnings to a specific author. | | `OLLAMA_HOST` | — | Standard Ollama environment variable. Dewey reads this as a fallback when `DEWEY_EMBEDDING_ENDPOINT` is not set and no `embedding.endpoint` is configured in `config.yaml`. | -> **Synthesis vs. embedding precedence**: Synthesis endpoint resolution uses an inverted precedence compared to embedding. For synthesis, `config.yaml` settings take highest priority over environment variables (`config.yaml` > `DEWEY_SYNTHESIS_ENDPOINT` > `OLLAMA_HOST` > default). For embedding, environment variables take highest priority (`DEWEY_EMBEDDING_ENDPOINT` > `config.yaml` > `OLLAMA_HOST` > default). This means setting `DEWEY_SYNTHESIS_ENDPOINT` has no effect if `synthesis.endpoint` is set in `config.yaml`. - `uf setup` sets `OLLAMA_MODEL` and `OLLAMA_EMBED_DIM` automatically during installation. The shell profile entries ensure they persist across terminal sessions. Without them, child processes may use different embedding models, causing inconsistent search results between the swarm and Dewey. ### Endpoint Resolution @@ -103,48 +79,12 @@ Values without a scheme (e.g., `192.168.1.50:11434`) are automatically normalize Most users do not need to set any of these — Dewey connects to `localhost:11434` by default, which is where Ollama listens. Set `OLLAMA_HOST` if you run Ollama on a remote machine or non-standard port, and `DEWEY_EMBEDDING_ENDPOINT` only if Dewey needs a different endpoint than other Ollama clients. -### Provider Configuration - -Dewey supports pluggable providers for both embedding and synthesis operations. Configure providers in your vault's `config.yaml` (`.uf/dewey/config.yaml`): - -**Ollama (default — local, privacy-preserving)**: - -```yaml -embedding: - provider: ollama - model: granite-embedding:30m - endpoint: http://localhost:11434 - -synthesis: - provider: ollama - model: granite3.2:2b - endpoint: http://localhost:11434 -``` +If the Homebrew formula is not yet available, install from source: -**Vertex AI (cloud — Google Cloud Platform)**: - -```yaml -embedding: - provider: vertex - project: my-gcp-project - region: us-east5 - model: text-embedding-005 - -synthesis: - provider: vertex - project: my-gcp-project - region: us-east5 - model: gemini-2.0-flash +```bash +go install github.com/unbound-force/dewey/v3@latest ``` -Vertex AI requires `gcloud` authentication. Run `gcloud auth application-default login` before using Vertex AI providers. - -The `region` field accepts either a specific GCP region (e.g., `us-east5`) or `global`. When set to `global`, Dewey uses the `aiplatform.googleapis.com` endpoint without a region prefix, routing requests to the nearest available region. - -### Global Configuration - -Dewey supports a global configuration file at `~/.config/dewey/config.yaml`. Per-vault configs (`.uf/dewey/config.yaml`) override global settings, allowing you to set organization-wide defaults while customizing individual projects. - ## Initialize Your Repository Initialize Dewey in your repository: @@ -356,8 +296,6 @@ dewey index --source web-go-stdlib This separates the "fetch external content" operation (which may take seconds to minutes) from the "start serving queries" operation (which is near-instant from the persistent index). -The index pipeline is optimized for large vaults: embeddings are generated in batches (batch size 32) rather than per-block, and content sources are fetched concurrently. These optimizations mean indexing time scales sub-linearly with vault size. - ## Extending Your Sources `uf init` gives you disk and GitHub sources automatically, but **web sources must be added manually** because they are project-specific. This is the single most impactful customization you can make — it gives your AI agents access to current API documentation for the frameworks and libraries your project depends on. @@ -445,39 +383,6 @@ For a TypeScript or JavaScript project: After adding web sources, run `dewey index` to fetch and index the new content. Subsequent indexes only re-fetch when the refresh interval expires. -## Content Sanitization - -When indexing content from untrusted sources, Dewey applies a 4-layer sanitization pipeline to protect your knowledge base: - -| Layer | What It Checks | Severity | -| ----- | -------------- | -------- | -| **Injection Pattern Scanning** | 10 regex patterns detecting prompt injection, system prompt overrides, and role manipulation | Critical / High | -| **Content Hash Drift** | Detects unexpected changes in previously indexed content | Medium | -| **Markdown Structure Validation** | Validates Markdown structure to catch malformed or adversarial content | Medium | -| **Size Anomaly Detection** | Flags documents that deviate by more than 3 standard deviations from the source's mean size | Medium | - -Configure sanitization per-source in `sources.yaml`: - -```yaml -sources: - - id: web-external-docs - type: web - name: external-docs - sanitize_mode: strict # warn | strict | off - trust_tier: untrusted # authored | validated | draft | untrusted - config: - urls: - - https://external-docs.example.com/ -``` - -- **`sanitize_mode: strict`** — blocks content that triggers critical or high severity patterns -- **`sanitize_mode: warn`** — logs findings but indexes the content (default) -- **`sanitize_mode: off`** — skips sanitization entirely - -> **Security warning**: Setting `sanitize_mode: off` disables all content scanning. Only use this for fully trusted sources where you control the content. Incorrect `trust_tier` assignment (e.g., marking untrusted content as `authored`) can cause unvalidated content to rank higher in search results. - -Sanitization findings are surfaced by `dewey doctor` and `dewey lint`, making it easy to audit your content pipeline. - ## OpenCode Integration Dewey integrates with OpenCode as an MCP server. Add this to your `opencode.json`: @@ -502,7 +407,7 @@ Once configured, all hero agents can use Dewey's MCP tools for knowledge retriev ### `dewey doctor` -Run `dewey doctor` to check the health of your Dewey installation. It reports on 8 diagnostic sections: +Run `dewey doctor` to check the health of your Dewey installation. It reports on 7 diagnostic sections: | Section | What It Checks | | ----------------------- | ---------------------------------------------------------- | @@ -511,7 +416,6 @@ Run `dewey doctor` to check the health of your Dewey installation. It reports on | **Database** | `graph.db` health, page/block/embedding counts | | **Sources in Database** | Per-source page counts | | **Embedding Layer** | Ollama availability, model status, legacy model advisory | -| **Synthesis Layer** | Provider type (ollama/vertex/unconfigured), resolved endpoint, model name, connectivity status, and (for Ollama) model availability | | **MCP Server** | Lock file, `opencode.json` configuration | | **Summary** | Overall health with emoji markers (✓ pass, ⚠ warn, ✗ fail) | @@ -560,24 +464,6 @@ If Ollama is running but the configured embedding model has not been pulled, Dew This means you can run `dewey serve` or `dewey index` immediately after installing Dewey, even before pulling the embedding model. Dewey is fully functional for structured queries; semantic search becomes available once you run `ollama pull granite-embedding:30m`. -## Curated Knowledge Stores - -The `dewey curate` command synthesizes indexed content into structured knowledge articles, grouped by topic. Configure curation targets in `knowledge-stores.yaml`: - -```yaml -stores: - - tag: authentication - description: "Authentication patterns and decisions" - - tag: deployment - description: "Deployment procedures and configuration" -``` - -Run `dewey curate` to process all configured stores, or `dewey curate --store authentication` to curate a single topic. Curated articles receive the `curated` trust tier — ranking above raw `draft` content but below `validated` and `authored` content in search results. - -Background curation runs automatically during `dewey serve`, keeping curated articles current as new learnings and indexed content arrive. You can also trigger curation manually or from CI pipelines. - -When using Vertex AI as the synthesis provider, note that curation of large vaults may take several minutes — Vertex AI supports up to 16000 max output tokens per request with a 300-second timeout for large prompt processing. - ## Knowledge Lifecycle Dewey provides three commands that manage the quality and evolution of stored knowledge over time. @@ -612,20 +498,18 @@ Moves content between trust tiers — from draft to validated, or from validated ```bash # Promote a draft article to validated -dewey promote --id gotcha-20260502T143022-alice +dewey promote --id gotcha-003 ``` ## Trust Tiers -Dewey classifies all stored knowledge into five trust tiers. Tiers affect how content ranks in search results and allow agents to filter by quality level. +Dewey classifies all stored knowledge into three trust tiers. Tiers affect how content ranks in search results and allow agents to filter by quality level. -| Tier | Meaning | How Content Gets This Tier | -| -------------- | ----------------------------------- | ----------------------------------------------------------------------------- | -| **Authored** | Human-written content | Content created directly by humans (specs, READMEs, design docs) | -| **Curated** | Machine-synthesized, topic-grouped | Articles produced by `dewey curate` from configured knowledge stores | -| **Validated** | Machine-generated, human-reviewed | Content generated by agents and approved by a human via `dewey promote` | -| **Draft** | Machine-generated, not yet reviewed | Content stored by agents via `store_learning` or generated by `dewey compile` | -| **Untrusted** | External or unverified content | Content from sources configured with `trust_tier: untrusted` in `sources.yaml` | +| Tier | Meaning | How Content Gets This Tier | +| ------------- | ----------------------------------- | ----------------------------------------------------------------------------- | +| **Authored** | Human-written content | Content created directly by humans (specs, READMEs, design docs) | +| **Validated** | Machine-generated, human-reviewed | Content generated by agents and approved by a human via `dewey promote` | +| **Draft** | Machine-generated, not yet reviewed | Content stored by agents via `store_learning` or generated by `dewey compile` | Higher-tier content ranks above lower-tier content in search results. The `dewey_semantic_search_filtered` tool accepts a `tier` parameter, allowing agents to restrict searches to validated or authored content when reliability matters. @@ -643,9 +527,7 @@ Agents store learnings in Dewey using the `store_learning` MCP tool. Each learni ### Response -The tool returns a `{tag}-{YYYYMMDDTHHMMSS}-{author}` identity string (e.g., `gotcha-20260502T143022-alice`), which uniquely identifies the stored learning for future reference. The author component comes from the `DEWEY_AUTHOR` environment variable (defaults to the system username). - -> **Migration note**: Prior to v3.2.0, learning identities used a sequential format (`{tag}-{sequence}`, e.g., `gotcha-003`). Existing learnings in the old format are automatically re-ingested on startup — no manual migration is required. The old `tags` parameter is still accepted for backward compatibility. +The tool returns a `{tag}-{sequence}` identity string (e.g., `gotcha-003`), which uniquely identifies the stored learning for future reference. ### Search Result Metadata @@ -655,7 +537,7 @@ When retrieving learnings via `dewey_semantic_search` or `dewey_semantic_search_ | ------------ | -------------------------------------------------------- | | `created_at` | Timestamp when the learning was stored | | `category` | The learning's classification (if provided at storage) | -| `tier` | The trust tier of the content (authored/curated/validated/draft/untrusted) | +| `tier` | The trust tier of the content (authored/validated/draft) | Use the `tier` parameter on `dewey_semantic_search_filtered` to filter results by trust level — for example, restricting to `authored` or `validated` content when making critical decisions. diff --git a/content/docs/getting-started/multi-platform.md b/content/docs/getting-started/multi-platform.md index 4f25622..c62d8f2 100644 --- a/content/docs/getting-started/multi-platform.md +++ b/content/docs/getting-started/multi-platform.md @@ -42,7 +42,7 @@ The `.opencode/` directory receives: - **MCP server configuration** -- entries for Dewey (knowledge retrieval) and Replicator (multi-agent coordination) in `opencode.json` - **Convention packs** -- numbered, severity-classified coding rules in `.opencode/uf/packs/` (e.g., `default.md`, `go.md`, `content.md` plus user-owned `*-custom.md` variants) - **Agent definitions** -- Divisor review personas, Cobalt-Crush, Constitution Check, and other hero agents -- **Commands** -- Speckit pipeline commands (`/speckit.specify`, `/uf.unleash`, `/uf.finale`, etc.) +- **Commands** -- Speckit pipeline commands (`/speckit.specify`, `/unleash`, `/finale`, etc.) See the [Developer Guide](/docs/getting-started/developer/#project-scaffolding-with-uf-init) for the full list of deployed files and the file ownership model. diff --git a/content/docs/getting-started/product-owner.md b/content/docs/getting-started/product-owner.md index aef7de8..61fd61b 100644 --- a/content/docs/getting-started/product-owner.md +++ b/content/docs/getting-started/product-owner.md @@ -65,7 +65,7 @@ Good seeds are specific enough to convey intent but don't need to be detailed: - "Refactor the webhook handler to support configurable retry logic with exponential backoff" - "Create a getting-started guide for new contributors to the website project" -The swarm handles everything from here -- specification, planning, implementation, testing, and review -- pausing only at the accept stage for your decision. Developers can run the full pipeline with [`/uf.unleash`](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash), which orchestrates all stages autonomously and exits when human judgment is needed. +The swarm handles everything from here -- specification, planning, implementation, testing, and review -- pausing only at the accept stage for your decision. Developers can run the full pipeline with [`/unleash`](/docs/getting-started/common-workflows/#autonomous-pipeline-unleash), which orchestrates all stages autonomously and exits when human judgment is needed. To seed a feature, use the `/workflow seed` command: diff --git a/content/docs/getting-started/quality-gates.md b/content/docs/getting-started/quality-gates.md index 882ee85..d0e156e 100644 --- a/content/docs/getting-started/quality-gates.md +++ b/content/docs/getting-started/quality-gates.md @@ -30,7 +30,7 @@ For Go projects, the CI layer typically includes: - `govulncheck ./...` — known vulnerability scanning - OSV-Scanner and Trivy — dependency vulnerability scanning -CI is a soft gate with causality analysis. When a check fails, the pipeline determines whether the failure is *new* (introduced by your branch) or *pre-existing* (already broken on `main`). New failures block the pipeline — no amount of reasoning or justification overrides a new regression. Pre-existing failures are reported as informational findings but do not block, preventing inherited CI debt from stalling your work. This is the foundational layer that all other quality checks build on. +CI is a hard gate. If any check fails, the pipeline stops. No amount of reasoning or justification overrides a failing test. This is the foundational layer that all other quality checks build on. The CI commands are not hardcoded — they are derived from `.github/workflows/` files, which are the source of truth. Agents read the workflow files to determine exactly which checks to run locally before declaring a task complete (the CI Parity Gate). diff --git a/content/docs/getting-started/quick-start.md b/content/docs/getting-started/quick-start.md index 1cd7db7..ad26062 100644 --- a/content/docs/getting-started/quick-start.md +++ b/content/docs/getting-started/quick-start.md @@ -49,11 +49,11 @@ Start in plan mode to explore your idea, then switch to build mode: ```text /speckit.specify # describe what you want to build -/uf.unleash # the swarm takes it from here -/uf.finale # commit, push, create PR +/unleash # the swarm takes it from here +/finale # commit, push, create PR ``` -`/uf.unleash` runs the entire pipeline autonomously: clarify, plan, implement, test, and review. It pauses when it needs you and resumes where it left off. See the [blog post](/blog/unleash-in-practice/) for a walkthrough. +`/unleash` runs the entire pipeline autonomously: clarify, plan, implement, test, and review. It pauses when it needs you and resumes where it left off. See the [blog post](/blog/unleash-in-practice/) for a walkthrough. ### Small Tasks @@ -61,8 +61,8 @@ For bug fixes and tactical changes: ```text /opsx-propose fix-the-bug # create proposal + design + tasks -/uf.cobalt-crush # implement with convention pack adherence -/uf.finale # commit, push, create PR +/cobalt-crush # implement with convention pack adherence +/finale # commit, push, create PR ``` ## The Stack diff --git a/content/docs/getting-started/tester.md b/content/docs/getting-started/tester.md index 18ce682..65ebf12 100644 --- a/content/docs/getting-started/tester.md +++ b/content/docs/getting-started/tester.md @@ -102,7 +102,7 @@ Gaze is stage 3 (validate) in the [hero lifecycle](/docs/getting-started/common- As a tester, you can invoke the review council to get a comprehensive code review: ``` -/uf.review-council +/review-council ``` The council launches 6 Divisor personas in parallel. The **Testing persona** is particularly relevant -- it evaluates: diff --git a/content/docs/projects/dewey.md b/content/docs/projects/dewey.md index bf3f70a..3de34fa 100644 --- a/content/docs/projects/dewey.md +++ b/content/docs/projects/dewey.md @@ -14,7 +14,7 @@ AI agents make better decisions when they have better context. Dewey is an MCP s A search for "authentication timeout" finds an issue titled "login session expiry" because Dewey understands meaning, not just keywords. Agents start with a vague concept and refine their understanding through structured navigation, discovering related specifications, past decisions, and connected documentation they did not know to ask for. -Dewey is a hard fork of [graphthulhu](https://github.com/skridlevsky/graphthulhu), building on its knowledge graph foundation and adding persistent storage, semantic search, and pluggable content sources. Dewey now provides 50 MCP tools across 12 categories. +Dewey is a hard fork of [graphthulhu](https://github.com/skridlevsky/graphthulhu), building on its knowledge graph foundation and adding persistent storage, semantic search, and pluggable content sources. Dewey now provides 48 MCP tools across 12 categories. ## Installation @@ -34,6 +34,7 @@ sudo dnf install ./dewey__linux_amd64.rpm ``` RPM packages are available for both `amd64` and `arm64` architectures. The binary installs to `/usr/bin/dewey`. + Or install from source: ```bash @@ -42,9 +43,9 @@ go install github.com/unbound-force/dewey/v3@latest ## Key Features -### 50 MCP Tools Across 12 Categories +### 48 MCP Tools Across 12 Categories -Dewey exposes 50 MCP tools for navigate, search, analyze, write, decision, journal, flashcard, whiteboard, semantic search, health, knowledge management, and learning. Agents use these tools through the standard MCP protocol — no custom integrations required. +Dewey exposes 48 MCP tools for navigate, search, analyze, write, decision, journal, flashcard, whiteboard, semantic search, health, knowledge management, and learning. Agents use these tools through the standard MCP protocol — no custom integrations required. ### Semantic Search @@ -57,26 +58,14 @@ Vector-based similarity search using IBM Granite embeddings (30M parameters, 63 - **Web crawl** — indexes documentation from toolstack websites with robots.txt compliance and local caching - **Code** — Go AST parsing to extract function signatures, CLI commands, MCP tool registrations, and package documentation from Go source files -### Pluggable Embedding and Synthesis Providers - -Dewey supports multiple AI providers for both embedding and synthesis operations. Choose between Ollama (local, privacy-preserving) and Vertex AI (cloud, Google Cloud Platform) depending on your requirements. Provider configuration is per-vault in `config.yaml`, with a global configuration fallback at `~/.config/dewey/config.yaml`. See the [getting-started guide](/docs/getting-started/knowledge/) for setup instructions. - ### Persistent SQLite Index Indexes persist to `.uf/dewey/graph.db` across sessions. Subsequent startups load from the persistent index and only re-process changed files — startup is near-instant after the first index. -### Content Sanitization - -When indexing content from untrusted sources, Dewey applies a 4-layer sanitization pipeline: injection pattern scanning, content hash drift detection, Markdown structure validation, and size anomaly detection. Each content source can be configured with a `sanitize_mode` (warn, strict, or off) and `trust_tier` in `sources.yaml`. Findings are surfaced by `dewey doctor` and `dewey lint`. - ### Graceful Degradation Dewey is an enhancement, not a requirement. Every hero in the swarm functions without Dewey, falling back to direct file reads. Semantic search requires Ollama; structured graph queries work without it. -### Curated Knowledge Stores - -The `dewey curate` command synthesizes indexed content into structured knowledge articles. Configure knowledge stores in `knowledge-stores.yaml` to define which topics to curate, and Dewey produces focused articles ranked at the `curated` trust tier — higher than raw indexed content but below human-validated knowledge. Background curation runs automatically during `dewey serve`, keeping curated articles current as new content arrives. - ### Knowledge Lifecycle Dewey does not just store knowledge — it actively curates it. Three commands manage the lifecycle of stored learnings: @@ -101,7 +90,7 @@ Dewey runs as an MCP server alongside your AI coding environment. It combines: - **Knowledge graph** — in-memory graph built from Markdown files with wikilink, tag, and property relationships - **SQLite persistence** — pages, blocks, links, and embeddings stored in `.uf/dewey/graph.db` -- **Pluggable embedding providers** — IBM Granite model generates vector embeddings for semantic similarity search. Dewey supports both Ollama (local, privacy-preserving) and Vertex AI (cloud) as embedding and synthesis providers +- **Ollama embeddings** — IBM Granite model generates vector embeddings for semantic similarity search. Dewey reads the standard `OLLAMA_HOST` environment variable, so it automatically connects to the same Ollama instance as other tools in your workflow - **Pluggable sources** — content source interface supports disk, GitHub, web crawl, and code with configurable refresh intervals ## Learn More diff --git a/content/docs/roadmap/_index.md b/content/docs/roadmap/_index.md deleted file mode 100644 index 42e5d50..0000000 --- a/content/docs/roadmap/_index.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: "Roadmap" -description: "The Unbound Force roadmap — capability horizons from headless autonomy and the factory foundation through trust at scale to factory-to-factory operation." -lead: "Organized into capability horizons — Now, Next, and Later — shaped by model improvements, upstream dependencies, and community demand." -date: 2026-01-01T00:00:00+00:00 -draft: false -weight: 6 -toc: true ---- - -This roadmap is organized into capability horizons — Now, Next, and Later — rather than calendar dates. The work is shaped by model improvements, upstream dependencies, and community demand, all of which shift faster than quarterly plans can track. Where the phasing roughly maps to calendar time, it aligns with: Now ≈ Q4 2026, Next ≈ H1 2027, Later ≈ H2 2027 and beyond. - -For the vision and principles that drive this roadmap, see [Vision](/docs/vision/). - ---- - -## Where We Are Today - -An honest snapshot of strengths and gaps, scored against the factory pattern described in the vision. - -**Strong.** SDLC acceleration is the system's best area. The spec-driven pipeline (Speckit/OpenSpec), the 8-phase `/uf.unleash` workflow, the Divisor review council, Gaze test-quality measurement, convention packs, and the constitution governance model are all operational and battle-tested across multiple repositories and contributors. - -**Operational.** Phase 1 (human-fronted factories) and Phase 2 (agentic review participation) of the trust ladder are working today. Agents produce specs, implement code, and post formal PR reviews. Humans make every merge decision. The `council-review-action` GitHub Action runs Divisor reviews in CI on real pull requests. - -**Partial.** Setup and operations (distribution is solid via Homebrew/RPM/go install/containers, but first-run onboarding has friction). Governance and compliance (convention packs are strong, but design-level and architectural-level metrics are only now emerging via vibe-check). Cost and FinOps (no native cost tracking — this is infrastructure-layer work that FullSend provides). Interrupt-centric metrics (the OTEL substrate exists but is not fully instrumented). - -**Gap.** The eval harness is the largest gap. Gaze measures code and test quality. Vibe-check measures design quality. Neither measures whether agent *output* satisfies *success criteria* — the end-to-end evaluation loop that the factory pattern demands. This is the single most important capability to build. Cross-repo factory-to-factory operation does not exist yet; forge is single-repo. Vertical/platform accelerators are absent and demand-driven. - ---- - -## Horizon 1 — Now: Headless Autonomy and the Factory Foundation - -The immediate work establishes Unbound Force as a headless, autonomous agent layer that runs inside infrastructure platforms without losing any of its local capabilities. This is the foundation that every later horizon depends on. - -### FullSend BYOA Integration - -The defining work of this horizon is running the full Unbound Force swarm inside FullSend's Bring Your Own Agent containers with complete local/FullSend parity — the same `.opencode/` directory, the same constitution, the same slash commands, the same convention packs. Not a degraded skill-based shim; full parity. - -This follows a five-increment progression, each building trust before the next adds capability: - -**Increment 1 — uf-review (read-only).** Prove that the Divisor review council runs headless inside a FullSend sandbox. OpenCode runs via `opencode run --format json`, emitting ndjson events that the FullSend runtime consumes. The agent reads code, posts structured review findings, and exits. No writes. This is the go/no-go gate — if OpenCode cannot run headless in the sandbox, the entire approach is blocked. ([#509](https://github.com/unbound-force/unbound-force/issues/509)) - -**Increment 2 — uf-address-feedback (async Q&A + resume).** Add the ability for agents to pause, ask questions via GitHub comments, and resume when a human answers. This replaces blocking interactive prompts with an async `status:needs_input` / `/uf.answer` pattern that works in unattended environments. ([#513](https://github.com/unbound-force/unbound-force/issues/513)) - -**Increment 3 — uf-specify + `uf gate` (first writes, with security).** The agent creates specification artifacts — proposals, designs, task breakdowns — and enforces spec-first via `uf gate`, a deterministic pre-commit hook that cannot be bypassed by the model because it is not a prompt instruction. This increment requires closing the narrow security-hook gap in OpenCode's before-hook (structured block channel, not throw-only). Security is a prerequisite, not a follow-up. ([#514](https://github.com/unbound-force/unbound-force/issues/514), [#515](https://github.com/unbound-force/unbound-force/issues/515)) - -**Increment 4 — uf-code (source writing).** Cobalt-Crush implements approved specifications inside the sandbox. The full write path: branch, implement against the spec, run tests, commit. This is where the agent goes from reading and reviewing to producing code — the transition from Phase 2 to the operational core of Phase 1 at scale. - -**Increment 5 — uf-forge (multi-agent parallelism).** Multiple agents operate in a single sandbox via OpenCode's sub-agent delegation. Parallel worktree execution with cherry-pick merge. This is the foundation for machine-speed throughput within a single repository. - -**Upstream contributions.** The approach is upstream-first: contribute `OpenCodeRuntime` to `fullsend-ai/fullsend` (no fork), publish a digest-pinned `ghcr.io/unbound-force/fullsend-opencode` container image, and onboard the unbound-force org's own repos into FullSend. The `pi` runtime — shipped as the second non-Claude runtime — proves this is a days-scale contribution effort and serves as the template. ([#510](https://github.com/unbound-force/unbound-force/issues/510), [#511](https://github.com/unbound-force/unbound-force/issues/511), [#519](https://github.com/unbound-force/unbound-force/issues/519)) - -### Spec-First Enforcement - -`uf gate` is a new headless subcommand that enforces the spec-first constraint deterministically. It runs as a `validation_loop.script` in FullSend and as a pre-commit hook locally. The model cannot bypass it because it operates outside the model's control surface — it checks whether spec artifacts exist and are committed before allowing implementation files to be written. This is the mechanism that makes the factory pattern's "specs before code" property structural rather than aspirational. ([#514](https://github.com/unbound-force/unbound-force/issues/514)) - -### Vibe-Check GA - -Vibe-check reaches general availability as an independent project measuring design and architectural quality. The universal metrics model is complete — Instability, Abstractness, Distance from main sequence, LCOM, zone classification — with a cross-language adapter architecture (JSON-RPC 2.0 over stdin/stdout). The remaining work: the Entropy Sentinel agent for Boy Scout enforcement (structural delta tracking base-vs-PR), the architectural design convention pack (AD-001 through AD-010), and the `/vibe-check` reporter command. Vibe-check deploys into consuming repos via `vibe-check init`, the same scaffolding pattern as `uf init`. - -### Gaze Multi-Language Backends - -Gaze's test-quality measurement — CRAP scores, contract coverage, side-effect classification — extends beyond Go to Python and TypeScript/JavaScript through dedicated backend projects: - -- **Snake-eyes** (Python): JSON-RPC server implementing the Gaze analyzer protocol. Taxonomy of 48 side-effect types, side-effect detection, complexity scoring, coverage analysis, classification signal extraction, and test mapping pipeline. -- **Reading-stone** (TypeScript): The same protocol, adapted for TypeScript and JavaScript codebases. - -Both backends communicate with the Gaze frontend via the same JSON-RPC interface, producing metrics that are directly comparable across languages — a requirement of Constitution Principle III (Observable Quality: metrics MUST be comparable across runs). - -### Vibe-Check Multi-Language Backends - -Vibe-check's design and architectural metrics — instability, abstractness, distance from the main sequence, cohesion, and circular-dependency detection — extend across languages through the same universal-model adapter architecture the completed metrics package defines (JSON-RPC 2.0 over stdin/stdout). The frontend stays language-agnostic; each backend implements the analyzer protocol for one language: - -- **Go** (native): `vibe-check analyze` computes package-level coupling metrics directly. ([vibe-check#2](https://github.com/zero-dot-force/vibe-check/issues/2)) -- **rattler** (Python): a coupling adapter bringing the same Martin-metrics analysis to Python codebases. ([vibe-check#9](https://github.com/zero-dot-force/vibe-check/issues/9)) -- **TypeScript/JavaScript**: a coupling adapter over the same protocol, planned alongside the other cross-language work. ([vibe-check#14](https://github.com/zero-dot-force/vibe-check/issues/14)) - -As with Gaze, every backend produces metrics directly comparable across languages — the universal model guarantees an identical unit of analysis (the module) and identical metric definitions regardless of source language, satisfying Constitution Principle III. This is the design-quality counterpart to Gaze's test-quality backends: one measures whether tests verify contractual behavior, the other whether the architecture stays on the main sequence, and both speak the same adapter protocol so a polyglot repository gets consistent measurement from a single toolchain. - -### Inherited Infrastructure Capabilities - -By adopting FullSend as the infrastructure layer, several previously-gapped capabilities close without Unbound Force building them: - -- **Cost and FinOps** — FullSend's `RunMetrics` tracks `TotalCostUSD`, token counts, and OTEL telemetry per run. Unbound Force inherits this by running inside the platform. -- **Provenance and attribution** — FullSend's `TranscriptHandler` records model identity, tool invocations, fetch audit trails, and trace IDs. Every agent action is attributable. -- **Sandbox security** — FullSend owns env sanitization, OpenShell/landlock containment, network isolation, and prompt-injection hardening. Unbound Force's agents operate inside these controls rather than reimplementing them. - -This is the boundary thesis in practice: the agent layer focuses on what it differentiates on; the infrastructure layer provides everything else. - ---- - -## Horizon 2 — Next: Trust and Governance at Scale - -With the factory foundation operational, the next horizon builds the governance, measurement, and interoperability capabilities that allow organizations to extend trust — moving from "agents produce code that humans review" toward "agents produce evidence that justifies trust." - -### Eval Harness - -The largest gap in the current system. Gaze measures whether tests are good. Vibe-check measures whether design is sound. Neither measures whether agent *output* satisfies the *success criteria* that motivated the work. - -The eval harness closes this loop. Given a specification and an agent's implementation, the harness evaluates whether the implementation fulfills the spec — not just whether it compiles and passes tests, but whether it achieves the stated objectives. This is the cross-cutting capability that the factory pattern demands most urgently. A concrete first instance: the review council validating that a PR addresses the originating issue's acceptance criteria — the output-side mirror of intake-kit's input-side validation. ([#563](https://github.com/unbound-force/unbound-force/issues/563)) - -Evaluation spans two complementary layers that share infrastructure — the same headless driver, rubric-based LLM judge, and comparable-results store: - -- **Output eval** (the loop above) — does an implementation satisfy its spec's success criteria? The design draws on FullSend's `validation_loop` and the `agent-eval-harness` pattern (ADR 0051 upstream), with cross-model evaluation — the same task judged by different models — to reduce single-model bias. -- **Command and harness-quality eval** — do the commands, agents, and skills the project ships perform well, and have they regressed? The `eval-infra` proposal defines a `unbound-force/eval-infra` repository: a reusable GitHub Actions workflow any repo can call, a TypeScript SDK driver that runs OpenCode headlessly and can answer the interactive `AskUserQuestion` prompts that pervade multi-phase commands (the gap that off-the-shelf harnesses hit), a fixture format, and a persistent `runs.db` tracking token cost and output quality over time. Configuration profiles measure whether an efficiency change saves money without degrading output. ([Discussion #399](https://github.com/orgs/unbound-force/discussions/399)) - -### Security Hooks for Write-Capable Agents - -OpenCode's permission system is documented as "a UX feature, not a security boundary." Headless mode grants all permissions by default. For read-only operations (Increment 1), this is acceptable — FullSend's sandbox provides compensating controls. For write-capable agents (Increments 3+), the narrow gap must close: OpenCode's `tool.execute.before` hook needs a structured block channel (not throw-only) so that policy decisions can be communicated back to the runtime rather than simply aborting the operation. - -This is the prerequisite for safely running spec-writing and code-writing agents in unattended environments. The fix is narrow and well-understood; the upstream coordination is the harder part. - -### Design-Quality Gates - -Vibe-check's metrics become CI-enforced quality gates: - -- **Entropy Sentinel** — a Divisor agent (`divisor-entropy`) that computes structural deltas between base and PR branches. If a PR increases coupling, reduces cohesion, or introduces circular dependencies, the sentinel reports it with quantified evidence. Not a subjective "this feels coupled" — a measured change in Ce, I, or D metrics. -- **Pre-change CRAP gate** — before modifying a function, Gaze checks whether its existing CRAP score exceeds the threshold. If it does, the function must be improved (tests added, complexity reduced) before new changes are applied. The Boy Scout rule, enforced by measurement. -- **Architectural design convention pack** (AD-001 through AD-010) — rules with concrete thresholds: cognitive complexity < 15, efferent coupling < 10, instability < 0.7, no circular dependencies, files < 400 lines. Consumed by both Cobalt-Crush (when writing) and Divisor (when reviewing), ensuring the same standards apply to production and review. -- **Package regression in CI** — track coupling and cohesion metrics across builds. A PR that causes package-level regression fails CI. This makes design quality a ratchet, not a snapshot. -- **Architectural drift tracking** — Dewey stores time-series coupling and cohesion data. A trend agent monitors for gradual drift — the kind that no single PR causes but that accumulates over months. This is mandated by Constitution Principle III: metrics must be comparable across runs, which implies they must be tracked over time. - -### Curated Knowledge Stores - -Dewey's current knowledge layer is manual (`store_learning`) and ephemeral (SQLite-only). Curated knowledge stores replace this with a persistent, file-backed system: - -- **Config-driven extraction** — map sources (meetings, Slack, GitHub issues) to knowledge stores via configuration. LLMs extract decisions, facts, patterns, and references automatically. -- **Source tracing** — every extracted fact links back to its source document, block, and timestamp. Full provenance, auditable in git. -- **Multi-source aggregation** — knowledge compounds across sources. A decision made in a meeting, referenced in a Slack thread, and formalized in a GitHub issue converges into a single, attributed knowledge article. -- **Quality scoring** — confidence levels (high/medium/low/flagged) and quality flags (missing rationale, implied dependency, contradiction, stale reference, scope conflict). `dewey lint` surfaces knowledge quality problems. -- **Git-backed persistence** — knowledge stores are markdown files in the repository. They are versioned, diffable, reviewable, and mergeable. No external database required for the canonical store. - -This extends Dewey from a session-scoped tool into an organizational memory that improves with every interaction. ([Discussion #114](https://github.com/orgs/unbound-force/discussions/114)) - -### Pluggable VCS and Ticketing - -Unbound Force is currently GitHub-only — Issues, PRs, Actions, the `gh` CLI. Real-world adoption requires: - -- **GitLab support** — Merge Requests instead of Pull Requests, GitLab CI instead of GitHub Actions, the Files API for knowledge store operations. -- **Jira integration** — stories-as-Jira-tickets alongside stories-as-GitHub-Issues, for organizations where project management lives in Jira. - -The architecture already supports this in principle: convention packs, agents, and the constitution are VCS-agnostic markdown files. The coupling is in the CLI commands and workflow scripts that assume GitHub. Pluggable backends for VCS operations and ticketing operations make the agent layer portable across platforms. - -### The Three-Layer Intake Ecosystem - -The long-term architecture for requirements flowing into Unbound Force is a three-layer system: - -1. **Domain Intake** — intake-kit provides CUE-validated PRD authoring with a 5-specialist review council (Guard, Adversary, Tester, Operator, Curator) that gates requirements on testability, completeness, and security before any code is written. Domain-specific convention packs (e.g., `spog.md`) extend the intake layer for particular products without modifying the core agent layer. This forms the input side of a symmetric two-council architecture: intake-kit validates requirements in; the Divisor review council validates implementations out. -2. **SDD Bridge** — OpenSpec and Speckit translate domain requirements into stories (GitHub Issues) and capability-level specs. The complytime RFC defines the long-term bridge: a PRD+ADR-to-task adapter folded into `/unleash`, run per story under ADR constraints, with spec/task artifacts as disposable scaffolding. The GitHub Issue — carrying FR/AC IDs from the PRD — is the durable anchor that connects the intake council's input validation to the review council's output validation. -3. **Execution Engine** — `/uf.unleash` through `/uf.finale`: the agent pipeline that produces and validates code from specs. - -Each layer is independently valuable. The bridge makes them composable. The adapter pattern ensures domain intake tooling does not need to know about Unbound Force's internals — it produces structured requirements; the bridge translates them; the engine executes them. - -### RFE-to-STRAT Front-End - -The pipeline has a gap at the very beginning: the path from a raw request-for-enhancement to a strategic decision to pursue it. Today, this is informal — someone writes an issue, it gets discussed, work starts. The front-end formalizes the intake: structured RFE capture, strategic prioritization, and routing into the SDD bridge. - -Intake-kit already provides the core authoring and review machinery (CUE-validated PRDs with a 5-specialist review council). The complytime RFC defines the workflow spine: PRD → ADR → AAC Review → Story (GitHub Issue) → OpenSpec. The remaining work is the strategic prioritization layer — the rules and tooling that help organizations decide *which* validated requirements to pursue and in what order — and tighter integration between intake-kit's output and the SDD bridge's input. - -This is uf's domain and differentiator — the part of the pipeline that no infrastructure platform provides. - -### Asynchronous Agent Coordination and Typed Guardrails - -Today the swarm executes a feedforward, spec-driven plan (`tasks.md`) through phase-gated stages. This is effective for well-specified work, but for long-horizon tasks the rigidity becomes a liability: an agent that discovers mid-execution that its plan is invalid — a wrong dependency assumption, a violated ADR, a compliance conflict — is trapped until the next phase boundary. Because standard MCP tool calls are synchronous, an agent cannot work and listen for lateral updates at the same time. The costs are wasted compute, no passive awareness, and flat escalation — no way to distinguish a bug the swarm should fix itself from an architectural flaw it must not touch. - -Asynchronous coordination decouples listening from the model's context window. Replicator gains a pub/sub message broker; an OpenCode background-listener custom tool connects to it, returns immediately so the agent keeps working, and injects lateral messages back into the session as system notifications via the OpenCode SDK. Coordination messages are strongly typed rather than free text — which is what turns real-time messaging into governance: - -- **`IMPLEMENTATION_DEVIATION`** — the swarm self-heals: force an interrupt, discard the invalidated `tasks.md`, and trigger an `/opsx-repropose` loop, no human needed. -- **`GOVERNANCE_BLOCKER`** — the swarm halts: if the flaw is in the specification itself (an ADR with an impossible constraint), stop the `/uf.unleash` loop and escalate to a human architect. Agents may rewrite implementations but never overrule architecture. - -This gives the execution engine mid-flight agility and autonomous recovery while keeping architectural authority with humans — attention governance encoded in the message type system. It is also the foundation the next horizon builds on: the same typed-interruption substrate, extended across repository boundaries, is what makes factory-to-factory coordination safe. ([Discussion #444](https://github.com/orgs/unbound-force/discussions/444)) - ---- - -## Horizon 3 — Later: Factory-to-Factory - -The final horizon is where the factory pattern reaches its full expression: multiple autonomous factory instances operating across repositories at machine speed, with humans setting policy and handling escalations. - -### Cross-Repo Forge - -Today, `/uf.forge` orchestrates multi-agent parallelism within a single repository. Cross-repo forge extends this to multi-repository coordination: one factory identifies an integration issue in a dependency, dispatches a signal, and another factory produces and validates a fix. - -This requires solving several hard problems: cross-repo artifact routing, dependency-aware dispatch (a change in library A triggers re-validation in services B and C), and merge coordination across repositories with different owners and policies. It builds directly on the asynchronous coordination and typed guardrails established in Horizon 2 — extending the same self-correction and escalation substrate across repository boundaries — but the cross-repo topology itself is new. - -### Machine-Speed Loops - -When factories operate across repositories, the loop from "issue identified" to "fix validated" can run faster than human review cadence. This does not mean removing humans from the loop — it means changing what humans review. Instead of reviewing individual PRs, humans review *policies* (convention packs, constitution amendments, approval thresholds) and *outcomes* (trend dashboards, eval harness results, architectural drift reports). - -The infrastructure for this is partially in place: OTEL telemetry, structured review output, provenance recording. What is missing is the policy layer — the rules that determine which outcomes require human attention and which can be auto-approved based on accumulated trust evidence. - -### Tiered Approvals and Embargo Controls - -Not all changes carry the same risk. A documentation fix and a security-sensitive API change should not go through the same approval process. Tiered approvals classify changes by risk and route them accordingly: - -- **Low risk** (documentation, test additions, low-complexity refactors) — auto-approvable if CI passes and eval harness confirms spec satisfaction. -- **Medium risk** (feature implementation, dependency updates) — agent review + one human approval. -- **High risk** (security changes, public API modifications, dependency additions) — full Divisor council review + multiple human approvals. -- **Embargo** — changes that affect unreleased features or IP-sensitive code require additional controls: restricted visibility, mandatory legal/compliance review, time-locked merge windows. - -This is a shared frontier across the industry. No system has mature tiered approval for AI-generated code. The design will draw on whatever emerges as best practice, anchored by the constitution's Security by Default principle. - -### Vertical and Platform Accelerators - -Domain-specific convention packs and agent configurations for particular technology stacks, compliance frameworks, or industry verticals. These are demand-driven — built when specific communities need them, not speculatively. Examples might include: - -- A compliance-focused pack for FedRAMP/FISMA requirements -- A platform-specific pack for Kubernetes operator development -- An industry-specific pack for financial services regulatory constraints - -The convention pack architecture already supports this. The work is in writing, testing, and maintaining domain-specific rules — which requires domain expertise from the communities that need them. - ---- - -## The Throughline: The Harness Shrinks - -Across all three horizons, a single discipline runs as a cross-cutting concern: the harness should get lighter over time. - -Every component is a bet on a model limitation. As models improve, some bets expire. The pruning methodology is simple: after each model upgrade, run the same task with and without each harness component. Measure quality. Delete what does not contribute. Crucially, this measurement is automated rather than manual — the command and harness-quality eval layer (`eval-infra`, above) produces comparable token-cost and quality data across runs, so each pruning experiment yields evidence instead of an impression. - -Concrete experiments that should be run periodically: - -- Run with fewer Divisor agents (3 instead of 5, or even 1 with computational-only validation) -- Simplify agent persona instructions from multi-page documents to single paragraphs -- Skip the Gaze feedback loop for a sprint and measure whether quality degrades -- Remove Dewey knowledge retrieval from agent initialization and compare output -- Reduce the 3-iteration review cap to 2 or 1 -- Test whether explicit ownership boundaries between review agents are still necessary - -If quality holds in any of these experiments, that component has outlived its usefulness and should be removed. The goal is not to preserve the current architecture — it is to preserve the outcomes the architecture produces, with the minimum scaffolding necessary. - -The system at its best is invisible. The specification is clear, the implementation is correct, the tests verify contractual behavior, the design is structurally sound, and the harness that made it happen is as light as it can possibly be. That is the destination. The roadmap is how we get there. diff --git a/content/docs/team/dewey.md b/content/docs/team/dewey.md index 46d53ef..2e70f59 100644 --- a/content/docs/team/dewey.md +++ b/content/docs/team/dewey.md @@ -32,7 +32,7 @@ Existing agent configurations that use graphthulhu can migrate to Dewey by chang ## Query Capabilities -Dewey exposes 50 MCP tools across 12 categories. For knowledge retrieval, agents primarily use 9 query tools across two search modes. +Dewey exposes 48 MCP tools across 12 categories. For knowledge retrieval, agents primarily use 9 query tools across two search modes. ### Structured Queries @@ -61,13 +61,11 @@ New in Dewey, these tools use vector embeddings for conceptual similarity: New in Dewey v3.0.0, these tools manage the knowledge lifecycle: -| Tool | What It Does | -| ---------------- | -------------------------------------------------------------------------------------------- | -| `compile` | Cluster stored learnings by topic and synthesize them into current-state articles via LLM | -| `curate` | Synthesize indexed content into compiled knowledge articles for configured knowledge stores | -| `lint` | Detect quality issues: stale decisions, uncompiled learnings, embedding gaps, contradictions | -| `promote` | Move content between trust tiers (draft to validated to authored) after human review | -| `store_compiled` | Persist a compiled article synthesized by an agent, with provenance tracking and embeddings | +| Tool | What It Does | +| --------- | -------------------------------------------------------------------------------------------- | +| `compile` | Cluster stored learnings by topic and synthesize them into current-state articles via LLM | +| `lint` | Detect quality issues: stale decisions, uncompiled learnings, embedding gaps, contradictions | +| `promote` | Move content between trust tiers (draft to validated to authored) after human review | ### Learning @@ -125,9 +123,7 @@ Dewey uses [IBM Granite Embedding](https://www.ibm.com/granite/docs/models/embed Enterprise licensing provenance matters. Granite's training data is fully disclosed and permissibly licensed — there are no questions about whether the model was trained on proprietary or restricted content. This is a deliberate choice for organizations where licensing provenance is a compliance requirement. -The embedding model is configurable. Dewey supports pluggable providers — **Ollama** for local execution and **Vertex AI** for cloud-hosted inference. While Granite via Ollama is the recommended default, teams can swap to any compatible embedding model. See the [provider configuration guide](/docs/getting-started/knowledge/#provider-configuration) for setup details. - -To configure the default Ollama provider, edit `.uf/dewey/config.yaml`: +The embedding model is configurable. While Granite is the recommended default, teams can swap to any Ollama-compatible embedding model by editing `.uf/dewey/config.yaml`: ```yaml embedding: diff --git a/content/docs/vision/_index.md b/content/docs/vision/_index.md deleted file mode 100644 index f3abaa7..0000000 --- a/content/docs/vision/_index.md +++ /dev/null @@ -1,125 +0,0 @@ ---- -title: "Vision" -description: "The Unbound Force vision — why the industry is shifting from co-pilot to factory, and how a spec-driven AI agent swarm makes that transition real." -lead: "Unbound Force is built for the world where engineers write specifications and agents produce implementations." -date: 2026-01-01T00:00:00+00:00 -draft: false -weight: 5 -toc: true ---- - -## The Shift - -The industry is moving from co-pilot to factory. - -In the co-pilot model, an engineer writes code while an AI assistant fills in the gaps — autocomplete, boilerplate generation, question answering. The human is in the loop for every decision. The AI accelerates individual tasks but does not change the shape of the work. - -In the factory model, the relationship inverts. Engineers write specifications. Agents produce implementations. The embodiment — the generated code itself — is disposable. If it does not pass quality gates, the agent regenerates it. Engineers stop fixing code and start fixing the agents and specs that produce the code. The human moves from in-the-loop to on-the-loop: setting direction, reviewing outcomes, and intervening only when the system cannot resolve a problem on its own. - -This is not a speculative future. It is the structural shift that every team building production-grade agent systems is converging toward. As Steven Huels articulated: *"Open source communities will increasingly differentiate not on code, but on quality of specs, strength of evals, strong governance and the interoperability of systems."* - -Unbound Force is built for that world. - -## What Unbound Force Is - -Unbound Force is a spec-driven AI agent swarm for software engineering. It is a composable toolkit — CLI-native, local-first, Apache-2.0 licensed — that gives AI coding agents the structure they lack on their own. - -The swarm is organized around hero personas, each with a distinct role: - -- **Cobalt-Crush** — the Developer. Implements approved specifications, follows convention packs, produces tested code. -- **Gaze** — the Quality Sentinel. Measures test quality through CRAP scores, contract coverage, and side-effect classification. Does not measure whether code "looks good" — measures whether tests verify the contractual behavior of the code they exercise. -- **The Divisor** — the Review Council. A panel of specialized reviewers (Guard, Architect, Adversary, SRE, Testing, Curator, Scribe, Herald, Envoy) that evaluate pull requests from orthogonal quality dimensions in parallel. - -Requirements intake is handled by **intake-kit** — a CUE-validated PRD authoring and review system with its own 5-specialist council (Guard, Adversary, Tester, Operator, Curator) that validates requirements are well-formed, testable, and unambiguous before any code is written. This creates a symmetric two-council architecture: intake-kit validates inputs, the Divisor validates outputs, with the GitHub Issue as the durable anchor between them. - -These personas and tools scaffold into any repository via `uf init`, deploying agents, commands, skills, and convention packs into the consuming project's `.opencode/` directory. Each tool — `uf`, `gaze`, `dewey`, `replicator`, `vibe-check`, `intake-kit` — is independently installable and useful on its own. Combining them produces additive value without mandatory dependencies. - -**OpenCode-first.** Unbound Force is designed and tested to operate with [OpenCode](https://opencode.ai/). The commands, skills, agents, and scaffolding assume OpenCode's tool system, sub-agent delegation, and headless execution model. While the underlying concepts — convention packs, constitutions, spec-driven workflows — are agent-runtime agnostic, using UF with other coding agents (Claude Code, Cursor, etc.) is not officially supported and may require significant adaptation work. This alignment is deliberate: deep integration with one runtime produces better outcomes than shallow compatibility with many. - -## The Problem - -AI coding agents are powerful but not self-directing. - -Give an agent a feature description and it will produce code. Sometimes that code is excellent. Sometimes it silently drifts from the specification. Sometimes it passes tests that do not actually verify the behavior the tests claim to cover. Sometimes it introduces architectural debt that compounds across the codebase. - -At scale, three things erode without structure: - -**Quality.** Without measurement, "the agent wrote code" is not evidence that the code is correct, well-tested, or maintainable. Quality claims require automated, reproducible evidence — not spot-checking. - -**Governance.** Without process boundaries, the agent plans and executes in the same pass, skipping the review and decomposition steps that catch design errors early. Every team that builds production agent systems independently discovers that planning and execution must be separated with hard gates between them. - -**Trust.** Without trust, organizations cannot move from human-in-the-loop to human-on-the-loop. Trust is not a feeling — it is an accumulation of evidence that the system produces reliable outcomes under known constraints. That evidence must be measurable, comparable across runs, and auditable after the fact. - -Unbound Force exists to solve all three. - -## The Enduring Core - -The project is governed by a constitution with five non-negotiable principles. These are not model-capability compensators — they are organizational values that persist regardless of how capable the underlying models become. - -**I. Autonomous Collaboration.** Agents communicate through well-defined artifacts — files, reports, schemas — rather than runtime coupling. Every agent completes its primary function without requiring synchronous interaction with another agent. Outputs are self-describing with provenance metadata. This makes collaboration asynchronous, auditable, and resilient to individual agent unavailability. - -**II. Composability First.** Every agent is independently installable and usable without any other agent being present. Combining agents produces additive value without introducing mandatory dependencies. Adoption friction kills tools; composability ensures each agent earns its place independently. - -**III. Observable Quality.** Every agent produces machine-parseable output with provenance metadata. Quality claims are backed by automated, reproducible evidence. Metrics are comparable across runs. A swarm that cannot measure its own performance cannot improve. - -**IV. Testability.** Every component is testable in isolation without requiring external services or shared mutable state. Tests verify observable side effects — return values, state mutations, I/O operations — rather than implementation details. Coverage ratchets are enforced automatically; any regression blocks the build. - -**V. Security by Default.** Security is a structural property, not a review-time afterthought. Dependencies are verified by content hash. External inputs are validated before reaching security-sensitive operations. Components operate with minimum permissions. Every dependency is attack surface; the default answer is "do not add." - -These principles are decay-resistant because they answer the question "what does this organization care about" rather than "what can this model not do." A model that writes perfect code still needs to know what the organization values. - -## Build to Delete - -Every component in an AI agent harness exists because someone believed the model could not do something reliably enough on its own. A multi-agent review council exists because one agent cannot reliably self-review. A specification pipeline exists because agents cannot reliably plan and execute in the same pass. Convention packs exist because agents do not consistently follow coding standards without explicit rules. - -These are bets on model limitations. Some are good bets that will remain true for years. Some are already becoming unnecessary. - -The honest position is this: we do not know which components of Unbound Force will prove to be permanent architecture and which will turn out to be temporary scaffolding. What we do know is the methodology for finding out. - -After each model upgrade, run the same task with and without each harness component. Measure quality. If quality holds without the component, delete it — not deprecate, not make optional, delete. Dead harness weight consumes context window, adds latency, and gives a false sense of security. - -**What persists:** the constitution and governance model, CI pipeline checks, convention packs, branch protection and commit gates. These encode organizational intent that does not expire with model improvements. - -**What may decay:** the size of the Divisor Council, detailed step-by-step instructions in agent personas, iteration caps, portions of Dewey's role as models develop better native codebase understanding. - -The system should shrink over time. That is a sign of progress, not regression. The discipline is to keep testing. - -## What Makes Us Different - -**Contract coverage.** Gaze does not measure line coverage or branch coverage alone. It measures whether tests verify the *contractual behavior* of the code they exercise — return values, state mutations, I/O side effects — versus testing implementation details that change when the code is refactored. No other system in the AI agent space measures this. Gaze classifies 37+ side-effect types and computes GazeCRAP scores that combine complexity, coverage, and contract verification into a single actionable metric. Multi-language support comes through language-specific backends: snake-eyes for Python, reading-stone for TypeScript/JavaScript, with Go built in. - -**Design and architectural quality.** Vibe-check measures structural health at the package level — coupling, cohesion, circular dependencies, instability, abstractness, distance from the main sequence — using Robert C. Martin's package metrics. It uses a universal model with a cross-language adapter architecture (JSON-RPC 2.0 protocol), so the same metrics are comparable whether the codebase is Go, Python, or TypeScript. Gaze tells you whether your tests are good. Vibe-check tells you whether your design is sound. Together they provide quality measurement at both the function and architectural levels. - -**Composability by design.** Each tool — `uf`, `gaze`, `dewey`, `replicator`, `vibe-check` — delivers standalone value. `gaze` works without `uf`. `dewey` works without `gaze`. `uf init --divisor` deploys only the PR review agents. There is no monolithic platform to adopt; you install the pieces you need and add more when you are ready. When tools are deployed together, they auto-detect each other and activate enhanced capabilities without requiring manual configuration. - -**Spec-driven development as a structural constraint.** The separation between planning and execution is not a suggestion — it is enforced. Branch naming gates pipeline entry. All spec artifacts must be committed before implementation begins. The `/uf.unleash` command has defined exit points where human judgment is required. `uf gate` enforces spec-first deterministically in headless/CI environments — the model cannot bypass it because it is not a prompt instruction but a pre-commit hook. - -**Factory pattern alignment by design.** All five characteristics of the factory pattern — agents producing specs, automation implementing and validating, disposable embodiment, engineers fixing agents rather than code, human-on-the-loop — were structural properties of Unbound Force before the factory vision was formally published. This is convergent design, not retrofitting. - -## The Boundary Thesis - -Unbound Force is a fluid agent layer — the personas, workflows, quality measurement, and governance rules that shape *how* agents do work. It is not an infrastructure layer and does not aspire to be one. - -Infrastructure — sandbox provisioning, credential management, event dispatch, cost tracking, provenance recording, security isolation — belongs to the steady-state layer. When Unbound Force runs inside FullSend's Bring Your Own Agent (BYOA) containers, FullSend provides that infrastructure. When it runs locally, OpenCode provides the runtime. The agent layer is the same in both environments: the same `.opencode/` directory, the same constitution, the same convention packs, the same slash commands. - -This boundary is deliberate. By not owning infrastructure, Unbound Force inherits capabilities it would otherwise have to build and maintain — cost/FinOps telemetry, provenance and attribution, sandbox security, event-driven dispatch — while focusing its energy on the agent layer where its differentiation lives. - -The broader ecosystem forms three layers: - -1. **Domain Intake** — intake-kit provides CUE-validated PRD authoring with a 5-specialist review council. Domain-specific toolkits and convention packs extend it for particular products. ADRs formalize architectural decisions. This is where organizational context enters the system and is validated before any code is written. -2. **Spec-Driven Development Bridge** — OpenSpec and Speckit decompose requirements into stories (GitHub Issues) and capability-level specs that drive implementation. This is the translation layer between human intent and agent-executable work. -3. **Execution Engine** — `/uf.unleash` through `/uf.finale`: branching, clarification, planning, task decomposition, spec review, parallel implementation, code review, and commit/PR/CI workflows. This is where agents produce and validate code. - -Each layer is independently valuable. Domain intake tooling works without Unbound Force. Unbound Force works without a formal intake layer. But when all three layers connect, the system achieves end-to-end traceability from business requirement to tested, reviewed, merged code — with every decision auditable in git. - -## What Success Looks Like - -The path from where most organizations are today to full factory-pattern operation has three phases. Each phase builds trust through accumulated evidence. - -**Phase 1 — Human-Fronted Factories.** Agents produce artifacts — specs, implementations, reviews, test results — but humans make every merge decision. The agent swarm accelerates work; the human validates outcomes. Unbound Force is ready for this phase today. The `/uf.unleash` command runs the full pipeline autonomously but never auto-merges. The `/uf.finale` command pushes a PR, watches CI, and waits for human approval. - -**Phase 2 — Agentic Review Participation.** Agents post formal reviews on pull requests, and those reviews carry weight in the merge decision. The Divisor Council already operates in this mode via the `council-review-action` GitHub Action — agents review PRs in CI and post structured findings. Humans still merge, but agent reviews are a first-class input to the decision, not an afterthought. - -**Phase 3 — Factory-to-Factory.** Multiple factory instances operate across repositories at machine speed. One factory identifies an integration issue in its dependency; another factory receives the signal and produces a fix; a third factory validates the fix against its own test suite. Humans set policy and handle escalations. The loop runs continuously. This phase requires cross-repo forge capabilities, mature eval harnesses, and tiered approval policies that do not yet exist. It is the destination, not the current state. - -The honest assessment: Phase 1 is operational. Phase 2 is operational for review participation. Phase 3 is not yet built. The roadmap is the path from here to there. diff --git a/layouts/home.html b/layouts/home.html index 472564d..e9a00df 100644 --- a/layouts/home.html +++ b/layouts/home.html @@ -139,7 +139,7 @@

Why Unbound Force?

Spec to Demo in One Command

- Run /uf.unleash and the swarm handles clarification, + Run /unleash and the swarm handles clarification, planning, implementation, testing, and review autonomously. It exits when it needs your judgment and resumes where it left off. No manual step-by-step orchestration required. diff --git a/openspec/changes/dewey-docs-sync/.openspec.yaml b/openspec/changes/devpod-preflight-docs/.openspec.yaml similarity index 52% rename from openspec/changes/dewey-docs-sync/.openspec.yaml rename to openspec/changes/devpod-preflight-docs/.openspec.yaml index 018e641..2f8943c 100644 --- a/openspec/changes/dewey-docs-sync/.openspec.yaml +++ b/openspec/changes/devpod-preflight-docs/.openspec.yaml @@ -1,2 +1,2 @@ schema: unbound-force -created: 2026-08-21 +created: 2026-08-20 diff --git a/openspec/changes/devpod-preflight-docs/design.md b/openspec/changes/devpod-preflight-docs/design.md new file mode 100644 index 0000000..854773a --- /dev/null +++ b/openspec/changes/devpod-preflight-docs/design.md @@ -0,0 +1,45 @@ +## Context + +PR unbound-force/unbound-force#436 removed the `LookPath("podman")` pre-flight check from `uf sandbox create --backend devpod` and added a diagnostic hint on `devpod up` failure. The website documentation currently states Podman must be installed as a prerequisite and does not mention the diagnostic hint. These docs need updating to match the new behavior. + +The proposal (constitution alignment: all N/A) confirms this is a documentation-only change with no hero functionality, artifact interfaces, or testability implications. + +## Goals / Non-Goals + +### Goals +- Update sandbox reference prerequisites to remove standalone Podman binary requirement for DevPod workspaces +- Document the new `devpod up` failure diagnostic hint (`uf doctor` / `uf setup`) +- Clarify that `uf setup` registers a docker-type provider under the name `podman` via `DOCKER_PATH=podman` +- Update blog post to remove misleading "Podman required" limitation for DevPod users +- Add changelog entry for the pre-flight change +- Preserve accuracy: ephemeral Podman sandbox (`uf sandbox start` without DevPod) still requires Podman installed + +### Non-Goals +- Rewriting the sandbox reference page structure or adding new sections +- Documenting the upstream code changes (that belongs in the unbound-force repo) +- Updating DevPod provider internals or architecture diagrams +- Modifying CLI reference (subcommand table is already accurate) + +## Decisions + +### D1: Distinguish ephemeral vs. persistent prerequisites + +The sandbox has two paths: ephemeral containers (`uf sandbox start` — uses Podman directly) and persistent workspaces (`uf sandbox create` — uses DevPod). Only the DevPod path dropped the standalone Podman requirement. The documentation must make this distinction clear to avoid confusing users who use ephemeral containers (and still need Podman). + +**Approach**: Split the prerequisites paragraph into two contexts — ephemeral (Podman required) and persistent/DevPod (`uf setup` configures everything). This avoids a blanket statement in either direction. + +### D2: Blog post update scope + +The blog post `sandbox-isolation.md` lists "Podman required" as a current limitation. Rather than removing the limitation entirely (since ephemeral mode still needs it), update the wording to clarify the limitation applies to ephemeral containers only, and that DevPod workspaces handle runtime resolution automatically. + +### D3: Changelog placement + +Add the pre-flight change to the changelog as a "Changed" item under the next release version. Since the upstream PR targets a future release, use a placeholder version header that will be finalized at release time. + +## Risks / Trade-offs + +### Risk: Over-simplification +Removing "Podman required" without nuance could lead DevPod users to think they never need Podman, when ephemeral mode still requires it. **Mitigation**: Explicit split between ephemeral and DevPod prerequisites. + +### Risk: Blog post drift +Blog posts are point-in-time artifacts. Editing post-publication content could create confusion if readers saw the original version. **Mitigation**: The edit is factual correction, not opinion change. The limitation is being refined, not removed. diff --git a/openspec/changes/devpod-preflight-docs/proposal.md b/openspec/changes/devpod-preflight-docs/proposal.md new file mode 100644 index 0000000..80d8468 --- /dev/null +++ b/openspec/changes/devpod-preflight-docs/proposal.md @@ -0,0 +1,71 @@ +## Why + +PR unbound-force/unbound-force#436 (fixing #431) changed the DevPod sandbox pre-flight behavior: + +1. **Removed** the `LookPath("podman")` pre-flight check — users no longer need the `podman` binary in `$PATH`. The docker provider aliased as `podman` (configured by `uf setup`) handles container runtime resolution internally. +2. **Added** a diagnostic hint on `devpod up` failure: `"run 'uf doctor' to diagnose or 'uf setup' to configure"`. +3. **Unchanged**: The `--provider podman` flag is retained — it references the registered DevPod provider name, not a standalone binary. + +The website documentation currently states Podman must be installed as a prerequisite and implies a standalone `podman` binary is required in `$PATH`. This is no longer accurate and could confuse users who follow the docs and install standalone Podman when `uf setup` already configures everything needed. + +## What Changes + +Update documentation across multiple pages to reflect the new DevPod provider model and diagnostic hint. + +## Capabilities + +### New Capabilities +- `diagnostic-hint-docs`: Document the new `devpod up` failure diagnostic hint that directs users to `uf doctor` and `uf setup` + +### Modified Capabilities +- `sandbox-prerequisites`: Update prerequisites to clarify that `uf setup` configures the DevPod provider (a docker-type provider registered under the name `podman` via `DOCKER_PATH=podman`) — users do not need to install standalone Podman separately for DevPod workspaces +- `sandbox-blog-post`: Update the blog post to remove the implication that standalone Podman installation is a user prerequisite for DevPod workspaces + +### Removed Capabilities +- `podman-in-path-prerequisite`: Remove documentation stating users need `podman` in `$PATH` as a prerequisite for DevPod sandbox usage + +## Impact + +**Affected pages** (files containing outdated podman prerequisite or DevPod provider information): + +| File | What Needs Changing | +|------|-------------------| +| `content/docs/reference/sandbox.md` | Update Prerequisites paragraph (line 15): remove "Podman and DevPod must be installed" framing, clarify provider model, add diagnostic hint | +| `content/blog/sandbox-isolation.md` | Update "Current Limitations" section (line 147): "Podman required" is misleading for DevPod users; update blog post startup sequence to reflect new pre-flight behavior | +| `content/docs/reference/cli.md` | No changes needed — sandbox subcommand table is accurate as-is | +| `content/docs/getting-started/quick-start.md` | No changes needed — no Podman prerequisite mentioned | +| `content/docs/changelog/_index.md` | Add changelog entry for the pre-flight change in the next release section | + +**What is NOT changing:** + +- Ephemeral Podman sandbox (`uf sandbox start` without DevPod) still requires Podman — only the DevPod workspace path (`uf sandbox create`) dropped the standalone binary requirement +- `--backend podman` flag name is unchanged +- UID mapping, mount modes, security model — all unchanged + +## Constitution Alignment + +Assessed against the Unbound Force org constitution. + +### I. Autonomous Collaboration + +**Assessment**: N/A + +This is a documentation-only change. No artifact interfaces, hero communication protocols, or runtime coupling are affected. + +### II. Composability First + +**Assessment**: N/A + +No hero functionality is added, removed, or modified. The change updates text content to reflect upstream CLI behavior changes. + +### III. Observable Quality + +**Assessment**: N/A + +No machine-parseable output or provenance metadata is involved. This is a static website content update. + +### IV. Testability + +**Assessment**: N/A + +Documentation changes are validated through `npm run build` (build succeeds) and visual verification (content renders correctly). No code-level testability concerns. diff --git a/openspec/changes/devpod-preflight-docs/specs/sandbox-docs.md b/openspec/changes/devpod-preflight-docs/specs/sandbox-docs.md new file mode 100644 index 0000000..e172d8f --- /dev/null +++ b/openspec/changes/devpod-preflight-docs/specs/sandbox-docs.md @@ -0,0 +1,56 @@ +## ADDED Requirements + +### Requirement: DevPod failure diagnostic hint + +The sandbox reference page MUST document that when `devpod up` fails, the CLI displays a diagnostic hint: `"run 'uf doctor' to diagnose or 'uf setup' to configure"`. + +#### Scenario: User reads about DevPod workspace troubleshooting +- **GIVEN** a user is reading the sandbox reference page +- **WHEN** they look for information about DevPod workspace creation failures +- **THEN** they find documentation that `uf doctor` and `uf setup` are the recommended diagnostic and recovery commands + +### Requirement: Changelog entry for pre-flight change + +The changelog MUST include an entry documenting the removal of the standalone Podman binary pre-flight check for DevPod workspaces and the addition of the diagnostic hint. + +#### Scenario: User checks changelog for breaking changes +- **GIVEN** a user is reading the changelog for the next release +- **WHEN** they look for sandbox-related changes +- **THEN** they find an entry describing the DevPod pre-flight change (removed `podman` binary check, added diagnostic hint) + +## MODIFIED Requirements + +### Requirement: Sandbox prerequisites + +The sandbox reference prerequisites MUST distinguish between ephemeral containers (which require Podman installed) and DevPod persistent workspaces (which do not require a standalone `podman` binary in `$PATH`). The documentation MUST clarify that `uf setup` registers a docker-type DevPod provider under the name `podman` via `DOCKER_PATH=podman`, handling runtime resolution automatically. + +Previously: "Prerequisites: Podman and DevPod must be installed." + +#### Scenario: User reads prerequisites for DevPod workspace +- **GIVEN** a user wants to create a persistent DevPod workspace +- **WHEN** they read the sandbox prerequisites +- **THEN** they understand that `uf setup` configures the DevPod provider and they do not need to install standalone Podman separately + +#### Scenario: User reads prerequisites for ephemeral sandbox +- **GIVEN** a user wants to run an ephemeral sandbox container +- **WHEN** they read the sandbox prerequisites +- **THEN** they understand that Podman must be installed for ephemeral containers + +### Requirement: Blog post Podman limitation + +The blog post "Current Limitations" section SHOULD clarify that the "Podman required" limitation applies to ephemeral containers only, not to DevPod persistent workspaces where the provider handles runtime resolution. + +Previously: "Podman required: The sandbox uses Podman, not Docker." + +#### Scenario: User reads blog post limitations +- **GIVEN** a user is reading the sandbox isolation blog post +- **WHEN** they read the current limitations section +- **THEN** they understand that Podman is required only for ephemeral containers, and DevPod workspaces use a configured provider + +## REMOVED Requirements + +### Requirement: Standalone Podman binary as universal prerequisite + +Documentation MUST NOT state that users need `podman` in `$PATH` as a blanket prerequisite for all sandbox usage. The standalone binary requirement applies only to ephemeral containers, not DevPod workspaces. + +Reason: The upstream `LookPath("podman")` pre-flight check was removed from the DevPod code path. The docker provider aliased as `podman` (configured by `uf setup`) handles container runtime resolution without requiring the standalone binary. diff --git a/openspec/changes/devpod-preflight-docs/tasks.md b/openspec/changes/devpod-preflight-docs/tasks.md new file mode 100644 index 0000000..27216fa --- /dev/null +++ b/openspec/changes/devpod-preflight-docs/tasks.md @@ -0,0 +1,28 @@ + + +## 1. Update sandbox reference prerequisites + +- [x] 1.1 [P] Update the Prerequisites paragraph in `content/docs/reference/sandbox.md` (line 15): split into ephemeral container prerequisites (Podman required) and DevPod persistent workspace prerequisites (`uf setup` configures the docker-type provider aliased as `podman`). Add note about the `devpod up` failure diagnostic hint (`uf doctor` / `uf setup`). File: `content/docs/reference/sandbox.md` + +## 2. Update blog post limitations + +- [x] 2.1 [P] Update the "Current Limitations" section in `content/blog/sandbox-isolation.md` (line 147): refine the "Podman required" limitation to clarify it applies to ephemeral containers only, and that DevPod persistent workspaces use a configured provider that handles runtime resolution automatically. File: `content/blog/sandbox-isolation.md` + +## 3. Add changelog entry + +- [x] 3.1 [P] Add a changelog entry to `content/docs/changelog/_index.md` documenting: (a) removed standalone `podman` binary pre-flight check for DevPod workspaces, (b) added diagnostic hint on `devpod up` failure directing users to `uf doctor` and `uf setup`. File: `content/docs/changelog/_index.md` + +## 4. Verification + +- [x] 4.1 Run `npm run build` to verify the site builds without errors +- [x] 4.2 Verify constitution alignment: all four principles assessed as N/A (documentation-only change — no hero functionality, artifact interfaces, machine-parseable output, or testability implications) diff --git a/openspec/changes/dewey-docs-sync/design.md b/openspec/changes/dewey-docs-sync/design.md deleted file mode 100644 index 4394bbe..0000000 --- a/openspec/changes/dewey-docs-sync/design.md +++ /dev/null @@ -1,83 +0,0 @@ -## Context - -The Dewey documentation on the Unbound Force website spans three pages (`projects/dewey.md`, `getting-started/knowledge.md`, `team/dewey.md`) and is stale relative to the current Dewey v3.2.0 release. Twelve upstream changes need to be reflected. The proposal (proposal.md) established that all changes are additive updates to existing pages with no structural, navigation, or layout changes required. Constitution alignment is N/A for Autonomous Collaboration, Composability First, and Security by Default; PASS for Observable Quality and Testability. - -## Goals / Non-Goals - -### Goals -- Update all three Dewey documentation pages to accurately reflect Dewey v3.2.0 -- Maintain cross-page consistency for shared facts (tool count, installation methods, provider list) -- Preserve existing page structure and section ordering on each page -- Source all content from upstream GitHub issues with traceable provenance -- Keep documentation website-audience appropriate (not raw README content) - -### Non-Goals -- Creating new documentation pages (all content fits existing pages) -- Documenting Dewey internals or implementation details (website is user-facing) -- Covering unreleased or in-progress Dewey features -- Modifying navigation, layouts, templates, or SCSS -- Updating non-Dewey documentation pages - -## Decisions - -### D1: Update in-place rather than restructure - -**Decision**: Modify existing sections within each page rather than reorganizing the page structure. - -**Rationale**: The current page structure is well-established and linked from multiple locations. Restructuring would risk breaking internal cross-references and user bookmarks. The twelve changes all fit naturally into existing sections (installation, configuration, environment variables, diagnostics, etc.). - -### D2: Group related changes by target section - -**Decision**: Apply changes to each page in section order (top to bottom) rather than by issue number. - -**Rationale**: This minimizes edit conflicts and ensures each section is touched once with all relevant updates applied together. For example, the installation section on `knowledge.md` receives both the RPM addition (#186) and the Homebrew fix note (#213) in a single editing pass. - -### D3: Tool count follows cumulative progression - -**Decision**: The final tool count is 50 across all pages. The progression is: 48 (baseline) → 49 (`curate` from #41) → 50 (`store_compiled` from #113). - -**Rationale**: Both tools are documented in their respective issues. The count must be consistent across `projects/dewey.md` (feature list), `getting-started/knowledge.md` (if mentioned), and `team/dewey.md` (tool catalog header). - -### D4: Environment variable documentation pattern - -**Decision**: New env vars (`DEWEY_CHUNK_MAX_CHARS`, `DEWEY_SYNTHESIS_ENDPOINT`, `DEWEY_AUTHOR`) follow the existing table format established in `knowledge.md` for `DEWEY_EMBEDDING_MODEL` and related variables. - -**Rationale**: Consistency with the existing documentation pattern. The env var reference table in `knowledge.md` already uses a consistent format with variable name, description, and default value columns. - -### D5: Provider configuration uses side-by-side examples - -**Decision**: Document Ollama and Vertex AI provider configuration with separate `config.yaml` code blocks showing each provider's settings, rather than a single combined example. - -**Rationale**: Users typically configure one provider, not both. Separate examples are easier to copy-paste and reduce confusion about which fields apply to which provider. The `region: global` behavior for Vertex AI (#240) is documented inline within the Vertex AI example. - -### D6: Synthesis endpoint precedence documented as a callout - -**Decision**: The inverted precedence chain for `DEWEY_SYNTHESIS_ENDPOINT` (config.yaml > env var, opposite of embedding) is documented with an explicit callout/note rather than buried in a table. - -**Rationale**: This is a surprising behavior that could cause user confusion. Making it visually prominent prevents misconfiguration. References issue #243. - -### D7: Content sanitization as a new subsection within existing pages - -**Decision**: Add a "Content Sanitization" subsection to `knowledge.md` under the existing content sources or configuration section, rather than creating a standalone page. - -**Rationale**: Sanitization is configured per-source in `sources.yaml` and is part of the content pipeline. It fits naturally alongside the existing content source documentation. The pattern catalog (10 regex patterns across 3 severity levels) is concise enough for a subsection. - -## Risks / Trade-offs - -### R1: Page length growth - -**Risk**: `knowledge.md` is already 555 lines. Adding provider configuration, sanitization, curated stores, and new env vars could push it past 700 lines. - -**Mitigation**: Use collapsible sections or concise formatting where appropriate. The page already has a table of contents (`toc: true`) which helps navigation. If the page becomes unwieldy during implementation, individual sections can be extracted to dedicated pages in a follow-up change. - -### R2: Upstream drift during implementation - -**Risk**: New Dewey changes could land while this documentation sync is in progress. - -**Mitigation**: This change covers a specific set of 12 issues. Any new upstream changes will be tracked by new GitHub issues and addressed in a subsequent sync. The branch-based workflow isolates this work. - -### R3: Accuracy of feature descriptions - -**Risk**: Documentation is derived from GitHub issue descriptions, not from direct testing of Dewey features. - -**Mitigation**: All content is traceable to specific issue numbers. The issues contain detailed technical descriptions authored by the Dewey maintainers. Any uncertainty should be resolved by checking the linked PRs in the upstream repository. The zero-waste mandate prevents fabricating features. diff --git a/openspec/changes/dewey-docs-sync/proposal.md b/openspec/changes/dewey-docs-sync/proposal.md deleted file mode 100644 index 2463e22..0000000 --- a/openspec/changes/dewey-docs-sync/proposal.md +++ /dev/null @@ -1,86 +0,0 @@ -## Why - -The Dewey documentation on the Unbound Force website is significantly out of date. Twelve upstream changes spanning v3.1.0 and v3.2.0 have shipped in the `unbound-force/dewey` repository without corresponding website documentation updates. Users visiting the website encounter stale tool counts (48 instead of 50), missing installation methods (RPM, fixed Homebrew), undocumented environment variables (`DEWEY_CHUNK_MAX_CHARS`, `DEWEY_SYNTHESIS_ENDPOINT`, `DEWEY_AUTHOR`), missing provider configuration (Vertex AI alongside Ollama), and no mention of major features like curated knowledge stores, content sanitization, or the `dewey doctor` synthesis diagnostics. - -This creates a trust gap: the website claims to be the authoritative documentation, but users who install the latest release discover capabilities and configuration options that aren't documented anywhere on the site. - -Tracked by: #207, #208, #209, #213, #240, #243, #249, #186, #132, #131, #41, #113. - -## What Changes - -Synchronize three existing documentation pages to reflect the current state of Dewey (through v3.2.0): - -1. **`content/docs/projects/dewey.md`** — Update tool count from 48 to 50, add curated knowledge stores and pluggable providers to feature list, add RPM to installation options, mention content sanitization. - -2. **`content/docs/getting-started/knowledge.md`** — Add RPM installation section, document `DEWEY_CHUNK_MAX_CHARS` and `DEWEY_SYNTHESIS_ENDPOINT` environment variables, add Vertex AI provider configuration alongside Ollama, document `region: global` endpoint behavior, update `dewey doctor` output to include synthesis layer diagnostics, add content sanitization configuration (`sanitize_mode`, `trust_tier`), document curated knowledge stores (`dewey curate`, `knowledge-stores.yaml`), update learning identity format to v3.2.0 timestamped format, add `DEWEY_AUTHOR` env var, note Homebrew cask fix. - -3. **`content/docs/team/dewey.md`** — Update tool count from 48 to 50, add `curate` and `store_compiled` tools to the tool catalog, update `max_chunk_chars` documentation with the `DEWEY_CHUNK_MAX_CHARS` env var, mention pluggable providers. - -## Capabilities - -### New Capabilities -- `RPM installation docs`: Fedora/RHEL/CentOS installation instructions with `dnf install` workflow -- `Vertex AI provider configuration`: Complete setup guide for Vertex AI as an alternative to Ollama, including `gcloud` auth, project/region config, and `region: global` endpoint behavior -- `Content sanitization reference`: Documentation of the 4-layer sanitization pipeline, pattern catalog, severity classifications, and per-source configuration -- `Curated knowledge stores reference`: Documentation of `dewey curate`, `knowledge-stores.yaml`, the `curated` trust tier, and background curation -- `Synthesis endpoint configuration`: `DEWEY_SYNTHESIS_ENDPOINT` env var documentation with precedence chain explanation -- `Doctor synthesis diagnostics`: Updated `dewey doctor` output reference showing the synthesis layer section - -### Modified Capabilities -- `Tool count`: Updated from 48 to 50 across all pages that reference it -- `Installation section`: Homebrew cask fix noted, RPM added between Homebrew and `go install` -- `Environment variables reference`: Added `DEWEY_CHUNK_MAX_CHARS`, `DEWEY_SYNTHESIS_ENDPOINT`, `DEWEY_AUTHOR` -- `Learning identity format`: Updated examples to v3.2.0 timestamped format with migration note -- `Embedding configuration`: Added `DEWEY_CHUNK_MAX_CHARS` and `embedding.max_chunk_chars` documentation - -### Removed Capabilities -- None. All changes are additive or corrective. - -## Impact - -**Affected files:** -- `content/docs/projects/dewey.md` — Feature list, tool count, installation options -- `content/docs/getting-started/knowledge.md` — Installation, env vars, provider config, doctor output, sanitization, curation, learning format -- `content/docs/team/dewey.md` — Tool catalog, tool count, embedding config - -**No structural changes:** -- No new pages created (all content fits within existing page structure) -- No navigation changes needed -- No layout or template changes -- No SCSS/CSS changes - -**Cross-page consistency:** Tool count must be updated consistently across all three pages (48 → 50). The `curate` tool (from #41) brings it to 49, and `store_compiled` (from #113) brings it to 50. - -## Constitution Alignment - -Assessed against the Unbound Force org constitution. - -### I. Autonomous Collaboration - -**Assessment**: N/A - -This change updates static documentation content on the website. It does not modify artifact-based communication protocols, tool interfaces, or agent interaction patterns. Documentation pages are self-contained Markdown files that do not introduce runtime coupling. - -### II. Composability First - -**Assessment**: N/A - -No new dependencies are introduced. The website remains a standalone Hugo static site. The documentation updates describe Dewey features but do not create mandatory dependencies between the website and Dewey's runtime. - -### III. Observable Quality - -**Assessment**: PASS - -The documentation updates improve observable quality by accurately documenting Dewey's current capabilities, configuration options, and diagnostic outputs. Users can verify the documentation against their installed version. Content is sourced from upstream GitHub issues with traceable provenance (#207, #208, #209, #213, #240, #243, #249, #186, #132, #131, #41, #113). - -### IV. Testability - -**Assessment**: PASS - -This change modifies documentation content only. The project has no test suite (AGENTS.md). Verification strategy is defined in tasks group 4: `npm run build` (zero errors), visual inspection of all three pages, cross-page consistency checks for shared facts (tool count, provider terminology, `DEWEY_CHUNK_MAX_CHARS`), and constitution alignment verification. All acceptance scenarios use GIVEN/WHEN/THEN format verifiable through manual inspection of rendered pages. - -### V. Security by Default - -**Assessment**: N/A - -This change documents existing security features (content sanitization) but does not modify any security-sensitive code, dependencies, or CI configuration. The documentation accurately describes sanitization capabilities without introducing new attack surface. diff --git a/openspec/changes/dewey-docs-sync/specs/knowledge-page.md b/openspec/changes/dewey-docs-sync/specs/knowledge-page.md deleted file mode 100644 index 09d8473..0000000 --- a/openspec/changes/dewey-docs-sync/specs/knowledge-page.md +++ /dev/null @@ -1,151 +0,0 @@ -# Delta Spec: Knowledge Page (`content/docs/getting-started/knowledge.md`) - -Issues: #207, #208, #209, #213, #240, #243, #249, #186, #132, #131, #41, #113 - -## ADDED Requirements - -### Requirement: RPM Installation Section - -The installation section MUST include an RPM subsection for Fedora/RHEL/CentOS, positioned between Homebrew and `go install`. The section MUST document downloading from GitHub Releases and installing with `sudo dnf install ./dewey__linux_amd64.rpm`. Both `amd64` and `arm64` architectures SHOULD be mentioned. - -#### Scenario: RPM installation instructions -- **GIVEN** a user on Fedora/RHEL/CentOS visits the installation section -- **WHEN** they look for their platform's install method -- **THEN** they find RPM instructions with the `dnf install` command and a note about available architectures - -### Requirement: DEWEY_CHUNK_MAX_CHARS Environment Variable (Ref: #208) - -The environment variables reference MUST document `DEWEY_CHUNK_MAX_CHARS` (default: 12288) with its description (maximum characters per embedding chunk), corresponding config field (`embedding.max_chunk_chars`), and default value. Note: this variable is already partially documented in the Embedding Model Alignment table (lines 48, 55). Verify the existing documentation is accurate and consistent with #208 rather than duplicating content. - -#### Scenario: User configures chunk size -- **GIVEN** a user wants to tune embedding chunk size -- **WHEN** they consult the environment variables table -- **THEN** they find `DEWEY_CHUNK_MAX_CHARS` with its description and default value (12288) - -### Requirement: DEWEY_SYNTHESIS_ENDPOINT Environment Variable - -The environment variables reference MUST document `DEWEY_SYNTHESIS_ENDPOINT` with its description and fallback chain (`DEWEY_SYNTHESIS_ENDPOINT` → `OLLAMA_HOST` → `http://localhost:11434`). A callout MUST note the inverted precedence: for synthesis, `config.yaml` takes highest priority over env vars (opposite of embedding). - -#### Scenario: User configures synthesis endpoint -- **GIVEN** a user wants to set a custom synthesis endpoint -- **WHEN** they read the env var documentation -- **THEN** they see the fallback chain and an explicit warning about the inverted precedence relative to embedding - -### Requirement: DEWEY_AUTHOR Environment Variable - -The environment variables reference MUST document `DEWEY_AUTHOR` with its description (author tag for learning identities in CI/shared environments). - -#### Scenario: User sets author for CI -- **GIVEN** a user runs Dewey in CI -- **WHEN** they need learnings attributed to a specific author -- **THEN** they find `DEWEY_AUTHOR` documented with its purpose - -### Requirement: Vertex AI Provider Configuration - -A provider configuration section MUST be added documenting how to configure Vertex AI alongside Ollama. This MUST include: -- `embedding.provider` and `synthesis.provider` config fields -- Vertex AI setup requirements (`gcloud` auth, project ID, region) -- `region: global` endpoint behavior (uses `aiplatform.googleapis.com` without region prefix) -- Separate config.yaml examples for Ollama and Vertex AI providers - -#### Scenario: User configures Vertex AI -- **GIVEN** a user wants to use Vertex AI instead of Ollama -- **WHEN** they read the provider configuration section -- **THEN** they find a complete Vertex AI config.yaml example with project, region, and auth requirements - -#### Scenario: User sets region to global -- **GIVEN** a user configures `region: global` for Vertex AI -- **WHEN** they read the provider docs -- **THEN** they understand that `global` routes to the nearest region via `aiplatform.googleapis.com` - -### Requirement: Content Sanitization Configuration - -A content sanitization subsection MUST be added documenting: -- The 4-layer sanitization pipeline (injection patterns, hash drift, Markdown validation, size anomaly) -- Per-source configuration via `sanitize_mode` (warn/strict/off) and `trust_tier` in `sources.yaml` -- The severity classifications (critical/high/medium) -- That findings are surfaced by `dewey doctor` and `dewey lint` - -#### Scenario: User enables strict sanitization -- **GIVEN** a user indexes untrusted external content -- **WHEN** they read the sanitization section -- **THEN** they know how to set `sanitize_mode: strict` and `trust_tier` per-source in `sources.yaml` - -### Requirement: Curated Knowledge Stores - -A curated knowledge stores subsection MUST be added documenting: -- The `dewey curate` command and its purpose -- The `knowledge-stores.yaml` configuration file -- The `curated` trust tier -- Background curation during `dewey serve` - -#### Scenario: User sets up curation -- **GIVEN** a user wants to curate their knowledge base -- **WHEN** they read the curated knowledge stores section -- **THEN** they understand how to configure `knowledge-stores.yaml` and run `dewey curate` - -### Requirement: Global Config Path (Ref: #113) - -The configuration section MUST document the global config path (`~/.config/dewey/config.yaml`) and how per-vault configs override global settings. - -#### Scenario: User sets global defaults -- **GIVEN** a user wants to set default provider config across all vaults -- **WHEN** they read the configuration section -- **THEN** they learn about `~/.config/dewey/config.yaml` and per-vault overrides - -### Requirement: Index Pipeline Performance Note (Ref: #207) - -The diagnostic commands section or the `dewey index` reference SHOULD include a note about batch embedding and concurrent source fetching for performance context. - -#### Scenario: User learns about indexing performance -- **GIVEN** a user runs `dewey index` on a large vault -- **WHEN** they read about the index command -- **THEN** they understand that embedding is batched and sources are fetched concurrently - -### Requirement: Vertex AI Curation Defaults (Ref: #209) - -The `dewey curate` documentation SHOULD note Vertex AI-specific defaults (16000 max output tokens, 300s timeout) to set user expectations for curation performance. - -#### Scenario: User curates with Vertex AI -- **GIVEN** a user runs `dewey curate` with Vertex AI -- **WHEN** curation takes several minutes -- **THEN** documentation explains that large prompt processing may take up to 300s - -## MODIFIED Requirements - -### Requirement: Doctor Output Reference - -The `dewey doctor` command description MUST include the Synthesis Layer section between the Embedding Layer and MCP Server sections, updating the diagnostic section count from 7 to 8. The synthesis layer reports: provider type (ollama/vertex/unconfigured), resolved endpoint, model name, connectivity status, and (for Ollama) model availability. - -Previously: `dewey doctor` documentation showed only Embedding Layer and MCP Server sections. - -#### Scenario: User runs dewey doctor -- **GIVEN** a user runs `dewey doctor` to diagnose configuration -- **WHEN** they compare their output to the documentation -- **THEN** the docs show the Synthesis Layer section reporting provider type, resolved endpoint, model name, connectivity status, and (for Ollama) model availability - -### Requirement: Learning Identity Format - -Learning identity examples MUST use the v3.2.0 timestamped format (`{tag}-{YYYYMMDDTHHMMSS}-{author}`) instead of the old sequential format (`{tag}-{sequence}`). A migration note SHOULD explain the change and backward compatibility. - -Previously: Examples showed `authentication-3` format. - -#### Scenario: User stores a learning -- **GIVEN** a user reads the learning documentation -- **WHEN** they see identity format examples -- **THEN** examples use the timestamped format (e.g., `authentication-20260502T143022-alice`) - -### Requirement: Homebrew Install Note - -The Homebrew installation section SHOULD note that macOS cask install issues present in v3.1.0 and v3.2.0 have been fixed. - -Previously: No mention of cask install reliability. - -#### Scenario: User installs via Homebrew on macOS -- **GIVEN** a macOS user previously encountered SHA-256 mismatch errors -- **WHEN** they read the installation docs -- **THEN** they see a note confirming the cask install is fixed - -## REMOVED Requirements - -None. diff --git a/openspec/changes/dewey-docs-sync/specs/project-page.md b/openspec/changes/dewey-docs-sync/specs/project-page.md deleted file mode 100644 index 889c755..0000000 --- a/openspec/changes/dewey-docs-sync/specs/project-page.md +++ /dev/null @@ -1,58 +0,0 @@ -# Delta Spec: Project Page (`content/docs/projects/dewey.md`) - -Issues: #41, #113, #186, #131 - -## ADDED Requirements - -### Requirement: RPM Installation Option - -The installation section MUST include an RPM installation method for Fedora/RHEL/CentOS systems, positioned after Homebrew and before `go install`. - -#### Scenario: User views installation options -- **GIVEN** a user visits the Dewey project page -- **WHEN** they read the installation section -- **THEN** they see RPM listed as an installation method alongside Homebrew and Linux binary - -### Requirement: Curated Knowledge Stores Feature - -The key features list MUST include curated knowledge stores as a capability, referencing the `dewey curate` command. - -#### Scenario: User reviews Dewey capabilities -- **GIVEN** a user reads the key features section -- **WHEN** they scan the feature list -- **THEN** they see curated knowledge stores listed with a description of what it provides - -### Requirement: Pluggable Provider Feature - -The key features list MUST mention pluggable embedding and synthesis providers (Ollama and Vertex AI). - -#### Scenario: User evaluates provider support -- **GIVEN** a user wants to know which AI providers Dewey supports -- **WHEN** they read the key features section -- **THEN** they see that both Ollama and Vertex AI are supported as configurable providers - -### Requirement: Content Sanitization Feature - -The key features list SHOULD mention content sanitization as a security capability. - -#### Scenario: User evaluates security features -- **GIVEN** a user is concerned about untrusted content in their knowledge base -- **WHEN** they read the key features section -- **THEN** they see content sanitization listed with a brief description - -## MODIFIED Requirements - -### Requirement: Tool Count - -The tool count MUST be updated from 48 to 50 in all locations where it appears on the page. - -Previously: "48 MCP tools" - -#### Scenario: Tool count accuracy -- **GIVEN** a user reads the Dewey project page -- **WHEN** they see a reference to MCP tool count -- **THEN** the count reads 50 (not 48) - -## REMOVED Requirements - -None. diff --git a/openspec/changes/dewey-docs-sync/specs/team-page.md b/openspec/changes/dewey-docs-sync/specs/team-page.md deleted file mode 100644 index 0bb4b45..0000000 --- a/openspec/changes/dewey-docs-sync/specs/team-page.md +++ /dev/null @@ -1,60 +0,0 @@ -# Delta Spec: Team Page (`content/docs/team/dewey.md`) - -Issues: #41, #113, #208 - -## ADDED Requirements - -### Requirement: Curate Tool in Tool Catalog - -The tool catalog MUST include the `curate` tool in the appropriate category (Knowledge Management). - -#### Scenario: User reviews available tools -- **GIVEN** a user reads the tool catalog on the team page -- **WHEN** they look at Knowledge Management tools -- **THEN** they see `curate` listed with a brief description - -### Requirement: Store Compiled Tool in Tool Catalog - -The tool catalog MUST include the `store_compiled` tool in the Knowledge Management category (alongside `compile`, `lint`, and `promote`). - -#### Scenario: User reviews compiled article tools -- **GIVEN** a user wants to persist compiled knowledge articles -- **WHEN** they look at the tool catalog -- **THEN** they see `store_compiled` listed with a brief description - -### Requirement: Pluggable Providers Mention - -The embedding model section SHOULD mention that Dewey supports pluggable providers (Ollama and Vertex AI), not just the default IBM Granite model. - -#### Scenario: User evaluates embedding options -- **GIVEN** a user reads the embedding model section -- **WHEN** they want to know about alternative providers -- **THEN** they see a note about pluggable provider support with a link to the getting-started guide - -## MODIFIED Requirements - -### Requirement: Tool Count - -The tool count MUST be updated from 48 to 50 in the tool catalog header and any other location where the count appears. - -Previously: "48 tools across 12 categories" - -#### Scenario: Tool count consistency -- **GIVEN** a user reads the team page -- **WHEN** they see the tool count -- **THEN** it reads 50 (not 48) - -### Requirement: Embedding Chunk Size Configuration - -The `max_chunk_chars` documentation MUST also reference the `DEWEY_CHUNK_MAX_CHARS` environment variable as an alternative configuration method. Note: this env var is already documented at line 136 of the current page. Verify the existing content is accurate and consistent with #208 rather than duplicating. - -Previously: `DEWEY_CHUNK_MAX_CHARS` env var is already mentioned (line 136). Verify accuracy against #208. - -#### Scenario: User configures chunk size via env var -- **GIVEN** a user wants to set chunk size without editing config.yaml -- **WHEN** they read the embedding model section -- **THEN** they see `DEWEY_CHUNK_MAX_CHARS` mentioned alongside the config field - -## REMOVED Requirements - -None. diff --git a/openspec/changes/dewey-docs-sync/tasks.md b/openspec/changes/dewey-docs-sync/tasks.md deleted file mode 100644 index 1b994af..0000000 --- a/openspec/changes/dewey-docs-sync/tasks.md +++ /dev/null @@ -1,63 +0,0 @@ - - -## 1. Update Project Page (`content/docs/projects/dewey.md`) - -All tasks in this group modify the same file. No [P] markers — execute sequentially. - -- [x] 1.1 Update tool count from 48 to 50 in all locations on the page (paragraph text, section heading, section body). Refs: #41, #113 -- [x] 1.2 Add RPM to the installation section (after Homebrew, before `go install`). Ref: #186 -- [x] 1.3 Add curated knowledge stores to the key features list. Ref: #41 -- [x] 1.4 Add pluggable providers (Ollama + Vertex AI) to the key features list. Ref: #113 -- [x] 1.5 Add content sanitization to the key features list. Ref: #131 - -## 2. Update Knowledge Page (`content/docs/getting-started/knowledge.md`) - -All tasks in this group modify the same file. No [P] markers — execute sequentially. - -- [x] 2.1 Add RPM installation subsection between Homebrew and `go install`. Ref: #186 -- [x] 2.2 Add note to Homebrew section that macOS cask install issues are fixed. Ref: #213 -- [x] 2.3 Add `DEWEY_CHUNK_MAX_CHARS` to the environment variables reference table with description, config field (`embedding.max_chunk_chars`), and default value. Ref: #208 -- [x] 2.4 Add `DEWEY_SYNTHESIS_ENDPOINT` to the env var reference with fallback chain and a callout about inverted precedence (config.yaml > env var for synthesis, opposite of embedding). Ref: #243 -- [x] 2.5 Add `DEWEY_AUTHOR` to the env var reference with description (author tag for learning identities). Ref: #132 -- [x] 2.6 Add provider configuration section with separate Ollama and Vertex AI config.yaml examples. Include `embedding.provider`, `synthesis.provider`, `gcloud` auth requirements, and `region: global` endpoint behavior. Refs: #113, #240 -- [x] 2.7 Document global config path (`~/.config/dewey/config.yaml`) and per-vault override behavior. Ref: #113 -- [x] 2.8 Update `dewey doctor` reference to include the Synthesis Layer section (provider type, endpoint, model, connectivity, Ollama model availability). Update diagnostic section count from 7 to 8. Ref: #249 -- [x] 2.9 Add Vertex AI curation defaults note (16000 max output tokens, 300s timeout) to `dewey curate` or curation-related documentation. Ref: #209 -- [x] 2.10 Add content sanitization subsection: 4-layer pipeline, per-source `sanitize_mode`/`trust_tier` in `sources.yaml`, severity classifications, `dewey doctor`/`dewey lint` surfacing. Ref: #131 -- [x] 2.11 Add curated knowledge stores subsection: `dewey curate` command, `knowledge-stores.yaml` config, `curated` trust tier, background curation. Ref: #41 -- [x] 2.12 Update learning identity examples to v3.2.0 timestamped format (`{tag}-{YYYYMMDDTHHMMSS}-{author}`). Add migration note and backward compatibility info. Ref: #132 -- [x] 2.13 Add index pipeline performance note (batch embedding, concurrent source fetching). Ref: #207 - -## 3. Update Team Page (`content/docs/team/dewey.md`) - -All tasks in this group modify the same file. No [P] markers — execute sequentially. - -- [x] 3.1 Update tool count from 48 to 50 in the tool catalog header. Refs: #41, #113 -- [x] 3.2 Add `curate` tool to the Knowledge Management category in the tool catalog. Ref: #41 -- [x] 3.3 Add `store_compiled` tool to the Knowledge Management category in the tool catalog (alongside `compile`, `lint`, `promote`). Ref: #113 -- [x] 3.4 Add `DEWEY_CHUNK_MAX_CHARS` env var reference alongside `max_chunk_chars` in the embedding model section. Ref: #208 -- [x] 3.5 Add pluggable providers note to the embedding model section with link to getting-started guide. Ref: #113 - -## 4. Cross-Page Verification - -- [x] 4.1 Verify tool count is consistently 50 across all three pages -- [x] 4.2 Verify installation methods are consistent between project page and knowledge page -- [x] 4.3 Run `npm run build` and confirm zero errors -- [x] 4.4 Run `npm run dev` and visually verify all three updated pages render correctly -- [x] 4.5 Verify constitution alignment: Observable Quality — all content traceable to issue numbers, no fabricated features -- [x] 4.6 Verify provider terminology is consistent across all three pages (Ollama and Vertex AI mentioned consistently) -- [x] 4.7 Verify `DEWEY_CHUNK_MAX_CHARS` documentation is consistent between knowledge page and team page (description, default value, config field mapping) -- [x] 4.8 Verify tool count against Dewey source (confirm exactly 50 tools before publishing) - - - diff --git a/openspec/changes/slash-command-docs-update/design.md b/openspec/changes/slash-command-docs-update/design.md deleted file mode 100644 index d624ecf..0000000 --- a/openspec/changes/slash-command-docs-update/design.md +++ /dev/null @@ -1,80 +0,0 @@ -## Context - -The Unbound Force toolchain shipped a namespace migration moving all hero-specific commands from flat names to the `uf.*` namespace (e.g., `/unleash` → `/uf.unleash`). Several commands also gained significant new capabilities: soft-gate CI causality analysis, structured PR descriptions, sub-agent conflict resolution, GitHub review posting, and multi-agent issue triage. - -The website currently uses the old command names exclusively across 14+ content pages, blog posts, layout templates, and internal documentation. This design covers how to systematically update all references and document new capabilities. - -## Goals / Non-Goals - -### Goals -- Replace every old command name with its `uf.*` equivalent across all website content -- Document new command capabilities accurately (soft-gate, structured PRs, triage) -- Document new commands (`/uf.triage-issue`, `/forge`, `/org`, `/inbox`, `/handoff`) -- Preserve the persona name vs command name distinction (Cobalt-Crush as team member vs `/uf.cobalt-crush` as command) -- Ensure `npm run build` passes after all changes with no broken links or rendering issues -- Close all 7 tracked issues (#220, #221, #224, #179, #162, #204, #202) with the resulting PR - -### Non-Goals -- Creating new documentation pages for commands that don't have existing coverage (e.g., a standalone `/uf.triage-issue` tutorial) — new commands are documented within existing pages only -- Restructuring the information architecture of the docs section -- Restructuring AGENTS.md governance prose or adding new governance sections — only updating stale command name references -- Changing blog post narratives or adding new blog posts — only updating command names in existing posts -- Updating openspec artifacts or spec files that reference old command names (these are historical records) - -## Decisions - -### D1: Bulk rename approach — find-and-replace with manual review - -**Decision**: Use systematic grep + manual edit rather than automated sed replacement. - -**Rationale**: Command names appear in different contexts — code blocks, prose, headings, link anchors, URL fragments, SCSS comments. A blind find-and-replace risks breaking markdown link syntax, URL anchors (e.g., `#autonomous-pipeline-unleash` → needs to become `#autonomous-pipeline-ufunleash`?), and inline code formatting. Each file will be reviewed in context to ensure the replacement is correct for that usage. - -**Constitution alignment**: This supports Observable Quality (Principle III) — ensuring documentation accuracy through careful review rather than brittle automation. - -### D2: URL anchor handling — preserve existing anchors - -**Decision**: Keep existing URL fragment anchors unchanged (e.g., `#autonomous-pipeline-unleash` stays as-is). Only update the display text and code references. - -**Rationale**: Changing heading text that generates anchors would break all internal cross-references and any external bookmarks. Hugo generates anchors from heading text — changing "Autonomous Pipeline (`/unleash`)" to "Autonomous Pipeline (`/uf.unleash`)" would change the anchor. Instead, we update the heading display but ensure any anchor-generating headings preserve their current slug or use explicit anchor IDs. - -**Risk**: If Hugo auto-generates anchors from the new heading text, existing links break. Mitigation: Use Hugo's `{#anchor-id}` syntax or keep heading text identical where anchors are referenced, updating only code blocks and prose. - -### D3: Persona name vs command name distinction - -**Decision**: "Cobalt-Crush", "Divisor", and other persona names remain unchanged when used as team member references. Only the slash command syntax updates (e.g., "run `/cobalt-crush`" → "run `/uf.cobalt-crush`", but "the Cobalt-Crush developer agent" stays). - -**Rationale**: Personas are identities, not commands. The team page for Cobalt-Crush describes the agent's role and philosophy — the persona name is part of the brand. The command `/uf.cobalt-crush` is how users invoke that persona. - -### D4: New capability documentation — inline additions to existing pages - -**Decision**: Document new capabilities (#221, #224, #179, #162, #204) by updating the relevant sections in existing pages rather than creating new standalone pages. - -**Rationale**: The website already has comprehensive coverage of `/review-council`, `/review-pr`, and `/finale` in `common-workflows.md` and `code-review-tutorial.md`. Adding new capability details inline keeps related information together and avoids fragmenting the docs. The zero-waste mandate (AGENTS.md) also discourages creating pages without substantial standalone content. - -### D5: New command documentation — add to common-workflows.md - -**Decision**: Document `/uf.triage-issue`, `/forge`, `/org`, `/inbox`, and `/handoff` as new sections in `common-workflows.md`. - -**Rationale**: `common-workflows.md` is the central command reference page. Adding new commands there maintains the single-source pattern. If any command grows complex enough to warrant its own tutorial, that can be a follow-up change. - -### D6: Blog posts — minimal text changes only - -**Decision**: Update command names in blog posts but do not rewrite narratives or add new capability descriptions. - -**Rationale**: Blog posts are point-in-time artifacts. The narrative should remain coherent with the original publication context. Updating command names ensures readers can follow along with current tooling, but adding new capability descriptions would change the post's scope and potentially confuse the narrative arc. A future blog post can cover the namespace migration and new capabilities. - -### D7: AGENTS.md — update command references - -**Decision**: Update `/review-council` references in AGENTS.md to `/uf.review-council` since AGENTS.md is a living governance document, not a historical record. - -**Rationale**: AGENTS.md instructs agents on current processes. Using stale command names would cause agents to invoke non-existent commands. - -## Risks / Trade-offs - -- **Risk**: Heading text changes may break Hugo-generated URL anchors. **Mitigation**: Audit all heading-based anchors referenced by internal links before changing heading text. Use explicit anchor syntax where needed. - -- **Risk**: Blog post command name updates may create temporal inconsistency (post written when commands had old names, now shows new names). **Mitigation**: Accepted trade-off — readers following along need current command names. Posts do not include publication-date caveats for every command reference. - -- **Risk**: Some pages have dense command references (common-workflows.md has 50+ references). Manual editing increases the chance of missed replacements. **Mitigation**: After all edits, run a final grep sweep for any remaining old command name patterns to catch stragglers. - -- **Risk**: The code-review-tutorial.md page was recently written for `common-workflows.md` PR #74 and extensively references `/review-council` and `/review-pr`. Heavy edits may introduce formatting issues. **Mitigation**: Build verification after editing each major file. diff --git a/openspec/changes/slash-command-docs-update/proposal.md b/openspec/changes/slash-command-docs-update/proposal.md deleted file mode 100644 index 86a2555..0000000 --- a/openspec/changes/slash-command-docs-update/proposal.md +++ /dev/null @@ -1,116 +0,0 @@ -## Why - -The Unbound Force toolchain has undergone a significant slash command namespace migration — all hero-specific commands moved from flat names (`/unleash`, `/finale`, `/review-council`) to the `uf.*` namespace (`/uf.unleash`, `/uf.finale`, `/uf.review-council`). Additionally, several commands gained new capabilities: `/uf.review-council` now uses soft-gate CI causality analysis, `/uf.review-pr` posts verdicts for all review outcomes, `/uf.finale` supports sub-agent merge conflict resolution and structured PR descriptions with AI attribution, and a new `/uf.triage-issue` command was added for multi-agent issue triage. - -The website currently uses the old command names exclusively across 14+ content pages, 1 layout template, blog posts, and internal documentation. Every reference is stale. Visitors following the documentation will encounter command names that no longer exist in the shipped toolchain. - -This change updates all website documentation to reflect the current state of the shipped commands, covering 7 tracked issues: #220, #221, #224, #179, #162, #204, #202. - -## What Changes - -1. **Namespace migration across all content** (#220): Replace every old command name with its `uf.*` equivalent across all pages, blog posts, templates, and configuration files. Add documentation for new commands (`/uf.triage-issue`) and new non-namespaced commands (`/forge`, `/forge:status`, `/org`, `/inbox`, `/handoff`). - -2. **Review council soft-gate documentation** (#221): Update all `/uf.review-council` documentation to reflect the soft-gate CI causality analysis behavior — pre-existing CI failures on `main` no longer block reviews. Document the two-tier baseline strategy (GitHub CI API check first, git worktree fallback). - -3. **Review PR verdict posting** (#224): Update `/uf.review-pr` documentation to reflect that verdict posting now appears for all review outcomes regardless of finding severity, not just for CRITICAL/HIGH findings. - -4. **GitHub review posting** (#179): Document the ability to post review council findings as GitHub PR reviews, including PR detection, multi-persona aggregation, verdict mapping (APPROVE/REQUEST_CHANGES/COMMENT), and the human confirmation requirement. - -5. **Finale structured PR descriptions** (#162): Document the structured PR body format (Summary, How to Test, How to Demo, Key Files Changed), AI attribution footer and git trailer, PR template detection, and review-council findings integration. - -6. **Finale sub-agent merge conflict resolution** (#204): Document the new Option 5 in conflict recovery — spawning a sub-agent for AI-assisted merge conflict resolution. - -7. **Triage-issue command** (#202): Add documentation for the new `/uf.triage-issue` command — multi-agent issue triage using 5 Divisor agents with 7 classification categories and structured output. - -## Capabilities - -### New Capabilities -- `triage-issue-docs`: Documentation for `/uf.triage-issue` multi-agent issue triage command -- `forge-command-docs`: Documentation for `/forge`, `/forge:status` commands -- `session-command-docs`: Documentation for `/org`, `/inbox`, `/handoff` session management commands -- `github-review-posting-docs`: Documentation for posting review council findings as GitHub PR reviews -- `conflict-sub-agent-docs`: Documentation for AI-assisted merge conflict resolution in `/uf.finale` -- `structured-pr-docs`: Documentation for structured PR descriptions and AI attribution - -### Modified Capabilities -- `command-references`: All old command names (`/unleash`, `/finale`, `/cobalt-crush`, `/review-council`, `/constitution-check`, `/uf-init`) replaced with `uf.*` namespace equivalents -- `review-council-docs`: Updated to reflect soft-gate CI causality behavior and GitHub review posting -- `review-pr-docs`: Updated to reflect verdict posting for all outcomes -- `finale-docs`: Updated to include structured PR bodies, AI attribution, and sub-agent conflict resolution -- `code-review-tutorial`: Updated with new command names and new capabilities - -### Removed Capabilities -- None — all old capabilities are preserved under new names - -## Impact - -### Files requiring changes (identified via grep) - -**Documentation pages** (primary content): -- `content/docs/getting-started/common-workflows.md` — heaviest impact; `/unleash`, `/finale`, `/cobalt-crush`, `/review-council` references throughout -- `content/docs/getting-started/developer.md` — `/unleash`, `/finale`, `/cobalt-crush` references in workflows and examples -- `content/docs/getting-started/quick-start.md` — `/unleash`, `/finale`, `/cobalt-crush` in code examples -- `content/docs/getting-started/code-review-tutorial.md` — `/review-council`, `/review-pr` throughout -- `content/docs/getting-started/tester.md` — `/review-council` reference -- `content/docs/getting-started/product-owner.md` — `/unleash` reference -- `content/docs/getting-started/architecture.md` — `/unleash`, `/review-council`, `/cobalt-crush` references -- `content/docs/getting-started/_index.md` — `/cobalt-crush`, `/unleash` references -- `content/docs/getting-started/constitution.md` — `/unleash`, `/review-council`, `/constitution-check` references - -**Team pages** (reviewed — no command references, persona names only): -- `content/docs/team/_index.md` — "Cobalt-Crush" persona name only, no slash command invocations -- `content/docs/team/cobalt-crush.md` — persona page, no slash command invocations - -**Blog posts**: -- `content/blog/unleash-in-practice.md` — heavy `/unleash` and `/finale` usage throughout -- `content/blog/dewey-vs-karpathy.md` — `/unleash` reference -- `content/blog/five-principles-every-ai-agent-harness-discovers.md` — `/unleash` reference -- `content/blog/sandbox-isolation.md` — `/unleash` reference -- `content/blog/the-8-phase-pipeline.md` — `/unleash` reference - -**Layout templates**: -- `layouts/home.html` — `/unleash` in hero section code reference - -**SCSS**: -- `assets/scss/common/_custom.scss` — comment referencing `/unleash` card - -**Internal docs** (AGENTS.md): -- `AGENTS.md` — `/review-council` references in Review Council section - -### Key distinction: command name vs persona name - -"Cobalt-Crush" is both a persona name (the team member identity) and a command name (`/cobalt-crush` → `/uf.cobalt-crush`). The persona name stays unchanged on team pages; only the slash command invocation updates. Same applies to other team pages — the persona names are not changing, only the `/command` syntax. - -## Constitution Alignment - -Assessed against the Unbound Force org constitution. - -### I. Autonomous Collaboration - -**Assessment**: N/A - -This change updates documentation content only. No agent artifacts, communication protocols, or artifact formats are affected. Agents continue to collaborate through the same well-defined artifacts — the documentation simply reflects the current command names accurately. - -### II. Composability First - -**Assessment**: N/A - -Documentation changes do not affect agent installability or standalone functionality. The commands being documented maintain their composable nature — this change ensures the documentation accurately reflects that composability. - -### III. Observable Quality - -**Assessment**: PASS - -This change improves observable quality by ensuring documentation matches shipped behavior. Visitors reading the docs will get accurate command names and accurate descriptions of capabilities (soft-gate CI analysis, structured PRs, verdict posting), reducing confusion and failed attempts to use non-existent command names. - -### IV. Testability - -**Assessment**: N/A - -No code, tests, or testable components are affected. The website has no test suite — validation is manual via `npm run build` and visual verification, which will be performed as part of the implementation CI parity gate. - -### V. Security by Default - -**Assessment**: N/A - -Documentation-only changes with no security implications. No dependencies added, no external inputs processed, no permissions changed. diff --git a/openspec/changes/slash-command-docs-update/specs/command-namespace-migration.md b/openspec/changes/slash-command-docs-update/specs/command-namespace-migration.md deleted file mode 100644 index d5842fa..0000000 --- a/openspec/changes/slash-command-docs-update/specs/command-namespace-migration.md +++ /dev/null @@ -1,132 +0,0 @@ -## ADDED Requirements - -### Requirement: Namespace migration completeness - -All slash command references in user-facing website content MUST use the `uf.*` namespace for hero-specific commands. The following mappings MUST be applied: - -| Old Name | New Name | -|----------|----------| -| `/unleash` | `/uf.unleash` | -| `/finale` | `/uf.finale` | -| `/cobalt-crush` | `/uf.cobalt-crush` | -| `/constitution-check` | `/uf.constitution-check` | -| `/review-council` | `/uf.review-council` | -| `/uf-init` | `/uf.init` | -| `/review-pr` | `/uf.review-pr` | - -Non-namespaced commands (`/forge`, `/forge:status`, `/org`, `/inbox`, `/handoff`) and Speckit commands (`/speckit.*`) are NOT affected by the namespace migration. - -#### Scenario: Visitor reads documentation with current command names -- **GIVEN** a visitor reading any page under `content/docs/` or `content/blog/` -- **WHEN** they encounter a slash command reference for a hero-specific command -- **THEN** the command MUST use the `uf.*` namespace (e.g., `/uf.unleash` not `/unleash`) - -#### Scenario: Persona names remain unchanged -- **GIVEN** a visitor reading a team page or a prose reference to an agent persona -- **WHEN** the text refers to the persona by name (e.g., "Cobalt-Crush", "the Divisor") -- **THEN** the persona name MUST remain unchanged — only slash command invocations update - -#### Scenario: URL anchors preserved -- **GIVEN** an internal link referencing a heading-generated anchor (e.g., `#autonomous-pipeline-unleash`) -- **WHEN** the heading text is updated to use the new command name -- **THEN** the anchor MUST remain functional — either by preserving the original anchor text or using explicit Hugo anchor syntax - -### Requirement: New command documentation - -The website MUST document the following new commands in the Common Workflows page (`content/docs/getting-started/common-workflows.md`): - -- `/uf.triage-issue` — multi-agent issue triage using 5 Divisor agents -- `/forge` and `/forge:status` — swarm coordination commands -- `/org` — work item management -- `/inbox` — message inbox -- `/handoff` — session handoff - -#### Scenario: Visitor discovers new triage command -- **GIVEN** a visitor reading the Common Workflows page -- **WHEN** they scroll to the command reference sections -- **THEN** they MUST find documentation for `/uf.triage-issue` including its purpose (multi-agent issue evaluation), agent count (5 Divisor agents), classification categories, and the human-gated label mutation behavior - -#### Scenario: Visitor discovers session management commands -- **GIVEN** a visitor reading the Common Workflows page -- **WHEN** they look for session management workflows -- **THEN** they MUST find documentation for `/org`, `/inbox`, and `/handoff` commands - -### Requirement: Soft-gate CI causality documentation - -The website MUST document that `/uf.review-council` uses soft-gate CI causality analysis. Pre-existing CI failures on `main` MUST be described as non-blocking informational findings. - -#### Scenario: Visitor understands CI failure handling -- **GIVEN** a visitor reading `/uf.review-council` documentation -- **WHEN** they read about CI failure handling -- **THEN** the documentation MUST explain that pre-existing failures on `main` do not block the review verdict -- **AND** the two-tier baseline strategy (GitHub CI API check, git worktree fallback) SHOULD be mentioned - -### Requirement: Verdict posting for all outcomes - -The website MUST document that `/uf.review-pr` posts verdicts for all review outcomes, not just CRITICAL/HIGH findings. - -#### Scenario: Visitor understands verdict posting -- **GIVEN** a visitor reading `/uf.review-pr` documentation -- **WHEN** they read about the review verdict step -- **THEN** the documentation MUST state that verdict posting occurs regardless of finding severity level - -### Requirement: GitHub review posting - -The website MUST document that `/uf.review-council` findings can be posted as GitHub PR reviews. - -#### Scenario: Visitor understands GitHub review posting -- **GIVEN** a visitor reading review command documentation -- **WHEN** they read about post-review actions -- **THEN** the documentation MUST describe PR detection, verdict mapping (APPROVE/REQUEST_CHANGES/COMMENT), and the human confirmation requirement - -### Requirement: Structured PR descriptions - -The website MUST document that `/uf.finale` generates structured PR descriptions with the following sections: Summary, How to Test, How to Demo, Key Files Changed. - -#### Scenario: Visitor understands PR description format -- **GIVEN** a visitor reading `/uf.finale` documentation -- **WHEN** they read about PR creation -- **THEN** the documentation MUST describe the structured PR body format and the AI attribution footer - -### Requirement: Sub-agent merge conflict resolution - -The website MUST document that `/uf.finale` supports AI-assisted merge conflict resolution via a spawned sub-agent. - -#### Scenario: Visitor understands conflict resolution options -- **GIVEN** a visitor reading `/uf.finale` documentation -- **WHEN** they read about merge conflict handling -- **THEN** the documentation MUST describe the sub-agent conflict resolution option alongside existing manual options - -## MODIFIED Requirements - -### Requirement: AGENTS.md command references - -AGENTS.md MUST use `/uf.review-council` instead of `/review-council` in the Review Council as PR Prerequisite section. - -Previously: AGENTS.md referenced `/review-council` (old flat namespace). - -#### Scenario: AGENTS.md uses current command names -- **GIVEN** an agent reading AGENTS.md for workflow guidance -- **WHEN** they encounter the Review Council section -- **THEN** the command reference MUST be `/uf.review-council` - -### Requirement: Layout template command references - -The homepage layout template (`layouts/home.html`) MUST reference `/uf.unleash` instead of `/unleash`. - -Previously: The template used `/unleash` in the hero section. - -#### Scenario: Homepage displays current command name -- **GIVEN** a visitor viewing the homepage -- **WHEN** they read the hero section or feature cards -- **THEN** the command reference MUST be `/uf.unleash` - -### Requirement: Code review tutorial command references - -The code review tutorial (`content/docs/getting-started/code-review-tutorial.md`) MUST use `/uf.review-council` and `/uf.review-pr` throughout. - -Previously: The tutorial used `/review-council` and `/review-pr`. - -## REMOVED Requirements - -None — no existing requirements are being removed. All capabilities are preserved under new command names. diff --git a/openspec/changes/slash-command-docs-update/tasks.md b/openspec/changes/slash-command-docs-update/tasks.md deleted file mode 100644 index 6258aac..0000000 --- a/openspec/changes/slash-command-docs-update/tasks.md +++ /dev/null @@ -1,68 +0,0 @@ - - -## 1. Namespace Migration — Documentation Pages (#220) - -Update all hero-specific slash command references to the `uf.*` namespace in documentation pages. Each task touches a different file so all are parallel-eligible. - -- [x] 1.1 [P] Update `content/docs/getting-started/common-workflows.md`: Replace all `/unleash` → `/uf.unleash`, `/finale` → `/uf.finale`, `/cobalt-crush` → `/uf.cobalt-crush`, `/review-council` → `/uf.review-council` references. Preserve heading anchor slugs by using Hugo `{#anchor-id}` syntax where headings are referenced by internal links (e.g., keep `{#autonomous-pipeline-unleash}` anchor on the renamed heading). Add new sections for `/uf.triage-issue`, `/forge`, `/forge:status`, `/org`, `/inbox`, `/handoff` commands. -- [x] 1.2 [P] Update `content/docs/getting-started/developer.md`: Replace all `/unleash` → `/uf.unleash`, `/finale` → `/uf.finale`, `/cobalt-crush` → `/uf.cobalt-crush` references. Distinguish persona name "Cobalt-Crush" (unchanged) from command `/uf.cobalt-crush` (updated). -- [x] 1.3 [P] Update `content/docs/getting-started/quick-start.md`: Replace `/unleash` → `/uf.unleash`, `/finale` → `/uf.finale`, `/cobalt-crush` → `/uf.cobalt-crush` in code examples and prose. -- [x] 1.4 [P] Update `content/docs/getting-started/code-review-tutorial.md`: Replace all `/review-council` → `/uf.review-council`, `/review-pr` → `/uf.review-pr`, `/finale` → `/uf.finale`, `/unleash` → `/uf.unleash` references throughout the tutorial. -- [x] 1.5 [P] Update `content/docs/getting-started/tester.md`: Replace `/review-council` → `/uf.review-council`. -- [x] 1.6 [P] Update `content/docs/getting-started/product-owner.md`: Replace `/unleash` → `/uf.unleash`. -- [x] 1.7 [P] Update `content/docs/getting-started/architecture.md`: Replace `/unleash` → `/uf.unleash`, `/review-council` → `/uf.review-council`, `/cobalt-crush` → `/uf.cobalt-crush` references. Keep persona name references unchanged. -- [x] 1.8 [P] Update `content/docs/getting-started/_index.md`: Replace `/unleash` → `/uf.unleash`, `/cobalt-crush` → `/uf.cobalt-crush` references. Keep persona name "Cobalt-Crush" unchanged. -- [x] 1.9 [P] Update `content/docs/getting-started/constitution.md`: Replace `/unleash` → `/uf.unleash`, `/review-council` → `/uf.review-council`, `/constitution-check` → `/uf.constitution-check` references. - -## 2. Namespace Migration — Blog Posts (#220) - -Update command references in blog posts. Each task touches a different file. - -- [x] 2.1 [P] Update `content/blog/unleash-in-practice.md`: Replace all `/unleash` → `/uf.unleash`, `/finale` → `/uf.finale` references. This file has the highest density of command references (~40+). Keep narrative coherent — update command names only, do not rewrite prose. -- [x] 2.2 [P] Update `content/blog/dewey-vs-karpathy.md`: Replace `/unleash` → `/uf.unleash`. -- [x] 2.3 [P] Update `content/blog/five-principles-every-ai-agent-harness-discovers.md`: Replace `/unleash` → `/uf.unleash`. -- [x] 2.4 [P] Update `content/blog/sandbox-isolation.md`: Replace `/unleash` → `/uf.unleash`. -- [x] 2.5 [P] Update `content/blog/the-8-phase-pipeline.md`: Replace `/unleash` → `/uf.unleash`. - -## 3. Namespace Migration — Templates, Styles, and Internal Docs (#220) - -- [x] 3.1 [P] Update `layouts/home.html`: Replace `/unleash` → `/uf.unleash` in the hero section code reference. -- [x] 3.2 [P] Update `assets/scss/common/_custom.scss`: Replace `/unleash` → `/uf.unleash` in the featured card comment. -- [x] 3.3 [P] Update `AGENTS.md`: Replace `/review-council` → `/uf.review-council` in the Review Council as PR Prerequisite section. Also update any other stale command references. - -## 4. New Capability Documentation — Review Commands (#221, #224, #179) - -These tasks modify `common-workflows.md` and `code-review-tutorial.md` (already touched in Group 1). They MUST run sequentially after Group 1. - -- [x] 4.1 Update the `/uf.review-council` section in `content/docs/getting-started/common-workflows.md`: Add documentation for soft-gate CI causality analysis — pre-existing CI failures on `main` are non-blocking informational findings. Describe the two-tier baseline strategy (GitHub CI API check first, git worktree fallback). Document GitHub review posting capability — PR detection, verdict mapping (APPROVE/REQUEST_CHANGES/COMMENT), human confirmation requirement. -- [x] 4.2 Update the `/uf.review-pr` section in `content/docs/getting-started/common-workflows.md`: Document that verdict posting now occurs for all review outcomes regardless of finding severity (previously skipped for MEDIUM/LOW-only or zero-finding reviews). -- [x] 4.3 Update `content/docs/getting-started/code-review-tutorial.md`: Add coverage of soft-gate CI behavior and GitHub review posting to the relevant tutorial sections. - -## 5. New Capability Documentation — Finale Command (#162, #204) - -These tasks modify `common-workflows.md` (already touched in Groups 1 and 4). They MUST run sequentially after Group 4. - -- [x] 5.1 Update the `/uf.finale` section in `content/docs/getting-started/common-workflows.md`: Document structured PR body format (Summary, How to Test, How to Demo, Key Files Changed), AI attribution footer and git trailer (`AI-assisted-by: /uf.finale`), and PR template detection. -- [x] 5.2 Update the `/uf.finale` section in `content/docs/getting-started/common-workflows.md`: Document the new sub-agent merge conflict resolution option (Option 5 in conflict recovery) — spawning a sub-agent to merge the target branch, identify conflicts, and resolve them with AI assistance. - -## 6. New Command Documentation — Triage Issue (#202) - -- [x] 6.1 Add a new section to `content/docs/getting-started/common-workflows.md` for `/uf.triage-issue`: Describe the multi-agent issue triage using 5 Divisor agents, 7 classification categories (bug, feature, enhancement, question, opinion, duplicate, needs-info), structured triage output with severity/priority/labels, and human-gated label mutations via AskUserQuestion. - -## 7. Verification and Build - -- [x] 7.1 Run `grep -rn` across `content/`, `layouts/`, `AGENTS.md` for any remaining old command names (`/unleash`, `/finale`, `/cobalt-crush`, `/constitution-check`, `/review-council`, `/uf-init`, `/review-pr`) that were missed. Fix any stragglers. Exclude `openspec/` and `specs/` directories (historical records). -- [x] 7.2 Run `npm run build` and verify no build errors. Check for broken internal links caused by anchor changes. -- [x] 7.3 Verify constitution alignment: confirm documentation changes are content-only with no agent behavior, artifact format, composability, or testability implications (all N/A per proposal). - - diff --git a/openspec/changes/vision-roadmap-pages/.openspec.yaml b/openspec/changes/vision-roadmap-pages/.openspec.yaml deleted file mode 100644 index 0d97165..0000000 --- a/openspec/changes/vision-roadmap-pages/.openspec.yaml +++ /dev/null @@ -1,2 +0,0 @@ -schema: unbound-force -created: 2026-08-31 diff --git a/openspec/changes/vision-roadmap-pages/design.md b/openspec/changes/vision-roadmap-pages/design.md deleted file mode 100644 index 8ab6470..0000000 --- a/openspec/changes/vision-roadmap-pages/design.md +++ /dev/null @@ -1,62 +0,0 @@ -## Context - -The Unbound Force organization maintains `VISION.md` and `ROADMAP.md` in the `unbound-force/unbound-force` repository. These documents define the project's purpose, principles, and trajectory. Currently they are only accessible to developers who browse the source repository — website visitors have no way to discover them. - -The website uses Hugo with the Doks theme (`@thulite/doks-core`). Content lives in `content/docs/` as Markdown files organized into sections. Navigation is configured in `config/_default/menus/menus.en.toml` with separate `[[docs]]` (sidebar) and `[[main]]` (top nav bar) entries. - -## Goals / Non-Goals - -### Goals -- Publish Vision and Roadmap as first-class documentation pages on unboundforce.dev -- Place both pages prominently: top of docs sidebar and in the main navigation bar -- Preserve all source content substance — adapt only formatting for Hugo/Doks compatibility -- Ensure all cross-references (GitHub issues, discussions, org links) render as working hyperlinks - -### Non-Goals -- Auto-syncing content from the upstream repository (manual updates are acceptable) -- Custom layouts or shortcodes — use standard Doks Markdown rendering -- Restructuring existing documentation sections or their weights -- Adding a dedicated "About" or "Community" section — Vision and Roadmap are standalone docs sections - -## Decisions - -### D1: Standalone sections, not nested under an existing section - -Each document becomes its own top-level docs section (`content/docs/vision/_index.md` and `content/docs/roadmap/_index.md`) rather than being nested under "Getting Started" or a new "About" section. This keeps the sidebar clean, gives each page its own section heading, and avoids creating a parent section that would only contain two children. - -### D2: Section index files (`_index.md`) for content - -Using `_index.md` (section index) rather than a plain `page.md` ensures Hugo treats each as a section root. This is the Doks convention for top-level sidebar entries and allows future sub-pages if the content grows. - -### D3: Weight ordering — Vision before Roadmap, both before Getting Started - -- Vision: sidebar weight 5, main nav weight 2 -- Roadmap: sidebar weight 6, main nav weight 3 -- Getting Started remains at sidebar weight 10, Blog remains at main nav weight 5 - -This positions Vision and Roadmap as the first things visitors see, establishing context before they dive into practical guides. - -### D4: Content adaptation approach - -Source Markdown is adapted minimally: -- Add Hugo YAML frontmatter (`title`, `description`, `lead`, `date`, `weight`, `toc`, `draft`) -- Convert H1 (`#`) to H2 (`##`) since the `title` frontmatter generates the H1 -- Shift all heading levels down by one accordingly -- Replace `[VISION.md](VISION.md)` cross-reference in ROADMAP with `[Vision](/docs/vision/)` -- Preserve all external GitHub URLs as-is (they're already fully qualified) -- Preserve all list structures, bold text, and inline formatting - -### D5: No custom CSS or layout overrides - -Both pages use standard Doks Markdown rendering. The Doks theme handles table of contents, heading anchors, dark mode, and responsive layout automatically. No custom SCSS, shortcodes, or template overrides needed. - -## Risks / Trade-offs - -### Content drift -The website pages are static copies, not synced from the upstream repository. If `VISION.md` or `ROADMAP.md` changes upstream, the website will become stale. **Mitigation**: This is acceptable for now — these documents change infrequently, and auto-sync would add complexity disproportionate to the update frequency. - -### Sidebar prominence -Placing Vision and Roadmap above Getting Started may surprise visitors who expect practical docs first. **Mitigation**: The titles are self-explanatory, and Getting Started remains easily accessible at weight 10. Visitors looking for practical guidance can find it quickly. - -### Heading level shift -Shifting all headings down by one level to accommodate Hugo's H1-from-title convention could affect readability if the source documents use deeply nested headings. **Mitigation**: Both source documents use H2 and H3 only, so the shift produces H2 and H3 (plus occasional H4) — well within readable range. diff --git a/openspec/changes/vision-roadmap-pages/proposal.md b/openspec/changes/vision-roadmap-pages/proposal.md deleted file mode 100644 index b2cc1a7..0000000 --- a/openspec/changes/vision-roadmap-pages/proposal.md +++ /dev/null @@ -1,61 +0,0 @@ -## Why - -GitHub issue [#270](https://github.com/unbound-force/website/issues/270) requests publishing the org-level `VISION.md` and `ROADMAP.md` documents as pages on unboundforce.dev. These documents define what Unbound Force is, where it's going, and why — but they're currently buried in the `unbound-force/unbound-force` repository where website visitors can't find them. Making them prominent website pages gives visitors immediate access to the project's direction and maturity. - -## What Changes - -- **Two new documentation sections** added to the site: Vision (`content/docs/vision/_index.md`) and Roadmap (`content/docs/roadmap/_index.md`). -- **Main navigation bar** updated to include Vision and Roadmap links (before Blog). -- **Docs sidebar** updated with Vision (weight 5) and Roadmap (weight 6) at the top, before Getting Started (weight 10). -- Content adapted from source Markdown to Hugo frontmatter format. Substance preserved exactly; only formatting adjusted for the Doks theme. -- Internal cross-reference (`[VISION.md](VISION.md)` in ROADMAP) rewritten as site-relative link (`[Vision](/docs/vision/)`). -- All external GitHub issue/discussion links preserved as full URLs. - -## Capabilities - -### New Capabilities -- `vision-page`: Publishes the Unbound Force vision statement as a docs page at `/docs/vision/` -- `roadmap-page`: Publishes the project roadmap as a docs page at `/docs/roadmap/` -- `nav-visibility`: Both pages accessible from main nav bar and docs sidebar - -### Modified Capabilities -- `site-navigation`: Main nav gains two new entries (Vision weight 2, Roadmap weight 3); docs sidebar gains two new sections (weights 5 and 6) - -### Removed Capabilities -- None - -## Impact - -- **Files created**: `content/docs/vision/_index.md`, `content/docs/roadmap/_index.md` -- **Files modified**: `config/_default/menus/menus.en.toml` -- **No code changes**: This is a docs-only change — Markdown content and TOML config only -- **No build system impact**: Standard Hugo content pages using Doks theme defaults -- **Navigation shift**: Existing sidebar sections (Getting Started, Projects, etc.) remain at their current weights but shift visually downward as Vision and Roadmap appear above them - -## Constitution Alignment - -Assessed against the Unbound Force org constitution. - -### I. Autonomous Collaboration - -**Assessment**: N/A - -This change adds static documentation pages to the website. It does not introduce runtime coupling or modify artifact-based communication between heroes. - -### II. Composability First - -**Assessment**: PASS - -The new pages are standard Hugo Markdown files with no custom layouts or dependencies. They use the Doks theme's built-in rendering. Either page can be added or removed independently without affecting the other or any existing pages. - -### III. Observable Quality - -**Assessment**: N/A - -This change produces static HTML documentation. It does not generate machine-parseable output or require provenance metadata — it publishes existing organizational documents. - -### IV. Testability - -**Assessment**: PASS - -The change is validated by `npm run build` (Hugo build succeeds), visual inspection (pages render correctly in light and dark mode), and link verification (all cross-references resolve). No external services required. diff --git a/openspec/changes/vision-roadmap-pages/specs/vision-roadmap.md b/openspec/changes/vision-roadmap-pages/specs/vision-roadmap.md deleted file mode 100644 index ac58ad9..0000000 --- a/openspec/changes/vision-roadmap-pages/specs/vision-roadmap.md +++ /dev/null @@ -1,87 +0,0 @@ -## ADDED Requirements - -### Requirement: Vision Page - -The site MUST publish a Vision page at `/docs/vision/` containing the full content of the org-level `VISION.md` document. The page MUST include Hugo YAML frontmatter with `title`, `description`, `lead`, `date`, `weight: 5`, `toc: true`, and `draft: false`. Body content MUST start with H2 headings (title frontmatter generates H1). The page MUST preserve all substantive content from the source document without additions, removals, or editorial changes. - -#### Scenario: Vision page renders correctly - -- **GIVEN** a visitor navigates to `https://unboundforce.dev/docs/vision/` -- **WHEN** the page loads -- **THEN** the page displays the full Vision content with a table of contents, all headings render as navigable anchors, and the page renders correctly in both light and dark mode - -#### Scenario: Vision page appears in sidebar - -- **GIVEN** a visitor is on any docs page -- **WHEN** they view the sidebar navigation -- **THEN** "Vision" appears as the first item (weight 5), above "Getting Started" (weight 10) - -### Requirement: Roadmap Page - -The site MUST publish a Roadmap page at `/docs/roadmap/` containing the full content of the org-level `ROADMAP.md` document. The page MUST include Hugo YAML frontmatter with `title`, `description`, `lead`, `date`, `weight: 6`, `toc: true`, and `draft: false`. Body content MUST start with H2 headings. The page MUST preserve all substantive content from the source document without additions, removals, or editorial changes. - -#### Scenario: Roadmap page renders correctly - -- **GIVEN** a visitor navigates to `https://unboundforce.dev/docs/roadmap/` -- **WHEN** the page loads -- **THEN** the page displays the full Roadmap content with a table of contents, all horizon sections are present, and the page renders correctly in both light and dark mode - -#### Scenario: Roadmap page appears in sidebar - -- **GIVEN** a visitor is on any docs page -- **WHEN** they view the sidebar navigation -- **THEN** "Roadmap" appears as the second item (weight 6), after "Vision" (weight 5) and before "Getting Started" (weight 10) - -### Requirement: Main Navigation Entries - -The site MUST add "Vision" and "Roadmap" entries to the main navigation bar. "Vision" MUST have weight 2 and link to `/docs/vision/`. "Roadmap" MUST have weight 3 and link to `/docs/roadmap/`. Both MUST appear before "Blog" (weight 5) and "GitHub" (weight 10). - -#### Scenario: Main nav displays Vision and Roadmap - -- **GIVEN** a visitor is on any page of the site -- **WHEN** they view the main navigation bar -- **THEN** the nav items appear in order: Vision, Roadmap, Blog, GitHub - -### Requirement: Docs Sidebar Entries - -The site MUST add `[[docs]]` entries for Vision (weight 5, identifier `vision`, url `/docs/vision/`) and Roadmap (weight 6, identifier `roadmap`, url `/docs/roadmap/`) in `menus.en.toml`. - -#### Scenario: Sidebar ordering is correct - -- **GIVEN** a visitor views the docs sidebar -- **WHEN** they scan the section list -- **THEN** sections appear in order: Vision (5), Roadmap (6), Getting Started (10), Projects (20), The Team (30), Reference (35), Changelog (38), Contributing (40) - -### Requirement: Cross-Reference Links - -All GitHub issue links (e.g., `https://github.com/unbound-force/unbound-force/issues/509`) and discussion links (e.g., `https://github.com/unbound-force/unbound-force/discussions/399`) in the Roadmap page MUST render as working hyperlinks. The internal cross-reference from Roadmap to Vision MUST use the site-relative path `/docs/vision/` instead of the source repository's `VISION.md`. - -#### Scenario: GitHub links are clickable - -- **GIVEN** a visitor is on the Roadmap page -- **WHEN** they click a GitHub issue link -- **THEN** they are navigated to the correct GitHub issue page - -#### Scenario: Vision cross-reference works - -- **GIVEN** a visitor is on the Roadmap page -- **WHEN** they click the reference to the Vision document -- **THEN** they are navigated to `/docs/vision/` on the same site - -### Requirement: Hugo Build Success - -The site MUST build successfully with `npm run build` (Hugo `--minify --gc`) after these changes are applied. No warnings or errors related to the new pages SHALL be produced. - -#### Scenario: Clean build - -- **GIVEN** the Vision and Roadmap pages and menu entries have been added -- **WHEN** `npm run build` is executed -- **THEN** the build completes with exit code 0 and no errors - -## MODIFIED Requirements - -No existing requirements are modified by this change. - -## REMOVED Requirements - -No existing requirements are removed by this change. diff --git a/openspec/changes/vision-roadmap-pages/tasks.md b/openspec/changes/vision-roadmap-pages/tasks.md deleted file mode 100644 index e90096e..0000000 --- a/openspec/changes/vision-roadmap-pages/tasks.md +++ /dev/null @@ -1,29 +0,0 @@ - - -## 1. Create Content Pages - -- [x] 1.1 [P] Create `content/docs/vision/_index.md` — adapt VISION.md from `/Users/jflowers/Projects/github/unbound-force/VISION.md` with Hugo YAML frontmatter (title, description, lead, date, weight: 5, toc: true, draft: false). Shift all headings down one level (H1→H2, H2→H3, etc.). Preserve all substantive content. -- [x] 1.2 [P] Create `content/docs/roadmap/_index.md` — adapt ROADMAP.md from `/Users/jflowers/Projects/github/unbound-force/ROADMAP.md` with Hugo YAML frontmatter (title, description, lead, date, weight: 6, toc: true, draft: false). Shift all headings down one level. Replace `[VISION.md](VISION.md)` with `[Vision](/docs/vision/)`. Preserve all GitHub issue/discussion URLs as-is. - -## 2. Update Navigation - -- [x] 2.1 Add `[[docs]]` entries for Vision (weight 5, identifier "vision", url "/docs/vision/") and Roadmap (weight 6, identifier "roadmap", url "/docs/roadmap/") to `config/_default/menus/menus.en.toml`. Place them before the existing Getting Started entry. -- [x] 2.2 Add `[[main]]` entries for Vision (weight 2, url "/docs/vision/") and Roadmap (weight 3, url "/docs/roadmap/") to `config/_default/menus/menus.en.toml`. Place them before the existing Blog entry. - -## 3. Validation - -- [x] 3.1 Run `npm run build` and verify exit code 0 with no errors or warnings related to the new pages. -- [x] 3.2 Verify constitution alignment: Composability (each page is independently removable) and Testability (build validates without external services) — both assessed as PASS in proposal. - - -