Skip to content
Back to search

Opencode-Roadmap

A set of tools that allow sharing a repo-wide todoliist between sessions.

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/igorwarzocha--opencode-roadmap/badge.svg)](/listings/igorwarzocha--opencode-roadmap)

HTML

<a href="/listings/igorwarzocha--opencode-roadmap"><img src="/api/listings/igorwarzocha--opencode-roadmap/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Add to your `opencode.json`:

{
  "plugins": [
    "@howaboua/opencode-planning-toolkit@latest"
  ]
}

Or for local development:

{
  "plugins": [
    "file:///path/to/opencode-planning-toolkit/index.ts"
  ]
}

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.

README.md · README · 165 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # OpenCode Planning Toolkit
  2. **Keep your projects organized and your AI agents aligned.**
  3. This plugin adds structure to your development workflow with reusable specifications, actionable plans, and progress tracking—all integrated directly into OpenCode.
  4. ## Why This Plugin
  5. - Enables planning with any and all agents
  6. - Organize work into reusable specs and actionable plans
  7. - Track progress with clear status (active/done)
  8. - Maintain project-wide standards that apply across all work
  9. - Automatically receive `<available_plans>` in the system prompt with all plan names and descriptions
  10. - **Bundled skill** automatically loads to guide agents through proper planning workflow
  11. ## Tools
  12. - **`create_spec`** - Create a reusable specification (repo-level or feature-specific)
  13. - **`create_plan`** - Create an actionable work plan with implementation steps (min 5)
  14. - **`append_spec`** - Link an existing spec to a plan
  15. - **`read_plan`** - Read a plan with all linked spec content expanded inline
  16. - **`mark_plan_done`** - Mark a plan as complete
  17. ![opencode-roadmap](https://github.com/user-attachments/assets/e2479a72-ec65-457f-9503-bf2d01580c70)
  18. ## Bundled Skill
  19. This plugin includes a **bundled skill** (`plans-and-specs`) that automatically loads with the plugin. The skill provides agents with:
  20. - Clear workflow instructions for creating plans and specs
  21. - Proper order of operations (create plan → append REPO specs → ask about FEATURE specs)
  22. - Instructions to check for existing plans before creating new ones
  23. - Guidance on when to use each tool
  24. **When agents use it:**
  25. - User asks to create a plan, roadmap, or break down work
  26. - User mentions specs, requirements, or standards documentation
  27. - User references existing plans that need reading or updating
  28. - User asks to mark work complete or link requirements
  29. The skill ensures agents follow best practices automatically without manual prompting.
  30. ## Installation
  31. Add to your `opencode.json`:
  32. ```json
  33. {
  34. "plugins": [
  35. "@howaboua/opencode-planning-toolkit@latest"
  36. ]
  37. }
  38. ```
  39. Or for local development:
  40. ```json
  41. {
  42. "plugins": [
  43. "file:///path/to/opencode-planning-toolkit/index.ts"
  44. ]
  45. }
  46. ```
  47. ## Quick Start
  48. ### 1. Create a Reusable Spec
  49. Define standards or requirements once, use them everywhere:
  50. **Ask the agent:** "Create a repo-level spec for TypeScript coding standards"
  51. The agent creates `docs/specs/typescript-standards.md`:
  52. ```markdown
  53. # Spec: typescript-standards
  54. Scope: repo
  55. - Use strict mode
  56. - All functions must have explicit return types
  57. - Prefer `const` over `let`
  58. - No `any` types without justification
  59. ```
  60. ### 2. Create a Plan
  61. Turn a goal into actionable steps:
  62. **Ask the agent:** "Create a plan for adding user authentication"
  63. The agent creates `docs/plans/user-auth.md`:
  64. ```markdown
  65. ---
  66. plan name: user-auth
  67. plan description: JWT authentication for API
  68. plan status: active
  69. ---
  70. ## Idea
  71. Add secure JWT authentication to the API with login, logout, and token refresh.
  72. ## Implementation
  73. - Design JWT token structure and expiry policy
  74. - Add /auth/login endpoint with password validation
  75. - Add /auth/refresh endpoint for token renewal
  76. - Add /auth/logout endpoint to invalidate tokens
  77. - Write tests for all auth endpoints
  78. ## Required Specs
  79. <!-- SPECS_START -->
  80. <!-- SPECS_END -->
  81. ```
  82. **Agent automatically:**
  83. 1. Links any existing REPO scope specs
  84. 2. Asks if you want a FEATURE spec for this plan
  85. ### 3. Link Specs to Plans
  86. Attach relevant specs to ensure standards are followed:
  87. **Ask the agent:** "Link typescript-standards spec to the user-auth plan"
  88. The plan updates:
  89. ```markdown
  90. ## Required Specs
  91. <!-- SPECS_START -->
  92. - typescript-standards
  93. <!-- SPECS_END -->
  94. ```
  95. ### 4. Read Before Work
  96. When starting implementation, the agent reads the full context:
  97. **Ask the agent:** "Read the user-auth plan and start implementing"
  98. The agent receives the full plan with all linked spec content expanded inline.
  99. ### 5. Mark Complete
  100. **Ask the agent:** "Mark the user-auth plan as done"
  101. Status updates from `active` → `done`.
  102. ## File Organization
  103. ```
  104. your-project/
  105. ├── docs/
  106. │ ├── specs/ # Reusable specifications
  107. │ │ └── *.md # Each spec is a markdown file
  108. │ └── plans/ # Work plans
  109. │ └── *.md # Each plan is a markdown file
  110. ```
  111. **Specs naming:** `{name}.md` (e.g., `typescript-standards.md`)
  112. **Plans naming:** `{name}.md` (e.g., `user-auth.md`)
  113. ## License
  114. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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