@infinitedusky/indusk-mcp 0.1.0

package/skills/verify.md

@@ -0,0 +1,138 @@
+---
+name: verify
+description: Gate work execution with automated checks (type check, lint, test, build). Shape impl documents to include progressive per-phase verification with specific runnable commands.
+---
+
+You know how to verify that code changes actually work.
+
+## What Verify Does
+
+Verify has two roles:
+
+1. **Shape how impls are written** — every impl phase must have a Verification section with specific, runnable commands that prove the phase works. Not "verify it works" — actual commands with expected output.
+2. **Gate work execution** — when the work skill executes an impl item, verify defines what checks run and in what order before the checkbox gets checked.
+
+## Role 1: Shaping Impl Documents
+
+When writing an impl (via the plan skill), every phase should have a `#### Phase N Verification` section. The verification items must be:
+
+- **Specific commands** — `pnpm turbo test --filter=mcp`, not "run the tests"
+- **Expected output** — "1 test passing", "server returns 200 on /health", "tsc exits with 0"
+- **Progressive** — each phase proves itself before the next begins. Phase 2's verification should confirm Phase 1 still works too (regression)
+
+If a verification section says "verify it works" or "confirm everything is good" without a command, **the impl isn't ready**. Push back and ask: "what command proves this works?"
+
+### What checks does a phase need?
+
+Evaluate based on what changed:
+
+| Change type | Type check | Lint | Test | Build |
+|---|---|---|---|---|
+| TypeScript source | Yes | Yes | Yes (affected) | Only if shared package |
+| CSS/styles | No | No | No | No |
+| Test files | No | Yes | Yes (the test itself) | No |
+| Config files | Depends | No | Yes (smoke) | Yes |
+| Markdown/docs | No | No | No | No |
+| Package.json / deps | Yes | No | Yes (smoke) | Yes |
+| Build config | Yes | No | Yes (smoke) | Yes |
+
+When unsure, run the check. False negatives (missing a real error) are worse than slow verification.
+
+## Role 2: Gating Work Execution
+
+When the work skill is executing an impl and reaches verification items, run checks in this order (fastest first):
+
+### Check Order
+
+1. **Type check** — `tsc --noEmit` or `pnpm turbo typecheck --filter={app}` if wired
+   - Skip for: CSS changes, markdown changes, image changes
+   - Catches: structural errors, type mismatches, missing imports
+
+2. **Lint** — `biome check` (when code-quality-system is set up) or detected linter
+   - Skip for: test file changes, markdown changes, generated files
+   - Catches: style violations, common bug patterns, unused imports
+
+3. **Affected tests** — `pnpm turbo test --filter={app}`
+   - Skip for: markdown changes, config-only changes with no test files
+   - Catches: behavioral regressions, broken logic
+   - Run affected app's tests, not the full suite
+   - **Use the code graph to find affected tests** — query `analyze_code_relationships` for the changed file to discover which test files import or depend on it. Run those tests specifically rather than guessing.
+
+4. **Build** — `pnpm turbo build --filter={app}`
+   - Only for: shared package changes, build config changes
+   - Skip for: most application-level changes (dev server catches these)
+   - Catches: production build issues, missing exports
+
+### Verification Report
+
+After running checks, summarize what happened:
+
+```
+Verification Report:
+  Type check: passed (tsc --noEmit, 0 errors)
+  Lint: skipped (no linter configured yet)
+  Tests: passed (1 test in mcp)
+  Build: skipped (no shared package change)
+  Result: ALL PASSED — safe to check off
+```
+
+Or on failure:
+
+```
+Verification Report:
+  Type check: FAILED
+    src/index.ts:42 — Property 'foo' does not exist on type 'Bar'
+  Lint: passed
+  Tests: not run (type check failed first)
+  Build: not run
+  Result: BLOCKED — fix type error before proceeding
+```
+
+### Failure Loop
+
+When a check fails during work execution:
+
+```
+verify fails
+  → read the error output carefully
+  → fix the issue
+  → re-run ONLY the failing check (not all checks)
+  → if pass: continue to next check or check off the item
+  → if fail again: try a different fix
+  → max 3 attempts before flagging as blocker to the user
+```
+
+Do not silently retry indefinitely. Three attempts, then escalate. When escalating, include:
+- The error output from each attempt
+- What you tried to fix it
+- Why you think it's not a simple fix
+
+### Skip Logic
+
+Not every change needs every check. Before running verification, evaluate what files changed and skip checks that can't possibly fail:
+
+- **Only markdown changed** → skip everything
+- **Only CSS/styles changed** → skip type check and tests
+- **Only test files changed** → skip type check, run the tests
+- **TypeScript source changed** → run type check + tests, skip build unless shared package
+
+When skipping, note it in the verification report with the reason.
+
+## Commands Reference
+
+| Check | Command | When to use |
+|---|---|---|
+| Type check | `tsc --noEmit` | Any TypeScript change |
+| Lint | `pnpm check` | Any source file change |
+| Test (scoped) | `pnpm turbo test --filter={app}` | Any logic change |
+| Test (all) | `pnpm test` | Cross-package changes |
+| Build (scoped) | `pnpm turbo build --filter={app}` | Shared package or build config changes |
+
+## Important
+
+- **Watch file length and encapsulation.** If a file grows past ~200 lines, consider extracting functions or splitting into modules. Use `find_code` to check for duplicate logic before adding new functions. Code should be DRY — reuse existing utilities rather than reimplementing.
+- Verification items in impls must be specific runnable commands, not vague assertions
+- Progressive: each phase proves itself. Phase 2 shouldn't break Phase 1
+- Run checks fastest-first. Stop on first failure — no point linting if types don't compile
+- Three retries max on failure, then escalate to the user
+- When in doubt, run the check. Slow verification beats missed bugs.

