Polaris

English | 中文

Polaris is a Claude Code / Codex workspace harness for teams that run work through JIRA, GitHub, Slack, and Confluence. It gives your coding agent durable workflow skills, local team context, deterministic gates, and a learning loop so it follows your operating model instead of improvising every session.

Polaris is intentionally an add-on layer. It owns framework instructions, skills, hooks, and ignored local company context under {company}/; product repositories keep ownership of their tracked CLAUDE.md, AGENTS.md, .github/**, and repo-owned AI configuration.

What You Can Do

Start with one workflow. The full skill catalog is available in Developer Workflow Guide and Chinese Triggers.

How Polaris Works

Polaris organizes agent behavior into three layers:

Skills load only when triggered. Rules and hooks provide the always-on guardrails: language policy, safety checks, PR body validation, task artifact validation, context continuity, and workflow gates.

Governance Philosophy

Polaris treats governance as a framework concern, not a per-session preference.

• Prefer strong constraints over advisory prose whenever a contract can be enforced mechanically.
• When a workflow or artifact can share one canonical shape, use one canonical shape across runtimes and lanes.
• Do not keep special writer paths for the same authoritative surface.
• When required authority inputs are missing, fail closed instead of improvising.

Proof-of-work markers follow the same rule. Completion-sensitive evidence under .polaris/evidence/ must be written by the owning producer declared in scripts/lib/evidence-producers.json; hooks and gates block direct JSON patching, stale /tmp-only pass markers, and auto-pass writing its own proof.

For locked/current DP-backed framework work, auto-pass DP-NNN is the canonical main-chain entry. It dispatches breakdown -> engineering -> verify-AC, stops at workspace PR ready plus current verification disposition, produces a durable report, and leaves merge, sync-to-Polaris, tagging, GitHub release, and closeout to framework-release.

This is why Polaris keeps pushing quality-critical workflow rules into shared scripts, hooks, validators, and generated runtime targets instead of relying on LLM discipline alone.

Requirements

Everyone needs:

• Claude Code or Codex configured with Polaris for Codex
• Atlassian MCP for JIRA and Confluence
• Slack MCP for notifications, standups, and review workflows

Use a coding-agent runtime from the workspace root, not the ordinary browser chat. The prompts below are typed into Claude Code or Codex conversations.

Developers also need:

• Git
• GitHub CLI (gh) authenticated with the organization
• Local Polaris toolchain readiness through the root public tasks mise run bootstrap and mise run doctor -- --profile runtime. The managed runtime covers Node >= 22.12.0, pnpm 10.10.0, Python 3.12, rg, jq, Playwright, Mockoon, and the docs viewer. Legacy compatibility docs may still mention bash scripts/polaris-toolchain.sh doctor --required; new workspaces should start with public task commands.

Optional integrations:

• Google Calendar MCP for meeting-aware standups
• Figma MCP for tickets that reference designs

Most multi-step workflows use sub-agents. In Claude Code, that requires the Max plan or API access.

MCP Setup

Claude Code can connect MCP servers through /mcp:

• Slack: https://mcp.slack.com/mcp
• Atlassian: https://mcp.atlassian.com/v1/mcp

Codex can mirror the same connectors:

codex mcp add claude_ai_Slack --url https://mcp.slack.com/mcp
codex mcp add claude_ai_Atlassian --url https://mcp.atlassian.com/v1/mcp
codex mcp login claude_ai_Slack
codex mcp login claude_ai_Atlassian
codex mcp list

Legacy stdio npx @anthropic-ai/claude-code-mcp-* setup is deprecated in this framework.

Quick Start

1. Create a workspace

Use the Polaris template repo on GitHub, then clone your new workspace:

git clone https://github.com/YOUR-ORG/your-polaris-workspace ~/polaris-workspace
cd ~/polaris-workspace

Choose a dedicated directory name. Avoid ~/work if you already use that path for product repositories.

Before onboarding, bootstrap and verify the local runtime toolchain through public tasks:

mise run bootstrap
mise run doctor -- --profile runtime

If the doctor reports missing tools, follow its repair command and rerun the doctor:

mise run doctor -- --profile runtime

The public task surface is bootstrap, doctor, doctor-mise, onboard-doctor, release-preflight, pr-create, spec-close-parent, script-audit, docs-health, verify, and cross-runtime-sync.

mise run bootstrap also regenerates the four session bootstrap interfaces: CLAUDE.md, AGENTS.md, .codex/AGENTS.md, and .github/copilot-instructions.md. These files are generated outputs read directly by their respective agent runtimes at session start; edit .claude/instructions/** or .claude/rules/**, then regenerate with mise run bootstrap or bash scripts/compile-runtime-instructions.sh. Use bash scripts/compile-runtime-instructions.sh --check to verify freshness without rewriting files.

Root pnpm scripts are thin aliases for common framework commands. They do not replace the public task surface; the script manifest and command catalog remain the governance source:

pnpm viewer:status
pnpm scripts:check
pnpm commands:check

2. Onboard your company

Open Claude Code or Codex from the workspace root, then type this into the agent conversation:

onboard Polaris workspace for my company

The onboard flow detects your GitHub org and repos, creates ignored company context, maps JIRA keys to local repos, and finishes with a readiness dashboard: ready, partial, or blocked.

If the dashboard is not ready, run:

onboard repair

3. Try one real workflow

Use a real ticket key from your JIRA project:

work on PROJ-123

PMs and Scrum Masters can start with:

standup

For a role-specific setup checklist, see PM Setup Checklist. For Codex runtime setup, see Polaris for Codex.

Repository Layout

your-workspace/
├── CLAUDE.md                  # Strategist instructions
├── AGENTS.md                  # Generated runtime bootstrap for coding agents
├── workspace-config.yaml      # Local company routing, ignored by git
├── .claude/
│   ├── rules/                 # Universal and company-scoped rules
│   └── skills/                # Workflow skills
├── docs/                      # Public guides
├── scripts/                   # Deterministic gates and workflow helpers
├── user/                      # Ignored user-local tools, notes, and scratch files
│   └── tools/
└── {company}/                 # Ignored local company context
    ├── workspace-config.yaml
    ├── polaris-config/
    │   └── {project}/handbook/
    └── {project}/             # Product repo; repo-owned files stay owned by the repo

Guides

Customization

Safe places to customize:

Framework internals such as .claude/skills/*/SKILL.md, .claude/skills/references/, .claude/rules/*.md, hooks, and scripts should only be changed when you are modifying Polaris itself.
Root scripts/ is only for framework-supported utilities that are releaseable and governed by the script manifest; company-only helpers and personal utilities belong in the ignored local surfaces above.

Upgrading

To pull framework updates from a Polaris template checkout:

./scripts/sync-from-polaris.sh --polaris ~/path-to-polaris-template --dry-run
./scripts/sync-from-polaris.sh --polaris ~/path-to-polaris-template

The sync preserves ignored company context, company rules, and project-specific files. Apply mode also runs cross-runtime parity checks for Claude Code and Codex.

Security

Polaris is designed for local-first operation:

• No telemetry, analytics, or usage reporting
• No framework phone-home behavior
• Local storage for memories, learnings, timelines, and checkpoints
• Shell-level safety hooks for dangerous commands
• Workspace language gates before downstream PR, JIRA, Slack, Confluence, commit, and release prose
• Plaintext skills, rules, and scripts that can be audited in git

Network activity comes from tools you explicitly invoke, such as git, gh, JIRA, Slack, Confluence, or MCP connectors.

Acknowledgements

Polaris draws inspiration from these open-source projects:

License

MIT