Skip to content
Helmsman
Open source · steady results, every project

A playbook for your AI coding assistant.

Helmsman is a folder of instructions you add to any project. It teaches your AI to plan first, follow shared rules, write things down, and verify its work — so you get reliable output instead of guesswork.

Get startedView on GitHub
$ git clone https://github.com/fadhilmufid/helmsman
AGENTS.md
# Agent instructions
Read helmsman-agent/ first.
  • ARead first
  • BClarify
  • CDocument & design
  • DPlan
  • ETask
  • FVerify

Plain Markdown — auto-provisioned for Cursor, Claude Code, Copilot, and AGENTS.md

CursorClaude CodeGitHub CopilotWindsurfCodexGemini CLIClineAiderCursorClaude CodeGitHub CopilotWindsurfCodexGemini CLIClineAider

What it does

Six habits, one system

Helmsman bundles the practices that keep AI-assisted development predictable: plan, document, follow rules, and verify before calling something done.

Plan before you code

The agent writes a blueprint plan and a step-by-step task list before changing any files. No jumping straight into code.

Start new apps the right way

Building from scratch? Helmsman scaffolds databases, APIs, and web apps, then checks that everything runs together.

Learn existing projects first

Already have an app? On first use, Helmsman reads your codebase and documents how it works before touching features.

Keep notes in one place

Plans, feature docs, histories, and project settings live in a single folder the agent maintains for you.

One rulebook for all code

Shared standards for style and quality mean the agent writes code the same way every time.

Fresh start each session

Every new chat begins with a quick re-read of the rules, so the agent never forgets how your project works.

Two ways to use it

New project or existing code?

Helmsman adapts to whether you are starting fresh or joining a codebase that already exists.

Starting fresh

Greenfield

You are building something new. Helmsman helps set up the pieces — database, API, web app — wire them together, and confirm they run before moving on.

  • Platform-by-platform bootstrap
  • End-to-end verification before done
  • Production bar by default

Scaffolds platforms/ and verifies with Docker per helmsman-agent/instructions/GREENFIELD.md.

Already have code

Brownfield

You already have an app. On first use, Helmsman reads your repo, writes a summary of how it is built, and only then starts new feature work.

  • Scans and maps the codebase first
  • Documents before it changes anything
  • Safe, incremental feature work

Fills helmsman-agent/project/ (PROJECT-OVERVIEW, PROJECT-INFRASTRUCTURE, PROJECT-DESIGN) per helmsman-agent/instructions/BROWNFIELD.md.

Built-in checkpoints

Six gates from read to ship

Gates keep the agent from skipping ahead. It must clear each one in order — read first, plan in the middle, code last, and verify before finishing.

  1. A

    Read first

    waits: Editing app code, platforms/, deploy/

    Read the playbook and scan project notes.

  2. B

    Clarify

    waits: Starting implementation

    Answer open questions and write a project overview.

  3. C

    Document & design

    waits: Scaffolding, platforms/, deploy/

    Write feature specs and design notes in scope.

  4. D

    Plan

    waits: Writing tasks or code

    Create a blueprint plan for the work.

  5. E

    Task

    waits: Editing application files

    Write a detailed, exhaustive task checklist.

  6. F

    Verify

    waits: Marking the task complete

    Run quality checks and verify end-to-end.

Why it helps

The difference it makes

Same model, same editor — a clear, repeatable process is what separates guesswork from steady, production-ready output.

Without Helmsman

  • Jumps straight into code on the first prompt
  • Forgets project conventions between chats
  • Style and structure drift across files
  • Context lives only in the chat history
  • “Done” means it compiled once

With Helmsman

  • Reads the playbook and plans before any edit
  • Re-reads the rulebook at the start of every session
  • One shared rulebook keeps code consistent
  • Plans, docs, and histories persist in one folder
  • “Done” means verified end-to-end

What the agent sets up

Pointers at your app root

Clone the repo and open your IDE. The agent auto-creates AGENTS.md, Cursor rules, and other IDE pointers — no manual setup. Day-to-day dev commands live in helmsman-agent/project/PROJECT-AGENTS.md.

# Agent instructions

<!-- HELMSMAN:START -->

> This app uses Helmsman. Before any non-trivial work, read the
> pack at helmsman-agent/ — start with helmsman-agent/HELMSMAN-AGENT.md.

## What is Helmsman
A folder of Markdown instructions at helmsman-agent/ — no runtime, no
build step. Full workflow: helmsman-agent/HELMSMAN-AGENT.md

## Start every session here
1. Bootstrap — agents provision AGENTS.md + IDE rules (BOOTSTRAP.md)
2. Read HELMSMAN-AGENT.md in full (re-entry, gates A–F)
3. Pick a mode — GREENFIELD.md or BROWNFIELD.md
4. Scan helmsman-agent/project/ (plans, tasks, histories, config)
5. Work the gates A–F — no app code until Gate A passes

## Do not
- Flatten helmsman-agent/instructions/ or project/ outside the pack
- Put application source inside helmsman-agent/

<!-- HELMSMAN:END -->

Setup

Four steps to get started

Clone the repo and open it in your IDE — the agent provisions AGENTS.md and IDE rules automatically.

Trying Helmsman in this repo? Open this repository root in Cursor, then ask your agent to read helmsman-agent/HELMSMAN-AGENT.md and edit files under helmsman-website/.
  1. 1

    Clone the repository

    Clone Helmsman from GitHub. That is all you need in the terminal to get started.

    $ git clone https://github.com/fadhilmufid/helmsman
  2. 2

    Open your IDE

    Open the cloned repo (or your project folder) in your editor. Your agent auto-creates AGENTS.md, Cursor rules, CLAUDE.md, and other IDE pointers from helmsman-agent/templates/.

  3. 3

    Let the agent read the playbook

    Your agent reads helmsman-agent/HELMSMAN-AGENT.md and instructions/RULES.md, runs bootstrap per instructions/BOOTSTRAP.md, then works through checkpoints A–F before writing application code.

  4. 4

    Leave the pack in the app root

    Keep instructions in helmsman-agent/instructions/ and project notes in helmsman-agent/project/. Do not flatten the pack outside helmsman-agent/. Multi-app repos get one pack per app.

Questions

Frequently asked

Helmsman is intentionally simple — here is what most people want to know before trying it.

It is a folder of Markdown instructions — no runtime, no build step, no dependency. Clone the repo, open it in your IDE, and your AI coding agent reads helmsman-agent/ to learn how to work in that project.

Give your coding agent a steady hand.

Free and open source. Drop in one folder and your AI starts planning, documenting, and verifying from the very first prompt.

Get it on GitHub
$ git clone …