Add Confluence bridge workflow

CHANGELOG.md

@@ -6,6 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.4.0] — 2026-05-18
+
+### Added
+- Confluence bridge commands for pulling wiki pages into local spec context, publishing spec
+  summaries, and syncing existing Confluence pages from approved artifacts.
+- Confluence integration docs and tutorial for knowledge-base context workflows.
+
 ## [1.3.0] — 2026-05-18
 
 ### Added

README.md

@@ -41,6 +41,7 @@ become clear.
 | Warehouse guidance | Pick the closest warehouse preset for cost, materialization, SQL dialect, and governance guardrails. The project still runs through your normal dbt adapter and database connection. | [Warehouse guides](docs/warehouse-guides) |
 | CI evidence | Start with local `validate` and `report`; promote `dbt-specify ci` when the team wants lifecycle checks to block PRs. | [Enterprise CI](docs/enterprise-ci.md) |
 | Jira integration | Pull Jira issues into local specs, attach approved specs/plans back to Jira, and create Jira subtasks from `tasks.md`. | [Jira integration](docs/integrations/jira.md) |
+| Confluence integration | Pull approved wiki context into `specs/<NNN>/context/` and publish spec summaries back to Confluence. | [Confluence integration](docs/integrations/confluence.md) |
 
 The key repo hygiene rule: keep approved decision records, not raw agent scratch work.
 
@@ -193,6 +194,28 @@ uvx --from dbt-spec-kit dbt-specify jira create-tasks NBA-123 \
 Jira remains intake and tracking. `spec.md` and `plan.md` remain the approved engineering contract.
 See [Jira integration](docs/integrations/jira.md).
 
+## Confluence bridge
+
+For teams that use Confluence as the knowledge base:
+
+```bash
+export CONFLUENCE_BASE_URL="https://your-company.atlassian.net"
+export CONFLUENCE_EMAIL="you@company.com"
+export CONFLUENCE_API_TOKEN="<atlassian-api-token>"
+
+uvx --from dbt-spec-kit dbt-specify confluence pull-page 123456789 \
+  --to specs/001-player-journey/context/player-metrics.md
+uvx --from dbt-spec-kit dbt-specify confluence publish \
+  --spec-dir specs/001-player-journey \
+  --space-key DATA \
+  --parent-id 987654321
+uvx --from dbt-spec-kit dbt-specify confluence sync \
+  --spec-dir specs/001-player-journey
+```
+
+Confluence remains the knowledge base. `spec.md`, `plan.md`, and `tasks.md` remain the approved
+implementation contract. See [Confluence integration](docs/integrations/confluence.md).
+
 ## Who this is for
 
 - Analytics engineers who want AI help without losing dbt conventions.
@@ -211,6 +234,7 @@ See [Jira integration](docs/integrations/jira.md).
 - [Skills and sub-agents](docs/skills-and-sub-agents.md)
 - [Enterprise CI](docs/enterprise-ci.md)
 - [Jira integration](docs/integrations/jira.md)
+- [Confluence integration](docs/integrations/confluence.md)
 - [Brownfield onboarding](docs/brownfield-onboarding.md)
 - [EARS cheatsheet](docs/ears-cheatsheet.md)
 - [Releasing to PyPI](docs/releasing.md)

docs/integrations/confluence.md

