Add missing OSS hygiene files

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,47 @@
+name: Bug report
+description: Report a defect in @code-first-agents/tool
+title: "[Bug]: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a bug report. Please fill in the
+        sections below so the issue can be reproduced and fixed.
+  - type: input
+    id: version
+    attributes:
+      label: Package version
+      description: Which version of `@code-first-agents/tool` are you using?
+      placeholder: "0.1.3"
+    validations:
+      required: true
+  - type: textarea
+    id: repro
+    attributes:
+      label: Steps to reproduce
+      description: A minimal, self-contained way to trigger the bug.
+      placeholder: |
+        1. Define a tool with ...
+        2. Run `bun run tool.ts ...`
+        3. See error
+    validations:
+      required: true
+  - type: textarea
+    id: expected-actual
+    attributes:
+      label: Expected vs. actual behavior
+      description: What did you expect to happen, and what actually happened?
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Runtime, OS, and Zod version.
+      placeholder: |
+        - Bun: 1.2.x
+        - OS: macOS 14
+        - Zod: 4.0.x
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Code-First Agents spec & docs
+    url: https://code-first-agents.com
+    about: Read the pattern spec and documentation before opening an issue.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,40 @@
+name: Feature request
+description: Suggest an enhancement for @code-first-agents/tool
+title: "[Feature]: "
+labels: [enhancement]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for suggesting an improvement. Please describe the problem and your
+        proposal so the change can be evaluated against the spec.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem or limitation are you running into?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Describe the change or feature you'd like to see.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches or workarounds you've thought about.
+    validations:
+      required: false
+  - type: textarea
+    id: spec-alignment
+    attributes:
+      label: Spec alignment
+      description: >-
+        How does this fit the Code-First Agents pattern
+        (https://code-first-agents.com)? Note any tension with the tool contract.
+    validations:
+      required: false

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,15 @@
+## Summary
+
+<!-- What does this PR change, and why? -->
+
+Closes #<!-- issue number, e.g. 22 -->
+
+## Checklist
+
+- [ ] Linked to an issue (`Closes #NN` above)
+- [ ] PR title follows [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `docs:`, …)
+- [ ] `bun test` passes
+- [ ] `bunx biome check .` passes
+- [ ] `bunx tsc --noEmit` passes
+- [ ] `bun run build` succeeds
+- [ ] Scope is focused — unrelated changes split into separate PRs

.github/dependabot.yml

@@ -0,0 +1,39 @@
+version: 2
+updates:
+  - package-ecosystem: npm
+    directory: "/"
+    schedule:
+      interval: weekly
+    target-branch: main
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore
+    labels:
+      - chore
+    groups:
+      npm-dependencies:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+          - major
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    target-branch: main
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: chore
+    labels:
+      - chore
+    groups:
+      github-actions:
+        patterns:
+          - "*"
+        update-types:
+          - minor
+          - patch
+          - major

.github/workflows/ci.yml

@@ -10,6 +10,11 @@ jobs:
   ci:
     name: Check & Test
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    concurrency:
+      group: ci-${{ github.ref }}
+      cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
     steps:
       - name: Checkout

CODE_OF_CONDUCT.md

@@ -0,0 +1,84 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. Examples of representing our community include using an official e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at beogip@gmail.com. All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq][FAQ]. Translations are available at [https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
+

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing
+
+Thanks for your interest in `@code-first-agents/tool`! This project implements the
+[Code-First Agents](https://code-first-agents.com/patterns/deterministic-tools.html)
+tool contract. Contributions are welcome — please read this guide first.
+
+> This project is maintained in spare time. Reviews and responses are best-effort,
+> so thank you for your patience.
+
+## Issue-first workflow
+
+Please **open an issue before sending a pull request**. This keeps the work
+lightweight and avoids duplicated or unwanted effort:
+
+1. Open an issue describing the bug or feature (use the issue forms).
+2. Wait for a quick confirmation that the change is wanted and the approach is sound.
+3. Fork, branch, and open a PR that links back to the issue.
+
+Small, obvious fixes (typos, broken links) can skip straight to a PR.
+
+## Development setup
+
+**Prerequisites:** [Bun](https://bun.sh) >= 1.0
+
+```bash
+git clone https://github.com/beogip/code-first-agents-tool.git
+cd code-first-agents-tool
+bun install
+```
+
+`bun install` runs the `prepare` script, which installs the
+[Lefthook](https://github.com/evilmartians/lefthook) git hooks (pre-commit Biome
+checks and commit-message validation).
+
+### Commands
+
+| Command          | Description                       |
+| ---------------- | --------------------------------- |
+| `bun install`    | Install deps + install git hooks  |
+| `bun run dev`    | Re-run `src/index.ts` on change (watch mode) |
+| `bun run build`  | Compile to `dist/` (bun + tsc)    |
+| `bun test`       | Run tests                         |
+| `bun run lint`   | Lint (Biome)                      |
+| `bun run format` | Format (Biome, auto-fix)          |
+| `bun run check`  | Lint + format (Biome, auto-fix)   |
+
+Before opening a PR, make sure the pipeline is green:
+
+```bash
+bun test
+bunx biome check .
+bunx tsc --noEmit
+bun run build
+```
+
+## Commit messages
+
+This repository enforces [Conventional Commits](https://www.conventionalcommits.org/)
+via the `commit-msg` git hook. Each commit message must start with one of these types:
+
+`feat` | `fix` | `docs` | `style` | `refactor` | `perf` | `test` | `build` | `ci` | `chore` | `revert`
+
+Examples:
+
+```
+feat: add user authentication
+fix(auth): handle token expiry
+chore!: drop support for Node 16
+```
+
+A `!` (or a `BREAKING CHANGE:` footer) marks a breaking change. Releases are
+automated via semantic-release, so commit types directly drive version bumps:
+`feat` → minor, `fix` → patch, breaking → major.
+
+## License
+
+This project is licensed under the [MIT License](LICENSE). By contributing, you agree
+that your contributions are licensed under the same terms (inbound = outbound).

README.md

@@ -7,6 +7,9 @@ TypeScript implementation of the [Code-First Agents](https://code-first-agents.c
 
 **Key idea:** deterministic work lives in code (Tools), the LLM orchestrates judgment (Skills). This library is the Tool side.
 
+> ℹ️ This project is maintained in spare time. Issues and pull requests are very
+> welcome — please bear with best-effort response times.
+
 ## Installation
 
 ```bash
@@ -173,6 +176,28 @@ bun run examples/changeset.ts size --files 12 --additions 340 --deletions 50
 
 `examples/changeset.ts` is one tool that demonstrates all three output levels (L1 data, L2 classification, L3 instructions). See [`examples/README.md`](examples/README.md) for the full walkthrough.
 
+## API Reference
+
+All exports come from the package root (`@code-first-agents/tool`). See the
+[spec](https://code-first-agents.com/patterns/deterministic-tools.html) for the
+contract these implement.
+
+| Export                       | Kind     | Purpose                                                                                  |
+| ---------------------------- | -------- | ---------------------------------------------------------------------------------------- |
+| `Tool`                       | class    | The orchestrator. Construct with `{ name, description }`, register subcommands, dispatch. |
+| `tool.subcommand(config)`    | method   | Register a subcommand with Zod `input`/`output` schemas and a `handler`.                  |
+| `tool.run(argv)`             | method   | Parse CLI args, dispatch, print the JSON envelope, and `process.exit(0)`.                 |
+| `tool.invoke(name, args)`    | method   | Call a subcommand in-process; returns the envelope object (useful in tests).             |
+| `l1Output(shape)`            | function | Build an **L1 (data)** output schema — raw signals for the LLM to interpret.              |
+| `l2Output(classification, fields?)` | function | Build an **L2 (classification)** output schema — a discrete category to branch on. `classification` is any Zod type (commonly `z.enum(...)`). |
+| `l3Output(fields?)`          | function | Build an **L3 (instructions)** output schema — a verbatim procedure for the LLM. Fields are optional.     |
+| `ToolError`                  | class    | Throw inside a handler for domain-specific errors: `new ToolError(code, message, detail?)`. Optional `detail` (string or object) is included in the error envelope's `detail` field. |
+| `schema` (builtin)           | command  | Auto-registered. Emits JSON Schema for every subcommand. Not user-overridable.           |
+| `help` (builtin)             | command  | Auto-registered. Emits a human-readable subcommand listing. Not user-overridable.        |
+
+Every successful result is the envelope `{ ok: true, message, ... }`; every error is
+`{ ok: false, error, ... }` with exit code `0`.
+
 ## Development
 
 **Prerequisites:** [Bun](https://bun.sh) >= 1.0
@@ -185,7 +210,7 @@ bun install
 
 | Command          | Description                     |
 | ---------------- | ------------------------------- |
-| `bun run dev`    | Run with file watcher           |
+| `bun run dev`    | Re-run `src/index.ts` on change (watch) |
 | `bun run build`  | Compile to `dist/` (bun + tsc)  |
 | `bun test`       | Run tests                       |
 | `bun run check`  | Lint + format (Biome, auto-fix) |