spec-lite

Portable, structured software-engineering workflows for Codex, Claude Code, GitHub Copilot, Pi, and any LLM.

spec-lite gives AI coding assistants the same focused agents, repeatable skills, and project context. The role definitions adapt to each harness, while plans, memory, feature specs, reviews, and documentation stay in the repository. Start work in Claude Code, continue it in Codex, review it in Copilot, or hand it to a teammate using Pi without rebuilding the context from scratch.

Why spec-lite

Coding harnesses represent agents and skills differently. Their conversation history is also isolated, which makes changing tools mid-feature surprisingly expensive. spec-lite separates the reusable workflow from the local project state:

Globally installed spec-lite agents and skills
        │
        ├── Codex
        ├── Claude Code
        ├── GitHub Copilot
        └── Pi
                │
                ▼
        The same project repository
                │
                ├── .spec-lite/memory.md
                ├── .spec-lite/plan*.md
                ├── .spec-lite/features/
                ├── .spec-lite/reviews/
                └── project documentation and code

The harness is the interface; the repository is the durable source of truth. Commit the .spec-lite/ directory so teammates and different assistants can resume from the same decisions, task state, and review history.

Highlights

• Cross-harness continuity — use the same project and feature state from Codex, Claude Code, Copilot, Pi, or exported Markdown prompts.
• Global reusable roles, local durable state — install agents and skills once, while each repository keeps its own memory, plans, features, reviews, and documentation.
• Native provider adapters — generates each harness's expected agent, command, prompt, skill, and root-instruction formats.
• Modular delivery workflow — use only the discovery, planning, implementation, testing, review, documentation, data, or DevOps role a task needs.
• Consolidated review — one deterministic review covers correctness, testing, security, performance, and dependency vulnerabilities using GitHub Advisories by default, with practical remediation guidance.
• Durable gates and checkpoints — pause on declared choices, answer locally or through GitHub, and resume in a live coding-agent session with explicit action ownership. Runtime feedback/logs remain local.
• Extensible lifecycle hooks — subscribe your own commands, webhooks, or skill hand-offs to versioned events; changeset capture is just the pair that ships enabled.
• First-class documentation — choose the documentation directory and depth, with optional updates during implementation and fixes.
• Shared memory — durable project conventions live in .spec-lite/memory.md and can be captured as the work evolves.
• Stable feature IDs — FEAT-### identifiers remain consistent across plans, feature specs, implementation, tests, and review.
• 14 stack baselines — TypeScript, Python, Java, .NET, Go, Rust, Kotlin, Swift, C/C++, PHP, Ruby, React, Vue, and Angular.
• Safe upgrades — update every configured provider, preselect newly shipped roles, migrate config and legacy flat feature specs (including FEAT-FP-### IDs), preserve Project Context edits, and clean obsolete generated outputs with confirmation.
• Portable export — combine selected roles and references into one self-contained Markdown prompt for chat tools, teammates, or unsupported harnesses.

Install

Requires Node.js 22 or newer (current LTS).

npm install -g @abranjith/spec-lite
spec-lite install --global --ai codex,claude-code,copilot,pi

cd your-project
spec-lite init

The first command installs the reusable roles for the harnesses you use; the second records this project's providers, profile, and documentation preferences in .spec-lite.json. Full walkthrough: Quickstart.

Use it

Run the full flow for a new application, or just the part a task needs:

Brainstorm → Plan → Feature × N → Implement → Review → Integration Tests → Document

| Situation | Suggested workflow | |---|---| | Clear idea for a new project | Plan → Feature → Implement → Review | | One focused enhancement | Feature Planner → Implement → Review → Document Update | | Existing defect or refactor | Fix → Review | | Architecture decision | Architect, then Plan or DevOps | | Existing plan needs a challenge | Plan Critic → revise or continue | | Well-scoped autonomous build | YOLO |

5 agents — Brainstormer, Planner, Feature Planner, Architect, YOLO.

18 skills — Feature, Implement, Review, Fix, Unit Tests, Integration Tests, Document (+ Design, Feature, Usage, README writers), Memorize, Plan Critic, Data Model, DevOps, Todo, Tool Helper, Hook Helper.

Personas, harness-by-harness selection, and example prompts for every role: Agents and skills.

Documentation

| Document | What it covers | |---|---| | Quickstart | Install, initialize, run a first workflow, hand off between harnesses | | Architecture | Global roles vs. local state, provider adapters, project layout, configuration | | CLI reference | Every command and option, including the hooks API | | Agents and skills | The full catalog, selection per harness, example prompts | | Hooks | Run your own automation at lifecycle events; built-in changeset capture | | Git workflow hooks | A worktree, branch, commits, and pull request per piece of work | | Gates and checkpoints | Checks that block the run, and questions that pause it for you | | Review | Deterministic scopes, findings, verdicts | | Documentation | Documentation settings, document set, and modes | | Memory and project state | Standing conventions and what to commit |

Development

git clone https://github.com/abranjith/spec-lite.git
cd spec-lite
git switch development
npm install
npm run build
npm run typecheck
npm test

| Command | Purpose | |---|---| | npm run dev | Rebuild on source changes. | | npm run build | Bundle the CLI and copy prompt/stack assets to dist/. | | npm run typecheck | Run strict TypeScript checking. | | npm run lint | Check JavaScript and TypeScript with ESLint; fail on warnings. | | npm run lint:fix | Fix automatically repairable lint issues. | | npm run format | Format JavaScript, TypeScript, and JSON with Prettier. | | npm run format:check | Check formatting without changing files. | | npm run precommit | Run linting and formatting on staged files. | | npm test | Run the Vitest regression suite. | | npm run generate:hooks-schema | Regenerate schema/hooks.schema.json from the source of truth. | | npm run generate:hook-docs | Regenerate the hook variable and event tables in the docs. |

Repository layout is described in Architecture.

npm install (or npm ci) installs the Husky Git hooks automatically. Before each commit, lint-staged runs ESLint fixes and Prettier on staged code, and Prettier on staged JSON. Remaining lint errors block the commit. Generated files, build output, and local project state are excluded from formatting. Markdown prompts are not included in the formatting commands. Git attributes keep code and hook line endings consistent on Windows and Unix.

Run npm run lint:fix and npm run format to clean up files manually. Pull requests also run lint and format:check alongside the existing build, typecheck, and tests.

Contributing

Issues and pull requests are welcome. Open pull requests against the development branch, not main.

Before submitting a change:

1. Keep source catalog mappings, provider handoffs, relative Markdown links, canonical shared blocks, and Project Context markers synchronized.
2. Add or update regression tests for CLI and provider behavior.
3. Run npm run lint, npm run format:check, npm run build, npm run typecheck, and npm test.
4. Set the pull request base branch to development.

License

MIT — see LICENSE.