oring

A Toolkit for Agentic Dev.

Three-pillars align for best results: Spec (Human), Sessions (Agent), Git (Truth)

Hooks

Oring packages portable TypeScript hook engines for:

• MARK section density checks
• TypeScript/JavaScript exported-contract JSDoc checks
• AI-assisted codebase tree generation

Quality and tree automation run from Git pre-commit, scoped to the staged commit.

The repository has these hook-related locations:

• .oring/ is Oring's own live hook policy and vendored-engine namespace.
• .githooks/ is Oring's own live Git hook config.
• src/hooks/ contains reusable TypeScript hook engine source.
• dist/hooks/ contains compiled hook engines copied into target repositories.
• templates/target-repo/ contains .oring/ and .githooks/ templates copied into other repositories.

Install into another repository:

npx -p @knowledgekit/oring oring hooks install --target /path/to/repo

Install into a monorepo subfolder and choose the LLM harness:

npx -p @knowledgekit/oring oring hooks install \
  --target /path/to/repo \
  --scope speculator-app \
  --hooks code-structure,codebase-tree \
  --provider codex \
  --model gpt-5 \
  --reasoning high

Use --hooks code-structure to install only structure/JSDoc/MARK checks, or --hooks codebase-tree to install only codebase tree generation. The default is --hooks all, which enables both helpers.

Update an existing install:

npx -p @knowledgekit/oring oring hooks update --target /path/to/repo

Remove Oring from a repository:

npx -p @knowledgekit/oring oring hooks uninstall --target /path/to/repo

Inspect drift before updating:

npx -p @knowledgekit/oring oring hooks diff --target /path/to/repo

Validate an install:

npx -p @knowledgekit/oring oring hooks doctor --target /path/to/repo

The installer also writes .githooks/pre-commit and sets the target repo's local Git config:

git config core.hooksPath .githooks

When a repository already has Git hooks, Oring adds a managed block instead of replacing the whole hook file:

• Existing core.hooksPath: Oring writes into that active hooks directory and leaves core.hooksPath unchanged.
• Existing .githooks/pre-commit: Oring preserves the existing script and adds its managed block.
• Existing .git/hooks/pre-commit with no core.hooksPath: Oring preserves that local hook and adds its managed block there.
• Fresh repo with no active hook: Oring creates .githooks/pre-commit and sets core.hooksPath=.githooks.

Uninstall removes Oring's managed block and vendored .oring/ files. It leaves unrelated hook content alone, and only unsets core.hooksPath when Oring created the now-empty .githooks directory.

Run the pre-commit flow intentionally:

npx -p @knowledgekit/oring oring precommit --target /path/to/repo
npx -p @knowledgekit/oring oring precommit --target /path/to/repo --disable-repair

Run structure checks intentionally:

npx -p @knowledgekit/oring oring hooks check --target /path/to/repo
npx -p @knowledgekit/oring oring hooks check --target /path/to/repo --all

The pre-commit flow checks staged content inside the configured scope. When structure findings exist, it uses the configured LLM harness to semantically repair the originally staged files, restages those files, verifies the staged snapshot, regenerates the codebase tree from staged content, and stages the generated tree. hooks check --all is the retroactive audit path for existing exported contracts and public class methods.

Repo-specific policy lives in:

.oring/config.json

Vendored Oring hook engines live under:

.oring/hooks/*.mjs

The target repository Git hook lives under:

.githooks/pre-commit

The installer writes source/version/hash metadata to:

.oring/oring.lock.json

Oring's Node hook engines read .oring/config.json.

The installer writes these onboarding choices into .oring/config.json:

{
  "scope": {
    "root": "speculator-app"
  },
  "hooks": {
    "preCommit": ["code-structure", "codebase-tree"]
  },
  "agent": {
    "provider": "codex",
    "model": "gpt-5",
    "reasoning": "high"
  }
}

Supported agent providers are codex and claude. For Codex, model maps to codex exec -m and reasoning maps to model_reasoning_effort. For Claude, model maps to claude --model and reasoning maps to claude --effort.

Local development:

npm run check
npm run pack:dry-run

Issue Search

Oring can sync GitHub issues into a local SQLite FTS5 cache for fast, network-free lookup by external composer integrations:

oring issues sync --repo KnowledgeKitAI/oring
oring issues search --repo KnowledgeKitAI/oring --json keystroke
oring issues hydrate --repo KnowledgeKitAI/oring --json 1

If --repo is omitted, Oring infers a GitHub owner/name repo from git remote get-url origin. See docs/issue-search.md for the JSON contract, composer integration contract, Codex TUI patch map, and local prototype validation steps.

Issue sync is explicit today. oring issues search and oring issues hydrate read only from the local cache, so run oring issues sync when you need fresh GitHub state. Staleness-aware sync is tracked in issue #3.