@notchlet/cli 0.1.0 → 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 (26) hide show
  1. package/dist/cli-format.js +46 -0
  2. package/dist/cli-prompt.js +73 -0
  3. package/dist/cli.js +895 -258
  4. package/dist/guidance-install.js +58 -35
  5. package/guidance/aliases.json +27 -27
  6. package/guidance/generated/claude-code/notchlet-deliver/SKILL.md +94 -0
  7. package/guidance/generated/claude-code/notchlet-implement/SKILL.md +94 -0
  8. package/guidance/generated/claude-code/notchlet-init/SKILL.md +30 -0
  9. package/guidance/generated/claude-code/notchlet-mcp/SKILL.md +60 -0
  10. package/guidance/generated/claude-code/notchlet-plan/SKILL.md +100 -0
  11. package/guidance/generated/claude-code/notchlet-platform/SKILL.md +85 -0
  12. package/guidance/generated/claude-code/notchlet-review/SKILL.md +68 -0
  13. package/guidance/generated/claude-code/notchlet-super/SKILL.md +47 -47
  14. package/guidance/generated/compatibility.json +7 -0
  15. package/guidance/generated/manifest.json +127 -5
  16. package/guidance/generated/opencode/notchlet-deliver/SKILL.md +94 -0
  17. package/guidance/generated/opencode/notchlet-implement/SKILL.md +94 -0
  18. package/guidance/generated/opencode/notchlet-init/SKILL.md +30 -0
  19. package/guidance/generated/opencode/notchlet-mcp/SKILL.md +60 -0
  20. package/guidance/generated/opencode/notchlet-plan/SKILL.md +100 -0
  21. package/guidance/generated/opencode/notchlet-platform/SKILL.md +85 -0
  22. package/guidance/generated/opencode/notchlet-review/SKILL.md +68 -0
  23. package/guidance/generated/opencode/notchlet-super/SKILL.md +47 -47
  24. package/package.json +1 -1
  25. package/scripts/generate-guidance.mjs +56 -20
  26. package/guidance/notchlet-super.md +0 -47
