northstar
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.
Badge for your README
Markdown
[](/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
- {
- "name": "northstar",
- "description": "Northstar: an operating system for AI coding agents.",
- "owner": { "name": "ugurshelby", "url": "https://github.com/ugurshelby" },
- "plugins": [
- {
- "name": "northstar",
- "source": "./",
- "description": "Owner brief, autonomy levels, phases, quality and security gates, and vetted skills for any project."
- }
- ]
- }
README.md · README · 182 lines
- # Northstar
- **You set the direction. Your coding agent does the work, safely, and tells you what changed in plain words.**
- [](https://github.com/ugurshelby/northstar/actions/workflows/verify.yml)
- [](LICENSE)
- 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`.
- 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.
- ---
- ## Why
- 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.
- Northstar gives the agent what a good team lead would:
- | Without it | With Northstar |
- |---|---|
- | Rules scattered over chat history and half-remembered prompts | One rule system per project, written into `AGENTS.md` from the real code |
- | "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 |
- | "Done!" with nothing to show | Done means proof: a screenshot or preview link, or the checks that ran |
- | The same rigor for a weekend prototype and a public launch | Gates that follow the phase: fast while exploring, strict before going live |
- | Plans, logs and agent files leaking into the repo | A clean public history; the agent's notes stay in a local `.work/` folder |
- | Random third-party skills with unknown scripts | A vetted catalog; the agent proposes, you approve, installs are pinned |
- ## How it works
- ```mermaid
- flowchart LR
- A[You: goal and brief] --> B[Install: reads the code,<br/>asks a few plain questions]
- B --> C[Rules, brief, phase,<br/>autonomy, security tier]
- C --> D[Every session:<br/>plan, build, check]
- D --> E[Report: result, proof,<br/>what needs you, next]
- E --> A
- ```
- 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.
- 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.
- 3. **Update in place.** A newer Northstar is applied as a diff to the project's copy, never as a reinstall.
- ## What a session feels like
- > **You:** Add a waitlist to the landing page.
- >
- > **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.
- >
- > …
- >
- > **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.
- No stack traces, no "Postgres or SQLite?". Engineering choices are made, logged, and explained when you ask.
- ## Features
- **Owner layer** ([references/12-owner-layer.md](references/12-owner-layer.md))
- - A one-page **brief** with "done when" lines written from the user's side; every plan and every "done" is checked against it.
- - 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".
- - **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.
- - **Plain voice**: result first, bad news first, no jargon, decisions offered as at most three options with the recommended one first.
- **Phases** ([references/13-phases.md](references/13-phases.md))
- - Idea → prototype → MVP → launch → maintain, each with a clear exit line and its own required checks.
- - A 12-point go/no-go **launch checklist**, and a shorter one for routine releases.
- **Quality and security** ([quality gates](references/07-quality-gates.md), [proportional security](references/03-security.md), [security reference](security/SECURITY-REFERENCE.md))
- - 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.
- - **Security tiers** from a public static site to regulated data: secrets and personal data get strict handling, public data does not get pointless encryption.
- **Skills, by proposal** ([catalog](catalog/README.md), [references/11-skills.md](references/11-skills.md))
- - 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.
- - 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.
- **Clean repository** ([references/04-git-showcase.md](references/04-git-showcase.md))
- - `.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.
- **Design** ([design/GUIDE.md](design/GUIDE.md))
- - 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.
- ## Quick start
- 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
- ```bash
- npx --yes --package github:ugurshelby/northstar northstar init path/to/your-project
- ```
- Or clone this repository and run:
- ```bash
- 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):
- ```bash
- node .agents/skills/northstar/scripts/cli.mjs repair
- ```
- Check an installed project, or this repository itself:
- ```bash
- node .agents/skills/northstar/scripts/cli.mjs verify
- node scripts/cli.mjs verify --skill
- ```
- ## What it adds to a project
- ```
- your-project/
- ├─ AGENTS.md, CLAUDE.md, GEMINI.md rules for every agent
- ├─ .agents/skills/northstar/ the project's own copy and its state.json
- ├─ .agents/skills/<project>-design/ the project's design language (UI projects)
- ├─ .claude/agents/ scout, architect, pm and critic subagents
- └─ .work/ brief, plan, decisions, open questions, quality, logs, security notes
- ```
- None of it is committed. Your repository keeps only your product.
- ## Repository map
- ```
- SKILL.md entry point: picks install, operate or update mode
- references/ the rules, one topic per file (01-13)
- workflows/ install, operate, update
- catalog/ vetted external skills: links, install and fit notes
- security/ rule reference with IDs, and a checklist
- stacks/ notes for Next.js + Supabase + Vercel, Vite SPA, Electron, Python
- design/ selection guide and design library
- templates/ files the install writes into a project
- scripts/ cli.mjs: init, repair, link-skills, untrack, verify, session-check
- commands/ Claude Code plugin owner commands
- hooks/ Claude Code plugin session-start check
- .claude-plugin/ plugin manifest and marketplace entry
- ```
- ## FAQ
- **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.
- **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.
- **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.
- **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.
- ## Contributing
- Ideas, skill suggestions and fixes are welcome: see [CONTRIBUTING.md](CONTRIBUTING.md). Report security issues privately as described in [SECURITY.md](SECURITY.md).
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.