Skip to content

Commit ef2441d

Browse files
xlogixxlogix
committed
docs(repo): add README, governance, and contribution guides
1 parent 45efade commit ef2441d

13 files changed

Lines changed: 780 additions & 0 deletions

File tree

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
name: Bug report
2+
description: Report something that is broken
3+
title: "[bug] "
4+
labels:
5+
- bug
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
Thanks for reporting this. Please include enough detail to reproduce.
11+
- type: input
12+
id: summary
13+
attributes:
14+
label: Summary
15+
description: What is broken?
16+
placeholder: Short bug summary
17+
validations:
18+
required: true
19+
- type: textarea
20+
id: reproduce
21+
attributes:
22+
label: Steps to reproduce
23+
description: Exact commands and expected vs actual behavior
24+
placeholder: |
25+
1. Run ...
26+
2. Run ...
27+
3. See error ...
28+
validations:
29+
required: true
30+
- type: dropdown
31+
id: os
32+
attributes:
33+
label: Operating system
34+
options:
35+
- macOS
36+
- Linux
37+
- Windows
38+
- Other
39+
validations:
40+
required: true
41+
- type: input
42+
id: package_manager
43+
attributes:
44+
label: Package manager
45+
description: brew, apt, dnf, pacman, zypper, apk, winget, choco, scoop
46+
placeholder: brew
47+
validations:
48+
required: true
49+
- type: textarea
50+
id: logs
51+
attributes:
52+
label: Logs/output
53+
description: Paste error output
54+
render: shell
55+

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
blank_issues_enabled: true
2+
contact_links:
3+
- name: Questions and discussions
4+
url: https://github.com/xlogix/agent-toolkit/discussions
5+
about: Ask usage questions and discuss ideas.
6+

‎.github/ISSUE_TEMPLATE/feature_request.yml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Feature request
2+
description: Suggest a new feature or improvement
3+
title: "[feature] "
4+
labels:
5+
- enhancement
6+
body:
7+
- type: markdown
8+
attributes:
9+
value: |
10+
Thanks for the idea. Please share the user impact and proposed behavior.
11+
- type: input
12+
id: problem
13+
attributes:
14+
label: Problem
15+
description: What pain point does this solve?
16+
placeholder: It is hard to...
17+
validations:
18+
required: true
19+
- type: textarea
20+
id: proposal
21+
attributes:
22+
label: Proposed solution
23+
description: What should happen?
24+
placeholder: Add a new command/flag that...
25+
validations:
26+
required: true
27+
- type: textarea
28+
id: alternatives
29+
attributes:
30+
label: Alternatives considered
31+
description: Any current workarounds or alternatives
32+
- type: dropdown
33+
id: surface
34+
attributes:
35+
label: Area
36+
options:
37+
- CLI
38+
- Installer
39+
- Docs
40+
- Packaging
41+
- Benchmarks
42+
- CI
43+
- Other
44+
validations:
45+
required: true
46+

‎.github/pull_request_template.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
## Summary
2+
3+
Describe what changed and why.
4+
5+
## Changes
6+
7+
-
8+
9+
## Validation
10+
11+
- [ ] `bash -n install.sh agent-tools.sh scripts/install-agent-tools.sh scripts/release-prep.sh`
12+
- [ ] `shellcheck install.sh agent-tools.sh scripts/install-agent-tools.sh scripts/release-prep.sh`
13+
- [ ] Relevant dry-run path tested (for example `./agent-tools.sh install --dry-run`)
14+
- [ ] Docs updated if behavior changed
15+
16+
## Notes
17+
18+
Anything maintainers should know before review.
19+

‎.github/workflows/smoke.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Smoke
2+
3+
on:
4+
push:
5+
pull_request:
6+
7+
jobs:
8+
shell-installer:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@v4
12+
- name: Bash syntax check
13+
run: bash -n install.sh agent-tools.sh scripts/install-agent-tools.sh scripts/release-prep.sh
14+
- name: Dry run (apt)
15+
run: bash install.sh --package-manager apt --dry-run --extras
16+
- name: CLI init dry run
17+
run: bash agent-tools.sh init --repo . --dry-run
18+
19+
powershell-installer:
20+
runs-on: windows-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
- name: Parse check
24+
run: |
25+
pwsh -NoProfile -Command "[void][System.Management.Automation.Language.Parser]::ParseFile('install.ps1',[ref]$null,[ref]$null)"
26+
- name: Dry run (winget)
27+
shell: pwsh
28+
run: ./install.ps1 -PackageManager winget -DryRun -Extras

‎.vscode/settings.json‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"cSpell.words": ["Abhishek", "Uniyal", "toolbelt"]
3+
}

