Skip to content
Back to search

northstar

MarketplaceWorks with Claude CodeGitHub

Northstar: an operating system for AI coding agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ugurshelby--northstar/badge.svg)](/listings/ugurshelby--northstar)

HTML

<a href="/listings/ugurshelby--northstar"><img src="/api/listings/ugurshelby--northstar/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Needs **Node 18+** and **git**. (Installing third-party skills through the `npx skills` CLI needs Node 22.20+.)

Claude Code plugin

Inside Claude Code (2.1.275 or later):

/plugin install northstar --marketplace ugurshelby/northstar

Then open your project and run `/northstar:install`. The plugin adds owner commands and a session-start check that spots missing hooks and new versions:

| Command | What it does | |---|---| | `/northstar:install` | Set up Northstar in this project | | `/northstar:status` | Where the project stands, in plain words | | `/northstar:add <what you want>` | Put a feature in the brief and build it | | `/northstar:ship` | Go/no-go check, then release | | `/northstar:autonomy [level]` | Show or change how independently the agent works | | `/northstar:skills` | Propose skills that would help this project | | `/northstar:checkup` | Routine check and clean-up | | `/northstar:update` | Update this project's copy to the plugin's version |

On older Claude Code versions: `/plugin marketplace add ugurshelby/northstar`, then `/plugin install northstar@northstar`.

Any agent

npx --yes --package github:ugurshelby/northstar northstar init path/to/your-project

Or clone this repository and run:

node scripts/cli.mjs init path/to/your-project

Then open the project in your coding agent and say **"install Northstar"**, in any language. Use a strong model for the install; any model can work inside the rules afterwards.

After cloning an installed project on another machine (ignore rules and hooks are local by design):

node .agents/skills/northstar/scripts/cli.mjs repair

Check an installed project, or this repository itself:

node .agents/skills/northstar/scripts/cli.mjs verify
node scripts/cli.mjs verify --skill

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "northstar",
  3. "description": "Northstar: an operating system for AI coding agents.",
  4. "owner": { "name": "ugurshelby", "url": "https://github.com/ugurshelby" },
  5. "plugins": [
  6. {
  7. "name": "northstar",
  8. "source": "./",
  9. "description": "Owner brief, autonomy levels, phases, quality and security gates, and vetted skills for any project."
  10. }
  11. ]
  12. }