@@ -0,0 +1,100 @@
1
+ ---
2
+ name: notchlet-plan
3
+ description: Use when creating or refining Notchlet epics, stories, and tasks from product documents, tickets, or existing workflows, with acceptance criteria, dependencies, estimates, and verified hierarchy. Produces a definition of ready before implementation begins.
4
+ ---
5
+
6
+ # Plan executable Notchlet backlogs
7
+
8
+ Native `backlog_development_context`, `backlog_comments_list`, `backlog_comment_add`, and `backlog_activities_list` are available on the connected `notchlet_*` host; discover live tool names and schemas and use targeted-read/comment fallbacks where needed. Context is bounded to 32 KiB serialized bytes, may include truncation metadata and scoped cursors, and should be expanded only as needed.
9
+
10
+ ## Entry criteria
11
+
12
+ - Product is resolved via `notchlet_workspace_context` or `notchlet_workspace_search`.
13
+ - Source documents (BRD/PRD/SRD/CUSTOM) or linked tickets are available and read.
14
+ - You know what outcome is requested; if not, ask before planning.
15
+
16
+ ## Discover scope
17
+
18
+ 1. Resolve the product from live workspace context. Read existing backlog/search results to avoid duplicates. Prefer refining an existing item when it covers the same requested work.
19
+ 2. Read relevant BRD/PRD/SRD or CUSTOM documents and linked tickets. For migrations, inspect actual source workflows and code callers before claiming detailed coverage.
20
+ 3. Identify deliverables, exclusions, dependencies, and acceptance criteria. Never substitute generic migration titles for inspected behavior.
21
+ 4. Before decomposing an epic or story, inspect its current children, reuse/update matching existing children, and create only missing work. Do not duplicate already represented tasks.
22
+
23
+ ## Risks and blockers
24
+
25
+ - Identify upstream dependencies (other items, teams, or external services) that must complete first.
26
+ - Flag items that cannot start until a dependent item reaches `DONE`.
27
+ - Mark items with uncertain requirements as needing clarification before implementation.
28
+
29
+ ## Decompose proportionately
30
+
31
+ - **Epic:** outcome and measurable completion conditions across the initiative.
32
+ - **Story:** a coherent user/system capability that can be verified independently. Include acceptance criteria and dependency titles/IDs.
33
+ - **Task:** actionable implementation or verification work with concrete scope, expected artifacts, and a check demonstrating completion.
34
+ - Keep planning lightweight. For a small code change, use the existing item description with a concise outcome and acceptance checks; do not require OpenSpec artifacts, create a proposal/design/spec-document hierarchy, or introduce a new spec/change-management system. Hosted OpenCode is not a prerequisite.
35
+ - Keep an evolving short approach in the description or a comment. Do not replace user-authored requirements with progress logs.
36
+ - Avoid overlapping tasks that implement the same runtime/provider/configuration behavior twice. Include frontend/caller changes, data implications, and release work when required by the source behavior.
37
+ - Estimate only when useful. Label estimates provisional. Treat story estimates and task estimates as alternative rollups; never add both into one total.
38
+ - Do not infer assignments, due dates, or urgency without requirements.
39
+
40
+ ## Definition of ready (before implementation)
41
+
42
+ A story or task is ready for `notchlet-implement` only when:
43
+
44
+ - [ ] Acceptance criteria are written and measurable (given/when/then or equivalent).
45
+ - [ ] Dependencies are listed with existing item titles and numeric IDs, or marked "none".
46
+ - [ ] Scope is specific: capability, route, or component is named.
47
+ - [ ] Verification criteria are defined (what test or evidence proves completion).
48
+ - [ ] No unresolved blocking dependency remains.
49
+
50
+ Description template:
51
+
52
+ ```markdown
53
+ ## Outcome
54
+ <observable result and source requirement>
55
+
56
+ ## Scope
57
+ - <specific capability, route, or component>
58
+
59
+ ## Acceptance criteria
60
+ - <given/when/then or measurable check>
61
+
62
+ ## Dependencies
63
+ - <existing item title and numeric ID, or none>
64
+
65
+ ## Verification
66
+ - <test/evidence required>
67
+ ```
68
+
69
+ ## Persist and verify
70
+
71
+ 1. Create the epic, then stories, then tasks **sequentially**, capturing each returned numeric ID for `parentId`. Do not guess key sequences or rely on display keys being unique.
72
+ 2. Check for successful writes before retrying errors. Keep track of partial creation so retries do not duplicate items.
73
+ 3. Read the root item after creation and verify child counts, types, product, parent links, descriptions, and estimates. If the hierarchy is truncated, fetch children individually.
74
+ 4. Report verified totals and a compact hierarchy. Report service anomalies explicitly; do not claim keys/parents were repaired using unsupported operations.
75
+
76
+ For existing work, fetch the latest description before editing and preserve its requirements, evidence, and user-authored content. Pass `expectedDescriptionRevision` on description updates when the live schema supports it; reread and reconcile conflicts. Prefer explicit create operations over batch generation unless the batch payload contract is established.
77
+
78
+ ## Exit criteria
79
+
80
+ - All planned items have a definition of ready met.
81
+ - Hierarchy (epic → stories → tasks) is verified in Notchlet.
82
+ - Items are in the correct status (typically `TODO` or `IN_PROGRESS` for the first executable item).
83
+
84
+ ## When NOT to use
85
+
86
+ - When you only need to implement an already-planned item — use `notchlet-implement` instead.
87
+ - When you only need to review or deliver completed work — use `notchlet-review` or `notchlet-deliver` instead.
88
+ - When you need to set up the MCP connection first — use `notchlet-mcp` instead.
89
+
90
+ ## Related skills
91
+
92
+ - `notchlet-platform` — resolve the product and backlog item before planning
93
+ - `notchlet-implement` — implement tasks after planning establishes Definition of Ready
94
+ - `notchlet-super` — orchestrates the full cycle including planning
95
+
96
+ ## When to use
97
+
98
+ - Creating or refining epics, stories, and tasks.
99
+ - Before implementation begins, to establish a definition of ready.
100
+ - When scope, dependencies, or acceptance criteria need clarification.
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: notchlet-platform
3
+ description: Use when discovering the Notchlet platform, resolving products and backlog items, or understanding available MCP operations and limitations before planning, implementing, or delivering work.
4
+ ---
5
+
6
+ # Notchlet Platform Discovery
7
+
8
+ Use this skill first to understand what is available on the connected Notchlet platform before planning, implementing, or delivering work.
9
+
10
+ ## Discover the platform
11
+
12
+ 1. Read available MCP operations and limitations from the connected `notchlet_*` host. Discover live tool names and schemas; never fabricate tool calls.
13
+ 2. Use `notchlet_workspace_context` to list accessible organizations, teams, and products.
14
+ 3. Use `notchlet_workspace_search` to search products, documents, backlog items, and tickets by query.
15
+ 4. Resolve a product by ID or name before creating or refining backlog items under it.
16
+
17
+ ## Resolve backlog items
18
+
19
+ 1. Resolve a backlog item by numeric ID, or search its title/key and fetch it with `notchlet_backlog_get`.
20
+ 2. If keys are duplicated, distinguish by title, product, parent, and numeric ID. Ask only if still ambiguous.
21
+ 3. Read the item's description, acceptance criteria, children, assignments, and linked documents before acting.
22
+ 4. Use `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 include 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.
23
+
24
+ ### Example MCP tool invocations
25
+
26
+ ```json
27
+ // Resolve workspace context to find products
28
+ {
29
+ "tool": "notchlet_workspace_context"
30
+ }
31
+
32
+ // Fetch a backlog item by ID
33
+ {
34
+ "tool": "notchlet_backlog_get",
35
+ "arguments": { "id": 42 }
36
+ }
37
+
38
+ // Get bounded development context for an item
39
+ {
40
+ "tool": "backlog_development_context",
41
+ "arguments": { "itemId": 42, "limit": 10 }
42
+ }
43
+ ```
44
+
45
+
46
+ ## Conflict detection
47
+
48
+ - Before editing a description, read the latest version and note its `descriptionRevision`.
49
+ - If another agent or user has modified the item since you last read it, reconcile conflicts before writing: reread, merge changes, and pass the latest `expectedDescriptionRevision`.
50
+ - Never overwrite another user's edits without reconciling first.
51
+
52
+ ## Comments and activities
53
+
54
+ 1. Use `backlog_comments_list` / `backlog_comment_add` to read or record checkpoint comments on a backlog item.
55
+ 2. Use `backlog_activities_list` to read the activity history for a backlog item.
56
+
57
+ ## Offline / degraded mode
58
+
59
+ If the Notchlet MCP host (`pg.mbintangr.com`) is unreachable:
60
+
61
+ - Continue repository work that does not depend on missing requirements (coding, testing, local verification).
62
+ - Do not claim remote updates succeeded.
63
+ - Record your intended changes locally so they can be synced when the platform returns.
64
+ - Report the synchronization blocker; do not silently proceed with status changes that cannot be verified on the platform.
65
+
66
+ ## When to use
67
+
68
+ - Before any planning, implementation, or delivery: resolve the product and item first.
69
+ - When you need to understand what MCP tools are available on the connected Notchlet host.
70
+ - When you need to search across products, documents, backlog items, or tickets.
71
+ - When you need bounded context for one backlog item without dumping the full backlog.
72
+ - When you suspect a conflict on an item's description or status.
73
+
74
+ ## When NOT to use
75
+
76
+ - When the product and backlog item are already resolved and you only need to plan, implement, or deliver — use the individual skill instead.
77
+ - When you need to configure the MCP connection itself — use `notchlet-mcp` first.
78
+
79
+ ## Related skills
80
+
81
+ - `notchlet-mcp` — configure MCP connection before using platform tools
82
+ - `notchlet-plan` — plan tasks after resolving the backlog item
83
+ - `notchlet-super` — orchestrates the full cycle including platform discovery
84
+
85
+ This skill is the entry point to Notchlet-driven development; `notchlet-plan`, `notchlet-implement`, `notchlet-review`, and `notchlet-deliver` assume the platform and item have already been resolved.
@@ -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
@@ -1,47 +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. The local CLI manages local `.notchlet` change records and synchronized snapshots; MCP tools access authorized server state. Keep those state boundaries clear. 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 the checkout, tests, docs, git state, and relevant bounded MCP context. Do not run `notchlet init`, create/convert a change, edit files, transition tasks, sync, checkpoint, or write backlog state. Exploration works without an initialized `.notchlet` workspace; for local state use `notchlet status` or `notchlet change list` only when useful (both report empty state when no workspace exists).
13
- - **Plan only (read-only unless asked to persist):** use `notchlet-plan` to clarify outcome, scope, assumptions, dependencies, risks, and verification criteria in the conversation. Planning does not require initialization, an epic→story→task hierarchy, or application/change-artifact writes. Existing server-side planning may use bounded read tools (`notchlet_workspace_context`, `notchlet_workspace_search`, `notchlet_backlog_get`, `notchlet_backlog_list`, `notchlet_backlog_development_context`, and `notchlet_document_list/get`); do not create/update items unless the user asks. `notchlet instructions <change> --action plan` is available only for an existing local change and is informational; it is not required for planning.
14
- - **Revise:** distinguish revising a proposed plan (keep it read-only unless persistence is requested) from revising an existing local change. For the latter, inspect it with `notchlet change show <id>`, `notchlet status <id>`, and `notchlet instructions <id> --action revise`; preserve stable IDs/progress, edit only requested artifacts, then run `notchlet validate <id>`. The `instructions` action itself is read-only.
15
- - **Implement:** first confirm scope, requirements, repository, branch, and user edits; read `notchlet status <id>` and `notchlet instructions <id> --action implement` when an existing change applies. Follow `notchlet-implement`; run only relevant project checks and record actual outcomes. Use `notchlet task start <task-id> --change <id> --revision <revision>` and `notchlet task complete <task-id> --change <id> --revision <revision>` for dependency/revision-checked local transitions; do not mark complete before evidence exists. `notchlet task update <change> <task> <status> <revision>` remains available for explicit transitions to any supported task state.
16
- - **Verify:** use `notchlet instructions <id> --action verify`, `notchlet validate <id>`, and actual repository test/check commands appropriate to the change. Record bounded results with `notchlet evidence record --change <id> --file <evidence.json>`; any `command` field is descriptive and never executed. Link required checks with their IDs in `checkIds`. A successful readiness validation is not a substitute for tests. Keep failed and unrun checks distinct; do not claim verification without observed results.
17
- - **Continue / resume:** locate current state with `notchlet status [<change>]`, `notchlet change list`, and, for a selected change, `notchlet change show <id>` plus `notchlet instructions <id> --action resume`. Continue only eligible work, preserve existing artifacts/user changes, and do not recreate valid plans or restart setup.
18
- - **Review:** use `notchlet-review`; distinguish a self-recorded check from independent human review.
19
- - **Deliver:** use `notchlet-deliver` after implementation, verification, and required review. `notchlet checkpoint --change <id> --name <name>` records a synchronized checkpoint; `notchlet sync status|push|pull --change <id>` inspects or explicitly synchronizes snapshots, and resolve only after reviewing divergence. Server delivery can be evaluated with `development_delivery_create` only when explicitly authorized and with its required idempotency/revision fields. A branch-linked item requires the exact linked PR/MR to be merged and approved before a `DONE` status request. Delivery evaluates existing provider state; it does not merge or deploy.
20
-
21
- ## Reuse current workspace and connection
22
-
23
- 1. Use the nearest initialized `.notchlet` workspace or the user's explicit `--workspace <path>` for change-oriented commands. Exploratory and conversation-only planning do not require one.
24
- 2. If there is no initialized workspace, local reads are side-effect free. Run `notchlet init` only when a requested local change workflow actually requires it and the user approves it; do not assume a separate bootstrap command exists. Never initialize just to explore or plan.
25
- 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.
26
- 4. Do not transfer numeric product IDs between servers. Rebind only after confirming the intended server/product/repository identity.
27
- 5. Fetch bounded context for the selected backlog item when one is relevant; never dump the entire product to find one item. Missing item/product identity is not a reason to turn an exploratory or local planning request into a backlog hierarchy.
28
- 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.
29
- 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.
30
-
31
- ## State-aware MCP tool calls
32
-
33
- 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:
34
-
35
- - `backlog_development_context({ itemId, section?, cursor?, knownFingerprint?, limit? })` for one bounded item context.
36
- - `development_changes_list({ productId?, limit?, cursor? })` and `development_change_get({ changeId })` to discover/read changes.
37
- - `development_instructions_get({ changeId, action, snapshotRevision?, context? })` for server-evaluated instructions tied to a synchronized revision; actions are `plan`, `revise`, `implement`, `verify`, and `resume` and require an existing authorized change.
38
- - `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.
39
-
40
- 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.
41
-
42
- ## Authorization and handoff
43
-
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.
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.
package/package.json CHANGED
@@ -1 +1 @@
1
- {"name":"@notchlet/cli","version":"0.1.0","type":"module","engines":{"node":">=22"},"bin":{"notchlet":"./dist/cli.js"},"files":["dist/cli.js","dist/auth.js","dist/integration.js","dist/guidance-install.js","dist/setup.js","guidance","scripts/generate-guidance.mjs"],"scripts":{"build":"tsc -p tsconfig.json","test":"npm run build && node --test dist/*.test.js","prepublishOnly":"npm test","guidance:generate":"node scripts/generate-guidance.mjs"},"dependencies":{"@modelcontextprotocol/sdk":"^1.32.2","@napi-rs/keyring":"^2.1.2","@notchlet/core":"^0.1.0"},"devDependencies":{"@types/node":"^22.15.0","typescript":"^5.8.3"}}
1
+ {"name":"@notchlet/cli","version":"0.2.0","type":"module","engines":{"node":">=22"},"bin":{"notchlet":"./dist/cli.js"},"files":["dist/cli.js","dist/auth.js","dist/cli-format.js","dist/cli-prompt.js","dist/guidance-install.js","dist/integration.js","dist/setup.js","guidance","scripts/generate-guidance.mjs"],"scripts":{"build":"tsc -p tsconfig.json","test":"npm run build && node --test dist/*.test.js","prepublishOnly":"npm test","guidance:generate":"node scripts/generate-guidance.mjs"},"dependencies":{"@modelcontextprotocol/sdk":"^1.32.2","@napi-rs/keyring":"^2.1.2","@notchlet/core":"^0.1.0"},"devDependencies":{"@types/node":"^22.15.0","typescript":"^5.8.3"}}
@@ -1,11 +1,13 @@
1
- import { mkdir, readFile, writeFile } from 'node:fs/promises';
1
+ import { readFile, readdir, stat, writeFile, mkdir } from 'node:fs/promises';
2
2
  import { createHash } from 'node:crypto';
