threadroot 0.1.0

package/package.json

@@ -0,0 +1,81 @@
+{
+  "name": "threadroot",
+  "version": "0.1.0",
+  "description": "Git for your AI agent harness: author skills, rules, tools, and memory once and compile them to every vendor format.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "threadroot": "dist/index.js",
+    "tr": "dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Sevan1211/threadroot.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Sevan1211/threadroot/issues"
+  },
+  "homepage": "https://github.com/Sevan1211/threadroot#readme",
+  "keywords": [
+    "ai",
+    "agents",
+    "agentic",
+    "codex",
+    "claude",
+    "cursor",
+    "copilot",
+    "mcp",
+    "developer-tools",
+    "cli",
+    "skills"
+  ],
+  "files": [
+    "dist",
+    "skills",
+    "packs",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsx src/index.ts",
+    "prepack": "pnpm build",
+    "prepublishOnly": "pnpm typecheck && pnpm lint && pnpm test",
+    "pack:check": "npm --cache /tmp/threadroot-npm-cache pack --dry-run",
+    "package:smoke": "node scripts/package-smoke.mjs",
+    "release:check": "pnpm typecheck && pnpm lint && pnpm test && pnpm pack:check && pnpm package:smoke",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint ."
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "yaml": "^2.9.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9",
+    "@types/node": "^22.10.2",
+    "eslint": "^9",
+    "tsup": "^8.3.5",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8",
+    "vitest": "^2.1.8"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@9.12.0"
+}

package/packs/code-review/pack.yaml

@@ -0,0 +1,7 @@
+name: code-review
+version: 1
+description: Code review and commit hygiene skills for agent-assisted development.
+skills:
+  - skills/code-review
+  - skills/security-review
+  - skills/conventional-commits

package/packs/python/pack.yaml

@@ -0,0 +1,10 @@
+name: python
+version: 1
+description: Python project skills for tests, debugging, review, docs, and tool authoring.
+skills:
+  - skills/add-test
+  - skills/debug-failure
+  - skills/code-review
+  - skills/security-review
+  - skills/write-docs
+  - skills/build-tool

package/packs/react-app/pack.yaml

@@ -0,0 +1,10 @@
+name: react-app
+version: 1
+description: React application skills for testing, review, docs, and safe tool authoring.
+skills:
+  - skills/add-test
+  - skills/debug-failure
+  - skills/code-review
+  - skills/security-review
+  - skills/write-docs
+  - skills/build-tool

package/packs/security-review/pack.yaml

@@ -0,0 +1,7 @@
+name: security-review
+version: 1
+description: Security review skills for identifying risky code, tools, and project changes.
+skills:
+  - skills/security-review
+  - skills/code-review
+  - skills/build-tool

package/packs/system-design/pack.yaml

@@ -0,0 +1,5 @@
+name: system-design
+version: 1
+description: System design skills for architecture, APIs, data, reliability, and observability.
+skills:
+  - skills/system-design

package/packs/testing/pack.yaml

@@ -0,0 +1,7 @@
+name: testing
+version: 1
+description: Testing-focused skills for adding, fixing, and reviewing project tests.
+skills:
+  - skills/add-test
+  - skills/debug-failure
+  - skills/code-review

package/packs/typescript-node/pack.yaml

@@ -0,0 +1,9 @@
+name: typescript-node
+version: 1
+description: Core TypeScript and Node.js agent harness skills for CLI and library projects.
+skills:
+  - skills/add-test
+  - skills/debug-failure
+  - skills/code-review
+  - skills/build-tool
+  - skills/conventional-commits

package/skills/README.md

@@ -0,0 +1,39 @@
+# Threadroot Skills
+
+Curated Agent Skills that can be installed into any Threadroot harness.
+
+```bash
+threadroot install github:Sevan1211/threadroot/skills/system-design@main --kind skill
+threadroot install github:Sevan1211/threadroot/skills/build-skill@main --kind skill
+threadroot skills validate --path skills
+threadroot skills inspect skills/system-design
+```
+
+Each skill uses the folder shape:
+
+```text
+skills/<name>/
+  SKILL.md
+  references/
+  scripts/
+  assets/
+  evals/triggers.json
+```
+
+Keep `SKILL.md` compact and procedural. Put detailed checklists, examples, and
+variant-specific guidance in `references/`, then link those files from `SKILL.md` so
+agents can load only the relevant details for the task.
+
+Good skills should:
+
+- Use a precise `description` that tells the agent when to trigger the skill.
+- Keep always-loaded instructions short enough to fit comfortably in context.
+- Move deep guidance, examples, and checklists into linked reference files.
+- Include `evals/triggers.json` with positive and negative trigger examples.
+- Avoid scripts and allowed tools unless the workflow truly needs them.
+
+Validate the curated pack before release:
+
+```bash
+threadroot skills validate --path skills
+```

