{
  "markdown": "# Sextant\n\n**Architecture-aware engineering principles framework for Claude Code and Codex.**\n\nSextant 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.\n\n---\n\n## Install\n\n### Codex\n\nCodex support is currently documented as a local development integration path, not a published one-command install flow.\n\nThe 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.\n\nFor 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.\n\n### Claude\n\n#### Option 1: Official Claude marketplace\n\n```\n/plugin install sextant@claude-plugins-official\n```\n\nOr use `/plugin` to open the interactive plugin manager, navigate to **Discover**, and search for \"sextant\".\n\n#### Option 2: Via GitHub marketplace\n\n```\n/plugin marketplace add hellotern/sextant\n/plugin install sextant@mohist-plugins\n```\n\n#### Option 3: Team configuration\n\nCommit `.claude/settings.json` to your repository. All team members get sextant automatically on checkout.\n\n```json\n{\n  \"extraKnownMarketplaces\": {\n    \"sextant\": {\n      \"source\": {\n        \"source\": \"github\",\n        \"repo\": \"hellotern/sextant\"\n      }\n    }\n  },\n  \"enabledPlugins\": {\n    \"sextant@sextant\": true\n  }\n}\n```\n\nSkills are available immediately — no restart required.\n\n#### Updating\n\n```\n/plugin update sextant\n```\n\n### Cursor\n\n#### Option 1: Project-level install\n\nClone the repo and run the installer from your project directory:\n\n```bash\ngit clone https://github.com/hellotern/sextant\ncd your-project\npython path/to/sextant/.cursor-plugin/install.py\n```\n\n#### Option 2: Global install (all Cursor projects)\n\n```bash\npython path/to/sextant/.cursor-plugin/install.py --global\n```\n\n#### Usage\n\n- Engineering principles (`§0–§6`) are **automatically active** in every Cursor AI interaction.\n- Invoke a workflow via the `/` command menu in Cursor chat: `/sextant-fix-bug`, `/sextant-add-feature`, `/sextant-review-code`, etc.\n- GitNexus integration activates automatically when `.gitnexus/` is present in your project.\n\n#### Updating\n\nPull the latest version and re-run the installer:\n\n```bash\ncd sextant && git pull\npython path/to/sextant/.cursor-plugin/install.py\n```\n\n---\n\n## How It Works\n\n> For an interactive version of the loading flow diagram, see [sextant_loading_flow.html](sextant_loading_flow.html).\n\n```mermaid\nflowchart TD\n    A([\"User prompt\"]) --> B\n\n    B[\"Host matches task type\n    to a sextant-* skill\"]\n    B --> R1[\"sextant:fix-bug\"]\n    B --> R2[\"sextant:add-feature\"]\n    B --> R3[\"sextant:modify-feature\"]\n    B --> R4[\"sextant:review-code\"]\n    B --> R5[\"sextant:write-tests\"]\n    B --> R6[\"sextant:refine-requirements\"]\n    B --> R8[\"sextant:debug\"]\n    B --> R9[\"sextant:ship\"]\n    B --> R10[\"sextant:plan\"]\n    B --> R11[\"sextant:migrate\"]\n    B --> R12[\"sextant:security\"]\n    B --> R7[\"sextant (fallback)\"]\n\n    R1 --> C\n    R2 --> C\n    R3 --> C\n    R4 --> C\n    R5 --> C\n    R6 --> C\n    R8 --> C\n    R9 --> C\n    R10 --> C\n    R11 --> C\n    R12 --> C\n    R7 --> F[\"principles/SKILL.md\n    loaded directly as the skill\"]\n\n    C[\"Sub-skill loads via direct include\"]\n    C --> P[\"principles/SKILL.md\n    §0 · §1 · §2 first (always)\n    ── lightweight gate ──\n    §3 · §4 · §5 · §6 (medium/large only)\"]\n    C --> GN[\"tool-gitnexus/SKILL_BODY.md\n    (always included)\"]\n    P --> D[\"Task workflow executes\"]\n    GN --> D\n    F --> D\n\n    D --> S1[\"Light — §0+§1+§2 core path · one-liner output\"]\n    D --> S2[\"Medium — +SRP · DRY · contracts\"]\n    D --> S3[\"Large — Full SOLID + arch review\"]\n\n    classDef skill       fill:#f8fafc,stroke:#cbd5e1,color:#475569\n    classDef inject      fill:#dbeafe,stroke:#2563eb,color:#1e40af\n    classDef conditional fill:#fef3c7,stroke:#d97706,color:#92400e\n    classDef fallback    fill:#f0fdf4,stroke:#86efac,color:#16a34a\n\n    class R1,R2,R3,R4,R5,R6,R7,R8,R9,R10,R11,R12 skill\n    class P,D inject\n    class GN conditional\n    class F fallback\n```\n\nSextant operates as a **layered skill system**:\n\n1. **Skill Matching** — The host identifies the task type (bug fix, new feature, etc.) and loads the corresponding sextant skill\n2. **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\n3. **Scale Assessment** — Activates rules proportionally to task size (lightweight / medium / large)\n4. **Workflow Execution** — Follows the structured workflow, applying only principles relevant to the current task\n\n### Task Types\n\n| Task Type | Skill | Key behavior |\n|-----------|-------|--------------|\n| Bug Fix | `sextant:fix-bug` | Disambiguation gate vs modify-feature; surgical minimal-change fix; **progress block + confirmation gate** before applying any fix |\n| 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) |\n| 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) |\n| Code Review | `sextant:review-code` | **Declares Review-only or Review+patch mode** before reading any code; **progress block** per review dimension |\n| Write Tests | `sextant:write-tests` | Bug-fix entry path for reproduction tests; **progress block + confirmation gate** (new test modules / full coverage passes) |\n| Requirements Analysis & Refinement | `sextant:refine-requirements` | Break down ambiguous requirements before coding |\n| Debug (symptom known, location unknown) | `sextant:debug` | Paradigm-aware bisection; hypothesis limit gate after 3+ eliminations; hands off to fix-bug |\n| Ship / PR Preparation | `sextant:ship` | Pre-ship checklist; structured PR description; post-merge verification |\n| Sprint Planning | `sextant:plan` | Dependency-ordered task list; transitions to execution pipeline entry after plan confirmation |\n| Migration (multi-module, versioned) | `sextant:migrate` | Leaf-first migration sequence; **progress block + confirmation gate** between phases; legacy cleanup |\n| Security Audit | `sextant:security` | 4-dimension audit: input validation, auth/authZ, sensitive data, manifest-verifiable dependency checks; **progress block** per dimension |\n| General Coding | `sextant` (fallback) | Lightweight tasks and exempt scenarios |\n\n### Rule Scaling\n\n| Scale | Trigger | Active Rules | Output format |\n|-------|---------|--------------|---------------|\n| **Lightweight** | Single-function adjustments, config changes, style fixes | §0 baselines + §1 anti-pattern flags + §2 direct execution | One-liner (`✅` / `⚠️`) |\n| **Medium** | New functions/classes, module-internal changes, bug fixes | + §3 task rules + §4 SOLID + §5 DRY/contracts | Full summary block |\n| **Large** | Cross-module changes, public interface modifications, new modules | Full §3–§6 activation + architecture audit | Full summary block |\n\n### Interactive Execution Features\n\nMulti-step skills include two interactive behaviors that keep the user in control throughout execution:\n\n**Progress tracking** — At the start of each applicable step, the skill outputs a live progress block so the user always knows where execution is:\n\n```\nBug Fix Progress\n✓ Step 1: Reproduce & Locate   — root cause: off-by-one in index range\n→ Step 2: Impact Assessment    — in progress\n○ Step 3: Minimal-Change Fix\n○ Step 4: Boundary Validation\n```\n\nSkills with progress tracking: `fix-bug`, `add-feature`, `modify-feature`, `write-tests`, `migrate`, `review-code`, `security`.\n\n**Confirmation Gate** — Before writing any code, the skill uses a confirmation gate with a structured plan summary (root cause, files to change, risk level) and waits for explicit approval. If the host supports `AskUserQuestion`, it should use it. Otherwise, it should present the same question and options directly in the conversation. Code is never written until the user selects \"Yes\". If the user selects \"No\", the skill asks for direction, revises the plan, and presents it again.\n\nEach skill defines its own trigger threshold:\n- `fix-bug` — gates on **all** risk levels (High / Medium / Low). Low-risk offers an additional option to skip confirmations for the rest of the session.\n- `add-feature`, `modify-feature`, `write-tests`, `migrate` — gate on **medium and large** tasks only; lightweight tasks proceed directly.\n\nSkills with a confirmation gate: `fix-bug`, `add-feature`, `modify-feature`, `write-tests`, `migrate`.\n\n---\n\n### Exempt Scenarios\n\nThe following bypass most rules (baseline rules §0 still apply, with §1 limited to §0-only violations):\n- One-off scripts / temporary tools\n- Demos / prototypes / POCs\n- Algorithm problems / competitive programming\n- Notebooks / data exploration\n\n---\n\n## Core Principles\n\n### SOLID\n- **SRP** — Every module, class, and function has one responsibility and one reason to change\n- **OCP** — Open for extension, closed for modification\n- **LSP** — Subclasses must be transparently substitutable for their base classes\n- **ISP** — Interfaces stay small; implementors are not forced to depend on unused methods\n- **DIP** — High-level modules depend on abstractions, not concrete implementations\n\n### Architecture Constraints\n- **Hollywood Principle** — Modules declare dependencies (injected); they don't proactively pull them\n- **Dependency Direction** — Entry → Logic → Data → Infrastructure (one-way, no reversal)\n- **Module Boundaries** — Cross-module communication via public interfaces or event bus only\n\n### Code Quality Baselines (§0 — Always Active)\nNever swallow exceptions · No magic numbers or strings · Accurate function naming · Validate parameters at public interfaces · Explicit type declarations · Meaningful log messages · Explicit dependency declaration · Side effects isolated from pure computation\n\n---\n\n## GitNexus Integration (Optional)\n\n> **GitNexus is NOT required.** Sextant works fully without it. When GitNexus is present, certain manual grep/read steps are replaced with precise graph queries — it's a performance accelerator, not a dependency.\n\n[GitNexus](https://gitnexus.dev) indexes your codebase as a knowledge graph and exposes MCP tools. `tool-gitnexus/SKILL_BODY.md` is always included in every sub-skill — the content describes GitNexus tools and the agent will apply them only when the MCP tools are actually available:\n\n| Manual Approach | GitNexus Enhanced |\n|----------------|-------------------|\n| Grep for function, read call chain file by file | `context` returns complete caller/callee graph in one call |\n| Estimate \"what will this change break\" | `impact` returns layered impact list with confidence scores |\n| `pydeps` / `madge` for circular dependency detection | `impact both` queries the graph, covers all languages |\n| Search for similar code to avoid duplication | `query` semantic search + cluster membership |\n| Manually review `git diff` impact | `diff_review` analyzes change impact automatically |\n\nTo enable: run `npx gitnexus analyze` in your project root. Sextant detects the resulting `.gitnexus/` directory automatically.\n\n---\n\n\n## File Structure\n\n```\nsextant/\n├── skills/\n│   ├── principles/              # §0·§1·§2 first (always), then §3–§6 (medium/large) — shared source + fallback skill\n│   │   ├── SKILL.md             # frontmatter (skill description) + !SKILL_BODY.md\n│   │   ├── SKILL_BODY.md        # body content — included by all sub-skills\n│   │   └── strip_frontmatter.py\n│   ├── fix-bug/                 # Bug fix workflow\n│   │   └── SKILL.md\n│   ├── add-feature/             # New feature workflow (+ optional TDD contract tests)\n│   │   └── SKILL.md\n│   ├── modify-feature/          # Modify/refactor workflow (+ optional TDD baseline + contract tests)\n│   │   └── SKILL.md\n│   ├── review-code/             # Code review workflow\n│   │   └── SKILL.md\n│   ├── write-tests/             # Test writing workflow\n│   │   └── SKILL.md\n│   ├── refine-requirements/     # Requirements analysis workflow\n│   │   └── SKILL.md\n│   ├── debug/                   # Debug workflow: symptom known, location unknown\n│   │   └── SKILL.md\n│   ├── ship/                    # Ship / PR preparation workflow\n│   │   └── SKILL.md\n│   ├── plan/                    # Sprint planning: dependency-ordered task list\n│   │   └── SKILL.md\n│   ├── migrate/                 # Multi-module migration workflow\n│   │   └── SKILL.md\n│   ├── security/                # Security audit workflow (4-dimension)\n│   │   └── SKILL.md\n│   └── tool-gitnexus/           # GitNexus integration (always included)\n│       ├── SKILL.md             # frontmatter + !SKILL_BODY.md\n│       └── SKILL_BODY.md        # body content — included by all sub-skills\n├── README.md\n└── LICENSE\n```\n\nEach task skill directly includes `principles/SKILL_BODY.md` and `tool-gitnexus/SKILL_BODY.md` via the `!` file directive — no bash command or external tool required. The principles file is structured so that §0 (quality baselines), §1 (anti-pattern detection), and §2 (communication standards) appear first, followed by an explicit lightweight task gate before the heavier §3–§6 sections (task rules, SOLID, DRY/YAGNI, architecture). This means the full principles body is always loaded into context, but short tasks exit early without processing the heavier sections. **One skill load = principles (front-loaded) + GitNexus reference + task workflow**.\n\n---\n\n## Project Configuration\n\nSextant works without any configuration. The following optional files let you customize behavior per project.\n\n### `.sextant.yaml` — Principle Configuration\n\nPlace in your project root to override TDD defaults and principle weights:\n\n```yaml\n# .sextant.yaml (optional — place in project root)\n\n# TDD mode for add-feature and modify-feature\n# off (default) | default_on | enforce\ntdd: off\n\n# Optional profile shorthand (documents project context)\n# profile: fast-iteration | financial | library\n\n# Principle weight overrides (maximum | high | normal | low | off)\n# principles:\n#   yagni: high          # raise YAGNI weight in this project\n#   ocp: low             # lower OCP weight (e.g. prototype context)\n```\n\n**`tdd` values:**\n- `off` (default) — scale-based prompts apply: add-feature Large defaults Y, Medium defaults n; modify-feature Large defaults Y\n- `default_on` — treats both Large and Medium as default Y across all workflows\n- `enforce` — TDD is mandatory; the prompt is skipped and tests are always written first\n\n**Principle weight values:** `maximum` (hard gate, blocks implementation) · `high` (strong recommendation) · `normal` (default) · `low` (advisory only) · `off` (suppressed)\n\n### `.sextant/state.json` — Sprint State\n\nCreated by `sextant:plan` (with explicit user confirmation) to persist sprint progress across sessions:\n\n```json\n{\n  \"version\": \"1\",\n  \"sprint\": {\n    \"requirement\": \"Add user notification system\",\n    \"tasks\": [\n      {\n        \"id\": 1,\n        \"title\": \"Add NotificationRepository interface\",\n        \"skill\": \"sextant:add-feature\",\n        \"scale\": \"Medium\",\n        \"status\": \"done\",\n        \"depends_on\": [],\n        \"acceptance\": \"Given a new notification, when save() is called, then the notification is persisted and retrievable by ID.\",\n        \"flags\": []\n      },\n      {\n        \"id\": 2,\n        \"title\": \"Implement NotificationService\",\n        \"skill\": \"sextant:add-feature\",\n        \"scale\": \"Medium\",\n        \"status\": \"in_progress\",\n        \"depends_on\": [1],\n        \"acceptance\": \"Given a user ID, when send() is called, then the notification is persisted and the user's unread count increments.\",\n        \"flags\": []\n      }\n    ],\n    \"suggested_sequence\": [1, 2, 3]\n  },\n  \"flags\": []\n}\n```\n\nTask `status` values: `pending` · `in_progress` · `done` · `blocked`\n\nWhen `sextant:plan` is invoked and `.sextant/state.json` exists, it offers to resume the existing sprint or start a new one.\n\n---\n\n## Design Philosophy\n\n**First establish a safe floor, then route by task shape, then apply heavier engineering pressure only when justified.**\n\n- **Safe floor:** Baseline quality rules, obvious anti-pattern checks, and direct communication rules apply first.\n- **Route:** Task type, scale, and exempt status determine how much rigor is needed.\n- **Pressure:** SOLID, DRY/YAGNI, and architecture constraints activate progressively for medium and large tasks.\n\n**Principles are tools, not chains.** The goal is the lowest long-term maintenance cost for the team. When principles conflict, that standard is the final arbiter.\n\n**Only activate what the task needs.** A one-line bug fix doesn't need a full architecture audit. Sextant scales its rigor to match the scope of the work.\n\n**Understand before acting.** Every workflow starts with reading and understanding existing code and its context. Changing code without reading it is like rerouting plumbing without a floor plan.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n",
  "bytes": 17781,
  "sha": "b89c1f90021236d052602325a640ce14d18958010f34649f41cdc40a73a56110",
  "repo_slug": "hellotern/sextant",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_hellotern_sextant_sextant_4fde465f/readme"
}