README.md · README · 182 lines
  1. # Northstar
  2. **You set the direction. Your coding agent does the work, safely, and tells you what changed in plain words.**
  3. [![verify](https://github.com/ugurshelby/northstar/actions/workflows/verify.yml/badge.svg)](https://github.com/ugurshelby/northstar/actions/workflows/verify.yml)
  4. [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  5. Northstar is an operating system for AI coding agents. It installs into a project, new or half-built, and shapes itself around it. From then on the agent works from your brief, at the level of independence you chose, inside quality and security gates that fit the project's stage. It works with Claude Code, Codex, Cursor, Antigravity, Copilot and any other tool that reads `AGENTS.md`.
  6. It is built for people who lead a product rather than write every line: founders, product people, designers, and developers who would rather review outcomes than babysit prompts.
  7. ---
  8. ## Why
  9. Coding agents are fast, but left alone they drift. They forget yesterday's decisions, ask you engineering questions you should not have to answer, call untested work "done", commit their plans and tooling to your repo, and install whatever skill a blog post recommended.
  10. Northstar gives the agent what a good team lead would:
  11. | Without it | With Northstar |
  12. |---|---|
  13. | Rules scattered over chat history and half-remembered prompts | One rule system per project, written into `AGENTS.md` from the real code |
  14. | "Should I use X or Y?" on every technical detail | The agent makes engineering calls itself and asks you only what is yours to decide |
  15. | "Done!" with nothing to show | Done means proof: a screenshot or preview link, or the checks that ran |
  16. | The same rigor for a weekend prototype and a public launch | Gates that follow the phase: fast while exploring, strict before going live |
  17. | Plans, logs and agent files leaking into the repo | A clean public history; the agent's notes stay in a local `.work/` folder |
  18. | Random third-party skills with unknown scripts | A vetted catalog; the agent proposes, you approve, installs are pinned |
  19. ## How it works
  20. ```mermaid
  21. flowchart LR
  22. A[You: goal and brief] --> B[Install: reads the code,<br/>asks a few plain questions]
  23. B --> C[Rules, brief, phase,<br/>autonomy, security tier]
  24. C --> D[Every session:<br/>plan, build, check]
  25. D --> E[Report: result, proof,<br/>what needs you, next]
  26. E --> A
  27. ```
  28. 1. **Install once.** The agent inventories the project, absorbs any older rule files, writes `AGENTS.md` with the project's real commands and structure, sets up local git hooks and ignore rules, and asks you a handful of questions in your language: what you are building, how independent it should be, how technical the conversation may get.
  29. 2. **Operate every session.** The agent reads the brief and the plan, works in small verified steps, keeps docs and logs current, and cleans up after itself.
  30. 3. **Update in place.** A newer Northstar is applied as a diff to the project's copy, never as a reinstall.
  31. ## What a session feels like
  32. > **You:** Add a waitlist to the landing page.
  33. >
  34. > **Agent:** Added to the brief as a must: "done when a visitor can join with their email and gets a confirmation." About half a day. Starting now.
  35. >
  36. > …
  37. >
  38. > **Agent:** The waitlist works on the preview. Proof: the preview link, and I joined with a test address and received the confirmation. Needs you: the email service's free plan covers us for now; I recommend staying on it until we have real traffic. Next: the pricing section.
  39. No stack traces, no "Postgres or SQLite?". Engineering choices are made, logged, and explained when you ask.
  40. ## Features
  41. **Owner layer** ([references/12-owner-layer.md](references/12-owner-layer.md))
  42. - A one-page **brief** with "done when" lines written from the user's side; every plan and every "done" is checked against it.
  43. - Three **autonomy levels**: *guided* (check with me), *balanced* (handle the details, ask me the big things), *autonomous* (run with it). Change it in your own words at any time, or scope it: "decide the UI yourself, always ask me about pricing".
  44. - **Hard limits** that hold at every level: spending money, creating or deleting accounts, deleting user data, going public for the first time, legal and privacy choices, installing skills.
  45. - **Plain voice**: result first, bad news first, no jargon, decisions offered as at most three options with the recommended one first.
  46. **Phases** ([references/13-phases.md](references/13-phases.md))
  47. - Idea → prototype → MVP → launch → maintain, each with a clear exit line and its own required checks.
  48. - A 12-point go/no-go **launch checklist**, and a shorter one for routine releases.
  49. **Quality and security** ([quality gates](references/07-quality-gates.md), [proportional security](references/03-security.md), [security reference](security/SECURITY-REFERENCE.md))
  50. - Non-negotiables for every change (fail closed, validated boundaries, no silent failures, tests before fixes), deterministic tooling, and a zero-context adversarial reviewer for risky paths.
  51. - **Security tiers** from a public static site to regulated data: secrets and personal data get strict handling, public data does not get pointless encryption.
  52. **Skills, by proposal** ([catalog](catalog/README.md), [references/11-skills.md](references/11-skills.md))
  53. - Close to 40 third-party skill sources, each with license, purpose, fit notes and the commit it was checked at. Bundles per project type explain which skills work together and what you gain.
  54. - Northstar ships none of them. The agent proposes a short list in plain words, installs only what you approve, pins it, and writes into the rules how this project uses it.
  55. **Clean repository** ([references/04-git-showcase.md](references/04-git-showcase.md))
  56. - `.gitignore` lists itself, agent files are excluded locally, and local hooks block tooling files, likely secrets and AI trailers in commit messages. Your history reads like an engineer wrote it.
  57. **Design** ([design/GUIDE.md](design/GUIDE.md))
  58. - A design library (principles, UX laws, platform rules, colour, type, nine style references) and, for UI projects, a project-specific design skill written at install.
  59. ## Quick start
  60. Needs **Node 18+** and **git**. (Installing third-party skills through the `npx skills` CLI needs Node 22.20+.)
  61. ### Claude Code plugin
  62. Inside Claude Code (2.1.275 or later):
  63. ```
  64. /plugin install northstar --marketplace ugurshelby/northstar
  65. ```
  66. Then open your project and run `/northstar:install`. The plugin adds owner commands and a session-start check that spots missing hooks and new versions:
  67. | Command | What it does |
  68. |---|---|
  69. | `/northstar:install` | Set up Northstar in this project |
  70. | `/northstar:status` | Where the project stands, in plain words |
  71. | `/northstar:add <what you want>` | Put a feature in the brief and build it |
  72. | `/northstar:ship` | Go/no-go check, then release |
  73. | `/northstar:autonomy [level]` | Show or change how independently the agent works |
  74. | `/northstar:skills` | Propose skills that would help this project |
  75. | `/northstar:checkup` | Routine check and clean-up |
  76. | `/northstar:update` | Update this project's copy to the plugin's version |
  77. On older Claude Code versions: `/plugin marketplace add ugurshelby/northstar`, then `/plugin install northstar@northstar`.
  78. ### Any agent
  79. ```bash
  80. npx --yes --package github:ugurshelby/northstar northstar init path/to/your-project
  81. ```
  82. Or clone this repository and run:
  83. ```bash
  84. node scripts/cli.mjs init path/to/your-project
  85. ```
  86. Then open the project in your coding agent and say **"install Northstar"**, in any language. Use a strong model for the install; any model can work inside the rules afterwards.
  87. After cloning an installed project on another machine (ignore rules and hooks are local by design):
  88. ```bash
  89. node .agents/skills/northstar/scripts/cli.mjs repair
  90. ```
  91. Check an installed project, or this repository itself:
  92. ```bash
  93. node .agents/skills/northstar/scripts/cli.mjs verify
  94. node scripts/cli.mjs verify --skill
  95. ```
  96. ## What it adds to a project
  97. ```
  98. your-project/
  99. ├─ AGENTS.md, CLAUDE.md, GEMINI.md rules for every agent
  100. ├─ .agents/skills/northstar/ the project's own copy and its state.json
  101. ├─ .agents/skills/<project>-design/ the project's design language (UI projects)
  102. ├─ .claude/agents/ scout, architect, pm and critic subagents
  103. └─ .work/ brief, plan, decisions, open questions, quality, logs, security notes
  104. ```
  105. None of it is committed. Your repository keeps only your product.
  106. ## Repository map
  107. ```
  108. SKILL.md entry point: picks install, operate or update mode
  109. references/ the rules, one topic per file (01-13)
  110. workflows/ install, operate, update
  111. catalog/ vetted external skills: links, install and fit notes
  112. security/ rule reference with IDs, and a checklist
  113. stacks/ notes for Next.js + Supabase + Vercel, Vite SPA, Electron, Python
  114. design/ selection guide and design library
  115. templates/ files the install writes into a project
  116. scripts/ cli.mjs: init, repair, link-skills, untrack, verify, session-check
  117. commands/ Claude Code plugin owner commands
  118. hooks/ Claude Code plugin session-start check
  119. .claude-plugin/ plugin manifest and marketplace entry
  120. ```
  121. ## FAQ
  122. **Does it work with my agent?** Anything that reads `AGENTS.md` works. Claude Code also gets subagents and skill links; Antigravity and Gemini get pointer files.
  123. **Will it change my code?** Installing touches rule files, ignore rules and hooks only. It never changes application behavior, rewrites git history or pushes on its own.
  124. **Does it send anything anywhere?** The CLI has no dependencies and makes no network calls. Third-party skills are fetched only after you approve them, from the commit that was checked.
  125. **Can I use it on a half-built project?** That is the main case. Older rule files, runbooks and vendored libraries are absorbed into one system, and the leftovers are removed.
  126. ## Contributing
  127. Ideas, skill suggestions and fixes are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Report security issues privately as described in [SECURITY.md](SECURITY.md).
  128. ## License
  129. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.