package/skills/add-test/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: add-test
+description: Use when adding, fixing, or reviewing tests for code changes, bugs, edge cases, regressions, CLI behavior, MCP tools, schemas, adapters, or generated output.
+scope: project
+tags:
+  - testing
+---
+
+# Add Test
+
+Write tests that pin observable behavior, not implementation trivia.
+
+## Workflow
+
+1. Identify the behavior, boundary, or bug being protected.
+2. Find the nearest existing test style and reuse local helpers.
+3. Cover the happy path and at least one meaningful failure or edge case.
+4. Keep tests deterministic and independent.
+5. If fixing a bug, confirm the test fails before the fix when practical.
+6. Run the narrow test first, then the broader gate.

package/skills/add-test/evals/triggers.json

@@ -0,0 +1,12 @@
+{
+  "shouldTrigger": [
+    "Add regression tests for this bug fix.",
+    "Write tests that cover this CLI command's failure modes.",
+    "Update the test suite for this schema validation change."
+  ],
+  "shouldNotTrigger": [
+    "Review this PR for security issues.",
+    "Plan the architecture for a new service.",
+    "Write a README quickstart."
+  ]
+}

package/skills/build-skill/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: build-skill
+description: Use when creating, reviewing, or improving Threadroot or Agent Skills, including SKILL.md descriptions, progressive disclosure, bundled references/scripts/assets, validation, trigger quality, and skill evals.
+scope: project
+tags:
+  - skills
+  - agent-harness
+  - prompting
+---
+
+# Build Skill
+
+Build skills as compact operating procedures, not essays. Assume the model is capable; add only context that improves repeatability, accuracy, or safety.
+
+## Workflow
+
+1. Capture concrete trigger examples and non-trigger examples.
+2. Write a precise `description` that says what the skill does and when to use it. The description is the trigger surface.
+3. Keep `SKILL.md` procedural and short. Move variant details, schemas, examples, policies, and longer guidance into `references/`.
+4. Add scripts only for deterministic, fragile, or frequently repeated work. Scripts must be non-interactive and have clear errors.
+5. Add assets only when the skill needs reusable output material such as templates or boilerplate.
+6. Add eval prompts that compare with-skill and without-skill behavior on realistic tasks.
+7. Validate frontmatter, folder naming, reference links, and token footprint before shipping.
+
+## Quality Bar
+
+- Prefer one strong skill per repeatable workflow over giant catch-all skills.
+- Keep instructions imperative and directly actionable.
+- Include failure modes and validation steps.
+- Do not duplicate reference content in `SKILL.md`; link to it.
+- Never hide risky tool use in a skill. Surface confirmation, trust, and environment needs clearly.
+
+## Reference Loading
+
+- Read `references/skill-quality.md` before authoring a new curated skill.
+- Read `references/eval-prompts.md` when adding or reviewing skill tests.

package/skills/build-skill/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "shouldTrigger": [
+    "Create a skill for reviewing Prisma schema migrations.",
+    "Improve this SKILL.md so it triggers more accurately and uses references correctly.",
+    "Help me design eval prompts for a frontend performance skill."
+  ],
+  "shouldNotTrigger": [
+    "Use the existing testing skill to add coverage for this function.",
+    "Install a package from npm.",
+    "Summarize this product requirement document."
+  ],
+  "expectedReferences": [
+    "references/skill-quality.md",
+    "references/eval-prompts.md"
+  ]
+}

package/skills/build-skill/references/eval-prompts.md

