tuncss-plan-kit 0.1.1 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.opencode/plugins/tuncss-plan-kit.js +48 -44
- package/README.md +115 -113
- package/bin/cli.js +454 -429
- package/commands/codex/brainstorm.md +1 -1
- package/commands/codex/changelog.md +1 -0
- package/commands/codex/handoff-plan.md +1 -1
- package/commands/codex/plan-universal.md +1 -1
- package/commands/opencode/brainstorm.md +5 -5
- package/commands/opencode/changelog.md +5 -0
- package/commands/opencode/handoff-plan.md +5 -5
- package/commands/opencode/plan-universal.md +5 -5
- package/package.json +36 -36
- package/skills/brainstorm/SKILL.md +132 -132
- package/skills/changelog/SKILL.md +95 -0
- package/skills/handoff-plan/SKILL.md +78 -77
- package/skills/plan-universal/SKILL.md +139 -138
- package/templates/instructions-block.md +3 -2
|
@@ -1,44 +1,48 @@
|
|
|
1
|
-
import path from "path";
|
|
2
|
-
import { fileURLToPath } from "url";
|
|
3
|
-
|
|
4
|
-
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
5
|
-
const skillsDir = path.resolve(__dirname, "../../skills");
|
|
6
|
-
|
|
7
|
-
// Minimal templates: just pass the user's input through. The skill's
|
|
8
|
-
// `description` frontmatter is what triggers the model to invoke the skill
|
|
9
|
-
// when relevant — we don't force-load it from the wrapper, which would
|
|
10
|
-
// dump the full SKILL.md body into the chat in OpenCode's UI.
|
|
11
|
-
const WRAPPERS = {
|
|
12
|
-
brainstorm: {
|
|
13
|
-
description: "Turn an idea into an approved spec",
|
|
14
|
-
template: "$ARGUMENTS\n",
|
|
15
|
-
},
|
|
16
|
-
"plan-universal": {
|
|
17
|
-
description: "Turn an approved spec into an executable implementation plan",
|
|
18
|
-
template: "$ARGUMENTS\n",
|
|
19
|
-
},
|
|
20
|
-
"handoff-plan": {
|
|
21
|
-
description:
|
|
22
|
-
"Generate a paste-ready handoff message for another LLM agent to execute the plan",
|
|
23
|
-
template: "$ARGUMENTS\n",
|
|
24
|
-
},
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
}
|
|
34
|
-
config.
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
}
|
|
1
|
+
import path from "path";
|
|
2
|
+
import { fileURLToPath } from "url";
|
|
3
|
+
|
|
4
|
+
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
5
|
+
const skillsDir = path.resolve(__dirname, "../../skills");
|
|
6
|
+
|
|
7
|
+
// Minimal templates: just pass the user's input through. The skill's
|
|
8
|
+
// `description` frontmatter is what triggers the model to invoke the skill
|
|
9
|
+
// when relevant — we don't force-load it from the wrapper, which would
|
|
10
|
+
// dump the full SKILL.md body into the chat in OpenCode's UI.
|
|
11
|
+
const WRAPPERS = {
|
|
12
|
+
brainstorm: {
|
|
13
|
+
description: "Turn an idea into an approved spec",
|
|
14
|
+
template: "$ARGUMENTS\n",
|
|
15
|
+
},
|
|
16
|
+
"plan-universal": {
|
|
17
|
+
description: "Turn an approved spec into an executable implementation plan",
|
|
18
|
+
template: "$ARGUMENTS\n",
|
|
19
|
+
},
|
|
20
|
+
"handoff-plan": {
|
|
21
|
+
description:
|
|
22
|
+
"Generate a paste-ready handoff message for another LLM agent to execute the plan",
|
|
23
|
+
template: "$ARGUMENTS\n",
|
|
24
|
+
},
|
|
25
|
+
changelog: {
|
|
26
|
+
description: "Record what changed in docs/CHANGELOG.md",
|
|
27
|
+
template: "$ARGUMENTS\n",
|
|
28
|
+
},
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
export const TuncssPlanKitPlugin = async () => ({
|
|
32
|
+
config: async (config) => {
|
|
33
|
+
config.skills = config.skills || {};
|
|
34
|
+
config.skills.paths = config.skills.paths || [];
|
|
35
|
+
if (!config.skills.paths.includes(skillsDir)) {
|
|
36
|
+
config.skills.paths.push(skillsDir);
|
|
37
|
+
}
|
|
38
|
+
config.command = config.command || {};
|
|
39
|
+
for (const [name, def] of Object.entries(WRAPPERS)) {
|
|
40
|
+
if (!config.command[name]) {
|
|
41
|
+
config.command[name] = {
|
|
42
|
+
template: def.template,
|
|
43
|
+
description: def.description,
|
|
44
|
+
};
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
},
|
|
48
|
+
});
|
package/README.md
CHANGED
|
@@ -1,113 +1,115 @@
|
|
|
1
|
-
# tuncss-plan-kit
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
- **`/brainstorm`** — turn an idea into an approved spec (`docs/specs/`)
|
|
6
|
-
- **`/plan-universal`** — turn a spec into an executable plan (`docs/plans/`)
|
|
7
|
-
- **`/handoff-plan`** — generate a paste-ready briefing for another LLM agent to execute the plan (`docs/handoffs/`)
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
| `.
|
|
25
|
-
| `.
|
|
26
|
-
|
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
npx tuncss-plan-kit init --target=claude
|
|
33
|
-
npx tuncss-plan-kit init --target=
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
|
46
|
-
|
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
>
|
|
89
|
-
>
|
|
90
|
-
>
|
|
91
|
-
>
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
|
104
|
-
|
|
105
|
-
| `--
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
1
|
+
# tuncss-plan-kit
|
|
2
|
+
|
|
3
|
+
Four skills for spec-driven development, installable into Claude Code, Codex CLI, and OpenCode:
|
|
4
|
+
|
|
5
|
+
- **`/brainstorm`** — turn an idea into an approved spec (`docs/specs/`)
|
|
6
|
+
- **`/plan-universal`** — turn a spec into an executable plan (`docs/plans/`)
|
|
7
|
+
- **`/handoff-plan`** — generate a paste-ready briefing for another LLM agent to execute the plan (`docs/handoffs/`)
|
|
8
|
+
- **`/changelog`** — record what changed, in plain sentences (`docs/CHANGELOG.md`)
|
|
9
|
+
|
|
10
|
+
No agents, no routing, no TDD ceremony. Just four skills that get you from idea → spec → plan → handoff, and a record of what actually changed.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
In your project directory:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
npx tuncss-plan-kit init
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
The installer auto-detects which platform(s) the project uses and writes the right files.
|
|
21
|
+
|
|
22
|
+
| Detected | Means |
|
|
23
|
+
|---|---|
|
|
24
|
+
| `.claude/` or `CLAUDE.md` | Claude Code |
|
|
25
|
+
| `.codex/` | Codex CLI |
|
|
26
|
+
| `.opencode/` | OpenCode |
|
|
27
|
+
| `AGENTS.md` (alone) | Both Codex and OpenCode (they share `AGENTS.md`) |
|
|
28
|
+
|
|
29
|
+
If nothing is detected, pass an explicit target:
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
npx tuncss-plan-kit init --target=claude
|
|
33
|
+
npx tuncss-plan-kit init --target=claude,codex
|
|
34
|
+
npx tuncss-plan-kit init --target=all
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Re-running is safe. Skill and command files are overwritten only with `--force`. Instruction-file marker blocks are always replaced in place — your other content survives.
|
|
38
|
+
|
|
39
|
+
Restart your coding agent after install so it picks up the new skills and slash commands.
|
|
40
|
+
|
|
41
|
+
## What gets written where
|
|
42
|
+
|
|
43
|
+
| Platform | Skills | Commands | Instructions |
|
|
44
|
+
|---|---|---|---|
|
|
45
|
+
| Claude Code | `.claude/skills/<n>/SKILL.md` | *(none — skills auto-expose as slash)* | `CLAUDE.md` |
|
|
46
|
+
| Codex CLI | `.agents/skills/<n>/SKILL.md` | `.codex/prompts/<n>.md` | `AGENTS.md` |
|
|
47
|
+
| OpenCode | `.opencode/skills/<n>/SKILL.md` | `.opencode/commands/<n>.md` | `AGENTS.md` |
|
|
48
|
+
|
|
49
|
+
Claude Code automatically exposes any skill named `foo` as `/foo`, so the kit doesn't write wrapper command files for it. Codex and OpenCode don't auto-expose, so wrappers are written there to give you the same `/brainstorm`, `/plan-universal`, `/handoff-plan` UX everywhere.
|
|
50
|
+
|
|
51
|
+
With `--global` the same files go to user-wide locations (`~/.claude/`, `~/.agents/`, `~/.codex/`).
|
|
52
|
+
|
|
53
|
+
**OpenCode `--global` is supported via an npm-plugin route**: the kit installs itself into `~/.config/opencode/node_modules/`, registers itself in `~/.config/opencode/opencode.json`'s `plugin` array, and drops command wrappers into `~/.config/opencode/commands/`. After install, restart OpenCode — skills appear in every project. (For Claude and Codex, `--global` is a plain file copy.)
|
|
54
|
+
|
|
55
|
+
Project-local is still the default for all three — recommended unless you specifically want the kit available everywhere.
|
|
56
|
+
|
|
57
|
+
## Workflow
|
|
58
|
+
|
|
59
|
+
```
|
|
60
|
+
You: /brainstorm I want a CLI that ...
|
|
61
|
+
Agent: ↓ brainstorming skill
|
|
62
|
+
asks one question at a time, proposes 2-3 approaches, presents
|
|
63
|
+
the design section by section, writes spec to docs/specs/
|
|
64
|
+
You: (review and approve)
|
|
65
|
+
|
|
66
|
+
You: /plan-universal
|
|
67
|
+
Agent: ↓ writing-plans skill
|
|
68
|
+
writes plan to docs/plans/ with execution contract at the top,
|
|
69
|
+
tasks shaped as Targets / Model Tier / Implementation Notes /
|
|
70
|
+
Done When / Verification
|
|
71
|
+
|
|
72
|
+
You: do TASK-01
|
|
73
|
+
Agent: reads only TASK-01's block, stays inside its Targets, writes the
|
|
74
|
+
changelog entry to docs/CHANGELOG.md, stops for approval when done
|
|
75
|
+
|
|
76
|
+
— or —
|
|
77
|
+
|
|
78
|
+
You: /handoff-plan
|
|
79
|
+
Agent: ↓ handoff skill
|
|
80
|
+
writes a short briefing to docs/handoffs/ that you can paste
|
|
81
|
+
into another agent (or feed it the file path)
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## What's in a plan
|
|
85
|
+
|
|
86
|
+
Every plan starts with this contract:
|
|
87
|
+
|
|
88
|
+
> 1. Read **only** that task's block. Do not preview other tasks.
|
|
89
|
+
> 2. Stay strictly inside its **Targets** — do not edit files outside that list.
|
|
90
|
+
> 3. Follow the **Implementation Notes**; do not invent extra scope.
|
|
91
|
+
> 4. When **Done When** and **Verification** are satisfied, write the changelog entry (rule 6), then **stop and report**. Wait for approval before moving to the next task.
|
|
92
|
+
> 5. If verification fails, report the failure and stop. Do not attempt fixes outside the task's Targets, and do not write a changelog entry.
|
|
93
|
+
> 6. **Changelog entry:** use the `changelog` skill to append this task's entry to `docs/CHANGELOG.md`. Base it on the actual diff, not on what you set out to do.
|
|
94
|
+
|
|
95
|
+
Tasks are tagged with model tiers (T1 Fast / T2 Balanced / T3 Power / T4 Reasoning) so you can route execution to the cheapest model that can do the job.
|
|
96
|
+
|
|
97
|
+
## Options
|
|
98
|
+
|
|
99
|
+
```
|
|
100
|
+
npx tuncss-plan-kit init [--target=<list>] [--global] [--force]
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
| Flag | Effect |
|
|
104
|
+
|------|--------|
|
|
105
|
+
| `--target=<list>` | Comma-separated. Values: `claude`, `codex`, `opencode`, `all`. Auto-detected if omitted. |
|
|
106
|
+
| `--global` | Install to user-wide locations instead of the current project. |
|
|
107
|
+
| `--force` | Overwrite existing skill/command files without warning. |
|
|
108
|
+
|
|
109
|
+
## Why this exists
|
|
110
|
+
|
|
111
|
+
Existing kits ship dozens of agents and skills you'll never use, but every one of them sits in your context and burns tokens each turn. `tuncss-plan-kit` ships four files that cover the only loop most projects need: design → plan → execute (here or elsewhere) → record. That's it.
|
|
112
|
+
|
|
113
|
+
## License
|
|
114
|
+
|
|
115
|
+
MIT
|