sextant

Sextant

Architecture-aware engineering principles framework for Claude Code and Codex.

Sextant provides systematic, tiered workflows for the full software engineering lifecycle — bug fixes, new features, refactoring, code review, test writing, requirements refinement, debugging, shipping, sprint planning, migrations, and security audits. Like a nautical sextant that helps navigators fix their exact position before charting a course, it helps the agent understand where it is in the codebase before making changes.

---

Install

Codex

Codex support is currently documented as a local development integration path, not a published one-command install flow.

The repository root is the plugin root. The Codex manifest lives at .codex-plugin/plugin.json and points to the shared skills/ directory.

For local testing, .agents/plugins/marketplace.json provides a repo-local marketplace entry that points back to this repository. Use it as a development setup reference, not as a published installation contract.

Claude

Option 1: Official Claude marketplace

/plugin install sextant@claude-plugins-official

Or use /plugin to open the interactive plugin manager, navigate to Discover, and search for "sextant".

Option 2: Via GitHub marketplace

/plugin marketplace add hellotern/sextant
/plugin install sextant@mohist-plugins

Option 3: Team configuration

Commit .claude/settings.json to your repository. All team members get sextant automatically on checkout.

{
  "extraKnownMarketplaces": {
    "sextant": {
      "source": {
        "source": "github",
        "repo": "hellotern/sextant"
      }
    }
  },
  "enabledPlugins": {
    "sextant@sextant": true
  }
}

Skills are available immediately — no restart required.

Updating

/plugin update sextant

Cursor

Option 1: Project-level install

Clone the repo and run the installer from your project directory:

git clone https://github.com/hellotern/sextant
cd your-project
python path/to/sextant/.cursor-plugin/install.py

Option 2: Global install (all Cursor projects)

python path/to/sextant/.cursor-plugin/install.py --global

Usage

• Engineering principles (§0–§6) are automatically active in every Cursor AI interaction.
• Invoke a workflow via the / command menu in Cursor chat: /sextant-fix-bug, /sextant-add-feature, /sextant-review-code, etc.
• GitNexus integration activates automatically when .gitnexus/ is present in your project.

Updating

Pull the latest version and re-run the installer:

cd sextant && git pull
python path/to/sextant/.cursor-plugin/install.py

---

How It Works

For an interactive version of the loading flow diagram, see sextant_loading_flow.html.

flowchart TD
    A(["User prompt"]) --> B

    B["Host matches task type
    to a sextant-* skill"]
    B --> R1["sextant:fix-bug"]
    B --> R2["sextant:add-feature"]
    B --> R3["sextant:modify-feature"]
    B --> R4["sextant:review-code"]
    B --> R5["sextant:write-tests"]
    B --> R6["sextant:refine-requirements"]
    B --> R8["sextant:debug"]
    B --> R9["sextant:ship"]
    B --> R10["sextant:plan"]
    B --> R11["sextant:migrate"]
    B --> R12["sextant:security"]
    B --> R7["sextant (fallback)"]

    R1 --> C
    R2 --> C
    R3 --> C
    R4 --> C
    R5 --> C
    R6 --> C
    R8 --> C
    R9 --> C
    R10 --> C
    R11 --> C
    R12 --> C
    R7 --> F["principles/SKILL.md
    loaded directly as the skill"]

    C["Sub-skill loads via direct include"]
    C --> P["principles/SKILL.md
    §0 · §1 · §2 first (always)
    ── lightweight gate ──
    §3 · §4 · §5 · §6 (medium/large only)"]
    C --> GN["tool-gitnexus/SKILL_BODY.md
    (always included)"]
    P --> D["Task workflow executes"]
    GN --> D
    F --> D

    D --> S1["Light — §0+§1+§2 core path · one-liner output"]
    D --> S2["Medium — +SRP · DRY · contracts"]
    D --> S3["Large — Full SOLID + arch review"]

    classDef skill       fill:#f8fafc,stroke:#cbd5e1,color:#475569
    classDef inject      fill:#dbeafe,stroke:#2563eb,color:#1e40af
    classDef conditional fill:#fef3c7,stroke:#d97706,color:#92400e
    classDef fallback    fill:#f0fdf4,stroke:#86efac,color:#16a34a

    class R1,R2,R3,R4,R5,R6,R7,R8,R9,R10,R11,R12 skill
    class P,D inject
    class GN conditional
    class F fallback

Sextant operates as a layered skill system:

1. Skill Matching — The host identifies the task type (bug fix, new feature, etc.) and loads the corresponding sextant skill
2. Direct Injection — Each sub-skill directly includes principles/SKILL_BODY.md at load time via the ! file directive (no bash command required). The file is front-loaded: §0 (baselines), §1 (anti-pattern detection), and §2 (communication) appear first, followed by a lightweight task gate — so short tasks stop reading early without needing a separate file
3. Scale Assessment — Activates rules proportionally to task size (lightweight / medium / large)
4. Workflow Execution — Follows the structured workflow, applying only principles relevant to the current task

Task Types

Rule Scaling

Interactive Execution Features

Multi-step skills include two interactive behaviors that keep the user in control throughout execution:

Progress tracking — At the start