polaris

# Polaris — llms.txt

> A modular skills/agents/workflows system for AI-assisted development with Claude Code.
> This file is a concise reference for AI agents. For full details, see the linked files.

## What Polaris Is

Polaris is a collection of **markdown instruction files** (no runtime code) that guide Claude Code through structured planning, execution, and verification of software projects. It installs into Claude's config directories so skills are automatically available in sessions.

Files are **copied** (not symlinked) so projects work independently. A checksum system detects stale installs.

## Repository Structure

```
install.sh              Installer (init, global, new, project, uninstall, hooks, status, validate, list-profiles, list-skills)
context-pull.sh         Extracts Django backend context for frontend sessions
skills/                 Native Agent Skills — one dir per skill: skills/<name>/SKILL.md.
                        Frontmatter sets behavior: auto-trigger (description / paths glob) or
                        command-only (disable-model-invocation → /name). ~52 skills, e.g.
                        plan-and-scope, phase-breakdown, scaffold, execute, verify, autopilot,
                        orchestrator, intel, work-discipline, {django,nextjs,flutter,astro}-patterns,
                        *-bootstrap, verify-{django,nextjs,flutter,astro,…}, recall, remember, reflect.
                        skills/misc/ holds flat project-specific skills (not in any profile).
agents/                 planner, executor, reviewer, integrator, design-intake, drift-detector
templates/              integration-summary.md, claude-md-defaults.md, context/ scaffold templates
profiles/               Stack manifests (.txt) + CLAUDE.md snippets (.claude.md)
```

## Installation

```bash
# First-time setup
./install.sh init          # Saves repo path, adds `polaris` shell alias, merges settings
source ~/.zshrc
polaris global --fresh     # Install global skills + developer defaults to ~/.claude/

# Per-project (interactive or explicit)
cd ~/prj/my-app
polaris project --stack django --stack nextjs
polaris project --stack django --standalone   # Single-stack repo (directory = ".")
polaris project --clean --stack django        # Wipe and reinstall

# Check for stale files
polaris status

# Create new project (interactive stack selection + brainstorm launch)
polaris new ~/prj/my-app
```

**What install does:** Copies skills/agents into `~/.claude/` (global) or `.claude/` (project). Generates CLAUDE.md with references to installed files between `<!-- polaris:start/end -->` markers. Merges tool permissions and LSP config into `~/.claude/settings.json`.

## Profiles (Composable Stacks)

Select a backend + 0..N frontends. Each profile lists which skills to install.

| Profile | Type | Default Dir | Details |
|---------|------|-------------|---------|
| `global` | — | `~/.claude/` | Planning, writing, git, memory, meta skills + agents |
| `django` | backend | `server` | Django/DRF patterns + verification |
| `nextjs-fullstack` | backend | `web` | Full-stack Next.js (Drizzle, Postgres, Redis, BullMQ, Auth.js) — pair with a Next.js frontend profile |
| `nextjs` | frontend | `web` | Next.js (DaisyUI) + React/Tailwind as on-demand commands |
| `nextjs-shadcn` | frontend | `web` | Next.js (ShadCN UI) variant |
| `nextjs-mui` | frontend | `web` | Next.js (Material UI) variant |
| `flutter` | frontend | `mobile` | Flutter patterns + verification |
| `astro` | frontend | `landing` | Astro patterns + verification |

Multi-stack installs auto-add `_multi-stack.txt` (integrator agent, cross-repo-context, integration summary template).

**Profile format** (`profiles/*.txt`) — bare skill names + agent paths:
```
# stack: backend|frontend
# label: Display Name
# directory: default-dir

django-patterns          # installs skills/django-patterns/ (auto-triggers, or paths-scoped)
django-bootstrap         # command-only skill (disable-model-invocation) → /django-bootstrap
agents/executor.md       # agent definition (copied as-is)
```

## Skills Overview

Skills are self-contained markdown files. No dependencies between skills.

**Planning:** Brainstorming (guided ideation) → Plan and Scope (goals, scope in/out, risks) → Phase Breakdown (small phases, parallel groups, sync points) → Scaffold (create project from plan).

