{"_id":"@codewithahsan/paperclip-plugin-gsd","_rev":"3-23ea4a3eca7f5a92e31c2fe09e5639b4","name":"@codewithahsan/paperclip-plugin-gsd","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@codewithahsan/paperclip-plugin-gsd","version":"0.1.0","keywords":["paperclip","plugin","gsd","get-shit-done","project-management","ai-agents","claude-code","gemini-cli"],"author":{"name":"Ahsan Ayaz","email":"ahsan@codewithahsan.dev"},"license":"MIT","_id":"@codewithahsan/paperclip-plugin-gsd@0.1.0","maintainers":[{"name":"ahsanayaz","email":"ahsan.ubitian@gmail.com"}],"homepage":"https://github.com/AhsanAyaz/paperclip-plugin-gsd#readme","bugs":{"url":"https://github.com/AhsanAyaz/paperclip-plugin-gsd/issues"},"dist":{"shasum":"05ba42f5b2666a9819d5b50802d5c33971151253","tarball":"https://registry.npmjs.org/@codewithahsan/paperclip-plugin-gsd/-/paperclip-plugin-gsd-0.1.0.tgz","fileCount":9,"integrity":"sha512-dkIUPM1LfQFPvRY3n2ERI7vU20rm9idx08+oJ9DkcaCf/dv2zyKY+s5fShcqkcFCtV3ZK7QBjaxMqs96UDWbjQ==","signatures":[{"sig":"MEUCIQCFFRZXaeppS/Gh3JW0IyelWJMKPRteDhlrKZgKoT4aSAIgawINQJLClh97bDMO1/VqfJ7dQWML2Na291+UlGCbcyA=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":643607},"type":"module","exports":{".":"./dist/worker.js","./ui":"./dist/ui/index.js","./manifest":"./dist/manifest.js"},"gitHead":"531a54fe2e976daf7d6b7e0000b64452355a7afa","scripts":{"test":"vitest run","build":"node esbuild.config.mjs","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest","build:watch":"node esbuild.config.mjs --watch","prepublishOnly":"npm run build"},"_npmUser":{"name":"ahsanayaz","email":"ahsan.ubitian@gmail.com"},"repository":{"url":"git+https://github.com/AhsanAyaz/paperclip-plugin-gsd.git","type":"git"},"_npmVersion":"10.9.2","description":"GSD (Get Shit Done) plugin for Paperclip. Syncs phases, milestones, and progress from agent workspaces into Paperclip issues and UI.","directories":{},"_nodeVersion":"22.13.1","dependencies":{"@paperclipai/plugin-sdk":"^2026.318.0"},"_hasShrinkwrap":false,"devDependencies":{"react":"^19.0.0","vitest":"^3.0.0","esbuild":"^0.27.3","react-dom":"^19.0.0","typescript":"^5.7.3","@types/node":"^24.6.0","@types/react":"^19.0.8","@types/react-dom":"^19.0.3"},"paperclipPlugin":{"ui":"./dist/ui/","worker":"./dist/worker.js","manifest":"./dist/manifest.js"},"peerDependencies":{"react":">=18"},"_npmOperationalInternal":{"tmp":"tmp/paperclip-plugin-gsd_0.1.0_1774183291906_0.9557018390617338","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@codewithahsan/paperclip-plugin-gsd","version":"0.1.1","keywords":["paperclip","plugin","gsd","get-shit-done","project-management","ai-agents","claude-code","gemini-cli"],"author":{"name":"Ahsan Ayaz","email":"ahsan@codewithahsan.dev"},"license":"MIT","_id":"@codewithahsan/paperclip-plugin-gsd@0.1.1","maintainers":[{"name":"ahsanayaz","email":"ahsan.ubitian@gmail.com"}],"homepage":"https://github.com/AhsanAyaz/paperclip-plugin-gsd#readme","bugs":{"url":"https://github.com/AhsanAyaz/paperclip-plugin-gsd/issues"},"dist":{"shasum":"8828415fb14b6f0aebc8b2321eb4fb124bbe52ed","tarball":"https://registry.npmjs.org/@codewithahsan/paperclip-plugin-gsd/-/paperclip-plugin-gsd-0.1.1.tgz","fileCount":9,"integrity":"sha512-lujbvLilgzD90BgoX4c2NKEbwHKUgFw4b8+Hovwc9eF5B/wqb3qUPafJ/qHNcZVqGjyNwkggAQSgN1dSD1Y3tQ==","signatures":[{"sig":"MEYCIQC1VgcG3QNoEhaJyBM6WTtUd61/iruR4Kp0tf6mVkQvhQIhALI/v13Yaghm9pB58nJ4osMckaE0CbnYIKBd1K+ex7PY","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":640358},"type":"module","exports":{".":"./dist/worker.js","./ui":"./dist/ui/index.js","./manifest":"./dist/manifest.js"},"gitHead":"ab6b94d5a4f8fb6f3d1f1f88f0b7fb167384d117","scripts":{"test":"vitest run","build":"node esbuild.config.mjs","clean":"rm -rf dist","typecheck":"tsc --noEmit","test:watch":"vitest","build:watch":"node esbuild.config.mjs --watch","postinstall":"patch-package","prepublishOnly":"npm run build"},"_npmUser":{"name":"ahsanayaz","email":"ahsan.ubitian@gmail.com"},"repository":{"url":"git+https://github.com/AhsanAyaz/paperclip-plugin-gsd.git","type":"git"},"_npmVersion":"10.9.2","description":"GSD (Get Shit Done) plugin for Paperclip. Syncs phases, milestones, and progress from agent workspaces into Paperclip issues and UI.","directories":{},"_nodeVersion":"22.13.1","dependencies":{"@paperclipai/plugin-sdk":"^2026.318.0"},"_hasShrinkwrap":false,"devDependencies":{"react":"^19.0.0","vitest":"^3.0.0","esbuild":"^0.27.3","react-dom":"^19.0.0","typescript":"^5.7.3","@types/node":"^24.6.0","@types/react":"^19.0.8","patch-package":"^8.0.1","@types/react-dom":"^19.0.3","postinstall-postinstall":"^2.1.0"},"paperclipPlugin":{"ui":"./dist/ui/","worker":"./dist/worker.js","manifest":"./dist/manifest.js"},"peerDependencies":{"react":">=18"},"_npmOperationalInternal":{"tmp":"tmp/paperclip-plugin-gsd_0.1.1_1780437473205_0.055883186264094276","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@codewithahsan/paperclip-plugin-gsd","version":"0.1.2","description":"GSD (Get Shit Done) plugin for Paperclip. Syncs phases, milestones, and progress from agent workspaces into Paperclip issues and UI.","type":"module","license":"MIT","author":{"name":"Ahsan Ayaz","email":"ahsan@codewithahsan.dev"},"repository":{"type":"git","url":"git+https://github.com/AhsanAyaz/paperclip-plugin-gsd.git"},"keywords":["paperclip","plugin","gsd","get-shit-done","project-management","ai-agents","claude-code","gemini-cli"],"exports":{".":"./dist/worker.js","./manifest":"./dist/manifest.js","./ui":"./dist/ui/index.js"},"paperclipPlugin":{"manifest":"./dist/manifest.js","worker":"./dist/worker.js","ui":"./dist/ui/"},"scripts":{"build":"node esbuild.config.mjs","build:watch":"node esbuild.config.mjs --watch","clean":"rm -rf dist","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","postinstall":"patch-package","prepublishOnly":"npm run build"},"dependencies":{"@paperclipai/plugin-sdk":"^2026.318.0"},"devDependencies":{"@types/node":"^24.6.0","@types/react":"^19.0.8","@types/react-dom":"^19.0.3","esbuild":"^0.27.3","patch-package":"^8.0.1","postinstall-postinstall":"^2.1.0","react":"^19.0.0","react-dom":"^19.0.0","typescript":"^5.7.3","vitest":"^3.0.0"},"peerDependencies":{"react":">=18"},"_id":"@codewithahsan/paperclip-plugin-gsd@0.1.2","gitHead":"a21f35ee36ae1c9f74aa70341647a3326a539244","bugs":{"url":"https://github.com/AhsanAyaz/paperclip-plugin-gsd/issues"},"homepage":"https://github.com/AhsanAyaz/paperclip-plugin-gsd#readme","_nodeVersion":"22.13.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-6HKMJS33zfW5Rm6kprZzBBX7oAJRyAIF4IqpfpdC47XcQG3jsdZdvbab4Fnf3Y+4JOgGp9GsD/dvNi824bVnrA==","shasum":"3b62646951552c27ce08105a4da005e29925a176","tarball":"https://registry.npmjs.org/@codewithahsan/paperclip-plugin-gsd/-/paperclip-plugin-gsd-0.1.2.tgz","fileCount":9,"unpackedSize":640492,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDWeFDpsw10k8ilZxclrTXfYdq7DlQwehZ4cFxqpXRm4AiAD97l6DH05ht0ds+vwFjYKtkWk5oTP9YhFa7MvcZ3VsQ=="}]},"_npmUser":{"name":"ahsanayaz","email":"ahsan.ubitian@gmail.com"},"directories":{},"maintainers":[{"name":"ahsanayaz","email":"ahsan.ubitian@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/paperclip-plugin-gsd_0.1.2_1780438312645_0.23481379865292884"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-22T12:41:31.746Z","modified":"2026-06-02T22:11:52.944Z","0.1.0":"2026-03-22T12:41:32.080Z","0.1.1":"2026-06-02T21:57:53.382Z","0.1.2":"2026-06-02T22:11:52.822Z"},"bugs":{"url":"https://github.com/AhsanAyaz/paperclip-plugin-gsd/issues"},"author":{"name":"Ahsan Ayaz","email":"ahsan@codewithahsan.dev"},"license":"MIT","homepage":"https://github.com/AhsanAyaz/paperclip-plugin-gsd#readme","keywords":["paperclip","plugin","gsd","get-shit-done","project-management","ai-agents","claude-code","gemini-cli"],"repository":{"type":"git","url":"git+https://github.com/AhsanAyaz/paperclip-plugin-gsd.git"},"description":"GSD (Get Shit Done) plugin for Paperclip. Syncs phases, milestones, and progress from agent workspaces into Paperclip issues and UI.","maintainers":[{"name":"ahsanayaz","email":"ahsan.ubitian@gmail.com"}],"readme":"# @codewithahsan/paperclip-plugin-gsd\n\n> Bring your GSD planning workflows into [Paperclip](https://github.com/paperclipai/paperclip) — see phase progress, milestones, and verification status right where you manage your AI agents.\n\n---\n\n## Why this exists\n\nIf you use [GSD (Get Shit Done)](https://github.com/get-shit-done/get-shit-done) to plan and execute work with AI agents, you already know how powerful it is. Phases, plans, waves, verification — GSD gives your agents real structure.\n\nBut there's a gap: GSD lives in the terminal. Your `.planning/` directory has all the state, but you can't see it from Paperclip's UI. You can't glance at a dashboard and know which phases are done, which agent is executing, or whether verification passed.\n\nThis plugin bridges that gap. It reads GSD's `.planning/` files (the single source of truth) and surfaces everything in Paperclip — dashboard widgets, project tabs, issue linking, and more. No reimplementation, no duplication. Just a clean read-only window into what GSD is doing.\n\n## How it works\n\n```mermaid\nflowchart LR\n    subgraph Agent Environment\n        A[AI Agent] -->|runs| B[GSD Plugin]\n        B -->|writes| C[.planning/ directory]\n    end\n\n    subgraph Paperclip\n        D[paperclip-plugin-gsd] -->|reads| C\n        D -->|syncs state| E[Plugin State Store]\n        E --> F[Dashboard Widget]\n        E --> G[Project Tab]\n        E --> H[Issue Tab]\n        E --> I[Settings Page]\n        D -->|posts comments| J[Linked Issues]\n    end\n\n    style C fill:#4f46e5,stroke:#4f46e5,color:#fff\n    style D fill:#22c55e,stroke:#22c55e,color:#fff\n```\n\nThe plugin **never writes** to `.planning/` — it only reads. GSD remains the single source of truth.\n\n### Sync triggers\n\nThe plugin syncs GSD state in three ways:\n\n```mermaid\nflowchart TD\n    A[Agent finishes a run] -->|event: agent.run.finished| S[Sync workspace]\n    B[New workspace created] -->|event: project.workspace_created| S\n    C[Periodic timer] -->|every N seconds| S\n    D[Manual button click] -->|action: sync-project| S\n\n    S --> P[Parse .planning/]\n    P --> U[Update plugin state]\n    U --> I[Comment on linked issues]\n```\n\n### Phase lifecycle\n\nGSD phases move through a well-defined lifecycle. The plugin detects where each phase is by analyzing which files exist:\n\n```mermaid\nstateDiagram-v2\n    [*] --> NotStarted: Phase directory created\n    NotStarted --> Context: CONTEXT.md written\n    Context --> Researching: RESEARCH.md written\n    Researching --> Planned: PLAN.md files created\n    Planned --> Executing: First SUMMARY.md written\n    Executing --> Executing: More SUMMARY.md files\n    Executing --> Finishing: All SUMMARY.md done (current phase)\n    Finishing --> Complete: Verification passed\n    Finishing --> Verifying: Gaps found / needs review\n    Verifying --> Complete: Gaps resolved\n    Executing --> Diagnosed: UAT found issues\n    Diagnosed --> Executing: Fix plans added\n```\n\n| Status | What it means | How it's detected |\n|--------|---------------|-------------------|\n| Not Started | Phase directory exists, nothing inside | No CONTEXT, RESEARCH, or PLAN files |\n| Context Gathered | Design vision captured | `CONTEXT.md` present |\n| Researched | Technical research done | `RESEARCH.md` present |\n| Planned | Plans created, ready to execute | `PLAN.md` files exist, no `SUMMARY.md` |\n| Executing | Agent is working through plans | Some plans have `SUMMARY.md` |\n| Finishing | All plans done, post-execution running | All `SUMMARY.md` exist, still current phase |\n| Verifying | Verification found gaps or needs human review | `VERIFICATION.md` status is `gaps_found` or `human_needed` |\n| Complete | Phase fully done | All `SUMMARY.md` + verification passed (or no verification) |\n| Gaps Found | UAT diagnosed issues | `UAT.md` status is `diagnosed` |\n\n## Getting started\n\n### Prerequisites\n\n- A running [Paperclip](https://github.com/paperclipai/paperclip) instance\n- [GSD](https://github.com/get-shit-done/get-shit-done) installed in your agent's environment (Claude Code plugin, Gemini CLI skill, etc.)\n\n### Install the plugin\n\nFrom npm:\n\n```bash\nnpx paperclipai plugin install @codewithahsan/paperclip-plugin-gsd\n```\n\nFrom a local clone:\n\n```bash\ngit clone https://github.com/AhsanAyaz/paperclip-plugin-gsd.git\ncd paperclip-plugin-gsd\nnpm install && npm run build\nnpx paperclipai plugin install ./\n```\n\n### What you'll see\n\nOnce installed, the plugin adds five UI components to Paperclip:\n\n| Component | Where | What it shows |\n|-----------|-------|---------------|\n| **Dashboard Widget** | Main dashboard | Progress overview across all projects |\n| **GSD Tab** | Project detail page | Full phase roadmap with progress bars, artifact badges, and verification status |\n| **GSD Phase Tab** | Issue detail page | Phase details for issues linked to GSD phases |\n| **Sync GSD Button** | Project toolbar | One-click manual sync |\n| **GSD Settings** | Plugin settings | Auto-sync toggle, sync interval, agent compatibility table |\n\n### Configuration\n\nOpen the GSD Settings page in Paperclip to configure:\n\n- **Auto-sync** — Enable/disable periodic syncing (default: enabled)\n- **Sync interval** — How often to check for GSD changes, 10–600 seconds (default: 30s)\n\n### Linking phases to issues\n\nYou can link GSD phases to Paperclip issues. When a linked phase makes progress (plans complete, verification runs), the plugin posts a comment on the issue automatically.\n\nUse the `link-phase` action via the plugin API:\n\n```\nprojectId: \"your-project-id\"\nphaseNumber: \"17\"\nissueId: \"your-issue-id\"\n```\n\n## Architecture\n\n```\nsrc/\n├── manifest.ts          # Plugin manifest (capabilities, UI slots, config schema)\n├── worker.ts            # Core sync logic, event handlers, data providers, actions\n├── gsd-parser.ts        # Reads and parses .planning/ directory structure\n├── gsd-types.ts         # TypeScript interfaces for all GSD data structures\n├── adapter-compat.ts    # Agent adapter compatibility detection\n├── constants.ts         # Plugin IDs, data keys, action keys\n└── ui/\n    └── index.tsx         # All 5 UI components (React)\n```\n\n### Key design decisions\n\n- **Read-only** — The plugin never modifies `.planning/` files. GSD is the single source of truth.\n- **File-based detection** — Phase status is inferred from which files exist (CONTEXT.md, RESEARCH.md, PLAN.md, SUMMARY.md, VERIFICATION.md, UAT.md), not from any configuration.\n- **Adapter-aware** — Not all agent adapters support GSD. The plugin detects compatibility and surfaces it clearly in the settings page.\n- **Event-driven + periodic** — Syncs happen on agent run completion, workspace creation, and on a configurable timer. Manual sync is always available.\n\n## Development\n\n```bash\n# Install dependencies\nnpm install\n\n# Build the plugin (worker + manifest + UI)\nnpm run build\n\n# Watch mode for development\nnpm run build:watch\n\n# Run tests\nnpm test\n\n# Type check\nnpm run typecheck\n```\n\n### Running tests\n\nTests use [Vitest](https://vitest.dev/) and test the GSD parser against fixture files in `tests/fixtures/.planning/`:\n\n```bash\nnpm test\n```\n\n## Contributing\n\nContributions are welcome! Whether it's a bug fix, a new feature, or better docs — we'd love your help.\n\n### How to contribute\n\n1. **Fork** the repo\n2. **Create a branch** for your change (`git checkout -b feat/my-feature`)\n3. **Make your changes** — follow the existing code style\n4. **Add tests** if you're changing parser or worker logic\n5. **Run `npm test`** to make sure nothing breaks\n6. **Open a PR** with a clear description of what you changed and why\n\n### Ideas for contributions\n\n- Better UI components (charts, timeline views)\n- Support for more agent adapters\n- Phase-to-issue auto-linking based on naming conventions\n- Milestone progress tracking across multiple projects\n- Notifications when phases complete or verification fails\n\n### Code style\n\n- TypeScript, strict mode\n- No unnecessary abstractions — keep it simple\n- Tests for parser and worker logic\n- UI components use inline styles with CSS variable fallbacks\n\n## Compatibility\n\n- **Paperclip** — tested with the latest version\n- **GSD** — compatible with the GSD `.planning/` directory format\n- **Agents** — works with Claude Code (`claude_local` adapter, full support), OpenCode (`opencode_local` adapter, full support), process-based agents (partial support). Other adapters will show an informational message.\n\n## License\n\nMIT — see [LICENSE](./LICENSE)\n\n---\n\nBuilt with care by [Ahsan Ayaz](https://codewithahsan.dev). If this plugin helps your workflow, give it a star!\n","readmeFilename":"README.md"}