@infinitedusky/indusk-mcp 0.7.2 → 0.8.5

package/hooks/check-gates.js

@@ -27,7 +27,34 @@ if (!filePath.endsWith("/impl.md") && !filePath.endsWith("\\impl.md")) {
 
 // Check for skip-gates escape hatch
 const newContent = toolInput.new_string ?? toolInput.content ?? "";
-if (newContent.includes("<!-- skip-gates -->")) {
+
+// Read gate policy from the impl file and settings
+function readGatePolicy() {
+	try {
+		const content = readFileSync(filePath, "utf-8");
+		const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
+		if (fmMatch) {
+			const policyMatch = fmMatch[1].match(/gate_policy:\s*(strict|ask|auto)/);
+			if (policyMatch) return policyMatch[1];
+		}
+	} catch {
+		// ignore
+	}
+	// Check project settings
+	try {
+		const settingsPath = `${event.cwd}/.claude/settings.json`;
+		const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+		if (settings.indusk?.gate_policy) return settings.indusk.gate_policy;
+	} catch {
+		// ignore
+	}
+	return "ask"; // default
+}
+
+const gatePolicy = readGatePolicy();
+
+// In strict mode, skip-gates escape hatch is not allowed
+if (newContent.includes("<!-- skip-gates -->") && gatePolicy !== "strict") {
 	process.exit(0);
 }
 
@@ -80,6 +107,22 @@ if (event.tool_name === "Edit" && oldContent) {
 	process.exit(0);
 }
 
+// Detect workflow type from content frontmatter
+function detectWorkflow(content) {
+	const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
+	const fm = fmMatch ? fmMatch[1] : "";
+	const m = fm.match(/workflow:\s*(bugfix|refactor|feature|spike)/);
+	return m ? m[1] : "feature";
+}
+
+// Which gate types are required per workflow
+const WORKFLOW_GATES = {
+	feature: ["verification", "context", "document"],
+	refactor: ["verification", "context", "document"],
+	bugfix: ["verification", "document"],
+	spike: [],
+};
+
 // Parse phases from the NEW content (after edit) and OLD content (before edit)
 function parsePhases(content) {
 	// Strip frontmatter
@@ -131,6 +174,8 @@ function parsePhases(content) {
 	return phases;
 }
 
+const workflow = detectWorkflow(fullContent);
+const requiredGates = WORKFLOW_GATES[workflow] || WORKFLOW_GATES.feature;
 const oldPhases = parsePhases(fullContent);
 const newPhases = parsePhases(newFullContent);
 
@@ -171,15 +216,24 @@ for (const item of newlyChecked) {
 	for (const phase of oldPhases) {
 		if (phase.number >= item.phase) break;
 
+		const isOverridden = (text) =>
+			gatePolicy !== "strict" &&
+			(text.includes("(none needed)") ||
+				text.includes("(not applicable)") ||
+				text.includes("skip-reason:"));
+
 		const uncheckedGates = phase.items.filter(
-			(i) =>
-				!i.checked && (i.gate === "verification" || i.gate === "context" || i.gate === "document"),
+			(i) => !i.checked && !isOverridden(i.text) && requiredGates.includes(i.gate),
 		);
 
 		if (uncheckedGates.length > 0) {
 			const missing = uncheckedGates.map((i) => `  [${i.gate}] ${i.text}`).join("\n");
+			const skipHint =
+				gatePolicy === "strict"
+					? "Gate policy is 'strict' — no overrides allowed.\n"
+					: "To skip a gate item, ask the user first, then mark with (none needed) or skip-reason: {why}\n";
 			process.stderr.write(
-				`Phase ${item.phase} blocked: complete Phase ${phase.number} gates first:\n${missing}\n`,
+				`Phase ${item.phase} blocked (policy: ${gatePolicy}): complete Phase ${phase.number} gates first:\n${missing}\n${skipHint}`,
 			);
 			process.exit(2);
 		}

package/hooks/validate-impl-structure.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse hook: validates that impl phases have all four gate sections.
+ *
+ * Every phase must have: implementation items, Verification, Context, Document.
+ * Sections can opt out with (none needed), (not applicable), or skip-reason: {why}.
+ *
+ * Exit 0 = allow the edit
+ * Exit 2 = block the edit (stderr sent to agent as feedback)
+ */
+
+import { readFileSync } from "node:fs";
+
+// Read hook input from stdin
+let input = "";
+for await (const chunk of process.stdin) {
+	input += chunk;
+}
+
+const event = JSON.parse(input);
+const toolInput = event.tool_input ?? {};
+const filePath = toolInput.file_path ?? "";
+
+// Fast path: not an impl.md file
+if (!filePath.endsWith("/impl.md") && !filePath.endsWith("\\impl.md")) {
+	process.exit(0);
+}
+
+// Check for skip-gates escape hatch
+const newContent = toolInput.new_string ?? toolInput.content ?? "";
+
+// Read gate policy
+function readGatePolicy() {
+	// Check the content being written for a gate_policy in frontmatter
+	const contentToCheck = toolInput.content ?? toolInput.new_string ?? "";
+	const fmMatch = contentToCheck.match(/gate_policy:\s*(strict|ask|auto)/);
+	if (fmMatch) return fmMatch[1];
+	// Check existing file
+	try {
+		const existing = readFileSync(filePath, "utf-8");
+		const existingFm = existing.match(/^---\n([\s\S]*?)\n---\n/);
+		if (existingFm) {
+			const m = existingFm[1].match(/gate_policy:\s*(strict|ask|auto)/);
+			if (m) return m[1];
+		}
+	} catch {
+		// ignore
+	}
+	// Check project settings
+	try {
+		const settingsPath = `${event.cwd}/.claude/settings.json`;
+		const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+		if (settings.indusk?.gate_policy) return settings.indusk.gate_policy;
+	} catch {
+		// ignore
+	}
+	return "ask";
+}
+
+const gatePolicy = readGatePolicy();
+
+if (newContent.includes("<!-- skip-gates -->") && gatePolicy !== "strict") {
+	process.exit(0);
+}
+
+// Determine the full new content after edit
+let newFullContent;
+if (event.tool_name === "Edit" && toolInput.old_string) {
+	try {
+		const diskContent = readFileSync(filePath, "utf-8");
+		newFullContent = diskContent.replace(toolInput.old_string, newContent);
+	} catch {
+		// File doesn't exist yet — will be created by Write
+		newFullContent = newContent;
+	}
+} else if (event.tool_name === "Write") {
+	newFullContent = toolInput.content ?? "";
+} else {
+	process.exit(0);
+}
+
+// Only validate if this edit is adding/modifying phase structure
+// Check if the edit contains phase headers
+const editContent = toolInput.new_string ?? toolInput.content ?? "";
+const hasPhaseHeader = /###\s+Phase\s+\d+/.test(editContent);
+const hasChecklistItem = /- \[ \]/.test(editContent);
+
+// If the edit doesn't touch phase structure, allow it
+if (!hasPhaseHeader && !hasChecklistItem) {
+	process.exit(0);
+}
+
+// Parse frontmatter to detect workflow type
+const fmMatch = newFullContent.match(/^---\n([\s\S]*?)\n---\n/);
+const frontmatter = fmMatch ? fmMatch[1] : "";
+const body = fmMatch ? newFullContent.slice(fmMatch[0].length) : newFullContent;
+
+// Detect workflow type from frontmatter (workflow: bugfix|refactor|feature)
+// or infer from plan structure
+const workflowMatch = frontmatter.match(/workflow:\s*(bugfix|refactor|feature|spike)/);
+const workflow = workflowMatch ? workflowMatch[1] : "feature";
+
+// Different workflows have different requirements
+const requirements = {
+	feature: { verification: true, context: true, document: true },
+	refactor: { verification: true, context: true, document: true },
+	bugfix: { verification: true, context: false, document: true },
+	spike: { verification: false, context: false, document: false },
+}[workflow];
+const lines = body.split("\n");
+
+const phases = [];
+let currentPhase = null;
+let currentSection = "implementation";
+
+for (const line of lines) {
+	const phaseMatch = line.match(/^###\s+Phase\s+(\d+)[:\s]+(.*)/);
+	if (phaseMatch) {
+		if (currentPhase) phases.push(currentPhase);
+		currentPhase = {
+			number: parseInt(phaseMatch[1], 10),
+			name: phaseMatch[2].trim(),
+			hasImplementation: false,
+			hasVerification: false,
+			hasContext: false,
+			hasDocument: false,
+			verificationIsOptOut: false,
+			contextIsOptOut: false,
+			documentIsOptOut: false,
+		};
+		currentSection = "implementation";
+		continue;
+	}
+
+	if (!currentPhase) continue;
+
+	// Detect gate section headers
+	const verMatch = line.match(/^####\s+Phase\s+\d+\s+Verification\b/);
+	if (verMatch) {
+		currentPhase.hasVerification = true;
+		currentSection = "verification";
+		continue;
+	}
+
+	const ctxMatch = line.match(/^####\s+Phase\s+\d+\s+Context\b/);
+	if (ctxMatch) {
+		currentPhase.hasContext = true;
+		currentSection = "context";
+		continue;
+	}
+
+	const docMatch = line.match(/^####\s+Phase\s+\d+\s+Document\b/);
+	if (docMatch) {
+		currentPhase.hasDocument = true;
+		currentSection = "document";
+		continue;
+	}
+
+	// Check for implementation items
+	if (currentSection === "implementation" && /^-\s+\[[ x]\]/.test(line)) {
+		currentPhase.hasImplementation = true;
+	}
+
+	// Track opt-out content in gate sections
+	const isOptOutLine =
+		line.includes("(none needed)") ||
+		line.includes("(not applicable)") ||
+		line.includes("skip-reason:");
+	if (currentPhase && isOptOutLine) {
+		if (currentSection === "verification") currentPhase.verificationIsOptOut = true;
+		if (currentSection === "context") currentPhase.contextIsOptOut = true;
+		if (currentSection === "document") currentPhase.documentIsOptOut = true;
+	}
+
+	// Forward intelligence doesn't count as a gate
+	if (line.match(/^####\s+Phase\s+\d+\s+Forward Intelligence\b/)) {
+		currentSection = "fi";
+	}
+}
+if (currentPhase) phases.push(currentPhase);
+
+// Check for opt-out content in gate sections
+// Re-scan to check if sections that exist have (none needed) or skip-reason:
+const isOptedOut = (text) =>
+	text.includes("(none needed)") ||
+	text.includes("(not applicable)") ||
+	text.includes("skip-reason:");
+
+// Validate each phase
+const errors = [];
+for (const phase of phases) {
+	if (!phase.hasImplementation) continue; // Skip phases with no impl items (might be a header-only outline)
+
+	const missing = [];
+	if (requirements.verification && !phase.hasVerification) missing.push("Verification");
+	if (requirements.context && !phase.hasContext) missing.push("Context");
+	if (requirements.document && !phase.hasDocument) missing.push("Document");
+
+	if (missing.length > 0) {
+		errors.push(`Phase ${phase.number} (${phase.name}) is missing: ${missing.join(", ")}`);
+	}
+
+	// In strict mode, opt-outs are not allowed — sections must have real items
+	if (gatePolicy === "strict") {
+		const optOuts = [];
+		if (requirements.verification && phase.hasVerification && phase.verificationIsOptOut)
+			optOuts.push("Verification");
+		if (requirements.context && phase.hasContext && phase.contextIsOptOut)
+			optOuts.push("Context");
+		if (requirements.document && phase.hasDocument && phase.documentIsOptOut)
+			optOuts.push("Document");
+		if (optOuts.length > 0) {
+			errors.push(
+				`Phase ${phase.number} (${phase.name}): ${optOuts.join(", ")} cannot use opt-outs in strict mode — add real items`,
+			);
+		}
+	}
+}
+
+if (errors.length > 0) {
+	const msg = errors.join("\n");
+	const reqNames = Object.entries(requirements)
+		.filter(([, v]) => v)
+		.map(([k]) => k.charAt(0).toUpperCase() + k.slice(1));
+	const skipHint =
+		gatePolicy === "strict"
+			? "Gate policy is 'strict' — all sections must have real items, no overrides.\n"
+			: "If a section isn't needed, add it with (none needed) or skip-reason: {why}\nExample: #### Phase 1 Document\\n(none needed)\n";
+	process.stderr.write(
+		`Impl structure incomplete (workflow: ${workflow}, policy: ${gatePolicy}):\n${msg}\n\nThis workflow requires: ${reqNames.join(", ")} sections per phase.\n${skipHint}To change requirements, add 'workflow: bugfix' to the impl frontmatter.\n`,
+	);
+	process.exit(2);
+}
+
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "0.7.2",
+	"version": "0.8.5",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [

package/skills/document.md

@@ -1,11 +1,26 @@
 ---
 name: document
-description: Per-phase documentation gate during impl execution. Writes and updates docs in the VitePress site. Encourages Mermaid diagrams for architecture, flows, and relationships.
+description: Build and maintain the project encyclopedia — a human-readable record of what was built, why, and how. Every plan contributes to documentation. This is not optional metadata.
 argument-hint: "[what to document or 'check']"
 ---
 
 You know how to maintain documentation in this project.
 
+## Why Documentation Exists
+
+Documentation is **the project's encyclopedia**. It is a human-readable record that any developer — today or a year from now — can read and understand:
+
+- **What** was built and how it works
+- **Why** it was built this way and not another
+- **How** to use it, configure it, extend it
+- **What changed** over time (changelogs, decision records)
+
+This is NOT the same as CLAUDE.md (which is agent-facing project memory) or code comments (which are implementation details). Documentation is for humans who need to understand the project without reading every source file.
+
+**Documentation is never optional.** The question is not "does this need docs?" — the question is "what docs does this need?" Even a bugfix updates the changelog. Even a refactor updates architecture diagrams. Even an internal change may need a decision record explaining why.
+
+The fact that information exists in CLAUDE.md, planning docs, or code does NOT eliminate the need for documentation. Those are working artifacts. Documentation is the polished, organized, permanent record.
+
 ## What Document Does
 
 Document is a per-phase gate during impl execution, alongside verify and context. The full phase order is:
@@ -14,14 +29,25 @@ Document is a per-phase gate during impl execution, alongside verify and context
 implement → verify → context → document → advance
 ```
 
-After context items are done, the document gate asks one question:
+After context items are done, the document gate asks:
+
+**"What should a developer reading this project's docs learn from what this phase built?"**
 
-**"Does this phase change something a user or developer needs to know?"**
+To answer this accurately, **REQUIRED: call `query_dependencies`** on the key files changed in this phase to understand what was affected and how broadly.
 
-To answer this accurately, **REQUIRED: call `query_dependencies`** on the key files changed in this phase. If the change affects files with many dependents, it likely needs documentation. If it's internal with no downstream consumers, it might not.
+For each phase, consider all of these:
 
-- If **yes**: write or update the relevant page in `apps/indusk-docs/src/`
-- If **no**: skip — not every phase produces documentation. The gate asks the question but doesn't always produce output.
+| What happened | What to document |
+|---|---|
+| New feature or tool | Reference page + guide if complex |
+| Architecture change | Update architecture page + diagrams |
+| New decision (ADR accepted) | Decision page distilled from ADR |
+| Bug fixed | Changelog entry + update affected reference pages |
+| Refactor | Update architecture diagrams + any affected reference pages |
+| New convention | Update conventions/reference page |
+| API change | Update API reference |
+| Configuration change | Update configuration reference |
+| Lesson learned | Will go in lessons/ during retrospective |
 
 ## Where Docs Live
 
@@ -97,16 +123,75 @@ flowchart TD
 
 **Never** use bare ` ```mermaid ` blocks without the wrapper. The diagrams are often too small to read inline, and the FullscreenDiagram gives users zoom and pan controls.
 
+## Two Documentation Layers
+
+### Standard Documentation (always)
+
+What was built, how it works, why it's designed this way. This is the reference someone reads to understand the system. Exists regardless of mode.
+
+### Learning Journal (teach mode only)
+
+When running in teach mode (`/work teach`), documentation gains a second layer: **what we learned building it**. This captures:
+
+- What surprised us during implementation
+- Why we chose this approach over the alternatives we considered
+- What was harder or easier than expected
+- Conceptual connections — "this pattern is similar to X because..."
+- What we'd do differently next time
+
+Learning journal entries go in `apps/indusk-docs/src/lessons/` as standalone pages, or as `## What We Learned` sections within existing guide pages. They're written in first person and read like a developer's notebook — not formal reference docs.
+
+In teach mode, every Document gate should produce both:
+1. **Standard docs** — reference/guide updates (same as normal mode)
+2. **Learning entry** — what the developer should take away from this phase
+
+The learning journal is what makes teach mode more than just "go slow." It builds a permanent record of understanding alongside the permanent record of what was built.
+
+## Documentation by Workflow Type
+
+The depth varies by workflow type, but every workflow produces documentation.
+
+### Feature (full documentation)
+
+A feature is new functionality. It gets the full treatment:
+- Write new reference pages for tools, APIs, or configuration added
+- Write guide pages for workflows introduced
+- Create Mermaid diagrams for architecture, flows, and relationships
+- Update existing pages that reference the area you changed
+- Add a changelog entry describing the feature
+- If an ADR was accepted, create a decision page in `decisions/`
+
+### Refactor (update existing docs)
+
+A refactor restructures existing code. The docs must reflect the new reality:
+- Update existing pages that reference moved/renamed code
+- Update architecture diagrams to show the new structure
+- Add a changelog entry explaining what was restructured and why
+- If the refactor changes how developers interact with the code, update the relevant guide
+
+### Bugfix (document the fix)
+
+A bugfix solves a specific problem. Even small fixes leave a paper trail:
+- Add a changelog entry describing the bug and the fix
+- Update any docs that described the broken behavior
+- If the bug revealed a gotcha, add it to the relevant reference page
+- If the fix changes a public API or configuration, update that reference page
+
 ## Shaping Impl Documents
 
-When writing an impl (via the plan skill), every phase should consider documentation:
+When writing an impl (via the plan skill), every phase gets a Document section:
 
 ```markdown
 #### Phase N Document
 - [ ] {Specific docs page to write or update}
+- [ ] {Changelog entry}
 ```
 
-The agent writing the impl must answer: **"What does a user or developer need to know about what this phase built?"** If the answer is "nothing user-facing" — no document items needed. Not every phase produces docs. But the question must be asked.
+The agent writing the impl must answer: **"What should a developer reading the docs learn from what this phase built?"**
+
+Every phase should produce at minimum a changelog entry. Beyond that, consider: does this phase add, change, or remove something that appears in the docs? If yes, list the specific pages to create or update.
+
+The `gate_policy` setting controls whether `(none needed)` is acceptable — in `strict` mode it is not. In `ask` mode, the agent must justify and get user approval before opting out. See the work skill for details.
 
 ### Document Items Are Blocking
 
@@ -118,37 +203,18 @@ implementation items → verification items → context items → document items
 
 A phase is not complete until its document items are done.
 
-## LLM-Readable Companion Files
-
-Every documentation page you create must have a corresponding **llms.txt** companion file. This makes the docs easy for AI agents to consume directly without HTML parsing.
-
-### How It Works
-
-For every page at `apps/indusk-docs/src/{path}.md`, create a matching file at `apps/indusk-docs/public/llms/{path}.txt`.
-
-```
-apps/indusk-docs/src/reference/skills/plan.md       → apps/indusk-docs/public/llms/reference/skills/plan.txt
-apps/indusk-docs/src/guide/getting-started.md        → apps/indusk-docs/public/llms/guide/getting-started.txt
-apps/indusk-docs/src/reference/tools/indusk-mcp.md   → apps/indusk-docs/public/llms/reference/tools/indusk-mcp.txt
-```
-
-### Content Rules
-
-The llms.txt file should contain the **same content** as the markdown page, with these adjustments:
-
-- Strip Mermaid diagram blocks and FullscreenDiagram wrappers (diagrams aren't useful as text)
-- Keep all tables, code blocks, headings, and prose
-- Keep all examples — these are the most valuable part for LLMs
-- Add a header line: `# {Page Title} — LLM-readable version`
-- Add a source line: `Source: {relative path to the .md file}`
+## LLM-Readable Output (llms.txt)
 
-### Why
+The docs site auto-generates LLM-friendly content via `vitepress-plugin-llms`. No manual work needed.
 
-When an external agent needs to understand this system, you can point it at `https://your-domain/llms/reference/skills/plan.txt` and it gets clean, structured text. No HTML parsing, no JavaScript rendering, no Mermaid SVGs to decode.
+At build time, the plugin produces:
+- `/llms.txt` — index with links to all pages (for LLM navigation)
+- `/llms-full.txt` — entire docs concatenated into one markdown file (for full ingestion)
+- Per-page `.md` files accessible directly
 
-### Also Create an Index
+This follows the [llms.txt convention](https://llmstxt.org/) used by Vite, Vue.js, Vitest, Stripe, and Cloudflare.
 
-Maintain `apps/indusk-docs/public/llms.txt` as a root index listing all available LLM-readable pages with their URLs and one-line descriptions. This follows the [llms.txt convention](https://llmstxt.org/).
+**Do not** manually create llms.txt files — the plugin handles everything.
 
 ## Running the Docs Site
 
@@ -162,7 +228,10 @@ pnpm turbo build --filter=indusk-docs
 
 ## Important
 
-- Documentation is human-facing. CLAUDE.md is agent-facing. They serve different audiences — don't duplicate between them.
-- Link, don't duplicate. If something is fully documented in a skill file or ADR, link to the docs page for it rather than copying content.
+- **Documentation is the project's permanent record.** It outlives conversations, planning docs, and even the code itself. Write it like someone will read it a year from now with no other context.
+- **Documentation is human-facing. CLAUDE.md is agent-facing.** They serve different audiences. CLAUDE.md helps the agent work. Docs help humans understand.
+- **The existence of information elsewhere does not replace documentation.** ADRs, CLAUDE.md, planning docs, and code comments are working artifacts. Documentation is the polished, organized, permanent version.
+- **Every plan contributes to documentation.** Features add pages. Refactors update pages. Bugfixes add changelog entries. There is no plan that produces zero documentation.
 - Keep reference pages focused and scannable. Use tables and diagrams over paragraphs.
-- The `decisions/` and `lessons/` sections are populated during retrospective only, not during normal impl work.
+- The `decisions/` and `lessons/` sections are populated during retrospective, but decision pages can also be created during impl when an ADR is accepted.
+- When in doubt, document more, not less. Excess documentation can be trimmed. Missing documentation is invisible.

package/skills/onboard.md

@@ -0,0 +1,61 @@
+---
+name: onboard
+description: Get a new agent caught up on the project. Reads context, plans, lessons, and code graph health in one shot. Run at the start of every new session.
+---
+
+You are starting a new session on this project. Before doing anything else, get caught up.
+
+## Steps (execute in order)
+
+### 1. Read Lessons
+Call `list_lessons`. Read every lesson. These are rules learned from past mistakes — not suggestions. Internalize them before touching any code.
+
+### 2. Check Infrastructure
+Call `check_health`. Verify FalkorDB and CGC are running. If unhealthy, tell the user what's down and how to fix it.
+
+### 3. Read Project Context
+Call `get_context` to read CLAUDE.md. This contains:
+- **Architecture** — what the project is, how it's structured
+- **Conventions** — rules to follow (commit style, no DB from Next.js, no fallback URLs, etc.)
+- **Key Decisions** — ADRs that have been accepted (with links)
+- **Known Gotchas** — things that will bite you if you don't know about them
+- **Current State** — what's been built, what's working, what's in progress
+
+Read it fully. Don't skim.
+
+### 4. Check Active Plans
+Call `list_plans`. This shows every plan and its status. Pay attention to:
+- Plans with status `in-progress` — these are actively being worked on
+- The current phase of each active plan — this is where `/work` will pick up
+- Dependencies between plans — don't start a blocked plan
+
+### 5. Check Code Graph
+Call `get_repository_stats` to understand the codebase size and structure. This gives you a sense of what's indexed and queryable.
+
+### 6. Summarize
+
+After completing steps 1-5, present a brief summary to the user:
+
+```
+**Session ready.**
+- Lessons: N loaded
+- Infrastructure: [healthy / issues]
+- Active plans: [list with current phase]
+- Codebase: [N files indexed]
+
+Ready to work. What would you like to do?
+```
+
+## When to Use
+
+- Start of every new Claude Code session
+- When the user says "get caught up", "what's going on", "where are we"
+- When context was compressed and you need to re-orient
+- `/onboard` explicitly
+
+## Important
+
+- Do NOT skip any step. Each one prevents a class of mistake.
+- Do NOT start coding before completing onboarding. The lessons and context exist because of past failures.
+- If CLAUDE.md seems outdated, flag it to the user — it may need a `/context` update.
+- If a plan's impl has unchecked items from a previous session, that's where `/work` picks up. Don't re-do completed work.

package/skills/plan.md

@@ -49,7 +49,14 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
 
 2. **Figure out where things stand.** If a plan folder already exists, read what's there. Check frontmatter statuses. The next document to write is the first one that's missing or incomplete.
 
-3. **If starting fresh**, create the plan folder and start with the first document for the workflow type:
+3. **If starting fresh**, do a quick scan of the project (read CLAUDE.md, check the code graph) to understand the context. Then **ask the user discovery questions before doing any research or writing any documents.** The goal is to understand what they're trying to achieve, not just what they named the plan. Good discovery questions:
+   - "What problem are you trying to solve?" or "What should this feature do for your users?"
+   - "Is there anything specific you've already thought through or have strong opinions about?"
+   - "Are there any constraints I should know about — timeline, technology preferences, things to avoid?"
+
+   For non-developers especially, this conversation is critical. They may not know the right technical terms, but they know what they want. Draw that out before proceeding.
+
+   Once you understand the intent, create the plan folder and start with the first document for the workflow type:
    - **feature**: start with research
    - **bugfix**: start with brief (streamlined template)
    - **refactor**: start with brief (includes boundary map)
@@ -62,12 +69,29 @@ Workflow templates are in `templates/workflows/` in the package. They describe w
    - Include the graph findings in research.md — concrete numbers like "X has 12 dependents across 3 apps"
    Document what you find. The research doc records findings and analysis, but saves the recommendation for the brief.
 
-4. **If research is done**, write the brief. This is where a direction emerges from the research. The brief proposes what we're building and why, informed by what the research uncovered. Present for review.
+4. **If research is done**, write the brief. This is where a direction emerges from the research. The brief proposes what we're building and why, informed by what the research uncovered. **Present the brief and have a conversation about it.** Don't just ask "does this look good?" — walk the user through it: "Here's what I'm proposing we build. Does this match what you had in mind? Is there anything missing, or anything here you don't want?" Iterate until the user is genuinely happy with the direction, then mark it as `accepted`.
 
 5. **If brief is accepted** and the workflow includes an ADR (feature only), write the ADR. The ADR formalizes the decisions that were discussed during research and led to the brief. It records what was chosen, what was rejected, and why. **After the ADR is accepted**, add a one-liner to CLAUDE.md's Key Decisions section per the context skill: `- {decision summary} — see planning/{plan}/adr.md`
 
 6. **If ADR is accepted** (or brief is accepted for bugfix/refactor), write the impl. Break into phased checklists with concrete tasks. For refactor workflows, include a `## Boundary Map` section. For multi-phase impls of any type, consider adding a boundary map.
 
+   **Gate policy applies when writing impls.** The same `gate_policy` (strict/ask/auto) that governs work execution also governs how the impl is written:
+
+   - **`strict`**: Every phase MUST have all four sections (implementation, verification, context, document) with real items. No `(none needed)` or `skip-reason:`. If a section genuinely doesn't apply, you still must include it with a concrete item.
+   - **`ask`** (default): Every phase MUST have all required sections (per workflow type). If you think a section should be `(none needed)`, ask the user: "Phase 3 Document — I don't think this phase changes anything user-facing. Can I mark it (none needed)?" Only mark it after approval.
+   - **`auto`**: Include all sections, but you can use `(none needed)` or `skip-reason:` based on your judgment without asking.
+
+   Set the policy in the impl frontmatter:
+   ```yaml
+   ---
+   title: "My Plan"
+   gate_policy: ask
+   workflow: feature
+   ---
+   ```
+
+   The `validate-impl-structure` hook enforces this at write time — it will block the impl if sections are missing for the workflow type.
+
 7. **If impl is completed** (all items checked off by `/work`), invoke the retrospective skill (`/retrospective {plan-name}`). This handles the structured audit (docs, tests, quality, context), knowledge handoff to the docs site, and archival. Do not write a freeform retrospective — use the skill. (Bugfix and refactor workflows may skip retrospective for small changes — user's call.)
 
 8. **Always present each document for review** before moving to the next stage. The user signs off on each step.

package/skills/work.md

@@ -61,6 +61,54 @@ Implementation plans live in `planning/{plan-name}/impl.md` as checklists. Your
 
    A phase is not complete until all four are done. **Enforced by hooks:** if you try to check off a Phase N+1 implementation item while Phase N has unchecked gates, the edit will be blocked with a message listing what's missing. Complete the gates first.
 
+## Gate Override Policy
+
+Gates exist to prevent skipping important work. But sometimes a gate genuinely doesn't apply. The override policy controls what happens when the agent wants to skip a gate item.
+
+Three modes, configured via `gate_policy` in the impl frontmatter or `.claude/settings.json`:
+
+| Mode | Behavior |
+|------|----------|
+| **`strict`** | No overrides. Every gate item must be completed. `(none needed)` and `skip-reason:` are not accepted. Use for critical work where nothing should be skipped. |
+| **`ask`** (default) | Agent must ask the user before skipping any gate item. The agent explains why it wants to skip and waits for approval. Only after the user says yes can it mark with `skip-reason:`. |
+| **`auto`** | Agent can skip with `skip-reason:` without asking. Use when running autonomously or when you trust the agent's judgment. |
+
+### How to set the mode
+
+**Per-plan** (in impl frontmatter):
+```yaml
+---
+title: "My Plan"
+gate_policy: strict
+---
+```
+
+**Per-project** (in `.claude/settings.json`):
+```json
+{
+  "indusk": {
+    "gate_policy": "ask"
+  }
+}
+```
+
+**Per-invocation**: `/work --strict`, `/work --ask`, `/work --auto`
+
+Priority: per-invocation > per-plan > per-project > default (`ask`).
+
+### What "ask" mode looks like
+
+When the agent encounters a gate item it thinks should be skipped:
+
+> "Phase 2 has a Document gate: 'Write reference page for the new API.' I don't think this phase needs a new docs page because we only changed internal implementation — the public API didn't change. Can I mark this as `skip-reason: internal change, no public API change`?"
+
+The user can say:
+- **"yes"** — agent marks it with skip-reason and continues
+- **"no, do it"** — agent completes the gate item
+- **"no, but mark it (none needed)"** — if the gate truly doesn't apply
+
+**The agent must NEVER skip a gate without asking in `ask` mode.** This is the core enforcement. The hooks block unauthorized skips, and the skill enforces the conversation.
+
 11. **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"
@@ -91,6 +139,8 @@ When invoked as `/work teach` or `/work --teach {plan}`, slow down to a mentorin
 
 ### Before each edit:
 
+**Where we are:** State the current position in the system — which plan, which phase, which gate (implementation/verification/context/document), and why this gate exists. Example: "We're in Phase 3 of the auth-system plan, working through implementation items. After these, we'll verify with type checks and tests, then update CLAUDE.md with what changed, then document it. That's the four-gate cycle that every phase goes through."
+
 **Why this change:** Explain what you're about to modify and why. Reference the plan, the architecture, and the reasoning. Use plain language.
 
 Then **stop and wait** for the user to say "continue" before making the edit.
@@ -103,15 +153,33 @@ Then **stop and wait** for the user to say "continue" before making the edit.
 
 Then **stop and wait** for the user to say "continue" before moving to the next item.
 
+### At gate transitions:
+
+When moving from implementation to verification, or verification to context, or context to document — explain the transition and why this gate exists:
+
+- **Implementation → Verification:** "The code is written. Now we prove it works. The verify skill says to run checks fastest-first: type check, lint, tests, build. This catches errors before they compound."
+- **Verification → Context:** "Everything passes. Now we update CLAUDE.md so the next session knows what changed. Context is how the project remembers — without it, the next agent starts from scratch."
+- **Context → Document:** "CLAUDE.md is updated. Now we write or update the project's documentation — the encyclopedia that any developer can read to understand what was built and why. In teach mode, we also write a learning entry: what surprised us, what we'd do differently, what conceptual connections to notice."
+- **Phase complete → Next phase:** "All four gates passed for Phase N. The hook would have blocked us if we'd tried to skip any. Now Phase N+1 builds on what Phase N produced — here's what the boundary map says it needs..."
+
 ### Between checklist items:
 
-Summarize what was accomplished and preview the next item. Explain how they connect.
+Summarize what was accomplished and preview the next item. Explain how they connect — both in terms of the feature being built and the InDusk system driving the process.
+
+### Document gate in teach mode:
+
+In teach mode, every Document gate produces two things:
+1. **Standard docs** — the same reference/guide updates you'd write in normal mode
+2. **Learning entry** — what the developer should take away from this phase: what surprised us, what we chose and why, what conceptual connections to notice
+
+See the document skill's "Two Documentation Layers" section for details. The learning journal is what makes teach mode a teaching tool, not just a slow mode.
 
 ### Important for teach mode:
 
 - Never batch multiple edits between pauses
 - Use clear headings to separate teaching from doing
 - If the user asks a question, answer it fully before continuing
+- Always give both layers: the **what** (the feature/code) and the **why** (the InDusk system's reasoning)
 - Normal `/work` (without teach) remains unchanged — fast execution, no pauses
 
 ## Corrections and Context Learning