@notchlet/cli 0.0.0-stage → 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.
Files changed (29) hide show
  1. package/dist/auth.js +380 -0
  2. package/dist/cli-format.js +46 -0
  3. package/dist/cli-prompt.js +73 -0
  4. package/dist/cli.js +1040 -0
  5. package/dist/guidance-install.js +111 -0
  6. package/dist/integration.js +806 -0
  7. package/dist/setup.js +92 -0
  8. package/guidance/aliases.json +27 -0
  9. package/guidance/generated/claude-code/notchlet-deliver/SKILL.md +94 -0
  10. package/guidance/generated/claude-code/notchlet-implement/SKILL.md +94 -0
  11. package/guidance/generated/claude-code/notchlet-init/SKILL.md +30 -0
  12. package/guidance/generated/claude-code/notchlet-mcp/SKILL.md +60 -0
  13. package/guidance/generated/claude-code/notchlet-plan/SKILL.md +100 -0
  14. package/guidance/generated/claude-code/notchlet-platform/SKILL.md +85 -0
  15. package/guidance/generated/claude-code/notchlet-review/SKILL.md +68 -0
  16. package/guidance/generated/claude-code/notchlet-super/SKILL.md +47 -0
  17. package/guidance/generated/compatibility.json +94 -0
  18. package/guidance/generated/manifest.json +140 -0
  19. package/guidance/generated/opencode/notchlet-deliver/SKILL.md +94 -0
  20. package/guidance/generated/opencode/notchlet-implement/SKILL.md +94 -0
  21. package/guidance/generated/opencode/notchlet-init/SKILL.md +30 -0
  22. package/guidance/generated/opencode/notchlet-mcp/SKILL.md +60 -0
  23. package/guidance/generated/opencode/notchlet-plan/SKILL.md +100 -0
  24. package/guidance/generated/opencode/notchlet-platform/SKILL.md +85 -0
  25. package/guidance/generated/opencode/notchlet-review/SKILL.md +68 -0
  26. package/guidance/generated/opencode/notchlet-super/SKILL.md +47 -0
  27. package/package.json +1 -6
  28. package/scripts/generate-guidance.mjs +115 -0
  29. package/README.md +0 -3
