Skip to content

README.md

Latest commit

 

History

History
65 lines (57 loc) · 4.04 KB

README.md

File metadata and controls

65 lines (57 loc) · 4.04 KB

Hecate agent instructions

Canonical agent instruction layer for the Hecate repo. Tool-specific entry points (CLAUDE.md, AGENTS.md, .cursor/rules/) are thin adapters that point here — the substance lives in this directory.

Layout

docs-ai/
  README.md                       this file — load order and quick rules
  core/
    project-context.md            what Hecate is, repo layout, rings, storage tiers, toolchain pins, risky areas
    engineering-standards.md      project-wide coding/style standards (backend + UI)
    workflow.md                   default operating loop, planning triggers, commit etiquette
    verification.md               build/test ladders, done criteria, manual smoke expectations
  tasks/
    planning.md                   how to write a plan when "stop and plan first" fires
    implementation.md             how to implement once a plan exists
    debugging.md                  how to debug deliberately
    refactoring.md                how to reshape code without changing behavior
    code-review.md                review rubric and output format
    release.md                    cut a release tag (pre-flight, snapshot, gate, recovery)
  skills/
    backend/SKILL.md              Go backend skill (anything outside ui/ and tauri/)
    ui/SKILL.md                   React UI skill (ui/)
    tauri/SKILL.md                native desktop app skill (tauri/): Rust layer, sidecar
                                  lifecycle, platform bundling, gateway↔webview integration
    providers/SKILL.md            internal/providers/ skill (parallel-struct boundary, seven-step chain)
    architect/SKILL.md            posture skill: plan-first for substantial changes
    tester/SKILL.md               posture skill: test strategy and verification reporting
    devops/SKILL.md               posture skill: delivery surfaces and rollback paths

What to load

Load the skill for your area first, then core/project-context.md if you need repo layout, ring rules, or risky-area guidance. core/engineering-standards.md and core/workflow.md are reference — reach for them when you hit a style or commit question.

Task Load first Also load
Backend — any Go outside ui/ and tauri/ skills/backend/SKILL.md core/project-context.md, core/verification.md
Provider adapter (internal/providers/) skills/providers/SKILL.md skills/backend/SKILL.md
React UI (ui/) skills/ui/SKILL.md core/project-context.md, core/verification.md
Native desktop (tauri/) skills/tauri/SKILL.md core/project-context.md, core/verification.md
Substantial change — plan first skills/architect/SKILL.md + tasks/planning.md core/project-context.md
Debugging tasks/debugging.md skill for the relevant area
Code review tasks/code-review.md skill for the relevant area
Test strategy / coverage skills/tester/SKILL.md core/verification.md
Delivery / CI / env vars / schema skills/devops/SKILL.md core/verification.md
Release / tag tasks/release.md core/verification.md

Core rules (always in force)

  • Don't auto-commit. Propose a Conventional Commits message; operator merges.
  • Docs in the same change. New env var → .env.example + docs/<feature>.md. New event type → event-protocol taxonomy check + docs/events.md. Not as a follow-up.
  • Race suite is the floor for backend/runtime changes — not a nice-to-have. Use /race or go test -race -timeout 10m ./....
  • No plan labels (Phase 1, P0, #15, Milestone N) in commit messages or code comments.
  • Probe before assuming paths. grep, ls, go build before writing file paths from memory. Wrong paths compound.
  • Build early, build often. go build ./... before the first edit (confirm the tree is clean) and after each logical step.
  • Beta-scope work gets a branch. Start from current master, use a feature/refactor/docs branch, and land through PR. Direct master commits are for release mechanics or explicitly requested urgent corrections only.