{"id":51231172,"url":"https://github.com/bonnguyenitc/specship","last_synced_at":"2026-06-28T16:30:50.205Z","repository":{"id":364099776,"uuid":"1266377274","full_name":"bonnguyenitc/specship","owner":"bonnguyenitc","description":"A staged spec → plan → coding → review workflow for shipping AI-assisted code. Works with Claude Code, Codex, Cursor \u0026 Antigravity.","archived":false,"fork":false,"pushed_at":"2026-06-28T14:35:12.000Z","size":4543,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-28T16:15:11.389Z","etag":null,"topics":["agent","agent-skills","agent-workflow","ai-agents","claude-code","claudecode","cli","codex","coding","cursor","developer-tools","gemini","llm","spec-driven-development","workflow"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bonnguyenitc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"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-06-11T15:02:17.000Z","updated_at":"2026-06-28T14:35:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bonnguyenitc/specship","commit_stats":null,"previous_names":["bonnguyenitc/specship"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bonnguyenitc/specship","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnguyenitc%2Fspecship","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnguyenitc%2Fspecship/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnguyenitc%2Fspecship/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnguyenitc%2Fspecship/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bonnguyenitc","download_url":"https://codeload.github.com/bonnguyenitc/specship/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bonnguyenitc%2Fspecship/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34896652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-28T02:00:05.809Z","response_time":54,"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","agent-skills","agent-workflow","ai-agents","claude-code","claudecode","cli","codex","coding","cursor","developer-tools","gemini","llm","spec-driven-development","workflow"],"created_at":"2026-06-28T16:30:45.968Z","updated_at":"2026-06-28T16:30:50.195Z","avatar_url":"https://github.com/bonnguyenitc.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/logo-specship-full-bg.png\" alt=\"specship logo\" width=\"132\" style=\"border-radius: 24px;\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003especship\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  A staged \u003cstrong\u003espec → plan → coding → review\u003c/strong\u003e workflow for shipping AI-assisted code with durable handoffs.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/specship\"\u003e\u003cimg alt=\"npm version\" src=\"https://img.shields.io/npm/v/specship?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/specship\"\u003e\u003cimg alt=\"npm downloads\" src=\"https://img.shields.io/npm/dm/specship?style=flat-square\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"node version\" src=\"https://img.shields.io/badge/node-%3E%3D16-222?style=flat-square\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"license\" src=\"https://img.shields.io/badge/license-MIT-222?style=flat-square\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#quick-start\"\u003eQuick Start\u003c/a\u003e ·\n  \u003ca href=\"#workflow\"\u003eWorkflow\u003c/a\u003e ·\n  \u003ca href=\"#commands\"\u003eCommands\u003c/a\u003e ·\n  \u003ca href=\"#contributing\"\u003eContributing\u003c/a\u003e ·\n  \u003ca href=\"https://github.com/bonnguyenitc/specship/releases\"\u003eChangelog\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/specship-banner.png\" alt=\"specship — spec → plan → coding → review, then ship\" width=\"100%\" style=\"border-radius: 16px;\"\u003e\n\u003c/p\u003e\n\n## Why specship\n\nspecship installs a repeatable agent workflow into any project. One command drops\nin the skill playbooks and writes the right config file at each AI coding\nagent's native location.\n\n| What you get | Why it matters |\n| --- | --- |\n| **Staged work** | Requirements, plans, code, and review each get their own explicit checkpoint. |\n| **Disk-backed state** | Any agent or human can resume from `tasks/TASK-\u003cID\u003e/` without relying on chat history. |\n| **Native agent setup** | Claude Code, Codex, Cursor, and Antigravity receive their files in the paths they already expect. |\n| **Reviewable artifacts** | Specs, plans, bug logs, and review notes stay in the repo as durable project context. |\n\n## Quick Start\n\nRequires [Node.js](https://nodejs.org) \u003e= 16.\n\n```bash\nnpx specship init --claude        # Claude Code\nnpx specship init --codex         # Codex\nnpx specship init --cursor        # Cursor\nnpx specship init --all           # all of the above (+ Antigravity)\n```\n\nAfter installing:\n\n1. Map the codebase once with `/explore-source`.\n2. Start a task with `/spec \u003cticket or feature request\u003e`.\n3. Approve each checkpoint as the task flows through `plan → coding → review`.\n\nUse `ship` when you want the whole pipeline to run from one request:\n\n```bash\n/ship implement login\n```\n\nComing back later or setting work aside? `/resume-task` picks up where you left\noff, `/pause-task` shelves a task as `paused`, and `/archive-task` moves a\nfinished one into `tasks/archive/` — see [Task lifecycle](#task-lifecycle).\n\n## Workflow\n\n```text\nexplore-source ──▶ docs/onboarding/*        (one-time: learn the codebase)\n                        │  read by every stage\n                        ▼\nspec ──▶ plan ──▶ coding ──▶ review ──▶ done\n                   ▲           │\n                   └─ debug ◀──┘           (attaches whenever a bug appears)\n```\n\nEvery task lives in its own folder:\n\n```text\ntasks/\n├── LESSONS.md       # project-wide process lessons (L#), read by every stage\n├── archive/         # shelved tasks (archive-task) — skipped by active scans\n│   └── TASK-000/    # a whole task folder moved here intact\n└── TASK-001/\n    ├── task.md      # SHARED STATE — stage, status, pipeline log\n    ├── spec.md      # requirements (R#), acceptance criteria (AC#)\n    ├── plan.md      # ordered steps (S#), each tracing to R#/AC#\n    ├── review.md    # gate results, AC verification, commit/PR draft\n    └── debug.md     # chronological bug log (BUG#)\n```\n\nBecause state is on disk, not hidden in a chat session, any agent or human can\npick up a task exactly where the last one left off.\n\n### Task lifecycle\n\nA task has two independent axes:\n\n- **`stage`** — *where the work is* in the pipeline: `spec → plan → coding → review → done`.\n- **`status`** — *whether it's being worked on*: `active`, `blocked` (stuck on an\n  external dependency), `paused` (deliberately shelved), or `done`.\n\nThe `status` axis moves like this (the `stage` axis is untouched throughout):\n\n```text\n                         pause-task\n            ┌──────────────────────────────────▶ paused\n  spec ──▶ active ◀──────────────────────────────┘\n            │  ▲              resume-task\n            │  │\n   stage    │  │  dependency appears / clears\n   skills   ▼  │\n          blocked\n\n  review approved:   active ──▶ done\n\n  archive-task:   any status ─────────────▶  archived  (folder → tasks/archive/)\n   active │ blocked │ paused │ done             │\n                                                │  resume-task \u003cID\u003e\n                              active  ◀─────────┘  (move folder back + restore status)\n```\n\n- `active ↔ blocked` is set by the **stage skills** (a dependency appears /\n  clears) — not a lifecycle action.\n- `pause-task` / `resume-task` toggle `active ↔ paused`.\n- `archive-task` moves **any** status into `archive/`; `resume-task \u003cID\u003e` moves it\n  back and re-activates it.\n\nThree lifecycle skills move a task around the pipeline **without ever changing its\n`stage` or artifacts** — they touch only `status` and location, and every\ntransition leaves a dated Pipeline Log line:\n\n| Skill | Effect | Reverse |\n| --- | --- | --- |\n| `/resume-task [ID]` | Locate a task, reconstruct its state from disk, report where it stands, and resume the right stage. With no ID it picks the most recently updated **active** task (never an archived or `paused` one). | — (it's the entry point) |\n| `/pause-task [ID]` | Mark a task `status: paused` with a reason, leaving it in place. It won't be mistaken for active work or auto-picked. | `/resume-task \u003cID\u003e` flips it back to `active`. |\n| `/archive-task [ID]` | Move a finished or abandoned task's folder into `tasks/archive/`, history intact, so active scans stay clean. Nothing is deleted. | `/resume-task \u003cID\u003e` finds it in `archive/` and moves it back. |\n\nPipeline state is always preserved: pausing, archiving, and restoring never change\n`stage` or any artifact — resuming continues exactly where the work stopped. A task\nthat was both paused **and** archived is fully re-activated on resume (moved out of\n`archive/` *and* flipped back to `active`).\n\n## Stages\n\n| Stage | Output | Done when |\n| --- | --- | --- |\n| `explore-source` | `docs/onboarding/{source-structure, how-to-code, what-is-stack, how-to-deploy}.md` | The codebase map exists and can be read by every later stage. |\n| `spec` | `tasks/TASK-\u003cID\u003e/task.md` + `spec.md` | Requirements, acceptance criteria, boundaries, and open questions are `confirmed`. |\n| `plan` | `plan.md` | Ordered steps trace back to `R#`/`AC#` and each step has a verify check. |\n| `coding` | Code changes + checked-off `S#` items | Each planned step is implemented minimally and verified. |\n| `review` | `review.md` | The full gate passes, `AC#` items are verified, and a commit/PR draft is written. |\n| `debug` | `debug.md` | A defect is reproduced, fixed minimally, and verified with regression coverage when possible. |\n| `ship` | A complete task run | `spec → plan → coding → review` runs end to end, stopping only on blockers. |\n\n`explore-source` and `ship` are not stages either: `explore-source` is a one-time\ncodebase mapping that every stage reads, and `ship` is an orchestrator that runs\nthe four stages back to back.\n\n### Lifecycle skills\n\nThese manage a task's `status` and location around the pipeline — see\n[Task lifecycle](#task-lifecycle) for the full picture. They never change `stage`\nor artifacts.\n\n| Skill | Output | Done when |\n| --- | --- | --- |\n| `resume-task` | Re-entry into an existing task | The task is located (un-shelved first if paused/archived), its state reconstructed from disk and reported, and the correct stage skill resumed. |\n| `pause-task` | A task marked `paused` | The task is deliberately shelved with a reason; pipeline stage and artifacts are left intact for later resume. |\n| `archive-task` | A task moved to `tasks/archive/` | A finished or abandoned task is moved out of the active set, history preserved; `resume-task` can restore it. |\n\n### Checkpoints\n\nStages never auto-advance by default. At the end of each stage, the agent\nupdates shared state, summarizes, and asks before moving on:\n\n```text\nspec → \"plan it?\"\nplan → \"start coding?\"\ncoding → \"review it?\"\n```\n\nApproving moves the task into the next stage. Declining stops with everything\nsaved on disk. Invoking `ship` grants that approval up front for one task, then\nstops only on blocker questions, destructive actions, or review failures.\n\n## Commands\n\n| Command | What it does |\n| --- | --- |\n| `init \u003cagents\u003e` | Install the workflow for `--claude`, `--codex`, `--cursor`, `--antigravity`, or `--all`. |\n| `update` | Refresh skills and config for whatever agents are already installed in the project. |\n| `list` | Show which agents are installed here. |\n\nOptions:\n\n| Option | Meaning |\n| --- | --- |\n| `--dir \u003cpath\u003e` | Target project. Defaults to the current working directory. |\n| `--force` | Overwrite modified skill files. By default, local edits are kept. |\n| `-v`, `--version` | Print the CLI version. |\n| `-h`, `--help` | Print help. |\n\n```bash\nnpx specship update\nnpx specship list\n```\n\n## What `init` Installs\n\nFor each agent, `init` copies the skills to that agent's skills folder and\nwrites or merges its config pointer at the correct native path.\n\n| Agent | Skills | Config | Mode |\n| --- | --- | --- | --- |\n| `--claude` | `.claude/skills/` | `CLAUDE.md` | merge |\n| `--codex` | `.codex/skills/` | `AGENTS.md` | merge |\n| `--cursor` | `.cursor/skills/` | `.cursor/rules/specship.mdc` | write |\n| `--antigravity` | `.agent/skills/` | `.agent/rules/specship.md` | write |\n\n`merge` inserts an idempotent `\u003c!-- specship:start --\u003e…\u003c!-- specship:end --\u003e`\nblock into your existing file. Re-running `init` updates that block without\nduplicating it, and creates the file if absent.\n\n`write` drops a standalone config file, such as a Cursor rule.\n\n## Contract Rules\n\n- **`task.md` is the source of truth.** Every skill reads it first and updates\n  it last with stage, status, artifact status, and a timestamped Pipeline Log\n  line.\n- **IDs are stable and append-only.** `R#`, `AC#`, `S#`, and `BUG#` are never\n  renumbered. Dropped items are struck through with a timestamp, not deleted.\n- **Checkboxes are progress.** `coding` ticks `S#` in `plan.md`; `review` ticks\n  `AC#` in `spec.md`. Unticked means not done.\n- **Everything is timestamped.** Timestamps use `YYYY-MM-DD HH:MM +TZ`, taken\n  from `date`, never guessed.\n- **Edit in place, never fork.** Artifacts evolve via `updated:` and Change\n  History lines. There is no `spec-v2.md`.\n- **Upstream changes invalidate downstream work.** If `spec.md` changes after\n  the plan exists, the plan or review may be stale and must be revisited.\n- **Stage preconditions are enforced.** `plan` requires a `confirmed` spec,\n  `coding` requires an `approved` plan, and `review` requires all `S#` items\n  ticked.\n- **The flow learns from its own mistakes.** Process errors become lessons in\n  `tasks/LESSONS.md`, which every stage reads during hydration.\n- **Lifecycle changes preserve pipeline state.** `pause-task`, `archive-task`,\n  and `resume-task` change only `status`/location, never `stage` or artifacts,\n  and each transition logs a dated reason. Un-shelving fully re-activates a task\n  (out of `archive/` and back to `active`) before any stage resumes.\n\nThe full contract is in [skills/WORKFLOW.md](skills/WORKFLOW.md). Each stage\nplaybook lives in `skills/\u003cstage\u003e/SKILL.md`.\n\n## Example\n\n[examples/slugify-demo/](examples/slugify-demo/) is a complete worked task for\na `slugify()` utility. It ran the full pipeline, including a real bug caught\nduring coding, root-caused and logged as `BUG1` in `debug.md`, then verified\nin review.\n\nRead `examples/slugify-demo/tasks/TASK-001/*` to see every artifact in\npractice, and `examples/slugify-demo/tasks/LESSONS.md` for process lessons\nrecorded against the contract.\n\n## Package Layout\n\n```text\nskills/                 # canonical skill playbooks shipped to each agent\n.claude/CLAUDE.md       # pointer template → installed as CLAUDE.md\n.codex/AGENTS.md        # pointer template → installed as AGENTS.md\n.cursor/WORKFLOW.mdc    # pointer template → installed as .cursor/rules/specship.mdc\n.antigravity/rules.md   # pointer template → installed as .agent/rules/specship.md\nbin/cli.js              # CLI entry\nsrc/                    # CLI logic; targets.js holds source→dest mappings\nexamples/slugify-demo/  # complete worked task, not installed\n```\n\nTo add or re-map an agent, edit `src/targets.js` and add its pointer template.\nNo other code changes are needed.\n\n## Contributing\n\nBug reports and pull requests are welcome on\n[GitHub](https://github.com/bonnguyenitc/specship/issues).\n\n```bash\ngit clone https://github.com/bonnguyenitc/specship.git\ncd specship\nnpm test\n```\n\n- Keep changes small and focused; `npm test` must pass before and after.\n- CLI behavior lives in `src/` ([src/targets.js](src/targets.js) maps each\n  agent's source → destination paths).\n- Changes to the workflow itself belong in `skills/` — that is what `init`\n  ships to user projects.\n\n## Releases\n\nSee [GitHub Releases](https://github.com/bonnguyenitc/specship/releases) for\nthe changelog. specship follows [semver](https://semver.org); until 1.0,\nminor versions may include breaking changes.\n\n## License\n\n[MIT](LICENSE) © 2026 Thoai Nguyen\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonnguyenitc%2Fspecship","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbonnguyenitc%2Fspecship","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbonnguyenitc%2Fspecship/lists"}