@@ -0,0 +1,137 @@
+# Confluence integration
+
+The Confluence bridge lets teams use wiki pages as approved business and architecture context
+without turning the wiki into the source of truth for dbt implementation.
+
+```text
+Confluence context -> local context markdown -> spec.md -> plan.md -> Confluence summary page
+```
+
+Confluence is for shared knowledge. The local `spec.md`, `plan.md`, and `tasks.md` files remain the
+implementation contract.
+
+## Authentication
+
+Set these environment variables before running Confluence commands:
+
+```bash
+export CONFLUENCE_BASE_URL="https://your-company.atlassian.net"
+export CONFLUENCE_EMAIL="you@company.com"
+export CONFLUENCE_API_TOKEN="<atlassian-api-token>"
+```
+
+Create the token from [Atlassian account security settings](https://id.atlassian.com/manage-profile/security/api-tokens)
+and make sure the account can read, create, and update pages in the target space. The bridge uses
+the [Confluence Cloud REST API v2 page endpoints](https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-page/).
+Do not commit these values. Use local shell secrets or CI secrets.
+
+## Pull a wiki page into spec context
+
+Run from the dbt project root:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify confluence pull-page 123456789 \
+  --to specs/001-player-journey/context/player-metrics.md
+```
+
+This creates or updates:
+
+```text
+specs/001-player-journey/
+  confluence.yml
+  context/
+    player-metrics.md
+```
+
+The context file contains the page title, URL, page id, sync timestamp, and a lightweight markdown
+rendering of the page body. `confluence.yml` records the source page so reviewers know where the
+context came from.
+
+Use this for focused wiki context only. Do not bulk-copy entire spaces into the repo.
+
+## Publish a spec summary page
+
+After `spec.md` and `plan.md` are approved:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify confluence publish \
+  --spec-dir specs/001-player-journey \
+  --space-key DATA \
+  --parent-id 987654321
+```
+
+This creates a Confluence page summarizing the local artifacts and writes page metadata to
+`specs/001-player-journey/confluence.yml`.
+
+If your automation already knows the Confluence v2 space id, use `--space-id` instead of
+`--space-key`:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify confluence publish \
+  --spec-dir specs/001-player-journey \
+  --space-id 12345
+```
+
+To update an existing page:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify confluence publish \
+  --spec-dir specs/001-player-journey \
+  --page-id 123456789
+```
+
+Preview without writing:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify confluence publish \
+  --spec-dir specs/001-player-journey \
+  --space-key DATA \
+  --dry-run
+```
+
+Dry-run reads local files only and does not require Confluence credentials.
+
+## Sync a previously published page
+
+Once `confluence.yml` has a `page_id`, use:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify confluence sync \
+  --spec-dir specs/001-player-journey
+```
+
+This updates the recorded page from current local files.
+
+## What gets published
+
+The summary page includes the available files from the spec directory:
+
+- `spec.md`
+- `plan.md`
+- `tasks.md`
+- `review.md`
+- `governance-review.md`
+- `dbt-specify-report.md`
+- markdown files under `context/`
+
+The page is intentionally a readable knowledge summary. It does not replace the PR, CI checks, or
+the local approved artifacts.
+
+## Recommended enterprise policy
+
+- Pull only relevant Confluence pages into `specs/<NNN>/context/`.
+- Keep page ids and URLs in `confluence.yml` for traceability.
+- Publish only approved or review-ready spec directories.
+- Use Confluence for durable business summaries, onboarding, architecture notes, and metric
+  definitions.
+- Keep Jira as the ticket/task tracker and the PR as the merge gate.
+- Use `confluence publish --dry-run` before the first production rollout.
+
+## Troubleshooting
+
+- `Missing Confluence environment variable`: set `CONFLUENCE_BASE_URL`, `CONFLUENCE_EMAIL`, and
+  `CONFLUENCE_API_TOKEN`.
+- `Confluence space not found`: verify `--space-key` or pass `--space-id`.
+- `confluence.yml is missing page_id`: run `confluence publish` before `confluence sync`.
+- `HTTP 401`: check the email/token pair and site URL.
+- `HTTP 403`: confirm the account can read pages and create or update pages in the target space.

docs/tutorials/06-confluence-context-workflow.md

@@ -0,0 +1,86 @@
+# Tutorial 6: Confluence context workflow
+
+This tutorial shows how to use Confluence pages as approved business context for a dbt-spec-kit
+feature, then publish the final spec summary back to Confluence.
+
+## 1. Configure Confluence credentials
+
+```bash
+export CONFLUENCE_BASE_URL="https://your-company.atlassian.net"
+export CONFLUENCE_EMAIL="you@company.com"
+export CONFLUENCE_API_TOKEN="<atlassian-api-token>"
+```
+
+Use a local shell profile or secret manager. Do not write tokens into the repo.
+
+## 2. Pull relevant wiki context
+
+Run from the dbt project root:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify confluence pull-page 123456789 \
+  --to specs/001-player-journey/context/player-metrics.md
+```
+
+Expected output:
+
+```text
+pulled Player metric definitions (123456789)
+wrote specs/001-player-journey/context/player-metrics.md
+```
+
+The spec directory also gets `confluence.yml` with source page traceability.
+
+## 3. Ask the agent to use context carefully
+
+Ask your agent:
+
+```text
+Read specs/001-player-journey/context/player-metrics.md and the current dbt project.
+Use it as source context for business meaning, but keep the approved spec.md as the implementation
+contract. Do not edit SQL or YAML yet.
+```
+
+Then run the normal workflow:
+
+```text
+/dbt.specify Build a player journey mart using the approved player metrics definitions.
+/dbt.plan
+/dbt.tasks
+```
+
+## 4. Publish the approved summary
+
+After `spec.md` and `plan.md` are approved:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify confluence publish \
+  --spec-dir specs/001-player-journey \
+  --space-key DATA \
+  --parent-id 987654321
+```
+
+This creates a Confluence page and records the page id in:
+
+```text
+specs/001-player-journey/confluence.yml
+```
+
+## 5. Sync after review
+
+After implementation and review evidence are added:
+
+```bash
+uvx --from dbt-spec-kit dbt-specify report --format markdown \
+  > specs/001-player-journey/dbt-specify-report.md
+
+uvx --from dbt-spec-kit dbt-specify confluence sync \
+  --spec-dir specs/001-player-journey
+```
+
+## Success criteria
+
+- Confluence source context is stored under `context/`, not copied blindly into the spec.
+- `confluence.yml` records source page ids and the published summary page id.
+- The Confluence summary reflects approved local artifacts.
+- The PR remains the merge gate for dbt code.

docs/tutorials/README.md

@@ -11,6 +11,7 @@ Use them in order when onboarding a team:
 | [3. Adopt in a brownfield enterprise repo](03-brownfield-enterprise-adoption.md) | 30 min | Data platform leads | Roll out the workflow without rewriting production models |
 | [4. Run skills and sub-agent handoffs](04-skills-and-sub-agent-handoffs.md) | 20 min | Teams using AI agents | Decide when to use skills, sub-agents, and human approval gates |
 | [5. Jira to spec workflow](05-jira-to-spec-workflow.md) | 20 min | Enterprise teams using Jira | Pull Jira context into specs and publish approved artifacts back |
+| [6. Confluence context workflow](06-confluence-context-workflow.md) | 20 min | Enterprise teams using Confluence | Pull wiki context into specs and publish approved summaries |
 
 ## Learning path
 
@@ -22,6 +23,7 @@ Install
   -> implement one task
   -> attach CI evidence
   -> sync approved artifacts to Jira
+  -> publish durable context to Confluence
   -> review and merge
 ```
 
@@ -37,3 +39,4 @@ GitHub Copilot, Gemini CLI, Cline, and similar tools can all use the generated p
 - dbt-spec-kit skills and sub-agent roles enforce enterprise delivery rules.
 - CI evidence proves the final diff followed the approved plan.
 - Jira remains the intake and task tracking system, while specs remain the engineering contract.
+- Confluence remains the knowledge base, while local specs remain the implementation contract.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dbt-spec-kit"
-version = "1.3.0"
+version = "1.4.0"
 description = "Enterprise AI SDLC toolkit for dbt projects, with spec-driven workflows, CI validation, and warehouse-specific presets."
 readme = "README.md"
 license = { file = "LICENSE" }
@@ -26,6 +26,7 @@ keywords = [
     "duckdb",
     "athena",
     "jira",
+    "confluence",
 ]
 classifiers = [
     "Development Status :: 3 - Alpha",

src/dbt_specify/_version.py

@@ -1,4 +1,4 @@
 """Single source of truth for the package version."""
 from __future__ import annotations
 
-__version__ = "1.3.0"
+__version__ = "1.4.0"