---
description: Set up or adapt a repository for the Orual Jira/Confluence Polytoken workflow, including project variables, Jira-as-agent-truth conventions, jj workspace policy, and validation.
polytoken:
  tags: [jira, confluence, workflow, configuration, jj]
---

# Jira/Confluence Workflow Setup

Use this skill when initializing a repository to use the Orual Jira/Confluence workflow or when adapting the workflow to a new Jira project/space.

Announce: "using the jira/confluence workflow setup skill to initialize this repo"

Before changing Polytoken config, facets, hooks, skills, subagents, or permissions, load `polytoken:config_reference`. Treat it as authoritative for schema, config layering, and validation rules.

## Goal

Configure the repo so agents can safely use Jira as both:

- the human source of truth; and
- the agent working truth when Jira tools are available and permitted.

Confluence is used for larger design/reference documents when the project has a configured space/page convention. Local Markdown remains useful for repo-owned templates and fallback notes, but it is not the canonical issue state for this workflow.

## Required setup facts

Determine these before editing files. Prefer existing repo config and Jira/Confluence tool discovery before asking the operator.

- Atlassian cloudId.
- Jira project key.
- Jira issue types eligible for autonomous solo-tasker work.
- Jira status transition IDs for at least: To Do, In Progress, In Review, Done.
- Labels that block automation, such as `no-auto`.
- Whether claims are represented by comments, assignee, status, or a combination.
- Confluence space key, numeric space ID for page APIs, overview/root page ID, and page conventions, if design docs should live in Confluence.
- jj workspace location convention: sibling directory, project wrapper, or current checkout only.
- Review gate roster and model pins.
- Validation commands: format, lint, tests, build, provider/live checks.
- Permission expectations for Jira/Confluence MCP tools in plan and execute facets.

If any fact is unavailable and materially affects setup, ask the operator with a focused question.

## Files to create or update

Typical project-local files:

```text
.polytoken/project_vars.yaml
.polytoken/skills/jira-solo-tasker-plan/SKILL.md
.polytoken/skills/jira-solo-tasker-execute/SKILL.md
.polytoken/skills/jira-confluence-workflow-setup/SKILL.md
.polytoken/permissions.yaml or .polytoken/permissions.local.yaml  # only with operator approval
```

Optional docs/templates:

```text
docs/polytoken-workflows/
docs/polytoken-workflows/templates/
```

Do not store secrets in repo files. Do not write user-specific credentials or Atlassian tokens into project config.

## Project vars contract

Update `.polytoken/project_vars.yaml` with human-readable instructions for facets and skills. A useful shape is:

```yaml
design_workflow_instructions: |
  Jira is the human source of truth and agent working truth for implementation tasks when Jira tools are available.
  Use project <KEY> for task state. Use Confluence space <SPACE> for durable design/reference docs when linked from Jira.
  Local Markdown under docs/polytoken-workflows/ is fallback/supporting material, not the canonical ticket state.

plan_handoff_instructions: |
  Handoff plans for Jira tasks must cite the Jira issue key, current status, claim state, relevant Confluence links, jj workspace/bookmark name, validation commands, and review-gate requirements.

orual_workflow:
  source_of_truth:
    human: jira
    agent: jira
  jira:
    cloud_id: "<cloud-id>"
    project_key: "<KEY>"
    statuses:
      todo: "To Do"
      in_progress: "In Progress"
      in_review: "In Review"
      done: "Done"
    transitions:
      todo: "11"
      in_progress: "21"
      in_review: "31"
      done: "41"
    eligible_issue_types: [Task, Bug]
    automation_block_labels: [no-auto]
  confluence:
    space_key: "<SPACE>"
    space_id: "<numeric space id for page APIs>"
    overview_page_id: "<overview/root page id, if used>"
    design_page_parent: "<page id or title, if used>"
  vcs:
    kind: jj
    workspace_policy: sibling
  review:
    gate_severities: [Critical, High]
```

The string fields are for prompt rendering. The structured `orual_workflow` block is for hooks, setup checks, and future tools; scripts must tolerate missing keys.

## Rewrite skill constants

Ensure the Jira solo-tasker skills match the project:

- cloudId and project key;
- transition IDs and status names;
- eligible issue types;
- automation block labels;
- Confluence space key, numeric space ID, and overview/root page ID if design docs live in Confluence;
- Jira-as-agent-truth statement;
- jj workspace policy;
- review roster.

Avoid duplicating config in too many places. If Polytoken skill templating is available for the needed fields, prefer rendering from `project_vars`; otherwise keep the constants compact and make the setup skill the checklist for keeping them synchronized.

## jj workspace policy

Default to jj workspaces, not Git worktrees. Every ticket workflow must start a fresh jj change with `jj new -m ...` before edits; do not rely on `jj describe` at setup time because it describes the current change.

Recommended generic policy:

```sh
root="$(jj workspace root)"
jj workspace list
workspace_path="$(dirname "$root")/<ticket-slug>"
jj workspace add "$workspace_path" -r @
cd "$workspace_path" && jj new -m "<ticket-key>: <summary>"
```

Project wrappers are allowed and preferred when documented. The setup skill should record the wrapper command in project vars or repo instructions.

Do not add Git worktree, direct `main` merge, or merge-lock instructions unless the target repo actually uses them.

## Jira/Confluence tool checks

When tools are available, verify:

1. The Jira project exists and is visible.
2. A representative issue exposes the expected fields.
3. `getTransitionsForJiraIssue` returns the configured transition IDs.
4. Comment and transition tools are permissioned as intended.
5. Confluence space/page discovery works, if Confluence is part of the workflow. Note that some Confluence page APIs require numeric space IDs even when CQL and URLs use the space key.

If tools are not available in the current facet/session, write the setup as pending verification and tell the operator exactly what to test.

## Permission guidance

Use permission files only with operator approval.

For unattended planning, the plan facet may need approval policy for Jira search/read, transition, and comment tools. For execution, it may need Jira read/comment/transition and Confluence read tools, plus filesystem access to the jj workspace path.

Keep broad write permissions out of shared project config unless the team explicitly wants them. Prefer `.polytoken/permissions.local.yaml` for operator-machine-specific allows.

## Validation

After edits:

```sh
polytoken config validate
```

If facets, hooks, skills, or permissions changed in a live session, reload or restart Polytoken before testing behavior.

Then perform a dry run where possible:

- invoke the plan skill on a known safe test ticket or ask it to list candidates without claiming;
- verify it would use Jira as agent truth;
- verify it names `jira-solo-tasker-execute` in the handoff;
- verify the execute skill uses jj workspace terminology and does not mention Git worktrees or merge locks.

## Final report

Report:

- files changed;
- configured Jira project/cloud and Confluence space assumptions;
- transition IDs verified or pending verification;
- jj workspace policy;
- permission changes made or intentionally left for the operator;
- validation command results;
- next manual test to run.