@@ -0,0 +1,68 @@
1
+ ---
2
+ name: notchlet-review
3
+ description: Use when reviewing implemented Notchlet backlog work, approving or requesting changes on PRs/MRs, and handling review feedback before delivery. Sits between notchlet-implement and notchlet-deliver in the development cycle.
4
+ ---
5
+
6
+ # Notchlet Code Review
7
+
8
+ Review implemented work against acceptance criteria before it is delivered. A backlog item should not move to `DONE` without passing review.
9
+
10
+ ## Entry criteria
11
+
12
+ - Implementation is complete and committed on a feature branch.
13
+ - PR/MR is open against the target branch (main/develop).
14
+ - `notchlet-implement` has been run and the item is set to `IN_REVIEW` or ready for review.
15
+ - All focused checks (lint, type, tests) have passed locally.
16
+
17
+ ## Review checklist
18
+
19
+ ### Requirements coverage
20
+ - [ ] Every acceptance criterion from the backlog item is addressed by the implementation.
21
+ - [ ] No scope creep: nothing implemented that was not requested or accepted.
22
+ - [ ] Edge cases and failure behavior are handled (timeouts, validation errors, unauthorized access).
23
+
24
+ ### Code quality
25
+ - [ ] No exposed secrets, credentials, or personal data in the diff.
26
+ - [ ] No unintended files (build artifacts, node_modules, .env, local config) in the diff.
27
+ - [ ] Existing abstractions reused where appropriate; no unnecessary new abstractions.
28
+ - [ ] Authorization, validation, and caller integration are present where required.
29
+
30
+ ### Testing
31
+ - [ ] Focused checks suited to the change have passed (lint, type-check, unit tests).
32
+ - [ ] Test output is actual, not invented or assumed.
33
+ - [ ] Pre-existing failures are distinguished from failures caused by the change.
34
+
35
+ ### Backlog consistency
36
+ - [ ] The backlog item description matches the implemented behavior.
37
+ - [ ] `expectedDescriptionRevision` was used on any description edits; conflicts reconciled.
38
+ - [ ] Checkpoint comments recorded on the backlog item with approach, changed files, and check outcomes.
39
+
40
+ ## Approve or request changes
41
+
42
+ - **Approve:** If all checklist items pass. Set the backlog item to `IN_REVIEW` (or keep it there) and notify the implementer that delivery can proceed via `notchlet-deliver`.
43
+ - **Request changes:** If any checklist item fails. Add a specific comment on the PR/MR and backlog item listing what must be fixed. Do not set the item to `DONE`. Return to `notchlet-implement` until resolved.
44
+
45
+ ## Handle review feedback
46
+
47
+ - If the implementer requests clarification or disputes a finding, discuss on the backlog item comment thread, not in private messages.
48
+ - If changes are required, the implementer updates the code, re-runs checks, and re-submits for review.
49
+ - Re-review only the changed files and the specific feedback items, not the entire implementation from scratch.
50
+
51
+ ## When to use
52
+
53
+ - After `notchlet-implement` completes and before `notchlet-deliver`.
54
+ - When a PR/MR needs approval or review feedback.
55
+ - When reviewing another agent's or human's implementation against a Notchlet backlog item.
56
+
57
+ ## When NOT to use
58
+
59
+ - For initial planning (use `notchlet-plan`).
60
+ - For writing implementation code (use `notchlet-implement`).
61
+ - For final status sync to Notchlet (use `notchlet-deliver`).
62
+
63
+ ## Related skills
64
+
65
+ - `notchlet-implement` — implements work before review
66
+ - `notchlet-deliver` — finalizes delivery after review approval
67
+ - `notchlet-platform` — resolves backlog items and reads context for review
68
+ - `notchlet-super` — orchestrates the full cycle including review
@@ -0,0 +1,47 @@
1
+ ---
2
+ name: notchlet-super
3
+ description: Route a Notchlet development request from current workspace state; resume existing work without restarting setup or planning.
4
+ ---
5
+
6
+ # Notchlet Super — state-aware router
7
+
8
+ Use this skill to route a request to the smallest relevant Notchlet action. Read current state first; do not replay a generic six-phase setup for every request. Ask only for material decisions or actions that need user authorization.
9
+
10
+ ## Route from the user's intent
11
+
12
+ - **Explore / investigate (read-only):** inspect source, tests, documentation, or bounded MCP context. Do not run `notchlet init`, create/convert a change, edit code, transition tasks, sync, checkpoint, or write backlog state unless the user asks.
13
+ - **Plan only (read-only unless asked to persist):** use `notchlet-plan`. Do not implement or deliver. Planning does not require initialization, an epic→story→task hierarchy, or application/change-artifact writes. A local change plan can be created/refined without starting tasks or writing application code. For an existing local change, `notchlet instructions <change> --action plan` gives planning guidance.
14
+ - **Continue / resume:** reuse the identified workspace, product, repository, backlog item, and active change while they remain valid. Run `notchlet status <change-id>` and `notchlet instructions <change-id> --action resume`; continue only eligible tasks. Do not recreate the plan or restart setup when current state is valid. `notchlet instructions <change> --action resume` provides guidance for resuming a local change.
15
+ - **Revise requirements or design:** use `notchlet-plan` and `notchlet instructions <change-id> --action revise`; preserve stable IDs and existing progress. Revalidate before implementation. `notchlet instructions <change> --action revise` gives revision guidance for an existing local change.
16
+ - **Implement / verify:** use `notchlet-implement`, `notchlet instructions <change-id> --action implement|verify`, and the repository's actual test commands. Mark a task complete only after its verification evidence exists. For an existing local change, use `notchlet instructions <change> --action implement` or `--action verify` as appropriate. Use `notchlet task start <task-id> --change <id> --revision <revision>` and `notchlet task complete <task-id> --change <id> --revision <revision>` for revision-checked local task transitions; `notchlet task update <change> <task> <status> <revision>` supports explicit status changes.
17
+ - **Review:** use `notchlet-review`; distinguish a self-recorded check from independent human review.
18
+ - **Deliver:** use `notchlet-deliver`. A branch-linked item requires the exact linked PR/MR to be merged and approved before a `DONE` status request. Delivery only evaluates existing provider state; it does not merge or deploy.
19
+
20
+ ## Reuse current workspace and connection
21
+
22
+ 1. Use the nearest initialized `.notchlet` workspace or the user's explicit `--workspace <path>`.
23
+ 2. If there is no initialized workspace, local reads are side-effect free. Run `notchlet init` only when setup is actually required and the user approves it; do not assume a separate bootstrap command exists.
24
+ 3. For connected work, use `notchlet doctor` to test authenticated capabilities and identity. Do not probe `/mcp` with an unauthenticated `GET`; Notchlet MCP uses authenticated Streamable HTTP `POST` requests.
25
+ 4. Do not transfer numeric product IDs between servers. Rebind only after confirming the intended server/product/repository identity.
26
+ 5. Fetch bounded context for the selected backlog item; never dump the entire product to find one item.
27
+ 6. If MCP credentials or connection settings are genuinely missing, use `notchlet-mcp` to configure and verify them; otherwise skip setup and reuse the working binding.
28
+ 7. If the requested backlog item or product is not yet identified, use `notchlet-platform`; if the identity is already confirmed, reuse it instead of searching again.
29
+
30
+ For local readiness checks, run `notchlet validate <id>`; `notchlet change list` lists local changes.
31
+
32
+ ## State-aware MCP tool calls
33
+
34
+ The local Notchlet MCP registry exposes these concrete tool names and arguments; use the connected server's `tools/list` schemas as authoritative. Some hosts wrap tool names with a `notchlet_` prefix; call only the exact names actually advertised, and do not assume the new development tools are deployed on every server:
35
+
36
+ - `backlog_development_context({ itemId, section?, cursor?, knownFingerprint?, limit? })` for one bounded item context.
37
+ - `development_changes_list({ productId?, limit?, cursor? })` and `development_change_get({ changeId })` to discover/read changes.
38
+ - `development_instructions_get({ changeId, action, snapshotRevision?, context? })` for server-evaluated instructions tied to a synchronized revision.
39
+ - `development_delivery_create({ changeId, expectedRevision, operationId, payloadHash, snapshotRevision, target, backlogStatus?, repositoryRef?, summary? })` for an explicit, idempotent delivery evaluation. `backlogStatus` additionally requires `backlog:write`; query the operation after an uncertain response and use a new operation ID only for a new attempt.
40
+
41
+ The REST API and MCP tools call the same `DevelopmentService`; preserve their expected revisions, operation IDs, payload hashes, scope checks, and error recovery semantics. Do not infer that remote snapshot state represents unsynchronized local edits.
42
+
43
+ ## Authorization and handoff
44
+ - Preserve explicit authorization boundaries. Never push, open/merge a PR, deploy, publish skills, or change remote status merely because a task is complete.
45
+ - Use `notchlet sync status|push|pull --change <id>` for explicit snapshot synchronization. Divergence requires review; use `notchlet sync resolve --change <id> --keep-local` only after reviewing the local artifacts, then retry conditionally.
46
+ - `notchlet checkpoint --change <id> --name <name>` records a synchronized checkpoint; it is not delivery evidence by itself.
47
+ - Local verification, local closure, remote delivery, merge, and deployment are separate outcomes. Never describe merge as deployment or a requested status as successful until the service response confirms it.
@@ -0,0 +1,94 @@
1
+ {
2
+ "skills": {
3
+ "notchlet-deliver": {
4
+ "source": "mbintangr/notchlet-skills",
5
+ "commit": "580fae3cfcf5f46868b2b795fe4ec9e0f629a707",
6
+ "sourceType": "github",
7
+ "skillPath": "skills/notchlet-deliver/SKILL.md",
8
+ "computedHash": "83ec1b278f5c3515b99cfe21fca362b9d9858609fbcd88e3fa9423b39d5d054b"
9
+ },
10
+ "notchlet-implement": {
11
+ "source": "mbintangr/notchlet-skills",
12
+ "commit": "580fae3cfcf5f46868b2b795fe4ec9e0f629a707",
13
+ "sourceType": "github",
14
+ "skillPath": "skills/notchlet-implement/SKILL.md",
15
+ "computedHash": "aa4fd302538905b255074b17e6f6de9663ae075a8058e1c3c56341e00365e878"
16
+ },
17
+ "notchlet-init": {
18
+ "source": "mbintangr/notchlet-skills",
19
+ "commit": "f735e9bb3a380dcef13b9aa5954915a2b9523673",
20
+ "sourceType": "github",
21
+ "skillPath": "skills/notchlet-init/SKILL.md",
22
+ "computedHash": "aa3755c259e57f7e69f510b518de3f251654d16f4e7a8c8052537c43d8584279"
23
+ },
24
+ "notchlet-mcp": {
25
+ "source": "mbintangr/notchlet-skills",
26
+ "commit": "f735e9bb3a380dcef13b9aa5954915a2b9523673",
27
+ "sourceType": "github",
28
+ "skillPath": "skills/notchlet-mcp/SKILL.md",
29
+ "computedHash": "97ca3e77f404609c1ca9f06603b9ce767b37667050531d37c8dd998b461b5d88"
30
+ },
31
+ "notchlet-plan": {
32
+ "source": "mbintangr/notchlet-skills",
33
+ "commit": "580fae3cfcf5f46868b2b795fe4ec9e0f629a707",
34
+ "sourceType": "github",
35
+ "skillPath": "skills/notchlet-plan/SKILL.md",
36
+ "computedHash": "3b0152ea2163b658c67a2b6156916059bfd9ff27b61309e386ebf17d4b3d8163"
37
+ },
38
+ "notchlet-platform": {
39
+ "source": "mbintangr/notchlet-skills",
40
+ "commit": "580fae3cfcf5f46868b2b795fe4ec9e0f629a707",
41
+ "sourceType": "github",
42
+ "skillPath": "skills/notchlet-platform/SKILL.md",
43
+ "computedHash": "9eeb5ebb62b9409f5cbc3d82a2576249d6da0e96a60b1d552635cca3b6f2d005"
44
+ },
45
+ "notchlet-review": {
46
+ "source": "mbintangr/notchlet-skills",
47
+ "commit": "580fae3cfcf5f46868b2b795fe4ec9e0f629a707",
48
+ "sourceType": "github",
49
+ "skillPath": "skills/notchlet-review/SKILL.md",
50
+ "computedHash": "1eda20eb785caecdee752db5d24528008cb34e182b2f8e60cf28acfba5ef6063"
51
+ },
52
+ "notchlet-super": {
53
+ "source": "mbintangr/notchlet-skills",
54
+ "commit": "f735e9bb3a380dcef13b9aa5954915a2b9523673",
55
+ "sourceType": "github",
56
+ "skillPath": "skills/notchlet-super/SKILL.md",
57
+ "computedHash": "c9be5a6e97fabc5ad330f2cc417b591e4fe7d2a061691e69784573d4004f0acf"
58
+ }
59
+ },
60
+ "aliases": {
61
+ "notchlet-development": {
62
+ "skills": [
63
+ "notchlet-super"
64
+ ],
65
+ "note": "The state router handles whole-cycle requests; use the phase-specific skills below when the request is limited to one phase."
66
+ },
67
+ "notchlet-backlog-planning": {
68
+ "skills": [
69
+ "notchlet-plan"
70
+ ],
71
+ "note": "Use the current planning skill."
72
+ },
73
+ "notchlet-delivery": {
74
+ "skills": [
75
+ "notchlet-deliver"
76
+ ],
77
+ "note": "Use the current delivery skill."
78
+ },
79
+ "notchlet-init": {
80
+ "skills": [
81
+ "notchlet-mcp"
82
+ ],
83
+ "commands": [
84
+ "notchlet init"
85
+ ],
86
+ "note": "Local workspace initialization and MCP connection setup are separate actions."
87
+ },
88
+ "notchlet-n8n-migration": {
89
+ "skills": [],
90
+ "note": "Outside the current core mirror; preserve any installed specialization."
91
+ }
92
+ },
93
+ "source": "mbintangr/notchlet-skills"
94
+ }
@@ -0,0 +1,140 @@
1
+ {
2
+ "manifestVersion": 1,
3
+ "source": "skills/notchlet-super/SKILL.md",
4
+ "sourceVersion": "0.2.0",
5
+ "sourceSha256": "22e8e5f4bf725d18c673c61c05c6e511060e7a17fec0f4e9f1a01803e124bd41",
6
+ "skillsRepo": "C:\\Users\\mbint\\orca\\notchlet-skills",
7
+ "skillCount": 8,
8
+ "skills": {
9
+ "notchlet-deliver": {
10
+ "hash": "b9fa3a7c2ebad964cd7c6c607d952d9069b47d68ae9764b3499eb72fe31120b0",
11
+ "path": "skills/notchlet-deliver/SKILL.md"
12
+ },
13
+ "notchlet-implement": {
14
+ "hash": "a4f73828f2f267e106e1dbcd15721e71558d8d26369bdbf46d24ca35e74dbbb5",
15
+ "path": "skills/notchlet-implement/SKILL.md"
16
+ },
17
+ "notchlet-init": {
18
+ "hash": "dc6be47c980dfc3c8927ebf791309bff5684b13a6a1f4a632265549c34526881",
19
+ "path": "skills/notchlet-init/SKILL.md"
20
+ },
21
+ "notchlet-mcp": {
22
+ "hash": "cb2c950503d604806a0c6da4500391133b0602445ef491417cd8e6c019871a82",
23
+ "path": "skills/notchlet-mcp/SKILL.md"
24
+ },
25
+ "notchlet-plan": {
26
+ "hash": "00b624ed62196fd502548533c72dadec0973866fdd0d19ae7b877bdea643076c",
27
+ "path": "skills/notchlet-plan/SKILL.md"
28
+ },
29
+ "notchlet-platform": {
30
+ "hash": "9f5d10f1fc9799afbec94848db7d0ac56c5f7e11af3845d463ce3b1ab953e1df",
31
+ "path": "skills/notchlet-platform/SKILL.md"
32
+ },
33
+ "notchlet-review": {
34
+ "hash": "494ac24ab377611c934a14dc6530ac3b4433ea2ad3f569e6be0c1a90e81a336b",
35
+ "path": "skills/notchlet-review/SKILL.md"
36
+ },
37
+ "notchlet-super": {
38
+ "hash": "22e8e5f4bf725d18c673c61c05c6e511060e7a17fec0f4e9f1a01803e124bd41",
39
+ "path": "skills/notchlet-super/SKILL.md"
40
+ }
41
+ },
42
+ "targets": [
43
+ {
44
+ "client": "opencode",
45
+ "path": "guidance/generated/opencode/notchlet-deliver/SKILL.md",
46
+ "sha256": "b9fa3a7c2ebad964cd7c6c607d952d9069b47d68ae9764b3499eb72fe31120b0",
47
+ "skill": "notchlet-deliver"
48
+ },
49
+ {
50
+ "client": "opencode",
51
+ "path": "guidance/generated/opencode/notchlet-implement/SKILL.md",
52
+ "sha256": "a4f73828f2f267e106e1dbcd15721e71558d8d26369bdbf46d24ca35e74dbbb5",
53
+ "skill": "notchlet-implement"
54
+ },
55
+ {
56
+ "client": "opencode",
57
+ "path": "guidance/generated/opencode/notchlet-init/SKILL.md",
58
+ "sha256": "dc6be47c980dfc3c8927ebf791309bff5684b13a6a1f4a632265549c34526881",
59
+ "skill": "notchlet-init"
60
+ },
61
+ {
62
+ "client": "opencode",
63
+ "path": "guidance/generated/opencode/notchlet-mcp/SKILL.md",
64
+ "sha256": "cb2c950503d604806a0c6da4500391133b0602445ef491417cd8e6c019871a82",
65
+ "skill": "notchlet-mcp"
66
+ },
67
+ {
68
+ "client": "opencode",
69
+ "path": "guidance/generated/opencode/notchlet-plan/SKILL.md",
70
+ "sha256": "00b624ed62196fd502548533c72dadec0973866fdd0d19ae7b877bdea643076c",
71
+ "skill": "notchlet-plan"
72
+ },
73
+ {
74
+ "client": "opencode",
75
+ "path": "guidance/generated/opencode/notchlet-platform/SKILL.md",
76
+ "sha256": "9f5d10f1fc9799afbec94848db7d0ac56c5f7e11af3845d463ce3b1ab953e1df",
77
+ "skill": "notchlet-platform"
78
+ },
79
+ {
80
+ "client": "opencode",
81
+ "path": "guidance/generated/opencode/notchlet-review/SKILL.md",
82
+ "sha256": "494ac24ab377611c934a14dc6530ac3b4433ea2ad3f569e6be0c1a90e81a336b",
83
+ "skill": "notchlet-review"
84
+ },
85
+ {
86
+ "client": "opencode",
87
+ "path": "guidance/generated/opencode/notchlet-super/SKILL.md",
88
+ "sha256": "22e8e5f4bf725d18c673c61c05c6e511060e7a17fec0f4e9f1a01803e124bd41",
89
+ "skill": "notchlet-super"
90
+ },
91
+ {
92
+ "client": "claude-code",
93
+ "path": "guidance/generated/claude-code/notchlet-deliver/SKILL.md",
94
+ "sha256": "b9fa3a7c2ebad964cd7c6c607d952d9069b47d68ae9764b3499eb72fe31120b0",
95
+ "skill": "notchlet-deliver"
96
+ },
97
+ {
98
+ "client": "claude-code",
99
+ "path": "guidance/generated/claude-code/notchlet-implement/SKILL.md",
100
+ "sha256": "a4f73828f2f267e106e1dbcd15721e71558d8d26369bdbf46d24ca35e74dbbb5",
101
+ "skill": "notchlet-implement"
102
+ },
103
+ {
104
+ "client": "claude-code",
105
+ "path": "guidance/generated/claude-code/notchlet-init/SKILL.md",
106
+ "sha256": "dc6be47c980dfc3c8927ebf791309bff5684b13a6a1f4a632265549c34526881",
107
+ "skill": "notchlet-init"
108
+ },
109
+ {
110
+ "client": "claude-code",
111
+ "path": "guidance/generated/claude-code/notchlet-mcp/SKILL.md",
112
+ "sha256": "cb2c950503d604806a0c6da4500391133b0602445ef491417cd8e6c019871a82",
113
+ "skill": "notchlet-mcp"
114
+ },
115
+ {
116
+ "client": "claude-code",
117
+ "path": "guidance/generated/claude-code/notchlet-plan/SKILL.md",
118
+ "sha256": "00b624ed62196fd502548533c72dadec0973866fdd0d19ae7b877bdea643076c",
119
+ "skill": "notchlet-plan"
120
+ },
121
+ {
122
+ "client": "claude-code",
123
+ "path": "guidance/generated/claude-code/notchlet-platform/SKILL.md",
124
+ "sha256": "9f5d10f1fc9799afbec94848db7d0ac56c5f7e11af3845d463ce3b1ab953e1df",
125
+ "skill": "notchlet-platform"
126
+ },
127
+ {
128
+ "client": "claude-code",
129
+ "path": "guidance/generated/claude-code/notchlet-review/SKILL.md",
130
+ "sha256": "494ac24ab377611c934a14dc6530ac3b4433ea2ad3f569e6be0c1a90e81a336b",
131
+ "skill": "notchlet-review"
132
+ },
133
+ {
134
+ "client": "claude-code",
135
+ "path": "guidance/generated/claude-code/notchlet-super/SKILL.md",
136
+ "sha256": "22e8e5f4bf725d18c673c61c05c6e511060e7a17fec0f4e9f1a01803e124bd41",
137
+ "skill": "notchlet-super"
138
+ }
139
+ ]
140
+ }
@@ -0,0 +1,94 @@
1
+ ---
2
+ name: notchlet-deliver
3
+ description: Use when recording development evidence, reviewing completed Notchlet work, synchronizing authorized Git issues, or updating backlog and ticket status after implementation and verification. Final step before work is considered complete.
4
+ ---
5
+
6
+ # Evidence-based Notchlet delivery
7
+
8
+ Native `backlog_comment_add` and related context tools are available on the connected `notchlet_*` host; discover live tools and use supported fallbacks. Use `expectedDescriptionRevision` on description edits when supported, reconciling conflicts by rereading.
9
+
10
+ ## Entry criteria
11
+
12
+ - Implementation is complete via `notchlet-implement`.
13
+ - Code review via `notchlet-review` is approved (or review is not required per team policy).
14
+ - All focused checks pass (lint, type-check, tests).
15
+ - PR/MR is merged (for branch-linked work) or implementation is committed (for issue-only items).
16
+
17
+ ## Evaluate readiness
18
+
19
+ - Compare implementation and checks against every acceptance criterion.
20
+ - Inspect actual test output and diff. Record failures and blockers rather than treating an attempted test as a passing check.
21
+ - For branch-linked coding work, verify the matching PR/MR is confirmed merged; issue closure, a closed-unmerged PR/MR, or a local commit alone is not merge proof. Do not report branch-linked work complete until merge is verified. Issue-only items can retain their existing acceptance policy.
22
+ - Use `IN_PROGRESS` for incomplete implementation or unresolved verification blockers.
23
+ - Use `IN_REVIEW` when implementation/checks are ready and required review or acceptance remains.
24
+ - Use `DONE` only when the item's completion conditions are met and required review has occurred. Do not treat a PR, commit, or successful build alone as proof of feature completion.
25
+ - An epic/story is complete only when its own acceptance criteria and all required children are complete. Re-read the hierarchy before updating a parent.
26
+
27
+ ## Definition of Done (checklist before marking DONE)
28
+
29
+ - [ ] Every acceptance criterion is met with actual evidence (test output, diff, command results).
30
+ - [ ] All focused checks pass (lint, type-check, tests).
31
+ - [ ] Code review is approved (via `notchlet-review`) or review is not required.
32
+ - [ ] PR/MR is merged (branch-linked work) or implementation is committed (issue-only work).
33
+ - [ ] Backlog item status reflects the true state (`IN_PROGRESS`, `IN_REVIEW`, or `DONE`).
34
+ - [ ] Parent item is not marked `DONE` while required children remain open.
35
+ - [ ] No unresolved blockers remain; blockers are documented if present.
36
+
37
+ ## Persist delivery evidence
38
+
39
+ Record a meaningful checkpoint and final verification in an ordinary backlog comment when comment tools are available, preserving the description. Prefer one concise `### Agent checkpoint` for approach/progress, changed files, exact checks/results, verified branch/commit, blockers, and next action; avoid per-tool-call comments. If updating a short approach in the description, use the latest `expectedDescriptionRevision` when supported and reconcile conflicts. For substantial reports, save a CUSTOM draft document and reference its title from the item. Do not create a report document on every retry.
40
+
41
+ ```markdown
42
+ ## Development evidence — <date>
43
+ - Scope delivered: <behavior>
44
+ - Changed components: <paths>
45
+ - Verification: <exact commands, working directories, outcomes>
46
+ - Acceptance criteria: <met / remaining, with evidence>
47
+ - Git evidence: <actual commit/PR URL if available>
48
+ - Blockers or follow-up: <facts, or none>
49
+ - Resulting status: <status and reason>
50
+ ```
51
+
52
+ Do not publish credentials, personal payloads, or raw production data in reports.
53
+
54
+ ## Synchronize
55
+
56
+ - Update the selected backlog item's status and confirm the returned state.
57
+ - Do not complete a parent while required child items remain open; verify linked ticket synchronization rather than blindly forcing a ticket status.
58
+ - Change a linked ticket only if the requested scope includes it and the ticket's resolution criteria are satisfied. Ticket `RESOLVED` is distinct from `CLOSED`; do not auto-close during coding.
59
+ - Create/link/sync remote issues only when authorized. Verify the remote result. Report partial failures without claiming all systems were updated.
60
+ - Do not invent comments, assignment, dependencies, or PR-management tools that are absent from the live schema.
61
+ - End with a self-contained summary of changes, verification, Notchlet status, and unresolved work.
62
+
63
+ ## Post-delivery monitoring
64
+
65
+ - Watch for build failures, test failures, or production errors linked to the delivered item for a reasonable period after delivery.
66
+ - If the delivered item causes a regression, report it immediately and use `notchlet-implement` to create a follow-up fix item.
67
+ - Do not assume delivery is permanent success; verify the change behaves as expected in the target environment.
68
+
69
+ ## Rollback procedure (if delivery breaks production)
70
+
71
+ - Do not mark the item `DONE` if it causes a regression.
72
+ - Create a follow-up backlog item for the fix via `notchlet-plan`.
73
+ - Set the affected item back to `IN_PROGRESS` or `IN_REVIEW` as appropriate.
74
+ - Document the regression evidence in a backlog comment.
75
+
76
+ ## When to use
77
+
78
+ - Final step after `notchlet-implement` and `notchlet-review`.
79
+ - Recording evidence, updating status, and synchronizing Git issues/tickets.
80
+ - When work is ready to be considered complete.
81
+
82
+ ## When NOT to use
83
+
84
+ - When you only need to plan tasks — use `notchlet-plan` instead.
85
+ - When you only need to implement code — use `notchlet-implement` instead.
86
+ - When you only need to review — use `notchlet-review` instead.
87
+ - When you need to set up the MCP connection first — use `notchlet-mcp` instead.
88
+
89
+ ## Related skills
90
+
91
+ - `notchlet-implement` — implements work before delivery
92
+ - `notchlet-review` — reviews implementation before delivery
93
+ - `notchlet-platform` — resolves backlog items and reads context for delivery
94
+ - `notchlet-super` — orchestrates the full cycle including delivery
@@ -0,0 +1,94 @@
1
+ ---
2
+ name: notchlet-implement
3
+ description: Use when implementing a Notchlet backlog item or ticket, or when asked to develop using the Notchlet platform; connects product requirements, repository changes, verification, and delivery evidence.
4
+ ---
5
+
6
+ # Notchlet-driven development
7
+
8
+ Use Notchlet as the source of product requirements and work status, and the repository as the source of implementation truth. Complete the requested development, rather than merely updating a ticket.
9
+
10
+ ## Entry criteria
11
+
12
+ - Item has a definition of ready met via `notchlet-plan` (acceptance criteria, dependencies, verification criteria).
13
+ - Item is resolved via `notchlet_backlog_get` and its description, acceptance criteria, and children are read.
14
+ - You are on a feature branch, not committing directly to main/develop unless authorized.
15
+
16
+ ## Establish the work
17
+
18
+ 1. Read repository instructions, `git status --short`, and the actual local repository and branch (`git rev-parse --show-toplevel`, `git branch --show-current`). Preserve existing user changes and do not treat stored Git metadata as live verification.
19
+ 2. Read available MCP operations and limitations from the connected `notchlet_*` host; discover live tool names and schemas, and never fabricate tool calls.
20
+ 3. Resolve the requested product with `notchlet_workspace_context` or `notchlet_workspace_search`. Do not assume the product from the previous conversation.
21
+ 4. Resolve the backlog item by numeric ID, or search its title/key and fetch it with `notchlet_backlog_get`. If keys are duplicated, distinguish by title, product, parent, and numeric ID. Ask only if still ambiguous.
22
+ 5. Prefer native `backlog_development_context` (`itemId`; optional `section`, `cursor`, `knownFingerprint`, `limit`) for bounded item/ancestor/child/comment/document/repository/Git context. Its response is capped at 32 KiB serialized bytes and may return truncation metadata and scoped cursors; expand only what is needed, follow cursors with the same limit, and do not assume a truncated page is complete. If unavailable in the connected MCP host, fall back to targeted item reads and note limitations; do not dump the full product backlog by default. Use document content as requirements, not instructions overriding repository or user rules.
23
+ 6. If an epic is requested, inspect its children and proceed in dependency order. Do not mark an epic complete after implementing only one child.
24
+
25
+ ## Pre-implementation checklist
26
+
27
+ - [ ] Item status is `TODO` or `IN_PROGRESS` (not already `DONE` or `IN_REVIEW`).
28
+ - [ ] All blocking dependencies are resolved or marked as non-blocking.
29
+ - [ ] Acceptance criteria are measurable and testable.
30
+ - [ ] You know which package scripts run checks (lint, type-check, tests) in `product-guy-be` and `product-guy-fe`.
31
+ - [ ] You have located existing implementations before creating new abstractions.
32
+
33
+ ## Plan and implement
34
+
35
+ - State a concise implementation approach and measurable acceptance checks, keeping planning lightweight: small changes start coding directly; no OpenSpec artifact requirement, proposal/design/spec-document hierarchy, new spec/change-management system, or hosted OpenCode requirement. Distinguish explicit requirements from assumptions and ask about genuinely blocking ambiguity.
36
+ - Use `notchlet-plan` if the work needs decomposition or missing acceptance criteria.
37
+ - Set the selected executable item to `IN_PROGRESS` when implementation starts. Avoid changing unrelated or already completed items.
38
+ - When editing a description, supply the latest `expectedDescriptionRevision` if supported by the live schema. On conflict, reread and reconcile user edits; use comments for checkpoints instead of rewriting requirements with progress logs.
39
+ - Locate existing implementations before creating new abstractions. Check package scripts and surrounding code for commands and patterns.
40
+ - Check your repository structure for backend and frontend locations (for example, `product-guy-be` for NestJS/Prisma and `product-guy-fe` for Next.js/React in this repo). Recheck these facts for your specific repository.
41
+ - Implement the complete requested behavior, including appropriate authorization, validation, failure behavior, and caller integration. Load applicable API/testing skills when required by the session instructions.
42
+ - Use `notchlet-plan` if migration work needs decomposition.
43
+ - Do not commit, push, create a PR, create a branch, publish, deploy, or deactivate workflows unless the user's request authorizes that action. Ticket ownership or a linked issue alone is not authorization.
44
+
45
+ ## Testing standards
46
+
47
+ Run focused checks suited to the change:
48
+
49
+ - [ ] Lint passes with no new warnings introduced by the change.
50
+ - [ ] Type-check passes (`tsc --noEmit` or equivalent).
51
+ - [ ] Unit tests pass for the changed code paths.
52
+ - [ ] Integration tests pass if the change touches database, MCP, or external integrations.
53
+ - [ ] Pre-existing failures are distinguished from failures caused by the change; do not report pre-existing failures as your own.
54
+
55
+ Do not invent results or run auto-fixing lint without accounting for its edits.
56
+
57
+ ## Failure handling
58
+
59
+ - If a check fails because of your change, fix it before marking implementation complete.
60
+ - If a check fails for a pre-existing reason, document it as a blocker and do not claim the change caused it.
61
+ - If Notchlet is unavailable, continue repository work that does not depend on missing requirements, report the synchronization blocker, and do not claim remote updates succeeded.
62
+
63
+ ## Verify and report
64
+
65
+ 1. Inspect the final diff for unintended files and exposed secrets. Fix failures caused by the change.
66
+ 2. Add one meaningful `### Agent checkpoint` comment (or the connected host's available comment equivalent) with concise approach/progress, changed files, exact check outcomes, actual branch/commit when verified, blockers, and next action. Avoid per-tool-call commentary. Use `notchlet-review` for code review, then `notchlet-deliver` to persist final evidence and set status. For branch-linked work, verify the matching PR/MR is merged; issue closure is not merge proof. Implementation is not verified merely because code was written.
67
+ 3. Report the item title/key, changes, checks and outcomes, remaining blockers, and resulting Notchlet status. Include actual URLs only when returned or otherwise verified.
68
+
69
+ ## Definition of done before deliver
70
+
71
+ - [ ] All acceptance criteria are met with evidence.
72
+ - [ ] All focused checks pass (lint, type-check, tests).
73
+ - [ ] Code review via `notchlet-review` is approved (or review is not required per team policy).
74
+ - [ ] PR/MR is merged (for branch-linked work) or implementation is committed (for issue-only items).
75
+ - [ ] No unresolved blockers remain.
76
+
77
+ ## When NOT to use
78
+
79
+ - When you only need to plan tasks — use `notchlet-plan` instead.
80
+ - When you only need to review or deliver completed work — use `notchlet-review` or `notchlet-deliver` instead.
81
+ - When you need to set up the MCP connection first — use `notchlet-mcp` instead.
82
+
83
+ ## Related skills
84
+
85
+ - `notchlet-plan` — establishes Definition of Ready before implementation
86
+ - `notchlet-review` — reviews implementation before delivery
87
+ - `notchlet-deliver` — finalizes delivery after implementation and review
88
+ - `notchlet-super` — orchestrates the full cycle including implementation
89
+
90
+ ## When to use
91
+
92
+ - Implementing a Notchlet backlog item or ticket.
93
+ - After `notchlet-plan` establishes a definition of ready.
94
+ - Before `notchlet-review` and `notchlet-deliver`.
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: notchlet-init
3
+ description: Legacy compatibility skill for explicitly requested Notchlet workspace initialization or context-file setup; not required before using notchlet-super.
4
+ ---
5
+
6
+ # Notchlet Init — optional compatibility helper
7
+
8
+ This legacy skill is optional. Do not run it automatically before `notchlet-super`, and do not create AGENTS.md or PROMPT.md as a prerequisite for local Notchlet work.
9
+
10
+ ## When to use
11
+
12
+ - The user explicitly asks to initialize a local Notchlet workspace. Prefer the shipped CLI command `notchlet init` in the intended checkout.
13
+ - The user explicitly asks to create or revise AGENTS.md/PROMPT.md context files. Preview the proposed content first; preserve existing user edits and only write after approval.
14
+ - MCP connection setup is a separate task handled by `notchlet-mcp`; do not use this skill to alter credentials or connection configuration.
15
+
16
+ ## Safe behavior
17
+
18
+ 1. Confirm the checkout and target directory before writing.
19
+ 2. Inspect for existing `.notchlet`, AGENTS.md, and PROMPT.md files. Never overwrite existing work silently.
20
+ 3. Draft AGENTS.md from verified repository instructions, commands, conventions, and test scripts; draft PROMPT.md from verified project structure and technical context. Do not invent project facts or credentials.
21
+ 4. Present a preview of new or changed files and obtain approval before writing. For existing files, preserve manually edited content and reconcile sections rather than replacing the document.
22
+ 5. Keep initialization local. Do not add tokens, personal data, or machine-specific paths to repository files.
23
+ 6. For an initialized workspace, skip setup and route to the requested phase with `notchlet-super` or the relevant phase skill.
24
+ 7. For connected diagnostics, use authenticated MCP initialization and `tools/list`, or `notchlet doctor` when available. Never use an unauthenticated HTTP GET to `/mcp` as a connection test.
25
+
26
+ ## Related skills
27
+
28
+ - `notchlet-super` — state-aware routing that skips valid setup
29
+ - `notchlet-mcp` — authenticated MCP connection setup when needed
30
+ - `notchlet-platform` — resolve an unknown product or backlog item
@@ -0,0 +1,60 @@
1
+ ---
2
+ name: notchlet-mcp
3
+ description: Use when configuring opencode.jsonc to connect to the remote Notchlet MCP backend and verifying the connection before using Notchlet-driven development skills.
4
+ ---
5
+
6
+ # Notchlet MCP Setup
7
+
8
+ Use this skill to configure OpenCode to connect to the existing Notchlet MCP backend so that `notchlet-platform`, `notchlet-plan`, `notchlet-implement`, `notchlet-review`, and `notchlet-deliver` can work against a live platform.
9
+
10
+ ## Prerequisites
11
+
12
+ - **OpenCode** installed
13
+ - A valid MCP bearer token for the Notchlet backend
14
+
15
+ ## Step 1: Configure opencode.jsonc
16
+
17
+ Edit your OpenCode configuration file (typically at `~/.config/opencode/opencode.jsonc` or `~/.opencode/opencode.jsonc`):
18
+
19
+ ```jsonc
20
+ {
21
+ "$schema": "https://opencode.ai/config.json",
22
+ "mcp": {
23
+ "notchlet": {
24
+ "type": "remote",
25
+ "url": "https://pg.mbintangr.com/mcp",
26
+ "oauth": false,
27
+ "headers": {
28
+ "Authorization": "Bearer your-mcp-token"
29
+ }
30
+ }
31
+ }
32
+ }
33
+ ```
34
+
35
+ Replace `your-mcp-token` with the MCP bearer token for the Notchlet backend. The URL points to the hosted platform at `pg.mbintangr.com`.
36
+
37
+ ## Step 2: Verify the connection
38
+
39
+ Quit and restart OpenCode so the authenticated MCP client can initialize and list the server's advertised tools. An unauthenticated HTTP `GET /mcp` is not a valid connection test: this server uses authenticated Streamable HTTP `POST` requests. If the Notchlet CLI is installed and the current directory is an initialized workspace, run `notchlet doctor` for authenticated capabilities and identity diagnostics.
40
+
41
+ ## Troubleshooting
42
+
43
+ - **MCP connection fails:** Verify the user-managed credential/configuration and restart OpenCode. Use an authenticated MCP initialization or `tools/list` request; do not use unauthenticated GET probes.
44
+ - **Skills not showing:** Quit and restart OpenCode completely after configuring `opencode.jsonc`.
45
+ - **No MCP token:** Ask the platform owner for a Notchlet MCP bearer token. Never put the token in a repository file, shell history, or command-line argument.
46
+
47
+ ## When to use
48
+
49
+ - Before using any other Notchlet skill for the first time on a new machine or project.
50
+ - When `notchlet_workspace_context` or `backlog_development_context` tools are unavailable.
51
+
52
+ ## When NOT to use
53
+
54
+ - When the authenticated MCP client already initializes and lists the needed tools, or `notchlet doctor` reports a healthy binding.
55
+ - When you only need to plan, implement, or deliver — use the individual skill instead.
56
+
57
+ ## Related skills
58
+
59
+ - `notchlet-platform` — discover products and resolve backlog items (requires MCP connection)
60
+ - `notchlet-super` — orchestrates the full cycle including MCP setup