@@ -0,0 +1,20 @@
+# Skill Eval Prompts
+
+Use these prompt patterns to validate a skill.
+
+## Should Trigger
+
+- Ask for the exact workflow the skill claims to improve.
+- Include ambiguous real-world constraints.
+- Check whether the agent loads only relevant references.
+
+## Should Not Trigger
+
+- Ask for adjacent tasks that share vocabulary but not intent.
+- Check that the skill description is not too broad.
+
+## Output Checks
+
+- Did the answer follow the skill workflow?
+- Did it avoid irrelevant reference loading?
+- Did it produce safer, more specific, or more complete output than a no-skill baseline?

package/skills/build-skill/references/skill-quality.md

@@ -0,0 +1,18 @@
+# Skill Quality
+
+A strong skill has:
+
+- Clear trigger description with realistic language users and agents will use.
+- A narrow job and explicit boundaries.
+- A short procedural body that changes behavior after loading.
+- References for deep details, split by task variant.
+- Scripts for deterministic repeated work.
+- Evals that prove it improves outcomes.
+
+Avoid:
+
+- Generic best-practice lists with no workflow.
+- Repeating common model knowledge.
+- Large always-loaded manuals.
+- Broad descriptions that trigger on unrelated work.
+- Skills that silently require credentials, network access, or destructive commands.

package/skills/build-tool/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: build-tool
+description: Use when creating, reviewing, or improving Threadroot tools, especially executable commands, local CLI wrappers, healthchecks, risk levels, confirmation behavior, inputs, and connection-backed capabilities.
+scope: project
+tags:
+  - tools
+  - security
+  - agent-harness
+---
+
+# Build Tool
+
+Create tools as small, explicit, testable wrappers around commands the project already trusts.
+
+## Workflow
+
+1. Identify the exact command the user or repo already uses.
+2. Prefer a read-only or validation command first.
+3. Classify risk:
+   - `low`: reads state, validates, tests, formats, or prints information.
+   - `medium`: writes local files or changes non-production state.
+   - `high`: deploys, deletes, migrates, publishes, spends money, changes cloud resources, or touches secrets.
+4. Require `confirm: true` for high-risk tools.
+5. If the command depends on a cloud/account CLI, reference a `.threadroot/connections/*.yaml` connection.
+6. Declare inputs instead of accepting freeform shell fragments.
+7. Add a finite `healthcheck` when possible. Do not use long-running dev servers as healthchecks.
+8. Validate with `threadroot tools check` and `threadroot doctor`.
+
+## Safety Rules
+
+- Never put secrets, tokens, passwords, or private keys in tool manifests.
+- Never hide destructive behavior behind a low-risk description.
+- Keep shell commands narrow; prefer existing package scripts, Make targets, just recipes, or official CLIs.
+- Use connection manifests for AWS, GitHub, Azure, Snowflake, and similar authenticated CLIs.
+- If unsure, mark the tool high risk and require confirmation.

package/skills/build-tool/evals/triggers.json

@@ -0,0 +1,13 @@
+{
+  "shouldTrigger": [
+    "Create a Threadroot tool for running tests",
+    "Wrap an AWS CLI command as a safe agent tool",
+    "Add a healthcheck to this harness tool",
+    "Review this tool manifest for risk and confirmation behavior"
+  ],
+  "shouldNotTrigger": [
+    "Design the data model for this app",
+    "Write release notes for this change",
+    "Debug this failing unit test"
+  ]
+}

package/skills/catalog.json

@@ -0,0 +1,50 @@
+{
+  "version": 1,
+  "skills": [
+    {
+      "name": "system-design",
+      "description": "Architecture and tradeoff design for new or existing software systems.",
+      "path": "skills/system-design"
+    },
+    {
+      "name": "build-skill",
+      "description": "Create and improve high-quality Threadroot and Agent Skills.",
+      "path": "skills/build-skill"
+    },
+    {
+      "name": "build-tool",
+      "description": "Create and improve safe, testable Threadroot tools and connection-backed capabilities.",
+      "path": "skills/build-tool"
+    },
+    {
+      "name": "code-review",
+      "description": "Review code, pull requests, generated changes, and agent output.",
+      "path": "skills/code-review"
+    },
+    {
+      "name": "security-review",
+      "description": "Review trust boundaries, tool execution, supply-chain risk, and unsafe inputs.",
+      "path": "skills/security-review"
+    },
+    {
+      "name": "add-test",
+      "description": "Add or improve tests around changed behavior and regressions.",
+      "path": "skills/add-test"
+    },
+    {
+      "name": "debug-failure",
+      "description": "Debug failing tests, broken builds, runtime errors, and bad generated output.",
+      "path": "skills/debug-failure"
+    },
+    {
+      "name": "write-docs",
+      "description": "Write or update technical documentation and agent-facing instructions.",
+      "path": "skills/write-docs"
+    },
+    {
+      "name": "conventional-commits",
+      "description": "Write structured git commit messages and release summaries.",
+      "path": "skills/conventional-commits"
+    }
+  ]
+}