package/skills/work.md

@@ -0,0 +1,104 @@
+---
+name: work
+description: Execute an implementation plan by working through its checklist. Reads the full plan context first, then works items in order, checking each off as it's completed.
+argument-hint: "[plan name or keyword]"
+---
+
+You know how to execute plans in this project.
+
+## How Work Works Here
+
+Implementation plans live in `planning/{plan-name}/impl.md` as checklists. Your job is to work through them methodically — one item at a time, in order, checking each off immediately after completing it.
+
+## What to Do When Asked to Work
+
+1. **Find the right plan.** Look in `planning/` for the plan matching what the user asked for. If they didn't specify, list all plans that have an impl with status `approved` or `in-progress` and ask which one.
+
+2. **Check prerequisites.** Before starting work:
+   - If the plan has an ADR, verify its status is `accepted`. If it's still `proposed`, warn the user: "The ADR hasn't been accepted yet — want to review it first, or proceed anyway?"
+   - If the brief has a `## Depends On` section, check that blocking plans are completed or far enough along.
+
+3. **Read the full plan context first.** Before touching any code, read everything in the plan folder — research, brief, ADR, impl. These contain the decisions and reasoning that should guide implementation choices. Don't just read the checklist.
+
+4. **Update status.** If the impl status is `approved`, change it to `in-progress`.
+
+5. **Work through the checklist in order.**
+   - Start from the first unchecked item (`- [ ]`)
+   - For each item:
+     a. **Query the code graph first** — before modifying a file, use `analyze_code_relationships` or `find_code` to understand its dependents. If the file is widely imported, flag the blast radius before proceeding.
+     b. **Check for existing code** — before writing new functions, use `find_code` to search for functions that already do what you need. Reuse and extend existing code rather than duplicating. Stay DRY.
+     c. Read the relevant source files
+     d. Implement the change
+     d. Immediately edit impl.md to check the item off (`- [ ]` → `- [x]`)
+     e. Move to the next item
+   - Do NOT skip ahead or work out of order unless there's a dependency reason
+   - Do NOT batch checklist updates — check each off as soon as it's done
+
+6. **Handle blockers.** If you can't complete an item:
+   - Add a note to impl.md under the item explaining the blocker
+   - Move to the next item if possible
+   - Flag the blocker to the user
+
+7. **Add discovered work.** If you find something that needs doing that isn't in the checklist:
+   - Add it as a new item in the appropriate phase
+   - Then do it and check it off
+
+8. **Per-phase completion order.** Each phase has up to four types of items. Complete them in this order:
+
+   **Implementation items** → build the thing
+   **Verification items** → prove it works (tests, type checks, commands)
+   **Context items** → capture what changed (concrete CLAUDE.md edits)
+   **Document items** → write or update docs pages (see document skill)
+
+   A phase is not complete until all four are done. Do not advance to the next phase with unchecked verification, context, or document items.
+
+9. **Verification items.** The Verification section requires proof, not assumption. See the verify skill for full guidance.
+   - Run checks in order: type check → lint → affected tests → build. Skip checks that don't apply (see verify skill's skip logic table).
+   - Run commands and capture output — verification items must be specific runnable commands, not "verify it works"
+   - If a check fails: read the error, fix it, re-run only the failing check. Max 3 attempts before flagging as a blocker to the user.
+   - Check items off only when actually verified, not assumed
+
+10. **Context items.** The Context section specifies concrete CLAUDE.md edits:
+    - Each item is a specific edit: "Add to Architecture: ...", "Add to Conventions: ...", etc.
+    - Make the edit to CLAUDE.md, then check the item off
+    - If a phase has no context items, that's fine — not every phase changes project context
+
+11. **Document items.** The Document section specifies docs pages to write or update:
+    - Each item targets a specific page in `apps/indusk-docs/src/`
+    - See the document skill for guidance on what to document, where, and how to use Mermaid diagrams
+    - If a phase has no document items, that's fine — not every phase produces user-facing documentation
+
+12. **Phase transitions.** When all items in a phase (implementation + verification + context + document) are checked, note it and move to the next phase.
+
+13. **Completion.** When all phases are checked:
+    - Update impl status to `completed`
+    - Summarize what was done
+    - If this plan included an ADR, confirm CLAUDE.md's Key Decisions was updated
+    - Let the user know the plan is ready for a retrospective if they want one (`/plan {name}` will pick up at the retrospective stage)
+
+## Corrections and Context Learning
+
+When you are corrected mid-work — the user says "no, not that way" or "don't do X, do Y" — suggest capturing it with `context learn`:
+
+> "Should I capture this? `/context learn 'use pnpm ce, not npx — the skill doc specifies pnpm'`"
+
+Don't wait to be told. Corrections are the most valuable source of project knowledge.
+
+## Commits
+
+Commit at natural boundaries — typically at the end of a phase or when the context changes. Follow the monorepo rule: commits should be siloed between different contexts (what would be separate repos).
+
+Don't commit after every single checklist item — that's too granular. Don't wait until the entire plan is done — that's too coarse. A phase is usually the right unit.
+
+## Cross-Plan Impact
+
+If your work changes something referenced by another plan (e.g., a schema field, a function signature, a contract interface), update that plan's impl or notes to reflect the change. Plans should never reference stale information.
+
+## Important
+
+- The impl doc is the source of truth for progress. Anyone should be able to read it and know exactly what's done and what's left.
+- Always read the research, brief, and ADR before starting. They contain context that matters.
+- Check items off one at a time, immediately. The checklist should always reflect reality.
+- Explain what you're doing and why as you work through items.
+- **Before touching shared code, query the graph to understand blast radius.** Use `analyze_code_relationships` to see what depends on a file before modifying it.
+- The user's input is: $ARGUMENTS