3
3
  import path from 'node:path';
4
4
  import { fileURLToPath } from 'node:url';
5
5
 
6
6
  const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
7
- const repositoryRoot = path.resolve(packageRoot, '../..');
8
- const sourcePath = path.join(packageRoot, 'guidance', 'notchlet-super.md');
7
+ const repositoryRoot = path.resolve(packageRoot, '..');
8
+ const skillsRepoRoot = path.resolve(repositoryRoot, 'notchlet-skills');
9
+ const skillsSourceDir = path.join(skillsRepoRoot, 'skills');
10
+ const sourcePath = path.join(skillsSourceDir, 'notchlet-super', 'SKILL.md');
9
11
  const source = await readFile(sourcePath, 'utf8');
10
12
 
11
13
  const requiredCommands = [
@@ -23,7 +25,7 @@ for (const action of ['plan', 'revise', 'implement', 'verify', 'resume']) {
23
25
  if (!source.includes(`--action ${action}`)) throw new Error(`Canonical guidance does not reference its declared workflow action: ${action}`);
24
26
  }
25
27
 
26
- const skillLock = JSON.parse(await readFile(path.join(repositoryRoot, 'skills-lock.json'), 'utf8'));
28
+ const skillLock = JSON.parse(await readFile(path.join(skillsRepoRoot, 'skills-lock.json'), 'utf8'));
27
29
  const aliases = JSON.parse(await readFile(path.join(packageRoot, 'guidance', 'aliases.json'), 'utf8'));
28
30
  const requiredSkills = ['notchlet-mcp', 'notchlet-platform', 'notchlet-plan', 'notchlet-implement', 'notchlet-review', 'notchlet-deliver'];
29
31
  for (const skill of requiredSkills) {
@@ -35,9 +37,10 @@ for (const [legacy, migration] of Object.entries(aliases.aliases ?? {})) {
35
37
  for (const command of migration.commands ?? []) if (!cliSource.includes(command)) throw new Error(`Alias ${legacy} maps to an unsupported CLI command: ${command}`);
36
38
  }
37
39
 
40
+ const toolRoot = path.resolve(repositoryRoot, 'notchlet', 'notchlet-be', 'src', 'mcp', 'tools');
38
41
  const toolFiles = [
39
- path.join(repositoryRoot, 'product-guy-be', 'src', 'mcp', 'tools', 'lifecycle.tools.ts'),
40
- path.join(repositoryRoot, 'product-guy-be', 'src', 'mcp', 'tools', 'development.tools.ts'),
42
+ path.join(toolRoot, 'lifecycle.tools.ts'),
43
+ path.join(toolRoot, 'development.tools.ts'),
41
44
  ];
42
45
  const toolSources = await Promise.all(toolFiles.map(file => readFile(file, 'utf8')));
43
46
  const requiredTools = {
@@ -61,19 +64,52 @@ for (const action of ['plan', 'revise', 'implement', 'verify', 'resume']) {
61
64
  if (/notchlet-init|curl\s+[^\n]*\/mcp/i.test(source)) throw new Error('Canonical guidance contains a stale init or unauthenticated MCP GET assumption.');
62
65
  if (!/Explore \/ investigate \(read-only\)[\s\S]*?Do not run `notchlet init`/.test(source)) throw new Error('Explore guidance must explicitly be read-only and avoid initialization.');
63
66
  if (!/Plan only \(read-only unless asked to persist\)[\s\S]*?does not require initialization, an epic→story→task hierarchy, or application\/change-artifact writes/.test(source)) throw new Error('Planning guidance must be read-only by default and independent of initialization and backlog hierarchy.');
64
- const targets = [
65
- path.join(packageRoot, 'guidance', 'generated', 'opencode', 'notchlet-super', 'SKILL.md'),
66
- path.join(packageRoot, 'guidance', 'generated', 'claude-code', 'notchlet-super', 'SKILL.md'),
67
- ];
68
- const sourceHash = createHash('sha256').update(source).digest('hex');
69
- const generated = [];
70
- for (const target of targets) {
71
- await mkdir(path.dirname(target), { recursive: true });
72
- await writeFile(target, source, 'utf8');
73
- generated.push({ client: target.includes(`${path.sep}opencode${path.sep}`) ? 'opencode' : 'claude-code', path: path.relative(packageRoot, target).replace(/\\/g, '/'), sha256: sourceHash });
67
+
68
+ const clients = ['opencode', 'claude-code'];
69
+ const skillDirs = await readdir(skillsSourceDir);
70
+ const skillEntries = [];
71
+ for (const dir of skillDirs) {
72
+ const skillFile = path.join(skillsSourceDir, dir, 'SKILL.md');
73
+ let st;
74
+ try { st = await stat(skillFile); } catch { st = null; }
75
+ if (!st || !st.isFile()) continue;
76
+ const content = await readFile(skillFile, 'utf8');
77
+ skillEntries.push({ name: dir, content, hash: createHash('sha256').update(content).digest('hex') });
74
78
  }
79
+ // Use local guidance/notchlet-super.md as canonical source for notchlet-super skill
80
+ const localSuperSource = await readFile(sourcePath, 'utf8');
81
+ for (const entry of skillEntries) {
82
+ if (entry.name === 'notchlet-super') {
83
+ entry.content = localSuperSource;
84
+ entry.hash = createHash('sha256').update(localSuperSource).digest('hex');
85
+ }
86
+ }
87
+
88
+ const targets = [];
89
+ for (const client of clients) {
90
+ for (const entry of skillEntries) {
91
+ const target = path.join(packageRoot, 'guidance', 'generated', client, entry.name, 'SKILL.md');
92
+ await mkdir(path.dirname(target), { recursive: true });
93
+ await writeFile(target, entry.content, 'utf8');
94
+ targets.push({ client, path: path.relative(packageRoot, target).replace(/\\/g, '/'), sha256: entry.hash, skill: entry.name });
95
+ }
96
+ }
97
+
75
98
  const packageManifest = JSON.parse(await readFile(path.join(packageRoot, 'package.json'), 'utf8'));
76
- const manifest = { manifestVersion: 1, source: 'guidance/notchlet-super.md', sourceVersion: packageManifest.version, sourceSha256: sourceHash, targets: generated };
77
- await writeFile(path.join(packageRoot, 'guidance', 'generated', 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
78
- await writeFile(path.join(packageRoot, 'guidance', 'generated', 'compatibility.json'), `${JSON.stringify({ skills: skillLock.skills, aliases: aliases.aliases, source: aliases.source }, null, 2)}\n`, 'utf8');
79
- console.log(`Generated ${targets.length} state-aware notchlet-super outputs from ${path.relative(repositoryRoot, sourcePath)}.`);
99
+ const skillsMap = {};
100
+ for (const e of skillEntries) skillsMap[e.name] = { hash: e.hash, path: `skills/${e.name}/SKILL.md` };
101
+ const manifest = {
102
+ manifestVersion: 1,
103
+ source: 'skills/notchlet-super/SKILL.md',
104
+ sourceVersion: packageManifest.version,
105
+ sourceSha256: createHash('sha256').update(source).digest('hex'),
106
+ skillsRepo: skillsRepoRoot,
107
+ skillCount: skillEntries.length,
108
+ skills: skillsMap,
109
+ targets,
110
+ };
111
+ const manifestDir = path.join(packageRoot, 'guidance', 'generated');
112
+ await mkdir(manifestDir, { recursive: true });
113
+ await writeFile(path.join(manifestDir, 'manifest.json'), `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
114
+ await writeFile(path.join(manifestDir, 'compatibility.json'), `${JSON.stringify({ skills: skillLock.skills, aliases: aliases.aliases, source: aliases.source }, null, 2)}\n`, 'utf8');
115
+ console.log(`Synced ${targets.length} skill outputs (${skillEntries.length} skills x ${clients.length} clients) from ${skillsRepoRoot} to guidance/generated/.`);
@@ -1,47 +0,0 @@
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. The local CLI manages local `.notchlet` change records and synchronized snapshots; MCP tools access authorized server state. Keep those state boundaries clear. 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 the checkout, tests, docs, git state, and relevant bounded MCP context. Do not run `notchlet init`, create/convert a change, edit files, transition tasks, sync, checkpoint, or write backlog state. Exploration works without an initialized `.notchlet` workspace; for local state use `notchlet status` or `notchlet change list` only when useful (both report empty state when no workspace exists).
13
- - **Plan only (read-only unless asked to persist):** use `notchlet-plan` to clarify outcome, scope, assumptions, dependencies, risks, and verification criteria in the conversation. Planning does not require initialization, an epic→story→task hierarchy, or application/change-artifact writes. Existing server-side planning may use bounded read tools (`notchlet_workspace_context`, `notchlet_workspace_search`, `notchlet_backlog_get`, `notchlet_backlog_list`, `notchlet_backlog_development_context`, and `notchlet_document_list/get`); do not create/update items unless the user asks. `notchlet instructions <change> --action plan` is available only for an existing local change and is informational; it is not required for planning.
14
- - **Revise:** distinguish revising a proposed plan (keep it read-only unless persistence is requested) from revising an existing local change. For the latter, inspect it with `notchlet change show <id>`, `notchlet status <id>`, and `notchlet instructions <id> --action revise`; preserve stable IDs/progress, edit only requested artifacts, then run `notchlet validate <id>`. The `instructions` action itself is read-only.
15
- - **Implement:** first confirm scope, requirements, repository, branch, and user edits; read `notchlet status <id>` and `notchlet instructions <id> --action implement` when an existing change applies. Follow `notchlet-implement`; run only relevant project checks and record actual outcomes. Use `notchlet task start <task-id> --change <id> --revision <revision>` and `notchlet task complete <task-id> --change <id> --revision <revision>` for dependency/revision-checked local transitions; do not mark complete before evidence exists. `notchlet task update <change> <task> <status> <revision>` remains available for explicit transitions to any supported task state.
16
- - **Verify:** use `notchlet instructions <id> --action verify`, `notchlet validate <id>`, and actual repository test/check commands appropriate to the change. Record bounded results with `notchlet evidence record --change <id> --file <evidence.json>`; any `command` field is descriptive and never executed. Link required checks with their IDs in `checkIds`. A successful readiness validation is not a substitute for tests. Keep failed and unrun checks distinct; do not claim verification without observed results.
17
- - **Continue / resume:** locate current state with `notchlet status [<change>]`, `notchlet change list`, and, for a selected change, `notchlet change show <id>` plus `notchlet instructions <id> --action resume`. Continue only eligible work, preserve existing artifacts/user changes, and do not recreate valid plans or restart setup.
18
- - **Review:** use `notchlet-review`; distinguish a self-recorded check from independent human review.
19
- - **Deliver:** use `notchlet-deliver` after implementation, verification, and required review. `notchlet checkpoint --change <id> --name <name>` records a synchronized checkpoint; `notchlet sync status|push|pull --change <id>` inspects or explicitly synchronizes snapshots, and resolve only after reviewing divergence. Server delivery can be evaluated with `development_delivery_create` only when explicitly authorized and with its required idempotency/revision fields. A branch-linked item requires the exact linked PR/MR to be merged and approved before a `DONE` status request. Delivery evaluates existing provider state; it does not merge or deploy.
20
-
21
- ## Reuse current workspace and connection
22
-
23
- 1. Use the nearest initialized `.notchlet` workspace or the user's explicit `--workspace <path>` for change-oriented commands. Exploratory and conversation-only planning do not require one.
24
- 2. If there is no initialized workspace, local reads are side-effect free. Run `notchlet init` only when a requested local change workflow actually requires it and the user approves it; do not assume a separate bootstrap command exists. Never initialize just to explore or plan.
25
- 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.
26
- 4. Do not transfer numeric product IDs between servers. Rebind only after confirming the intended server/product/repository identity.
27
- 5. Fetch bounded context for the selected backlog item when one is relevant; never dump the entire product to find one item. Missing item/product identity is not a reason to turn an exploratory or local planning request into a backlog hierarchy.
28
- 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.
29
- 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.
30
-
31
- ## State-aware MCP tool calls
32
-
33
- 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:
34
-
35
- - `backlog_development_context({ itemId, section?, cursor?, knownFingerprint?, limit? })` for one bounded item context.
36
- - `development_changes_list({ productId?, limit?, cursor? })` and `development_change_get({ changeId })` to discover/read changes.
37
- - `development_instructions_get({ changeId, action, snapshotRevision?, context? })` for server-evaluated instructions tied to a synchronized revision; actions are `plan`, `revise`, `implement`, `verify`, and `resume` and require an existing authorized change.
38
- - `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.
39
-
40
- 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.
41
-
42
- ## Authorization and handoff
43
-
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.