KNM VSCode extension (
|
| Command | Does |
|---|---|
| KNM: Sign in / Sign out | Stores a personal access token in ~/.knm/credentials (mode 600), or removes it |
| KNM: Select project | Binds the workspace to a project (.project-knm/context/config.json) |
| KNM: Sync | Reloads the project from the API |
| KNM: Open KNM web app | Opens the web app (also "Open in web app" per item) |
| KNM: Install project files (reinstall) | Adds or updates the skills, helper tools and settings in the workspace |
| KNM: Add feature(s) | /knm:import-features docs/features/add-features-<stamp>.md: typed text in, requirements to create and to change out |
| KNM: Define intent | /knm:define-intent: the gate for the other skills - creates docs/project/intent.md (purpose, ranked goals, non-goals, success) from the documents, asks you to validate it and to commit it |
| KNM: Import features | /knm:import-features: creates features, decisions and requirements from the context documents |
| KNM: Create walkthrough | /knm:create-walkthrough: clickable mock walkthrough with a gap list |
| KNM: Create DB design | /knm:create-db-design: db_design_tables.csv and db_design.md |
| Implement DB design (skill, no button yet) | /knm:implement-db-design: asks where db_design.md is, writes ORM models and a migration, applies it to the target DB |
| KNM: Validate context | Opens the Context panel and checks docs/project/context.md |
| KNM: Apply scaffolding plan | Applies a saved plan (SCF-xxxx); needs Claude Code and a clean git tree |
Skills and tools: shipped inside the extension
Skills, helper tools and the module pack live in plugin/ (a Claude Code plugin named knm) and are not copied into workspaces. Run them as /knm:<skill>, for example /knm:add-requirement DEC-009. On first start the extension asks once to set the Claude Code user setting claudeCode.claudeProcessWrapper to plugin/bin/claude-wrapper.sh, which starts Claude with --plugin-dir; later versions update the path silently. On Windows (a .cmd wrapper cannot be started, EINVAL) the extension instead installs the plugin through the claude program bundled with the Claude Code extension (local marketplace knm-local, plugin/.claude-plugin/marketplace.json). KNM: Register skills with Claude Code asks again.
Each skill pre-allows node ${CLAUDE_PLUGIN_ROOT}/tools/*, so no per-project permission rule is needed.
What bootstrap still writes into the workspace (after a modal; Cancel writes nothing): .project-knm/context/config.json, two .gitignore lines and .claude/settings.json allow rules for git, Read and Edit under docs. Workspaces that hold the old copies (.claude/skills, .project-knm/tools, .project-knm/pack) get one offer to remove them; only files KNM wrote are removed.
Layout of plugin/: .claude-plugin/plugin.json, skills/ (source), tools/ (knm-api.js, knm-context.js built by esbuild.mjs; knm-module.js and walkthrough/), pack/ (built by app/tools/module-pack), bin/claude-wrapper.sh.
Develop
cd app && npm run build -w project-conductor
code --extensionDevelopmentPath=/Users/roopesh/projects/project_knm/app/apps/vscode <workspace folder>
Start the API (npm run dev -w @knm/api, port 8787) and the web app (port 5190), create a personal access token in the web Settings page. Settings: knm.apiBaseUrl (default the deployed function URL), knm.webAppUrl (default https://knm-om.web.app).
Tests: npm test -w project-conductor; against a fresh local API add KNM_TEST_API=http://localhost:8788 (it mutates the seed, use a new file database each run). Package: npm run package -w project-conductor.
Code layout
src/ is plain TS bundled by esbuild into dist/extension.js. Pure modules (no vscode import, unit tested): credentials, config, api, data, treeModel, actions, detailHtml, claudePrompt, webUrl, cache, bootstrap, sync, contextDoc, homeHtml, contextHtml. VSCode-bound: extension, commands, store, tree, detail, home, status, notify, claudeSend, bootstrapUi, contextPanel, contextFs, scaffoldApply, scaffoldApplyUi. files/ is what bootstrap copies into a workspace (only config.json); plugin/ is what Claude loads.
The knm-api helper
node .project-knm/tools/knm-api.js <METHOD> /api/... [--json '<body>' | --file f.json | --stdin] [--query k=v ...], upload --entity-type T --entity-id ID --key K --file f, get <decision|requirement|workitem|test> <id> (looks the id up in your projects and adds projectId), whoami. Built from src/tools/knm-api.ts by npm run build (committed). No dependencies, Node >= 18. stdout is only the JSON data; failures are one line on stderr with the status and API message, exit 1; the token is never printed.
- Authentication: reads
~/.knm/credentials, falls back toapiBaseUrlin.project-knm/context/config.json, sendsAuthorization: Bearer. 401/403 or no credentials: "Run KNM: Sign in in VSCode".KNM_CREDENTIALS=<file>overrides the path (tests). - Request bodies are written to
.knm/tmp/(gitignored) and passed with--file: Claude Code's shell check rejects braces with quotes in a command. A small--json '{"a":1}'is fine. - Allow rules written to
.claude/settings.json:Bash(node .project-knm/tools/knm-api.js:*),Read,Edit(/docs/**),Edit(/.project-knm/**),Edit(/.knm/**). Claude Code ignores them until the workspace is trusted; headless runs pass--allowedTools. - Skill files and the helper carry
knm-managed: v1 version: N. - Tests:
test/knmApi.test.ts,test/bootstrapSkills.test.ts,test/skillsLint.test.ts(no curl, only the helper, every route exists in the contract).
Scaffolding
KNM: Apply scaffolding plan applies a saved plan with the bundled headless claude and the implement-scaffolding skill (see new_docs/screens/scaffold/design.md section 7). Needs the Claude Code extension and a clean git tree.
Manual checklist (about 15 minutes)
- Open a folder with no
.project-knm. A modal lists.project-knm/context/config.jsonand the two.gitignorelines. Cancel it: nothing is written. RunKNM: Install project files (reinstall), press Add files: files appear; run it again: "already in place". - Status bar shows
KNM: signed out; the KNM activity bar view shows the welcome buttons. KNM: Sign in, paste a bad token: readable error. Paste a good token: "signed in",~/.knm/credentialsexists with mode 600.- The project quick pick opens; choose a project.
.project-knm/context/config.jsonhas the projectId; status bar shows the project name and "synced hh:mm". - The tree shows feature > decision > requirement > work item and test,
ID title, with status text. Gated rows show a lock and "waiting on "..claude/requirements.jsonexists and is in.gitignore. - The activity bar badge equals the number of open gates (create questions on a requirement in the web app, press Sync: it goes up).
- Click a decision with no requirement: a tab opens with fields, parent link (click it), children list (click one) and
Create Requirement (AI)showing/knm:add-requirement <id>. - Press it: the Claude panel opens with the command prefilled and NOT submitted; a notification says to press Enter. (If the panel is empty, paste: the command is on the clipboard.)
- Click a gated requirement:
Answer questionsis disabled with a note. A decision with an open draft showsReview draft, disabled. - Click a finalized, not approved requirement:
Approve requirementis offered (a developer token gets "Only the product owner can do this"). Press it as the owner: notification, tree refreshes, tab now showsCreate Work Item (AI)andCreate Test (AI). - Click a finalized work item:
Preview (AI)andImplement (AI)with/knm:preview-workitem <id>and/knm:implement-workitem <id>. Open in web appopenshttp://localhost:5190/project/<id>/manage?f=...&r=....- Change something in the web app, press Sync in the tree title: the tree and any open tab update.
- Stop the API and press Sync: a readable "Cannot reach the KNM API" notification, status bar shows "sync failed".
KNM: Sign out: credentials file is gone, tree shows the sign-in welcome view, status bar says signed out.- Skills: in a workspace that still has the old skills, a warning offers "Back up and install"; accept:
SKILL.md.bakfiles appear and the new skills are in place..claude/settings.jsonhas the allow rules and other keys are intact. - In the Claude panel run
/knm:add-requirement DEC-009(workspace trusted): no permission prompts; it ends with "Draft saved. Review and approve it in KNM ..." and the requirement is NOT created. After approving the draft and answering its questions in KNM,/knm:finalize-requirement <REQ-id>writesreq.mdandmock.mdand the status becomesfinalized. - Sign out and run any skill: the answer says to run "KNM: Sign in".
- Home view: Requirements opens the Requirements screen (and back); there Define intent, Import features, Create walkthrough, Create DB design prefill their command in Claude and Validate context opens the Context panel.
- Add Feature(s): Create is disabled until text is typed; Create prefills
/knm:import-features docs/features/add-features-<stamp>.mdand the file holds the text. In Claude, the skill lists requirements to create and to change, asks which, and leaves finalized/approved ones alone.