Skip to content
Back to search

research-workflow

MarketplaceWorks with Claude CodeGitHub

Research workflow skills for Claude.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/giulianonetto--research-workflow/badge.svg)](/listings/giulianonetto--research-workflow)

HTML

<a href="/listings/giulianonetto--research-workflow"><img src="/api/listings/giulianonetto--research-workflow/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "research-workflow",
  3. "owner": { "name": "giulianonetto" },
  4. "description": "Research workflow skills for Claude.",
  5. "plugins": [
  6. {
  7. "name": "research-workflow",
  8. "source": "./",
  9. "description": "Plans, progress logs, DECISION lines and experiments for research repos.",
  10. "category": "productivity",
  11. "keywords": ["research", "planning", "experiments"]
  12. }
  13. ]
  14. }
README.md · README · 109 lines
  1. # research-workflow
  2. **Claude skills for research repos.** You plan with Claude over days, and every session picks up where the last one stopped. Claude builds the plan step by step and stops where you said you want to look.
  3. **Site:** [giulianonetto.github.io/research-workflow](https://giulianonetto.github.io/research-workflow/), everything on one page, with a worked example.
  4. <picture>
  5. <source media="(prefers-color-scheme: dark)" srcset="docs/img/flow-dark.svg">
  6. <img src="docs/img/flow-light.svg" alt="The life of a task: start a plan, shape it, finalize it, build it in runs, close it. The draft lives in tmp/ until you approve it, then moves to plans/ on a task branch, linked from the issue. Finalize checks that every step is ready to build (one commit, or sub-steps) and becomes planned only after you approve the plan and its stops. Claude reviews each step before its commit and the whole branch before the PR; you review and merge the PR. Under each stage: what you do and what you see on GitHub. Every session starts with /project-refresher and ends with /progress. Record keeping: PROGRESS.md at the root, the folder log (one per project), logs active tasks, status changes, PRs and releases; plans/<task>/PROGRESS.md, the task log (one per task), logs the work of each step, its DECISION lines and what is next. Any time: /sandbox to check by hand, or change the plan.">
  7. </picture>
  8. ## Why use it
  9. - **Pick up where you left off**, even after weeks.
  10. - **Keep every decision**, with its reason, one `grep` away.
  11. - **Decide where Claude stops.** Between stops, it builds alone.
  12. - **Review in small pieces.** One commit per step, one box per step in the GitHub issue, one PR per big step.
  13. ## How a build runs
  14. <picture>
  15. <source media="(prefers-color-scheme: dark)" srcset="docs/img/runs-dark.svg">
  16. <img src="docs/img/runs-light.svg" alt="A build in runs: /implement-next builds steps 1 and 2, then stops so you can look at the plots; run again, it builds steps 3 to 6 and stops for the review and the PR into main.">
  17. </picture>
  18. Each `/implement-next` asks once, then builds up to the next **Stop** in the plan (at most 5 steps). It also stops early if a test fails or a question comes up that the plan does not answer. Claude pushes the task branch after each step: allow `git push` in Claude Code's `/permissions` to skip the prompt.
  19. ## Get started
  20. <picture>
  21. <source media="(prefers-color-scheme: dark)" srcset="docs/img/start-dark.svg">
  22. <img src="docs/img/start-light.svg" alt="Get started: install the plugin, run /setup-workflow once per repo, then /new-plan for each task.">
  23. </picture>
  24. 1. **Install.** In Claude Desktop, open **Customize → Plugins → Add marketplace** and enter:
  25. ```
  26. giulianonetto/research-workflow
  27. ```
  28. Then add the **research-workflow** plugin (connect GitHub if asked). Turn on **Sync automatically** to get updates.
  29. 2. **Set up a repo** with `/setup-workflow`. After an update, run it again: it shows what changed.
  30. 3. **Start a task:** say the idea, then `/new-plan`.
  31. <details>
  32. <summary>Claude Code without Claude Desktop</summary>
  33. ```bash
  34. claude plugin install research-workflow --marketplace giulianonetto/research-workflow
  35. ```
  36. Commands then carry the plugin's name: `/research-workflow:setup-workflow`. Install it one way only, or every command appears twice.
  37. </details>
  38. ## Commands
  39. | Command | When |
  40. |---|---|
  41. | `/project-refresher` | Start of a session: "where was I? what is next?" |
  42. | `/project-refresher tasks` | All tasks with their status |
  43. | `/new-plan` | A new task |
  44. | `/grill-plan` | Hard questions about a draft plan |
  45. | `/finalize-plan` | The plan is ready to build |
  46. | `/implement-next` | Build up to the next stop |
  47. | `/sandbox` | Check something by hand |
  48. | `/progress` | Log work, change a status (or say "log progress") |
  49. An **experiment** (try something out, end in an answer) is a task too: start it with `/new-plan exp`, and write it up with `/write-results` before you close it.
  50. The plan can change at any time: just say what to change. All rules live in one file in your project, `plans/README.md`. All past decisions: `grep -rn '^- \*\*DECISION' PROGRESS.md plans/*/PROGRESS.md`
  51. More examples [on the site](https://giulianonetto.github.io/research-workflow/#example): one task from idea to merged PR, then a new repo, an open issue, coming back to a draft, and an experiment.
  52. <details>
  53. <summary><b>What it writes in a project</b></summary>
  54. ```
  55. your-project/
  56. ├── CLAUDE.md + a short workflow section
  57. ├── README.md + a short workflow section
  58. ├── PROGRESS.md the folder log: active tasks, status changes, PRs, releases
  59. └── plans/
  60. ├── README.md all the rules
  61. └── <task>/
  62. ├── PLAN.md the plan: Goal, steps, stops
  63. ├── PROGRESS.md the task log: work, DECISION lines, Next
  64. └── sandbox/ code for you to run and look at
  65. ```
  66. </details>
  67. ## Credits
  68. This project is heavily inspired by Matt Pocock's [mattpocock-skills](https://github.com/mattpocock/skills) (MIT License). `/grill-plan` and the Spec part of the review are adapted from it; see [NOTICE](NOTICE).
  69. ## Development
  70. <details>
  71. <summary><b>Working on this repo</b></summary>
  72. This repo uses its own workflow: see [PROGRESS.md](PROGRESS.md) and [plans/](plans/). Every design decision is a DECISION line.
  73. - `python3 tests/check_skills.py`: frontmatter, plugin manifest, versions, local links, stale names.
  74. - `bash tests/check_scripts.sh`: runs the `run.sh` template and the refresher on a fake project.
  75. - `python3 docs/figures.py`: redraws the README figures in `docs/img/` (light and dark).
  76. - Both checks run on every push (GitHub Actions). Pushing a tag `vX.Y.Z` builds the zips and attaches them to a release.
  77. Releasing: bump `version` in `.claude-plugin/plugin.json` and the `Workflow version:` line in `skills/setup-workflow/PLANS-README.md` (the checks fail if they differ), add a `## X.Y.Z` section to [CHANGELOG.md](CHANGELOG.md), then tag.
  78. </details>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.