package/templates/CLAUDE.md

@@ -0,0 +1,25 @@
+# {Project Name} — Project Context
+
+## What This Is
+
+{1-2 sentences: what the project is and who it's for}
+
+## Architecture
+
+{Directory tree, key technologies, how things connect.}
+
+## Conventions
+
+(None yet — will be populated as the project develops)
+
+## Key Decisions
+
+(None yet — will be populated as ADRs are accepted)
+
+## Known Gotchas
+
+(None yet — will be populated as the agent makes mistakes)
+
+## Current State
+
+Project initialized with InDusk dev system.

package/templates/biome.template.json

@@ -0,0 +1,36 @@
+{
+	"$schema": "https://biomejs.dev/schemas/2.4.8/schema.json",
+	"vcs": {
+		"enabled": true,
+		"clientKind": "git",
+		"useIgnoreFile": true
+	},
+	"formatter": {
+		"enabled": true,
+		"indentStyle": "tab",
+		"lineWidth": 100
+	},
+	"linter": {
+		"enabled": true,
+		"rules": {
+			"recommended": true,
+			"correctness": {
+				"noUnusedVariables": "error",
+				"noUnusedImports": "error"
+			},
+			"suspicious": {
+				"noExplicitAny": "error",
+				"noDebugger": "error",
+				"noConsole": {
+					"level": "warn",
+					"options": {
+						"allow": ["warn", "error", "info"]
+					}
+				}
+			},
+			"style": {
+				"useConst": "error"
+			}
+		}
+	}
+}

package/templates/vscode-settings.json

@@ -0,0 +1,23 @@
+{
+	"editor.defaultFormatter": "biomejs.biome",
+	"editor.formatOnSave": true,
+	"eslint.enable": false,
+	"editor.codeActionsOnSave": {
+		"source.fixAll.biome": "explicit"
+	},
+	"[typescript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[typescriptreact]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[javascript]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[json]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	},
+	"[css]": {
+		"editor.defaultFormatter": "biomejs.biome"
+	}
+}