repo-signal 1.0.0

AI-assisted repo analysis for turning rough prototypes into clear, documented, publishable GitHub projects.

repo-signal

What problem does this solve? You have a local repo — maybe a prototype, a side project, or a tool in progress. It works, but the README is thin, the docs are missing, the version is out of sync, and you don't know if it's actually ready to publish. repo-signal tells you exactly what's wrong and what to fix next.

Who is this for? Developers who build small tools and want structured signals for when something is actually ready. Works standalone or as a backend contract for AI agent workflows.

repo-signal turns local repository state into clear analysis reports, publish-readiness signals, and machine-readable JSON contracts for AI-assisted development workflows.

---

Install

From PyPI:

pipx install repo-signal

Current local development install:

git clone https://github.com/MCamner/repo-signal.git
cd repo-signal
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[ai]"

See PyPI publishing guide for the release workflow.

---

Try this in 60 seconds

# Get a high-level overview
repo-signal analyze

# Fast status report and next commit suggestion
repo-signal inspect

# Machine-readable status for integrations
repo-signal inspect --json

# Full readiness diagnosis
repo-signal doctor

# Check public-readiness signals
repo-signal publish-checklist .

---

Command Surface

Stable commands:

repo-signal
├── analyze            # Front-door orientation
├── inspect            # Fast status and next commit
├── inspect --json     # Machine-readable inspect.v1 contract
├── doctor             # Full readiness diagnosis
├── publish-checklist  # Public signal quality gate
├── report             # Unified report — inspect + publish-checklist in one
├── report --json      # Machine-readable report.v1 contract
├── suggest            # Safe patch suggestions — read-only, no mutations
├── suggest --json     # Machine-readable suggest.v1 contract
├── repoaware          # AI context export
└── demo               # Generate example reports

Stable JSON contracts: inspect.v1 · doctor.v1 · report.v1 · suggest.v1

See the Command Reference and Roadmap for full details.

---

Screenshots

---

Examples

• Report (text)
• Report (JSON — report.v1)
• Suggest (text)
• Suggest (JSON — suggest.v1)
• Inspect (text)
• Inspect (JSON — inspect.v1)
• Doctor (text)
• Doctor (JSON — doctor.v1)
• Analyze

Generate your own local demo reports:

repo-signal demo --generate

---

Use with AI agents

repo-signal is designed as a backend contract for AI agent workflows. All stable commands have JSON output that agent tools can consume safely:

# Check schema before parsing
repo-signal inspect --json . | python3 -c "
import json, sys
d = json.load(sys.stdin)
assert d['schema'] == 'inspect.v1'
print(d['recommended_next_commit'])
"

See Integrations for mqlaunch, mq-agent, mq-mcp, and mq-hal patterns.

---

Documentation

Live docs: mcamner.github.io/repo-signal

Contracts:

• Inspect Schema — inspect.v1 field reference
• Doctor Schema — doctor.v1 field reference
• Report Schema — report.v1 field reference
• Suggest Schema — suggest.v1 field reference, no-mutation guarantee

Usage:

• Command Reference — Detailed CLI usage and flags
• Integrations — How mqlaunch, mq-mcp, mq-hal, and Bridget consume JSON contracts
• RepoAware — High-signal AI context ranking and export
• Semantic Memory — Uploading symbol maps to vector stores

Publishing:

• Packaging — PyPI / pipx readiness plan and packaging smoke tests
• PyPI — Real PyPI publishing guide and Trusted Publisher values
• Generated Examples — How examples are generated and verified before release
• Roadmap — Release direction and stability checklist

---

v1.0.0 status

• 4 stable JSON contracts: inspect.v1, doctor.v1, report.v1, suggest.v1
• Full test suite passes — 155 passed, 2 skipped
• Schema checks in release.sh for all four stable contracts
• Contract docs: INSPECT_SCHEMA.md, DOCTOR_SCHEMA.md, REPORT_SCHEMA.md, SUGGEST_SCHEMA.md
• Generated examples: examples/report/, examples/suggest/, examples/inspect/, examples/doctor/
• CLI surface frozen for v1.x

See CHANGELOG.md for full release history.

• GitHub Actions green (Tests, Packaging, Generated examples, Publish checklist)
• .markdownlint.json configured

---

Author

Mattias Camner

Infrastructure / Platform Architect
Builder of command surfaces, endpoint readiness prototypes, and structured workflow systems.

---

License

MIT