ISA — Issues-as-Code

Keep the why of every change inside the repository, and trace it through Git commit trailers.

Install

npm install -g @d0ublecl1ck/isa-cli

Daily loop

isa new <title>        # 1. create the issue BEFORE touching files
isa start <id>         # 2. validate intent, flip to in-progress
# ... code, committing early and often, each commit carries `Issue: <id>` ...
isa check              # 3. validate all issue documents (CI-friendly)
isa close <id>         # 4. verify evidence and trailers, archive to docs/issues/closed/

Why

• Traceable from intent to commit — issue documents are plain Markdown with YAML front matter; the trailer chain links every line back to the issue that motivated it.
• Process that can't be skipped silently — start validates intent, close validates trailers across the commit range, isa check keeps every document valid in CI.
• Offline-first, local-first — every command works against the repository; mirroring to GitHub Issues is explicit via isa sync.
• Agent-ready — ships a skill that teaches AI coding agents the same discipline.

Requires Node.js 20 or higher. isa init creates docs/issues/ and appends a mandatory Issues-as-Code constraint to AGENTS.md.