‎AGENTS.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# AGENTS.md
2+
3+
This file helps both human contributors and coding agents collaborate safely in this repo.
4+
5+
## Mission
6+
7+
`agent-toolkit` provides a cross-platform CLI toolkit that makes coding-agent workflows faster:
8+
9+
- install
10+
- update
11+
- reinstall
12+
- diagnose
13+
- initialize repo-safe `.gitignore` entries
14+
15+
## Start Here
16+
17+
1. Read [README.md](./README.md).
18+
2. Run the CLI help:
19+
- `./agent-tools.sh --help`
20+
3. Run checks before opening a PR:
21+
- `bash -n install.sh agent-tools.sh scripts/install-agent-tools.sh scripts/release-prep.sh`
22+
- `shellcheck install.sh agent-tools.sh scripts/install-agent-tools.sh scripts/release-prep.sh`
23+
- `./agent-tools.sh install --package-manager brew --dry-run --no-update` (or your local manager)
24+
25+
## Contributor Rules
26+
27+
1. Keep scripts cross-platform and shell-safe.
28+
2. Prefer additive changes over breaking existing commands.
29+
3. Keep package mappings explicit per package manager.
30+
4. If behavior changes, update docs in the same PR.
31+
5. Do not commit secrets, tokens, or machine-local paths.
32+
33+
## Agent-Specific Guidance
34+
35+
When changing installer logic:
36+
37+
1. Validate `install`, `update`, `reinstall`, `add`, `doctor`, and `init` paths.
38+
2. Preserve idempotency where expected (especially `init` for `.gitignore`).
39+
3. Keep dry-run support accurate and predictable.
40+
4. Prefer clear failure summaries instead of hard-failing early.
41+
42+
## Definition Of Done
43+
44+
A contribution is ready when:
45+
46+
1. Scripts pass syntax and lint checks.
47+
2. Dry-run works for the modified path.
48+
3. README/docs are updated.
49+
4. PR explains what changed and why.
50+

‎CITATION.cff‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
cff-version: 1.2.0
2+
title: Agent Toolkit
3+
message: "If you use this project, please cite it using this metadata."
4+
type: software
5+
authors:
6+
- family-names: Uniyal
7+
given-names: Abhishek
8+
repository-code: "https://github.com/xlogix/agent-toolkit"
9+
url: "https://github.com/xlogix/agent-toolkit"
10+
license: MIT
11+
keywords:
12+
- llm
13+
- agents
14+
- developer-tools
15+
- cli
16+
- productivity

‎CODE_OF_CONDUCT.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
# Code of Conduct
2+
3+
## Our Standard
4+
5+
We are committed to a welcoming, respectful, and harassment-free community.
6+
7+
Examples of expected behavior:
8+
9+
- be respectful and constructive
10+
- assume good intent
11+
- focus on ideas and outcomes, not people
12+
- help newcomers and first-time contributors
13+
14+
Examples of unacceptable behavior:
15+
16+
- harassment, hate speech, or personal attacks
17+
- doxxing or sharing private information
18+
- intentionally disruptive or abusive conduct
19+
20+
## Scope
21+
22+
This Code of Conduct applies to project spaces and public interactions related to this repository.
23+
24+
## Reporting
25+
26+
If you experience or witness unacceptable behavior, open a private security report or contact maintainers through GitHub.
27+
28+
Maintainers will review and respond appropriately.
29+

‎CONTRIBUTING.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Contributing
2+
3+
Thanks for helping improve `agent-toolkit`.
4+
5+
## Ways To Contribute
6+
7+
- report bugs
8+
- propose features
9+
- improve package-manager support
10+
- improve docs and benchmarks
11+
- improve reliability and DX of CLI flows
12+
13+
## Local Setup
14+
15+
```bash
16+
git clone git@github.com:xlogix/agent-toolkit.git
17+
cd agent-toolkit
18+
chmod +x agent-tools.sh install.sh scripts/install-agent-tools.sh scripts/release-prep.sh
19+
```
20+
21+
## Quick Validation
22+
23+
```bash
24+
bash -n install.sh agent-tools.sh scripts/install-agent-tools.sh scripts/release-prep.sh
25+
shellcheck install.sh agent-tools.sh scripts/install-agent-tools.sh scripts/release-prep.sh
26+
./agent-tools.sh install --package-manager brew --dry-run --no-update
27+
./agent-tools.sh init --repo . --dry-run
28+
```
29+
30+
Use your local package manager if not on Homebrew.
31+
32+
## Pull Request Process
33+
34+
1. Create a branch from `main`.
35+
2. Keep PR scope focused.
36+
3. Include a short "what changed" and "why" summary.
37+
4. Update README/docs if behavior changed.
38+
5. Ensure checks pass.
39+
40+
## Commit Style
41+
42+
Use clear, imperative commit messages:
43+
44+
- `feat: add zypper mapping for yq`
45+
- `fix: keep init gitignore idempotent`
46+
- `docs: add benchmark reproduction section`
47+
48+
## Need Help?
49+
50+
Open a feature request or bug report from the issue templates.

0 commit comments

Comments
 (0)