{"id":47635755,"url":"https://github.com/subkoks/agents-md","last_synced_at":"2026-04-19T23:13:22.746Z","repository":{"id":345589071,"uuid":"1185780118","full_name":"subkoks/agents-md","owner":"subkoks","description":"Canonical source for a cross-editor agent operating system built on the GOTCHA framework. Includes crypto/web3/Solana skill pack, runtime automation, and production-grade scaffolding.","archived":false,"fork":false,"pushed_at":"2026-03-22T23:59:41.000Z","size":112,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-02T08:09:26.475Z","etag":null,"topics":["agent-framework","automation","blockchain","crypto","gotcha","pump","skills","sniper-bot","solana","trading","web3"],"latest_commit_sha":null,"homepage":"https://github.com/subkoks/agents-md","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/subkoks.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-18T23:54:49.000Z","updated_at":"2026-03-22T23:59:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/subkoks/agents-md","commit_stats":null,"previous_names":["subkoks/agents-md"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/subkoks/agents-md","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subkoks%2Fagents-md","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subkoks%2Fagents-md/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subkoks%2Fagents-md/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subkoks%2Fagents-md/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/subkoks","download_url":"https://codeload.github.com/subkoks/agents-md/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/subkoks%2Fagents-md/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32025859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","automation","blockchain","crypto","gotcha","pump","skills","sniper-bot","solana","trading","web3"],"created_at":"2026-04-02T00:04:19.652Z","updated_at":"2026-04-19T23:13:22.739Z","avatar_url":"https://github.com/subkoks.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# agents-md\n\nCanonical source for a cross-editor agent operating system built on the GOTCHA framework.\n\n## What This Repository Is\n\n`agents-md` is the project-local control plane for high-quality agent behavior:\n\n- canonical rule body (`src/gotcha.md`)\n- pattern and ecosystem database (`docs/`)\n- operational scripts (`scripts/`)\n- reusable templates (`templates/`)\n- roadmap and experiments (`ROADMAP.md`, `ideas/`)\n\nThis repo is intentionally editor-agnostic and aligns behavior across Windsurf, Claude, and Codex.\n\n## Architecture (GOTCHA)\n\n- **G**oals: explicit work routing and workflow selection\n- **O**rchestration: the agent decision layer\n- **T**ools: deterministic scripts and MCP operations\n- **C**ontext: static reference material\n- **H**ard prompts: focused task templates\n- **A**rgs: runtime behavior settings\n\nCore principle: push reliability into deterministic tooling, keep reasoning flexibility in orchestration.\n\n## Repository Layout\n\n```text\nagents-md/\n├── src/\n│   └── gotcha.md\n├── docs/\n│   ├── agent-database.md\n│   ├── agent-patterns.md\n│   ├── agent-upgrade-roadmap.md\n│   ├── hook-reference.md\n│   └── ...\n├── scripts/\n│   ├── build-rule-artifacts.sh\n│   ├── validate-rules.sh\n│   ├── check-links.sh\n│   ├── check-local-drift.sh\n│   ├── sniper-config-template.yaml\n│   ├── pumpfun-bot-checklist.sh\n│   └── sniper-journal-summary.sh\n├── skills/\n│   ├── README.md\n│   ├── solana-anchor-program-dev.md\n│   ├── solana-client-kit-and-wallets.md\n│   ├── solana-security-and-audit.md\n│   ├── evm-smart-contract-dev.md\n│   ├── defi-protocol-engineering.md\n│   ├── token-launch-and-memecoin-ops.md\n│   ├── onchain-trading-and-flow-analysis.md\n│   ├── memecoin-trading-risk-playbook.md\n│   ├── pumpfun-launch-and-trading-automation.md\n│   ├── solana-terminal-workflows-axiom-padre-nova.md\n│   └── solana-sniper-bot-scripts-and-ops.md\n├── templates/\n├── ideas/\n├── ROADMAP.md\n└── CHANGELOG.md\n```\n\n## Quick Start\n\n```bash\n# Validate rules and check compatibility\n./scripts/validate-comprehensive.sh\n\n# Run deterministic governance pipeline (strict -\u003e drift -\u003e build -\u003e strict drift)\n./scripts/run-governance.sh\n\n# Build local artifacts\n./scripts/build-rule-artifacts.sh\n\n# Build specific artifacts\n./scripts/build-rule-artifacts.sh windsurf claude\n\n# Check artifact status\n./scripts/build-rule-artifacts.sh --list\n```\n\n## Daily Operations\n\n```bash\n# Strict repo checks (recommended before commit)\nmake check\n\n# Full deterministic governance pipeline\nmake governance-run\n\n# Health report with timestamped logs\nmake health\n```\n\n## Troubleshooting\n\n- If artifacts drift, run `make governance-run` and re-check with `make drift-check-strict`.\n- If shell scripts fail in CI, run `bash -n scripts/*.sh` locally before committing.\n- If optional tools are missing, run `./scripts/health-check.sh` to see degraded-safe diagnostics.\n\n## Canonical Governance Contract\n\n- Canonical rule body: `src/gotcha.md` only.\n- Local artifacts are generated at `dist/rules/*.md`.\n- Do not edit generated artifacts directly; rebuild via `scripts/build-rule-artifacts.sh` or `scripts/run-governance.sh`.\n- Pre-commit guard rejects artifact-only edits without canonical update.\n- This repository does not manage personal editor, AI agent, or global git-hook files under `~`.\n\n## Quality Gates\n\n- Comprehensive validation: `scripts/validate-comprehensive.sh`\n  - Rule structure and integrity\n  - Local artifact compatibility\n  - Version drift detection\n  - Artifact accessibility\n  - Content integrity\n- Individual checks: `scripts/validate-rules.sh`, `scripts/check-links.sh`, `scripts/check-local-drift.sh`\n- Automated hooks: Pre-commit and CI/CD validation\n- Runtime/system health: `scripts/health-check.sh` (writes timestamped logs to `logs/health/`)\n- Skill drift monitoring: `scripts/check-skill-registry-drift.sh` against `skills/registry.tsv`\n\nAll scripts degrade safely when optional dependencies are missing.\n\n## Local Artifacts\n\n- `dist/rules/windsurf.md`\n- `dist/rules/claude.md`\n- `dist/rules/codex.md`\n\n## GitHub-Ready Workflow\n\n- Run local validation:\n\n```bash\n./scripts/validate-comprehensive.sh\n```\n\n- Create branch and commit logically grouped changes (pre-commit hooks run automatically).\n- Open PR using `.github/pull_request_template.md`.\n- CI (`.github/workflows/ci.yml`) runs four jobs in sequence:\n  - `lint` — `shellcheck`, `actionlint`, `markdownlint-cli2`\n  - `validate` — rule structure, comprehensive validation, link and drift checks\n  - `build` — rebuild local artifacts and verify strict drift\n  - `security-scan` — `trufflehog` on PR diffs for verified/unknown secrets\n- Ensure all CI checks pass.\n- Merge and update `CHANGELOG.md`.\n\n## Sniper Bot Quick Start\n\n```bash\nchmod +x scripts/pumpfun-bot-checklist.sh scripts/sniper-journal-summary.sh\ncp scripts/sniper-config-template.yaml sniper-config.yaml\n./scripts/pumpfun-bot-checklist.sh ./sniper-config.yaml\n# After trading:\n./scripts/sniper-journal-summary.sh ./logs/sniper-events.jsonl\n```\n\n## Core Documents\n\n- `docs/agent-database.md`: curated inventory and source map\n- `docs/agent-patterns.md`: normalized reusable patterns\n- `docs/hook-reference.md`: hook behavior and portability notes\n- `docs/hook-routing.md`: global/project/repo hook ownership and routing\n- `docs/editor-alignment-strategy.md`: artifact packaging strategy by editor\n- `docs/hook-portability-spec.md`: generic hook contract model\n- `docs/goals-manifest.md`: task-to-asset routing matrix\n- `docs/security-scan-spec.md`: config security scanner taxonomy and output schema\n- `docs/orchestration-dag-spec.md`: dependency-graph orchestration and quality-gate contract\n- `docs/sniper-runbook.md`: sniper bot preflight, runtime monitoring, and incident playbooks\n- `skills/README.md`: crypto/web3/Solana skill index and trigger map\n\n## Versioning\n\nSee `CHANGELOG.md` for release history and unreleased changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubkoks%2Fagents-md","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsubkoks%2Fagents-md","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsubkoks%2Fagents-md/lists"}