package/skills/code-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: code-review
+description: Use when reviewing code, pull requests, diffs, generated changes, or agent output for correctness, regressions, risk, maintainability, security, and missing tests.
+scope: project
+tags:
+  - review
+  - quality
+---
+
+# Code Review
+
+Review behavior before style.
+
+## Workflow
+
+1. Identify the claimed intent of the change.
+2. Inspect the behavioral path, data flow, edge cases, and failure handling.
+3. Check for security issues: input validation, auth boundaries, path traversal, command execution, secrets, unsafe defaults.
+4. Check tests: missing coverage, weak assertions, untested failures, snapshots that hide behavior.
+5. Report findings first, ordered by severity, with file/line references when available.
+
+## Output
+
+Lead with findings. If there are no material issues, say so and mention residual risk or test gaps.

package/skills/code-review/evals/triggers.json

@@ -0,0 +1,12 @@
+{
+  "shouldTrigger": [
+    "Review this diff for correctness and missing tests.",
+    "Can you check this PR for regressions and risky edge cases?",
+    "Look at these generated changes and tell me if anything should block merge."
+  ],
+  "shouldNotTrigger": [
+    "Design a new database schema from scratch.",
+    "Write docs for this CLI command.",
+    "Debug this failing test output."
+  ]
+}

package/skills/conventional-commits/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: conventional-commits
+description: Use when writing, reviewing, or suggesting git commit messages, release notes, changelog entries, or structured commit summaries.
+scope: project
+tags:
+  - git
+  - commits
+---
+
+# Conventional Commits
+
+Write commits as `type(scope): subject`.
+
+## Types
+
+- `feat`: user-visible feature.
+- `fix`: bug fix.
+- `docs`: documentation only.
+- `refactor`: behavior-preserving code change.
+- `test`: test-only change.
+- `chore`: maintenance.
+- `build` or `ci`: build system or CI.
+
+## Rules
+
+- Keep the subject imperative, specific, and under about 72 characters.
+- Do not add a trailing period.
+- Explain why in the body when the change is non-obvious.
+- Mark breaking changes with `!` or a `BREAKING CHANGE:` footer.

package/skills/conventional-commits/evals/triggers.json

@@ -0,0 +1,12 @@
+{
+  "shouldTrigger": [
+    "Write a commit message for these changes.",
+    "Suggest a Conventional Commit subject for this diff.",
+    "Turn this summary into a release-note style commit body."
+  ],
+  "shouldNotTrigger": [
+    "Review this code for correctness.",
+    "Add tests for this parser.",
+    "Design the database schema."
+  ]
+}

package/skills/debug-failure/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: debug-failure
+description: Use when debugging failing tests, broken builds, runtime errors, flaky behavior, bad generated output, or unexpected CLI/MCP behavior.
+scope: project
+tags:
+  - debugging
+---
+
+# Debug Failure
+
+Reproduce, isolate, fix the cause, then preserve the lesson.
+
+## Workflow
+
+1. Capture the exact command, output, environment, and recent change.
+2. Reproduce the failure with the smallest command.
+3. Read the full error before editing.
+4. Form one hypothesis at a time and test it.
+5. Add or update a regression test when the failure reveals a bug.
+6. After fixing, run the narrow test and relevant full gate.
+7. Record durable lessons in pitfalls memory when useful.

package/skills/debug-failure/evals/triggers.json

@@ -0,0 +1,12 @@
+{
+  "shouldTrigger": [
+    "This test is failing; help me reproduce and isolate the cause.",
+    "The build broke after my last change, debug it.",
+    "The CLI output is unexpected; figure out what changed."
+  ],
+  "shouldNotTrigger": [
+    "Design a new API contract.",
+    "Add a new skill for code review.",
+    "Write a changelog entry."
+  ]
+}

