# sextant

Adopt this skill: https://proskills.md/skills/other/hellotern-sextant-skills-principles

Page: https://proskills.md/skills/other/hellotern-sextant-skills-principles
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/principles/SKILL.md
size: 854
upstream: https://github.com/hellotern/sextant/blob/main/skills/principles/SKILL.md

```text
---
name: sextant
description: >-
  Fallback for general coding work that does not match any specific sextant sub-skill.
  Use for lightweight tasks: config changes, style fixes, utility functions, one-off scripts, or tasks too small to warrant a dedicated workflow.
  All dedicated sub-skills take priority over this one — check these first: sextant:fix-bug (broken behavior), sextant:debug (unknown bug location), sextant:add-feature (new functionality), sextant:modify-feature (changing existing behavior), sextant:review-code (evaluating code), sextant:write-tests (test coverage), sextant:refine-requirements (ambiguous scope), sextant:plan (multi-step sequencing), sextant:ship (release prep), sextant:migrate (cross-module upgrade), sextant:security (vulnerability audit).
  Only use this skill when none of the above match.
---

!SKILL_BODY.md
```

## File: README.md
upstream: https://github.com/hellotern/sextant/blob/main/README.md

````text
# 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`](.codex-plugin/plugin.json) and points to the shared [skills/](skills) directory.

For local testing, [`.agents/plugins/marketplace.json`](.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.

```json
{
  "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:

```bash
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)

```bash
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:

```bash
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](sextant_loading_flow.html).

```mermaid
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

| Task Type | Skill | Key behavior |
|-----------|-------|--------------|
| Bug Fix | `sextant:fix-bug` | Disambiguation gate vs modify-feature; surgical minimal-change fix; **progress block + confirmation gate** before applying any fix |
| New Feature / Module | `sextant:add-feature` | Full impact analysis before implementation; TDD contract tests (Large: default Y, Medium: opt-in); **progress block + confirmation gate** (medium/large) |
| Modify / Enhance / Refactor | `sextant:modify-feature` | Disambiguation gate vs fix-bug; multi-step change strategy; TDD baseline + contract tests (Large: default Y); **progress block + confirmation gate** (medium/large) |
| Code Review | `sextant:review-code` | **Declares Review-only or Review+patch mode** before reading any code; **progress block** per review dimension |
| Write Tests | `sextant:write-tests` | Bug-fix entry path for reproduction tests; **progress block + confirmation gate** (new test modules / full coverage passes) |
| Requirements Analysis & Refinement | `sextant:refine-requirements` | Break down ambiguous requirements before coding |
| Debug (symptom known, location unknown) | `sextant:debug` | Paradigm-aware bisection; hypothesis limit gate after 3+ eliminations; hands off to fix-bug |
| Ship / PR Preparation | `sextant:ship` | Pre-ship checklist; structured PR description; post-merge verification |
| Sprint Planning | `sextant:plan` | Dependency-ordered task list; transitions to execution pipeline entry after plan confirmation |
| Migration (multi-module, versioned) | `sextant:migrate` | Leaf-first migration sequence; **progress block + confirmation gate** between phases; legacy cleanup |
| Security Audit | `sextant:security` | 4-dimension audit: input validation, auth/authZ, sensitive data, manifest-verifiable dependency checks; **progress block** per dimension |
| General Coding | `sextant` (fallback) | Lightweight tasks and exempt scenarios |

### Rule Scaling

| Scale | Trigger | Active Rules | Output format |
|-------|---------|--------------|---------------|
| **Lightweight** | Single-function adjustments, config changes, style fixes | §0 baselines + §1 anti-pattern flags + §2 direct execution | One-liner (`✅` / `⚠️`) |
| **Medium** | New functions/classes, module-internal changes, bug fixes | + §3 task rules + §4 SOLID + §5 DRY/contracts | Full summary block |
| **Large** | Cross-module changes, public interface modifications, new modules | Full §3–§6 activation + architecture audit | Full summary block |

### Interactive Execution Features

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

**Progress tracking** — At the start 
````