**UX:** PRD (7-section product requirements) → UX Spec (6 forced design passes: mental model, IA, affordances, cognitive load, states, flow integrity) → UX-to-Prompts (build-order prompts for UI tools like v0/Bolt).

**Execution:** Execute Phase (plan mode → explore → implement → test → summarize). Work Discipline (behavioral guardrails: plan mode defaults, subagent strategy, verify-as-you-go, re-plan triggers). Axon Code Intelligence (structural analysis via knowledge graph — when/how to use call graphs, impact analysis, dead code detection during each workflow stage). Stack patterns define conventions per framework. Bootstrap skills scaffold new projects. Autopilot loops execute → test → verify → commit across all phases.

**Verification:** Verify Phase (tests, plan match, security, code quality, scope). Per-stack checklists add framework-specific checks. Axon tools provide structural verification — mapping diffs to affected symbols, detecting orphaned code, confirming all call sites were updated.

**Other:** Writing clearly, commit conventions, worktrees, cross-repo context, visual-feedback (browser-annotated UI fixes via Agentation MCP), session reflection, meta skill for authoring new skills.

→ Detailed skill files: `skills/` subdirectories

## Agents

| Agent | Role | Input | Output |
|-------|------|-------|--------|
| **planner** | Design → phased plan | Design docs in `docs/plans/` | `plan.md` |
| **executor** | Implement a single phase | `plan.md` + assigned phase | Uncommitted changes + integration summary |
| **reviewer** | Verify completed phase | `plan.md` + recent changes | Verification report (PASS/WARN/FAIL) |
| **integrator** | Bridge backend↔frontend | Backend code | Integration summary (API contracts) |
| **design-intake** | Distill design artifacts | Files in `docs/design/` | Structured design doc |
| **drift-detector** | Catch convention drift | `.claude/context/` + recent changes | Drift report (aligned/drifted/undocumented) |

→ Detailed agent files: `agents/`

## On-Demand Slash Commands

Command-only skills (`disable-model-invocation: true`), installed to `.claude/skills/<name>/` — only loaded when invoked as `/<name>`.

| Command | Purpose |
|---------|---------|
| `/prd` | Generate product requirements document |
| `/ux-spec` | Create UX specification (6 design passes) |
| `/ux-to-prompts` | UX spec → build-order prompts for UI tools |
| `/execute` | Execute a phase of the plan |
| `/verify` | Verify a completed phase |
| `/autopilot` | Autonomous phase loop (execute → test → verify → commit) |
| `/orchestrator` | Flexible task orchestration (parallel waves, auto-phasing, model overrides) |
| `/scaffold` | Create project from plan |
| `/intel` | Generate/update the project context scaffold |
| `/remember` | Save a decision, convention, or pattern to the scaffold |
| `/recall` | Load relevant project context at session start |
| `/reflect` | Session reflection/retrospective |
| `/wrap` | End-of-session close-out (memory + context + connected stores + repo report) |
| `/relay` | Hand in-flight work to a fresh session (steerable /compact alternative) |
| `/actionable` | Extract just the human-required steps from a long answer |
| `/scratch` | Scratch-in/scratch-out paste board setup + discipline |
| `/write-as-human` | Strip AI writing patterns from prose |
| `/write-as-friend` | Casual plain-text messages (Discord/Slack/text/email register) |
| `/django-bootstrap` | Scaffold Django project |
| `/nextjs-bootstrap` · `/nextjs-shadcn-bootstrap` · `/nextjs-mui-bootstrap` | Scaffold a Next.js project (DaisyUI / ShadCN / Material UI) |
| `/nextjs-fullstack-bootstrap` | Scaffold full-stack Next.js project |
| `/flutter-bootstrap` | Scaffold Flutter project |
| `/astro-bootstrap` | Scaffold Astro project |
| `/react` | React best practices reference |
| `/tailwind` | Tailwind v4 + DaisyUI patterns |
| `/visual-feedback` | Browser-annotated UI fix workflow |
| `/worktrees` | Git worktree setup for parallel features |
| `/writing-skills` | Guide for authoring new skills |
| `/full-feature` | End-to-end feature workflow (plan → execute → verify → merge) |