package/skills/security-review/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: security-review
+description: Use when evaluating code, tools, scripts, install flows, MCP surfaces, auth, filesystem access, command execution, secrets, supply-chain risk, or user-controlled input for security issues.
+scope: project
+tags:
+  - security
+  - review
+---
+
+# Security Review
+
+Focus on exploitable paths and trust boundaries.
+
+## Workflow
+
+1. Identify attacker-controlled inputs and privileged outputs.
+2. Trace filesystem, network, shell, database, credential, and MCP/tool execution paths.
+3. Look for path traversal, command injection, unsafe deserialization, auth bypass, secret exposure, SSRF, dependency risk, and confused-deputy behavior.
+4. Verify allow-lists, confirmation prompts, provenance, integrity checks, and least privilege.
+5. Recommend the smallest fix that closes the class of bug, plus a regression test.
+
+## Output
+
+Use severity labels. Distinguish confirmed vulnerabilities from hardening suggestions.

package/skills/security-review/evals/triggers.json

@@ -0,0 +1,12 @@
+{
+  "shouldTrigger": [
+    "Review this install flow for path traversal and command execution risks.",
+    "Check whether this MCP tool exposes unsafe file or shell access.",
+    "Audit this authentication middleware for bypasses and unsafe defaults."
+  ],
+  "shouldNotTrigger": [
+    "Write a release note for this change.",
+    "Suggest a commit message.",
+    "Explain what this component renders."
+  ]
+}

package/skills/system-design/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: system-design
+description: Use when designing, reviewing, or changing software architecture, APIs, data models, scaling strategy, reliability, observability, security, deployment, or technical tradeoffs for a new or existing system.
+scope: project
+tags:
+  - architecture
+  - system-design
+  - planning
+---
+
+# System Design
+
+Use this skill before major implementation when architecture decisions could be expensive to reverse.
+
+## Workflow
+
+1. Clarify the product goal, users, constraints, traffic, data sensitivity, integration points, and deployment target.
+2. Separate hard requirements, soft preferences, non-goals, and unknowns.
+3. Propose the simplest architecture that satisfies the known constraints before adding scale patterns.
+4. Define API boundaries, data ownership, background jobs, and external dependencies.
+5. Identify failure modes, abuse cases, operational risks, rollback strategy, and observability.
+6. Compare tradeoffs explicitly: reliability, security, performance, cost, operability, and delivery speed.
+7. Produce a concrete implementation plan and validation plan.
+
+## Output Shape
+
+Return concise sections: Goal, Requirements, Non-goals, Constraints, Proposed Architecture, Data Model, API Surface, Background Jobs, Failure Modes, Security, Observability, Cost/Scale Assumptions, Tradeoffs, Implementation Plan, Validation Plan.
+
+## Reference Loading
+
+- Read `references/architecture-checklist.md` for architecture review prompts.
+- Read `references/reliability-observability.md` when uptime, incidents, metrics, queues, or distributed behavior matter.
+- Read `references/api-data-design.md` when designing public APIs, schemas, migrations, or integration boundaries.

package/skills/system-design/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "shouldTrigger": [
+    "Design the architecture for a multi-tenant analytics dashboard with background imports and usage limits.",
+    "Before we build billing, help me decide the API boundaries, data model, failure modes, and rollout plan.",
+    "Review this proposed queue-based architecture for reliability, observability, and operational risks."
+  ],
+  "shouldNotTrigger": [
+    "Write a unit test for this pure date formatting helper.",
+    "Fix this typo in the README.",
+    "Create a conventional commit message for my current diff."
+  ],
+  "expectedReferences": [
+    "references/architecture-checklist.md",
+    "references/reliability-observability.md",
+    "references/api-data-design.md"
+  ]
+}

package/skills/system-design/references/api-data-design.md

@@ -0,0 +1,15 @@
+# API And Data Design
+
+Use this reference when defining interfaces, schemas, persistence, or migrations.
+
+## API Shape
+
+- Define request/response types, auth, validation, pagination, idempotency, and error format.
+- Keep external APIs stable and version only when compatibility requires it.
+- Prefer explicit domain names over transport/framework names.
+
+## Data Shape
+
+- Identify source-of-truth tables/entities and derived/cache data.
+- Name uniqueness constraints, indexes, retention, deletion, and privacy requirements.
+- Plan migrations as reversible or forward-fixable steps.