Polaris

Polaris Quickstart

Cheat sheet for scaffolding a new project. See USAGE.md for full details.

First-Time Setup (once)

  • git clone https://github.com/theyoungastronauts/polaris.git ~/prj/polaris && cd ~/prj/polaris
  • ./install.sh init — saves repo path, adds polaris alias
  • source ~/.zshrc — pick up the alias
  • polaris global --fresh — install global skills + developer defaults
  • pip install axoniq — optional: Axon is a third-party code-graph tool (call graphs, impact analysis) that Polaris uses over MCP when present; everything works without it

Safe on an existing setup. Plain polaris global amends: CLAUDE.md content outside the Polaris markers is preserved, settings.json is merged (nothing of yours removed), and every file written is manifest-tracked so polaris uninstall removes exactly what was added. --fresh is the one flag that replaces your CLAUDE.md — it backs the old one up first. When in doubt, drop --fresh.

New Project

1. Initialize + Design

  • polaris new ~/prj/my-app — creates project, selects stacks, installs context
  • cd ~/prj/my-app

Option A — brainstorm from scratch:

  • Open Claude Code session
  • "Let's brainstorm [your idea] using the brainstorming skill"
  • The agent already knows your stack — no need to re-explain it
  • Iterate until design is solid
  • Design saved to docs/plans/YYYY-MM-DD-<topic>-brainstorm.md

Option B — bring existing design work:

  • Drop briefs, wireframes, sitemaps, flow diagrams into docs/design/
  • Open Claude Code session
  • "Review my design materials using the design-intake agent"
  • Answer clarifying questions as the agent distills the artifacts
  • Design doc saved to docs/plans/YYYY-MM-DD-<topic>-design.md

1b. Product Definition (optional, for UI features)

  • /prd — formalize requirements into a structured PRD
  • /ux-spec — run 6 UX passes (mental model, IA, affordances, cognitive load, states, flow integrity)
  • Skip for backend-only features

1c. Generate Project Context (after first few phases)

  • /intel — populates .claude/context/ with architecture, decisions, conventions, patterns
  • Skip for brand-new projects — run after there's enough code to analyze

2. Scaffold

  • In the same session: "Let's scaffold the project using /scaffold"
  • Confirm the scaffold plan (stacks, directory names)
  • Claude creates subdirectories, git inits, bootstraps
  • If Axon is installed, initial index runs automatically

3. Plan

  • Start a new Claude session
  • "Turn the design docs in docs/plans/ into a phased implementation plan"
  • The planner reads the most structured artifact available: UX spec > PRD > brainstorm doc
  • Review phases — small enough to review individually? Dependencies flow forward?
  • plan.md saved to project root

4. Execute + Review (repeat per phase)

  • cd into sub-project (e.g., ~/prj/my-app/api/)
  • Open Claude Code session
  • /execute — picks up the plan, confirms the phase, implements on main
  • When done, start a new Claude session
  • /verify — checks the work against the plan, produces verification report, commits on PASS
  • Fix any FAILs, then move to next phase
  • /remember — capture any decisions, conventions, or patterns worth preserving

Or use hands-off execution:

  • /autopilot — for pre-planned phases: implement → test → verify → commit loop
  • /orchestrator — for broader work: inline tasks, parallel execution, auto-phasing, model overrides
  • Both stop on FAIL — fix issues and resume with /autopilot N or /orchestrator N

5. Cross-Repo Handoff (if applicable)

  • After API phases: "Generate an integration summary"
  • Before web phases: ~/prj/polaris/context-pull.sh ../api
  • Then execute web phases with the integration context loaded

Ongoing Development

  • /recall at session start — loads relevant project context
  • /wrap at session end — one-command close-out: memory, context, repo report (/remember for a single targeted save)
  • /relay when context gets heavy mid-task — hand off to a fresh session instead of /compact

Single feature: branch → /execute → /verify → PR → merge

Parallel features: use git worktrees (the /worktrees skill)