## Core Workflow

**New project (MVP):**

1. **Brainstorm** — Shape the idea conversationally → `docs/plans/*-brainstorm.md`
2. **Define** (optional, UI features) — `/prd` → `/ux-spec` for structured requirements
3. **Plan** (new session) — Planner agent → `plan.md` with phased implementation
4. **Scaffold** — `/scaffold` creates sub-project dirs, git inits, installs profiles
5. **Execute + Verify** (per phase, separate sessions):
   - `/execute` — Implements phase on main (leaves changes uncommitted)
   - `/verify` — Reviews in fresh session, produces PASS/WARN/FAIL report, commits on PASS
   - Fix FAILs, move to next phase
   - OR: `/autopilot` for hands-off loop through all phases
6. **Cross-repo handoff** — Backend generates integration summary → frontend pulls context via `context-pull.sh`

**Ongoing development:**
- Single feature: branch → `/execute` → `/verify` → PR → merge
- Parallel features: git worktrees for isolated workspaces

→ Full walkthrough: `USAGE.md`
→ Cheat sheet: `QUICKSTART.md`
→ Workflow doc: the `/full-feature` skill (`skills/full-feature/SKILL.md`)

## Cross-Repo Context

For full-stack projects with separate backend/frontend repos:

```bash
# From frontend repo, pull backend context
~/prj/polaris/context-pull.sh ../backend-api
# Creates .claude/backend-context.md (models, serializers, views, URLs)
```

Backend phases generate integration summaries (`docs/integration/[feature].md`) documenting endpoints, request/response shapes, auth, and error codes. Frontend phases consume these as contracts.

→ Details: `skills/cross-repo-context/SKILL.md`, `templates/integration-summary.md`

## Axon Integration (Code Intelligence)

Polaris integrates with [Axon](https://github.com/harshkedia177/axon), a graph-powered structural analysis tool. If installed (`pip install axoniq`), it provides MCP tools for call graphs, impact analysis, dead code detection, and execution flow tracing.

**Setup:** `axon analyze .` to index a project, then `axon serve --watch` for live re-indexing via MCP. Scaffold (`/scaffold`) auto-detects Axon and runs initial indexing.

**Key tools:** `axon_query` (hybrid search), `axon_context` (360° symbol view), `axon_impact` (blast radius), `axon_dead_code` (unreachable code), `axon_detect_changes` (diff → affected symbols), `axon_cypher` (graph queries).

**Workflow integration:** Planner uses Axon to explore structure and assess risk. Executor checks impact before modifying symbols. Reviewer maps diffs to affected symbols and catches orphaned code.

→ Details: `skills/axon-code-intel/SKILL.md`

## Key Principles

- **Plan before code.** Brainstorm → plan → execute. A bad plan compounds into bad code.
- **Small phases.** Each phase should be reviewable in one sitting (1–3 hours of execution).
- **Verify separately.** Fresh session = fresh eyes. Don't verify in the session that wrote the code.
- **Tests alongside implementation.** Not after.
- **Commits are atomic.** One logical change per commit, imperative tense, body explains why.
- **Integration summaries are contracts.** Update when backend changes, consume before frontend builds.
- **On-demand commands keep context light.** Heavy reference docs load only when invoked.

## Extending Polaris

- **Add a skill:** Create `skills/<name>/SKILL.md` with `name`/`description` frontmatter (add `disable-model-invocation: true` for command-only, or `paths:` to scope auto-trigger) → list its bare name in the relevant `profiles/*.txt`
- **Add a profile:** Create `profiles/<name>.txt` with metadata headers + a bare-name skill list → create companion `profiles/<name>.claude.md`
- **Add an agent:** Create `.md` in `agents/`
- **Project-specific extras:** `polaris project --extra skills/misc/my-skill.md`

→ Skill authoring guide: the `/writing-skills` skill (`skills/writing-skills/SKILL.md`)
→ Repo conventions: `CLAUDE.md`